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 #ifndef DISABLE_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.
218 Retrieves the size, in bytes, of the context buffer required for SHA-1 hash operations.
220 If this interface is not supported, then return zero.
222 @return The size, in bytes, of the context buffer required for SHA-1 hash operations.
223 @retval 0 This interface is not supported.
233 Initializes user-supplied memory pointed by Sha1Context as SHA-1 hash context for
236 If Sha1Context is NULL, then return FALSE.
237 If this interface is not supported, then return FALSE.
239 @param[out] Sha1Context Pointer to SHA-1 context being initialized.
241 @retval TRUE SHA-1 context initialization succeeded.
242 @retval FALSE SHA-1 context initialization failed.
243 @retval FALSE This interface is not supported.
249 OUT VOID
*Sha1Context
253 Makes a copy of an existing SHA-1 context.
255 If Sha1Context is NULL, then return FALSE.
256 If NewSha1Context is NULL, then return FALSE.
257 If this interface is not supported, then return FALSE.
259 @param[in] Sha1Context Pointer to SHA-1 context being copied.
260 @param[out] NewSha1Context Pointer to new SHA-1 context.
262 @retval TRUE SHA-1 context copy succeeded.
263 @retval FALSE SHA-1 context copy failed.
264 @retval FALSE This interface is not supported.
270 IN CONST VOID
*Sha1Context
,
271 OUT VOID
*NewSha1Context
275 Digests the input data and updates SHA-1 context.
277 This function performs SHA-1 digest on a data buffer of the specified size.
278 It can be called multiple times to compute the digest of long or discontinuous data streams.
279 SHA-1 context should be already correctly initialized by Sha1Init(), and should not be finalized
280 by Sha1Final(). Behavior with invalid context is undefined.
282 If Sha1Context is NULL, then return FALSE.
283 If this interface is not supported, then return FALSE.
285 @param[in, out] Sha1Context Pointer to the SHA-1 context.
286 @param[in] Data Pointer to the buffer containing the data to be hashed.
287 @param[in] DataSize Size of Data buffer in bytes.
289 @retval TRUE SHA-1 data digest succeeded.
290 @retval FALSE SHA-1 data digest failed.
291 @retval FALSE This interface is not supported.
297 IN OUT VOID
*Sha1Context
,
303 Completes computation of the SHA-1 digest value.
305 This function completes SHA-1 hash computation and retrieves the digest value into
306 the specified memory. After this function has been called, the SHA-1 context cannot
308 SHA-1 context should be already correctly initialized by Sha1Init(), and should not be
309 finalized by Sha1Final(). Behavior with invalid SHA-1 context is undefined.
311 If Sha1Context is NULL, then return FALSE.
312 If HashValue is NULL, then return FALSE.
313 If this interface is not supported, then return FALSE.
315 @param[in, out] Sha1Context Pointer to the SHA-1 context.
316 @param[out] HashValue Pointer to a buffer that receives the SHA-1 digest
319 @retval TRUE SHA-1 digest computation succeeded.
320 @retval FALSE SHA-1 digest computation failed.
321 @retval FALSE This interface is not supported.
327 IN OUT VOID
*Sha1Context
,
332 Computes the SHA-1 message digest of a input data buffer.
334 This function performs the SHA-1 message digest of a given data buffer, and places
335 the digest value into the specified memory.
337 If this interface is not supported, then return FALSE.
339 @param[in] Data Pointer to the buffer containing the data to be hashed.
340 @param[in] DataSize Size of Data buffer in bytes.
341 @param[out] HashValue Pointer to a buffer that receives the SHA-1 digest
344 @retval TRUE SHA-1 digest computation succeeded.
345 @retval FALSE SHA-1 digest computation failed.
346 @retval FALSE This interface is not supported.
358 Retrieves the size, in bytes, of the context buffer required for SHA-256 hash operations.
360 @return The size, in bytes, of the context buffer required for SHA-256 hash operations.
365 Sha256GetContextSize (
370 Initializes user-supplied memory pointed by Sha256Context as SHA-256 hash context for
373 If Sha256Context is NULL, then return FALSE.
375 @param[out] Sha256Context Pointer to SHA-256 context being initialized.
377 @retval TRUE SHA-256 context initialization succeeded.
378 @retval FALSE SHA-256 context initialization failed.
384 OUT VOID
*Sha256Context
388 Makes a copy of an existing SHA-256 context.
390 If Sha256Context is NULL, then return FALSE.
391 If NewSha256Context is NULL, then return FALSE.
392 If this interface is not supported, then return FALSE.
394 @param[in] Sha256Context Pointer to SHA-256 context being copied.
395 @param[out] NewSha256Context Pointer to new SHA-256 context.
397 @retval TRUE SHA-256 context copy succeeded.
398 @retval FALSE SHA-256 context copy failed.
399 @retval FALSE This interface is not supported.
405 IN CONST VOID
*Sha256Context
,
406 OUT VOID
*NewSha256Context
410 Digests the input data and updates SHA-256 context.
412 This function performs SHA-256 digest on a data buffer of the specified size.
413 It can be called multiple times to compute the digest of long or discontinuous data streams.
414 SHA-256 context should be already correctly initialized by Sha256Init(), and should not be finalized
415 by Sha256Final(). Behavior with invalid context is undefined.
417 If Sha256Context is NULL, then return FALSE.
419 @param[in, out] Sha256Context Pointer to the SHA-256 context.
420 @param[in] Data Pointer to the buffer containing the data to be hashed.
421 @param[in] DataSize Size of Data buffer in bytes.
423 @retval TRUE SHA-256 data digest succeeded.
424 @retval FALSE SHA-256 data digest failed.
430 IN OUT VOID
*Sha256Context
,
436 Completes computation of the SHA-256 digest value.
438 This function completes SHA-256 hash computation and retrieves the digest value into
439 the specified memory. After this function has been called, the SHA-256 context cannot
441 SHA-256 context should be already correctly initialized by Sha256Init(), and should not be
442 finalized by Sha256Final(). Behavior with invalid SHA-256 context is undefined.
444 If Sha256Context is NULL, then return FALSE.
445 If HashValue is NULL, then return FALSE.
447 @param[in, out] Sha256Context Pointer to the SHA-256 context.
448 @param[out] HashValue Pointer to a buffer that receives the SHA-256 digest
451 @retval TRUE SHA-256 digest computation succeeded.
452 @retval FALSE SHA-256 digest computation failed.
458 IN OUT VOID
*Sha256Context
,
463 Computes the SHA-256 message digest of a input data buffer.
465 This function performs the SHA-256 message digest of a given data buffer, and places
466 the digest value into the specified memory.
468 If this interface is not supported, then return FALSE.
470 @param[in] Data Pointer to the buffer containing the data to be hashed.
471 @param[in] DataSize Size of Data buffer in bytes.
472 @param[out] HashValue Pointer to a buffer that receives the SHA-256 digest
475 @retval TRUE SHA-256 digest computation succeeded.
476 @retval FALSE SHA-256 digest computation failed.
477 @retval FALSE This interface is not supported.
489 Retrieves the size, in bytes, of the context buffer required for SHA-384 hash operations.
491 @return The size, in bytes, of the context buffer required for SHA-384 hash operations.
496 Sha384GetContextSize (
501 Initializes user-supplied memory pointed by Sha384Context as SHA-384 hash context for
504 If Sha384Context is NULL, then return FALSE.
506 @param[out] Sha384Context Pointer to SHA-384 context being initialized.
508 @retval TRUE SHA-384 context initialization succeeded.
509 @retval FALSE SHA-384 context initialization failed.
515 OUT VOID
*Sha384Context
519 Makes a copy of an existing SHA-384 context.
521 If Sha384Context is NULL, then return FALSE.
522 If NewSha384Context is NULL, then return FALSE.
523 If this interface is not supported, then return FALSE.
525 @param[in] Sha384Context Pointer to SHA-384 context being copied.
526 @param[out] NewSha384Context Pointer to new SHA-384 context.
528 @retval TRUE SHA-384 context copy succeeded.
529 @retval FALSE SHA-384 context copy failed.
530 @retval FALSE This interface is not supported.
536 IN CONST VOID
*Sha384Context
,
537 OUT VOID
*NewSha384Context
541 Digests the input data and updates SHA-384 context.
543 This function performs SHA-384 digest on a data buffer of the specified size.
544 It can be called multiple times to compute the digest of long or discontinuous data streams.
545 SHA-384 context should be already correctly initialized by Sha384Init(), and should not be finalized
546 by Sha384Final(). Behavior with invalid context is undefined.
548 If Sha384Context is NULL, then return FALSE.
550 @param[in, out] Sha384Context Pointer to the SHA-384 context.
551 @param[in] Data Pointer to the buffer containing the data to be hashed.
552 @param[in] DataSize Size of Data buffer in bytes.
554 @retval TRUE SHA-384 data digest succeeded.
555 @retval FALSE SHA-384 data digest failed.
561 IN OUT VOID
*Sha384Context
,
567 Completes computation of the SHA-384 digest value.
569 This function completes SHA-384 hash computation and retrieves the digest value into
570 the specified memory. After this function has been called, the SHA-384 context cannot
572 SHA-384 context should be already correctly initialized by Sha384Init(), and should not be
573 finalized by Sha384Final(). Behavior with invalid SHA-384 context is undefined.
575 If Sha384Context is NULL, then return FALSE.
576 If HashValue is NULL, then return FALSE.
578 @param[in, out] Sha384Context Pointer to the SHA-384 context.
579 @param[out] HashValue Pointer to a buffer that receives the SHA-384 digest
582 @retval TRUE SHA-384 digest computation succeeded.
583 @retval FALSE SHA-384 digest computation failed.
589 IN OUT VOID
*Sha384Context
,
594 Computes the SHA-384 message digest of a input data buffer.
596 This function performs the SHA-384 message digest of a given data buffer, and places
597 the digest value into the specified memory.
599 If this interface is not supported, then return FALSE.
601 @param[in] Data Pointer to the buffer containing the data to be hashed.
602 @param[in] DataSize Size of Data buffer in bytes.
603 @param[out] HashValue Pointer to a buffer that receives the SHA-384 digest
606 @retval TRUE SHA-384 digest computation succeeded.
607 @retval FALSE SHA-384 digest computation failed.
608 @retval FALSE This interface is not supported.
620 Retrieves the size, in bytes, of the context buffer required for SHA-512 hash operations.
622 @return The size, in bytes, of the context buffer required for SHA-512 hash operations.
627 Sha512GetContextSize (
632 Initializes user-supplied memory pointed by Sha512Context as SHA-512 hash context for
635 If Sha512Context is NULL, then return FALSE.
637 @param[out] Sha512Context Pointer to SHA-512 context being initialized.
639 @retval TRUE SHA-512 context initialization succeeded.
640 @retval FALSE SHA-512 context initialization failed.
646 OUT VOID
*Sha512Context
650 Makes a copy of an existing SHA-512 context.
652 If Sha512Context is NULL, then return FALSE.
653 If NewSha512Context is NULL, then return FALSE.
654 If this interface is not supported, then return FALSE.
656 @param[in] Sha512Context Pointer to SHA-512 context being copied.
657 @param[out] NewSha512Context Pointer to new SHA-512 context.
659 @retval TRUE SHA-512 context copy succeeded.
660 @retval FALSE SHA-512 context copy failed.
661 @retval FALSE This interface is not supported.
667 IN CONST VOID
*Sha512Context
,
668 OUT VOID
*NewSha512Context
672 Digests the input data and updates SHA-512 context.
674 This function performs SHA-512 digest on a data buffer of the specified size.
675 It can be called multiple times to compute the digest of long or discontinuous data streams.
676 SHA-512 context should be already correctly initialized by Sha512Init(), and should not be finalized
677 by Sha512Final(). Behavior with invalid context is undefined.
679 If Sha512Context is NULL, then return FALSE.
681 @param[in, out] Sha512Context Pointer to the SHA-512 context.
682 @param[in] Data Pointer to the buffer containing the data to be hashed.
683 @param[in] DataSize Size of Data buffer in bytes.
685 @retval TRUE SHA-512 data digest succeeded.
686 @retval FALSE SHA-512 data digest failed.
692 IN OUT VOID
*Sha512Context
,
698 Completes computation of the SHA-512 digest value.
700 This function completes SHA-512 hash computation and retrieves the digest value into
701 the specified memory. After this function has been called, the SHA-512 context cannot
703 SHA-512 context should be already correctly initialized by Sha512Init(), and should not be
704 finalized by Sha512Final(). Behavior with invalid SHA-512 context is undefined.
706 If Sha512Context is NULL, then return FALSE.
707 If HashValue is NULL, then return FALSE.
709 @param[in, out] Sha512Context Pointer to the SHA-512 context.
710 @param[out] HashValue Pointer to a buffer that receives the SHA-512 digest
713 @retval TRUE SHA-512 digest computation succeeded.
714 @retval FALSE SHA-512 digest computation failed.
720 IN OUT VOID
*Sha512Context
,
725 Computes the SHA-512 message digest of a input data buffer.
727 This function performs the SHA-512 message digest of a given data buffer, and places
728 the digest value into the specified memory.
730 If this interface is not supported, then return FALSE.
732 @param[in] Data Pointer to the buffer containing the data to be hashed.
733 @param[in] DataSize Size of Data buffer in bytes.
734 @param[out] HashValue Pointer to a buffer that receives the SHA-512 digest
737 @retval TRUE SHA-512 digest computation succeeded.
738 @retval FALSE SHA-512 digest computation failed.
739 @retval FALSE This interface is not supported.
751 Retrieves the size, in bytes, of the context buffer required for SM3 hash operations.
753 @return The size, in bytes, of the context buffer required for SM3 hash operations.
763 Initializes user-supplied memory pointed by Sm3Context as SM3 hash context for
766 If Sm3Context is NULL, then return FALSE.
768 @param[out] Sm3Context Pointer to SM3 context being initialized.
770 @retval TRUE SM3 context initialization succeeded.
771 @retval FALSE SM3 context initialization failed.
781 Makes a copy of an existing SM3 context.
783 If Sm3Context is NULL, then return FALSE.
784 If NewSm3Context is NULL, then return FALSE.
785 If this interface is not supported, then return FALSE.
787 @param[in] Sm3Context Pointer to SM3 context being copied.
788 @param[out] NewSm3Context Pointer to new SM3 context.
790 @retval TRUE SM3 context copy succeeded.
791 @retval FALSE SM3 context copy failed.
792 @retval FALSE This interface is not supported.
798 IN CONST VOID
*Sm3Context
,
799 OUT VOID
*NewSm3Context
803 Digests the input data and updates SM3 context.
805 This function performs SM3 digest on a data buffer of the specified size.
806 It can be called multiple times to compute the digest of long or discontinuous data streams.
807 SM3 context should be already correctly initialized by Sm3Init(), and should not be finalized
808 by Sm3Final(). Behavior with invalid context is undefined.
810 If Sm3Context is NULL, then return FALSE.
812 @param[in, out] Sm3Context Pointer to the SM3 context.
813 @param[in] Data Pointer to the buffer containing the data to be hashed.
814 @param[in] DataSize Size of Data buffer in bytes.
816 @retval TRUE SM3 data digest succeeded.
817 @retval FALSE SM3 data digest failed.
823 IN OUT VOID
*Sm3Context
,
829 Completes computation of the SM3 digest value.
831 This function completes SM3 hash computation and retrieves the digest value into
832 the specified memory. After this function has been called, the SM3 context cannot
834 SM3 context should be already correctly initialized by Sm3Init(), and should not be
835 finalized by Sm3Final(). Behavior with invalid SM3 context is undefined.
837 If Sm3Context is NULL, then return FALSE.
838 If HashValue is NULL, then return FALSE.
840 @param[in, out] Sm3Context Pointer to the SM3 context.
841 @param[out] HashValue Pointer to a buffer that receives the SM3 digest
844 @retval TRUE SM3 digest computation succeeded.
845 @retval FALSE SM3 digest computation failed.
851 IN OUT VOID
*Sm3Context
,
856 Computes the SM3 message digest of a input data buffer.
858 This function performs the SM3 message digest of a given data buffer, and places
859 the digest value into the specified memory.
861 If this interface is not supported, then return FALSE.
863 @param[in] Data Pointer to the buffer containing the data to be hashed.
864 @param[in] DataSize Size of Data buffer in bytes.
865 @param[out] HashValue Pointer to a buffer that receives the SM3 digest
868 @retval TRUE SM3 digest computation succeeded.
869 @retval FALSE SM3 digest computation failed.
870 @retval FALSE This interface is not supported.
881 //=====================================================================================
882 // MAC (Message Authentication Code) Primitive
883 //=====================================================================================
886 Allocates and initializes one HMAC_CTX context for subsequent HMAC-SHA256 use.
888 @return Pointer to the HMAC_CTX context that has been initialized.
889 If the allocations fails, HmacSha256New() returns NULL.
899 Release the specified HMAC_CTX context.
901 @param[in] HmacSha256Ctx Pointer to the HMAC_CTX context to be released.
907 IN VOID
*HmacSha256Ctx
911 Set user-supplied key for subsequent use. It must be done before any
912 calling to HmacSha256Update().
914 If HmacSha256Context is NULL, then return FALSE.
915 If this interface is not supported, then return FALSE.
917 @param[out] HmacSha256Context Pointer to HMAC-SHA256 context.
918 @param[in] Key Pointer to the user-supplied key.
919 @param[in] KeySize Key size in bytes.
921 @retval TRUE The Key is set successfully.
922 @retval FALSE The Key is set unsuccessfully.
923 @retval FALSE This interface is not supported.
929 OUT VOID
*HmacSha256Context
,
935 Makes a copy of an existing HMAC-SHA256 context.
937 If HmacSha256Context is NULL, then return FALSE.
938 If NewHmacSha256Context is NULL, then return FALSE.
939 If this interface is not supported, then return FALSE.
941 @param[in] HmacSha256Context Pointer to HMAC-SHA256 context being copied.
942 @param[out] NewHmacSha256Context Pointer to new HMAC-SHA256 context.
944 @retval TRUE HMAC-SHA256 context copy succeeded.
945 @retval FALSE HMAC-SHA256 context copy failed.
946 @retval FALSE This interface is not supported.
951 HmacSha256Duplicate (
952 IN CONST VOID
*HmacSha256Context
,
953 OUT VOID
*NewHmacSha256Context
957 Digests the input data and updates HMAC-SHA256 context.
959 This function performs HMAC-SHA256 digest on a data buffer of the specified size.
960 It can be called multiple times to compute the digest of long or discontinuous data streams.
961 HMAC-SHA256 context should be initialized by HmacSha256New(), and should not be finalized
962 by HmacSha256Final(). Behavior with invalid context is undefined.
964 If HmacSha256Context is NULL, then return FALSE.
965 If this interface is not supported, then return FALSE.
967 @param[in, out] HmacSha256Context Pointer to the HMAC-SHA256 context.
968 @param[in] Data Pointer to the buffer containing the data to be digested.
969 @param[in] DataSize Size of Data buffer in bytes.
971 @retval TRUE HMAC-SHA256 data digest succeeded.
972 @retval FALSE HMAC-SHA256 data digest failed.
973 @retval FALSE This interface is not supported.
979 IN OUT VOID
*HmacSha256Context
,
985 Completes computation of the HMAC-SHA256 digest value.
987 This function completes HMAC-SHA256 hash computation and retrieves the digest value into
988 the specified memory. After this function has been called, the HMAC-SHA256 context cannot
990 HMAC-SHA256 context should be initialized by HmacSha256New(), and should not be finalized
991 by HmacSha256Final(). Behavior with invalid HMAC-SHA256 context is undefined.
993 If HmacSha256Context is NULL, then return FALSE.
994 If HmacValue is NULL, then return FALSE.
995 If this interface is not supported, then return FALSE.
997 @param[in, out] HmacSha256Context Pointer to the HMAC-SHA256 context.
998 @param[out] HmacValue Pointer to a buffer that receives the HMAC-SHA256 digest
1001 @retval TRUE HMAC-SHA256 digest computation succeeded.
1002 @retval FALSE HMAC-SHA256 digest computation failed.
1003 @retval FALSE This interface is not supported.
1009 IN OUT VOID
*HmacSha256Context
,
1010 OUT UINT8
*HmacValue
1013 //=====================================================================================
1014 // Symmetric Cryptography Primitive
1015 //=====================================================================================
1018 Retrieves the size, in bytes, of the context buffer required for AES operations.
1020 If this interface is not supported, then return zero.
1022 @return The size, in bytes, of the context buffer required for AES operations.
1023 @retval 0 This interface is not supported.
1033 Initializes user-supplied memory as AES context for subsequent use.
1035 This function initializes user-supplied memory pointed by AesContext as AES context.
1036 In addition, it sets up all AES key materials for subsequent encryption and decryption
1038 There are 3 options for key length, 128 bits, 192 bits, and 256 bits.
1040 If AesContext is NULL, then return FALSE.
1041 If Key is NULL, then return FALSE.
1042 If KeyLength is not valid, then return FALSE.
1043 If this interface is not supported, then return FALSE.
1045 @param[out] AesContext Pointer to AES context being initialized.
1046 @param[in] Key Pointer to the user-supplied AES key.
1047 @param[in] KeyLength Length of AES key in bits.
1049 @retval TRUE AES context initialization succeeded.
1050 @retval FALSE AES context initialization failed.
1051 @retval FALSE This interface is not supported.
1057 OUT VOID
*AesContext
,
1058 IN CONST UINT8
*Key
,
1063 Performs AES encryption on a data buffer of the specified size in CBC mode.
1065 This function performs AES encryption on data buffer pointed by Input, of specified
1066 size of InputSize, in CBC mode.
1067 InputSize must be multiple of block size (16 bytes). This function does not perform
1068 padding. Caller must perform padding, if necessary, to ensure valid input data size.
1069 Initialization vector should be one block size (16 bytes).
1070 AesContext should be already correctly initialized by AesInit(). Behavior with
1071 invalid AES context is undefined.
1073 If AesContext is NULL, then return FALSE.
1074 If Input is NULL, then return FALSE.
1075 If InputSize is not multiple of block size (16 bytes), then return FALSE.
1076 If Ivec is NULL, then return FALSE.
1077 If Output is NULL, then return FALSE.
1078 If this interface is not supported, then return FALSE.
1080 @param[in] AesContext Pointer to the AES context.
1081 @param[in] Input Pointer to the buffer containing the data to be encrypted.
1082 @param[in] InputSize Size of the Input buffer in bytes.
1083 @param[in] Ivec Pointer to initialization vector.
1084 @param[out] Output Pointer to a buffer that receives the AES encryption output.
1086 @retval TRUE AES encryption succeeded.
1087 @retval FALSE AES encryption failed.
1088 @retval FALSE This interface is not supported.
1094 IN VOID
*AesContext
,
1095 IN CONST UINT8
*Input
,
1097 IN CONST UINT8
*Ivec
,
1102 Performs AES decryption on a data buffer of the specified size in CBC mode.
1104 This function performs AES decryption on data buffer pointed by Input, of specified
1105 size of InputSize, in CBC mode.
1106 InputSize must be multiple of block size (16 bytes). This function does not perform
1107 padding. Caller must perform padding, if necessary, to ensure valid input data size.
1108 Initialization vector should be one block size (16 bytes).
1109 AesContext should be already correctly initialized by AesInit(). Behavior with
1110 invalid AES context is undefined.
1112 If AesContext is NULL, then return FALSE.
1113 If Input is NULL, then return FALSE.
1114 If InputSize is not multiple of block size (16 bytes), then return FALSE.
1115 If Ivec is NULL, then return FALSE.
1116 If Output is NULL, then return FALSE.
1117 If this interface is not supported, then return FALSE.
1119 @param[in] AesContext Pointer to the AES context.
1120 @param[in] Input Pointer to the buffer containing the data to be encrypted.
1121 @param[in] InputSize Size of the Input buffer in bytes.
1122 @param[in] Ivec Pointer to initialization vector.
1123 @param[out] Output Pointer to a buffer that receives the AES encryption output.
1125 @retval TRUE AES decryption succeeded.
1126 @retval FALSE AES decryption failed.
1127 @retval FALSE This interface is not supported.
1133 IN VOID
*AesContext
,
1134 IN CONST UINT8
*Input
,
1136 IN CONST UINT8
*Ivec
,
1140 //=====================================================================================
1141 // Asymmetric Cryptography Primitive
1142 //=====================================================================================
1145 Allocates and initializes one RSA context for subsequent use.
1147 @return Pointer to the RSA context that has been initialized.
1148 If the allocations fails, RsaNew() returns NULL.
1158 Release the specified RSA context.
1160 If RsaContext is NULL, then return FALSE.
1162 @param[in] RsaContext Pointer to the RSA context to be released.
1172 Sets the tag-designated key component into the established RSA context.
1174 This function sets the tag-designated RSA key component into the established
1175 RSA context from the user-specified non-negative integer (octet string format
1176 represented in RSA PKCS#1).
1177 If BigNumber is NULL, then the specified key component in RSA context is cleared.
1179 If RsaContext is NULL, then return FALSE.
1181 @param[in, out] RsaContext Pointer to RSA context being set.
1182 @param[in] KeyTag Tag of RSA key component being set.
1183 @param[in] BigNumber Pointer to octet integer buffer.
1184 If NULL, then the specified key component in RSA
1186 @param[in] BnSize Size of big number buffer in bytes.
1187 If BigNumber is NULL, then it is ignored.
1189 @retval TRUE RSA key component was set successfully.
1190 @retval FALSE Invalid RSA key component tag.
1196 IN OUT VOID
*RsaContext
,
1197 IN RSA_KEY_TAG KeyTag
,
1198 IN CONST UINT8
*BigNumber
,
1203 Gets the tag-designated RSA key component from the established RSA context.
1205 This function retrieves the tag-designated RSA key component from the
1206 established RSA context as a non-negative integer (octet string format
1207 represented in RSA PKCS#1).
1208 If specified key component has not been set or has been cleared, then returned
1210 If the BigNumber buffer is too small to hold the contents of the key, FALSE
1211 is returned and BnSize is set to the required buffer size to obtain the key.
1213 If RsaContext is NULL, then return FALSE.
1214 If BnSize is NULL, then return FALSE.
1215 If BnSize is large enough but BigNumber is NULL, then return FALSE.
1216 If this interface is not supported, then return FALSE.
1218 @param[in, out] RsaContext Pointer to RSA context being set.
1219 @param[in] KeyTag Tag of RSA key component being set.
1220 @param[out] BigNumber Pointer to octet integer buffer.
1221 @param[in, out] BnSize On input, the size of big number buffer in bytes.
1222 On output, the size of data returned in big number buffer in bytes.
1224 @retval TRUE RSA key component was retrieved successfully.
1225 @retval FALSE Invalid RSA key component tag.
1226 @retval FALSE BnSize is too small.
1227 @retval FALSE This interface is not supported.
1233 IN OUT VOID
*RsaContext
,
1234 IN RSA_KEY_TAG KeyTag
,
1235 OUT UINT8
*BigNumber
,
1236 IN OUT UINTN
*BnSize
1240 Generates RSA key components.
1242 This function generates RSA key components. It takes RSA public exponent E and
1243 length in bits of RSA modulus N as input, and generates all key components.
1244 If PublicExponent is NULL, the default RSA public exponent (0x10001) will be used.
1246 Before this function can be invoked, pseudorandom number generator must be correctly
1247 initialized by RandomSeed().
1249 If RsaContext is NULL, then return FALSE.
1250 If this interface is not supported, then return FALSE.
1252 @param[in, out] RsaContext Pointer to RSA context being set.
1253 @param[in] ModulusLength Length of RSA modulus N in bits.
1254 @param[in] PublicExponent Pointer to RSA public exponent.
1255 @param[in] PublicExponentSize Size of RSA public exponent buffer in bytes.
1257 @retval TRUE RSA key component was generated successfully.
1258 @retval FALSE Invalid RSA key component tag.
1259 @retval FALSE This interface is not supported.
1265 IN OUT VOID
*RsaContext
,
1266 IN UINTN ModulusLength
,
1267 IN CONST UINT8
*PublicExponent
,
1268 IN UINTN PublicExponentSize
1272 Validates key components of RSA context.
1273 NOTE: This function performs integrity checks on all the RSA key material, so
1274 the RSA key structure must contain all the private key data.
1276 This function validates key components of RSA context in following aspects:
1277 - Whether p is a prime
1278 - Whether q is a prime
1280 - Whether d*e = 1 mod lcm(p-1,q-1)
1282 If RsaContext is NULL, then return FALSE.
1283 If this interface is not supported, then return FALSE.
1285 @param[in] RsaContext Pointer to RSA context to check.
1287 @retval TRUE RSA key components are valid.
1288 @retval FALSE RSA key components are not valid.
1289 @retval FALSE This interface is not supported.
1299 Carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme.
1301 This function carries out the RSA-SSA signature generation with EMSA-PKCS1-v1_5 encoding scheme defined in
1303 If the Signature buffer is too small to hold the contents of signature, FALSE
1304 is returned and SigSize is set to the required buffer size to obtain the signature.
1306 If RsaContext is NULL, then return FALSE.
1307 If MessageHash is NULL, then return FALSE.
1308 If HashSize is not equal to the size of MD5, SHA-1 or SHA-256 digest, then return FALSE.
1309 If SigSize is large enough but Signature is NULL, then return FALSE.
1310 If this interface is not supported, then return FALSE.
1312 @param[in] RsaContext Pointer to RSA context for signature generation.
1313 @param[in] MessageHash Pointer to octet message hash to be signed.
1314 @param[in] HashSize Size of the message hash in bytes.
1315 @param[out] Signature Pointer to buffer to receive RSA PKCS1-v1_5 signature.
1316 @param[in, out] SigSize On input, the size of Signature buffer in bytes.
1317 On output, the size of data returned in Signature buffer in bytes.
1319 @retval TRUE Signature successfully generated in PKCS1-v1_5.
1320 @retval FALSE Signature generation failed.
1321 @retval FALSE SigSize is too small.
1322 @retval FALSE This interface is not supported.
1328 IN VOID
*RsaContext
,
1329 IN CONST UINT8
*MessageHash
,
1331 OUT UINT8
*Signature
,
1332 IN OUT UINTN
*SigSize
1336 Verifies the RSA-SSA signature with EMSA-PKCS1-v1_5 encoding scheme defined in
1339 If RsaContext is NULL, then return FALSE.
1340 If MessageHash is NULL, then return FALSE.
1341 If Signature is NULL, then return FALSE.
1342 If HashSize is not equal to the size of MD5, SHA-1, SHA-256 digest, then return FALSE.
1344 @param[in] RsaContext Pointer to RSA context for signature verification.
1345 @param[in] MessageHash Pointer to octet message hash to be checked.
1346 @param[in] HashSize Size of the message hash in bytes.
1347 @param[in] Signature Pointer to RSA PKCS1-v1_5 signature to be verified.
1348 @param[in] SigSize Size of signature in bytes.
1350 @retval TRUE Valid signature encoded in PKCS1-v1_5.
1351 @retval FALSE Invalid signature or invalid RSA context.
1357 IN VOID
*RsaContext
,
1358 IN CONST UINT8
*MessageHash
,
1360 IN CONST UINT8
*Signature
,
1365 Retrieve the RSA Private Key from the password-protected PEM key data.
1367 If PemData is NULL, then return FALSE.
1368 If RsaContext is NULL, then return FALSE.
1369 If this interface is not supported, then return FALSE.
1371 @param[in] PemData Pointer to the PEM-encoded key data to be retrieved.
1372 @param[in] PemSize Size of the PEM key data in bytes.
1373 @param[in] Password NULL-terminated passphrase used for encrypted PEM key data.
1374 @param[out] RsaContext Pointer to new-generated RSA context which contain the retrieved
1375 RSA private key component. Use RsaFree() function to free the
1378 @retval TRUE RSA Private Key was retrieved successfully.
1379 @retval FALSE Invalid PEM key data or incorrect password.
1380 @retval FALSE This interface is not supported.
1385 RsaGetPrivateKeyFromPem (
1386 IN CONST UINT8
*PemData
,
1388 IN CONST CHAR8
*Password
,
1389 OUT VOID
**RsaContext
1393 Retrieve the RSA Public Key from one DER-encoded X509 certificate.
1395 If Cert is NULL, then return FALSE.
1396 If RsaContext is NULL, then return FALSE.
1397 If this interface is not supported, then return FALSE.
1399 @param[in] Cert Pointer to the DER-encoded X509 certificate.
1400 @param[in] CertSize Size of the X509 certificate in bytes.
1401 @param[out] RsaContext Pointer to new-generated RSA context which contain the retrieved
1402 RSA public key component. Use RsaFree() function to free the
1405 @retval TRUE RSA Public Key was retrieved successfully.
1406 @retval FALSE Fail to retrieve RSA public key from X509 certificate.
1407 @retval FALSE This interface is not supported.
1412 RsaGetPublicKeyFromX509 (
1413 IN CONST UINT8
*Cert
,
1415 OUT VOID
**RsaContext
1419 Retrieve the subject bytes from one X.509 certificate.
1421 If Cert is NULL, then return FALSE.
1422 If SubjectSize is NULL, then return FALSE.
1423 If this interface is not supported, then return FALSE.
1425 @param[in] Cert Pointer to the DER-encoded X509 certificate.
1426 @param[in] CertSize Size of the X509 certificate in bytes.
1427 @param[out] CertSubject Pointer to the retrieved certificate subject bytes.
1428 @param[in, out] SubjectSize The size in bytes of the CertSubject buffer on input,
1429 and the size of buffer returned CertSubject on output.
1431 @retval TRUE The certificate subject retrieved successfully.
1432 @retval FALSE Invalid certificate, or the SubjectSize is too small for the result.
1433 The SubjectSize will be updated with the required size.
1434 @retval FALSE This interface is not supported.
1439 X509GetSubjectName (
1440 IN CONST UINT8
*Cert
,
1442 OUT UINT8
*CertSubject
,
1443 IN OUT UINTN
*SubjectSize
1447 Retrieve the common name (CN) string from one X.509 certificate.
1449 @param[in] Cert Pointer to the DER-encoded X509 certificate.
1450 @param[in] CertSize Size of the X509 certificate in bytes.
1451 @param[out] CommonName Buffer to contain the retrieved certificate common
1452 name string (UTF8). At most CommonNameSize bytes will be
1453 written and the string will be null terminated. May be
1454 NULL in order to determine the size buffer needed.
1455 @param[in,out] CommonNameSize The size in bytes of the CommonName buffer on input,
1456 and the size of buffer returned CommonName on output.
1457 If CommonName is NULL then the amount of space needed
1458 in buffer (including the final null) is returned.
1460 @retval RETURN_SUCCESS The certificate CommonName retrieved successfully.
1461 @retval RETURN_INVALID_PARAMETER If Cert is NULL.
1462 If CommonNameSize is NULL.
1463 If CommonName is not NULL and *CommonNameSize is 0.
1464 If Certificate is invalid.
1465 @retval RETURN_NOT_FOUND If no CommonName entry exists.
1466 @retval RETURN_BUFFER_TOO_SMALL If the CommonName is NULL. The required buffer size
1467 (including the final null) is returned in the
1468 CommonNameSize parameter.
1469 @retval RETURN_UNSUPPORTED The operation is not supported.
1475 IN CONST UINT8
*Cert
,
1477 OUT CHAR8
*CommonName
, OPTIONAL
1478 IN OUT UINTN
*CommonNameSize
1482 Retrieve the organization name (O) string from one X.509 certificate.
1484 @param[in] Cert Pointer to the DER-encoded X509 certificate.
1485 @param[in] CertSize Size of the X509 certificate in bytes.
1486 @param[out] NameBuffer Buffer to contain the retrieved certificate organization
1487 name string. At most NameBufferSize bytes will be
1488 written and the string will be null terminated. May be
1489 NULL in order to determine the size buffer needed.
1490 @param[in,out] NameBufferSize The size in bytes of the Name buffer on input,
1491 and the size of buffer returned Name on output.
1492 If NameBuffer is NULL then the amount of space needed
1493 in buffer (including the final null) is returned.
1495 @retval RETURN_SUCCESS The certificate Organization Name retrieved successfully.
1496 @retval RETURN_INVALID_PARAMETER If Cert is NULL.
1497 If NameBufferSize is NULL.
1498 If NameBuffer is not NULL and *CommonNameSize is 0.
1499 If Certificate is invalid.
1500 @retval RETURN_NOT_FOUND If no Organization Name entry exists.
1501 @retval RETURN_BUFFER_TOO_SMALL If the NameBuffer is NULL. The required buffer size
1502 (including the final null) is returned in the
1503 CommonNameSize parameter.
1504 @retval RETURN_UNSUPPORTED The operation is not supported.
1509 X509GetOrganizationName (
1510 IN CONST UINT8
*Cert
,
1512 OUT CHAR8
*NameBuffer
, OPTIONAL
1513 IN OUT UINTN
*NameBufferSize
1517 Verify one X509 certificate was issued by the trusted CA.
1519 If Cert is NULL, then return FALSE.
1520 If CACert is NULL, then return FALSE.
1521 If this interface is not supported, then return FALSE.
1523 @param[in] Cert Pointer to the DER-encoded X509 certificate to be verified.
1524 @param[in] CertSize Size of the X509 certificate in bytes.
1525 @param[in] CACert Pointer to the DER-encoded trusted CA certificate.
1526 @param[in] CACertSize Size of the CA Certificate in bytes.
1528 @retval TRUE The certificate was issued by the trusted CA.
1529 @retval FALSE Invalid certificate or the certificate was not issued by the given
1531 @retval FALSE This interface is not supported.
1537 IN CONST UINT8
*Cert
,
1539 IN CONST UINT8
*CACert
,
1544 Construct a X509 object from DER-encoded certificate data.
1546 If Cert is NULL, then return FALSE.
1547 If SingleX509Cert is NULL, then return FALSE.
1548 If this interface is not supported, then return FALSE.
1550 @param[in] Cert Pointer to the DER-encoded certificate data.
1551 @param[in] CertSize The size of certificate data in bytes.
1552 @param[out] SingleX509Cert The generated X509 object.
1554 @retval TRUE The X509 object generation succeeded.
1555 @retval FALSE The operation failed.
1556 @retval FALSE This interface is not supported.
1561 X509ConstructCertificate (
1562 IN CONST UINT8
*Cert
,
1564 OUT UINT8
**SingleX509Cert
1568 Construct a X509 stack object from a list of DER-encoded certificate data.
1570 If X509Stack is NULL, then return FALSE.
1571 If this interface is not supported, then return FALSE.
1573 @param[in, out] X509Stack On input, pointer to an existing or NULL X509 stack object.
1574 On output, pointer to the X509 stack object with new
1575 inserted X509 certificate.
1576 @param[in] Args VA_LIST marker for the variable argument list.
1577 A list of DER-encoded single certificate data followed
1578 by certificate size. A NULL terminates the list. The
1579 pairs are the arguments to X509ConstructCertificate().
1581 @retval TRUE The X509 stack construction succeeded.
1582 @retval FALSE The construction operation failed.
1583 @retval FALSE This interface is not supported.
1588 X509ConstructCertificateStackV (
1589 IN OUT UINT8
**X509Stack
,
1594 Construct a X509 stack object from a list of DER-encoded certificate data.
1596 If X509Stack is NULL, then return FALSE.
1597 If this interface is not supported, then return FALSE.
1599 @param[in, out] X509Stack On input, pointer to an existing or NULL X509 stack object.
1600 On output, pointer to the X509 stack object with new
1601 inserted X509 certificate.
1602 @param ... A list of DER-encoded single certificate data followed
1603 by certificate size. A NULL terminates the list. The
1604 pairs are the arguments to X509ConstructCertificate().
1606 @retval TRUE The X509 stack construction succeeded.
1607 @retval FALSE The construction operation failed.
1608 @retval FALSE This interface is not supported.
1613 X509ConstructCertificateStack (
1614 IN OUT UINT8
**X509Stack
,
1619 Release the specified X509 object.
1621 If the interface is not supported, then ASSERT().
1623 @param[in] X509Cert Pointer to the X509 object to be released.
1633 Release the specified X509 stack object.
1635 If the interface is not supported, then ASSERT().
1637 @param[in] X509Stack Pointer to the X509 stack object to be released.
1647 Retrieve the TBSCertificate from one given X.509 certificate.
1649 @param[in] Cert Pointer to the given DER-encoded X509 certificate.
1650 @param[in] CertSize Size of the X509 certificate in bytes.
1651 @param[out] TBSCert DER-Encoded To-Be-Signed certificate.
1652 @param[out] TBSCertSize Size of the TBS certificate in bytes.
1654 If Cert is NULL, then return FALSE.
1655 If TBSCert is NULL, then return FALSE.
1656 If TBSCertSize is NULL, then return FALSE.
1657 If this interface is not supported, then return FALSE.
1659 @retval TRUE The TBSCertificate was retrieved successfully.
1660 @retval FALSE Invalid X.509 certificate.
1666 IN CONST UINT8
*Cert
,
1668 OUT UINT8
**TBSCert
,
1669 OUT UINTN
*TBSCertSize
1673 Derives a key from a password using a salt and iteration count, based on PKCS#5 v2.0
1674 password based encryption key derivation function PBKDF2, as specified in RFC 2898.
1676 If Password or Salt or OutKey is NULL, then return FALSE.
1677 If the hash algorithm could not be determined, then return FALSE.
1678 If this interface is not supported, then return FALSE.
1680 @param[in] PasswordLength Length of input password in bytes.
1681 @param[in] Password Pointer to the array for the password.
1682 @param[in] SaltLength Size of the Salt in bytes.
1683 @param[in] Salt Pointer to the Salt.
1684 @param[in] IterationCount Number of iterations to perform. Its value should be
1685 greater than or equal to 1.
1686 @param[in] DigestSize Size of the message digest to be used (eg. SHA256_DIGEST_SIZE).
1687 NOTE: DigestSize will be used to determine the hash algorithm.
1688 Only SHA1_DIGEST_SIZE or SHA256_DIGEST_SIZE is supported.
1689 @param[in] KeyLength Size of the derived key buffer in bytes.
1690 @param[out] OutKey Pointer to the output derived key buffer.
1692 @retval TRUE A key was derived successfully.
1693 @retval FALSE One of the pointers was NULL or one of the sizes was too large.
1694 @retval FALSE The hash algorithm could not be determined from the digest size.
1695 @retval FALSE The key derivation operation failed.
1696 @retval FALSE This interface is not supported.
1702 IN UINTN PasswordLength
,
1703 IN CONST CHAR8
*Password
,
1704 IN UINTN SaltLength
,
1705 IN CONST UINT8
*Salt
,
1706 IN UINTN IterationCount
,
1707 IN UINTN DigestSize
,
1713 Encrypts a blob using PKCS1v2 (RSAES-OAEP) schema. On success, will return the
1714 encrypted message in a newly allocated buffer.
1716 Things that can cause a failure include:
1717 - X509 key size does not match any known key size.
1718 - Fail to parse X509 certificate.
1719 - Fail to allocate an intermediate buffer.
1720 - Null pointer provided for a non-optional parameter.
1721 - Data size is too large for the provided key size (max size is a function of key size
1722 and hash digest size).
1724 @param[in] PublicKey A pointer to the DER-encoded X509 certificate that
1725 will be used to encrypt the data.
1726 @param[in] PublicKeySize Size of the X509 cert buffer.
1727 @param[in] InData Data to be encrypted.
1728 @param[in] InDataSize Size of the data buffer.
1729 @param[in] PrngSeed [Optional] If provided, a pointer to a random seed buffer
1730 to be used when initializing the PRNG. NULL otherwise.
1731 @param[in] PrngSeedSize [Optional] If provided, size of the random seed buffer.
1733 @param[out] EncryptedData Pointer to an allocated buffer containing the encrypted
1735 @param[out] EncryptedDataSize Size of the encrypted message buffer.
1737 @retval TRUE Encryption was successful.
1738 @retval FALSE Encryption failed.
1744 IN CONST UINT8
*PublicKey
,
1745 IN UINTN PublicKeySize
,
1747 IN UINTN InDataSize
,
1748 IN CONST UINT8
*PrngSeed
, OPTIONAL
1749 IN UINTN PrngSeedSize
, OPTIONAL
1750 OUT UINT8
**EncryptedData
,
1751 OUT UINTN
*EncryptedDataSize
1755 The 3rd parameter of Pkcs7GetSigners will return all embedded
1756 X.509 certificate in one given PKCS7 signature. The format is:
1758 // UINT8 CertNumber;
1759 // UINT32 Cert1Length;
1761 // UINT32 Cert2Length;
1764 // UINT32 CertnLength;
1768 The two following C-structure are used for parsing CertStack more clearly.
1773 UINT32 CertDataLength
; // The length in bytes of X.509 certificate.
1774 UINT8 CertDataBuffer
[0]; // The X.509 certificate content (DER).
1778 UINT8 CertNumber
; // Number of X.509 certificate.
1779 //EFI_CERT_DATA CertArray[]; // An array of X.509 certificate.
1785 Get the signer's certificates from PKCS#7 signed data as described in "PKCS #7:
1786 Cryptographic Message Syntax Standard". The input signed data could be wrapped
1787 in a ContentInfo structure.
1789 If P7Data, CertStack, StackLength, TrustedCert or CertLength is NULL, then
1790 return FALSE. If P7Length overflow, then return FALSE.
1791 If this interface is not supported, then return FALSE.
1793 @param[in] P7Data Pointer to the PKCS#7 message to verify.
1794 @param[in] P7Length Length of the PKCS#7 message in bytes.
1795 @param[out] CertStack Pointer to Signer's certificates retrieved from P7Data.
1796 It's caller's responsibility to free the buffer with
1798 This data structure is EFI_CERT_STACK type.
1799 @param[out] StackLength Length of signer's certificates in bytes.
1800 @param[out] TrustedCert Pointer to a trusted certificate from Signer's certificates.
1801 It's caller's responsibility to free the buffer with
1803 @param[out] CertLength Length of the trusted certificate in bytes.
1805 @retval TRUE The operation is finished successfully.
1806 @retval FALSE Error occurs during the operation.
1807 @retval FALSE This interface is not supported.
1813 IN CONST UINT8
*P7Data
,
1815 OUT UINT8
**CertStack
,
1816 OUT UINTN
*StackLength
,
1817 OUT UINT8
**TrustedCert
,
1818 OUT UINTN
*CertLength
1822 Wrap function to use free() to free allocated memory for certificates.
1824 If this interface is not supported, then ASSERT().
1826 @param[in] Certs Pointer to the certificates to be freed.
1836 Retrieves all embedded certificates from PKCS#7 signed data as described in "PKCS #7:
1837 Cryptographic Message Syntax Standard", and outputs two certificate lists chained and
1838 unchained to the signer's certificates.
1839 The input signed data could be wrapped in a ContentInfo structure.
1841 @param[in] P7Data Pointer to the PKCS#7 message.
1842 @param[in] P7Length Length of the PKCS#7 message in bytes.
1843 @param[out] SignerChainCerts Pointer to the certificates list chained to signer's
1844 certificate. It's caller's responsibility to free the buffer
1845 with Pkcs7FreeSigners().
1846 This data structure is EFI_CERT_STACK type.
1847 @param[out] ChainLength Length of the chained certificates list buffer in bytes.
1848 @param[out] UnchainCerts Pointer to the unchained certificates lists. It's caller's
1849 responsibility to free the buffer with Pkcs7FreeSigners().
1850 This data structure is EFI_CERT_STACK type.
1851 @param[out] UnchainLength Length of the unchained certificates list buffer in bytes.
1853 @retval TRUE The operation is finished successfully.
1854 @retval FALSE Error occurs during the operation.
1859 Pkcs7GetCertificatesList (
1860 IN CONST UINT8
*P7Data
,
1862 OUT UINT8
**SignerChainCerts
,
1863 OUT UINTN
*ChainLength
,
1864 OUT UINT8
**UnchainCerts
,
1865 OUT UINTN
*UnchainLength
1869 Creates a PKCS#7 signedData as described in "PKCS #7: Cryptographic Message
1870 Syntax Standard, version 1.5". This interface is only intended to be used for
1871 application to perform PKCS#7 functionality validation.
1873 If this interface is not supported, then return FALSE.
1875 @param[in] PrivateKey Pointer to the PEM-formatted private key data for
1877 @param[in] PrivateKeySize Size of the PEM private key data in bytes.
1878 @param[in] KeyPassword NULL-terminated passphrase used for encrypted PEM
1880 @param[in] InData Pointer to the content to be signed.
1881 @param[in] InDataSize Size of InData in bytes.
1882 @param[in] SignCert Pointer to signer's DER-encoded certificate to sign with.
1883 @param[in] OtherCerts Pointer to an optional additional set of certificates to
1884 include in the PKCS#7 signedData (e.g. any intermediate
1886 @param[out] SignedData Pointer to output PKCS#7 signedData. It's caller's
1887 responsibility to free the buffer with FreePool().
1888 @param[out] SignedDataSize Size of SignedData in bytes.
1890 @retval TRUE PKCS#7 data signing succeeded.
1891 @retval FALSE PKCS#7 data signing failed.
1892 @retval FALSE This interface is not supported.
1898 IN CONST UINT8
*PrivateKey
,
1899 IN UINTN PrivateKeySize
,
1900 IN CONST UINT8
*KeyPassword
,
1902 IN UINTN InDataSize
,
1904 IN UINT8
*OtherCerts OPTIONAL
,
1905 OUT UINT8
**SignedData
,
1906 OUT UINTN
*SignedDataSize
1910 Verifies the validity of a PKCS#7 signed data as described in "PKCS #7:
1911 Cryptographic Message Syntax Standard". The input signed data could be wrapped
1912 in a ContentInfo structure.
1914 If P7Data, TrustedCert or InData is NULL, then return FALSE.
1915 If P7Length, CertLength or DataLength overflow, then return FALSE.
1916 If this interface is not supported, then return FALSE.
1918 @param[in] P7Data Pointer to the PKCS#7 message to verify.
1919 @param[in] P7Length Length of the PKCS#7 message in bytes.
1920 @param[in] TrustedCert Pointer to a trusted/root certificate encoded in DER, which
1921 is used for certificate chain verification.
1922 @param[in] CertLength Length of the trusted certificate in bytes.
1923 @param[in] InData Pointer to the content to be verified.
1924 @param[in] DataLength Length of InData in bytes.
1926 @retval TRUE The specified PKCS#7 signed data is valid.
1927 @retval FALSE Invalid PKCS#7 signed data.
1928 @retval FALSE This interface is not supported.
1934 IN CONST UINT8
*P7Data
,
1936 IN CONST UINT8
*TrustedCert
,
1937 IN UINTN CertLength
,
1938 IN CONST UINT8
*InData
,
1943 This function receives a PKCS7 formatted signature, and then verifies that
1944 the specified Enhanced or Extended Key Usages (EKU's) are present in the end-entity
1945 leaf signing certificate.
1946 Note that this function does not validate the certificate chain.
1948 Applications for custom EKU's are quite flexible. For example, a policy EKU
1949 may be present in an Issuing Certificate Authority (CA), and any sub-ordinate
1950 certificate issued might also contain this EKU, thus constraining the
1951 sub-ordinate certificate. Other applications might allow a certificate
1952 embedded in a device to specify that other Object Identifiers (OIDs) are
1953 present which contains binary data specifying custom capabilities that
1954 the device is able to do.
1956 @param[in] Pkcs7Signature The PKCS#7 signed information content block. An array
1957 containing the content block with both the signature,
1958 the signer's certificate, and any necessary intermediate
1960 @param[in] Pkcs7SignatureSize Number of bytes in Pkcs7Signature.
1961 @param[in] RequiredEKUs Array of null-terminated strings listing OIDs of
1962 required EKUs that must be present in the signature.
1963 @param[in] RequiredEKUsSize Number of elements in the RequiredEKUs string array.
1964 @param[in] RequireAllPresent If this is TRUE, then all of the specified EKU's
1965 must be present in the leaf signer. If it is
1966 FALSE, then we will succeed if we find any
1967 of the specified EKU's.
1969 @retval EFI_SUCCESS The required EKUs were found in the signature.
1970 @retval EFI_INVALID_PARAMETER A parameter was invalid.
1971 @retval EFI_NOT_FOUND One or more EKU's were not found in the signature.
1976 VerifyEKUsInPkcs7Signature (
1977 IN CONST UINT8
*Pkcs7Signature
,
1978 IN CONST UINT32 SignatureSize
,
1979 IN CONST CHAR8
*RequiredEKUs
[],
1980 IN CONST UINT32 RequiredEKUsSize
,
1981 IN BOOLEAN RequireAllPresent
1985 Extracts the attached content from a PKCS#7 signed data if existed. The input signed
1986 data could be wrapped in a ContentInfo structure.
1988 If P7Data, Content, or ContentSize is NULL, then return FALSE. If P7Length overflow,
1989 then return FALSE. If the P7Data is not correctly formatted, then return FALSE.
1991 Caution: This function may receive untrusted input. So this function will do
1992 basic check for PKCS#7 data structure.
1994 @param[in] P7Data Pointer to the PKCS#7 signed data to process.
1995 @param[in] P7Length Length of the PKCS#7 signed data in bytes.
1996 @param[out] Content Pointer to the extracted content from the PKCS#7 signedData.
1997 It's caller's responsibility to free the buffer with FreePool().
1998 @param[out] ContentSize The size of the extracted content in bytes.
2000 @retval TRUE The P7Data was correctly formatted for processing.
2001 @retval FALSE The P7Data was not correctly formatted for processing.
2006 Pkcs7GetAttachedContent (
2007 IN CONST UINT8
*P7Data
,
2010 OUT UINTN
*ContentSize
2014 Verifies the validity of a PE/COFF Authenticode Signature as described in "Windows
2015 Authenticode Portable Executable Signature Format".
2017 If AuthData is NULL, then return FALSE.
2018 If ImageHash is NULL, then return FALSE.
2019 If this interface is not supported, then return FALSE.
2021 @param[in] AuthData Pointer to the Authenticode Signature retrieved from signed
2022 PE/COFF image to be verified.
2023 @param[in] DataSize Size of the Authenticode Signature in bytes.
2024 @param[in] TrustedCert Pointer to a trusted/root certificate encoded in DER, which
2025 is used for certificate chain verification.
2026 @param[in] CertSize Size of the trusted certificate in bytes.
2027 @param[in] ImageHash Pointer to the original image file hash value. The procedure
2028 for calculating the image hash value is described in Authenticode
2030 @param[in] HashSize Size of Image hash value in bytes.
2032 @retval TRUE The specified Authenticode Signature is valid.
2033 @retval FALSE Invalid Authenticode Signature.
2034 @retval FALSE This interface is not supported.
2039 AuthenticodeVerify (
2040 IN CONST UINT8
*AuthData
,
2042 IN CONST UINT8
*TrustedCert
,
2044 IN CONST UINT8
*ImageHash
,
2049 Verifies the validity of a RFC3161 Timestamp CounterSignature embedded in PE/COFF Authenticode
2052 If AuthData is NULL, then return FALSE.
2053 If this interface is not supported, then return FALSE.
2055 @param[in] AuthData Pointer to the Authenticode Signature retrieved from signed
2056 PE/COFF image to be verified.
2057 @param[in] DataSize Size of the Authenticode Signature in bytes.
2058 @param[in] TsaCert Pointer to a trusted/root TSA certificate encoded in DER, which
2059 is used for TSA certificate chain verification.
2060 @param[in] CertSize Size of the trusted certificate in bytes.
2061 @param[out] SigningTime Return the time of timestamp generation time if the timestamp
2064 @retval TRUE The specified Authenticode includes a valid RFC3161 Timestamp CounterSignature.
2065 @retval FALSE No valid RFC3161 Timestamp CounterSignature in the specified Authenticode data.
2070 ImageTimestampVerify (
2071 IN CONST UINT8
*AuthData
,
2073 IN CONST UINT8
*TsaCert
,
2075 OUT EFI_TIME
*SigningTime
2078 //=====================================================================================
2079 // DH Key Exchange Primitive
2080 //=====================================================================================
2083 Allocates and Initializes one Diffie-Hellman Context for subsequent use.
2085 @return Pointer to the Diffie-Hellman Context that has been initialized.
2086 If the allocations fails, DhNew() returns NULL.
2087 If the interface is not supported, DhNew() returns NULL.
2097 Release the specified DH context.
2099 If the interface is not supported, then ASSERT().
2101 @param[in] DhContext Pointer to the DH context to be released.
2111 Generates DH parameter.
2113 Given generator g, and length of prime number p in bits, this function generates p,
2114 and sets DH context according to value of g and p.
2116 Before this function can be invoked, pseudorandom number generator must be correctly
2117 initialized by RandomSeed().
2119 If DhContext is NULL, then return FALSE.
2120 If Prime is NULL, then return FALSE.
2121 If this interface is not supported, then return FALSE.
2123 @param[in, out] DhContext Pointer to the DH context.
2124 @param[in] Generator Value of generator.
2125 @param[in] PrimeLength Length in bits of prime to be generated.
2126 @param[out] Prime Pointer to the buffer to receive the generated prime number.
2128 @retval TRUE DH parameter generation succeeded.
2129 @retval FALSE Value of Generator is not supported.
2130 @retval FALSE PRNG fails to generate random prime number with PrimeLength.
2131 @retval FALSE This interface is not supported.
2136 DhGenerateParameter (
2137 IN OUT VOID
*DhContext
,
2139 IN UINTN PrimeLength
,
2144 Sets generator and prime parameters for DH.
2146 Given generator g, and prime number p, this function and sets DH
2147 context accordingly.
2149 If DhContext is NULL, then return FALSE.
2150 If Prime is NULL, then return FALSE.
2151 If this interface is not supported, then return FALSE.
2153 @param[in, out] DhContext Pointer to the DH context.
2154 @param[in] Generator Value of generator.
2155 @param[in] PrimeLength Length in bits of prime to be generated.
2156 @param[in] Prime Pointer to the prime number.
2158 @retval TRUE DH parameter setting succeeded.
2159 @retval FALSE Value of Generator is not supported.
2160 @retval FALSE Value of Generator is not suitable for the Prime.
2161 @retval FALSE Value of Prime is not a prime number.
2162 @retval FALSE Value of Prime is not a safe prime number.
2163 @retval FALSE This interface is not supported.
2169 IN OUT VOID
*DhContext
,
2171 IN UINTN PrimeLength
,
2172 IN CONST UINT8
*Prime
2176 Generates DH public key.
2178 This function generates random secret exponent, and computes the public key, which is
2179 returned via parameter PublicKey and PublicKeySize. DH context is updated accordingly.
2180 If the PublicKey buffer is too small to hold the public key, FALSE is returned and
2181 PublicKeySize is set to the required buffer size to obtain the public key.
2183 If DhContext is NULL, then return FALSE.
2184 If PublicKeySize is NULL, then return FALSE.
2185 If PublicKeySize is large enough but PublicKey is NULL, then return FALSE.
2186 If this interface is not supported, then return FALSE.
2188 @param[in, out] DhContext Pointer to the DH context.
2189 @param[out] PublicKey Pointer to the buffer to receive generated public key.
2190 @param[in, out] PublicKeySize On input, the size of PublicKey buffer in bytes.
2191 On output, the size of data returned in PublicKey buffer in bytes.
2193 @retval TRUE DH public key generation succeeded.
2194 @retval FALSE DH public key generation failed.
2195 @retval FALSE PublicKeySize is not large enough.
2196 @retval FALSE This interface is not supported.
2202 IN OUT VOID
*DhContext
,
2203 OUT UINT8
*PublicKey
,
2204 IN OUT UINTN
*PublicKeySize
2208 Computes exchanged common key.
2210 Given peer's public key, this function computes the exchanged common key, based on its own
2211 context including value of prime modulus and random secret exponent.
2213 If DhContext is NULL, then return FALSE.
2214 If PeerPublicKey is NULL, then return FALSE.
2215 If KeySize is NULL, then return FALSE.
2216 If Key is NULL, then return FALSE.
2217 If KeySize is not large enough, then return FALSE.
2218 If this interface is not supported, then return FALSE.
2220 @param[in, out] DhContext Pointer to the DH context.
2221 @param[in] PeerPublicKey Pointer to the peer's public key.
2222 @param[in] PeerPublicKeySize Size of peer's public key in bytes.
2223 @param[out] Key Pointer to the buffer to receive generated key.
2224 @param[in, out] KeySize On input, the size of Key buffer in bytes.
2225 On output, the size of data returned in Key buffer in bytes.
2227 @retval TRUE DH exchanged key generation succeeded.
2228 @retval FALSE DH exchanged key generation failed.
2229 @retval FALSE KeySize is not large enough.
2230 @retval FALSE This interface is not supported.
2236 IN OUT VOID
*DhContext
,
2237 IN CONST UINT8
*PeerPublicKey
,
2238 IN UINTN PeerPublicKeySize
,
2240 IN OUT UINTN
*KeySize
2243 //=====================================================================================
2244 // Pseudo-Random Generation Primitive
2245 //=====================================================================================
2248 Sets up the seed value for the pseudorandom number generator.
2250 This function sets up the seed value for the pseudorandom number generator.
2251 If Seed is not NULL, then the seed passed in is used.
2252 If Seed is NULL, then default seed is used.
2253 If this interface is not supported, then return FALSE.
2255 @param[in] Seed Pointer to seed value.
2256 If NULL, default seed is used.
2257 @param[in] SeedSize Size of seed value.
2258 If Seed is NULL, this parameter is ignored.
2260 @retval TRUE Pseudorandom number generator has enough entropy for random generation.
2261 @retval FALSE Pseudorandom number generator does not have enough entropy for random generation.
2262 @retval FALSE This interface is not supported.
2268 IN CONST UINT8
*Seed OPTIONAL
,
2273 Generates a pseudorandom byte stream of the specified size.
2275 If Output is NULL, then return FALSE.
2276 If this interface is not supported, then return FALSE.
2278 @param[out] Output Pointer to buffer to receive random value.
2279 @param[in] Size Size of random bytes to generate.
2281 @retval TRUE Pseudorandom byte stream generated successfully.
2282 @retval FALSE Pseudorandom number generator fails to generate due to lack of entropy.
2283 @retval FALSE This interface is not supported.
2293 //=====================================================================================
2294 // Key Derivation Function Primitive
2295 //=====================================================================================
2298 Derive key data using HMAC-SHA256 based KDF.
2300 @param[in] Key Pointer to the user-supplied key.
2301 @param[in] KeySize Key size in bytes.
2302 @param[in] Salt Pointer to the salt(non-secret) value.
2303 @param[in] SaltSize Salt size in bytes.
2304 @param[in] Info Pointer to the application specific info.
2305 @param[in] InfoSize Info size in bytes.
2306 @param[out] Out Pointer to buffer to receive hkdf value.
2307 @param[in] OutSize Size of hkdf bytes to generate.
2309 @retval TRUE Hkdf generated successfully.
2310 @retval FALSE Hkdf generation failed.
2315 HkdfSha256ExtractAndExpand (
2316 IN CONST UINT8
*Key
,
2318 IN CONST UINT8
*Salt
,
2320 IN CONST UINT8
*Info
,
2326 #endif // __BASE_CRYPT_LIB_H__