diff -r 000000000000 -r af10295192d8 networksecurity/tlsprovider/inc/tlsprovtokeninterfaces.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/networksecurity/tlsprovider/inc/tlsprovtokeninterfaces.h Tue Jan 26 15:23:49 2010 +0200 @@ -0,0 +1,468 @@ +// Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// under the terms of "Eclipse Public License v1.0" +// which accompanies this distribution, and is available +// at the URL "http://www.eclipse.org/legal/epl-v10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// + +/** + @file + @publishedPartner + @released +*/ + +#ifndef __TLSPROVTOKENINTERFACES_H__ +#define __TLSPROVTOKENINTERFACES_H__ + + +#include +#include +#include + +#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS +#include +#endif + +// forward declarations +class CCTCertInfo; +class CCTKeyInfo; + +/**@ingroup tlsprovider */ +class MTLSTokenProvider : public MCTTokenInterface +/** +This an interface to a cryptographic token that is capable to provide services +for TLS/SSL protocols. +@publishedPartner +@released +*/ + { + public: + + virtual const TDesC& Label() = 0; + + /** + Provides information about session associated with given server + indicated by aServerName argument. If a session has previously been established + to that server and remains held in the cache of the token and is resumable then + on completion, the aOutputSessionData will contain that session id, cipher + suite and protocol version information. + The aAcceptableCipherSuites and aAcceptableProtVersions parameters allow to impose + additional conditions on the retrieved session. That is if any of them is non-empty + then returned aOutputSessionData.iSessionId will be non trivial only when + the cipher suite and/or protocol version of cached session match some + cipher suite/protocol version included in the lists passed in the arguments. + + If no resumable session to the server is cached or cached sessions don't satisfy + conditions imposed by a caller, aOutputSessionData.iSessionId will be zero length. + + + @released + @param aServerName the name of the server the TLS protocol is intending to connect to + @param aAcceptableProtVersions a list of protocol versions, can be empty + @param aOutputSessionData session data retrieved from the cache + @param aStatus asynchronous request status set on the completion + @see CTLSProvider::GetSession + */ + virtual void GetSession( + const TTLSServerAddr& aServerName, + RArray& aAcceptableProtVersions, + TTLSSessionData& aOutputSessionData, + TRequestStatus& aStatus) = 0; + + /** + Clears a session identified by aServerName and aSession.iId from associated token's + cache. + The operation may fail if session cached in the token is in use. + @released + @param aServerName the name of the server the TLS protocol tried to connect to + @param aSession the session identifier object relating to the server + indicated in the first parameter + @param aResult a result of the operation: ETrue if cache cleared, EFalse if not + @param aStatus asynchronous request status set on the completion + */ + virtual void ClearSessionCache( + const TTLSServerAddr& aServerName, + TTLSSessionId& aSession, + TBool& aResult, + TRequestStatus& aStatus) = 0; + + /** + Retrieves list of protocol versions, key exchange algorithms and signature algorithms + supported by the token. + @released + @param aProtocols a list of supported protocol versions is returned in + this parameter + @param aKeyExchAlgs a list of supported key exchange algorithms is returned in + this parameter + @param aSigAlgs a list of supported signature algorithms is returned in + this parameter + @param aStatus asynchronous request status set on the completion + */ + virtual void CryptoCapabilities( + RArray& aProtocols, + RArray& aKeyExchAlgs, + RArray& aSigAlgs, + TRequestStatus& aStatus) = 0; + + + /** + Cancels corresponding asynchronous request. + @released + */ + virtual void CancelGetSession() = 0; + + /** + Cancels corresponding asynchronous request. + @released + */ + virtual void CancelCryptoCapabilities() = 0; + + /** + Cancels corresponding asynchronous request. + @released + */ + virtual void CancelClearSessionCache() = 0; + + }; + + + + +class MTLSSession : public MCTTokenInterface +/** +This is an interface to a cryptographic token for the cryptographic services +required by the TLS/SSL protocols. +@publishedPartner +@released +*/ + { + + public: + + /** + The enumeration used by PHash method in order to identify the type of operation + to be performed. + @released + */ + enum TPHashOp { + /** + Key block generation. + */ + EKeyBlockOp, + + /** + Calculations for Server Finished message. + */ + EServerFinishedOp, + + /** + Calculations for Client Finished message. + */ + EClientFinishedOp, + + /** + Calculations for CertificateVerify message + */ + ECertificateVerifyOp }; + + + virtual const TDesC& Label() = 0; + + + /** + 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). + @released + @param aSessionNameAndID a server name and session identifier + @param aCipherSuite a cipher suite selected for the session + @param aCompressionMethod a compression method identifier + @param aVersion a TLS/SSL protocol version number + @param aResume ETrue if caller wants to resume cached session, EFalse otherwise + @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 + */ + virtual void InitL( + const TTLSSessionNameAndID& aSessionNameAndID, + const TTLSCipherSuite& aCipherSuite, + const TTLSCompressionMethod& aCompressionMethod, + const TTLSProtocolVersion& aVersion, + TBool aResume ) = 0; + + + /** + Used to retrieve client certificate information from cache. + @released + @param aCertInfo returned client certificate information, set to NULL if + no certificate information is cached + @param aStatus asynchronous request status set on the completion + */ + virtual void ClientCertificate( + CCTCertInfo*& aCertInfo, + TRequestStatus& aStatus) = 0; + + + /** + 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. + @released + @param aEncodedServerCert encoded server certificate retrieved from cache, + NULL if server certificate isn't stored in cache + @param aStatus asynchronous request status set on the completion + */ + virtual void ServerCertificate( + HBufC8*& aEncodedServerCert, + TRequestStatus& aStatus ) = 0; + + /** + 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. + + @released + @pre object should have been initialised by call to InitL + @post master secret is generated + @param aMasterSecretInput input needed for master secret generation (client and server + random values) + @param aClientHelloVersion protocol version number sent in client hello message + @param aEncodedServerCert server certificate in encoded format (as received from the server) + @param 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 + @param aClientKeyExch buffer with key exchange message contents (output parameter) + @param aStatus asynchronous request status set on the completion + */ + virtual void ClientKeyExchange( + const TTLSMasterSecretInput& aMasterSecretInput, + const TTLSProtocolVersion& aClientHelloVersion, + const TDes8& aEncodedServerCert, + const CTLSPublicKeyParams* aKeyParams, + HBufC8*& aClientKeyExch, + TRequestStatus& aStatus ) = 0; + + + + /** + 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. + + @released + @pre master secret should have been generated before (by call to ClientKeyExchange) + @param aInputData the data which is to be used as a seed for computations + (master secret is concatenated with aInputData), + @param 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 + @param aOperation this argument indicates a type of operation that the method should perform + @param aStatus asynchronous request status set on the completion + */ + virtual void PHash( + const TDesC8& aInputData, + HBufC8*& aOutput, + const TPHashOp& aOperation, + TRequestStatus& aStatus) = 0; + + /** + 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). + + @released + @param aMd5Digest the pointer to MD5 hashing object updated with appropriate input + @param aShaDigest the pointer to SHA hashing object updated with appropriate input + @param aOutput the result of the operation - cleint or server finish check + (depending on the input) + @param aOperation this argument indicates a type of operation that the method should perform + @param aStatus asynchronous request status set on the completion + */ + virtual void PHash( + CMessageDigest* aMd5Digest, + CMessageDigest* aShaDigest, + HBufC8*& aOutput, + const TPHashOp& aOperation, + TRequestStatus& aStatus ) = 0; + + /** + Used to sign given input with client private key. The private key comes matches the public key + from client certificate selected for authentication. + @released + @pre master secret should have been generated before (by call to ClientKeyExchange) + @param aInput message to be signed + @param aSignature signature of aInput (output paramter) + @param aCertInfo structure containing information about certificate selected for + client authentication + @param aKeyInfo structure containing information about private key matching public key from + client certificate, this key is used for signing + @param aStatus asynchronous request status set on the completion + */ + virtual void ComputeDigitalSignature( + const TDesC8& aInput, + HBufC8*& aSignature, + CCTCertInfo& aCertInfo, + CCTKeyInfo& aKeyInfo, + TRequestStatus& aStatus) = 0; + + /** + 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. + @released + @pre object should have been initialised (by call to InitL) and master secret generated + (by call to ClientKeyExchange) before call to this method + @post session is cached in case of successful handshake + @param aSuccessful ETrue if handshake successfully completed, EFalse otherwise + @param aServerAuthenticated ETrue if Server authenticated, EFalse otherwise + @param aClientAuthenticated ETrue if Client authenticated, EFalse otherwise + @param aStatus asynchronous request status set on the completion + */ + virtual void ConnectionEstablished( TBool aSuccessful, + TBool aServerAuthenticated, + TBool aClientAuthenticated, + TRequestStatus& aStatus ) = 0; + + + + /** + Cancels corresponding asynchronous request. + @released + */ + virtual void CancelClientCertificate() = 0; + + + /** + Cancels corresponding asynchronous request. + @released + */ + virtual void CancelServerCertificate() = 0; + + /** + Cancels corresponding asynchronous request. + @released + */ + virtual void CancelClientKeyExchange() = 0; + + /** + Cancels corresponding asynchronous request. + @released + */ + virtual void CancelPHash() = 0; + + /** + Cancels corresponding asynchronous request. + @released + */ + virtual void CancelComputeDigitalSignature() = 0; + + /** + Cancels corresponding asynchronous request. + @released + */ + virtual void CancelConnectionEstablished() = 0; + + /** + 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 object should have been initialised (by call to InitL) and master + secret generated (by call to ClientKeyExchange) before call to this method + @post session is cached in case of successful handshake + @param aLabel Contains the string "client key encryption". + @param aMasterSecretInput The structure containing "Client and Server Random" binary data. + @param aKeyingMaterial Contains the EAP 128 + 64 bytes string. + */ + virtual TInt KeyDerivation( + const TDesC8& aLabel, + const TTLSMasterSecretInput& aMasterSecretInput, + TDes8& aKeyingMaterial); + + }; + +#ifdef _BullseyeCoverage +#pragma suppress_warnings on +#pragma BullseyeCoverage save off +#endif +inline TInt MTLSSession::KeyDerivation( + const TDesC8& /*aLabel*/, + const TTLSMasterSecretInput& /*aMasterSecretInput*/, + TDes8& /*aKeyingMaterial*/) + { + return KErrNotSupported; + } +#ifdef _BullseyeCoverage +#pragma BullseyeCoverage restore +#pragma suppress_warnings off +#endif + +/** @} */ + + +#endif //__TLSPROVTOKENINTERFACES_H__