MSecureSocket Class Reference

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:

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

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

6.2

Constructor & Destructor Documentation

~MSecureSocket()

~MSecureSocket()[inline, virtual]

Standard destructor.

Member Functions Documentation

AvailableCipherSuites(TDes8 &)

TInt AvailableCipherSuites(TDes8 &aCiphers)[pure virtual]

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.

Any one of the system error codes, or KErrNone on success.

Parameters

TDes8 & aCiphersA reference to a descriptor, should be at least 64 bytes long.

CancelAll()

voidCancelAll()[pure virtual]

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.

CancelHandshake()

voidCancelHandshake()[pure virtual]

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.

CancelRecv()

voidCancelRecv()[pure virtual]

Cancels any outstanding read operation. See individual implementation notes for behaviour after canceling.

CancelSend()

voidCancelSend()[pure virtual]

Cancels any outstanding send operation. See individual implementation notes for behaviour after canceling.

ClientCert()

const CX509Certificate *ClientCert()[pure virtual]

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.

A pointer to the client certificate, or NULL if none exists.

ClientCertMode()

TClientCertMode ClientCertMode()[pure virtual]

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. TClientCertMode for details of each mode.

TClientCertMode The current mode that is set.

Close()

voidClose()[pure virtual]

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.

CurrentCipherSuite(TDes8 &)

TInt CurrentCipherSuite(TDes8 &aCipherSuite)[pure virtual]

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.

Any one of the system error codes, or KErrNone on success.

Parameters

TDes8 & aCipherSuiteA 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.

DialogMode()

TDialogMode DialogMode()[pure virtual]

Gets the current dialog mode. TDialogMode for description of valid modes.

TDialogMode The current dialog mode.

FlushSessionCache()

voidFlushSessionCache()[pure virtual]

Flushes the session cache.

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

GetOpt(TUint, TUint, TDes8 &)

TInt GetOpt(TUintaOptionName,
TUintaOptionLevel,
TDes8 &aOption
)[pure virtual]

Gets an option.

SecureSocket implementations may provide options that can be read with this method. See individual implementation notes for details.

KErrNone if successful, otherwise another of the system-wide error codes.

Parameters

TUint aOptionNameAn integer constant which identifies an option.
TUint aOptionLevelAn integer constant which identifies level of an option.
TDes8 & aOptionOption value packaged in a descriptor.

GetOpt(TUint, TUint, TInt &)

TInt GetOpt(TUintaOptionName,
TUintaOptionLevel,
TInt &aOption
)[pure virtual]

Gets an option.

Secure socket implementations may provide options that can be read with this method. See individual implementation notes for details.

KErrNone if successful, otherwise another of the system-wide error codes.

Parameters

TUint aOptionNameAn integer constant which identifies an option.
TUint aOptionLevelAn integer constant which identifies level of an option.
TInt & aOptionOption value as an integer.

Protocol(TDes &)

TInt Protocol(TDes &aProtocol)[pure virtual]

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.

KErrNone if successful; otherwise, another of the system-wide error codes.

Parameters

TDes & aProtocolA 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.

Recv(TDes8 &, TRequestStatus &)

voidRecv(TDes8 &aDesc,
TRequestStatus &aStatus
)[pure virtual]

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.

Parameters

TDes8 & aDescA descriptor where data read will be placed.
TRequestStatus & aStatusOn 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.

RecvOneOrMore(TDes8 &, TRequestStatus &, TSockXfrLength &)

voidRecvOneOrMore(TDes8 &aDesc,
TRequestStatus &aStatus,
TSockXfrLength &aLen
)[pure virtual]

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.

Parameters

TDes8 & aDescA descriptor where data read will be placed.
TRequestStatus & aStatusOn 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.
TSockXfrLength & aLenOn return, a length which indicates how much data was read. This is the same as the length of the returned aDesc.

RenegotiateHandshake(TRequestStatus &)

voidRenegotiateHandshake(TRequestStatus &aStatus)[pure virtual]

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.

Parameters

TRequestStatus & aStatusOn completion, will contain an error code: see the system-wide error codes.

Send(const TDesC8 &, TRequestStatus &)

