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".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
17 #ifndef __SECURESOCKETINTERFACE_H__
18 #define __SECURESOCKETINTERFACE_H__
27 * @file SecureSocketInterface.h
28 * Definition of the MSecureSocket class.
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.
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
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
63 /** All untrusted certificates result in a user dialog. */
65 /** Untrusted certificates are canceled without user confirmation. */
72 * Abstract interface API for secure socket implementations.
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.
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:
86 * static MSecureSocket* NewL( RSocket& aSocket, const TDesC& aProtocol );
89 * aSocket A reference to an already opened and connected socket.
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.
95 * For error code definitions see SSLErr.h
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.
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;
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;
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;
129 * Cancels any outstanding read operation.
130 * See individual implementation notes for behaviour after canceling. */
131 virtual void CancelRecv() = 0;
134 * Cancels any outstanding send operation.
135 * See individual implementation notes for behaviour after canceling. */
136 virtual void CancelSend() = 0;
139 * Gets the current client certificate.
141 * When a secure socket is acting in server mode, the returned certificate will be the certificate that the remote
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.
146 * Note that if there is no client certificate defined, either in server or client mode,
147 * this method will return NULL.
149 * @return A pointer to the client certificate, or NULL if none exists.*/
150 virtual const CX509Certificate* ClientCert() = 0;
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;
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.
166 virtual void Close() = 0;
169 * Gets the current cipher suite in use.
170 * The current cipher suite is returned in the referenced buffer.
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.
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
180 * @return Any one of the system error codes, or KErrNone on success. */
181 virtual TInt CurrentCipherSuite( TDes8& aCipherSuite ) = 0;
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;
190 * Flushes the session cache.
192 * If protocols implement a session cache, this method will cause that cache to be flushed. */
193 virtual void FlushSessionCache() = 0;
198 * SecureSocket implementations may provide options that can be read with this method.
199 * See individual implementation notes for details.
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;
210 * Secure socket implementations may provide options that can be read with this method.
211 * See individual implementation notes for details.
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;
220 * Get the protocol in use.
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.
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;
233 * Receives data from the socket.
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.
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;
245 * Receives data from the socket.
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.
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;
259 * Initiates a renegotiation of the secure connection.
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.
265 * @param aStatus On completion, will contain an error code: see the system-wide error
267 virtual void RenegotiateHandshake(TRequestStatus& aStatus) = 0;
270 * Send data over the socket.
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
276 virtual void Send(const TDesC8& aDesc, TRequestStatus& aStatus) = 0;
279 * Send data over the socket.
281 * This is an asynchronous call. Only one Send operation can be outstanding at any time.
283 * @param aDesc A constant descriptor.
284 * @param aStatus On completion, will contain an error code: see the system-wide error
286 * @param aLen Filled in with amount of data sent before completion */
287 virtual void Send(const TDesC8& aDesc, TRequestStatus& aStatus, TSockXfrLength& aLen) = 0;
290 * Gets the current server certificate.
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.
297 * @return CX509Certificate A pointer to the certificate. */
298 virtual const CX509Certificate* ServerCert() = 0;
301 * Sets a list of cipher suites that are available to use.
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.
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;
314 * Sets the client certificate to use.
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;
324 * Set the client certificate mode.
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.
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;
336 * Set the untrusted certificate dialog mode.
338 * Determines if a dialog is displayed when an untrusted certificate is received.
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;
346 * Sets a socket option.
348 * Secure socket implementations may provide options that can be set with this method.
349 * See individual implementation notes for details.
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;
361 * SecureSocket implementations may provide options that can be set with this method.
362 * See individual implementation notes for details.
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;
372 * Set a specific protocol/version to use.
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.
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;
383 * Set the server certificate.
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.
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;
394 * Start acting as a client and initiate a handshake with the remote server.
396 * This is an asynchronous call, and will only complete when the handshake completes
397 * and the secure connection is established, or it fails.
399 * @param aStatus On completion, any one of the system error codes, or KErrNone on success. */
400 virtual void StartClientHandshake(TRequestStatus& aStatus) = 0;
403 * Start acting as a server and listen for a handshake from the remote client.
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.
409 * @param aStatus On completion, any one of the system error codes, or KErrNone on success. */
410 virtual void StartServerHandshake(TRequestStatus& aStatus) = 0;
412 /** Standard destructor. */
413 virtual ~MSecureSocket() {};
417 #endif // __SECURESOCKETINTERFACE_H__