#include <Guid/ImageAuthentication.h>

Data Structures
struct	_EFI_PKCS7_VERIFY_PROTOCOL

Macros
#define	EFI_PKCS7_VERIFY_PROTOCOL_GUID

Typedefs
typedef struct _EFI_PKCS7_VERIFY_PROTOCOL	EFI_PKCS7_VERIFY_PROTOCOL

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)

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)

Variables
EFI_GUID	gEfiPkcs7VerifyProtocolGuid

Detailed Description

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.
SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file Pkcs7Verify.h.

Macro Definition Documentation

◆ EFI_PKCS7_VERIFY_PROTOCOL_GUID

#define EFI_PKCS7_VERIFY_PROTOCOL_GUID

Value:

  { \
    0x47889fb2, 0xd671, 0x4fab, {0xa0, 0xca, 0xdf, 0x0e, 0x44, 0xdf, 0x70, 0xd6 } \
  }

Global ID for the PKCS7 Verification Protocol

Definition at line 22 of file Pkcs7Verify.h.

Typedef Documentation

◆ EFI_PKCS7_VERIFY_BUFFER

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 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.

Parameters

[in]	This	Pointer to EFI_PKCS7_VERIFY_PROTOCOL instance.
[in]	SignedData	Points to buffer containing ASN.1 DER-encoded PKCS7 signature.
[in]	SignedDataSize	The size of SignedData buffer in bytes.
[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.
[in]	InDataSize	When InData is used, the size of InData buffer in bytes. When InData is NULL. This parameter must be 0.
[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.
[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.
[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.
[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.
[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.

Return values

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.
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.
EFI_COMPROMISED_DATA	Calculated hash differs from signed hash.
EFI_INVALID_PARAMETER	SignedData is NULL or SignedDataSize is zero. AllowedDb is NULL.
EFI_INVALID_PARAMETER	Content is not NULL and ContentSize is NULL.
EFI_ABORTED	Unsupported or invalid format in TimeStampDb, RevokedDb or AllowedDb list contents was detected.
EFI_NOT_FOUND	Content not found because InData is NULL and no content embedded in SignedData.
EFI_UNSUPPORTED	The SignedData buffer was not correctly formatted for processing by the function.
EFI_UNSUPPORTED	Signed data embedded in SignedData but InData is not NULL.
EFI_BUFFER_TOO_SMALL	The size of buffer indicated by ContentSize is too small to hold the content. ContentSize updated to required size.

Definition at line 116 of file Pkcs7Verify.h.

◆ EFI_PKCS7_VERIFY_PROTOCOL

typedef struct _EFI_PKCS7_VERIFY_PROTOCOL EFI_PKCS7_VERIFY_PROTOCOL

Definition at line 27 of file Pkcs7Verify.h.

◆ EFI_PKCS7_VERIFY_SIGNATURE

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)

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).

Parameters

[in]	This	Pointer to EFI_PKCS7_VERIFY_PROTOCOL instance.
[in]	Signature	Points to buffer containing ASN.1 DER-encoded PKCS detached signature.
[in]	SignatureSize	The size of Signature buffer in bytes.
[in]	InHash	InHash points to buffer containing the caller calculated hash of the data. The parameter may not be NULL.
[in]	InHashSize	The size in bytes of InHash buffer.
[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.
[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.
[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.

Return values

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.
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.
EFI_COMPROMISED_DATA	Caller provided hash differs from signed hash. Or, caller and encrypted hash are different sizes.
EFI_INVALID_PARAMETER	Signature is NULL or SignatureSize is zero. InHash is NULL or InHashSize is zero. AllowedDb is NULL.
EFI_ABORTED	Unsupported or invalid format in TimeStampDb, RevokedDb or AllowedDb list contents was detected.
EFI_UNSUPPORTED	The Signature buffer was not correctly formatted for processing by the function.

Definition at line 197 of file Pkcs7Verify.h.

Data Structures

Macros

Typedefs