1 /** @file 2 EFI_PKCS7_VERIFY_PROTOCOL as defined in UEFI 2.5. 3 The EFI_PKCS7_VERIFY_PROTOCOL is used to verify data signed using PKCS#7 4 formatted authentication. The PKCS#7 data to be verified must be binary 5 DER encoded. 6 PKCS#7 is a general-purpose cryptographic standard (defined by RFC2315, 7 available at http://tools.ietf.org/html/rfc2315). 8 9 Copyright (c) 2015, Intel Corporation. All rights reserved.<BR> 10 This program and the accompanying materials are licensed and made available under 11 the terms and conditions of the BSD License that accompanies this distribution. 12 The full text of the license may be found at 13 http://opensource.org/licenses/bsd-license.php. 14 15 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 16 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 17 18 **/ 19 20 #ifndef __EFI_PKCS7_VERIFY_PROTOCOL_H__ 21 #define __EFI_PKCS7_VERIFY_PROTOCOL_H__ 22 23 #include <Guid/ImageAuthentication.h> 24 25 /// 26 /// Global ID for the PKCS7 Verification Protocol 27 /// 28 #define EFI_PKCS7_VERIFY_PROTOCOL_GUID \ 29 { \ 30 0x47889fb2, 0xd671, 0x4fab, {0xa0, 0xca, 0xdf, 0x0e, 0x44, 0xdf, 0x70, 0xd6 } \ 31 } 32 33 typedef struct _EFI_PKCS7_VERIFY_PROTOCOL EFI_PKCS7_VERIFY_PROTOCOL; 34 35 36 /** 37 Processes a buffer containing binary DER-encoded PKCS7 signature. 38 The signed data content may be embedded within the buffer or separated. Funtion 39 verifies the signature of the content is valid and signing certificate was not 40 revoked and is contained within a list of trusted signers. 41 42 @param[in] This Pointer to EFI_PKCS7_VERIFY_PROTOCOL instance. 43 @param[in] SignedData Points to buffer containing ASN.1 DER-encoded PKCS7 44 signature. 45 @param[in] SignedDataSize The size of SignedData buffer in bytes. 46 @param[in] InData In case of detached signature, InData points to 47 buffer containing the raw message data previously 48 signed and to be verified by function. In case of 49 SignedData containing embedded data, InData must be 50 NULL. 51 @param[in] InDataSize When InData is used, the size of InData buffer in 52 bytes. When InData is NULL. This parameter must be 53 0. 54 @param[in] AllowedDb Pointer to a list of pointers to EFI_SIGNATURE_LIST 55 structures. The list is terminated by a null 56 pointer. The EFI_SIGNATURE_LIST structures contain 57 lists of X.509 certificates of approved signers. 58 Function recognizes signer certificates of type 59 EFI_CERT_X509_GUID. Any hash certificate in AllowedDb 60 list is ignored by this function. Function returns 61 success if signer of the buffer is within this list 62 (and not within RevokedDb). This parameter is 63 required. 64 @param[in] RevokedDb Optional pointer to a list of pointers to 65 EFI_SIGNATURE_LIST structures. The list is terminated 66 by a null pointer. List of X.509 certificates of 67 revoked signers and revoked file hashes. Except as 68 noted in description of TimeStampDb signature 69 verification will always fail if the signer of the 70 file or the hash of the data component of the buffer 71 is in RevokedDb list. This list is optional and 72 caller may pass Null or pointer to NULL if not 73 required. 74 @param[in] TimeStampDb Optional pointer to a list of pointers to 75 EFI_SIGNATURE_LIST structures. The list is terminated 76 by a null pointer. This parameter can be used to pass 77 a list of X.509 certificates of trusted time stamp 78 signers. This list is optional and caller must pass 79 Null or pointer to NULL if not required. 80 @param[out] Content On input, points to an optional caller-allocated 81 buffer into which the function will copy the content 82 portion of the file after verification succeeds. 83 This parameter is optional and if NULL, no copy of 84 content from file is performed. 85 @param[in,out] ContentSize On input, points to the size in bytes of the optional 86 buffer Content previously allocated by caller. On 87 output, if the verification succeeds, the value 88 referenced by ContentSize will contain the actual 89 size of the content from signed file. If ContentSize 90 indicates the caller-allocated buffer is too small 91 to contain content, an error is returned, and 92 ContentSize will be updated with the required size. 93 This parameter must be 0 if Content is Null. 94 95 @retval EFI_SUCCESS Content signature was verified against hash of 96 content, the signer's certificate was not found in 97 RevokedDb, and was found in AllowedDb or if in signer 98 is found in both AllowedDb and RevokedDb, the 99 signing was allowed by reference to TimeStampDb as 100 described above, and no hash matching content hash 101 was found in RevokedDb. 102 @retval EFI_SECURITY_VIOLATION The SignedData buffer was correctly formatted but 103 signer was in RevokedDb or not in AllowedDb. Also 104 returned if matching content hash found in RevokedDb. 105 @retval EFI_COMPROMISED_DATA Calculated hash differs from signed hash. 106 @retval EFI_INVALID_PARAMETER SignedData is NULL or SignedDataSize is zero. 107 AllowedDb is NULL. 108 @retval EFI_INVALID_PARAMETER Content is not NULL and ContentSize is NULL. 109 @retval EFI_ABORTED Unsupported or invalid format in TimeStampDb, 110 RevokedDb or AllowedDb list contents was detected. 111 @retval EFI_NOT_FOUND Content not found because InData is NULL and no 112 content embedded in SignedData. 113 @retval EFI_UNSUPPORTED The SignedData buffer was not correctly formatted 114 for processing by the function. 115 @retval EFI_UNSUPPORTED Signed data embedded in SignedData but InData is not 116 NULL. 117 @retval EFI_BUFFER_TOO_SMALL The size of buffer indicated by ContentSize is too 118 small to hold the content. ContentSize updated to 119 required size. 120 121 **/ 122 typedef 123 EFI_STATUS 124 (EFIAPI *EFI_PKCS7_VERIFY_BUFFER) ( 125 IN EFI_PKCS7_VERIFY_PROTOCOL *This, 126 IN VOID *SignedData, 127 IN UINTN SignedDataSize, 128 IN VOID *InData OPTIONAL, 129 IN UINTN InDataSize, 130 IN EFI_SIGNATURE_LIST **AllowedDb, 131 IN EFI_SIGNATURE_LIST **RevokedDb OPTIONAL, 132 IN EFI_SIGNATURE_LIST **TimeStampDb OPTIONAL, 133 OUT VOID *Content OPTIONAL, 134 IN OUT UINTN *ContentSize 135 ); 136 137 /** 138 Processes a buffer containing binary DER-encoded detached PKCS7 signature. 139 The hash of the signed data content is calculated and passed by the caller. Function 140 verifies the signature of the content is valid and signing certificate was not revoked 141 and is contained within a list of trusted signers. 142 143 @param[in] This Pointer to EFI_PKCS7_VERIFY_PROTOCOL instance. 144 @param[in] Signature Points to buffer containing ASN.1 DER-encoded PKCS 145 detached signature. 146 @param[in] SignatureSize The size of Signature buffer in bytes. 147 @param[in] InHash InHash points to buffer containing the caller 148 calculated hash of the data. The parameter may not 149 be NULL. 150 @param[in] InHashSize The size in bytes of InHash buffer. 151 @param[in] AllowedDb Pointer to a list of pointers to EFI_SIGNATURE_LIST 152 structures. The list is terminated by a null 153 pointer. The EFI_SIGNATURE_LIST structures contain 154 lists of X.509 certificates of approved signers. 155 Function recognizes signer certificates of type 156 EFI_CERT_X509_GUID. Any hash certificate in AllowedDb 157 list is ignored by this function. Function returns 158 success if signer of the buffer is within this list 159 (and not within RevokedDb). This parameter is 160 required. 161 @param[in] RevokedDb Optional pointer to a list of pointers to 162 EFI_SIGNATURE_LIST structures. The list is terminated 163 by a null pointer. List of X.509 certificates of 164 revoked signers and revoked file hashes. Signature 165 verification will always fail if the signer of the 166 file or the hash of the data component of the buffer 167 is in RevokedDb list. This parameter is optional 168 and caller may pass Null if not required. 169 @param[in] TimeStampDb Optional pointer to a list of pointers to 170 EFI_SIGNATURE_LIST structures. The list is terminated 171 by a null pointer. This parameter can be used to pass 172 a list of X.509 certificates of trusted time stamp 173 counter-signers. 174 175 @retval EFI_SUCCESS Signed hash was verified against caller-provided 176 hash of content, the signer's certificate was not 177 found in RevokedDb, and was found in AllowedDb or 178 if in signer is found in both AllowedDb and 179 RevokedDb, the signing was allowed by reference to 180 TimeStampDb as described above, and no hash matching 181 content hash was found in RevokedDb. 182 @retval EFI_SECURITY_VIOLATION The SignedData buffer was correctly formatted but 183 signer was in RevokedDb or not in AllowedDb. Also 184 returned if matching content hash found in RevokedDb. 185 @retval EFI_COMPROMISED_DATA Caller provided hash differs from signed hash. Or, 186 caller and encrypted hash are different sizes. 187 @retval EFI_INVALID_PARAMETER Signature is NULL or SignatureSize is zero. InHash 188 is NULL or InHashSize is zero. AllowedDb is NULL. 189 @retval EFI_ABORTED Unsupported or invalid format in TimeStampDb, 190 RevokedDb or AllowedDb list contents was detected. 191 @retval EFI_UNSUPPORTED The Signature buffer was not correctly formatted 192 for processing by the function. 193 194 **/ 195 typedef 196 EFI_STATUS 197 (EFIAPI *EFI_PKCS7_VERIFY_SIGNATURE) ( 198 IN EFI_PKCS7_VERIFY_PROTOCOL *This, 199 IN VOID *Signature, 200 IN UINTN SignatureSize, 201 IN VOID *InHash, 202 IN UINTN InHashSize, 203 IN EFI_SIGNATURE_LIST **AllowedDb, 204 IN EFI_SIGNATURE_LIST **RevokedDb OPTIONAL, 205 IN EFI_SIGNATURE_LIST **TimeStampDb OPTIONAL 206 ); 207 208 /// 209 /// The EFI_PKCS7_VERIFY_PROTOCOL is used to verify data signed using PKCS7 210 /// structure. The PKCS7 data to be verified must be ASN.1 (DER) encoded. 211 /// SHA256 must be supported as digest algorithm with RSA digest encryption. 212 /// Support of other hash algorithms is optional. 213 /// 214 struct _EFI_PKCS7_VERIFY_PROTOCOL { 215 EFI_PKCS7_VERIFY_BUFFER VerifyBuffer; 216 EFI_PKCS7_VERIFY_SIGNATURE VerifySignature; 217 }; 218 219 extern EFI_GUID gEfiPkcs7VerifyProtocolGuid; 220 221 #endif 222
