CTLSSession Class Reference

class CTLSSession : private CBase

This class provides a wrapper around a MTLSSession object. A number of its methods simply call corresponding MTLSSession methods. However it also acts as an intermediary between the client and cryptographic libraries where services not involving tokens are required.

Inherits from

Constructor & Destructor Documentation

CTLSSession(CTlsSessionImpl *)

CTLSSession ( CTlsSessionImpl * aSessionPtr )

Parameters

CTlsSessionImpl * aSessionPtr

~CTLSSession()

IMPORT_C ~CTLSSession ( )

Member Functions Documentation

Attributes()

IMPORT_C CTlsCryptoAttributes * Attributes ( )

The first call to CTLSProvider takes place before ClientHello is send, then as the handshake progress, the information relevant for Provider and token will be gradually filled in the structure. The ownership will then be passed to the CTLSSession object. This function returns the pointer to the structure. This method returns the CTlsCryptoAttributes structure associated with this session

CancelRequest()

IMPORT_C void CancelRequest ( )

This method cancels all the asynchronous operations of CTLSSession

This synchronous method cancels all the asynchronous operations of CTLSProvider

CertificateVerifySignatureL(CMessageDigest *, CMessageDigest *, HBufC8 *&, TRequestStatus &)

IMPORT_C void CertificateVerifySignatureL ( CMessageDigest * aMd5DigestInput,
CMessageDigest * aShaDigestInput,
HBufC8 *& aOutput,
TRequestStatus & aStatus
)
Plain text, the overview for this function. optional further explanation may appear here
Post-condition
CClassExample object is now fully initialised
This asynchronous method generates a signature of the given input with client private key. Used in client certificate verify message for both SSL/TLS case. This input for this message is a hash of concatenation of all the handshake messages exchanged thus far (as specified by RFC2246 and SSL3.0 specification). The hash of the handshake is finalised and then send to the token for signing.

Parameters

CMessageDigest * aMd5DigestInput
CMessageDigest * aShaDigestInput
HBufC8 *& aOutput Client's Certificate Verify message
TRequestStatus & aStatus asynchronous request status set on the completion

ClientCertificate(HBufC8 *&, TRequestStatus &)

IMPORT_C void ClientCertificate ( HBufC8 *& aEncodedClientCert,
TRequestStatus & aStatus
)

This asynchronous method is used to retrieve a client certificate in its encoded form, which would be normally send out to the server. If the connection has reached a stage where the session would have been cached, then this API would retrieve the information ( CCTCertInfo ) from token's cache and returns the retrieved certificate from the Certstore. In all other case, the information ( CCTCertInfo ) is stored locally This asynchronous method is used to retrieve a client certificate in its encoded form, which would be normally send out to the server. If the connection has reached a stage where the session would have been cached, then this API would retrieve the information ( CCTCertInfo ) from token's cache and returns the retrieved certificate from the Certstore. In all other case, the information ( CCTCertInfo ) is stored locally

Parameters

HBufC8 *& aEncodedClientCert Output - Encoded client sertificate
TRequestStatus & aStatus asynchronous request status set on the completion

ClientCertificate(CX509Certificate *&, TRequestStatus &)

IMPORT_C void ClientCertificate ( CX509Certificate *& aX509ClientCert,
TRequestStatus & aStatus
)

This asynchronous method is used to retrieve a client certificate in an X509 form, which would be normally used for displaying it to the user. If the connection has reached a stage where the session would have been cached, then this API would retrieve the information ( CCTCertInfo ) from token's cache and returns the retrieved certificate from the Certstore. In all other case, the information ( CCTCertInfo ) is stored locally. This asynchronous method is used to retrieve a client certificate in an X509 form, which would be normally used for displaying it to the user. If the connection has reached a stage where the session would have been cached, then this API would retrieve the information ( CCTCertInfo ) from token's cache and returns the retrieved certificate from the Certstore. In all other case, the information ( CCTCertInfo ) is stored locally.

Parameters

CX509Certificate *& aX509ClientCert Output - Client certificate in returned in an x509 format
TRequestStatus & aStatus asynchronous request status set on the completion

ClientCertificate(RPointerArray< HBufC8 > *, TRequestStatus &)

IMPORT_C void ClientCertificate ( RPointerArray < HBufC8 > * aClientCertArray,
TRequestStatus & aStatus
)

