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