/** @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 - 2017, Intel Corporation. All rights reserved.<BR> | |
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 <Guid/ImageAuthentication.h> | |
/// | |
/// 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. | |
Note: because this function uses hashes and the specification contains a variety of | |
hash choices, you should be aware that the check against the RevokedDb list | |
will improperly succeed if the signature is revoked using a different hash | |
algorithm. For this reason, you should either cycle through all UEFI supported | |
hashes to see if one is forbidden, or rely on a single hash choice only if the | |
UEFI signature authority only signs and revokes with a single hash (at time | |
of writing, this hash choice is SHA256). | |
@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 |