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