VirtualBox

source: vbox/trunk/src/VBox/Devices/EFI/Firmware/CryptoPkg/Include/Library/BaseCryptLib.h

最後變更 在這個檔案是 105670,由 vboxsync 提交於 6 月 前

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

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