MdePkg/Include/Protocol/Pkcs7Verify.h

   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 - 2017, 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   Note: because this function uses hashes and the specification contains a variety of
 144         hash choices, you should be aware that the check against the RevokedDb list
 145         will improperly succeed if the signature is revoked using a different hash
 146         algorithm.  For this reason, you should either cycle through all UEFI supported
 147         hashes to see if one is forbidden, or rely on a single hash choice only if the
 148         UEFI signature authority only signs and revokes with a single hash (at time
 149         of writing, this hash choice is SHA256).
 150
 151   @param[in]     This                 Pointer to EFI_PKCS7_VERIFY_PROTOCOL instance.
 152   @param[in]     Signature            Points to buffer containing ASN.1 DER-encoded PKCS
 153                                       detached signature.
 154   @param[in]     SignatureSize        The size of Signature buffer in bytes.
 155   @param[in]     InHash               InHash points to buffer containing the caller
 156                                       calculated hash of the data. The parameter may not
 157                                       be NULL.
 158   @param[in]     InHashSize           The size in bytes of InHash buffer.
 159   @param[in]     AllowedDb            Pointer to a list of pointers to EFI_SIGNATURE_LIST
 160                                       structures. The list is terminated by a null
 161                                       pointer. The EFI_SIGNATURE_LIST structures contain
 162                                       lists of X.509 certificates of approved signers.
 163                                       Function recognizes signer certificates of type
 164                                       EFI_CERT_X509_GUID. Any hash certificate in AllowedDb
 165                                       list is ignored by this function. Function returns
 166                                       success if signer of the buffer is within this list
 167                                       (and not within RevokedDb). This parameter is
 168                                       required.
 169   @param[in]     RevokedDb            Optional pointer to a list of pointers to
 170                                       EFI_SIGNATURE_LIST structures. The list is terminated
 171                                       by a null pointer. List of X.509 certificates of
 172                                       revoked signers and revoked file hashes. Signature
 173                                       verification will always fail if the signer of the
 174                                       file or the hash of the data component of the buffer
 175                                       is in RevokedDb list. This parameter is optional
 176                                       and caller may pass Null if not required.
 177   @param[in]     TimeStampDb          Optional pointer to a list of pointers to
 178                                       EFI_SIGNATURE_LIST structures. The list is terminated
 179                                       by a null pointer. This parameter can be used to pass
 180                                       a list of X.509 certificates of trusted time stamp
 181                                       counter-signers.
 182
 183   @retval EFI_SUCCESS                 Signed hash was verified against caller-provided
 184                                       hash of content, the signer's certificate was not
 185                                       found in RevokedDb, and was found in AllowedDb or
 186                                       if in signer is found in both AllowedDb and
 187                                       RevokedDb, the signing was allowed by reference to
 188                                       TimeStampDb as described above, and no hash matching
 189                                       content hash was found in RevokedDb.
 190   @retval EFI_SECURITY_VIOLATION      The SignedData buffer was correctly formatted but
 191                                       signer was in RevokedDb or not in AllowedDb. Also
 192                                       returned if matching content hash found in RevokedDb.
 193   @retval EFI_COMPROMISED_DATA        Caller provided hash differs from signed hash. Or,
 194                                       caller and encrypted hash are different sizes.
 195   @retval EFI_INVALID_PARAMETER       Signature is NULL or SignatureSize is zero. InHash
 196                                       is NULL or InHashSize is zero. AllowedDb is NULL.
 197   @retval EFI_ABORTED                 Unsupported or invalid format in TimeStampDb,
 198                                       RevokedDb or AllowedDb list contents was detected.
 199   @retval EFI_UNSUPPORTED             The Signature buffer was not correctly formatted
 200                                       for processing by the function.
 201
 202 **/
 203 typedef
 204 EFI_STATUS
 205 (EFIAPI *EFI_PKCS7_VERIFY_SIGNATURE) (
 206   IN EFI_PKCS7_VERIFY_PROTOCOL   *This,
 207   IN VOID                        *Signature,
 208   IN UINTN                       SignatureSize,
 209   IN VOID                        *InHash,
 210   IN UINTN                       InHashSize,
 211   IN EFI_SIGNATURE_LIST          **AllowedDb,
 212   IN EFI_SIGNATURE_LIST          **RevokedDb       OPTIONAL,
 213   IN EFI_SIGNATURE_LIST          **TimeStampDb     OPTIONAL
 214   );
 215
 216 ///
 217 /// The EFI_PKCS7_VERIFY_PROTOCOL is used to verify data signed using PKCS7
 218 /// structure. The PKCS7 data to be verified must be ASN.1 (DER) encoded.
 219 /// SHA256 must be supported as digest algorithm with RSA digest encryption.
 220 /// Support of other hash algorithms is optional.
 221 ///
 222 struct _EFI_PKCS7_VERIFY_PROTOCOL {
 223   EFI_PKCS7_VERIFY_BUFFER         VerifyBuffer;
 224   EFI_PKCS7_VERIFY_SIGNATURE      VerifySignature;
 225 };
 226
 227 extern EFI_GUID gEfiPkcs7VerifyProtocolGuid;
 228
 229 #endif