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