MdePkg/Include/Protocol/Bis.h

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