[mirror_edk2.git] / MdePkg / Include / Protocol / Pkcs7Verify.h

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