diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/securesocketinterface.h --- a/epoc32/include/securesocketinterface.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/securesocketinterface.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,417 @@ -securesocketinterface.h +// Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members +// which accompanies this distribution, and is available +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// + + +#ifndef __SECURESOCKETINTERFACE_H__ +#define __SECURESOCKETINTERFACE_H__ + +#include +#include +#include +#include + +// File description +/** + * @file SecureSocketInterface.h + * Definition of the MSecureSocket class. + * + * @publishedAll + * @released + */ + +/** + * Server client certificate mode. + * Specifies if client certificates will be asked for when in server mode, and also if they are optional + * or must be provided to complete the handshake successfully. + * + * @since v7.0 + */ +enum TClientCertMode + { + /** Client certificates won't be asked for during handshake negotiation. */ + EClientCertModeIgnore, + /** Client certificates will be requested, but are not compulsory, + * and the handshake will continue if the client doesn't supply one. */ + EClientCertModeOptional, + /** Client certificates must be supplied, and the handshake will fail if + * the client does not provide a one. */ + EClientCertModeRequired + }; + +/** + * Untrusted certificate dialog mode. + * When an untrusted certificate is received, the dialog mode determines if the handshake + * fails automatically, or if a dialog is displayed allowing the user the option of continuing + * anyway. + * + * @since v7.0 + */ +enum TDialogMode + { + /** All untrusted certificates result in a user dialog. */ + EDialogModeAttended, + /** Untrusted certificates are canceled without user confirmation. */ + EDialogModeUnattended + }; + + +class MSecureSocket +/** + * Abstract interface API for secure socket implementations. + * + * MSecureSocket is the interface that secure socket implementations must adhere to. + * The API supports both client and server operation, see individual implementations' + * documentation for details of client/server operation that they may support. + * + * Secure socket implementations will be used to secure an already open and connected socket. + * The class must be passed a reference to an already open and connected socket when a new + * secure socket is created. New secure sockets are created through the CSecureSocket class, + * which hides the MSecureSocket class and the underlying plug-in nature of implementations + * from applications. Secure socket implementations MUST provide a NewL function that + * matches the following: + * + * @code + * static MSecureSocket* NewL( RSocket& aSocket, const TDesC& aProtocol ); + * @endcode + * + * aSocket A reference to an already opened and connected socket. + * + * aProtocol A descriptor containing the name of a protocol, i.e. SSL3.0, TLS1.0, that the + * application must specify when it creates the secure socket. The maximum length that can + * be specified for a protocol name is 32 characters. + * + * For error code definitions see SSLErr.h + * + * @since 6.2 + */ + { + +public: + + /** + * Gets the list of cipher suites that are available to use. + * The list of cipher suites that will be used by default will be returned in the descriptor. + * They are returned in the order that they will be used during a handshake, and are assumed to + * be in the format as per the SSL/TLS RFCs, i.e. [0x??][0x??] for each suite. + * See individual implementation notes for any differences. + * + * @param aCiphers A reference to a descriptor, should be at least 64 bytes long. + * @return Any one of the system error codes, or KErrNone on success. */ + virtual TInt AvailableCipherSuites( TDes8& aCiphers ) = 0; + + /** + * Cancels all outstanding operations. + * This method will cancel all outstanding operations with the exception of Shutdown, + * which cannot be canceled once started. + * See individual implementation notes for behaviour after canceling. */ + virtual void CancelAll() = 0; + + /** + * Cancels an outstanding handshake operation. + * This method is used to cancel the StartClientHandshake, StartServerHandshake and + * RenegociateHandshake operations. + * See individual implementation notes for behaviour after canceling.*/ + virtual void CancelHandshake() = 0; + + /** + * Cancels any outstanding read operation. + * See individual implementation notes for behaviour after canceling. */ + virtual void CancelRecv() = 0; + + /** + * Cancels any outstanding send operation. + * See individual implementation notes for behaviour after canceling. */ + virtual void CancelSend() = 0; + + /** + * Gets the current client certificate. + * + * When a secure socket is acting in server mode, the returned certificate will be the certificate that the remote + * client provided. + * When acting in client mode, the certificate returned will be the one that the client will send to the + * remote server if requested. + * + * Note that if there is no client certificate defined, either in server or client mode, + * this method will return NULL. + * + * @return A pointer to the client certificate, or NULL if none exists.*/ + virtual const CX509Certificate* ClientCert() = 0; + + /** + * Returns the current client certificate mode. + * The client certificate mode is used when the socket is acting as a server, and determines if a + * client certificate is requested. + * @see TClientCertMode for details of each mode. + * @return TClientCertMode The current mode that is set. */ + virtual TClientCertMode ClientCertMode() = 0; + + /** + * Closes the secure connection. + * Implementations should terminate the secure connection gracefully as appropriate to their protocol. + * It is assumed that they also close the socket when finished unless explicitly stated. They MUST NOT + * destroy the RSocket object, this is left to the client application. + */ + virtual void Close() = 0; + + /** + * Gets the current cipher suite in use. + * The current cipher suite is returned in the referenced buffer. + * + * Note that it is assumed that implementations return cipher suites in two byte format + * as is the case with the TLS/SSL protocols, i.e. [0x??][0x??]. + * Implementations should specify if they differ. + * + * @param aCipherSuite A reference to a descriptor at least 2 bytes long, + implementations that differ from the [0x??][0x??] format may + require larger descriptors. See individual implementations + notes for details. + * @return Any one of the system error codes, or KErrNone on success. */ + virtual TInt CurrentCipherSuite( TDes8& aCipherSuite ) = 0; + + /** + * Gets the current dialog mode. + * @see TDialogMode for description of valid modes. + * @return TDialogMode The current dialog mode. */ + virtual TDialogMode DialogMode() = 0; + + /** + * Flushes the session cache. + * + * If protocols implement a session cache, this method will cause that cache to be flushed. */ + virtual void FlushSessionCache() = 0; + + /** + * Gets an option. + * + * SecureSocket implementations may provide options that can be read with this method. + * See individual implementation notes for details. + * + * @param aOptionName An integer constant which identifies an option. + * @param aOptionLevel An integer constant which identifies level of an option. + * @param aOption Option value packaged in a descriptor. + * @return KErrNone if successful, otherwise another of the system-wide error codes. */ + virtual TInt GetOpt(TUint aOptionName,TUint aOptionLevel,TDes8& aOption) = 0; + + /** + * Gets an option. + * + * Secure socket implementations may provide options that can be read with this method. + * See individual implementation notes for details. + * + * @param aOptionName An integer constant which identifies an option. + * @param aOptionLevel An integer constant which identifies level of an option. + * @param aOption Option value as an integer. + * @return KErrNone if successful, otherwise another of the system-wide error codes. */ + virtual TInt GetOpt(TUint aOptionName,TUint aOptionLevel,TInt& aOption) = 0; + + /** + * Get the protocol in use. + * + * This method can be used to return the particular protocol/version that is being + * used by implementations that support different protocols/versions. + * See individual implementation notes for details. + * + * @param aProtocol A descriptor containing the protocol name/version that is being + used. Protocol names can be upto 32 characters long, and so a + descriptor of at least that size is required. + * @return KErrNone if successful; otherwise, another of the system-wide error codes. */ + virtual TInt Protocol(TDes& aProtocol) = 0; + + /** + * Receives data from the socket. + * + * This is an asynchronous method, and will complete when the descriptor has been filled. + * Only one Recv or RecvOneOrMore operation can be outstanding at any time. + * + * @param aDesc A descriptor where data read will be placed. + * @param aStatus On completion, will contain an error code: see the system-wide error + codes. Note that KErrEof indicates that a remote connection is + closed, and that no more data is available for reading. */ + virtual void Recv(TDes8& aDesc, TRequestStatus & aStatus) = 0; + + /** + * Receives data from the socket. + * + * This is an asynchronous call, and will complete when at least one byte has been read. + * Only one Recv or RecvOneOrMore operation can be outstanding at any time. + * + * @param aDesc A descriptor where data read will be placed. + * @param aStatus On completion, will contain an error code: see the system-wide error + * codes. Note that KErrEof indicates that a remote connection is closed, + * and that no more data is available for reading. + * @param aLen On return, a length which indicates how much data was read. + * This is the same as the length of the returned aDesc. */ + virtual void RecvOneOrMore(TDes8& aDesc, TRequestStatus& aStatus, TSockXfrLength& aLen) = 0; + + /** + * Initiates a renegotiation of the secure connection. + * + * This is an asynchronous method that completes when renegotiation is complete. + * It is valid for both client and server operation. + * There can only be one outstanding RenegotiateHandshake operation at a time. + * + * @param aStatus On completion, will contain an error code: see the system-wide error + codes. */ + virtual void RenegotiateHandshake(TRequestStatus& aStatus) = 0; + + /** + * Send data over the socket. + * + * This is an asynchronous call. Only one Send operation can be outstanding at any time. + * @param aDesc A constant descriptor containing the data to be sent. + * @param aStatus On completion, will contain an error code: see the system-wide error + codes. */ + virtual void Send(const TDesC8& aDesc, TRequestStatus& aStatus) = 0; + + /** + * Send data over the socket. + * + * This is an asynchronous call. Only one Send operation can be outstanding at any time. + * + * @param aDesc A constant descriptor. + * @param aStatus On completion, will contain an error code: see the system-wide error + * codes. + * @param aLen Filled in with amount of data sent before completion */ + virtual void Send(const TDesC8& aDesc, TRequestStatus& aStatus, TSockXfrLength& aLen) = 0; + + /** + * Gets the current server certificate. + * + * When a secure socket is acting in client mode, the returned certificate will be the + * certificate for the remote server. + * When acting in server mode, the certificate returned will be the one that is being + * used as the server certificate. + * + * @return CX509Certificate A pointer to the certificate. */ + virtual const CX509Certificate* ServerCert() = 0; + + /** + * Sets a list of cipher suites that are available to use. + * + * It is assumed that implementations require a list of cipher suites supplied in a descriptor in two + * byte format as is the case with the TLS/SSL protocols, i.e. [0x??][0x??]. + * It is also assumed that the order of suites is important, and so they should be listed + * with the preferred suites first. + * Implementations should specify if they differ. + * + * @param aCiphers A descriptor containing the list or ciphers suites to use. + * @return Any one of the system error codes, or KErrNone on success. */ + virtual TInt SetAvailableCipherSuites(const TDesC8& aCiphers) = 0; + + /** + * Sets the client certificate to use. + * + * When a secure socket is acting in client mode, this method will set the certificate + * that will be used if a server requests one. + * When acting in server mode, this method will perform no action, but will return KErrNotSupported. + * @param aCert A reference to the certificate to use. + * @return Any one of the system error codes, or KErrNone on success. */ + virtual TInt SetClientCert(const CX509Certificate& aCert) = 0; + + /** + * Set the client certificate mode. + * + * When a secure socket is acting in server mode, the client certificate mode determines + * if clients will be requested to provide a certificate. + * When acting in client mode, this method will perform no action, but will return KErrNotSupported. + * + * @see TClientCertMode for details of each available mode. + * @param aClientCertMode The client certificate mode to use. + * @return Any one of the system error codes, or KErrNone on success. */ + virtual TInt SetClientCertMode(const TClientCertMode aClientCertMode) = 0; + + /** + * Set the untrusted certificate dialog mode. + * + * Determines if a dialog is displayed when an untrusted certificate is received. + * + * @see TDialogMode for details of each available mode. + * @param aDialogMode The dialog mode to use. + * @return Any one of the system error codes, or KErrNone on success. */ + virtual TInt SetDialogMode(const TDialogMode aDialogMode) = 0; + + /** + * Sets a socket option. + * + * Secure socket implementations may provide options that can be set with this method. + * See individual implementation notes for details. + * + * @param aOptionName An integer constant which identifies an option. + * @param aOptionLevel An integer constant which identifies level of an option: + * i.e. an option level groups related options together. + * @param aOption Option value packaged in a descriptor + * @return Any one of the system error codes, or KErrNone on success. */ + virtual TInt SetOpt(TUint aOptionName,TUint aOptionLevel, const TDesC8& aOption=KNullDesC8()) = 0; + + /** + * Sets an option. + * + * SecureSocket implementations may provide options that can be set with this method. + * See individual implementation notes for details. + * + * @param aOptionName An integer constant which identifies an option. + * @param aOptionLevel An integer constant which identifies level of an option: + * i.e. an option level groups related options together. + * @param aOption Option value as an integer + * @return Any one of the system error codes, or KErrNone on success. */ + virtual TInt SetOpt(TUint aOptionName,TUint aOptionLevel,TInt anOption) = 0; + + /** + * Set a specific protocol/version to use. + * + * This method can be used to select a particular protocol version to use in + * implementations that support different protocols/versions. + * See individual implementation notes for details. + * + * @param aProtocol A reference to a descriptor containing the protocol name/version to use. + * @return KErrNone if successful, a system-wide error code if not. */ + virtual TInt SetProtocol(const TDesC& aProtocol) = 0; + + /** + * Set the server certificate. + * + * When acting in server mode, this method will set the certificate that is to be used + * as the server certificate. + * When acting in client mode, this method will perform no action, but will return KErrNotSupported. + * + * @param aCert The certificate to use. + * @return Any one of the system error codes, or KErrNone on success. */ + virtual TInt SetServerCert(const CX509Certificate& aCert) = 0; + + /** + * Start acting as a client and initiate a handshake with the remote server. + * + * This is an asynchronous call, and will only complete when the handshake completes + * and the secure connection is established, or it fails. + * + * @param aStatus On completion, any one of the system error codes, or KErrNone on success. */ + virtual void StartClientHandshake(TRequestStatus& aStatus) = 0; + + /** + * Start acting as a server and listen for a handshake from the remote client. + * + * This is an asynchronous call, and will only complete when a client completes the + * handshake, or if it fails. Normally, the socket passed in will usually have been + * previously used in a call to Accept() on a listening socket, but this is not required. + * + * @param aStatus On completion, any one of the system error codes, or KErrNone on success. */ + virtual void StartServerHandshake(TRequestStatus& aStatus) = 0; + + /** Standard destructor. */ + virtual ~MSecureSocket() {}; + + }; + +#endif // __SECURESOCKETINTERFACE_H__