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.
7 Copyright (c) 2009 - 2020, Intel Corporation. All rights reserved.<BR>
8 SPDX-License-Identifier: BSD-2-Clause-Patent
12 #ifndef __BASE_CRYPT_LIB_H__
13 #define __BASE_CRYPT_LIB_H__
15 #include <Uefi/UefiBaseType.h>
18 /// MD5 digest size in bytes
20 #define MD5_DIGEST_SIZE 16
23 /// SHA-1 digest size in bytes.
25 #define SHA1_DIGEST_SIZE 20
28 /// SHA-256 digest size in bytes
30 #define SHA256_DIGEST_SIZE 32
33 /// SHA-384 digest size in bytes
35 #define SHA384_DIGEST_SIZE 48
38 /// SHA-512 digest size in bytes
40 #define SHA512_DIGEST_SIZE 64
43 /// SM3 digest size in bytes
45 #define SM3_256_DIGEST_SIZE 32
48 /// TDES block size in bytes
50 #define TDES_BLOCK_SIZE 8
53 /// AES block size in bytes
55 #define AES_BLOCK_SIZE 16
58 /// RSA Key Tags Definition used in RsaSetKey() function for key component identification.
61 RsaKeyN
, ///< RSA public Modulus (N)
62 RsaKeyE
, ///< RSA Public exponent (e)
63 RsaKeyD
, ///< RSA Private exponent (d)
64 RsaKeyP
, ///< RSA secret prime factor of Modulus (p)
65 RsaKeyQ
, ///< RSA secret prime factor of Modules (q)
66 RsaKeyDp
, ///< p's CRT exponent (== d mod (p - 1))
67 RsaKeyDq
, ///< q's CRT exponent (== d mod (q - 1))
68 RsaKeyQInv
///< The CRT coefficient (== 1/q mod p)
71 //=====================================================================================
72 // One-Way Cryptographic Hash Primitives
73 //=====================================================================================
75 #ifdef ENABLE_MD5_DEPRECATED_INTERFACES
77 Retrieves the size, in bytes, of the context buffer required for MD5 hash operations.
79 If this interface is not supported, then return zero.
81 @return The size, in bytes, of the context buffer required for MD5 hash operations.
82 @retval 0 This interface is not supported.
92 Initializes user-supplied memory pointed by Md5Context as MD5 hash context for
95 If Md5Context is NULL, then return FALSE.
96 If this interface is not supported, then return FALSE.
98 @param[out] Md5Context Pointer to MD5 context being initialized.
100 @retval TRUE MD5 context initialization succeeded.
101 @retval FALSE MD5 context initialization failed.
102 @retval FALSE This interface is not supported.
112 Makes a copy of an existing MD5 context.
114 If Md5Context is NULL, then return FALSE.
115 If NewMd5Context is NULL, then return FALSE.
116 If this interface is not supported, then return FALSE.
118 @param[in] Md5Context Pointer to MD5 context being copied.
119 @param[out] NewMd5Context Pointer to new MD5 context.
121 @retval TRUE MD5 context copy succeeded.
122 @retval FALSE MD5 context copy failed.
123 @retval FALSE This interface is not supported.
129 IN CONST VOID
*Md5Context
,
130 OUT VOID
*NewMd5Context
134 Digests the input data and updates MD5 context.
136 This function performs MD5 digest on a data buffer of the specified size.
137 It can be called multiple times to compute the digest of long or discontinuous data streams.
138 MD5 context should be already correctly initialized by Md5Init(), and should not be finalized
139 by Md5Final(). Behavior with invalid context is undefined.
141 If Md5Context is NULL, then return FALSE.
142 If this interface is not supported, then return FALSE.
144 @param[in, out] Md5Context Pointer to the MD5 context.
145 @param[in] Data Pointer to the buffer containing the data to be hashed.
146 @param[in] DataSize Size of Data buffer in bytes.
148 @retval TRUE MD5 data digest succeeded.
149 @retval FALSE MD5 data digest failed.
150 @retval FALSE This interface is not supported.
156 IN OUT VOID
*Md5Context
,
162 Completes computation of the MD5 digest value.
164 This function completes MD5 hash computation and retrieves the digest value into
165 the specified memory. After this function has been called, the MD5 context cannot
167 MD5 context should be already correctly initialized by Md5Init(), and should not be
168 finalized by Md5Final(). Behavior with invalid MD5 context is undefined.
170 If Md5Context is NULL, then return FALSE.
171 If HashValue is NULL, then return FALSE.
172 If this interface is not supported, then return FALSE.
174 @param[in, out] Md5Context Pointer to the MD5 context.
175 @param[out] HashValue Pointer to a buffer that receives the MD5 digest
178 @retval TRUE MD5 digest computation succeeded.
179 @retval FALSE MD5 digest computation failed.
180 @retval FALSE This interface is not supported.
186 IN OUT VOID
*Md5Context
,
191 Computes the MD5 message digest of a input data buffer.
193 This function performs the MD5 message digest of a given data buffer, and places
194 the digest value into the specified memory.
196 If this interface is not supported, then return FALSE.
198 @param[in] Data Pointer to the buffer containing the data to be hashed.
199 @param[in] DataSize Size of Data buffer in bytes.
200 @param[out] HashValue Pointer to a buffer that receives the MD5 digest
203 @retval TRUE MD5 digest computation succeeded.
204 @retval FALSE MD5 digest computation failed.
205 @retval FALSE This interface is not supported.
217 #ifndef DISABLE_SHA1_DEPRECATED_INTERFACES
219 Retrieves the size, in bytes, of the context buffer required for SHA-1 hash operations.
221 If this interface is not supported, then return zero.
223 @return The size, in bytes, of the context buffer required for SHA-1 hash operations.
224 @retval 0 This interface is not supported.
234 Initializes user-supplied memory pointed by Sha1Context as SHA-1 hash context for
237 If Sha1Context is NULL, then return FALSE.
238 If this interface is not supported, then return FALSE.
240 @param[out] Sha1Context Pointer to SHA-1 context being initialized.
242 @retval TRUE SHA-1 context initialization succeeded.
243 @retval FALSE SHA-1 context initialization failed.
244 @retval FALSE This interface is not supported.
250 OUT VOID
*Sha1Context
254 Makes a copy of an existing SHA-1 context.
256 If Sha1Context is NULL, then return FALSE.
257 If NewSha1Context is NULL, then return FALSE.
258 If this interface is not supported, then return FALSE.
260 @param[in] Sha1Context Pointer to SHA-1 context being copied.
261 @param[out] NewSha1Context Pointer to new SHA-1 context.
263 @retval TRUE SHA-1 context copy succeeded.
264 @retval FALSE SHA-1 context copy failed.
265 @retval FALSE This interface is not supported.
271 IN CONST VOID
*Sha1Context
,
272 OUT VOID
*NewSha1Context
276 Digests the input data and updates SHA-1 context.
278 This function performs SHA-1 digest on a data buffer of the specified size.
279 It can be called multiple times to compute the digest of long or discontinuous data streams.
280 SHA-1 context should be already correctly initialized by Sha1Init(), and should not be finalized
281 by Sha1Final(). Behavior with invalid context is undefined.
283 If Sha1Context is NULL, then return FALSE.
284 If this interface is not supported, then return FALSE.
286 @param[in, out] Sha1Context Pointer to the SHA-1 context.
287 @param[in] Data Pointer to the buffer containing the data to be hashed.
288 @param[in] DataSize Size of Data buffer in bytes.
290 @retval TRUE SHA-1 data digest succeeded.
291 @retval FALSE SHA-1 data digest failed.
292 @retval FALSE This interface is not supported.
298 IN OUT VOID
*Sha1Context
,
304 Completes computation of the SHA-1 digest value.
306 This function completes SHA-1 hash computation and retrieves the digest value into
307 the specified memory. After this function has been called, the SHA-1 context cannot
309 SHA-1 context should be already correctly initialized by Sha1Init(), and should not be
310 finalized by Sha1Final(). Behavior with invalid SHA-1 context is undefined.
312 If Sha1Context is NULL, then return FALSE.
313 If HashValue is NULL, then return FALSE.
314 If this interface is not supported, then return FALSE.
316 @param[in, out] Sha1Context Pointer to the SHA-1 context.
317 @param[out] HashValue Pointer to a buffer that receives the SHA-1 digest
320 @retval TRUE SHA-1 digest computation succeeded.
321 @retval FALSE SHA-1 digest computation failed.
322 @retval FALSE This interface is not supported.
328 IN OUT VOID
*Sha1Context
,
333 Computes the SHA-1 message digest of a input data buffer.
335 This function performs the SHA-1 message digest of a given data buffer, and places
336 the digest value into the specified memory.
338 If this interface is not supported, then return FALSE.
340 @param[in] Data Pointer to the buffer containing the data to be hashed.
341 @param[in] DataSize Size of Data buffer in bytes.
342 @param[out] HashValue Pointer to a buffer that receives the SHA-1 digest
345 @retval TRUE SHA-1 digest computation succeeded.
346 @retval FALSE SHA-1 digest computation failed.
347 @retval FALSE This interface is not supported.
360 Retrieves the size, in bytes, of the context buffer required for SHA-256 hash operations.
362 @return The size, in bytes, of the context buffer required for SHA-256 hash operations.
367 Sha256GetContextSize (
372 Initializes user-supplied memory pointed by Sha256Context as SHA-256 hash context for
375 If Sha256Context is NULL, then return FALSE.
377 @param[out] Sha256Context Pointer to SHA-256 context being initialized.
379 @retval TRUE SHA-256 context initialization succeeded.
380 @retval FALSE SHA-256 context initialization failed.
386 OUT VOID
*Sha256Context
390 Makes a copy of an existing SHA-256 context.
392 If Sha256Context is NULL, then return FALSE.
393 If NewSha256Context is NULL, then return FALSE.
394 If this interface is not supported, then return FALSE.
396 @param[in] Sha256Context Pointer to SHA-256 context being copied.
397 @param[out] NewSha256Context Pointer to new SHA-256 context.
399 @retval TRUE SHA-256 context copy succeeded.
400 @retval FALSE SHA-256 context copy failed.
401 @retval FALSE This interface is not supported.
407 IN CONST VOID
*Sha256Context
,
408 OUT VOID
*NewSha256Context
412 Digests the input data and updates SHA-256 context.
414 This function performs SHA-256 digest on a data buffer of the specified size.
415 It can be called multiple times to compute the digest of long or discontinuous data streams.
416 SHA-256 context should be already correctly initialized by Sha256Init(), and should not be finalized
417 by Sha256Final(). Behavior with invalid context is undefined.
419 If Sha256Context is NULL, then return FALSE.
421 @param[in, out] Sha256Context Pointer to the SHA-256 context.
422 @param[in] Data Pointer to the buffer containing the data to be hashed.
423 @param[in] DataSize Size of Data buffer in bytes.
425 @retval TRUE SHA-256 data digest succeeded.
426 @retval FALSE SHA-256 data digest failed.
432 IN OUT VOID
*Sha256Context
,
438 Completes computation of the SHA-256 digest value.
440 This function completes SHA-256 hash computation and retrieves the digest value into
441 the specified memory. After this function has been called, the SHA-256 context cannot
443 SHA-256 context should be already correctly initialized by Sha256Init(), and should not be
444 finalized by Sha256Final(). Behavior with invalid SHA-256 context is undefined.
446 If Sha256Context is NULL, then return FALSE.
447 If HashValue is NULL, then return FALSE.
449 @param[in, out] Sha256Context Pointer to the SHA-256 context.
450 @param[out] HashValue Pointer to a buffer that receives the SHA-256 digest
453 @retval TRUE SHA-256 digest computation succeeded.
454 @retval FALSE SHA-256 digest computation failed.
460 IN OUT VOID
*Sha256Context
,
465 Computes the SHA-256 message digest of a input data buffer.
467 This function performs the SHA-256 message digest of a given data buffer, and places
468 the digest value into the specified memory.
470 If this interface is not supported, then return FALSE.
472 @param[in] Data Pointer to the buffer containing the data to be hashed.
473 @param[in] DataSize Size of Data buffer in bytes.
474 @param[out] HashValue Pointer to a buffer that receives the SHA-256 digest
477 @retval TRUE SHA-256 digest computation succeeded.
478 @retval FALSE SHA-256 digest computation failed.
479 @retval FALSE This interface is not supported.
491 Retrieves the size, in bytes, of the context buffer required for SHA-384 hash operations.
493 @return The size, in bytes, of the context buffer required for SHA-384 hash operations.
498 Sha384GetContextSize (
503 Initializes user-supplied memory pointed by Sha384Context as SHA-384 hash context for
506 If Sha384Context is NULL, then return FALSE.
508 @param[out] Sha384Context Pointer to SHA-384 context being initialized.
510 @retval TRUE SHA-384 context initialization succeeded.
511 @retval FALSE SHA-384 context initialization failed.
517 OUT VOID
*Sha384Context
521 Makes a copy of an existing SHA-384 context.
523 If Sha384Context is NULL, then return FALSE.
524 If NewSha384Context is NULL, then return FALSE.
525 If this interface is not supported, then return FALSE.
527 @param[in] Sha384Context Pointer to SHA-384 context being copied.
528 @param[out] NewSha384Context Pointer to new SHA-384 context.
530 @retval TRUE SHA-384 context copy succeeded.
531 @retval FALSE SHA-384 context copy failed.
532 @retval FALSE This interface is not supported.
538 IN CONST VOID
*Sha384Context
,
539 OUT VOID
*NewSha384Context
543 Digests the input data and updates SHA-384 context.
545 This function performs SHA-384 digest on a data buffer of the specified size.
546 It can be called multiple times to compute the digest of long or discontinuous data streams.
547 SHA-384 context should be already correctly initialized by Sha384Init(), and should not be finalized
548 by Sha384Final(). Behavior with invalid context is undefined.
550 If Sha384Context is NULL, then return FALSE.
552 @param[in, out] Sha384Context Pointer to the SHA-384 context.
553 @param[in] Data Pointer to the buffer containing the data to be hashed.
554 @param[in] DataSize Size of Data buffer in bytes.
556 @retval TRUE SHA-384 data digest succeeded.
557 @retval FALSE SHA-384 data digest failed.
563 IN OUT VOID
*Sha384Context
,
569 Completes computation of the SHA-384 digest value.
571 This function completes SHA-384 hash computation and retrieves the digest value into
572 the specified memory. After this function has been called, the SHA-384 context cannot
574 SHA-384 context should be already correctly initialized by Sha384Init(), and should not be
575 finalized by Sha384Final(). Behavior with invalid SHA-384 context is undefined.
577 If Sha384Context is NULL, then return FALSE.
578 If HashValue is NULL, then return FALSE.
580 @param[in, out] Sha384Context Pointer to the SHA-384 context.
581 @param[out] HashValue Pointer to a buffer that receives the SHA-384 digest
584 @retval TRUE SHA-384 digest computation succeeded.
585 @retval FALSE SHA-384 digest computation failed.
591 IN OUT VOID
*Sha384Context
,
596 Computes the SHA-384 message digest of a input data buffer.
598 This function performs the SHA-384 message digest of a given data buffer, and places
599 the digest value into the specified memory.
601 If this interface is not supported, then return FALSE.
603 @param[in] Data Pointer to the buffer containing the data to be hashed.
604 @param[in] DataSize Size of Data buffer in bytes.
605 @param[out] HashValue Pointer to a buffer that receives the SHA-384 digest
608 @retval TRUE SHA-384 digest computation succeeded.
609 @retval FALSE SHA-384 digest computation failed.
610 @retval FALSE This interface is not supported.
622 Retrieves the size, in bytes, of the context buffer required for SHA-512 hash operations.
624 @return The size, in bytes, of the context buffer required for SHA-512 hash operations.
629 Sha512GetContextSize (
634 Initializes user-supplied memory pointed by Sha512Context as SHA-512 hash context for
637 If Sha512Context is NULL, then return FALSE.
639 @param[out] Sha512Context Pointer to SHA-512 context being initialized.
641 @retval TRUE SHA-512 context initialization succeeded.
642 @retval FALSE SHA-512 context initialization failed.
648 OUT VOID
*Sha512Context
652 Makes a copy of an existing SHA-512 context.
654 If Sha512Context is NULL, then return FALSE.
655 If NewSha512Context is NULL, then return FALSE.
656 If this interface is not supported, then return FALSE.
658 @param[in] Sha512Context Pointer to SHA-512 context being copied.
659 @param[out] NewSha512Context Pointer to new SHA-512 context.
661 @retval TRUE SHA-512 context copy succeeded.
662 @retval FALSE SHA-512 context copy failed.
663 @retval FALSE This interface is not supported.
669 IN CONST VOID
*Sha512Context
,
670 OUT VOID
*NewSha512Context
674 Digests the input data and updates SHA-512 context.
676 This function performs SHA-512 digest on a data buffer of the specified size.
677 It can be called multiple times to compute the digest of long or discontinuous data streams.
678 SHA-512 context should be already correctly initialized by Sha512Init(), and should not be finalized
679 by Sha512Final(). Behavior with invalid context is undefined.
681 If Sha512Context is NULL, then return FALSE.
683 @param[in, out] Sha512Context Pointer to the SHA-512 context.
684 @param[in] Data Pointer to the buffer containing the data to be hashed.
685 @param[in] DataSize Size of Data buffer in bytes.
687 @retval TRUE SHA-512 data digest succeeded.
688 @retval FALSE SHA-512 data digest failed.
694 IN OUT VOID
*Sha512Context
,
700 Completes computation of the SHA-512 digest value.
702 This function completes SHA-512 hash computation and retrieves the digest value into
703 the specified memory. After this function has been called, the SHA-512 context cannot
705 SHA-512 context should be already correctly initialized by Sha512Init(), and should not be
706 finalized by Sha512Final(). Behavior with invalid SHA-512 context is undefined.
708 If Sha512Context is NULL, then return FALSE.
709 If HashValue is NULL, then return FALSE.
711 @param[in, out] Sha512Context Pointer to the SHA-512 context.
712 @param[out] HashValue Pointer to a buffer that receives the SHA-512 digest
715 @retval TRUE SHA-512 digest computation succeeded.
716 @retval FALSE SHA-512 digest computation failed.
722 IN OUT VOID
*Sha512Context
,
727 Computes the SHA-512 message digest of a input data buffer.
729 This function performs the SHA-512 message digest of a given data buffer, and places
730 the digest value into the specified memory.
732 If this interface is not supported, then return FALSE.
734 @param[in] Data Pointer to the buffer containing the data to be hashed.
735 @param[in] DataSize Size of Data buffer in bytes.
736 @param[out] HashValue Pointer to a buffer that receives the SHA-512 digest
739 @retval TRUE SHA-512 digest computation succeeded.
740 @retval FALSE SHA-512 digest computation failed.
741 @retval FALSE This interface is not supported.
753 Retrieves the size, in bytes, of the context buffer required for SM3 hash operations.
755 @return The size, in bytes, of the context buffer required for SM3 hash operations.
765 Initializes user-supplied memory pointed by Sm3Context as SM3 hash context for
768 If Sm3Context is NULL, then return FALSE.
770 @param[out] Sm3Context Pointer to SM3 context being initialized.
772 @retval TRUE SM3 context initialization succeeded.
773 @retval FALSE SM3 context initialization failed.
783 Makes a copy of an existing SM3 context.
785 If Sm3Context is NULL, then return FALSE.
786 If NewSm3Context is NULL, then return FALSE.
787 If this interface is not supported, then return FALSE.
789 @param[in] Sm3Context Pointer to SM3 context being copied.
790 @param[out] NewSm3Context Pointer to new SM3 context.
792 @retval TRUE SM3 context copy succeeded.
793 @retval FALSE SM3 context copy failed.
794 @retval FALSE This interface is not supported.
800 IN CONST VOID
*Sm3Context
,
801 OUT VOID
*NewSm3Context
805 Digests the input data and updates SM3 context.
807 This function performs SM3 digest on a data buffer of the specified size.
808 It can be called multiple times to compute the digest of long or discontinuous data streams.
809 SM3 context should be already correctly initialized by Sm3Init(), and should not be finalized
810 by Sm3Final(). Behavior with invalid context is undefined.
812 If Sm3Context is NULL, then return FALSE.
814 @param[in, out] Sm3Context Pointer to the SM3 context.
815 @param[in] Data Pointer to the buffer containing the data to be hashed.
816 @param[in] DataSize Size of Data buffer in bytes.
818 @retval TRUE SM3 data digest succeeded.
819 @retval FALSE SM3 data digest failed.
825 IN OUT VOID
*Sm3Context
,
831 Completes computation of the SM3 digest value.
833 This function completes SM3 hash computation and retrieves the digest value into
834 the specified memory. After this function has been called, the SM3 context cannot
836 SM3 context should be already correctly initialized by Sm3Init(), and should not be
837 finalized by Sm3Final(). Behavior with invalid SM3 context is undefined.
839 If Sm3Context is NULL, then return FALSE.
840 If HashValue is NULL, then return FALSE.
842 @param[in, out] Sm3Context Pointer to the SM3 context.
843 @param[out] HashValue Pointer to a buffer that receives the SM3 digest
846 @retval TRUE SM3 digest computation succeeded.
847 @retval FALSE SM3 digest computation failed.
853 IN OUT VOID
*Sm3Context
,
858 Computes the SM3 message digest of a input data buffer.
860 This function performs the SM3 message digest of a given data buffer, and places
861 the digest value into the specified memory.
863 If this interface is not supported, then return FALSE.
865 @param[in] Data Pointer to the buffer containing the data to be hashed.
866 @param[in] DataSize Size of Data buffer in bytes.
867 @param[out] HashValue Pointer to a buffer that receives the SM3 digest
870 @retval TRUE SM3 digest computation succeeded.
871 @retval FALSE SM3 digest computation failed.
872 @retval FALSE This interface is not supported.
883 //=====================================================================================
884 // MAC (Message Authentication Code) Primitive
885 //=====================================================================================
888 Allocates and initializes one HMAC_CTX context for subsequent HMAC-SHA256 use.
890 @return Pointer to the HMAC_CTX context that has been initialized.
891 If the allocations fails, HmacSha256New() returns NULL.
901 Release the specified HMAC_CTX context.
903 @param[in] HmacSha256Ctx Pointer to the HMAC_CTX context to be released.
909 IN VOID
*HmacSha256Ctx
913 Set user-supplied key for subsequent use. It must be done before any
914 calling to HmacSha256Update().
916 If HmacSha256Context is NULL, then return FALSE.
917 If this interface is not supported, then return FALSE.
919 @param[out] HmacSha256Context Pointer to HMAC-SHA256 context.
920 @param[in] Key Pointer to the user-supplied key.
921 @param[in] KeySize Key size in bytes.
923 @retval TRUE The Key is set successfully.
924 @retval FALSE The Key is set unsuccessfully.
925 @retval FALSE This interface is not supported.
931 OUT VOID
*HmacSha256Context
,
937 Makes a copy of an existing HMAC-SHA256 context.
939 If HmacSha256Context is NULL, then return FALSE.
940 If NewHmacSha256Context is NULL, then return FALSE.
941 If this interface is not supported, then return FALSE.
943 @param[in] HmacSha256Context Pointer to HMAC-SHA256 context being copied.
944 @param[out] NewHmacSha256Context Pointer to new HMAC-SHA256 context.
946 @retval TRUE HMAC-SHA256 context copy succeeded.
947 @retval FALSE HMAC-SHA256 context copy failed.
948 @retval FALSE This interface is not supported.
953 HmacSha256Duplicate (
954 IN CONST VOID
*HmacSha256Context
,
955 OUT VOID
*NewHmacSha256Context
959 Digests the input data and updates HMAC-SHA256 context.
961 This function performs HMAC-SHA256 digest on a data buffer of the specified size.
962 It can be called multiple times to compute the digest of long or discontinuous data streams.
963 HMAC-SHA256 context should be initialized by HmacSha256New(), and should not be finalized
964 by HmacSha256Final(). Behavior with invalid context is undefined.
966 If HmacSha256Context is NULL, then return FALSE.
967 If this interface is not supported, then return FALSE.
969 @param[in, out] HmacSha256Context Pointer to the HMAC-SHA256 context.
970 @param[in] Data Pointer to the buffer containing the data to be digested.
971 @param[in] DataSize Size of Data buffer in bytes.
973 @retval TRUE HMAC-SHA256 data digest succeeded.
974 @retval FALSE HMAC-SHA256 data digest failed.
975 @retval FALSE This interface is not supported.
981 IN OUT VOID
*HmacSha256Context
,
987 Completes computation of the HMAC-SHA256 digest value.
989 This function completes HMAC-SHA256 hash computation and retrieves the digest value into
990 the specified memory. After this function has been called, the HMAC-SHA256 context cannot
992 HMAC-SHA256 context should be initialized by HmacSha256New(), and should not be finalized
993 by HmacSha256Final(). Behavior with invalid HMAC-SHA256 context is undefined.
995 If HmacSha256Context is NULL, then return FALSE.
996 If HmacValue is NULL, then return FALSE.
997 If this interface is not supported, then return FALSE.
999 @param[in, out] HmacSha256Context Pointer to the HMAC-SHA256 context.
1000 @param[out] HmacValue Pointer to a buffer that receives the HMAC-SHA256 digest
1003 @retval TRUE HMAC-SHA256 digest computation succeeded.
1004 @retval FALSE HMAC-SHA256 digest computation failed.
1005 @retval FALSE This interface is not supported.
1011 IN OUT VOID
*HmacSha256Context
,
1012 OUT UINT8
*HmacValue
1015 //=====================================================================================
1016 // Symmetric Cryptography Primitive
1017 //=====================================================================================
1020 Retrieves the size, in bytes, of the context buffer required for AES operations.
1022 If this interface is not supported, then return zero.
1024 @return The size, in bytes, of the context buffer required for AES operations.
1025 @retval 0 This interface is not supported.
1035 Initializes user-supplied memory as AES context for subsequent use.
1037 This function initializes user-supplied memory pointed by AesContext as AES context.
1038 In addition, it sets up all AES key materials for subsequent encryption and decryption
1040 There are 3 options for key length, 128 bits, 192 bits, and 256 bits.
1042 If AesContext is NULL, then return FALSE.
1043 If Key is NULL, then return FALSE.
1044 If KeyLength is not valid, then return FALSE.
1045 If this interface is not supported, then return FALSE.
1047 @param[out] AesContext Pointer to AES context being initialized.
1048 @param[in] Key Pointer to the user-supplied AES key.
1049 @param[in] KeyLength Length of AES key in bits.
1051 @retval TRUE AES context initialization succeeded.
1052 @retval FALSE AES context initialization failed.
1053 @retval FALSE This interface is not supported.
1059 OUT VOID
*AesContext
,
1060 IN CONST UINT8
*Key
,
1065 Performs AES encryption on a data buffer of the specified size in CBC mode.
1067 This function performs AES encryption on data buffer pointed by Input, of specified
1068 size of InputSize, in CBC mode.
1069 InputSize must be multiple of block size (16 bytes). This function does not perform
1070 padding. Caller must perform padding, if necessary, to ensure valid input data size.
1071 Initialization vector should be one block size (16 bytes).
1072 AesContext should be already correctly initialized by AesInit(). Behavior with
1073 invalid AES context is undefined.
1075 If AesContext is NULL, then return FALSE.
1076 If Input is NULL, then return FALSE.
1077 If InputSize is not multiple of block size (16 bytes), then return FALSE.
1078 If Ivec is NULL, then return FALSE.
1079 If Output is NULL, then return FALSE.
1080 If this interface is not supported, then return FALSE.
1082 @param[in] AesContext Pointer to the AES context.
1083 @param[in] Input Pointer to the buffer containing the data to be encrypted.
1084 @param[in] InputSize Size of the Input buffer in bytes.
1085 @param[in] Ivec Pointer to initialization vector.
1086 @param[out] Output Pointer to a buffer that receives the AES encryption output.
1088 @retval TRUE AES encryption succeeded.
1089 @retval FALSE AES encryption failed.
1090 @retval FALSE This interface is not supported.
1096 IN VOID
*AesContext
,
1097 IN CONST UINT8
*Input
,
1099 IN CONST UINT8
*Ivec
,
1104 Performs AES decryption on a data buffer of the specified size in CBC mode.
1106 This function performs AES decryption on data buffer pointed by Input, of specified
1107 size of InputSize, in CBC mode.
1108 InputSize must be multiple of block size (16 bytes). This function does not perform
1109 padding. Caller must perform padding, if necessary, to ensure valid input data size.
1110 Initialization vector should be one block size (16 bytes).
1111 AesContext should be already correctly initialized by AesInit(). Behavior with
1112 invalid AES context is undefined.
1114 If AesContext is NULL, then return FALSE.
1115 If Input is NULL, then return FALSE.
1116 If InputSize is not multiple of block size (16 bytes), then return FALSE.
1117 If Ivec is NULL, then return FALSE.
1118 If Output is NULL, then return FALSE.
1119 If this interface is not supported, then return FALSE.
1121 @param[in] AesContext Pointer to the AES context.
1122 @param[in] Input Pointer to the buffer containing the data to be encrypted.
1123 @param[in] InputSize Size of the Input buffer in bytes.
1124 @param[in] Ivec Pointer to initialization vector.
1125 @param[out] Output Pointer to a buffer that receives the AES encryption output.
1127 @retval TRUE AES decryption succeeded.
1128 @retval FALSE AES decryption failed.
1129 @retval FALSE This interface is not supported.
1135 IN VOID
*AesContext
,
1136 IN CONST UINT8
*Input
,
1138 IN CONST UINT8
*Ivec
,
1142 //=====================================================================================
1143 // Asymmetric Cryptography Primitive
1144 //=====================================================================================
1147 Allocates and initializes one RSA context for subsequent use.
1149 @return Pointer to the RSA context that has been initialized.
1150 If the allocations fails, RsaNew() returns NULL.
1160 Release the specified RSA context.
1162 If RsaContext is NULL, then return FALSE.
1164 @param[in] RsaContext Pointer to the RSA context to be released.
1174 Sets the tag-designated key component into the established RSA context.
1176 This function sets the tag-designated RSA key component into the established
1177 RSA context from the user-specified non-negative integer (octet string format
1178 represented in RSA PKCS#1).
1179 If BigNumber is NULL, then the specified key component in RSA context is cleared.
1181 If RsaContext is NULL, then return FALSE.
1183 @param[in, out] RsaContext Pointer to RSA context being set.
1184 @param[in] KeyTag Tag of RSA key component being set.
1185 @param[in] BigNumber Pointer to octet integer buffer.
1186 If NULL, then the specified key component in RSA
1188 @param[in] BnSize Size of big number buffer in bytes.
1189 If BigNumber is NULL, then it is ignored.
1191 @retval TRUE RSA key component was set successfully.
1192 @retval FALSE Invalid RSA key component tag.
1198 IN OUT VOID
*RsaContext
,
1199 IN RSA_KEY_TAG KeyTag
,
1200 IN CONST UINT8
*BigNumber
,
1205 Gets the tag-designated RSA key component from the established RSA context.
1207 This function retrieves the tag-designated RSA key component from the
1208 established RSA context as a non-negative integer (octet string format
1209 represented in RSA PKCS#1).
1210 If specified key component has not been set or has been cleared, then returned
1212 If the BigNumber buffer is too small to hold the contents of the key, FALSE
1213 is returned and BnSize is set to the required buffer size to obtain the key.
1215 If RsaContext is NULL, then return FALSE.
1216 If BnSize is NULL, then return FALSE.
1217 If BnSize is large enough but BigNumber is NULL, then return FALSE.
1218 If this interface is not supported, then return FALSE.
1220 @param[in, out] RsaContext Pointer to RSA context being set.
1221 @param[in] KeyTag Tag of RSA key component being set.
1222 @param[out] BigNumber Pointer to octet integer buffer.
1223 @param[in, out] BnSize On input, the size of big number buffer in bytes.
1224 On output, the size of data returned in big number buffer in bytes.
1226 @retval TRUE RSA key component was retrieved successfully.
1227 @retval FALSE Invalid RSA key component tag.
1228 @retval FALSE BnSize is too small.
1229 @retval FALSE This interface is not supported.
1235 IN OUT VOID
*RsaContext
,
1236 IN RSA_KEY_TAG KeyTag
,
1237 OUT UINT8
*BigNumber
,
1238 IN OUT UINTN
*BnSize
1242 Generates RSA key components.
1244 This function generates RSA key components. It takes RSA public exponent E and
1245 length in bits of RSA modulus N as input, and generates all key components.
1246 If PublicExponent is NULL, the default RSA public exponent (0x10001) will be used.
1248 Before this function can be invoked, pseudorandom number generator must be correctly
1249 initialized by RandomSeed().
1251 If RsaContext is NULL, then return FALSE.
1252 If this interface is not supported, then return FALSE.
1254 @param[in, out] RsaContext Pointer to RSA context being set.
1255 @param[in] ModulusLength Length of RSA modulus N in bits.
1256 @param[in] PublicExponent Pointer to RSA public exponent.
1257 @param[in] PublicExponentSize Size of RSA public exponent buffer in bytes.
1259 @retval TRUE RSA key component was generated successfully.
1260 @retval FALSE Invalid RSA key component tag.
1261 @retval FALSE This interface is not supported.
1267 IN OUT VOID
*RsaContext
,
1268 IN UINTN ModulusLength
,
1269 IN CONST UINT8
*PublicExponent
,
1270 IN UINTN PublicExponentSize
1274 Validates key components of RSA context.
1275 NOTE: This function performs integrity checks on all the RSA key material, so
1276 the RSA key structure must contain all the private key data.
1278 This function validates key components of RSA context in following aspects:
1279 - Whether p is a prime
1280 - Whether q is a prime
1282 - Whether d*e = 1 mod lcm(p-1,q-1)
1284 If RsaContext is NULL, then return FALSE.
1285 If this interface is not supported, then return FALSE.
1287 @param[in] RsaContext Pointer to RSA context to check.
1289 @retval TRUE RSA key components are valid.
1290 @retval FALSE RSA key components are not valid.
1291 @retval FALSE This interface is not supported.
1301 Carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme.
1303 This function carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme defined in
1305 If the Signature buffer is too small to hold the contents of signature, FALSE
1306 is returned and SigSize is set to the required buffer size to obtain the signature.
1308 If RsaContext is NULL, then return FALSE.
1309 If MessageHash is NULL, then return FALSE.
1310 If HashSize is not equal to the size of MD5, SHA-1 or SHA-256 digest, then return FALSE.
1311 If SigSize is large enough but Signature is NULL, then return FALSE.
1312 If this interface is not supported, then return FALSE.
1314 @param[in] RsaContext Pointer to RSA context for signature generation.
1315 @param[in] MessageHash Pointer to octet message hash to be signed.
1316 @param[in] HashSize Size of the message hash in bytes.
1317 @param[out] Signature Pointer to buffer to receive RSA PKCS1-v1_5 signature.
1318 @param[in, out] SigSize On input, the size of Signature buffer in bytes.
1319 On output, the size of data returned in Signature buffer in bytes.
1321 @retval TRUE Signature successfully generated in PKCS1-v1_5.
1322 @retval FALSE Signature generation failed.
1323 @retval FALSE SigSize is too small.
1324 @retval FALSE This interface is not supported.
1330 IN VOID
*RsaContext
,
1331 IN CONST UINT8
*MessageHash
,
1333 OUT UINT8
*Signature
,
1334 IN OUT UINTN
*SigSize
1338 Verifies the RSA-SSA signature with EMSA-PKCS1-v1_5 encoding scheme defined in
1341 If RsaContext is NULL, then return FALSE.
1342 If MessageHash is NULL, then return FALSE.
1343 If Signature is NULL, then return FALSE.
1344 If HashSize is not equal to the size of MD5, SHA-1, SHA-256 digest, then return FALSE.
1346 @param[in] RsaContext Pointer to RSA context for signature verification.
1347 @param[in] MessageHash Pointer to octet message hash to be checked.
1348 @param[in] HashSize Size of the message hash in bytes.
1349 @param[in] Signature Pointer to RSA PKCS1-v1_5 signature to be verified.
1350 @param[in] SigSize Size of signature in bytes.
1352 @retval TRUE Valid signature encoded in PKCS1-v1_5.
1353 @retval FALSE Invalid signature or invalid RSA context.
1359 IN VOID
*RsaContext
,
1360 IN CONST UINT8
*MessageHash
,
1362 IN CONST UINT8
*Signature
,
1367 Carries out the RSA-SSA signature generation with EMSA-PSS encoding scheme.
1369 This function carries out the RSA-SSA signature generation with EMSA-PSS encoding scheme defined in
1371 Mask generation function is the same as the message digest algorithm.
1372 If the Signature buffer is too small to hold the contents of signature, FALSE
1373 is returned and SigSize is set to the required buffer size to obtain the signature.
1375 If RsaContext is NULL, then return FALSE.
1376 If Message is NULL, then return FALSE.
1377 If MsgSize is zero or > INT_MAX, then return FALSE.
1378 If DigestLen is NOT 32, 48 or 64, return FALSE.
1379 If SaltLen is < DigestLen, then return FALSE.
1380 If SigSize is large enough but Signature is NULL, then return FALSE.
1381 If this interface is not supported, then return FALSE.
1383 @param[in] RsaContext Pointer to RSA context for signature generation.
1384 @param[in] Message Pointer to octet message to be signed.
1385 @param[in] MsgSize Size of the message in bytes.
1386 @param[in] DigestLen Length of the digest in bytes to be used for RSA signature operation.
1387 @param[in] SaltLen Length of the salt in bytes to be used for PSS encoding.
1388 @param[out] Signature Pointer to buffer to receive RSA PSS signature.
1389 @param[in, out] SigSize On input, the size of Signature buffer in bytes.
1390 On output, the size of data returned in Signature buffer in bytes.
1392 @retval TRUE Signature successfully generated in RSASSA-PSS.
1393 @retval FALSE Signature generation failed.
1394 @retval FALSE SigSize is too small.
1395 @retval FALSE This interface is not supported.
1401 IN VOID
*RsaContext
,
1402 IN CONST UINT8
*Message
,
1404 IN UINT16 DigestLen
,
1406 OUT UINT8
*Signature
,
1407 IN OUT UINTN
*SigSize
1411 Verifies the RSA signature with RSASSA-PSS signature scheme defined in RFC 8017.
1412 Implementation determines salt length automatically from the signature encoding.
1413 Mask generation function is the same as the message digest algorithm.
1414 Salt length should atleast be equal to digest length.
1416 @param[in] RsaContext Pointer to RSA context for signature verification.
1417 @param[in] Message Pointer to octet message to be verified.
1418 @param[in] MsgSize Size of the message in bytes.
1419 @param[in] Signature Pointer to RSASSA-PSS signature to be verified.
1420 @param[in] SigSize Size of signature in bytes.
1421 @param[in] DigestLen Length of digest for RSA operation.
1422 @param[in] SaltLen Salt length for PSS encoding.
1424 @retval TRUE Valid signature encoded in RSASSA-PSS.
1425 @retval FALSE Invalid signature or invalid RSA context.
1431 IN VOID
*RsaContext
,
1432 IN CONST UINT8
*Message
,
1434 IN CONST UINT8
*Signature
,
1436 IN UINT16 DigestLen
,
1441 Retrieve the RSA Private Key from the password-protected PEM key data.
1443 If PemData is NULL, then return FALSE.
1444 If RsaContext is NULL, then return FALSE.
1445 If this interface is not supported, then return FALSE.
1447 @param[in] PemData Pointer to the PEM-encoded key data to be retrieved.
1448 @param[in] PemSize Size of the PEM key data in bytes.
1449 @param[in] Password NULL-terminated passphrase used for encrypted PEM key data.
1450 @param[out] RsaContext Pointer to new-generated RSA context which contain the retrieved
1451 RSA private key component. Use RsaFree() function to free the
1454 @retval TRUE RSA Private Key was retrieved successfully.
1455 @retval FALSE Invalid PEM key data or incorrect password.
1456 @retval FALSE This interface is not supported.
1461 RsaGetPrivateKeyFromPem (
1462 IN CONST UINT8
*PemData
,
1464 IN CONST CHAR8
*Password
,
1465 OUT VOID
**RsaContext
1469 Retrieve the RSA Public Key from one DER-encoded X509 certificate.
1471 If Cert is NULL, then return FALSE.
1472 If RsaContext is NULL, then return FALSE.
1473 If this interface is not supported, then return FALSE.
1475 @param[in] Cert Pointer to the DER-encoded X509 certificate.
1476 @param[in] CertSize Size of the X509 certificate in bytes.
1477 @param[out] RsaContext Pointer to new-generated RSA context which contain the retrieved
1478 RSA public key component. Use RsaFree() function to free the
1481 @retval TRUE RSA Public Key was retrieved successfully.
1482 @retval FALSE Fail to retrieve RSA public key from X509 certificate.
1483 @retval FALSE This interface is not supported.
1488 RsaGetPublicKeyFromX509 (
1489 IN CONST UINT8
*Cert
,
1491 OUT VOID
**RsaContext
1495 Retrieve the subject bytes from one X.509 certificate.
1497 If Cert is NULL, then return FALSE.
1498 If SubjectSize is NULL, then return FALSE.
1499 If this interface is not supported, then return FALSE.
1501 @param[in] Cert Pointer to the DER-encoded X509 certificate.
1502 @param[in] CertSize Size of the X509 certificate in bytes.
1503 @param[out] CertSubject Pointer to the retrieved certificate subject bytes.
1504 @param[in, out] SubjectSize The size in bytes of the CertSubject buffer on input,
1505 and the size of buffer returned CertSubject on output.
1507 @retval TRUE The certificate subject retrieved successfully.
1508 @retval FALSE Invalid certificate, or the SubjectSize is too small for the result.
1509 The SubjectSize will be updated with the required size.
1510 @retval FALSE This interface is not supported.
1515 X509GetSubjectName (
1516 IN CONST UINT8
*Cert
,
1518 OUT UINT8
*CertSubject
,
1519 IN OUT UINTN
*SubjectSize
1523 Retrieve the common name (CN) string from one X.509 certificate.
1525 @param[in] Cert Pointer to the DER-encoded X509 certificate.
1526 @param[in] CertSize Size of the X509 certificate in bytes.
1527 @param[out] CommonName Buffer to contain the retrieved certificate common
1528 name string (UTF8). At most CommonNameSize bytes will be
1529 written and the string will be null terminated. May be
1530 NULL in order to determine the size buffer needed.
1531 @param[in,out] CommonNameSize The size in bytes of the CommonName buffer on input,
1532 and the size of buffer returned CommonName on output.
1533 If CommonName is NULL then the amount of space needed
1534 in buffer (including the final null) is returned.
1536 @retval RETURN_SUCCESS The certificate CommonName retrieved successfully.
1537 @retval RETURN_INVALID_PARAMETER If Cert is NULL.
1538 If CommonNameSize is NULL.
1539 If CommonName is not NULL and *CommonNameSize is 0.
1540 If Certificate is invalid.
1541 @retval RETURN_NOT_FOUND If no CommonName entry exists.
1542 @retval RETURN_BUFFER_TOO_SMALL If the CommonName is NULL. The required buffer size
1543 (including the final null) is returned in the
1544 CommonNameSize parameter.
1545 @retval RETURN_UNSUPPORTED The operation is not supported.
1551 IN CONST UINT8
*Cert
,
1553 OUT CHAR8
*CommonName
, OPTIONAL
1554 IN OUT UINTN
*CommonNameSize
1558 Retrieve the organization name (O) string from one X.509 certificate.
1560 @param[in] Cert Pointer to the DER-encoded X509 certificate.
1561 @param[in] CertSize Size of the X509 certificate in bytes.
1562 @param[out] NameBuffer Buffer to contain the retrieved certificate organization
1563 name string. At most NameBufferSize bytes will be
1564 written and the string will be null terminated. May be
1565 NULL in order to determine the size buffer needed.
1566 @param[in,out] NameBufferSize The size in bytes of the Name buffer on input,
1567 and the size of buffer returned Name on output.
1568 If NameBuffer is NULL then the amount of space needed
1569 in buffer (including the final null) is returned.
1571 @retval RETURN_SUCCESS The certificate Organization Name retrieved successfully.
1572 @retval RETURN_INVALID_PARAMETER If Cert is NULL.
1573 If NameBufferSize is NULL.
1574 If NameBuffer is not NULL and *CommonNameSize is 0.
1575 If Certificate is invalid.
1576 @retval RETURN_NOT_FOUND If no Organization Name entry exists.
1577 @retval RETURN_BUFFER_TOO_SMALL If the NameBuffer is NULL. The required buffer size
1578 (including the final null) is returned in the
1579 CommonNameSize parameter.
1580 @retval RETURN_UNSUPPORTED The operation is not supported.
1585 X509GetOrganizationName (
1586 IN CONST UINT8
*Cert
,
1588 OUT CHAR8
*NameBuffer
, OPTIONAL
1589 IN OUT UINTN
*NameBufferSize
1593 Verify one X509 certificate was issued by the trusted CA.
1595 If Cert is NULL, then return FALSE.
1596 If CACert is NULL, then return FALSE.
1597 If this interface is not supported, then return FALSE.
1599 @param[in] Cert Pointer to the DER-encoded X509 certificate to be verified.
1600 @param[in] CertSize Size of the X509 certificate in bytes.
1601 @param[in] CACert Pointer to the DER-encoded trusted CA certificate.
1602 @param[in] CACertSize Size of the CA Certificate in bytes.
1604 @retval TRUE The certificate was issued by the trusted CA.
1605 @retval FALSE Invalid certificate or the certificate was not issued by the given
1607 @retval FALSE This interface is not supported.
1613 IN CONST UINT8
*Cert
,
1615 IN CONST UINT8
*CACert
,
1620 Construct a X509 object from DER-encoded certificate data.
1622 If Cert is NULL, then return FALSE.
1623 If SingleX509Cert is NULL, then return FALSE.
1624 If this interface is not supported, then return FALSE.
1626 @param[in] Cert Pointer to the DER-encoded certificate data.
1627 @param[in] CertSize The size of certificate data in bytes.
1628 @param[out] SingleX509Cert The generated X509 object.
1630 @retval TRUE The X509 object generation succeeded.
1631 @retval FALSE The operation failed.
1632 @retval FALSE This interface is not supported.
1637 X509ConstructCertificate (
1638 IN CONST UINT8
*Cert
,
1640 OUT UINT8
**SingleX509Cert
1644 Construct a X509 stack object from a list of DER-encoded certificate data.
1646 If X509Stack is NULL, then return FALSE.
1647 If this interface is not supported, then return FALSE.
1649 @param[in, out] X509Stack On input, pointer to an existing or NULL X509 stack object.
1650 On output, pointer to the X509 stack object with new
1651 inserted X509 certificate.
1652 @param[in] Args VA_LIST marker for the variable argument list.
1653 A list of DER-encoded single certificate data followed
1654 by certificate size. A NULL terminates the list. The
1655 pairs are the arguments to X509ConstructCertificate().
1657 @retval TRUE The X509 stack construction succeeded.
1658 @retval FALSE The construction operation failed.
1659 @retval FALSE This interface is not supported.
1664 X509ConstructCertificateStackV (
1665 IN OUT UINT8
**X509Stack
,
1670 Construct a X509 stack object from a list of DER-encoded certificate data.
1672 If X509Stack is NULL, then return FALSE.
1673 If this interface is not supported, then return FALSE.
1675 @param[in, out] X509Stack On input, pointer to an existing or NULL X509 stack object.
1676 On output, pointer to the X509 stack object with new
1677 inserted X509 certificate.
1678 @param ... A list of DER-encoded single certificate data followed
1679 by certificate size. A NULL terminates the list. The
1680 pairs are the arguments to X509ConstructCertificate().
1682 @retval TRUE The X509 stack construction succeeded.
1683 @retval FALSE The construction operation failed.
1684 @retval FALSE This interface is not supported.
1689 X509ConstructCertificateStack (
1690 IN OUT UINT8
**X509Stack
,
1695 Release the specified X509 object.
1697 If the interface is not supported, then ASSERT().
1699 @param[in] X509Cert Pointer to the X509 object to be released.
1709 Release the specified X509 stack object.
1711 If the interface is not supported, then ASSERT().
1713 @param[in] X509Stack Pointer to the X509 stack object to be released.
1723 Retrieve the TBSCertificate from one given X.509 certificate.
1725 @param[in] Cert Pointer to the given DER-encoded X509 certificate.
1726 @param[in] CertSize Size of the X509 certificate in bytes.
1727 @param[out] TBSCert DER-Encoded To-Be-Signed certificate.
1728 @param[out] TBSCertSize Size of the TBS certificate in bytes.
1730 If Cert is NULL, then return FALSE.
1731 If TBSCert is NULL, then return FALSE.
1732 If TBSCertSize is NULL, then return FALSE.
1733 If this interface is not supported, then return FALSE.
1735 @retval TRUE The TBSCertificate was retrieved successfully.
1736 @retval FALSE Invalid X.509 certificate.
1742 IN CONST UINT8
*Cert
,
1744 OUT UINT8
**TBSCert
,
1745 OUT UINTN
*TBSCertSize
1749 Derives a key from a password using a salt and iteration count, based on PKCS#5 v2.0
1750 password based encryption key derivation function PBKDF2, as specified in RFC 2898.
1752 If Password or Salt or OutKey is NULL, then return FALSE.
1753 If the hash algorithm could not be determined, then return FALSE.
1754 If this interface is not supported, then return FALSE.
1756 @param[in] PasswordLength Length of input password in bytes.
1757 @param[in] Password Pointer to the array for the password.
1758 @param[in] SaltLength Size of the Salt in bytes.
1759 @param[in] Salt Pointer to the Salt.
1760 @param[in] IterationCount Number of iterations to perform. Its value should be
1761 greater than or equal to 1.
1762 @param[in] DigestSize Size of the message digest to be used (eg. SHA256_DIGEST_SIZE).
1763 NOTE: DigestSize will be used to determine the hash algorithm.
1764 Only SHA1_DIGEST_SIZE or SHA256_DIGEST_SIZE is supported.
1765 @param[in] KeyLength Size of the derived key buffer in bytes.
1766 @param[out] OutKey Pointer to the output derived key buffer.
1768 @retval TRUE A key was derived successfully.
1769 @retval FALSE One of the pointers was NULL or one of the sizes was too large.
1770 @retval FALSE The hash algorithm could not be determined from the digest size.
1771 @retval FALSE The key derivation operation failed.
1772 @retval FALSE This interface is not supported.
1778 IN UINTN PasswordLength
,
1779 IN CONST CHAR8
*Password
,
1780 IN UINTN SaltLength
,
1781 IN CONST UINT8
*Salt
,
1782 IN UINTN IterationCount
,
1783 IN UINTN DigestSize
,
1789 Encrypts a blob using PKCS1v2 (RSAES-OAEP) schema. On success, will return the
1790 encrypted message in a newly allocated buffer.
1792 Things that can cause a failure include:
1793 - X509 key size does not match any known key size.
1794 - Fail to parse X509 certificate.
1795 - Fail to allocate an intermediate buffer.
1796 - Null pointer provided for a non-optional parameter.
1797 - Data size is too large for the provided key size (max size is a function of key size
1798 and hash digest size).
1800 @param[in] PublicKey A pointer to the DER-encoded X509 certificate that
1801 will be used to encrypt the data.
1802 @param[in] PublicKeySize Size of the X509 cert buffer.
1803 @param[in] InData Data to be encrypted.
1804 @param[in] InDataSize Size of the data buffer.
1805 @param[in] PrngSeed [Optional] If provided, a pointer to a random seed buffer
1806 to be used when initializing the PRNG. NULL otherwise.
1807 @param[in] PrngSeedSize [Optional] If provided, size of the random seed buffer.
1809 @param[out] EncryptedData Pointer to an allocated buffer containing the encrypted
1811 @param[out] EncryptedDataSize Size of the encrypted message buffer.
1813 @retval TRUE Encryption was successful.
1814 @retval FALSE Encryption failed.
1820 IN CONST UINT8
*PublicKey
,
1821 IN UINTN PublicKeySize
,
1823 IN UINTN InDataSize
,
1824 IN CONST UINT8
*PrngSeed
, OPTIONAL
1825 IN UINTN PrngSeedSize
, OPTIONAL
1826 OUT UINT8
**EncryptedData
,
1827 OUT UINTN
*EncryptedDataSize
1831 The 3rd parameter of Pkcs7GetSigners will return all embedded
1832 X.509 certificate in one given PKCS7 signature. The format is:
1834 // UINT8 CertNumber;
1835 // UINT32 Cert1Length;
1837 // UINT32 Cert2Length;
1840 // UINT32 CertnLength;
1844 The two following C-structure are used for parsing CertStack more clearly.
1849 UINT32 CertDataLength
; // The length in bytes of X.509 certificate.
1850 UINT8 CertDataBuffer
[0]; // The X.509 certificate content (DER).
1854 UINT8 CertNumber
; // Number of X.509 certificate.
1855 //EFI_CERT_DATA CertArray[]; // An array of X.509 certificate.
1861 Get the signer's certificates from PKCS#7 signed data as described in "PKCS #7:
1862 Cryptographic Message Syntax Standard". The input signed data could be wrapped
1863 in a ContentInfo structure.
1865 If P7Data, CertStack, StackLength, TrustedCert or CertLength is NULL, then
1866 return FALSE. If P7Length overflow, then return FALSE.
1867 If this interface is not supported, then return FALSE.
1869 @param[in] P7Data Pointer to the PKCS#7 message to verify.
1870 @param[in] P7Length Length of the PKCS#7 message in bytes.
1871 @param[out] CertStack Pointer to Signer's certificates retrieved from P7Data.
1872 It's caller's responsibility to free the buffer with
1874 This data structure is EFI_CERT_STACK type.
1875 @param[out] StackLength Length of signer's certificates in bytes.
1876 @param[out] TrustedCert Pointer to a trusted certificate from Signer's certificates.
1877 It's caller's responsibility to free the buffer with
1879 @param[out] CertLength Length of the trusted certificate in bytes.
1881 @retval TRUE The operation is finished successfully.
1882 @retval FALSE Error occurs during the operation.
1883 @retval FALSE This interface is not supported.
1889 IN CONST UINT8
*P7Data
,
1891 OUT UINT8
**CertStack
,
1892 OUT UINTN
*StackLength
,
1893 OUT UINT8
**TrustedCert
,
1894 OUT UINTN
*CertLength
1898 Wrap function to use free() to free allocated memory for certificates.
1900 If this interface is not supported, then ASSERT().
1902 @param[in] Certs Pointer to the certificates to be freed.
1912 Retrieves all embedded certificates from PKCS#7 signed data as described in "PKCS #7:
1913 Cryptographic Message Syntax Standard", and outputs two certificate lists chained and
1914 unchained to the signer's certificates.
1915 The input signed data could be wrapped in a ContentInfo structure.
1917 @param[in] P7Data Pointer to the PKCS#7 message.
1918 @param[in] P7Length Length of the PKCS#7 message in bytes.
1919 @param[out] SignerChainCerts Pointer to the certificates list chained to signer's
1920 certificate. It's caller's responsibility to free the buffer
1921 with Pkcs7FreeSigners().
1922 This data structure is EFI_CERT_STACK type.
1923 @param[out] ChainLength Length of the chained certificates list buffer in bytes.
1924 @param[out] UnchainCerts Pointer to the unchained certificates lists. It's caller's
1925 responsibility to free the buffer with Pkcs7FreeSigners().
1926 This data structure is EFI_CERT_STACK type.
1927 @param[out] UnchainLength Length of the unchained certificates list buffer in bytes.
1929 @retval TRUE The operation is finished successfully.
1930 @retval FALSE Error occurs during the operation.
1935 Pkcs7GetCertificatesList (
1936 IN CONST UINT8
*P7Data
,
1938 OUT UINT8
**SignerChainCerts
,
1939 OUT UINTN
*ChainLength
,
1940 OUT UINT8
**UnchainCerts
,
1941 OUT UINTN
*UnchainLength
1945 Creates a PKCS#7 signedData as described in "PKCS #7: Cryptographic Message
1946 Syntax Standard, version 1.5". This interface is only intended to be used for
1947 application to perform PKCS#7 functionality validation.
1949 If this interface is not supported, then return FALSE.
1951 @param[in] PrivateKey Pointer to the PEM-formatted private key data for
1953 @param[in] PrivateKeySize Size of the PEM private key data in bytes.
1954 @param[in] KeyPassword NULL-terminated passphrase used for encrypted PEM
1956 @param[in] InData Pointer to the content to be signed.
1957 @param[in] InDataSize Size of InData in bytes.
1958 @param[in] SignCert Pointer to signer's DER-encoded certificate to sign with.
1959 @param[in] OtherCerts Pointer to an optional additional set of certificates to
1960 include in the PKCS#7 signedData (e.g. any intermediate
1962 @param[out] SignedData Pointer to output PKCS#7 signedData. It's caller's
1963 responsibility to free the buffer with FreePool().
1964 @param[out] SignedDataSize Size of SignedData in bytes.
1966 @retval TRUE PKCS#7 data signing succeeded.
1967 @retval FALSE PKCS#7 data signing failed.
1968 @retval FALSE This interface is not supported.
1974 IN CONST UINT8
*PrivateKey
,
1975 IN UINTN PrivateKeySize
,
1976 IN CONST UINT8
*KeyPassword
,
1978 IN UINTN InDataSize
,
1980 IN UINT8
*OtherCerts OPTIONAL
,
1981 OUT UINT8
**SignedData
,
1982 OUT UINTN
*SignedDataSize
1986 Verifies the validity of a PKCS#7 signed data as described in "PKCS #7:
1987 Cryptographic Message Syntax Standard". The input signed data could be wrapped
1988 in a ContentInfo structure.
1990 If P7Data, TrustedCert or InData is NULL, then return FALSE.
1991 If P7Length, CertLength or DataLength overflow, then return FALSE.
1992 If this interface is not supported, then return FALSE.
1994 @param[in] P7Data Pointer to the PKCS#7 message to verify.
1995 @param[in] P7Length Length of the PKCS#7 message in bytes.
1996 @param[in] TrustedCert Pointer to a trusted/root certificate encoded in DER, which
1997 is used for certificate chain verification.
1998 @param[in] CertLength Length of the trusted certificate in bytes.
1999 @param[in] InData Pointer to the content to be verified.
2000 @param[in] DataLength Length of InData in bytes.
2002 @retval TRUE The specified PKCS#7 signed data is valid.
2003 @retval FALSE Invalid PKCS#7 signed data.
2004 @retval FALSE This interface is not supported.
2010 IN CONST UINT8
*P7Data
,
2012 IN CONST UINT8
*TrustedCert
,
2013 IN UINTN CertLength
,
2014 IN CONST UINT8
*InData
,
2019 This function receives a PKCS7 formatted signature, and then verifies that
2020 the specified Enhanced or Extended Key Usages (EKU's) are present in the end-entity
2021 leaf signing certificate.
2022 Note that this function does not validate the certificate chain.
2024 Applications for custom EKU's are quite flexible. For example, a policy EKU
2025 may be present in an Issuing Certificate Authority (CA), and any sub-ordinate
2026 certificate issued might also contain this EKU, thus constraining the
2027 sub-ordinate certificate. Other applications might allow a certificate
2028 embedded in a device to specify that other Object Identifiers (OIDs) are
2029 present which contains binary data specifying custom capabilities that
2030 the device is able to do.
2032 @param[in] Pkcs7Signature The PKCS#7 signed information content block. An array
2033 containing the content block with both the signature,
2034 the signer's certificate, and any necessary intermediate
2036 @param[in] Pkcs7SignatureSize Number of bytes in Pkcs7Signature.
2037 @param[in] RequiredEKUs Array of null-terminated strings listing OIDs of
2038 required EKUs that must be present in the signature.
2039 @param[in] RequiredEKUsSize Number of elements in the RequiredEKUs string array.
2040 @param[in] RequireAllPresent If this is TRUE, then all of the specified EKU's
2041 must be present in the leaf signer. If it is
2042 FALSE, then we will succeed if we find any
2043 of the specified EKU's.
2045 @retval EFI_SUCCESS The required EKUs were found in the signature.
2046 @retval EFI_INVALID_PARAMETER A parameter was invalid.
2047 @retval EFI_NOT_FOUND One or more EKU's were not found in the signature.
2052 VerifyEKUsInPkcs7Signature (
2053 IN CONST UINT8
*Pkcs7Signature
,
2054 IN CONST UINT32 SignatureSize
,
2055 IN CONST CHAR8
*RequiredEKUs
[],
2056 IN CONST UINT32 RequiredEKUsSize
,
2057 IN BOOLEAN RequireAllPresent
2061 Extracts the attached content from a PKCS#7 signed data if existed. The input signed
2062 data could be wrapped in a ContentInfo structure.
2064 If P7Data, Content, or ContentSize is NULL, then return FALSE. If P7Length overflow,
2065 then return FALSE. If the P7Data is not correctly formatted, then return FALSE.
2067 Caution: This function may receive untrusted input. So this function will do
2068 basic check for PKCS#7 data structure.
2070 @param[in] P7Data Pointer to the PKCS#7 signed data to process.
2071 @param[in] P7Length Length of the PKCS#7 signed data in bytes.
2072 @param[out] Content Pointer to the extracted content from the PKCS#7 signedData.
2073 It's caller's responsibility to free the buffer with FreePool().
2074 @param[out] ContentSize The size of the extracted content in bytes.
2076 @retval TRUE The P7Data was correctly formatted for processing.
2077 @retval FALSE The P7Data was not correctly formatted for processing.
2082 Pkcs7GetAttachedContent (
2083 IN CONST UINT8
*P7Data
,
2086 OUT UINTN
*ContentSize
2090 Verifies the validity of a PE/COFF Authenticode Signature as described in "Windows
2091 Authenticode Portable Executable Signature Format".
2093 If AuthData is NULL, then return FALSE.
2094 If ImageHash is NULL, then return FALSE.
2095 If this interface is not supported, then return FALSE.
2097 @param[in] AuthData Pointer to the Authenticode Signature retrieved from signed
2098 PE/COFF image to be verified.
2099 @param[in] DataSize Size of the Authenticode Signature in bytes.
2100 @param[in] TrustedCert Pointer to a trusted/root certificate encoded in DER, which
2101 is used for certificate chain verification.
2102 @param[in] CertSize Size of the trusted certificate in bytes.
2103 @param[in] ImageHash Pointer to the original image file hash value. The procedure
2104 for calculating the image hash value is described in Authenticode
2106 @param[in] HashSize Size of Image hash value in bytes.
2108 @retval TRUE The specified Authenticode Signature is valid.
2109 @retval FALSE Invalid Authenticode Signature.
2110 @retval FALSE This interface is not supported.
2115 AuthenticodeVerify (
2116 IN CONST UINT8
*AuthData
,
2118 IN CONST UINT8
*TrustedCert
,
2120 IN CONST UINT8
*ImageHash
,
2125 Verifies the validity of a RFC3161 Timestamp CounterSignature embedded in PE/COFF Authenticode
2128 If AuthData is NULL, then return FALSE.
2129 If this interface is not supported, then return FALSE.
2131 @param[in] AuthData Pointer to the Authenticode Signature retrieved from signed
2132 PE/COFF image to be verified.
2133 @param[in] DataSize Size of the Authenticode Signature in bytes.
2134 @param[in] TsaCert Pointer to a trusted/root TSA certificate encoded in DER, which
2135 is used for TSA certificate chain verification.
2136 @param[in] CertSize Size of the trusted certificate in bytes.
2137 @param[out] SigningTime Return the time of timestamp generation time if the timestamp
2140 @retval TRUE The specified Authenticode includes a valid RFC3161 Timestamp CounterSignature.
2141 @retval FALSE No valid RFC3161 Timestamp CounterSignature in the specified Authenticode data.
2146 ImageTimestampVerify (
2147 IN CONST UINT8
*AuthData
,
2149 IN CONST UINT8
*TsaCert
,
2151 OUT EFI_TIME
*SigningTime
2154 //=====================================================================================
2155 // DH Key Exchange Primitive
2156 //=====================================================================================
2159 Allocates and Initializes one Diffie-Hellman Context for subsequent use.
2161 @return Pointer to the Diffie-Hellman Context that has been initialized.
2162 If the allocations fails, DhNew() returns NULL.
2163 If the interface is not supported, DhNew() returns NULL.
2173 Release the specified DH context.
2175 If the interface is not supported, then ASSERT().
2177 @param[in] DhContext Pointer to the DH context to be released.
2187 Generates DH parameter.
2189 Given generator g, and length of prime number p in bits, this function generates p,
2190 and sets DH context according to value of g and p.
2192 Before this function can be invoked, pseudorandom number generator must be correctly
2193 initialized by RandomSeed().
2195 If DhContext is NULL, then return FALSE.
2196 If Prime is NULL, then return FALSE.
2197 If this interface is not supported, then return FALSE.
2199 @param[in, out] DhContext Pointer to the DH context.
2200 @param[in] Generator Value of generator.
2201 @param[in] PrimeLength Length in bits of prime to be generated.
2202 @param[out] Prime Pointer to the buffer to receive the generated prime number.
2204 @retval TRUE DH parameter generation succeeded.
2205 @retval FALSE Value of Generator is not supported.
2206 @retval FALSE PRNG fails to generate random prime number with PrimeLength.
2207 @retval FALSE This interface is not supported.
2212 DhGenerateParameter (
2213 IN OUT VOID
*DhContext
,
2215 IN UINTN PrimeLength
,
2220 Sets generator and prime parameters for DH.
2222 Given generator g, and prime number p, this function and sets DH
2223 context accordingly.
2225 If DhContext is NULL, then return FALSE.
2226 If Prime is NULL, then return FALSE.
2227 If this interface is not supported, then return FALSE.
2229 @param[in, out] DhContext Pointer to the DH context.
2230 @param[in] Generator Value of generator.
2231 @param[in] PrimeLength Length in bits of prime to be generated.
2232 @param[in] Prime Pointer to the prime number.
2234 @retval TRUE DH parameter setting succeeded.
2235 @retval FALSE Value of Generator is not supported.
2236 @retval FALSE Value of Generator is not suitable for the Prime.
2237 @retval FALSE Value of Prime is not a prime number.
2238 @retval FALSE Value of Prime is not a safe prime number.
2239 @retval FALSE This interface is not supported.
2245 IN OUT VOID
*DhContext
,
2247 IN UINTN PrimeLength
,
2248 IN CONST UINT8
*Prime
2252 Generates DH public key.
2254 This function generates random secret exponent, and computes the public key, which is
2255 returned via parameter PublicKey and PublicKeySize. DH context is updated accordingly.
2256 If the PublicKey buffer is too small to hold the public key, FALSE is returned and
2257 PublicKeySize is set to the required buffer size to obtain the public key.
2259 If DhContext is NULL, then return FALSE.
2260 If PublicKeySize is NULL, then return FALSE.
2261 If PublicKeySize is large enough but PublicKey is NULL, then return FALSE.
2262 If this interface is not supported, then return FALSE.
2264 @param[in, out] DhContext Pointer to the DH context.
2265 @param[out] PublicKey Pointer to the buffer to receive generated public key.
2266 @param[in, out] PublicKeySize On input, the size of PublicKey buffer in bytes.
2267 On output, the size of data returned in PublicKey buffer in bytes.
2269 @retval TRUE DH public key generation succeeded.
2270 @retval FALSE DH public key generation failed.
2271 @retval FALSE PublicKeySize is not large enough.
2272 @retval FALSE This interface is not supported.
2278 IN OUT VOID
*DhContext
,
2279 OUT UINT8
*PublicKey
,
2280 IN OUT UINTN
*PublicKeySize
2284 Computes exchanged common key.
2286 Given peer's public key, this function computes the exchanged common key, based on its own
2287 context including value of prime modulus and random secret exponent.
2289 If DhContext is NULL, then return FALSE.
2290 If PeerPublicKey is NULL, then return FALSE.
2291 If KeySize is NULL, then return FALSE.
2292 If Key is NULL, then return FALSE.
2293 If KeySize is not large enough, then return FALSE.
2294 If this interface is not supported, then return FALSE.
2296 @param[in, out] DhContext Pointer to the DH context.
2297 @param[in] PeerPublicKey Pointer to the peer's public key.
2298 @param[in] PeerPublicKeySize Size of peer's public key in bytes.
2299 @param[out] Key Pointer to the buffer to receive generated key.
2300 @param[in, out] KeySize On input, the size of Key buffer in bytes.
2301 On output, the size of data returned in Key buffer in bytes.
2303 @retval TRUE DH exchanged key generation succeeded.
2304 @retval FALSE DH exchanged key generation failed.
2305 @retval FALSE KeySize is not large enough.
2306 @retval FALSE This interface is not supported.
2312 IN OUT VOID
*DhContext
,
2313 IN CONST UINT8
*PeerPublicKey
,
2314 IN UINTN PeerPublicKeySize
,
2316 IN OUT UINTN
*KeySize
2319 //=====================================================================================
2320 // Pseudo-Random Generation Primitive
2321 //=====================================================================================
2324 Sets up the seed value for the pseudorandom number generator.
2326 This function sets up the seed value for the pseudorandom number generator.
2327 If Seed is not NULL, then the seed passed in is used.
2328 If Seed is NULL, then default seed is used.
2329 If this interface is not supported, then return FALSE.
2331 @param[in] Seed Pointer to seed value.
2332 If NULL, default seed is used.
2333 @param[in] SeedSize Size of seed value.
2334 If Seed is NULL, this parameter is ignored.
2336 @retval TRUE Pseudorandom number generator has enough entropy for random generation.
2337 @retval FALSE Pseudorandom number generator does not have enough entropy for random generation.
2338 @retval FALSE This interface is not supported.
2344 IN CONST UINT8
*Seed OPTIONAL
,
2349 Generates a pseudorandom byte stream of the specified size.
2351 If Output is NULL, then return FALSE.
2352 If this interface is not supported, then return FALSE.
2354 @param[out] Output Pointer to buffer to receive random value.
2355 @param[in] Size Size of random bytes to generate.
2357 @retval TRUE Pseudorandom byte stream generated successfully.
2358 @retval FALSE Pseudorandom number generator fails to generate due to lack of entropy.
2359 @retval FALSE This interface is not supported.
2369 //=====================================================================================
2370 // Key Derivation Function Primitive
2371 //=====================================================================================
2374 Derive key data using HMAC-SHA256 based KDF.
2376 @param[in] Key Pointer to the user-supplied key.
2377 @param[in] KeySize Key size in bytes.
2378 @param[in] Salt Pointer to the salt(non-secret) value.
2379 @param[in] SaltSize Salt size in bytes.
2380 @param[in] Info Pointer to the application specific info.
2381 @param[in] InfoSize Info size in bytes.
2382 @param[out] Out Pointer to buffer to receive hkdf value.
2383 @param[in] OutSize Size of hkdf bytes to generate.
2385 @retval TRUE Hkdf generated successfully.
2386 @retval FALSE Hkdf generation failed.
2391 HkdfSha256ExtractAndExpand (
2392 IN CONST UINT8
*Key
,
2394 IN CONST UINT8
*Salt
,
2396 IN CONST UINT8
*Info
,
2402 #endif // __BASE_CRYPT_LIB_H__