MSecureSocket Class Reference

#include <securesocketinterface.h>

Link against: ssl.lib

class MSecureSocket

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

Detailed Description

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

Since: 6.2

Constructor & Destructor Documentation

~MSecureSocket ( )

~MSecureSocket

(

)

[inline, virtual]

Standard destructor.

Member Function 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.

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

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

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.

Returns: 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.

See also: TClientCertMode for details of each mode.

Returns: 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.

Parameter	Description
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.

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

DialogMode ( )

TDialogMode

DialogMode

(

)

[pure virtual]

Gets the current dialog mode.

See also: TDialogMode for description of valid modes.

Returns: 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.

Parameter	Description
aOptionName	An integer constant which identifies an option.
aOptionLevel	An integer constant which identifies level of an option.
aOption	Option value packaged in a descriptor.

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

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.

Parameter	Description
aOptionName	An integer constant which identifies an option.
aOptionLevel	An integer constant which identifies level of an option.
aOption	Option value as an integer.

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

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.

Parameter	Description
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.

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

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.

Parameter	Description
aDesc	A descriptor where data read will be placed.
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.

Parameter	Description
aDesc	A descriptor where data read will be placed.
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.
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.

Parameter	Description
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.

Parameter	Description
aDesc	A constant descriptor containing the data to be sent.
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.

Parameter	Description
aDesc	A constant descriptor.
aStatus	On completion, will contain an error code: see the system-wide error codes.
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.

Returns: 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.

Parameter	Description
aCiphers	A descriptor containing the list or ciphers suites to use.

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

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.

Parameter	Description
aCert	A reference to the certificate to use.

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

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.

See also: TClientCertMode for details of each available mode.

Parameter	Description
aClientCertMode	The client certificate mode to use.

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

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.

See also: TDialogMode for details of each available mode.

Parameter	Description
aDialogMode	The dialog mode to use.

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

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.

Parameter	Description
aOptionName	An integer constant which identifies an option.
aOptionLevel	An integer constant which identifies level of an option: i.e. an option level groups related options together.
aOption	Option value packaged in a descriptor

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

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.

Parameter	Description
aOptionName	An integer constant which identifies an option.
aOptionLevel	An integer constant which identifies level of an option: i.e. an option level groups related options together.

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

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.

Parameter	Description
aProtocol	A reference to a descriptor containing the protocol name/version to use.

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

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.

Parameter	Description
aCert	The certificate to use.

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

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.

Parameter	Description
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.

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