1 securesocketinterface.h

     1 // Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // 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

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 

    17 #ifndef __SECURESOCKETINTERFACE_H__

    18 #define __SECURESOCKETINTERFACE_H__

    19 

    20 #include <e32base.h>

    21 #include <sslerr.h>

    22 #include <x509cert.h>

    23 #include <es_sock.h>

    24 

    25 // File description

    26 /** 

    27  * @file SecureSocketInterface.h

    28  * Definition of the MSecureSocket class.

    29  *

    30  * @publishedAll

    31  * @released

    32  */

    33 

    34 /** 

    35  * Server client certificate mode.

    36  * Specifies if client certificates will be asked for when in server mode, and also if they are optional

    37  * or must be provided to complete the handshake successfully.

    38  *

    39  * @since v7.0

    40  */

    41 enum TClientCertMode

    42 	{

    43 	/** Client certificates won't be asked for during handshake negotiation. */

    44 	EClientCertModeIgnore,

    45 	/** Client certificates will be requested, but are not compulsory, 

    46 	  * and the handshake will continue if the client doesn't supply one. */

    47 	EClientCertModeOptional,

    48 	/** Client certificates must be supplied, and the handshake will fail if 

    49 	  * the client does not provide a one. */

    50 	EClientCertModeRequired

    51 	};

    52 

    53 /**

    54  * Untrusted certificate dialog mode.

    55  * When an untrusted certificate is received, the dialog mode determines if the handshake 

    56  * fails automatically, or if a dialog is displayed allowing the user the option of continuing

    57  * anyway. 

    58  *

    59  * @since v7.0

    60  */

    61 enum TDialogMode

    62 	{

    63 	/** All untrusted certificates result in a user dialog. */

    64 	EDialogModeAttended,

    65 	/** Untrusted certificates are canceled without user confirmation. */

    66 	EDialogModeUnattended

    67 	};

    68 

    69 

    70 class MSecureSocket

    71 /**

    72  * Abstract interface API for secure socket implementations.

    73  *

    74  * MSecureSocket is the interface that secure socket implementations must adhere to.

    75  * The API supports both client and server operation, see individual implementations'

    76  * documentation for details of client/server operation that they may support.

    77  * 

    78  * Secure socket implementations will be used to secure an already open and connected socket. 

    79  * The class must be passed a reference to an already open and connected socket when a new 

    80  * secure socket is created. New secure sockets are created through the CSecureSocket class, 

    81  * which hides the MSecureSocket class and the underlying plug-in nature of implementations 

    82  * from applications. Secure socket implementations MUST provide a NewL function that 

    83  * matches the following:

    84  *

    85  * @code

    86  * static MSecureSocket* NewL( RSocket& aSocket, const TDesC& aProtocol );

    87  * @endcode

    88  *

    89  * aSocket A reference to an already opened and connected socket.

    90  *

    91  * aProtocol A descriptor containing the name of a protocol, i.e. SSL3.0, TLS1.0, that the 

    92  * application must specify when it creates the secure socket. The maximum length that can 

    93  * be specified for a protocol name is 32 characters.

    94  *

    95  * For error code definitions see SSLErr.h

    96  *

    97  * @since 6.2

    98  */

    99 	{

   100 

   101 public:

   102 

   103 	 /** 

   104 	 * Gets the list of cipher suites that are available to use. 

   105 	 * The list of cipher suites that will be used by default will be returned in the descriptor.

   106 	 * They are returned in the order that they will be used during a handshake, and are assumed to

   107 	 * be in the format as per the SSL/TLS RFCs, i.e. [0x??][0x??] for each suite. 

   108 	 * See individual implementation notes for any differences.

   109 	 *

   110 	 * @param aCiphers	A reference to a descriptor, should be at least 64 bytes long. 

   111 	 * @return			Any one of the system error codes, or KErrNone on success. */

   112 	virtual TInt AvailableCipherSuites( TDes8& aCiphers ) = 0;

   113 

   114 	 /**

   115 	 * Cancels all outstanding operations. 

   116 	 * This method will cancel all outstanding operations with the exception of Shutdown, 

   117 	 * which cannot be canceled once started. 

   118 	 * See individual implementation notes for behaviour after canceling. */

   119 	virtual void CancelAll() = 0;

   120 

   121 	 /**

   122 	 * Cancels an outstanding handshake operation. 

   123 	 * This method is used to cancel the StartClientHandshake, StartServerHandshake and 

   124 	 * RenegociateHandshake operations. 

   125 	 * See individual implementation notes for behaviour after canceling.*/

   126 	virtual void CancelHandshake() = 0;

   127 

   128 	 /** 

   129 	 * Cancels any outstanding read operation.

   130 	 * See individual implementation notes for behaviour after canceling. */

   131 	virtual void CancelRecv() = 0;

   132 

   133 	 /** 

   134 	 * Cancels any outstanding send operation. 

   135 	 * See individual implementation notes for behaviour after canceling. */

   136 	virtual void CancelSend() = 0;

   137 

   138 	 /**

   139 	 * Gets the current client certificate.

   140 	 *

   141 	 * When a secure socket is acting in server mode, the returned certificate will be the certificate that the remote

   142 	 * client provided. 

   143 	 * When acting in client mode, the certificate returned will be the one that the client will send to the 

   144 	 * remote server if requested. 

   145 	 * 

   146  	 * Note that if there is no client certificate defined, either in server or client mode, 

   147 	 * this method will return NULL.

   148 	 *

   149 	 * @return A pointer to the client certificate, or NULL if none exists.*/

   150 	virtual const CX509Certificate* ClientCert() = 0;

   151 

   152 	 /** 

   153 	 * Returns the current client certificate mode.

   154 	 * The client certificate mode is used when the socket is acting as a server, and determines if a 

   155 	 * client certificate is requested.

   156 	 * @see TClientCertMode for details of each mode.

   157 	 * @return TClientCertMode The current mode that is set. */

   158 	virtual TClientCertMode ClientCertMode() = 0; 

   159 

   160 	 /** 

   161 	 * Closes the secure connection.

   162 	 * Implementations should terminate the secure connection gracefully as appropriate to their protocol. 

   163 	 * It is assumed that they also close the socket when finished unless explicitly stated. They MUST NOT 

   164 	 * destroy the RSocket object, this is left to the client application.

   165 	 */

   166 	virtual void Close() = 0;

   167 

   168 	 /**

   169 	 * Gets the current cipher suite in use.

   170 	 * The current cipher suite is returned in the referenced buffer.

   171 	 * 

   172 	 * Note that it is assumed that implementations return cipher suites in two byte format 

   173 	 * as is the case with the TLS/SSL protocols, i.e. [0x??][0x??]. 

   174 	 * Implementations should specify if they differ.

   175 	 *

   176 	 * @param aCipherSuite		A reference to a descriptor at least 2 bytes long, 

   177 								implementations that differ from the [0x??][0x??] format may 

   178 								require larger descriptors. See individual implementations 

   179 								notes for details. 

   180 	 * @return					Any one of the system error codes, or KErrNone on success. */

   181 	virtual TInt CurrentCipherSuite( TDes8& aCipherSuite ) = 0;

   182 

   183 	 /**

   184 	 * Gets the current dialog mode.

   185 	 * @see		TDialogMode for description of valid modes.

   186 	 * @return	TDialogMode The current dialog mode. */

   187 	virtual TDialogMode	DialogMode() = 0; 

   188 

   189 	 /** 

   190 	 * Flushes the session cache.

   191 	 *

   192 	 * If protocols implement a session cache, this method will cause that cache to be flushed. */

   193 	virtual void FlushSessionCache() = 0;

   194 

   195 	 /**

   196 	 * Gets an option.

   197 	 *

   198 	 * SecureSocket implementations may provide options that can be read with this method.

   199 	 * See individual implementation notes for details.

   200 	 *

   201 	 * @param aOptionName	An integer constant which identifies an option.	 

   202 	 * @param aOptionLevel	An integer constant which identifies level of an option.	 

   203 	 * @param aOption		Option value packaged in a descriptor.

   204 	 * @return				KErrNone if successful, otherwise another of the system-wide error codes. */

   205 	virtual TInt GetOpt(TUint aOptionName,TUint aOptionLevel,TDes8& aOption) = 0;

   206 

   207 	 /**

   208 	 * Gets an option.

   209 	 *

   210 	 * Secure socket implementations may provide options that can be read with this method.

   211 	 * See individual implementation notes for details.

   212 	 *

   213 	 * @param aOptionName	An integer constant which identifies an option.

   214 	 * @param aOptionLevel	An integer constant which identifies level of an option.	 

   215 	 * @param aOption		Option value as an integer.

   216 	 * @return				KErrNone if successful, otherwise another of the system-wide error codes. */

   217 	virtual TInt GetOpt(TUint aOptionName,TUint aOptionLevel,TInt& aOption) = 0;

   218 

   219 	 /**

   220 	 * Get the protocol in use.

   221 	 *

   222 	 * This method can be used to return the particular protocol/version that is being 

   223 	 * used by implementations that support different protocols/versions.

   224 	 * See individual implementation notes for details.

   225 	 *

   226 	 * @param aProtocol		A descriptor containing the protocol name/version that is being 

   227 							used. Protocol names can be upto 32 characters long, and so a 

   228 							descriptor of at least that size is required.

   229 	 * @return			KErrNone if successful; otherwise, another of the system-wide error codes. */

   230 	virtual TInt Protocol(TDes& aProtocol) = 0;

   231 

   232 	 /**

   233 	 * Receives data from the socket.

   234 	 *

   235 	 * This is an asynchronous method, and will complete when the descriptor has been filled. 

   236 	 * Only one Recv or RecvOneOrMore operation can be outstanding at any time.

   237 	 *

   238 	 * @param aDesc		A descriptor where data read will be placed.

   239 	 * @param aStatus	On completion, will contain an error code: see the system-wide error 

   240 						codes. Note that KErrEof indicates that a remote connection is 

   241 						closed, and that no more data is available for reading. */

   242 	virtual void Recv(TDes8& aDesc, TRequestStatus & aStatus) = 0;

   243 

   244 	 /** 

   245 	 * Receives data from the socket. 

   246 	 *

   247 	 * This is an asynchronous call, and will complete when at least one byte has been read.

   248 	 * Only one Recv or RecvOneOrMore operation can be outstanding at any time.

   249 	 *

   250 	 * @param aDesc		A descriptor where data read will be placed.

   251 	 * @param aStatus	On completion, will contain an error code: see the system-wide error 

   252 	 *					codes. Note that KErrEof indicates that a remote connection is closed,

   253      *					and that no more data is available for reading.

   254 	 * @param aLen		On return, a length which indicates how much data was read. 

   255 	 *					This is the same as the length of the returned aDesc. */

   256 	virtual void RecvOneOrMore(TDes8& aDesc, TRequestStatus& aStatus, TSockXfrLength& aLen) = 0;

   257 

   258 	 /**

   259 	 * Initiates a renegotiation of the secure connection.

   260 	 *

   261 	 * This is an asynchronous method that completes when renegotiation is complete. 

   262 	 * It is valid for both client and server operation. 

   263 	 * There can only be one outstanding RenegotiateHandshake operation at a time.

   264 	 *

   265 	 * @param aStatus	On completion, will contain an error code: see the system-wide error 

   266 						codes. */

   267 	virtual void RenegotiateHandshake(TRequestStatus& aStatus) = 0;

   268 

   269 	 /** 

   270 	 * Send data over the socket. 

   271 	 *

   272 	 * This is an asynchronous call. Only one Send operation can be outstanding at any time. 

   273 	 * @param aDesc		A constant descriptor containing the data to be sent.

   274 	 * @param aStatus	On completion, will contain an error code: see the system-wide error 

   275 						codes. */

   276 	virtual void Send(const TDesC8& aDesc, TRequestStatus& aStatus) = 0;

   277 

   278 	 /** 

   279 	 * Send data over the socket.

   280 	 *

   281 	 * This is an asynchronous call. Only one Send operation can be outstanding at any time.

   282 	 *

   283 	 * @param aDesc		A constant descriptor.

   284 	 * @param aStatus	On completion, will contain an error code: see the system-wide error 

   285 	 *					codes. 

   286 	 * @param aLen		Filled in with amount of data sent before completion */

   287 	virtual void Send(const TDesC8& aDesc, TRequestStatus& aStatus, TSockXfrLength& aLen) = 0;

   288 

   289 	 /**

   290 	 * Gets the current server certificate.

   291 	 *

   292 	 * When a secure socket is acting in client mode, the returned certificate will be the 

   293 	 * certificate for the remote server.

   294 	 * When acting in server mode, the certificate returned will be the one that is being 

   295 	 * used as the server certificate.

   296 	 *

   297 	 * @return CX509Certificate A pointer to the certificate. */ 

   298 	virtual const CX509Certificate* ServerCert() = 0;

   299 

   300 	 /** 

   301 	 * Sets a list of cipher suites that are available to use. 

   302 	 *

   303 	 * It is assumed that implementations require a list of cipher suites supplied in a descriptor in two

   304 	 * byte format as is the case with the TLS/SSL protocols, i.e. [0x??][0x??]. 

   305 	 * It is also assumed that the order of suites is important, and so they should be listed

   306 	 * with the preferred suites first. 

   307 	 * Implementations should specify if they differ.

   308 	 *

   309 	 * @param aCiphers	A descriptor containing the list or ciphers suites to use. 

   310 	 * @return			Any one of the system error codes, or KErrNone on success. */

   311 	virtual TInt SetAvailableCipherSuites(const TDesC8& aCiphers) = 0;

   312 

   313 	 /**

   314 	 * Sets the client certificate to use.

   315 	 *

   316 	 * When a secure socket is acting in client mode, this method will set the certificate 

   317 	 * that will be used if a server requests one.

   318 	 * When acting in server mode, this method will perform no action, but will return KErrNotSupported.

   319 	 * @param aCert		A reference to the certificate to use.

   320 	 * @return			Any one of the system error codes, or KErrNone on success. */

   321 	virtual TInt SetClientCert(const CX509Certificate& aCert) = 0;

   322 

   323 	 /** 

   324 	 * Set the client certificate mode. 

   325 	 *

   326 	 * When a secure socket is acting in server mode, the client certificate mode determines

   327 	 * if clients will be requested to provide a certificate.

   328 	 * When acting in client mode, this method will perform no action, but will return KErrNotSupported.

   329 	 *

   330 	 * @see TClientCertMode for details of each available mode.

   331 	 * @param aClientCertMode	The client certificate mode to use.

   332 	 * @return					Any one of the system error codes, or KErrNone on success. */

   333 	virtual TInt SetClientCertMode(const TClientCertMode aClientCertMode) = 0;

   334 

   335 	 /**

   336 	 * Set the untrusted certificate dialog mode.

   337 	 *

   338 	 * Determines if a dialog is displayed when an untrusted certificate is received.

   339 	 *

   340 	 * @see TDialogMode for details of each available mode.

   341 	 * @param aDialogMode	The dialog mode to use.

   342 	 * @return				Any one of the system error codes, or KErrNone on success. */

   343 	virtual TInt SetDialogMode(const TDialogMode aDialogMode) = 0;

   344 

   345 	 /** 

   346 	 * Sets a socket option. 

   347 	 *

   348 	 * Secure socket implementations may provide options that can be set with this method.

   349 	 * See individual implementation notes for details.

   350 	 *

   351 	 * @param aOptionName	An integer constant which identifies an option.

   352 	 * @param aOptionLevel	An integer constant which identifies level of an option: 

   353 	 *						i.e. an option level groups related options together.

   354 	 * @param aOption		Option value packaged in a descriptor

   355 	 * @return				Any one of the system error codes, or KErrNone on success. */

   356 	virtual TInt SetOpt(TUint aOptionName,TUint aOptionLevel, const TDesC8& aOption=KNullDesC8()) = 0;

   357 																					   

   358 	 /** 

   359 	 * Sets an option.

   360 	 *

   361 	 * SecureSocket implementations may provide options that can be set with this method.

   362 	 * See individual implementation notes for details.

   363 	 *

   364 	 * @param aOptionName	An integer constant which identifies an option.

   365 	 * @param aOptionLevel	An integer constant which identifies level of an option: 

   366 	 *						i.e. an option level groups related options together.

   367 	 * @param aOption		Option value as an integer

   368 	 * @return				Any one of the system error codes, or KErrNone on success. */

   369 	virtual TInt SetOpt(TUint aOptionName,TUint aOptionLevel,TInt anOption) = 0;

   370 

   371 	 /**

   372 	 * Set a specific protocol/version to use.

   373 	 *

   374 	 * This method can be used to select a particular protocol version to use in 

   375 	 * implementations that support different protocols/versions.

   376 	 * See individual implementation notes for details.

   377 	 *

   378 	 * @param aProtocol A reference to a descriptor containing the protocol name/version to use.

   379 	 * @return			KErrNone if successful, a system-wide error code if not. */

   380 	virtual TInt SetProtocol(const TDesC& aProtocol) = 0;

   381 

   382 	 /**

   383 	 * Set the server certificate.

   384 	 *

   385 	 * When acting in server mode, this method will set the certificate that is to be used 

   386 	 * as the server certificate.

   387 	 * When acting in client mode, this method will perform no action, but will return KErrNotSupported.

   388 	 *

   389 	 * @param aCert The certificate to use.

   390 	 * @return		Any one of the system error codes, or KErrNone on success. */

   391 	virtual TInt SetServerCert(const CX509Certificate& aCert) = 0;

   392 

   393 	 /**

   394 	 * Start acting as a client and initiate a handshake with the remote server.

   395 	 *

   396 	 * This is an asynchronous call, and will only complete when the handshake completes 

   397 	 * and the secure connection is established, or it fails.

   398 	 *

   399 	 * @param aStatus On completion, any one of the system error codes, or KErrNone on success. */

   400 	virtual void StartClientHandshake(TRequestStatus& aStatus) = 0;

   401 

   402 	 /**

   403 	 * Start acting as a server and listen for a handshake from the remote client.

   404 	 *

   405 	 * This is an asynchronous call, and will only complete when a client completes the 

   406 	 * handshake, or if it fails. Normally, the socket passed in will usually have been 

   407 	 * previously used in a call to Accept() on a listening socket, but this is not required. 

   408 	 *

   409 	 * @param aStatus On completion, any one of the system error codes, or KErrNone on success. */

   410 	virtual void StartServerHandshake(TRequestStatus& aStatus) = 0;

   411 

   412 	/** Standard destructor. */

   413 	virtual ~MSecureSocket() {};

   414 

   415 	};

   416 

   417 #endif // __SECURESOCKETINTERFACE_H__