X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=blobdiff_plain;f=CryptoPkg%2FInclude%2FLibrary%2FBaseCryptLib.h;h=f9191f6e96d33d2e0c0a2d666e79fa992ca93f9c;hp=45dac3b4c10c4ad1f9de1c8309530c8107fe96dd;hb=1796a39493b2447758099e1fba77e61b5cfe9261;hpb=2998af862469c6a05657e169d7def6f55420caad
diff --git a/CryptoPkg/Include/Library/BaseCryptLib.h b/CryptoPkg/Include/Library/BaseCryptLib.h
index 45dac3b4c1..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 - 2016, 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
**/
@@ -897,6 +891,8 @@ Sha512HashAll (
/**
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.
@@ -910,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.
@@ -994,11 +1020,11 @@ HmacMd5Update (
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.
@@ -1015,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.
@@ -1028,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.
@@ -1112,11 +1170,11 @@ HmacSha1Update (
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.
@@ -1133,6 +1191,8 @@ HmacSha1Final (
/**
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.
@@ -1146,6 +1206,31 @@ 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.
@@ -1230,11 +1315,11 @@ HmacSha256Update (
not be finalized by HmacSha256Final(). Behavior with invalid HMAC-SHA256 context is undefined.
If HmacSha256Context 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] HmacSha256Context Pointer to the HMAC-SHA256 context.
- @param[out] HashValue Pointer to a buffer that receives the HMAC-SHA256 digest
+ @param[out] HmacValue Pointer to a buffer that receives the HMAC-SHA256 digest
value (32 bytes).
@retval TRUE HMAC-SHA256 digest computation succeeded.
@@ -1699,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.
@@ -1731,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.
@@ -2080,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.
@@ -2250,6 +2405,36 @@ Pkcs5HashPassword (
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
@@ -2262,10 +2447,13 @@ Pkcs5HashPassword (
@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 responsibility 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 responsibility 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.
@@ -2307,10 +2495,13 @@ Pkcs7FreeSigners (
@param[in] P7Data Pointer to the PKCS#7 message.
@param[in] P7Length Length of the PKCS#7 message in bytes.
@param[out] SignerChainCerts Pointer to the certificates list chained to signer's
- certificate. It's caller's responsibility to free the buffer.
+ 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
- responsibility 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.
@@ -2346,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.
@@ -2401,6 +2593,48 @@ 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.
@@ -2414,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 responsibility 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 (