primitives (Hash Serials, HMAC, RSA, Diffie-Hellman, etc) for UEFI security\r
functionality enabling.\r
\r
-Copyright (c) 2009 - 2020, Intel Corporation. All rights reserved.<BR>\r
+Copyright (c) 2009 - 2022, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#include <Uefi/UefiBaseType.h>\r
\r
+#define CRYPTO_NID_NULL 0x0000\r
+\r
+// Hash\r
+#define CRYPTO_NID_SHA256 0x0001\r
+#define CRYPTO_NID_SHA384 0x0002\r
+#define CRYPTO_NID_SHA512 0x0003\r
+\r
+// Key Exchange\r
+#define CRYPTO_NID_SECP256R1 0x0204\r
+#define CRYPTO_NID_SECP384R1 0x0205\r
+#define CRYPTO_NID_SECP521R1 0x0206\r
+\r
///\r
/// MD5 digest size in bytes\r
///\r
-#define MD5_DIGEST_SIZE 16\r
+#define MD5_DIGEST_SIZE 16\r
\r
///\r
/// SHA-1 digest size in bytes.\r
///\r
-#define SHA1_DIGEST_SIZE 20\r
+#define SHA1_DIGEST_SIZE 20\r
\r
///\r
/// SHA-256 digest size in bytes\r
///\r
/// SM3 digest size in bytes\r
///\r
-#define SM3_256_DIGEST_SIZE 32\r
+#define SM3_256_DIGEST_SIZE 32\r
\r
///\r
/// TDES block size in bytes\r
///\r
-#define TDES_BLOCK_SIZE 8\r
+#define TDES_BLOCK_SIZE 8\r
\r
///\r
/// AES block size in bytes\r
///\r
-#define AES_BLOCK_SIZE 16\r
+#define AES_BLOCK_SIZE 16\r
\r
///\r
/// RSA Key Tags Definition used in RsaSetKey() function for key component identification.\r
RsaKeyQInv ///< The CRT coefficient (== 1/q mod p)\r
} RSA_KEY_TAG;\r
\r
-//=====================================================================================\r
+// =====================================================================================\r
// One-Way Cryptographic Hash Primitives\r
-//=====================================================================================\r
+// =====================================================================================\r
+\r
+#ifdef ENABLE_MD5_DEPRECATED_INTERFACES\r
\r
-#ifndef DISABLE_MD5_DEPRECATED_INTERFACES\r
/**\r
Retrieves the size, in bytes, of the context buffer required for MD5 hash operations.\r
\r
IN UINTN DataSize,\r
OUT UINT8 *HashValue\r
);\r
+\r
#endif\r
\r
#ifndef DISABLE_SHA1_DEPRECATED_INTERFACES\r
+\r
/**\r
Retrieves the size, in bytes, of the context buffer required for SHA-1 hash operations.\r
\r
IN UINTN DataSize,\r
OUT UINT8 *HashValue\r
);\r
+\r
#endif\r
\r
/**\r
OUT UINT8 *HashValue\r
);\r
\r
+/**\r
+ Parallel hash function ParallelHash256, as defined in NIST's Special Publication 800-185,\r
+ published December 2016.\r
+\r
+ @param[in] Input Pointer to the input message (X).\r
+ @param[in] InputByteLen The number(>0) of input bytes provided for the input data.\r
+ @param[in] BlockSize The size of each block (B).\r
+ @param[out] Output Pointer to the output buffer.\r
+ @param[in] OutputByteLen The desired number of output bytes (L).\r
+ @param[in] Customization Pointer to the customization string (S).\r
+ @param[in] CustomByteLen The length of the customization string in bytes.\r
+\r
+ @retval TRUE ParallelHash256 digest computation succeeded.\r
+ @retval FALSE ParallelHash256 digest computation failed.\r
+ @retval FALSE This interface is not supported.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+ParallelHash256HashAll (\r
+ IN CONST VOID *Input,\r
+ IN UINTN InputByteLen,\r
+ IN UINTN BlockSize,\r
+ OUT VOID *Output,\r
+ IN UINTN OutputByteLen,\r
+ IN CONST VOID *Customization,\r
+ IN UINTN CustomByteLen\r
+ );\r
+\r
/**\r
Retrieves the size, in bytes, of the context buffer required for SM3 hash operations.\r
\r
OUT UINT8 *HashValue\r
);\r
\r
-//=====================================================================================\r
+// =====================================================================================\r
// MAC (Message Authentication Code) Primitive\r
-//=====================================================================================\r
+// =====================================================================================\r
\r
/**\r
Allocates and initializes one HMAC_CTX context for subsequent HMAC-SHA256 use.\r
OUT UINT8 *HmacValue\r
);\r
\r
-//=====================================================================================\r
+/**\r
+ Computes the HMAC-SHA256 digest of a input data buffer.\r
+\r
+ This function performs the HMAC-SHA256 digest of a given data buffer, and places\r
+ the digest value into the specified memory.\r
+\r
+ If this interface is not supported, then return FALSE.\r
+\r
+ @param[in] Data Pointer to the buffer containing the data to be digested.\r
+ @param[in] DataSize Size of Data buffer in bytes.\r
+ @param[in] Key Pointer to the user-supplied key.\r
+ @param[in] KeySize Key size in bytes.\r
+ @param[out] HashValue Pointer to a buffer that receives the HMAC-SHA256 digest\r
+ value (32 bytes).\r
+\r
+ @retval TRUE HMAC-SHA256 digest computation succeeded.\r
+ @retval FALSE HMAC-SHA256 digest computation failed.\r
+ @retval FALSE This interface is not supported.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+HmacSha256All (\r
+ IN CONST VOID *Data,\r
+ IN UINTN DataSize,\r
+ IN CONST UINT8 *Key,\r
+ IN UINTN KeySize,\r
+ OUT UINT8 *HmacValue\r
+ );\r
+\r
+/**\r
+ Allocates and initializes one HMAC_CTX context for subsequent HMAC-SHA384 use.\r
+\r
+ @return Pointer to the HMAC_CTX context that has been initialized.\r
+ If the allocations fails, HmacSha384New() returns NULL.\r
+\r
+**/\r
+VOID *\r
+EFIAPI\r
+HmacSha384New (\r
+ VOID\r
+ );\r
+\r
+/**\r
+ Release the specified HMAC_CTX context.\r
+\r
+ @param[in] HmacSha384Ctx Pointer to the HMAC_CTX context to be released.\r
+\r
+**/\r
+VOID\r
+EFIAPI\r
+HmacSha384Free (\r
+ IN VOID *HmacSha384Ctx\r
+ );\r
+\r
+/**\r
+ Set user-supplied key for subsequent use. It must be done before any\r
+ calling to HmacSha384Update().\r
+\r
+ If HmacSha384Context is NULL, then return FALSE.\r
+ If this interface is not supported, then return FALSE.\r
+\r
+ @param[out] HmacSha384Context Pointer to HMAC-SHA384 context.\r
+ @param[in] Key Pointer to the user-supplied key.\r
+ @param[in] KeySize Key size in bytes.\r
+\r
+ @retval TRUE The Key is set successfully.\r
+ @retval FALSE The Key is set unsuccessfully.\r
+ @retval FALSE This interface is not supported.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+HmacSha384SetKey (\r
+ OUT VOID *HmacSha384Context,\r
+ IN CONST UINT8 *Key,\r
+ IN UINTN KeySize\r
+ );\r
+\r
+/**\r
+ Makes a copy of an existing HMAC-SHA384 context.\r
+\r
+ If HmacSha384Context is NULL, then return FALSE.\r
+ If NewHmacSha384Context is NULL, then return FALSE.\r
+ If this interface is not supported, then return FALSE.\r
+\r
+ @param[in] HmacSha384Context Pointer to HMAC-SHA384 context being copied.\r
+ @param[out] NewHmacSha384Context Pointer to new HMAC-SHA384 context.\r
+\r
+ @retval TRUE HMAC-SHA384 context copy succeeded.\r
+ @retval FALSE HMAC-SHA384 context copy failed.\r
+ @retval FALSE This interface is not supported.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+HmacSha384Duplicate (\r
+ IN CONST VOID *HmacSha384Context,\r
+ OUT VOID *NewHmacSha384Context\r
+ );\r
+\r
+/**\r
+ Digests the input data and updates HMAC-SHA384 context.\r
+\r
+ This function performs HMAC-SHA384 digest on a data buffer of the specified size.\r
+ It can be called multiple times to compute the digest of long or discontinuous data streams.\r
+ HMAC-SHA384 context should be initialized by HmacSha384New(), and should not be finalized\r
+ by HmacSha384Final(). Behavior with invalid context is undefined.\r
+\r
+ If HmacSha384Context is NULL, then return FALSE.\r
+ If this interface is not supported, then return FALSE.\r
+\r
+ @param[in, out] HmacSha384Context Pointer to the HMAC-SHA384 context.\r
+ @param[in] Data Pointer to the buffer containing the data to be digested.\r
+ @param[in] DataSize Size of Data buffer in bytes.\r
+\r
+ @retval TRUE HMAC-SHA384 data digest succeeded.\r
+ @retval FALSE HMAC-SHA384 data digest failed.\r
+ @retval FALSE This interface is not supported.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+HmacSha384Update (\r
+ IN OUT VOID *HmacSha384Context,\r
+ IN CONST VOID *Data,\r
+ IN UINTN DataSize\r
+ );\r
+\r
+/**\r
+ Completes computation of the HMAC-SHA384 digest value.\r
+\r
+ This function completes HMAC-SHA384 hash computation and retrieves the digest value into\r
+ the specified memory. After this function has been called, the HMAC-SHA384 context cannot\r
+ be used again.\r
+ HMAC-SHA384 context should be initialized by HmacSha384New(), and should not be finalized\r
+ by HmacSha384Final(). Behavior with invalid HMAC-SHA384 context is undefined.\r
+\r
+ If HmacSha384Context is NULL, then return FALSE.\r
+ If HmacValue is NULL, then return FALSE.\r
+ If this interface is not supported, then return FALSE.\r
+\r
+ @param[in, out] HmacSha384Context Pointer to the HMAC-SHA384 context.\r
+ @param[out] HmacValue Pointer to a buffer that receives the HMAC-SHA384 digest\r
+ value (48 bytes).\r
+\r
+ @retval TRUE HMAC-SHA384 digest computation succeeded.\r
+ @retval FALSE HMAC-SHA384 digest computation failed.\r
+ @retval FALSE This interface is not supported.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+HmacSha384Final (\r
+ IN OUT VOID *HmacSha384Context,\r
+ OUT UINT8 *HmacValue\r
+ );\r
+\r
+/**\r
+ Computes the HMAC-SHA384 digest of a input data buffer.\r
+\r
+ This function performs the HMAC-SHA384 digest of a given data buffer, and places\r
+ the digest value into the specified memory.\r
+\r
+ If this interface is not supported, then return FALSE.\r
+\r
+ @param[in] Data Pointer to the buffer containing the data to be digested.\r
+ @param[in] DataSize Size of Data buffer in bytes.\r
+ @param[in] Key Pointer to the user-supplied key.\r
+ @param[in] KeySize Key size in bytes.\r
+ @param[out] HashValue Pointer to a buffer that receives the HMAC-SHA384 digest\r
+ value (48 bytes).\r
+\r
+ @retval TRUE HMAC-SHA384 digest computation succeeded.\r
+ @retval FALSE HMAC-SHA384 digest computation failed.\r
+ @retval FALSE This interface is not supported.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+HmacSha384All (\r
+ IN CONST VOID *Data,\r
+ IN UINTN DataSize,\r
+ IN CONST UINT8 *Key,\r
+ IN UINTN KeySize,\r
+ OUT UINT8 *HmacValue\r
+ );\r
+\r
+// =====================================================================================\r
// Symmetric Cryptography Primitive\r
-//=====================================================================================\r
+// =====================================================================================\r
\r
/**\r
Retrieves the size, in bytes, of the context buffer required for AES operations.\r
OUT UINT8 *Output\r
);\r
\r
-//=====================================================================================\r
+// =====================================================================================\r
+// Authenticated Encryption with Associated Data (AEAD) Cryptography Primitive\r
+// =====================================================================================\r
+\r
+/**\r
+ Performs AEAD AES-GCM authenticated encryption on a data buffer and additional authenticated data (AAD).\r
+\r
+ IvSize must be 12, otherwise FALSE is returned.\r
+ KeySize must be 16, 24 or 32, otherwise FALSE is returned.\r
+ TagSize must be 12, 13, 14, 15, 16, otherwise FALSE is returned.\r
+\r
+ @param[in] Key Pointer to the encryption key.\r
+ @param[in] KeySize Size of the encryption key in bytes.\r
+ @param[in] Iv Pointer to the IV value.\r
+ @param[in] IvSize Size of the IV value in bytes.\r
+ @param[in] AData Pointer to the additional authenticated data (AAD).\r
+ @param[in] ADataSize Size of the additional authenticated data (AAD) in bytes.\r
+ @param[in] DataIn Pointer to the input data buffer to be encrypted.\r
+ @param[in] DataInSize Size of the input data buffer in bytes.\r
+ @param[out] TagOut Pointer to a buffer that receives the authentication tag output.\r
+ @param[in] TagSize Size of the authentication tag in bytes.\r
+ @param[out] DataOut Pointer to a buffer that receives the encryption output.\r
+ @param[out] DataOutSize Size of the output data buffer in bytes.\r
+\r
+ @retval TRUE AEAD AES-GCM authenticated encryption succeeded.\r
+ @retval FALSE AEAD AES-GCM authenticated encryption failed.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+AeadAesGcmEncrypt (\r
+ IN CONST UINT8 *Key,\r
+ IN UINTN KeySize,\r
+ IN CONST UINT8 *Iv,\r
+ IN UINTN IvSize,\r
+ IN CONST UINT8 *AData,\r
+ IN UINTN ADataSize,\r
+ IN CONST UINT8 *DataIn,\r
+ IN UINTN DataInSize,\r
+ OUT UINT8 *TagOut,\r
+ IN UINTN TagSize,\r
+ OUT UINT8 *DataOut,\r
+ OUT UINTN *DataOutSize\r
+ );\r
+\r
+/**\r
+ Performs AEAD AES-GCM authenticated decryption on a data buffer and additional authenticated data (AAD).\r
+\r
+ IvSize must be 12, otherwise FALSE is returned.\r
+ KeySize must be 16, 24 or 32, otherwise FALSE is returned.\r
+ TagSize must be 12, 13, 14, 15, 16, otherwise FALSE is returned.\r
+ If additional authenticated data verification fails, FALSE is returned.\r
+\r
+ @param[in] Key Pointer to the encryption key.\r
+ @param[in] KeySize Size of the encryption key in bytes.\r
+ @param[in] Iv Pointer to the IV value.\r
+ @param[in] IvSize Size of the IV value in bytes.\r
+ @param[in] AData Pointer to the additional authenticated data (AAD).\r
+ @param[in] ADataSize Size of the additional authenticated data (AAD) in bytes.\r
+ @param[in] DataIn Pointer to the input data buffer to be decrypted.\r
+ @param[in] DataInSize Size of the input data buffer in bytes.\r
+ @param[in] Tag Pointer to a buffer that contains the authentication tag.\r
+ @param[in] TagSize Size of the authentication tag in bytes.\r
+ @param[out] DataOut Pointer to a buffer that receives the decryption output.\r
+ @param[out] DataOutSize Size of the output data buffer in bytes.\r
+\r
+ @retval TRUE AEAD AES-GCM authenticated decryption succeeded.\r
+ @retval FALSE AEAD AES-GCM authenticated decryption failed.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+AeadAesGcmDecrypt (\r
+ IN CONST UINT8 *Key,\r
+ IN UINTN KeySize,\r
+ IN CONST UINT8 *Iv,\r
+ IN UINTN IvSize,\r
+ IN CONST UINT8 *AData,\r
+ IN UINTN ADataSize,\r
+ IN CONST UINT8 *DataIn,\r
+ IN UINTN DataInSize,\r
+ IN CONST UINT8 *Tag,\r
+ IN UINTN TagSize,\r
+ OUT UINT8 *DataOut,\r
+ OUT UINTN *DataOutSize\r
+ );\r
+\r
+// =====================================================================================\r
// Asymmetric Cryptography Primitive\r
-//=====================================================================================\r
+// =====================================================================================\r
\r
/**\r
Allocates and initializes one RSA context for subsequent use.\r
IN UINTN SigSize\r
);\r
\r
+/**\r
+ Carries out the RSA-SSA signature generation with EMSA-PSS encoding scheme.\r
+\r
+ This function carries out the RSA-SSA signature generation with EMSA-PSS encoding scheme defined in\r
+ RFC 8017.\r
+ Mask generation function is the same as the message digest algorithm.\r
+ If the Signature buffer is too small to hold the contents of signature, FALSE\r
+ is returned and SigSize is set to the required buffer size to obtain the signature.\r
+\r
+ If RsaContext is NULL, then return FALSE.\r
+ If Message is NULL, then return FALSE.\r
+ If MsgSize is zero or > INT_MAX, then return FALSE.\r
+ If DigestLen is NOT 32, 48 or 64, return FALSE.\r
+ If SaltLen is not equal to DigestLen, then return FALSE.\r
+ If SigSize is large enough but Signature is NULL, then return FALSE.\r
+ If this interface is not supported, then return FALSE.\r
+\r
+ @param[in] RsaContext Pointer to RSA context for signature generation.\r
+ @param[in] Message Pointer to octet message to be signed.\r
+ @param[in] MsgSize Size of the message in bytes.\r
+ @param[in] DigestLen Length of the digest in bytes to be used for RSA signature operation.\r
+ @param[in] SaltLen Length of the salt in bytes to be used for PSS encoding.\r
+ @param[out] Signature Pointer to buffer to receive RSA PSS signature.\r
+ @param[in, out] SigSize On input, the size of Signature buffer in bytes.\r
+ On output, the size of data returned in Signature buffer in bytes.\r
+\r
+ @retval TRUE Signature successfully generated in RSASSA-PSS.\r
+ @retval FALSE Signature generation failed.\r
+ @retval FALSE SigSize is too small.\r
+ @retval FALSE This interface is not supported.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+RsaPssSign (\r
+ IN VOID *RsaContext,\r
+ IN CONST UINT8 *Message,\r
+ IN UINTN MsgSize,\r
+ IN UINT16 DigestLen,\r
+ IN UINT16 SaltLen,\r
+ OUT UINT8 *Signature,\r
+ IN OUT UINTN *SigSize\r
+ );\r
+\r
+/**\r
+ Verifies the RSA signature with RSASSA-PSS signature scheme defined in RFC 8017.\r
+ Implementation determines salt length automatically from the signature encoding.\r
+ Mask generation function is the same as the message digest algorithm.\r
+ Salt length should be equal to digest length.\r
+\r
+ @param[in] RsaContext Pointer to RSA context for signature verification.\r
+ @param[in] Message Pointer to octet message to be verified.\r
+ @param[in] MsgSize Size of the message in bytes.\r
+ @param[in] Signature Pointer to RSASSA-PSS signature to be verified.\r
+ @param[in] SigSize Size of signature in bytes.\r
+ @param[in] DigestLen Length of digest for RSA operation.\r
+ @param[in] SaltLen Salt length for PSS encoding.\r
+\r
+ @retval TRUE Valid signature encoded in RSASSA-PSS.\r
+ @retval FALSE Invalid signature or invalid RSA context.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+RsaPssVerify (\r
+ IN VOID *RsaContext,\r
+ IN CONST UINT8 *Message,\r
+ IN UINTN MsgSize,\r
+ IN CONST UINT8 *Signature,\r
+ IN UINTN SigSize,\r
+ IN UINT16 DigestLen,\r
+ IN UINT16 SaltLen\r
+ );\r
+\r
/**\r
Retrieve the RSA Private Key from the password-protected PEM key data.\r
\r
X509GetCommonName (\r
IN CONST UINT8 *Cert,\r
IN UINTN CertSize,\r
- OUT CHAR8 *CommonName, OPTIONAL\r
+ OUT CHAR8 *CommonName OPTIONAL,\r
IN OUT UINTN *CommonNameSize\r
);\r
\r
RETURN_STATUS\r
EFIAPI\r
X509GetOrganizationName (\r
- IN CONST UINT8 *Cert,\r
- IN UINTN CertSize,\r
- OUT CHAR8 *NameBuffer, OPTIONAL\r
- IN OUT UINTN *NameBufferSize\r
+ IN CONST UINT8 *Cert,\r
+ IN UINTN CertSize,\r
+ OUT CHAR8 *NameBuffer OPTIONAL,\r
+ IN OUT UINTN *NameBufferSize\r
);\r
\r
/**\r
IN UINTN PublicKeySize,\r
IN UINT8 *InData,\r
IN UINTN InDataSize,\r
- IN CONST UINT8 *PrngSeed, OPTIONAL\r
- IN UINTN PrngSeedSize, OPTIONAL\r
+ IN CONST UINT8 *PrngSeed OPTIONAL,\r
+ IN UINTN PrngSeedSize OPTIONAL,\r
OUT UINT8 **EncryptedData,\r
OUT UINTN *EncryptedDataSize\r
);\r
} EFI_CERT_DATA;\r
\r
typedef struct {\r
- UINT8 CertNumber; // Number of X.509 certificate.\r
- //EFI_CERT_DATA CertArray[]; // An array of X.509 certificate.\r
+ UINT8 CertNumber; // Number of X.509 certificate.\r
+ // EFI_CERT_DATA CertArray[]; // An array of X.509 certificate.\r
} EFI_CERT_STACK;\r
\r
#pragma pack()\r
VOID\r
EFIAPI\r
Pkcs7FreeSigners (\r
- IN UINT8 *Certs\r
+ IN UINT8 *Certs\r
);\r
\r
/**\r
OUT EFI_TIME *SigningTime\r
);\r
\r
-//=====================================================================================\r
+// =====================================================================================\r
// DH Key Exchange Primitive\r
-//=====================================================================================\r
+// =====================================================================================\r
\r
/**\r
Allocates and Initializes one Diffie-Hellman Context for subsequent use.\r
IN OUT UINTN *KeySize\r
);\r
\r
-//=====================================================================================\r
+// =====================================================================================\r
// Pseudo-Random Generation Primitive\r
-//=====================================================================================\r
+// =====================================================================================\r
\r
/**\r
Sets up the seed value for the pseudorandom number generator.\r
IN UINTN Size\r
);\r
\r
-//=====================================================================================\r
+// =====================================================================================\r
// Key Derivation Function Primitive\r
-//=====================================================================================\r
+// =====================================================================================\r
\r
/**\r
Derive key data using HMAC-SHA256 based KDF.\r
IN UINTN OutSize\r
);\r
\r
+/**\r
+ Derive SHA256 HMAC-based Extract key Derivation Function (HKDF).\r
+\r
+ @param[in] Key Pointer to the user-supplied key.\r
+ @param[in] KeySize key size in bytes.\r
+ @param[in] Salt Pointer to the salt(non-secret) value.\r
+ @param[in] SaltSize salt size in bytes.\r
+ @param[out] PrkOut Pointer to buffer to receive hkdf value.\r
+ @param[in] PrkOutSize size of hkdf bytes to generate.\r
+\r
+ @retval true Hkdf generated successfully.\r
+ @retval false Hkdf generation failed.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+HkdfSha256Extract (\r
+ IN CONST UINT8 *Key,\r
+ IN UINTN KeySize,\r
+ IN CONST UINT8 *Salt,\r
+ IN UINTN SaltSize,\r
+ OUT UINT8 *PrkOut,\r
+ UINTN PrkOutSize\r
+ );\r
+\r
+/**\r
+ Derive SHA256 HMAC-based Expand Key Derivation Function (HKDF).\r
+\r
+ @param[in] Prk Pointer to the user-supplied key.\r
+ @param[in] PrkSize Key size in bytes.\r
+ @param[in] Info Pointer to the application specific info.\r
+ @param[in] InfoSize Info size in bytes.\r
+ @param[out] Out Pointer to buffer to receive hkdf value.\r
+ @param[in] OutSize Size of hkdf bytes to generate.\r
+\r
+ @retval TRUE Hkdf generated successfully.\r
+ @retval FALSE Hkdf generation failed.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+HkdfSha256Expand (\r
+ IN CONST UINT8 *Prk,\r
+ IN UINTN PrkSize,\r
+ IN CONST UINT8 *Info,\r
+ IN UINTN InfoSize,\r
+ OUT UINT8 *Out,\r
+ IN UINTN OutSize\r
+ );\r
+\r
+/**\r
+ Derive SHA384 HMAC-based Extract-and-Expand Key Derivation Function (HKDF).\r
+\r
+ @param[in] Key Pointer to the user-supplied key.\r
+ @param[in] KeySize Key size in bytes.\r
+ @param[in] Salt Pointer to the salt(non-secret) value.\r
+ @param[in] SaltSize Salt size in bytes.\r
+ @param[in] Info Pointer to the application specific info.\r
+ @param[in] InfoSize Info size in bytes.\r
+ @param[out] Out Pointer to buffer to receive hkdf value.\r
+ @param[in] OutSize Size of hkdf bytes to generate.\r
+\r
+ @retval TRUE Hkdf generated successfully.\r
+ @retval FALSE Hkdf generation failed.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+HkdfSha384ExtractAndExpand (\r
+ IN CONST UINT8 *Key,\r
+ IN UINTN KeySize,\r
+ IN CONST UINT8 *Salt,\r
+ IN UINTN SaltSize,\r
+ IN CONST UINT8 *Info,\r
+ IN UINTN InfoSize,\r
+ OUT UINT8 *Out,\r
+ IN UINTN OutSize\r
+ );\r
+\r
+/**\r
+ Derive SHA384 HMAC-based Extract key Derivation Function (HKDF).\r
+\r
+ @param[in] Key Pointer to the user-supplied key.\r
+ @param[in] KeySize key size in bytes.\r
+ @param[in] Salt Pointer to the salt(non-secret) value.\r
+ @param[in] SaltSize salt size in bytes.\r
+ @param[out] PrkOut Pointer to buffer to receive hkdf value.\r
+ @param[in] PrkOutSize size of hkdf bytes to generate.\r
+\r
+ @retval true Hkdf generated successfully.\r
+ @retval false Hkdf generation failed.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+HkdfSha384Extract (\r
+ IN CONST UINT8 *Key,\r
+ IN UINTN KeySize,\r
+ IN CONST UINT8 *Salt,\r
+ IN UINTN SaltSize,\r
+ OUT UINT8 *PrkOut,\r
+ UINTN PrkOutSize\r
+ );\r
+\r
+/**\r
+ Derive SHA384 HMAC-based Expand Key Derivation Function (HKDF).\r
+\r
+ @param[in] Prk Pointer to the user-supplied key.\r
+ @param[in] PrkSize Key size in bytes.\r
+ @param[in] Info Pointer to the application specific info.\r
+ @param[in] InfoSize Info size in bytes.\r
+ @param[out] Out Pointer to buffer to receive hkdf value.\r
+ @param[in] OutSize Size of hkdf bytes to generate.\r
+\r
+ @retval TRUE Hkdf generated successfully.\r
+ @retval FALSE Hkdf generation failed.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+HkdfSha384Expand (\r
+ IN CONST UINT8 *Prk,\r
+ IN UINTN PrkSize,\r
+ IN CONST UINT8 *Info,\r
+ IN UINTN InfoSize,\r
+ OUT UINT8 *Out,\r
+ IN UINTN OutSize\r
+ );\r
+\r
+// =====================================================================================\r
+// Big number primitives\r
+// =====================================================================================\r
+\r
+/**\r
+ Allocate new Big Number.\r
+\r
+ @retval New BigNum opaque structure or NULL on failure.\r
+**/\r
+VOID *\r
+EFIAPI\r
+BigNumInit (\r
+ VOID\r
+ );\r
+\r
+/**\r
+ Allocate new Big Number and assign the provided value to it.\r
+\r
+ @param[in] Buf Big endian encoded buffer.\r
+ @param[in] Len Buffer length.\r
+\r
+ @retval New BigNum opaque structure or NULL on failure.\r
+**/\r
+VOID *\r
+EFIAPI\r
+BigNumFromBin (\r
+ IN CONST UINT8 *Buf,\r
+ IN UINTN Len\r
+ );\r
+\r
+/**\r
+ Convert the absolute value of Bn into big-endian form and store it at Buf.\r
+ The Buf array should have at least BigNumBytes() in it.\r
+\r
+ @param[in] Bn Big number to convert.\r
+ @param[out] Buf Output buffer.\r
+\r
+ @retval The length of the big-endian number placed at Buf or -1 on error.\r
+**/\r
+INTN\r
+EFIAPI\r
+BigNumToBin (\r
+ IN CONST VOID *Bn,\r
+ OUT UINT8 *Buf\r
+ );\r
+\r
+/**\r
+ Free the Big Number.\r
+\r
+ @param[in] Bn Big number to free.\r
+ @param[in] Clear TRUE if the buffer should be cleared.\r
+**/\r
+VOID\r
+EFIAPI\r
+BigNumFree (\r
+ IN VOID *Bn,\r
+ IN BOOLEAN Clear\r
+ );\r
+\r
+/**\r
+ Calculate the sum of two Big Numbers.\r
+ Please note, all "out" Big number arguments should be properly initialized\r
+ by calling to BigNumInit() or BigNumFromBin() functions.\r
+\r
+ @param[in] BnA Big number.\r
+ @param[in] BnB Big number.\r
+ @param[out] BnRes The result of BnA + BnB.\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+BigNumAdd (\r
+ IN CONST VOID *BnA,\r
+ IN CONST VOID *BnB,\r
+ OUT VOID *BnRes\r
+ );\r
+\r
+/**\r
+ Subtract two Big Numbers.\r
+ Please note, all "out" Big number arguments should be properly initialized\r
+ by calling to BigNumInit() or BigNumFromBin() functions.\r
+\r
+ @param[in] BnA Big number.\r
+ @param[in] BnB Big number.\r
+ @param[out] BnRes The result of BnA - BnB.\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+BigNumSub (\r
+ IN CONST VOID *BnA,\r
+ IN CONST VOID *BnB,\r
+ OUT VOID *BnRes\r
+ );\r
+\r
+/**\r
+ Calculate remainder: BnRes = BnA % BnB.\r
+ Please note, all "out" Big number arguments should be properly initialized\r
+ by calling to BigNumInit() or BigNumFromBin() functions.\r
+\r
+ @param[in] BnA Big number.\r
+ @param[in] BnB Big number.\r
+ @param[out] BnRes The result of BnA % BnB.\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+BigNumMod (\r
+ IN CONST VOID *BnA,\r
+ IN CONST VOID *BnB,\r
+ OUT VOID *BnRes\r
+ );\r
+\r
+/**\r
+ Compute BnA to the BnP-th power modulo BnM.\r
+ Please note, all "out" Big number arguments should be properly initialized\r
+ by calling to BigNumInit() or BigNumFromBin() functions.\r
+\r
+ @param[in] BnA Big number.\r
+ @param[in] BnP Big number (power).\r
+ @param[in] BnM Big number (modulo).\r
+ @param[out] BnRes The result of (BnA ^ BnP) % BnM.\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+BigNumExpMod (\r
+ IN CONST VOID *BnA,\r
+ IN CONST VOID *BnP,\r
+ IN CONST VOID *BnM,\r
+ OUT VOID *BnRes\r
+ );\r
+\r
+/**\r
+ Compute BnA inverse modulo BnM.\r
+ Please note, all "out" Big number arguments should be properly initialized\r
+ by calling to BigNumInit() or BigNumFromBin() functions.\r
+\r
+ @param[in] BnA Big number.\r
+ @param[in] BnM Big number (modulo).\r
+ @param[out] BnRes The result, such that (BnA * BnRes) % BnM == 1.\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+BigNumInverseMod (\r
+ IN CONST VOID *BnA,\r
+ IN CONST VOID *BnM,\r
+ OUT VOID *BnRes\r
+ );\r
+\r
+/**\r
+ Divide two Big Numbers.\r
+ Please note, all "out" Big number arguments should be properly initialized\r
+ by calling to BigNumInit() or BigNumFromBin() functions.\r
+\r
+ @param[in] BnA Big number.\r
+ @param[in] BnB Big number.\r
+ @param[out] BnRes The result, such that BnA / BnB.\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+BigNumDiv (\r
+ IN CONST VOID *BnA,\r
+ IN CONST VOID *BnB,\r
+ OUT VOID *BnRes\r
+ );\r
+\r
+/**\r
+ Multiply two Big Numbers modulo BnM.\r
+ Please note, all "out" Big number arguments should be properly initialized\r
+ by calling to BigNumInit() or BigNumFromBin() functions.\r
+\r
+ @param[in] BnA Big number.\r
+ @param[in] BnB Big number.\r
+ @param[in] BnM Big number (modulo).\r
+ @param[out] BnRes The result, such that (BnA * BnB) % BnM.\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+BigNumMulMod (\r
+ IN CONST VOID *BnA,\r
+ IN CONST VOID *BnB,\r
+ IN CONST VOID *BnM,\r
+ OUT VOID *BnRes\r
+ );\r
+\r
+/**\r
+ Compare two Big Numbers.\r
+\r
+ @param[in] BnA Big number.\r
+ @param[in] BnB Big number.\r
+\r
+ @retval 0 BnA == BnB.\r
+ @retval 1 BnA > BnB.\r
+ @retval -1 BnA < BnB.\r
+**/\r
+INTN\r
+EFIAPI\r
+BigNumCmp (\r
+ IN CONST VOID *BnA,\r
+ IN CONST VOID *BnB\r
+ );\r
+\r
+/**\r
+ Get number of bits in Bn.\r
+\r
+ @param[in] Bn Big number.\r
+\r
+ @retval Number of bits.\r
+**/\r
+\r
+UINTN\r
+EFIAPI\r
+BigNumBits (\r
+ IN CONST VOID *Bn\r
+ );\r
+\r
+/**\r
+ Get number of bytes in Bn.\r
+\r
+ @param[in] Bn Big number.\r
+\r
+ @retval Number of bytes.\r
+**/\r
+UINTN\r
+EFIAPI\r
+BigNumBytes (\r
+ IN CONST VOID *Bn\r
+ );\r
+\r
+/**\r
+ Checks if Big Number equals to the given Num.\r
+\r
+ @param[in] Bn Big number.\r
+ @param[in] Num Number.\r
+\r
+ @retval TRUE iff Bn == Num.\r
+ @retval FALSE otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+BigNumIsWord (\r
+ IN CONST VOID *Bn,\r
+ IN UINTN Num\r
+ );\r
+\r
+/**\r
+ Checks if Big Number is odd.\r
+\r
+ @param[in] Bn Big number.\r
+\r
+ @retval TRUE Bn is odd (Bn % 2 == 1).\r
+ @retval FALSE otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+BigNumIsOdd (\r
+ IN CONST VOID *Bn\r
+ );\r
+\r
+/**\r
+ Copy Big number.\r
+\r
+ @param[out] BnDst Destination.\r
+ @param[in] BnSrc Source.\r
+\r
+ @retval BnDst on success.\r
+ @retval NULL otherwise.\r
+**/\r
+VOID *\r
+EFIAPI\r
+BigNumCopy (\r
+ OUT VOID *BnDst,\r
+ IN CONST VOID *BnSrc\r
+ );\r
+\r
+/**\r
+ Get constant Big number with value of "1".\r
+ This may be used to save expensive allocations.\r
+\r
+ @retval Big Number with value of 1.\r
+**/\r
+CONST VOID *\r
+EFIAPI\r
+BigNumValueOne (\r
+ VOID\r
+ );\r
+\r
+/**\r
+ Shift right Big Number.\r
+ Please note, all "out" Big number arguments should be properly initialized\r
+ by calling to BigNumInit() or BigNumFromBin() functions.\r
+\r
+ @param[in] Bn Big number.\r
+ @param[in] N Number of bits to shift.\r
+ @param[out] BnRes The result.\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+BigNumRShift (\r
+ IN CONST VOID *Bn,\r
+ IN UINTN N,\r
+ OUT VOID *BnRes\r
+ );\r
+\r
+/**\r
+ Mark Big Number for constant time computations.\r
+ This function should be called before any constant time computations are\r
+ performed on the given Big number.\r
+\r
+ @param[in] Bn Big number.\r
+**/\r
+VOID\r
+EFIAPI\r
+BigNumConstTime (\r
+ IN VOID *Bn\r
+ );\r
+\r
+/**\r
+ Calculate square modulo.\r
+ Please note, all "out" Big number arguments should be properly initialized\r
+ by calling to BigNumInit() or BigNumFromBin() functions.\r
+\r
+ @param[in] BnA Big number.\r
+ @param[in] BnM Big number (modulo).\r
+ @param[out] BnRes The result, such that (BnA ^ 2) % BnM.\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+BigNumSqrMod (\r
+ IN CONST VOID *BnA,\r
+ IN CONST VOID *BnM,\r
+ OUT VOID *BnRes\r
+ );\r
+\r
+/**\r
+ Create new Big Number computation context. This is an opaque structure\r
+ which should be passed to any function that requires it. The BN context is\r
+ needed to optimize calculations and expensive allocations.\r
+\r
+ @retval Big Number context struct or NULL on failure.\r
+**/\r
+VOID *\r
+EFIAPI\r
+BigNumNewContext (\r
+ VOID\r
+ );\r
+\r
+/**\r
+ Free Big Number context that was allocated with BigNumNewContext().\r
+\r
+ @param[in] BnCtx Big number context to free.\r
+**/\r
+VOID\r
+EFIAPI\r
+BigNumContextFree (\r
+ IN VOID *BnCtx\r
+ );\r
+\r
+/**\r
+ Set Big Number to a given value.\r
+\r
+ @param[in] Bn Big number to set.\r
+ @param[in] Val Value to set.\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+BigNumSetUint (\r
+ IN VOID *Bn,\r
+ IN UINTN Val\r
+ );\r
+\r
+/**\r
+ Add two Big Numbers modulo BnM.\r
+\r
+ @param[in] BnA Big number.\r
+ @param[in] BnB Big number.\r
+ @param[in] BnM Big number (modulo).\r
+ @param[out] BnRes The result, such that (BnA + BnB) % BnM.\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+BigNumAddMod (\r
+ IN CONST VOID *BnA,\r
+ IN CONST VOID *BnB,\r
+ IN CONST VOID *BnM,\r
+ OUT VOID *BnRes\r
+ );\r
+\r
+// =====================================================================================\r
+// Basic Elliptic Curve Primitives\r
+// =====================================================================================\r
+\r
+/**\r
+ Initialize new opaque EcGroup object. This object represents an EC curve and\r
+ and is used for calculation within this group. This object should be freed\r
+ using EcGroupFree() function.\r
+\r
+ @param[in] CryptoNid Identifying number for the ECC curve (Defined in\r
+ BaseCryptLib.h).\r
+\r
+ @retval EcGroup object On success.\r
+ @retval NULL On failure.\r
+**/\r
+VOID *\r
+EFIAPI\r
+EcGroupInit (\r
+ IN UINTN CryptoNid\r
+ );\r
+\r
+/**\r
+ Get EC curve parameters. While elliptic curve equation is Y^2 mod P = (X^3 + AX + B) Mod P.\r
+ This function will set the provided Big Number objects to the corresponding\r
+ values. The caller needs to make sure all the "out" BigNumber parameters\r
+ are properly initialized.\r
+\r
+ @param[in] EcGroup EC group object.\r
+ @param[out] BnPrime Group prime number.\r
+ @param[out] BnA A coefficient.\r
+ @param[out] BnB B coefficient.\r
+ @param[in] BnCtx BN context.\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+EcGroupGetCurve (\r
+ IN CONST VOID *EcGroup,\r
+ OUT VOID *BnPrime,\r
+ OUT VOID *BnA,\r
+ OUT VOID *BnB,\r
+ IN VOID *BnCtx\r
+ );\r
+\r
+/**\r
+ Get EC group order.\r
+ This function will set the provided Big Number object to the corresponding\r
+ value. The caller needs to make sure that the "out" BigNumber parameter\r
+ is properly initialized.\r
+\r
+ @param[in] EcGroup EC group object.\r
+ @param[out] BnOrder Group prime number.\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+EcGroupGetOrder (\r
+ IN VOID *EcGroup,\r
+ OUT VOID *BnOrder\r
+ );\r
+\r
+/**\r
+ Free previously allocated EC group object using EcGroupInit().\r
+\r
+ @param[in] EcGroup EC group object to free.\r
+**/\r
+VOID\r
+EFIAPI\r
+EcGroupFree (\r
+ IN VOID *EcGroup\r
+ );\r
+\r
+/**\r
+ Initialize new opaque EC Point object. This object represents an EC point\r
+ within the given EC group (curve).\r
+\r
+ @param[in] EC Group, properly initialized using EcGroupInit().\r
+\r
+ @retval EC Point object On success.\r
+ @retval NULL On failure.\r
+**/\r
+VOID *\r
+EFIAPI\r
+EcPointInit (\r
+ IN CONST VOID *EcGroup\r
+ );\r
+\r
+/**\r
+ Free previously allocated EC Point object using EcPointInit().\r
+\r
+ @param[in] EcPoint EC Point to free.\r
+ @param[in] Clear TRUE iff the memory should be cleared.\r
+**/\r
+VOID\r
+EFIAPI\r
+EcPointDeInit (\r
+ IN VOID *EcPoint,\r
+ IN BOOLEAN Clear\r
+ );\r
+\r
+/**\r
+ Get EC point affine (x,y) coordinates.\r
+ This function will set the provided Big Number objects to the corresponding\r
+ values. The caller needs to make sure all the "out" BigNumber parameters\r
+ are properly initialized.\r
+\r
+ @param[in] EcGroup EC group object.\r
+ @param[in] EcPoint EC point object.\r
+ @param[out] BnX X coordinate.\r
+ @param[out] BnY Y coordinate.\r
+ @param[in] BnCtx BN context, created with BigNumNewContext().\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+EcPointGetAffineCoordinates (\r
+ IN CONST VOID *EcGroup,\r
+ IN CONST VOID *EcPoint,\r
+ OUT VOID *BnX,\r
+ OUT VOID *BnY,\r
+ IN VOID *BnCtx\r
+ );\r
+\r
+/**\r
+ Set EC point affine (x,y) coordinates.\r
+\r
+ @param[in] EcGroup EC group object.\r
+ @param[in] EcPoint EC point object.\r
+ @param[in] BnX X coordinate.\r
+ @param[in] BnY Y coordinate.\r
+ @param[in] BnCtx BN context, created with BigNumNewContext().\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+EcPointSetAffineCoordinates (\r
+ IN CONST VOID *EcGroup,\r
+ IN VOID *EcPoint,\r
+ IN CONST VOID *BnX,\r
+ IN CONST VOID *BnY,\r
+ IN VOID *BnCtx\r
+ );\r
+\r
+/**\r
+ EC Point addition. EcPointResult = EcPointA + EcPointB.\r
+\r
+ @param[in] EcGroup EC group object.\r
+ @param[out] EcPointResult EC point to hold the result. The point should\r
+ be properly initialized.\r
+ @param[in] EcPointA EC Point.\r
+ @param[in] EcPointB EC Point.\r
+ @param[in] BnCtx BN context, created with BigNumNewContext().\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+EcPointAdd (\r
+ IN CONST VOID *EcGroup,\r
+ OUT VOID *EcPointResult,\r
+ IN CONST VOID *EcPointA,\r
+ IN CONST VOID *EcPointB,\r
+ IN VOID *BnCtx\r
+ );\r
+\r
+/**\r
+ Variable EC point multiplication. EcPointResult = EcPoint * BnPScalar.\r
+\r
+ @param[in] EcGroup EC group object.\r
+ @param[out] EcPointResult EC point to hold the result. The point should\r
+ be properly initialized.\r
+ @param[in] EcPoint EC Point.\r
+ @param[in] BnPScalar P Scalar.\r
+ @param[in] BnCtx BN context, created with BigNumNewContext().\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+EcPointMul (\r
+ IN CONST VOID *EcGroup,\r
+ OUT VOID *EcPointResult,\r
+ IN CONST VOID *EcPoint,\r
+ IN CONST VOID *BnPScalar,\r
+ IN VOID *BnCtx\r
+ );\r
+\r
+/**\r
+ Calculate the inverse of the supplied EC point.\r
+\r
+ @param[in] EcGroup EC group object.\r
+ @param[in,out] EcPoint EC point to invert.\r
+ @param[in] BnCtx BN context, created with BigNumNewContext().\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+EcPointInvert (\r
+ IN CONST VOID *EcGroup,\r
+ IN OUT VOID *EcPoint,\r
+ IN VOID *BnCtx\r
+ );\r
+\r
+/**\r
+ Check if the supplied point is on EC curve.\r
+\r
+ @param[in] EcGroup EC group object.\r
+ @param[in] EcPoint EC point to check.\r
+ @param[in] BnCtx BN context, created with BigNumNewContext().\r
+\r
+ @retval TRUE On curve.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+EcPointIsOnCurve (\r
+ IN CONST VOID *EcGroup,\r
+ IN CONST VOID *EcPoint,\r
+ IN VOID *BnCtx\r
+ );\r
+\r
+/**\r
+ Check if the supplied point is at infinity.\r
+\r
+ @param[in] EcGroup EC group object.\r
+ @param[in] EcPoint EC point to check.\r
+\r
+ @retval TRUE At infinity.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+EcPointIsAtInfinity (\r
+ IN CONST VOID *EcGroup,\r
+ IN CONST VOID *EcPoint\r
+ );\r
+\r
+/**\r
+ Check if EC points are equal.\r
+\r
+ @param[in] EcGroup EC group object.\r
+ @param[in] EcPointA EC point A.\r
+ @param[in] EcPointB EC point B.\r
+ @param[in] BnCtx BN context, created with BigNumNewContext().\r
+\r
+ @retval TRUE A == B.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+EcPointEqual (\r
+ IN CONST VOID *EcGroup,\r
+ IN CONST VOID *EcPointA,\r
+ IN CONST VOID *EcPointB,\r
+ IN VOID *BnCtx\r
+ );\r
+\r
+/**\r
+ Set EC point compressed coordinates. Points can be described in terms of\r
+ their compressed coordinates. For a point (x, y), for any given value for x\r
+ such that the point is on the curve there will only ever be two possible\r
+ values for y. Therefore, a point can be set using this function where BnX is\r
+ the x coordinate and YBit is a value 0 or 1 to identify which of the two\r
+ possible values for y should be used.\r
+\r
+ @param[in] EcGroup EC group object.\r
+ @param[in] EcPoint EC Point.\r
+ @param[in] BnX X coordinate.\r
+ @param[in] YBit 0 or 1 to identify which Y value is used.\r
+ @param[in] BnCtx BN context, created with BigNumNewContext().\r
+\r
+ @retval TRUE On success.\r
+ @retval FALSE Otherwise.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+EcPointSetCompressedCoordinates (\r
+ IN CONST VOID *EcGroup,\r
+ IN VOID *EcPoint,\r
+ IN CONST VOID *BnX,\r
+ IN UINT8 YBit,\r
+ IN VOID *BnCtx\r
+ );\r
+\r
+// =====================================================================================\r
+// Elliptic Curve Diffie Hellman Primitives\r
+// =====================================================================================\r
+\r
+/**\r
+ Allocates and Initializes one Elliptic Curve Context for subsequent use\r
+ with the NID.\r
+\r
+ @param[in] Nid cipher NID\r
+ @return Pointer to the Elliptic Curve Context that has been initialized.\r
+ If the allocations fails, EcNewByNid() returns NULL.\r
+**/\r
+VOID *\r
+EFIAPI\r
+EcNewByNid (\r
+ IN UINTN Nid\r
+ );\r
+\r
+/**\r
+ Release the specified EC context.\r
+\r
+ @param[in] EcContext Pointer to the EC context to be released.\r
+**/\r
+VOID\r
+EFIAPI\r
+EcFree (\r
+ IN VOID *EcContext\r
+ );\r
+\r
+/**\r
+ Generates EC key and returns EC public key (X, Y), Please note, this function uses\r
+ pseudo random number generator. The caller must make sure RandomSeed()\r
+ function was properly called before.\r
+ The Ec context should be correctly initialized by EcNewByNid.\r
+ This function generates random secret, and computes the public key (X, Y), which is\r
+ returned via parameter Public, PublicSize.\r
+ X is the first half of Public with size being PublicSize / 2,\r
+ Y is the second half of Public with size being PublicSize / 2.\r
+ EC context is updated accordingly.\r
+ If the Public buffer is too small to hold the public X, Y, FALSE is returned and\r
+ PublicSize is set to the required buffer size to obtain the public X, Y.\r
+ For P-256, the PublicSize is 64. First 32-byte is X, Second 32-byte is Y.\r
+ For P-384, the PublicSize is 96. First 48-byte is X, Second 48-byte is Y.\r
+ For P-521, the PublicSize is 132. First 66-byte is X, Second 66-byte is Y.\r
+ If EcContext is NULL, then return FALSE.\r
+ If PublicSize is NULL, then return FALSE.\r
+ If PublicSize is large enough but Public is NULL, then return FALSE.\r
+ @param[in, out] EcContext Pointer to the EC context.\r
+ @param[out] PublicKey Pointer to t buffer to receive generated public X,Y.\r
+ @param[in, out] PublicKeySize On input, the size of Public buffer in bytes.\r
+ On output, the size of data returned in Public buffer in bytes.\r
+ @retval TRUE EC public X,Y generation succeeded.\r
+ @retval FALSE EC public X,Y generation failed.\r
+ @retval FALSE PublicKeySize is not large enough.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+EcGenerateKey (\r
+ IN OUT VOID *EcContext,\r
+ OUT UINT8 *PublicKey,\r
+ IN OUT UINTN *PublicKeySize\r
+ );\r
+\r
+/**\r
+ Gets the public key component from the established EC context.\r
+ The Ec context should be correctly initialized by EcNewByNid, and successfully\r
+ generate key pair from EcGenerateKey().\r
+ For P-256, the PublicSize is 64. First 32-byte is X, Second 32-byte is Y.\r
+ For P-384, the PublicSize is 96. First 48-byte is X, Second 48-byte is Y.\r
+ For P-521, the PublicSize is 132. First 66-byte is X, Second 66-byte is Y.\r
+ @param[in, out] EcContext Pointer to EC context being set.\r
+ @param[out] PublicKey Pointer to t buffer to receive generated public X,Y.\r
+ @param[in, out] PublicKeySize On input, the size of Public buffer in bytes.\r
+ On output, the size of data returned in Public buffer in bytes.\r
+ @retval TRUE EC key component was retrieved successfully.\r
+ @retval FALSE Invalid EC key component.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+EcGetPubKey (\r
+ IN OUT VOID *EcContext,\r
+ OUT UINT8 *PublicKey,\r
+ IN OUT UINTN *PublicKeySize\r
+ );\r
+\r
+/**\r
+ Computes exchanged common key.\r
+ Given peer's public key (X, Y), this function computes the exchanged common key,\r
+ based on its own context including value of curve parameter and random secret.\r
+ X is the first half of PeerPublic with size being PeerPublicSize / 2,\r
+ Y is the second half of PeerPublic with size being PeerPublicSize / 2.\r
+ If EcContext is NULL, then return FALSE.\r
+ If PeerPublic is NULL, then return FALSE.\r
+ If PeerPublicSize is 0, then return FALSE.\r
+ If Key is NULL, then return FALSE.\r
+ If KeySize is not large enough, then return FALSE.\r
+ For P-256, the PeerPublicSize is 64. First 32-byte is X, Second 32-byte is Y.\r
+ For P-384, the PeerPublicSize is 96. First 48-byte is X, Second 48-byte is Y.\r
+ For P-521, the PeerPublicSize is 132. First 66-byte is X, Second 66-byte is Y.\r
+ @param[in, out] EcContext Pointer to the EC context.\r
+ @param[in] PeerPublic Pointer to the peer's public X,Y.\r
+ @param[in] PeerPublicSize Size of peer's public X,Y in bytes.\r
+ @param[in] CompressFlag Flag of PeerPublic is compressed or not.\r
+ @param[out] Key Pointer to the buffer to receive generated key.\r
+ @param[in, out] KeySize On input, the size of Key buffer in bytes.\r
+ On output, the size of data returned in Key buffer in bytes.\r
+ @retval TRUE EC exchanged key generation succeeded.\r
+ @retval FALSE EC exchanged key generation failed.\r
+ @retval FALSE KeySize is not large enough.\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+EcDhComputeKey (\r
+ IN OUT VOID *EcContext,\r
+ IN CONST UINT8 *PeerPublic,\r
+ IN UINTN PeerPublicSize,\r
+ IN CONST INT32 *CompressFlag,\r
+ OUT UINT8 *Key,\r
+ IN OUT UINTN *KeySize\r
+ );\r
+\r
+/**\r
+ Retrieve the EC Private Key from the password-protected PEM key data.\r
+\r
+ @param[in] PemData Pointer to the PEM-encoded key data to be retrieved.\r
+ @param[in] PemSize Size of the PEM key data in bytes.\r
+ @param[in] Password NULL-terminated passphrase used for encrypted PEM key data.\r
+ @param[out] EcContext Pointer to new-generated EC DSA context which contain the retrieved\r
+ EC private key component. Use EcFree() function to free the\r
+ resource.\r
+\r
+ If PemData is NULL, then return FALSE.\r
+ If EcContext is NULL, then return FALSE.\r
+\r
+ @retval TRUE EC Private Key was retrieved successfully.\r
+ @retval FALSE Invalid PEM key data or incorrect password.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+EcGetPrivateKeyFromPem (\r
+ IN CONST UINT8 *PemData,\r
+ IN UINTN PemSize,\r
+ IN CONST CHAR8 *Password,\r
+ OUT VOID **EcContext\r
+ );\r
+\r
+/**\r
+ Retrieve the EC Public Key from one DER-encoded X509 certificate.\r
+\r
+ @param[in] Cert Pointer to the DER-encoded X509 certificate.\r
+ @param[in] CertSize Size of the X509 certificate in bytes.\r
+ @param[out] EcContext Pointer to new-generated EC DSA context which contain the retrieved\r
+ EC public key component. Use EcFree() function to free the\r
+ resource.\r
+\r
+ If Cert is NULL, then return FALSE.\r
+ If EcContext is NULL, then return FALSE.\r
+\r
+ @retval TRUE EC Public Key was retrieved successfully.\r
+ @retval FALSE Fail to retrieve EC public key from X509 certificate.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+EcGetPublicKeyFromX509 (\r
+ IN CONST UINT8 *Cert,\r
+ IN UINTN CertSize,\r
+ OUT VOID **EcContext\r
+ );\r
+\r
+/**\r
+ Carries out the EC-DSA signature.\r
+\r
+ This function carries out the EC-DSA signature.\r
+ If the Signature buffer is too small to hold the contents of signature, FALSE\r
+ is returned and SigSize is set to the required buffer size to obtain the signature.\r
+\r
+ If EcContext is NULL, then return FALSE.\r
+ If MessageHash is NULL, then return FALSE.\r
+ If HashSize need match the HashNid. HashNid could be SHA256, SHA384, SHA512, SHA3_256, SHA3_384, SHA3_512.\r
+ If SigSize is large enough but Signature is NULL, then return FALSE.\r
+\r
+ For P-256, the SigSize is 64. First 32-byte is R, Second 32-byte is S.\r
+ For P-384, the SigSize is 96. First 48-byte is R, Second 48-byte is S.\r
+ For P-521, the SigSize is 132. First 66-byte is R, Second 66-byte is S.\r
+\r
+ @param[in] EcContext Pointer to EC context for signature generation.\r
+ @param[in] HashNid hash NID\r
+ @param[in] MessageHash Pointer to octet message hash to be signed.\r
+ @param[in] HashSize Size of the message hash in bytes.\r
+ @param[out] Signature Pointer to buffer to receive EC-DSA signature.\r
+ @param[in, out] SigSize On input, the size of Signature buffer in bytes.\r
+ On output, the size of data returned in Signature buffer in bytes.\r
+\r
+ @retval TRUE Signature successfully generated in EC-DSA.\r
+ @retval FALSE Signature generation failed.\r
+ @retval FALSE SigSize is too small.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+EcDsaSign (\r
+ IN VOID *EcContext,\r
+ IN UINTN HashNid,\r
+ IN CONST UINT8 *MessageHash,\r
+ IN UINTN HashSize,\r
+ OUT UINT8 *Signature,\r
+ IN OUT UINTN *SigSize\r
+ );\r
+\r
+/**\r
+ Verifies the EC-DSA signature.\r
+\r
+ If EcContext is NULL, then return FALSE.\r
+ If MessageHash is NULL, then return FALSE.\r
+ If Signature is NULL, then return FALSE.\r
+ If HashSize need match the HashNid. HashNid could be SHA256, SHA384, SHA512, SHA3_256, SHA3_384, SHA3_512.\r
+\r
+ For P-256, the SigSize is 64. First 32-byte is R, Second 32-byte is S.\r
+ For P-384, the SigSize is 96. First 48-byte is R, Second 48-byte is S.\r
+ For P-521, the SigSize is 132. First 66-byte is R, Second 66-byte is S.\r
+\r
+ @param[in] EcContext Pointer to EC context for signature verification.\r
+ @param[in] HashNid hash NID\r
+ @param[in] MessageHash Pointer to octet message hash to be checked.\r
+ @param[in] HashSize Size of the message hash in bytes.\r
+ @param[in] Signature Pointer to EC-DSA signature to be verified.\r
+ @param[in] SigSize Size of signature in bytes.\r
+\r
+ @retval TRUE Valid signature encoded in EC-DSA.\r
+ @retval FALSE Invalid signature or invalid EC context.\r
+\r
+**/\r
+BOOLEAN\r
+EFIAPI\r
+EcDsaVerify (\r
+ IN VOID *EcContext,\r
+ IN UINTN HashNid,\r
+ IN CONST UINT8 *MessageHash,\r
+ IN UINTN HashSize,\r
+ IN CONST UINT8 *Signature,\r
+ IN UINTN SigSize\r
+ );\r
+\r
#endif // __BASE_CRYPT_LIB_H__\r