1 /** @file 2 The Key Management Service (KMS) protocol as defined in the UEFI 2.3.1 specification is to 3 provides services to generate, store, retrieve, and manage cryptographic keys. 4 The intention is to specify a simple generic protocol that could be used for many implementations. 5 6 A driver implementing the protocol may need to provide basic key service that consists of a 7 key store and cryptographic key generation capability. It may connect to an external key 8 server over the network, or to a Hardware Security Module (HSM) attached to the system it 9 runs on, or anything else that is capable of providing the key management service. 10 11 Copyright (c) 2011, Intel Corporation. All rights reserved.<BR> 12 This program and the accompanying materials are licensed and made available under 13 the terms and conditions of the BSD License that accompanies this distribution. 14 The full text of the license may be found at 15 http://opensource.org/licenses/bsd-license.php. 16 17 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 18 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 19 20 **/ 21 22 #ifndef __KMS_H__ 23 #define __KMS_H__ 24 25 #define EFI_KMS_PROTOCOL_GUID \ 26 { \ 27 0xEC3A978D, 0x7C4E, 0x48FA, {0x9A, 0xBE, 0x6A, 0xD9, 0x1C, 0xC8, 0xF8, 0x11 } \ 28 } 29 30 typedef struct _EFI_KMS_PROTOCOL EFI_KMS_PROTOCOL; 31 32 // 33 // Where appropriate, EFI_KMS_DATA_TYPE values may be combined using a bitwise 'OR' 34 // operation to indicate support for multiple data types. 35 // 36 #define EFI_KMS_DATA_TYPE_NONE 0 37 #define EFI_KMS_DATA_TYPE_BINARY 1 38 #define EFI_KMS_DATA_TYPE_ASCII 2 39 #define EFI_KMS_DATA_TYPE_UNICODE 4 40 #define EFI_KMS_DATA_TYPE_UTF8 8 41 42 43 // 44 // The key formats recognized by the KMS protocol are defined by an EFI_GUID which specifies 45 // a (key-algorithm, key-size) pair. The names of these GUIDs are in the format 46 // EFI_KMS_KEY_(key-algorithm)_(key-size)_GUID, where the key-size is expressed in bits. 47 // The key formats recognized fall into three categories, generic (no algorithm), hash algorithms, 48 // and encrypted algorithms. 49 // 50 51 /// 52 /// The following GUIDs define formats that contain generic key data of a specific size in bits, 53 /// but which is not associated with any specific key algorithm(s). 54 ///@{ 55 #define EFI_KMS_FORMAT_GENERIC_128_GUID \ 56 { \ 57 0xec8a3d69, 0x6ddf, 0x4108, {0x94, 0x76, 0x73, 0x37, 0xfc, 0x52, 0x21, 0x36 } \ 58 } 59 #define EFI_KMS_FORMAT_GENERIC_160_GUID \ 60 { \ 61 0xa3b3e6f8, 0xefca, 0x4bc1, {0x88, 0xfb, 0xcb, 0x87, 0x33, 0x9b, 0x25, 0x79 } \ 62 } 63 #define EFI_KMS_FORMAT_GENERIC_256_GUID \ 64 { \ 65 0x70f64793, 0xc323, 0x4261, {0xac, 0x2c, 0xd8, 0x76, 0xf2, 0x7c, 0x53, 0x45 } \ 66 } 67 #define EFI_KMS_FORMAT_GENERIC_512_GUID \ 68 { \ 69 0x978fe043, 0xd7af, 0x422e, {0x8a, 0x92, 0x2b, 0x48, 0xe4, 0x63, 0xbd, 0xe6 } \ 70 } 71 #define EFI_KMS_FORMAT_GENERIC_1024_GUID \ 72 { \ 73 0x43be0b44, 0x874b, 0x4ead, {0xb0, 0x9c, 0x24, 0x1a, 0x4f, 0xbd, 0x7e, 0xb3 } \ 74 } 75 #define EFI_KMS_FORMAT_GENERIC_2048_GUID \ 76 { \ 77 0x40093f23, 0x630c, 0x4626, {0x9c, 0x48, 0x40, 0x37, 0x3b, 0x19, 0xcb, 0xbe } \ 78 } 79 #define EFI_KMS_FORMAT_GENERIC_3072_GUID \ 80 { \ 81 0xb9237513, 0x6c44, 0x4411, {0xa9, 0x90, 0x21, 0xe5, 0x56, 0xe0, 0x5a, 0xde } \ 82 } 83 ///@} 84 85 /// 86 /// These GUIDS define key data formats that contain data generated by basic hash algorithms 87 /// with no cryptographic properties. 88 ///@{ 89 #define EFI_KMS_FORMAT_MD2_128_GUID \ 90 { \ 91 0x78be11c4, 0xee44, 0x4a22, {0x9f, 0x05, 0x03, 0x85, 0x2e, 0xc5, 0xc9, 0x78 } \ 92 } 93 #define EFI_KMS_FORMAT_MDC2_128_GUID \ 94 { \ 95 0xf7ad60f8, 0xefa8, 0x44a3, {0x91, 0x13, 0x23, 0x1f, 0x39, 0x9e, 0xb4, 0xc7 } \ 96 } 97 #define EFI_KMS_FORMAT_MD4_128_GUID \ 98 { \ 99 0xd1c17aa1, 0xcac5, 0x400f, {0xbe, 0x17, 0xe2, 0xa2, 0xae, 0x06, 0x67, 0x7c } \ 100 } 101 #define EFI_KMS_FORMAT_MDC4_128_GUID \ 102 { \ 103 0x3fa4f847, 0xd8eb, 0x4df4, {0xbd, 0x49, 0x10, 0x3a, 0x0a, 0x84, 0x7b, 0xbc } \ 104 } 105 #define EFI_KMS_FORMAT_MD5_128_GUID \ 106 { \ 107 0xdcbc3662, 0x9cda, 0x4b52, {0xa0, 0x4c, 0x82, 0xeb, 0x1d, 0x23, 0x48, 0xc7 } \ 108 } 109 #define EFI_KMS_FORMAT_MD5SHA_128_GUID \ 110 { \ 111 0x1c178237, 0x6897, 0x459e, {0x9d, 0x36, 0x67, 0xce, 0x8e, 0xf9, 0x4f, 0x76 } \ 112 } 113 #define EFI_KMS_FORMAT_SHA1_160_GUID \ 114 { \ 115 0x453c5e5a, 0x482d, 0x43f0, {0x87, 0xc9, 0x59, 0x41, 0xf3, 0xa3, 0x8a, 0xc2 } \ 116 } 117 #define EFI_KMS_FORMAT_SHA256_256_GUID \ 118 { \ 119 0x6bb4f5cd, 0x8022, 0x448d, {0xbc, 0x6d, 0x77, 0x1b, 0xae, 0x93, 0x5f, 0xc6 } \ 120 } 121 #define EFI_KMS_FORMAT_SHA512_512_GUID \ 122 { \ 123 0x2f240e12, 0xe14d, 0x475c, {0x83, 0xb0, 0xef, 0xff, 0x22, 0xd7, 0x7b, 0xe7 } \ 124 } 125 ///@} 126 127 /// 128 /// These GUIDs define key data formats that contain data generated by cryptographic key algorithms. 129 /// There may or may not be a separate data hashing algorithm associated with the key algorithm. 130 ///@{ 131 #define EFI_KMS_FORMAT_AESXTS_128_GUID \ 132 { \ 133 0x4776e33f, 0xdb47, 0x479a, {0xa2, 0x5f, 0xa1, 0xcd, 0x0a, 0xfa, 0xb3, 0x8b } \ 134 } 135 #define EFI_KMS_FORMAT_AESXTS_256_GUID \ 136 { \ 137 0xdc7e8613, 0xc4bb, 0x4db0, {0x84, 0x62, 0x13, 0x51, 0x13, 0x57, 0xab, 0xe2 } \ 138 } 139 #define EFI_KMS_FORMAT_AESCBC_128_GUID \ 140 { \ 141 0xa0e8ee6a, 0x0e92, 0x44d4, {0x86, 0x1b, 0x0e, 0xaa, 0x4a, 0xca, 0x44, 0xa2 } \ 142 } 143 #define EFI_KMS_FORMAT_AESCBC_256_GUID \ 144 { \ 145 0xd7e69789, 0x1f68, 0x45e8, {0x96, 0xef, 0x3b, 0x64, 0x07, 0xa5, 0xb2, 0xdc } \ 146 } 147 #define EFI_KMS_FORMAT_RSASHA1_1024_GUID \ 148 { \ 149 0x56417bed, 0x6bbe, 0x4882, {0x86, 0xa0, 0x3a, 0xe8, 0xbb, 0x17, 0xf8, 0xf9 } \ 150 } 151 #define EFI_KMS_FORMAT_RSASHA1_2048_GUID \ 152 { \ 153 0xf66447d4, 0x75a6, 0x463e, {0xa8, 0x19, 0x07, 0x7f, 0x2d, 0xda, 0x05, 0xe9 } \ 154 } 155 #define EFI_KMS_FORMAT_RSASHA256_2048_GUID \ 156 { \ 157 0xa477af13, 0x877d, 0x4060, {0xba, 0xa1, 0x25, 0xd1, 0xbe, 0xa0, 0x8a, 0xd3 } \ 158 } 159 #define EFI_KMS_FORMAT_RSASHA256_3072_GUID \ 160 { \ 161 0x4e1356c2, 0xeed, 0x463f, {0x81, 0x47, 0x99, 0x33, 0xab, 0xdb, 0xc7, 0xd5 } \ 162 } 163 ///@} 164 165 #define EFI_KMS_ATTRIBUTE_TYPE_NONE 0x00 166 #define EFI_KMS_ATTRIBUTE_TYPE_INTEGER 0x01 167 #define EFI_KMS_ATTRIBUTE_TYPE_LONG_INTEGER 0x02 168 #define EFI_KMS_ATTRIBUTE_TYPE_BIG_INTEGER 0x03 169 #define EFI_KMS_ATTRIBUTE_TYPE_ENUMERATION 0x04 170 #define EFI_KMS_ATTRIBUTE_TYPE_BOOLEAN 0x05 171 #define EFI_KMS_ATTRIBUTE_TYPE_BYTE_STRING 0x06 172 #define EFI_KMS_ATTRIBUTE_TYPE_TEXT_STRING 0x07 173 #define EFI_KMS_ATTRIBUTE_TYPE_DATE_TIME 0x08 174 #define EFI_KMS_ATTRIBUTE_TYPE_INTERVAL 0x09 175 #define EFI_KMS_ATTRIBUTE_TYPE_STRUCTURE 0x0A 176 #define EFI_KMS_ATTRIBUTE_TYPE_DYNAMIC 0x0B 177 178 typedef struct { 179 /// 180 /// The size in bytes for the client identifier. 181 /// 182 UINT16 ClientIdSize; 183 /// 184 /// Pointer to a valid client identifier. 185 /// 186 VOID *ClientId; 187 /// 188 /// The client name string type used by this client. The string type set here must be one of 189 /// the string types reported in the ClientNameStringTypes field of the KMS protocol. If the 190 /// KMS does not support client names, this field should be set to EFI_KMS_DATA_TYPE_NONE. 191 /// 192 UINT8 ClientNameType; 193 /// 194 /// The size in characters for the client name. This field will be ignored if 195 /// ClientNameStringType is set to EFI_KMS_DATA_TYPE_NONE. Otherwise, it must contain 196 /// number of characters contained in the ClientName field. 197 /// 198 UINT8 ClientNameCount; 199 /// 200 /// Pointer to a client name. This field will be ignored if ClientNameStringType is set to 201 /// EFI_KMS_DATA_TYPE_NONE. Otherwise, it must point to a valid string of the specified type. 202 /// 203 VOID *ClientName; 204 } EFI_KMS_CLIENT_INFO; 205 206 typedef struct { 207 /// 208 /// The size of the KeyIdentifier field in bytes. This field is limited to the range 0 to 255. 209 /// 210 UINT8 KeyIdentifierSize; 211 /// 212 /// Pointer to an array of KeyIdentifierType elements. 213 /// 214 VOID *KeyIdentifier; 215 /// 216 /// An EFI_GUID which specifies the algorithm and key value size for this key. 217 /// 218 EFI_GUID KeyFormat; 219 /// 220 /// Pointer to a key value for a key specified by the KeyFormat field. A NULL value for this 221 /// field indicates that no key is available. 222 /// 223 VOID *KeyValue; 224 /// 225 /// Specifies the results of KMS operations performed with this descriptor. This field is used 226 /// to indicate the status of individual operations when a KMS function is called with multiple 227 /// EFI_KMS_KEY_DESCRIPTOR structures. 228 /// KeyStatus codes returned for the individual key requests are: 229 /// EFI_SUCCESS Successfully processed this key. 230 /// EFI_WARN_STALE_DATA Successfully processed this key, however, the key's parameters 231 /// exceed internal policies/limits and should be replaced. 232 /// EFI_COMPROMISED_DATA Successfully processed this key, but the key may have been 233 /// compromised and must be replaced. 234 /// EFI_UNSUPPORTED Key format is not supported by the service. 235 /// EFI_OUT_OF_RESOURCES Could not allocate resources for the key processing. 236 /// EFI_TIMEOUT Timed out waiting for device or key server. 237 /// EFI_DEVICE_ERROR Device or key server error. 238 /// EFI_INVALID_PARAMETER KeyFormat is invalid. 239 /// EFI_NOT_FOUND The key does not exist on the KMS. 240 /// 241 EFI_STATUS KeyStatus; 242 } EFI_KMS_KEY_DESCRIPTOR; 243 244 typedef struct { 245 /// 246 /// Part of a tag-type-length triplet that identifies the KeyAttributeData formatting. The 247 /// definition of the value is outside the scope of this standard and may be defined by the KMS. 248 /// 249 UINT16 Tag; 250 /// 251 /// Part of a tag-type-length triplet that identifies the KeyAttributeData formatting. The 252 /// definition of the value is outside the scope of this standard and may be defined by the KMS. 253 /// 254 UINT16 Type; 255 /// 256 /// Length in bytes of the KeyAttributeData. 257 /// 258 UINT32 Length; 259 /// 260 /// An array of bytes to hold the attribute data associated with the KeyAttributeIdentifier. 261 /// 262 UINT8 KeyAttributeData[1]; 263 } EFI_KMS_DYNAMIC_FIELD; 264 265 typedef struct { 266 /// 267 /// The number of members in the EFI_KMS_DYNAMIC_ATTRIBUTE structure. 268 /// 269 UINT32 FieldCount; 270 /// 271 /// An array of EFI_KMS_DYNAMIC_FIELD structures. 272 /// 273 EFI_KMS_DYNAMIC_FIELD Field[1]; 274 } EFI_KMS_DYNAMIC_ATTRIBUTE; 275 276 typedef struct { 277 /// 278 /// The data type used for the KeyAttributeIdentifier field. Values for this field are defined 279 /// by the EFI_KMS_DATA_TYPE constants, except that EFI_KMS_DATA_TYPE_BINARY is not 280 /// valid for this field. 281 /// 282 UINT8 KeyAttributeIdentifierType; 283 /// 284 /// The length of the KeyAttributeIdentifier field in units defined by KeyAttributeIdentifierType 285 /// field. This field is limited to the range 0 to 255. 286 /// 287 UINT8 KeyAttributeIdentifierCount; 288 /// 289 /// Pointer to an array of KeyAttributeIdentifierType elements. For string types, there must 290 /// not be a null-termination element at the end of the array. 291 /// 292 VOID *KeyAttributeIdentifier; 293 /// 294 /// The instance number of this attribute. If there is only one instance, the value is set to 295 /// one. If this value is set to 0xFFFF (all binary 1's) then this field should be ignored if an 296 /// output or treated as a wild card matching any value if it is an input. If the attribute is 297 /// stored with this field, it will match any attribute request regardless of the setting of the 298 /// field in the request. If set to 0xFFFF in the request, it will match any attribute with the 299 /// same KeyAttributeIdentifier. 300 /// 301 UINT16 KeyAttributeInstance; 302 /// 303 /// The data type of the KeyAttributeValue (e.g. struct, bool, etc.). See the list of 304 /// KeyAttributeType definitions. 305 /// 306 UINT16 KeyAttributeType; 307 /// 308 /// The size in bytes of the KeyAttribute field. A value of zero for this field indicates that no 309 /// key attribute value is available. 310 /// 311 UINT16 KeyAttributeValueSize; 312 /// 313 /// Pointer to a key attribute value for the attribute specified by the KeyAttributeIdentifier 314 /// field. If the KeyAttributeValueSize field is zero, then this field must be NULL. 315 /// 316 VOID *KeyAttributeValue; 317 /// 318 /// KeyAttributeStatusSpecifies the results of KMS operations performed with this attribute. 319 /// This field is used to indicate the status of individual operations when a KMS function is 320 /// called with multiple EFI_KMS_KEY_ATTRIBUTE structures. 321 /// KeyAttributeStatus codes returned for the individual key attribute requests are: 322 /// EFI_SUCCESS Successfully processed this request. 323 /// EFI_WARN_STALE_DATA Successfully processed this request, however, the key's 324 /// parameters exceed internal policies/limits and should be replaced. 325 /// EFI_COMPROMISED_DATA Successfully processed this request, but the key may have been 326 /// compromised and must be replaced. 327 /// EFI_UNSUPPORTED Key attribute format is not supported by the service. 328 /// EFI_OUT_OF_RESOURCES Could not allocate resources for the request processing. 329 /// EFI_TIMEOUT Timed out waiting for device or key server. 330 /// EFI_DEVICE_ERROR Device or key server error. 331 /// EFI_INVALID_PARAMETER A field in the EFI_KMS_KEY_ATTRIBUTE structure is invalid. 332 /// EFI_NOT_FOUND The key attribute does not exist on the KMS. 333 /// 334 EFI_STATUS KeyAttributeStatus; 335 } EFI_KMS_KEY_ATTRIBUTE; 336 337 /** 338 Get the current status of the key management service. 339 340 @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. 341 342 @retval EFI_SUCCESS The KMS is ready for use. 343 @retval EFI_NOT_READY No connection to the KMS is available. 344 @retval EFI_NO_MAPPING No valid connection configuration exists for the KMS. 345 @retval EFI_NO_RESPONSE No response was received from the KMS. 346 @retval EFI_DEVICE_ERROR An error occurred when attempting to access the KMS. 347 @retval EFI_INVALID_PARAMETER This is NULL. 348 349 **/ 350 typedef 351 EFI_STATUS 352 (EFIAPI *EFI_KMS_GET_SERVICE_STATUS) ( 353 IN EFI_KMS_PROTOCOL *This 354 ); 355 356 /** 357 Register client information with the supported KMS. 358 359 @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. 360 @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. 361 @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of 362 data specified by the ClientData parameter. This 363 parameter may be NULL, in which case the ClientData 364 parameter will be ignored and no data will be 365 transferred to or from the KMS. If the parameter is 366 not NULL, then ClientData must be a valid pointer. 367 If the value pointed to is 0, no data will be transferred 368 to the KMS, but data may be returned by the KMS. 369 For all non-zero values *ClientData will be transferred 370 to the KMS, which may also return data to the caller. 371 In all cases, the value upon return to the caller will 372 be the size of the data block returned to the caller, 373 which will be zero if no data is returned from the KMS. 374 @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of 375 *ClientDataSize that is to be passed directly to the 376 KMS if it supports the use of client data. This 377 parameter may be NULL if and only if the 378 ClientDataSize parameter is also NULL. Upon return to 379 the caller, *ClientData points to a block of data of 380 *ClientDataSize that was returned from the KMS. 381 If the returned value for *ClientDataSize is zero, 382 then the returned value for *ClientData must be NULL 383 and should be ignored by the caller. The KMS protocol 384 consumer is responsible for freeing all valid buffers 385 used for client data regardless of whether they are 386 allocated by the caller for input to the function or by 387 the implementation for output back to the caller. 388 389 @retval EFI_SUCCESS The client information has been accepted by the KMS. 390 @retval EFI_NOT_READY No connection to the KMS is available. 391 @retval EFI_NO_RESPONSE There was no response from the device or the key server. 392 @retval EFI_ACCESS_DENIED Access was denied by the device or the key server. 393 @retval EFI_DEVICE_ERROR An error occurred when attempting to access the KMS. 394 @retval EFI_OUT_OF_RESOURCES Required resources were not available to perform the function. 395 @retval EFI_INVALID_PARAMETER This is NULL. 396 @retval EFI_UNSUPPORTED The KMS does not support the use of client identifiers. 397 398 **/ 399 typedef 400 EFI_STATUS 401 (EFIAPI *EFI_KMS_REGISTER_CLIENT) ( 402 IN EFI_KMS_PROTOCOL *This, 403 IN EFI_KMS_CLIENT_INFO *Client, 404 IN OUT UINTN *ClientDataSize OPTIONAL, 405 IN OUT VOID **ClientData OPTIONAL 406 ); 407 408 /** 409 Request that the KMS generate one or more new keys and associate them with key identifiers. 410 The key value(s) is returned to the caller. 411 412 @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. 413 @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. 414 @param[in, out] KeyDescriptorCount Pointer to a count of the number of key descriptors to be 415 processed by this operation. On return, this number 416 will be updated with the number of key descriptors 417 successfully processed. 418 @param[in, out] KeyDescriptors Pointer to an array of EFI_KMS_KEY_DESCRIPTOR 419 structures which describe the keys to be generated. 420 On input, the KeyIdentifierSize and the KeyIdentifier 421 may specify an identifier to be used for the key, 422 but this is not required. The KeyFormat field must 423 specify a key format GUID reported as supported by 424 the KeyFormats field of the EFI_KMS_PROTOCOL. 425 The value for this field in the first key descriptor will 426 be considered the default value for subsequent key 427 descriptors requested in this operation if those key 428 descriptors have a NULL GUID in the key format field. 429 On output, the KeyIdentifierSize and KeyIdentifier fields 430 will specify an identifier for the key which will be either 431 the original identifier if one was provided, or an identifier 432 generated either by the KMS or the KMS protocol 433 implementation. The KeyFormat field will be updated 434 with the GUID used to generate the key if it was a 435 NULL GUID, and the KeyValue field will contain a pointer 436 to memory containing the key value for the generated 437 key. Memory for both the KeyIdentifier and the KeyValue 438 fields will be allocated with the BOOT_SERVICES_DATA 439 type and must be freed by the caller when it is no longer 440 needed. Also, the KeyStatus field must reflect the result 441 of the request relative to that key. 442 @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of 443 data specified by the ClientData parameter. This 444 parameter may be NULL, in which case the ClientData 445 parameter will be ignored and no data will be 446 transferred to or from the KMS. If the parameter is 447 not NULL, then ClientData must be a valid pointer. 448 If the value pointed to is 0, no data will be transferred 449 to the KMS, but data may be returned by the KMS. 450 For all non-zero values *ClientData will be transferred 451 to the KMS, which may also return data to the caller. 452 In all cases, the value upon return to the caller will 453 be the size of the data block returned to the caller, 454 which will be zero if no data is returned from the KMS. 455 @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of 456 *ClientDataSize that is to be passed directly to the 457 KMS if it supports the use of client data. This 458 parameter may be NULL if and only if the 459 ClientDataSize parameter is also NULL. Upon return to 460 the caller, *ClientData points to a block of data of 461 *ClientDataSize that was returned from the KMS. 462 If the returned value for *ClientDataSize is zero, 463 then the returned value for *ClientData must be NULL 464 and should be ignored by the caller. The KMS protocol 465 consumer is responsible for freeing all valid buffers 466 used for client data regardless of whether they are 467 allocated by the caller for input to the function or by 468 the implementation for output back to the caller. 469 470 @retval EFI_SUCCESS Successfully generated and retrieved all requested keys. 471 @retval EFI_UNSUPPORTED This function is not supported by the KMS. --OR-- 472 One (or more) of the key requests submitted is not supported by 473 the KMS. Check individual key request(s) to see which ones 474 may have been processed. 475 @retval EFI_OUT_OF_RESOURCES Required resources were not available to perform the function. 476 @retval EFI_TIMEOUT Timed out waiting for device or key server. Check individual key 477 request(s) to see which ones may have been processed. 478 @retval EFI_ACCESS_DENIED Access was denied by the device or the key server; OR a 479 ClientId is required by the server and either no id was 480 provided or an invalid id was provided. 481 @retval EFI_DEVICE_ERROR An error occurred when attempting to access the KMS. Check 482 individual key request(s) to see which ones may have been 483 processed. 484 @retval EFI_INVALID_PARAMETER This is NULL, ClientId is required but it is NULL, 485 KeyDescriptorCount is NULL, or Keys is NULL. 486 @retval EFI_NOT_FOUND One or more EFI_KMS_KEY_DESCRIPTOR structures 487 could not be processed properly. KeyDescriptorCount 488 contains the number of structures which were successfully 489 processed. Individual structures will reflect the status of the 490 processing for that structure. 491 492 **/ 493 typedef 494 EFI_STATUS 495 (EFIAPI *EFI_KMS_CREATE_KEY) ( 496 IN EFI_KMS_PROTOCOL *This, 497 IN EFI_KMS_CLIENT_INFO *Client, 498 IN OUT UINT16 *KeyDescriptorCount, 499 IN OUT EFI_KMS_KEY_DESCRIPTOR *KeyDescriptors, 500 IN OUT UINTN *ClientDataSize OPTIONAL, 501 IN OUT VOID **ClientData OPTIONAL 502 ); 503 504 /** 505 Retrieve an existing key. 506 507 @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. 508 @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. 509 @param[in, out] KeyDescriptorCount Pointer to a count of the number of key descriptors to be 510 processed by this operation. On return, this number 511 will be updated with the number of key descriptors 512 successfully processed. 513 @param[in, out] KeyDescriptors Pointer to an array of EFI_KMS_KEY_DESCRIPTOR 514 structures which describe the keys to be retrieved 515 from the KMS. 516 On input, the KeyIdentifierSize and the KeyIdentifier 517 must specify an identifier to be used to retrieve a 518 specific key. All other fields in the descriptor should 519 be NULL. 520 On output, the KeyIdentifierSize and KeyIdentifier fields 521 will be unchanged, while the KeyFormat and KeyValue 522 fields will be updated values associated with this key 523 identifier. Memory for the KeyValue field will be 524 allocated with the BOOT_SERVICES_DATA type and 525 must be freed by the caller when it is no longer needed. 526 Also, the KeyStatus field will reflect the result of the 527 request relative to the individual key descriptor. 528 @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of 529 data specified by the ClientData parameter. This 530 parameter may be NULL, in which case the ClientData 531 parameter will be ignored and no data will be 532 transferred to or from the KMS. If the parameter is 533 not NULL, then ClientData must be a valid pointer. 534 If the value pointed to is 0, no data will be transferred 535 to the KMS, but data may be returned by the KMS. 536 For all non-zero values *ClientData will be transferred 537 to the KMS, which may also return data to the caller. 538 In all cases, the value upon return to the caller will 539 be the size of the data block returned to the caller, 540 which will be zero if no data is returned from the KMS. 541 @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of 542 *ClientDataSize that is to be passed directly to the 543 KMS if it supports the use of client data. This 544 parameter may be NULL if and only if the 545 ClientDataSize parameter is also NULL. Upon return to 546 the caller, *ClientData points to a block of data of 547 *ClientDataSize that was returned from the KMS. 548 If the returned value for *ClientDataSize is zero, 549 then the returned value for *ClientData must be NULL 550 and should be ignored by the caller. The KMS protocol 551 consumer is responsible for freeing all valid buffers 552 used for client data regardless of whether they are 553 allocated by the caller for input to the function or by 554 the implementation for output back to the caller. 555 556 @retval EFI_SUCCESS Successfully retrieved all requested keys. 557 @retval EFI_OUT_OF_RESOURCES Could not allocate resources for the method processing. 558 @retval EFI_TIMEOUT Timed out waiting for device or key server. Check individual key 559 request(s) to see which ones may have been processed. 560 @retval EFI_BUFFER_TOO_SMALL If multiple keys are associated with a single identifier, and the 561 KeyValue buffer does not contain enough structures 562 (KeyDescriptorCount) to contain all the key data, then 563 the available structures will be filled and 564 KeyDescriptorCount will be updated to indicate the 565 number of keys which could not be processed. 566 @retval EFI_ACCESS_DENIED Access was denied by the device or the key server; OR a 567 ClientId is required by the server and either none or an 568 invalid id was provided. 569 @retval EFI_DEVICE_ERROR Device or key server error. Check individual key request(s) to 570 see which ones may have been processed. 571 @retval EFI_INVALID_PARAMETER This is NULL, ClientId is required but it is NULL, 572 KeyDescriptorCount is NULL, or Keys is NULL. 573 @retval EFI_NOT_FOUND One or more EFI_KMS_KEY_DESCRIPTOR structures 574 could not be processed properly. KeyDescriptorCount 575 contains the number of structures which were successfully 576 processed. Individual structures will reflect the status of the 577 processing for that structure. 578 @retval EFI_UNSUPPORTED The implementation/KMS does not support this function. 579 580 **/ 581 typedef 582 EFI_STATUS 583 (EFIAPI *EFI_KMS_GET_KEY) ( 584 IN EFI_KMS_PROTOCOL *This, 585 IN EFI_KMS_CLIENT_INFO *Client, 586 IN OUT UINT16 *KeyDescriptorCount, 587 IN OUT EFI_KMS_KEY_DESCRIPTOR *KeyDescriptors, 588 IN OUT UINTN *ClientDataSize OPTIONAL, 589 IN OUT VOID **ClientData OPTIONAL 590 ); 591 592 /** 593 Add a new key. 594 595 @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. 596 @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. 597 @param[in, out] KeyDescriptorCount Pointer to a count of the number of key descriptors to be 598 processed by this operation. On normal return, this 599 number will be updated with the number of key 600 descriptors successfully processed. 601 @param[in, out] KeyDescriptors Pointer to an array of EFI_KMS_KEY_DESCRIPTOR 602 structures which describe the keys to be added. 603 On input, the KeyId field for first key must contain 604 valid identifier data to be used for adding a key to 605 the KMS. The values for these fields in this key 606 definition will be considered default values for 607 subsequent keys requested in this operation. A value 608 of 0 in any subsequent KeyId field will be replaced 609 with the current default value. The KeyFormat and 610 KeyValue fields for each key to be added must contain 611 consistent values to be associated with the given KeyId. 612 On return, the KeyStatus field will reflect the result 613 of the operation for each key request. 614 @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of 615 data specified by the ClientData parameter. This 616 parameter may be NULL, in which case the ClientData 617 parameter will be ignored and no data will be 618 transferred to or from the KMS. If the parameter is 619 not NULL, then ClientData must be a valid pointer. 620 If the value pointed to is 0, no data will be transferred 621 to the KMS, but data may be returned by the KMS. 622 For all non-zero values *ClientData will be transferred 623 to the KMS, which may also return data to the caller. 624 In all cases, the value upon return to the caller will 625 be the size of the data block returned to the caller, 626 which will be zero if no data is returned from the KMS. 627 @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of 628 *ClientDataSize that is to be passed directly to the 629 KMS if it supports the use of client data. This 630 parameter may be NULL if and only if the 631 ClientDataSize parameter is also NULL. Upon return to 632 the caller, *ClientData points to a block of data of 633 *ClientDataSize that was returned from the KMS. 634 If the returned value for *ClientDataSize is zero, 635 then the returned value for *ClientData must be NULL 636 and should be ignored by the caller. The KMS protocol 637 consumer is responsible for freeing all valid buffers 638 used for client data regardless of whether they are 639 allocated by the caller for input to the function or by 640 the implementation for output back to the caller. 641 642 @retval EFI_SUCCESS Successfully added all requested keys. 643 @retval EFI_OUT_OF_RESOURCES Could not allocate required resources. 644 @retval EFI_TIMEOUT Timed out waiting for device or key server. Check individual key 645 request(s) to see which ones may have been processed. 646 @retval EFI_BUFFER_TOO_SMALL If multiple keys are associated with a single identifier, and the 647 KeyValue buffer does not contain enough structures 648 (KeyDescriptorCount) to contain all the key data, then 649 the available structures will be filled and 650 KeyDescriptorCount will be updated to indicate the 651 number of keys which could not be processed 652 @retval EFI_ACCESS_DENIED Access was denied by the device or the key server; OR a 653 ClientId is required by the server and either none or an 654 invalid id was provided. 655 @retval EFI_DEVICE_ERROR Device or key server error. Check individual key request(s) to 656 see which ones may have been processed. 657 @retval EFI_INVALID_PARAMETER This is NULL, ClientId is required but it is NULL, 658 KeyDescriptorCount is NULL, or Keys is NULL. 659 @retval EFI_NOT_FOUND One or more EFI_KMS_KEY_DESCRIPTOR structures 660 could not be processed properly. KeyDescriptorCount 661 contains the number of structures which were successfully 662 processed. Individual structures will reflect the status of the 663 processing for that structure. 664 @retval EFI_UNSUPPORTED The implementation/KMS does not support this function. 665 666 **/ 667 typedef 668 EFI_STATUS 669 (EFIAPI *EFI_KMS_ADD_KEY) ( 670 IN EFI_KMS_PROTOCOL *This, 671 IN EFI_KMS_CLIENT_INFO *Client, 672 IN OUT UINT16 *KeyDescriptorCount, 673 IN OUT EFI_KMS_KEY_DESCRIPTOR *KeyDescriptors, 674 IN OUT UINTN *ClientDataSize OPTIONAL, 675 IN OUT VOID **ClientData OPTIONAL 676 ); 677 678 /** 679 Delete an existing key from the KMS database. 680 681 @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. 682 @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. 683 @param[in, out] KeyDescriptorCount Pointer to a count of the number of key descriptors to be 684 processed by this operation. On normal return, this 685 number will be updated with the number of key 686 descriptors successfully processed. 687 @param[in, out] KeyDescriptors Pointer to an array of EFI_KMS_KEY_DESCRIPTOR 688 structures which describe the keys to be deleted. 689 On input, the KeyId field for first key must contain 690 valid identifier data to be used for adding a key to 691 the KMS. The values for these fields in this key 692 definition will be considered default values for 693 subsequent keys requested in this operation. A value 694 of 0 in any subsequent KeyId field will be replaced 695 with the current default value. The KeyFormat and 696 KeyValue fields are ignored, but should be 0. 697 On return, the KeyStatus field will reflect the result 698 of the operation for each key request. 699 @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of 700 data specified by the ClientData parameter. This 701 parameter may be NULL, in which case the ClientData 702 parameter will be ignored and no data will be 703 transferred to or from the KMS. If the parameter is 704 not NULL, then ClientData must be a valid pointer. 705 If the value pointed to is 0, no data will be transferred 706 to the KMS, but data may be returned by the KMS. 707 For all non-zero values *ClientData will be transferred 708 to the KMS, which may also return data to the caller. 709 In all cases, the value upon return to the caller will 710 be the size of the data block returned to the caller, 711 which will be zero if no data is returned from the KMS. 712 @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of 713 *ClientDataSize that is to be passed directly to the 714 KMS if it supports the use of client data. This 715 parameter may be NULL if and only if the 716 ClientDataSize parameter is also NULL. Upon return to 717 the caller, *ClientData points to a block of data of 718 *ClientDataSize that was returned from the KMS. 719 If the returned value for *ClientDataSize is zero, 720 then the returned value for *ClientData must be NULL 721 and should be ignored by the caller. The KMS protocol 722 consumer is responsible for freeing all valid buffers 723 used for client data regardless of whether they are 724 allocated by the caller for input to the function or by 725 the implementation for output back to the caller. 726 727 @retval EFI_SUCCESS Successfully deleted all requested keys. 728 @retval EFI_OUT_OF_RESOURCES Could not allocate required resources. 729 @retval EFI_TIMEOUT Timed out waiting for device or key server. Check individual key 730 request(s) to see which ones may have been processed. 731 @retval EFI_ACCESS_DENIED Access was denied by the device or the key server; OR a 732 ClientId is required by the server and either none or an 733 invalid id was provided. 734 @retval EFI_DEVICE_ERROR Device or key server error. Check individual key request(s) to 735 see which ones may have been processed. 736 @retval EFI_INVALID_PARAMETER This is NULL, ClientId is required but it is NULL, 737 KeyDescriptorCount is NULL, or Keys is NULL. 738 @retval EFI_NOT_FOUND One or more EFI_KMS_KEY_DESCRIPTOR structures 739 could not be processed properly. KeyDescriptorCount 740 contains the number of structures which were successfully 741 processed. Individual structures will reflect the status of the 742 processing for that structure. 743 @retval EFI_UNSUPPORTED The implementation/KMS does not support this function. 744 745 **/ 746 typedef 747 EFI_STATUS 748 (EFIAPI *EFI_KMS_DELETE_KEY) ( 749 IN EFI_KMS_PROTOCOL *This, 750 IN EFI_KMS_CLIENT_INFO *Client, 751 IN OUT UINT16 *KeyDescriptorCount, 752 IN OUT EFI_KMS_KEY_DESCRIPTOR *KeyDescriptors, 753 IN OUT UINTN *ClientDataSize OPTIONAL, 754 IN OUT VOID **ClientData OPTIONAL 755 ); 756 757 /** 758 Get one or more attributes associated with a specified key identifier. 759 If none are found, the returned attributes count contains a value of zero. 760 761 @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. 762 @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. 763 @param[in] KeyIdentifierSize Pointer to the size in bytes of the KeyIdentifier variable. 764 @param[in] KeyIdentifier Pointer to the key identifier associated with this key. 765 @param[in, out] KeyAttributesCount Pointer to the number of EFI_KMS_KEY_ATTRIBUTE 766 structures associated with the Key identifier. If none 767 are found, the count value is zero on return. 768 On input this value reflects the number of KeyAttributes 769 that may be returned. 770 On output, the value reflects the number of completed 771 KeyAttributes structures found. 772 @param[in, out] KeyAttributes Pointer to an array of EFI_KMS_KEY_ATTRIBUTE 773 structures associated with the Key Identifier. 774 On input, the fields in the structure should be NULL. 775 On output, the attribute fields will have updated values 776 for attributes associated with this key identifier. 777 @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of 778 data specified by the ClientData parameter. This 779 parameter may be NULL, in which case the ClientData 780 parameter will be ignored and no data will be 781 transferred to or from the KMS. If the parameter is 782 not NULL, then ClientData must be a valid pointer. 783 If the value pointed to is 0, no data will be transferred 784 to the KMS, but data may be returned by the KMS. 785 For all non-zero values *ClientData will be transferred 786 to the KMS, which may also return data to the caller. 787 In all cases, the value upon return to the caller will 788 be the size of the data block returned to the caller, 789 which will be zero if no data is returned from the KMS. 790 @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of 791 *ClientDataSize that is to be passed directly to the 792 KMS if it supports the use of client data. This 793 parameter may be NULL if and only if the 794 ClientDataSize parameter is also NULL. Upon return to 795 the caller, *ClientData points to a block of data of 796 *ClientDataSize that was returned from the KMS. 797 If the returned value for *ClientDataSize is zero, 798 then the returned value for *ClientData must be NULL 799 and should be ignored by the caller. The KMS protocol 800 consumer is responsible for freeing all valid buffers 801 used for client data regardless of whether they are 802 allocated by the caller for input to the function or by 803 the implementation for output back to the caller. 804 805 @retval EFI_SUCCESS Successfully retrieved all key attributes. 806 @retval EFI_OUT_OF_RESOURCES Could not allocate resources for the method processing. 807 @retval EFI_TIMEOUT Timed out waiting for device or key server. Check individual key 808 attribute request(s) to see which ones may have been 809 processed. 810 @retval EFI_BUFFER_TOO_SMALL If multiple key attributes are associated with a single identifier, 811 and the KeyAttributes buffer does not contain enough 812 structures (KeyAttributesCount) to contain all the key 813 attributes data, then the available structures will be filled and 814 KeyAttributesCount will be updated to indicate the 815 number of key attributes which could not be processed. 816 @retval EFI_ACCESS_DENIED Access was denied by the device or the key server; OR a 817 ClientId is required by the server and either none or an 818 invalid id was provided. 819 @retval EFI_DEVICE_ERROR Device or key server error. Check individual key attribute 820 request(s) (i.e. key attribute status for each) to see which ones 821 may have been processed. 822 @retval EFI_INVALID_PARAMETER This is NULL, ClientId is required but it is NULL, 823 KeyIdentifierSize is NULL , or KeyIdentifier 824 is NULL, or KeyAttributes is NULL, or 825 KeyAttributesSize is NULL. 826 @retval EFI_NOT_FOUND The KeyIdentifier could not be found. 827 KeyAttributesCount contains zero. Individual 828 structures will reflect the status of the processing for that 829 structure. 830 @retval EFI_UNSUPPORTED The implementation/KMS does not support this function. 831 832 **/ 833 typedef 834 EFI_STATUS 835 (EFIAPI *EFI_KMS_GET_KEY_ATTRIBUTES) ( 836 IN EFI_KMS_PROTOCOL *This, 837 IN EFI_KMS_CLIENT_INFO *Client, 838 IN UINT8 *KeyIdentifierSize, 839 IN CONST VOID *KeyIdentifier, 840 IN OUT UINT16 *KeyAttributesCount, 841 IN OUT EFI_KMS_KEY_ATTRIBUTE *KeyAttributes, 842 IN OUT UINTN *ClientDataSize OPTIONAL, 843 IN OUT VOID **ClientData OPTIONAL 844 ); 845 846 /** 847 Add one or more attributes to a key specified by a key identifier. 848 849 @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. 850 @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. 851 @param[in] KeyIdentifierSize Pointer to the size in bytes of the KeyIdentifier variable. 852 @param[in] KeyIdentifier Pointer to the key identifier associated with this key. 853 @param[in, out] KeyAttributesCount Pointer to the number of EFI_KMS_KEY_ATTRIBUTE 854 structures to associate with the Key. On normal returns, 855 this number will be updated with the number of key 856 attributes successfully processed. 857 @param[in, out] KeyAttributes Pointer to an array of EFI_KMS_KEY_ATTRIBUTE 858 structures providing the attribute information to 859 associate with the key. 860 On input, the values for the fields in the structure 861 are completely filled in. 862 On return the KeyAttributeStatus field will reflect the 863 result of the operation for each key attribute request. 864 @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of 865 data specified by the ClientData parameter. This 866 parameter may be NULL, in which case the ClientData 867 parameter will be ignored and no data will be 868 transferred to or from the KMS. If the parameter is 869 not NULL, then ClientData must be a valid pointer. 870 If the value pointed to is 0, no data will be transferred 871 to the KMS, but data may be returned by the KMS. 872 For all non-zero values *ClientData will be transferred 873 to the KMS, which may also return data to the caller. 874 In all cases, the value upon return to the caller will 875 be the size of the data block returned to the caller, 876 which will be zero if no data is returned from the KMS. 877 @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of 878 *ClientDataSize that is to be passed directly to the 879 KMS if it supports the use of client data. This 880 parameter may be NULL if and only if the 881 ClientDataSize parameter is also NULL. Upon return to 882 the caller, *ClientData points to a block of data of 883 *ClientDataSize that was returned from the KMS. 884 If the returned value for *ClientDataSize is zero, 885 then the returned value for *ClientData must be NULL 886 and should be ignored by the caller. The KMS protocol 887 consumer is responsible for freeing all valid buffers 888 used for client data regardless of whether they are 889 allocated by the caller for input to the function or by 890 the implementation for output back to the caller. 891 892 @retval EFI_SUCCESS Successfully added all requested key attributes. 893 @retval EFI_OUT_OF_RESOURCES Could not allocate required resources. 894 @retval EFI_TIMEOUT Timed out waiting for device or key server. Check individual key 895 attribute request(s) to see which ones may have been 896 processed. 897 @retval EFI_BUFFER_TOO_SMALL If multiple keys attributes are associated with a single key 898 identifier, and the attributes buffer does not contain 899 enough structures (KeyAttributesCount) to contain all 900 the data, then the available structures will be filled and 901 KeyAttributesCount will be updated to indicate the 902 number of key attributes which could not be processed. The 903 status of each key attribute is also updated indicating success or 904 failure for that attribute in case there are other errors for those 905 attributes that could be processed. 906 @retval EFI_ACCESS_DENIED Access was denied by the device or the key server; OR a 907 ClientId is required by the server and either none or an 908 invalid id was provided. 909 @retval EFI_DEVICE_ERROR Device or key server error. Check individual key attribute 910 request(s) (i.e. key attribute status for each) to see which ones 911 may have been processed. 912 @retval EFI_INVALID_PARAMETER This is NULL, ClientId is required but it is NULL, 913 KeyAttributesCount is NULL, or KeyAttributes 914 is NULL, or KeyIdentifierSize is NULL, or 915 KeyIdentifer is NULL. 916 @retval EFI_NOT_FOUND The KeyIdentifier could not be found. On return the 917 KeyAttributesCount contains the number of attributes 918 processed. Individual structures will reflect the status of the 919 processing for that structure. 920 @retval EFI_UNSUPPORTED The implementation/KMS does not support this function. 921 922 **/ 923 typedef 924 EFI_STATUS 925 (EFIAPI *EFI_KMS_ADD_KEY_ATTRIBUTES) ( 926 IN EFI_KMS_PROTOCOL *This, 927 IN EFI_KMS_CLIENT_INFO *Client, 928 IN UINT8 *KeyIdentifierSize, 929 IN CONST VOID *KeyIdentifier, 930 IN OUT UINT16 *KeyAttributesCount, 931 IN OUT EFI_KMS_KEY_ATTRIBUTE *KeyAttributes, 932 IN OUT UINTN *ClientDataSize OPTIONAL, 933 IN OUT VOID **ClientData OPTIONAL 934 ); 935 936 /** 937 Delete attributes to a key specified by a key identifier. 938 939 @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. 940 @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. 941 @param[in] KeyIdentifierSize Pointer to the size in bytes of the KeyIdentifier variable. 942 @param[in] KeyIdentifier Pointer to the key identifier associated with this key. 943 @param[in, out] KeyAttributesCount Pointer to the number of EFI_KMS_KEY_ATTRIBUTE 944 structures to associate with the Key. 945 On input, the count value is one or more. 946 On normal returns, this number will be updated with 947 the number of key attributes successfully processed. 948 @param[in, out] KeyAttributes Pointer to an array of EFI_KMS_KEY_ATTRIBUTE 949 structures providing the attribute information to 950 associate with the key. 951 On input, the values for the fields in the structure 952 are completely filled in. 953 On return the KeyAttributeStatus field will reflect the 954 result of the operation for each key attribute request. 955 @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of 956 data specified by the ClientData parameter. This 957 parameter may be NULL, in which case the ClientData 958 parameter will be ignored and no data will be 959 transferred to or from the KMS. If the parameter is 960 not NULL, then ClientData must be a valid pointer. 961 If the value pointed to is 0, no data will be transferred 962 to the KMS, but data may be returned by the KMS. 963 For all non-zero values *ClientData will be transferred 964 to the KMS, which may also return data to the caller. 965 In all cases, the value upon return to the caller will 966 be the size of the data block returned to the caller, 967 which will be zero if no data is returned from the KMS. 968 @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of 969 *ClientDataSize that is to be passed directly to the 970 KMS if it supports the use of client data. This 971 parameter may be NULL if and only if the 972 ClientDataSize parameter is also NULL. Upon return to 973 the caller, *ClientData points to a block of data of 974 *ClientDataSize that was returned from the KMS. 975 If the returned value for *ClientDataSize is zero, 976 then the returned value for *ClientData must be NULL 977 and should be ignored by the caller. The KMS protocol 978 consumer is responsible for freeing all valid buffers 979 used for client data regardless of whether they are 980 allocated by the caller for input to the function or by 981 the implementation for output back to the caller. 982 983 @retval EFI_SUCCESS Successfully deleted all requested key attributes. 984 @retval EFI_OUT_OF_RESOURCES Could not allocate required resources. 985 @retval EFI_TIMEOUT Timed out waiting for device or key server. Check individual key 986 attribute request(s) to see which ones may have been 987 processed. 988 @retval EFI_ACCESS_DENIED Access was denied by the device or the key server; OR a 989 ClientId is required by the server and either none or an 990 invalid id was provided. 991 @retval EFI_DEVICE_ERROR Device or key server error. Check individual key attribute 992 request(s) (i.e. key attribute status for each) to see which ones 993 may have been processed. 994 @retval EFI_INVALID_PARAMETER This is NULL, ClientId is required but it is NULL, 995 KeyAttributesCount is NULL, or 996 KeyAttributes is NULL, or KeyIdentifierSize 997 is NULL, or KeyIdentifer is NULL. 998 @retval EFI_NOT_FOUND The KeyIdentifier could not be found or the attribute 999 could not be found. On return the KeyAttributesCount 1000 contains the number of attributes processed. Individual 1001 structures will reflect the status of the processing for that 1002 structure. 1003 @retval EFI_UNSUPPORTED The implementation/KMS does not support this function. 1004 1005 **/ 1006 typedef 1007 EFI_STATUS 1008 (EFIAPI *EFI_KMS_DELETE_KEY_ATTRIBUTES) ( 1009 IN EFI_KMS_PROTOCOL *This, 1010 IN EFI_KMS_CLIENT_INFO *Client, 1011 IN UINT8 *KeyIdentifierSize, 1012 IN CONST VOID *KeyIdentifier, 1013 IN OUT UINT16 *KeyAttributesCount, 1014 IN OUT EFI_KMS_KEY_ATTRIBUTE *KeyAttributes, 1015 IN OUT UINTN *ClientDataSize OPTIONAL, 1016 IN OUT VOID **ClientData OPTIONAL 1017 ); 1018 1019 /** 1020 Retrieve one or more key that has matched all of the specified key attributes. 1021 1022 @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. 1023 @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. 1024 @param[in, out] KeyAttributesCount Pointer to a count of the number of key attribute structures 1025 that must be matched for each returned key descriptor. 1026 On input the count value is one or more. 1027 On normal returns, this number will be updated with 1028 the number of key attributes successfully processed. 1029 @param[in, out] KeyAttributes Pointer to an array of EFI_KMS_KEY_ATTRIBUTE 1030 structure to search for. 1031 On input, the values for the fields in the structure are 1032 completely filled in. 1033 On return the KeyAttributeStatus field will reflect the 1034 result of the operation for each key attribute request. 1035 @param[in, out] KeyDescriptorCount Pointer to a count of the number of key descriptors matched 1036 by this operation. 1037 On entry, this number will be zero. 1038 On return, this number will be updated to the number 1039 of key descriptors successfully found. 1040 @param[in, out] KeyDescriptors Pointer to an array of EFI_KMS_KEY_DESCRIPTOR 1041 structures which describe the keys from the KMS 1042 having the KeyAttribute(s) specified. 1043 On input, this pointer will be NULL. 1044 On output, the array will contain an 1045 EFI_KMS_KEY_DESCRIPTOR structure for each key 1046 meeting the search criteria. Memory for the array 1047 and all KeyValue fields will be allocated with the 1048 EfiBootServicesData type and must be freed by the 1049 caller when it is no longer needed. Also, the KeyStatus 1050 field of each descriptor will reflect the result of the 1051 request relative to that key descriptor. 1052 @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of 1053 data specified by the ClientData parameter. This 1054 parameter may be NULL, in which case the ClientData 1055 parameter will be ignored and no data will be 1056 transferred to or from the KMS. If the parameter is 1057 not NULL, then ClientData must be a valid pointer. 1058 If the value pointed to is 0, no data will be transferred 1059 to the KMS, but data may be returned by the KMS. 1060 For all non-zero values *ClientData will be transferred 1061 to the KMS, which may also return data to the caller. 1062 In all cases, the value upon return to the caller will 1063 be the size of the data block returned to the caller, 1064 which will be zero if no data is returned from the KMS. 1065 @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of 1066 *ClientDataSize that is to be passed directly to the 1067 KMS if it supports the use of client data. This 1068 parameter may be NULL if and only if the 1069 ClientDataSize parameter is also NULL. Upon return to 1070 the caller, *ClientData points to a block of data of 1071 *ClientDataSize that was returned from the KMS. 1072 If the returned value for *ClientDataSize is zero, 1073 then the returned value for *ClientData must be NULL 1074 and should be ignored by the caller. The KMS protocol 1075 consumer is responsible for freeing all valid buffers 1076 used for client data regardless of whether they are 1077 allocated by the caller for input to the function or by 1078 the implementation for output back to the caller. 1079 1080 @retval EFI_SUCCESS Successfully retrieved all requested keys. 1081 @retval EFI_OUT_OF_RESOURCES Could not allocate required resources. 1082 @retval EFI_TIMEOUT Timed out waiting for device or key server. Check individual key 1083 attribute request(s) to see which ones may have been 1084 processed. 1085 @retval EFI_BUFFER_TOO_SMALL If multiple keys are associated with the attribute(s), and the 1086 KeyValue buffer does not contain enough structures 1087 (KeyDescriptorCount) to contain all the key data, then 1088 the available structures will be filled and 1089 KeyDescriptorCount will be updated to indicate the 1090 number of keys which could not be processed. 1091 @retval EFI_ACCESS_DENIED Access was denied by the device or the key server; OR a 1092 ClientId is required by the server and either none or an 1093 invalid id was provided. 1094 @retval EFI_DEVICE_ERROR Device or key server error. Check individual key attribute 1095 request(s) (i.e. key attribute status for each) to see which ones 1096 may have been processed. 1097 @retval EFI_INVALID_PARAMETER This is NULL, ClientId is required but it is NULL, 1098 KeyDescriptorCount is NULL, or 1099 KeyDescriptors is NULL or KeyAttributes is 1100 NULL, or KeyAttributesCount is NULL. 1101 @retval EFI_NOT_FOUND One or more EFI_KMS_KEY_ATTRIBUTE structures could 1102 not be processed properly. KeyAttributeCount contains 1103 the number of structures which were successfully processed. 1104 Individual structures will reflect the status of the processing for 1105 that structure. 1106 @retval EFI_UNSUPPORTED The implementation/KMS does not support this function. 1107 1108 **/ 1109 typedef 1110 EFI_STATUS 1111 (EFIAPI *EFI_KMS_GET_KEY_BY_ATTRIBUTES) ( 1112 IN EFI_KMS_PROTOCOL *This, 1113 IN EFI_KMS_CLIENT_INFO *Client, 1114 IN OUT UINTN *KeyAttributeCount, 1115 IN OUT EFI_KMS_KEY_ATTRIBUTE *KeyAttributes, 1116 IN OUT UINTN *KeyDescriptorCount, 1117 IN OUT EFI_KMS_KEY_DESCRIPTOR *KeyDescriptors, 1118 IN OUT UINTN *ClientDataSize OPTIONAL, 1119 IN OUT VOID **ClientData OPTIONAL 1120 ); 1121 1122 /// 1123 /// The Key Management Service (KMS) protocol provides services to generate, store, retrieve, 1124 /// and manage cryptographic keys. 1125 /// 1126 struct _EFI_KMS_PROTOCOL { 1127 /// 1128 /// Get the current status of the key management service. If the implementation has not yet 1129 /// connected to the KMS, then a call to this function will initiate a connection. This is the 1130 /// only function that is valid for use prior to the service being marked available. 1131 /// 1132 EFI_KMS_GET_SERVICE_STATUS GetServiceStatus; 1133 /// 1134 /// Register a specific client with the KMS. 1135 /// 1136 EFI_KMS_REGISTER_CLIENT RegisterClient; 1137 /// 1138 /// Request the generation of a new key and retrieve it. 1139 /// 1140 EFI_KMS_CREATE_KEY CreateKey; 1141 /// 1142 /// Retrieve an existing key. 1143 /// 1144 EFI_KMS_GET_KEY GetKey; 1145 /// 1146 /// Add a local key to KMS database. If there is an existing key with this key identifier in the 1147 /// KMS database, it will be replaced with the new key. 1148 /// 1149 EFI_KMS_ADD_KEY AddKey; 1150 /// 1151 /// Delete an existing key from the KMS database. 1152 /// 1153 EFI_KMS_DELETE_KEY DeleteKey; 1154 /// 1155 /// Get attributes for an existing key in the KMS database. 1156 /// 1157 EFI_KMS_GET_KEY_ATTRIBUTES GetKeyAttributes; 1158 /// 1159 /// Add attributes to an existing key in the KMS database. 1160 /// 1161 EFI_KMS_ADD_KEY_ATTRIBUTES AddKeyAttributes; 1162 /// 1163 /// Delete attributes for an existing key in the KMS database. 1164 /// 1165 EFI_KMS_DELETE_KEY_ATTRIBUTES DeleteKeyAttributes; 1166 /// 1167 /// Get existing key(s) with the specified attributes. 1168 /// 1169 EFI_KMS_GET_KEY_BY_ATTRIBUTES GetKeyByAttributes; 1170 /// 1171 /// The version of this EFI_KMS_PROTOCOL structure. This must be set to 0x00020040 for 1172 /// the initial version of this protocol. 1173 /// 1174 UINT32 ProtocolVersion; 1175 /// 1176 /// Optional GUID used to identify a specific KMS. This GUID may be supplied by the provider, 1177 /// by the implementation, or may be null. If is null, then the ServiceName must not be null. 1178 /// 1179 EFI_GUID ServiceId; 1180 /// 1181 /// Optional pointer to a unicode string which may be used to identify the KMS or provide 1182 /// other information about the supplier. 1183 /// 1184 CHAR16 *ServiceName; 1185 /// 1186 /// Optional 32-bit value which may be used to indicate the version of the KMS provided by 1187 /// the supplier. 1188 /// 1189 UINT32 ServiceVersion; 1190 /// 1191 /// TRUE if and only if the service is active and available for use. To avoid unnecessary 1192 /// delays in POST, this protocol may be installed without connecting to the service. In this 1193 /// case, the first call to the GetServiceStatus () function will cause the implementation to 1194 /// connect to the supported service and mark it as available. The capabilities of this service 1195 /// as defined in the reminder of this protocol are not guaranteed to be valid until the service 1196 /// has been marked available. 1197 /// 1198 BOOLEAN ServiceAvailable; 1199 /// 1200 /// TRUE if and only if the service supports client identifiers. Client identifiers may be used 1201 /// for auditing, access control or any other purpose specific to the implementation. 1202 /// 1203 BOOLEAN ClientIdSupported; 1204 /// 1205 /// TRUE if and only if the service requires a client identifier in order to process key requests. 1206 /// FALSE otherwise. 1207 /// 1208 BOOLEAN ClientIdRequired; 1209 /// 1210 /// The maximum size in bytes for the client identifier. 1211 /// 1212 UINT16 ClientIdMaxSize; 1213 /// 1214 /// The client name string type(s) supported by the KMS service. If client names are not 1215 /// supported, this field will be set the EFI_KMS_DATA_TYPE_NONE. Otherwise, it will be set 1216 /// to the inclusive 'OR' of all client name formats supported. Client names may be used for 1217 /// auditing, access control or any other purpose specific to the implementation. 1218 /// 1219 UINT8 ClientNameStringTypes; 1220 /// 1221 /// TRUE if only if the KMS requires a client name to be supplied to the service. 1222 /// FALSE otherwise. 1223 /// 1224 BOOLEAN ClientNameRequired; 1225 /// 1226 /// The maximum number of characters allowed for the client name. 1227 /// 1228 UINT16 ClientNameMaxCount; 1229 /// 1230 /// TRUE if and only if the service supports arbitrary client data requests. The use of client 1231 /// data requires the caller to have specific knowledge of the individual KMS service and 1232 /// should be used only if absolutely necessary. 1233 /// FALSE otherwise. 1234 /// 1235 BOOLEAN ClientDataSupported; 1236 /// 1237 /// The maximum size in bytes for the client data. If the maximum data size is not specified 1238 /// by the KMS or it is not known, then this field must be filled with all ones. 1239 /// 1240 UINTN ClientDataMaxSize; 1241 /// 1242 /// TRUE if variable length key identifiers are supported. 1243 /// FALSE if a fixed length key identifier is supported. 1244 /// 1245 BOOLEAN KeyIdVariableLenSupported; 1246 /// 1247 /// If KeyIdVariableLenSupported is TRUE, this is the maximum supported key identifier length 1248 /// in bytes. Otherwise this is the fixed length of key identifier supported. Key ids shorter 1249 /// than the fixed length will be padded on the right with blanks. 1250 /// 1251 UINTN KeyIdMaxSize; 1252 /// 1253 /// The number of key format/size GUIDs returned in the KeyFormats field. 1254 /// 1255 UINTN KeyFormatsCount; 1256 /// 1257 /// A pointer to an array of EFI_GUID values which specify key formats/sizes supported by 1258 /// this KMS. Each format/size pair will be specified by a separate EFI_GUID. At least one 1259 /// key format/size must be supported. All formats/sizes with the same hashing algorithm 1260 /// must be contiguous in the array, and for each hashing algorithm, the key sizes must be in 1261 /// ascending order. See "Related Definitions" for GUIDs which identify supported key formats/sizes. 1262 /// This list of GUIDs supported by the KMS is not required to be exhaustive, and the KMS 1263 /// may provide support for additional key formats/sizes. Users may request key information 1264 /// using an arbitrary GUID, but any GUID not recognized by the implementation or not 1265 /// supported by the KMS will return an error code of EFI_UNSUPPORTED 1266 /// 1267 EFI_GUID *KeyFormats; 1268 /// 1269 /// TRUE if key attributes are supported. 1270 /// FALSE if key attributes are not supported. 1271 /// 1272 BOOLEAN KeyAttributesSupported; 1273 /// 1274 /// The key attribute identifier string type(s) supported by the KMS service. If key attributes 1275 /// are not supported, this field will be set to EFI_KMS_DATA_TYPE_NONE. Otherwise, it will 1276 /// be set to the inclusive 'OR' of all key attribute identifier string types supported. 1277 /// EFI_KMS_DATA_TYPE_BINARY is not valid for this field. 1278 /// 1279 UINT8 KeyAttributeIdStringTypes; 1280 UINT16 KeyAttributeIdMaxCount; 1281 /// 1282 /// The number of predefined KeyAttributes structures returned in the KeyAttributes 1283 /// parameter. If the KMS does not support predefined key attributes, or if it does not 1284 /// provide a method to obtain predefined key attributes data, then this field must be zero. 1285 /// 1286 UINTN KeyAttributesCount; 1287 /// 1288 /// A pointer to an array of KeyAttributes structures which contains the predefined 1289 /// attributes supported by this KMS. Each structure must contain a valid key attribute 1290 /// identifier and should provide any other information as appropriate for the attribute, 1291 /// including a default value if one exists. This variable must be set to NULL if the 1292 /// KeyAttributesCount variable is zero. It must point to a valid buffer if the 1293 /// KeyAttributesCount variable is non-zero. 1294 /// This list of predefined attributes is not required to be exhaustive, and the KMS may 1295 /// provide additional predefined attributes not enumerated in this list. The implementation 1296 /// does not distinguish between predefined and used defined attributes, and therefore, 1297 /// predefined attributes not enumerated will still be processed to the KMS. 1298 /// 1299 EFI_KMS_KEY_ATTRIBUTE *KeyAttributes; 1300 }; 1301 1302 extern EFI_GUID gEfiKmsFormatGeneric128Guid; 1303 extern EFI_GUID gEfiKmsFormatGeneric160Guid; 1304 extern EFI_GUID gEfiKmsFormatGeneric256Guid; 1305 extern EFI_GUID gEfiKmsFormatGeneric512Guid; 1306 extern EFI_GUID gEfiKmsFormatGeneric1024Guid; 1307 extern EFI_GUID gEfiKmsFormatGeneric2048Guid; 1308 extern EFI_GUID gEfiKmsFormatGeneric3072Guid; 1309 extern EFI_GUID gEfiKmsFormatMd2128Guid; 1310 extern EFI_GUID gEfiKmsFormatMdc2128Guid; 1311 extern EFI_GUID gEfiKmsFormatMd4128Guid; 1312 extern EFI_GUID gEfiKmsFormatMdc4128Guid; 1313 extern EFI_GUID gEfiKmsFormatMd5128Guid; 1314 extern EFI_GUID gEfiKmsFormatMd5sha128Guid; 1315 extern EFI_GUID gEfiKmsFormatSha1160Guid; 1316 extern EFI_GUID gEfiKmsFormatSha256256Guid; 1317 extern EFI_GUID gEfiKmsFormatSha512512Guid; 1318 extern EFI_GUID gEfiKmsFormatAesxts128Guid; 1319 extern EFI_GUID gEfiKmsFormatAesxts256Guid; 1320 extern EFI_GUID gEfiKmsFormatAescbc128Guid; 1321 extern EFI_GUID gEfiKmsFormatAescbc256Guid; 1322 extern EFI_GUID gEfiKmsFormatRsasha11024Guid; 1323 extern EFI_GUID gEfiKmsFormatRsasha12048Guid; 1324 extern EFI_GUID gEfiKmsFormatRsasha2562048Guid; 1325 extern EFI_GUID gEfiKmsFormatRsasha2563072Guid; 1326 extern EFI_GUID gEfiKmsProtocolGuid; 1327 1328 #endif 1329