ee8c44d367efa9163bc0790545f343f85d25ef25
[mirror_edk2.git] / CryptoPkg / Include / Library / BaseCryptLib.h
1 /** @file\r
2   Defines base cryptographic library APIs.\r
3   The Base Cryptographic Library provides implementations of basic cryptography\r
4   primitives (Hash Serials, HMAC, RSA, Diffie-Hellman, etc) for UEFI security\r
5   functionality enabling.\r
6 \r
7 Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR>\r
8 This program and the accompanying materials\r
9 are licensed and made available under the terms and conditions of the BSD License\r
10 which accompanies this distribution.  The full text of the license may be found at\r
11 http://opensource.org/licenses/bsd-license.php\r
12 \r
13 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
14 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
15 \r
16 **/\r
17 \r
18 #ifndef __BASE_CRYPT_LIB_H__\r
19 #define __BASE_CRYPT_LIB_H__\r
20 \r
21 ///\r
22 /// MD5 digest size in bytes\r
23 ///\r
24 #define MD5_DIGEST_SIZE     16\r
25 \r
26 ///\r
27 /// SHA-1 digest size in bytes.\r
28 ///\r
29 #define SHA1_DIGEST_SIZE    20\r
30 \r
31 ///\r
32 /// SHA-256 digest size in bytes\r
33 ///\r
34 #define SHA256_DIGEST_SIZE  32\r
35 \r
36 ///\r
37 /// TDES block size in bytes\r
38 ///\r
39 #define TDES_BLOCK_SIZE     8\r
40 \r
41 ///\r
42 /// AES block size in bytes\r
43 ///\r
44 #define AES_BLOCK_SIZE      16\r
45 \r
46 ///\r
47 /// RSA Key Tags Definition used in RsaSetKey() function for key component identification.\r
48 ///\r
49 typedef enum {\r
50   RsaKeyN,      ///< RSA public Modulus (N)\r
51   RsaKeyE,      ///< RSA Public exponent (e)\r
52   RsaKeyD,      ///< RSA Private exponent (d)\r
53   RsaKeyP,      ///< RSA secret prime factor of Modulus (p)\r
54   RsaKeyQ,      ///< RSA secret prime factor of Modules (q)\r
55   RsaKeyDp,     ///< p's CRT exponent (== d mod (p - 1))\r
56   RsaKeyDq,     ///< q's CRT exponent (== d mod (q - 1))\r
57   RsaKeyQInv    ///< The CRT coefficient (== 1/q mod p)\r
58 } RSA_KEY_TAG;\r
59 \r
60 //=====================================================================================\r
61 //    One-Way Cryptographic Hash Primitives\r
62 //=====================================================================================\r
63 \r
64 /**\r
65   Retrieves the size, in bytes, of the context buffer required for MD5 hash operations.\r
66 \r
67   @return  The size, in bytes, of the context buffer required for MD5 hash operations.\r
68 \r
69 **/\r
70 UINTN\r
71 EFIAPI\r
72 Md5GetContextSize (\r
73   VOID\r
74   );\r
75 \r
76 /**\r
77   Initializes user-supplied memory pointed by Md5Context as MD5 hash context for\r
78   subsequent use.\r
79 \r
80   If Md5Context is NULL, then ASSERT().\r
81 \r
82   @param[out]  Md5Context  Pointer to MD5 context being initialized.\r
83 \r
84   @retval TRUE   MD5 context initialization succeeded.\r
85   @retval FALSE  MD5 context initialization failed.\r
86 \r
87 **/\r
88 BOOLEAN\r
89 EFIAPI\r
90 Md5Init (\r
91   OUT  VOID  *Md5Context\r
92   );\r
93 \r
94 /**\r
95   Makes a copy of an existing MD5 context.\r
96 \r
97   If Md5Context is NULL, then ASSERT().\r
98   If NewMd5Context is NULL, then ASSERT().\r
99 \r
100   @param[in]  Md5Context     Pointer to MD5 context being copied.\r
101   @param[out] NewMd5Context  Pointer to new MD5 context.\r
102 \r
103   @retval TRUE   MD5 context copy succeeded.\r
104   @retval FALSE  MD5 context copy failed.\r
105 \r
106 **/\r
107 BOOLEAN\r
108 EFIAPI\r
109 Md5Duplicate (\r
110   IN   CONST VOID  *Md5Context,\r
111   OUT  VOID        *NewMd5Context\r
112   );\r
113 \r
114 /**\r
115   Digests the input data and updates MD5 context.\r
116 \r
117   This function performs MD5 digest on a data buffer of the specified size.\r
118   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
119   MD5 context should be already correctly intialized by Md5Init(), and should not be finalized\r
120   by Md5Final(). Behavior with invalid context is undefined.\r
121 \r
122   If Md5Context is NULL, then ASSERT().\r
123 \r
124   @param[in, out]  Md5Context  Pointer to the MD5 context.\r
125   @param[in]       Data        Pointer to the buffer containing the data to be hashed.\r
126   @param[in]       DataSize    Size of Data buffer in bytes.\r
127 \r
128   @retval TRUE   MD5 data digest succeeded.\r
129   @retval FALSE  MD5 data digest failed.\r
130 \r
131 **/\r
132 BOOLEAN\r
133 EFIAPI\r
134 Md5Update (\r
135   IN OUT  VOID        *Md5Context,\r
136   IN      CONST VOID  *Data,\r
137   IN      UINTN       DataSize\r
138   );\r
139 \r
140 /**\r
141   Completes computation of the MD5 digest value.\r
142 \r
143   This function completes MD5 hash computation and retrieves the digest value into\r
144   the specified memory. After this function has been called, the MD5 context cannot\r
145   be used again.\r
146   MD5 context should be already correctly intialized by Md5Init(), and should not be\r
147   finalized by Md5Final(). Behavior with invalid MD5 context is undefined.\r
148 \r
149   If Md5Context is NULL, then ASSERT().\r
150   If HashValue is NULL, then ASSERT().\r
151 \r
152   @param[in, out]  Md5Context  Pointer to the MD5 context.\r
153   @param[out]      HashValue   Pointer to a buffer that receives the MD5 digest\r
154                                value (16 bytes).\r
155 \r
156   @retval TRUE   MD5 digest computation succeeded.\r
157   @retval FALSE  MD5 digest computation failed.\r
158 \r
159 **/\r
160 BOOLEAN\r
161 EFIAPI\r
162 Md5Final (\r
163   IN OUT  VOID   *Md5Context,\r
164   OUT     UINT8  *HashValue\r
165   );\r
166 \r
167 /**\r
168   Retrieves the size, in bytes, of the context buffer required for SHA-1 hash operations.\r
169 \r
170   @return  The size, in bytes, of the context buffer required for SHA-1 hash operations.\r
171 \r
172 **/\r
173 UINTN\r
174 EFIAPI\r
175 Sha1GetContextSize (\r
176   VOID\r
177   );\r
178 \r
179 /**\r
180   Initializes user-supplied memory pointed by Sha1Context as SHA-1 hash context for\r
181   subsequent use.\r
182 \r
183   If Sha1Context is NULL, then ASSERT().\r
184 \r
185   @param[out]  Sha1Context  Pointer to SHA-1 context being initialized.\r
186 \r
187   @retval TRUE   SHA-1 context initialization succeeded.\r
188   @retval FALSE  SHA-1 context initialization failed.\r
189 \r
190 **/\r
191 BOOLEAN\r
192 EFIAPI\r
193 Sha1Init (\r
194   OUT  VOID  *Sha1Context\r
195   );\r
196 \r
197 /**\r
198   Makes a copy of an existing SHA-1 context.\r
199 \r
200   If Sha1Context is NULL, then ASSERT().\r
201   If NewSha1Context is NULL, then ASSERT().\r
202 \r
203   @param[in]  Sha1Context     Pointer to SHA-1 context being copied.\r
204   @param[out] NewSha1Context  Pointer to new SHA-1 context.\r
205 \r
206   @retval TRUE   SHA-1 context copy succeeded.\r
207   @retval FALSE  SHA-1 context copy failed.\r
208 \r
209 **/\r
210 BOOLEAN\r
211 EFIAPI\r
212 Sha1Duplicate (\r
213   IN   CONST VOID  *Sha1Context,\r
214   OUT  VOID        *NewSha1Context\r
215   );\r
216 \r
217 /**\r
218   Digests the input data and updates SHA-1 context.\r
219 \r
220   This function performs SHA-1 digest on a data buffer of the specified size.\r
221   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
222   SHA-1 context should be already correctly intialized by Sha1Init(), and should not be finalized\r
223   by Sha1Final(). Behavior with invalid context is undefined.\r
224 \r
225   If Sha1Context is NULL, then ASSERT().\r
226 \r
227   @param[in, out]  Sha1Context  Pointer to the SHA-1 context.\r
228   @param[in]       Data         Pointer to the buffer containing the data to be hashed.\r
229   @param[in]       DataSize     Size of Data buffer in bytes.\r
230 \r
231   @retval TRUE   SHA-1 data digest succeeded.\r
232   @retval FALSE  SHA-1 data digest failed.\r
233 \r
234 **/\r
235 BOOLEAN\r
236 EFIAPI\r
237 Sha1Update (\r
238   IN OUT  VOID        *Sha1Context,\r
239   IN      CONST VOID  *Data,\r
240   IN      UINTN       DataSize\r
241   );\r
242 \r
243 /**\r
244   Completes computation of the SHA-1 digest value.\r
245 \r
246   This function completes SHA-1 hash computation and retrieves the digest value into\r
247   the specified memory. After this function has been called, the SHA-1 context cannot\r
248   be used again.\r
249   SHA-1 context should be already correctly intialized by Sha1Init(), and should not be\r
250   finalized by Sha1Final(). Behavior with invalid SHA-1 context is undefined.\r
251 \r
252   If Sha1Context is NULL, then ASSERT().\r
253   If HashValue is NULL, then ASSERT().\r
254 \r
255   @param[in, out]  Sha1Context  Pointer to the SHA-1 context.\r
256   @param[out]      HashValue    Pointer to a buffer that receives the SHA-1 digest\r
257                                 value (20 bytes).\r
258 \r
259   @retval TRUE   SHA-1 digest computation succeeded.\r
260   @retval FALSE  SHA-1 digest computation failed.\r
261 \r
262 **/\r
263 BOOLEAN\r
264 EFIAPI\r
265 Sha1Final (\r
266   IN OUT  VOID   *Sha1Context,\r
267   OUT     UINT8  *HashValue\r
268   );\r
269 \r
270 /**\r
271   Retrieves the size, in bytes, of the context buffer required for SHA-256 hash operations.\r
272 \r
273   @return  The size, in bytes, of the context buffer required for SHA-256 hash operations.\r
274 \r
275 **/\r
276 UINTN\r
277 EFIAPI\r
278 Sha256GetContextSize (\r
279   VOID\r
280   );\r
281 \r
282 /**\r
283   Initializes user-supplied memory pointed by Sha256Context as SHA-256 hash context for\r
284   subsequent use.\r
285 \r
286   If Sha256Context is NULL, then ASSERT().\r
287 \r
288   @param[out]  Sha256Context  Pointer to SHA-256 context being initialized.\r
289 \r
290   @retval TRUE   SHA-256 context initialization succeeded.\r
291   @retval FALSE  SHA-256 context initialization failed.\r
292 \r
293 **/\r
294 BOOLEAN\r
295 EFIAPI\r
296 Sha256Init (\r
297   OUT  VOID  *Sha256Context\r
298   );\r
299 \r
300 /**\r
301   Makes a copy of an existing SHA-256 context.\r
302 \r
303   If Sha256Context is NULL, then ASSERT().\r
304   If NewSha256Context is NULL, then ASSERT().\r
305 \r
306   @param[in]  Sha256Context     Pointer to SHA-256 context being copied.\r
307   @param[out] NewSha256Context  Pointer to new SHA-256 context.\r
308 \r
309   @retval TRUE   SHA-256 context copy succeeded.\r
310   @retval FALSE  SHA-256 context copy failed.\r
311 \r
312 **/\r
313 BOOLEAN\r
314 EFIAPI\r
315 Sha256Duplicate (\r
316   IN   CONST VOID  *Sha256Context,\r
317   OUT  VOID        *NewSha256Context\r
318   );\r
319 \r
320 /**\r
321   Digests the input data and updates SHA-256 context.\r
322 \r
323   This function performs SHA-256 digest on a data buffer of the specified size.\r
324   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
325   SHA-256 context should be already correctly intialized by Sha256Init(), and should not be finalized\r
326   by Sha256Final(). Behavior with invalid context is undefined.\r
327 \r
328   If Sha256Context is NULL, then ASSERT().\r
329 \r
330   @param[in, out]  Sha256Context  Pointer to the SHA-256 context.\r
331   @param[in]       Data           Pointer to the buffer containing the data to be hashed.\r
332   @param[in]       DataSize       Size of Data buffer in bytes.\r
333 \r
334   @retval TRUE   SHA-256 data digest succeeded.\r
335   @retval FALSE  SHA-256 data digest failed.\r
336 \r
337 **/\r
338 BOOLEAN\r
339 EFIAPI\r
340 Sha256Update (\r
341   IN OUT  VOID        *Sha256Context,\r
342   IN      CONST VOID  *Data,\r
343   IN      UINTN       DataSize\r
344   );\r
345 \r
346 /**\r
347   Completes computation of the SHA-256 digest value.\r
348 \r
349   This function completes SHA-256 hash computation and retrieves the digest value into\r
350   the specified memory. After this function has been called, the SHA-256 context cannot\r
351   be used again.\r
352   SHA-256 context should be already correctly intialized by Sha256Init(), and should not be\r
353   finalized by Sha256Final(). Behavior with invalid SHA-256 context is undefined.\r
354 \r
355   If Sha256Context is NULL, then ASSERT().\r
356   If HashValue is NULL, then ASSERT().\r
357 \r
358   @param[in, out]  Sha256Context  Pointer to the SHA-256 context.\r
359   @param[out]      HashValue      Pointer to a buffer that receives the SHA-256 digest\r
360                                   value (32 bytes).\r
361 \r
362   @retval TRUE   SHA-256 digest computation succeeded.\r
363   @retval FALSE  SHA-256 digest computation failed.\r
364 \r
365 **/\r
366 BOOLEAN\r
367 EFIAPI\r
368 Sha256Final (\r
369   IN OUT  VOID   *Sha256Context,\r
370   OUT     UINT8  *HashValue\r
371   );\r
372 \r
373 \r
374 //=====================================================================================\r
375 //    MAC (Message Authentication Code) Primitive\r
376 //=====================================================================================\r
377 \r
378 /**\r
379   Retrieves the size, in bytes, of the context buffer required for HMAC-MD5 operations.\r
380 \r
381   @return  The size, in bytes, of the context buffer required for HMAC-MD5 operations.\r
382 \r
383 **/\r
384 UINTN\r
385 EFIAPI\r
386 HmacMd5GetContextSize (\r
387   VOID\r
388   );\r
389 \r
390 /**\r
391   Initializes user-supplied memory pointed by HmacMd5Context as HMAC-MD5 context for\r
392   subsequent use.\r
393 \r
394   If HmacMd5Context is NULL, then ASSERT().\r
395 \r
396   @param[out]  HmacMd5Context  Pointer to HMAC-MD5 context being initialized.\r
397   @param[in]   Key             Pointer to the user-supplied key.\r
398   @param[in]   KeySize         Key size in bytes.\r
399 \r
400   @retval TRUE   HMAC-MD5 context initialization succeeded.\r
401   @retval FALSE  HMAC-MD5 context initialization failed.\r
402 \r
403 **/\r
404 BOOLEAN\r
405 EFIAPI\r
406 HmacMd5Init (\r
407   OUT  VOID         *HmacMd5Context,\r
408   IN   CONST UINT8  *Key,\r
409   IN   UINTN        KeySize\r
410   );\r
411 \r
412 /**\r
413   Makes a copy of an existing HMAC-MD5 context.\r
414 \r
415   If HmacMd5Context is NULL, then ASSERT().\r
416   If NewHmacMd5Context is NULL, then ASSERT().\r
417 \r
418   @param[in]  HmacMd5Context     Pointer to HMAC-MD5 context being copied.\r
419   @param[out] NewHmacMd5Context  Pointer to new HMAC-MD5 context.\r
420 \r
421   @retval TRUE   HMAC-MD5 context copy succeeded.\r
422   @retval FALSE  HMAC-MD5 context copy failed.\r
423 \r
424 **/\r
425 BOOLEAN\r
426 EFIAPI\r
427 HmacMd5Duplicate (\r
428   IN   CONST VOID  *HmacMd5Context,\r
429   OUT  VOID        *NewHmacMd5Context\r
430   );\r
431 \r
432 /**\r
433   Digests the input data and updates HMAC-MD5 context.\r
434 \r
435   This function performs HMAC-MD5 digest on a data buffer of the specified size.\r
436   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
437   HMAC-MD5 context should be already correctly intialized by HmacMd5Init(), and should not be\r
438   finalized by HmacMd5Final(). Behavior with invalid context is undefined.\r
439 \r
440   If HmacMd5Context is NULL, then ASSERT().\r
441 \r
442   @param[in, out]  HmacMd5Context  Pointer to the HMAC-MD5 context.\r
443   @param[in]       Data            Pointer to the buffer containing the data to be digested.\r
444   @param[in]       DataSize        Size of Data buffer in bytes.\r
445 \r
446   @retval TRUE   HMAC-MD5 data digest succeeded.\r
447   @retval FALSE  HMAC-MD5 data digest failed.\r
448 \r
449 **/\r
450 BOOLEAN\r
451 EFIAPI\r
452 HmacMd5Update (\r
453   IN OUT  VOID        *HmacMd5Context,\r
454   IN      CONST VOID  *Data,\r
455   IN      UINTN       DataSize\r
456   );\r
457 \r
458 /**\r
459   Completes computation of the HMAC-MD5 digest value.\r
460 \r
461   This function completes HMAC-MD5 hash computation and retrieves the digest value into\r
462   the specified memory. After this function has been called, the HMAC-MD5 context cannot\r
463   be used again.\r
464   HMAC-MD5 context should be already correctly intialized by HmacMd5Init(), and should not be\r
465   finalized by HmacMd5Final(). Behavior with invalid HMAC-MD5 context is undefined.\r
466 \r
467   If HmacMd5Context is NULL, then ASSERT().\r
468   If HashValue is NULL, then ASSERT().\r
469 \r
470   @param[in, out]  HmacMd5Context  Pointer to the HMAC-MD5 context.\r
471   @param[out]      HashValue       Pointer to a buffer that receives the HMAC-MD5 digest\r
472                                    value (16 bytes).\r
473 \r
474   @retval TRUE   HMAC-MD5 digest computation succeeded.\r
475   @retval FALSE  HMAC-MD5 digest computation failed.\r
476 \r
477 **/\r
478 BOOLEAN\r
479 EFIAPI\r
480 HmacMd5Final (\r
481   IN OUT  VOID   *HmacMd5Context,\r
482   OUT     UINT8  *HmacValue\r
483   );\r
484 \r
485 /**\r
486   Retrieves the size, in bytes, of the context buffer required for HMAC-SHA1 operations.\r
487 \r
488   @return  The size, in bytes, of the context buffer required for HMAC-SHA1 operations.\r
489 \r
490 **/\r
491 UINTN\r
492 EFIAPI\r
493 HmacSha1GetContextSize (\r
494   VOID\r
495   );\r
496 \r
497 /**\r
498   Initializes user-supplied memory pointed by HmacSha1Context as HMAC-SHA1 context for\r
499   subsequent use.\r
500 \r
501   If HmacSha1Context is NULL, then ASSERT().\r
502 \r
503   @param[out]  HmacSha1Context  Pointer to HMAC-SHA1 context being initialized.\r
504   @param[in]   Key              Pointer to the user-supplied key.\r
505   @param[in]   KeySize          Key size in bytes.\r
506 \r
507   @retval TRUE   HMAC-SHA1 context initialization succeeded.\r
508   @retval FALSE  HMAC-SHA1 context initialization failed.\r
509 \r
510 **/\r
511 BOOLEAN\r
512 EFIAPI\r
513 HmacSha1Init (\r
514   OUT  VOID         *HmacSha1Context,\r
515   IN   CONST UINT8  *Key,\r
516   IN   UINTN        KeySize\r
517   );\r
518 \r
519 /**\r
520   Makes a copy of an existing HMAC-SHA1 context.\r
521 \r
522   If HmacSha1Context is NULL, then ASSERT().\r
523   If NewHmacSha1Context is NULL, then ASSERT().\r
524 \r
525   @param[in]  HmacSha1Context     Pointer to HMAC-SHA1 context being copied.\r
526   @param[out] NewHmacSha1Context  Pointer to new HMAC-SHA1 context.\r
527 \r
528   @retval TRUE   HMAC-SHA1 context copy succeeded.\r
529   @retval FALSE  HMAC-SHA1 context copy failed.\r
530 \r
531 **/\r
532 BOOLEAN\r
533 EFIAPI\r
534 HmacSha1Duplicate (\r
535   IN   CONST VOID  *HmacSha1Context,\r
536   OUT  VOID        *NewHmacSha1Context\r
537   );\r
538 \r
539 /**\r
540   Digests the input data and updates HMAC-SHA1 context.\r
541 \r
542   This function performs HMAC-SHA1 digest on a data buffer of the specified size.\r
543   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
544   HMAC-SHA1 context should be already correctly intialized by HmacSha1Init(), and should not\r
545   be finalized by HmacSha1Final(). Behavior with invalid context is undefined.\r
546 \r
547   If HmacSha1Context is NULL, then ASSERT().\r
548 \r
549   @param[in, out]  HmacSha1Context Pointer to the HMAC-SHA1 context.\r
550   @param[in]       Data            Pointer to the buffer containing the data to be digested.\r
551   @param[in]       DataSize        Size of Data buffer in bytes.\r
552 \r
553   @retval TRUE   HMAC-SHA1 data digest succeeded.\r
554   @retval FALSE  HMAC-SHA1 data digest failed.\r
555 \r
556 **/\r
557 BOOLEAN\r
558 EFIAPI\r
559 HmacSha1Update (\r
560   IN OUT  VOID        *HmacSha1Context,\r
561   IN      CONST VOID  *Data,\r
562   IN      UINTN       DataSize\r
563   );\r
564 \r
565 /**\r
566   Completes computation of the HMAC-SHA1 digest value.\r
567 \r
568   This function completes HMAC-SHA1 hash computation and retrieves the digest value into\r
569   the specified memory. After this function has been called, the HMAC-SHA1 context cannot\r
570   be used again.\r
571   HMAC-SHA1 context should be already correctly intialized by HmacSha1Init(), and should\r
572   not be finalized by HmacSha1Final(). Behavior with invalid HMAC-SHA1 context is undefined.\r
573 \r
574   If HmacSha1Context is NULL, then ASSERT().\r
575   If HashValue is NULL, then ASSERT().\r
576 \r
577   @param[in, out]  HmacSha1Context  Pointer to the HMAC-SHA1 context.\r
578   @param[out]      HashValue        Pointer to a buffer that receives the HMAC-SHA1 digest\r
579                                     value (20 bytes).\r
580 \r
581   @retval TRUE   HMAC-SHA1 digest computation succeeded.\r
582   @retval FALSE  HMAC-SHA1 digest computation failed.\r
583 \r
584 **/\r
585 BOOLEAN\r
586 EFIAPI\r
587 HmacSha1Final (\r
588   IN OUT  VOID   *HmacSha1Context,\r
589   OUT     UINT8  *HmacValue\r
590   );\r
591 \r
592 \r
593 //=====================================================================================\r
594 //    Symmetric Cryptography Primitive\r
595 //=====================================================================================\r
596 \r
597 /**\r
598   Retrieves the size, in bytes, of the context buffer required for TDES operations.\r
599 \r
600   @return  The size, in bytes, of the context buffer required for TDES operations.\r
601 \r
602 **/\r
603 UINTN\r
604 EFIAPI\r
605 TdesGetContextSize (\r
606   VOID\r
607   );\r
608 \r
609 /**\r
610   Initializes user-supplied memory as TDES context for subsequent use.\r
611 \r
612   This function initializes user-supplied memory pointed by TdesContext as TDES context.\r
613   In addtion, it sets up all TDES key materials for subsequent encryption and decryption\r
614   operations.\r
615   There are 3 key options as follows:\r
616   KeyLength = 64,  Keying option 1: K1 == K2 == K3 (Backward compatibility with DES)\r
617   KeyLength = 128, Keying option 2: K1 != K2 and K3 = K1 (Less Security)\r
618   KeyLength = 192  Keying option 3: K1 != K2 != K3 (Strongest)\r
619 \r
620   If TdesContext is NULL, then ASSERT().\r
621   If Key is NULL, then ASSERT().\r
622   If KeyLength is not valid, then ASSERT().\r
623 \r
624   @param[out]  TdesContext  Pointer to TDES context being initialized.\r
625   @param[in]   Key          Pointer to the user-supplied TDES key.\r
626   @param[in]   KeyLength    Length of TDES key in bits.\r
627 \r
628   @retval TRUE   TDES context initialization succeeded.\r
629   @retval FALSE  TDES context initialization failed.\r
630 \r
631 **/\r
632 BOOLEAN\r
633 EFIAPI\r
634 TdesInit (\r
635   OUT  VOID         *TdesContext,\r
636   IN   CONST UINT8  *Key,\r
637   IN   UINTN        KeyLength\r
638   );\r
639 \r
640 /**\r
641   Performs TDES encryption on a data buffer of the specified size in ECB mode.\r
642 \r
643   This function performs TDES encryption on data buffer pointed by Input, of specified\r
644   size of InputSize, in ECB mode.\r
645   InputSize must be multiple of block size (8 bytes). This function does not perform\r
646   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
647   TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
648   invalid TDES context is undefined.\r
649 \r
650   If TdesContext is NULL, then ASSERT().\r
651   If Input is NULL, then ASSERT().\r
652   If InputSize is not multiple of block size (8 bytes), then ASSERT().\r
653   If Output is NULL, then ASSERT().\r
654 \r
655   @param[in]   TdesContext  Pointer to the TDES context.\r
656   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.\r
657   @param[in]   InputSize    Size of the Input buffer in bytes.\r
658   @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.\r
659 \r
660   @retval TRUE   TDES encryption succeeded.\r
661   @retval FALSE  TDES encryption failed.\r
662 \r
663 **/\r
664 BOOLEAN\r
665 EFIAPI\r
666 TdesEcbEncrypt (\r
667   IN   VOID         *TdesContext,\r
668   IN   CONST UINT8  *Input,\r
669   IN   UINTN        InputSize,\r
670   OUT  UINT8        *Output\r
671   );\r
672 \r
673 /**\r
674   Performs TDES decryption on a data buffer of the specified size in ECB mode.\r
675 \r
676   This function performs TDES decryption on data buffer pointed by Input, of specified\r
677   size of InputSize, in ECB mode.\r
678   InputSize must be multiple of block size (8 bytes). This function does not perform\r
679   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
680   TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
681   invalid TDES context is undefined.\r
682 \r
683   If TdesContext is NULL, then ASSERT().\r
684   If Input is NULL, then ASSERT().\r
685   If InputSize is not multiple of block size (8 bytes), then ASSERT().\r
686   If Output is NULL, then ASSERT().\r
687 \r
688   @param[in]   TdesContext  Pointer to the TDES context.\r
689   @param[in]   Input        Pointer to the buffer containing the data to be decrypted.\r
690   @param[in]   InputSize    Size of the Input buffer in bytes.\r
691   @param[out]  Output       Pointer to a buffer that receives the TDES decryption output.\r
692 \r
693   @retval TRUE   TDES decryption succeeded.\r
694   @retval FALSE  TDES decryption failed.\r
695 \r
696 **/\r
697 BOOLEAN\r
698 EFIAPI\r
699 TdesEcbDecrypt (\r
700   IN   VOID         *TdesContext,\r
701   IN   CONST UINT8  *Input,\r
702   IN   UINTN        InputSize,\r
703   OUT  UINT8        *Output\r
704   );\r
705 \r
706 /**\r
707   Performs TDES encryption on a data buffer of the specified size in CBC mode.\r
708 \r
709   This function performs TDES encryption on data buffer pointed by Input, of specified\r
710   size of InputSize, in CBC mode.\r
711   InputSize must be multiple of block size (8 bytes). This function does not perform\r
712   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
713   Initialization vector should be one block size (8 bytes).\r
714   TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
715   invalid TDES context is undefined.\r
716 \r
717   If TdesContext is NULL, then ASSERT().\r
718   If Input is NULL, then ASSERT().\r
719   If InputSize is not multiple of block size (8 bytes), then ASSERT().\r
720   If Ivec is NULL, then ASSERT().\r
721   If Output is NULL, then ASSERT().\r
722 \r
723   @param[in]   TdesContext  Pointer to the TDES context.\r
724   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.\r
725   @param[in]   InputSize    Size of the Input buffer in bytes.\r
726   @param[in]   Ivec         Pointer to initialization vector.\r
727   @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.\r
728 \r
729   @retval TRUE   TDES encryption succeeded.\r
730   @retval FALSE  TDES encryption failed.\r
731 \r
732 **/\r
733 BOOLEAN\r
734 EFIAPI\r
735 TdesCbcEncrypt (\r
736   IN   VOID         *TdesContext,\r
737   IN   CONST UINT8  *Input,\r
738   IN   UINTN        InputSize,\r
739   IN   CONST UINT8  *Ivec,\r
740   OUT  UINT8        *Output\r
741   );\r
742 \r
743 /**\r
744   Performs TDES decryption on a data buffer of the specified size in CBC mode.\r
745 \r
746   This function performs TDES decryption on data buffer pointed by Input, of specified\r
747   size of InputSize, in CBC mode.\r
748   InputSize must be multiple of block size (8 bytes). This function does not perform\r
749   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
750   Initialization vector should be one block size (8 bytes).\r
751   TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
752   invalid TDES context is undefined.\r
753 \r
754   If TdesContext is NULL, then ASSERT().\r
755   If Input is NULL, then ASSERT().\r
756   If InputSize is not multiple of block size (8 bytes), then ASSERT().\r
757   If Ivec is NULL, then ASSERT().\r
758   If Output is NULL, then ASSERT().\r
759 \r
760   @param[in]   TdesContext  Pointer to the TDES context.\r
761   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.\r
762   @param[in]   InputSize    Size of the Input buffer in bytes.\r
763   @param[in]   Ivec         Pointer to initialization vector.\r
764   @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.\r
765 \r
766   @retval TRUE   TDES decryption succeeded.\r
767   @retval FALSE  TDES decryption failed.\r
768 \r
769 **/\r
770 BOOLEAN\r
771 EFIAPI\r
772 TdesCbcDecrypt (\r
773   IN   VOID         *TdesContext,\r
774   IN   CONST UINT8  *Input,\r
775   IN   UINTN        InputSize,\r
776   IN   CONST UINT8  *Ivec,\r
777   OUT  UINT8        *Output\r
778   );\r
779 \r
780 /**\r
781   Retrieves the size, in bytes, of the context buffer required for AES operations.\r
782 \r
783   @return  The size, in bytes, of the context buffer required for AES operations.\r
784 \r
785 **/\r
786 UINTN\r
787 EFIAPI\r
788 AesGetContextSize (\r
789   VOID\r
790   );\r
791 \r
792 /**\r
793   Initializes user-supplied memory as AES context for subsequent use.\r
794 \r
795   This function initializes user-supplied memory pointed by AesContext as AES context.\r
796   In addtion, it sets up all AES key materials for subsequent encryption and decryption\r
797   operations.\r
798   There are 3 options for key length, 128 bits, 192 bits, and 256 bits.\r
799 \r
800   If AesContext is NULL, then ASSERT().\r
801   If Key is NULL, then ASSERT().\r
802   If KeyLength is not valid, then ASSERT().\r
803 \r
804   @param[out]  AesContext  Pointer to AES context being initialized.\r
805   @param[in]   Key         Pointer to the user-supplied AES key.\r
806   @param[in]   KeyLength   Length of AES key in bits.\r
807 \r
808   @retval TRUE   AES context initialization succeeded.\r
809   @retval FALSE  AES context initialization failed.\r
810 \r
811 **/\r
812 BOOLEAN\r
813 EFIAPI\r
814 AesInit (\r
815   OUT  VOID         *AesContext,\r
816   IN   CONST UINT8  *Key,\r
817   IN   UINTN        KeyLength\r
818   );\r
819 \r
820 /**\r
821   Performs AES encryption on a data buffer of the specified size in ECB mode.\r
822 \r
823   This function performs AES encryption on data buffer pointed by Input, of specified\r
824   size of InputSize, in ECB mode.\r
825   InputSize must be multiple of block size (16 bytes). This function does not perform\r
826   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
827   AesContext should be already correctly initialized by AesInit(). Behavior with\r
828   invalid AES context is undefined.\r
829 \r
830   If AesContext is NULL, then ASSERT().\r
831   If Input is NULL, then ASSERT().\r
832   If InputSize is not multiple of block size (16 bytes), then ASSERT().\r
833   If Output is NULL, then ASSERT().\r
834 \r
835   @param[in]   AesContext  Pointer to the AES context.\r
836   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.\r
837   @param[in]   InputSize   Size of the Input buffer in bytes.\r
838   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.\r
839 \r
840   @retval TRUE   AES encryption succeeded.\r
841   @retval FALSE  AES encryption failed.\r
842 \r
843 **/\r
844 BOOLEAN\r
845 EFIAPI\r
846 AesEcbEncrypt (\r
847   IN   VOID         *AesContext,\r
848   IN   CONST UINT8  *Input,\r
849   IN   UINTN        InputSize,\r
850   OUT  UINT8        *Output\r
851   );\r
852 \r
853 /**\r
854   Performs AES decryption on a data buffer of the specified size in ECB mode.\r
855 \r
856   This function performs AES decryption on data buffer pointed by Input, of specified\r
857   size of InputSize, in ECB mode.\r
858   InputSize must be multiple of block size (16 bytes). This function does not perform\r
859   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
860   AesContext should be already correctly initialized by AesInit(). Behavior with\r
861   invalid AES context is undefined.\r
862 \r
863   If AesContext is NULL, then ASSERT().\r
864   If Input is NULL, then ASSERT().\r
865   If InputSize is not multiple of block size (16 bytes), then ASSERT().\r
866   If Output is NULL, then ASSERT().\r
867 \r
868   @param[in]   AesContext  Pointer to the AES context.\r
869   @param[in]   Input       Pointer to the buffer containing the data to be decrypted.\r
870   @param[in]   InputSize   Size of the Input buffer in bytes.\r
871   @param[out]  Output      Pointer to a buffer that receives the AES decryption output.\r
872 \r
873   @retval TRUE   AES decryption succeeded.\r
874   @retval FALSE  AES decryption failed.\r
875 \r
876 **/\r
877 BOOLEAN\r
878 EFIAPI\r
879 AesEcbDecrypt (\r
880   IN   VOID         *AesContext,\r
881   IN   CONST UINT8  *Input,\r
882   IN   UINTN        InputSize,\r
883   OUT  UINT8        *Output\r
884   );\r
885 \r
886 /**\r
887   Performs AES encryption on a data buffer of the specified size in CBC mode.\r
888 \r
889   This function performs AES encryption on data buffer pointed by Input, of specified\r
890   size of InputSize, in CBC mode.\r
891   InputSize must be multiple of block size (16 bytes). This function does not perform\r
892   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
893   Initialization vector should be one block size (16 bytes).\r
894   AesContext should be already correctly initialized by AesInit(). Behavior with\r
895   invalid AES context is undefined.\r
896 \r
897   If AesContext is NULL, then ASSERT().\r
898   If Input is NULL, then ASSERT().\r
899   If InputSize is not multiple of block size (16 bytes), then ASSERT().\r
900   If Ivec is NULL, then ASSERT().\r
901   If Output is NULL, then ASSERT().\r
902 \r
903   @param[in]   AesContext  Pointer to the AES context.\r
904   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.\r
905   @param[in]   InputSize   Size of the Input buffer in bytes.\r
906   @param[in]   Ivec        Pointer to initialization vector.\r
907   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.\r
908 \r
909   @retval TRUE   AES encryption succeeded.\r
910   @retval FALSE  AES encryption failed.\r
911 \r
912 **/\r
913 BOOLEAN\r
914 EFIAPI\r
915 AesCbcEncrypt (\r
916   IN   VOID         *AesContext,\r
917   IN   CONST UINT8  *Input,\r
918   IN   UINTN        InputSize,\r
919   IN   CONST UINT8  *Ivec,\r
920   OUT  UINT8        *Output\r
921   );\r
922 \r
923 /**\r
924   Performs AES decryption on a data buffer of the specified size in CBC mode.\r
925 \r
926   This function performs AES decryption on data buffer pointed by Input, of specified\r
927   size of InputSize, in CBC mode.\r
928   InputSize must be multiple of block size (16 bytes). This function does not perform\r
929   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
930   Initialization vector should be one block size (16 bytes).\r
931   AesContext should be already correctly initialized by AesInit(). Behavior with\r
932   invalid AES context is undefined.\r
933 \r
934   If AesContext is NULL, then ASSERT().\r
935   If Input is NULL, then ASSERT().\r
936   If InputSize is not multiple of block size (16 bytes), then ASSERT().\r
937   If Ivec is NULL, then ASSERT().\r
938   If Output is NULL, then ASSERT().\r
939 \r
940   @param[in]   AesContext  Pointer to the AES context.\r
941   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.\r
942   @param[in]   InputSize   Size of the Input buffer in bytes.\r
943   @param[in]   Ivec        Pointer to initialization vector.\r
944   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.\r
945 \r
946   @retval TRUE   AES decryption succeeded.\r
947   @retval FALSE  AES decryption failed.\r
948 \r
949 **/\r
950 BOOLEAN\r
951 EFIAPI\r
952 AesCbcDecrypt (\r
953   IN   VOID         *AesContext,\r
954   IN   CONST UINT8  *Input,\r
955   IN   UINTN        InputSize,\r
956   IN   CONST UINT8  *Ivec,\r
957   OUT  UINT8        *Output\r
958   );\r
959 \r
960 /**\r
961   Retrieves the size, in bytes, of the context buffer required for ARC4 operations.\r
962 \r
963   @return  The size, in bytes, of the context buffer required for ARC4 operations.\r
964 \r
965 **/\r
966 UINTN\r
967 EFIAPI\r
968 Arc4GetContextSize (\r
969   VOID\r
970   );\r
971 \r
972 /**\r
973   Initializes user-supplied memory as ARC4 context for subsequent use.\r
974 \r
975   This function initializes user-supplied memory pointed by Arc4Context as ARC4 context.\r
976   In addtion, it sets up all ARC4 key materials for subsequent encryption and decryption\r
977   operations.\r
978 \r
979   If Arc4Context is NULL, then ASSERT().\r
980   If Key is NULL, then ASSERT().\r
981   If KeySize does not in the range of [5, 256] bytes, then ASSERT().\r
982 \r
983   @param[out]  Arc4Context  Pointer to ARC4 context being initialized.\r
984   @param[in]   Key          Pointer to the user-supplied ARC4 key.\r
985   @param[in]   KeySize      Size of ARC4 key in bytes.\r
986 \r
987   @retval TRUE   ARC4 context initialization succeeded.\r
988   @retval FALSE  ARC4 context initialization failed.\r
989 \r
990 **/\r
991 BOOLEAN\r
992 EFIAPI\r
993 Arc4Init (\r
994   OUT  VOID         *Arc4Context,\r
995   IN   CONST UINT8  *Key,\r
996   IN   UINTN        KeySize\r
997   );\r
998 \r
999 /**\r
1000   Performs ARC4 encryption on a data buffer of the specified size.\r
1001 \r
1002   This function performs ARC4 encryption on data buffer pointed by Input, of specified\r
1003   size of InputSize.\r
1004   Arc4Context should be already correctly initialized by Arc4Init(). Behavior with\r
1005   invalid ARC4 context is undefined.\r
1006 \r
1007   If Arc4Context is NULL, then ASSERT().\r
1008   If Input is NULL, then ASSERT().\r
1009   If Output is NULL, then ASSERT().\r
1010 \r
1011   @param[in]   Arc4Context  Pointer to the ARC4 context.\r
1012   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.\r
1013   @param[in]   InputSize    Size of the Input buffer in bytes.\r
1014   @param[out]  Output       Pointer to a buffer that receives the ARC4 encryption output.\r
1015 \r
1016   @retval TRUE   ARC4 encryption succeeded.\r
1017   @retval FALSE  ARC4 encryption failed.\r
1018 \r
1019 **/\r
1020 BOOLEAN\r
1021 EFIAPI\r
1022 Arc4Encrypt (\r
1023   IN OUT  VOID         *Arc4Context,\r
1024   IN      CONST UINT8  *Input,\r
1025   IN      UINTN        InputSize,\r
1026   OUT     UINT8        *Output\r
1027   );\r
1028 \r
1029 /**\r
1030   Performs ARC4 decryption on a data buffer of the specified size.\r
1031 \r
1032   This function performs ARC4 decryption on data buffer pointed by Input, of specified\r
1033   size of InputSize.\r
1034   Arc4Context should be already correctly initialized by Arc4Init(). Behavior with\r
1035   invalid ARC4 context is undefined.\r
1036 \r
1037   If Arc4Context is NULL, then ASSERT().\r
1038   If Input is NULL, then ASSERT().\r
1039   If Output is NULL, then ASSERT().\r
1040 \r
1041   @param[in]   Arc4Context  Pointer to the ARC4 context.\r
1042   @param[in]   Input        Pointer to the buffer containing the data to be decrypted.\r
1043   @param[in]   InputSize    Size of the Input buffer in bytes.\r
1044   @param[out]  Output       Pointer to a buffer that receives the ARC4 decryption output.\r
1045 \r
1046   @retval TRUE   ARC4 decryption succeeded.\r
1047   @retval FALSE  ARC4 decryption failed.\r
1048 \r
1049 **/\r
1050 BOOLEAN\r
1051 EFIAPI\r
1052 Arc4Decrypt (\r
1053   IN OUT  VOID   *Arc4Context,\r
1054   IN      UINT8  *Input,\r
1055   IN      UINTN  InputSize,\r
1056   OUT     UINT8  *Output\r
1057   );\r
1058 \r
1059 /**\r
1060   Resets the ARC4 context to the initial state.\r
1061 \r
1062   The function resets the ARC4 context to the state it had immediately after the\r
1063   ARC4Init() function call.\r
1064   Contrary to ARC4Init(), Arc4Reset() requires no secret key as input, but ARC4 context\r
1065   should be already correctly initialized by ARC4Init().\r
1066 \r
1067   If Arc4Context is NULL, then ASSERT().\r
1068 \r
1069   @param[in, out]  Arc4Context  Pointer to the ARC4 context.\r
1070 \r
1071   @retval TRUE   ARC4 reset succeeded.\r
1072   @retval FALSE  ARC4 reset failed.\r
1073 \r
1074 **/\r
1075 BOOLEAN\r
1076 EFIAPI\r
1077 Arc4Reset (\r
1078   IN OUT  VOID  *Arc4Context\r
1079   );\r
1080 \r
1081 //=====================================================================================\r
1082 //    Asymmetric Cryptography Primitive\r
1083 //=====================================================================================\r
1084 \r
1085 /**\r
1086   Allocates and initializes one RSA context for subsequent use.\r
1087 \r
1088   @return  Pointer to the RSA context that has been initialized.\r
1089            If the allocations fails, RsaNew() returns NULL.\r
1090 \r
1091 **/\r
1092 VOID *\r
1093 EFIAPI\r
1094 RsaNew (\r
1095   VOID\r
1096   );\r
1097 \r
1098 /**\r
1099   Release the specified RSA context.\r
1100 \r
1101   If RsaContext is NULL, then ASSERT().\r
1102 \r
1103   @param[in]  RsaContext  Pointer to the RSA context to be released.\r
1104 \r
1105 **/\r
1106 VOID\r
1107 EFIAPI\r
1108 RsaFree (\r
1109   IN  VOID  *RsaContext\r
1110   );\r
1111 \r
1112 /**\r
1113   Sets the tag-designated key component into the established RSA context.\r
1114 \r
1115   This function sets the tag-designated RSA key component into the established\r
1116   RSA context from the user-specified non-negative integer (octet string format\r
1117   represented in RSA PKCS#1).\r
1118   If BigNumber is NULL, then the specified key componenet in RSA context is cleared.\r
1119 \r
1120   If RsaContext is NULL, then ASSERT().\r
1121 \r
1122   @param[in, out]  RsaContext  Pointer to RSA context being set.\r
1123   @param[in]       KeyTag      Tag of RSA key component being set.\r
1124   @param[in]       BigNumber   Pointer to octet integer buffer.\r
1125                                If NULL, then the specified key componenet in RSA\r
1126                                context is cleared.\r
1127   @param[in]       BnSize      Size of big number buffer in bytes.\r
1128                                If BigNumber is NULL, then it is ignored.\r
1129 \r
1130   @retval  TRUE   RSA key component was set successfully.\r
1131   @retval  FALSE  Invalid RSA key component tag.\r
1132 \r
1133 **/\r
1134 BOOLEAN\r
1135 EFIAPI\r
1136 RsaSetKey (\r
1137   IN OUT  VOID         *RsaContext,\r
1138   IN      RSA_KEY_TAG  KeyTag,\r
1139   IN      CONST UINT8  *BigNumber,\r
1140   IN      UINTN        BnSize\r
1141   );\r
1142 \r
1143 /**\r
1144   Gets the tag-designated RSA key component from the established RSA context.\r
1145 \r
1146   This function retrieves the tag-designated RSA key component from the\r
1147   established RSA context as a non-negative integer (octet string format\r
1148   represented in RSA PKCS#1).\r
1149   If specified key component has not been set or has been cleared, then returned\r
1150   BnSize is set to 0.\r
1151   If the BigNumber buffer is too small to hold the contents of the key, FALSE\r
1152   is returned and BnSize is set to the required buffer size to obtain the key.\r
1153 \r
1154   If RsaContext is NULL, then ASSERT().\r
1155   If BnSize is NULL, then ASSERT().\r
1156   If BnSize is large enough but BigNumber is NULL, then ASSERT().\r
1157 \r
1158   @param[in, out]  RsaContext  Pointer to RSA context being set.\r
1159   @param[in]       KeyTag      Tag of RSA key component being set.\r
1160   @param[out]      BigNumber   Pointer to octet integer buffer.\r
1161   @param[in, out]  BnSize      On input, the size of big number buffer in bytes.\r
1162                                On output, the size of data returned in big number buffer in bytes.\r
1163 \r
1164   @retval  TRUE   RSA key component was retrieved successfully.\r
1165   @retval  FALSE  Invalid RSA key component tag.\r
1166   @retval  FALSE  BnSize is too small.\r
1167 \r
1168 **/\r
1169 BOOLEAN\r
1170 EFIAPI\r
1171 RsaGetKey (\r
1172   IN OUT  VOID         *RsaContext,\r
1173   IN      RSA_KEY_TAG  KeyTag,\r
1174   OUT     UINT8        *BigNumber,\r
1175   IN OUT  UINTN        *BnSize\r
1176   );\r
1177 \r
1178 /**\r
1179   Generates RSA key components.\r
1180 \r
1181   This function generates RSA key components. It takes RSA public exponent E and\r
1182   length in bits of RSA modulus N as input, and generates all key components.\r
1183   If PublicExponent is NULL, the default RSA public exponent (0x10001) will be used.\r
1184 \r
1185   Before this function can be invoked, pseudorandom number generator must be correctly\r
1186   initialized by RandomSeed().\r
1187 \r
1188   If RsaContext is NULL, then ASSERT().\r
1189 \r
1190   @param[in, out]  RsaContext           Pointer to RSA context being set.\r
1191   @param[in]       ModulusLength        Length of RSA modulus N in bits.\r
1192   @param[in]       PublicExponent       Pointer to RSA public exponent.\r
1193   @param[in]       PublicExponentSize   Size of RSA public exponent buffer in bytes. \r
1194 \r
1195   @retval  TRUE   RSA key component was generated successfully.\r
1196   @retval  FALSE  Invalid RSA key component tag.\r
1197 \r
1198 **/\r
1199 BOOLEAN\r
1200 EFIAPI\r
1201 RsaGenerateKey (\r
1202   IN OUT  VOID         *RsaContext,\r
1203   IN      UINTN        ModulusLength,\r
1204   IN      CONST UINT8  *PublicExponent,\r
1205   IN      UINTN        PublicExponentSize\r
1206   );\r
1207 \r
1208 /**\r
1209   Validates key components of RSA context.\r
1210 \r
1211   This function validates key compoents of RSA context in following aspects:\r
1212   - Whether p is a prime\r
1213   - Whether q is a prime\r
1214   - Whether n = p * q\r
1215   - Whether d*e = 1  mod lcm(p-1,q-1)\r
1216 \r
1217   If RsaContext is NULL, then ASSERT().\r
1218 \r
1219   @param[in]  RsaContext  Pointer to RSA context to check.\r
1220 \r
1221   @retval  TRUE   RSA key components are valid.\r
1222   @retval  FALSE  RSA key components are not valid.\r
1223 \r
1224 **/\r
1225 BOOLEAN\r
1226 EFIAPI\r
1227 RsaCheckKey (\r
1228   IN  VOID  *RsaContext\r
1229   );\r
1230 \r
1231 /**\r
1232   Carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme.\r
1233 \r
1234   This function carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme defined in\r
1235   RSA PKCS#1.\r
1236   If the Signature buffer is too small to hold the contents of signature, FALSE\r
1237   is returned and SigSize is set to the required buffer size to obtain the signature.\r
1238 \r
1239   If RsaContext is NULL, then ASSERT().\r
1240   If MessageHash is NULL, then ASSERT().\r
1241   If HashSize is not equal to the size of MD5, SHA-1, SHA-256, SHA-224, SHA-512 or SHA-384 digest, then ASSERT().\r
1242   If SigSize is large enough but Signature is NULL, then ASSERT().\r
1243 \r
1244   @param[in]      RsaContext   Pointer to RSA context for signature generation.\r
1245   @param[in]      MessageHash  Pointer to octet message hash to be signed.\r
1246   @param[in]      HashSize     Size of the message hash in bytes.\r
1247   @param[out]     Signature    Pointer to buffer to receive RSA PKCS1-v1_5 signature.\r
1248   @param[in, out] SigSize      On input, the size of Signature buffer in bytes.\r
1249                               On output, the size of data returned in Signature buffer in bytes.\r
1250 \r
1251   @retval  TRUE   Signature successfully generated in PKCS1-v1_5.\r
1252   @retval  FALSE  Signature generation failed.\r
1253   @retval  FALSE  SigSize is too small.\r
1254 \r
1255 **/\r
1256 BOOLEAN\r
1257 EFIAPI\r
1258 RsaPkcs1Sign (\r
1259   IN      VOID         *RsaContext,\r
1260   IN      CONST UINT8  *MessageHash,\r
1261   IN      UINTN        HashSize,\r
1262   OUT     UINT8        *Signature,\r
1263   IN OUT  UINTN        *SigSize\r
1264   );\r
1265 \r
1266 /**\r
1267   Verifies the RSA-SSA signature with EMSA-PKCS1-v1_5 encoding scheme defined in\r
1268   RSA PKCS#1.\r
1269 \r
1270   If RsaContext is NULL, then ASSERT().\r
1271   If MessageHash is NULL, then ASSERT().\r
1272   If Signature is NULL, then ASSERT().\r
1273   If HashSize is not equal to the size of MD5, SHA-1, SHA-256, SHA-224, SHA-512 or SHA-384 digest, then ASSERT().\r
1274 \r
1275   @param[in]  RsaContext   Pointer to RSA context for signature verification.\r
1276   @param[in]  MessageHash  Pointer to octet message hash to be checked.\r
1277   @param[in]  HashSize     Size of the message hash in bytes.\r
1278   @param[in]  Signature    Pointer to RSA PKCS1-v1_5 signature to be verified.\r
1279   @param[in]  SigSize      Size of signature in bytes.\r
1280 \r
1281   @retval  TRUE   Valid signature encoded in PKCS1-v1_5.\r
1282   @retval  FALSE  Invalid signature or invalid RSA context.\r
1283 \r
1284 **/\r
1285 BOOLEAN\r
1286 EFIAPI\r
1287 RsaPkcs1Verify (\r
1288   IN  VOID         *RsaContext,\r
1289   IN  CONST UINT8  *MessageHash,\r
1290   IN  UINTN        HashSize,\r
1291   IN  UINT8        *Signature,\r
1292   IN  UINTN        SigSize\r
1293   );\r
1294 \r
1295 /**\r
1296   Verifies the validility of a PKCS#7 signed data as described in "PKCS #7: Cryptographic\r
1297   Message Syntax Standard".\r
1298 \r
1299   If P7Data is NULL, then ASSERT().\r
1300 \r
1301   @param[in]  P7Data       Pointer to the PKCS#7 message to verify.\r
1302   @param[in]  P7Size       Size of the PKCS#7 message in bytes.\r
1303   @param[in]  TrustedCert  Pointer to a trusted/root certificate encoded in DER, which\r
1304                            is used for certificate chain verification.\r
1305   @param[in]  CertSize     Size of the trusted certificate in bytes.\r
1306   @param[in]  InData       Pointer to the content to be verified.\r
1307   @param[in]  DataSize     Size of InData in bytes.\r
1308 \r
1309   @retval  TRUE  The specified PKCS#7 signed data is valid.\r
1310   @retval  FALSE Invalid PKCS#7 signed data.\r
1311 \r
1312 **/\r
1313 BOOLEAN\r
1314 EFIAPI\r
1315 Pkcs7Verify (\r
1316   IN  CONST UINT8  *P7Data,\r
1317   IN  UINTN        P7Size,\r
1318   IN  CONST UINT8  *TrustedCert,\r
1319   IN  UINTN        CertSize,\r
1320   IN  CONST UINT8  *InData,\r
1321   IN  UINTN        DataSize\r
1322   );\r
1323 \r
1324 //=====================================================================================\r
1325 //    DH Key Exchange Primitive\r
1326 //=====================================================================================\r
1327 \r
1328 /**\r
1329   Allocates and Initializes one Diffie-Hellman Context for subsequent use.\r
1330 \r
1331   @return  Pointer to the Diffie-Hellman Context that has been initialized.\r
1332            If the allocations fails, DhNew() returns NULL.\r
1333 \r
1334 **/\r
1335 VOID *\r
1336 EFIAPI\r
1337 DhNew (\r
1338   VOID\r
1339   );\r
1340 \r
1341 /**\r
1342   Release the specified DH context.\r
1343 \r
1344   If DhContext is NULL, then ASSERT().\r
1345 \r
1346   @param[in]  DhContext  Pointer to the DH context to be released.\r
1347 \r
1348 **/\r
1349 VOID\r
1350 EFIAPI\r
1351 DhFree (\r
1352   IN  VOID  *DhContext\r
1353   );\r
1354 \r
1355 /**\r
1356   Generates DH parameter.\r
1357 \r
1358   Given generator g, and length of prime number p in bits, this function generates p,\r
1359   and sets DH context according to value of g and p.\r
1360   \r
1361   Before this function can be invoked, pseudorandom number generator must be correctly\r
1362   initialized by RandomSeed().\r
1363 \r
1364   If DhContext is NULL, then ASSERT().\r
1365   If Prime is NULL, then ASSERT().\r
1366 \r
1367   @param[in, out]  DhContext    Pointer to the DH context.\r
1368   @param[in]       Generator    Value of generator.\r
1369   @param[in]       PrimeLength  Length in bits of prime to be generated.\r
1370   @param[out]      Prime        Pointer to the buffer to receive the generated prime number.\r
1371 \r
1372   @retval TRUE   DH pamameter generation succeeded.\r
1373   @retval FALSE  Value of Generator is not supported.\r
1374   @retval FALSE  PRNG fails to generate random prime number with PrimeLength.\r
1375 \r
1376 **/\r
1377 BOOLEAN\r
1378 EFIAPI\r
1379 DhGenerateParameter (\r
1380   IN OUT  VOID   *DhContext,\r
1381   IN      UINTN  Generator,\r
1382   IN      UINTN  PrimeLength,\r
1383   OUT     UINT8  *Prime\r
1384   );\r
1385 \r
1386 /**\r
1387   Sets generator and prime parameters for DH.\r
1388 \r
1389   Given generator g, and prime number p, this function and sets DH\r
1390   context accordingly.\r
1391 \r
1392   If DhContext is NULL, then ASSERT().\r
1393   If Prime is NULL, then ASSERT().\r
1394 \r
1395   @param[in, out]  DhContext    Pointer to the DH context.\r
1396   @param[in]       Generator    Value of generator.\r
1397   @param[in]       PrimeLength  Length in bits of prime to be generated.\r
1398   @param[in]       Prime        Pointer to the prime number.\r
1399 \r
1400   @retval TRUE   DH pamameter setting succeeded.\r
1401   @retval FALSE  Value of Generator is not supported.\r
1402   @retval FALSE  Value of Generator is not suitable for the Prime.\r
1403   @retval FALSE  Value of Prime is not a prime number.\r
1404   @retval FALSE  Value of Prime is not a safe prime number.\r
1405 \r
1406 **/\r
1407 BOOLEAN\r
1408 EFIAPI\r
1409 DhSetParameter (\r
1410   IN OUT  VOID         *DhContext,\r
1411   IN      UINTN        Generator,\r
1412   IN      UINTN        PrimeLength,\r
1413   IN      CONST UINT8  *Prime\r
1414   );\r
1415 \r
1416 /**\r
1417   Generates DH public key.\r
1418 \r
1419   This function generates random secret exponent, and computes the public key, which is \r
1420   returned via parameter PublicKey and PublicKeySize. DH context is updated accordingly.\r
1421   If the PublicKey buffer is too small to hold the public key, FALSE is returned and\r
1422   PublicKeySize is set to the required buffer size to obtain the public key.\r
1423 \r
1424   If DhContext is NULL, then ASSERT().\r
1425   If PublicKeySize is NULL, then ASSERT().\r
1426   If PublicKeySize is large enough but PublicKey is NULL, then ASSERT().\r
1427 \r
1428   @param[in, out]  DhContext      Pointer to the DH context.\r
1429   @param[out]      PublicKey      Pointer to the buffer to receive generated public key.\r
1430   @param[in, out]  PublicKeySize  On input, the size of PublicKey buffer in bytes.\r
1431                                  On output, the size of data returned in PublicKey buffer in bytes.\r
1432 \r
1433   @retval TRUE   DH public key generation succeeded.\r
1434   @retval FALSE  DH public key generation failed.\r
1435   @retval FALSE  PublicKeySize is not large enough.\r
1436 \r
1437 **/\r
1438 BOOLEAN\r
1439 EFIAPI\r
1440 DhGenerateKey (\r
1441   IN OUT  VOID   *DhContext,\r
1442   OUT     UINT8  *PublicKey,\r
1443   IN OUT  UINTN  *PublicKeySize\r
1444   );\r
1445 \r
1446 /**\r
1447   Computes exchanged common key.\r
1448 \r
1449   Given peer's public key, this function computes the exchanged common key, based on its own\r
1450   context including value of prime modulus and random secret exponent. \r
1451 \r
1452   If DhContext is NULL, then ASSERT().\r
1453   If PeerPublicKey is NULL, then ASSERT().\r
1454   If KeySize is NULL, then ASSERT().\r
1455   If KeySize is large enough but Key is NULL, then ASSERT().\r
1456 \r
1457   @param[in, out]  DhContext          Pointer to the DH context.\r
1458   @param[in]       PeerPublicKey      Pointer to the peer's public key.\r
1459   @param[in]       PeerPublicKeySize  Size of peer's public key in bytes.\r
1460   @param[out]      Key                Pointer to the buffer to receive generated key.\r
1461   @param[in, out]  KeySize            On input, the size of Key buffer in bytes.\r
1462                                      On output, the size of data returned in Key buffer in bytes.\r
1463 \r
1464   @retval TRUE   DH exchanged key generation succeeded.\r
1465   @retval FALSE  DH exchanged key generation failed.\r
1466   @retval FALSE  KeySize is not large enough.\r
1467 \r
1468 **/\r
1469 BOOLEAN\r
1470 EFIAPI\r
1471 DhComputeKey (\r
1472   IN OUT  VOID         *DhContext,\r
1473   IN      CONST UINT8  *PeerPublicKey,\r
1474   IN      UINTN        PeerPublicKeySize,\r
1475   OUT     UINT8        *Key,\r
1476   IN OUT  UINTN        *KeySize\r
1477   );\r
1478 \r
1479 //=====================================================================================\r
1480 //    Pseudo-Random Generation Primitive\r
1481 //=====================================================================================\r
1482 \r
1483 /**\r
1484   Sets up the seed value for the pseudorandom number generator.\r
1485 \r
1486   This function sets up the seed value for the pseudorandom number generator.\r
1487   If Seed is not NULL, then the seed passed in is used.\r
1488   If Seed is NULL, then default seed is used.\r
1489 \r
1490   @param[in]  Seed      Pointer to seed value.\r
1491                         If NULL, default seed is used.\r
1492   @param[in]  SeedSize  Size of seed value.\r
1493                         If Seed is NULL, this parameter is ignored.\r
1494 \r
1495   @retval TRUE   Pseudorandom number generator has enough entropy for random generation.\r
1496   @retval FALSE  Pseudorandom number generator does not have enough entropy for random generation.\r
1497 \r
1498 **/\r
1499 BOOLEAN\r
1500 EFIAPI\r
1501 RandomSeed (\r
1502   IN  CONST  UINT8  *Seed  OPTIONAL,\r
1503   IN  UINTN         SeedSize\r
1504   );\r
1505 \r
1506 /**\r
1507   Generates a pseudorandom byte stream of the specified size.\r
1508 \r
1509   If Output is NULL, then ASSERT().\r
1510 \r
1511   @param[out]  Output  Pointer to buffer to receive random value.\r
1512   @param[in]   Size    Size of randome bytes to generate.\r
1513 \r
1514   @retval TRUE   Pseudorandom byte stream generated successfully.\r
1515   @retval FALSE  Pseudorandom number generator fails to generate due to lack of entropy.\r
1516 \r
1517 **/\r
1518 BOOLEAN\r
1519 EFIAPI\r
1520 RandomBytes (\r
1521   OUT  UINT8  *Output,\r
1522   IN   UINTN  Size\r
1523   );\r
1524 \r
1525 #endif // __BASE_CRYPT_LIB_H__\r