MTLSSession Class Reference

class MTLSSession : public MCTTokenInterface

This is an interface to a cryptographic token for the cryptographic services required by the TLS/SSL protocols.

Inherits from

Member Functions Documentation

CancelClientCertificate()

void CancelClientCertificate ( ) [pure virtual]

Cancels corresponding asynchronous request.

CancelClientKeyExchange()

void CancelClientKeyExchange ( ) [pure virtual]

Cancels corresponding asynchronous request.

CancelComputeDigitalSignature()

void CancelComputeDigitalSignature ( ) [pure virtual]

Cancels corresponding asynchronous request.

CancelConnectionEstablished()

void CancelConnectionEstablished ( ) [pure virtual]

Cancels corresponding asynchronous request.

CancelPHash()

void CancelPHash ( ) [pure virtual]

Cancels corresponding asynchronous request.

CancelServerCertificate()

void CancelServerCertificate ( ) [pure virtual]

Cancels corresponding asynchronous request.

ClientCertificate(CCTCertInfo *&, TRequestStatus &)

void ClientCertificate ( CCTCertInfo *& aCertInfo,
TRequestStatus & aStatus
) [pure virtual]

Used to retrieve client certificate information from cache.

Parameters

CCTCertInfo *& aCertInfo returned client certificate information, set to NULL if no certificate information is cached
TRequestStatus & aStatus asynchronous request status set on the completion

ClientKeyExchange(const TTLSMasterSecretInput &, const TTLSProtocolVersion &, const TDes8 &, const CTLSPublicKeyParams *, HBufC8 *&, TRequestStatus &)

void ClientKeyExchange ( const TTLSMasterSecretInput & aMasterSecretInput,
const TTLSProtocolVersion & aClientHelloVersion,
const TDes8 & aEncodedServerCert,
const CTLSPublicKeyParams * aKeyParams,
HBufC8 *& aClientKeyExch,
TRequestStatus & aStatus
) [pure virtual]

Provides the contents of ClientKeyExchange message to TLS/SSL protocol. That is, pre-master secret encrypted with server RSA public key in case of RSA key exchange method or DH public value in case of Diffie-Hellman ephemeral key exchange method. When the method completes, a pre-master secret is generated (so the implementation of this method for WIM should use either WIM-KeyTransport or WIM-KeyAgreement primitive) and a master secret is generated as well (which implies that also WIM-DeriveMasterSecret primitive in WIM implementation should have been called). When the method completes the session can be already stored in the token's cache. However mustn't be set to resumable until MTLSSession::ConnectionEstablished method is called. It is recommended to apply the following policy of managing the cache: if there is no memory for new entry in the cache the memory should be released by removing the oldest unused session. It is probably reasonable to lock the WIM for the duration of this method but it is left as an internal decision of WIM supplier to do so.

Pre-condition
object should have been initialised by call to InitL
Post-condition
master secret is generated

Parameters

const TTLSMasterSecretInput & aMasterSecretInput input needed for master secret generation (client and server random values)
const TTLSProtocolVersion & aClientHelloVersion protocol version number sent in client hello message
const TDes8 & aEncodedServerCert server certificate in encoded format (as received from the server)
const CTLSPublicKeyParams * aKeyParams structure with server public key parameters retrieved from ServerKeyExchange message, the type flag of the TTLSPublicKeyParams structure should indicate appropriate key exchange algorithm to use; the parameter should be set to NULL if is irrelevant for selected cipher suite
HBufC8 *& aClientKeyExch buffer with key exchange message contents (output parameter)
TRequestStatus & aStatus asynchronous request status set on the completion

ComputeDigitalSignature(const TDesC8 &, HBufC8 *&, CCTCertInfo &, CCTKeyInfo &, TRequestStatus &)

void ComputeDigitalSignature ( const TDesC8 & aInput,
HBufC8 *& aSignature,
CCTCertInfo & aCertInfo,
CCTKeyInfo & aKeyInfo,
TRequestStatus & aStatus
) [pure virtual]
Used to sign given input with client private key. The private key comes matches the public key from client certificate selected for authentication.
Pre-condition
master secret should have been generated before (by call to ClientKeyExchange)

Parameters

const TDesC8 & aInput message to be signed
HBufC8 *& aSignature signature of aInput (output paramter)
CCTCertInfo & aCertInfo structure containing information about certificate selected for client authentication
CCTKeyInfo & aKeyInfo structure containing information about private key matching public key from client certificate, this key is used for signing
TRequestStatus & aStatus asynchronous request status set on the completion

ConnectionEstablished(TBool, TBool, TBool, TRequestStatus &)

void ConnectionEstablished ( TBool aSuccessful,
TBool aServerAuthenticated,
TBool aClientAuthenticated,
TRequestStatus & aStatus
) [pure virtual]
Called when handshake is finished. Used to inform the token whether handshake was successful or not. If yes, the session data will be stored in the cache and marked as resumable. Otherwise the session should be removed from the cache. Additional parameters tell whether Server and Client authentication was successful. This information is added to the cache.
Pre-condition
object 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

Parameters

TBool aSuccessful ETrue if handshake successfully completed, EFalse otherwise
TBool aServerAuthenticated ETrue if Server authenticated, EFalse otherwise
TBool aClientAuthenticated ETrue if Client authenticated, EFalse otherwise
TRequestStatus & aStatus asynchronous request status set on the completion

InitL(const TTLSSessionNameAndID &, const TTLSCipherSuite &, const TTLSCompressionMethod &, const TTLSProtocolVersion &, TBool)

