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