X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=CryptoPkg%2FInclude%2FLibrary%2FBaseCryptLib.h;h=f9191f6e96d33d2e0c0a2d666e79fa992ca93f9c;hp=390e302f98c84f38eaa1d62e3cdcfd88035ed14f;hb=1796a39493b2447758099e1fba77e61b5cfe9261;hpb=45419de6ca5bad34567e0ca2a16a4bc78f6a6f63 diff --git a/CryptoPkg/Include/Library/BaseCryptLib.h b/CryptoPkg/Include/Library/BaseCryptLib.h index 390e302f98..f9191f6e96 100644 --- a/CryptoPkg/Include/Library/BaseCryptLib.h +++ b/CryptoPkg/Include/Library/BaseCryptLib.h @@ -4,14 +4,8 @@ primitives (Hash Serials, HMAC, RSA, Diffie-Hellman, etc) for UEFI security functionality enabling. -Copyright (c) 2009 - 2015, Intel Corporation. All rights reserved.
-This program and the accompanying materials -are licensed and made available under the terms and conditions of the BSD License -which accompanies this distribution. The full text of the license may be found at -http://opensource.org/licenses/bsd-license.php - -THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, -WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. +Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.
+SPDX-License-Identifier: BSD-2-Clause-Patent **/ @@ -140,7 +134,7 @@ Md4Duplicate ( This function performs MD4 digest on a data buffer of the specified size. It can be called multiple times to compute the digest of long or discontinuous data streams. - MD4 context should be already correctly intialized by Md4Init(), and should not be finalized + MD4 context should be already correctly initialized by Md4Init(), and should not be finalized by Md4Final(). Behavior with invalid context is undefined. If Md4Context is NULL, then return FALSE. @@ -169,7 +163,7 @@ Md4Update ( This function completes MD4 hash computation and retrieves the digest value into the specified memory. After this function has been called, the MD4 context cannot be used again. - MD4 context should be already correctly intialized by Md4Init(), and should not be + MD4 context should be already correctly initialized by Md4Init(), and should not be finalized by Md4Final(). Behavior with invalid MD4 context is undefined. If Md4Context is NULL, then return FALSE. @@ -192,6 +186,32 @@ Md4Final ( OUT UINT8 *HashValue ); +/** + Computes the MD4 message digest of a input data buffer. + + This function performs the MD4 message digest of a given data buffer, and places + the digest value into the specified memory. + + If this interface is not supported, then return FALSE. + + @param[in] Data Pointer to the buffer containing the data to be hashed. + @param[in] DataSize Size of Data buffer in bytes. + @param[out] HashValue Pointer to a buffer that receives the MD4 digest + value (16 bytes). + + @retval TRUE MD4 digest computation succeeded. + @retval FALSE MD4 digest computation failed. + @retval FALSE This interface is not supported. + +**/ +BOOLEAN +EFIAPI +Md4HashAll ( + IN CONST VOID *Data, + IN UINTN DataSize, + OUT UINT8 *HashValue + ); + /** Retrieves the size, in bytes, of the context buffer required for MD5 hash operations. @@ -254,7 +274,7 @@ Md5Duplicate ( This function performs MD5 digest on a data buffer of the specified size. It can be called multiple times to compute the digest of long or discontinuous data streams. - MD5 context should be already correctly intialized by Md5Init(), and should not be finalized + MD5 context should be already correctly initialized by Md5Init(), and should not be finalized by Md5Final(). Behavior with invalid context is undefined. If Md5Context is NULL, then return FALSE. @@ -283,7 +303,7 @@ Md5Update ( This function completes MD5 hash computation and retrieves the digest value into the specified memory. After this function has been called, the MD5 context cannot be used again. - MD5 context should be already correctly intialized by Md5Init(), and should not be + MD5 context should be already correctly initialized by Md5Init(), and should not be finalized by Md5Final(). Behavior with invalid MD5 context is undefined. If Md5Context is NULL, then return FALSE. @@ -306,6 +326,32 @@ Md5Final ( OUT UINT8 *HashValue ); +/** + Computes the MD5 message digest of a input data buffer. + + This function performs the MD5 message digest of a given data buffer, and places + the digest value into the specified memory. + + If this interface is not supported, then return FALSE. + + @param[in] Data Pointer to the buffer containing the data to be hashed. + @param[in] DataSize Size of Data buffer in bytes. + @param[out] HashValue Pointer to a buffer that receives the MD5 digest + value (16 bytes). + + @retval TRUE MD5 digest computation succeeded. + @retval FALSE MD5 digest computation failed. + @retval FALSE This interface is not supported. + +**/ +BOOLEAN +EFIAPI +Md5HashAll ( + IN CONST VOID *Data, + IN UINTN DataSize, + OUT UINT8 *HashValue + ); + /** Retrieves the size, in bytes, of the context buffer required for SHA-1 hash operations. @@ -368,7 +414,7 @@ Sha1Duplicate ( This function performs SHA-1 digest on a data buffer of the specified size. It can be called multiple times to compute the digest of long or discontinuous data streams. - SHA-1 context should be already correctly intialized by Sha1Init(), and should not be finalized + SHA-1 context should be already correctly initialized by Sha1Init(), and should not be finalized by Sha1Final(). Behavior with invalid context is undefined. If Sha1Context is NULL, then return FALSE. @@ -397,7 +443,7 @@ Sha1Update ( This function completes SHA-1 hash computation and retrieves the digest value into the specified memory. After this function has been called, the SHA-1 context cannot be used again. - SHA-1 context should be already correctly intialized by Sha1Init(), and should not be + SHA-1 context should be already correctly initialized by Sha1Init(), and should not be finalized by Sha1Final(). Behavior with invalid SHA-1 context is undefined. If Sha1Context is NULL, then return FALSE. @@ -420,6 +466,32 @@ Sha1Final ( OUT UINT8 *HashValue ); +/** + Computes the SHA-1 message digest of a input data buffer. + + This function performs the SHA-1 message digest of a given data buffer, and places + the digest value into the specified memory. + + If this interface is not supported, then return FALSE. + + @param[in] Data Pointer to the buffer containing the data to be hashed. + @param[in] DataSize Size of Data buffer in bytes. + @param[out] HashValue Pointer to a buffer that receives the SHA-1 digest + value (20 bytes). + + @retval TRUE SHA-1 digest computation succeeded. + @retval FALSE SHA-1 digest computation failed. + @retval FALSE This interface is not supported. + +**/ +BOOLEAN +EFIAPI +Sha1HashAll ( + IN CONST VOID *Data, + IN UINTN DataSize, + OUT UINT8 *HashValue + ); + /** Retrieves the size, in bytes, of the context buffer required for SHA-256 hash operations. @@ -477,7 +549,7 @@ Sha256Duplicate ( This function performs SHA-256 digest on a data buffer of the specified size. It can be called multiple times to compute the digest of long or discontinuous data streams. - SHA-256 context should be already correctly intialized by Sha256Init(), and should not be finalized + SHA-256 context should be already correctly initialized by Sha256Init(), and should not be finalized by Sha256Final(). Behavior with invalid context is undefined. If Sha256Context is NULL, then return FALSE. @@ -504,7 +576,7 @@ Sha256Update ( This function completes SHA-256 hash computation and retrieves the digest value into the specified memory. After this function has been called, the SHA-256 context cannot be used again. - SHA-256 context should be already correctly intialized by Sha256Init(), and should not be + SHA-256 context should be already correctly initialized by Sha256Init(), and should not be finalized by Sha256Final(). Behavior with invalid SHA-256 context is undefined. If Sha256Context is NULL, then return FALSE. @@ -525,6 +597,32 @@ Sha256Final ( OUT UINT8 *HashValue ); +/** + Computes the SHA-256 message digest of a input data buffer. + + This function performs the SHA-256 message digest of a given data buffer, and places + the digest value into the specified memory. + + If this interface is not supported, then return FALSE. + + @param[in] Data Pointer to the buffer containing the data to be hashed. + @param[in] DataSize Size of Data buffer in bytes. + @param[out] HashValue Pointer to a buffer that receives the SHA-256 digest + value (32 bytes). + + @retval TRUE SHA-256 digest computation succeeded. + @retval FALSE SHA-256 digest computation failed. + @retval FALSE This interface is not supported. + +**/ +BOOLEAN +EFIAPI +Sha256HashAll ( + IN CONST VOID *Data, + IN UINTN DataSize, + OUT UINT8 *HashValue + ); + /** Retrieves the size, in bytes, of the context buffer required for SHA-384 hash operations. @@ -582,7 +680,7 @@ Sha384Duplicate ( This function performs SHA-384 digest on a data buffer of the specified size. It can be called multiple times to compute the digest of long or discontinuous data streams. - SHA-384 context should be already correctly intialized by Sha384Init(), and should not be finalized + SHA-384 context should be already correctly initialized by Sha384Init(), and should not be finalized by Sha384Final(). Behavior with invalid context is undefined. If Sha384Context is NULL, then return FALSE. @@ -609,7 +707,7 @@ Sha384Update ( This function completes SHA-384 hash computation and retrieves the digest value into the specified memory. After this function has been called, the SHA-384 context cannot be used again. - SHA-384 context should be already correctly intialized by Sha384Init(), and should not be + SHA-384 context should be already correctly initialized by Sha384Init(), and should not be finalized by Sha384Final(). Behavior with invalid SHA-384 context is undefined. If Sha384Context is NULL, then return FALSE. @@ -630,6 +728,32 @@ Sha384Final ( OUT UINT8 *HashValue ); +/** + Computes the SHA-384 message digest of a input data buffer. + + This function performs the SHA-384 message digest of a given data buffer, and places + the digest value into the specified memory. + + If this interface is not supported, then return FALSE. + + @param[in] Data Pointer to the buffer containing the data to be hashed. + @param[in] DataSize Size of Data buffer in bytes. + @param[out] HashValue Pointer to a buffer that receives the SHA-384 digest + value (48 bytes). + + @retval TRUE SHA-384 digest computation succeeded. + @retval FALSE SHA-384 digest computation failed. + @retval FALSE This interface is not supported. + +**/ +BOOLEAN +EFIAPI +Sha384HashAll ( + IN CONST VOID *Data, + IN UINTN DataSize, + OUT UINT8 *HashValue + ); + /** Retrieves the size, in bytes, of the context buffer required for SHA-512 hash operations. @@ -687,7 +811,7 @@ Sha512Duplicate ( This function performs SHA-512 digest on a data buffer of the specified size. It can be called multiple times to compute the digest of long or discontinuous data streams. - SHA-512 context should be already correctly intialized by Sha512Init(), and should not be finalized + SHA-512 context should be already correctly initialized by Sha512Init(), and should not be finalized by Sha512Final(). Behavior with invalid context is undefined. If Sha512Context is NULL, then return FALSE. @@ -714,7 +838,7 @@ Sha512Update ( This function completes SHA-512 hash computation and retrieves the digest value into the specified memory. After this function has been called, the SHA-512 context cannot be used again. - SHA-512 context should be already correctly intialized by Sha512Init(), and should not be + SHA-512 context should be already correctly initialized by Sha512Init(), and should not be finalized by Sha512Final(). Behavior with invalid SHA-512 context is undefined. If Sha512Context is NULL, then return FALSE. @@ -735,12 +859,40 @@ Sha512Final ( OUT UINT8 *HashValue ); +/** + Computes the SHA-512 message digest of a input data buffer. + + This function performs the SHA-512 message digest of a given data buffer, and places + the digest value into the specified memory. + + If this interface is not supported, then return FALSE. + + @param[in] Data Pointer to the buffer containing the data to be hashed. + @param[in] DataSize Size of Data buffer in bytes. + @param[out] HashValue Pointer to a buffer that receives the SHA-512 digest + value (64 bytes). + + @retval TRUE SHA-512 digest computation succeeded. + @retval FALSE SHA-512 digest computation failed. + @retval FALSE This interface is not supported. + +**/ +BOOLEAN +EFIAPI +Sha512HashAll ( + IN CONST VOID *Data, + IN UINTN DataSize, + OUT UINT8 *HashValue + ); + //===================================================================================== // MAC (Message Authentication Code) Primitive //===================================================================================== /** Retrieves the size, in bytes, of the context buffer required for HMAC-MD5 operations. + (NOTE: This API is deprecated. + Use HmacMd5New() / HmacMd5Free() for HMAC-MD5 Context operations.) If this interface is not supported, then return zero. @@ -754,6 +906,36 @@ HmacMd5GetContextSize ( VOID ); +/** + Allocates and initializes one HMAC_CTX context for subsequent HMAC-MD5 use. + + If this interface is not supported, then return NULL. + + @return Pointer to the HMAC_CTX context that has been initialized. + If the allocations fails, HmacMd5New() returns NULL. + @retval NULL This interface is not supported. + +**/ +VOID * +EFIAPI +HmacMd5New ( + VOID + ); + +/** + Release the specified HMAC_CTX context. + + If this interface is not supported, then do nothing. + + @param[in] HmacMd5Ctx Pointer to the HMAC_CTX context to be released. + +**/ +VOID +EFIAPI +HmacMd5Free ( + IN VOID *HmacMd5Ctx + ); + /** Initializes user-supplied memory pointed by HmacMd5Context as HMAC-MD5 context for subsequent use. @@ -805,7 +987,7 @@ HmacMd5Duplicate ( This function performs HMAC-MD5 digest on a data buffer of the specified size. It can be called multiple times to compute the digest of long or discontinuous data streams. - HMAC-MD5 context should be already correctly intialized by HmacMd5Init(), and should not be + HMAC-MD5 context should be already correctly initialized by HmacMd5Init(), and should not be finalized by HmacMd5Final(). Behavior with invalid context is undefined. If HmacMd5Context is NULL, then return FALSE. @@ -834,15 +1016,15 @@ HmacMd5Update ( This function completes HMAC-MD5 hash computation and retrieves the digest value into the specified memory. After this function has been called, the HMAC-MD5 context cannot be used again. - HMAC-MD5 context should be already correctly intialized by HmacMd5Init(), and should not be + HMAC-MD5 context should be already correctly initialized by HmacMd5Init(), and should not be finalized by HmacMd5Final(). Behavior with invalid HMAC-MD5 context is undefined. If HmacMd5Context is NULL, then return FALSE. - If HashValue is NULL, then return FALSE. + If HmacValue is NULL, then return FALSE. If this interface is not supported, then return FALSE. @param[in, out] HmacMd5Context Pointer to the HMAC-MD5 context. - @param[out] HashValue Pointer to a buffer that receives the HMAC-MD5 digest + @param[out] HmacValue Pointer to a buffer that receives the HMAC-MD5 digest value (16 bytes). @retval TRUE HMAC-MD5 digest computation succeeded. @@ -859,6 +1041,8 @@ HmacMd5Final ( /** Retrieves the size, in bytes, of the context buffer required for HMAC-SHA1 operations. + (NOTE: This API is deprecated. + Use HmacSha1New() / HmacSha1Free() for HMAC-SHA1 Context operations.) If this interface is not supported, then return zero. @@ -872,6 +1056,36 @@ HmacSha1GetContextSize ( VOID ); +/** + Allocates and initializes one HMAC_CTX context for subsequent HMAC-SHA1 use. + + If this interface is not supported, then return NULL. + + @return Pointer to the HMAC_CTX context that has been initialized. + If the allocations fails, HmacSha1New() returns NULL. + @return NULL This interface is not supported. + +**/ +VOID * +EFIAPI +HmacSha1New ( + VOID + ); + +/** + Release the specified HMAC_CTX context. + + If this interface is not supported, then do nothing. + + @param[in] HmacSha1Ctx Pointer to the HMAC_CTX context to be released. + +**/ +VOID +EFIAPI +HmacSha1Free ( + IN VOID *HmacSha1Ctx + ); + /** Initializes user-supplied memory pointed by HmacSha1Context as HMAC-SHA1 context for subsequent use. @@ -923,7 +1137,7 @@ HmacSha1Duplicate ( This function performs HMAC-SHA1 digest on a data buffer of the specified size. It can be called multiple times to compute the digest of long or discontinuous data streams. - HMAC-SHA1 context should be already correctly intialized by HmacSha1Init(), and should not + HMAC-SHA1 context should be already correctly initialized by HmacSha1Init(), and should not be finalized by HmacSha1Final(). Behavior with invalid context is undefined. If HmacSha1Context is NULL, then return FALSE. @@ -952,15 +1166,15 @@ HmacSha1Update ( This function completes HMAC-SHA1 hash computation and retrieves the digest value into the specified memory. After this function has been called, the HMAC-SHA1 context cannot be used again. - HMAC-SHA1 context should be already correctly intialized by HmacSha1Init(), and should + HMAC-SHA1 context should be already correctly initialized by HmacSha1Init(), and should not be finalized by HmacSha1Final(). Behavior with invalid HMAC-SHA1 context is undefined. If HmacSha1Context is NULL, then return FALSE. - If HashValue is NULL, then return FALSE. + If HmacValue is NULL, then return FALSE. If this interface is not supported, then return FALSE. @param[in, out] HmacSha1Context Pointer to the HMAC-SHA1 context. - @param[out] HashValue Pointer to a buffer that receives the HMAC-SHA1 digest + @param[out] HmacValue Pointer to a buffer that receives the HMAC-SHA1 digest value (20 bytes). @retval TRUE HMAC-SHA1 digest computation succeeded. @@ -975,6 +1189,151 @@ HmacSha1Final ( OUT UINT8 *HmacValue ); +/** + Retrieves the size, in bytes, of the context buffer required for HMAC-SHA256 operations. + (NOTE: This API is deprecated. + Use HmacSha256New() / HmacSha256Free() for HMAC-SHA256 Context operations.) + + If this interface is not supported, then return zero. + + @return The size, in bytes, of the context buffer required for HMAC-SHA256 operations. + @retval 0 This interface is not supported. + +**/ +UINTN +EFIAPI +HmacSha256GetContextSize ( + VOID + ); + +/** + Allocates and initializes one HMAC_CTX context for subsequent HMAC-SHA256 use. + + @return Pointer to the HMAC_CTX context that has been initialized. + If the allocations fails, HmacSha256New() returns NULL. + +**/ +VOID * +EFIAPI +HmacSha256New ( + VOID + ); + +/** + Release the specified HMAC_CTX context. + + @param[in] HmacSha256Ctx Pointer to the HMAC_CTX context to be released. + +**/ +VOID +EFIAPI +HmacSha256Free ( + IN VOID *HmacSha256Ctx + ); + +/** + Initializes user-supplied memory pointed by HmacSha256Context as HMAC-SHA256 context for + subsequent use. + + If HmacSha256Context is NULL, then return FALSE. + If this interface is not supported, then return FALSE. + + @param[out] HmacSha256Context Pointer to HMAC-SHA256 context being initialized. + @param[in] Key Pointer to the user-supplied key. + @param[in] KeySize Key size in bytes. + + @retval TRUE HMAC-SHA256 context initialization succeeded. + @retval FALSE HMAC-SHA256 context initialization failed. + @retval FALSE This interface is not supported. + +**/ +BOOLEAN +EFIAPI +HmacSha256Init ( + OUT VOID *HmacSha256Context, + IN CONST UINT8 *Key, + IN UINTN KeySize + ); + +/** + Makes a copy of an existing HMAC-SHA256 context. + + If HmacSha256Context is NULL, then return FALSE. + If NewHmacSha256Context is NULL, then return FALSE. + If this interface is not supported, then return FALSE. + + @param[in] HmacSha256Context Pointer to HMAC-SHA256 context being copied. + @param[out] NewHmacSha256Context Pointer to new HMAC-SHA256 context. + + @retval TRUE HMAC-SHA256 context copy succeeded. + @retval FALSE HMAC-SHA256 context copy failed. + @retval FALSE This interface is not supported. + +**/ +BOOLEAN +EFIAPI +HmacSha256Duplicate ( + IN CONST VOID *HmacSha256Context, + OUT VOID *NewHmacSha256Context + ); + +/** + Digests the input data and updates HMAC-SHA256 context. + + This function performs HMAC-SHA256 digest on a data buffer of the specified size. + It can be called multiple times to compute the digest of long or discontinuous data streams. + HMAC-SHA256 context should be already correctly initialized by HmacSha256Init(), and should not + be finalized by HmacSha256Final(). Behavior with invalid context is undefined. + + If HmacSha256Context is NULL, then return FALSE. + If this interface is not supported, then return FALSE. + + @param[in, out] HmacSha256Context Pointer to the HMAC-SHA256 context. + @param[in] Data Pointer to the buffer containing the data to be digested. + @param[in] DataSize Size of Data buffer in bytes. + + @retval TRUE HMAC-SHA256 data digest succeeded. + @retval FALSE HMAC-SHA256 data digest failed. + @retval FALSE This interface is not supported. + +**/ +BOOLEAN +EFIAPI +HmacSha256Update ( + IN OUT VOID *HmacSha256Context, + IN CONST VOID *Data, + IN UINTN DataSize + ); + +/** + Completes computation of the HMAC-SHA256 digest value. + + This function completes HMAC-SHA256 hash computation and retrieves the digest value into + the specified memory. After this function has been called, the HMAC-SHA256 context cannot + be used again. + HMAC-SHA256 context should be already correctly initialized by HmacSha256Init(), and should + not be finalized by HmacSha256Final(). Behavior with invalid HMAC-SHA256 context is undefined. + + If HmacSha256Context is NULL, then return FALSE. + If HmacValue is NULL, then return FALSE. + If this interface is not supported, then return FALSE. + + @param[in, out] HmacSha256Context Pointer to the HMAC-SHA256 context. + @param[out] HmacValue Pointer to a buffer that receives the HMAC-SHA256 digest + value (32 bytes). + + @retval TRUE HMAC-SHA256 digest computation succeeded. + @retval FALSE HMAC-SHA256 digest computation failed. + @retval FALSE This interface is not supported. + +**/ +BOOLEAN +EFIAPI +HmacSha256Final ( + IN OUT VOID *HmacSha256Context, + OUT UINT8 *HmacValue + ); + //===================================================================================== // Symmetric Cryptography Primitive //===================================================================================== @@ -1425,10 +1784,10 @@ Arc4Init ( If Output is NULL, then return FALSE. If this interface is not supported, then return FALSE. - @param[in] Arc4Context Pointer to the ARC4 context. - @param[in] Input Pointer to the buffer containing the data to be encrypted. - @param[in] InputSize Size of the Input buffer in bytes. - @param[out] Output Pointer to a buffer that receives the ARC4 encryption output. + @param[in, out] Arc4Context Pointer to the ARC4 context. + @param[in] Input Pointer to the buffer containing the data to be encrypted. + @param[in] InputSize Size of the Input buffer in bytes. + @param[out] Output Pointer to a buffer that receives the ARC4 encryption output. @retval TRUE ARC4 encryption succeeded. @retval FALSE ARC4 encryption failed. @@ -1457,10 +1816,10 @@ Arc4Encrypt ( If Output is NULL, then return FALSE. If this interface is not supported, then return FALSE. - @param[in] Arc4Context Pointer to the ARC4 context. - @param[in] Input Pointer to the buffer containing the data to be decrypted. - @param[in] InputSize Size of the Input buffer in bytes. - @param[out] Output Pointer to a buffer that receives the ARC4 decryption output. + @param[in, out] Arc4Context Pointer to the ARC4 context. + @param[in] Input Pointer to the buffer containing the data to be decrypted. + @param[in] InputSize Size of the Input buffer in bytes. + @param[out] Output Pointer to a buffer that receives the ARC4 decryption output. @retval TRUE ARC4 decryption succeeded. @retval FALSE ARC4 decryption failed. @@ -1537,14 +1896,14 @@ RsaFree ( This function sets the tag-designated RSA key component into the established RSA context from the user-specified non-negative integer (octet string format represented in RSA PKCS#1). - If BigNumber is NULL, then the specified key componenet in RSA context is cleared. + If BigNumber is NULL, then the specified key component in RSA context is cleared. If RsaContext is NULL, then return FALSE. @param[in, out] RsaContext Pointer to RSA context being set. @param[in] KeyTag Tag of RSA key component being set. @param[in] BigNumber Pointer to octet integer buffer. - If NULL, then the specified key componenet in RSA + If NULL, then the specified key component in RSA context is cleared. @param[in] BnSize Size of big number buffer in bytes. If BigNumber is NULL, then it is ignored. @@ -1636,7 +1995,7 @@ RsaGenerateKey ( NOTE: This function performs integrity checks on all the RSA key material, so the RSA key structure must contain all the private key data. - This function validates key compoents of RSA context in following aspects: + This function validates key components of RSA context in following aspects: - Whether p is a prime - Whether q is a prime - Whether n = p * q @@ -1806,6 +2165,76 @@ X509GetSubjectName ( IN OUT UINTN *SubjectSize ); +/** + Retrieve the common name (CN) string from one X.509 certificate. + + @param[in] Cert Pointer to the DER-encoded X509 certificate. + @param[in] CertSize Size of the X509 certificate in bytes. + @param[out] CommonName Buffer to contain the retrieved certificate common + name string (UTF8). At most CommonNameSize bytes will be + written and the string will be null terminated. May be + NULL in order to determine the size buffer needed. + @param[in,out] CommonNameSize The size in bytes of the CommonName buffer on input, + and the size of buffer returned CommonName on output. + If CommonName is NULL then the amount of space needed + in buffer (including the final null) is returned. + + @retval RETURN_SUCCESS The certificate CommonName retrieved successfully. + @retval RETURN_INVALID_PARAMETER If Cert is NULL. + If CommonNameSize is NULL. + If CommonName is not NULL and *CommonNameSize is 0. + If Certificate is invalid. + @retval RETURN_NOT_FOUND If no CommonName entry exists. + @retval RETURN_BUFFER_TOO_SMALL If the CommonName is NULL. The required buffer size + (including the final null) is returned in the + CommonNameSize parameter. + @retval RETURN_UNSUPPORTED The operation is not supported. + +**/ +RETURN_STATUS +EFIAPI +X509GetCommonName ( + IN CONST UINT8 *Cert, + IN UINTN CertSize, + OUT CHAR8 *CommonName, OPTIONAL + IN OUT UINTN *CommonNameSize + ); + +/** + Retrieve the organization name (O) string from one X.509 certificate. + + @param[in] Cert Pointer to the DER-encoded X509 certificate. + @param[in] CertSize Size of the X509 certificate in bytes. + @param[out] NameBuffer Buffer to contain the retrieved certificate organization + name string. At most NameBufferSize bytes will be + written and the string will be null terminated. May be + NULL in order to determine the size buffer needed. + @param[in,out] NameBufferSize The size in bytes of the Name buffer on input, + and the size of buffer returned Name on output. + If NameBuffer is NULL then the amount of space needed + in buffer (including the final null) is returned. + + @retval RETURN_SUCCESS The certificate Organization Name retrieved successfully. + @retval RETURN_INVALID_PARAMETER If Cert is NULL. + If NameBufferSize is NULL. + If NameBuffer is not NULL and *CommonNameSize is 0. + If Certificate is invalid. + @retval RETURN_NOT_FOUND If no Organization Name entry exists. + @retval RETURN_BUFFER_TOO_SMALL If the NameBuffer is NULL. The required buffer size + (including the final null) is returned in the + CommonNameSize parameter. + @retval RETURN_UNSUPPORTED The operation is not supported. + +**/ +RETURN_STATUS +EFIAPI +X509GetOrganizationName ( + IN CONST UINT8 *Cert, + IN UINTN CertSize, + OUT CHAR8 *NameBuffer, OPTIONAL + IN OUT UINTN *NameBufferSize + ); + /** Verify one X509 certificate was issued by the trusted CA. @@ -1936,22 +2365,95 @@ X509GetTBSCert ( OUT UINTN *TBSCertSize ); +/** + Derives a key from a password using a salt and iteration count, based on PKCS#5 v2.0 + password based encryption key derivation function PBKDF2, as specified in RFC 2898. + + If Password or Salt or OutKey is NULL, then return FALSE. + If the hash algorithm could not be determined, then return FALSE. + If this interface is not supported, then return FALSE. + + @param[in] PasswordLength Length of input password in bytes. + @param[in] Password Pointer to the array for the password. + @param[in] SaltLength Size of the Salt in bytes. + @param[in] Salt Pointer to the Salt. + @param[in] IterationCount Number of iterations to perform. Its value should be + greater than or equal to 1. + @param[in] DigestSize Size of the message digest to be used (eg. SHA256_DIGEST_SIZE). + NOTE: DigestSize will be used to determine the hash algorithm. + Only SHA1_DIGEST_SIZE or SHA256_DIGEST_SIZE is supported. + @param[in] KeyLength Size of the derived key buffer in bytes. + @param[out] OutKey Pointer to the output derived key buffer. + + @retval TRUE A key was derived successfully. + @retval FALSE One of the pointers was NULL or one of the sizes was too large. + @retval FALSE The hash algorithm could not be determined from the digest size. + @retval FALSE The key derivation operation failed. + @retval FALSE This interface is not supported. + +**/ +BOOLEAN +EFIAPI +Pkcs5HashPassword ( + IN UINTN PasswordLength, + IN CONST CHAR8 *Password, + IN UINTN SaltLength, + IN CONST UINT8 *Salt, + IN UINTN IterationCount, + IN UINTN DigestSize, + IN UINTN KeyLength, + OUT UINT8 *OutKey + ); + +/** + The 3rd parameter of Pkcs7GetSigners will return all embedded + X.509 certificate in one given PKCS7 signature. The format is: + // + // UINT8 CertNumber; + // UINT32 Cert1Length; + // UINT8 Cert1[]; + // UINT32 Cert2Length; + // UINT8 Cert2[]; + // ... + // UINT32 CertnLength; + // UINT8 Certn[]; + // + + The two following C-structure are used for parsing CertStack more clearly. +**/ +#pragma pack(1) + +typedef struct { + UINT32 CertDataLength; // The length in bytes of X.509 certificate. + UINT8 CertDataBuffer[0]; // The X.509 certificate content (DER). +} EFI_CERT_DATA; + +typedef struct { + UINT8 CertNumber; // Number of X.509 certificate. + //EFI_CERT_DATA CertArray[]; // An array of X.509 certificate. +} EFI_CERT_STACK; + +#pragma pack() + /** Get the signer's certificates from PKCS#7 signed data as described in "PKCS #7: Cryptographic Message Syntax Standard". The input signed data could be wrapped in a ContentInfo structure. If P7Data, CertStack, StackLength, TrustedCert or CertLength is NULL, then - return FALSE. If P7Length overflow, then return FAlSE. + return FALSE. If P7Length overflow, then return FALSE. If this interface is not supported, then return FALSE. @param[in] P7Data Pointer to the PKCS#7 message to verify. @param[in] P7Length Length of the PKCS#7 message in bytes. @param[out] CertStack Pointer to Signer's certificates retrieved from P7Data. - It's caller's responsiblity to free the buffer. + It's caller's responsibility to free the buffer with + Pkcs7FreeSigners(). + This data structure is EFI_CERT_STACK type. @param[out] StackLength Length of signer's certificates in bytes. @param[out] TrustedCert Pointer to a trusted certificate from Signer's certificates. - It's caller's responsiblity to free the buffer. + It's caller's responsibility to free the buffer with + Pkcs7FreeSigners(). @param[out] CertLength Length of the trusted certificate in bytes. @retval TRUE The operation is finished successfully. @@ -1992,11 +2494,14 @@ Pkcs7FreeSigners ( @param[in] P7Data Pointer to the PKCS#7 message. @param[in] P7Length Length of the PKCS#7 message in bytes. - @param[out] SingerChainCerts Pointer to the certificates list chained to signer's - certificate. It's caller's responsiblity to free the buffer. + @param[out] SignerChainCerts Pointer to the certificates list chained to signer's + certificate. It's caller's responsibility to free the buffer + with Pkcs7FreeSigners(). + This data structure is EFI_CERT_STACK type. @param[out] ChainLength Length of the chained certificates list buffer in bytes. @param[out] UnchainCerts Pointer to the unchained certificates lists. It's caller's - responsiblity to free the buffer. + responsibility to free the buffer with Pkcs7FreeSigners(). + This data structure is EFI_CERT_STACK type. @param[out] UnchainLength Length of the unchained certificates list buffer in bytes. @retval TRUE The operation is finished successfully. @@ -2032,7 +2537,8 @@ Pkcs7GetCertificatesList ( @param[in] OtherCerts Pointer to an optional additional set of certificates to include in the PKCS#7 signedData (e.g. any intermediate CAs in the chain). - @param[out] SignedData Pointer to output PKCS#7 signedData. + @param[out] SignedData Pointer to output PKCS#7 signedData. It's caller's + responsibility to free the buffer with FreePool(). @param[out] SignedDataSize Size of SignedData in bytes. @retval TRUE PKCS#7 data signing succeeded. @@ -2055,12 +2561,12 @@ Pkcs7Sign ( ); /** - Verifies the validility of a PKCS#7 signed data as described in "PKCS #7: + Verifies the validity of a PKCS#7 signed data as described in "PKCS #7: Cryptographic Message Syntax Standard". The input signed data could be wrapped in a ContentInfo structure. If P7Data, TrustedCert or InData is NULL, then return FALSE. - If P7Length, CertLength or DataLength overflow, then return FAlSE. + If P7Length, CertLength or DataLength overflow, then return FALSE. If this interface is not supported, then return FALSE. @param[in] P7Data Pointer to the PKCS#7 message to verify. @@ -2087,12 +2593,54 @@ Pkcs7Verify ( IN UINTN DataLength ); +/** + This function receives a PKCS7 formatted signature, and then verifies that + the specified Enhanced or Extended Key Usages (EKU's) are present in the end-entity + leaf signing certificate. + Note that this function does not validate the certificate chain. + + Applications for custom EKU's are quite flexible. For example, a policy EKU + may be present in an Issuing Certificate Authority (CA), and any sub-ordinate + certificate issued might also contain this EKU, thus constraining the + sub-ordinate certificate. Other applications might allow a certificate + embedded in a device to specify that other Object Identifiers (OIDs) are + present which contains binary data specifying custom capabilities that + the device is able to do. + + @param[in] Pkcs7Signature The PKCS#7 signed information content block. An array + containing the content block with both the signature, + the signer's certificate, and any necessary intermediate + certificates. + @param[in] Pkcs7SignatureSize Number of bytes in Pkcs7Signature. + @param[in] RequiredEKUs Array of null-terminated strings listing OIDs of + required EKUs that must be present in the signature. + @param[in] RequiredEKUsSize Number of elements in the RequiredEKUs string array. + @param[in] RequireAllPresent If this is TRUE, then all of the specified EKU's + must be present in the leaf signer. If it is + FALSE, then we will succeed if we find any + of the specified EKU's. + + @retval EFI_SUCCESS The required EKUs were found in the signature. + @retval EFI_INVALID_PARAMETER A parameter was invalid. + @retval EFI_NOT_FOUND One or more EKU's were not found in the signature. + +**/ +RETURN_STATUS +EFIAPI +VerifyEKUsInPkcs7Signature ( + IN CONST UINT8 *Pkcs7Signature, + IN CONST UINT32 SignatureSize, + IN CONST CHAR8 *RequiredEKUs[], + IN CONST UINT32 RequiredEKUsSize, + IN BOOLEAN RequireAllPresent + ); + /** Extracts the attached content from a PKCS#7 signed data if existed. The input signed data could be wrapped in a ContentInfo structure. If P7Data, Content, or ContentSize is NULL, then return FALSE. If P7Length overflow, - then return FAlSE. If the P7Data is not correctly formatted, then return FALSE. + then return FALSE. If the P7Data is not correctly formatted, then return FALSE. Caution: This function may receive untrusted input. So this function will do basic check for PKCS#7 data structure. @@ -2100,13 +2648,13 @@ Pkcs7Verify ( @param[in] P7Data Pointer to the PKCS#7 signed data to process. @param[in] P7Length Length of the PKCS#7 signed data in bytes. @param[out] Content Pointer to the extracted content from the PKCS#7 signedData. - It's caller's responsiblity to free the buffer. + It's caller's responsibility to free the buffer with FreePool(). @param[out] ContentSize The size of the extracted content in bytes. @retval TRUE The P7Data was correctly formatted for processing. @retval FALSE The P7Data was not correctly formatted for processing. -*/ +**/ BOOLEAN EFIAPI Pkcs7GetAttachedContent ( @@ -2117,7 +2665,7 @@ Pkcs7GetAttachedContent ( ); /** - Verifies the validility of a PE/COFF Authenticode Signature as described in "Windows + Verifies the validity of a PE/COFF Authenticode Signature as described in "Windows Authenticode Portable Executable Signature Format". If AuthData is NULL, then return FALSE. @@ -2130,7 +2678,7 @@ Pkcs7GetAttachedContent ( @param[in] TrustedCert Pointer to a trusted/root certificate encoded in DER, which is used for certificate chain verification. @param[in] CertSize Size of the trusted certificate in bytes. - @param[in] ImageHash Pointer to the original image file hash value. The procudure + @param[in] ImageHash Pointer to the original image file hash value. The procedure for calculating the image hash value is described in Authenticode specification. @param[in] HashSize Size of Image hash value in bytes. @@ -2152,7 +2700,7 @@ AuthenticodeVerify ( ); /** - Verifies the validility of a RFC3161 Timestamp CounterSignature embedded in PE/COFF Authenticode + Verifies the validity of a RFC3161 Timestamp CounterSignature embedded in PE/COFF Authenticode signature. If AuthData is NULL, then return FALSE. @@ -2231,7 +2779,7 @@ DhFree ( @param[in] PrimeLength Length in bits of prime to be generated. @param[out] Prime Pointer to the buffer to receive the generated prime number. - @retval TRUE DH pamameter generation succeeded. + @retval TRUE DH parameter generation succeeded. @retval FALSE Value of Generator is not supported. @retval FALSE PRNG fails to generate random prime number with PrimeLength. @retval FALSE This interface is not supported. @@ -2261,7 +2809,7 @@ DhGenerateParameter ( @param[in] PrimeLength Length in bits of prime to be generated. @param[in] Prime Pointer to the prime number. - @retval TRUE DH pamameter setting succeeded. + @retval TRUE DH parameter setting succeeded. @retval FALSE Value of Generator is not supported. @retval FALSE Value of Generator is not suitable for the Prime. @retval FALSE Value of Prime is not a prime number. @@ -2382,7 +2930,7 @@ RandomSeed ( If this interface is not supported, then return FALSE. @param[out] Output Pointer to buffer to receive random value. - @param[in] Size Size of randome bytes to generate. + @param[in] Size Size of random bytes to generate. @retval TRUE Pseudorandom byte stream generated successfully. @retval FALSE Pseudorandom number generator fails to generate due to lack of entropy.