|
1 // Copyright (c) 2003-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 /** |
|
17 @file |
|
18 @publishedPartner |
|
19 @released |
|
20 */ |
|
21 |
|
22 #ifndef __TLSPROVTOKENINTERFACES_H__ |
|
23 #define __TLSPROVTOKENINTERFACES_H__ |
|
24 |
|
25 |
|
26 #include <tlstypedef.h> |
|
27 #include <hash.h> |
|
28 #include <ct.h> |
|
29 |
|
30 #ifndef SYMBIAN_ENABLE_SPLIT_HEADERS |
|
31 #include <tlsprovtokeninterfaces_internal.h> |
|
32 #endif |
|
33 |
|
34 // forward declarations |
|
35 class CCTCertInfo; |
|
36 class CCTKeyInfo; |
|
37 |
|
38 /**@ingroup tlsprovider */ |
|
39 class MTLSTokenProvider : public MCTTokenInterface |
|
40 /** |
|
41 This an interface to a cryptographic token that is capable to provide services |
|
42 for TLS/SSL protocols. |
|
43 @publishedPartner |
|
44 @released |
|
45 */ |
|
46 { |
|
47 public: |
|
48 |
|
49 virtual const TDesC& Label() = 0; |
|
50 |
|
51 /** |
|
52 Provides information about session associated with given server |
|
53 indicated by aServerName argument. If a session has previously been established |
|
54 to that server and remains held in the cache of the token and is resumable then |
|
55 on completion, the aOutputSessionData will contain that session id, cipher |
|
56 suite and protocol version information. |
|
57 The aAcceptableCipherSuites and aAcceptableProtVersions parameters allow to impose |
|
58 additional conditions on the retrieved session. That is if any of them is non-empty |
|
59 then returned aOutputSessionData.iSessionId will be non trivial only when |
|
60 the cipher suite and/or protocol version of cached session match some |
|
61 cipher suite/protocol version included in the lists passed in the arguments. |
|
62 |
|
63 If no resumable session to the server is cached or cached sessions don't satisfy |
|
64 conditions imposed by a caller, aOutputSessionData.iSessionId will be zero length. |
|
65 |
|
66 |
|
67 @released |
|
68 @param aServerName the name of the server the TLS protocol is intending to connect to |
|
69 @param aAcceptableProtVersions a list of protocol versions, can be empty |
|
70 @param aOutputSessionData session data retrieved from the cache |
|
71 @param aStatus asynchronous request status set on the completion |
|
72 @see CTLSProvider::GetSession |
|
73 */ |
|
74 virtual void GetSession( |
|
75 const TTLSServerAddr& aServerName, |
|
76 RArray<TTLSProtocolVersion>& aAcceptableProtVersions, |
|
77 TTLSSessionData& aOutputSessionData, |
|
78 TRequestStatus& aStatus) = 0; |
|
79 |
|
80 /** |
|
81 Clears a session identified by aServerName and aSession.iId from associated token's |
|
82 cache. |
|
83 The operation may fail if session cached in the token is in use. |
|
84 @released |
|
85 @param aServerName the name of the server the TLS protocol tried to connect to |
|
86 @param aSession the session identifier object relating to the server |
|
87 indicated in the first parameter |
|
88 @param aResult a result of the operation: ETrue if cache cleared, EFalse if not |
|
89 @param aStatus asynchronous request status set on the completion |
|
90 */ |
|
91 virtual void ClearSessionCache( |
|
92 const TTLSServerAddr& aServerName, |
|
93 TTLSSessionId& aSession, |
|
94 TBool& aResult, |
|
95 TRequestStatus& aStatus) = 0; |
|
96 |
|
97 /** |
|
98 Retrieves list of protocol versions, key exchange algorithms and signature algorithms |
|
99 supported by the token. |
|
100 @released |
|
101 @param aProtocols a list of supported protocol versions is returned in |
|
102 this parameter |
|
103 @param aKeyExchAlgs a list of supported key exchange algorithms is returned in |
|
104 this parameter |
|
105 @param aSigAlgs a list of supported signature algorithms is returned in |
|
106 this parameter |
|
107 @param aStatus asynchronous request status set on the completion |
|
108 */ |
|
109 virtual void CryptoCapabilities( |
|
110 RArray<TTLSProtocolVersion>& aProtocols, |
|
111 RArray<TTLSKeyExchangeAlgorithm>& aKeyExchAlgs, |
|
112 RArray<TTLSSignatureAlgorithm>& aSigAlgs, |
|
113 TRequestStatus& aStatus) = 0; |
|
114 |
|
115 |
|
116 /** |
|
117 Cancels corresponding asynchronous request. |
|
118 @released |
|
119 */ |
|
120 virtual void CancelGetSession() = 0; |
|
121 |
|
122 /** |
|
123 Cancels corresponding asynchronous request. |
|
124 @released |
|
125 */ |
|
126 virtual void CancelCryptoCapabilities() = 0; |
|
127 |
|
128 /** |
|
129 Cancels corresponding asynchronous request. |
|
130 @released |
|
131 */ |
|
132 virtual void CancelClearSessionCache() = 0; |
|
133 |
|
134 }; |
|
135 |
|
136 |
|
137 |
|
138 |
|
139 class MTLSSession : public MCTTokenInterface |
|
140 /** |
|
141 This is an interface to a cryptographic token for the cryptographic services |
|
142 required by the TLS/SSL protocols. |
|
143 @publishedPartner |
|
144 @released |
|
145 */ |
|
146 { |
|
147 |
|
148 public: |
|
149 |
|
150 /** |
|
151 The enumeration used by PHash method in order to identify the type of operation |
|
152 to be performed. |
|
153 @released |
|
154 */ |
|
155 enum TPHashOp { |
|
156 /** |
|
157 Key block generation. |
|
158 */ |
|
159 EKeyBlockOp, |
|
160 |
|
161 /** |
|
162 Calculations for Server Finished message. |
|
163 */ |
|
164 EServerFinishedOp, |
|
165 |
|
166 /** |
|
167 Calculations for Client Finished message. |
|
168 */ |
|
169 EClientFinishedOp, |
|
170 |
|
171 /** |
|
172 Calculations for CertificateVerify message |
|
173 */ |
|
174 ECertificateVerifyOp }; |
|
175 |
|
176 |
|
177 virtual const TDesC& Label() = 0; |
|
178 |
|
179 |
|
180 /** |
|
181 Initialisation method. Should allocate memory for internally stored |
|
182 information about the session. The concrete implementation of MTLSSession |
|
183 abstract class should hold information about session identifier, cipher suite |
|
184 and a protocol version. This information is provided in the arguments of this method. |
|
185 It is supposed that the information will be stored in class' member variables |
|
186 (which implies that the method doesn't need to talk to asynchronous device and |
|
187 that's why the method is synchronous). |
|
188 @released |
|
189 @param aSessionNameAndID a server name and session identifier |
|
190 @param aCipherSuite a cipher suite selected for the session |
|
191 @param aCompressionMethod a compression method identifier |
|
192 @param aVersion a TLS/SSL protocol version number |
|
193 @param aResume ETrue if caller wants to resume cached session, EFalse otherwise |
|
194 @leave KTLSBadProtocolVersion if the protocol version passed in the parameter |
|
195 is not supported by the token |
|
196 @leave KTLSBadCipherSuite if the cipher suite passed in the parameter is not supported |
|
197 by the token |
|
198 @leave KTLSErrNotCached if resumption of session is attempted but appropriate entry |
|
199 missing in the cache |
|
200 @leave KTLSErrCacheEntryInUse if resumption of session is attempted but appropriate |
|
201 entry is set to non resumable |
|
202 @leave KErrNoMemory if it not able to allocate memory for the object's members |
|
203 */ |
|
204 virtual void InitL( |
|
205 const TTLSSessionNameAndID& aSessionNameAndID, |
|
206 const TTLSCipherSuite& aCipherSuite, |
|
207 const TTLSCompressionMethod& aCompressionMethod, |
|
208 const TTLSProtocolVersion& aVersion, |
|
209 TBool aResume ) = 0; |
|
210 |
|
211 |
|
212 /** |
|
213 Used to retrieve client certificate information from cache. |
|
214 @released |
|
215 @param aCertInfo returned client certificate information, set to NULL if |
|
216 no certificate information is cached |
|
217 @param aStatus asynchronous request status set on the completion |
|
218 */ |
|
219 virtual void ClientCertificate( |
|
220 CCTCertInfo*& aCertInfo, |
|
221 TRequestStatus& aStatus) = 0; |
|
222 |
|
223 |
|
224 /** |
|
225 Used to retrieve server certificate from a session cache. The certificates may not be available |
|
226 if the token has no capability of storing server certificates. |
|
227 @released |
|
228 @param aEncodedServerCert encoded server certificate retrieved from cache, |
|
229 NULL if server certificate isn't stored in cache |
|
230 @param aStatus asynchronous request status set on the completion |
|
231 */ |
|
232 virtual void ServerCertificate( |
|
233 HBufC8*& aEncodedServerCert, |
|
234 TRequestStatus& aStatus ) = 0; |
|
235 |
|
236 /** |
|
237 Provides the contents of ClientKeyExchange message to TLS/SSL protocol. That is, |
|
238 pre-master secret encrypted with server RSA public key in case of RSA key exchange method |
|
239 or DH public value in case of Diffie-Hellman ephemeral key exchange method. |
|
240 When the method completes, a pre-master secret is generated (so the implementation |
|
241 of this method for WIM should use either WIM-KeyTransport or WIM-KeyAgreement primitive) |
|
242 and a master secret is generated as well (which implies that also WIM-DeriveMasterSecret |
|
243 primitive in WIM implementation should have been called). |
|
244 When the method completes the session can be already stored in the token's cache. |
|
245 However mustn't be set to resumable until MTLSSession::ConnectionEstablished method is called. |
|
246 It is recommended to apply the following policy of managing the cache: if there is no memory |
|
247 for new entry in the cache the memory should be released by removing the oldest |
|
248 unused session. |
|
249 It is probably reasonable to lock the WIM for the duration of this method but it is left as |
|
250 an internal decision of WIM supplier to do so. |
|
251 |
|
252 @released |
|
253 @pre object should have been initialised by call to InitL |
|
254 @post master secret is generated |
|
255 @param aMasterSecretInput input needed for master secret generation (client and server |
|
256 random values) |
|
257 @param aClientHelloVersion protocol version number sent in client hello message |
|
258 @param aEncodedServerCert server certificate in encoded format (as received from the server) |
|
259 @param aKeyParams structure with server public key parameters retrieved from ServerKeyExchange |
|
260 message, the type flag of the TTLSPublicKeyParams structure should indicate appropriate |
|
261 key exchange algorithm to use; the parameter should be set to NULL if |
|
262 is irrelevant for selected cipher suite |
|
263 @param aClientKeyExch buffer with key exchange message contents (output parameter) |
|
264 @param aStatus asynchronous request status set on the completion |
|
265 */ |
|
266 virtual void ClientKeyExchange( |
|
267 const TTLSMasterSecretInput& aMasterSecretInput, |
|
268 const TTLSProtocolVersion& aClientHelloVersion, |
|
269 const TDes8& aEncodedServerCert, |
|
270 const CTLSPublicKeyParams* aKeyParams, |
|
271 HBufC8*& aClientKeyExch, |
|
272 TRequestStatus& aStatus ) = 0; |
|
273 |
|
274 |
|
275 |
|
276 /** |
|
277 Used to generate the key material for security parameters used during bulk data |
|
278 encryption/decryption (server and client: keys, MAC secrets, IVs). The method is also |
|
279 to be used to calculate Finish Check. In case of TLS the calculations are done by TLS PRF |
|
280 which uses master secret, label and input string to generate hash. |
|
281 In case of SSL the calculations should be performed using algorithms specified in SSL3.0 |
|
282 specification. |
|
283 The type of operation to be performed is indicated by an aOperation argument of type: |
|
284 enum {EKeyBlockOp, EServerFinishedOp, EClientFinishedOp, ECertificateVerifyOp} TPHashOp. |
|
285 This enumerated type is defined within scope of MTLSSession class. |
|
286 In case of keys generation, an aInputData parameter should be: |
|
287 TLS case: |
|
288 "key expansion" + server_random + client_random, |
|
289 SSL case: |
|
290 server_random + client_random. |
|
291 In case of Finish Check calculation aInputData should be: |
|
292 TLS case: |
|
293 "client finished" + MD5(handshake_messages) + SHA-1(handshake_messages), |
|
294 "server finished" + MD5(handshake_messages) + SHA-1(handshake_messages), |
|
295 SSL case: |
|
296 handshake_msgs + Sender.server, |
|
297 handshake_msgs + Sender.client |
|
298 (where Sender is defined as: enum { client(0x434C4E54), server(0x53525652) } Sender; - compare |
|
299 with specification for SSL3.0). |
|
300 Apart from the above cases the method should be used in SSL case for generation of hash |
|
301 for client's CertificateVerify message (the calculations require use of master secret). |
|
302 In the latter case aInputData parameter should be: |
|
303 handshake_msgs. |
|
304 |
|
305 @released |
|
306 @pre master secret should have been generated before (by call to ClientKeyExchange) |
|
307 @param aInputData the data which is to be used as a seed for computations |
|
308 (master secret is concatenated with aInputData), |
|
309 @param aOutput the result of the operation - key block (to be partitioned to required security |
|
310 parameters) or finish check (depending on the input) or certificte verify check |
|
311 @param aOperation this argument indicates a type of operation that the method should perform |
|
312 @param aStatus asynchronous request status set on the completion |
|
313 */ |
|
314 virtual void PHash( |
|
315 const TDesC8& aInputData, |
|
316 HBufC8*& aOutput, |
|
317 const TPHashOp& aOperation, |
|
318 TRequestStatus& aStatus) = 0; |
|
319 |
|
320 /** |
|
321 Used to generate Finished check or Certificate Verify check in SSL case. |
|
322 Thus the type of operation to be performed is indicated by an aOperation argument |
|
323 (of type TPHashOp) can be either: |
|
324 EServerFinishedOp or EClientFinishedOp or ECertificateVerifyOp. |
|
325 The method takes pointers to MD5 and SHA hashing objects updated before |
|
326 the call (but not finalized) with: |
|
327 handshake_msgs + Sender.server |
|
328 or |
|
329 handshake_msgs + Sender.client |
|
330 (in case of Finished check), |
|
331 or: |
|
332 handshake_msgs |
|
333 (in case of Certificate Verify check). |
|
334 |
|
335 @released |
|
336 @param aMd5Digest the pointer to MD5 hashing object updated with appropriate input |
|
337 @param aShaDigest the pointer to SHA hashing object updated with appropriate input |
|
338 @param aOutput the result of the operation - cleint or server finish check |
|
339 (depending on the input) |
|
340 @param aOperation this argument indicates a type of operation that the method should perform |
|
341 @param aStatus asynchronous request status set on the completion |
|
342 */ |
|
343 virtual void PHash( |
|
344 CMessageDigest* aMd5Digest, |
|
345 CMessageDigest* aShaDigest, |
|
346 HBufC8*& aOutput, |
|
347 const TPHashOp& aOperation, |
|
348 TRequestStatus& aStatus ) = 0; |
|
349 |
|
350 /** |
|
351 Used to sign given input with client private key. The private key comes matches the public key |
|
352 from client certificate selected for authentication. |
|
353 @released |
|
354 @pre master secret should have been generated before (by call to ClientKeyExchange) |
|
355 @param aInput message to be signed |
|
356 @param aSignature signature of aInput (output paramter) |
|
357 @param aCertInfo structure containing information about certificate selected for |
|
358 client authentication |
|
359 @param aKeyInfo structure containing information about private key matching public key from |
|
360 client certificate, this key is used for signing |
|
361 @param aStatus asynchronous request status set on the completion |
|
362 */ |
|
363 virtual void ComputeDigitalSignature( |
|
364 const TDesC8& aInput, |
|
365 HBufC8*& aSignature, |
|
366 CCTCertInfo& aCertInfo, |
|
367 CCTKeyInfo& aKeyInfo, |
|
368 TRequestStatus& aStatus) = 0; |
|
369 |
|
370 /** |
|
371 Called when handshake is finished. Used to inform the token whether handshake |
|
372 was successful or not. If yes, the session data will be stored in the cache and |
|
373 marked as resumable. |
|
374 Otherwise the session should be removed from the cache. |
|
375 Additional parameters tell whether Server and Client authentication was successful. |
|
376 This information is added to the cache. |
|
377 @released |
|
378 @pre object should have been initialised (by call to InitL) and master secret generated |
|
379 (by call to ClientKeyExchange) before call to this method |
|
380 @post session is cached in case of successful handshake |
|
381 @param aSuccessful ETrue if handshake successfully completed, EFalse otherwise |
|
382 @param aServerAuthenticated ETrue if Server authenticated, EFalse otherwise |
|
383 @param aClientAuthenticated ETrue if Client authenticated, EFalse otherwise |
|
384 @param aStatus asynchronous request status set on the completion |
|
385 */ |
|
386 virtual void ConnectionEstablished( TBool aSuccessful, |
|
387 TBool aServerAuthenticated, |
|
388 TBool aClientAuthenticated, |
|
389 TRequestStatus& aStatus ) = 0; |
|
390 |
|
391 |
|
392 |
|
393 /** |
|
394 Cancels corresponding asynchronous request. |
|
395 @released |
|
396 */ |
|
397 virtual void CancelClientCertificate() = 0; |
|
398 |
|
399 |
|
400 /** |
|
401 Cancels corresponding asynchronous request. |
|
402 @released |
|
403 */ |
|
404 virtual void CancelServerCertificate() = 0; |
|
405 |
|
406 /** |
|
407 Cancels corresponding asynchronous request. |
|
408 @released |
|
409 */ |
|
410 virtual void CancelClientKeyExchange() = 0; |
|
411 |
|
412 /** |
|
413 Cancels corresponding asynchronous request. |
|
414 @released |
|
415 */ |
|
416 virtual void CancelPHash() = 0; |
|
417 |
|
418 /** |
|
419 Cancels corresponding asynchronous request. |
|
420 @released |
|
421 */ |
|
422 virtual void CancelComputeDigitalSignature() = 0; |
|
423 |
|
424 /** |
|
425 Cancels corresponding asynchronous request. |
|
426 @released |
|
427 */ |
|
428 virtual void CancelConnectionEstablished() = 0; |
|
429 |
|
430 /** |
|
431 This synchronous method provides the EAP string that is derived or |
|
432 computed from master secret key, "client key encryption" string (or any |
|
433 string from client), client and server hello random values. The EAP |
|
434 string returned would be of 128 + 64 bytes length. |
|
435 @pre object should have been initialised (by call to InitL) and master |
|
436 secret generated (by call to ClientKeyExchange) before call to this method |
|
437 @post session is cached in case of successful handshake |
|
438 @param aLabel Contains the string "client key encryption". |
|
439 @param aMasterSecretInput The structure containing "Client and Server Random" binary data. |
|
440 @param aKeyingMaterial Contains the EAP 128 + 64 bytes string. |
|
441 */ |
|
442 virtual TInt KeyDerivation( |
|
443 const TDesC8& aLabel, |
|
444 const TTLSMasterSecretInput& aMasterSecretInput, |
|
445 TDes8& aKeyingMaterial); |
|
446 |
|
447 }; |
|
448 |
|
449 #ifdef _BullseyeCoverage |
|
450 #pragma suppress_warnings on |
|
451 #pragma BullseyeCoverage save off |
|
452 #endif |
|
453 inline TInt MTLSSession::KeyDerivation( |
|
454 const TDesC8& /*aLabel*/, |
|
455 const TTLSMasterSecretInput& /*aMasterSecretInput*/, |
|
456 TDes8& /*aKeyingMaterial*/) |
|
457 { |
|
458 return KErrNotSupported; |
|
459 } |
|
460 #ifdef _BullseyeCoverage |
|
461 #pragma BullseyeCoverage restore |
|
462 #pragma suppress_warnings off |
|
463 #endif |
|
464 |
|
465 /** @} */ |
|
466 |
|
467 |
|
468 #endif //__TLSPROVTOKENINTERFACES_H__ |