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