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 typedef struct _EFI_BIS_PROTOCOL  EFI_BIS_PROTOCOL;
  24
  25
  26 //
  27 // Basic types
  28 //
  29 typedef VOID    *BIS_APPLICATION_HANDLE;
  30 typedef UINT16  BIS_ALG_ID;
  31 typedef UINT32  BIS_CERT_ID;
  32
  33 //
  34 // EFI_BIS_DATA type.
  35 //
  36 // EFI_BIS_DATA instances obtained from BIS must be freed by calling Free( ).
  37 //
  38 typedef struct {
  39   UINT32  Length; // Length of Data in 8 bit bytes.
  40   UINT8   *Data;  // 32 Bit Flat Address of data.
  41 } EFI_BIS_DATA;
  42
  43 //
  44 // EFI_BIS_VERSION type.
  45 //
  46 typedef struct {
  47   UINT32  Major;  // BIS Interface version number.
  48   UINT32  Minor;  // Build number.
  49 } EFI_BIS_VERSION;
  50
  51 //
  52 // ----------------------------------------------------//
  53 // Use these values to initialize EFI_BIS_VERSION.Major
  54 // and to interpret results of Initialize.
  55 // ----------------------------------------------------//
  56 //
  57 #define BIS_CURRENT_VERSION_MAJOR BIS_VERSION_1
  58 #define BIS_VERSION_1             1
  59
  60 //
  61 // EFI_BIS_SIGNATURE_INFO type.
  62 //
  63 typedef struct {
  64   BIS_CERT_ID CertificateID;  // Truncated hash of platform Boot Object
  65   //  authorization certificate.
  66   //
  67   BIS_ALG_ID  AlgorithmID;  // A signature algorithm number.
  68   UINT16      KeyLength;    // Length of alg. keys in bits.
  69 } EFI_BIS_SIGNATURE_INFO;
  70
  71 //
  72 // Currently defined values for EFI_BIS_SIGNATURE_INFO.AlgorithmID.
  73 // The exact numeric values come from
  74 //    "Common Data Security Architecture (CDSA) Specification".
  75 //
  76 #define BIS_ALG_DSA     (41)  // CSSM_ALGID_DSA
  77 #define BIS_ALG_RSA_MD5 (42)  // CSSM_ALGID_MD5_WITH_RSA
  78 // Currently defined values for EFI_BIS_SIGNATURE_INFO.CertificateId.
  79 //
  80 #define BIS_CERT_ID_DSA     BIS_ALG_DSA     // CSSM_ALGID_DSA
  81 #define BIS_CERT_ID_RSA_MD5 BIS_ALG_RSA_MD5 // CSSM_ALGID_MD5_WITH_RSA
  82 // The  following  is a mask value that gets applied to the truncated hash of a
  83 // platform  Boot Object Authorization Certificate to create the certificateID.
  84 // A certificateID must not have any bits set to the value 1 other than bits in
  85 // this mask.
  86 //
  87 #define BIS_CERT_ID_MASK  (0xFF7F7FFF)
  88
  89 //
  90 // Macros for dealing with the EFI_BIS_DATA object obtained
  91 // from BIS_GetSignatureInfo()
  92 // BIS_GET_SIGINFO_COUNT - tells how many EFI_BIS_SIGNATURE_INFO
  93 //  elements are contained in a EFI_BIS_DATA struct pointed to
  94 //  by the provided EFI_BIS_DATA*.
  95 //
  96 #define BIS_GET_SIGINFO_COUNT(BisDataPtr) ((BisDataPtr)->Length / sizeof (EFI_BIS_SIGNATURE_INFO))
  97
  98 //
  99 // BIS_GET_SIGINFO_ARRAY - produces a EFI_BIS_SIGNATURE_INFO*
 100 //  from a given EFI_BIS_DATA*.
 101 //
 102 #define BIS_GET_SIGINFO_ARRAY(BisDataPtr) ((EFI_BIS_SIGNATURE_INFO *) (BisDataPtr)->Data)
 103
 104 //
 105 // Binary Value of "X-Intel-BIS-ParameterSet" Attribute.
 106 // (Value is Base64 encoded in actual signed manifest).
 107 // {EDD35E31-07B9-11d2-83A3-00A0C91FADCF}
 108 //
 109 #define BOOT_OBJECT_AUTHORIZATION_PARMSET_GUID \
 110   { \
 111     0xedd35e31, 0x7b9, 0x11d2, \
 112     { \
 113       0x83, 0xa3, 0x0, 0xa0, 0xc9, 0x1f, 0xad, 0xcf \
 114     } \
 115   }
 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
 136   @param  TargetAddress            Indicates a network or device address of the BIS platform to connect to.
 137
 138   @retval EFI_SUCCESS              The function completed successfully.
 139   @retval EFI_INCOMPATIBLE_VERSION The InterfaceVersion.Major requested by the
 140                                    caller was not compatible with the interface version of the
 141   @retval EFI_UNSUPPORTED          This is a local-platform implementation and
 142                                    TargetAddress.Data was not NULL, or
 143                                    TargetAddress.Data was any other value that was not
 144                                    supported by the implementation.
 145   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 146   @retval EFI_DEVICE_ERROR         The function encountered an unexpected internal failure.
 147   @retval EFI_INVALID_PARAMETER    One or more parameters are invalid.
 148
 149 **/
 150 typedef
 151 EFI_STATUS
 152 (EFIAPI *EFI_BIS_INITIALIZE) (
 153   IN     EFI_BIS_PROTOCOL        *This,
 154   OUT    BIS_APPLICATION_HANDLE  *AppHandle,
 155   IN OUT EFI_BIS_VERSION         *InterfaceVersion,
 156   IN     EFI_BIS_DATA            *TargetAddress
 157   );
 158
 159 /**
 160   Frees memory structures allocated and returned by other functions in the EFI_BIS protocol.
 161
 162   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization
 163                                    of the BIS service.
 164   @param  ToFree                   An EFI_BIS_DATA* and associated memory block to be freed.
 165
 166   @retval EFI_SUCCESS              The function completed successfully.
 167   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid
 168                                    application instance handle associated with the EFI_BIS protocol.
 169   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 170   @retval EFI_INVALID_PARAMETER    The ToFree parameter is not or is no longer a memory resource
 171                                    associated with this AppHandle.
 172
 173 **/
 174 typedef
 175 EFI_STATUS
 176 (EFIAPI *EFI_BIS_FREE) (
 177   IN BIS_APPLICATION_HANDLE  AppHandle,
 178   IN EFI_BIS_DATA            *ToFree
 179   );
 180
 181 /**
 182   Shuts down an application's instance of the BIS service, invalidating the application handle. After
 183   this call, other BIS functions may no longer be invoked using the application handle value.
 184
 185   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization
 186                                    of the BIS service.
 187
 188   @retval EFI_SUCCESS              The function completed successfully.
 189   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid
 190                                    application instance handle associated with the EFI_BIS protocol.
 191   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 192   @retval EFI_DEVICE_ERROR         The function encountered an unexpected internal failure.
 193
 194 **/
 195 typedef
 196 EFI_STATUS
 197 (EFIAPI *EFI_BIS_SHUTDOWN) (
 198   IN BIS_APPLICATION_HANDLE  AppHandle
 199   );
 200
 201 /**
 202   Retrieves the certificate that has been configured as the identity of the organization designated as
 203   the source of authorization for signatures of boot objects.
 204
 205   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization
 206                                    of the BIS service.
 207   @param  Certificate              The function writes an allocated EFI_BIS_DATA* containing the Boot
 208                                    Object Authorization Certificate object.
 209
 210   @retval EFI_SUCCESS              The function completed successfully.
 211   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid
 212                                    application instance handle associated with the EFI_BIS protocol.
 213   @retval EFI_NOT_FOUND            There is no Boot Object Authorization Certificate currently installed.
 214   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 215   @retval EFI_INVALID_PARAMETER    The Certificate parameter supplied by the caller is NULL or
 216                                    an invalid memory reference.
 217
 218 **/
 219 typedef
 220 EFI_STATUS
 221 (EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE) (
 222   IN  BIS_APPLICATION_HANDLE  AppHandle,
 223   OUT EFI_BIS_DATA            **Certificate
 224   );
 225
 226 /**
 227   Verifies the integrity and authorization of the indicated data object according to the
 228   indicated credentials.
 229
 230   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization
 231                                    of the BIS service.
 232   @param  Credentials              A Signed Manifest containing verification information for the indicated
 233                                    data object.
 234   @param  DataObject               An in-memory copy of the raw data object to be verified.
 235   @param  IsVerified               The function writes TRUE if the verification succeeded, otherwise
 236                                    FALSE.
 237
 238   @retval EFI_SUCCESS              The function completed successfully.
 239   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid
 240                                    application instance handle associated with the EFI_BIS protocol.
 241   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 242   @retval EFI_INVALID_PARAMETER    One or more parameters are invalid.
 243   @retval EFI_SECURITY_VIOLATION   The signed manifest supplied as the Credentials parameter
 244                                    was invalid (could not be parsed) or Platform-specific authorization failed, etc.
 245   @retval EFI_DEVICE_ERROR         An unexpected internal error occurred.
 246
 247 **/
 248 typedef
 249 EFI_STATUS
 250 (EFIAPI *EFI_BIS_VERIFY_BOOT_OBJECT) (
 251   IN  BIS_APPLICATION_HANDLE AppHandle,
 252   IN  EFI_BIS_DATA           *Credentials,
 253   IN  EFI_BIS_DATA           *DataObject,
 254   OUT BOOLEAN                *IsVerified
 255   );
 256
 257 /**
 258   Retrieves the current status of the Boot Authorization Check Flag.
 259
 260   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization
 261                                    of the BIS service.
 262   @param  CheckIsRequired          The function writes the value TRUE if a Boot Authorization Check is
 263                                    currently required on this platform, otherwise the function writes
 264                                    FALSE.
 265
 266   @retval EFI_SUCCESS              The function completed successfully.
 267   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid
 268                                    application instance handle associated with the EFI_BIS protocol.
 269   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 270   @retval EFI_INVALID_PARAMETER    The CheckIsRequired parameter supplied by the caller is
 271                                    NULL or an invalid memory reference.
 272
 273 **/
 274 typedef
 275 EFI_STATUS
 276 (EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG) (
 277   IN  BIS_APPLICATION_HANDLE  AppHandle,
 278   OUT BOOLEAN                 *CheckIsRequired
 279   );
 280
 281 /**
 282   Retrieves a unique token value to be included in the request credential for the next update of any
 283   parameter in the Boot Object Authorization set
 284
 285   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization
 286                                    of the BIS service.
 287   @param  UpdateToken              The function writes an allocated EFI_BIS_DATA* containing the new
 288                                    unique update token value.
 289
 290   @retval EFI_SUCCESS              The function completed successfully.
 291   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid
 292                                    application instance handle associated with the EFI_BIS protocol.
 293   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 294   @retval EFI_INVALID_PARAMETER    The UpdateToken parameter supplied by the caller is NULL or
 295                                    an invalid memory reference.
 296   @retval EFI_DEVICE_ERROR         An unexpected internal error occurred.
 297
 298 **/
 299 typedef
 300 EFI_STATUS
 301 (EFIAPI *EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN) (
 302   IN  BIS_APPLICATION_HANDLE  AppHandle,
 303   OUT EFI_BIS_DATA            **UpdateToken
 304   );
 305
 306 /**
 307   Updates one of the configurable parameters of the Boot Object Authorization set.
 308
 309   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization
 310                                    of the BIS service.
 311   @param  RequestCredential        This is a Signed Manifest with embedded attributes that carry the details
 312                                    of the requested update.
 313   @param  NewUpdateToken           The function writes an allocated EFI_BIS_DATA* containing the new
 314                                    unique update token value.
 315
 316   @retval EFI_SUCCESS              The function completed successfully.
 317   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid
 318                                    application instance handle associated with the EFI_BIS protocol.
 319   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 320   @retval EFI_INVALID_PARAMETER    One or more parameters are invalid.
 321   @retval EFI_SECURITY_VIOLATION   The signed manifest supplied as the RequestCredential parameter
 322                                    was invalid (could not be parsed) or Platform-specific authorization failed, etc.
 323   @retval EFI_DEVICE_ERROR         An unexpected internal error occurred.
 324
 325 **/
 326 typedef
 327 EFI_STATUS
 328 (EFIAPI *EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION) (
 329   IN  BIS_APPLICATION_HANDLE AppHandle,
 330   IN  EFI_BIS_DATA           *RequestCredential,
 331   OUT EFI_BIS_DATA           **NewUpdateToken
 332   );
 333
 334 /**
 335   Verifies the integrity and authorization of the indicated data object according to the indicated
 336   credentials and authority certificate.
 337
 338   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization
 339                                    of the BIS service.
 340   @param  Credentials              A Signed Manifest containing verification information for the
 341                                    indicated data object.
 342   @param  DataObject               An in-memory copy of the raw data object to be verified.
 343   @param  SectionName              An ASCII (not Unicode) string giving the section name in the
 344                                    manifest holding the verification information (in other words,
 345                                    hash value) that corresponds to DataObject.
 346   @param  AuthorityCertificate     A digital certificate whose public key must match the signer's
 347                                    public key which is found in the credentials.
 348   @param  IsVerified               The function writes TRUE if the verification was successful.
 349                                    Otherwise, the function writes FALSE.
 350
 351   @retval EFI_SUCCESS              The function completed successfully.
 352   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid
 353                                    application instance handle associated with the EFI_BIS protocol.
 354   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 355   @retval EFI_INVALID_PARAMETER    One or more parameters are invalid.
 356   @retval EFI_SECURITY_VIOLATION   The Credentials.Data supplied by the caller is NULL,
 357                                    or the AuthorityCertificate supplied by the caller was
 358                                    invalid (could not be parsed),
 359                                    or Platform-specific authorization failed, etc.
 360   @retval EFI_DEVICE_ERROR         An unexpected internal error occurred.
 361
 362 **/
 363 typedef
 364 EFI_STATUS
 365 (EFIAPI *EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL) (
 366   IN  BIS_APPLICATION_HANDLE AppHandle,
 367   IN  EFI_BIS_DATA           *Credentials,
 368   IN  EFI_BIS_DATA           *DataObject,
 369   IN  EFI_BIS_DATA           *SectionName,
 370   IN  EFI_BIS_DATA           *AuthorityCertificate,
 371   OUT BOOLEAN                *IsVerified
 372   );
 373
 374 /**
 375   Retrieves a list of digital certificate identifier, digital signature algorithm, hash algorithm, and keylength
 376   combinations that the platform supports.
 377
 378   @param  AppHandle                An opaque handle that identifies the caller's instance of initialization
 379                                    of the BIS service.
 380   @param  SignatureInfo            The function writes an allocated EFI_BIS_DATA* containing the array
 381                                    of EFI_BIS_SIGNATURE_INFO structures representing the supported
 382                                    digital certificate identifier, algorithm, and key length combinations.
 383
 384   @retval EFI_SUCCESS              The function completed successfully.
 385   @retval EFI_NO_MAPPING           The AppHandle parameter is not or is no longer a valid
 386                                    application instance handle associated with the EFI_BIS protocol.
 387   @retval EFI_OUT_OF_RESOURCES     The function failed due to lack of memory or other resources.
 388   @retval EFI_INVALID_PARAMETER    The SignatureInfo parameter supplied by the caller is NULL
 389                                    or an invalid memory reference.
 390   @retval EFI_DEVICE_ERROR         An unexpected internal error occurred.
 391
 392 **/
 393 typedef
 394 EFI_STATUS
 395 (EFIAPI *EFI_BIS_GET_SIGNATURE_INFO) (
 396   IN  BIS_APPLICATION_HANDLE  AppHandle,
 397   OUT EFI_BIS_DATA            **SignatureInfo
 398   );
 399
 400 struct _EFI_BIS_PROTOCOL {
 401   EFI_BIS_INITIALIZE                                  Initialize;
 402   EFI_BIS_SHUTDOWN                                    Shutdown;
 403   EFI_BIS_FREE                                        Free;
 404   EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CERTIFICATE   GetBootObjectAuthorizationCertificate;
 405   EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_CHECKFLAG     GetBootObjectAuthorizationCheckFlag;
 406   EFI_BIS_GET_BOOT_OBJECT_AUTHORIZATION_UPDATE_TOKEN  GetBootObjectAuthorizationUpdateToken;
 407   EFI_BIS_GET_SIGNATURE_INFO                          GetSignatureInfo;
 408   EFI_BIS_UPDATE_BOOT_OBJECT_AUTHORIZATION            UpdateBootObjectAuthorization;
 409   EFI_BIS_VERIFY_BOOT_OBJECT                          VerifyBootObject;
 410   EFI_BIS_VERIFY_OBJECT_WITH_CREDENTIAL               VerifyObjectWithCredential;
 411 };
 412
 413 extern EFI_GUID gEfiBisProtocolGuid;
 414 extern EFI_GUID gBootObjectAuthorizationParmsetGuid;
 415
 416 #endif