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