[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 - 2012, 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
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   If this interface is not supported, then return zero.\r
73 \r
74   @return  The size, in bytes, of the context buffer required for MD4 hash operations.\r
75   @retval  0   This interface is not supported.\r
76 \r
77 **/\r
78 UINTN\r
80 Md4GetContextSize (\r
81   VOID\r
82   );\r
83 \r
84 /**\r
85   Initializes user-supplied memory pointed by Md4Context as MD4 hash context for\r
86   subsequent use.\r
87 \r
88   If Md4Context is NULL, then return FALSE.\r
89   If this interface is not supported, then return FALSE.\r
90 \r
91   @param[out]  Md4Context  Pointer to MD4 context being initialized.\r
92 \r
93   @retval TRUE   MD4 context initialization succeeded.\r
94   @retval FALSE  MD4 context initialization failed.\r
95   @retval FALSE  This interface is not supported.\r
96 \r
97 **/\r
100 Md4Init (\r
101   OUT  VOID  *Md4Context\r
102   );\r
103 \r
104 /**\r
105   Makes a copy of an existing MD4 context.\r
106 \r
107   If Md4Context is NULL, then return FALSE.\r
108   If NewMd4Context is NULL, then return FALSE.\r
109   If this interface is not supported, then return FALSE.\r
110 \r
111   @param[in]  Md4Context     Pointer to MD4 context being copied.\r
112   @param[out] NewMd4Context  Pointer to new MD4 context.\r
113 \r
114   @retval TRUE   MD4 context copy succeeded.\r
115   @retval FALSE  MD4 context copy failed.\r
116   @retval FALSE  This interface is not supported.\r
117 \r
118 **/\r
120 EFIAPI\r
121 Md4Duplicate (\r
122   IN   CONST VOID  *Md4Context,\r
123   OUT  VOID        *NewMd4Context\r
124   );\r
125 \r
126 /**\r
127   Digests the input data and updates MD4 context.\r
128 \r
129   This function performs MD4 digest on a data buffer of the specified size.\r
130   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
131   MD4 context should be already correctly intialized by Md4Init(), and should not be finalized\r
132   by Md4Final(). Behavior with invalid context is undefined.\r
133 \r
134   If Md4Context is NULL, then return FALSE.\r
135   If this interface is not supported, then return FALSE.\r
136 \r
137   @param[in, out]  Md4Context  Pointer to the MD4 context.\r
138   @param[in]       Data        Pointer to the buffer containing the data to be hashed.\r
139   @param[in]       DataSize    Size of Data buffer in bytes.\r
140 \r
141   @retval TRUE   MD4 data digest succeeded.\r
142   @retval FALSE  MD4 data digest failed.\r
143   @retval FALSE  This interface is not supported.\r
144 \r
145 **/\r
147 EFIAPI\r
148 Md4Update (\r
149   IN OUT  VOID        *Md4Context,\r
150   IN      CONST VOID  *Data,\r
151   IN      UINTN       DataSize\r
152   );\r
153 \r
154 /**\r
155   Completes computation of the MD4 digest value.\r
156 \r
157   This function completes MD4 hash computation and retrieves the digest value into\r
158   the specified memory. After this function has been called, the MD4 context cannot\r
159   be used again.\r
160   MD4 context should be already correctly intialized by Md4Init(), and should not be\r
161   finalized by Md4Final(). Behavior with invalid MD4 context is undefined.\r
162 \r
163   If Md4Context is NULL, then return FALSE.\r
164   If HashValue is NULL, then return FALSE.\r
165   If this interface is not supported, then return FALSE.\r
166 \r
167   @param[in, out]  Md4Context  Pointer to the MD4 context.\r
168   @param[out]      HashValue   Pointer to a buffer that receives the MD4 digest\r
169                                value (16 bytes).\r
170 \r
171   @retval TRUE   MD4 digest computation succeeded.\r
172   @retval FALSE  MD4 digest computation failed.\r
173   @retval FALSE  This interface is not supported.\r
174 \r
175 **/\r
177 EFIAPI\r
178 Md4Final (\r
179   IN OUT  VOID   *Md4Context,\r
180   OUT     UINT8  *HashValue\r
181   );\r
182 \r
183 /**\r
184   Retrieves the size, in bytes, of the context buffer required for MD5 hash operations.\r
185 \r
186   If this interface is not supported, then return zero.\r
187 \r
188   @return  The size, in bytes, of the context buffer required for MD5 hash operations.\r
189   @retval  0   This interface is not supported.\r
190 \r
191 **/\r
192 UINTN\r
193 EFIAPI\r
194 Md5GetContextSize (\r
195   VOID\r
196   );\r
197 \r
198 /**\r
199   Initializes user-supplied memory pointed by Md5Context as MD5 hash context for\r
200   subsequent use.\r
201 \r
202   If Md5Context is NULL, then return FALSE.\r
203   If this interface is not supported, then return FALSE.\r
204 \r
205   @param[out]  Md5Context  Pointer to MD5 context being initialized.\r
206 \r
207   @retval TRUE   MD5 context initialization succeeded.\r
208   @retval FALSE  MD5 context initialization failed.\r
209   @retval FALSE  This interface is not supported.\r
210 \r
211 **/\r
213 EFIAPI\r
214 Md5Init (\r
215   OUT  VOID  *Md5Context\r
216   );\r
217 \r
218 /**\r
219   Makes a copy of an existing MD5 context.\r
220 \r
221   If Md5Context is NULL, then return FALSE.\r
222   If NewMd5Context is NULL, then return FALSE.\r
223   If this interface is not supported, then return FALSE.\r
224 \r
225   @param[in]  Md5Context     Pointer to MD5 context being copied.\r
226   @param[out] NewMd5Context  Pointer to new MD5 context.\r
227 \r
228   @retval TRUE   MD5 context copy succeeded.\r
229   @retval FALSE  MD5 context copy failed.\r
230   @retval FALSE  This interface is not supported.\r
231 \r
232 **/\r
234 EFIAPI\r
235 Md5Duplicate (\r
236   IN   CONST VOID  *Md5Context,\r
237   OUT  VOID        *NewMd5Context\r
238   );\r
239 \r
240 /**\r
241   Digests the input data and updates MD5 context.\r
242 \r
243   This function performs MD5 digest on a data buffer of the specified size.\r
244   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
245   MD5 context should be already correctly intialized by Md5Init(), and should not be finalized\r
246   by Md5Final(). Behavior with invalid context is undefined.\r
247 \r
248   If Md5Context is NULL, then return FALSE.\r
249   If this interface is not supported, then return FALSE.\r
250 \r
251   @param[in, out]  Md5Context  Pointer to the MD5 context.\r
252   @param[in]       Data        Pointer to the buffer containing the data to be hashed.\r
253   @param[in]       DataSize    Size of Data buffer in bytes.\r
254 \r
255   @retval TRUE   MD5 data digest succeeded.\r
256   @retval FALSE  MD5 data digest failed.\r
257   @retval FALSE  This interface is not supported.\r
258 \r
259 **/\r
261 EFIAPI\r
262 Md5Update (\r
263   IN OUT  VOID        *Md5Context,\r
264   IN      CONST VOID  *Data,\r
265   IN      UINTN       DataSize\r
266   );\r
267 \r
268 /**\r
269   Completes computation of the MD5 digest value.\r
270 \r
271   This function completes MD5 hash computation and retrieves the digest value into\r
272   the specified memory. After this function has been called, the MD5 context cannot\r
273   be used again.\r
274   MD5 context should be already correctly intialized by Md5Init(), and should not be\r
275   finalized by Md5Final(). Behavior with invalid MD5 context is undefined.\r
276 \r
277   If Md5Context is NULL, then return FALSE.\r
278   If HashValue is NULL, then return FALSE.\r
279   If this interface is not supported, then return FALSE.\r
280 \r
281   @param[in, out]  Md5Context  Pointer to the MD5 context.\r
282   @param[out]      HashValue   Pointer to a buffer that receives the MD5 digest\r
283                                value (16 bytes).\r
284 \r
285   @retval TRUE   MD5 digest computation succeeded.\r
286   @retval FALSE  MD5 digest computation failed.\r
287   @retval FALSE  This interface is not supported.\r
288 \r
289 **/\r
291 EFIAPI\r
292 Md5Final (\r
293   IN OUT  VOID   *Md5Context,\r
294   OUT     UINT8  *HashValue\r
295   );\r
296 \r
297 /**\r
298   Retrieves the size, in bytes, of the context buffer required for SHA-1 hash operations.\r
299 \r
300   If this interface is not supported, then return zero.\r
301 \r
302   @return  The size, in bytes, of the context buffer required for SHA-1 hash operations.\r
303   @retval  0   This interface is not supported.\r
304 \r
305 **/\r
306 UINTN\r
307 EFIAPI\r
308 Sha1GetContextSize (\r
309   VOID\r
310   );\r
311 \r
312 /**\r
313   Initializes user-supplied memory pointed by Sha1Context as SHA-1 hash context for\r
314   subsequent use.\r
315 \r
316   If Sha1Context is NULL, then return FALSE.\r
317   If this interface is not supported, then return FALSE.\r
318 \r
319   @param[out]  Sha1Context  Pointer to SHA-1 context being initialized.\r
320 \r
321   @retval TRUE   SHA-1 context initialization succeeded.\r
322   @retval FALSE  SHA-1 context initialization failed.\r
323   @retval FALSE  This interface is not supported.\r
324 \r
325 **/\r
327 EFIAPI\r
328 Sha1Init (\r
329   OUT  VOID  *Sha1Context\r
330   );\r
331 \r
332 /**\r
333   Makes a copy of an existing SHA-1 context.\r
334 \r
335   If Sha1Context is NULL, then return FALSE.\r
336   If NewSha1Context is NULL, then return FALSE.\r
337   If this interface is not supported, then return FALSE.\r
338 \r
339   @param[in]  Sha1Context     Pointer to SHA-1 context being copied.\r
340   @param[out] NewSha1Context  Pointer to new SHA-1 context.\r
341 \r
342   @retval TRUE   SHA-1 context copy succeeded.\r
343   @retval FALSE  SHA-1 context copy failed.\r
344   @retval FALSE  This interface is not supported.\r
345 \r
346 **/\r
348 EFIAPI\r
349 Sha1Duplicate (\r
350   IN   CONST VOID  *Sha1Context,\r
351   OUT  VOID        *NewSha1Context\r
352   );\r
353 \r
354 /**\r
355   Digests the input data and updates SHA-1 context.\r
356 \r
357   This function performs SHA-1 digest on a data buffer of the specified size.\r
358   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
359   SHA-1 context should be already correctly intialized by Sha1Init(), and should not be finalized\r
360   by Sha1Final(). Behavior with invalid context is undefined.\r
361 \r
362   If Sha1Context is NULL, then return FALSE.\r
363   If this interface is not supported, then return FALSE.\r
364 \r
365   @param[in, out]  Sha1Context  Pointer to the SHA-1 context.\r
366   @param[in]       Data         Pointer to the buffer containing the data to be hashed.\r
367   @param[in]       DataSize     Size of Data buffer in bytes.\r
368 \r
369   @retval TRUE   SHA-1 data digest succeeded.\r
370   @retval FALSE  SHA-1 data digest failed.\r
371   @retval FALSE  This interface is not supported.\r
372 \r
373 **/\r
375 EFIAPI\r
376 Sha1Update (\r
377   IN OUT  VOID        *Sha1Context,\r
378   IN      CONST VOID  *Data,\r
379   IN      UINTN       DataSize\r
380   );\r
381 \r
382 /**\r
383   Completes computation of the SHA-1 digest value.\r
384 \r
385   This function completes SHA-1 hash computation and retrieves the digest value into\r
386   the specified memory. After this function has been called, the SHA-1 context cannot\r
387   be used again.\r
388   SHA-1 context should be already correctly intialized by Sha1Init(), and should not be\r
389   finalized by Sha1Final(). Behavior with invalid SHA-1 context is undefined.\r
390 \r
391   If Sha1Context is NULL, then return FALSE.\r
392   If HashValue is NULL, then return FALSE.\r
393   If this interface is not supported, then return FALSE.\r
394 \r
395   @param[in, out]  Sha1Context  Pointer to the SHA-1 context.\r
396   @param[out]      HashValue    Pointer to a buffer that receives the SHA-1 digest\r
397                                 value (20 bytes).\r
398 \r
399   @retval TRUE   SHA-1 digest computation succeeded.\r
400   @retval FALSE  SHA-1 digest computation failed.\r
401   @retval FALSE  This interface is not supported.\r
402 \r
403 **/\r
405 EFIAPI\r
406 Sha1Final (\r
407   IN OUT  VOID   *Sha1Context,\r
408   OUT     UINT8  *HashValue\r
409   );\r
410 \r
411 /**\r
412   Retrieves the size, in bytes, of the context buffer required for SHA-256 hash operations.\r
413 \r
414   @return  The size, in bytes, of the context buffer required for SHA-256 hash operations.\r
415 \r
416 **/\r
417 UINTN\r
418 EFIAPI\r
419 Sha256GetContextSize (\r
420   VOID\r
421   );\r
422 \r
423 /**\r
424   Initializes user-supplied memory pointed by Sha256Context as SHA-256 hash context for\r
425   subsequent use.\r
426 \r
427   If Sha256Context is NULL, then return FALSE.\r
428 \r
429   @param[out]  Sha256Context  Pointer to SHA-256 context being initialized.\r
430 \r
431   @retval TRUE   SHA-256 context initialization succeeded.\r
432   @retval FALSE  SHA-256 context initialization failed.\r
433 \r
434 **/\r
436 EFIAPI\r
437 Sha256Init (\r
438   OUT  VOID  *Sha256Context\r
439   );\r
440 \r
441 /**\r
442   Makes a copy of an existing SHA-256 context.\r
443 \r
444   If Sha256Context is NULL, then return FALSE.\r
445   If NewSha256Context is NULL, then return FALSE.\r
446   If this interface is not supported, then return FALSE.\r
447 \r
448   @param[in]  Sha256Context     Pointer to SHA-256 context being copied.\r
449   @param[out] NewSha256Context  Pointer to new SHA-256 context.\r
450 \r
451   @retval TRUE   SHA-256 context copy succeeded.\r
452   @retval FALSE  SHA-256 context copy failed.\r
453   @retval FALSE  This interface is not supported.\r
454 \r
455 **/\r
457 EFIAPI\r
458 Sha256Duplicate (\r
459   IN   CONST VOID  *Sha256Context,\r
460   OUT  VOID        *NewSha256Context\r
461   );\r
462 \r
463 /**\r
464   Digests the input data and updates SHA-256 context.\r
465 \r
466   This function performs SHA-256 digest on a data buffer of the specified size.\r
467   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
468   SHA-256 context should be already correctly intialized by Sha256Init(), and should not be finalized\r
469   by Sha256Final(). Behavior with invalid context is undefined.\r
470 \r
471   If Sha256Context is NULL, then return FALSE.\r
472 \r
473   @param[in, out]  Sha256Context  Pointer to the SHA-256 context.\r
474   @param[in]       Data           Pointer to the buffer containing the data to be hashed.\r
475   @param[in]       DataSize       Size of Data buffer in bytes.\r
476 \r
477   @retval TRUE   SHA-256 data digest succeeded.\r
478   @retval FALSE  SHA-256 data digest failed.\r
479 \r
480 **/\r
482 EFIAPI\r
483 Sha256Update (\r
484   IN OUT  VOID        *Sha256Context,\r
485   IN      CONST VOID  *Data,\r
486   IN      UINTN       DataSize\r
487   );\r
488 \r
489 /**\r
490   Completes computation of the SHA-256 digest value.\r
491 \r
492   This function completes SHA-256 hash computation and retrieves the digest value into\r
493   the specified memory. After this function has been called, the SHA-256 context cannot\r
494   be used again.\r
495   SHA-256 context should be already correctly intialized by Sha256Init(), and should not be\r
496   finalized by Sha256Final(). Behavior with invalid SHA-256 context is undefined.\r
497 \r
498   If Sha256Context is NULL, then return FALSE.\r
499   If HashValue is NULL, then return FALSE.\r
500 \r
501   @param[in, out]  Sha256Context  Pointer to the SHA-256 context.\r
502   @param[out]      HashValue      Pointer to a buffer that receives the SHA-256 digest\r
503                                   value (32 bytes).\r
504 \r
505   @retval TRUE   SHA-256 digest computation succeeded.\r
506   @retval FALSE  SHA-256 digest computation failed.\r
507 \r
508 **/\r
510 EFIAPI\r
511 Sha256Final (\r
512   IN OUT  VOID   *Sha256Context,\r
513   OUT     UINT8  *HashValue\r
514   );\r
515 \r
516 \r
517 //=====================================================================================\r
518 //    MAC (Message Authentication Code) Primitive\r
519 //=====================================================================================\r
520 \r
521 /**\r
522   Retrieves the size, in bytes, of the context buffer required for HMAC-MD5 operations.\r
523 \r
524   If this interface is not supported, then return zero.\r
525 \r
526   @return  The size, in bytes, of the context buffer required for HMAC-MD5 operations.\r
527   @retval  0   This interface is not supported.\r
528 \r
529 **/\r
530 UINTN\r
531 EFIAPI\r
532 HmacMd5GetContextSize (\r
533   VOID\r
534   );\r
535 \r
536 /**\r
537   Initializes user-supplied memory pointed by HmacMd5Context as HMAC-MD5 context for\r
538   subsequent use.\r
539 \r
540   If HmacMd5Context is NULL, then return FALSE.\r
541   If this interface is not supported, then return FALSE.\r
542 \r
543   @param[out]  HmacMd5Context  Pointer to HMAC-MD5 context being initialized.\r
544   @param[in]   Key             Pointer to the user-supplied key.\r
545   @param[in]   KeySize         Key size in bytes.\r
546 \r
547   @retval TRUE   HMAC-MD5 context initialization succeeded.\r
548   @retval FALSE  HMAC-MD5 context initialization failed.\r
549   @retval FALSE  This interface is not supported.\r
550 \r
551 **/\r
553 EFIAPI\r
554 HmacMd5Init (\r
555   OUT  VOID         *HmacMd5Context,\r
556   IN   CONST UINT8  *Key,\r
557   IN   UINTN        KeySize\r
558   );\r
559 \r
560 /**\r
561   Makes a copy of an existing HMAC-MD5 context.\r
562 \r
563   If HmacMd5Context is NULL, then return FALSE.\r
564   If NewHmacMd5Context is NULL, then return FALSE.\r
565   If this interface is not supported, then return FALSE.\r
566 \r
567   @param[in]  HmacMd5Context     Pointer to HMAC-MD5 context being copied.\r
568   @param[out] NewHmacMd5Context  Pointer to new HMAC-MD5 context.\r
569 \r
570   @retval TRUE   HMAC-MD5 context copy succeeded.\r
571   @retval FALSE  HMAC-MD5 context copy failed.\r
572   @retval FALSE  This interface is not supported.\r
573 \r
574 **/\r
576 EFIAPI\r
577 HmacMd5Duplicate (\r
578   IN   CONST VOID  *HmacMd5Context,\r
579   OUT  VOID        *NewHmacMd5Context\r
580   );\r
581 \r
582 /**\r
583   Digests the input data and updates HMAC-MD5 context.\r
584 \r
585   This function performs HMAC-MD5 digest on a data buffer of the specified size.\r
586   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
587   HMAC-MD5 context should be already correctly intialized by HmacMd5Init(), and should not be\r
588   finalized by HmacMd5Final(). Behavior with invalid context is undefined.\r
589 \r
590   If HmacMd5Context is NULL, then return FALSE.\r
591   If this interface is not supported, then return FALSE.\r
592 \r
593   @param[in, out]  HmacMd5Context  Pointer to the HMAC-MD5 context.\r
594   @param[in]       Data            Pointer to the buffer containing the data to be digested.\r
595   @param[in]       DataSize        Size of Data buffer in bytes.\r
596 \r
597   @retval TRUE   HMAC-MD5 data digest succeeded.\r
598   @retval FALSE  HMAC-MD5 data digest failed.\r
599   @retval FALSE  This interface is not supported.\r
600 \r
601 **/\r
603 EFIAPI\r
604 HmacMd5Update (\r
605   IN OUT  VOID        *HmacMd5Context,\r
606   IN      CONST VOID  *Data,\r
607   IN      UINTN       DataSize\r
608   );\r
609 \r
610 /**\r
611   Completes computation of the HMAC-MD5 digest value.\r
612 \r
613   This function completes HMAC-MD5 hash computation and retrieves the digest value into\r
614   the specified memory. After this function has been called, the HMAC-MD5 context cannot\r
615   be used again.\r
616   HMAC-MD5 context should be already correctly intialized by HmacMd5Init(), and should not be\r
617   finalized by HmacMd5Final(). Behavior with invalid HMAC-MD5 context is undefined.\r
618 \r
619   If HmacMd5Context is NULL, then return FALSE.\r
620   If HashValue is NULL, then return FALSE.\r
621   If this interface is not supported, then return FALSE.\r
622 \r
623   @param[in, out]  HmacMd5Context  Pointer to the HMAC-MD5 context.\r
624   @param[out]      HashValue       Pointer to a buffer that receives the HMAC-MD5 digest\r
625                                    value (16 bytes).\r
626 \r
627   @retval TRUE   HMAC-MD5 digest computation succeeded.\r
628   @retval FALSE  HMAC-MD5 digest computation failed.\r
629   @retval FALSE  This interface is not supported.\r
630 \r
631 **/\r
633 EFIAPI\r
634 HmacMd5Final (\r
635   IN OUT  VOID   *HmacMd5Context,\r
636   OUT     UINT8  *HmacValue\r
637   );\r
638 \r
639 /**\r
640   Retrieves the size, in bytes, of the context buffer required for HMAC-SHA1 operations.\r
641 \r
642   If this interface is not supported, then return zero.\r
643 \r
644   @return  The size, in bytes, of the context buffer required for HMAC-SHA1 operations.\r
645   @retval  0   This interface is not supported.\r
646 \r
647 **/\r
648 UINTN\r
649 EFIAPI\r
650 HmacSha1GetContextSize (\r
651   VOID\r
652   );\r
653 \r
654 /**\r
655   Initializes user-supplied memory pointed by HmacSha1Context as HMAC-SHA1 context for\r
656   subsequent use.\r
657 \r
658   If HmacSha1Context is NULL, then return FALSE.\r
659   If this interface is not supported, then return FALSE.\r
660 \r
661   @param[out]  HmacSha1Context  Pointer to HMAC-SHA1 context being initialized.\r
662   @param[in]   Key              Pointer to the user-supplied key.\r
663   @param[in]   KeySize          Key size in bytes.\r
664 \r
665   @retval TRUE   HMAC-SHA1 context initialization succeeded.\r
666   @retval FALSE  HMAC-SHA1 context initialization failed.\r
667   @retval FALSE  This interface is not supported.\r
668 \r
669 **/\r
671 EFIAPI\r
672 HmacSha1Init (\r
673   OUT  VOID         *HmacSha1Context,\r
674   IN   CONST UINT8  *Key,\r
675   IN   UINTN        KeySize\r
676   );\r
677 \r
678 /**\r
679   Makes a copy of an existing HMAC-SHA1 context.\r
680 \r
681   If HmacSha1Context is NULL, then return FALSE.\r
682   If NewHmacSha1Context is NULL, then return FALSE.\r
683   If this interface is not supported, then return FALSE.\r
684 \r
685   @param[in]  HmacSha1Context     Pointer to HMAC-SHA1 context being copied.\r
686   @param[out] NewHmacSha1Context  Pointer to new HMAC-SHA1 context.\r
687 \r
688   @retval TRUE   HMAC-SHA1 context copy succeeded.\r
689   @retval FALSE  HMAC-SHA1 context copy failed.\r
690   @retval FALSE  This interface is not supported.\r
691 \r
692 **/\r
694 EFIAPI\r
695 HmacSha1Duplicate (\r
696   IN   CONST VOID  *HmacSha1Context,\r
697   OUT  VOID        *NewHmacSha1Context\r
698   );\r
699 \r
700 /**\r
701   Digests the input data and updates HMAC-SHA1 context.\r
702 \r
703   This function performs HMAC-SHA1 digest on a data buffer of the specified size.\r
704   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
705   HMAC-SHA1 context should be already correctly intialized by HmacSha1Init(), and should not\r
706   be finalized by HmacSha1Final(). Behavior with invalid context is undefined.\r
707 \r
708   If HmacSha1Context is NULL, then return FALSE.\r
709   If this interface is not supported, then return FALSE.\r
710 \r
711   @param[in, out]  HmacSha1Context Pointer to the HMAC-SHA1 context.\r
712   @param[in]       Data            Pointer to the buffer containing the data to be digested.\r
713   @param[in]       DataSize        Size of Data buffer in bytes.\r
714 \r
715   @retval TRUE   HMAC-SHA1 data digest succeeded.\r
716   @retval FALSE  HMAC-SHA1 data digest failed.\r
717   @retval FALSE  This interface is not supported.\r
718 \r
719 **/\r
721 EFIAPI\r
722 HmacSha1Update (\r
723   IN OUT  VOID        *HmacSha1Context,\r
724   IN      CONST VOID  *Data,\r
725   IN      UINTN       DataSize\r
726   );\r
727 \r
728 /**\r
729   Completes computation of the HMAC-SHA1 digest value.\r
730 \r
731   This function completes HMAC-SHA1 hash computation and retrieves the digest value into\r
732   the specified memory. After this function has been called, the HMAC-SHA1 context cannot\r
733   be used again.\r
734   HMAC-SHA1 context should be already correctly intialized by HmacSha1Init(), and should\r
735   not be finalized by HmacSha1Final(). Behavior with invalid HMAC-SHA1 context is undefined.\r
736 \r
737   If HmacSha1Context is NULL, then return FALSE.\r
738   If HashValue is NULL, then return FALSE.\r
739   If this interface is not supported, then return FALSE.\r
740 \r
741   @param[in, out]  HmacSha1Context  Pointer to the HMAC-SHA1 context.\r
742   @param[out]      HashValue        Pointer to a buffer that receives the HMAC-SHA1 digest\r
743                                     value (20 bytes).\r
744 \r
745   @retval TRUE   HMAC-SHA1 digest computation succeeded.\r
746   @retval FALSE  HMAC-SHA1 digest computation failed.\r
747   @retval FALSE  This interface is not supported.\r
748 \r
749 **/\r
751 EFIAPI\r
752 HmacSha1Final (\r
753   IN OUT  VOID   *HmacSha1Context,\r
754   OUT     UINT8  *HmacValue\r
755   );\r
756 \r
757 \r
758 //=====================================================================================\r
759 //    Symmetric Cryptography Primitive\r
760 //=====================================================================================\r
761 \r
762 /**\r
763   Retrieves the size, in bytes, of the context buffer required for TDES operations.\r
764 \r
765   If this interface is not supported, then return zero.\r
766 \r
767   @return  The size, in bytes, of the context buffer required for TDES operations.\r
768   @retval  0   This interface is not supported.\r
769 \r
770 **/\r
771 UINTN\r
772 EFIAPI\r
773 TdesGetContextSize (\r
774   VOID\r
775   );\r
776 \r
777 /**\r
778   Initializes user-supplied memory as TDES context for subsequent use.\r
779 \r
780   This function initializes user-supplied memory pointed by TdesContext as TDES context.\r
781   In addtion, it sets up all TDES key materials for subsequent encryption and decryption\r
782   operations.\r
783   There are 3 key options as follows:\r
784   KeyLength = 64,  Keying option 1: K1 == K2 == K3 (Backward compatibility with DES)\r
785   KeyLength = 128, Keying option 2: K1 != K2 and K3 = K1 (Less Security)\r
786   KeyLength = 192  Keying option 3: K1 != K2 != K3 (Strongest)\r
787 \r
788   If TdesContext is NULL, then return FALSE.\r
789   If Key is NULL, then return FALSE.\r
790   If KeyLength is not valid, then return FALSE.\r
791   If this interface is not supported, then return FALSE.\r
792 \r
793   @param[out]  TdesContext  Pointer to TDES context being initialized.\r
794   @param[in]   Key          Pointer to the user-supplied TDES key.\r
795   @param[in]   KeyLength    Length of TDES key in bits.\r
796 \r
797   @retval TRUE   TDES context initialization succeeded.\r
798   @retval FALSE  TDES context initialization failed.\r
799   @retval FALSE  This interface is not supported.\r
800 \r
801 **/\r
803 EFIAPI\r
804 TdesInit (\r
805   OUT  VOID         *TdesContext,\r
806   IN   CONST UINT8  *Key,\r
807   IN   UINTN        KeyLength\r
808   );\r
809 \r
810 /**\r
811   Performs TDES encryption on a data buffer of the specified size in ECB mode.\r
812 \r
813   This function performs TDES encryption on data buffer pointed by Input, of specified\r
814   size of InputSize, in ECB mode.\r
815   InputSize must be multiple of block size (8 bytes). This function does not perform\r
816   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
817   TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
818   invalid TDES context is undefined.\r
819 \r
820   If TdesContext is NULL, then return FALSE.\r
821   If Input is NULL, then return FALSE.\r
822   If InputSize is not multiple of block size (8 bytes), then return FALSE.\r
823   If Output is NULL, then return FALSE.\r
824   If this interface is not supported, then return FALSE.\r
825 \r
826   @param[in]   TdesContext  Pointer to the TDES context.\r
827   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.\r
828   @param[in]   InputSize    Size of the Input buffer in bytes.\r
829   @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.\r
830 \r
831   @retval TRUE   TDES encryption succeeded.\r
832   @retval FALSE  TDES encryption failed.\r
833   @retval FALSE  This interface is not supported.\r
834 \r
835 **/\r
837 EFIAPI\r
838 TdesEcbEncrypt (\r
839   IN   VOID         *TdesContext,\r
840   IN   CONST UINT8  *Input,\r
841   IN   UINTN        InputSize,\r
842   OUT  UINT8        *Output\r
843   );\r
844 \r
845 /**\r
846   Performs TDES decryption on a data buffer of the specified size in ECB mode.\r
847 \r
848   This function performs TDES decryption on data buffer pointed by Input, of specified\r
849   size of InputSize, in ECB mode.\r
850   InputSize must be multiple of block size (8 bytes). This function does not perform\r
851   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
852   TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
853   invalid TDES context is undefined.\r
854 \r
855   If TdesContext is NULL, then return FALSE.\r
856   If Input is NULL, then return FALSE.\r
857   If InputSize is not multiple of block size (8 bytes), then return FALSE.\r
858   If Output is NULL, then return FALSE.\r
859   If this interface is not supported, then return FALSE.\r
860 \r
861   @param[in]   TdesContext  Pointer to the TDES context.\r
862   @param[in]   Input        Pointer to the buffer containing the data to be decrypted.\r
863   @param[in]   InputSize    Size of the Input buffer in bytes.\r
864   @param[out]  Output       Pointer to a buffer that receives the TDES decryption output.\r
865 \r
866   @retval TRUE   TDES decryption succeeded.\r
867   @retval FALSE  TDES decryption failed.\r
868   @retval FALSE  This interface is not supported.\r
869 \r
870 **/\r
872 EFIAPI\r
873 TdesEcbDecrypt (\r
874   IN   VOID         *TdesContext,\r
875   IN   CONST UINT8  *Input,\r
876   IN   UINTN        InputSize,\r
877   OUT  UINT8        *Output\r
878   );\r
879 \r
880 /**\r
881   Performs TDES encryption on a data buffer of the specified size in CBC mode.\r
882 \r
883   This function performs TDES encryption on data buffer pointed by Input, of specified\r
884   size of InputSize, in CBC mode.\r
885   InputSize must be multiple of block size (8 bytes). This function does not perform\r
886   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
887   Initialization vector should be one block size (8 bytes).\r
888   TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
889   invalid TDES context is undefined.\r
890 \r
891   If TdesContext is NULL, then return FALSE.\r
892   If Input is NULL, then return FALSE.\r
893   If InputSize is not multiple of block size (8 bytes), then return FALSE.\r
894   If Ivec is NULL, then return FALSE.\r
895   If Output is NULL, then return FALSE.\r
896   If this interface is not supported, then return FALSE.\r
897 \r
898   @param[in]   TdesContext  Pointer to the TDES context.\r
899   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.\r
900   @param[in]   InputSize    Size of the Input buffer in bytes.\r
901   @param[in]   Ivec         Pointer to initialization vector.\r
902   @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.\r
903 \r
904   @retval TRUE   TDES encryption succeeded.\r
905   @retval FALSE  TDES encryption failed.\r
906   @retval FALSE  This interface is not supported.\r
907 \r
908 **/\r
910 EFIAPI\r
911 TdesCbcEncrypt (\r
912   IN   VOID         *TdesContext,\r
913   IN   CONST UINT8  *Input,\r
914   IN   UINTN        InputSize,\r
915   IN   CONST UINT8  *Ivec,\r
916   OUT  UINT8        *Output\r
917   );\r
918 \r
919 /**\r
920   Performs TDES decryption on a data buffer of the specified size in CBC mode.\r
921 \r
922   This function performs TDES decryption on data buffer pointed by Input, of specified\r
923   size of InputSize, in CBC mode.\r
924   InputSize must be multiple of block size (8 bytes). This function does not perform\r
925   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
926   Initialization vector should be one block size (8 bytes).\r
927   TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
928   invalid TDES context is undefined.\r
929 \r
930   If TdesContext is NULL, then return FALSE.\r
931   If Input is NULL, then return FALSE.\r
932   If InputSize is not multiple of block size (8 bytes), then return FALSE.\r
933   If Ivec is NULL, then return FALSE.\r
934   If Output is NULL, then return FALSE.\r
935   If this interface is not supported, then return FALSE.\r
936 \r
937   @param[in]   TdesContext  Pointer to the TDES context.\r
938   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.\r
939   @param[in]   InputSize    Size of the Input buffer in bytes.\r
940   @param[in]   Ivec         Pointer to initialization vector.\r
941   @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.\r
942 \r
943   @retval TRUE   TDES decryption succeeded.\r
944   @retval FALSE  TDES decryption failed.\r
945   @retval FALSE  This interface is not supported.\r
946 \r
947 **/\r
949 EFIAPI\r
950 TdesCbcDecrypt (\r
951   IN   VOID         *TdesContext,\r
952   IN   CONST UINT8  *Input,\r
953   IN   UINTN        InputSize,\r
954   IN   CONST UINT8  *Ivec,\r
955   OUT  UINT8        *Output\r
956   );\r
957 \r
958 /**\r
959   Retrieves the size, in bytes, of the context buffer required for AES operations.\r
960 \r
961   If this interface is not supported, then return zero.\r
962 \r
963   @return  The size, in bytes, of the context buffer required for AES operations.\r
964   @retval  0   This interface is not supported.\r
965 \r
966 **/\r
967 UINTN\r
968 EFIAPI\r
969 AesGetContextSize (\r
970   VOID\r
971   );\r
972 \r
973 /**\r
974   Initializes user-supplied memory as AES context for subsequent use.\r
975 \r
976   This function initializes user-supplied memory pointed by AesContext as AES context.\r
977   In addtion, it sets up all AES key materials for subsequent encryption and decryption\r
978   operations.\r
979   There are 3 options for key length, 128 bits, 192 bits, and 256 bits.\r
980 \r
981   If AesContext is NULL, then return FALSE.\r
982   If Key is NULL, then return FALSE.\r
983   If KeyLength is not valid, then return FALSE.\r
984   If this interface is not supported, then return FALSE.\r
985 \r
986   @param[out]  AesContext  Pointer to AES context being initialized.\r
987   @param[in]   Key         Pointer to the user-supplied AES key.\r
988   @param[in]   KeyLength   Length of AES key in bits.\r
989 \r
990   @retval TRUE   AES context initialization succeeded.\r
991   @retval FALSE  AES context initialization failed.\r
992   @retval FALSE  This interface is not supported.\r
993 \r
994 **/\r
996 EFIAPI\r
997 AesInit (\r
998   OUT  VOID         *AesContext,\r
999   IN   CONST UINT8  *Key,\r
1000   IN   UINTN        KeyLength\r
1001   );\r
1002 \r
1003 /**\r
1004   Performs AES encryption on a data buffer of the specified size in ECB mode.\r
1005 \r
1006   This function performs AES encryption on data buffer pointed by Input, of specified\r
1007   size of InputSize, in ECB mode.\r
1008   InputSize must be multiple of block size (16 bytes). This function does not perform\r
1009   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1010   AesContext should be already correctly initialized by AesInit(). Behavior with\r
1011   invalid AES context is undefined.\r
1012 \r
1013   If AesContext is NULL, then return FALSE.\r
1014   If Input is NULL, then return FALSE.\r
1015   If InputSize is not multiple of block size (16 bytes), then return FALSE.\r
1016   If Output is NULL, then return FALSE.\r
1017   If this interface is not supported, then return FALSE.\r
1018 \r
1019   @param[in]   AesContext  Pointer to the AES context.\r
1020   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.\r
1021   @param[in]   InputSize   Size of the Input buffer in bytes.\r
1022   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.\r
1023 \r
1024   @retval TRUE   AES encryption succeeded.\r
1025   @retval FALSE  AES encryption failed.\r
1026   @retval FALSE  This interface is not supported.\r
1027 \r
1028 **/\r
1029 BOOLEAN\r
1030 EFIAPI\r
1031 AesEcbEncrypt (\r
1032   IN   VOID         *AesContext,\r
1033   IN   CONST UINT8  *Input,\r
1034   IN   UINTN        InputSize,\r
1035   OUT  UINT8        *Output\r
1036   );\r
1037 \r
1038 /**\r
1039   Performs AES decryption on a data buffer of the specified size in ECB mode.\r
1040 \r
1041   This function performs AES decryption on data buffer pointed by Input, of specified\r
1042   size of InputSize, in ECB mode.\r
1043   InputSize must be multiple of block size (16 bytes). This function does not perform\r
1044   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1045   AesContext should be already correctly initialized by AesInit(). Behavior with\r
1046   invalid AES context is undefined.\r
1047 \r
1048   If AesContext is NULL, then return FALSE.\r
1049   If Input is NULL, then return FALSE.\r
1050   If InputSize is not multiple of block size (16 bytes), then return FALSE.\r
1051   If Output is NULL, then return FALSE.\r
1052   If this interface is not supported, then return FALSE.\r
1053 \r
1054   @param[in]   AesContext  Pointer to the AES context.\r
1055   @param[in]   Input       Pointer to the buffer containing the data to be decrypted.\r
1056   @param[in]   InputSize   Size of the Input buffer in bytes.\r
1057   @param[out]  Output      Pointer to a buffer that receives the AES decryption output.\r
1058 \r
1059   @retval TRUE   AES decryption succeeded.\r
1060   @retval FALSE  AES decryption failed.\r
1061   @retval FALSE  This interface is not supported.\r
1062 \r
1063 **/\r
1064 BOOLEAN\r
1065 EFIAPI\r
1066 AesEcbDecrypt (\r
1067   IN   VOID         *AesContext,\r
1068   IN   CONST UINT8  *Input,\r
1069   IN   UINTN        InputSize,\r
1070   OUT  UINT8        *Output\r
1071   );\r
1072 \r
1073 /**\r
1074   Performs AES encryption on a data buffer of the specified size in CBC mode.\r
1075 \r
1076   This function performs AES encryption on data buffer pointed by Input, of specified\r
1077   size of InputSize, in CBC mode.\r
1078   InputSize must be multiple of block size (16 bytes). This function does not perform\r
1079   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1080   Initialization vector should be one block size (16 bytes).\r
1081   AesContext should be already correctly initialized by AesInit(). Behavior with\r
1082   invalid AES context is undefined.\r
1083 \r
1084   If AesContext is NULL, then return FALSE.\r
1085   If Input is NULL, then return FALSE.\r
1086   If InputSize is not multiple of block size (16 bytes), then return FALSE.\r
1087   If Ivec is NULL, then return FALSE.\r
1088   If Output is NULL, then return FALSE.\r
1089   If this interface is not supported, then return FALSE.\r
1090 \r
1091   @param[in]   AesContext  Pointer to the AES context.\r
1092   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.\r
1093   @param[in]   InputSize   Size of the Input buffer in bytes.\r
1094   @param[in]   Ivec        Pointer to initialization vector.\r
1095   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.\r
1096 \r
1097   @retval TRUE   AES encryption succeeded.\r
1098   @retval FALSE  AES encryption failed.\r
1099   @retval FALSE  This interface is not supported.\r
1100 \r
1101 **/\r
1102 BOOLEAN\r
1103 EFIAPI\r
1104 AesCbcEncrypt (\r
1105   IN   VOID         *AesContext,\r
1106   IN   CONST UINT8  *Input,\r
1107   IN   UINTN        InputSize,\r
1108   IN   CONST UINT8  *Ivec,\r
1109   OUT  UINT8        *Output\r
1110   );\r
1111 \r
1112 /**\r
1113   Performs AES decryption on a data buffer of the specified size in CBC mode.\r
1114 \r
1115   This function performs AES decryption on data buffer pointed by Input, of specified\r
1116   size of InputSize, in CBC mode.\r
1117   InputSize must be multiple of block size (16 bytes). This function does not perform\r
1118   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1119   Initialization vector should be one block size (16 bytes).\r
1120   AesContext should be already correctly initialized by AesInit(). Behavior with\r
1121   invalid AES context is undefined.\r
1122 \r
1123   If AesContext is NULL, then return FALSE.\r
1124   If Input is NULL, then return FALSE.\r
1125   If InputSize is not multiple of block size (16 bytes), then return FALSE.\r
1126   If Ivec is NULL, then return FALSE.\r
1127   If Output is NULL, then return FALSE.\r
1128   If this interface is not supported, then return FALSE.\r
1129 \r
1130   @param[in]   AesContext  Pointer to the AES context.\r
1131   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.\r
1132   @param[in]   InputSize   Size of the Input buffer in bytes.\r
1133   @param[in]   Ivec        Pointer to initialization vector.\r
1134   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.\r
1135 \r
1136   @retval TRUE   AES decryption succeeded.\r
1137   @retval FALSE  AES decryption failed.\r
1138   @retval FALSE  This interface is not supported.\r
1139 \r
1140 **/\r
1141 BOOLEAN\r
1142 EFIAPI\r
1143 AesCbcDecrypt (\r
1144   IN   VOID         *AesContext,\r
1145   IN   CONST UINT8  *Input,\r
1146   IN   UINTN        InputSize,\r
1147   IN   CONST UINT8  *Ivec,\r
1148   OUT  UINT8        *Output\r
1149   );\r
1150 \r
1151 /**\r
1152   Retrieves the size, in bytes, of the context buffer required for ARC4 operations.\r
1153 \r
1154   If this interface is not supported, then return zero.\r
1155 \r
1156   @return  The size, in bytes, of the context buffer required for ARC4 operations.\r
1157   @retval  0   This interface is not supported.\r
1158 \r
1159 **/\r
1160 UINTN\r
1161 EFIAPI\r
1162 Arc4GetContextSize (\r
1163   VOID\r
1164   );\r
1165 \r
1166 /**\r
1167   Initializes user-supplied memory as ARC4 context for subsequent use.\r
1168 \r
1169   This function initializes user-supplied memory pointed by Arc4Context as ARC4 context.\r
1170   In addtion, it sets up all ARC4 key materials for subsequent encryption and decryption\r
1171   operations.\r
1172 \r
1173   If Arc4Context is NULL, then return FALSE.\r
1174   If Key is NULL, then return FALSE.\r
1175   If KeySize does not in the range of [5, 256] bytes, then return FALSE.\r
1176   If this interface is not supported, then return FALSE.\r
1177 \r
1178   @param[out]  Arc4Context  Pointer to ARC4 context being initialized.\r
1179   @param[in]   Key          Pointer to the user-supplied ARC4 key.\r
1180   @param[in]   KeySize      Size of ARC4 key in bytes.\r
1181 \r
1182   @retval TRUE   ARC4 context initialization succeeded.\r
1183   @retval FALSE  ARC4 context initialization failed.\r
1184   @retval FALSE  This interface is not supported.\r
1185 \r
1186 **/\r
1187 BOOLEAN\r
1188 EFIAPI\r
1189 Arc4Init (\r
1190   OUT  VOID         *Arc4Context,\r
1191   IN   CONST UINT8  *Key,\r
1192   IN   UINTN        KeySize\r
1193   );\r
1194 \r
1195 /**\r
1196   Performs ARC4 encryption on a data buffer of the specified size.\r
1197 \r
1198   This function performs ARC4 encryption on data buffer pointed by Input, of specified\r
1199   size of InputSize.\r
1200   Arc4Context should be already correctly initialized by Arc4Init(). Behavior with\r
1201   invalid ARC4 context is undefined.\r
1202 \r
1203   If Arc4Context is NULL, then return FALSE.\r
1204   If Input is NULL, then return FALSE.\r
1205   If Output is NULL, then return FALSE.\r
1206   If this interface is not supported, then return FALSE.\r
1207 \r
1208   @param[in]   Arc4Context  Pointer to the ARC4 context.\r
1209   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.\r
1210   @param[in]   InputSize    Size of the Input buffer in bytes.\r
1211   @param[out]  Output       Pointer to a buffer that receives the ARC4 encryption output.\r
1212 \r
1213   @retval TRUE   ARC4 encryption succeeded.\r
1214   @retval FALSE  ARC4 encryption failed.\r
1215   @retval FALSE  This interface is not supported.\r
1216 \r
1217 **/\r
1218 BOOLEAN\r
1219 EFIAPI\r
1220 Arc4Encrypt (\r
1221   IN OUT  VOID         *Arc4Context,\r
1222   IN      CONST UINT8  *Input,\r
1223   IN      UINTN        InputSize,\r
1224   OUT     UINT8        *Output\r
1225   );\r
1226 \r
1227 /**\r
1228   Performs ARC4 decryption on a data buffer of the specified size.\r
1229 \r
1230   This function performs ARC4 decryption on data buffer pointed by Input, of specified\r
1231   size of InputSize.\r
1232   Arc4Context should be already correctly initialized by Arc4Init(). Behavior with\r
1233   invalid ARC4 context is undefined.\r
1234 \r
1235   If Arc4Context is NULL, then return FALSE.\r
1236   If Input is NULL, then return FALSE.\r
1237   If Output is NULL, then return FALSE.\r
1238   If this interface is not supported, then return FALSE.\r
1239 \r
1240   @param[in]   Arc4Context  Pointer to the ARC4 context.\r
1241   @param[in]   Input        Pointer to the buffer containing the data to be decrypted.\r
1242   @param[in]   InputSize    Size of the Input buffer in bytes.\r
1243   @param[out]  Output       Pointer to a buffer that receives the ARC4 decryption output.\r
1244 \r
1245   @retval TRUE   ARC4 decryption succeeded.\r
1246   @retval FALSE  ARC4 decryption failed.\r
1247   @retval FALSE  This interface is not supported.\r
1248 \r
1249 **/\r
1250 BOOLEAN\r
1251 EFIAPI\r
1252 Arc4Decrypt (\r
1253   IN OUT  VOID   *Arc4Context,\r
1254   IN      UINT8  *Input,\r
1255   IN      UINTN  InputSize,\r
1256   OUT     UINT8  *Output\r
1257   );\r
1258 \r
1259 /**\r
1260   Resets the ARC4 context to the initial state.\r
1261 \r
1262   The function resets the ARC4 context to the state it had immediately after the\r
1263   ARC4Init() function call.\r
1264   Contrary to ARC4Init(), Arc4Reset() requires no secret key as input, but ARC4 context\r
1265   should be already correctly initialized by ARC4Init().\r
1266 \r
1267   If Arc4Context is NULL, then return FALSE.\r
1268   If this interface is not supported, then return FALSE.\r
1269 \r
1270   @param[in, out]  Arc4Context  Pointer to the ARC4 context.\r
1271 \r
1272   @retval TRUE   ARC4 reset succeeded.\r
1273   @retval FALSE  ARC4 reset failed.\r
1274   @retval FALSE  This interface is not supported.\r
1275 \r
1276 **/\r
1277 BOOLEAN\r
1278 EFIAPI\r
1279 Arc4Reset (\r
1280   IN OUT  VOID  *Arc4Context\r
1281   );\r
1282 \r
1283 //=====================================================================================\r
1284 //    Asymmetric Cryptography Primitive\r
1285 //=====================================================================================\r
1286 \r
1287 /**\r
1288   Allocates and initializes one RSA context for subsequent use.\r
1289 \r
1290   @return  Pointer to the RSA context that has been initialized.\r
1291            If the allocations fails, RsaNew() returns NULL.\r
1292 \r
1293 **/\r
1294 VOID *\r
1295 EFIAPI\r
1296 RsaNew (\r
1297   VOID\r
1298   );\r
1299 \r
1300 /**\r
1301   Release the specified RSA context.\r
1302 \r
1303   If RsaContext is NULL, then return FALSE.\r
1304 \r
1305   @param[in]  RsaContext  Pointer to the RSA context to be released.\r
1306 \r
1307 **/\r
1308 VOID\r
1309 EFIAPI\r
1310 RsaFree (\r
1311   IN  VOID  *RsaContext\r
1312   );\r
1313 \r
1314 /**\r
1315   Sets the tag-designated key component into the established RSA context.\r
1316 \r
1317   This function sets the tag-designated RSA key component into the established\r
1318   RSA context from the user-specified non-negative integer (octet string format\r
1319   represented in RSA PKCS#1).\r
1320   If BigNumber is NULL, then the specified key componenet in RSA context is cleared.\r
1321 \r
1322   If RsaContext is NULL, then return FALSE.\r
1323 \r
1324   @param[in, out]  RsaContext  Pointer to RSA context being set.\r
1325   @param[in]       KeyTag      Tag of RSA key component being set.\r
1326   @param[in]       BigNumber   Pointer to octet integer buffer.\r
1327                                If NULL, then the specified key componenet in RSA\r
1328                                context is cleared.\r
1329   @param[in]       BnSize      Size of big number buffer in bytes.\r
1330                                If BigNumber is NULL, then it is ignored.\r
1331 \r
1332   @retval  TRUE   RSA key component was set successfully.\r
1333   @retval  FALSE  Invalid RSA key component tag.\r
1334 \r
1335 **/\r
1336 BOOLEAN\r
1337 EFIAPI\r
1338 RsaSetKey (\r
1339   IN OUT  VOID         *RsaContext,\r
1340   IN      RSA_KEY_TAG  KeyTag,\r
1341   IN      CONST UINT8  *BigNumber,\r
1342   IN      UINTN        BnSize\r
1343   );\r
1344 \r
1345 /**\r
1346   Gets the tag-designated RSA key component from the established RSA context.\r
1347 \r
1348   This function retrieves the tag-designated RSA key component from the\r
1349   established RSA context as a non-negative integer (octet string format\r
1350   represented in RSA PKCS#1).\r
1351   If specified key component has not been set or has been cleared, then returned\r
1352   BnSize is set to 0.\r
1353   If the BigNumber buffer is too small to hold the contents of the key, FALSE\r
1354   is returned and BnSize is set to the required buffer size to obtain the key.\r
1355 \r
1356   If RsaContext is NULL, then return FALSE.\r
1357   If BnSize is NULL, then return FALSE.\r
1358   If BnSize is large enough but BigNumber is NULL, then return FALSE.\r
1359   If this interface is not supported, then return FALSE.\r
1360 \r
1361   @param[in, out]  RsaContext  Pointer to RSA context being set.\r
1362   @param[in]       KeyTag      Tag of RSA key component being set.\r
1363   @param[out]      BigNumber   Pointer to octet integer buffer.\r
1364   @param[in, out]  BnSize      On input, the size of big number buffer in bytes.\r
1365                                On output, the size of data returned in big number buffer in bytes.\r
1366 \r
1367   @retval  TRUE   RSA key component was retrieved successfully.\r
1368   @retval  FALSE  Invalid RSA key component tag.\r
1369   @retval  FALSE  BnSize is too small.\r
1370   @retval  FALSE  This interface is not supported.\r
1371 \r
1372 **/\r
1373 BOOLEAN\r
1374 EFIAPI\r
1375 RsaGetKey (\r
1376   IN OUT  VOID         *RsaContext,\r
1377   IN      RSA_KEY_TAG  KeyTag,\r
1378   OUT     UINT8        *BigNumber,\r
1379   IN OUT  UINTN        *BnSize\r
1380   );\r
1381 \r
1382 /**\r
1383   Generates RSA key components.\r
1384 \r
1385   This function generates RSA key components. It takes RSA public exponent E and\r
1386   length in bits of RSA modulus N as input, and generates all key components.\r
1387   If PublicExponent is NULL, the default RSA public exponent (0x10001) will be used.\r
1388 \r
1389   Before this function can be invoked, pseudorandom number generator must be correctly\r
1390   initialized by RandomSeed().\r
1391 \r
1392   If RsaContext is NULL, then return FALSE.\r
1393   If this interface is not supported, then return FALSE.\r
1394 \r
1395   @param[in, out]  RsaContext           Pointer to RSA context being set.\r
1396   @param[in]       ModulusLength        Length of RSA modulus N in bits.\r
1397   @param[in]       PublicExponent       Pointer to RSA public exponent.\r
1398   @param[in]       PublicExponentSize   Size of RSA public exponent buffer in bytes. \r
1399 \r
1400   @retval  TRUE   RSA key component was generated successfully.\r
1401   @retval  FALSE  Invalid RSA key component tag.\r
1402   @retval  FALSE  This interface is not supported.\r
1403 \r
1404 **/\r
1405 BOOLEAN\r
1406 EFIAPI\r
1407 RsaGenerateKey (\r
1408   IN OUT  VOID         *RsaContext,\r
1409   IN      UINTN        ModulusLength,\r
1410   IN      CONST UINT8  *PublicExponent,\r
1411   IN      UINTN        PublicExponentSize\r
1412   );\r
1413 \r
1414 /**\r
1415   Validates key components of RSA context.\r
1416 \r
1417   This function validates key compoents of RSA context in following aspects:\r
1418   - Whether p is a prime\r
1419   - Whether q is a prime\r
1420   - Whether n = p * q\r
1421   - Whether d*e = 1  mod lcm(p-1,q-1)\r
1422 \r
1423   If RsaContext is NULL, then return FALSE.\r
1424   If this interface is not supported, then return FALSE.\r
1425 \r
1426   @param[in]  RsaContext  Pointer to RSA context to check.\r
1427 \r
1428   @retval  TRUE   RSA key components are valid.\r
1429   @retval  FALSE  RSA key components are not valid.\r
1430   @retval  FALSE  This interface is not supported.\r
1431 \r
1432 **/\r
1433 BOOLEAN\r
1434 EFIAPI\r
1435 RsaCheckKey (\r
1436   IN  VOID  *RsaContext\r
1437   );\r
1438 \r
1439 /**\r
1440   Carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme.\r
1441 \r
1442   This function carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme defined in\r
1443   RSA PKCS#1.\r
1444   If the Signature buffer is too small to hold the contents of signature, FALSE\r
1445   is returned and SigSize is set to the required buffer size to obtain the signature.\r
1446 \r
1447   If RsaContext is NULL, then return FALSE.\r
1448   If MessageHash is NULL, then return FALSE.\r
1449   If HashSize is not equal to the size of MD5, SHA-1 or SHA-256 digest, then return FALSE.\r
1450   If SigSize is large enough but Signature is NULL, then return FALSE.\r
1451   If this interface is not supported, then return FALSE.\r
1452 \r
1453   @param[in]      RsaContext   Pointer to RSA context for signature generation.\r
1454   @param[in]      MessageHash  Pointer to octet message hash to be signed.\r
1455   @param[in]      HashSize     Size of the message hash in bytes.\r
1456   @param[out]     Signature    Pointer to buffer to receive RSA PKCS1-v1_5 signature.\r
1457   @param[in, out] SigSize      On input, the size of Signature buffer in bytes.\r
1458                                On output, the size of data returned in Signature buffer in bytes.\r
1459 \r
1460   @retval  TRUE   Signature successfully generated in PKCS1-v1_5.\r
1461   @retval  FALSE  Signature generation failed.\r
1462   @retval  FALSE  SigSize is too small.\r
1463   @retval  FALSE  This interface is not supported.\r
1464 \r
1465 **/\r
1466 BOOLEAN\r
1467 EFIAPI\r
1468 RsaPkcs1Sign (\r
1469   IN      VOID         *RsaContext,\r
1470   IN      CONST UINT8  *MessageHash,\r
1471   IN      UINTN        HashSize,\r
1472   OUT     UINT8        *Signature,\r
1473   IN OUT  UINTN        *SigSize\r
1474   );\r
1475 \r
1476 /**\r
1477   Verifies the RSA-SSA signature with EMSA-PKCS1-v1_5 encoding scheme defined in\r
1478   RSA PKCS#1.\r
1479 \r
1480   If RsaContext is NULL, then return FALSE.\r
1481   If MessageHash is NULL, then return FALSE.\r
1482   If Signature is NULL, then return FALSE.\r
1483   If HashSize is not equal to the size of MD5, SHA-1, SHA-256 digest, then return FALSE.\r
1484 \r
1485   @param[in]  RsaContext   Pointer to RSA context for signature verification.\r
1486   @param[in]  MessageHash  Pointer to octet message hash to be checked.\r
1487   @param[in]  HashSize     Size of the message hash in bytes.\r
1488   @param[in]  Signature    Pointer to RSA PKCS1-v1_5 signature to be verified.\r
1489   @param[in]  SigSize      Size of signature in bytes.\r
1490 \r
1491   @retval  TRUE   Valid signature encoded in PKCS1-v1_5.\r
1492   @retval  FALSE  Invalid signature or invalid RSA context.\r
1493 \r
1494 **/\r
1495 BOOLEAN\r
1496 EFIAPI\r
1497 RsaPkcs1Verify (\r
1498   IN  VOID         *RsaContext,\r
1499   IN  CONST UINT8  *MessageHash,\r
1500   IN  UINTN        HashSize,\r
1501   IN  UINT8        *Signature,\r
1502   IN  UINTN        SigSize\r
1503   );\r
1504 \r
1505 /**\r
1506   Retrieve the RSA Private Key from the password-protected PEM key data.\r
1507 \r
1508   If PemData is NULL, then return FALSE.\r
1509   If RsaContext is NULL, then return FALSE.\r
1510   If this interface is not supported, then return FALSE.\r
1511 \r
1512   @param[in]  PemData      Pointer to the PEM-encoded key data to be retrieved.\r
1513   @param[in]  PemSize      Size of the PEM key data in bytes.\r
1514   @param[in]  Password     NULL-terminated passphrase used for encrypted PEM key data.\r
1515   @param[out] RsaContext   Pointer to new-generated RSA context which contain the retrieved\r
1516                            RSA private key component. Use RsaFree() function to free the\r
1517                            resource.\r
1518 \r
1519   @retval  TRUE   RSA Private Key was retrieved successfully.\r
1520   @retval  FALSE  Invalid PEM key data or incorrect password.\r
1521   @retval  FALSE  This interface is not supported.\r
1522   \r
1523 \r
1524 **/\r
1525 BOOLEAN\r
1526 EFIAPI\r
1527 RsaGetPrivateKeyFromPem (\r
1528   IN   CONST UINT8  *PemData,\r
1529   IN   UINTN        PemSize,\r
1530   IN   CONST CHAR8  *Password,\r
1531   OUT  VOID         **RsaContext\r
1532   );\r
1533 \r
1534 /**\r
1535   Retrieve the RSA Public Key from one DER-encoded X509 certificate.\r
1536 \r
1537   If Cert is NULL, then return FALSE.\r
1538   If RsaContext is NULL, then return FALSE.\r
1539   If this interface is not supported, then return FALSE.\r
1540 \r
1541   @param[in]  Cert         Pointer to the DER-encoded X509 certificate.\r
1542   @param[in]  CertSize     Size of the X509 certificate in bytes.\r
1543   @param[out] RsaContext   Pointer to new-generated RSA context which contain the retrieved\r
1544                            RSA public key component. Use RsaFree() function to free the\r
1545                            resource.\r
1546 \r
1547   @retval  TRUE   RSA Public Key was retrieved successfully.\r
1548   @retval  FALSE  Fail to retrieve RSA public key from X509 certificate.\r
1549   @retval  FALSE  This interface is not supported.\r
1550 \r
1551 **/\r
1552 BOOLEAN\r
1553 EFIAPI\r
1554 RsaGetPublicKeyFromX509 (\r
1555   IN   CONST UINT8  *Cert,\r
1556   IN   UINTN        CertSize,\r
1557   OUT  VOID         **RsaContext\r
1558   );\r
1559 \r
1560 /**\r
1561   Retrieve the subject bytes from one X.509 certificate.\r
1562 \r
1563   If Cert is NULL, then return FALSE.\r
1564   If SubjectSize is NULL, then return FALSE.\r
1565   If this interface is not supported, then return FALSE.\r
1566 \r
1567   @param[in]      Cert         Pointer to the DER-encoded X509 certificate.\r
1568   @param[in]      CertSize     Size of the X509 certificate in bytes.\r
1569   @param[out]     CertSubject  Pointer to the retrieved certificate subject bytes.\r
1570   @param[in, out] SubjectSize  The size in bytes of the CertSubject buffer on input,\r
1571                                and the size of buffer returned CertSubject on output.\r
1572 \r
1573   @retval  TRUE   The certificate subject retrieved successfully.\r
1574   @retval  FALSE  Invalid certificate, or the SubjectSize is too small for the result.\r
1575                   The SubjectSize will be updated with the required size.\r
1576   @retval  FALSE  This interface is not supported.\r
1577 \r
1578 **/\r
1579 BOOLEAN\r
1580 EFIAPI\r
1581 X509GetSubjectName (\r
1582   IN      CONST UINT8  *Cert,\r
1583   IN      UINTN        CertSize,\r
1584   OUT     UINT8        *CertSubject,\r
1585   IN OUT  UINTN        *SubjectSize\r
1586   );\r
1587 \r
1588 /**\r
1589   Verify one X509 certificate was issued by the trusted CA.\r
1590 \r
1591   If Cert is NULL, then return FALSE.\r
1592   If CACert is NULL, then return FALSE.\r
1593   If this interface is not supported, then return FALSE.\r
1594 \r
1595   @param[in]      Cert         Pointer to the DER-encoded X509 certificate to be verified.\r
1596   @param[in]      CertSize     Size of the X509 certificate in bytes.\r
1597   @param[in]      CACert       Pointer to the DER-encoded trusted CA certificate.\r
1598   @param[in]      CACertSize   Size of the CA Certificate in bytes.\r
1599 \r
1600   @retval  TRUE   The certificate was issued by the trusted CA.\r
1601   @retval  FALSE  Invalid certificate or the certificate was not issued by the given\r
1602                   trusted CA.\r
1603   @retval  FALSE  This interface is not supported.\r
1604 \r
1605 **/\r
1606 BOOLEAN\r
1607 EFIAPI\r
1608 X509VerifyCert (\r
1609   IN  CONST UINT8  *Cert,\r
1610   IN  UINTN        CertSize,\r
1611   IN  CONST UINT8  *CACert,\r
1612   IN  UINTN        CACertSize\r
1613   );\r
1614 \r
1615 /**\r
1616   Construct a X509 object from DER-encoded certificate data.\r
1617 \r
1618   If Cert is NULL, then return FALSE.\r
1619   If SingleX509Cert is NULL, then return FALSE.\r
1620   If this interface is not supported, then return FALSE.\r
1621 \r
1622   @param[in]  Cert            Pointer to the DER-encoded certificate data.\r
1623   @param[in]  CertSize        The size of certificate data in bytes.\r
1624   @param[out] SingleX509Cert  The generated X509 object.\r
1625 \r
1626   @retval     TRUE            The X509 object generation succeeded.\r
1627   @retval     FALSE           The operation failed.\r
1628   @retval     FALSE           This interface is not supported.\r
1629 \r
1630 **/\r
1631 BOOLEAN\r
1632 EFIAPI\r
1633 X509ConstructCertificate (\r
1634   IN   CONST UINT8  *Cert,\r
1635   IN   UINTN        CertSize,\r
1636   OUT  UINT8        **SingleX509Cert\r
1637   );\r
1638 \r
1639 /**\r
1640   Construct a X509 stack object from a list of DER-encoded certificate data.\r
1641 \r
1642   If X509Stack is NULL, then return FALSE.\r
1643   If this interface is not supported, then return FALSE.\r
1644 \r
1645   @param[in, out]  X509Stack  On input, pointer to an existing X509 stack object.\r
1646                               On output, pointer to the X509 stack object with new\r
1647                               inserted X509 certificate.\r
1648   @param           ...        A list of DER-encoded single certificate data followed\r
1649                               by certificate size. A NULL terminates the list. The\r
1650                               pairs are the arguments to X509ConstructCertificate().\r
1651                                  \r
1652   @retval     TRUE            The X509 stack construction succeeded.\r
1653   @retval     FALSE           The construction operation failed.\r
1654   @retval     FALSE           This interface is not supported.\r
1655 \r
1656 **/\r
1657 BOOLEAN\r
1658 EFIAPI\r
1659 X509ConstructCertificateStack (\r
1660   IN OUT  UINT8  **X509Stack,\r
1661   ...  \r
1662   );\r
1663 \r
1664 /**\r
1665   Release the specified X509 object.\r
1666 \r
1667   If the interface is not supported, then ASSERT().\r
1668 \r
1669   @param[in]  X509Cert  Pointer to the X509 object to be released.\r
1670 \r
1671 **/\r
1672 VOID\r
1673 EFIAPI\r
1674 X509Free (\r
1675   IN  VOID  *X509Cert\r
1676   );\r
1677 \r
1678 /**\r
1679   Release the specified X509 stack object.\r
1680 \r
1681   If the interface is not supported, then ASSERT().\r
1682 \r
1683   @param[in]  X509Stack  Pointer to the X509 stack object to be released.\r
1684 \r
1685 **/\r
1686 VOID\r
1687 EFIAPI\r
1688 X509StackFree (\r
1689   IN  VOID  *X509Stack\r
1690   );\r
1691 \r
1692 /**\r
1693   Get the signer's certificates from PKCS#7 signed data as described in "PKCS #7:\r
1694   Cryptographic Message Syntax Standard". The input signed data could be wrapped\r
1695   in a ContentInfo structure.\r
1696 \r
1697   If P7Data, CertStack, StackLength, TrustedCert or CertLength is NULL, then\r
1698   return FALSE. If P7Length overflow, then return FAlSE.\r
1699   If this interface is not supported, then return FALSE.\r
1700 \r
1701   @param[in]  P7Data       Pointer to the PKCS#7 message to verify.\r
1702   @param[in]  P7Length     Length of the PKCS#7 message in bytes.\r
1703   @param[out] CertStack    Pointer to Signer's certificates retrieved from P7Data.\r
1704                            It's caller's responsiblity to free the buffer.\r
1705   @param[out] StackLength  Length of signer's certificates in bytes.\r
1706   @param[out] TrustedCert  Pointer to a trusted certificate from Signer's certificates.\r
1707                            It's caller's responsiblity to free the buffer.\r
1708   @param[out] CertLength   Length of the trusted certificate in bytes.\r
1709 \r
1710   @retval  TRUE            The operation is finished successfully.\r
1711   @retval  FALSE           Error occurs during the operation.\r
1712   @retval  FALSE           This interface is not supported.\r
1713 \r
1714 **/\r
1715 BOOLEAN\r
1716 EFIAPI\r
1717 Pkcs7GetSigners (\r
1718   IN  CONST UINT8  *P7Data,\r
1719   IN  UINTN        P7Length,\r
1720   OUT UINT8        **CertStack,\r
1721   OUT UINTN        *StackLength,\r
1722   OUT UINT8        **TrustedCert,\r
1723   OUT UINTN        *CertLength\r
1724   );\r
1725 \r
1726 /**\r
1727   Wrap function to use free() to free allocated memory for certificates.\r
1728 \r
1729   If this interface is not supported, then ASSERT().\r
1730 \r
1731   @param[in]  Certs        Pointer to the certificates to be freed.\r
1732 \r
1733 **/\r
1734 VOID\r
1735 EFIAPI\r
1736 Pkcs7FreeSigners (\r
1737   IN  UINT8        *Certs\r
1738   );\r
1739 \r
1740 /**\r
1741   Creates a PKCS#7 signedData as described in "PKCS #7: Cryptographic Message\r
1742   Syntax Standard, version 1.5". This interface is only intended to be used for\r
1743   application to perform PKCS#7 functionality validation.\r
1744 \r
1745   If this interface is not supported, then return FALSE.\r
1746 \r
1747   @param[in]  PrivateKey       Pointer to the PEM-formatted private key data for\r
1748                                data signing.\r
1749   @param[in]  PrivateKeySize   Size of the PEM private key data in bytes.\r
1750   @param[in]  KeyPassword      NULL-terminated passphrase used for encrypted PEM\r
1751                                key data.\r
1752   @param[in]  InData           Pointer to the content to be signed.\r
1753   @param[in]  InDataSize       Size of InData in bytes.\r
1754   @param[in]  SignCert         Pointer to signer's DER-encoded certificate to sign with.\r
1755   @param[in]  OtherCerts       Pointer to an optional additional set of certificates to\r
1756                                include in the PKCS#7 signedData (e.g. any intermediate\r
1757                                CAs in the chain).\r
1758   @param[out] SignedData       Pointer to output PKCS#7 signedData.\r
1759   @param[out] SignedDataSize   Size of SignedData in bytes.\r
1760 \r
1761   @retval     TRUE             PKCS#7 data signing succeeded.\r
1762   @retval     FALSE            PKCS#7 data signing failed.\r
1763   @retval     FALSE            This interface is not supported.\r
1764 \r
1765 **/\r
1766 BOOLEAN\r
1767 EFIAPI\r
1768 Pkcs7Sign (\r
1769   IN   CONST UINT8  *PrivateKey,\r
1770   IN   UINTN        PrivateKeySize,\r
1771   IN   CONST UINT8  *KeyPassword,\r
1772   IN   UINT8        *InData,\r
1773   IN   UINTN        InDataSize,\r
1774   IN   UINT8        *SignCert,\r
1775   IN   UINT8        *OtherCerts      OPTIONAL,\r
1776   OUT  UINT8        **SignedData,\r
1777   OUT  UINTN        *SignedDataSize\r
1778   );\r
1779 \r
1780 /**\r
1781   Verifies the validility of a PKCS#7 signed data as described in "PKCS #7:\r
1782   Cryptographic Message Syntax Standard". The input signed data could be wrapped\r
1783   in a ContentInfo structure.\r
1784 \r
1785   If P7Data, TrustedCert or InData is NULL, then return FALSE.\r
1786   If P7Length, CertLength or DataLength overflow, then return FAlSE.\r
1787   If this interface is not supported, then return FALSE.\r
1788 \r
1789   @param[in]  P7Data       Pointer to the PKCS#7 message to verify.\r
1790   @param[in]  P7Length     Length of the PKCS#7 message in bytes.\r
1791   @param[in]  TrustedCert  Pointer to a trusted/root certificate encoded in DER, which\r
1792                            is used for certificate chain verification.\r
1793   @param[in]  CertLength   Length of the trusted certificate in bytes.\r
1794   @param[in]  InData       Pointer to the content to be verified.\r
1795   @param[in]  DataLength   Length of InData in bytes.\r
1796 \r
1797   @retval  TRUE  The specified PKCS#7 signed data is valid.\r
1798   @retval  FALSE Invalid PKCS#7 signed data.\r
1799   @retval  FALSE This interface is not supported.\r
1800 \r
1801 **/\r
1802 BOOLEAN\r
1803 EFIAPI\r
1804 Pkcs7Verify (\r
1805   IN  CONST UINT8  *P7Data,\r
1806   IN  UINTN        P7Length,\r
1807   IN  CONST UINT8  *TrustedCert,\r
1808   IN  UINTN        CertLength,\r
1809   IN  CONST UINT8  *InData,\r
1810   IN  UINTN        DataLength\r
1811   );\r
1812 \r
1813 /**\r
1814   Verifies the validility of a PE/COFF Authenticode Signature as described in "Windows\r
1815   Authenticode Portable Executable Signature Format".\r
1816 \r
1817   If AuthData is NULL, then return FALSE.\r
1818   If ImageHash is NULL, then return FALSE.\r
1819   If this interface is not supported, then return FALSE.\r
1820 \r
1821   @param[in]  AuthData     Pointer to the Authenticode Signature retrieved from signed\r
1822                            PE/COFF image to be verified.\r
1823   @param[in]  DataSize     Size of the Authenticode Signature in bytes.\r
1824   @param[in]  TrustedCert  Pointer to a trusted/root certificate encoded in DER, which\r
1825                            is used for certificate chain verification.\r
1826   @param[in]  CertSize     Size of the trusted certificate in bytes.\r
1827   @param[in]  ImageHash    Pointer to the original image file hash value. The procudure\r
1828                            for calculating the image hash value is described in Authenticode\r
1829                            specification.\r
1830   @param[in]  HashSize     Size of Image hash value in bytes.\r
1831 \r
1832   @retval  TRUE   The specified Authenticode Signature is valid.\r
1833   @retval  FALSE  Invalid Authenticode Signature.\r
1834   @retval  FALSE  This interface is not supported.\r
1835 \r
1836 **/\r
1837 BOOLEAN\r
1838 EFIAPI\r
1839 AuthenticodeVerify (\r
1840   IN  CONST UINT8  *AuthData,\r
1841   IN  UINTN        DataSize,\r
1842   IN  CONST UINT8  *TrustedCert,\r
1843   IN  UINTN        CertSize,\r
1844   IN  CONST UINT8  *ImageHash,\r
1845   IN  UINTN        HashSize\r
1846   );\r
1847 \r
1848 //=====================================================================================\r
1849 //    DH Key Exchange Primitive\r
1850 //=====================================================================================\r
1851 \r
1852 /**\r
1853   Allocates and Initializes one Diffie-Hellman Context for subsequent use.\r
1854 \r
1855   @return  Pointer to the Diffie-Hellman Context that has been initialized.\r
1856            If the allocations fails, DhNew() returns NULL.\r
1857            If the interface is not supported, DhNew() returns NULL.\r
1858 \r
1859 **/\r
1860 VOID *\r
1861 EFIAPI\r
1862 DhNew (\r
1863   VOID\r
1864   );\r
1865 \r
1866 /**\r
1867   Release the specified DH context.\r
1868 \r
1869   If the interface is not supported, then ASSERT().\r
1870 \r
1871   @param[in]  DhContext  Pointer to the DH context to be released.\r
1872 \r
1873 **/\r
1874 VOID\r
1875 EFIAPI\r
1876 DhFree (\r
1877   IN  VOID  *DhContext\r
1878   );\r
1879 \r
1880 /**\r
1881   Generates DH parameter.\r
1882 \r
1883   Given generator g, and length of prime number p in bits, this function generates p,\r
1884   and sets DH context according to value of g and p.\r
1885   \r
1886   Before this function can be invoked, pseudorandom number generator must be correctly\r
1887   initialized by RandomSeed().\r
1888 \r
1889   If DhContext is NULL, then return FALSE.\r
1890   If Prime is NULL, then return FALSE.\r
1891   If this interface is not supported, then return FALSE.\r
1892 \r
1893   @param[in, out]  DhContext    Pointer to the DH context.\r
1894   @param[in]       Generator    Value of generator.\r
1895   @param[in]       PrimeLength  Length in bits of prime to be generated.\r
1896   @param[out]      Prime        Pointer to the buffer to receive the generated prime number.\r
1897 \r
1898   @retval TRUE   DH pamameter generation succeeded.\r
1899   @retval FALSE  Value of Generator is not supported.\r
1900   @retval FALSE  PRNG fails to generate random prime number with PrimeLength.\r
1901   @retval FALSE  This interface is not supported.\r
1902 \r
1903 **/\r
1904 BOOLEAN\r
1905 EFIAPI\r
1906 DhGenerateParameter (\r
1907   IN OUT  VOID   *DhContext,\r
1908   IN      UINTN  Generator,\r
1909   IN      UINTN  PrimeLength,\r
1910   OUT     UINT8  *Prime\r
1911   );\r
1912 \r
1913 /**\r
1914   Sets generator and prime parameters for DH.\r
1915 \r
1916   Given generator g, and prime number p, this function and sets DH\r
1917   context accordingly.\r
1918 \r
1919   If DhContext is NULL, then return FALSE.\r
1920   If Prime is NULL, then return FALSE.\r
1921   If this interface is not supported, then return FALSE.\r
1922 \r
1923   @param[in, out]  DhContext    Pointer to the DH context.\r
1924   @param[in]       Generator    Value of generator.\r
1925   @param[in]       PrimeLength  Length in bits of prime to be generated.\r
1926   @param[in]       Prime        Pointer to the prime number.\r
1927 \r
1928   @retval TRUE   DH pamameter setting succeeded.\r
1929   @retval FALSE  Value of Generator is not supported.\r
1930   @retval FALSE  Value of Generator is not suitable for the Prime.\r
1931   @retval FALSE  Value of Prime is not a prime number.\r
1932   @retval FALSE  Value of Prime is not a safe prime number.\r
1933   @retval FALSE  This interface is not supported.\r
1934 \r
1935 **/\r
1936 BOOLEAN\r
1937 EFIAPI\r
1938 DhSetParameter (\r
1939   IN OUT  VOID         *DhContext,\r
1940   IN      UINTN        Generator,\r
1941   IN      UINTN        PrimeLength,\r
1942   IN      CONST UINT8  *Prime\r
1943   );\r
1944 \r
1945 /**\r
1946   Generates DH public key.\r
1947 \r
1948   This function generates random secret exponent, and computes the public key, which is \r
1949   returned via parameter PublicKey and PublicKeySize. DH context is updated accordingly.\r
1950   If the PublicKey buffer is too small to hold the public key, FALSE is returned and\r
1951   PublicKeySize is set to the required buffer size to obtain the public key.\r
1952 \r
1953   If DhContext is NULL, then return FALSE.\r
1954   If PublicKeySize is NULL, then return FALSE.\r
1955   If PublicKeySize is large enough but PublicKey is NULL, then return FALSE.\r
1956   If this interface is not supported, then return FALSE.\r
1957 \r
1958   @param[in, out]  DhContext      Pointer to the DH context.\r
1959   @param[out]      PublicKey      Pointer to the buffer to receive generated public key.\r
1960   @param[in, out]  PublicKeySize  On input, the size of PublicKey buffer in bytes.\r
1961                                  On output, the size of data returned in PublicKey buffer in bytes.\r
1962 \r
1963   @retval TRUE   DH public key generation succeeded.\r
1964   @retval FALSE  DH public key generation failed.\r
1965   @retval FALSE  PublicKeySize is not large enough.\r
1966   @retval FALSE  This interface is not supported.\r
1967 \r
1968 **/\r
1969 BOOLEAN\r
1970 EFIAPI\r
1971 DhGenerateKey (\r
1972   IN OUT  VOID   *DhContext,\r
1973   OUT     UINT8  *PublicKey,\r
1974   IN OUT  UINTN  *PublicKeySize\r
1975   );\r
1976 \r
1977 /**\r
1978   Computes exchanged common key.\r
1979 \r
1980   Given peer's public key, this function computes the exchanged common key, based on its own\r
1981   context including value of prime modulus and random secret exponent. \r
1982 \r
1983   If DhContext is NULL, then return FALSE.\r
1984   If PeerPublicKey is NULL, then return FALSE.\r
1985   If KeySize is NULL, then return FALSE.\r
1986   If KeySize is large enough but Key is NULL, then return FALSE.\r
1987   If this interface is not supported, then return FALSE.\r
1988 \r
1989   @param[in, out]  DhContext          Pointer to the DH context.\r
1990   @param[in]       PeerPublicKey      Pointer to the peer's public key.\r
1991   @param[in]       PeerPublicKeySize  Size of peer's public key in bytes.\r
1992   @param[out]      Key                Pointer to the buffer to receive generated key.\r
1993   @param[in, out]  KeySize            On input, the size of Key buffer in bytes.\r
1994                                      On output, the size of data returned in Key buffer in bytes.\r
1995 \r
1996   @retval TRUE   DH exchanged key generation succeeded.\r
1997   @retval FALSE  DH exchanged key generation failed.\r
1998   @retval FALSE  KeySize is not large enough.\r
1999   @retval FALSE  This interface is not supported.\r
2000 \r
2001 **/\r
2002 BOOLEAN\r
2003 EFIAPI\r
2004 DhComputeKey (\r
2005   IN OUT  VOID         *DhContext,\r
2006   IN      CONST UINT8  *PeerPublicKey,\r
2007   IN      UINTN        PeerPublicKeySize,\r
2008   OUT     UINT8        *Key,\r
2009   IN OUT  UINTN        *KeySize\r
2010   );\r
2011 \r
2012 //=====================================================================================\r
2013 //    Pseudo-Random Generation Primitive\r
2014 //=====================================================================================\r
2015 \r
2016 /**\r
2017   Sets up the seed value for the pseudorandom number generator.\r
2018 \r
2019   This function sets up the seed value for the pseudorandom number generator.\r
2020   If Seed is not NULL, then the seed passed in is used.\r
2021   If Seed is NULL, then default seed is used.\r
2022   If this interface is not supported, then return FALSE.\r
2023 \r
2024   @param[in]  Seed      Pointer to seed value.\r
2025                         If NULL, default seed is used.\r
2026   @param[in]  SeedSize  Size of seed value.\r
2027                         If Seed is NULL, this parameter is ignored.\r
2028 \r
2029   @retval TRUE   Pseudorandom number generator has enough entropy for random generation.\r
2030   @retval FALSE  Pseudorandom number generator does not have enough entropy for random generation.\r
2031   @retval FALSE  This interface is not supported.\r
2032 \r
2033 **/\r
2034 BOOLEAN\r
2035 EFIAPI\r
2036 RandomSeed (\r
2037   IN  CONST  UINT8  *Seed  OPTIONAL,\r
2038   IN  UINTN         SeedSize\r
2039   );\r
2040 \r
2041 /**\r
2042   Generates a pseudorandom byte stream of the specified size.\r
2043 \r
2044   If Output is NULL, then return FALSE.\r
2045   If this interface is not supported, then return FALSE.\r
2046 \r
2047   @param[out]  Output  Pointer to buffer to receive random value.\r
2048   @param[in]   Size    Size of randome bytes to generate.\r
2049 \r
2050   @retval TRUE   Pseudorandom byte stream generated successfully.\r
2051   @retval FALSE  Pseudorandom number generator fails to generate due to lack of entropy.\r
2052   @retval FALSE  This interface is not supported.\r
2053 \r
2054 **/\r
2055 BOOLEAN\r
2056 EFIAPI\r
2057 RandomBytes (\r
2058   OUT  UINT8  *Output,\r
2059   IN   UINTN  Size\r
2060   );\r
2061 \r
2062 #endif // __BASE_CRYPT_LIB_H__\r