VirtualBox

source: vbox/trunk/src/VBox/Devices/EFI/FirmwareNew/CryptoPkg/Include/Library/BaseCryptLib.h@ 108794

Last change on this file since 108794 was 108794, checked in by vboxsync, 2 weeks ago

Devices/EFI/FirmwareNew: Merge edk2-stable202502 from the vendor branch and make it build for the important platforms, bugref:4643
  • Property svn:eol-style set to native
File size: 139.0 KB
Line 
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
7Copyright (c) 2009 - 2022, Intel Corporation. All rights reserved.<BR>
8Copyright (c) Microsoft Corporation. All rights reserved.
9SPDX-License-Identifier: BSD-2-Clause-Patent
10
11**/
12
13#ifndef __BASE_CRYPT_LIB_H__
14#define __BASE_CRYPT_LIB_H__
15
16#include <Uefi/UefiBaseType.h>
17
18#define CRYPTO_NID_NULL 0x0000
19
20// Hash
21#define CRYPTO_NID_SHA256 0x0001
22#define CRYPTO_NID_SHA384 0x0002
23#define CRYPTO_NID_SHA512 0x0003
24
25// Key Exchange
26#define CRYPTO_NID_SECP256R1 0x0204
27#define CRYPTO_NID_SECP384R1 0x0205
28#define CRYPTO_NID_SECP521R1 0x0206
29#define CRYPTO_NID_BRAINPOOLP512R1 0x03A5
30
31///
32/// MD5 digest size in bytes
33///
34#define MD5_DIGEST_SIZE 16
35
36///
37/// SHA-1 digest size in bytes.
38///
39#define SHA1_DIGEST_SIZE 20
40
41///
42/// SHA-256 digest size in bytes
43///
44#define SHA256_DIGEST_SIZE 32
45
46///
47/// SHA-384 digest size in bytes
48///
49#define SHA384_DIGEST_SIZE 48
50
51///
52/// SHA-512 digest size in bytes
53///
54#define SHA512_DIGEST_SIZE 64
55
56///
57/// SM3 digest size in bytes
58///
59#define SM3_256_DIGEST_SIZE 32
60
61///
62/// TDES block size in bytes
63///
64#define TDES_BLOCK_SIZE 8
65
66///
67/// AES block size in bytes
68///
69#define AES_BLOCK_SIZE 16
70
71///
72/// RSA Key Tags Definition used in RsaSetKey() function for key component identification.
73///
74typedef enum {
75 RsaKeyN, ///< RSA public Modulus (N)
76 RsaKeyE, ///< RSA Public exponent (e)
77 RsaKeyD, ///< RSA Private exponent (d)
78 RsaKeyP, ///< RSA secret prime factor of Modulus (p)
79 RsaKeyQ, ///< RSA secret prime factor of Modules (q)
80 RsaKeyDp, ///< p's CRT exponent (== d mod (p - 1))
81 RsaKeyDq, ///< q's CRT exponent (== d mod (q - 1))
82 RsaKeyQInv ///< The CRT coefficient (== 1/q mod p)
83} RSA_KEY_TAG;
84
85// =====================================================================================
86// One-Way Cryptographic Hash Primitives
87// =====================================================================================
88
89#ifdef ENABLE_MD5_DEPRECATED_INTERFACES
90
91/**
92 Retrieves the size, in bytes, of the context buffer required for MD5 hash operations.
93
94 If this interface is not supported, then return zero.
95
96 @return The size, in bytes, of the context buffer required for MD5 hash operations.
97 @retval 0 This interface is not supported.
98
99**/
100UINTN
101EFIAPI
102Md5GetContextSize (
103 VOID
104 );
105
106/**
107 Initializes user-supplied memory pointed by Md5Context as MD5 hash context for
108 subsequent use.
109
110 If Md5Context is NULL, then return FALSE.
111 If this interface is not supported, then return FALSE.
112
113 @param[out] Md5Context Pointer to MD5 context being initialized.
114
115 @retval TRUE MD5 context initialization succeeded.
116 @retval FALSE MD5 context initialization failed.
117 @retval FALSE This interface is not supported.
118
119**/
120BOOLEAN
121EFIAPI
122Md5Init (
123 OUT VOID *Md5Context
124 );
125
126/**
127 Makes a copy of an existing MD5 context.
128
129 If Md5Context is NULL, then return FALSE.
130 If NewMd5Context is NULL, then return FALSE.
131 If this interface is not supported, then return FALSE.
132
133 @param[in] Md5Context Pointer to MD5 context being copied.
134 @param[out] NewMd5Context Pointer to new MD5 context.
135
136 @retval TRUE MD5 context copy succeeded.
137 @retval FALSE MD5 context copy failed.
138 @retval FALSE This interface is not supported.
139
140**/
141BOOLEAN
142EFIAPI
143Md5Duplicate (
144 IN CONST VOID *Md5Context,
145 OUT VOID *NewMd5Context
146 );
147
148/**
149 Digests the input data and updates MD5 context.
150
151 This function performs MD5 digest on a data buffer of the specified size.
152 It can be called multiple times to compute the digest of long or discontinuous data streams.
153 MD5 context should be already correctly initialized by Md5Init(), and should not be finalized
154 by Md5Final(). Behavior with invalid context is undefined.
155
156 If Md5Context is NULL, then return FALSE.
157 If this interface is not supported, then return FALSE.
158
159 @param[in, out] Md5Context Pointer to the MD5 context.
160 @param[in] Data Pointer to the buffer containing the data to be hashed.
161 @param[in] DataSize Size of Data buffer in bytes.
162
163 @retval TRUE MD5 data digest succeeded.
164 @retval FALSE MD5 data digest failed.
165 @retval FALSE This interface is not supported.
166
167**/
168BOOLEAN
169EFIAPI
170Md5Update (
171 IN OUT VOID *Md5Context,
172 IN CONST VOID *Data,
173 IN UINTN DataSize
174 );
175
176/**
177 Completes computation of the MD5 digest value.
178
179 This function completes MD5 hash computation and retrieves the digest value into
180 the specified memory. After this function has been called, the MD5 context cannot
181 be used again.
182 MD5 context should be already correctly initialized by Md5Init(), and should not be
183 finalized by Md5Final(). Behavior with invalid MD5 context is undefined.
184
185 If Md5Context is NULL, then return FALSE.
186 If HashValue is NULL, then return FALSE.
187 If this interface is not supported, then return FALSE.
188
189 @param[in, out] Md5Context Pointer to the MD5 context.
190 @param[out] HashValue Pointer to a buffer that receives the MD5 digest
191 value (16 bytes).
192
193 @retval TRUE MD5 digest computation succeeded.
194 @retval FALSE MD5 digest computation failed.
195 @retval FALSE This interface is not supported.
196
197**/
198BOOLEAN
199EFIAPI
200Md5Final (
201 IN OUT VOID *Md5Context,
202 OUT UINT8 *HashValue
203 );
204
205/**
206 Computes the MD5 message digest of a input data buffer.
207
208 This function performs the MD5 message digest of a given data buffer, and places
209 the digest value into the specified memory.
210
211 If this interface is not supported, then return FALSE.
212
213 @param[in] Data Pointer to the buffer containing the data to be hashed.
214 @param[in] DataSize Size of Data buffer in bytes.
215 @param[out] HashValue Pointer to a buffer that receives the MD5 digest
216 value (16 bytes).
217
218 @retval TRUE MD5 digest computation succeeded.
219 @retval FALSE MD5 digest computation failed.
220 @retval FALSE This interface is not supported.
221
222**/
223BOOLEAN
224EFIAPI
225Md5HashAll (
226 IN CONST VOID *Data,
227 IN UINTN DataSize,
228 OUT UINT8 *HashValue
229 );
230
231#endif
232
233#ifndef DISABLE_SHA1_DEPRECATED_INTERFACES
234
235/**
236 Retrieves the size, in bytes, of the context buffer required for SHA-1 hash operations.
237
238 If this interface is not supported, then return zero.
239
240 @return The size, in bytes, of the context buffer required for SHA-1 hash operations.
241 @retval 0 This interface is not supported.
242
243**/
244UINTN
245EFIAPI
246Sha1GetContextSize (
247 VOID
248 );
249
250/**
251 Initializes user-supplied memory pointed by Sha1Context as SHA-1 hash context for
252 subsequent use.
253
254 If Sha1Context is NULL, then return FALSE.
255 If this interface is not supported, then return FALSE.
256
257 @param[out] Sha1Context Pointer to SHA-1 context being initialized.
258
259 @retval TRUE SHA-1 context initialization succeeded.
260 @retval FALSE SHA-1 context initialization failed.
261 @retval FALSE This interface is not supported.
262
263**/
264BOOLEAN
265EFIAPI
266Sha1Init (
267 OUT VOID *Sha1Context
268 );
269
270/**
271 Makes a copy of an existing SHA-1 context.
272
273 If Sha1Context is NULL, then return FALSE.
274 If NewSha1Context is NULL, then return FALSE.
275 If this interface is not supported, then return FALSE.
276
277 @param[in] Sha1Context Pointer to SHA-1 context being copied.
278 @param[out] NewSha1Context Pointer to new SHA-1 context.
279
280 @retval TRUE SHA-1 context copy succeeded.
281 @retval FALSE SHA-1 context copy failed.
282 @retval FALSE This interface is not supported.
283
284**/
285BOOLEAN
286EFIAPI
287Sha1Duplicate (
288 IN CONST VOID *Sha1Context,
289 OUT VOID *NewSha1Context
290 );
291
292/**
293 Digests the input data and updates SHA-1 context.
294
295 This function performs SHA-1 digest on a data buffer of the specified size.
296 It can be called multiple times to compute the digest of long or discontinuous data streams.
297 SHA-1 context should be already correctly initialized by Sha1Init(), and should not be finalized
298 by Sha1Final(). Behavior with invalid context is undefined.
299
300 If Sha1Context is NULL, then return FALSE.
301 If this interface is not supported, then return FALSE.
302
303 @param[in, out] Sha1Context Pointer to the SHA-1 context.
304 @param[in] Data Pointer to the buffer containing the data to be hashed.
305 @param[in] DataSize Size of Data buffer in bytes.
306
307 @retval TRUE SHA-1 data digest succeeded.
308 @retval FALSE SHA-1 data digest failed.
309 @retval FALSE This interface is not supported.
310
311**/
312BOOLEAN
313EFIAPI
314Sha1Update (
315 IN OUT VOID *Sha1Context,
316 IN CONST VOID *Data,
317 IN UINTN DataSize
318 );
319
320/**
321 Completes computation of the SHA-1 digest value.
322
323 This function completes SHA-1 hash computation and retrieves the digest value into
324 the specified memory. After this function has been called, the SHA-1 context cannot
325 be used again.
326 SHA-1 context should be already correctly initialized by Sha1Init(), and should not be
327 finalized by Sha1Final(). Behavior with invalid SHA-1 context is undefined.
328
329 If Sha1Context is NULL, then return FALSE.
330 If HashValue is NULL, then return FALSE.
331 If this interface is not supported, then return FALSE.
332
333 @param[in, out] Sha1Context Pointer to the SHA-1 context.
334 @param[out] HashValue Pointer to a buffer that receives the SHA-1 digest
335 value (20 bytes).
336
337 @retval TRUE SHA-1 digest computation succeeded.
338 @retval FALSE SHA-1 digest computation failed.
339 @retval FALSE This interface is not supported.
340
341**/
342BOOLEAN
343EFIAPI
344Sha1Final (
345 IN OUT VOID *Sha1Context,
346 OUT UINT8 *HashValue
347 );
348
349/**
350 Computes the SHA-1 message digest of a input data buffer.
351
352 This function performs the SHA-1 message digest of a given data buffer, and places
353 the digest value into the specified memory.
354
355 If this interface is not supported, then return FALSE.
356
357 @param[in] Data Pointer to the buffer containing the data to be hashed.
358 @param[in] DataSize Size of Data buffer in bytes.
359 @param[out] HashValue Pointer to a buffer that receives the SHA-1 digest
360 value (20 bytes).
361
362 @retval TRUE SHA-1 digest computation succeeded.
363 @retval FALSE SHA-1 digest computation failed.
364 @retval FALSE This interface is not supported.
365
366**/
367BOOLEAN
368EFIAPI
369Sha1HashAll (
370 IN CONST VOID *Data,
371 IN UINTN DataSize,
372 OUT UINT8 *HashValue
373 );
374
375#endif
376
377/**
378 Retrieves the size, in bytes, of the context buffer required for SHA-256 hash operations.
379
380 @return The size, in bytes, of the context buffer required for SHA-256 hash operations.
381
382**/
383UINTN
384EFIAPI
385Sha256GetContextSize (
386 VOID
387 );
388
389/**
390 Initializes user-supplied memory pointed by Sha256Context as SHA-256 hash context for
391 subsequent use.
392
393 If Sha256Context is NULL, then return FALSE.
394
395 @param[out] Sha256Context Pointer to SHA-256 context being initialized.
396
397 @retval TRUE SHA-256 context initialization succeeded.
398 @retval FALSE SHA-256 context initialization failed.
399
400**/
401BOOLEAN
402EFIAPI
403Sha256Init (
404 OUT VOID *Sha256Context
405 );
406
407/**
408 Makes a copy of an existing SHA-256 context.
409
410 If Sha256Context is NULL, then return FALSE.
411 If NewSha256Context is NULL, then return FALSE.
412 If this interface is not supported, then return FALSE.
413
414 @param[in] Sha256Context Pointer to SHA-256 context being copied.
415 @param[out] NewSha256Context Pointer to new SHA-256 context.
416
417 @retval TRUE SHA-256 context copy succeeded.
418 @retval FALSE SHA-256 context copy failed.
419 @retval FALSE This interface is not supported.
420
421**/
422BOOLEAN
423EFIAPI
424Sha256Duplicate (
425 IN CONST VOID *Sha256Context,
426 OUT VOID *NewSha256Context
427 );
428
429/**
430 Digests the input data and updates SHA-256 context.
431
432 This function performs SHA-256 digest on a data buffer of the specified size.
433 It can be called multiple times to compute the digest of long or discontinuous data streams.
434 SHA-256 context should be already correctly initialized by Sha256Init(), and should not be finalized
435 by Sha256Final(). Behavior with invalid context is undefined.
436
437 If Sha256Context is NULL, then return FALSE.
438
439 @param[in, out] Sha256Context Pointer to the SHA-256 context.
440 @param[in] Data Pointer to the buffer containing the data to be hashed.
441 @param[in] DataSize Size of Data buffer in bytes.
442
443 @retval TRUE SHA-256 data digest succeeded.
444 @retval FALSE SHA-256 data digest failed.
445
446**/
447BOOLEAN
448EFIAPI
449Sha256Update (
450 IN OUT VOID *Sha256Context,
451 IN CONST VOID *Data,
452 IN UINTN DataSize
453 );
454
455/**
456 Completes computation of the SHA-256 digest value.
457
458 This function completes SHA-256 hash computation and retrieves the digest value into
459 the specified memory. After this function has been called, the SHA-256 context cannot
460 be used again.
461 SHA-256 context should be already correctly initialized by Sha256Init(), and should not be
462 finalized by Sha256Final(). Behavior with invalid SHA-256 context is undefined.
463
464 If Sha256Context is NULL, then return FALSE.
465 If HashValue is NULL, then return FALSE.
466
467 @param[in, out] Sha256Context Pointer to the SHA-256 context.
468 @param[out] HashValue Pointer to a buffer that receives the SHA-256 digest
469 value (32 bytes).
470
471 @retval TRUE SHA-256 digest computation succeeded.
472 @retval FALSE SHA-256 digest computation failed.
473
474**/
475BOOLEAN
476EFIAPI
477Sha256Final (
478 IN OUT VOID *Sha256Context,
479 OUT UINT8 *HashValue
480 );
481
482/**
483 Computes the SHA-256 message digest of a input data buffer.
484
485 This function performs the SHA-256 message digest of a given data buffer, and places
486 the digest value into the specified memory.
487
488 If this interface is not supported, then return FALSE.
489
490 @param[in] Data Pointer to the buffer containing the data to be hashed.
491 @param[in] DataSize Size of Data buffer in bytes.
492 @param[out] HashValue Pointer to a buffer that receives the SHA-256 digest
493 value (32 bytes).
494
495 @retval TRUE SHA-256 digest computation succeeded.
496 @retval FALSE SHA-256 digest computation failed.
497 @retval FALSE This interface is not supported.
498
499**/
500BOOLEAN
501EFIAPI
502Sha256HashAll (
503 IN CONST VOID *Data,
504 IN UINTN DataSize,
505 OUT UINT8 *HashValue
506 );
507
508/**
509 Retrieves the size, in bytes, of the context buffer required for SHA-384 hash operations.
510
511 @return The size, in bytes, of the context buffer required for SHA-384 hash operations.
512
513**/
514UINTN
515EFIAPI
516Sha384GetContextSize (
517 VOID
518 );
519
520/**
521 Initializes user-supplied memory pointed by Sha384Context as SHA-384 hash context for
522 subsequent use.
523
524 If Sha384Context is NULL, then return FALSE.
525
526 @param[out] Sha384Context Pointer to SHA-384 context being initialized.
527
528 @retval TRUE SHA-384 context initialization succeeded.
529 @retval FALSE SHA-384 context initialization failed.
530
531**/
532BOOLEAN
533EFIAPI
534Sha384Init (
535 OUT VOID *Sha384Context
536 );
537
538/**
539 Makes a copy of an existing SHA-384 context.
540
541 If Sha384Context is NULL, then return FALSE.
542 If NewSha384Context is NULL, then return FALSE.
543 If this interface is not supported, then return FALSE.
544
545 @param[in] Sha384Context Pointer to SHA-384 context being copied.
546 @param[out] NewSha384Context Pointer to new SHA-384 context.
547
548 @retval TRUE SHA-384 context copy succeeded.
549 @retval FALSE SHA-384 context copy failed.
550 @retval FALSE This interface is not supported.
551
552**/
553BOOLEAN
554EFIAPI
555Sha384Duplicate (
556 IN CONST VOID *Sha384Context,
557 OUT VOID *NewSha384Context
558 );
559
560/**
561 Digests the input data and updates SHA-384 context.
562
563 This function performs SHA-384 digest on a data buffer of the specified size.
564 It can be called multiple times to compute the digest of long or discontinuous data streams.
565 SHA-384 context should be already correctly initialized by Sha384Init(), and should not be finalized
566 by Sha384Final(). Behavior with invalid context is undefined.
567
568 If Sha384Context is NULL, then return FALSE.
569
570 @param[in, out] Sha384Context Pointer to the SHA-384 context.
571 @param[in] Data Pointer to the buffer containing the data to be hashed.
572 @param[in] DataSize Size of Data buffer in bytes.
573
574 @retval TRUE SHA-384 data digest succeeded.
575 @retval FALSE SHA-384 data digest failed.
576
577**/
578BOOLEAN
579EFIAPI
580Sha384Update (
581 IN OUT VOID *Sha384Context,
582 IN CONST VOID *Data,
583 IN UINTN DataSize
584 );
585
586/**
587 Completes computation of the SHA-384 digest value.
588
589 This function completes SHA-384 hash computation and retrieves the digest value into
590 the specified memory. After this function has been called, the SHA-384 context cannot
591 be used again.
592 SHA-384 context should be already correctly initialized by Sha384Init(), and should not be
593 finalized by Sha384Final(). Behavior with invalid SHA-384 context is undefined.
594
595 If Sha384Context is NULL, then return FALSE.
596 If HashValue is NULL, then return FALSE.
597
598 @param[in, out] Sha384Context Pointer to the SHA-384 context.
599 @param[out] HashValue Pointer to a buffer that receives the SHA-384 digest
600 value (48 bytes).
601
602 @retval TRUE SHA-384 digest computation succeeded.
603 @retval FALSE SHA-384 digest computation failed.
604
605**/
606BOOLEAN
607EFIAPI
608Sha384Final (
609 IN OUT VOID *Sha384Context,
610 OUT UINT8 *HashValue
611 );
612
613/**
614 Computes the SHA-384 message digest of a input data buffer.
615
616 This function performs the SHA-384 message digest of a given data buffer, and places
617 the digest value into the specified memory.
618
619 If this interface is not supported, then return FALSE.
620
621 @param[in] Data Pointer to the buffer containing the data to be hashed.
622 @param[in] DataSize Size of Data buffer in bytes.
623 @param[out] HashValue Pointer to a buffer that receives the SHA-384 digest
624 value (48 bytes).
625
626 @retval TRUE SHA-384 digest computation succeeded.
627 @retval FALSE SHA-384 digest computation failed.
628 @retval FALSE This interface is not supported.
629
630**/
631BOOLEAN
632EFIAPI
633Sha384HashAll (
634 IN CONST VOID *Data,
635 IN UINTN DataSize,
636 OUT UINT8 *HashValue
637 );
638
639/**
640 Retrieves the size, in bytes, of the context buffer required for SHA-512 hash operations.
641
642 @return The size, in bytes, of the context buffer required for SHA-512 hash operations.
643
644**/
645UINTN
646EFIAPI
647Sha512GetContextSize (
648 VOID
649 );
650
651/**
652 Initializes user-supplied memory pointed by Sha512Context as SHA-512 hash context for
653 subsequent use.
654
655 If Sha512Context is NULL, then return FALSE.
656
657 @param[out] Sha512Context Pointer to SHA-512 context being initialized.
658
659 @retval TRUE SHA-512 context initialization succeeded.
660 @retval FALSE SHA-512 context initialization failed.
661
662**/
663BOOLEAN
664EFIAPI
665Sha512Init (
666 OUT VOID *Sha512Context
667 );
668
669/**
670 Makes a copy of an existing SHA-512 context.
671
672 If Sha512Context is NULL, then return FALSE.
673 If NewSha512Context is NULL, then return FALSE.
674 If this interface is not supported, then return FALSE.
675
676 @param[in] Sha512Context Pointer to SHA-512 context being copied.
677 @param[out] NewSha512Context Pointer to new SHA-512 context.
678
679 @retval TRUE SHA-512 context copy succeeded.
680 @retval FALSE SHA-512 context copy failed.
681 @retval FALSE This interface is not supported.
682
683**/
684BOOLEAN
685EFIAPI
686Sha512Duplicate (
687 IN CONST VOID *Sha512Context,
688 OUT VOID *NewSha512Context
689 );
690
691/**
692 Digests the input data and updates SHA-512 context.
693
694 This function performs SHA-512 digest on a data buffer of the specified size.
695 It can be called multiple times to compute the digest of long or discontinuous data streams.
696 SHA-512 context should be already correctly initialized by Sha512Init(), and should not be finalized
697 by Sha512Final(). Behavior with invalid context is undefined.
698
699 If Sha512Context is NULL, then return FALSE.
700
701 @param[in, out] Sha512Context Pointer to the SHA-512 context.
702 @param[in] Data Pointer to the buffer containing the data to be hashed.
703 @param[in] DataSize Size of Data buffer in bytes.
704
705 @retval TRUE SHA-512 data digest succeeded.
706 @retval FALSE SHA-512 data digest failed.
707
708**/
709BOOLEAN
710EFIAPI
711Sha512Update (
712 IN OUT VOID *Sha512Context,
713 IN CONST VOID *Data,
714 IN UINTN DataSize
715 );
716
717/**
718 Completes computation of the SHA-512 digest value.
719
720 This function completes SHA-512 hash computation and retrieves the digest value into
721 the specified memory. After this function has been called, the SHA-512 context cannot
722 be used again.
723 SHA-512 context should be already correctly initialized by Sha512Init(), and should not be
724 finalized by Sha512Final(). Behavior with invalid SHA-512 context is undefined.
725
726 If Sha512Context is NULL, then return FALSE.
727 If HashValue is NULL, then return FALSE.
728
729 @param[in, out] Sha512Context Pointer to the SHA-512 context.
730 @param[out] HashValue Pointer to a buffer that receives the SHA-512 digest
731 value (64 bytes).
732
733 @retval TRUE SHA-512 digest computation succeeded.
734 @retval FALSE SHA-512 digest computation failed.
735
736**/
737BOOLEAN
738EFIAPI
739Sha512Final (
740 IN OUT VOID *Sha512Context,
741 OUT UINT8 *HashValue
742 );
743
744/**
745 Computes the SHA-512 message digest of a input data buffer.
746
747 This function performs the SHA-512 message digest of a given data buffer, and places
748 the digest value into the specified memory.
749
750 If this interface is not supported, then return FALSE.
751
752 @param[in] Data Pointer to the buffer containing the data to be hashed.
753 @param[in] DataSize Size of Data buffer in bytes.
754 @param[out] HashValue Pointer to a buffer that receives the SHA-512 digest
755 value (64 bytes).
756
757 @retval TRUE SHA-512 digest computation succeeded.
758 @retval FALSE SHA-512 digest computation failed.
759 @retval FALSE This interface is not supported.
760
761**/
762BOOLEAN
763EFIAPI
764Sha512HashAll (
765 IN CONST VOID *Data,
766 IN UINTN DataSize,
767 OUT UINT8 *HashValue
768 );
769
770/**
771 Parallel hash function ParallelHash256, as defined in NIST's Special Publication 800-185,
772 published December 2016.
773
774 @param[in] Input Pointer to the input message (X).
775 @param[in] InputByteLen The number(>0) of input bytes provided for the input data.
776 @param[in] BlockSize The size of each block (B).
777 @param[out] Output Pointer to the output buffer.
778 @param[in] OutputByteLen The desired number of output bytes (L).
779 @param[in] Customization Pointer to the customization string (S).
780 @param[in] CustomByteLen The length of the customization string in bytes.
781
782 @retval TRUE ParallelHash256 digest computation succeeded.
783 @retval FALSE ParallelHash256 digest computation failed.
784 @retval FALSE This interface is not supported.
785
786**/
787BOOLEAN
788EFIAPI
789ParallelHash256HashAll (
790 IN CONST VOID *Input,
791 IN UINTN InputByteLen,
792 IN UINTN BlockSize,
793 OUT VOID *Output,
794 IN UINTN OutputByteLen,
795 IN CONST VOID *Customization,
796 IN UINTN CustomByteLen
797 );
798
799/**
800 Retrieves the size, in bytes, of the context buffer required for SM3 hash operations.
801
802 @return The size, in bytes, of the context buffer required for SM3 hash operations.
803
804**/
805UINTN
806EFIAPI
807Sm3GetContextSize (
808 VOID
809 );
810
811/**
812 Initializes user-supplied memory pointed by Sm3Context as SM3 hash context for
813 subsequent use.
814
815 If Sm3Context is NULL, then return FALSE.
816
817 @param[out] Sm3Context Pointer to SM3 context being initialized.
818
819 @retval TRUE SM3 context initialization succeeded.
820 @retval FALSE SM3 context initialization failed.
821
822**/
823BOOLEAN
824EFIAPI
825Sm3Init (
826 OUT VOID *Sm3Context
827 );
828
829/**
830 Makes a copy of an existing SM3 context.
831
832 If Sm3Context is NULL, then return FALSE.
833 If NewSm3Context is NULL, then return FALSE.
834 If this interface is not supported, then return FALSE.
835
836 @param[in] Sm3Context Pointer to SM3 context being copied.
837 @param[out] NewSm3Context Pointer to new SM3 context.
838
839 @retval TRUE SM3 context copy succeeded.
840 @retval FALSE SM3 context copy failed.
841 @retval FALSE This interface is not supported.
842
843**/
844BOOLEAN
845EFIAPI
846Sm3Duplicate (
847 IN CONST VOID *Sm3Context,
848 OUT VOID *NewSm3Context
849 );
850
851/**
852 Digests the input data and updates SM3 context.
853
854 This function performs SM3 digest on a data buffer of the specified size.
855 It can be called multiple times to compute the digest of long or discontinuous data streams.
856 SM3 context should be already correctly initialized by Sm3Init(), and should not be finalized
857 by Sm3Final(). Behavior with invalid context is undefined.
858
859 If Sm3Context is NULL, then return FALSE.
860
861 @param[in, out] Sm3Context Pointer to the SM3 context.
862 @param[in] Data Pointer to the buffer containing the data to be hashed.
863 @param[in] DataSize Size of Data buffer in bytes.
864
865 @retval TRUE SM3 data digest succeeded.
866 @retval FALSE SM3 data digest failed.
867
868**/
869BOOLEAN
870EFIAPI
871Sm3Update (
872 IN OUT VOID *Sm3Context,
873 IN CONST VOID *Data,
874 IN UINTN DataSize
875 );
876
877/**
878 Completes computation of the SM3 digest value.
879
880 This function completes SM3 hash computation and retrieves the digest value into
881 the specified memory. After this function has been called, the SM3 context cannot
882 be used again.
883 SM3 context should be already correctly initialized by Sm3Init(), and should not be
884 finalized by Sm3Final(). Behavior with invalid SM3 context is undefined.
885
886 If Sm3Context is NULL, then return FALSE.
887 If HashValue is NULL, then return FALSE.
888
889 @param[in, out] Sm3Context Pointer to the SM3 context.
890 @param[out] HashValue Pointer to a buffer that receives the SM3 digest
891 value (32 bytes).
892
893 @retval TRUE SM3 digest computation succeeded.
894 @retval FALSE SM3 digest computation failed.
895
896**/
897BOOLEAN
898EFIAPI
899Sm3Final (
900 IN OUT VOID *Sm3Context,
901 OUT UINT8 *HashValue
902 );
903
904/**
905 Computes the SM3 message digest of a input data buffer.
906
907 This function performs the SM3 message digest of a given data buffer, and places
908 the digest value into the specified memory.
909
910 If this interface is not supported, then return FALSE.
911
912 @param[in] Data Pointer to the buffer containing the data to be hashed.
913 @param[in] DataSize Size of Data buffer in bytes.
914 @param[out] HashValue Pointer to a buffer that receives the SM3 digest
915 value (32 bytes).
916
917 @retval TRUE SM3 digest computation succeeded.
918 @retval FALSE SM3 digest computation failed.
919 @retval FALSE This interface is not supported.
920
921**/
922BOOLEAN
923EFIAPI
924Sm3HashAll (
925 IN CONST VOID *Data,
926 IN UINTN DataSize,
927 OUT UINT8 *HashValue
928 );
929
930// =====================================================================================
931// MAC (Message Authentication Code) Primitive
932// =====================================================================================
933
934/**
935 Allocates and initializes one HMAC_CTX context for subsequent HMAC-SHA256 use.
936
937 @return Pointer to the HMAC_CTX context that has been initialized.
938 If the allocations fails, HmacSha256New() returns NULL.
939
940**/
941VOID *
942EFIAPI
943HmacSha256New (
944 VOID
945 );
946
947/**
948 Release the specified HMAC_CTX context.
949
950 @param[in] HmacSha256Ctx Pointer to the HMAC_CTX context to be released.
951
952**/
953VOID
954EFIAPI
955HmacSha256Free (
956 IN VOID *HmacSha256Ctx
957 );
958
959/**
960 Set user-supplied key for subsequent use. It must be done before any
961 calling to HmacSha256Update().
962
963 If HmacSha256Context is NULL, then return FALSE.
964 If this interface is not supported, then return FALSE.
965
966 @param[out] HmacSha256Context Pointer to HMAC-SHA256 context.
967 @param[in] Key Pointer to the user-supplied key.
968 @param[in] KeySize Key size in bytes.
969
970 @retval TRUE The Key is set successfully.
971 @retval FALSE The Key is set unsuccessfully.
972 @retval FALSE This interface is not supported.
973
974**/
975BOOLEAN
976EFIAPI
977HmacSha256SetKey (
978 OUT VOID *HmacSha256Context,
979 IN CONST UINT8 *Key,
980 IN UINTN KeySize
981 );
982
983/**
984 Makes a copy of an existing HMAC-SHA256 context.
985
986 If HmacSha256Context is NULL, then return FALSE.
987 If NewHmacSha256Context is NULL, then return FALSE.
988 If this interface is not supported, then return FALSE.
989
990 @param[in] HmacSha256Context Pointer to HMAC-SHA256 context being copied.
991 @param[out] NewHmacSha256Context Pointer to new HMAC-SHA256 context.
992
993 @retval TRUE HMAC-SHA256 context copy succeeded.
994 @retval FALSE HMAC-SHA256 context copy failed.
995 @retval FALSE This interface is not supported.
996
997**/
998BOOLEAN
999EFIAPI
1000HmacSha256Duplicate (
1001 IN CONST VOID *HmacSha256Context,
1002 OUT VOID *NewHmacSha256Context
1003 );
1004
1005/**
1006 Digests the input data and updates HMAC-SHA256 context.
1007
1008 This function performs HMAC-SHA256 digest on a data buffer of the specified size.
1009 It can be called multiple times to compute the digest of long or discontinuous data streams.
1010 HMAC-SHA256 context should be initialized by HmacSha256New(), and should not be finalized
1011 by HmacSha256Final(). Behavior with invalid context is undefined.
1012
1013 If HmacSha256Context is NULL, then return FALSE.
1014 If this interface is not supported, then return FALSE.
1015
1016 @param[in, out] HmacSha256Context Pointer to the HMAC-SHA256 context.
1017 @param[in] Data Pointer to the buffer containing the data to be digested.
1018 @param[in] DataSize Size of Data buffer in bytes.
1019
1020 @retval TRUE HMAC-SHA256 data digest succeeded.
1021 @retval FALSE HMAC-SHA256 data digest failed.
1022 @retval FALSE This interface is not supported.
1023
1024**/
1025BOOLEAN
1026EFIAPI
1027HmacSha256Update (
1028 IN OUT VOID *HmacSha256Context,
1029 IN CONST VOID *Data,
1030 IN UINTN DataSize
1031 );
1032
1033/**
1034 Completes computation of the HMAC-SHA256 digest value.
1035
1036 This function completes HMAC-SHA256 hash computation and retrieves the digest value into
1037 the specified memory. After this function has been called, the HMAC-SHA256 context cannot
1038 be used again.
1039 HMAC-SHA256 context should be initialized by HmacSha256New(), and should not be finalized
1040 by HmacSha256Final(). Behavior with invalid HMAC-SHA256 context is undefined.
1041
1042 If HmacSha256Context is NULL, then return FALSE.
1043 If HmacValue is NULL, then return FALSE.
1044 If this interface is not supported, then return FALSE.
1045
1046 @param[in, out] HmacSha256Context Pointer to the HMAC-SHA256 context.
1047 @param[out] HmacValue Pointer to a buffer that receives the HMAC-SHA256 digest
1048 value (32 bytes).
1049
1050 @retval TRUE HMAC-SHA256 digest computation succeeded.
1051 @retval FALSE HMAC-SHA256 digest computation failed.
1052 @retval FALSE This interface is not supported.
1053
1054**/
1055BOOLEAN
1056EFIAPI
1057HmacSha256Final (
1058 IN OUT VOID *HmacSha256Context,
1059 OUT UINT8 *HmacValue
1060 );
1061
1062/**
1063 Computes the HMAC-SHA256 digest of a input data buffer.
1064
1065 This function performs the HMAC-SHA256 digest of a given data buffer, and places
1066 the digest value into the specified memory.
1067
1068 If this interface is not supported, then return FALSE.
1069
1070 @param[in] Data Pointer to the buffer containing the data to be digested.
1071 @param[in] DataSize Size of Data buffer in bytes.
1072 @param[in] Key Pointer to the user-supplied key.
1073 @param[in] KeySize Key size in bytes.
1074 @param[out] HashValue Pointer to a buffer that receives the HMAC-SHA256 digest
1075 value (32 bytes).
1076
1077 @retval TRUE HMAC-SHA256 digest computation succeeded.
1078 @retval FALSE HMAC-SHA256 digest computation failed.
1079 @retval FALSE This interface is not supported.
1080
1081**/
1082BOOLEAN
1083EFIAPI
1084HmacSha256All (
1085 IN CONST VOID *Data,
1086 IN UINTN DataSize,
1087 IN CONST UINT8 *Key,
1088 IN UINTN KeySize,
1089 OUT UINT8 *HmacValue
1090 );
1091
1092/**
1093 Allocates and initializes one HMAC_CTX context for subsequent HMAC-SHA384 use.
1094
1095 @return Pointer to the HMAC_CTX context that has been initialized.
1096 If the allocations fails, HmacSha384New() returns NULL.
1097
1098**/
1099VOID *
1100EFIAPI
1101HmacSha384New (
1102 VOID
1103 );
1104
1105/**
1106 Release the specified HMAC_CTX context.
1107
1108 @param[in] HmacSha384Ctx Pointer to the HMAC_CTX context to be released.
1109
1110**/
1111VOID
1112EFIAPI
1113HmacSha384Free (
1114 IN VOID *HmacSha384Ctx
1115 );
1116
1117/**
1118 Set user-supplied key for subsequent use. It must be done before any
1119 calling to HmacSha384Update().
1120
1121 If HmacSha384Context is NULL, then return FALSE.
1122 If this interface is not supported, then return FALSE.
1123
1124 @param[out] HmacSha384Context Pointer to HMAC-SHA384 context.
1125 @param[in] Key Pointer to the user-supplied key.
1126 @param[in] KeySize Key size in bytes.
1127
1128 @retval TRUE The Key is set successfully.
1129 @retval FALSE The Key is set unsuccessfully.
1130 @retval FALSE This interface is not supported.
1131
1132**/
1133BOOLEAN
1134EFIAPI
1135HmacSha384SetKey (
1136 OUT VOID *HmacSha384Context,
1137 IN CONST UINT8 *Key,
1138 IN UINTN KeySize
1139 );
1140
1141/**
1142 Makes a copy of an existing HMAC-SHA384 context.
1143
1144 If HmacSha384Context is NULL, then return FALSE.
1145 If NewHmacSha384Context is NULL, then return FALSE.
1146 If this interface is not supported, then return FALSE.
1147
1148 @param[in] HmacSha384Context Pointer to HMAC-SHA384 context being copied.
1149 @param[out] NewHmacSha384Context Pointer to new HMAC-SHA384 context.
1150
1151 @retval TRUE HMAC-SHA384 context copy succeeded.
1152 @retval FALSE HMAC-SHA384 context copy failed.
1153 @retval FALSE This interface is not supported.
1154
1155**/
1156BOOLEAN
1157EFIAPI
1158HmacSha384Duplicate (
1159 IN CONST VOID *HmacSha384Context,
1160 OUT VOID *NewHmacSha384Context
1161 );
1162
1163/**
1164 Digests the input data and updates HMAC-SHA384 context.
1165
1166 This function performs HMAC-SHA384 digest on a data buffer of the specified size.
1167 It can be called multiple times to compute the digest of long or discontinuous data streams.
1168 HMAC-SHA384 context should be initialized by HmacSha384New(), and should not be finalized
1169 by HmacSha384Final(). Behavior with invalid context is undefined.
1170
1171 If HmacSha384Context is NULL, then return FALSE.
1172 If this interface is not supported, then return FALSE.
1173
1174 @param[in, out] HmacSha384Context Pointer to the HMAC-SHA384 context.
1175 @param[in] Data Pointer to the buffer containing the data to be digested.
1176 @param[in] DataSize Size of Data buffer in bytes.
1177
1178 @retval TRUE HMAC-SHA384 data digest succeeded.
1179 @retval FALSE HMAC-SHA384 data digest failed.
1180 @retval FALSE This interface is not supported.
1181
1182**/
1183BOOLEAN
1184EFIAPI
1185HmacSha384Update (
1186 IN OUT VOID *HmacSha384Context,
1187 IN CONST VOID *Data,
1188 IN UINTN DataSize
1189 );
1190
1191/**
1192 Completes computation of the HMAC-SHA384 digest value.
1193
1194 This function completes HMAC-SHA384 hash computation and retrieves the digest value into
1195 the specified memory. After this function has been called, the HMAC-SHA384 context cannot
1196 be used again.
1197 HMAC-SHA384 context should be initialized by HmacSha384New(), and should not be finalized
1198 by HmacSha384Final(). Behavior with invalid HMAC-SHA384 context is undefined.
1199
1200 If HmacSha384Context is NULL, then return FALSE.
1201 If HmacValue is NULL, then return FALSE.
1202 If this interface is not supported, then return FALSE.
1203
1204 @param[in, out] HmacSha384Context Pointer to the HMAC-SHA384 context.
1205 @param[out] HmacValue Pointer to a buffer that receives the HMAC-SHA384 digest
1206 value (48 bytes).
1207
1208 @retval TRUE HMAC-SHA384 digest computation succeeded.
1209 @retval FALSE HMAC-SHA384 digest computation failed.
1210 @retval FALSE This interface is not supported.
1211
1212**/
1213BOOLEAN
1214EFIAPI
1215HmacSha384Final (
1216 IN OUT VOID *HmacSha384Context,
1217 OUT UINT8 *HmacValue
1218 );
1219
1220/**
1221 Computes the HMAC-SHA384 digest of a input data buffer.
1222
1223 This function performs the HMAC-SHA384 digest of a given data buffer, and places
1224 the digest value into the specified memory.
1225
1226 If this interface is not supported, then return FALSE.
1227
1228 @param[in] Data Pointer to the buffer containing the data to be digested.
1229 @param[in] DataSize Size of Data buffer in bytes.
1230 @param[in] Key Pointer to the user-supplied key.
1231 @param[in] KeySize Key size in bytes.
1232 @param[out] HashValue Pointer to a buffer that receives the HMAC-SHA384 digest
1233 value (48 bytes).
1234
1235 @retval TRUE HMAC-SHA384 digest computation succeeded.
1236 @retval FALSE HMAC-SHA384 digest computation failed.
1237 @retval FALSE This interface is not supported.
1238
1239**/
1240BOOLEAN
1241EFIAPI
1242HmacSha384All (
1243 IN CONST VOID *Data,
1244 IN UINTN DataSize,
1245 IN CONST UINT8 *Key,
1246 IN UINTN KeySize,
1247 OUT UINT8 *HmacValue
1248 );
1249
1250// =====================================================================================
1251// Symmetric Cryptography Primitive
1252// =====================================================================================
1253
1254/**
1255 Retrieves the size, in bytes, of the context buffer required for AES operations.
1256
1257 If this interface is not supported, then return zero.
1258
1259 @return The size, in bytes, of the context buffer required for AES operations.
1260 @retval 0 This interface is not supported.
1261
1262**/
1263UINTN
1264EFIAPI
1265AesGetContextSize (
1266 VOID
1267 );
1268
1269/**
1270 Initializes user-supplied memory as AES context for subsequent use.
1271
1272 This function initializes user-supplied memory pointed by AesContext as AES context.
1273 In addition, it sets up all AES key materials for subsequent encryption and decryption
1274 operations.
1275 There are 3 options for key length, 128 bits, 192 bits, and 256 bits.
1276
1277 If AesContext is NULL, then return FALSE.
1278 If Key is NULL, then return FALSE.
1279 If KeyLength is not valid, then return FALSE.
1280 If this interface is not supported, then return FALSE.
1281
1282 @param[out] AesContext Pointer to AES context being initialized.
1283 @param[in] Key Pointer to the user-supplied AES key.
1284 @param[in] KeyLength Length of AES key in bits.
1285
1286 @retval TRUE AES context initialization succeeded.
1287 @retval FALSE AES context initialization failed.
1288 @retval FALSE This interface is not supported.
1289
1290**/
1291BOOLEAN
1292EFIAPI
1293AesInit (
1294 OUT VOID *AesContext,
1295 IN CONST UINT8 *Key,
1296 IN UINTN KeyLength
1297 );
1298
1299/**
1300 Performs AES encryption on a data buffer of the specified size in CBC mode.
1301
1302 This function performs AES encryption on data buffer pointed by Input, of specified
1303 size of InputSize, in CBC mode.
1304 InputSize must be multiple of block size (16 bytes). This function does not perform
1305 padding. Caller must perform padding, if necessary, to ensure valid input data size.
1306 Initialization vector should be one block size (16 bytes).
1307 AesContext should be already correctly initialized by AesInit(). Behavior with
1308 invalid AES context is undefined.
1309
1310 If AesContext is NULL, then return FALSE.
1311 If Input is NULL, then return FALSE.
1312 If InputSize is not multiple of block size (16 bytes), then return FALSE.
1313 If Ivec is NULL, then return FALSE.
1314 If Output is NULL, then return FALSE.
1315 If this interface is not supported, then return FALSE.
1316
1317 @param[in] AesContext Pointer to the AES context.
1318 @param[in] Input Pointer to the buffer containing the data to be encrypted.
1319 @param[in] InputSize Size of the Input buffer in bytes.
1320 @param[in] Ivec Pointer to initialization vector.
1321 @param[out] Output Pointer to a buffer that receives the AES encryption output.
1322
1323 @retval TRUE AES encryption succeeded.
1324 @retval FALSE AES encryption failed.
1325 @retval FALSE This interface is not supported.
1326
1327**/
1328BOOLEAN
1329EFIAPI
1330AesCbcEncrypt (
1331 IN VOID *AesContext,
1332 IN CONST UINT8 *Input,
1333 IN UINTN InputSize,
1334 IN CONST UINT8 *Ivec,
1335 OUT UINT8 *Output
1336 );
1337
1338/**
1339 Performs AES decryption on a data buffer of the specified size in CBC mode.
1340
1341 This function performs AES decryption on data buffer pointed by Input, of specified
1342 size of InputSize, in CBC mode.
1343 InputSize must be multiple of block size (16 bytes). This function does not perform
1344 padding. Caller must perform padding, if necessary, to ensure valid input data size.
1345 Initialization vector should be one block size (16 bytes).
1346 AesContext should be already correctly initialized by AesInit(). Behavior with
1347 invalid AES context is undefined.
1348
1349 If AesContext is NULL, then return FALSE.
1350 If Input is NULL, then return FALSE.
1351 If InputSize is not multiple of block size (16 bytes), then return FALSE.
1352 If Ivec is NULL, then return FALSE.
1353 If Output is NULL, then return FALSE.
1354 If this interface is not supported, then return FALSE.
1355
1356 @param[in] AesContext Pointer to the AES context.
1357 @param[in] Input Pointer to the buffer containing the data to be encrypted.
1358 @param[in] InputSize Size of the Input buffer in bytes.
1359 @param[in] Ivec Pointer to initialization vector.
1360 @param[out] Output Pointer to a buffer that receives the AES encryption output.
1361
1362 @retval TRUE AES decryption succeeded.
1363 @retval FALSE AES decryption failed.
1364 @retval FALSE This interface is not supported.
1365
1366**/
1367BOOLEAN
1368EFIAPI
1369AesCbcDecrypt (
1370 IN VOID *AesContext,
1371 IN CONST UINT8 *Input,
1372 IN UINTN InputSize,
1373 IN CONST UINT8 *Ivec,
1374 OUT UINT8 *Output
1375 );
1376
1377// =====================================================================================
1378// Authenticated Encryption with Associated Data (AEAD) Cryptography Primitive
1379// =====================================================================================
1380
1381/**
1382 Performs AEAD AES-GCM authenticated encryption on a data buffer and additional authenticated data (AAD).
1383
1384 IvSize must be 12, otherwise FALSE is returned.
1385 KeySize must be 16, 24 or 32, otherwise FALSE is returned.
1386 TagSize must be 12, 13, 14, 15, 16, otherwise FALSE is returned.
1387
1388 @param[in] Key Pointer to the encryption key.
1389 @param[in] KeySize Size of the encryption key in bytes.
1390 @param[in] Iv Pointer to the IV value.
1391 @param[in] IvSize Size of the IV value in bytes.
1392 @param[in] AData Pointer to the additional authenticated data (AAD).
1393 @param[in] ADataSize Size of the additional authenticated data (AAD) in bytes.
1394 @param[in] DataIn Pointer to the input data buffer to be encrypted.
1395 @param[in] DataInSize Size of the input data buffer in bytes.
1396 @param[out] TagOut Pointer to a buffer that receives the authentication tag output.
1397 @param[in] TagSize Size of the authentication tag in bytes.
1398 @param[out] DataOut Pointer to a buffer that receives the encryption output.
1399 @param[out] DataOutSize Size of the output data buffer in bytes.
1400
1401 @retval TRUE AEAD AES-GCM authenticated encryption succeeded.
1402 @retval FALSE AEAD AES-GCM authenticated encryption failed.
1403
1404**/
1405BOOLEAN
1406EFIAPI
1407AeadAesGcmEncrypt (
1408 IN CONST UINT8 *Key,
1409 IN UINTN KeySize,
1410 IN CONST UINT8 *Iv,
1411 IN UINTN IvSize,
1412 IN CONST UINT8 *AData,
1413 IN UINTN ADataSize,
1414 IN CONST UINT8 *DataIn,
1415 IN UINTN DataInSize,
1416 OUT UINT8 *TagOut,
1417 IN UINTN TagSize,
1418 OUT UINT8 *DataOut,
1419 OUT UINTN *DataOutSize
1420 );
1421
1422/**
1423 Performs AEAD AES-GCM authenticated decryption on a data buffer and additional authenticated data (AAD).
1424
1425 IvSize must be 12, otherwise FALSE is returned.
1426 KeySize must be 16, 24 or 32, otherwise FALSE is returned.
1427 TagSize must be 12, 13, 14, 15, 16, otherwise FALSE is returned.
1428 If additional authenticated data verification fails, FALSE is returned.
1429
1430 @param[in] Key Pointer to the encryption key.
1431 @param[in] KeySize Size of the encryption key in bytes.
1432 @param[in] Iv Pointer to the IV value.
1433 @param[in] IvSize Size of the IV value in bytes.
1434 @param[in] AData Pointer to the additional authenticated data (AAD).
1435 @param[in] ADataSize Size of the additional authenticated data (AAD) in bytes.
1436 @param[in] DataIn Pointer to the input data buffer to be decrypted.
1437 @param[in] DataInSize Size of the input data buffer in bytes.
1438 @param[in] Tag Pointer to a buffer that contains the authentication tag.
1439 @param[in] TagSize Size of the authentication tag in bytes.
1440 @param[out] DataOut Pointer to a buffer that receives the decryption output.
1441 @param[out] DataOutSize Size of the output data buffer in bytes.
1442
1443 @retval TRUE AEAD AES-GCM authenticated decryption succeeded.
1444 @retval FALSE AEAD AES-GCM authenticated decryption failed.
1445
1446**/
1447BOOLEAN
1448EFIAPI
1449AeadAesGcmDecrypt (
1450 IN CONST UINT8 *Key,
1451 IN UINTN KeySize,
1452 IN CONST UINT8 *Iv,
1453 IN UINTN IvSize,
1454 IN CONST UINT8 *AData,
1455 IN UINTN ADataSize,
1456 IN CONST UINT8 *DataIn,
1457 IN UINTN DataInSize,
1458 IN CONST UINT8 *Tag,
1459 IN UINTN TagSize,
1460 OUT UINT8 *DataOut,
1461 OUT UINTN *DataOutSize
1462 );
1463
1464// =====================================================================================
1465// Asymmetric Cryptography Primitive
1466// =====================================================================================
1467
1468/**
1469 Allocates and initializes one RSA context for subsequent use.
1470
1471 @return Pointer to the RSA context that has been initialized.
1472 If the allocations fails, RsaNew() returns NULL.
1473
1474**/
1475VOID *
1476EFIAPI
1477RsaNew (
1478 VOID
1479 );
1480
1481/**
1482 Release the specified RSA context.
1483
1484 If RsaContext is NULL, then return FALSE.
1485
1486 @param[in] RsaContext Pointer to the RSA context to be released.
1487
1488**/
1489VOID
1490EFIAPI
1491RsaFree (
1492 IN VOID *RsaContext
1493 );
1494
1495/**
1496 Sets the tag-designated key component into the established RSA context.
1497
1498 This function sets the tag-designated RSA key component into the established
1499 RSA context from the user-specified non-negative integer (octet string format
1500 represented in RSA PKCS#1).
1501 If BigNumber is NULL, then the specified key component in RSA context is cleared.
1502
1503 If RsaContext is NULL, then return FALSE.
1504
1505 @param[in, out] RsaContext Pointer to RSA context being set.
1506 @param[in] KeyTag Tag of RSA key component being set.
1507 @param[in] BigNumber Pointer to octet integer buffer.
1508 If NULL, then the specified key component in RSA
1509 context is cleared.
1510 @param[in] BnSize Size of big number buffer in bytes.
1511 If BigNumber is NULL, then it is ignored.
1512
1513 @retval TRUE RSA key component was set successfully.
1514 @retval FALSE Invalid RSA key component tag.
1515
1516**/
1517BOOLEAN
1518EFIAPI
1519RsaSetKey (
1520 IN OUT VOID *RsaContext,
1521 IN RSA_KEY_TAG KeyTag,
1522 IN CONST UINT8 *BigNumber,
1523 IN UINTN BnSize
1524 );
1525
1526/**
1527 Gets the tag-designated RSA key component from the established RSA context.
1528
1529 This function retrieves the tag-designated RSA key component from the
1530 established RSA context as a non-negative integer (octet string format
1531 represented in RSA PKCS#1).
1532 If specified key component has not been set or has been cleared, then returned
1533 BnSize is set to 0.
1534 If the BigNumber buffer is too small to hold the contents of the key, FALSE
1535 is returned and BnSize is set to the required buffer size to obtain the key.
1536
1537 If RsaContext is NULL, then return FALSE.
1538 If BnSize is NULL, then return FALSE.
1539 If BnSize is large enough but BigNumber is NULL, then return FALSE.
1540 If this interface is not supported, 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[out] BigNumber Pointer to octet integer buffer.
1545 @param[in, out] BnSize On input, the size of big number buffer in bytes.
1546 On output, the size of data returned in big number buffer in bytes.
1547
1548 @retval TRUE RSA key component was retrieved successfully.
1549 @retval FALSE Invalid RSA key component tag.
1550 @retval FALSE BnSize is too small.
1551 @retval FALSE This interface is not supported.
1552
1553**/
1554BOOLEAN
1555EFIAPI
1556RsaGetKey (
1557 IN OUT VOID *RsaContext,
1558 IN RSA_KEY_TAG KeyTag,
1559 OUT UINT8 *BigNumber,
1560 IN OUT UINTN *BnSize
1561 );
1562
1563/**
1564 Generates RSA key components.
1565
1566 This function generates RSA key components. It takes RSA public exponent E and
1567 length in bits of RSA modulus N as input, and generates all key components.
1568 If PublicExponent is NULL, the default RSA public exponent (0x10001) will be used.
1569
1570 Before this function can be invoked, pseudorandom number generator must be correctly
1571 initialized by RandomSeed().
1572
1573 If RsaContext is NULL, then return FALSE.
1574 If this interface is not supported, then return FALSE.
1575
1576 @param[in, out] RsaContext Pointer to RSA context being set.
1577 @param[in] ModulusLength Length of RSA modulus N in bits.
1578 @param[in] PublicExponent Pointer to RSA public exponent.
1579 @param[in] PublicExponentSize Size of RSA public exponent buffer in bytes.
1580
1581 @retval TRUE RSA key component was generated successfully.
1582 @retval FALSE Invalid RSA key component tag.
1583 @retval FALSE This interface is not supported.
1584
1585**/
1586BOOLEAN
1587EFIAPI
1588RsaGenerateKey (
1589 IN OUT VOID *RsaContext,
1590 IN UINTN ModulusLength,
1591 IN CONST UINT8 *PublicExponent,
1592 IN UINTN PublicExponentSize
1593 );
1594
1595/**
1596 Validates key components of RSA context.
1597 NOTE: This function performs integrity checks on all the RSA key material, so
1598 the RSA key structure must contain all the private key data.
1599
1600 This function validates key components of RSA context in following aspects:
1601 - Whether p is a prime
1602 - Whether q is a prime
1603 - Whether n = p * q
1604 - Whether d*e = 1 mod lcm(p-1,q-1)
1605
1606 If RsaContext is NULL, then return FALSE.
1607 If this interface is not supported, then return FALSE.
1608
1609 @param[in] RsaContext Pointer to RSA context to check.
1610
1611 @retval TRUE RSA key components are valid.
1612 @retval FALSE RSA key components are not valid.
1613 @retval FALSE This interface is not supported.
1614
1615**/
1616BOOLEAN
1617EFIAPI
1618RsaCheckKey (
1619 IN VOID *RsaContext
1620 );
1621
1622/**
1623 Carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme.
1624
1625 This function carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme defined in
1626 RSA PKCS#1.
1627 If the Signature buffer is too small to hold the contents of signature, FALSE
1628 is returned and SigSize is set to the required buffer size to obtain the signature.
1629
1630 If RsaContext is NULL, then return FALSE.
1631 If MessageHash is NULL, then return FALSE.
1632 If HashSize is not equal to the size of MD5, SHA-1 or SHA-256 digest, then return FALSE.
1633 If SigSize is large enough but Signature is NULL, then return FALSE.
1634 If this interface is not supported, then return FALSE.
1635
1636 @param[in] RsaContext Pointer to RSA context for signature generation.
1637 @param[in] MessageHash Pointer to octet message hash to be signed.
1638 @param[in] HashSize Size of the message hash in bytes.
1639 @param[out] Signature Pointer to buffer to receive RSA PKCS1-v1_5 signature.
1640 @param[in, out] SigSize On input, the size of Signature buffer in bytes.
1641 On output, the size of data returned in Signature buffer in bytes.
1642
1643 @retval TRUE Signature successfully generated in PKCS1-v1_5.
1644 @retval FALSE Signature generation failed.
1645 @retval FALSE SigSize is too small.
1646 @retval FALSE This interface is not supported.
1647
1648**/
1649BOOLEAN
1650EFIAPI
1651RsaPkcs1Sign (
1652 IN VOID *RsaContext,
1653 IN CONST UINT8 *MessageHash,
1654 IN UINTN HashSize,
1655 OUT UINT8 *Signature,
1656 IN OUT UINTN *SigSize
1657 );
1658
1659/**
1660 Verifies the RSA-SSA signature with EMSA-PKCS1-v1_5 encoding scheme defined in
1661 RSA PKCS#1.
1662
1663 If RsaContext is NULL, then return FALSE.
1664 If MessageHash is NULL, then return FALSE.
1665 If Signature is NULL, then return FALSE.
1666 If HashSize is not equal to the size of MD5, SHA-1, SHA-256 digest, then return FALSE.
1667
1668 @param[in] RsaContext Pointer to RSA context for signature verification.
1669 @param[in] MessageHash Pointer to octet message hash to be checked.
1670 @param[in] HashSize Size of the message hash in bytes.
1671 @param[in] Signature Pointer to RSA PKCS1-v1_5 signature to be verified.
1672 @param[in] SigSize Size of signature in bytes.
1673
1674 @retval TRUE Valid signature encoded in PKCS1-v1_5.
1675 @retval FALSE Invalid signature or invalid RSA context.
1676
1677**/
1678BOOLEAN
1679EFIAPI
1680RsaPkcs1Verify (
1681 IN VOID *RsaContext,
1682 IN CONST UINT8 *MessageHash,
1683 IN UINTN HashSize,
1684 IN CONST UINT8 *Signature,
1685 IN UINTN SigSize
1686 );
1687
1688/**
1689 Carries out the RSA-SSA signature generation with EMSA-PSS encoding scheme.
1690
1691 This function carries out the RSA-SSA signature generation with EMSA-PSS encoding scheme defined in
1692 RFC 8017.
1693 Mask generation function is the same as the message digest algorithm.
1694 If the Signature buffer is too small to hold the contents of signature, FALSE
1695 is returned and SigSize is set to the required buffer size to obtain the signature.
1696
1697 If RsaContext is NULL, then return FALSE.
1698 If Message is NULL, then return FALSE.
1699 If MsgSize is zero or > INT_MAX, then return FALSE.
1700 If DigestLen is NOT 32, 48 or 64, return FALSE.
1701 If SaltLen is not equal to DigestLen, then return FALSE.
1702 If SigSize is large enough but Signature is NULL, then return FALSE.
1703 If this interface is not supported, then return FALSE.
1704
1705 @param[in] RsaContext Pointer to RSA context for signature generation.
1706 @param[in] Message Pointer to octet message to be signed.
1707 @param[in] MsgSize Size of the message in bytes.
1708 @param[in] DigestLen Length of the digest in bytes to be used for RSA signature operation.
1709 @param[in] SaltLen Length of the salt in bytes to be used for PSS encoding.
1710 @param[out] Signature Pointer to buffer to receive RSA PSS signature.
1711 @param[in, out] SigSize On input, the size of Signature buffer in bytes.
1712 On output, the size of data returned in Signature buffer in bytes.
1713
1714 @retval TRUE Signature successfully generated in RSASSA-PSS.
1715 @retval FALSE Signature generation failed.
1716 @retval FALSE SigSize is too small.
1717 @retval FALSE This interface is not supported.
1718
1719**/
1720BOOLEAN
1721EFIAPI
1722RsaPssSign (
1723 IN VOID *RsaContext,
1724 IN CONST UINT8 *Message,
1725 IN UINTN MsgSize,
1726 IN UINT16 DigestLen,
1727 IN UINT16 SaltLen,
1728 OUT UINT8 *Signature,
1729 IN OUT UINTN *SigSize
1730 );
1731
1732/**
1733 Verifies the RSA signature with RSASSA-PSS signature scheme defined in RFC 8017.
1734 Implementation determines salt length automatically from the signature encoding.
1735 Mask generation function is the same as the message digest algorithm.
1736 Salt length should be equal to digest length.
1737
1738 @param[in] RsaContext Pointer to RSA context for signature verification.
1739 @param[in] Message Pointer to octet message to be verified.
1740 @param[in] MsgSize Size of the message in bytes.
1741 @param[in] Signature Pointer to RSASSA-PSS signature to be verified.
1742 @param[in] SigSize Size of signature in bytes.
1743 @param[in] DigestLen Length of digest for RSA operation.
1744 @param[in] SaltLen Salt length for PSS encoding.
1745
1746 @retval TRUE Valid signature encoded in RSASSA-PSS.
1747 @retval FALSE Invalid signature or invalid RSA context.
1748
1749**/
1750BOOLEAN
1751EFIAPI
1752RsaPssVerify (
1753 IN VOID *RsaContext,
1754 IN CONST UINT8 *Message,
1755 IN UINTN MsgSize,
1756 IN CONST UINT8 *Signature,
1757 IN UINTN SigSize,
1758 IN UINT16 DigestLen,
1759 IN UINT16 SaltLen
1760 );
1761
1762/**
1763 Retrieve the RSA Private Key from the password-protected PEM key data.
1764
1765 If PemData is NULL, then return FALSE.
1766 If RsaContext is NULL, then return FALSE.
1767 If this interface is not supported, then return FALSE.
1768
1769 @param[in] PemData Pointer to the PEM-encoded key data to be retrieved.
1770 @param[in] PemSize Size of the PEM key data in bytes.
1771 @param[in] Password NULL-terminated passphrase used for encrypted PEM key data.
1772 @param[out] RsaContext Pointer to new-generated RSA context which contain the retrieved
1773 RSA private key component. Use RsaFree() function to free the
1774 resource.
1775
1776 @retval TRUE RSA Private Key was retrieved successfully.
1777 @retval FALSE Invalid PEM key data or incorrect password.
1778 @retval FALSE This interface is not supported.
1779
1780**/
1781BOOLEAN
1782EFIAPI
1783RsaGetPrivateKeyFromPem (
1784 IN CONST UINT8 *PemData,
1785 IN UINTN PemSize,
1786 IN CONST CHAR8 *Password,
1787 OUT VOID **RsaContext
1788 );
1789
1790/**
1791 Retrieve the RSA Public Key from one DER-encoded X509 certificate.
1792
1793 If Cert is NULL, then return FALSE.
1794 If RsaContext is NULL, then return FALSE.
1795 If this interface is not supported, then return FALSE.
1796
1797 @param[in] Cert Pointer to the DER-encoded X509 certificate.
1798 @param[in] CertSize Size of the X509 certificate in bytes.
1799 @param[out] RsaContext Pointer to new-generated RSA context which contain the retrieved
1800 RSA public key component. Use RsaFree() function to free the
1801 resource.
1802
1803 @retval TRUE RSA Public Key was retrieved successfully.
1804 @retval FALSE Fail to retrieve RSA public key from X509 certificate.
1805 @retval FALSE This interface is not supported.
1806
1807**/
1808BOOLEAN
1809EFIAPI
1810RsaGetPublicKeyFromX509 (
1811 IN CONST UINT8 *Cert,
1812 IN UINTN CertSize,
1813 OUT VOID **RsaContext
1814 );
1815
1816/**
1817 Retrieve the subject bytes from one X.509 certificate.
1818
1819 If Cert is NULL, then return FALSE.
1820 If SubjectSize is NULL, then return FALSE.
1821 If this interface is not supported, then return FALSE.
1822
1823 @param[in] Cert Pointer to the DER-encoded X509 certificate.
1824 @param[in] CertSize Size of the X509 certificate in bytes.
1825 @param[out] CertSubject Pointer to the retrieved certificate subject bytes.
1826 @param[in, out] SubjectSize The size in bytes of the CertSubject buffer on input,
1827 and the size of buffer returned CertSubject on output.
1828
1829 @retval TRUE The certificate subject retrieved successfully.
1830 @retval FALSE Invalid certificate, or the SubjectSize is too small for the result.
1831 The SubjectSize will be updated with the required size.
1832 @retval FALSE This interface is not supported.
1833
1834**/
1835BOOLEAN
1836EFIAPI
1837X509GetSubjectName (
1838 IN CONST UINT8 *Cert,
1839 IN UINTN CertSize,
1840 OUT UINT8 *CertSubject,
1841 IN OUT UINTN *SubjectSize
1842 );
1843
1844/**
1845 Retrieve the common name (CN) string from one X.509 certificate.
1846
1847 @param[in] Cert Pointer to the DER-encoded X509 certificate.
1848 @param[in] CertSize Size of the X509 certificate in bytes.
1849 @param[out] CommonName Buffer to contain the retrieved certificate common
1850 name string (UTF8). At most CommonNameSize bytes will be
1851 written and the string will be null terminated. May be
1852 NULL in order to determine the size buffer needed.
1853 @param[in,out] CommonNameSize The size in bytes of the CommonName buffer on input,
1854 and the size of buffer returned CommonName on output.
1855 If CommonName is NULL then the amount of space needed
1856 in buffer (including the final null) is returned.
1857
1858 @retval RETURN_SUCCESS The certificate CommonName retrieved successfully.
1859 @retval RETURN_INVALID_PARAMETER If Cert is NULL.
1860 If CommonNameSize is NULL.
1861 If CommonName is not NULL and *CommonNameSize is 0.
1862 If Certificate is invalid.
1863 @retval RETURN_NOT_FOUND If no CommonName entry exists.
1864 @retval RETURN_BUFFER_TOO_SMALL If the CommonName is NULL. The required buffer size
1865 (including the final null) is returned in the
1866 CommonNameSize parameter.
1867 @retval RETURN_UNSUPPORTED The operation is not supported.
1868
1869**/
1870RETURN_STATUS
1871EFIAPI
1872X509GetCommonName (
1873 IN CONST UINT8 *Cert,
1874 IN UINTN CertSize,
1875 OUT CHAR8 *CommonName OPTIONAL,
1876 IN OUT UINTN *CommonNameSize
1877 );
1878
1879/**
1880 Retrieve the organization name (O) string from one X.509 certificate.
1881
1882 @param[in] Cert Pointer to the DER-encoded X509 certificate.
1883 @param[in] CertSize Size of the X509 certificate in bytes.
1884 @param[out] NameBuffer Buffer to contain the retrieved certificate organization
1885 name string. At most NameBufferSize bytes will be
1886 written and the string will be null terminated. May be
1887 NULL in order to determine the size buffer needed.
1888 @param[in,out] NameBufferSize The size in bytes of the Name buffer on input,
1889 and the size of buffer returned Name on output.
1890 If NameBuffer is NULL then the amount of space needed
1891 in buffer (including the final null) is returned.
1892
1893 @retval RETURN_SUCCESS The certificate Organization Name retrieved successfully.
1894 @retval RETURN_INVALID_PARAMETER If Cert is NULL.
1895 If NameBufferSize is NULL.
1896 If NameBuffer is not NULL and *CommonNameSize is 0.
1897 If Certificate is invalid.
1898 @retval RETURN_NOT_FOUND If no Organization Name entry exists.
1899 @retval RETURN_BUFFER_TOO_SMALL If the NameBuffer is NULL. The required buffer size
1900 (including the final null) is returned in the
1901 CommonNameSize parameter.
1902 @retval RETURN_UNSUPPORTED The operation is not supported.
1903
1904**/
1905RETURN_STATUS
1906EFIAPI
1907X509GetOrganizationName (
1908 IN CONST UINT8 *Cert,
1909 IN UINTN CertSize,
1910 OUT CHAR8 *NameBuffer OPTIONAL,
1911 IN OUT UINTN *NameBufferSize
1912 );
1913
1914/**
1915 Verify one X509 certificate was issued by the trusted CA.
1916
1917 If Cert is NULL, then return FALSE.
1918 If CACert is NULL, then return FALSE.
1919 If this interface is not supported, then return FALSE.
1920
1921 @param[in] Cert Pointer to the DER-encoded X509 certificate to be verified.
1922 @param[in] CertSize Size of the X509 certificate in bytes.
1923 @param[in] CACert Pointer to the DER-encoded trusted CA certificate.
1924 @param[in] CACertSize Size of the CA Certificate in bytes.
1925
1926 @retval TRUE The certificate was issued by the trusted CA.
1927 @retval FALSE Invalid certificate or the certificate was not issued by the given
1928 trusted CA.
1929 @retval FALSE This interface is not supported.
1930
1931**/
1932BOOLEAN
1933EFIAPI
1934X509VerifyCert (
1935 IN CONST UINT8 *Cert,
1936 IN UINTN CertSize,
1937 IN CONST UINT8 *CACert,
1938 IN UINTN CACertSize
1939 );
1940
1941/**
1942 Construct a X509 object from DER-encoded certificate data.
1943
1944 If Cert is NULL, then return FALSE.
1945 If SingleX509Cert is NULL, then return FALSE.
1946 If this interface is not supported, then return FALSE.
1947
1948 @param[in] Cert Pointer to the DER-encoded certificate data.
1949 @param[in] CertSize The size of certificate data in bytes.
1950 @param[out] SingleX509Cert The generated X509 object.
1951
1952 @retval TRUE The X509 object generation succeeded.
1953 @retval FALSE The operation failed.
1954 @retval FALSE This interface is not supported.
1955
1956**/
1957BOOLEAN
1958EFIAPI
1959X509ConstructCertificate (
1960 IN CONST UINT8 *Cert,
1961 IN UINTN CertSize,
1962 OUT UINT8 **SingleX509Cert
1963 );
1964
1965/**
1966 Construct a X509 stack object from a list of DER-encoded certificate data.
1967
1968 If X509Stack is NULL, then return FALSE.
1969 If this interface is not supported, then return FALSE.
1970
1971 @param[in, out] X509Stack On input, pointer to an existing or NULL X509 stack object.
1972 On output, pointer to the X509 stack object with new
1973 inserted X509 certificate.
1974 @param[in] Args VA_LIST marker for the variable argument list.
1975 A list of DER-encoded single certificate data followed
1976 by certificate size. A NULL terminates the list. The
1977 pairs are the arguments to X509ConstructCertificate().
1978
1979 @retval TRUE The X509 stack construction succeeded.
1980 @retval FALSE The construction operation failed.
1981 @retval FALSE This interface is not supported.
1982
1983**/
1984BOOLEAN
1985EFIAPI
1986X509ConstructCertificateStackV (
1987 IN OUT UINT8 **X509Stack,
1988 IN VA_LIST Args
1989 );
1990
1991/**
1992 Construct a X509 stack object from a list of DER-encoded certificate data.
1993
1994 If X509Stack is NULL, then return FALSE.
1995 If this interface is not supported, then return FALSE.
1996
1997 @param[in, out] X509Stack On input, pointer to an existing or NULL X509 stack object.
1998 On output, pointer to the X509 stack object with new
1999 inserted X509 certificate.
2000 @param ... A list of DER-encoded single certificate data followed
2001 by certificate size. A NULL terminates the list. The
2002 pairs are the arguments to X509ConstructCertificate().
2003
2004 @retval TRUE The X509 stack construction succeeded.
2005 @retval FALSE The construction operation failed.
2006 @retval FALSE This interface is not supported.
2007
2008**/
2009BOOLEAN
2010EFIAPI
2011X509ConstructCertificateStack (
2012 IN OUT UINT8 **X509Stack,
2013 ...
2014 );
2015
2016/**
2017 Release the specified X509 object.
2018
2019 If the interface is not supported, then ASSERT().
2020
2021 @param[in] X509Cert Pointer to the X509 object to be released.
2022
2023**/
2024VOID
2025EFIAPI
2026X509Free (
2027 IN VOID *X509Cert
2028 );
2029
2030/**
2031 Release the specified X509 stack object.
2032
2033 If the interface is not supported, then ASSERT().
2034
2035 @param[in] X509Stack Pointer to the X509 stack object to be released.
2036
2037**/
2038VOID
2039EFIAPI
2040X509StackFree (
2041 IN VOID *X509Stack
2042 );
2043
2044/**
2045 Retrieve the TBSCertificate from one given X.509 certificate.
2046
2047 @param[in] Cert Pointer to the given DER-encoded X509 certificate.
2048 @param[in] CertSize Size of the X509 certificate in bytes.
2049 @param[out] TBSCert DER-Encoded To-Be-Signed certificate.
2050 @param[out] TBSCertSize Size of the TBS certificate in bytes.
2051
2052 If Cert is NULL, then return FALSE.
2053 If TBSCert is NULL, then return FALSE.
2054 If TBSCertSize is NULL, then return FALSE.
2055 If this interface is not supported, then return FALSE.
2056
2057 @retval TRUE The TBSCertificate was retrieved successfully.
2058 @retval FALSE Invalid X.509 certificate.
2059
2060**/
2061BOOLEAN
2062EFIAPI
2063X509GetTBSCert (
2064 IN CONST UINT8 *Cert,
2065 IN UINTN CertSize,
2066 OUT UINT8 **TBSCert,
2067 OUT UINTN *TBSCertSize
2068 );
2069
2070/**
2071 Derives a key from a password using a salt and iteration count, based on PKCS#5 v2.0
2072 password based encryption key derivation function PBKDF2, as specified in RFC 2898.
2073
2074 If Password or Salt or OutKey is NULL, then return FALSE.
2075 If the hash algorithm could not be determined, then return FALSE.
2076 If this interface is not supported, then return FALSE.
2077
2078 @param[in] PasswordLength Length of input password in bytes.
2079 @param[in] Password Pointer to the array for the password.
2080 @param[in] SaltLength Size of the Salt in bytes.
2081 @param[in] Salt Pointer to the Salt.
2082 @param[in] IterationCount Number of iterations to perform. Its value should be
2083 greater than or equal to 1.
2084 @param[in] DigestSize Size of the message digest to be used (eg. SHA256_DIGEST_SIZE).
2085 NOTE: DigestSize will be used to determine the hash algorithm.
2086 Only SHA1_DIGEST_SIZE or SHA256_DIGEST_SIZE is supported.
2087 @param[in] KeyLength Size of the derived key buffer in bytes.
2088 @param[out] OutKey Pointer to the output derived key buffer.
2089
2090 @retval TRUE A key was derived successfully.
2091 @retval FALSE One of the pointers was NULL or one of the sizes was too large.
2092 @retval FALSE The hash algorithm could not be determined from the digest size.
2093 @retval FALSE The key derivation operation failed.
2094 @retval FALSE This interface is not supported.
2095
2096**/
2097BOOLEAN
2098EFIAPI
2099Pkcs5HashPassword (
2100 IN UINTN PasswordLength,
2101 IN CONST CHAR8 *Password,
2102 IN UINTN SaltLength,
2103 IN CONST UINT8 *Salt,
2104 IN UINTN IterationCount,
2105 IN UINTN DigestSize,
2106 IN UINTN KeyLength,
2107 OUT UINT8 *OutKey
2108 );
2109
2110/**
2111 Encrypts a blob using PKCS1v2 (RSAES-OAEP) schema. On success, will return the
2112 encrypted message in a newly allocated buffer.
2113
2114 Things that can cause a failure include:
2115 - X509 key size does not match any known key size.
2116 - Fail to parse X509 certificate.
2117 - Fail to allocate an intermediate buffer.
2118 - Null pointer provided for a non-optional parameter.
2119 - Data size is too large for the provided key size (max size is a function of key size
2120 and hash digest size).
2121
2122 @param[in] PublicKey A pointer to the DER-encoded X509 certificate that
2123 will be used to encrypt the data.
2124 @param[in] PublicKeySize Size of the X509 cert buffer.
2125 @param[in] InData Data to be encrypted.
2126 @param[in] InDataSize Size of the data buffer.
2127 @param[in] PrngSeed [Optional] If provided, a pointer to a random seed buffer
2128 to be used when initializing the PRNG. NULL otherwise.
2129 @param[in] PrngSeedSize [Optional] If provided, size of the random seed buffer.
2130 0 otherwise.
2131 @param[out] EncryptedData Pointer to an allocated buffer containing the encrypted
2132 message.
2133 @param[out] EncryptedDataSize Size of the encrypted message buffer.
2134
2135 @retval TRUE Encryption was successful.
2136 @retval FALSE Encryption failed.
2137
2138**/
2139BOOLEAN
2140EFIAPI
2141Pkcs1v2Encrypt (
2142 IN CONST UINT8 *PublicKey,
2143 IN UINTN PublicKeySize,
2144 IN UINT8 *InData,
2145 IN UINTN InDataSize,
2146 IN CONST UINT8 *PrngSeed OPTIONAL,
2147 IN UINTN PrngSeedSize OPTIONAL,
2148 OUT UINT8 **EncryptedData,
2149 OUT UINTN *EncryptedDataSize
2150 );
2151
2152/**
2153 Encrypts a blob using PKCS1v2 (RSAES-OAEP) schema. On success, will return the
2154 encrypted message in a newly allocated buffer.
2155
2156 Things that can cause a failure include:
2157 - X509 key size does not match any known key size.
2158 - Fail to allocate an intermediate buffer.
2159 - Null pointer provided for a non-optional parameter.
2160 - Data size is too large for the provided key size (max size is a function of key size
2161 and hash digest size).
2162
2163 @param[in] RsaContext A pointer to an RSA context created by RsaNew() and
2164 provisioned with a public key using RsaSetKey().
2165 @param[in] InData Data to be encrypted.
2166 @param[in] InDataSize Size of the data buffer.
2167 @param[in] PrngSeed [Optional] If provided, a pointer to a random seed buffer
2168 to be used when initializing the PRNG. NULL otherwise.
2169 @param[in] PrngSeedSize [Optional] If provided, size of the random seed buffer.
2170 0 otherwise.
2171 @param[in] DigestLen [Optional] If provided, size of the hash used:
2172 SHA1_DIGEST_SIZE
2173 SHA256_DIGEST_SIZE
2174 SHA384_DIGEST_SIZE
2175 SHA512_DIGEST_SIZE
2176 0 to use default (SHA1)
2177 @param[out] EncryptedData Pointer to an allocated buffer containing the encrypted
2178 message.
2179 @param[out] EncryptedDataSize Size of the encrypted message buffer.
2180
2181 @retval TRUE Encryption was successful.
2182 @retval FALSE Encryption failed.
2183
2184**/
2185BOOLEAN
2186EFIAPI
2187RsaOaepEncrypt (
2188 IN VOID *RsaContext,
2189 IN UINT8 *InData,
2190 IN UINTN InDataSize,
2191 IN CONST UINT8 *PrngSeed OPTIONAL,
2192 IN UINTN PrngSeedSize OPTIONAL,
2193 IN UINT16 DigestLen OPTIONAL,
2194 OUT UINT8 **EncryptedData,
2195 OUT UINTN *EncryptedDataSize
2196 );
2197
2198/**
2199 Decrypts a blob using PKCS1v2 (RSAES-OAEP) schema. On success, will return the
2200 decrypted message in a newly allocated buffer.
2201
2202 Things that can cause a failure include:
2203 - Fail to parse private key.
2204 - Fail to allocate an intermediate buffer.
2205 - Null pointer provided for a non-optional parameter.
2206
2207 @param[in] PrivateKey A pointer to the DER-encoded private key.
2208 @param[in] PrivateKeySize Size of the private key buffer.
2209 @param[in] EncryptedData Data to be decrypted.
2210 @param[in] EncryptedDataSize Size of the encrypted buffer.
2211 @param[out] OutData Pointer to an allocated buffer containing the encrypted
2212 message.
2213 @param[out] OutDataSize Size of the encrypted message buffer.
2214
2215 @retval TRUE Encryption was successful.
2216 @retval FALSE Encryption failed.
2217
2218**/
2219BOOLEAN
2220EFIAPI
2221Pkcs1v2Decrypt (
2222 IN CONST UINT8 *PrivateKey,
2223 IN UINTN PrivateKeySize,
2224 IN UINT8 *EncryptedData,
2225 IN UINTN EncryptedDataSize,
2226 OUT UINT8 **OutData,
2227 OUT UINTN *OutDataSize
2228 );
2229
2230/**
2231 Decrypts a blob using PKCS1v2 (RSAES-OAEP) schema. On success, will return the
2232 decrypted message in a newly allocated buffer.
2233
2234 Things that can cause a failure include:
2235 - Fail to parse private key.
2236 - Fail to allocate an intermediate buffer.
2237 - Null pointer provided for a non-optional parameter.
2238
2239 @param[in] RsaContext A pointer to an RSA context created by RsaNew() and
2240 provisioned with a private key using RsaSetKey().
2241 @param[in] EncryptedData Data to be decrypted.
2242 @param[in] EncryptedDataSize Size of the encrypted buffer.
2243 @param[in] DigestLen [Optional] If provided, size of the hash used:
2244 SHA1_DIGEST_SIZE
2245 SHA256_DIGEST_SIZE
2246 SHA384_DIGEST_SIZE
2247 SHA512_DIGEST_SIZE
2248 0 to use default (SHA1)
2249 @param[out] OutData Pointer to an allocated buffer containing the encrypted
2250 message.
2251 @param[out] OutDataSize Size of the encrypted message buffer.
2252
2253 @retval TRUE Encryption was successful.
2254 @retval FALSE Encryption failed.
2255
2256**/
2257BOOLEAN
2258EFIAPI
2259RsaOaepDecrypt (
2260 IN VOID *RsaContext,
2261 IN UINT8 *EncryptedData,
2262 IN UINTN EncryptedDataSize,
2263 IN UINT16 DigestLen OPTIONAL,
2264 OUT UINT8 **OutData,
2265 OUT UINTN *OutDataSize
2266 );
2267
2268/**
2269 The 3rd parameter of Pkcs7GetSigners will return all embedded
2270 X.509 certificate in one given PKCS7 signature. The format is:
2271 //
2272 // UINT8 CertNumber;
2273 // UINT32 Cert1Length;
2274 // UINT8 Cert1[];
2275 // UINT32 Cert2Length;
2276 // UINT8 Cert2[];
2277 // ...
2278 // UINT32 CertnLength;
2279 // UINT8 Certn[];
2280 //
2281
2282 The two following C-structure are used for parsing CertStack more clearly.
2283**/
2284#pragma pack(1)
2285
2286typedef struct {
2287 UINT32 CertDataLength; // The length in bytes of X.509 certificate.
2288 UINT8 CertDataBuffer[0]; // The X.509 certificate content (DER).
2289} EFI_CERT_DATA;
2290
2291typedef struct {
2292 UINT8 CertNumber; // Number of X.509 certificate.
2293 // EFI_CERT_DATA CertArray[]; // An array of X.509 certificate.
2294} EFI_CERT_STACK;
2295
2296#pragma pack()
2297
2298/**
2299 Get the signer's certificates from PKCS#7 signed data as described in "PKCS #7:
2300 Cryptographic Message Syntax Standard". The input signed data could be wrapped
2301 in a ContentInfo structure.
2302
2303 If P7Data, CertStack, StackLength, TrustedCert or CertLength is NULL, then
2304 return FALSE. If P7Length overflow, then return FALSE.
2305 If this interface is not supported, then return FALSE.
2306
2307 @param[in] P7Data Pointer to the PKCS#7 message to verify.
2308 @param[in] P7Length Length of the PKCS#7 message in bytes.
2309 @param[out] CertStack Pointer to Signer's certificates retrieved from P7Data.
2310 It's caller's responsibility to free the buffer with
2311 Pkcs7FreeSigners().
2312 This data structure is EFI_CERT_STACK type.
2313 @param[out] StackLength Length of signer's certificates in bytes.
2314 @param[out] TrustedCert Pointer to a trusted certificate from Signer's certificates.
2315 It's caller's responsibility to free the buffer with
2316 Pkcs7FreeSigners().
2317 @param[out] CertLength Length of the trusted certificate in bytes.
2318
2319 @retval TRUE The operation is finished successfully.
2320 @retval FALSE Error occurs during the operation.
2321 @retval FALSE This interface is not supported.
2322
2323**/
2324BOOLEAN
2325EFIAPI
2326Pkcs7GetSigners (
2327 IN CONST UINT8 *P7Data,
2328 IN UINTN P7Length,
2329 OUT UINT8 **CertStack,
2330 OUT UINTN *StackLength,
2331 OUT UINT8 **TrustedCert,
2332 OUT UINTN *CertLength
2333 );
2334
2335/**
2336 Wrap function to use free() to free allocated memory for certificates.
2337
2338 If this interface is not supported, then ASSERT().
2339
2340 @param[in] Certs Pointer to the certificates to be freed.
2341
2342**/
2343VOID
2344EFIAPI
2345Pkcs7FreeSigners (
2346 IN UINT8 *Certs
2347 );
2348
2349/**
2350 Retrieves all embedded certificates from PKCS#7 signed data as described in "PKCS #7:
2351 Cryptographic Message Syntax Standard", and outputs two certificate lists chained and
2352 unchained to the signer's certificates.
2353 The input signed data could be wrapped in a ContentInfo structure.
2354
2355 Pkcs7GetCertificatesList has not been implemented in BaseCryptoLibMbedTls.
2356
2357 @param[in] P7Data Pointer to the PKCS#7 message.
2358 @param[in] P7Length Length of the PKCS#7 message in bytes.
2359 @param[out] SignerChainCerts Pointer to the certificates list chained to signer's
2360 certificate. It's caller's responsibility to free the buffer
2361 with Pkcs7FreeSigners().
2362 This data structure is EFI_CERT_STACK type.
2363 @param[out] ChainLength Length of the chained certificates list buffer in bytes.
2364 @param[out] UnchainCerts Pointer to the unchained certificates lists. It's caller's
2365 responsibility to free the buffer with Pkcs7FreeSigners().
2366 This data structure is EFI_CERT_STACK type.
2367 @param[out] UnchainLength Length of the unchained certificates list buffer in bytes.
2368
2369 @retval TRUE The operation is finished successfully.
2370 @retval FALSE Error occurs during the operation.
2371
2372**/
2373BOOLEAN
2374EFIAPI
2375Pkcs7GetCertificatesList (
2376 IN CONST UINT8 *P7Data,
2377 IN UINTN P7Length,
2378 OUT UINT8 **SignerChainCerts,
2379 OUT UINTN *ChainLength,
2380 OUT UINT8 **UnchainCerts,
2381 OUT UINTN *UnchainLength
2382 );
2383
2384/**
2385 Creates a PKCS#7 signedData as described in "PKCS #7: Cryptographic Message
2386 Syntax Standard, version 1.5". This interface is only intended to be used for
2387 application to perform PKCS#7 functionality validation.
2388
2389 If this interface is not supported, then return FALSE.
2390
2391 @param[in] PrivateKey Pointer to the PEM-formatted private key data for
2392 data signing.
2393 @param[in] PrivateKeySize Size of the PEM private key data in bytes.
2394 @param[in] KeyPassword NULL-terminated passphrase used for encrypted PEM
2395 key data.
2396 @param[in] InData Pointer to the content to be signed.
2397 @param[in] InDataSize Size of InData in bytes.
2398 @param[in] SignCert Pointer to signer's DER-encoded certificate to sign with.
2399 @param[in] OtherCerts Pointer to an optional additional set of certificates to
2400 include in the PKCS#7 signedData (e.g. any intermediate
2401 CAs in the chain).
2402 @param[out] SignedData Pointer to output PKCS#7 signedData. It's caller's
2403 responsibility to free the buffer with FreePool().
2404 @param[out] SignedDataSize Size of SignedData in bytes.
2405
2406 @retval TRUE PKCS#7 data signing succeeded.
2407 @retval FALSE PKCS#7 data signing failed.
2408 @retval FALSE This interface is not supported.
2409
2410**/
2411BOOLEAN
2412EFIAPI
2413Pkcs7Sign (
2414 IN CONST UINT8 *PrivateKey,
2415 IN UINTN PrivateKeySize,
2416 IN CONST UINT8 *KeyPassword,
2417 IN UINT8 *InData,
2418 IN UINTN InDataSize,
2419 IN UINT8 *SignCert,
2420 IN UINT8 *OtherCerts OPTIONAL,
2421 OUT UINT8 **SignedData,
2422 OUT UINTN *SignedDataSize
2423 );
2424
2425/**
2426 Verifies the validity of a PKCS#7 signed data as described in "PKCS #7:
2427 Cryptographic Message Syntax Standard". The input signed data could be wrapped
2428 in a ContentInfo structure.
2429
2430 If P7Data, TrustedCert or InData is NULL, then return FALSE.
2431 If P7Length, CertLength or DataLength overflow, then return FALSE.
2432 If this interface is not supported, then return FALSE.
2433
2434 @param[in] P7Data Pointer to the PKCS#7 message to verify.
2435 @param[in] P7Length Length of the PKCS#7 message in bytes.
2436 @param[in] TrustedCert Pointer to a trusted/root certificate encoded in DER, which
2437 is used for certificate chain verification.
2438 @param[in] CertLength Length of the trusted certificate in bytes.
2439 @param[in] InData Pointer to the content to be verified.
2440 @param[in] DataLength Length of InData in bytes.
2441
2442 @retval TRUE The specified PKCS#7 signed data is valid.
2443 @retval FALSE Invalid PKCS#7 signed data.
2444 @retval FALSE This interface is not supported.
2445
2446**/
2447BOOLEAN
2448EFIAPI
2449Pkcs7Verify (
2450 IN CONST UINT8 *P7Data,
2451 IN UINTN P7Length,
2452 IN CONST UINT8 *TrustedCert,
2453 IN UINTN CertLength,
2454 IN CONST UINT8 *InData,
2455 IN UINTN DataLength
2456 );
2457
2458/**
2459 This function receives a PKCS7 formatted signature, and then verifies that
2460 the specified Enhanced or Extended Key Usages (EKU's) are present in the end-entity
2461 leaf signing certificate.
2462 Note that this function does not validate the certificate chain.
2463
2464 Applications for custom EKU's are quite flexible. For example, a policy EKU
2465 may be present in an Issuing Certificate Authority (CA), and any sub-ordinate
2466 certificate issued might also contain this EKU, thus constraining the
2467 sub-ordinate certificate. Other applications might allow a certificate
2468 embedded in a device to specify that other Object Identifiers (OIDs) are
2469 present which contains binary data specifying custom capabilities that
2470 the device is able to do.
2471
2472 @param[in] Pkcs7Signature The PKCS#7 signed information content block. An array
2473 containing the content block with both the signature,
2474 the signer's certificate, and any necessary intermediate
2475 certificates.
2476 @param[in] Pkcs7SignatureSize Number of bytes in Pkcs7Signature.
2477 @param[in] RequiredEKUs Array of null-terminated strings listing OIDs of
2478 required EKUs that must be present in the signature.
2479 @param[in] RequiredEKUsSize Number of elements in the RequiredEKUs string array.
2480 @param[in] RequireAllPresent If this is TRUE, then all of the specified EKU's
2481 must be present in the leaf signer. If it is
2482 FALSE, then we will succeed if we find any
2483 of the specified EKU's.
2484
2485 @retval EFI_SUCCESS The required EKUs were found in the signature.
2486 @retval EFI_INVALID_PARAMETER A parameter was invalid.
2487 @retval EFI_NOT_FOUND One or more EKU's were not found in the signature.
2488
2489**/
2490RETURN_STATUS
2491EFIAPI
2492VerifyEKUsInPkcs7Signature (
2493 IN CONST UINT8 *Pkcs7Signature,
2494 IN CONST UINT32 SignatureSize,
2495 IN CONST CHAR8 *RequiredEKUs[],
2496 IN CONST UINT32 RequiredEKUsSize,
2497 IN BOOLEAN RequireAllPresent
2498 );
2499
2500/**
2501 Extracts the attached content from a PKCS#7 signed data if existed. The input signed
2502 data could be wrapped in a ContentInfo structure.
2503
2504 If P7Data, Content, or ContentSize is NULL, then return FALSE. If P7Length overflow,
2505 then return FALSE. If the P7Data is not correctly formatted, then return FALSE.
2506
2507 Caution: This function may receive untrusted input. So this function will do
2508 basic check for PKCS#7 data structure.
2509
2510 @param[in] P7Data Pointer to the PKCS#7 signed data to process.
2511 @param[in] P7Length Length of the PKCS#7 signed data in bytes.
2512 @param[out] Content Pointer to the extracted content from the PKCS#7 signedData.
2513 It's caller's responsibility to free the buffer with FreePool().
2514 @param[out] ContentSize The size of the extracted content in bytes.
2515
2516 @retval TRUE The P7Data was correctly formatted for processing.
2517 @retval FALSE The P7Data was not correctly formatted for processing.
2518
2519**/
2520BOOLEAN
2521EFIAPI
2522Pkcs7GetAttachedContent (
2523 IN CONST UINT8 *P7Data,
2524 IN UINTN P7Length,
2525 OUT VOID **Content,
2526 OUT UINTN *ContentSize
2527 );
2528
2529/**
2530 Verifies the validity of a PE/COFF Authenticode Signature as described in "Windows
2531 Authenticode Portable Executable Signature Format".
2532
2533 If AuthData is NULL, then return FALSE.
2534 If ImageHash is NULL, then return FALSE.
2535 If this interface is not supported, then return FALSE.
2536
2537 @param[in] AuthData Pointer to the Authenticode Signature retrieved from signed
2538 PE/COFF image to be verified.
2539 @param[in] DataSize Size of the Authenticode Signature in bytes.
2540 @param[in] TrustedCert Pointer to a trusted/root certificate encoded in DER, which
2541 is used for certificate chain verification.
2542 @param[in] CertSize Size of the trusted certificate in bytes.
2543 @param[in] ImageHash Pointer to the original image file hash value. The procedure
2544 for calculating the image hash value is described in Authenticode
2545 specification.
2546 @param[in] HashSize Size of Image hash value in bytes.
2547
2548 @retval TRUE The specified Authenticode Signature is valid.
2549 @retval FALSE Invalid Authenticode Signature.
2550 @retval FALSE This interface is not supported.
2551
2552**/
2553BOOLEAN
2554EFIAPI
2555AuthenticodeVerify (
2556 IN CONST UINT8 *AuthData,
2557 IN UINTN DataSize,
2558 IN CONST UINT8 *TrustedCert,
2559 IN UINTN CertSize,
2560 IN CONST UINT8 *ImageHash,
2561 IN UINTN HashSize
2562 );
2563
2564/**
2565 Verifies the validity of a RFC3161 Timestamp CounterSignature embedded in PE/COFF Authenticode
2566 signature.
2567
2568 If AuthData is NULL, then return FALSE.
2569 If this interface is not supported, then return FALSE.
2570
2571 @param[in] AuthData Pointer to the Authenticode Signature retrieved from signed
2572 PE/COFF image to be verified.
2573 @param[in] DataSize Size of the Authenticode Signature in bytes.
2574 @param[in] TsaCert Pointer to a trusted/root TSA certificate encoded in DER, which
2575 is used for TSA certificate chain verification.
2576 @param[in] CertSize Size of the trusted certificate in bytes.
2577 @param[out] SigningTime Return the time of timestamp generation time if the timestamp
2578 signature is valid.
2579
2580 @retval TRUE The specified Authenticode includes a valid RFC3161 Timestamp CounterSignature.
2581 @retval FALSE No valid RFC3161 Timestamp CounterSignature in the specified Authenticode data.
2582
2583**/
2584BOOLEAN
2585EFIAPI
2586ImageTimestampVerify (
2587 IN CONST UINT8 *AuthData,
2588 IN UINTN DataSize,
2589 IN CONST UINT8 *TsaCert,
2590 IN UINTN CertSize,
2591 OUT EFI_TIME *SigningTime
2592 );
2593
2594/**
2595 Retrieve the version from one X.509 certificate.
2596
2597 If Cert is NULL, then return FALSE.
2598 If CertSize is 0, then return FALSE.
2599 If this interface is not supported, then return FALSE.
2600
2601 @param[in] Cert Pointer to the DER-encoded X509 certificate.
2602 @param[in] CertSize Size of the X509 certificate in bytes.
2603 @param[out] Version Pointer to the retrieved version integer.
2604
2605 @retval TRUE The certificate version retrieved successfully.
2606 @retval FALSE If Cert is NULL or CertSize is Zero.
2607 @retval FALSE The operation is not supported.
2608
2609**/
2610BOOLEAN
2611EFIAPI
2612X509GetVersion (
2613 IN CONST UINT8 *Cert,
2614 IN UINTN CertSize,
2615 OUT UINTN *Version
2616 );
2617
2618/**
2619 Retrieve the serialNumber from one X.509 certificate.
2620
2621 If Cert is NULL, then return FALSE.
2622 If CertSize is 0, then return FALSE.
2623 If this interface is not supported, then return FALSE.
2624
2625 @param[in] Cert Pointer to the DER-encoded X509 certificate.
2626 @param[in] CertSize Size of the X509 certificate in bytes.
2627 @param[out] SerialNumber Pointer to the retrieved certificate SerialNumber bytes.
2628 @param[in, out] SerialNumberSize The size in bytes of the SerialNumber buffer on input,
2629 and the size of buffer returned SerialNumber on output.
2630
2631 @retval TRUE The certificate serialNumber retrieved successfully.
2632 @retval FALSE If Cert is NULL or CertSize is Zero.
2633 If SerialNumberSize is NULL.
2634 If Certificate is invalid.
2635 @retval FALSE If no SerialNumber exists.
2636 @retval FALSE If the SerialNumber is NULL. The required buffer size
2637 (including the final null) is returned in the
2638 SerialNumberSize parameter.
2639 @retval FALSE The operation is not supported.
2640**/
2641BOOLEAN
2642EFIAPI
2643X509GetSerialNumber (
2644 IN CONST UINT8 *Cert,
2645 IN UINTN CertSize,
2646 OUT UINT8 *SerialNumber, OPTIONAL
2647 IN OUT UINTN *SerialNumberSize
2648 );
2649
2650/**
2651 Retrieve the issuer bytes from one X.509 certificate.
2652
2653 If Cert is NULL, then return FALSE.
2654 If CertIssuerSize is NULL, then return FALSE.
2655 If this interface is not supported, then return FALSE.
2656
2657 @param[in] Cert Pointer to the DER-encoded X509 certificate.
2658 @param[in] CertSize Size of the X509 certificate in bytes.
2659 @param[out] CertIssuer Pointer to the retrieved certificate subject bytes.
2660 @param[in, out] CertIssuerSize The size in bytes of the CertIssuer buffer on input,
2661 and the size of buffer returned CertSubject on output.
2662
2663 @retval TRUE The certificate issuer retrieved successfully.
2664 @retval FALSE Invalid certificate, or the CertIssuerSize is too small for the result.
2665 The CertIssuerSize will be updated with the required size.
2666 @retval FALSE This interface is not supported.
2667
2668**/
2669BOOLEAN
2670EFIAPI
2671X509GetIssuerName (
2672 IN CONST UINT8 *Cert,
2673 IN UINTN CertSize,
2674 OUT UINT8 *CertIssuer,
2675 IN OUT UINTN *CertIssuerSize
2676 );
2677
2678/**
2679 Retrieve the Signature Algorithm from one X.509 certificate.
2680
2681 @param[in] Cert Pointer to the DER-encoded X509 certificate.
2682 @param[in] CertSize Size of the X509 certificate in bytes.
2683 @param[out] Oid Signature Algorithm Object identifier buffer.
2684 @param[in,out] OidSize Signature Algorithm Object identifier buffer size
2685
2686 @retval TRUE The certificate Extension data retrieved successfully.
2687 @retval FALSE If Cert is NULL.
2688 If OidSize is NULL.
2689 If Oid is not NULL and *OidSize is 0.
2690 If Certificate is invalid.
2691 @retval FALSE If no SignatureType.
2692 @retval FALSE If the Oid is NULL. The required buffer size
2693 is returned in the OidSize.
2694 @retval FALSE The operation is not supported.
2695**/
2696BOOLEAN
2697EFIAPI
2698X509GetSignatureAlgorithm (
2699 IN CONST UINT8 *Cert,
2700 IN UINTN CertSize,
2701 OUT UINT8 *Oid, OPTIONAL
2702 IN OUT UINTN *OidSize
2703 );
2704
2705/**
2706 Retrieve Extension data from one X.509 certificate.
2707
2708 @param[in] Cert Pointer to the DER-encoded X509 certificate.
2709 @param[in] CertSize Size of the X509 certificate in bytes.
2710 @param[in] Oid Object identifier buffer
2711 @param[in] OidSize Object identifier buffer size
2712 @param[out] ExtensionData Extension bytes.
2713 @param[in, out] ExtensionDataSize Extension bytes size.
2714
2715 @retval TRUE The certificate Extension data retrieved successfully.
2716 @retval FALSE If Cert is NULL.
2717 If ExtensionDataSize is NULL.
2718 If ExtensionData is not NULL and *ExtensionDataSize is 0.
2719 If Certificate is invalid.
2720 @retval FALSE If no Extension entry match Oid.
2721 @retval FALSE If the ExtensionData is NULL. The required buffer size
2722 is returned in the ExtensionDataSize parameter.
2723 @retval FALSE The operation is not supported.
2724**/
2725BOOLEAN
2726EFIAPI
2727X509GetExtensionData (
2728 IN CONST UINT8 *Cert,
2729 IN UINTN CertSize,
2730 IN CONST UINT8 *Oid,
2731 IN UINTN OidSize,
2732 OUT UINT8 *ExtensionData,
2733 IN OUT UINTN *ExtensionDataSize
2734 );
2735
2736/**
2737 Retrieve the Validity from one X.509 certificate
2738
2739 If Cert is NULL, then return FALSE.
2740 If CertIssuerSize is NULL, then return FALSE.
2741 If this interface is not supported, then return FALSE.
2742
2743 @param[in] Cert Pointer to the DER-encoded X509 certificate.
2744 @param[in] CertSize Size of the X509 certificate in bytes.
2745 @param[in] From notBefore Pointer to DateTime object.
2746 @param[in,out] FromSize notBefore DateTime object size.
2747 @param[in] To notAfter Pointer to DateTime object.
2748 @param[in,out] ToSize notAfter DateTime object size.
2749
2750 Note: X509CompareDateTime to compare DateTime oject
2751 x509SetDateTime to get a DateTime object from a DateTimeStr
2752
2753 @retval TRUE The certificate Validity retrieved successfully.
2754 @retval FALSE Invalid certificate, or Validity retrieve failed.
2755 @retval FALSE This interface is not supported.
2756**/
2757BOOLEAN
2758EFIAPI
2759X509GetValidity (
2760 IN CONST UINT8 *Cert,
2761 IN UINTN CertSize,
2762 IN UINT8 *From,
2763 IN OUT UINTN *FromSize,
2764 IN UINT8 *To,
2765 IN OUT UINTN *ToSize
2766 );
2767
2768/**
2769 Format a DateTimeStr to DataTime object in DataTime Buffer
2770
2771 If DateTimeStr is NULL, then return FALSE.
2772 If DateTimeSize is NULL, then return FALSE.
2773 If this interface is not supported, then return FALSE.
2774
2775 @param[in] DateTimeStr DateTime string like YYYYMMDDhhmmssZ
2776 Ref: https://www.w3.org/TR/NOTE-datetime
2777 Z stand for UTC time
2778 @param[out] DateTime Pointer to a DateTime object.
2779 @param[in,out] DateTimeSize DateTime object buffer size.
2780
2781 @retval TRUE The DateTime object create successfully.
2782 @retval FALSE If DateTimeStr is NULL.
2783 If DateTimeSize is NULL.
2784 If DateTime is not NULL and *DateTimeSize is 0.
2785 If Year Month Day Hour Minute Second combination is invalid datetime.
2786 @retval FALSE If the DateTime is NULL. The required buffer size
2787 (including the final null) is returned in the
2788 DateTimeSize parameter.
2789 @retval FALSE The operation is not supported.
2790**/
2791BOOLEAN
2792EFIAPI
2793X509FormatDateTime (
2794 IN CONST CHAR8 *DateTimeStr,
2795 OUT VOID *DateTime,
2796 IN OUT UINTN *DateTimeSize
2797 );
2798
2799/**
2800 Compare DateTime1 object and DateTime2 object.
2801
2802 If DateTime1 is NULL, then return -2.
2803 If DateTime2 is NULL, then return -2.
2804 If DateTime1 == DateTime2, then return 0
2805 If DateTime1 > DateTime2, then return 1
2806 If DateTime1 < DateTime2, then return -1
2807
2808 @param[in] DateTime1 Pointer to a DateTime Ojbect
2809 @param[in] DateTime2 Pointer to a DateTime Object
2810
2811 @retval 0 If DateTime1 == DateTime2
2812 @retval 1 If DateTime1 > DateTime2
2813 @retval -1 If DateTime1 < DateTime2
2814**/
2815INT32
2816EFIAPI
2817X509CompareDateTime (
2818 IN CONST VOID *DateTime1,
2819 IN CONST VOID *DateTime2
2820 );
2821
2822/**
2823 Retrieve the Key Usage from one X.509 certificate.
2824
2825 @param[in] Cert Pointer to the DER-encoded X509 certificate.
2826 @param[in] CertSize Size of the X509 certificate in bytes.
2827 @param[out] Usage Key Usage (CRYPTO_X509_KU_*)
2828
2829 @retval TRUE The certificate Key Usage retrieved successfully.
2830 @retval FALSE Invalid certificate, or Usage is NULL
2831 @retval FALSE This interface is not supported.
2832**/
2833BOOLEAN
2834EFIAPI
2835X509GetKeyUsage (
2836 IN CONST UINT8 *Cert,
2837 IN UINTN CertSize,
2838 OUT UINTN *Usage
2839 );
2840
2841/**
2842 Retrieve the Extended Key Usage from one X.509 certificate.
2843
2844 @param[in] Cert Pointer to the DER-encoded X509 certificate.
2845 @param[in] CertSize Size of the X509 certificate in bytes.
2846 @param[out] Usage Key Usage bytes.
2847 @param[in, out] UsageSize Key Usage buffer size in bytes.
2848
2849 @retval TRUE The Usage bytes retrieve successfully.
2850 @retval FALSE If Cert is NULL.
2851 If CertSize is NULL.
2852 If Usage is not NULL and *UsageSize is 0.
2853 If Cert is invalid.
2854 @retval FALSE If the Usage is NULL. The required buffer size
2855 is returned in the UsageSize parameter.
2856 @retval FALSE The operation is not supported.
2857**/
2858BOOLEAN
2859EFIAPI
2860X509GetExtendedKeyUsage (
2861 IN CONST UINT8 *Cert,
2862 IN UINTN CertSize,
2863 OUT UINT8 *Usage,
2864 IN OUT UINTN *UsageSize
2865 );
2866
2867/**
2868 Verify one X509 certificate was issued by the trusted CA.
2869 @param[in] RootCert Trusted Root Certificate buffer
2870
2871 @param[in] RootCertLength Trusted Root Certificate buffer length
2872 @param[in] CertChain One or more ASN.1 DER-encoded X.509 certificates
2873 where the first certificate is signed by the Root
2874 Certificate or is the Root Certificate itself. and
2875 subsequent certificate is signed by the preceding
2876 certificate.
2877 @param[in] CertChainLength Total length of the certificate chain, in bytes.
2878
2879 @retval TRUE All certificates was issued by the first certificate in X509Certchain.
2880 @retval FALSE Invalid certificate or the certificate was not issued by the given
2881 trusted CA.
2882**/
2883BOOLEAN
2884EFIAPI
2885X509VerifyCertChain (
2886 IN CONST UINT8 *RootCert,
2887 IN UINTN RootCertLength,
2888 IN CONST UINT8 *CertChain,
2889 IN UINTN CertChainLength
2890 );
2891
2892/**
2893 Get one X509 certificate from CertChain.
2894
2895 @param[in] CertChain One or more ASN.1 DER-encoded X.509 certificates
2896 where the first certificate is signed by the Root
2897 Certificate or is the Root Certificate itself. and
2898 subsequent certificate is signed by the preceding
2899 certificate.
2900 @param[in] CertChainLength Total length of the certificate chain, in bytes.
2901
2902 @param[in] CertIndex Index of certificate. If index is -1 indecate the
2903 last certificate in CertChain.
2904
2905 @param[out] Cert The certificate at the index of CertChain.
2906 @param[out] CertLength The length certificate at the index of CertChain.
2907
2908 @retval TRUE Success.
2909 @retval FALSE Failed to get certificate from certificate chain.
2910**/
2911BOOLEAN
2912EFIAPI
2913X509GetCertFromCertChain (
2914 IN CONST UINT8 *CertChain,
2915 IN UINTN CertChainLength,
2916 IN CONST INT32 CertIndex,
2917 OUT CONST UINT8 **Cert,
2918 OUT UINTN *CertLength
2919 );
2920
2921/**
2922 Retrieve the tag and length of the tag.
2923
2924 @param Ptr The position in the ASN.1 data
2925 @param End End of data
2926 @param Length The variable that will receive the length
2927 @param Tag The expected tag
2928
2929 @retval TRUE Get tag successful
2930 @retval FALSe Failed to get tag or tag not match
2931**/
2932BOOLEAN
2933EFIAPI
2934Asn1GetTag (
2935 IN OUT UINT8 **Ptr,
2936 IN CONST UINT8 *End,
2937 OUT UINTN *Length,
2938 IN UINT32 Tag
2939 );
2940
2941/**
2942 Retrieve the basic constraints from one X.509 certificate.
2943
2944 @param[in] Cert Pointer to the DER-encoded X509 certificate.
2945 @param[in] CertSize size of the X509 certificate in bytes.
2946 @param[out] BasicConstraints basic constraints bytes.
2947 @param[in, out] BasicConstraintsSize basic constraints buffer size in bytes.
2948
2949 @retval TRUE The basic constraints retrieve successfully.
2950 @retval FALSE If cert is NULL.
2951 If cert_size is NULL.
2952 If basic_constraints is not NULL and *basic_constraints_size is 0.
2953 If cert is invalid.
2954 @retval FALSE The required buffer size is small.
2955 The return buffer size is basic_constraints_size parameter.
2956 @retval FALSE If no Extension entry match oid.
2957 @retval FALSE The operation is not supported.
2958 **/
2959BOOLEAN
2960EFIAPI
2961X509GetExtendedBasicConstraints (
2962 CONST UINT8 *Cert,
2963 UINTN CertSize,
2964 UINT8 *BasicConstraints,
2965 UINTN *BasicConstraintsSize
2966 );
2967
2968// =====================================================================================
2969// DH Key Exchange Primitive
2970// =====================================================================================
2971
2972/**
2973 Allocates and Initializes one Diffie-Hellman Context for subsequent use.
2974
2975 @return Pointer to the Diffie-Hellman Context that has been initialized.
2976 If the allocations fails, DhNew() returns NULL.
2977 If the interface is not supported, DhNew() returns NULL.
2978
2979**/
2980VOID *
2981EFIAPI
2982DhNew (
2983 VOID
2984 );
2985
2986/**
2987 Release the specified DH context.
2988
2989 If the interface is not supported, then ASSERT().
2990
2991 @param[in] DhContext Pointer to the DH context to be released.
2992
2993**/
2994VOID
2995EFIAPI
2996DhFree (
2997 IN VOID *DhContext
2998 );
2999
3000/**
3001 Generates DH parameter.
3002
3003 Given generator g, and length of prime number p in bits, this function generates p,
3004 and sets DH context according to value of g and p.
3005
3006 Before this function can be invoked, pseudorandom number generator must be correctly
3007 initialized by RandomSeed().
3008
3009 If DhContext is NULL, then return FALSE.
3010 If Prime is NULL, then return FALSE.
3011 If this interface is not supported, then return FALSE.
3012
3013 @param[in, out] DhContext Pointer to the DH context.
3014 @param[in] Generator Value of generator.
3015 @param[in] PrimeLength Length in bits of prime to be generated.
3016 @param[out] Prime Pointer to the buffer to receive the generated prime number.
3017
3018 @retval TRUE DH parameter generation succeeded.
3019 @retval FALSE Value of Generator is not supported.
3020 @retval FALSE PRNG fails to generate random prime number with PrimeLength.
3021 @retval FALSE This interface is not supported.
3022
3023**/
3024BOOLEAN
3025EFIAPI
3026DhGenerateParameter (
3027 IN OUT VOID *DhContext,
3028 IN UINTN Generator,
3029 IN UINTN PrimeLength,
3030 OUT UINT8 *Prime
3031 );
3032
3033/**
3034 Sets generator and prime parameters for DH.
3035
3036 Given generator g, and prime number p, this function and sets DH
3037 context accordingly.
3038
3039 If DhContext is NULL, then return FALSE.
3040 If Prime is NULL, then return FALSE.
3041 If this interface is not supported, then return FALSE.
3042
3043 @param[in, out] DhContext Pointer to the DH context.
3044 @param[in] Generator Value of generator.
3045 @param[in] PrimeLength Length in bits of prime to be generated.
3046 @param[in] Prime Pointer to the prime number.
3047
3048 @retval TRUE DH parameter setting succeeded.
3049 @retval FALSE Value of Generator is not supported.
3050 @retval FALSE Value of Generator is not suitable for the Prime.
3051 @retval FALSE Value of Prime is not a prime number.
3052 @retval FALSE Value of Prime is not a safe prime number.
3053 @retval FALSE This interface is not supported.
3054
3055**/
3056BOOLEAN
3057EFIAPI
3058DhSetParameter (
3059 IN OUT VOID *DhContext,
3060 IN UINTN Generator,
3061 IN UINTN PrimeLength,
3062 IN CONST UINT8 *Prime
3063 );
3064
3065/**
3066 Generates DH public key.
3067
3068 This function generates random secret exponent, and computes the public key, which is
3069 returned via parameter PublicKey and PublicKeySize. DH context is updated accordingly.
3070 If the PublicKey buffer is too small to hold the public key, FALSE is returned and
3071 PublicKeySize is set to the required buffer size to obtain the public key.
3072
3073 If DhContext is NULL, then return FALSE.
3074 If PublicKeySize is NULL, then return FALSE.
3075 If PublicKeySize is large enough but PublicKey is NULL, then return FALSE.
3076 If this interface is not supported, then return FALSE.
3077
3078 @param[in, out] DhContext Pointer to the DH context.
3079 @param[out] PublicKey Pointer to the buffer to receive generated public key.
3080 @param[in, out] PublicKeySize On input, the size of PublicKey buffer in bytes.
3081 On output, the size of data returned in PublicKey buffer in bytes.
3082
3083 @retval TRUE DH public key generation succeeded.
3084 @retval FALSE DH public key generation failed.
3085 @retval FALSE PublicKeySize is not large enough.
3086 @retval FALSE This interface is not supported.
3087
3088**/
3089BOOLEAN
3090EFIAPI
3091DhGenerateKey (
3092 IN OUT VOID *DhContext,
3093 OUT UINT8 *PublicKey,
3094 IN OUT UINTN *PublicKeySize
3095 );
3096
3097/**
3098 Computes exchanged common key.
3099
3100 Given peer's public key, this function computes the exchanged common key, based on its own
3101 context including value of prime modulus and random secret exponent.
3102
3103 If DhContext is NULL, then return FALSE.
3104 If PeerPublicKey is NULL, then return FALSE.
3105 If KeySize is NULL, then return FALSE.
3106 If Key is NULL, then return FALSE.
3107 If KeySize is not large enough, then return FALSE.
3108 If this interface is not supported, then return FALSE.
3109
3110 @param[in, out] DhContext Pointer to the DH context.
3111 @param[in] PeerPublicKey Pointer to the peer's public key.
3112 @param[in] PeerPublicKeySize Size of peer's public key in bytes.
3113 @param[out] Key Pointer to the buffer to receive generated key.
3114 @param[in, out] KeySize On input, the size of Key buffer in bytes.
3115 On output, the size of data returned in Key buffer in bytes.
3116
3117 @retval TRUE DH exchanged key generation succeeded.
3118 @retval FALSE DH exchanged key generation failed.
3119 @retval FALSE KeySize is not large enough.
3120 @retval FALSE This interface is not supported.
3121
3122**/
3123BOOLEAN
3124EFIAPI
3125DhComputeKey (
3126 IN OUT VOID *DhContext,
3127 IN CONST UINT8 *PeerPublicKey,
3128 IN UINTN PeerPublicKeySize,
3129 OUT UINT8 *Key,
3130 IN OUT UINTN *KeySize
3131 );
3132
3133// =====================================================================================
3134// Pseudo-Random Generation Primitive
3135// =====================================================================================
3136
3137/**
3138 Sets up the seed value for the pseudorandom number generator.
3139
3140 This function sets up the seed value for the pseudorandom number generator.
3141 If Seed is not NULL, then the seed passed in is used.
3142 If Seed is NULL, then default seed is used.
3143 If this interface is not supported, then return FALSE.
3144
3145 RandomSeed has not been implemented in BaseCryptoLibMbedTls.
3146
3147 @param[in] Seed Pointer to seed value.
3148 If NULL, default seed is used.
3149 @param[in] SeedSize Size of seed value.
3150 If Seed is NULL, this parameter is ignored.
3151
3152 @retval TRUE Pseudorandom number generator has enough entropy for random generation.
3153 @retval FALSE Pseudorandom number generator does not have enough entropy for random generation.
3154 @retval FALSE This interface is not supported.
3155
3156**/
3157BOOLEAN
3158EFIAPI
3159RandomSeed (
3160 IN CONST UINT8 *Seed OPTIONAL,
3161 IN UINTN SeedSize
3162 );
3163
3164/**
3165 Generates a pseudorandom byte stream of the specified size.
3166
3167 If Output is NULL, then return FALSE.
3168 If this interface is not supported, then return FALSE.
3169
3170 @param[out] Output Pointer to buffer to receive random value.
3171 @param[in] Size Size of random bytes to generate.
3172
3173 @retval TRUE Pseudorandom byte stream generated successfully.
3174 @retval FALSE Pseudorandom number generator fails to generate due to lack of entropy.
3175 @retval FALSE This interface is not supported.
3176
3177**/
3178BOOLEAN
3179EFIAPI
3180RandomBytes (
3181 OUT UINT8 *Output,
3182 IN UINTN Size
3183 );
3184
3185// =====================================================================================
3186// Key Derivation Function Primitive
3187// =====================================================================================
3188
3189/**
3190 Derive key data using HMAC-SHA256 based KDF.
3191
3192 @param[in] Key Pointer to the user-supplied key.
3193 @param[in] KeySize Key size in bytes.
3194 @param[in] Salt Pointer to the salt(non-secret) value.
3195 @param[in] SaltSize Salt size in bytes.
3196 @param[in] Info Pointer to the application specific info.
3197 @param[in] InfoSize Info size in bytes.
3198 @param[out] Out Pointer to buffer to receive hkdf value.
3199 @param[in] OutSize Size of hkdf bytes to generate.
3200
3201 @retval TRUE Hkdf generated successfully.
3202 @retval FALSE Hkdf generation failed.
3203
3204**/
3205BOOLEAN
3206EFIAPI
3207HkdfSha256ExtractAndExpand (
3208 IN CONST UINT8 *Key,
3209 IN UINTN KeySize,
3210 IN CONST UINT8 *Salt,
3211 IN UINTN SaltSize,
3212 IN CONST UINT8 *Info,
3213 IN UINTN InfoSize,
3214 OUT UINT8 *Out,
3215 IN UINTN OutSize
3216 );
3217
3218/**
3219 Derive SHA256 HMAC-based Extract key Derivation Function (HKDF).
3220
3221 @param[in] Key Pointer to the user-supplied key.
3222 @param[in] KeySize key size in bytes.
3223 @param[in] Salt Pointer to the salt(non-secret) value.
3224 @param[in] SaltSize salt size in bytes.
3225 @param[out] PrkOut Pointer to buffer to receive hkdf value.
3226 @param[in] PrkOutSize size of hkdf bytes to generate.
3227
3228 @retval true Hkdf generated successfully.
3229 @retval false Hkdf generation failed.
3230
3231**/
3232BOOLEAN
3233EFIAPI
3234HkdfSha256Extract (
3235 IN CONST UINT8 *Key,
3236 IN UINTN KeySize,
3237 IN CONST UINT8 *Salt,
3238 IN UINTN SaltSize,
3239 OUT UINT8 *PrkOut,
3240 UINTN PrkOutSize
3241 );
3242
3243/**
3244 Derive SHA256 HMAC-based Expand Key Derivation Function (HKDF).
3245
3246 @param[in] Prk Pointer to the user-supplied key.
3247 @param[in] PrkSize Key size in bytes.
3248 @param[in] Info Pointer to the application specific info.
3249 @param[in] InfoSize Info size in bytes.
3250 @param[out] Out Pointer to buffer to receive hkdf value.
3251 @param[in] OutSize Size of hkdf bytes to generate.
3252
3253 @retval TRUE Hkdf generated successfully.
3254 @retval FALSE Hkdf generation failed.
3255
3256**/
3257BOOLEAN
3258EFIAPI
3259HkdfSha256Expand (
3260 IN CONST UINT8 *Prk,
3261 IN UINTN PrkSize,
3262 IN CONST UINT8 *Info,
3263 IN UINTN InfoSize,
3264 OUT UINT8 *Out,
3265 IN UINTN OutSize
3266 );
3267
3268/**
3269 Derive SHA384 HMAC-based Extract-and-Expand Key Derivation Function (HKDF).
3270
3271 @param[in] Key Pointer to the user-supplied key.
3272 @param[in] KeySize Key size in bytes.
3273 @param[in] Salt Pointer to the salt(non-secret) value.
3274 @param[in] SaltSize Salt size in bytes.
3275 @param[in] Info Pointer to the application specific info.
3276 @param[in] InfoSize Info size in bytes.
3277 @param[out] Out Pointer to buffer to receive hkdf value.
3278 @param[in] OutSize Size of hkdf bytes to generate.
3279
3280 @retval TRUE Hkdf generated successfully.
3281 @retval FALSE Hkdf generation failed.
3282
3283**/
3284BOOLEAN
3285EFIAPI
3286HkdfSha384ExtractAndExpand (
3287 IN CONST UINT8 *Key,
3288 IN UINTN KeySize,
3289 IN CONST UINT8 *Salt,
3290 IN UINTN SaltSize,
3291 IN CONST UINT8 *Info,
3292 IN UINTN InfoSize,
3293 OUT UINT8 *Out,
3294 IN UINTN OutSize
3295 );
3296
3297/**
3298 Derive SHA384 HMAC-based Extract key Derivation Function (HKDF).
3299
3300 @param[in] Key Pointer to the user-supplied key.
3301 @param[in] KeySize key size in bytes.
3302 @param[in] Salt Pointer to the salt(non-secret) value.
3303 @param[in] SaltSize salt size in bytes.
3304 @param[out] PrkOut Pointer to buffer to receive hkdf value.
3305 @param[in] PrkOutSize size of hkdf bytes to generate.
3306
3307 @retval true Hkdf generated successfully.
3308 @retval false Hkdf generation failed.
3309
3310**/
3311BOOLEAN
3312EFIAPI
3313HkdfSha384Extract (
3314 IN CONST UINT8 *Key,
3315 IN UINTN KeySize,
3316 IN CONST UINT8 *Salt,
3317 IN UINTN SaltSize,
3318 OUT UINT8 *PrkOut,
3319 UINTN PrkOutSize
3320 );
3321
3322/**
3323 Derive SHA384 HMAC-based Expand Key Derivation Function (HKDF).
3324
3325 @param[in] Prk Pointer to the user-supplied key.
3326 @param[in] PrkSize Key size in bytes.
3327 @param[in] Info Pointer to the application specific info.
3328 @param[in] InfoSize Info size in bytes.
3329 @param[out] Out Pointer to buffer to receive hkdf value.
3330 @param[in] OutSize Size of hkdf bytes to generate.
3331
3332 @retval TRUE Hkdf generated successfully.
3333 @retval FALSE Hkdf generation failed.
3334
3335**/
3336BOOLEAN
3337EFIAPI
3338HkdfSha384Expand (
3339 IN CONST UINT8 *Prk,
3340 IN UINTN PrkSize,
3341 IN CONST UINT8 *Info,
3342 IN UINTN InfoSize,
3343 OUT UINT8 *Out,
3344 IN UINTN OutSize
3345 );
3346
3347// =====================================================================================
3348// Big number primitives
3349// =====================================================================================
3350
3351/**
3352 Allocate new Big Number.
3353
3354 @retval New BigNum opaque structure or NULL on failure.
3355**/
3356VOID *
3357EFIAPI
3358BigNumInit (
3359 VOID
3360 );
3361
3362/**
3363 Allocate new Big Number and assign the provided value to it.
3364
3365 @param[in] Buf Big endian encoded buffer.
3366 @param[in] Len Buffer length.
3367
3368 @retval New BigNum opaque structure or NULL on failure.
3369**/
3370VOID *
3371EFIAPI
3372BigNumFromBin (
3373 IN CONST UINT8 *Buf,
3374 IN UINTN Len
3375 );
3376
3377/**
3378 Convert the absolute value of Bn into big-endian form and store it at Buf.
3379 The Buf array should have at least BigNumBytes() in it.
3380
3381 @param[in] Bn Big number to convert.
3382 @param[out] Buf Output buffer.
3383
3384 @retval The length of the big-endian number placed at Buf or -1 on error.
3385**/
3386INTN
3387EFIAPI
3388BigNumToBin (
3389 IN CONST VOID *Bn,
3390 OUT UINT8 *Buf
3391 );
3392
3393/**
3394 Free the Big Number.
3395
3396 @param[in] Bn Big number to free.
3397 @param[in] Clear TRUE if the buffer should be cleared.
3398**/
3399VOID
3400EFIAPI
3401BigNumFree (
3402 IN VOID *Bn,
3403 IN BOOLEAN Clear
3404 );
3405
3406/**
3407 Calculate the sum of two Big Numbers.
3408 Please note, all "out" Big number arguments should be properly initialized
3409 by calling to BigNumInit() or BigNumFromBin() functions.
3410
3411 @param[in] BnA Big number.
3412 @param[in] BnB Big number.
3413 @param[out] BnRes The result of BnA + BnB.
3414
3415 @retval TRUE On success.
3416 @retval FALSE Otherwise.
3417**/
3418BOOLEAN
3419EFIAPI
3420BigNumAdd (
3421 IN CONST VOID *BnA,
3422 IN CONST VOID *BnB,
3423 OUT VOID *BnRes
3424 );
3425
3426/**
3427 Subtract two Big Numbers.
3428 Please note, all "out" Big number arguments should be properly initialized
3429 by calling to BigNumInit() or BigNumFromBin() functions.
3430
3431 @param[in] BnA Big number.
3432 @param[in] BnB Big number.
3433 @param[out] BnRes The result of BnA - BnB.
3434
3435 @retval TRUE On success.
3436 @retval FALSE Otherwise.
3437**/
3438BOOLEAN
3439EFIAPI
3440BigNumSub (
3441 IN CONST VOID *BnA,
3442 IN CONST VOID *BnB,
3443 OUT VOID *BnRes
3444 );
3445
3446/**
3447 Calculate remainder: BnRes = BnA % BnB.
3448 Please note, all "out" Big number arguments should be properly initialized
3449 by calling to BigNumInit() or BigNumFromBin() functions.
3450
3451 @param[in] BnA Big number.
3452 @param[in] BnB Big number.
3453 @param[out] BnRes The result of BnA % BnB.
3454
3455 @retval TRUE On success.
3456 @retval FALSE Otherwise.
3457**/
3458BOOLEAN
3459EFIAPI
3460BigNumMod (
3461 IN CONST VOID *BnA,
3462 IN CONST VOID *BnB,
3463 OUT VOID *BnRes
3464 );
3465
3466/**
3467 Compute BnA to the BnP-th power modulo BnM.
3468 Please note, all "out" Big number arguments should be properly initialized
3469 by calling to BigNumInit() or BigNumFromBin() functions.
3470
3471 @param[in] BnA Big number.
3472 @param[in] BnP Big number (power).
3473 @param[in] BnM Big number (modulo).
3474 @param[out] BnRes The result of (BnA ^ BnP) % BnM.
3475
3476 @retval TRUE On success.
3477 @retval FALSE Otherwise.
3478**/
3479BOOLEAN
3480EFIAPI
3481BigNumExpMod (
3482 IN CONST VOID *BnA,
3483 IN CONST VOID *BnP,
3484 IN CONST VOID *BnM,
3485 OUT VOID *BnRes
3486 );
3487
3488/**
3489 Compute BnA inverse modulo BnM.
3490 Please note, all "out" Big number arguments should be properly initialized
3491 by calling to BigNumInit() or BigNumFromBin() functions.
3492
3493 @param[in] BnA Big number.
3494 @param[in] BnM Big number (modulo).
3495 @param[out] BnRes The result, such that (BnA * BnRes) % BnM == 1.
3496
3497 @retval TRUE On success.
3498 @retval FALSE Otherwise.
3499**/
3500BOOLEAN
3501EFIAPI
3502BigNumInverseMod (
3503 IN CONST VOID *BnA,
3504 IN CONST VOID *BnM,
3505 OUT VOID *BnRes
3506 );
3507
3508/**
3509 Divide two Big Numbers.
3510 Please note, all "out" Big number arguments should be properly initialized
3511 by calling to BigNumInit() or BigNumFromBin() functions.
3512
3513 @param[in] BnA Big number.
3514 @param[in] BnB Big number.
3515 @param[out] BnRes The result, such that BnA / BnB.
3516
3517 @retval TRUE On success.
3518 @retval FALSE Otherwise.
3519**/
3520BOOLEAN
3521EFIAPI
3522BigNumDiv (
3523 IN CONST VOID *BnA,
3524 IN CONST VOID *BnB,
3525 OUT VOID *BnRes
3526 );
3527
3528/**
3529 Multiply two Big Numbers modulo BnM.
3530 Please note, all "out" Big number arguments should be properly initialized
3531 by calling to BigNumInit() or BigNumFromBin() functions.
3532
3533 @param[in] BnA Big number.
3534 @param[in] BnB Big number.
3535 @param[in] BnM Big number (modulo).
3536 @param[out] BnRes The result, such that (BnA * BnB) % BnM.
3537
3538 @retval TRUE On success.
3539 @retval FALSE Otherwise.
3540**/
3541BOOLEAN
3542EFIAPI
3543BigNumMulMod (
3544 IN CONST VOID *BnA,
3545 IN CONST VOID *BnB,
3546 IN CONST VOID *BnM,
3547 OUT VOID *BnRes
3548 );
3549
3550/**
3551 Compare two Big Numbers.
3552
3553 @param[in] BnA Big number.
3554 @param[in] BnB Big number.
3555
3556 @retval 0 BnA == BnB.
3557 @retval 1 BnA > BnB.
3558 @retval -1 BnA < BnB.
3559**/
3560INTN
3561EFIAPI
3562BigNumCmp (
3563 IN CONST VOID *BnA,
3564 IN CONST VOID *BnB
3565 );
3566
3567/**
3568 Get number of bits in Bn.
3569
3570 @param[in] Bn Big number.
3571
3572 @retval Number of bits.
3573**/
3574
3575UINTN
3576EFIAPI
3577BigNumBits (
3578 IN CONST VOID *Bn
3579 );
3580
3581/**
3582 Get number of bytes in Bn.
3583
3584 @param[in] Bn Big number.
3585
3586 @retval Number of bytes.
3587**/
3588UINTN
3589EFIAPI
3590BigNumBytes (
3591 IN CONST VOID *Bn
3592 );
3593
3594/**
3595 Checks if Big Number equals to the given Num.
3596
3597 @param[in] Bn Big number.
3598 @param[in] Num Number.
3599
3600 @retval TRUE iff Bn == Num.
3601 @retval FALSE otherwise.
3602**/
3603BOOLEAN
3604EFIAPI
3605BigNumIsWord (
3606 IN CONST VOID *Bn,
3607 IN UINTN Num
3608 );
3609
3610/**
3611 Checks if Big Number is odd.
3612
3613 @param[in] Bn Big number.
3614
3615 @retval TRUE Bn is odd (Bn % 2 == 1).
3616 @retval FALSE otherwise.
3617**/
3618BOOLEAN
3619EFIAPI
3620BigNumIsOdd (
3621 IN CONST VOID *Bn
3622 );
3623
3624/**
3625 Copy Big number.
3626
3627 @param[out] BnDst Destination.
3628 @param[in] BnSrc Source.
3629
3630 @retval BnDst on success.
3631 @retval NULL otherwise.
3632**/
3633VOID *
3634EFIAPI
3635BigNumCopy (
3636 OUT VOID *BnDst,
3637 IN CONST VOID *BnSrc
3638 );
3639
3640/**
3641 Get constant Big number with value of "1".
3642 This may be used to save expensive allocations.
3643
3644 @retval Big Number with value of 1.
3645**/
3646CONST VOID *
3647EFIAPI
3648BigNumValueOne (
3649 VOID
3650 );
3651
3652/**
3653 Shift right Big Number.
3654 Please note, all "out" Big number arguments should be properly initialized
3655 by calling to BigNumInit() or BigNumFromBin() functions.
3656
3657 @param[in] Bn Big number.
3658 @param[in] N Number of bits to shift.
3659 @param[out] BnRes The result.
3660
3661 @retval TRUE On success.
3662 @retval FALSE Otherwise.
3663**/
3664BOOLEAN
3665EFIAPI
3666BigNumRShift (
3667 IN CONST VOID *Bn,
3668 IN UINTN N,
3669 OUT VOID *BnRes
3670 );
3671
3672/**
3673 Mark Big Number for constant time computations.
3674 This function should be called before any constant time computations are
3675 performed on the given Big number.
3676
3677 @param[in] Bn Big number.
3678**/
3679VOID
3680EFIAPI
3681BigNumConstTime (
3682 IN VOID *Bn
3683 );
3684
3685/**
3686 Calculate square modulo.
3687 Please note, all "out" Big number arguments should be properly initialized
3688 by calling to BigNumInit() or BigNumFromBin() functions.
3689
3690 @param[in] BnA Big number.
3691 @param[in] BnM Big number (modulo).
3692 @param[out] BnRes The result, such that (BnA ^ 2) % BnM.
3693
3694 @retval TRUE On success.
3695 @retval FALSE Otherwise.
3696**/
3697BOOLEAN
3698EFIAPI
3699BigNumSqrMod (
3700 IN CONST VOID *BnA,
3701 IN CONST VOID *BnM,
3702 OUT VOID *BnRes
3703 );
3704
3705/**
3706 Create new Big Number computation context. This is an opaque structure
3707 which should be passed to any function that requires it. The BN context is
3708 needed to optimize calculations and expensive allocations.
3709
3710 @retval Big Number context struct or NULL on failure.
3711**/
3712VOID *
3713EFIAPI
3714BigNumNewContext (
3715 VOID
3716 );
3717
3718/**
3719 Free Big Number context that was allocated with BigNumNewContext().
3720
3721 @param[in] BnCtx Big number context to free.
3722**/
3723VOID
3724EFIAPI
3725BigNumContextFree (
3726 IN VOID *BnCtx
3727 );
3728
3729/**
3730 Set Big Number to a given value.
3731
3732 @param[in] Bn Big number to set.
3733 @param[in] Val Value to set.
3734
3735 @retval TRUE On success.
3736 @retval FALSE Otherwise.
3737**/
3738BOOLEAN
3739EFIAPI
3740BigNumSetUint (
3741 IN VOID *Bn,
3742 IN UINTN Val
3743 );
3744
3745/**
3746 Add two Big Numbers modulo BnM.
3747
3748 @param[in] BnA Big number.
3749 @param[in] BnB Big number.
3750 @param[in] BnM Big number (modulo).
3751 @param[out] BnRes The result, such that (BnA + BnB) % BnM.
3752
3753 @retval TRUE On success.
3754 @retval FALSE Otherwise.
3755**/
3756BOOLEAN
3757EFIAPI
3758BigNumAddMod (
3759 IN CONST VOID *BnA,
3760 IN CONST VOID *BnB,
3761 IN CONST VOID *BnM,
3762 OUT VOID *BnRes
3763 );
3764
3765// =====================================================================================
3766// Basic Elliptic Curve Primitives
3767// =====================================================================================
3768
3769/**
3770 Initialize new opaque EcGroup object. This object represents an EC curve and
3771 and is used for calculation within this group. This object should be freed
3772 using EcGroupFree() function.
3773
3774 @param[in] CryptoNid Identifying number for the ECC curve (Defined in
3775 BaseCryptLib.h).
3776
3777 @retval EcGroup object On success.
3778 @retval NULL On failure.
3779**/
3780VOID *
3781EFIAPI
3782EcGroupInit (
3783 IN UINTN CryptoNid
3784 );
3785
3786/**
3787 Get EC curve parameters. While elliptic curve equation is Y^2 mod P = (X^3 + AX + B) Mod P.
3788 This function will set the provided Big Number objects to the corresponding
3789 values. The caller needs to make sure all the "out" BigNumber parameters
3790 are properly initialized.
3791
3792 @param[in] EcGroup EC group object.
3793 @param[out] BnPrime Group prime number.
3794 @param[out] BnA A coefficient.
3795 @param[out] BnB B coefficient.
3796 @param[in] BnCtx BN context.
3797
3798 @retval TRUE On success.
3799 @retval FALSE Otherwise.
3800**/
3801BOOLEAN
3802EFIAPI
3803EcGroupGetCurve (
3804 IN CONST VOID *EcGroup,
3805 OUT VOID *BnPrime,
3806 OUT VOID *BnA,
3807 OUT VOID *BnB,
3808 IN VOID *BnCtx
3809 );
3810
3811/**
3812 Get EC group order.
3813 This function will set the provided Big Number object to the corresponding
3814 value. The caller needs to make sure that the "out" BigNumber parameter
3815 is properly initialized.
3816
3817 @param[in] EcGroup EC group object.
3818 @param[out] BnOrder Group prime number.
3819
3820 @retval TRUE On success.
3821 @retval FALSE Otherwise.
3822**/
3823BOOLEAN
3824EFIAPI
3825EcGroupGetOrder (
3826 IN VOID *EcGroup,
3827 OUT VOID *BnOrder
3828 );
3829
3830/**
3831 Free previously allocated EC group object using EcGroupInit().
3832
3833 @param[in] EcGroup EC group object to free.
3834**/
3835VOID
3836EFIAPI
3837EcGroupFree (
3838 IN VOID *EcGroup
3839 );
3840
3841/**
3842 Initialize new opaque EC Point object. This object represents an EC point
3843 within the given EC group (curve).
3844
3845 @param[in] EC Group, properly initialized using EcGroupInit().
3846
3847 @retval EC Point object On success.
3848 @retval NULL On failure.
3849**/
3850VOID *
3851EFIAPI
3852EcPointInit (
3853 IN CONST VOID *EcGroup
3854 );
3855
3856/**
3857 Free previously allocated EC Point object using EcPointInit().
3858
3859 @param[in] EcPoint EC Point to free.
3860 @param[in] Clear TRUE iff the memory should be cleared.
3861**/
3862VOID
3863EFIAPI
3864EcPointDeInit (
3865 IN VOID *EcPoint,
3866 IN BOOLEAN Clear
3867 );
3868
3869/**
3870 Get EC point affine (x,y) coordinates.
3871 This function will set the provided Big Number objects to the corresponding
3872 values. The caller needs to make sure all the "out" BigNumber parameters
3873 are properly initialized.
3874
3875 @param[in] EcGroup EC group object.
3876 @param[in] EcPoint EC point object.
3877 @param[out] BnX X coordinate.
3878 @param[out] BnY Y coordinate.
3879 @param[in] BnCtx BN context, created with BigNumNewContext().
3880
3881 @retval TRUE On success.
3882 @retval FALSE Otherwise.
3883**/
3884BOOLEAN
3885EFIAPI
3886EcPointGetAffineCoordinates (
3887 IN CONST VOID *EcGroup,
3888 IN CONST VOID *EcPoint,
3889 OUT VOID *BnX,
3890 OUT VOID *BnY,
3891 IN VOID *BnCtx
3892 );
3893
3894/**
3895 Set EC point affine (x,y) coordinates.
3896
3897 @param[in] EcGroup EC group object.
3898 @param[in] EcPoint EC point object.
3899 @param[in] BnX X coordinate.
3900 @param[in] BnY Y coordinate.
3901 @param[in] BnCtx BN context, created with BigNumNewContext().
3902
3903 @retval TRUE On success.
3904 @retval FALSE Otherwise.
3905**/
3906BOOLEAN
3907EFIAPI
3908EcPointSetAffineCoordinates (
3909 IN CONST VOID *EcGroup,
3910 IN VOID *EcPoint,
3911 IN CONST VOID *BnX,
3912 IN CONST VOID *BnY,
3913 IN VOID *BnCtx
3914 );
3915
3916/**
3917 EC Point addition. EcPointResult = EcPointA + EcPointB.
3918
3919 @param[in] EcGroup EC group object.
3920 @param[out] EcPointResult EC point to hold the result. The point should
3921 be properly initialized.
3922 @param[in] EcPointA EC Point.
3923 @param[in] EcPointB EC Point.
3924 @param[in] BnCtx BN context, created with BigNumNewContext().
3925
3926 @retval TRUE On success.
3927 @retval FALSE Otherwise.
3928**/
3929BOOLEAN
3930EFIAPI
3931EcPointAdd (
3932 IN CONST VOID *EcGroup,
3933 OUT VOID *EcPointResult,
3934 IN CONST VOID *EcPointA,
3935 IN CONST VOID *EcPointB,
3936 IN VOID *BnCtx
3937 );
3938
3939/**
3940 Variable EC point multiplication. EcPointResult = EcPoint * BnPScalar.
3941
3942 @param[in] EcGroup EC group object.
3943 @param[out] EcPointResult EC point to hold the result. The point should
3944 be properly initialized.
3945 @param[in] EcPoint EC Point.
3946 @param[in] BnPScalar P Scalar.
3947 @param[in] BnCtx BN context, created with BigNumNewContext().
3948
3949 @retval TRUE On success.
3950 @retval FALSE Otherwise.
3951**/
3952BOOLEAN
3953EFIAPI
3954EcPointMul (
3955 IN CONST VOID *EcGroup,
3956 OUT VOID *EcPointResult,
3957 IN CONST VOID *EcPoint,
3958 IN CONST VOID *BnPScalar,
3959 IN VOID *BnCtx
3960 );
3961
3962/**
3963 Calculate the inverse of the supplied EC point.
3964
3965 @param[in] EcGroup EC group object.
3966 @param[in,out] EcPoint EC point to invert.
3967 @param[in] BnCtx BN context, created with BigNumNewContext().
3968
3969 @retval TRUE On success.
3970 @retval FALSE Otherwise.
3971**/
3972BOOLEAN
3973EFIAPI
3974EcPointInvert (
3975 IN CONST VOID *EcGroup,
3976 IN OUT VOID *EcPoint,
3977 IN VOID *BnCtx
3978 );
3979
3980/**
3981 Check if the supplied point is on EC curve.
3982
3983 @param[in] EcGroup EC group object.
3984 @param[in] EcPoint EC point to check.
3985 @param[in] BnCtx BN context, created with BigNumNewContext().
3986
3987 @retval TRUE On curve.
3988 @retval FALSE Otherwise.
3989**/
3990BOOLEAN
3991EFIAPI
3992EcPointIsOnCurve (
3993 IN CONST VOID *EcGroup,
3994 IN CONST VOID *EcPoint,
3995 IN VOID *BnCtx
3996 );
3997
3998/**
3999 Check if the supplied point is at infinity.
4000
4001 @param[in] EcGroup EC group object.
4002 @param[in] EcPoint EC point to check.
4003
4004 @retval TRUE At infinity.
4005 @retval FALSE Otherwise.
4006**/
4007BOOLEAN
4008EFIAPI
4009EcPointIsAtInfinity (
4010 IN CONST VOID *EcGroup,
4011 IN CONST VOID *EcPoint
4012 );
4013
4014/**
4015 Check if EC points are equal.
4016
4017 @param[in] EcGroup EC group object.
4018 @param[in] EcPointA EC point A.
4019 @param[in] EcPointB EC point B.
4020 @param[in] BnCtx BN context, created with BigNumNewContext().
4021
4022 @retval TRUE A == B.
4023 @retval FALSE Otherwise.
4024**/
4025BOOLEAN
4026EFIAPI
4027EcPointEqual (
4028 IN CONST VOID *EcGroup,
4029 IN CONST VOID *EcPointA,
4030 IN CONST VOID *EcPointB,
4031 IN VOID *BnCtx
4032 );
4033
4034/**
4035 Set EC point compressed coordinates. Points can be described in terms of
4036 their compressed coordinates. For a point (x, y), for any given value for x
4037 such that the point is on the curve there will only ever be two possible
4038 values for y. Therefore, a point can be set using this function where BnX is
4039 the x coordinate and YBit is a value 0 or 1 to identify which of the two
4040 possible values for y should be used.
4041
4042 @param[in] EcGroup EC group object.
4043 @param[in] EcPoint EC Point.
4044 @param[in] BnX X coordinate.
4045 @param[in] YBit 0 or 1 to identify which Y value is used.
4046 @param[in] BnCtx BN context, created with BigNumNewContext().
4047
4048 @retval TRUE On success.
4049 @retval FALSE Otherwise.
4050**/
4051BOOLEAN
4052EFIAPI
4053EcPointSetCompressedCoordinates (
4054 IN CONST VOID *EcGroup,
4055 IN VOID *EcPoint,
4056 IN CONST VOID *BnX,
4057 IN UINT8 YBit,
4058 IN VOID *BnCtx
4059 );
4060
4061// =====================================================================================
4062// Elliptic Curve Diffie Hellman Primitives
4063// =====================================================================================
4064
4065/**
4066 Allocates and Initializes one Elliptic Curve Context for subsequent use
4067 with the NID.
4068
4069 @param[in] Nid cipher NID
4070 @return Pointer to the Elliptic Curve Context that has been initialized.
4071 If the allocations fails, EcNewByNid() returns NULL.
4072**/
4073VOID *
4074EFIAPI
4075EcNewByNid (
4076 IN UINTN Nid
4077 );
4078
4079/**
4080 Release the specified EC context.
4081
4082 @param[in] EcContext Pointer to the EC context to be released.
4083**/
4084VOID
4085EFIAPI
4086EcFree (
4087 IN VOID *EcContext
4088 );
4089
4090/**
4091 Generates EC key and returns EC public key (X, Y), Please note, this function uses
4092 pseudo random number generator. The caller must make sure RandomSeed()
4093 function was properly called before.
4094 The Ec context should be correctly initialized by EcNewByNid.
4095 This function generates random secret, and computes the public key (X, Y), which is
4096 returned via parameter Public, PublicSize.
4097 X is the first half of Public with size being PublicSize / 2,
4098 Y is the second half of Public with size being PublicSize / 2.
4099 EC context is updated accordingly.
4100 If the Public buffer is too small to hold the public X, Y, FALSE is returned and
4101 PublicSize is set to the required buffer size to obtain the public X, Y.
4102 For P-256, the PublicSize is 64. First 32-byte is X, Second 32-byte is Y.
4103 For P-384, the PublicSize is 96. First 48-byte is X, Second 48-byte is Y.
4104 For P-521, the PublicSize is 132. First 66-byte is X, Second 66-byte is Y.
4105 If EcContext is NULL, then return FALSE.
4106 If PublicSize is NULL, then return FALSE.
4107 If PublicSize is large enough but Public is NULL, then return FALSE.
4108 @param[in, out] EcContext Pointer to the EC context.
4109 @param[out] PublicKey Pointer to t buffer to receive generated public X,Y.
4110 @param[in, out] PublicKeySize On input, the size of Public buffer in bytes.
4111 On output, the size of data returned in Public buffer in bytes.
4112 @retval TRUE EC public X,Y generation succeeded.
4113 @retval FALSE EC public X,Y generation failed.
4114 @retval FALSE PublicKeySize is not large enough.
4115**/
4116BOOLEAN
4117EFIAPI
4118EcGenerateKey (
4119 IN OUT VOID *EcContext,
4120 OUT UINT8 *PublicKey,
4121 IN OUT UINTN *PublicKeySize
4122 );
4123
4124/**
4125 Gets the public key component from the established EC context.
4126 The Ec context should be correctly initialized by EcNewByNid, and successfully
4127 generate key pair from EcGenerateKey().
4128 For P-256, the PublicSize is 64. First 32-byte is X, Second 32-byte is Y.
4129 For P-384, the PublicSize is 96. First 48-byte is X, Second 48-byte is Y.
4130 For P-521, the PublicSize is 132. First 66-byte is X, Second 66-byte is Y.
4131 @param[in, out] EcContext Pointer to EC context being set.
4132 @param[out] PublicKey Pointer to t buffer to receive generated public X,Y.
4133 @param[in, out] PublicKeySize On input, the size of Public buffer in bytes.
4134 On output, the size of data returned in Public buffer in bytes.
4135 @retval TRUE EC key component was retrieved successfully.
4136 @retval FALSE Invalid EC key component.
4137**/
4138BOOLEAN
4139EFIAPI
4140EcGetPubKey (
4141 IN OUT VOID *EcContext,
4142 OUT UINT8 *PublicKey,
4143 IN OUT UINTN *PublicKeySize
4144 );
4145
4146/**
4147 Computes exchanged common key.
4148 Given peer's public key (X, Y), this function computes the exchanged common key,
4149 based on its own context including value of curve parameter and random secret.
4150 X is the first half of PeerPublic with size being PeerPublicSize / 2,
4151 Y is the second half of PeerPublic with size being PeerPublicSize / 2.
4152 If EcContext is NULL, then return FALSE.
4153 If PeerPublic is NULL, then return FALSE.
4154 If PeerPublicSize is 0, then return FALSE.
4155 If Key is NULL, then return FALSE.
4156 If KeySize is not large enough, then return FALSE.
4157 For P-256, the PeerPublicSize is 64. First 32-byte is X, Second 32-byte is Y.
4158 For P-384, the PeerPublicSize is 96. First 48-byte is X, Second 48-byte is Y.
4159 For P-521, the PeerPublicSize is 132. First 66-byte is X, Second 66-byte is Y.
4160 @param[in, out] EcContext Pointer to the EC context.
4161 @param[in] PeerPublic Pointer to the peer's public X,Y.
4162 @param[in] PeerPublicSize Size of peer's public X,Y in bytes.
4163 @param[in] CompressFlag Flag of PeerPublic is compressed or not.
4164 @param[out] Key Pointer to the buffer to receive generated key.
4165 @param[in, out] KeySize On input, the size of Key buffer in bytes.
4166 On output, the size of data returned in Key buffer in bytes.
4167 @retval TRUE EC exchanged key generation succeeded.
4168 @retval FALSE EC exchanged key generation failed.
4169 @retval FALSE KeySize is not large enough.
4170**/
4171BOOLEAN
4172EFIAPI
4173EcDhComputeKey (
4174 IN OUT VOID *EcContext,
4175 IN CONST UINT8 *PeerPublic,
4176 IN UINTN PeerPublicSize,
4177 IN CONST INT32 *CompressFlag,
4178 OUT UINT8 *Key,
4179 IN OUT UINTN *KeySize
4180 );
4181
4182/**
4183 Retrieve the EC Private Key from the password-protected PEM key data.
4184
4185 @param[in] PemData Pointer to the PEM-encoded key data to be retrieved.
4186 @param[in] PemSize Size of the PEM key data in bytes.
4187 @param[in] Password NULL-terminated passphrase used for encrypted PEM key data.
4188 @param[out] EcContext Pointer to new-generated EC DSA context which contain the retrieved
4189 EC private key component. Use EcFree() function to free the
4190 resource.
4191
4192 If PemData is NULL, then return FALSE.
4193 If EcContext is NULL, then return FALSE.
4194
4195 @retval TRUE EC Private Key was retrieved successfully.
4196 @retval FALSE Invalid PEM key data or incorrect password.
4197
4198**/
4199BOOLEAN
4200EFIAPI
4201EcGetPrivateKeyFromPem (
4202 IN CONST UINT8 *PemData,
4203 IN UINTN PemSize,
4204 IN CONST CHAR8 *Password,
4205 OUT VOID **EcContext
4206 );
4207
4208/**
4209 Retrieve the EC Public Key from one DER-encoded X509 certificate.
4210
4211 @param[in] Cert Pointer to the DER-encoded X509 certificate.
4212 @param[in] CertSize Size of the X509 certificate in bytes.
4213 @param[out] EcContext Pointer to new-generated EC DSA context which contain the retrieved
4214 EC public key component. Use EcFree() function to free the
4215 resource.
4216
4217 If Cert is NULL, then return FALSE.
4218 If EcContext is NULL, then return FALSE.
4219
4220 @retval TRUE EC Public Key was retrieved successfully.
4221 @retval FALSE Fail to retrieve EC public key from X509 certificate.
4222
4223**/
4224BOOLEAN
4225EFIAPI
4226EcGetPublicKeyFromX509 (
4227 IN CONST UINT8 *Cert,
4228 IN UINTN CertSize,
4229 OUT VOID **EcContext
4230 );
4231
4232/**
4233 Carries out the EC-DSA signature.
4234
4235 This function carries out the EC-DSA signature.
4236 If the Signature buffer is too small to hold the contents of signature, FALSE
4237 is returned and SigSize is set to the required buffer size to obtain the signature.
4238
4239 If EcContext is NULL, then return FALSE.
4240 If MessageHash is NULL, then return FALSE.
4241 If HashSize need match the HashNid. HashNid could be SHA256, SHA384, SHA512, SHA3_256, SHA3_384, SHA3_512.
4242 If SigSize is large enough but Signature is NULL, then return FALSE.
4243
4244 For P-256, the SigSize is 64. First 32-byte is R, Second 32-byte is S.
4245 For P-384, the SigSize is 96. First 48-byte is R, Second 48-byte is S.
4246 For P-521, the SigSize is 132. First 66-byte is R, Second 66-byte is S.
4247
4248 @param[in] EcContext Pointer to EC context for signature generation.
4249 @param[in] HashNid hash NID
4250 @param[in] MessageHash Pointer to octet message hash to be signed.
4251 @param[in] HashSize Size of the message hash in bytes.
4252 @param[out] Signature Pointer to buffer to receive EC-DSA signature.
4253 @param[in, out] SigSize On input, the size of Signature buffer in bytes.
4254 On output, the size of data returned in Signature buffer in bytes.
4255
4256 @retval TRUE Signature successfully generated in EC-DSA.
4257 @retval FALSE Signature generation failed.
4258 @retval FALSE SigSize is too small.
4259
4260**/
4261BOOLEAN
4262EFIAPI
4263EcDsaSign (
4264 IN VOID *EcContext,
4265 IN UINTN HashNid,
4266 IN CONST UINT8 *MessageHash,
4267 IN UINTN HashSize,
4268 OUT UINT8 *Signature,
4269 IN OUT UINTN *SigSize
4270 );
4271
4272/**
4273 Verifies the EC-DSA signature.
4274
4275 If EcContext is NULL, then return FALSE.
4276 If MessageHash is NULL, then return FALSE.
4277 If Signature is NULL, then return FALSE.
4278 If HashSize need match the HashNid. HashNid could be SHA256, SHA384, SHA512, SHA3_256, SHA3_384, SHA3_512.
4279
4280 For P-256, the SigSize is 64. First 32-byte is R, Second 32-byte is S.
4281 For P-384, the SigSize is 96. First 48-byte is R, Second 48-byte is S.
4282 For P-521, the SigSize is 132. First 66-byte is R, Second 66-byte is S.
4283
4284 @param[in] EcContext Pointer to EC context for signature verification.
4285 @param[in] HashNid hash NID
4286 @param[in] MessageHash Pointer to octet message hash to be checked.
4287 @param[in] HashSize Size of the message hash in bytes.
4288 @param[in] Signature Pointer to EC-DSA signature to be verified.
4289 @param[in] SigSize Size of signature in bytes.
4290
4291 @retval TRUE Valid signature encoded in EC-DSA.
4292 @retval FALSE Invalid signature or invalid EC context.
4293
4294**/
4295BOOLEAN
4296EFIAPI
4297EcDsaVerify (
4298 IN VOID *EcContext,
4299 IN UINTN HashNid,
4300 IN CONST UINT8 *MessageHash,
4301 IN UINTN HashSize,
4302 IN CONST UINT8 *Signature,
4303 IN UINTN SigSize
4304 );
4305
4306#endif // __BASE_CRYPT_LIB_H__
Note: See TracBrowser for help on using the repository browser.

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette