MdePkg:Add UEFI 2.5 PKCS7 Verification Protocol Definition
authorLong Qin <qin.long@intel.com>
Thu, 4 Jun 2015 07:10:17 +0000 (07:10 +0000)
committerqlong <qlong@Edk2>
Thu, 4 Jun 2015 07:10:17 +0000 (07:10 +0000)
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Long Qin <qin.long@intel.com>
Reviewed-by: Chao Zhang <chao.b.zhang@intel.com>
git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@17560 6f19259b-4bc3-4df7-8a09-765794883524

MdePkg/Include/Protocol/Pkcs7Verify.h [new file with mode: 0644]
MdePkg/MdePkg.dec

diff --git a/MdePkg/Include/Protocol/Pkcs7Verify.h b/MdePkg/Include/Protocol/Pkcs7Verify.h
new file mode 100644 (file)
index 0000000..ca5ec75
--- /dev/null
@@ -0,0 +1,221 @@
+/** @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
index a6f8b4fe26513977d5ca1ba4fff9d703f35d8f9c..245b6896c3c437e7cfdb876f0931b0d74e849234 100644 (file)
   ## Include/Protocol/EapConfiguration.h\r
   gEfiEapConfigurationProtocolGuid     = { 0xe5b58dbb, 0x7688, 0x44b4, {0x97, 0xbf, 0x5f, 0x1d, 0x4b, 0x7c, 0xc8, 0xdb }}\r
 \r
+  ## Include/Protocol/Pkcs7Verify.h\r
+  gEfiPkcs7VerifyProtocolGuid          = { 0x47889fb2, 0xd671, 0x4fab, { 0xa0, 0xca, 0xdf, 0x0e, 0x44, 0xdf, 0x70, 0xd6 }}\r
+\r
 #\r
 # [Error.gEfiMdePkgTokenSpaceGuid]\r
 #   0x80000001 | Invalid value provided.\r