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

voidCancelClientCertificate()[pure virtual]

Cancels corresponding asynchronous request.

CancelClientKeyExchange()

voidCancelClientKeyExchange()[pure virtual]

Cancels corresponding asynchronous request.

CancelComputeDigitalSignature()

voidCancelComputeDigitalSignature()[pure virtual]

Cancels corresponding asynchronous request.

CancelConnectionEstablished()

voidCancelConnectionEstablished()[pure virtual]

Cancels corresponding asynchronous request.

CancelPHash()

voidCancelPHash()[pure virtual]

Cancels corresponding asynchronous request.

CancelServerCertificate()

voidCancelServerCertificate()[pure virtual]

Cancels corresponding asynchronous request.

ClientCertificate(CCTCertInfo *&, TRequestStatus &)

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

Used to retrieve client certificate information from cache.

Parameters

CCTCertInfo *& aCertInforeturned client certificate information, set to NULL if no certificate information is cached
TRequestStatus & aStatusasynchronous request status set on the completion

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

voidClientKeyExchange(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 & aMasterSecretInputinput needed for master secret generation (client and server random values)
const TTLSProtocolVersion & aClientHelloVersionprotocol version number sent in client hello message
const TDes8 & aEncodedServerCertserver certificate in encoded format (as received from the server)
const CTLSPublicKeyParams * aKeyParamsstructure 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 *& aClientKeyExchbuffer with key exchange message contents (output parameter)
TRequestStatus & aStatusasynchronous request status set on the completion

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

voidComputeDigitalSignature(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 & aInputmessage to be signed
HBufC8 *& aSignaturesignature of aInput (output paramter)
CCTCertInfo & aCertInfostructure containing information about certificate selected for client authentication
CCTKeyInfo & aKeyInfostructure containing information about private key matching public key from client certificate, this key is used for signing
TRequestStatus & aStatusasynchronous request status set on the completion

ConnectionEstablished(TBool, TBool, TBool, TRequestStatus &)

voidConnectionEstablished(TBoolaSuccessful,
TBoolaServerAuthenticated,
TBoolaClientAuthenticated,
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 aSuccessfulETrue if handshake successfully completed, EFalse otherwise
TBool aServerAuthenticatedETrue if Server authenticated, EFalse otherwise
TBool aClientAuthenticatedETrue if Client authenticated, EFalse otherwise
TRequestStatus & aStatusasynchronous request status set on the completion

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

voidInitL(const TTLSSessionNameAndID &aSessionNameAndID,
const TTLSCipherSuite &aCipherSuite,
const TTLSCompressionMethod &aCompressionMethod,
const TTLSProtocolVersion &aVersion,
TBoolaResume
)[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 & aSessionNameAndIDa server name and session identifier
const TTLSCipherSuite & aCipherSuitea cipher suite selected for the session
const TTLSCompressionMethod & aCompressionMethoda compression method identifier
const TTLSProtocolVersion & aVersiona TLS/SSL protocol version number
TBool aResumeETrue 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 & aLabelContains the string "client key encryption".
const TTLSMasterSecretInput & aMasterSecretInputThe structure containing "Client and Server Random" binary data.
TDes8 & aKeyingMaterialContains the EAP 128 + 64 bytes string.

Label()

const TDesC &Label()[pure virtual]

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

voidPHash(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 & aInputDatathe data which is to be used as a seed for computations (master secret is concatenated with aInputData),
HBufC8 *& aOutputthe 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 & aOperationthis argument indicates a type of operation that the method should perform
TRequestStatus & aStatusasynchronous request status set on the completion

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

voidPHash(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 * aMd5Digestthe pointer to MD5 hashing object updated with appropriate input
CMessageDigest * aShaDigestthe pointer to SHA hashing object updated with appropriate input
HBufC8 *& aOutputthe result of the operation - cleint or server finish check (depending on the input)
const TPHashOp & aOperationthis argument indicates a type of operation that the method should perform
TRequestStatus & aStatusasynchronous request status set on the completion

ServerCertificate(HBufC8 *&, TRequestStatus &)

voidServerCertificate(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 *& aEncodedServerCertencoded server certificate retrieved from cache, NULL if server certificate isn't stored in cache
TRequestStatus & aStatusasynchronous 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