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

Public Member Functions
	~MSecureSocket()
TInt	AvailableCipherSuites(TDes8 &)
void	CancelAll()
void	CancelHandshake()
void	CancelRecv()
void	CancelSend()
const CX509Certificate *	ClientCert()
TClientCertMode	ClientCertMode()
void	Close()
TInt	CurrentCipherSuite(TDes8 &)
TDialogMode	DialogMode()
void	FlushSessionCache()
TInt	GetOpt(TUint, TUint, TDes8 &)
TInt	GetOpt(TUint, TUint, TInt &)
TInt	Protocol(TDes &)
void	Recv(TDes8 &, TRequestStatus &)
void	RecvOneOrMore(TDes8 &, TRequestStatus &, TSockXfrLength &)
void	RenegotiateHandshake(TRequestStatus &)
void	Send(const TDesC8 &, TRequestStatus &)
void	Send(const TDesC8 &, TRequestStatus &, TSockXfrLength &)
const CX509Certificate *	ServerCert()
TInt	SetAvailableCipherSuites(const TDesC8 &)
TInt	SetClientCert(const CX509Certificate &)
TInt	SetClientCertMode(const TClientCertMode)
TInt	SetDialogMode(const TDialogMode)
TInt	SetOpt(TUint, TUint, const TDesC8 &)
TInt	SetOpt(TUint, TUint, TInt)
TInt	SetProtocol(const TDesC &)
TInt	SetServerCert(const CX509Certificate &)
void	StartClientHandshake(TRequestStatus &)
void	StartServerHandshake(TRequestStatus &)

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 & aCiphers

A reference to a descriptor, should be at least 64 bytes long.

CancelAll()

void

CancelAll

(

)

[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()

void

CancelHandshake

(

)

[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()

void

CancelRecv

(

)

[pure virtual]

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

CancelSend()

void

CancelSend

(

)

[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()

void

(

)

[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 & aCipherSuite

A 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()

void

FlushSessionCache

(

)

[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	(	TUint	aOptionName,
			TUint	aOptionLevel,
			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 aOptionName	An integer constant which identifies an option.
TUint aOptionLevel	An integer constant which identifies level of an option.
TDes8 & aOption	Option value packaged in a descriptor.

GetOpt(TUint, TUint, TInt &)

TInt	GetOpt	(	TUint	aOptionName,
			TUint	aOptionLevel,
			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 aOptionName	An integer constant which identifies an option.
TUint aOptionLevel	An integer constant which identifies level of an option.
TInt & aOption	Option 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 & aProtocol

A 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 &)

void	Recv	(	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 & aDesc	A descriptor where data read will be placed.
TRequestStatus & aStatus	On 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 &)

void	RecvOneOrMore	(	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 & aDesc	A descriptor where data read will be placed.
TRequestStatus & aStatus	On 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 & aLen	On return, a length which indicates how much data was read. This is the same as the length of the returned aDesc.

RenegotiateHandshake(TRequestStatus &)

void

RenegotiateHandshake

(

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 & aStatus

On completion, will contain an error code: see the system-wide error codes.

Send(const TDesC8 &, TRequestStatus &)

void	Send	(	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 & aDesc	A constant descriptor containing the data to be sent.
TRequestStatus & aStatus	On completion, will contain an error code: see the system-wide error codes.

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

void	Send	(	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 & aDesc	A constant descriptor.
TRequestStatus & aStatus	On completion, will contain an error code: see the system-wide error codes.
TSockXfrLength & aLen	Filled 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 & aCiphers

A 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 & aCert

A reference to the certificate to use.

SetClientCertMode(const TClientCertMode)

TInt

SetClientCertMode

(

const TClientCertMode

aClientCertMode

)

[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 aClientCertMode

The client certificate mode to use.

SetDialogMode(const TDialogMode)

TInt

SetDialogMode

(

const TDialogMode

aDialogMode

)

[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 aDialogMode

The dialog mode to use.

SetOpt(TUint, TUint, const TDesC8 &)

TInt	SetOpt	(	TUint	aOptionName,
			TUint	aOptionLevel,
			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 aOptionName	An integer constant which identifies an option.
TUint aOptionLevel	An 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	(	TUint	aOptionName,
			TUint	aOptionLevel,
			TInt	anOption
		)	[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 aOptionName	An integer constant which identifies an option.
TUint aOptionLevel	An 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 & aProtocol

A 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 & aCert

The certificate to use.

StartClientHandshake(TRequestStatus &)

void

StartClientHandshake

(

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 & aStatus

On completion, any one of the system error codes, or KErrNone on success.

StartServerHandshake(TRequestStatus &)

void

StartServerHandshake

(

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 & aStatus

On completion, any one of the system error codes, or KErrNone on success.