This asynchronous method is used to retrieve a client certificate chain in its encoded form, which would be normally send out to the server. If the connection has reached a stage where the session would have been cached, then this API would retrieve the information ( CCTCertInfo ) from token's cache and returns the retrieved certificate from the Certstore. In all other case, the information ( CCTCertInfo ) is stored locally

Parameters

RPointerArray < HBufC8 > * aClientCertArray
TRequestStatus & aStatus - Asynchronous request status value

ClientFinishedMsgL(CMessageDigest *, CMessageDigest *, HBufC8 *&, TRequestStatus &)

IMPORT_C void ClientFinishedMsgL ( CMessageDigest * aMd5DigestInput,
CMessageDigest * aShaDigestInput,
HBufC8 *& aOutput,
TRequestStatus & aStatus
)

This asynchronous method generates a SSL/TLS protocol's Client 'Finished' message. This input for this message is a hash of concatenation of all the handshake messages exchanged thus far (as specified by RFC2246 and SSL3.0 specification). In order to create the required output,

Parameters

CMessageDigest * aMd5DigestInput
CMessageDigest * aShaDigestInput
HBufC8 *& aOutput - The result of the operation i.e. the Client's 'Finished' message.
TRequestStatus & aStatus - Asynchronous request status value that can be checked by the client.

ClientKeyExchange(HBufC8 *&, TRequestStatus &)

IMPORT_C void ClientKeyExchange ( HBufC8 *& aClientKeyExch,
TRequestStatus & aStatus
)

The ClientKeyExchange operation includes the following. The generation of the pre-master secret, The derivation of the master secret, Generation of keys for bulk data encryption and MAC secrets, If weak Export cipher is used, generation of Weak keys, Creation of CTLSSession's member objects responsible for symmetric encryption and HMAC hashing. ClientKeyExchange message created and returned This method returns the ClientKeyExchange message. The following functionalities are executed The ClientKeyExchange operation includes the following

Inside the token: 1. The generation of the pre-master secret, 2. The derivation of the master secret, 3. Generation of keys for bulk data encryption and MAC secrets, 4. ClientKeyExchange message created

Inside the Provider 1. If weak Export cipher is used, generation of Weak keys 2. Creation of CTlsSessionImpl's member objects responsible for symmetric encryption and HMAC hashing. 3. ClientKeyExchange message returned

Post-condition
Encryption,Decryption and HMAC objects are created

Parameters

HBufC8 *& aClientKeyExch Output - Client key Exchange message is returned
TRequestStatus & aStatus asynchronous request status set on the completion

DecryptAndVerifyL(const TDesC8 &, HBufC8 *&, TInt64 &, TRecordProtocol &)

IMPORT_C TInt DecryptAndVerifyL ( const TDesC8 & aInput,
HBufC8 *& aOutput,
TInt64 & aSeqNumber,
TRecordProtocol & aType
)

On receiving an input data, this method decrypts the data, parses the actual data from its MAC and verifies it. If the MAC is verified correctly the output will be returned The encryption and decryption objects should have been created in an earlier call to ClientKeyExchange before calling this API On receiving an input data, this synchronous method decrypts the data, parses the actual data from its MAC and verifies it. If the MAC is verified correctly, then the output will be returned The encryption and decryption objects should have been created in an earlier call to ClientKeyExchange before calling this API

Pre-condition
ClientKeyExchange method should have been called
CTlsSessionImpl::ClientKeyExchange
leave
Symbian Wide error code

Parameters

const TDesC8 & aInput Data to be Decrypted
HBufC8 *& aOutput Dencrypted output
TInt64 & aSeqNumber Sequence number of the packet
TRecordProtocol & aType Record protocol type, e.g: handshake, alerts, application data, etc

EncryptL(const TDesC8 &, HBufC8 *&, TInt64 &, TRecordProtocol &)

IMPORT_C TInt EncryptL ( const TDesC8 & aInput,
HBufC8 *& aOutput,
TInt64 & aSeqNumber,
TRecordProtocol & aType
)

On receiving an input data, this method computes the MAC, appends it into the input and encrypts the whole block. The encryption and decryption objects should have been created in an earlier call to ClientKeyExchange before calling this API On receiving an input data, this synchronous method computes the MAC, appends it into the input and encrypts the whole block. The encryption and decryption objects should have been created in an earlier call to ClientKeyExchange before calling this API. the MAC computations differ for TLS and SSL.

