|
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 // This file contains the interface exported from Tls provider |
|
15 // |
|
16 // |
|
17 |
|
18 /** |
|
19 @file |
|
20 @internalComponent |
|
21 */ |
|
22 |
|
23 #ifndef __TLSPROVINTERFACE_H__ |
|
24 #define __TLSPROVINTERFACE_H__ |
|
25 |
|
26 #include <e32std.h> |
|
27 #include <e32base.h> |
|
28 #include <hash.h> |
|
29 #include "tlstypedef.h" |
|
30 #include "ct.h" |
|
31 #include "pkixcertchain.h" |
|
32 |
|
33 #ifdef SYMBIAN_ENABLE_SPLIT_HEADERS |
|
34 #include <tlstypedef_internal.h> |
|
35 #endif |
|
36 |
|
37 class CTlsSessionImpl; |
|
38 class CTlsProviderImpl; |
|
39 |
|
40 /** |
|
41 This class provides a wrapper around a MTLSSession object. A number of its methods simply |
|
42 call corresponding MTLSSession methods. However it also acts as an intermediary between the |
|
43 client and cryptographic libraries where services not involving tokens are required. |
|
44 @internalComponent |
|
45 @released |
|
46 */ |
|
47 class CTLSSession : CBase |
|
48 { |
|
49 friend class CTlsSessionImpl; |
|
50 public: |
|
51 |
|
52 /** |
|
53 The ClientKeyExchange operation includes the following. The generation of the pre-master secret, |
|
54 The derivation of the master secret, Generation of keys for bulk data encryption and MAC secrets, |
|
55 If weak Export cipher is used, generation of Weak keys, Creation of CTLSSession's member objects responsible for symmetric encryption and HMAC hashing. |
|
56 ClientKeyExchange message created and returned |
|
57 @param aClientKeyExch - The client key exchange message |
|
58 @param aStatus - Asynchronous request status value |
|
59 */ |
|
60 IMPORT_C void ClientKeyExchange( |
|
61 HBufC8*& aClientKeyExch, |
|
62 TRequestStatus& aStatus); |
|
63 |
|
64 /** |
|
65 This asynchronous method is used to retrieve a client certificate in its encoded form, which would be normally send |
|
66 out to the server. If the connection has reached a stage where the session would have been cached, then this API would |
|
67 retrieve the information (CCTCertInfo) from token's cache and returns the retrieved certificate from the Certstore. In all |
|
68 other case, the information (CCTCertInfo) is stored locally |
|
69 @param aEncodedClientCert- The client certificate used in this session in encoded form |
|
70 @param aStatus - Asynchronous request status value |
|
71 */ |
|
72 IMPORT_C void ClientCertificate( |
|
73 HBufC8*& aEncodedClientCert, |
|
74 TRequestStatus& aStatus); |
|
75 |
|
76 /** |
|
77 This asynchronous method is used to retrieve a client certificate in an X509 form, which would be normally used for |
|
78 displaying it to the user. If the connection has reached a stage where the session would have been cached, then this API |
|
79 would retrieve the information (CCTCertInfo) from token's cache and returns the retrieved certificate from the Certstore. |
|
80 In all other case, the information (CCTCertInfo) is stored locally. |
|
81 @param aX509ClientCert - The client certificate used in this session in X509 form |
|
82 @param aStatus - Asynchronous request status value |
|
83 */ |
|
84 IMPORT_C void ClientCertificate( |
|
85 CX509Certificate*& aX509ClientCert, |
|
86 TRequestStatus& aStatus); |
|
87 |
|
88 /** |
|
89 This asynchronous method is used to retrieve a client certificate chain in its encoded form, which would be normally send |
|
90 out to the server. If the connection has reached a stage where the session would have been cached, then this API would |
|
91 retrieve the information (CCTCertInfo) from token's cache and returns the retrieved certificate from the Certstore. In all |
|
92 other case, the information (CCTCertInfo) is stored locally |
|
93 @param aClientCertArray- The client certificate chain used in this session in encoded form |
|
94 @param aStatus - Asynchronous request status value |
|
95 */ |
|
96 IMPORT_C void ClientCertificate( |
|
97 RPointerArray<HBufC8>* aClientCertArray, |
|
98 TRequestStatus& aStatus); |
|
99 |
|
100 /** |
|
101 This asynchronous method is used to retrieve the associated server certificate of the current session in its X509 form, |
|
102 which would be normally used for displaying it to the user. If the connection has reached a stage where the session would have been cached, |
|
103 then this API would retrieve the certificate from the Token. In all other case, the certificate is stored locally. |
|
104 @param aX509ServerCert - The server certificate used in this session in X509 form |
|
105 @param aStatus - Asynchronous request status value |
|
106 */ |
|
107 IMPORT_C void ServerCertificate( |
|
108 CX509Certificate*& aX509ServerCert, |
|
109 TRequestStatus& aStatus); |
|
110 |
|
111 /** |
|
112 This asynchronous method generates a SSL/TLS protocol's Client 'Finished' message. This input for this message is a hash |
|
113 of concatenation of all the handshake messages exchanged thus far (as specified by RFC2246 and SSL3.0 specification). |
|
114 In order to create the required output, |
|
115 @param iMd5DigestInput - The input data. |
|
116 @param iShaDigestInput - The input data. |
|
117 @param aOutput - The result of the operation i.e. the Client's 'Finished' message. |
|
118 @param aStatus - Asynchronous request status value that can be checked by the client. |
|
119 */ |
|
120 IMPORT_C void ClientFinishedMsgL( |
|
121 CMessageDigest* aMd5DigestInput, |
|
122 CMessageDigest* aShaDigestInput, |
|
123 HBufC8*& aOutput, |
|
124 TRequestStatus& aStatus); |
|
125 |
|
126 /** |
|
127 This method generates ServerFinished message given as an input hash of concatenation of all handshake messages |
|
128 (as specified by RFC2246 and SSL3.0 specification). In order to create required output, the function calls MTLSSesssion::PHash |
|
129 with the following input string: |
|
130 @param iMd5DigestInput - the input data, |
|
131 @param iShaDigestInput - the input data, |
|
132 @param aActualFinishedMsg - the result of the operation - ServerFinished message, |
|
133 @param aStatus - Asynchronous request status value that can be checked by the client. |
|
134 */ |
|
135 IMPORT_C void VerifyServerFinishedMsgL( |
|
136 CMessageDigest* aMd5DigestInput, |
|
137 CMessageDigest* aShaDigestInput, |
|
138 const TDesC8& aActualFinishedMsg, |
|
139 TRequestStatus& aStatus); |
|
140 |
|
141 /** |
|
142 Plain text, the overview for this function. |
|
143 @released optional further explanation may appear here |
|
144 @return Explanation of the object returned |
|
145 @param iMd5DigestInput - the input data, |
|
146 @param iShaDigestInput - the input data, |
|
147 @param aOutput - the result of the operation - ServerFinished message, |
|
148 @param aStatus - Asynchronous request status value that can be checked by the client. |
|
149 @post CClassExample object is now fully initialised |
|
150 */ |
|
151 IMPORT_C void CertificateVerifySignatureL( |
|
152 CMessageDigest* aMd5DigestInput, |
|
153 CMessageDigest* aShaDigestInput, |
|
154 HBufC8*& aOutput, |
|
155 TRequestStatus& aStatus); |
|
156 |
|
157 /** |
|
158 On receiving an input data, this method computes the MAC, appends it into the input and encrypts the whole block. |
|
159 The encryption and decryption objects should have been created in an earlier call to ClientKeyExchange before calling this API |
|
160 @return An SSL/TLS spec alert code will be returned if for any error, KErrNone otherwise |
|
161 @param aInput - The data to be encrypted |
|
162 @param aOutput - The encrypted output |
|
163 @param aSeqNumber - The sequence number of the message packet, the value is used for computing the MAC. |
|
164 @param aType - The type of message (e.g Handshake, alert, application data, etc) , the value is used for computing the MAC. |
|
165 */ |
|
166 IMPORT_C TInt EncryptL( |
|
167 const TDesC8& aInput, |
|
168 HBufC8*& aOutput, |
|
169 TInt64& aSeqNumber, |
|
170 TRecordProtocol& aType); |
|
171 |
|
172 /** |
|
173 On receiving an input data, this method decrypts the data, parses the actual data from its MAC and verifies it. |
|
174 If the MAC is verified correctly the output will be returned |
|
175 The encryption and decryption objects should have been created in an earlier call to ClientKeyExchange before calling this API |
|
176 @return An SSL/TLS spec alert code will be returned if for any error, KErrNone otherwise |
|
177 @param aInput - The data to be decrypted |
|
178 @param aOutput - Decrypted message data |
|
179 @param aSeqNumber - The sequence number of the message packet, the value is used for computing the MAC. |
|
180 @param aType - The type of message (e.g Handshake, alert, application data, etc) , the value is used for computing the MAC. |
|
181 */ |
|
182 IMPORT_C TInt DecryptAndVerifyL( |
|
183 const TDesC8& aInput, |
|
184 HBufC8*& aOutput, |
|
185 TInt64& aSeqNumber, |
|
186 TRecordProtocol& aType); |
|
187 |
|
188 /** |
|
189 The first call to CTLSProvider takes place before ClientHello is send, then as the handshake progress, the information relevant |
|
190 for Provider and token will be gradually filled in the structure. The ownership will then be passed to the CTLSSession object. |
|
191 This function returns the pointer to the structure. |
|
192 @return A pointer to TTlsCryptoAttributes |
|
193 */ |
|
194 IMPORT_C CTlsCryptoAttributes* Attributes() ; |
|
195 |
|
196 /** |
|
197 This synchronous method provides the EAP string that is derived or |
|
198 computed from master secret key, "client key encryption" string (or any |
|
199 string from client), client and server hello random values. The EAP |
|
200 string returned would be of 128 + 64 bytes length. |
|
201 @pre object should should have been initialised (by call to InitL) and master |
|
202 secret generated (by call to ClientKeyExchange) before call to this method |
|
203 @post session is cached in case of successful handshake |
|
204 @param aLabel Contains the string "client key encryption". |
|
205 @param aMasterSecretInput The structure containing "Client and Server Random" binary data. |
|
206 @param aKeyingMaterial Contains the EAP 128 + 64 bytes string. |
|
207 @see CTlsSessionImpl::ClientKeyExchange |
|
208 @return TInt Returns an SSL/TLS specific Alert code in case of an error. |
|
209 */ |
|
210 IMPORT_C TInt KeyDerivation( |
|
211 const TDesC8& aLabel, |
|
212 const TTLSMasterSecretInput& aMasterSecretInput, |
|
213 TDes8& aKeyingMaterial); |
|
214 |
|
215 /** |
|
216 This method cancels all the asynchronous operations of CTLSSession |
|
217 */ |
|
218 IMPORT_C void CancelRequest(); |
|
219 IMPORT_C ~CTLSSession(); |
|
220 //private: |
|
221 /** |
|
222 Allocates and constructs a new CTlsSessionImpl object. |
|
223 @return a pointer to CTLSSession |
|
224 @param aSessionPtr - a session pointer to CTLsSessionImpl |
|
225 */ |
|
226 IMPORT_C static CTLSSession* NewL(CTlsSessionImpl* aSessionPtr); |
|
227 |
|
228 CTLSSession(CTlsSessionImpl* aSessionPtr); |
|
229 private: |
|
230 CTlsSessionImpl* iTlsSessionImpl; |
|
231 |
|
232 }; |
|
233 |
|
234 /** |
|
235 This class allows direct access to methods which are not specific to a particular token. |
|
236 It also indirectly provides access to methods which calculate connection-specific settings. |
|
237 It enables the TLS protocol module to generate the ClientHello message without committing to use a specific token. |
|
238 Once the protocol module has enough information to select an appropriate token, |
|
239 it can use this class as a factory to create a CTLSSession object. |
|
240 @internalComponent |
|
241 @released |
|
242 @see TLS Provider API |
|
243 */ |
|
244 class CTLSProvider : CBase |
|
245 { |
|
246 public: |
|
247 /** |
|
248 creates a new CTLSProvider object |
|
249 @return pointer to CTLSProvider. |
|
250 */ |
|
251 IMPORT_C static CTLSProvider* ConnectL(); |
|
252 |
|
253 /** |
|
254 This synchronous method is used to request a number of randomly generated bytes from |
|
255 the TLS Provider. This function will set a length of aBuffer to zero in case of any |
|
256 problems with random number generation. |
|
257 @param aBuffer - A buffer for the generated random value. |
|
258 @return A buffer of Random bytes in the aBuffer argument. |
|
259 */ |
|
260 IMPORT_C void GenerateRandom(TDes8& aBuffer); |
|
261 |
|
262 /** |
|
263 This method provides a CTLSSession object to the protocol when the handshake has reached |
|
264 the stage where ServerHelloDone has been recevied. The main process of this function is to |
|
265 select the token and initialize it. |
|
266 @param aTlsSession - A newly created session relating to the server. |
|
267 @param aStatus - The result of the server certificate verification. |
|
268 @return Void, as this is an asynchronous method. On completion of the asynchronous request, the result will be read from the aTlsSession, aClientKeyExch and aStatus parameters. |
|
269 */ |
|
270 IMPORT_C void CreateL( |
|
271 CTLSSession*& aTlsSession, |
|
272 TRequestStatus& aStatus); |
|
273 |
|
274 /** |
|
275 This asynchronous method reads the list of supported cipher suites from the available tokens. This list is used within the SSL/TLS Protocol's ClientHello message. |
|
276 @param aUserCipherSuiteList - This is used to pass back (by reference) a list of cipher suites that are |
|
277 supported by the Security subsystem and the cryptographic tokens available in the device. |
|
278 @param aStatus - Asynchronous request status value that can be checked by the client. |
|
279 @return Void, as this is an asynchronous method. On completion of the asynchronous request, the results will be in the aCipherSuite and aStatus parameters. |
|
280 */ |
|
281 IMPORT_C void CipherSuitesL( |
|
282 RArray<TTLSCipherSuite>& aUserCipherSuiteList, |
|
283 TRequestStatus& aStatus); |
|
284 |
|
285 /** |
|
286 This asynchronous method is used to validate a received Server certificate. |
|
287 @param aEncodedServerCerts A string with server certificates (read from ServerCertificate message). |
|
288 @param aServerCert - The server certificate returned in a X509 format |
|
289 @param aStatus - The result of the server certificate verification. |
|
290 @return Void, as this is an asynchronous method. If the dialog mode is set to true, then a dialog will be popped if the server certificate is invalid. The user then has the choice to close the connection or continue. |
|
291 */ |
|
292 IMPORT_C void VerifyServerCertificate( |
|
293 const TDesC8& aEncodedServerCerts, |
|
294 CX509Certificate*& aServerCert, |
|
295 TRequestStatus& aStatus); |
|
296 |
|
297 /** |
|
298 This asynchronous method uses the server's public key to ensure that the signature was indeed created by the server. The result of this operation will be written in the aResult parameter.. |
|
299 @return Tbool Explanation of the object returned |
|
300 @param aServerPublicKey The server's public key; used to decrypt the signature created with the server's private key. |
|
301 @param aDigest - The data which we expect to extract from the server's signature when decrypted. |
|
302 @param aSig- The server's signature. |
|
303 @return ETrue if positively verified, otherwise EFalse |
|
304 */ |
|
305 IMPORT_C TBool VerifySignatureL( |
|
306 const CSubjectPublicKeyInfo& aServerPublicKey, |
|
307 const TDesC8& aDigest, |
|
308 const TDesC8& aSig); |
|
309 |
|
310 /** |
|
311 This asynchronous method will provide a session identifier object associated with a given server indicated by the aServerName argument |
|
312 @param aServerName - The name of the server the SSL/TLS protocol is intending to connect to. |
|
313 @param aSessionId - The respective session id from the session. |
|
314 @param aStatus - Asynchronous request status value that can be checked by the client. |
|
315 @return Void, as this is an asynchronous method. On completion of the asynchronous request, the result will be read from the aSessionId parameter. |
|
316 */ |
|
317 IMPORT_C void GetSessionL( |
|
318 TTLSServerAddr& aServerName, |
|
319 TTLSSessionId& aSessionId, |
|
320 TRequestStatus& aStatus) ; |
|
321 |
|
322 /** |
|
323 This asynchronous method will clear the session identified by the ServerName and Session.iId in aServerNameAndId.This operation may fail if the session cached on a token is in use (this maybe possible if a hardware token, e.g. a WIM is used. It is unlikely in the case of a software token implementation). |
|
324 @param aServerNameAndId - The name of the server and the corresponding session Id |
|
325 @param aStatus - Asynchronous request status value , ETrue if the cache is cleared otherwise EFalse. |
|
326 @return Void, as this is an asynchronous method. On completion of the asynchronous request, the result will be read from the aStatus parameter. |
|
327 */ |
|
328 IMPORT_C void ClearSessionCacheL( |
|
329 TTLSSessionNameAndID& aServerNameAndId, |
|
330 TRequestStatus& aStatus); |
|
331 |
|
332 /** |
|
333 The first call to CTLSProvider takes place before ClientHello is send, then as the handshake progress, the information relevant for Provider and token will be gradually filled in the structure returned by this API, If the structure already exists, then the pointer to the same structure is returned. |
|
334 @return A pointer to TTlsCryptoAttributes. |
|
335 */ |
|
336 IMPORT_C CTlsCryptoAttributes* Attributes(); |
|
337 |
|
338 /** |
|
339 This sets the TLS session pointer |
|
340 @return pointer to the CTLSSession |
|
341 */ |
|
342 IMPORT_C CTLSSession* TlsSessionPtr(); |
|
343 |
|
344 /** |
|
345 This method cancels all the asynchronous operations of CTLSProvider |
|
346 */ |
|
347 IMPORT_C void CancelRequest(); |
|
348 |
|
349 /** |
|
350 reconnect the connection if it fails at initial stage of conneciton |
|
351 */ |
|
352 IMPORT_C void ReConnectL(); |
|
353 |
|
354 IMPORT_C ~CTLSProvider(); |
|
355 |
|
356 private: |
|
357 /** |
|
358 An object of this class will be provided to the SSL/TLS Protocol client when it first requests a service from the TLS Provider token interface |
|
359 @param aProviderPtr |
|
360 */ |
|
361 CTLSProvider(CTlsProviderImpl* aProviderPtr); |
|
362 private: |
|
363 CTlsProviderImpl* iTlsProviderImpl; |
|
364 CTLSSession** iTlsSession; |
|
365 MCTToken* iTokenInterface; |
|
366 }; |
|
367 |
|
368 #endif |
|
369 |