MdePkg/Include/Protocol/Bis.h

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