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