Pre-condition
ClientKeyExchange method should have been called
CTlsSessionImpl::ClientKeyExchange
leave
Symbian Wide error code

Parameters

const TDesC8 & aInput Data to be encrypted
HBufC8 *& aOutput Encrypted output
TInt64 & aSeqNumber Sequence number of the packet
TRecordProtocol & aType Record protocol type, e.g: handshake, alerts, application data, etc

KeyDerivation(const TDesC8 &, const TTLSMasterSecretInput &, TDes8 &)

IMPORT_C TInt KeyDerivation ( const TDesC8 & aLabel,
const TTLSMasterSecretInput & aMasterSecretInput,
TDes8 & aKeyingMaterial
)
This synchronous method provides the EAP string that is derived or computed from master secret key, "client key encryption" string (or any string from client), client and server hello random values. The EAP string returned would be of 128 + 64 bytes length.
Pre-condition
object should should have been initialised (by call to InitL) and master secret generated (by call to ClientKeyExchange) before call to this method
Post-condition
session is cached in case of successful handshake
CTlsSessionImpl::ClientKeyExchange This synchronous method provides the EAP string that is derived or computed from master secret key, "client key encryption" string (or any string from client), client and server hello random values. The EAP string returned would be of 128 + 64 bytes length.
Pre-condition
object should should have been initialised (by call to InitL) and master secret generated (by call to ClientKeyExchange) before call to this method
Post-condition
session is cached in case of successful handshake
CTlsSessionImpl::ClientKeyExchange

Parameters

const TDesC8 & aLabel Contains the string "client key encryption".
const TTLSMasterSecretInput & aMasterSecretInput The structure containing "Client and Server Random" binary data.
TDes8 & aKeyingMaterial Contains the EAP 128 + 64 bytes string.

NewL(CTlsSessionImpl *)

IMPORT_C CTLSSession * NewL ( CTlsSessionImpl * aSessionPtr ) [static]

Allocates and constructs a new CTlsSessionImpl object.

Parameters

CTlsSessionImpl * aSessionPtr - a session pointer to CTLsSessionImpl

ServerCertificate(CX509Certificate *&, TRequestStatus &)

IMPORT_C void ServerCertificate ( CX509Certificate *& aX509ServerCert,
TRequestStatus & aStatus
)

This asynchronous method is used to retrieve the associated server certificate of the current session in its X509 form, which would be normally used for displaying it to the user. If the connection has reached a stage where the session would have been cached, then this API would retrieve the certificate from the Token. In all other case, the certificate is stored locally. This asynchronous method is used to retrieve the associated server certificate of the current session in its X509 form, which would be normally used for displaying it to the user. If the connection has reached a stage where the session would have been cached, then this API would retrieve the certificate from the Token. In all other case, the certificate is stored locally.

Parameters

CX509Certificate *& aX509ServerCert Output - Server certificate returned in an x509 format
TRequestStatus & aStatus asynchronous request status set on the completion

VerifyServerFinishedMsgL(CMessageDigest *, CMessageDigest *, const TDesC8 &, TRequestStatus &)

IMPORT_C void VerifyServerFinishedMsgL ( CMessageDigest * aMd5DigestInput,
CMessageDigest * aShaDigestInput,
const TDesC8 & aActualFinishedMsg,
TRequestStatus & aStatus
)

This method generates ServerFinished message given as an input hash of concatenation of all handshake messages (as specified by RFC2246 and SSL3.0 specification). In order to create required output, the function calls MTLSSesssion::PHash with the following input string: This asynchronous method verifies SSL/TLS protocol's Server 'Finished' message. This method generates ServerFinished message given as an input hash of concatenation of all handshake messages (as specified by RFC2246 and SSL3.0 specification). In order to create required output, the function calls MTLSSesssion::PHash with the following input string: TLS Protocol "client finished" + iMd5DigestInput + iShaDigestInput

SSL Protocol (iMd5DigestInput +" SRVR") + (iShaDigestInput +" SRVR")

Parameters

CMessageDigest * aMd5DigestInput
CMessageDigest * aShaDigestInput
const TDesC8 & aActualFinishedMsg Server's received 'Finished' message
TRequestStatus & aStatus asynchronous request status set on the completion

Member Data Documentation

CTlsSessionImpl * iTlsSessionImpl

CTlsSessionImpl * iTlsSessionImpl [private]