voidSend(const TDesC8 &aDesc,
TRequestStatus &aStatus
)[pure virtual]

Send data over the socket.

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

Parameters

const TDesC8 & aDescA constant descriptor containing the data to be sent.
TRequestStatus & aStatusOn completion, will contain an error code: see the system-wide error codes.

Send(const TDesC8 &, TRequestStatus &, TSockXfrLength &)

voidSend(const TDesC8 &aDesc,
TRequestStatus &aStatus,
TSockXfrLength &aLen
)[pure virtual]

Send data over the socket.

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

Parameters

const TDesC8 & aDescA constant descriptor.
TRequestStatus & aStatusOn completion, will contain an error code: see the system-wide error codes.
TSockXfrLength & aLenFilled in with amount of data sent before completion

ServerCert()

const CX509Certificate *ServerCert()[pure virtual]

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.

CX509Certificate A pointer to the certificate.

SetAvailableCipherSuites(const TDesC8 &)

TInt SetAvailableCipherSuites(const TDesC8 &aCiphers)[pure virtual]

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.

Any one of the system error codes, or KErrNone on success.

Parameters

const TDesC8 & aCiphersA descriptor containing the list or ciphers suites to use.

SetClientCert(const CX509Certificate &)

TInt SetClientCert(const CX509Certificate &aCert)[pure virtual]

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. Any one of the system error codes, or KErrNone on success.

Parameters

const CX509Certificate & aCertA reference to the certificate to use.

SetClientCertMode(const TClientCertMode)

TInt SetClientCertMode(const TClientCertModeaClientCertMode)[pure virtual]

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.

TClientCertMode for details of each available mode.

Any one of the system error codes, or KErrNone on success.

Parameters

const TClientCertMode aClientCertModeThe client certificate mode to use.

SetDialogMode(const TDialogMode)

TInt SetDialogMode(const TDialogModeaDialogMode)[pure virtual]

Set the untrusted certificate dialog mode.

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

TDialogMode for details of each available mode.

Any one of the system error codes, or KErrNone on success.

Parameters

const TDialogMode aDialogModeThe dialog mode to use.

SetOpt(TUint, TUint, const TDesC8 &)

TInt SetOpt(TUintaOptionName,
TUintaOptionLevel,
const TDesC8 &aOption =  KNullDesC8()
)[pure virtual]

Sets a socket option.

Secure socket implementations may provide options that can be set with this method. See individual implementation notes for details.

Any one of the system error codes, or KErrNone on success.

Parameters

TUint aOptionNameAn integer constant which identifies an option.
TUint aOptionLevelAn integer constant which identifies level of an option: i.e. an option level groups related options together.
const TDesC8 & aOption =  KNullDesC8()Option value packaged in a descriptor

SetOpt(TUint, TUint, TInt)

TInt SetOpt(TUintaOptionName,
TUintaOptionLevel,
TIntanOption
)[pure virtual]

Sets an option.

SecureSocket implementations may provide options that can be set with this method. See individual implementation notes for details.

Any one of the system error codes, or KErrNone on success.

Parameters

TUint aOptionNameAn integer constant which identifies an option.
TUint aOptionLevelAn integer constant which identifies level of an option: i.e. an option level groups related options together.
TInt anOption

SetProtocol(const TDesC &)

TInt SetProtocol(const TDesC &aProtocol)[pure virtual]

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.

KErrNone if successful, a system-wide error code if not.

Parameters

const TDesC & aProtocolA reference to a descriptor containing the protocol name/version to use.

SetServerCert(const CX509Certificate &)

TInt SetServerCert(const CX509Certificate &aCert)[pure virtual]

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.

Any one of the system error codes, or KErrNone on success.

Parameters

const CX509Certificate & aCertThe certificate to use.

StartClientHandshake(TRequestStatus &)

voidStartClientHandshake(TRequestStatus &aStatus)[pure virtual]

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.

Parameters

TRequestStatus & aStatusOn completion, any one of the system error codes, or KErrNone on success.

StartServerHandshake(TRequestStatus &)

voidStartServerHandshake(TRequestStatus &aStatus)[pure virtual]

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.

Parameters

TRequestStatus & aStatusOn completion, any one of the system error codes, or KErrNone on success.