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 452