Class CSecureSocket

class CSecureSocket : public CBase;

Description

Secure sockets class.

Derivation

• CBase - Base class for all classes to be instantiated on the heap

• CSecureSocket - Secure sockets class

Members

Defined in CSecureSocket:
AvailableCipherSuites(), CancelAll(), CancelHandshake(), CancelRecv(), CancelSend(), ClientCert(), ClientCertMode(), Close(), CurrentCipherSuite(), DialogMode(), FlushSessionCache(), GetOpt(), GetOpt(), NewL(), NewL(), Protocol(), Recv(), RecvOneOrMore(), RenegotiateHandshake(), Send(), Send(), ServerCert(), SetAvailableCipherSuites(), SetClientCert(), SetClientCertMode(), SetDialogMode(), SetOpt(), SetOpt(), SetProtocol(), SetServerCert(), StartClientHandshake(), StartServerHandshake()

Inherited from CBase:
Delete(), Extension_(), operator new()

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

Description

Creates and returns a pointer to a new secure socket.

A reference to an already open and connected socket should be passed in, along with a descriptor that contains the protocol name.

Parameters

RSocket &aSocket A reference to an open and connected RSocket object. const TDesC &aProtocol A constant descriptor containing the protocol name.

Return value

CSecureSocket * A pointer to the newly created secure socket, or NULL if the creation failed.

static IMPORT_C CSecureSocket *NewL(MGenericSecureSocket &aSocket, const TDesC &aProtocol);

Description

Creates and returns a pointer to a new secure socket.

A reference to a socket derived from MGenericSecureSocket should be passed in, along with a descriptor that contains the protocol name.

Parameters

MGenericSecureSocket &aSocket A reference to an MGenericSecureSocket derived object. const TDesC &aProtocol A constant descriptor containing the protocol name.

Return value

CSecureSocket * A pointer to the newly created secure socket, or NULL if the creation failed.

IMPORT_C TInt AvailableCipherSuites(TDes8 &aCiphers);

Description

Gets the available cipher suites.

Parameters

TDes8 &aCiphers Descriptor holding the ciphers.

Return value

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

IMPORT_C void CancelAll();

Description

Cancels all the send and receive actions in the SSL state machine.

IMPORT_C void CancelHandshake();

Description

Cancels the handshake.

IMPORT_C void CancelRecv();

Description

Cancels a receive action in the SSL state machine.

IMPORT_C void CancelSend();

Description

Cancels a send action in the SSL state machine.

IMPORT_C const CX509Certificate *ClientCert();

Description

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 local certificate.

Return value

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

IMPORT_C TClientCertMode ClientCertMode();

Description

Gets the current client certificate mode.

The client certificate mode is used when the socket is acting as a server, and determines whether a client certificate is requested.

Return value

TClientCertMode The current mode that is set.

IMPORT_C TDialogMode DialogMode();

Description

Gets the current dialog mode.

Return value

TDialogMode The current dialog mode.

IMPORT_C void Close();

Description

Closes the secure connection and the socket.

Implementations should terminate the secure connection gracefully as appropriate to their protocol. The RSocket object is not destoyed: this is left to the client application.

IMPORT_C TInt CurrentCipherSuite(TDes8 &aCipherSuite);

Description

Gets the current cipher suite in use.

The current cipher suite is returned in the referenced buffer in two byte format as, i.e. [0x??][0x??].

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 implementation notes for details.

Return value

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

IMPORT_C void FlushSessionCache();

Description

Flushes the session cache.

IMPORT_C TInt GetOpt(TUint aOptionName, TUint aOptionLevel, TDes8 &aOption);

Description

Gets an option.

Secure socket implementations may provide options that can be used with this function.

Parameters

TUint aOptionName An integer constant which identifies an option. TUint aOptionLevel An integer constant which identifies the level of an option, i.e. an option level group of related options. TDes8 &aOption An option value packaged in a descriptor.

Return value

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

IMPORT_C TInt GetOpt(TUint aOptionName, TUint aOptionLevel, TInt &aOption);

Description

Gets an option.

Secure socket implementations may provide options that can be used with this method.

Parameters

TUint aOptionName An integer constant which identifies an option. TUint aOptionLevel An integer constant which identifies the level of an option, i.e. an option level group of related options. TInt &aOption An integer option value.

Return value

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

IMPORT_C TInt Protocol(TDes &aProtocol);

Description

Gets 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.

Parameters

TDes &aProtocol A descriptor containing the protocol name/version that is being used. Protocol names can be up to 32 characters long, and so a descriptor of at least that size is required.

Return value

TInt KErrNone

IMPORT_C void Recv(TDes8 &aDesc, TRequestStatus &aStatus);

Description

Receives data from the socket.

This is an asynchronous function, and completes 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, KErrNone if successful; KErrEof if a remote connection is closed and there is no more data; KErrNotReady if called when an operation is still outstanding; or another system-wide error code.

IMPORT_C void RecvOneOrMore(TDes8 &aDesc, TRequestStatus &aStatus, TSockXfrLength &aLen);

Description

Receives data from the socket.