void InitL ( const TTLSSessionNameAndID & aSessionNameAndID,
const TTLSCipherSuite & aCipherSuite,
const TTLSCompressionMethod & aCompressionMethod,
const TTLSProtocolVersion & aVersion,
TBool aResume
) [pure virtual]
Initialisation method. Should allocate memory for internally stored information about the session. The concrete implementation of MTLSSession abstract class should hold information about session identifier, cipher suite and a protocol version. This information is provided in the arguments of this method. It is supposed that the information will be stored in class' member variables (which implies that the method doesn't need to talk to asynchronous device and that's why the method is synchronous).
leave
KTLSBadProtocolVersion if the protocol version passed in the parameter is not supported by the token
leave
KTLSBadCipherSuite if the cipher suite passed in the parameter is not supported by the token
leave
KTLSErrNotCached if resumption of session is attempted but appropriate entry missing in the cache
leave
KTLSErrCacheEntryInUse if resumption of session is attempted but appropriate entry is set to non resumable
leave
KErrNoMemory if it not able to allocate memory for the object's members

Parameters

const TTLSSessionNameAndID & aSessionNameAndID a server name and session identifier
const TTLSCipherSuite & aCipherSuite a cipher suite selected for the session
const TTLSCompressionMethod & aCompressionMethod a compression method identifier
const TTLSProtocolVersion & aVersion a TLS/SSL protocol version number
TBool aResume ETrue if caller wants to resume cached session, EFalse otherwise

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

TInt KeyDerivation ( const TDesC8 & aLabel,
const TTLSMasterSecretInput & aMasterSecretInput,
TDes8 & aKeyingMaterial
) [inline, virtual]
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 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

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.

Label()

const TDesC & Label ( ) [pure virtual]

PHash(const TDesC8 &, HBufC8 *&, const TPHashOp &, TRequestStatus &)

void PHash ( const TDesC8 & aInputData,
HBufC8 *& aOutput,
const TPHashOp & aOperation,
TRequestStatus & aStatus
) [pure virtual]

Used to generate the key material for security parameters used during bulk data encryption/decryption (server and client: keys, MAC secrets, IVs). The method is also to be used to calculate Finish Check. In case of TLS the calculations are done by TLS PRF which uses master secret, label and input string to generate hash. In case of SSL the calculations should be performed using algorithms specified in SSL3.0 specification. The type of operation to be performed is indicated by an aOperation argument of type: enum {EKeyBlockOp, EServerFinishedOp, EClientFinishedOp, ECertificateVerifyOp} TPHashOp. This enumerated type is defined within scope of MTLSSession class. In case of keys generation, an aInputData parameter should be: TLS case: "key expansion" + server_random + client_random, SSL case: server_random + client_random. In case of Finish Check calculation aInputData should be: TLS case: "client finished" + MD5(handshake_messages) + SHA-1(handshake_messages), "server finished" + MD5(handshake_messages) + SHA-1(handshake_messages), SSL case: handshake_msgs + Sender.server, handshake_msgs + Sender.client (where Sender is defined as: enum { client(0x434C4E54), server(0x53525652) } Sender; - compare with specification for SSL3.0). Apart from the above cases the method should be used in SSL case for generation of hash for client's CertificateVerify message (the calculations require use of master secret). In the latter case aInputData parameter should be: handshake_msgs.

Pre-condition
master secret should have been generated before (by call to ClientKeyExchange)

Parameters

const TDesC8 & aInputData the data which is to be used as a seed for computations (master secret is concatenated with aInputData),
HBufC8 *& aOutput the result of the operation - key block (to be partitioned to required security parameters) or finish check (depending on the input) or certificte verify check
const TPHashOp & aOperation this argument indicates a type of operation that the method should perform
TRequestStatus & aStatus asynchronous request status set on the completion

PHash(CMessageDigest *, CMessageDigest *, HBufC8 *&, const TPHashOp &, TRequestStatus &)

void PHash ( CMessageDigest * aMd5Digest,
CMessageDigest * aShaDigest,
HBufC8 *& aOutput,
const TPHashOp & aOperation,
TRequestStatus & aStatus
) [pure virtual]

Used to generate Finished check or Certificate Verify check in SSL case. Thus the type of operation to be performed is indicated by an aOperation argument (of type TPHashOp) can be either: EServerFinishedOp or EClientFinishedOp or ECertificateVerifyOp. The method takes pointers to MD5 and SHA hashing objects updated before the call (but not finalized) with: handshake_msgs + Sender.server or handshake_msgs + Sender.client (in case of Finished check), or: handshake_msgs (in case of Certificate Verify check).

Parameters

CMessageDigest * aMd5Digest the pointer to MD5 hashing object updated with appropriate input
CMessageDigest * aShaDigest the pointer to SHA hashing object updated with appropriate input
HBufC8 *& aOutput the result of the operation - cleint or server finish check (depending on the input)
const TPHashOp & aOperation this argument indicates a type of operation that the method should perform
TRequestStatus & aStatus asynchronous request status set on the completion

ServerCertificate(HBufC8 *&, TRequestStatus &)

void ServerCertificate ( HBufC8 *& aEncodedServerCert,
TRequestStatus & aStatus
) [pure virtual]

Used to retrieve server certificate from a session cache. The certificates may not be available if the token has no capability of storing server certificates.

Parameters

HBufC8 *& aEncodedServerCert encoded server certificate retrieved from cache, NULL if server certificate isn't stored in cache
TRequestStatus & aStatus asynchronous request status set on the completion

Member Enumerations Documentation

Enum TPHashOp

The enumeration used by PHash method in order to identify the type of operation to be performed.

Enumerators

EKeyBlockOp

Key block generation.

EServerFinishedOp

Calculations for Server Finished message.

EClientFinishedOp

Calculations for Client Finished message.

ECertificateVerifyOp

Calculations for CertificateVerify message