1.1 --- a/epoc32/include/securesocketinterface.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/securesocketinterface.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,417 @@
1.4 -securesocketinterface.h
1.5 +// Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// 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
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +//
1.19 +
1.20 +
1.21 +#ifndef __SECURESOCKETINTERFACE_H__
1.22 +#define __SECURESOCKETINTERFACE_H__
1.23 +
1.24 +#include <e32base.h>
1.25 +#include <sslerr.h>
1.26 +#include <x509cert.h>
1.27 +#include <es_sock.h>
1.28 +
1.29 +// File description
1.30 +/**
1.31 + * @file SecureSocketInterface.h
1.32 + * Definition of the MSecureSocket class.
1.33 + *
1.34 + * @publishedAll
1.35 + * @released
1.36 + */
1.37 +
1.38 +/**
1.39 + * Server client certificate mode.
1.40 + * Specifies if client certificates will be asked for when in server mode, and also if they are optional
1.41 + * or must be provided to complete the handshake successfully.
1.42 + *
1.43 + * @since v7.0
1.44 + */
1.45 +enum TClientCertMode
1.46 + {
1.47 + /** Client certificates won't be asked for during handshake negotiation. */
1.48 + EClientCertModeIgnore,
1.49 + /** Client certificates will be requested, but are not compulsory,
1.50 + * and the handshake will continue if the client doesn't supply one. */
1.51 + EClientCertModeOptional,
1.52 + /** Client certificates must be supplied, and the handshake will fail if
1.53 + * the client does not provide a one. */
1.54 + EClientCertModeRequired
1.55 + };
1.56 +
1.57 +/**
1.58 + * Untrusted certificate dialog mode.
1.59 + * When an untrusted certificate is received, the dialog mode determines if the handshake
1.60 + * fails automatically, or if a dialog is displayed allowing the user the option of continuing
1.61 + * anyway.
1.62 + *
1.63 + * @since v7.0
1.64 + */
1.65 +enum TDialogMode
1.66 + {
1.67 + /** All untrusted certificates result in a user dialog. */
1.68 + EDialogModeAttended,
1.69 + /** Untrusted certificates are canceled without user confirmation. */
1.70 + EDialogModeUnattended
1.71 + };
1.72 +
1.73 +
1.74 +class MSecureSocket
1.75 +/**
1.76 + * Abstract interface API for secure socket implementations.
1.77 + *
1.78 + * MSecureSocket is the interface that secure socket implementations must adhere to.
1.79 + * The API supports both client and server operation, see individual implementations'
1.80 + * documentation for details of client/server operation that they may support.
1.81 + *
1.82 + * Secure socket implementations will be used to secure an already open and connected socket.
1.83 + * The class must be passed a reference to an already open and connected socket when a new
1.84 + * secure socket is created. New secure sockets are created through the CSecureSocket class,
1.85 + * which hides the MSecureSocket class and the underlying plug-in nature of implementations
1.86 + * from applications. Secure socket implementations MUST provide a NewL function that
1.87 + * matches the following:
1.88 + *
1.89 + * @code
1.90 + * static MSecureSocket* NewL( RSocket& aSocket, const TDesC& aProtocol );
1.91 + * @endcode
1.92 + *
1.93 + * aSocket A reference to an already opened and connected socket.
1.94 + *
1.95 + * aProtocol A descriptor containing the name of a protocol, i.e. SSL3.0, TLS1.0, that the
1.96 + * application must specify when it creates the secure socket. The maximum length that can
1.97 + * be specified for a protocol name is 32 characters.
1.98 + *
1.99 + * For error code definitions see SSLErr.h
1.100 + *
1.101 + * @since 6.2
1.102 + */
1.103 + {
1.104 +
1.105 +public:
1.106 +
1.107 + /**
1.108 + * Gets the list of cipher suites that are available to use.
1.109 + * The list of cipher suites that will be used by default will be returned in the descriptor.
1.110 + * They are returned in the order that they will be used during a handshake, and are assumed to
1.111 + * be in the format as per the SSL/TLS RFCs, i.e. [0x??][0x??] for each suite.
1.112 + * See individual implementation notes for any differences.
1.113 + *
1.114 + * @param aCiphers A reference to a descriptor, should be at least 64 bytes long.
1.115 + * @return Any one of the system error codes, or KErrNone on success. */
1.116 + virtual TInt AvailableCipherSuites( TDes8& aCiphers ) = 0;
1.117 +
1.118 + /**
1.119 + * Cancels all outstanding operations.
1.120 + * This method will cancel all outstanding operations with the exception of Shutdown,
1.121 + * which cannot be canceled once started.
1.122 + * See individual implementation notes for behaviour after canceling. */
1.123 + virtual void CancelAll() = 0;
1.124 +
1.125 + /**
1.126 + * Cancels an outstanding handshake operation.
1.127 + * This method is used to cancel the StartClientHandshake, StartServerHandshake and
1.128 + * RenegociateHandshake operations.
1.129 + * See individual implementation notes for behaviour after canceling.*/
1.130 + virtual void CancelHandshake() = 0;
1.131 +
1.132 + /**
1.133 + * Cancels any outstanding read operation.
1.134 + * See individual implementation notes for behaviour after canceling. */
1.135 + virtual void CancelRecv() = 0;
1.136 +
1.137 + /**
1.138 + * Cancels any outstanding send operation.
1.139 + * See individual implementation notes for behaviour after canceling. */
1.140 + virtual void CancelSend() = 0;
1.141 +
1.142 + /**
1.143 + * Gets the current client certificate.
1.144 + *
1.145 + * When a secure socket is acting in server mode, the returned certificate will be the certificate that the remote
1.146 + * client provided.
1.147 + * When acting in client mode, the certificate returned will be the one that the client will send to the
1.148 + * remote server if requested.
1.149 + *
1.150 + * Note that if there is no client certificate defined, either in server or client mode,
1.151 + * this method will return NULL.
1.152 + *
1.153 + * @return A pointer to the client certificate, or NULL if none exists.*/
1.154 + virtual const CX509Certificate* ClientCert() = 0;
1.155 +
1.156 + /**
1.157 + * Returns the current client certificate mode.
1.158 + * The client certificate mode is used when the socket is acting as a server, and determines if a
1.159 + * client certificate is requested.
1.160 + * @see TClientCertMode for details of each mode.
1.161 + * @return TClientCertMode The current mode that is set. */
1.162 + virtual TClientCertMode ClientCertMode() = 0;
1.163 +
1.164 + /**
1.165 + * Closes the secure connection.
1.166 + * Implementations should terminate the secure connection gracefully as appropriate to their protocol.
1.167 + * It is assumed that they also close the socket when finished unless explicitly stated. They MUST NOT
1.168 + * destroy the RSocket object, this is left to the client application.
1.169 + */
1.170 + virtual void Close() = 0;
1.171 +
1.172 + /**
1.173 + * Gets the current cipher suite in use.
1.174 + * The current cipher suite is returned in the referenced buffer.
1.175 + *
1.176 + * Note that it is assumed that implementations return cipher suites in two byte format
1.177 + * as is the case with the TLS/SSL protocols, i.e. [0x??][0x??].
1.178 + * Implementations should specify if they differ.
1.179 + *
1.180 + * @param aCipherSuite A reference to a descriptor at least 2 bytes long,
1.181 + implementations that differ from the [0x??][0x??] format may
1.182 + require larger descriptors. See individual implementations
1.183 + notes for details.
1.184 + * @return Any one of the system error codes, or KErrNone on success. */
1.185 + virtual TInt CurrentCipherSuite( TDes8& aCipherSuite ) = 0;
1.186 +
1.187 + /**
1.188 + * Gets the current dialog mode.
1.189 + * @see TDialogMode for description of valid modes.
1.190 + * @return TDialogMode The current dialog mode. */
1.191 + virtual TDialogMode DialogMode() = 0;
1.192 +
1.193 + /**
1.194 + * Flushes the session cache.
1.195 + *
1.196 + * If protocols implement a session cache, this method will cause that cache to be flushed. */
1.197 + virtual void FlushSessionCache() = 0;
1.198 +
1.199 + /**
1.200 + * Gets an option.
1.201 + *
1.202 + * SecureSocket implementations may provide options that can be read with this method.
1.203 + * See individual implementation notes for details.
1.204 + *
1.205 + * @param aOptionName An integer constant which identifies an option.
1.206 + * @param aOptionLevel An integer constant which identifies level of an option.
1.207 + * @param aOption Option value packaged in a descriptor.
1.208 + * @return KErrNone if successful, otherwise another of the system-wide error codes. */
1.209 + virtual TInt GetOpt(TUint aOptionName,TUint aOptionLevel,TDes8& aOption) = 0;
1.210 +
1.211 + /**
1.212 + * Gets an option.
1.213 + *
1.214 + * Secure socket implementations may provide options that can be read with this method.
1.215 + * See individual implementation notes for details.
1.216 + *
1.217 + * @param aOptionName An integer constant which identifies an option.
1.218 + * @param aOptionLevel An integer constant which identifies level of an option.
1.219 + * @param aOption Option value as an integer.
1.220 + * @return KErrNone if successful, otherwise another of the system-wide error codes. */
1.221 + virtual TInt GetOpt(TUint aOptionName,TUint aOptionLevel,TInt& aOption) = 0;
1.222 +
1.223 + /**
1.224 + * Get the protocol in use.
1.225 + *
1.226 + * This method can be used to return the particular protocol/version that is being
1.227 + * used by implementations that support different protocols/versions.
1.228 + * See individual implementation notes for details.
1.229 + *
1.230 + * @param aProtocol A descriptor containing the protocol name/version that is being
1.231 + used. Protocol names can be upto 32 characters long, and so a
1.232 + descriptor of at least that size is required.
1.233 + * @return KErrNone if successful; otherwise, another of the system-wide error codes. */
1.234 + virtual TInt Protocol(TDes& aProtocol) = 0;
1.235 +
1.236 + /**
1.237 + * Receives data from the socket.
1.238 + *
1.239 + * This is an asynchronous method, and will complete when the descriptor has been filled.
1.240 + * Only one Recv or RecvOneOrMore operation can be outstanding at any time.
1.241 + *
1.242 + * @param aDesc A descriptor where data read will be placed.
1.243 + * @param aStatus On completion, will contain an error code: see the system-wide error
1.244 + codes. Note that KErrEof indicates that a remote connection is
1.245 + closed, and that no more data is available for reading. */
1.246 + virtual void Recv(TDes8& aDesc, TRequestStatus & aStatus) = 0;
1.247 +
1.248 + /**
1.249 + * Receives data from the socket.
1.250 + *
1.251 + * This is an asynchronous call, and will complete when at least one byte has been read.
1.252 + * Only one Recv or RecvOneOrMore operation can be outstanding at any time.
1.253 + *
1.254 + * @param aDesc A descriptor where data read will be placed.
1.255 + * @param aStatus On completion, will contain an error code: see the system-wide error
1.256 + * codes. Note that KErrEof indicates that a remote connection is closed,
1.257 + * and that no more data is available for reading.
1.258 + * @param aLen On return, a length which indicates how much data was read.
1.259 + * This is the same as the length of the returned aDesc. */
1.260 + virtual void RecvOneOrMore(TDes8& aDesc, TRequestStatus& aStatus, TSockXfrLength& aLen) = 0;
1.261 +
1.262 + /**
1.263 + * Initiates a renegotiation of the secure connection.
1.264 + *
1.265 + * This is an asynchronous method that completes when renegotiation is complete.
1.266 + * It is valid for both client and server operation.
1.267 + * There can only be one outstanding RenegotiateHandshake operation at a time.
1.268 + *
1.269 + * @param aStatus On completion, will contain an error code: see the system-wide error
1.270 + codes. */
1.271 + virtual void RenegotiateHandshake(TRequestStatus& aStatus) = 0;
1.272 +
1.273 + /**
1.274 + * Send data over the socket.
1.275 + *
1.276 + * This is an asynchronous call. Only one Send operation can be outstanding at any time.
1.277 + * @param aDesc A constant descriptor containing the data to be sent.
1.278 + * @param aStatus On completion, will contain an error code: see the system-wide error
1.279 + codes. */
1.280 + virtual void Send(const TDesC8& aDesc, TRequestStatus& aStatus) = 0;
1.281 +
1.282 + /**
1.283 + * Send data over the socket.
1.284 + *
1.285 + * This is an asynchronous call. Only one Send operation can be outstanding at any time.
1.286 + *
1.287 + * @param aDesc A constant descriptor.
1.288 + * @param aStatus On completion, will contain an error code: see the system-wide error
1.289 + * codes.
1.290 + * @param aLen Filled in with amount of data sent before completion */
1.291 + virtual void Send(const TDesC8& aDesc, TRequestStatus& aStatus, TSockXfrLength& aLen) = 0;
1.292 +
1.293 + /**
1.294 + * Gets the current server certificate.
1.295 + *
1.296 + * When a secure socket is acting in client mode, the returned certificate will be the
1.297 + * certificate for the remote server.
1.298 + * When acting in server mode, the certificate returned will be the one that is being
1.299 + * used as the server certificate.
1.300 + *
1.301 + * @return CX509Certificate A pointer to the certificate. */
1.302 + virtual const CX509Certificate* ServerCert() = 0;
1.303 +
1.304 + /**
1.305 + * Sets a list of cipher suites that are available to use.
1.306 + *
1.307 + * It is assumed that implementations require a list of cipher suites supplied in a descriptor in two
1.308 + * byte format as is the case with the TLS/SSL protocols, i.e. [0x??][0x??].
1.309 + * It is also assumed that the order of suites is important, and so they should be listed
1.310 + * with the preferred suites first.
1.311 + * Implementations should specify if they differ.
1.312 + *
1.313 + * @param aCiphers A descriptor containing the list or ciphers suites to use.
1.314 + * @return Any one of the system error codes, or KErrNone on success. */
1.315 + virtual TInt SetAvailableCipherSuites(const TDesC8& aCiphers) = 0;
1.316 +
1.317 + /**
1.318 + * Sets the client certificate to use.
1.319 + *
1.320 + * When a secure socket is acting in client mode, this method will set the certificate
1.321 + * that will be used if a server requests one.
1.322 + * When acting in server mode, this method will perform no action, but will return KErrNotSupported.
1.323 + * @param aCert A reference to the certificate to use.
1.324 + * @return Any one of the system error codes, or KErrNone on success. */
1.325 + virtual TInt SetClientCert(const CX509Certificate& aCert) = 0;
1.326 +
1.327 + /**
1.328 + * Set the client certificate mode.
1.329 + *
1.330 + * When a secure socket is acting in server mode, the client certificate mode determines
1.331 + * if clients will be requested to provide a certificate.
1.332 + * When acting in client mode, this method will perform no action, but will return KErrNotSupported.
1.333 + *
1.334 + * @see TClientCertMode for details of each available mode.
1.335 + * @param aClientCertMode The client certificate mode to use.
1.336 + * @return Any one of the system error codes, or KErrNone on success. */
1.337 + virtual TInt SetClientCertMode(const TClientCertMode aClientCertMode) = 0;
1.338 +
1.339 + /**
1.340 + * Set the untrusted certificate dialog mode.
1.341 + *
1.342 + * Determines if a dialog is displayed when an untrusted certificate is received.
1.343 + *
1.344 + * @see TDialogMode for details of each available mode.
1.345 + * @param aDialogMode The dialog mode to use.
1.346 + * @return Any one of the system error codes, or KErrNone on success. */
1.347 + virtual TInt SetDialogMode(const TDialogMode aDialogMode) = 0;
1.348 +
1.349 + /**
1.350 + * Sets a socket option.
1.351 + *
1.352 + * Secure socket implementations may provide options that can be set with this method.
1.353 + * See individual implementation notes for details.
1.354 + *
1.355 + * @param aOptionName An integer constant which identifies an option.
1.356 + * @param aOptionLevel An integer constant which identifies level of an option:
1.357 + * i.e. an option level groups related options together.
1.358 + * @param aOption Option value packaged in a descriptor
1.359 + * @return Any one of the system error codes, or KErrNone on success. */
1.360 + virtual TInt SetOpt(TUint aOptionName,TUint aOptionLevel, const TDesC8& aOption=KNullDesC8()) = 0;
1.361 +
1.362 + /**
1.363 + * Sets an option.
1.364 + *
1.365 + * SecureSocket implementations may provide options that can be set with this method.
1.366 + * See individual implementation notes for details.
1.367 + *
1.368 + * @param aOptionName An integer constant which identifies an option.
1.369 + * @param aOptionLevel An integer constant which identifies level of an option:
1.370 + * i.e. an option level groups related options together.
1.371 + * @param aOption Option value as an integer
1.372 + * @return Any one of the system error codes, or KErrNone on success. */
1.373 + virtual TInt SetOpt(TUint aOptionName,TUint aOptionLevel,TInt anOption) = 0;
1.374 +
1.375 + /**
1.376 + * Set a specific protocol/version to use.
1.377 + *
1.378 + * This method can be used to select a particular protocol version to use in
1.379 + * implementations that support different protocols/versions.
1.380 + * See individual implementation notes for details.
1.381 + *
1.382 + * @param aProtocol A reference to a descriptor containing the protocol name/version to use.
1.383 + * @return KErrNone if successful, a system-wide error code if not. */
1.384 + virtual TInt SetProtocol(const TDesC& aProtocol) = 0;
1.385 +
1.386 + /**
1.387 + * Set the server certificate.
1.388 + *
1.389 + * When acting in server mode, this method will set the certificate that is to be used
1.390 + * as the server certificate.
1.391 + * When acting in client mode, this method will perform no action, but will return KErrNotSupported.
1.392 + *
1.393 + * @param aCert The certificate to use.
1.394 + * @return Any one of the system error codes, or KErrNone on success. */
1.395 + virtual TInt SetServerCert(const CX509Certificate& aCert) = 0;
1.396 +
1.397 + /**
1.398 + * Start acting as a client and initiate a handshake with the remote server.
1.399 + *
1.400 + * This is an asynchronous call, and will only complete when the handshake completes
1.401 + * and the secure connection is established, or it fails.
1.402 + *
1.403 + * @param aStatus On completion, any one of the system error codes, or KErrNone on success. */
1.404 + virtual void StartClientHandshake(TRequestStatus& aStatus) = 0;
1.405 +
1.406 + /**
1.407 + * Start acting as a server and listen for a handshake from the remote client.
1.408 + *
1.409 + * This is an asynchronous call, and will only complete when a client completes the
1.410 + * handshake, or if it fails. Normally, the socket passed in will usually have been
1.411 + * previously used in a call to Accept() on a listening socket, but this is not required.
1.412 + *
1.413 + * @param aStatus On completion, any one of the system error codes, or KErrNone on success. */
1.414 + virtual void StartServerHandshake(TRequestStatus& aStatus) = 0;
1.415 +
1.416 + /** Standard destructor. */
1.417 + virtual ~MSecureSocket() {};
1.418 +
1.419 + };
1.420 +
1.421 +#endif // __SECURESOCKETINTERFACE_H__