This is an asynchronous function, 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, KErrNone if successful; KErrEof if a remote connection is closed and there is no more data; KErrNotReady if called when an operation is still outstanding; or another system-wide error code. TSockXfrLength &aLen On completion, the length of the descriptor, aDesc.

IMPORT_C void RenegotiateHandshake(TRequestStatus &aStatus);

Description

Initiates a renegotiation of the secure connection.

This is an asynchronous function 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, KErrNone if successful; KErrNotReady if called when an operation is still outstanding; or another system-wide error code.

IMPORT_C void Send(const TDesC8 &aDesc, TRequestStatus &aStatus, TSockXfrLength &aLen);

Description

Sends data over the socket.

This is an asynchronous function. Only one Send() operation can be outstanding at any time.

Parameters

const TDesC8 &aDesc A constant descriptor with the data to be send. TRequestStatus &aStatus On completion, KErrNone if successful; KErrNotReady if called when an operation is still outstanding; or another system-wise error code. TSockXfrLength &aLen On completion, the amount of data sent.

IMPORT_C void Send(const TDesC8 &aDesc, TRequestStatus &aStatus);

Description

Sends data over the socket.

This is an asynchronous function. Only one Send() operation can be outstanding at any time, and the function will complete with the error KErrNotReady if called when a send is still outstanding.

Parameters

const TDesC8 &aDesc A constant descriptor. The application must not modify this descriptor until the Send() completes. TRequestStatus &aStatus On completion, KErrNone; KErrNotReady if called when a send is still outstanding, if successful; or another system-wide error code.

IMPORT_C const CX509Certificate *ServerCert();

Description

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 local certificate.

Note that the operation in server mode is currently reserved for future use, and returns NULL.

Return value

const CX509Certificate * Pointer to the certificate, or NULL if no certificate is available.

IMPORT_C TInt SetAvailableCipherSuites(const TDesC8 &aCiphers);

Description

Sets the list of cipher suites that are available for use.

The list of cipher suites should be supplied in a descriptor in the format as per the TLS RFC, i.e. [0x??][0x??] for each suite. The order of suites is important, and so they should be listed with the preferred suites first.

Parameters

const TDesC8 &aCiphers Descriptor holding the cipher suites list.

Return value

TInt KErrNone if successful; otherwise, a system-wide error code.

IMPORT_C TInt SetClientCert(const CX509Certificate &aCert);

Description

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, if called this method will perform no action, but will return KErrNotSupported.

Note that this method is currently reserved for future use, and always returns KErrNotSupported.

Parameters

const CX509Certificate &aCert The client certificate.

Return value

TInt KErrNone if successful; otherwise, a system-wide error code.

IMPORT_C TInt SetClientCertMode(const TClientCertMode aClientCertMode);

Description

Sets the client certificate mode.

Parameters

const TClientCertMode aClientCertMode The client certificate mode to set.

Return value

TInt KErrNone if successful; otherwise, a system-wide error code.

IMPORT_C TInt SetDialogMode(const TDialogMode aDialogMode);

Description

Sets the Dialog mode.

Parameters

const TDialogMode aDialogMode Dialog mode to set.

Return value

TInt KErrNone if successful, otherwise, a system-wide error code.

IMPORT_C TInt SetProtocol(const TDesC &aProtocol);

Description

Sets the protocol

Parameters

const TDesC &aProtocol Descriptor holding the protocol name to be set, e.g. "SSL3.0" or "TLS1.0".

Return value

TInt KErrNone if successful, or KErrNotSupported if the protocol in the descriptor isn't recognized.

IMPORT_C TInt SetOpt(TUint aOptionName, TUint aOptionLevel, const TDesC8 &aOption=TPtrC8(0,0));

Description

Sets an option.

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

In order for full verification of the Server certificate during handshake negotiation the domain name must be set. This is done using the option KSoSSLDomainName, with the option level KSolInetSSL.

Parameters

TUint aOptionName An integer constant which identifies an option. TUint aOptionLevel An integer constant which identifies the level of an option: i.e. an option level group of related options. const TDesC8 &aOption An option value packaged in a descriptor.

Return value

TInt KErrNone if successful; otherwise, a system-wide error code.

IMPORT_C TInt SetOpt(TUint aOptionName, TUint aOptionLevel, TInt aOption);

Description

Sets an option.

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

Parameters

TUint aOptionName An integer constant which identifies an option. TUint aOptionLevel An integer constant which identifies the level of an option: i.e. an option level group of related options. TInt aOption An option value as an integer .

Return value

TInt KErrNone if successful; otherwise, a system-wide error code.

IMPORT_C TInt SetServerCert(const CX509Certificate &aCert);

Description

Sets the server X.509 certificate.

Parameters

const CX509Certificate &aCert The certificate to use.

Return value

TInt KErrNone if successful; otherwise, a system-wide error code.

IMPORT_C void StartClientHandshake(TRequestStatus &aStatus);

Description

Starts the client handshake.

Parameters

TRequestStatus &aStatus On completion, KErrNone if successful; otherwise, a system-wide error code.

IMPORT_C void StartServerHandshake(TRequestStatus &aStatus);

Description

Starts the server handshake.

Parameters

TRequestStatus &aStatus On completion, KErrNone if successful; otherwise, a system-wide error code.