CryptoPkg/BaseCryptLib.h: Add new API VerifyEKUsInPkcs7Signature
[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 - 2018, Intel Corporation. All rights reserved.<BR>\r
8 SPDX-License-Identifier: BSD-2-Clause-Patent\r
9 \r
10 **/\r
11 \r
12 #ifndef __BASE_CRYPT_LIB_H__\r
13 #define __BASE_CRYPT_LIB_H__\r
14 \r
15 #include <Uefi/UefiBaseType.h>\r
16 \r
17 ///\r
18 /// MD4 digest size in bytes\r
19 ///\r
20 #define MD4_DIGEST_SIZE     16\r
21 \r
22 ///\r
23 /// MD5 digest size in bytes\r
24 ///\r
25 #define MD5_DIGEST_SIZE     16\r
26 \r
27 ///\r
28 /// SHA-1 digest size in bytes.\r
29 ///\r
30 #define SHA1_DIGEST_SIZE    20\r
31 \r
32 ///\r
33 /// SHA-256 digest size in bytes\r
34 ///\r
35 #define SHA256_DIGEST_SIZE  32\r
36 \r
37 ///\r
38 /// SHA-384 digest size in bytes\r
39 ///\r
40 #define SHA384_DIGEST_SIZE  48\r
41 \r
42 ///\r
43 /// SHA-512 digest size in bytes\r
44 ///\r
45 #define SHA512_DIGEST_SIZE  64\r
46 \r
47 ///\r
48 /// TDES block size in bytes\r
49 ///\r
50 #define TDES_BLOCK_SIZE     8\r
51 \r
52 ///\r
53 /// AES block size in bytes\r
54 ///\r
55 #define AES_BLOCK_SIZE      16\r
56 \r
57 ///\r
58 /// RSA Key Tags Definition used in RsaSetKey() function for key component identification.\r
59 ///\r
60 typedef enum {\r
61   RsaKeyN,      ///< RSA public Modulus (N)\r
62   RsaKeyE,      ///< RSA Public exponent (e)\r
63   RsaKeyD,      ///< RSA Private exponent (d)\r
64   RsaKeyP,      ///< RSA secret prime factor of Modulus (p)\r
65   RsaKeyQ,      ///< RSA secret prime factor of Modules (q)\r
66   RsaKeyDp,     ///< p's CRT exponent (== d mod (p - 1))\r
67   RsaKeyDq,     ///< q's CRT exponent (== d mod (q - 1))\r
68   RsaKeyQInv    ///< The CRT coefficient (== 1/q mod p)\r
69 } RSA_KEY_TAG;\r
70 \r
71 //=====================================================================================\r
72 //    One-Way Cryptographic Hash Primitives\r
73 //=====================================================================================\r
74 \r
75 /**\r
76   Retrieves the size, in bytes, of the context buffer required for MD4 hash operations.\r
77 \r
78   If this interface is not supported, then return zero.\r
79 \r
80   @return  The size, in bytes, of the context buffer required for MD4 hash operations.\r
81   @retval  0   This interface is not supported.\r
82 \r
83 **/\r
84 UINTN\r
85 EFIAPI\r
86 Md4GetContextSize (\r
87   VOID\r
88   );\r
89 \r
90 /**\r
91   Initializes user-supplied memory pointed by Md4Context as MD4 hash context for\r
92   subsequent use.\r
93 \r
94   If Md4Context is NULL, then return FALSE.\r
95   If this interface is not supported, then return FALSE.\r
96 \r
97   @param[out]  Md4Context  Pointer to MD4 context being initialized.\r
98 \r
99   @retval TRUE   MD4 context initialization succeeded.\r
100   @retval FALSE  MD4 context initialization failed.\r
101   @retval FALSE  This interface is not supported.\r
102 \r
103 **/\r
104 BOOLEAN\r
105 EFIAPI\r
106 Md4Init (\r
107   OUT  VOID  *Md4Context\r
108   );\r
109 \r
110 /**\r
111   Makes a copy of an existing MD4 context.\r
112 \r
113   If Md4Context is NULL, then return FALSE.\r
114   If NewMd4Context is NULL, then return FALSE.\r
115   If this interface is not supported, then return FALSE.\r
116 \r
117   @param[in]  Md4Context     Pointer to MD4 context being copied.\r
118   @param[out] NewMd4Context  Pointer to new MD4 context.\r
119 \r
120   @retval TRUE   MD4 context copy succeeded.\r
121   @retval FALSE  MD4 context copy failed.\r
122   @retval FALSE  This interface is not supported.\r
123 \r
124 **/\r
125 BOOLEAN\r
126 EFIAPI\r
127 Md4Duplicate (\r
128   IN   CONST VOID  *Md4Context,\r
129   OUT  VOID        *NewMd4Context\r
130   );\r
131 \r
132 /**\r
133   Digests the input data and updates MD4 context.\r
134 \r
135   This function performs MD4 digest on a data buffer of the specified size.\r
136   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
137   MD4 context should be already correctly initialized by Md4Init(), and should not be finalized\r
138   by Md4Final(). Behavior with invalid context is undefined.\r
139 \r
140   If Md4Context is NULL, then return FALSE.\r
141   If this interface is not supported, then return FALSE.\r
142 \r
143   @param[in, out]  Md4Context  Pointer to the MD4 context.\r
144   @param[in]       Data        Pointer to the buffer containing the data to be hashed.\r
145   @param[in]       DataSize    Size of Data buffer in bytes.\r
146 \r
147   @retval TRUE   MD4 data digest succeeded.\r
148   @retval FALSE  MD4 data digest failed.\r
149   @retval FALSE  This interface is not supported.\r
150 \r
151 **/\r
152 BOOLEAN\r
153 EFIAPI\r
154 Md4Update (\r
155   IN OUT  VOID        *Md4Context,\r
156   IN      CONST VOID  *Data,\r
157   IN      UINTN       DataSize\r
158   );\r
159 \r
160 /**\r
161   Completes computation of the MD4 digest value.\r
162 \r
163   This function completes MD4 hash computation and retrieves the digest value into\r
164   the specified memory. After this function has been called, the MD4 context cannot\r
165   be used again.\r
166   MD4 context should be already correctly initialized by Md4Init(), and should not be\r
167   finalized by Md4Final(). Behavior with invalid MD4 context is undefined.\r
168 \r
169   If Md4Context is NULL, then return FALSE.\r
170   If HashValue is NULL, then return FALSE.\r
171   If this interface is not supported, then return FALSE.\r
172 \r
173   @param[in, out]  Md4Context  Pointer to the MD4 context.\r
174   @param[out]      HashValue   Pointer to a buffer that receives the MD4 digest\r
175                                value (16 bytes).\r
176 \r
177   @retval TRUE   MD4 digest computation succeeded.\r
178   @retval FALSE  MD4 digest computation failed.\r
179   @retval FALSE  This interface is not supported.\r
180 \r
181 **/\r
182 BOOLEAN\r
183 EFIAPI\r
184 Md4Final (\r
185   IN OUT  VOID   *Md4Context,\r
186   OUT     UINT8  *HashValue\r
187   );\r
188 \r
189 /**\r
190   Computes the MD4 message digest of a input data buffer.\r
191 \r
192   This function performs the MD4 message digest of a given data buffer, and places\r
193   the digest value into the specified memory.\r
194 \r
195   If this interface is not supported, then return FALSE.\r
196 \r
197   @param[in]   Data        Pointer to the buffer containing the data to be hashed.\r
198   @param[in]   DataSize    Size of Data buffer in bytes.\r
199   @param[out]  HashValue   Pointer to a buffer that receives the MD4 digest\r
200                            value (16 bytes).\r
201 \r
202   @retval TRUE   MD4 digest computation succeeded.\r
203   @retval FALSE  MD4 digest computation failed.\r
204   @retval FALSE  This interface is not supported.\r
205 \r
206 **/\r
207 BOOLEAN\r
208 EFIAPI\r
209 Md4HashAll (\r
210   IN   CONST VOID  *Data,\r
211   IN   UINTN       DataSize,\r
212   OUT  UINT8       *HashValue\r
213   );\r
214 \r
215 /**\r
216   Retrieves the size, in bytes, of the context buffer required for MD5 hash operations.\r
217 \r
218   If this interface is not supported, then return zero.\r
219 \r
220   @return  The size, in bytes, of the context buffer required for MD5 hash operations.\r
221   @retval  0   This interface is not supported.\r
222 \r
223 **/\r
224 UINTN\r
225 EFIAPI\r
226 Md5GetContextSize (\r
227   VOID\r
228   );\r
229 \r
230 /**\r
231   Initializes user-supplied memory pointed by Md5Context as MD5 hash context for\r
232   subsequent use.\r
233 \r
234   If Md5Context is NULL, then return FALSE.\r
235   If this interface is not supported, then return FALSE.\r
236 \r
237   @param[out]  Md5Context  Pointer to MD5 context being initialized.\r
238 \r
239   @retval TRUE   MD5 context initialization succeeded.\r
240   @retval FALSE  MD5 context initialization failed.\r
241   @retval FALSE  This interface is not supported.\r
242 \r
243 **/\r
244 BOOLEAN\r
245 EFIAPI\r
246 Md5Init (\r
247   OUT  VOID  *Md5Context\r
248   );\r
249 \r
250 /**\r
251   Makes a copy of an existing MD5 context.\r
252 \r
253   If Md5Context is NULL, then return FALSE.\r
254   If NewMd5Context is NULL, then return FALSE.\r
255   If this interface is not supported, then return FALSE.\r
256 \r
257   @param[in]  Md5Context     Pointer to MD5 context being copied.\r
258   @param[out] NewMd5Context  Pointer to new MD5 context.\r
259 \r
260   @retval TRUE   MD5 context copy succeeded.\r
261   @retval FALSE  MD5 context copy failed.\r
262   @retval FALSE  This interface is not supported.\r
263 \r
264 **/\r
265 BOOLEAN\r
266 EFIAPI\r
267 Md5Duplicate (\r
268   IN   CONST VOID  *Md5Context,\r
269   OUT  VOID        *NewMd5Context\r
270   );\r
271 \r
272 /**\r
273   Digests the input data and updates MD5 context.\r
274 \r
275   This function performs MD5 digest on a data buffer of the specified size.\r
276   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
277   MD5 context should be already correctly initialized by Md5Init(), and should not be finalized\r
278   by Md5Final(). Behavior with invalid context is undefined.\r
279 \r
280   If Md5Context is NULL, then return FALSE.\r
281   If this interface is not supported, then return FALSE.\r
282 \r
283   @param[in, out]  Md5Context  Pointer to the MD5 context.\r
284   @param[in]       Data        Pointer to the buffer containing the data to be hashed.\r
285   @param[in]       DataSize    Size of Data buffer in bytes.\r
286 \r
287   @retval TRUE   MD5 data digest succeeded.\r
288   @retval FALSE  MD5 data digest failed.\r
289   @retval FALSE  This interface is not supported.\r
290 \r
291 **/\r
292 BOOLEAN\r
293 EFIAPI\r
294 Md5Update (\r
295   IN OUT  VOID        *Md5Context,\r
296   IN      CONST VOID  *Data,\r
297   IN      UINTN       DataSize\r
298   );\r
299 \r
300 /**\r
301   Completes computation of the MD5 digest value.\r
302 \r
303   This function completes MD5 hash computation and retrieves the digest value into\r
304   the specified memory. After this function has been called, the MD5 context cannot\r
305   be used again.\r
306   MD5 context should be already correctly initialized by Md5Init(), and should not be\r
307   finalized by Md5Final(). Behavior with invalid MD5 context is undefined.\r
308 \r
309   If Md5Context is NULL, then return FALSE.\r
310   If HashValue is NULL, then return FALSE.\r
311   If this interface is not supported, then return FALSE.\r
312 \r
313   @param[in, out]  Md5Context  Pointer to the MD5 context.\r
314   @param[out]      HashValue   Pointer to a buffer that receives the MD5 digest\r
315                                value (16 bytes).\r
316 \r
317   @retval TRUE   MD5 digest computation succeeded.\r
318   @retval FALSE  MD5 digest computation failed.\r
319   @retval FALSE  This interface is not supported.\r
320 \r
321 **/\r
322 BOOLEAN\r
323 EFIAPI\r
324 Md5Final (\r
325   IN OUT  VOID   *Md5Context,\r
326   OUT     UINT8  *HashValue\r
327   );\r
328 \r
329 /**\r
330   Computes the MD5 message digest of a input data buffer.\r
331 \r
332   This function performs the MD5 message digest of a given data buffer, and places\r
333   the digest value into the specified memory.\r
334 \r
335   If this interface is not supported, then return FALSE.\r
336 \r
337   @param[in]   Data        Pointer to the buffer containing the data to be hashed.\r
338   @param[in]   DataSize    Size of Data buffer in bytes.\r
339   @param[out]  HashValue   Pointer to a buffer that receives the MD5 digest\r
340                            value (16 bytes).\r
341 \r
342   @retval TRUE   MD5 digest computation succeeded.\r
343   @retval FALSE  MD5 digest computation failed.\r
344   @retval FALSE  This interface is not supported.\r
345 \r
346 **/\r
347 BOOLEAN\r
348 EFIAPI\r
349 Md5HashAll (\r
350   IN   CONST VOID  *Data,\r
351   IN   UINTN       DataSize,\r
352   OUT  UINT8       *HashValue\r
353   );\r
354 \r
355 /**\r
356   Retrieves the size, in bytes, of the context buffer required for SHA-1 hash operations.\r
357 \r
358   If this interface is not supported, then return zero.\r
359 \r
360   @return  The size, in bytes, of the context buffer required for SHA-1 hash operations.\r
361   @retval  0   This interface is not supported.\r
362 \r
363 **/\r
364 UINTN\r
365 EFIAPI\r
366 Sha1GetContextSize (\r
367   VOID\r
368   );\r
369 \r
370 /**\r
371   Initializes user-supplied memory pointed by Sha1Context as SHA-1 hash context for\r
372   subsequent use.\r
373 \r
374   If Sha1Context is NULL, then return FALSE.\r
375   If this interface is not supported, then return FALSE.\r
376 \r
377   @param[out]  Sha1Context  Pointer to SHA-1 context being initialized.\r
378 \r
379   @retval TRUE   SHA-1 context initialization succeeded.\r
380   @retval FALSE  SHA-1 context initialization failed.\r
381   @retval FALSE  This interface is not supported.\r
382 \r
383 **/\r
384 BOOLEAN\r
385 EFIAPI\r
386 Sha1Init (\r
387   OUT  VOID  *Sha1Context\r
388   );\r
389 \r
390 /**\r
391   Makes a copy of an existing SHA-1 context.\r
392 \r
393   If Sha1Context is NULL, then return FALSE.\r
394   If NewSha1Context is NULL, then return FALSE.\r
395   If this interface is not supported, then return FALSE.\r
396 \r
397   @param[in]  Sha1Context     Pointer to SHA-1 context being copied.\r
398   @param[out] NewSha1Context  Pointer to new SHA-1 context.\r
399 \r
400   @retval TRUE   SHA-1 context copy succeeded.\r
401   @retval FALSE  SHA-1 context copy failed.\r
402   @retval FALSE  This interface is not supported.\r
403 \r
404 **/\r
405 BOOLEAN\r
406 EFIAPI\r
407 Sha1Duplicate (\r
408   IN   CONST VOID  *Sha1Context,\r
409   OUT  VOID        *NewSha1Context\r
410   );\r
411 \r
412 /**\r
413   Digests the input data and updates SHA-1 context.\r
414 \r
415   This function performs SHA-1 digest on a data buffer of the specified size.\r
416   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
417   SHA-1 context should be already correctly initialized by Sha1Init(), and should not be finalized\r
418   by Sha1Final(). Behavior with invalid context is undefined.\r
419 \r
420   If Sha1Context is NULL, then return FALSE.\r
421   If this interface is not supported, then return FALSE.\r
422 \r
423   @param[in, out]  Sha1Context  Pointer to the SHA-1 context.\r
424   @param[in]       Data         Pointer to the buffer containing the data to be hashed.\r
425   @param[in]       DataSize     Size of Data buffer in bytes.\r
426 \r
427   @retval TRUE   SHA-1 data digest succeeded.\r
428   @retval FALSE  SHA-1 data digest failed.\r
429   @retval FALSE  This interface is not supported.\r
430 \r
431 **/\r
432 BOOLEAN\r
433 EFIAPI\r
434 Sha1Update (\r
435   IN OUT  VOID        *Sha1Context,\r
436   IN      CONST VOID  *Data,\r
437   IN      UINTN       DataSize\r
438   );\r
439 \r
440 /**\r
441   Completes computation of the SHA-1 digest value.\r
442 \r
443   This function completes SHA-1 hash computation and retrieves the digest value into\r
444   the specified memory. After this function has been called, the SHA-1 context cannot\r
445   be used again.\r
446   SHA-1 context should be already correctly initialized by Sha1Init(), and should not be\r
447   finalized by Sha1Final(). Behavior with invalid SHA-1 context is undefined.\r
448 \r
449   If Sha1Context is NULL, then return FALSE.\r
450   If HashValue is NULL, then return FALSE.\r
451   If this interface is not supported, then return FALSE.\r
452 \r
453   @param[in, out]  Sha1Context  Pointer to the SHA-1 context.\r
454   @param[out]      HashValue    Pointer to a buffer that receives the SHA-1 digest\r
455                                 value (20 bytes).\r
456 \r
457   @retval TRUE   SHA-1 digest computation succeeded.\r
458   @retval FALSE  SHA-1 digest computation failed.\r
459   @retval FALSE  This interface is not supported.\r
460 \r
461 **/\r
462 BOOLEAN\r
463 EFIAPI\r
464 Sha1Final (\r
465   IN OUT  VOID   *Sha1Context,\r
466   OUT     UINT8  *HashValue\r
467   );\r
468 \r
469 /**\r
470   Computes the SHA-1 message digest of a input data buffer.\r
471 \r
472   This function performs the SHA-1 message digest of a given data buffer, and places\r
473   the digest value into the specified memory.\r
474 \r
475   If this interface is not supported, then return FALSE.\r
476 \r
477   @param[in]   Data        Pointer to the buffer containing the data to be hashed.\r
478   @param[in]   DataSize    Size of Data buffer in bytes.\r
479   @param[out]  HashValue   Pointer to a buffer that receives the SHA-1 digest\r
480                            value (20 bytes).\r
481 \r
482   @retval TRUE   SHA-1 digest computation succeeded.\r
483   @retval FALSE  SHA-1 digest computation failed.\r
484   @retval FALSE  This interface is not supported.\r
485 \r
486 **/\r
487 BOOLEAN\r
488 EFIAPI\r
489 Sha1HashAll (\r
490   IN   CONST VOID  *Data,\r
491   IN   UINTN       DataSize,\r
492   OUT  UINT8       *HashValue\r
493   );\r
494 \r
495 /**\r
496   Retrieves the size, in bytes, of the context buffer required for SHA-256 hash operations.\r
497 \r
498   @return  The size, in bytes, of the context buffer required for SHA-256 hash operations.\r
499 \r
500 **/\r
501 UINTN\r
502 EFIAPI\r
503 Sha256GetContextSize (\r
504   VOID\r
505   );\r
506 \r
507 /**\r
508   Initializes user-supplied memory pointed by Sha256Context as SHA-256 hash context for\r
509   subsequent use.\r
510 \r
511   If Sha256Context is NULL, then return FALSE.\r
512 \r
513   @param[out]  Sha256Context  Pointer to SHA-256 context being initialized.\r
514 \r
515   @retval TRUE   SHA-256 context initialization succeeded.\r
516   @retval FALSE  SHA-256 context initialization failed.\r
517 \r
518 **/\r
519 BOOLEAN\r
520 EFIAPI\r
521 Sha256Init (\r
522   OUT  VOID  *Sha256Context\r
523   );\r
524 \r
525 /**\r
526   Makes a copy of an existing SHA-256 context.\r
527 \r
528   If Sha256Context is NULL, then return FALSE.\r
529   If NewSha256Context is NULL, then return FALSE.\r
530   If this interface is not supported, then return FALSE.\r
531 \r
532   @param[in]  Sha256Context     Pointer to SHA-256 context being copied.\r
533   @param[out] NewSha256Context  Pointer to new SHA-256 context.\r
534 \r
535   @retval TRUE   SHA-256 context copy succeeded.\r
536   @retval FALSE  SHA-256 context copy failed.\r
537   @retval FALSE  This interface is not supported.\r
538 \r
539 **/\r
540 BOOLEAN\r
541 EFIAPI\r
542 Sha256Duplicate (\r
543   IN   CONST VOID  *Sha256Context,\r
544   OUT  VOID        *NewSha256Context\r
545   );\r
546 \r
547 /**\r
548   Digests the input data and updates SHA-256 context.\r
549 \r
550   This function performs SHA-256 digest on a data buffer of the specified size.\r
551   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
552   SHA-256 context should be already correctly initialized by Sha256Init(), and should not be finalized\r
553   by Sha256Final(). Behavior with invalid context is undefined.\r
554 \r
555   If Sha256Context is NULL, then return FALSE.\r
556 \r
557   @param[in, out]  Sha256Context  Pointer to the SHA-256 context.\r
558   @param[in]       Data           Pointer to the buffer containing the data to be hashed.\r
559   @param[in]       DataSize       Size of Data buffer in bytes.\r
560 \r
561   @retval TRUE   SHA-256 data digest succeeded.\r
562   @retval FALSE  SHA-256 data digest failed.\r
563 \r
564 **/\r
565 BOOLEAN\r
566 EFIAPI\r
567 Sha256Update (\r
568   IN OUT  VOID        *Sha256Context,\r
569   IN      CONST VOID  *Data,\r
570   IN      UINTN       DataSize\r
571   );\r
572 \r
573 /**\r
574   Completes computation of the SHA-256 digest value.\r
575 \r
576   This function completes SHA-256 hash computation and retrieves the digest value into\r
577   the specified memory. After this function has been called, the SHA-256 context cannot\r
578   be used again.\r
579   SHA-256 context should be already correctly initialized by Sha256Init(), and should not be\r
580   finalized by Sha256Final(). Behavior with invalid SHA-256 context is undefined.\r
581 \r
582   If Sha256Context is NULL, then return FALSE.\r
583   If HashValue is NULL, then return FALSE.\r
584 \r
585   @param[in, out]  Sha256Context  Pointer to the SHA-256 context.\r
586   @param[out]      HashValue      Pointer to a buffer that receives the SHA-256 digest\r
587                                   value (32 bytes).\r
588 \r
589   @retval TRUE   SHA-256 digest computation succeeded.\r
590   @retval FALSE  SHA-256 digest computation failed.\r
591 \r
592 **/\r
593 BOOLEAN\r
594 EFIAPI\r
595 Sha256Final (\r
596   IN OUT  VOID   *Sha256Context,\r
597   OUT     UINT8  *HashValue\r
598   );\r
599 \r
600 /**\r
601   Computes the SHA-256 message digest of a input data buffer.\r
602 \r
603   This function performs the SHA-256 message digest of a given data buffer, and places\r
604   the digest value into the specified memory.\r
605 \r
606   If this interface is not supported, then return FALSE.\r
607 \r
608   @param[in]   Data        Pointer to the buffer containing the data to be hashed.\r
609   @param[in]   DataSize    Size of Data buffer in bytes.\r
610   @param[out]  HashValue   Pointer to a buffer that receives the SHA-256 digest\r
611                            value (32 bytes).\r
612 \r
613   @retval TRUE   SHA-256 digest computation succeeded.\r
614   @retval FALSE  SHA-256 digest computation failed.\r
615   @retval FALSE  This interface is not supported.\r
616 \r
617 **/\r
618 BOOLEAN\r
619 EFIAPI\r
620 Sha256HashAll (\r
621   IN   CONST VOID  *Data,\r
622   IN   UINTN       DataSize,\r
623   OUT  UINT8       *HashValue\r
624   );\r
625 \r
626 /**\r
627   Retrieves the size, in bytes, of the context buffer required for SHA-384 hash operations.\r
628 \r
629   @return  The size, in bytes, of the context buffer required for SHA-384 hash operations.\r
630 \r
631 **/\r
632 UINTN\r
633 EFIAPI\r
634 Sha384GetContextSize (\r
635   VOID\r
636   );\r
637 \r
638 /**\r
639   Initializes user-supplied memory pointed by Sha384Context as SHA-384 hash context for\r
640   subsequent use.\r
641 \r
642   If Sha384Context is NULL, then return FALSE.\r
643 \r
644   @param[out]  Sha384Context  Pointer to SHA-384 context being initialized.\r
645 \r
646   @retval TRUE   SHA-384 context initialization succeeded.\r
647   @retval FALSE  SHA-384 context initialization failed.\r
648 \r
649 **/\r
650 BOOLEAN\r
651 EFIAPI\r
652 Sha384Init (\r
653   OUT  VOID  *Sha384Context\r
654   );\r
655 \r
656 /**\r
657   Makes a copy of an existing SHA-384 context.\r
658 \r
659   If Sha384Context is NULL, then return FALSE.\r
660   If NewSha384Context is NULL, then return FALSE.\r
661   If this interface is not supported, then return FALSE.\r
662 \r
663   @param[in]  Sha384Context     Pointer to SHA-384 context being copied.\r
664   @param[out] NewSha384Context  Pointer to new SHA-384 context.\r
665 \r
666   @retval TRUE   SHA-384 context copy succeeded.\r
667   @retval FALSE  SHA-384 context copy failed.\r
668   @retval FALSE  This interface is not supported.\r
669 \r
670 **/\r
671 BOOLEAN\r
672 EFIAPI\r
673 Sha384Duplicate (\r
674   IN   CONST VOID  *Sha384Context,\r
675   OUT  VOID        *NewSha384Context\r
676   );\r
677 \r
678 /**\r
679   Digests the input data and updates SHA-384 context.\r
680 \r
681   This function performs SHA-384 digest on a data buffer of the specified size.\r
682   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
683   SHA-384 context should be already correctly initialized by Sha384Init(), and should not be finalized\r
684   by Sha384Final(). Behavior with invalid context is undefined.\r
685 \r
686   If Sha384Context is NULL, then return FALSE.\r
687 \r
688   @param[in, out]  Sha384Context  Pointer to the SHA-384 context.\r
689   @param[in]       Data           Pointer to the buffer containing the data to be hashed.\r
690   @param[in]       DataSize       Size of Data buffer in bytes.\r
691 \r
692   @retval TRUE   SHA-384 data digest succeeded.\r
693   @retval FALSE  SHA-384 data digest failed.\r
694 \r
695 **/\r
696 BOOLEAN\r
697 EFIAPI\r
698 Sha384Update (\r
699   IN OUT  VOID        *Sha384Context,\r
700   IN      CONST VOID  *Data,\r
701   IN      UINTN       DataSize\r
702   );\r
703 \r
704 /**\r
705   Completes computation of the SHA-384 digest value.\r
706 \r
707   This function completes SHA-384 hash computation and retrieves the digest value into\r
708   the specified memory. After this function has been called, the SHA-384 context cannot\r
709   be used again.\r
710   SHA-384 context should be already correctly initialized by Sha384Init(), and should not be\r
711   finalized by Sha384Final(). Behavior with invalid SHA-384 context is undefined.\r
712 \r
713   If Sha384Context is NULL, then return FALSE.\r
714   If HashValue is NULL, then return FALSE.\r
715 \r
716   @param[in, out]  Sha384Context  Pointer to the SHA-384 context.\r
717   @param[out]      HashValue      Pointer to a buffer that receives the SHA-384 digest\r
718                                   value (48 bytes).\r
719 \r
720   @retval TRUE   SHA-384 digest computation succeeded.\r
721   @retval FALSE  SHA-384 digest computation failed.\r
722 \r
723 **/\r
724 BOOLEAN\r
725 EFIAPI\r
726 Sha384Final (\r
727   IN OUT  VOID   *Sha384Context,\r
728   OUT     UINT8  *HashValue\r
729   );\r
730 \r
731 /**\r
732   Computes the SHA-384 message digest of a input data buffer.\r
733 \r
734   This function performs the SHA-384 message digest of a given data buffer, and places\r
735   the digest value into the specified memory.\r
736 \r
737   If this interface is not supported, then return FALSE.\r
738 \r
739   @param[in]   Data        Pointer to the buffer containing the data to be hashed.\r
740   @param[in]   DataSize    Size of Data buffer in bytes.\r
741   @param[out]  HashValue   Pointer to a buffer that receives the SHA-384 digest\r
742                            value (48 bytes).\r
743 \r
744   @retval TRUE   SHA-384 digest computation succeeded.\r
745   @retval FALSE  SHA-384 digest computation failed.\r
746   @retval FALSE  This interface is not supported.\r
747 \r
748 **/\r
749 BOOLEAN\r
750 EFIAPI\r
751 Sha384HashAll (\r
752   IN   CONST VOID  *Data,\r
753   IN   UINTN       DataSize,\r
754   OUT  UINT8       *HashValue\r
755   );\r
756 \r
757 /**\r
758   Retrieves the size, in bytes, of the context buffer required for SHA-512 hash operations.\r
759 \r
760   @return  The size, in bytes, of the context buffer required for SHA-512 hash operations.\r
761 \r
762 **/\r
763 UINTN\r
764 EFIAPI\r
765 Sha512GetContextSize (\r
766   VOID\r
767   );\r
768 \r
769 /**\r
770   Initializes user-supplied memory pointed by Sha512Context as SHA-512 hash context for\r
771   subsequent use.\r
772 \r
773   If Sha512Context is NULL, then return FALSE.\r
774 \r
775   @param[out]  Sha512Context  Pointer to SHA-512 context being initialized.\r
776 \r
777   @retval TRUE   SHA-512 context initialization succeeded.\r
778   @retval FALSE  SHA-512 context initialization failed.\r
779 \r
780 **/\r
781 BOOLEAN\r
782 EFIAPI\r
783 Sha512Init (\r
784   OUT  VOID  *Sha512Context\r
785   );\r
786 \r
787 /**\r
788   Makes a copy of an existing SHA-512 context.\r
789 \r
790   If Sha512Context is NULL, then return FALSE.\r
791   If NewSha512Context is NULL, then return FALSE.\r
792   If this interface is not supported, then return FALSE.\r
793 \r
794   @param[in]  Sha512Context     Pointer to SHA-512 context being copied.\r
795   @param[out] NewSha512Context  Pointer to new SHA-512 context.\r
796 \r
797   @retval TRUE   SHA-512 context copy succeeded.\r
798   @retval FALSE  SHA-512 context copy failed.\r
799   @retval FALSE  This interface is not supported.\r
800 \r
801 **/\r
802 BOOLEAN\r
803 EFIAPI\r
804 Sha512Duplicate (\r
805   IN   CONST VOID  *Sha512Context,\r
806   OUT  VOID        *NewSha512Context\r
807   );\r
808 \r
809 /**\r
810   Digests the input data and updates SHA-512 context.\r
811 \r
812   This function performs SHA-512 digest on a data buffer of the specified size.\r
813   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
814   SHA-512 context should be already correctly initialized by Sha512Init(), and should not be finalized\r
815   by Sha512Final(). Behavior with invalid context is undefined.\r
816 \r
817   If Sha512Context is NULL, then return FALSE.\r
818 \r
819   @param[in, out]  Sha512Context  Pointer to the SHA-512 context.\r
820   @param[in]       Data           Pointer to the buffer containing the data to be hashed.\r
821   @param[in]       DataSize       Size of Data buffer in bytes.\r
822 \r
823   @retval TRUE   SHA-512 data digest succeeded.\r
824   @retval FALSE  SHA-512 data digest failed.\r
825 \r
826 **/\r
827 BOOLEAN\r
828 EFIAPI\r
829 Sha512Update (\r
830   IN OUT  VOID        *Sha512Context,\r
831   IN      CONST VOID  *Data,\r
832   IN      UINTN       DataSize\r
833   );\r
834 \r
835 /**\r
836   Completes computation of the SHA-512 digest value.\r
837 \r
838   This function completes SHA-512 hash computation and retrieves the digest value into\r
839   the specified memory. After this function has been called, the SHA-512 context cannot\r
840   be used again.\r
841   SHA-512 context should be already correctly initialized by Sha512Init(), and should not be\r
842   finalized by Sha512Final(). Behavior with invalid SHA-512 context is undefined.\r
843 \r
844   If Sha512Context is NULL, then return FALSE.\r
845   If HashValue is NULL, then return FALSE.\r
846 \r
847   @param[in, out]  Sha512Context  Pointer to the SHA-512 context.\r
848   @param[out]      HashValue      Pointer to a buffer that receives the SHA-512 digest\r
849                                   value (64 bytes).\r
850 \r
851   @retval TRUE   SHA-512 digest computation succeeded.\r
852   @retval FALSE  SHA-512 digest computation failed.\r
853 \r
854 **/\r
855 BOOLEAN\r
856 EFIAPI\r
857 Sha512Final (\r
858   IN OUT  VOID   *Sha512Context,\r
859   OUT     UINT8  *HashValue\r
860   );\r
861 \r
862 /**\r
863   Computes the SHA-512 message digest of a input data buffer.\r
864 \r
865   This function performs the SHA-512 message digest of a given data buffer, and places\r
866   the digest value into the specified memory.\r
867 \r
868   If this interface is not supported, then return FALSE.\r
869 \r
870   @param[in]   Data        Pointer to the buffer containing the data to be hashed.\r
871   @param[in]   DataSize    Size of Data buffer in bytes.\r
872   @param[out]  HashValue   Pointer to a buffer that receives the SHA-512 digest\r
873                            value (64 bytes).\r
874 \r
875   @retval TRUE   SHA-512 digest computation succeeded.\r
876   @retval FALSE  SHA-512 digest computation failed.\r
877   @retval FALSE  This interface is not supported.\r
878 \r
879 **/\r
880 BOOLEAN\r
881 EFIAPI\r
882 Sha512HashAll (\r
883   IN   CONST VOID  *Data,\r
884   IN   UINTN       DataSize,\r
885   OUT  UINT8       *HashValue\r
886   );\r
887 \r
888 //=====================================================================================\r
889 //    MAC (Message Authentication Code) Primitive\r
890 //=====================================================================================\r
891 \r
892 /**\r
893   Retrieves the size, in bytes, of the context buffer required for HMAC-MD5 operations.\r
894   (NOTE: This API is deprecated.\r
895          Use HmacMd5New() / HmacMd5Free() for HMAC-MD5 Context operations.)\r
896 \r
897   If this interface is not supported, then return zero.\r
898 \r
899   @return  The size, in bytes, of the context buffer required for HMAC-MD5 operations.\r
900   @retval  0   This interface is not supported.\r
901 \r
902 **/\r
903 UINTN\r
904 EFIAPI\r
905 HmacMd5GetContextSize (\r
906   VOID\r
907   );\r
908 \r
909 /**\r
910   Allocates and initializes one HMAC_CTX context for subsequent HMAC-MD5 use.\r
911 \r
912   If this interface is not supported, then return NULL.\r
913 \r
914   @return  Pointer to the HMAC_CTX context that has been initialized.\r
915            If the allocations fails, HmacMd5New() returns NULL.\r
916   @retval  NULL  This interface is not supported.\r
917 \r
918 **/\r
919 VOID *\r
920 EFIAPI\r
921 HmacMd5New (\r
922   VOID\r
923   );\r
924 \r
925 /**\r
926   Release the specified HMAC_CTX context.\r
927 \r
928   If this interface is not supported, then do nothing.\r
929 \r
930   @param[in]  HmacMd5Ctx  Pointer to the HMAC_CTX context to be released.\r
931 \r
932 **/\r
933 VOID\r
934 EFIAPI\r
935 HmacMd5Free (\r
936   IN  VOID  *HmacMd5Ctx\r
937   );\r
938 \r
939 /**\r
940   Initializes user-supplied memory pointed by HmacMd5Context as HMAC-MD5 context for\r
941   subsequent use.\r
942 \r
943   If HmacMd5Context is NULL, then return FALSE.\r
944   If this interface is not supported, then return FALSE.\r
945 \r
946   @param[out]  HmacMd5Context  Pointer to HMAC-MD5 context being initialized.\r
947   @param[in]   Key             Pointer to the user-supplied key.\r
948   @param[in]   KeySize         Key size in bytes.\r
949 \r
950   @retval TRUE   HMAC-MD5 context initialization succeeded.\r
951   @retval FALSE  HMAC-MD5 context initialization failed.\r
952   @retval FALSE  This interface is not supported.\r
953 \r
954 **/\r
955 BOOLEAN\r
956 EFIAPI\r
957 HmacMd5Init (\r
958   OUT  VOID         *HmacMd5Context,\r
959   IN   CONST UINT8  *Key,\r
960   IN   UINTN        KeySize\r
961   );\r
962 \r
963 /**\r
964   Makes a copy of an existing HMAC-MD5 context.\r
965 \r
966   If HmacMd5Context is NULL, then return FALSE.\r
967   If NewHmacMd5Context is NULL, then return FALSE.\r
968   If this interface is not supported, then return FALSE.\r
969 \r
970   @param[in]  HmacMd5Context     Pointer to HMAC-MD5 context being copied.\r
971   @param[out] NewHmacMd5Context  Pointer to new HMAC-MD5 context.\r
972 \r
973   @retval TRUE   HMAC-MD5 context copy succeeded.\r
974   @retval FALSE  HMAC-MD5 context copy failed.\r
975   @retval FALSE  This interface is not supported.\r
976 \r
977 **/\r
978 BOOLEAN\r
979 EFIAPI\r
980 HmacMd5Duplicate (\r
981   IN   CONST VOID  *HmacMd5Context,\r
982   OUT  VOID        *NewHmacMd5Context\r
983   );\r
984 \r
985 /**\r
986   Digests the input data and updates HMAC-MD5 context.\r
987 \r
988   This function performs HMAC-MD5 digest on a data buffer of the specified size.\r
989   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
990   HMAC-MD5 context should be already correctly initialized by HmacMd5Init(), and should not be\r
991   finalized by HmacMd5Final(). Behavior with invalid context is undefined.\r
992 \r
993   If HmacMd5Context is NULL, then return FALSE.\r
994   If this interface is not supported, then return FALSE.\r
995 \r
996   @param[in, out]  HmacMd5Context  Pointer to the HMAC-MD5 context.\r
997   @param[in]       Data            Pointer to the buffer containing the data to be digested.\r
998   @param[in]       DataSize        Size of Data buffer in bytes.\r
999 \r
1000   @retval TRUE   HMAC-MD5 data digest succeeded.\r
1001   @retval FALSE  HMAC-MD5 data digest failed.\r
1002   @retval FALSE  This interface is not supported.\r
1003 \r
1004 **/\r
1005 BOOLEAN\r
1006 EFIAPI\r
1007 HmacMd5Update (\r
1008   IN OUT  VOID        *HmacMd5Context,\r
1009   IN      CONST VOID  *Data,\r
1010   IN      UINTN       DataSize\r
1011   );\r
1012 \r
1013 /**\r
1014   Completes computation of the HMAC-MD5 digest value.\r
1015 \r
1016   This function completes HMAC-MD5 hash computation and retrieves the digest value into\r
1017   the specified memory. After this function has been called, the HMAC-MD5 context cannot\r
1018   be used again.\r
1019   HMAC-MD5 context should be already correctly initialized by HmacMd5Init(), and should not be\r
1020   finalized by HmacMd5Final(). Behavior with invalid HMAC-MD5 context is undefined.\r
1021 \r
1022   If HmacMd5Context is NULL, then return FALSE.\r
1023   If HmacValue is NULL, then return FALSE.\r
1024   If this interface is not supported, then return FALSE.\r
1025 \r
1026   @param[in, out]  HmacMd5Context  Pointer to the HMAC-MD5 context.\r
1027   @param[out]      HmacValue       Pointer to a buffer that receives the HMAC-MD5 digest\r
1028                                    value (16 bytes).\r
1029 \r
1030   @retval TRUE   HMAC-MD5 digest computation succeeded.\r
1031   @retval FALSE  HMAC-MD5 digest computation failed.\r
1032   @retval FALSE  This interface is not supported.\r
1033 \r
1034 **/\r
1035 BOOLEAN\r
1036 EFIAPI\r
1037 HmacMd5Final (\r
1038   IN OUT  VOID   *HmacMd5Context,\r
1039   OUT     UINT8  *HmacValue\r
1040   );\r
1041 \r
1042 /**\r
1043   Retrieves the size, in bytes, of the context buffer required for HMAC-SHA1 operations.\r
1044   (NOTE: This API is deprecated.\r
1045          Use HmacSha1New() / HmacSha1Free() for HMAC-SHA1 Context operations.)\r
1046 \r
1047   If this interface is not supported, then return zero.\r
1048 \r
1049   @return  The size, in bytes, of the context buffer required for HMAC-SHA1 operations.\r
1050   @retval  0   This interface is not supported.\r
1051 \r
1052 **/\r
1053 UINTN\r
1054 EFIAPI\r
1055 HmacSha1GetContextSize (\r
1056   VOID\r
1057   );\r
1058 \r
1059 /**\r
1060   Allocates and initializes one HMAC_CTX context for subsequent HMAC-SHA1 use.\r
1061 \r
1062   If this interface is not supported, then return NULL.\r
1063 \r
1064   @return  Pointer to the HMAC_CTX context that has been initialized.\r
1065            If the allocations fails, HmacSha1New() returns NULL.\r
1066   @return  NULL   This interface is not supported.\r
1067 \r
1068 **/\r
1069 VOID *\r
1070 EFIAPI\r
1071 HmacSha1New (\r
1072   VOID\r
1073   );\r
1074 \r
1075 /**\r
1076   Release the specified HMAC_CTX context.\r
1077 \r
1078   If this interface is not supported, then do nothing.\r
1079 \r
1080   @param[in]  HmacSha1Ctx  Pointer to the HMAC_CTX context to be released.\r
1081 \r
1082 **/\r
1083 VOID\r
1084 EFIAPI\r
1085 HmacSha1Free (\r
1086   IN  VOID  *HmacSha1Ctx\r
1087   );\r
1088 \r
1089 /**\r
1090   Initializes user-supplied memory pointed by HmacSha1Context as HMAC-SHA1 context for\r
1091   subsequent use.\r
1092 \r
1093   If HmacSha1Context is NULL, then return FALSE.\r
1094   If this interface is not supported, then return FALSE.\r
1095 \r
1096   @param[out]  HmacSha1Context  Pointer to HMAC-SHA1 context being initialized.\r
1097   @param[in]   Key              Pointer to the user-supplied key.\r
1098   @param[in]   KeySize          Key size in bytes.\r
1099 \r
1100   @retval TRUE   HMAC-SHA1 context initialization succeeded.\r
1101   @retval FALSE  HMAC-SHA1 context initialization failed.\r
1102   @retval FALSE  This interface is not supported.\r
1103 \r
1104 **/\r
1105 BOOLEAN\r
1106 EFIAPI\r
1107 HmacSha1Init (\r
1108   OUT  VOID         *HmacSha1Context,\r
1109   IN   CONST UINT8  *Key,\r
1110   IN   UINTN        KeySize\r
1111   );\r
1112 \r
1113 /**\r
1114   Makes a copy of an existing HMAC-SHA1 context.\r
1115 \r
1116   If HmacSha1Context is NULL, then return FALSE.\r
1117   If NewHmacSha1Context is NULL, then return FALSE.\r
1118   If this interface is not supported, then return FALSE.\r
1119 \r
1120   @param[in]  HmacSha1Context     Pointer to HMAC-SHA1 context being copied.\r
1121   @param[out] NewHmacSha1Context  Pointer to new HMAC-SHA1 context.\r
1122 \r
1123   @retval TRUE   HMAC-SHA1 context copy succeeded.\r
1124   @retval FALSE  HMAC-SHA1 context copy failed.\r
1125   @retval FALSE  This interface is not supported.\r
1126 \r
1127 **/\r
1128 BOOLEAN\r
1129 EFIAPI\r
1130 HmacSha1Duplicate (\r
1131   IN   CONST VOID  *HmacSha1Context,\r
1132   OUT  VOID        *NewHmacSha1Context\r
1133   );\r
1134 \r
1135 /**\r
1136   Digests the input data and updates HMAC-SHA1 context.\r
1137 \r
1138   This function performs HMAC-SHA1 digest on a data buffer of the specified size.\r
1139   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
1140   HMAC-SHA1 context should be already correctly initialized by HmacSha1Init(), and should not\r
1141   be finalized by HmacSha1Final(). Behavior with invalid context is undefined.\r
1142 \r
1143   If HmacSha1Context is NULL, then return FALSE.\r
1144   If this interface is not supported, then return FALSE.\r
1145 \r
1146   @param[in, out]  HmacSha1Context Pointer to the HMAC-SHA1 context.\r
1147   @param[in]       Data            Pointer to the buffer containing the data to be digested.\r
1148   @param[in]       DataSize        Size of Data buffer in bytes.\r
1149 \r
1150   @retval TRUE   HMAC-SHA1 data digest succeeded.\r
1151   @retval FALSE  HMAC-SHA1 data digest failed.\r
1152   @retval FALSE  This interface is not supported.\r
1153 \r
1154 **/\r
1155 BOOLEAN\r
1156 EFIAPI\r
1157 HmacSha1Update (\r
1158   IN OUT  VOID        *HmacSha1Context,\r
1159   IN      CONST VOID  *Data,\r
1160   IN      UINTN       DataSize\r
1161   );\r
1162 \r
1163 /**\r
1164   Completes computation of the HMAC-SHA1 digest value.\r
1165 \r
1166   This function completes HMAC-SHA1 hash computation and retrieves the digest value into\r
1167   the specified memory. After this function has been called, the HMAC-SHA1 context cannot\r
1168   be used again.\r
1169   HMAC-SHA1 context should be already correctly initialized by HmacSha1Init(), and should\r
1170   not be finalized by HmacSha1Final(). Behavior with invalid HMAC-SHA1 context is undefined.\r
1171 \r
1172   If HmacSha1Context is NULL, then return FALSE.\r
1173   If HmacValue is NULL, then return FALSE.\r
1174   If this interface is not supported, then return FALSE.\r
1175 \r
1176   @param[in, out]  HmacSha1Context  Pointer to the HMAC-SHA1 context.\r
1177   @param[out]      HmacValue        Pointer to a buffer that receives the HMAC-SHA1 digest\r
1178                                     value (20 bytes).\r
1179 \r
1180   @retval TRUE   HMAC-SHA1 digest computation succeeded.\r
1181   @retval FALSE  HMAC-SHA1 digest computation failed.\r
1182   @retval FALSE  This interface is not supported.\r
1183 \r
1184 **/\r
1185 BOOLEAN\r
1186 EFIAPI\r
1187 HmacSha1Final (\r
1188   IN OUT  VOID   *HmacSha1Context,\r
1189   OUT     UINT8  *HmacValue\r
1190   );\r
1191 \r
1192 /**\r
1193   Retrieves the size, in bytes, of the context buffer required for HMAC-SHA256 operations.\r
1194   (NOTE: This API is deprecated.\r
1195          Use HmacSha256New() / HmacSha256Free() for HMAC-SHA256 Context operations.)\r
1196 \r
1197   If this interface is not supported, then return zero.\r
1198 \r
1199   @return  The size, in bytes, of the context buffer required for HMAC-SHA256 operations.\r
1200   @retval  0   This interface is not supported.\r
1201 \r
1202 **/\r
1203 UINTN\r
1204 EFIAPI\r
1205 HmacSha256GetContextSize (\r
1206   VOID\r
1207   );\r
1208 \r
1209 /**\r
1210   Allocates and initializes one HMAC_CTX context for subsequent HMAC-SHA256 use.\r
1211 \r
1212   @return  Pointer to the HMAC_CTX context that has been initialized.\r
1213            If the allocations fails, HmacSha256New() returns NULL.\r
1214 \r
1215 **/\r
1216 VOID *\r
1217 EFIAPI\r
1218 HmacSha256New (\r
1219   VOID\r
1220   );\r
1221 \r
1222 /**\r
1223   Release the specified HMAC_CTX context.\r
1224 \r
1225   @param[in]  HmacSha256Ctx  Pointer to the HMAC_CTX context to be released.\r
1226 \r
1227 **/\r
1228 VOID\r
1229 EFIAPI\r
1230 HmacSha256Free (\r
1231   IN  VOID  *HmacSha256Ctx\r
1232   );\r
1233 \r
1234 /**\r
1235   Initializes user-supplied memory pointed by HmacSha256Context as HMAC-SHA256 context for\r
1236   subsequent use.\r
1237 \r
1238   If HmacSha256Context is NULL, then return FALSE.\r
1239   If this interface is not supported, then return FALSE.\r
1240 \r
1241   @param[out]  HmacSha256Context  Pointer to HMAC-SHA256 context being initialized.\r
1242   @param[in]   Key                Pointer to the user-supplied key.\r
1243   @param[in]   KeySize            Key size in bytes.\r
1244 \r
1245   @retval TRUE   HMAC-SHA256 context initialization succeeded.\r
1246   @retval FALSE  HMAC-SHA256 context initialization failed.\r
1247   @retval FALSE  This interface is not supported.\r
1248 \r
1249 **/\r
1250 BOOLEAN\r
1251 EFIAPI\r
1252 HmacSha256Init (\r
1253   OUT  VOID         *HmacSha256Context,\r
1254   IN   CONST UINT8  *Key,\r
1255   IN   UINTN        KeySize\r
1256   );\r
1257 \r
1258 /**\r
1259   Makes a copy of an existing HMAC-SHA256 context.\r
1260 \r
1261   If HmacSha256Context is NULL, then return FALSE.\r
1262   If NewHmacSha256Context is NULL, then return FALSE.\r
1263   If this interface is not supported, then return FALSE.\r
1264 \r
1265   @param[in]  HmacSha256Context     Pointer to HMAC-SHA256 context being copied.\r
1266   @param[out] NewHmacSha256Context  Pointer to new HMAC-SHA256 context.\r
1267 \r
1268   @retval TRUE   HMAC-SHA256 context copy succeeded.\r
1269   @retval FALSE  HMAC-SHA256 context copy failed.\r
1270   @retval FALSE  This interface is not supported.\r
1271 \r
1272 **/\r
1273 BOOLEAN\r
1274 EFIAPI\r
1275 HmacSha256Duplicate (\r
1276   IN   CONST VOID  *HmacSha256Context,\r
1277   OUT  VOID        *NewHmacSha256Context\r
1278   );\r
1279 \r
1280 /**\r
1281   Digests the input data and updates HMAC-SHA256 context.\r
1282 \r
1283   This function performs HMAC-SHA256 digest on a data buffer of the specified size.\r
1284   It can be called multiple times to compute the digest of long or discontinuous data streams.\r
1285   HMAC-SHA256 context should be already correctly initialized by HmacSha256Init(), and should not\r
1286   be finalized by HmacSha256Final(). Behavior with invalid context is undefined.\r
1287 \r
1288   If HmacSha256Context is NULL, then return FALSE.\r
1289   If this interface is not supported, then return FALSE.\r
1290 \r
1291   @param[in, out]  HmacSha256Context Pointer to the HMAC-SHA256 context.\r
1292   @param[in]       Data              Pointer to the buffer containing the data to be digested.\r
1293   @param[in]       DataSize          Size of Data buffer in bytes.\r
1294 \r
1295   @retval TRUE   HMAC-SHA256 data digest succeeded.\r
1296   @retval FALSE  HMAC-SHA256 data digest failed.\r
1297   @retval FALSE  This interface is not supported.\r
1298 \r
1299 **/\r
1300 BOOLEAN\r
1301 EFIAPI\r
1302 HmacSha256Update (\r
1303   IN OUT  VOID        *HmacSha256Context,\r
1304   IN      CONST VOID  *Data,\r
1305   IN      UINTN       DataSize\r
1306   );\r
1307 \r
1308 /**\r
1309   Completes computation of the HMAC-SHA256 digest value.\r
1310 \r
1311   This function completes HMAC-SHA256 hash computation and retrieves the digest value into\r
1312   the specified memory. After this function has been called, the HMAC-SHA256 context cannot\r
1313   be used again.\r
1314   HMAC-SHA256 context should be already correctly initialized by HmacSha256Init(), and should\r
1315   not be finalized by HmacSha256Final(). Behavior with invalid HMAC-SHA256 context is undefined.\r
1316 \r
1317   If HmacSha256Context is NULL, then return FALSE.\r
1318   If HmacValue is NULL, then return FALSE.\r
1319   If this interface is not supported, then return FALSE.\r
1320 \r
1321   @param[in, out]  HmacSha256Context  Pointer to the HMAC-SHA256 context.\r
1322   @param[out]      HmacValue          Pointer to a buffer that receives the HMAC-SHA256 digest\r
1323                                       value (32 bytes).\r
1324 \r
1325   @retval TRUE   HMAC-SHA256 digest computation succeeded.\r
1326   @retval FALSE  HMAC-SHA256 digest computation failed.\r
1327   @retval FALSE  This interface is not supported.\r
1328 \r
1329 **/\r
1330 BOOLEAN\r
1331 EFIAPI\r
1332 HmacSha256Final (\r
1333   IN OUT  VOID   *HmacSha256Context,\r
1334   OUT     UINT8  *HmacValue\r
1335   );\r
1336 \r
1337 //=====================================================================================\r
1338 //    Symmetric Cryptography Primitive\r
1339 //=====================================================================================\r
1340 \r
1341 /**\r
1342   Retrieves the size, in bytes, of the context buffer required for TDES operations.\r
1343 \r
1344   If this interface is not supported, then return zero.\r
1345 \r
1346   @return  The size, in bytes, of the context buffer required for TDES operations.\r
1347   @retval  0   This interface is not supported.\r
1348 \r
1349 **/\r
1350 UINTN\r
1351 EFIAPI\r
1352 TdesGetContextSize (\r
1353   VOID\r
1354   );\r
1355 \r
1356 /**\r
1357   Initializes user-supplied memory as TDES context for subsequent use.\r
1358 \r
1359   This function initializes user-supplied memory pointed by TdesContext as TDES context.\r
1360   In addition, it sets up all TDES key materials for subsequent encryption and decryption\r
1361   operations.\r
1362   There are 3 key options as follows:\r
1363   KeyLength = 64,  Keying option 1: K1 == K2 == K3 (Backward compatibility with DES)\r
1364   KeyLength = 128, Keying option 2: K1 != K2 and K3 = K1 (Less Security)\r
1365   KeyLength = 192  Keying option 3: K1 != K2 != K3 (Strongest)\r
1366 \r
1367   If TdesContext is NULL, then return FALSE.\r
1368   If Key is NULL, then return FALSE.\r
1369   If KeyLength is not valid, then return FALSE.\r
1370   If this interface is not supported, then return FALSE.\r
1371 \r
1372   @param[out]  TdesContext  Pointer to TDES context being initialized.\r
1373   @param[in]   Key          Pointer to the user-supplied TDES key.\r
1374   @param[in]   KeyLength    Length of TDES key in bits.\r
1375 \r
1376   @retval TRUE   TDES context initialization succeeded.\r
1377   @retval FALSE  TDES context initialization failed.\r
1378   @retval FALSE  This interface is not supported.\r
1379 \r
1380 **/\r
1381 BOOLEAN\r
1382 EFIAPI\r
1383 TdesInit (\r
1384   OUT  VOID         *TdesContext,\r
1385   IN   CONST UINT8  *Key,\r
1386   IN   UINTN        KeyLength\r
1387   );\r
1388 \r
1389 /**\r
1390   Performs TDES encryption on a data buffer of the specified size in ECB mode.\r
1391 \r
1392   This function performs TDES encryption on data buffer pointed by Input, of specified\r
1393   size of InputSize, in ECB mode.\r
1394   InputSize must be multiple of block size (8 bytes). This function does not perform\r
1395   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1396   TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
1397   invalid TDES context is undefined.\r
1398 \r
1399   If TdesContext is NULL, then return FALSE.\r
1400   If Input is NULL, then return FALSE.\r
1401   If InputSize is not multiple of block size (8 bytes), then return FALSE.\r
1402   If Output is NULL, then return FALSE.\r
1403   If this interface is not supported, then return FALSE.\r
1404 \r
1405   @param[in]   TdesContext  Pointer to the TDES context.\r
1406   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.\r
1407   @param[in]   InputSize    Size of the Input buffer in bytes.\r
1408   @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.\r
1409 \r
1410   @retval TRUE   TDES encryption succeeded.\r
1411   @retval FALSE  TDES encryption failed.\r
1412   @retval FALSE  This interface is not supported.\r
1413 \r
1414 **/\r
1415 BOOLEAN\r
1416 EFIAPI\r
1417 TdesEcbEncrypt (\r
1418   IN   VOID         *TdesContext,\r
1419   IN   CONST UINT8  *Input,\r
1420   IN   UINTN        InputSize,\r
1421   OUT  UINT8        *Output\r
1422   );\r
1423 \r
1424 /**\r
1425   Performs TDES decryption on a data buffer of the specified size in ECB mode.\r
1426 \r
1427   This function performs TDES decryption on data buffer pointed by Input, of specified\r
1428   size of InputSize, in ECB mode.\r
1429   InputSize must be multiple of block size (8 bytes). This function does not perform\r
1430   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1431   TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
1432   invalid TDES context is undefined.\r
1433 \r
1434   If TdesContext is NULL, then return FALSE.\r
1435   If Input is NULL, then return FALSE.\r
1436   If InputSize is not multiple of block size (8 bytes), then return FALSE.\r
1437   If Output is NULL, then return FALSE.\r
1438   If this interface is not supported, then return FALSE.\r
1439 \r
1440   @param[in]   TdesContext  Pointer to the TDES context.\r
1441   @param[in]   Input        Pointer to the buffer containing the data to be decrypted.\r
1442   @param[in]   InputSize    Size of the Input buffer in bytes.\r
1443   @param[out]  Output       Pointer to a buffer that receives the TDES decryption output.\r
1444 \r
1445   @retval TRUE   TDES decryption succeeded.\r
1446   @retval FALSE  TDES decryption failed.\r
1447   @retval FALSE  This interface is not supported.\r
1448 \r
1449 **/\r
1450 BOOLEAN\r
1451 EFIAPI\r
1452 TdesEcbDecrypt (\r
1453   IN   VOID         *TdesContext,\r
1454   IN   CONST UINT8  *Input,\r
1455   IN   UINTN        InputSize,\r
1456   OUT  UINT8        *Output\r
1457   );\r
1458 \r
1459 /**\r
1460   Performs TDES encryption on a data buffer of the specified size in CBC mode.\r
1461 \r
1462   This function performs TDES encryption on data buffer pointed by Input, of specified\r
1463   size of InputSize, in CBC mode.\r
1464   InputSize must be multiple of block size (8 bytes). This function does not perform\r
1465   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1466   Initialization vector should be one block size (8 bytes).\r
1467   TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
1468   invalid TDES context is undefined.\r
1469 \r
1470   If TdesContext is NULL, then return FALSE.\r
1471   If Input is NULL, then return FALSE.\r
1472   If InputSize is not multiple of block size (8 bytes), then return FALSE.\r
1473   If Ivec is NULL, then return FALSE.\r
1474   If Output is NULL, then return FALSE.\r
1475   If this interface is not supported, then return FALSE.\r
1476 \r
1477   @param[in]   TdesContext  Pointer to the TDES context.\r
1478   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.\r
1479   @param[in]   InputSize    Size of the Input buffer in bytes.\r
1480   @param[in]   Ivec         Pointer to initialization vector.\r
1481   @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.\r
1482 \r
1483   @retval TRUE   TDES encryption succeeded.\r
1484   @retval FALSE  TDES encryption failed.\r
1485   @retval FALSE  This interface is not supported.\r
1486 \r
1487 **/\r
1488 BOOLEAN\r
1489 EFIAPI\r
1490 TdesCbcEncrypt (\r
1491   IN   VOID         *TdesContext,\r
1492   IN   CONST UINT8  *Input,\r
1493   IN   UINTN        InputSize,\r
1494   IN   CONST UINT8  *Ivec,\r
1495   OUT  UINT8        *Output\r
1496   );\r
1497 \r
1498 /**\r
1499   Performs TDES decryption on a data buffer of the specified size in CBC mode.\r
1500 \r
1501   This function performs TDES decryption on data buffer pointed by Input, of specified\r
1502   size of InputSize, in CBC mode.\r
1503   InputSize must be multiple of block size (8 bytes). This function does not perform\r
1504   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1505   Initialization vector should be one block size (8 bytes).\r
1506   TdesContext should be already correctly initialized by TdesInit(). Behavior with\r
1507   invalid TDES context is undefined.\r
1508 \r
1509   If TdesContext is NULL, then return FALSE.\r
1510   If Input is NULL, then return FALSE.\r
1511   If InputSize is not multiple of block size (8 bytes), then return FALSE.\r
1512   If Ivec is NULL, then return FALSE.\r
1513   If Output is NULL, then return FALSE.\r
1514   If this interface is not supported, then return FALSE.\r
1515 \r
1516   @param[in]   TdesContext  Pointer to the TDES context.\r
1517   @param[in]   Input        Pointer to the buffer containing the data to be encrypted.\r
1518   @param[in]   InputSize    Size of the Input buffer in bytes.\r
1519   @param[in]   Ivec         Pointer to initialization vector.\r
1520   @param[out]  Output       Pointer to a buffer that receives the TDES encryption output.\r
1521 \r
1522   @retval TRUE   TDES decryption succeeded.\r
1523   @retval FALSE  TDES decryption failed.\r
1524   @retval FALSE  This interface is not supported.\r
1525 \r
1526 **/\r
1527 BOOLEAN\r
1528 EFIAPI\r
1529 TdesCbcDecrypt (\r
1530   IN   VOID         *TdesContext,\r
1531   IN   CONST UINT8  *Input,\r
1532   IN   UINTN        InputSize,\r
1533   IN   CONST UINT8  *Ivec,\r
1534   OUT  UINT8        *Output\r
1535   );\r
1536 \r
1537 /**\r
1538   Retrieves the size, in bytes, of the context buffer required for AES operations.\r
1539 \r
1540   If this interface is not supported, then return zero.\r
1541 \r
1542   @return  The size, in bytes, of the context buffer required for AES operations.\r
1543   @retval  0   This interface is not supported.\r
1544 \r
1545 **/\r
1546 UINTN\r
1547 EFIAPI\r
1548 AesGetContextSize (\r
1549   VOID\r
1550   );\r
1551 \r
1552 /**\r
1553   Initializes user-supplied memory as AES context for subsequent use.\r
1554 \r
1555   This function initializes user-supplied memory pointed by AesContext as AES context.\r
1556   In addition, it sets up all AES key materials for subsequent encryption and decryption\r
1557   operations.\r
1558   There are 3 options for key length, 128 bits, 192 bits, and 256 bits.\r
1559 \r
1560   If AesContext is NULL, then return FALSE.\r
1561   If Key is NULL, then return FALSE.\r
1562   If KeyLength is not valid, then return FALSE.\r
1563   If this interface is not supported, then return FALSE.\r
1564 \r
1565   @param[out]  AesContext  Pointer to AES context being initialized.\r
1566   @param[in]   Key         Pointer to the user-supplied AES key.\r
1567   @param[in]   KeyLength   Length of AES key in bits.\r
1568 \r
1569   @retval TRUE   AES context initialization succeeded.\r
1570   @retval FALSE  AES context initialization failed.\r
1571   @retval FALSE  This interface is not supported.\r
1572 \r
1573 **/\r
1574 BOOLEAN\r
1575 EFIAPI\r
1576 AesInit (\r
1577   OUT  VOID         *AesContext,\r
1578   IN   CONST UINT8  *Key,\r
1579   IN   UINTN        KeyLength\r
1580   );\r
1581 \r
1582 /**\r
1583   Performs AES encryption on a data buffer of the specified size in ECB mode.\r
1584 \r
1585   This function performs AES encryption on data buffer pointed by Input, of specified\r
1586   size of InputSize, in ECB mode.\r
1587   InputSize must be multiple of block size (16 bytes). This function does not perform\r
1588   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1589   AesContext should be already correctly initialized by AesInit(). Behavior with\r
1590   invalid AES context is undefined.\r
1591 \r
1592   If AesContext is NULL, then return FALSE.\r
1593   If Input is NULL, then return FALSE.\r
1594   If InputSize is not multiple of block size (16 bytes), then return FALSE.\r
1595   If Output is NULL, then return FALSE.\r
1596   If this interface is not supported, then return FALSE.\r
1597 \r
1598   @param[in]   AesContext  Pointer to the AES context.\r
1599   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.\r
1600   @param[in]   InputSize   Size of the Input buffer in bytes.\r
1601   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.\r
1602 \r
1603   @retval TRUE   AES encryption succeeded.\r
1604   @retval FALSE  AES encryption failed.\r
1605   @retval FALSE  This interface is not supported.\r
1606 \r
1607 **/\r
1608 BOOLEAN\r
1609 EFIAPI\r
1610 AesEcbEncrypt (\r
1611   IN   VOID         *AesContext,\r
1612   IN   CONST UINT8  *Input,\r
1613   IN   UINTN        InputSize,\r
1614   OUT  UINT8        *Output\r
1615   );\r
1616 \r
1617 /**\r
1618   Performs AES decryption on a data buffer of the specified size in ECB mode.\r
1619 \r
1620   This function performs AES decryption on data buffer pointed by Input, of specified\r
1621   size of InputSize, in ECB mode.\r
1622   InputSize must be multiple of block size (16 bytes). This function does not perform\r
1623   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1624   AesContext should be already correctly initialized by AesInit(). Behavior with\r
1625   invalid AES context is undefined.\r
1626 \r
1627   If AesContext is NULL, then return FALSE.\r
1628   If Input is NULL, then return FALSE.\r
1629   If InputSize is not multiple of block size (16 bytes), then return FALSE.\r
1630   If Output is NULL, then return FALSE.\r
1631   If this interface is not supported, then return FALSE.\r
1632 \r
1633   @param[in]   AesContext  Pointer to the AES context.\r
1634   @param[in]   Input       Pointer to the buffer containing the data to be decrypted.\r
1635   @param[in]   InputSize   Size of the Input buffer in bytes.\r
1636   @param[out]  Output      Pointer to a buffer that receives the AES decryption output.\r
1637 \r
1638   @retval TRUE   AES decryption succeeded.\r
1639   @retval FALSE  AES decryption failed.\r
1640   @retval FALSE  This interface is not supported.\r
1641 \r
1642 **/\r
1643 BOOLEAN\r
1644 EFIAPI\r
1645 AesEcbDecrypt (\r
1646   IN   VOID         *AesContext,\r
1647   IN   CONST UINT8  *Input,\r
1648   IN   UINTN        InputSize,\r
1649   OUT  UINT8        *Output\r
1650   );\r
1651 \r
1652 /**\r
1653   Performs AES encryption on a data buffer of the specified size in CBC mode.\r
1654 \r
1655   This function performs AES encryption on data buffer pointed by Input, of specified\r
1656   size of InputSize, in CBC mode.\r
1657   InputSize must be multiple of block size (16 bytes). This function does not perform\r
1658   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1659   Initialization vector should be one block size (16 bytes).\r
1660   AesContext should be already correctly initialized by AesInit(). Behavior with\r
1661   invalid AES context is undefined.\r
1662 \r
1663   If AesContext is NULL, then return FALSE.\r
1664   If Input is NULL, then return FALSE.\r
1665   If InputSize is not multiple of block size (16 bytes), then return FALSE.\r
1666   If Ivec is NULL, then return FALSE.\r
1667   If Output is NULL, then return FALSE.\r
1668   If this interface is not supported, then return FALSE.\r
1669 \r
1670   @param[in]   AesContext  Pointer to the AES context.\r
1671   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.\r
1672   @param[in]   InputSize   Size of the Input buffer in bytes.\r
1673   @param[in]   Ivec        Pointer to initialization vector.\r
1674   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.\r
1675 \r
1676   @retval TRUE   AES encryption succeeded.\r
1677   @retval FALSE  AES encryption failed.\r
1678   @retval FALSE  This interface is not supported.\r
1679 \r
1680 **/\r
1681 BOOLEAN\r
1682 EFIAPI\r
1683 AesCbcEncrypt (\r
1684   IN   VOID         *AesContext,\r
1685   IN   CONST UINT8  *Input,\r
1686   IN   UINTN        InputSize,\r
1687   IN   CONST UINT8  *Ivec,\r
1688   OUT  UINT8        *Output\r
1689   );\r
1690 \r
1691 /**\r
1692   Performs AES decryption on a data buffer of the specified size in CBC mode.\r
1693 \r
1694   This function performs AES decryption on data buffer pointed by Input, of specified\r
1695   size of InputSize, in CBC mode.\r
1696   InputSize must be multiple of block size (16 bytes). This function does not perform\r
1697   padding. Caller must perform padding, if necessary, to ensure valid input data size.\r
1698   Initialization vector should be one block size (16 bytes).\r
1699   AesContext should be already correctly initialized by AesInit(). Behavior with\r
1700   invalid AES context is undefined.\r
1701 \r
1702   If AesContext is NULL, then return FALSE.\r
1703   If Input is NULL, then return FALSE.\r
1704   If InputSize is not multiple of block size (16 bytes), then return FALSE.\r
1705   If Ivec is NULL, then return FALSE.\r
1706   If Output is NULL, then return FALSE.\r
1707   If this interface is not supported, then return FALSE.\r
1708 \r
1709   @param[in]   AesContext  Pointer to the AES context.\r
1710   @param[in]   Input       Pointer to the buffer containing the data to be encrypted.\r
1711   @param[in]   InputSize   Size of the Input buffer in bytes.\r
1712   @param[in]   Ivec        Pointer to initialization vector.\r
1713   @param[out]  Output      Pointer to a buffer that receives the AES encryption output.\r
1714 \r
1715   @retval TRUE   AES decryption succeeded.\r
1716   @retval FALSE  AES decryption failed.\r
1717   @retval FALSE  This interface is not supported.\r
1718 \r
1719 **/\r
1720 BOOLEAN\r
1721 EFIAPI\r
1722 AesCbcDecrypt (\r
1723   IN   VOID         *AesContext,\r
1724   IN   CONST UINT8  *Input,\r
1725   IN   UINTN        InputSize,\r
1726   IN   CONST UINT8  *Ivec,\r
1727   OUT  UINT8        *Output\r
1728   );\r
1729 \r
1730 /**\r
1731   Retrieves the size, in bytes, of the context buffer required for ARC4 operations.\r
1732 \r
1733   If this interface is not supported, then return zero.\r
1734 \r
1735   @return  The size, in bytes, of the context buffer required for ARC4 operations.\r
1736   @retval  0   This interface is not supported.\r
1737 \r
1738 **/\r
1739 UINTN\r
1740 EFIAPI\r
1741 Arc4GetContextSize (\r
1742   VOID\r
1743   );\r
1744 \r
1745 /**\r
1746   Initializes user-supplied memory as ARC4 context for subsequent use.\r
1747 \r
1748   This function initializes user-supplied memory pointed by Arc4Context as ARC4 context.\r
1749   In addition, it sets up all ARC4 key materials for subsequent encryption and decryption\r
1750   operations.\r
1751 \r
1752   If Arc4Context is NULL, then return FALSE.\r
1753   If Key is NULL, then return FALSE.\r
1754   If KeySize does not in the range of [5, 256] bytes, then return FALSE.\r
1755   If this interface is not supported, then return FALSE.\r
1756 \r
1757   @param[out]  Arc4Context  Pointer to ARC4 context being initialized.\r
1758   @param[in]   Key          Pointer to the user-supplied ARC4 key.\r
1759   @param[in]   KeySize      Size of ARC4 key in bytes.\r
1760 \r
1761   @retval TRUE   ARC4 context initialization succeeded.\r
1762   @retval FALSE  ARC4 context initialization failed.\r
1763   @retval FALSE  This interface is not supported.\r
1764 \r
1765 **/\r
1766 BOOLEAN\r
1767 EFIAPI\r
1768 Arc4Init (\r
1769   OUT  VOID         *Arc4Context,\r
1770   IN   CONST UINT8  *Key,\r
1771   IN   UINTN        KeySize\r
1772   );\r
1773 \r
1774 /**\r
1775   Performs ARC4 encryption on a data buffer of the specified size.\r
1776 \r
1777   This function performs ARC4 encryption on data buffer pointed by Input, of specified\r
1778   size of InputSize.\r
1779   Arc4Context should be already correctly initialized by Arc4Init(). Behavior with\r
1780   invalid ARC4 context is undefined.\r
1781 \r
1782   If Arc4Context is NULL, then return FALSE.\r
1783   If Input is NULL, then return FALSE.\r
1784   If Output is NULL, then return FALSE.\r
1785   If this interface is not supported, then return FALSE.\r
1786 \r
1787   @param[in, out]  Arc4Context  Pointer to the ARC4 context.\r
1788   @param[in]       Input        Pointer to the buffer containing the data to be encrypted.\r
1789   @param[in]       InputSize    Size of the Input buffer in bytes.\r
1790   @param[out]      Output       Pointer to a buffer that receives the ARC4 encryption output.\r
1791 \r
1792   @retval TRUE   ARC4 encryption succeeded.\r
1793   @retval FALSE  ARC4 encryption failed.\r
1794   @retval FALSE  This interface is not supported.\r
1795 \r
1796 **/\r
1797 BOOLEAN\r
1798 EFIAPI\r
1799 Arc4Encrypt (\r
1800   IN OUT  VOID         *Arc4Context,\r
1801   IN      CONST UINT8  *Input,\r
1802   IN      UINTN        InputSize,\r
1803   OUT     UINT8        *Output\r
1804   );\r
1805 \r
1806 /**\r
1807   Performs ARC4 decryption on a data buffer of the specified size.\r
1808 \r
1809   This function performs ARC4 decryption on data buffer pointed by Input, of specified\r
1810   size of InputSize.\r
1811   Arc4Context should be already correctly initialized by Arc4Init(). Behavior with\r
1812   invalid ARC4 context is undefined.\r
1813 \r
1814   If Arc4Context is NULL, then return FALSE.\r
1815   If Input is NULL, then return FALSE.\r
1816   If Output is NULL, then return FALSE.\r
1817   If this interface is not supported, then return FALSE.\r
1818 \r
1819   @param[in, out]  Arc4Context  Pointer to the ARC4 context.\r
1820   @param[in]       Input        Pointer to the buffer containing the data to be decrypted.\r
1821   @param[in]       InputSize    Size of the Input buffer in bytes.\r
1822   @param[out]      Output       Pointer to a buffer that receives the ARC4 decryption output.\r
1823 \r
1824   @retval TRUE   ARC4 decryption succeeded.\r
1825   @retval FALSE  ARC4 decryption failed.\r
1826   @retval FALSE  This interface is not supported.\r
1827 \r
1828 **/\r
1829 BOOLEAN\r
1830 EFIAPI\r
1831 Arc4Decrypt (\r
1832   IN OUT  VOID   *Arc4Context,\r
1833   IN      UINT8  *Input,\r
1834   IN      UINTN  InputSize,\r
1835   OUT     UINT8  *Output\r
1836   );\r
1837 \r
1838 /**\r
1839   Resets the ARC4 context to the initial state.\r
1840 \r
1841   The function resets the ARC4 context to the state it had immediately after the\r
1842   ARC4Init() function call.\r
1843   Contrary to ARC4Init(), Arc4Reset() requires no secret key as input, but ARC4 context\r
1844   should be already correctly initialized by ARC4Init().\r
1845 \r
1846   If Arc4Context is NULL, then return FALSE.\r
1847   If this interface is not supported, then return FALSE.\r
1848 \r
1849   @param[in, out]  Arc4Context  Pointer to the ARC4 context.\r
1850 \r
1851   @retval TRUE   ARC4 reset succeeded.\r
1852   @retval FALSE  ARC4 reset failed.\r
1853   @retval FALSE  This interface is not supported.\r
1854 \r
1855 **/\r
1856 BOOLEAN\r
1857 EFIAPI\r
1858 Arc4Reset (\r
1859   IN OUT  VOID  *Arc4Context\r
1860   );\r
1861 \r
1862 //=====================================================================================\r
1863 //    Asymmetric Cryptography Primitive\r
1864 //=====================================================================================\r
1865 \r
1866 /**\r
1867   Allocates and initializes one RSA context for subsequent use.\r
1868 \r
1869   @return  Pointer to the RSA context that has been initialized.\r
1870            If the allocations fails, RsaNew() returns NULL.\r
1871 \r
1872 **/\r
1873 VOID *\r
1874 EFIAPI\r
1875 RsaNew (\r
1876   VOID\r
1877   );\r
1878 \r
1879 /**\r
1880   Release the specified RSA context.\r
1881 \r
1882   If RsaContext is NULL, then return FALSE.\r
1883 \r
1884   @param[in]  RsaContext  Pointer to the RSA context to be released.\r
1885 \r
1886 **/\r
1887 VOID\r
1888 EFIAPI\r
1889 RsaFree (\r
1890   IN  VOID  *RsaContext\r
1891   );\r
1892 \r
1893 /**\r
1894   Sets the tag-designated key component into the established RSA context.\r
1895 \r
1896   This function sets the tag-designated RSA key component into the established\r
1897   RSA context from the user-specified non-negative integer (octet string format\r
1898   represented in RSA PKCS#1).\r
1899   If BigNumber is NULL, then the specified key component in RSA context is cleared.\r
1900 \r
1901   If RsaContext is NULL, then return FALSE.\r
1902 \r
1903   @param[in, out]  RsaContext  Pointer to RSA context being set.\r
1904   @param[in]       KeyTag      Tag of RSA key component being set.\r
1905   @param[in]       BigNumber   Pointer to octet integer buffer.\r
1906                                If NULL, then the specified key component in RSA\r
1907                                context is cleared.\r
1908   @param[in]       BnSize      Size of big number buffer in bytes.\r
1909                                If BigNumber is NULL, then it is ignored.\r
1910 \r
1911   @retval  TRUE   RSA key component was set successfully.\r
1912   @retval  FALSE  Invalid RSA key component tag.\r
1913 \r
1914 **/\r
1915 BOOLEAN\r
1916 EFIAPI\r
1917 RsaSetKey (\r
1918   IN OUT  VOID         *RsaContext,\r
1919   IN      RSA_KEY_TAG  KeyTag,\r
1920   IN      CONST UINT8  *BigNumber,\r
1921   IN      UINTN        BnSize\r
1922   );\r
1923 \r
1924 /**\r
1925   Gets the tag-designated RSA key component from the established RSA context.\r
1926 \r
1927   This function retrieves the tag-designated RSA key component from the\r
1928   established RSA context as a non-negative integer (octet string format\r
1929   represented in RSA PKCS#1).\r
1930   If specified key component has not been set or has been cleared, then returned\r
1931   BnSize is set to 0.\r
1932   If the BigNumber buffer is too small to hold the contents of the key, FALSE\r
1933   is returned and BnSize is set to the required buffer size to obtain the key.\r
1934 \r
1935   If RsaContext is NULL, then return FALSE.\r
1936   If BnSize is NULL, then return FALSE.\r
1937   If BnSize is large enough but BigNumber is NULL, then return FALSE.\r
1938   If this interface is not supported, then return FALSE.\r
1939 \r
1940   @param[in, out]  RsaContext  Pointer to RSA context being set.\r
1941   @param[in]       KeyTag      Tag of RSA key component being set.\r
1942   @param[out]      BigNumber   Pointer to octet integer buffer.\r
1943   @param[in, out]  BnSize      On input, the size of big number buffer in bytes.\r
1944                                On output, the size of data returned in big number buffer in bytes.\r
1945 \r
1946   @retval  TRUE   RSA key component was retrieved successfully.\r
1947   @retval  FALSE  Invalid RSA key component tag.\r
1948   @retval  FALSE  BnSize is too small.\r
1949   @retval  FALSE  This interface is not supported.\r
1950 \r
1951 **/\r
1952 BOOLEAN\r
1953 EFIAPI\r
1954 RsaGetKey (\r
1955   IN OUT  VOID         *RsaContext,\r
1956   IN      RSA_KEY_TAG  KeyTag,\r
1957   OUT     UINT8        *BigNumber,\r
1958   IN OUT  UINTN        *BnSize\r
1959   );\r
1960 \r
1961 /**\r
1962   Generates RSA key components.\r
1963 \r
1964   This function generates RSA key components. It takes RSA public exponent E and\r
1965   length in bits of RSA modulus N as input, and generates all key components.\r
1966   If PublicExponent is NULL, the default RSA public exponent (0x10001) will be used.\r
1967 \r
1968   Before this function can be invoked, pseudorandom number generator must be correctly\r
1969   initialized by RandomSeed().\r
1970 \r
1971   If RsaContext is NULL, then return FALSE.\r
1972   If this interface is not supported, then return FALSE.\r
1973 \r
1974   @param[in, out]  RsaContext           Pointer to RSA context being set.\r
1975   @param[in]       ModulusLength        Length of RSA modulus N in bits.\r
1976   @param[in]       PublicExponent       Pointer to RSA public exponent.\r
1977   @param[in]       PublicExponentSize   Size of RSA public exponent buffer in bytes.\r
1978 \r
1979   @retval  TRUE   RSA key component was generated successfully.\r
1980   @retval  FALSE  Invalid RSA key component tag.\r
1981   @retval  FALSE  This interface is not supported.\r
1982 \r
1983 **/\r
1984 BOOLEAN\r
1985 EFIAPI\r
1986 RsaGenerateKey (\r
1987   IN OUT  VOID         *RsaContext,\r
1988   IN      UINTN        ModulusLength,\r
1989   IN      CONST UINT8  *PublicExponent,\r
1990   IN      UINTN        PublicExponentSize\r
1991   );\r
1992 \r
1993 /**\r
1994   Validates key components of RSA context.\r
1995   NOTE: This function performs integrity checks on all the RSA key material, so\r
1996         the RSA key structure must contain all the private key data.\r
1997 \r
1998   This function validates key components of RSA context in following aspects:\r
1999   - Whether p is a prime\r
2000   - Whether q is a prime\r
2001   - Whether n = p * q\r
2002   - Whether d*e = 1  mod lcm(p-1,q-1)\r
2003 \r
2004   If RsaContext is NULL, then return FALSE.\r
2005   If this interface is not supported, then return FALSE.\r
2006 \r
2007   @param[in]  RsaContext  Pointer to RSA context to check.\r
2008 \r
2009   @retval  TRUE   RSA key components are valid.\r
2010   @retval  FALSE  RSA key components are not valid.\r
2011   @retval  FALSE  This interface is not supported.\r
2012 \r
2013 **/\r
2014 BOOLEAN\r
2015 EFIAPI\r
2016 RsaCheckKey (\r
2017   IN  VOID  *RsaContext\r
2018   );\r
2019 \r
2020 /**\r
2021   Carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme.\r
2022 \r
2023   This function carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme defined in\r
2024   RSA PKCS#1.\r
2025   If the Signature buffer is too small to hold the contents of signature, FALSE\r
2026   is returned and SigSize is set to the required buffer size to obtain the signature.\r
2027 \r
2028   If RsaContext is NULL, then return FALSE.\r
2029   If MessageHash is NULL, then return FALSE.\r
2030   If HashSize is not equal to the size of MD5, SHA-1 or SHA-256 digest, then return FALSE.\r
2031   If SigSize is large enough but Signature is NULL, then return FALSE.\r
2032   If this interface is not supported, then return FALSE.\r
2033 \r
2034   @param[in]      RsaContext   Pointer to RSA context for signature generation.\r
2035   @param[in]      MessageHash  Pointer to octet message hash to be signed.\r
2036   @param[in]      HashSize     Size of the message hash in bytes.\r
2037   @param[out]     Signature    Pointer to buffer to receive RSA PKCS1-v1_5 signature.\r
2038   @param[in, out] SigSize      On input, the size of Signature buffer in bytes.\r
2039                                On output, the size of data returned in Signature buffer in bytes.\r
2040 \r
2041   @retval  TRUE   Signature successfully generated in PKCS1-v1_5.\r
2042   @retval  FALSE  Signature generation failed.\r
2043   @retval  FALSE  SigSize is too small.\r
2044   @retval  FALSE  This interface is not supported.\r
2045 \r
2046 **/\r
2047 BOOLEAN\r
2048 EFIAPI\r
2049 RsaPkcs1Sign (\r
2050   IN      VOID         *RsaContext,\r
2051   IN      CONST UINT8  *MessageHash,\r
2052   IN      UINTN        HashSize,\r
2053   OUT     UINT8        *Signature,\r
2054   IN OUT  UINTN        *SigSize\r
2055   );\r
2056 \r
2057 /**\r
2058   Verifies the RSA-SSA signature with EMSA-PKCS1-v1_5 encoding scheme defined in\r
2059   RSA PKCS#1.\r
2060 \r
2061   If RsaContext is NULL, then return FALSE.\r
2062   If MessageHash is NULL, then return FALSE.\r
2063   If Signature is NULL, then return FALSE.\r
2064   If HashSize is not equal to the size of MD5, SHA-1, SHA-256 digest, then return FALSE.\r
2065 \r
2066   @param[in]  RsaContext   Pointer to RSA context for signature verification.\r
2067   @param[in]  MessageHash  Pointer to octet message hash to be checked.\r
2068   @param[in]  HashSize     Size of the message hash in bytes.\r
2069   @param[in]  Signature    Pointer to RSA PKCS1-v1_5 signature to be verified.\r
2070   @param[in]  SigSize      Size of signature in bytes.\r
2071 \r
2072   @retval  TRUE   Valid signature encoded in PKCS1-v1_5.\r
2073   @retval  FALSE  Invalid signature or invalid RSA context.\r
2074 \r
2075 **/\r
2076 BOOLEAN\r
2077 EFIAPI\r
2078 RsaPkcs1Verify (\r
2079   IN  VOID         *RsaContext,\r
2080   IN  CONST UINT8  *MessageHash,\r
2081   IN  UINTN        HashSize,\r
2082   IN  CONST UINT8  *Signature,\r
2083   IN  UINTN        SigSize\r
2084   );\r
2085 \r
2086 /**\r
2087   Retrieve the RSA Private Key from the password-protected PEM key data.\r
2088 \r
2089   If PemData is NULL, then return FALSE.\r
2090   If RsaContext is NULL, then return FALSE.\r
2091   If this interface is not supported, then return FALSE.\r
2092 \r
2093   @param[in]  PemData      Pointer to the PEM-encoded key data to be retrieved.\r
2094   @param[in]  PemSize      Size of the PEM key data in bytes.\r
2095   @param[in]  Password     NULL-terminated passphrase used for encrypted PEM key data.\r
2096   @param[out] RsaContext   Pointer to new-generated RSA context which contain the retrieved\r
2097                            RSA private key component. Use RsaFree() function to free the\r
2098                            resource.\r
2099 \r
2100   @retval  TRUE   RSA Private Key was retrieved successfully.\r
2101   @retval  FALSE  Invalid PEM key data or incorrect password.\r
2102   @retval  FALSE  This interface is not supported.\r
2103 \r
2104 **/\r
2105 BOOLEAN\r
2106 EFIAPI\r
2107 RsaGetPrivateKeyFromPem (\r
2108   IN   CONST UINT8  *PemData,\r
2109   IN   UINTN        PemSize,\r
2110   IN   CONST CHAR8  *Password,\r
2111   OUT  VOID         **RsaContext\r
2112   );\r
2113 \r
2114 /**\r
2115   Retrieve the RSA Public Key from one DER-encoded X509 certificate.\r
2116 \r
2117   If Cert is NULL, then return FALSE.\r
2118   If RsaContext is NULL, then return FALSE.\r
2119   If this interface is not supported, then return FALSE.\r
2120 \r
2121   @param[in]  Cert         Pointer to the DER-encoded X509 certificate.\r
2122   @param[in]  CertSize     Size of the X509 certificate in bytes.\r
2123   @param[out] RsaContext   Pointer to new-generated RSA context which contain the retrieved\r
2124                            RSA public key component. Use RsaFree() function to free the\r
2125                            resource.\r
2126 \r
2127   @retval  TRUE   RSA Public Key was retrieved successfully.\r
2128   @retval  FALSE  Fail to retrieve RSA public key from X509 certificate.\r
2129   @retval  FALSE  This interface is not supported.\r
2130 \r
2131 **/\r
2132 BOOLEAN\r
2133 EFIAPI\r
2134 RsaGetPublicKeyFromX509 (\r
2135   IN   CONST UINT8  *Cert,\r
2136   IN   UINTN        CertSize,\r
2137   OUT  VOID         **RsaContext\r
2138   );\r
2139 \r
2140 /**\r
2141   Retrieve the subject bytes from one X.509 certificate.\r
2142 \r
2143   If Cert is NULL, then return FALSE.\r
2144   If SubjectSize is NULL, then return FALSE.\r
2145   If this interface is not supported, then return FALSE.\r
2146 \r
2147   @param[in]      Cert         Pointer to the DER-encoded X509 certificate.\r
2148   @param[in]      CertSize     Size of the X509 certificate in bytes.\r
2149   @param[out]     CertSubject  Pointer to the retrieved certificate subject bytes.\r
2150   @param[in, out] SubjectSize  The size in bytes of the CertSubject buffer on input,\r
2151                                and the size of buffer returned CertSubject on output.\r
2152 \r
2153   @retval  TRUE   The certificate subject retrieved successfully.\r
2154   @retval  FALSE  Invalid certificate, or the SubjectSize is too small for the result.\r
2155                   The SubjectSize will be updated with the required size.\r
2156   @retval  FALSE  This interface is not supported.\r
2157 \r
2158 **/\r
2159 BOOLEAN\r
2160 EFIAPI\r
2161 X509GetSubjectName (\r
2162   IN      CONST UINT8  *Cert,\r
2163   IN      UINTN        CertSize,\r
2164   OUT     UINT8        *CertSubject,\r
2165   IN OUT  UINTN        *SubjectSize\r
2166   );\r
2167 \r
2168 /**\r
2169   Retrieve the common name (CN) string from one X.509 certificate.\r
2170 \r
2171   @param[in]      Cert             Pointer to the DER-encoded X509 certificate.\r
2172   @param[in]      CertSize         Size of the X509 certificate in bytes.\r
2173   @param[out]     CommonName       Buffer to contain the retrieved certificate common\r
2174                                    name string (UTF8). At most CommonNameSize bytes will be\r
2175                                    written and the string will be null terminated. May be\r
2176                                    NULL in order to determine the size buffer needed.\r
2177   @param[in,out]  CommonNameSize   The size in bytes of the CommonName buffer on input,\r
2178                                    and the size of buffer returned CommonName on output.\r
2179                                    If CommonName is NULL then the amount of space needed\r
2180                                    in buffer (including the final null) is returned.\r
2181 \r
2182   @retval RETURN_SUCCESS           The certificate CommonName retrieved successfully.\r
2183   @retval RETURN_INVALID_PARAMETER If Cert is NULL.\r
2184                                    If CommonNameSize is NULL.\r
2185                                    If CommonName is not NULL and *CommonNameSize is 0.\r
2186                                    If Certificate is invalid.\r
2187   @retval RETURN_NOT_FOUND         If no CommonName entry exists.\r
2188   @retval RETURN_BUFFER_TOO_SMALL  If the CommonName is NULL. The required buffer size\r
2189                                    (including the final null) is returned in the\r
2190                                    CommonNameSize parameter.\r
2191   @retval RETURN_UNSUPPORTED       The operation is not supported.\r
2192 \r
2193 **/\r
2194 RETURN_STATUS\r
2195 EFIAPI\r
2196 X509GetCommonName (\r
2197   IN      CONST UINT8  *Cert,\r
2198   IN      UINTN        CertSize,\r
2199   OUT     CHAR8        *CommonName,  OPTIONAL\r
2200   IN OUT  UINTN        *CommonNameSize\r
2201   );\r
2202 \r
2203 /**\r
2204   Retrieve the organization name (O) string from one X.509 certificate.\r
2205 \r
2206   @param[in]      Cert             Pointer to the DER-encoded X509 certificate.\r
2207   @param[in]      CertSize         Size of the X509 certificate in bytes.\r
2208   @param[out]     NameBuffer       Buffer to contain the retrieved certificate organization\r
2209                                    name string. At most NameBufferSize bytes will be\r
2210                                    written and the string will be null terminated. May be\r
2211                                    NULL in order to determine the size buffer needed.\r
2212   @param[in,out]  NameBufferSize   The size in bytes of the Name buffer on input,\r
2213                                    and the size of buffer returned Name on output.\r
2214                                    If NameBuffer is NULL then the amount of space needed\r
2215                                    in buffer (including the final null) is returned.\r
2216 \r
2217   @retval RETURN_SUCCESS           The certificate Organization Name retrieved successfully.\r
2218   @retval RETURN_INVALID_PARAMETER If Cert is NULL.\r
2219                                    If NameBufferSize is NULL.\r
2220                                    If NameBuffer is not NULL and *CommonNameSize is 0.\r
2221                                    If Certificate is invalid.\r
2222   @retval RETURN_NOT_FOUND         If no Organization Name entry exists.\r
2223   @retval RETURN_BUFFER_TOO_SMALL  If the NameBuffer is NULL. The required buffer size\r
2224                                    (including the final null) is returned in the\r
2225                                    CommonNameSize parameter.\r
2226   @retval RETURN_UNSUPPORTED       The operation is not supported.\r
2227 \r
2228 **/\r
2229 RETURN_STATUS\r
2230 EFIAPI\r
2231 X509GetOrganizationName (\r
2232   IN      CONST UINT8   *Cert,\r
2233   IN      UINTN         CertSize,\r
2234   OUT     CHAR8         *NameBuffer,  OPTIONAL\r
2235   IN OUT  UINTN         *NameBufferSize\r
2236   );\r
2237 \r
2238 /**\r
2239   Verify one X509 certificate was issued by the trusted CA.\r
2240 \r
2241   If Cert is NULL, then return FALSE.\r
2242   If CACert is NULL, then return FALSE.\r
2243   If this interface is not supported, then return FALSE.\r
2244 \r
2245   @param[in]      Cert         Pointer to the DER-encoded X509 certificate to be verified.\r
2246   @param[in]      CertSize     Size of the X509 certificate in bytes.\r
2247   @param[in]      CACert       Pointer to the DER-encoded trusted CA certificate.\r
2248   @param[in]      CACertSize   Size of the CA Certificate in bytes.\r
2249 \r
2250   @retval  TRUE   The certificate was issued by the trusted CA.\r
2251   @retval  FALSE  Invalid certificate or the certificate was not issued by the given\r
2252                   trusted CA.\r
2253   @retval  FALSE  This interface is not supported.\r
2254 \r
2255 **/\r
2256 BOOLEAN\r
2257 EFIAPI\r
2258 X509VerifyCert (\r
2259   IN  CONST UINT8  *Cert,\r
2260   IN  UINTN        CertSize,\r
2261   IN  CONST UINT8  *CACert,\r
2262   IN  UINTN        CACertSize\r
2263   );\r
2264 \r
2265 /**\r
2266   Construct a X509 object from DER-encoded certificate data.\r
2267 \r
2268   If Cert is NULL, then return FALSE.\r
2269   If SingleX509Cert is NULL, then return FALSE.\r
2270   If this interface is not supported, then return FALSE.\r
2271 \r
2272   @param[in]  Cert            Pointer to the DER-encoded certificate data.\r
2273   @param[in]  CertSize        The size of certificate data in bytes.\r
2274   @param[out] SingleX509Cert  The generated X509 object.\r
2275 \r
2276   @retval     TRUE            The X509 object generation succeeded.\r
2277   @retval     FALSE           The operation failed.\r
2278   @retval     FALSE           This interface is not supported.\r
2279 \r
2280 **/\r
2281 BOOLEAN\r
2282 EFIAPI\r
2283 X509ConstructCertificate (\r
2284   IN   CONST UINT8  *Cert,\r
2285   IN   UINTN        CertSize,\r
2286   OUT  UINT8        **SingleX509Cert\r
2287   );\r
2288 \r
2289 /**\r
2290   Construct a X509 stack object from a list of DER-encoded certificate data.\r
2291 \r
2292   If X509Stack is NULL, then return FALSE.\r
2293   If this interface is not supported, then return FALSE.\r
2294 \r
2295   @param[in, out]  X509Stack  On input, pointer to an existing or NULL X509 stack object.\r
2296                               On output, pointer to the X509 stack object with new\r
2297                               inserted X509 certificate.\r
2298   @param           ...        A list of DER-encoded single certificate data followed\r
2299                               by certificate size. A NULL terminates the list. The\r
2300                               pairs are the arguments to X509ConstructCertificate().\r
2301 \r
2302   @retval     TRUE            The X509 stack construction succeeded.\r
2303   @retval     FALSE           The construction operation failed.\r
2304   @retval     FALSE           This interface is not supported.\r
2305 \r
2306 **/\r
2307 BOOLEAN\r
2308 EFIAPI\r
2309 X509ConstructCertificateStack (\r
2310   IN OUT  UINT8  **X509Stack,\r
2311   ...\r
2312   );\r
2313 \r
2314 /**\r
2315   Release the specified X509 object.\r
2316 \r
2317   If the interface is not supported, then ASSERT().\r
2318 \r
2319   @param[in]  X509Cert  Pointer to the X509 object to be released.\r
2320 \r
2321 **/\r
2322 VOID\r
2323 EFIAPI\r
2324 X509Free (\r
2325   IN  VOID  *X509Cert\r
2326   );\r
2327 \r
2328 /**\r
2329   Release the specified X509 stack object.\r
2330 \r
2331   If the interface is not supported, then ASSERT().\r
2332 \r
2333   @param[in]  X509Stack  Pointer to the X509 stack object to be released.\r
2334 \r
2335 **/\r
2336 VOID\r
2337 EFIAPI\r
2338 X509StackFree (\r
2339   IN  VOID  *X509Stack\r
2340   );\r
2341 \r
2342 /**\r
2343   Retrieve the TBSCertificate from one given X.509 certificate.\r
2344 \r
2345   @param[in]      Cert         Pointer to the given DER-encoded X509 certificate.\r
2346   @param[in]      CertSize     Size of the X509 certificate in bytes.\r
2347   @param[out]     TBSCert      DER-Encoded To-Be-Signed certificate.\r
2348   @param[out]     TBSCertSize  Size of the TBS certificate in bytes.\r
2349 \r
2350   If Cert is NULL, then return FALSE.\r
2351   If TBSCert is NULL, then return FALSE.\r
2352   If TBSCertSize is NULL, then return FALSE.\r
2353   If this interface is not supported, then return FALSE.\r
2354 \r
2355   @retval  TRUE   The TBSCertificate was retrieved successfully.\r
2356   @retval  FALSE  Invalid X.509 certificate.\r
2357 \r
2358 **/\r
2359 BOOLEAN\r
2360 EFIAPI\r
2361 X509GetTBSCert (\r
2362   IN  CONST UINT8  *Cert,\r
2363   IN  UINTN        CertSize,\r
2364   OUT UINT8        **TBSCert,\r
2365   OUT UINTN        *TBSCertSize\r
2366   );\r
2367 \r
2368 /**\r
2369   Derives a key from a password using a salt and iteration count, based on PKCS#5 v2.0\r
2370   password based encryption key derivation function PBKDF2, as specified in RFC 2898.\r
2371 \r
2372   If Password or Salt or OutKey is NULL, then return FALSE.\r
2373   If the hash algorithm could not be determined, then return FALSE.\r
2374   If this interface is not supported, then return FALSE.\r
2375 \r
2376   @param[in]  PasswordLength  Length of input password in bytes.\r
2377   @param[in]  Password        Pointer to the array for the password.\r
2378   @param[in]  SaltLength      Size of the Salt in bytes.\r
2379   @param[in]  Salt            Pointer to the Salt.\r
2380   @param[in]  IterationCount  Number of iterations to perform. Its value should be\r
2381                               greater than or equal to 1.\r
2382   @param[in]  DigestSize      Size of the message digest to be used (eg. SHA256_DIGEST_SIZE).\r
2383                               NOTE: DigestSize will be used to determine the hash algorithm.\r
2384                                     Only SHA1_DIGEST_SIZE or SHA256_DIGEST_SIZE is supported.\r
2385   @param[in]  KeyLength       Size of the derived key buffer in bytes.\r
2386   @param[out] OutKey          Pointer to the output derived key buffer.\r
2387 \r
2388   @retval  TRUE   A key was derived successfully.\r
2389   @retval  FALSE  One of the pointers was NULL or one of the sizes was too large.\r
2390   @retval  FALSE  The hash algorithm could not be determined from the digest size.\r
2391   @retval  FALSE  The key derivation operation failed.\r
2392   @retval  FALSE  This interface is not supported.\r
2393 \r
2394 **/\r
2395 BOOLEAN\r
2396 EFIAPI\r
2397 Pkcs5HashPassword (\r
2398   IN  UINTN        PasswordLength,\r
2399   IN  CONST CHAR8  *Password,\r
2400   IN  UINTN        SaltLength,\r
2401   IN  CONST UINT8  *Salt,\r
2402   IN  UINTN        IterationCount,\r
2403   IN  UINTN        DigestSize,\r
2404   IN  UINTN        KeyLength,\r
2405   OUT UINT8        *OutKey\r
2406   );\r
2407 \r
2408 /**\r
2409   The 3rd parameter of Pkcs7GetSigners will return all embedded\r
2410   X.509 certificate in one given PKCS7 signature. The format is:\r
2411   //\r
2412   // UINT8  CertNumber;\r
2413   // UINT32 Cert1Length;\r
2414   // UINT8  Cert1[];\r
2415   // UINT32 Cert2Length;\r
2416   // UINT8  Cert2[];\r
2417   // ...\r
2418   // UINT32 CertnLength;\r
2419   // UINT8  Certn[];\r
2420   //\r
2421 \r
2422   The two following C-structure are used for parsing CertStack more clearly.\r
2423 **/\r
2424 #pragma pack(1)\r
2425 \r
2426 typedef struct {\r
2427   UINT32    CertDataLength;       // The length in bytes of X.509 certificate.\r
2428   UINT8     CertDataBuffer[0];    // The X.509 certificate content (DER).\r
2429 } EFI_CERT_DATA;\r
2430 \r
2431 typedef struct {\r
2432   UINT8             CertNumber;   // Number of X.509 certificate.\r
2433   //EFI_CERT_DATA   CertArray[];  // An array of X.509 certificate.\r
2434 } EFI_CERT_STACK;\r
2435 \r
2436 #pragma pack()\r
2437 \r
2438 /**\r
2439   Get the signer's certificates from PKCS#7 signed data as described in "PKCS #7:\r
2440   Cryptographic Message Syntax Standard". The input signed data could be wrapped\r
2441   in a ContentInfo structure.\r
2442 \r
2443   If P7Data, CertStack, StackLength, TrustedCert or CertLength is NULL, then\r
2444   return FALSE. If P7Length overflow, then return FALSE.\r
2445   If this interface is not supported, then return FALSE.\r
2446 \r
2447   @param[in]  P7Data       Pointer to the PKCS#7 message to verify.\r
2448   @param[in]  P7Length     Length of the PKCS#7 message in bytes.\r
2449   @param[out] CertStack    Pointer to Signer's certificates retrieved from P7Data.\r
2450                            It's caller's responsibility to free the buffer with\r
2451                            Pkcs7FreeSigners().\r
2452                            This data structure is EFI_CERT_STACK type.\r
2453   @param[out] StackLength  Length of signer's certificates in bytes.\r
2454   @param[out] TrustedCert  Pointer to a trusted certificate from Signer's certificates.\r
2455                            It's caller's responsibility to free the buffer with\r
2456                            Pkcs7FreeSigners().\r
2457   @param[out] CertLength   Length of the trusted certificate in bytes.\r
2458 \r
2459   @retval  TRUE            The operation is finished successfully.\r
2460   @retval  FALSE           Error occurs during the operation.\r
2461   @retval  FALSE           This interface is not supported.\r
2462 \r
2463 **/\r
2464 BOOLEAN\r
2465 EFIAPI\r
2466 Pkcs7GetSigners (\r
2467   IN  CONST UINT8  *P7Data,\r
2468   IN  UINTN        P7Length,\r
2469   OUT UINT8        **CertStack,\r
2470   OUT UINTN        *StackLength,\r
2471   OUT UINT8        **TrustedCert,\r
2472   OUT UINTN        *CertLength\r
2473   );\r
2474 \r
2475 /**\r
2476   Wrap function to use free() to free allocated memory for certificates.\r
2477 \r
2478   If this interface is not supported, then ASSERT().\r
2479 \r
2480   @param[in]  Certs        Pointer to the certificates to be freed.\r
2481 \r
2482 **/\r
2483 VOID\r
2484 EFIAPI\r
2485 Pkcs7FreeSigners (\r
2486   IN  UINT8        *Certs\r
2487   );\r
2488 \r
2489 /**\r
2490   Retrieves all embedded certificates from PKCS#7 signed data as described in "PKCS #7:\r
2491   Cryptographic Message Syntax Standard", and outputs two certificate lists chained and\r
2492   unchained to the signer's certificates.\r
2493   The input signed data could be wrapped in a ContentInfo structure.\r
2494 \r
2495   @param[in]  P7Data            Pointer to the PKCS#7 message.\r
2496   @param[in]  P7Length          Length of the PKCS#7 message in bytes.\r
2497   @param[out] SignerChainCerts  Pointer to the certificates list chained to signer's\r
2498                                 certificate. It's caller's responsibility to free the buffer\r
2499                                 with Pkcs7FreeSigners().\r
2500                                 This data structure is EFI_CERT_STACK type.\r
2501   @param[out] ChainLength       Length of the chained certificates list buffer in bytes.\r
2502   @param[out] UnchainCerts      Pointer to the unchained certificates lists. It's caller's\r
2503                                 responsibility to free the buffer with Pkcs7FreeSigners().\r
2504                                 This data structure is EFI_CERT_STACK type.\r
2505   @param[out] UnchainLength     Length of the unchained certificates list buffer in bytes.\r
2506 \r
2507   @retval  TRUE         The operation is finished successfully.\r
2508   @retval  FALSE        Error occurs during the operation.\r
2509 \r
2510 **/\r
2511 BOOLEAN\r
2512 EFIAPI\r
2513 Pkcs7GetCertificatesList (\r
2514   IN  CONST UINT8  *P7Data,\r
2515   IN  UINTN        P7Length,\r
2516   OUT UINT8        **SignerChainCerts,\r
2517   OUT UINTN        *ChainLength,\r
2518   OUT UINT8        **UnchainCerts,\r
2519   OUT UINTN        *UnchainLength\r
2520   );\r
2521 \r
2522 /**\r
2523   Creates a PKCS#7 signedData as described in "PKCS #7: Cryptographic Message\r
2524   Syntax Standard, version 1.5". This interface is only intended to be used for\r
2525   application to perform PKCS#7 functionality validation.\r
2526 \r
2527   If this interface is not supported, then return FALSE.\r
2528 \r
2529   @param[in]  PrivateKey       Pointer to the PEM-formatted private key data for\r
2530                                data signing.\r
2531   @param[in]  PrivateKeySize   Size of the PEM private key data in bytes.\r
2532   @param[in]  KeyPassword      NULL-terminated passphrase used for encrypted PEM\r
2533                                key data.\r
2534   @param[in]  InData           Pointer to the content to be signed.\r
2535   @param[in]  InDataSize       Size of InData in bytes.\r
2536   @param[in]  SignCert         Pointer to signer's DER-encoded certificate to sign with.\r
2537   @param[in]  OtherCerts       Pointer to an optional additional set of certificates to\r
2538                                include in the PKCS#7 signedData (e.g. any intermediate\r
2539                                CAs in the chain).\r
2540   @param[out] SignedData       Pointer to output PKCS#7 signedData. It's caller's\r
2541                                responsibility to free the buffer with FreePool().\r
2542   @param[out] SignedDataSize   Size of SignedData in bytes.\r
2543 \r
2544   @retval     TRUE             PKCS#7 data signing succeeded.\r
2545   @retval     FALSE            PKCS#7 data signing failed.\r
2546   @retval     FALSE            This interface is not supported.\r
2547 \r
2548 **/\r
2549 BOOLEAN\r
2550 EFIAPI\r
2551 Pkcs7Sign (\r
2552   IN   CONST UINT8  *PrivateKey,\r
2553   IN   UINTN        PrivateKeySize,\r
2554   IN   CONST UINT8  *KeyPassword,\r
2555   IN   UINT8        *InData,\r
2556   IN   UINTN        InDataSize,\r
2557   IN   UINT8        *SignCert,\r
2558   IN   UINT8        *OtherCerts      OPTIONAL,\r
2559   OUT  UINT8        **SignedData,\r
2560   OUT  UINTN        *SignedDataSize\r
2561   );\r
2562 \r
2563 /**\r
2564   Verifies the validity of a PKCS#7 signed data as described in "PKCS #7:\r
2565   Cryptographic Message Syntax Standard". The input signed data could be wrapped\r
2566   in a ContentInfo structure.\r
2567 \r
2568   If P7Data, TrustedCert or InData is NULL, then return FALSE.\r
2569   If P7Length, CertLength or DataLength overflow, then return FALSE.\r
2570   If this interface is not supported, then return FALSE.\r
2571 \r
2572   @param[in]  P7Data       Pointer to the PKCS#7 message to verify.\r
2573   @param[in]  P7Length     Length of the PKCS#7 message in bytes.\r
2574   @param[in]  TrustedCert  Pointer to a trusted/root certificate encoded in DER, which\r
2575                            is used for certificate chain verification.\r
2576   @param[in]  CertLength   Length of the trusted certificate in bytes.\r
2577   @param[in]  InData       Pointer to the content to be verified.\r
2578   @param[in]  DataLength   Length of InData in bytes.\r
2579 \r
2580   @retval  TRUE  The specified PKCS#7 signed data is valid.\r
2581   @retval  FALSE Invalid PKCS#7 signed data.\r
2582   @retval  FALSE This interface is not supported.\r
2583 \r
2584 **/\r
2585 BOOLEAN\r
2586 EFIAPI\r
2587 Pkcs7Verify (\r
2588   IN  CONST UINT8  *P7Data,\r
2589   IN  UINTN        P7Length,\r
2590   IN  CONST UINT8  *TrustedCert,\r
2591   IN  UINTN        CertLength,\r
2592   IN  CONST UINT8  *InData,\r
2593   IN  UINTN        DataLength\r
2594   );\r
2595 \r
2596 /**\r
2597   This function receives a PKCS7 formatted signature, and then verifies that\r
2598   the specified Enhanced or Extended Key Usages (EKU's) are present in the end-entity\r
2599   leaf signing certificate.\r
2600   Note that this function does not validate the certificate chain.\r
2601 \r
2602   Applications for custom EKU's are quite flexible. For example, a policy EKU\r
2603   may be present in an Issuing Certificate Authority (CA), and any sub-ordinate\r
2604   certificate issued might also contain this EKU, thus constraining the\r
2605   sub-ordinate certificate.  Other applications might allow a certificate\r
2606   embedded in a device to specify that other Object Identifiers (OIDs) are\r
2607   present which contains binary data specifying custom capabilities that\r
2608   the device is able to do.\r
2609 \r
2610   @param[in]  Pkcs7Signature       The PKCS#7 signed information content block. An array\r
2611                                    containing the content block with both the signature,\r
2612                                    the signer's certificate, and any necessary intermediate\r
2613                                    certificates.\r
2614   @param[in]  Pkcs7SignatureSize   Number of bytes in Pkcs7Signature.\r
2615   @param[in]  RequiredEKUs         Array of null-terminated strings listing OIDs of\r
2616                                    required EKUs that must be present in the signature.\r
2617   @param[in]  RequiredEKUsSize     Number of elements in the RequiredEKUs string array.\r
2618   @param[in]  RequireAllPresent    If this is TRUE, then all of the specified EKU's\r
2619                                    must be present in the leaf signer.  If it is\r
2620                                    FALSE, then we will succeed if we find any\r
2621                                    of the specified EKU's.\r
2622 \r
2623   @retval EFI_SUCCESS              The required EKUs were found in the signature.\r
2624   @retval EFI_INVALID_PARAMETER    A parameter was invalid.\r
2625   @retval EFI_NOT_FOUND            One or more EKU's were not found in the signature.\r
2626 \r
2627 **/\r
2628 RETURN_STATUS\r
2629 EFIAPI\r
2630 VerifyEKUsInPkcs7Signature (\r
2631   IN  CONST UINT8   *Pkcs7Signature,\r
2632   IN  CONST UINT32  SignatureSize,\r
2633   IN  CONST CHAR8   *RequiredEKUs[],\r
2634   IN  CONST UINT32  RequiredEKUsSize,\r
2635   IN  BOOLEAN       RequireAllPresent\r
2636   );\r
2637 \r
2638 /**\r
2639   Extracts the attached content from a PKCS#7 signed data if existed. The input signed\r
2640   data could be wrapped in a ContentInfo structure.\r
2641 \r
2642   If P7Data, Content, or ContentSize is NULL, then return FALSE. If P7Length overflow,\r
2643   then return FALSE. If the P7Data is not correctly formatted, then return FALSE.\r
2644 \r
2645   Caution: This function may receive untrusted input. So this function will do\r
2646            basic check for PKCS#7 data structure.\r
2647 \r
2648   @param[in]   P7Data       Pointer to the PKCS#7 signed data to process.\r
2649   @param[in]   P7Length     Length of the PKCS#7 signed data in bytes.\r
2650   @param[out]  Content      Pointer to the extracted content from the PKCS#7 signedData.\r
2651                             It's caller's responsibility to free the buffer with FreePool().\r
2652   @param[out]  ContentSize  The size of the extracted content in bytes.\r
2653 \r
2654   @retval     TRUE          The P7Data was correctly formatted for processing.\r
2655   @retval     FALSE         The P7Data was not correctly formatted for processing.\r
2656 \r
2657 **/\r
2658 BOOLEAN\r
2659 EFIAPI\r
2660 Pkcs7GetAttachedContent (\r
2661   IN  CONST UINT8  *P7Data,\r
2662   IN  UINTN        P7Length,\r
2663   OUT VOID         **Content,\r
2664   OUT UINTN        *ContentSize\r
2665   );\r
2666 \r
2667 /**\r
2668   Verifies the validity of a PE/COFF Authenticode Signature as described in "Windows\r
2669   Authenticode Portable Executable Signature Format".\r
2670 \r
2671   If AuthData is NULL, then return FALSE.\r
2672   If ImageHash is NULL, then return FALSE.\r
2673   If this interface is not supported, then return FALSE.\r
2674 \r
2675   @param[in]  AuthData     Pointer to the Authenticode Signature retrieved from signed\r
2676                            PE/COFF image to be verified.\r
2677   @param[in]  DataSize     Size of the Authenticode Signature in bytes.\r
2678   @param[in]  TrustedCert  Pointer to a trusted/root certificate encoded in DER, which\r
2679                            is used for certificate chain verification.\r
2680   @param[in]  CertSize     Size of the trusted certificate in bytes.\r
2681   @param[in]  ImageHash    Pointer to the original image file hash value. The procedure\r
2682                            for calculating the image hash value is described in Authenticode\r
2683                            specification.\r
2684   @param[in]  HashSize     Size of Image hash value in bytes.\r
2685 \r
2686   @retval  TRUE   The specified Authenticode Signature is valid.\r
2687   @retval  FALSE  Invalid Authenticode Signature.\r
2688   @retval  FALSE  This interface is not supported.\r
2689 \r
2690 **/\r
2691 BOOLEAN\r
2692 EFIAPI\r
2693 AuthenticodeVerify (\r
2694   IN  CONST UINT8  *AuthData,\r
2695   IN  UINTN        DataSize,\r
2696   IN  CONST UINT8  *TrustedCert,\r
2697   IN  UINTN        CertSize,\r
2698   IN  CONST UINT8  *ImageHash,\r
2699   IN  UINTN        HashSize\r
2700   );\r
2701 \r
2702 /**\r
2703   Verifies the validity of a RFC3161 Timestamp CounterSignature embedded in PE/COFF Authenticode\r
2704   signature.\r
2705 \r
2706   If AuthData is NULL, then return FALSE.\r
2707   If this interface is not supported, then return FALSE.\r
2708 \r
2709   @param[in]  AuthData     Pointer to the Authenticode Signature retrieved from signed\r
2710                            PE/COFF image to be verified.\r
2711   @param[in]  DataSize     Size of the Authenticode Signature in bytes.\r
2712   @param[in]  TsaCert      Pointer to a trusted/root TSA certificate encoded in DER, which\r
2713                            is used for TSA certificate chain verification.\r
2714   @param[in]  CertSize     Size of the trusted certificate in bytes.\r
2715   @param[out] SigningTime  Return the time of timestamp generation time if the timestamp\r
2716                            signature is valid.\r
2717 \r
2718   @retval  TRUE   The specified Authenticode includes a valid RFC3161 Timestamp CounterSignature.\r
2719   @retval  FALSE  No valid RFC3161 Timestamp CounterSignature in the specified Authenticode data.\r
2720 \r
2721 **/\r
2722 BOOLEAN\r
2723 EFIAPI\r
2724 ImageTimestampVerify (\r
2725   IN  CONST UINT8  *AuthData,\r
2726   IN  UINTN        DataSize,\r
2727   IN  CONST UINT8  *TsaCert,\r
2728   IN  UINTN        CertSize,\r
2729   OUT EFI_TIME     *SigningTime\r
2730   );\r
2731 \r
2732 //=====================================================================================\r
2733 //    DH Key Exchange Primitive\r
2734 //=====================================================================================\r
2735 \r
2736 /**\r
2737   Allocates and Initializes one Diffie-Hellman Context for subsequent use.\r
2738 \r
2739   @return  Pointer to the Diffie-Hellman Context that has been initialized.\r
2740            If the allocations fails, DhNew() returns NULL.\r
2741            If the interface is not supported, DhNew() returns NULL.\r
2742 \r
2743 **/\r
2744 VOID *\r
2745 EFIAPI\r
2746 DhNew (\r
2747   VOID\r
2748   );\r
2749 \r
2750 /**\r
2751   Release the specified DH context.\r
2752 \r
2753   If the interface is not supported, then ASSERT().\r
2754 \r
2755   @param[in]  DhContext  Pointer to the DH context to be released.\r
2756 \r
2757 **/\r
2758 VOID\r
2759 EFIAPI\r
2760 DhFree (\r
2761   IN  VOID  *DhContext\r
2762   );\r
2763 \r
2764 /**\r
2765   Generates DH parameter.\r
2766 \r
2767   Given generator g, and length of prime number p in bits, this function generates p,\r
2768   and sets DH context according to value of g and p.\r
2769 \r
2770   Before this function can be invoked, pseudorandom number generator must be correctly\r
2771   initialized by RandomSeed().\r
2772 \r
2773   If DhContext is NULL, then return FALSE.\r
2774   If Prime is NULL, then return FALSE.\r
2775   If this interface is not supported, then return FALSE.\r
2776 \r
2777   @param[in, out]  DhContext    Pointer to the DH context.\r
2778   @param[in]       Generator    Value of generator.\r
2779   @param[in]       PrimeLength  Length in bits of prime to be generated.\r
2780   @param[out]      Prime        Pointer to the buffer to receive the generated prime number.\r
2781 \r
2782   @retval TRUE   DH parameter generation succeeded.\r
2783   @retval FALSE  Value of Generator is not supported.\r
2784   @retval FALSE  PRNG fails to generate random prime number with PrimeLength.\r
2785   @retval FALSE  This interface is not supported.\r
2786 \r
2787 **/\r
2788 BOOLEAN\r
2789 EFIAPI\r
2790 DhGenerateParameter (\r
2791   IN OUT  VOID   *DhContext,\r
2792   IN      UINTN  Generator,\r
2793   IN      UINTN  PrimeLength,\r
2794   OUT     UINT8  *Prime\r
2795   );\r
2796 \r
2797 /**\r
2798   Sets generator and prime parameters for DH.\r
2799 \r
2800   Given generator g, and prime number p, this function and sets DH\r
2801   context accordingly.\r
2802 \r
2803   If DhContext is NULL, then return FALSE.\r
2804   If Prime is NULL, then return FALSE.\r
2805   If this interface is not supported, then return FALSE.\r
2806 \r
2807   @param[in, out]  DhContext    Pointer to the DH context.\r
2808   @param[in]       Generator    Value of generator.\r
2809   @param[in]       PrimeLength  Length in bits of prime to be generated.\r
2810   @param[in]       Prime        Pointer to the prime number.\r
2811 \r
2812   @retval TRUE   DH parameter setting succeeded.\r
2813   @retval FALSE  Value of Generator is not supported.\r
2814   @retval FALSE  Value of Generator is not suitable for the Prime.\r
2815   @retval FALSE  Value of Prime is not a prime number.\r
2816   @retval FALSE  Value of Prime is not a safe prime number.\r
2817   @retval FALSE  This interface is not supported.\r
2818 \r
2819 **/\r
2820 BOOLEAN\r
2821 EFIAPI\r
2822 DhSetParameter (\r
2823   IN OUT  VOID         *DhContext,\r
2824   IN      UINTN        Generator,\r
2825   IN      UINTN        PrimeLength,\r
2826   IN      CONST UINT8  *Prime\r
2827   );\r
2828 \r
2829 /**\r
2830   Generates DH public key.\r
2831 \r
2832   This function generates random secret exponent, and computes the public key, which is\r
2833   returned via parameter PublicKey and PublicKeySize. DH context is updated accordingly.\r
2834   If the PublicKey buffer is too small to hold the public key, FALSE is returned and\r
2835   PublicKeySize is set to the required buffer size to obtain the public key.\r
2836 \r
2837   If DhContext is NULL, then return FALSE.\r
2838   If PublicKeySize is NULL, then return FALSE.\r
2839   If PublicKeySize is large enough but PublicKey is NULL, then return FALSE.\r
2840   If this interface is not supported, then return FALSE.\r
2841 \r
2842   @param[in, out]  DhContext      Pointer to the DH context.\r
2843   @param[out]      PublicKey      Pointer to the buffer to receive generated public key.\r
2844   @param[in, out]  PublicKeySize  On input, the size of PublicKey buffer in bytes.\r
2845                                  On output, the size of data returned in PublicKey buffer in bytes.\r
2846 \r
2847   @retval TRUE   DH public key generation succeeded.\r
2848   @retval FALSE  DH public key generation failed.\r
2849   @retval FALSE  PublicKeySize is not large enough.\r
2850   @retval FALSE  This interface is not supported.\r
2851 \r
2852 **/\r
2853 BOOLEAN\r
2854 EFIAPI\r
2855 DhGenerateKey (\r
2856   IN OUT  VOID   *DhContext,\r
2857   OUT     UINT8  *PublicKey,\r
2858   IN OUT  UINTN  *PublicKeySize\r
2859   );\r
2860 \r
2861 /**\r
2862   Computes exchanged common key.\r
2863 \r
2864   Given peer's public key, this function computes the exchanged common key, based on its own\r
2865   context including value of prime modulus and random secret exponent.\r
2866 \r
2867   If DhContext is NULL, then return FALSE.\r
2868   If PeerPublicKey is NULL, then return FALSE.\r
2869   If KeySize is NULL, then return FALSE.\r
2870   If Key is NULL, then return FALSE.\r
2871   If KeySize is not large enough, then return FALSE.\r
2872   If this interface is not supported, then return FALSE.\r
2873 \r
2874   @param[in, out]  DhContext          Pointer to the DH context.\r
2875   @param[in]       PeerPublicKey      Pointer to the peer's public key.\r
2876   @param[in]       PeerPublicKeySize  Size of peer's public key in bytes.\r
2877   @param[out]      Key                Pointer to the buffer to receive generated key.\r
2878   @param[in, out]  KeySize            On input, the size of Key buffer in bytes.\r
2879                                      On output, the size of data returned in Key buffer in bytes.\r
2880 \r
2881   @retval TRUE   DH exchanged key generation succeeded.\r
2882   @retval FALSE  DH exchanged key generation failed.\r
2883   @retval FALSE  KeySize is not large enough.\r
2884   @retval FALSE  This interface is not supported.\r
2885 \r
2886 **/\r
2887 BOOLEAN\r
2888 EFIAPI\r
2889 DhComputeKey (\r
2890   IN OUT  VOID         *DhContext,\r
2891   IN      CONST UINT8  *PeerPublicKey,\r
2892   IN      UINTN        PeerPublicKeySize,\r
2893   OUT     UINT8        *Key,\r
2894   IN OUT  UINTN        *KeySize\r
2895   );\r
2896 \r
2897 //=====================================================================================\r
2898 //    Pseudo-Random Generation Primitive\r
2899 //=====================================================================================\r
2900 \r
2901 /**\r
2902   Sets up the seed value for the pseudorandom number generator.\r
2903 \r
2904   This function sets up the seed value for the pseudorandom number generator.\r
2905   If Seed is not NULL, then the seed passed in is used.\r
2906   If Seed is NULL, then default seed is used.\r
2907   If this interface is not supported, then return FALSE.\r
2908 \r
2909   @param[in]  Seed      Pointer to seed value.\r
2910                         If NULL, default seed is used.\r
2911   @param[in]  SeedSize  Size of seed value.\r
2912                         If Seed is NULL, this parameter is ignored.\r
2913 \r
2914   @retval TRUE   Pseudorandom number generator has enough entropy for random generation.\r
2915   @retval FALSE  Pseudorandom number generator does not have enough entropy for random generation.\r
2916   @retval FALSE  This interface is not supported.\r
2917 \r
2918 **/\r
2919 BOOLEAN\r
2920 EFIAPI\r
2921 RandomSeed (\r
2922   IN  CONST  UINT8  *Seed  OPTIONAL,\r
2923   IN  UINTN         SeedSize\r
2924   );\r
2925 \r
2926 /**\r
2927   Generates a pseudorandom byte stream of the specified size.\r
2928 \r
2929   If Output is NULL, then return FALSE.\r
2930   If this interface is not supported, then return FALSE.\r
2931 \r
2932   @param[out]  Output  Pointer to buffer to receive random value.\r
2933   @param[in]   Size    Size of random bytes to generate.\r
2934 \r
2935   @retval TRUE   Pseudorandom byte stream generated successfully.\r
2936   @retval FALSE  Pseudorandom number generator fails to generate due to lack of entropy.\r
2937   @retval FALSE  This interface is not supported.\r
2938 \r
2939 **/\r
2940 BOOLEAN\r
2941 EFIAPI\r
2942 RandomBytes (\r
2943   OUT  UINT8  *Output,\r
2944   IN   UINTN  Size\r
2945   );\r
2946 \r
2947 #endif // __BASE_CRYPT_LIB_H__\r