|
1 // Copyright (c) 2005-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 // crypto.h - IPSEC API towards cryptographic libraries |
|
15 // |
|
16 |
|
17 |
|
18 |
|
19 /** |
|
20 @internalComponent |
|
21 */ |
|
22 |
|
23 #ifndef __CRYPTO_H__ |
|
24 #define __CRYPTO_H__ |
|
25 /** |
|
26 // @file crypto.h |
|
27 // |
|
28 // The basic API for cryptographic algorithm library. |
|
29 // |
|
30 // IPSEC hook itself does not contain any cryptographic algorithms. |
|
31 // The available algorithms are dynamically imported to the IPSEC |
|
32 // by binding the IPSEC (pfkey) to one or more cryptographic libraries, |
|
33 // each of which are implemented as a protocol.. |
|
34 // |
|
35 // This header describes the basic API and base classes for building |
|
36 // such cryptographic algorithm libraries as protocol modules for IPSEC. |
|
37 // |
|
38 // In the TServerProtocolDesc of such protocol, the following fields |
|
39 // are significant for the IPSEC: |
|
40 // |
|
41 // @li TServerProtocolDesc::iName (protocol name) is the symbolic |
|
42 // name of the library. When multiple libraries are used, |
|
43 // they should have different names. |
|
44 // @li TServerProtocolDesc::iAddrFamily should be KAfCrypto |
|
45 // @li TServerProtocolDesc::iProtocol must be KProtocolCrypto |
|
46 // |
|
47 // The remaining fields can be freely initialized to any values |
|
48 // that satisfy the SocketServer requirements. The chosen values |
|
49 // will have no effect on the IPSEC functionality. |
|
50 // |
|
51 // The cryptographic library protocol can be implemented in any |
|
52 // protocol module (PRT file) along with other protocols. The |
|
53 // value KProtocolCrypto alone in iProtocol tells that the protocol |
|
54 // supports the API defined by this definition. |
|
55 // |
|
56 // An example of possible Ipsec configuration (ESK file) |
|
57 // @verbatim |
|
58 |
|
59 [sockman] |
|
60 protocols= secpol,pfkey,lib1,lib2 |
|
61 |
|
62 [pfkey] |
|
63 filename= ipsec6.prt |
|
64 index= 2 |
|
65 bindto= lib1,lib2 |
|
66 |
|
67 [secpol] |
|
68 filename= ipsec6.prt |
|
69 index= 1 |
|
70 bindto= pfkey,ip6 |
|
71 |
|
72 [lib1] |
|
73 filename= eaysymb.prt |
|
74 index= 1 |
|
75 |
|
76 [lib2] |
|
77 filename= newcrypto.prt |
|
78 index= 1 |
|
79 @endverbatim |
|
80 |
|
81 @internalTechnology |
|
82 @released |
|
83 */ |
|
84 #include <e32base.h> |
|
85 #include <es_prot.h> |
|
86 |
|
87 #include "cryptospidef.h" |
|
88 #include "cryptosymmetriccipherapi.h" |
|
89 #include "cryptomacapi.h" |
|
90 |
|
91 /** |
|
92 // The protocol number for a library. |
|
93 */ |
|
94 const TUint KProtocolCrypto = 0x104; |
|
95 /** |
|
96 // The protocol family for the library. |
|
97 */ |
|
98 const TUint KAfCrypto = 0x0803; |
|
99 |
|
100 |
|
101 typedef TBuf<0x20> TAlgorithmName; |
|
102 |
|
103 /** |
|
104 * @name Well Known Algorithm Names |
|
105 * The cryptographic libary can choose the names for it's algorithms freely, |
|
106 * but it will cause less confusion, if the well known standard algoriths |
|
107 * are named uniformly. |
|
108 */ |
|
109 //@{ |
|
110 /** |
|
111 * Single DES in CBC-Mode. |
|
112 * - key: 8 |
|
113 * - block: 8 |
|
114 * - IV: 8 |
|
115 */ |
|
116 _LIT(KIpsecName_DES_CBC, "descbc"); |
|
117 /** |
|
118 * Triple DES in CBC-Mode. |
|
119 * - key: 24 |
|
120 * - block: 8 |
|
121 * - IV: 8 |
|
122 */ |
|
123 _LIT(KIpsecName_3DES_CBC, "3descbc"); |
|
124 /** |
|
125 * Blowfish in CBC-Mode. |
|
126 * - key: variable in 8..72 |
|
127 * - block: 8 |
|
128 * - IV: 8 |
|
129 */ |
|
130 _LIT(KIpsecName_BLOWFISH_CBC, "blowfish"); |
|
131 /** |
|
132 * IDEA in CBC-Mode. |
|
133 * - key: 16 |
|
134 * - block: 8 |
|
135 * - IV: 8 |
|
136 */ |
|
137 _LIT(KIpsecName_IDEA_CBC, "idea"); |
|
138 /** |
|
139 * AES in CBC-Mode. |
|
140 * - key: 16, 24 or 32 |
|
141 * - block: 16 |
|
142 * - IV: 16 |
|
143 */ |
|
144 _LIT(KIpsecName_AES_CBC, "aescbc"); |
|
145 /** |
|
146 * AES in CTR-Mode. |
|
147 * - key 16, 24 or 32 (+ append 4 octets for the NONCE) |
|
148 * - block: 16 |
|
149 * - IV: 8 |
|
150 */ |
|
151 _LIT(KIpsecName_AES_CTR, "aesctr"); |
|
152 /** |
|
153 * RC5 in CBC-Mode. |
|
154 * - key: variable 5..255 |
|
155 * - block: 8 |
|
156 * - IV: 8 |
|
157 */ |
|
158 _LIT(KIpsecName_RC5, "rc5"); |
|
159 /** |
|
160 * SHA1 Digest. |
|
161 * - digest length: 20 |
|
162 * - block: 64 |
|
163 */ |
|
164 _LIT(KIpsecName_SHA1, "sha1"); |
|
165 /** |
|
166 * SHA2-256 Digest. |
|
167 * - digest length: 32 |
|
168 * - block: 64 |
|
169 */ |
|
170 _LIT(KIpsecName_SHA2_256, "sha2-256"); |
|
171 /** |
|
172 * MD5 Digest. |
|
173 * - digest length: 16 |
|
174 * - block: 64 |
|
175 */ |
|
176 _LIT(KIpsecName_MD5, "md5"); |
|
177 /** |
|
178 * |
|
179 * |
|
180 */ |
|
181 #ifdef SYMBIAN_IPSEC_VOIP_SUPPORT |
|
182 _LIT(KIpsecName_AES_XCBC_MAC, "aesxcbcmac") ; |
|
183 #endif //SYMBIAN_IPSEC_VOIP_SUPPORT |
|
184 //@} |
|
185 |
|
186 typedef enum |
|
187 { |
|
188 EAlgorithmClass_Digest, //< Message Digest algorithm |
|
189 EAlgorithmClass_Cipher, //< Symmetric Cipher algorithm |
|
190 #ifdef SYMBIAN_IPSEC_VOIP_SUPPORT |
|
191 EAlgorithmClass_Mac , |
|
192 #endif //SYMBIAN_IPSEC_VOIP_SUPPORT |
|
193 // |
|
194 // New types are possible by adding the symbol here |
|
195 // and defining the corresponding abstract class |
|
196 // (similar to CMessageDigestCrypto and CSymmetricCipher) |
|
197 // |
|
198 } TAlgorithmClass; |
|
199 |
|
200 // TAlgorithmDesc (and related types) |
|
201 /** |
|
202 // A description of available algorithm. |
|
203 // |
|
204 // Similar to ProtocolList, a protocol supporting this API must |
|
205 // return a description of each implemented algorithm as an |
|
206 // array of TAlgorithmDesc objects as a result of AlgorithmList |
|
207 // call. |
|
208 */ |
|
209 class TAlgorithmDesc |
|
210 { |
|
211 public: |
|
212 TAlgorithmName iName; //< Name of the algorithm |
|
213 TAlgorithmClass iAlgType; //< Class of the algorithm (cipher/digest) |
|
214 TUint iMinBits; //< Min Length of the key in bits (all keys total) |
|
215 TUint iMaxBits; //< Max Length of the key in bits (all keys total) |
|
216 TUint iBlock; //< Length of the block in bytes |
|
217 TUint iVector; //< Initialization Vector length (bytes) |
|
218 }; |
|
219 |
|
220 // Each of the following includes virtual destructor |
|
221 // just in case there is a need for a cleanup code |
|
222 // when the object is deleted using a pointer to |
|
223 // the base virtual class. |
|
224 |
|
225 // CMessageDigestCrypto |
|
226 // ******************** |
|
227 /** |
|
228 // Base Message Digest (abstract) class. |
|
229 // |
|
230 // All message digest algorithms must be derived from this |
|
231 // base class, which defines the IPSEC required API for |
|
232 // message digests (used by AH and ESP with authentication |
|
233 // implementations). |
|
234 // |
|
235 // Because IPSEC needs to run digest for each packet |
|
236 // independently, it is important that the implementation |
|
237 // can reset the computation by Init() without needing |
|
238 // to do any additional allocations. |
|
239 */ |
|
240 class CMessageDigestCrypto : public CBase |
|
241 { |
|
242 // NOTE: This class was originally designed based on assumption |
|
243 // that the derived class implementing the digest includes all |
|
244 // state in member variables and does not need to allocate |
|
245 // additional space -- thus no ConstructL method. |
|
246 public: |
|
247 /** |
|
248 // Set digest into initial state. |
|
249 // |
|
250 // IPSEC calls this method to start a new digest |
|
251 // computation for each IP packet that needs |
|
252 // digest computation. |
|
253 */ |
|
254 virtual void Init()=0; |
|
255 /** |
|
256 // Add segment of data to the digest. |
|
257 // |
|
258 // The octets in aMessage must be added to the digest |
|
259 // value. The length of the aMessage can be anything |
|
260 // from 0 or more octets. If the digest algorithm has |
|
261 // any inherent block requirements, then this method |
|
262 // must handle it (specifically, the digest must work |
|
263 // correctly, even if the data is fed to it one byte |
|
264 // at time). |
|
265 // |
|
266 // @param aMessage |
|
267 // describe the segment of octets to be added into |
|
268 // the digest (length >= 0). |
|
269 */ |
|
270 virtual void Update(const TDesC8& aMessage)=0; |
|
271 /** |
|
272 // Wrap up the digest and return the result. |
|
273 // |
|
274 // @param aDigest |
|
275 // a buffer to return the final computed digest value. |
|
276 */ |
|
277 virtual void Final(TDes8& aDigest)=0; |
|
278 virtual ~CMessageDigestCrypto() {} |
|
279 }; |
|
280 |
|
281 #ifdef SYMBIAN_IPSEC_VOIP_SUPPORT |
|
282 class CMacCrypto : public CBase |
|
283 { |
|
284 public: |
|
285 /** |
|
286 // Set digest into initial state. |
|
287 // |
|
288 // IPSEC calls this method to start a new digest |
|
289 // computation for each IP packet that needs |
|
290 // digest computation. |
|
291 */ |
|
292 virtual void Init()=0; |
|
293 /** |
|
294 // Add segment of data to the digest. |
|
295 // |
|
296 // The octets in aMessage must be added to the digest |
|
297 // value. The length of the aMessage can be anything |
|
298 // from 0 or more octets. If the digest algorithm has |
|
299 // any inherent block requirements, then this method |
|
300 // must handle it (specifically, the digest must work |
|
301 // correctly, even if the data is fed to it one byte |
|
302 // at time). |
|
303 // |
|
304 // @param aMessage |
|
305 // describe the segment of octets to be added into |
|
306 // the digest (length >= 0). |
|
307 */ |
|
308 virtual void Update(const TDesC8& aMessage)=0; |
|
309 /** |
|
310 // Wrap up the digest and return the result. |
|
311 // |
|
312 // @param aDigest |
|
313 // a buffer to return the final computed digest value. |
|
314 */ |
|
315 virtual void Final(TDes8& aDigest)=0; |
|
316 virtual ~CMacCrypto() {} |
|
317 }; |
|
318 #endif //SYMBIAN_IPSEC_VOIP_SUPPORT |
|
319 |
|
320 // CSymmetricCipher |
|
321 // **************** |
|
322 /** |
|
323 // Base Symmetric Cipher (abstract) class. |
|
324 // |
|
325 // All cipher algorithms must be derived from this |
|
326 // base class, which defines the IPSEC required API for |
|
327 // cipher algorithms (used by ESP implementation). |
|
328 // |
|
329 // Because IPSEC needs to run cipher for each packet |
|
330 // independently, it is important that the implementation |
|
331 // can reset the computation by InitL() without needing |
|
332 // to do any additional allocations [which means that |
|
333 // it being a leaving function is a bad sign!] |
|
334 */ |
|
335 class CSymmetricCipher : public CBase |
|
336 { |
|
337 public: |
|
338 enum TAction { EEncrypt, EDecrypt }; |
|
339 /** |
|
340 // Define the cipher key. |
|
341 // |
|
342 // Because setting the key can be time consuming, |
|
343 // this is only called once after instantiation of the |
|
344 // class. Then, each packet is started with a call |
|
345 // to InitL. |
|
346 // |
|
347 // @param aKey |
|
348 // the cipher key. The length of the key is |
|
349 // defined by the length of this descriptor, |
|
350 // and is always multiple of 8 bits. |
|
351 // @return |
|
352 // @li > 0, the key is weak (but set anyway) |
|
353 // @li = 0, all ok |
|
354 // @li < 0, the key not usable (not set) |
|
355 */ |
|
356 virtual TInt Setkey(const TDesC8& aKey)=0; |
|
357 /** |
|
358 // Reset the cipher engine to initial state. |
|
359 // |
|
360 // As this method is called for each packet, it |
|
361 // should not do any memory allocation or heavy |
|
362 // computations. |
|
363 // |
|
364 // @param aIV initial vector. |
|
365 // @param aMode tells whether initialize is for decrypt or encrypt. |
|
366 */ |
|
367 virtual void Init(const TDesC8 &aIV, TAction aMode)=0; |
|
368 /** |
|
369 // Perform encryption or decryption. |
|
370 // |
|
371 // Because algorithms are expected to work blocks, the |
|
372 // caller will guarantee that ALL Outbuf's given to Update |
|
373 // will exist up to Finish call (or at least as long as at |
|
374 // least blocksize octets have been given to Update after it). |
|
375 // The implementation of the algorithm can store pointer(s) to |
|
376 // aOutbuf described memory area, and return data to such |
|
377 // memory area on some later Update or Finish call. |
|
378 // |
|
379 // The lengths of buffers are always equal, e.g. aInbuf.Length() |
|
380 // octets will always fit into aOutbuf. This length can be anything |
|
381 // from zero upwards. The cipher must work even if octets were |
|
382 // fed to it one by one. |
|
383 // |
|
384 // @param aOutbuf result of the decrypt/encrypt |
|
385 // @param aInbuf input to decrypt/encrypt |
|
386 */ |
|
387 virtual void Update(TDes8& aOutbuf,const TDesC8& aInbuf)=0; |
|
388 /** |
|
389 // Finish encryption or decryption. |
|
390 // |
|
391 // Calling Finish is optional, it is needed if the total |
|
392 // bytes is not multiple of the blocksize, or if one wants |
|
393 // to get the final IV. |
|
394 // |
|
395 // IPSEC does use the final IV. |
|
396 // |
|
397 // @param aIV the place to return the final IV. |
|
398 */ |
|
399 virtual void Finish(TDes8& aIV)=0; |
|
400 virtual ~CSymmetricCipher() {} |
|
401 }; |
|
402 |
|
403 // CProtocolCrypto |
|
404 // *************** |
|
405 /** |
|
406 // Base class of the protocol implementing an algorithm library as a protocol |
|
407 // |
|
408 // All algorithm libraries must be derived from this base class. |
|
409 */ |
|
410 class CProtocolCrypto : public CProtocolBase |
|
411 { |
|
412 public: |
|
413 /** |
|
414 // Return the list of supported algorithms. |
|
415 // |
|
416 // IPSEC calls this method once during the binding |
|
417 // process to find out the algorithms that are supported |
|
418 // by this library. |
|
419 // |
|
420 // @retval aList |
|
421 // a pointer to a new allocated array of TAlgorithmDesc. |
|
422 // This array contains the descriptions of the supported |
|
423 // algorithms. Can also return NULL, if not algorithms |
|
424 // are supported at this point. The calling IPSEC will |
|
425 // release this array, when it is not needed. |
|
426 // |
|
427 // @returns |
|
428 // the length of the the array. May also return <= 0, |
|
429 // in which case IPSEC will not be using any algorithms |
|
430 // from this library. |
|
431 */ |
|
432 virtual TUint AlgorithmList(TAlgorithmDesc *&aList) = 0; |
|
433 /** |
|
434 // Create an instance of cipher algorithm |
|
435 // |
|
436 // When IPSEC requires a use of specific algorithm, it |
|
437 // asks a new instance of the algorithm by calling this |
|
438 // method. |
|
439 // |
|
440 // @param aAlg |
|
441 // index of the algorithm in the array of descriptions |
|
442 // that was returned by the AlgorithmList(). |
|
443 // |
|
444 // @param aKey - The key value to be used in the encryption/decryption operation |
|
445 // @return |
|
446 // @li NULL, if algorithm could not be instantiated |
|
447 // @li non-NULL (= new algorithm engine instance), if algorithm instantiated |
|
448 */ |
|
449 virtual CryptoSpi::CSymmetricCipher* SymmetricCipherL(TUint aAlg, const TDesC8 &aKey)=0; |
|
450 #ifdef SYMBIAN_IPSEC_VOIP_SUPPORT |
|
451 virtual CryptoSpi::CMac* GetMacImplementationL(const TDesC8& aKey)=0; |
|
452 #endif |
|
453 /** |
|
454 // Create an instance of digest algorithm |
|
455 // |
|
456 // When IPSEC requires a use of specific algorithm, it |
|
457 // asks a new instance of the algorithm by calling this |
|
458 // method. |
|
459 // |
|
460 // @param aAlg |
|
461 // index of the algorithm in the array of descriptions |
|
462 // that was returned by the AlgorithmList(). |
|
463 // |
|
464 // @return |
|
465 // @li NULL, if algorithm could not be instantiated |
|
466 // @li non-NULL (= new algorithm engine instance), if algorithm instantiated |
|
467 */ |
|
468 virtual CMessageDigestCrypto* MessageDigest(TUint aAlg)=0; |
|
469 protected: |
|
470 virtual ~CProtocolCrypto() {} |
|
471 }; |
|
472 |
|
473 #endif |