From a9efdcc3dcb4db3dbcf201a77bdb69a398c47f50 Mon Sep 17 00:00:00 2001 From: Long Qin Date: Thu, 4 Jun 2015 07:10:17 +0000 Subject: [PATCH] MdePkg:Add UEFI 2.5 PKCS7 Verification Protocol Definition Contributed-under: TianoCore Contribution Agreement 1.0 Signed-off-by: Long Qin Reviewed-by: Chao Zhang git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@17560 6f19259b-4bc3-4df7-8a09-765794883524 --- MdePkg/Include/Protocol/Pkcs7Verify.h | 221 ++++++++++++++++++++++++++ MdePkg/MdePkg.dec | 3 + 2 files changed, 224 insertions(+) create mode 100644 MdePkg/Include/Protocol/Pkcs7Verify.h diff --git a/MdePkg/Include/Protocol/Pkcs7Verify.h b/MdePkg/Include/Protocol/Pkcs7Verify.h new file mode 100644 index 0000000000..ca5ec75910 --- /dev/null +++ b/MdePkg/Include/Protocol/Pkcs7Verify.h @@ -0,0 +1,221 @@ +/** @file + EFI_PKCS7_VERIFY_PROTOCOL as defined in UEFI 2.5. + The EFI_PKCS7_VERIFY_PROTOCOL is used to verify data signed using PKCS#7 + formatted authentication. The PKCS#7 data to be verified must be binary + DER encoded. + PKCS#7 is a general-purpose cryptographic standard (defined by RFC2315, + available at http://tools.ietf.org/html/rfc2315). + +Copyright (c) 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 that 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. + +**/ + +#ifndef __EFI_PKCS7_VERIFY_PROTOCOL_H__ +#define __EFI_PKCS7_VERIFY_PROTOCOL_H__ + +#include + +/// +/// Global ID for the PKCS7 Verification Protocol +/// +#define EFI_PKCS7_VERIFY_PROTOCOL_GUID \ + { \ + 0x47889fb2, 0xd671, 0x4fab, {0xa0, 0xca, 0xdf, 0x0e, 0x44, 0xdf, 0x70, 0xd6 } \ + } + +typedef struct _EFI_PKCS7_VERIFY_PROTOCOL EFI_PKCS7_VERIFY_PROTOCOL; + + +/** + Processes a buffer containing binary DER-encoded PKCS7 signature. + The signed data content may be embedded within the buffer or separated. Funtion + verifies the signature of the content is valid and signing certificate was not + revoked and is contained within a list of trusted signers. + + @param[in] This Pointer to EFI_PKCS7_VERIFY_PROTOCOL instance. + @param[in] SignedData Points to buffer containing ASN.1 DER-encoded PKCS7 + signature. + @param[in] SignedDataSize The size of SignedData buffer in bytes. + @param[in] InData In case of detached signature, InData points to + buffer containing the raw message data previously + signed and to be verified by function. In case of + SignedData containing embedded data, InData must be + NULL. + @param[in] InDataSize When InData is used, the size of InData buffer in + bytes. When InData is NULL. This parameter must be + 0. + @param[in] AllowedDb Pointer to a list of pointers to EFI_SIGNATURE_LIST + structures. The list is terminated by a null + pointer. The EFI_SIGNATURE_LIST structures contain + lists of X.509 certificates of approved signers. + Function recognizes signer certificates of type + EFI_CERT_X509_GUID. Any hash certificate in AllowedDb + list is ignored by this function. Function returns + success if signer of the buffer is within this list + (and not within RevokedDb). This parameter is + required. + @param[in] RevokedDb Optional pointer to a list of pointers to + EFI_SIGNATURE_LIST structures. The list is terminated + by a null pointer. List of X.509 certificates of + revoked signers and revoked file hashes. Except as + noted in description of TimeStampDb signature + verification will always fail if the signer of the + file or the hash of the data component of the buffer + is in RevokedDb list. This list is optional and + caller may pass Null or pointer to NULL if not + required. + @param[in] TimeStampDb Optional pointer to a list of pointers to + EFI_SIGNATURE_LIST structures. The list is terminated + by a null pointer. This parameter can be used to pass + a list of X.509 certificates of trusted time stamp + signers. This list is optional and caller must pass + Null or pointer to NULL if not required. + @param[out] Content On input, points to an optional caller-allocated + buffer into which the function will copy the content + portion of the file after verification succeeds. + This parameter is optional and if NULL, no copy of + content from file is performed. + @param[in,out] ContentSize On input, points to the size in bytes of the optional + buffer Content previously allocated by caller. On + output, if the verification succeeds, the value + referenced by ContentSize will contain the actual + size of the content from signed file. If ContentSize + indicates the caller-allocated buffer is too small + to contain content, an error is returned, and + ContentSize will be updated with the required size. + This parameter must be 0 if Content is Null. + + @retval EFI_SUCCESS Content signature was verified against hash of + content, the signer's certificate was not found in + RevokedDb, and was found in AllowedDb or if in signer + is found in both AllowedDb and RevokedDb, the + signing was allowed by reference to TimeStampDb as + described above, and no hash matching content hash + was found in RevokedDb. + @retval EFI_SECURITY_VIOLATION The SignedData buffer was correctly formatted but + signer was in RevokedDb or not in AllowedDb. Also + returned if matching content hash found in RevokedDb. + @retval EFI_COMPROMISED_DATA Calculated hash differs from signed hash. + @retval EFI_INVALID_PARAMETER SignedData is NULL or SignedDataSize is zero. + AllowedDb is NULL. + @retval EFI_INVALID_PARAMETER Content is not NULL and ContentSize is NULL. + @retval EFI_ABORTED Unsupported or invalid format in TimeStampDb, + RevokedDb or AllowedDb list contents was detected. + @retval EFI_NOT_FOUND Content not found because InData is NULL and no + content embedded in SignedData. + @retval EFI_UNSUPPORTED The SignedData buffer was not correctly formatted + for processing by the function. + @retval EFI_UNSUPPORTED Signed data embedded in SignedData but InData is not + NULL. + @retval EFI_BUFFER_TOO_SMALL The size of buffer indicated by ContentSize is too + small to hold the content. ContentSize updated to + required size. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_PKCS7_VERIFY_BUFFER) ( + IN EFI_PKCS7_VERIFY_PROTOCOL *This, + IN VOID *SignedData, + IN UINTN SignedDataSize, + IN VOID *InData OPTIONAL, + IN UINTN InDataSize, + IN EFI_SIGNATURE_LIST **AllowedDb, + IN EFI_SIGNATURE_LIST **RevokedDb OPTIONAL, + IN EFI_SIGNATURE_LIST **TimeStampDb OPTIONAL, + OUT VOID *Content OPTIONAL, + IN OUT UINTN *ContentSize + ); + +/** + Processes a buffer containing binary DER-encoded detached PKCS7 signature. + The hash of the signed data content is calculated and passed by the caller. Function + verifies the signature of the content is valid and signing certificate was not revoked + and is contained within a list of trusted signers. + + @param[in] This Pointer to EFI_PKCS7_VERIFY_PROTOCOL instance. + @param[in] Signature Points to buffer containing ASN.1 DER-encoded PKCS + detached signature. + @param[in] SignatureSize The size of Signature buffer in bytes. + @param[in] InHash InHash points to buffer containing the caller + calculated hash of the data. The parameter may not + be NULL. + @param[in] InHashSize The size in bytes of InHash buffer. + @param[in] AllowedDb Pointer to a list of pointers to EFI_SIGNATURE_LIST + structures. The list is terminated by a null + pointer. The EFI_SIGNATURE_LIST structures contain + lists of X.509 certificates of approved signers. + Function recognizes signer certificates of type + EFI_CERT_X509_GUID. Any hash certificate in AllowedDb + list is ignored by this function. Function returns + success if signer of the buffer is within this list + (and not within RevokedDb). This parameter is + required. + @param[in] RevokedDb Optional pointer to a list of pointers to + EFI_SIGNATURE_LIST structures. The list is terminated + by a null pointer. List of X.509 certificates of + revoked signers and revoked file hashes. Signature + verification will always fail if the signer of the + file or the hash of the data component of the buffer + is in RevokedDb list. This parameter is optional + and caller may pass Null if not required. + @param[in] TimeStampDb Optional pointer to a list of pointers to + EFI_SIGNATURE_LIST structures. The list is terminated + by a null pointer. This parameter can be used to pass + a list of X.509 certificates of trusted time stamp + counter-signers. + + @retval EFI_SUCCESS Signed hash was verified against caller-provided + hash of content, the signer's certificate was not + found in RevokedDb, and was found in AllowedDb or + if in signer is found in both AllowedDb and + RevokedDb, the signing was allowed by reference to + TimeStampDb as described above, and no hash matching + content hash was found in RevokedDb. + @retval EFI_SECURITY_VIOLATION The SignedData buffer was correctly formatted but + signer was in RevokedDb or not in AllowedDb. Also + returned if matching content hash found in RevokedDb. + @retval EFI_COMPROMISED_DATA Caller provided hash differs from signed hash. Or, + caller and encrypted hash are different sizes. + @retval EFI_INVALID_PARAMETER Signature is NULL or SignatureSize is zero. InHash + is NULL or InHashSize is zero. AllowedDb is NULL. + @retval EFI_ABORTED Unsupported or invalid format in TimeStampDb, + RevokedDb or AllowedDb list contents was detected. + @retval EFI_UNSUPPORTED The Signature buffer was not correctly formatted + for processing by the function. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_PKCS7_VERIFY_SIGNATURE) ( + IN EFI_PKCS7_VERIFY_PROTOCOL *This, + IN VOID *Signature, + IN UINTN SignatureSize, + IN VOID *InHash, + IN UINTN InHashSize, + IN EFI_SIGNATURE_LIST **AllowedDb, + IN EFI_SIGNATURE_LIST **RevokedDb OPTIONAL, + IN EFI_SIGNATURE_LIST **TimeStampDb OPTIONAL + ); + +/// +/// The EFI_PKCS7_VERIFY_PROTOCOL is used to verify data signed using PKCS7 +/// structure. The PKCS7 data to be verified must be ASN.1 (DER) encoded. +/// SHA256 must be supported as digest algorithm with RSA digest encryption. +/// Support of other hash algorithms is optional. +/// +struct _EFI_PKCS7_VERIFY_PROTOCOL { + EFI_PKCS7_VERIFY_BUFFER VerifyBuffer; + EFI_PKCS7_VERIFY_SIGNATURE VerifySignature; +}; + +extern EFI_GUID gEfiPkcs7VerifyProtocolGuid; + +#endif diff --git a/MdePkg/MdePkg.dec b/MdePkg/MdePkg.dec index a6f8b4fe26..245b6896c3 100644 --- a/MdePkg/MdePkg.dec +++ b/MdePkg/MdePkg.dec @@ -1530,6 +1530,9 @@ ## Include/Protocol/EapConfiguration.h gEfiEapConfigurationProtocolGuid = { 0xe5b58dbb, 0x7688, 0x44b4, {0x97, 0xbf, 0x5f, 0x1d, 0x4b, 0x7c, 0xc8, 0xdb }} + ## Include/Protocol/Pkcs7Verify.h + gEfiPkcs7VerifyProtocolGuid = { 0x47889fb2, 0xd671, 0x4fab, { 0xa0, 0xca, 0xdf, 0x0e, 0x44, 0xdf, 0x70, 0xd6 }} + # # [Error.gEfiMdePkgTokenSpaceGuid] # 0x80000001 | Invalid value provided. -- 2.39.2