MdePkg/Include/Protocol/Bis.h

   1 /** @file
   2   The EFI_BIS_PROTOCOL is used to check a digital signature of a data block
   3   against a digital certificate for the purpose of an integrity and authorization check.
   4
   5 Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR>
   6 This program and the accompanying materials are licensed and made available under
   7 the terms and conditions of the BSD License that accompanies this distribution.
   8 The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php.
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14   @par Revision Reference:
  15   This Protocol is introduced in EFI Specification 1.10.
  16
  17 **/
  18
  19 #ifndef __BIS_H__
  20 #define __BIS_H__
  21
  22 #define EFI_BIS_PROTOCOL_GUID \
  23   { \
  24     0x0b64aab0, 0x5429, 0x11d4, {0x98, 0x16, 0x00, 0xa0, 0xc9, 0x1f, 0xad, 0xcf } \
  25   }
  26
  27 //
  28 // X-Intel-BIS-ParameterSet
  29 // Attribute value
  30 // Binary Value of X-Intel-BIS-ParameterSet Attribute.
  31 // (Value is Base-64 encoded in actual signed manifest).
  32 //
  33 #define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID \
  34   { \
  35     0xedd35e31, 0x7b9, 0x11d2, { 0x83,0xa3,0x0,0xa0,0xc9,0x1f,0xad,0xcf } \
  36   }
  37
  38
  39
  40 typedef struct _EFI_BIS_PROTOCOL  EFI_BIS_PROTOCOL;
  41
  42
  43 //
  44 // Basic types
  45 //
  46 typedef VOID    *BIS_APPLICATION_HANDLE;
  47 typedef UINT16  BIS_ALG_ID;
  48 typedef UINT32  BIS_CERT_ID;
  49
  50 ///
  51 /// EFI_BIS_DATA instances obtained from BIS must be freed by calling Free( ).
  52 ///
  53 typedef struct {
  54   UINT32  Length; ///< The length of Data in 8 bit bytes.
  55   UINT8   *Data;  ///< 32 Bit Flat Address of data.
  56 } EFI_BIS_DATA;
  57
  58 ///
  59 /// EFI_BIS_VERSION type.
  60 ///
  61 typedef struct {
  62   UINT32  Major;  ///< The major BIS version number.
  63   UINT32  Minor;  ///< A minor BIS version number.
  64 } EFI_BIS_VERSION;
  65
  66 //
  67 // ----------------------------------------------------//
  68 // Use these values to initialize EFI_BIS_VERSION.Major
  69 // and to interpret results of Initialize.
  70 // ----------------------------------------------------//
  71 //
  72 #define BIS_CURRENT_VERSION_MAJOR BIS_VERSION_1
  73 #define BIS_VERSION_1             1
  74
  75 ///
  76 /// EFI_BIS_SIGNATURE_INFO type.
  77 ///
  78 typedef struct {
  79   BIS_CERT_ID CertificateID;  ///< Truncated hash of platform Boot Object
  80   BIS_ALG_ID  AlgorithmID;    ///< A signature algorithm number.
  81   UINT16      KeyLength;      ///< The length of alg. keys in bits.
  82 } EFI_BIS_SIGNATURE_INFO;
  83
  84 ///
  85 /// values for EFI_BIS_SIGNATURE_INFO.AlgorithmID.
  86 /// The exact numeric values come from the
  87 ///    "Common Data Security Architecture (CDSA) Specification".
  88 ///
  89 #define BIS_ALG_DSA     (41)  // CSSM_ALGID_DSA
  90 #define BIS_ALG_RSA_MD5 (42)  // CSSM_ALGID_MD5_WITH_RSA
  91 ///
  92 /// values for EFI_BIS_SIGNATURE_INFO.CertificateId.
  93 ///
  94 #define BIS_CERT_ID_DSA     BIS_ALG_DSA     // CSSM_ALGID_DSA
  95 #define BIS_CERT_ID_RSA_MD5 BIS_ALG_RSA_MD5 // CSSM_ALGID_MD5_WITH_RSA
  96 ///
  97 /// The mask value that gets applied to the truncated hash of a
  98 /// platform  Boot Object Authorization Certificate to create the certificateID.
  99 /// A certificateID must not have any bits set to the value 1 other than bits in
 100 /// this mask.
 101 ///
 102 #define BIS_CERT_ID_MASK  (0xFF7F7FFF)
 103
 104 ///
 105 /// Macros for dealing with the EFI_BIS_DATA object obtained
 106 /// from BIS_GetSignatureInfo().
 107 /// BIS_GET_SIGINFO_COUNT - tells how many EFI_BIS_SIGNATURE_INFO
 108 ///  elements are contained in a EFI_BIS_DATA struct pointed to
 109 ///  by the provided EFI_BIS_DATA*.
 110 ///
 111 #define BIS_GET_SIGINFO_COUNT(BisDataPtr) ((BisDataPtr)->Length / sizeof (EFI_BIS_SIGNATURE_INFO))
 112
 113 ///
 114 /// BIS_GET_SIGINFO_ARRAY - produces a EFI_BIS_SIGNATURE_INFO*
 115 ///  from a given EFI_BIS_DATA*.
 116 ///
 117 #define BIS_GET_SIGINFO_ARRAY(BisDataPtr) ((EFI_BIS_SIGNATURE_INFO *) (BisDataPtr)->Data)
 118
 119 ///
 120 /// Support an old name for backward compatibility.
 121 ///
 122 #define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUIDVALUE \
 123         BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID
 124
 125 /**
 126   Initializes the BIS service, checking that it is compatible with the version requested by the caller.
 127   After this call, other BIS functions may be invoked.
 128
 129   @param  This                     A pointer to the EFI_BIS_PROTOCOL object.
 130   @param  AppHandle                The function writes the new BIS_APPLICATION_HANDLE if
 131                                    successful, otherwise it writes NULL. The caller must eventually
 132                                    destroy this handle by calling Shutdown().
 133   @param  InterfaceVersion         On input, the caller supplies the major version number of the
 134                                    interface version desired.
 135                                    On output, both the major and minor
 136                                    version numbers are updated with the major and minor version
 137                                    numbers of the interface. This update is done whether or not the
 138                                    initialization was successful.
 139   @param  TargetAddress            Indicates a network or device address of the BIS platform to connect to.
 140
 141   @retval EFI_SUCCESS              The function completed successfully.
 142   @retval EFI_INCOMPATIBLE_VERSION The InterfaceVersion.Major requested by the
 143                                    caller was not compatible with the interface version of the
 144                                    implementation. The InterfaceVersion.Major has
 145                                    been updated with the current interface version.
 146   @retval EFI_UNSUPPORTED          This is a local-platform implementation and
 147                                    TargetAddress.Data was not NULL, or
 148                                    TargetAddress.Data was any other value that was not
 149                                    supported by the implementation.
 150   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 151   @retval EFI_DEVICE_ERROR         One of the following device errors:
 152                                    * The function encountered an unexpected internal failure while initializing a cryptographic software module
 153                                    * No cryptographic software module with compatible version was found
 154                                    found
 155                                    * A resource limitation was encountered while using a cryptographic software module.
 156   @retval EFI_INVALID_PARAMETER    The This parameter supplied by the caller is NULL or does not
 157                                    reference a valid EFI_BIS_PROTOCOL object. Or,
 158                                    the AppHandle parameter supplied by the caller is NULL or
 159                                    an invalid memory reference. Or,
 160                                    the InterfaceVersion parameter supplied by the caller
 161                                    is NULL or an invalid memory reference. Or,
 162                                    the TargetAddress parameter supplied by the caller is
 163                                    NULL or an invalid memory reference.
 164
 165 **/
 166 typedef
 167 EFI_STATUS
 168 (EFIAPI *EFI_BIS_INITIALIZE)(
 169   IN     EFI_BIS_PROTOCOL        *This,
 170   OUT    BIS_APPLICATION_HANDLE  *AppHandle,
 171   IN OUT EFI_BIS_VERSION         *InterfaceVersion,
 172   IN     EFI_BIS_DATA            *TargetAddress
 173   );
 174
 175 /**
 176   Frees memory structures allocated and returned by other functions in the EFI_BIS protocol.
 177
 178   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization
 179                                    of the BIS service.
 180   @param  ToFree                   An EFI_BIS_DATA* and associated memory block to be freed.
 181                                    This EFI_BIS_DATA* must have been allocated by one of the other BIS functions.
 182
 183   @retval EFI_SUCCESS              The function completed successfully.
 184   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid
 185                                    application instance handle associated with the EFI_BIS protocol.
 186   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 187   @retval EFI_INVALID_PARAMETER    The ToFree parameter is not or is no longer a memory resource
 188                                    associated with this AppHandle.
 189
 190 **/
 191 typedef
 192 EFI_STATUS
 193 (EFIAPI *EFI_BIS_FREE)(
 194   IN BIS_APPLICATION_HANDLE  AppHandle,
 195   IN EFI_BIS_DATA            *ToFree
 196   );
 197
 198 /**
 199   Shuts down an application's instance of the BIS service, invalidating the application handle. After
 200   this call, other BIS functions may no longer be invoked using the application handle value.
 201
 202   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization
 203                                    of the BIS service.
 204
 205   @retval EFI_SUCCESS              The function completed successfully.
 206   @retval EFI_NO_MAPPING           The AppHandle parameter is not, or is no longer, a valid
 207                                    application instance handle associated with the EFI_BIS protocol.
 208   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 209   @retval EFI_DEVICE_ERROR         The function encountered an unexpected internal failure while
 210                                    returning resources associated with a cryptographic software module, or
 211                                    while trying to shut down a cryptographic software module.
 212 **/
 213 typedef
 214 EFI_STATUS
 215 (EFIAPI *EFI_BIS_SHUTDOWN)(
 216   IN BIS_APPLICATION_HANDLE  AppHandle
 217   );
 218
 219 /**
 220   Retrieves the certificate that has been configured as the identity of the organization designated as
 221   the source of authorization for signatures of boot objects.
 222
 223   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization
 224                                    of the BIS service.
 225   @param  Certificate              The function writes an allocated EFI_BIS_DATA* containing the Boot
 226                                    Object Authorization Certificate object.  The caller must
 227                                    eventually free the memory allocated by this function using the function Free().
 228
 229   @retval EFI_SUCCESS              The function completed successfully.
 230   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid
 231                                    application instance handle associated with the EFI_BIS protocol.
 232   @retval EFI_NOT_FOUND            There is no Boot Object Authorization Certificate currently installed.
 233   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 234   @retval EFI_INVALID_PARAMETER    The Certificate parameter supplied by the caller is NULL or
 235                                    an invalid memory reference.
 236
 237 **/
 238 typedef
 239 EFI_STATUS
 240 (EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE)(
 241   IN  BIS_APPLICATION_HANDLE  AppHandle,
 242   OUT EFI_BIS_DATA            **Certificate
 243   );
 244
 245 /**
 246   Verifies the integrity and authorization of the indicated data object according to the
 247   indicated credentials.
 248
 249   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization
 250                                    of the BIS service.
 251   @param  Credentials              A Signed Manifest containing verification information for the indicated
 252                                    data object.
 253   @param  DataObject               An in-memory copy of the raw data object to be verified.
 254   @param  IsVerified               The function writes TRUE if the verification succeeded, otherwise
 255                                    FALSE.
 256
 257   @retval EFI_SUCCESS              The function completed successfully.
 258   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid
 259                                    application instance handle associated with the EFI_BIS protocol.
 260   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 261   @retval EFI_INVALID_PARAMETER    One or more parameters are invalid.
 262   @retval EFI_SECURITY_VIOLATION   The signed manifest supplied as the Credentials parameter
 263                                    was invalid (could not be parsed) or Platform-specific authorization failed, etc.
 264   @retval EFI_DEVICE_ERROR         An unexpected internal error occurred.
 265
 266 **/
 267 typedef
 268 EFI_STATUS
 269 (EFIAPI *EFI_BIS_VERIFY_BOOT_OBJECT)(
 270   IN  BIS_APPLICATION_HANDLE AppHandle,
 271   IN  EFI_BIS_DATA           *Credentials,
 272   IN  EFI_BIS_DATA           *DataObject,
 273   OUT BOOLEAN                *IsVerified
 274   );
 275
 276 /**
 277   Retrieves the current status of the Boot Authorization Check Flag.
 278
 279   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization
 280                                    of the BIS service.
 281   @param  CheckIsRequired          The function writes the value TRUE if a Boot Authorization Check is
 282                                    currently required on this platform, otherwise the function writes
 283                                    FALSE.
 284
 285   @retval EFI_SUCCESS              The function completed successfully.
 286   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid
 287                                    application instance handle associated with the EFI_BIS protocol.
 288   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 289   @retval EFI_INVALID_PARAMETER    The CheckIsRequired parameter supplied by the caller is
 290                                    NULL or an invalid memory reference.
 291
 292 **/
 293 typedef
 294 EFI_STATUS
 295 (EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG)(
 296   IN  BIS_APPLICATION_HANDLE  AppHandle,
 297   OUT BOOLEAN                 *CheckIsRequired
 298   );
 299
 300 /**
 301   Retrieves a unique token value to be included in the request credential for the next update of any
 302   parameter in the Boot Object Authorization set
 303
 304   @param  AppHandle                An opaque handle that identifies the caller's
 305                                    instance of initialization of the BIS service.
 306   @param  UpdateToken              The function writes an allocated EFI_BIS_DATA*
 307                                    containing the newunique update token value.
 308                                    The caller musteventually free the memory allocated
 309                                    by this function using the function Free().
 310
 311   @retval EFI_SUCCESS              The function completed successfully.
 312   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid
 313                                    application instance handle associated with the EFI_BIS protocol.
 314   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 315   @retval EFI_INVALID_PARAMETER    The UpdateToken parameter supplied by the caller is NULL or
 316                                    an invalid memory reference.
 317   @retval EFI_DEVICE_ERROR         An unexpected internal error occurred.
 318
 319 **/
 320 typedef
 321 EFI_STATUS
 322 (EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN)(
 323   IN  BIS_APPLICATION_HANDLE  AppHandle,
 324   OUT EFI_BIS_DATA            **UpdateToken
 325   );
 326
 327 /**
 328   Updates one of the configurable parameters of the Boot Object Authorization set.
 329
 330   @param  AppHandle                An opaque handle that identifies the caller's
 331                                    instance of initialization of the BIS service.
 332   @param  RequestCredential        This is a Signed Manifest with embedded attributes
 333                                    that carry the details of the requested update.
 334   @param  NewUpdateToken           The function writes an allocated EFI_BIS_DATA*
 335                                    containing the new unique update token value.
 336                                    The caller must eventually free the memory allocated
 337                                    by this function using the function Free().
 338
 339   @retval EFI_SUCCESS              The function completed successfully.
 340   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid
 341                                    application instance handle associated with the EFI_BIS protocol.
 342   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 343   @retval EFI_INVALID_PARAMETER    One or more parameters are invalid.
 344   @retval EFI_SECURITY_VIOLATION   The signed manifest supplied as the RequestCredential parameter
 345                                    was invalid (could not be parsed) or Platform-specific authorization failed, etc.
 346   @retval EFI_DEVICE_ERROR         An unexpected internal error occurred while analyzing the new
 347                                    certificate's key algorithm, or while attempting to retrieve
 348                                    the public key algorithm of the manifest's signer's certificate,
 349                                    or An unexpected internal error occurred in a cryptographic software module.
 350
 351 **/
 352 typedef
 353 EFI_STATUS
 354 (EFIAPI *EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION)(
 355   IN  BIS_APPLICATION_HANDLE AppHandle,
 356   IN  EFI_BIS_DATA           *RequestCredential,
 357   OUT EFI_BIS_DATA           **NewUpdateToken
 358   );
 359
 360 /**
 361   Verifies the integrity and authorization of the indicated data object according to the indicated
 362   credentials and authority certificate.
 363
 364   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization
 365                                    of the BIS service.
 366   @param  Credentials              A Signed Manifest containing verification information for the
 367                                    indicated data object.
 368   @param  DataObject               An in-memory copy of the raw data object to be verified.
 369   @param  SectionName              An ASCII string giving the section name in the
 370                                    manifest holding the verification information (in other words,
 371                                    hash value) that corresponds to DataObject.
 372   @param  AuthorityCertificate     A digital certificate whose public key must match the signer's
 373                                    public key which is found in the credentials.
 374   @param  IsVerified               The function writes TRUE if the verification was successful.
 375                                    Otherwise, the function writes FALSE.
 376
 377   @retval EFI_SUCCESS              The function completed successfully.
 378   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid
 379                                    application instance handle associated with the EFI_BIS protocol.
 380   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 381   @retval EFI_INVALID_PARAMETER    One or more parameters are invalid.
 382   @retval EFI_SECURITY_VIOLATION   The Credentials.Data supplied by the caller is NULL,
 383                                    or the AuthorityCertificate supplied by the caller was
 384                                    invalid (could not be parsed),
 385                                    or Platform-specific authorization failed, etc.
 386   @retval EFI_DEVICE_ERROR         An unexpected internal error occurred while attempting to retrieve
 387                                    the public key algorithm of the manifest's signer's certificate,
 388                                    or An unexpected internal error occurred in a cryptographic software module.
 389 **/
 390 typedef
 391 EFI_STATUS
 392 (EFIAPI *EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL)(
 393   IN  BIS_APPLICATION_HANDLE AppHandle,
 394   IN  EFI_BIS_DATA           *Credentials,
 395   IN  EFI_BIS_DATA           *DataObject,
 396   IN  EFI_BIS_DATA           *SectionName,
 397   IN  EFI_BIS_DATA           *AuthorityCertificate,
 398   OUT BOOLEAN                *IsVerified
 399   );
 400
 401 /**
 402   Retrieves a list of digital certificate identifier, digital signature algorithm, hash algorithm, and keylength
 403   combinations that the platform supports.
 404
 405   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization
 406                                    of the BIS service.
 407   @param  SignatureInfo            The function writes an allocated EFI_BIS_DATA* containing the array
 408                                    of EFI_BIS_SIGNATURE_INFO structures representing the supported
 409                                    digital certificate identifier, algorithm, and key length combinations.
 410                                    The caller must eventually free the memory allocated by this function using the function Free().
 411
 412   @retval EFI_SUCCESS              The function completed successfully.
 413   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid
 414                                    application instance handle associated with the EFI_BIS protocol.
 415   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 416   @retval EFI_INVALID_PARAMETER    The SignatureInfo parameter supplied by the caller is NULL
 417                                    or an invalid memory reference.
 418   @retval EFI_DEVICE_ERROR         An unexpected internal error occurred in a
 419                                    cryptographic software module, or
 420                                    The function encountered an unexpected internal consistency check
 421                                    failure (possible corruption of stored Boot Object Authorization Certificate).
 422
 423 **/
 424 typedef
 425 EFI_STATUS
 426 (EFIAPI *EFI_BIS_GET_SIGNATURE_INFO)(
 427   IN  BIS_APPLICATION_HANDLE  AppHandle,
 428   OUT EFI_BIS_DATA            **SignatureInfo
 429   );
 430
 431 ///
 432 /// The EFI_BIS_PROTOCOL is used to check a digital signature of a data block against a digital
 433 /// certificate for the purpose of an integrity and authorization check.
 434 ///
 435 struct _EFI_BIS_PROTOCOL {
 436   EFI_BIS_INITIALIZE                                  Initialize;
 437   EFI_BIS_SHUTDOWN                                    Shutdown;
 438   EFI_BIS_FREE                                        Free;
 439   EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE   GetBootObjectAuthorizationCertificate;
 440   EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG     GetBootObjectAuthorizationCheckFlag;
 441   EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN  GetBootObjectAuthorizationUpdateToken;
 442   EFI_BIS_GET_SIGNATURE_INFO                          GetSignatureInfo;
 443   EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION            UpdateBootObjectAuthorization;
 444   EFI_BIS_VERIFY_BOOT_OBJECT                          VerifyBootObject;
 445   EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL               VerifyObjectWithCredential;
 446 };
 447
 448 extern EFI_GUID gEfiBisProtocolGuid;
 449 extern EFI_GUID gBootObjectAuthorizationParmsetGuid;
 450
 451 #endif