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.
Public Member Functions
|
void
|
CancelClientCertificate
()
|
void
|
CancelClientKeyExchange
()
|
void
|
CancelComputeDigitalSignature
()
|
void
|
CancelConnectionEstablished
()
|
void
|
CancelPHash
()
|
void
|
CancelServerCertificate
()
|
void
|
ClientCertificate
(
CCTCertInfo
*&,
TRequestStatus
&)
|
void
|
ClientKeyExchange
(const
TTLSMasterSecretInput
&, const
TTLSProtocolVersion
&, const
TDes8
&, const
CTLSPublicKeyParams
*,
HBufC8
*&,
TRequestStatus
&)
|
void
|
ComputeDigitalSignature
(const
TDesC8
&,
HBufC8
*&,
CCTCertInfo
&,
CCTKeyInfo
&,
TRequestStatus
&)
|
void
|
ConnectionEstablished
(
TBool
,
TBool
,
TBool
,
TRequestStatus
&)
|
void
|
InitL
(const
TTLSSessionNameAndID
&, const
TTLSCipherSuite
&, const
TTLSCompressionMethod
&, const
TTLSProtocolVersion
&,
TBool
)
|
TInt
|
KeyDerivation
(const
TDesC8
&, const
TTLSMasterSecretInput
&,
TDes8
&)
|
const
TDesC
&
|
Label
()
|
void
|
PHash
(const
TDesC8
&,
HBufC8
*&, const
TPHashOp
&,
TRequestStatus
&)
|
void
|
PHash
(
CMessageDigest
*,
CMessageDigest
*,
HBufC8
*&, const
TPHashOp
&,
TRequestStatus
&)
|
void
|
ServerCertificate
(
HBufC8
*&,
TRequestStatus
&)
|
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 &)
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 &)
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 &)
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)
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
KeyDerivation(const TDesC8 &, const TTLSMasterSecretInput &, TDes8 &)
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 &)
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 &)
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 &)
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
|
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights
reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License
v1.0.