diff options
Diffstat (limited to 'src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/Kms.h')
| -rw-r--r-- | src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/Kms.h | 1343 |
1 files changed, 1343 insertions, 0 deletions
diff --git a/src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/Kms.h b/src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/Kms.h new file mode 100644 index 0000000000..fa0afa132d --- /dev/null +++ b/src/vendorcode/intel/edk2/UDK2017/MdePkg/Include/Protocol/Kms.h @@ -0,0 +1,1343 @@ +/** @file + The Key Management Service (KMS) protocol as defined in the UEFI 2.3.1 specification is to + provides services to generate, store, retrieve, and manage cryptographic keys. + The intention is to specify a simple generic protocol that could be used for many implementations. + + A driver implementing the protocol may need to provide basic key service that consists of a + key store and cryptographic key generation capability. It may connect to an external key + server over the network, or to a Hardware Security Module (HSM) attached to the system it + runs on, or anything else that is capable of providing the key management service. + + Copyright (c) 2011 - 2017, Intel Corporation. All rights reserved.<BR> + This program and the accompanying materials are licensed and made available under + the terms and conditions of the BSD License that accompanies this distribution. + The full text of the license may be found at + http://opensource.org/licenses/bsd-license.php. + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. + +**/ + +#ifndef __KMS_H__ +#define __KMS_H__ + +#define EFI_KMS_PROTOCOL_GUID \ + { \ + 0xEC3A978D, 0x7C4E, 0x48FA, {0x9A, 0xBE, 0x6A, 0xD9, 0x1C, 0xC8, 0xF8, 0x11 } \ + } + +typedef struct _EFI_KMS_PROTOCOL EFI_KMS_PROTOCOL; + +// +// Where appropriate, EFI_KMS_DATA_TYPE values may be combined using a bitwise 'OR' +// operation to indicate support for multiple data types. +// +#define EFI_KMS_DATA_TYPE_NONE 0 +#define EFI_KMS_DATA_TYPE_BINARY 1 +#define EFI_KMS_DATA_TYPE_ASCII 2 +#define EFI_KMS_DATA_TYPE_UNICODE 4 +#define EFI_KMS_DATA_TYPE_UTF8 8 + + +// +// The key formats recognized by the KMS protocol are defined by an EFI_GUID which specifies +// a (key-algorithm, key-size) pair. The names of these GUIDs are in the format +// EFI_KMS_KEY_(key-algorithm)_(key-size)_GUID, where the key-size is expressed in bits. +// The key formats recognized fall into three categories, generic (no algorithm), hash algorithms, +// and encrypted algorithms. +// + +/// +/// The following GUIDs define formats that contain generic key data of a specific size in bits, +/// but which is not associated with any specific key algorithm(s). +///@{ +#define EFI_KMS_FORMAT_GENERIC_128_GUID \ + { \ + 0xec8a3d69, 0x6ddf, 0x4108, {0x94, 0x76, 0x73, 0x37, 0xfc, 0x52, 0x21, 0x36 } \ + } +#define EFI_KMS_FORMAT_GENERIC_160_GUID \ + { \ + 0xa3b3e6f8, 0xefca, 0x4bc1, {0x88, 0xfb, 0xcb, 0x87, 0x33, 0x9b, 0x25, 0x79 } \ + } +#define EFI_KMS_FORMAT_GENERIC_256_GUID \ + { \ + 0x70f64793, 0xc323, 0x4261, {0xac, 0x2c, 0xd8, 0x76, 0xf2, 0x7c, 0x53, 0x45 } \ + } +#define EFI_KMS_FORMAT_GENERIC_512_GUID \ + { \ + 0x978fe043, 0xd7af, 0x422e, {0x8a, 0x92, 0x2b, 0x48, 0xe4, 0x63, 0xbd, 0xe6 } \ + } +#define EFI_KMS_FORMAT_GENERIC_1024_GUID \ + { \ + 0x43be0b44, 0x874b, 0x4ead, {0xb0, 0x9c, 0x24, 0x1a, 0x4f, 0xbd, 0x7e, 0xb3 } \ + } +#define EFI_KMS_FORMAT_GENERIC_2048_GUID \ + { \ + 0x40093f23, 0x630c, 0x4626, {0x9c, 0x48, 0x40, 0x37, 0x3b, 0x19, 0xcb, 0xbe } \ + } +#define EFI_KMS_FORMAT_GENERIC_3072_GUID \ + { \ + 0xb9237513, 0x6c44, 0x4411, {0xa9, 0x90, 0x21, 0xe5, 0x56, 0xe0, 0x5a, 0xde } \ + } +#define EFI_KMS_FORMAT_GENERIC_DYNAMIC_GUID \ + { \ + 0x2156e996, 0x66de, 0x4b27, {0x9c, 0xc9, 0xb0, 0x9f, 0xac, 0x4d, 0x2, 0xbe } \ + } +///@} + +/// +/// These GUIDS define key data formats that contain data generated by basic hash algorithms +/// with no cryptographic properties. +///@{ +#define EFI_KMS_FORMAT_MD2_128_GUID \ + { \ + 0x78be11c4, 0xee44, 0x4a22, {0x9f, 0x05, 0x03, 0x85, 0x2e, 0xc5, 0xc9, 0x78 } \ + } +#define EFI_KMS_FORMAT_MDC2_128_GUID \ + { \ + 0xf7ad60f8, 0xefa8, 0x44a3, {0x91, 0x13, 0x23, 0x1f, 0x39, 0x9e, 0xb4, 0xc7 } \ + } +#define EFI_KMS_FORMAT_MD4_128_GUID \ + { \ + 0xd1c17aa1, 0xcac5, 0x400f, {0xbe, 0x17, 0xe2, 0xa2, 0xae, 0x06, 0x67, 0x7c } \ + } +#define EFI_KMS_FORMAT_MDC4_128_GUID \ + { \ + 0x3fa4f847, 0xd8eb, 0x4df4, {0xbd, 0x49, 0x10, 0x3a, 0x0a, 0x84, 0x7b, 0xbc } \ + } +#define EFI_KMS_FORMAT_MD5_128_GUID \ + { \ + 0xdcbc3662, 0x9cda, 0x4b52, {0xa0, 0x4c, 0x82, 0xeb, 0x1d, 0x23, 0x48, 0xc7 } \ + } +#define EFI_KMS_FORMAT_MD5SHA_128_GUID \ + { \ + 0x1c178237, 0x6897, 0x459e, {0x9d, 0x36, 0x67, 0xce, 0x8e, 0xf9, 0x4f, 0x76 } \ + } +#define EFI_KMS_FORMAT_SHA1_160_GUID \ + { \ + 0x453c5e5a, 0x482d, 0x43f0, {0x87, 0xc9, 0x59, 0x41, 0xf3, 0xa3, 0x8a, 0xc2 } \ + } +#define EFI_KMS_FORMAT_SHA256_256_GUID \ + { \ + 0x6bb4f5cd, 0x8022, 0x448d, {0xbc, 0x6d, 0x77, 0x1b, 0xae, 0x93, 0x5f, 0xc6 } \ + } +#define EFI_KMS_FORMAT_SHA512_512_GUID \ + { \ + 0x2f240e12, 0xe14d, 0x475c, {0x83, 0xb0, 0xef, 0xff, 0x22, 0xd7, 0x7b, 0xe7 } \ + } +///@} + +/// +/// These GUIDs define key data formats that contain data generated by cryptographic key algorithms. +/// There may or may not be a separate data hashing algorithm associated with the key algorithm. +///@{ +#define EFI_KMS_FORMAT_AESXTS_128_GUID \ + { \ + 0x4776e33f, 0xdb47, 0x479a, {0xa2, 0x5f, 0xa1, 0xcd, 0x0a, 0xfa, 0xb3, 0x8b } \ + } +#define EFI_KMS_FORMAT_AESXTS_256_GUID \ + { \ + 0xdc7e8613, 0xc4bb, 0x4db0, {0x84, 0x62, 0x13, 0x51, 0x13, 0x57, 0xab, 0xe2 } \ + } +#define EFI_KMS_FORMAT_AESCBC_128_GUID \ + { \ + 0xa0e8ee6a, 0x0e92, 0x44d4, {0x86, 0x1b, 0x0e, 0xaa, 0x4a, 0xca, 0x44, 0xa2 } \ + } +#define EFI_KMS_FORMAT_AESCBC_256_GUID \ + { \ + 0xd7e69789, 0x1f68, 0x45e8, {0x96, 0xef, 0x3b, 0x64, 0x07, 0xa5, 0xb2, 0xdc } \ + } +#define EFI_KMS_FORMAT_RSASHA1_1024_GUID \ + { \ + 0x56417bed, 0x6bbe, 0x4882, {0x86, 0xa0, 0x3a, 0xe8, 0xbb, 0x17, 0xf8, 0xf9 } \ + } +#define EFI_KMS_FORMAT_RSASHA1_2048_GUID \ + { \ + 0xf66447d4, 0x75a6, 0x463e, {0xa8, 0x19, 0x07, 0x7f, 0x2d, 0xda, 0x05, 0xe9 } \ + } +#define EFI_KMS_FORMAT_RSASHA256_2048_GUID \ + { \ + 0xa477af13, 0x877d, 0x4060, {0xba, 0xa1, 0x25, 0xd1, 0xbe, 0xa0, 0x8a, 0xd3 } \ + } +#define EFI_KMS_FORMAT_RSASHA256_3072_GUID \ + { \ + 0x4e1356c2, 0xeed, 0x463f, {0x81, 0x47, 0x99, 0x33, 0xab, 0xdb, 0xc7, 0xd5 } \ + } +///@} + +#define EFI_KMS_ATTRIBUTE_TYPE_NONE 0x00 +#define EFI_KMS_ATTRIBUTE_TYPE_INTEGER 0x01 +#define EFI_KMS_ATTRIBUTE_TYPE_LONG_INTEGER 0x02 +#define EFI_KMS_ATTRIBUTE_TYPE_BIG_INTEGER 0x03 +#define EFI_KMS_ATTRIBUTE_TYPE_ENUMERATION 0x04 +#define EFI_KMS_ATTRIBUTE_TYPE_BOOLEAN 0x05 +#define EFI_KMS_ATTRIBUTE_TYPE_BYTE_STRING 0x06 +#define EFI_KMS_ATTRIBUTE_TYPE_TEXT_STRING 0x07 +#define EFI_KMS_ATTRIBUTE_TYPE_DATE_TIME 0x08 +#define EFI_KMS_ATTRIBUTE_TYPE_INTERVAL 0x09 +#define EFI_KMS_ATTRIBUTE_TYPE_STRUCTURE 0x0A +#define EFI_KMS_ATTRIBUTE_TYPE_DYNAMIC 0x0B + +typedef struct { + /// + /// Length in bytes of the KeyData. + /// + UINT32 KeySize; + /// + /// The data of the key. + /// + UINT8 KeyData[1]; +} EFI_KMS_FORMAT_GENERIC_DYNAMIC; + +typedef struct { + /// + /// The size in bytes for the client identifier. + /// + UINT16 ClientIdSize; + /// + /// Pointer to a valid client identifier. + /// + VOID *ClientId; + /// + /// The client name string type used by this client. The string type set here must be one of + /// the string types reported in the ClientNameStringTypes field of the KMS protocol. If the + /// KMS does not support client names, this field should be set to EFI_KMS_DATA_TYPE_NONE. + /// + UINT8 ClientNameType; + /// + /// The size in characters for the client name. This field will be ignored if + /// ClientNameStringType is set to EFI_KMS_DATA_TYPE_NONE. Otherwise, it must contain + /// number of characters contained in the ClientName field. + /// + UINT8 ClientNameCount; + /// + /// Pointer to a client name. This field will be ignored if ClientNameStringType is set to + /// EFI_KMS_DATA_TYPE_NONE. Otherwise, it must point to a valid string of the specified type. + /// + VOID *ClientName; +} EFI_KMS_CLIENT_INFO; + +typedef struct { + /// + /// The size of the KeyIdentifier field in bytes. This field is limited to the range 0 to 255. + /// + UINT8 KeyIdentifierSize; + /// + /// Pointer to an array of KeyIdentifierType elements. + /// + VOID *KeyIdentifier; + /// + /// An EFI_GUID which specifies the algorithm and key value size for this key. + /// + EFI_GUID KeyFormat; + /// + /// Pointer to a key value for a key specified by the KeyFormat field. A NULL value for this + /// field indicates that no key is available. + /// + VOID *KeyValue; + /// + /// Specifies the results of KMS operations performed with this descriptor. This field is used + /// to indicate the status of individual operations when a KMS function is called with multiple + /// EFI_KMS_KEY_DESCRIPTOR structures. + /// KeyStatus codes returned for the individual key requests are: + /// EFI_SUCCESS Successfully processed this key. + /// EFI_WARN_STALE_DATA Successfully processed this key, however, the key's parameters + /// exceed internal policies/limits and should be replaced. + /// EFI_COMPROMISED_DATA Successfully processed this key, but the key may have been + /// compromised and must be replaced. + /// EFI_UNSUPPORTED Key format is not supported by the service. + /// EFI_OUT_OF_RESOURCES Could not allocate resources for the key processing. + /// EFI_TIMEOUT Timed out waiting for device or key server. + /// EFI_DEVICE_ERROR Device or key server error. + /// EFI_INVALID_PARAMETER KeyFormat is invalid. + /// EFI_NOT_FOUND The key does not exist on the KMS. + /// + EFI_STATUS KeyStatus; +} EFI_KMS_KEY_DESCRIPTOR; + +typedef struct { + /// + /// Part of a tag-type-length triplet that identifies the KeyAttributeData formatting. The + /// definition of the value is outside the scope of this standard and may be defined by the KMS. + /// + UINT16 Tag; + /// + /// Part of a tag-type-length triplet that identifies the KeyAttributeData formatting. The + /// definition of the value is outside the scope of this standard and may be defined by the KMS. + /// + UINT16 Type; + /// + /// Length in bytes of the KeyAttributeData. + /// + UINT32 Length; + /// + /// An array of bytes to hold the attribute data associated with the KeyAttributeIdentifier. + /// + UINT8 KeyAttributeData[1]; +} EFI_KMS_DYNAMIC_FIELD; + +typedef struct { + /// + /// The number of members in the EFI_KMS_DYNAMIC_ATTRIBUTE structure. + /// + UINT32 FieldCount; + /// + /// An array of EFI_KMS_DYNAMIC_FIELD structures. + /// + EFI_KMS_DYNAMIC_FIELD Field[1]; +} EFI_KMS_DYNAMIC_ATTRIBUTE; + +typedef struct { + /// + /// The data type used for the KeyAttributeIdentifier field. Values for this field are defined + /// by the EFI_KMS_DATA_TYPE constants, except that EFI_KMS_DATA_TYPE_BINARY is not + /// valid for this field. + /// + UINT8 KeyAttributeIdentifierType; + /// + /// The length of the KeyAttributeIdentifier field in units defined by KeyAttributeIdentifierType + /// field. This field is limited to the range 0 to 255. + /// + UINT8 KeyAttributeIdentifierCount; + /// + /// Pointer to an array of KeyAttributeIdentifierType elements. For string types, there must + /// not be a null-termination element at the end of the array. + /// + VOID *KeyAttributeIdentifier; + /// + /// The instance number of this attribute. If there is only one instance, the value is set to + /// one. If this value is set to 0xFFFF (all binary 1's) then this field should be ignored if an + /// output or treated as a wild card matching any value if it is an input. If the attribute is + /// stored with this field, it will match any attribute request regardless of the setting of the + /// field in the request. If set to 0xFFFF in the request, it will match any attribute with the + /// same KeyAttributeIdentifier. + /// + UINT16 KeyAttributeInstance; + /// + /// The data type of the KeyAttributeValue (e.g. struct, bool, etc.). See the list of + /// KeyAttributeType definitions. + /// + UINT16 KeyAttributeType; + /// + /// The size in bytes of the KeyAttribute field. A value of zero for this field indicates that no + /// key attribute value is available. + /// + UINT16 KeyAttributeValueSize; + /// + /// Pointer to a key attribute value for the attribute specified by the KeyAttributeIdentifier + /// field. If the KeyAttributeValueSize field is zero, then this field must be NULL. + /// + VOID *KeyAttributeValue; + /// + /// KeyAttributeStatusSpecifies the results of KMS operations performed with this attribute. + /// This field is used to indicate the status of individual operations when a KMS function is + /// called with multiple EFI_KMS_KEY_ATTRIBUTE structures. + /// KeyAttributeStatus codes returned for the individual key attribute requests are: + /// EFI_SUCCESS Successfully processed this request. + /// EFI_WARN_STALE_DATA Successfully processed this request, however, the key's + /// parameters exceed internal policies/limits and should be replaced. + /// EFI_COMPROMISED_DATA Successfully processed this request, but the key may have been + /// compromised and must be replaced. + /// EFI_UNSUPPORTED Key attribute format is not supported by the service. + /// EFI_OUT_OF_RESOURCES Could not allocate resources for the request processing. + /// EFI_TIMEOUT Timed out waiting for device or key server. + /// EFI_DEVICE_ERROR Device or key server error. + /// EFI_INVALID_PARAMETER A field in the EFI_KMS_KEY_ATTRIBUTE structure is invalid. + /// EFI_NOT_FOUND The key attribute does not exist on the KMS. + /// + EFI_STATUS KeyAttributeStatus; +} EFI_KMS_KEY_ATTRIBUTE; + +/** + Get the current status of the key management service. + + @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. + + @retval EFI_SUCCESS The KMS is ready for use. + @retval EFI_NOT_READY No connection to the KMS is available. + @retval EFI_NO_MAPPING No valid connection configuration exists for the KMS. + @retval EFI_NO_RESPONSE No response was received from the KMS. + @retval EFI_DEVICE_ERROR An error occurred when attempting to access the KMS. + @retval EFI_INVALID_PARAMETER This is NULL. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_KMS_GET_SERVICE_STATUS) ( + IN EFI_KMS_PROTOCOL *This + ); + +/** + Register client information with the supported KMS. + + @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. + @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. + @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of + data specified by the ClientData parameter. This + parameter may be NULL, in which case the ClientData + parameter will be ignored and no data will be + transferred to or from the KMS. If the parameter is + not NULL, then ClientData must be a valid pointer. + If the value pointed to is 0, no data will be transferred + to the KMS, but data may be returned by the KMS. + For all non-zero values *ClientData will be transferred + to the KMS, which may also return data to the caller. + In all cases, the value upon return to the caller will + be the size of the data block returned to the caller, + which will be zero if no data is returned from the KMS. + @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of + *ClientDataSize that is to be passed directly to the + KMS if it supports the use of client data. This + parameter may be NULL if and only if the + ClientDataSize parameter is also NULL. Upon return to + the caller, *ClientData points to a block of data of + *ClientDataSize that was returned from the KMS. + If the returned value for *ClientDataSize is zero, + then the returned value for *ClientData must be NULL + and should be ignored by the caller. The KMS protocol + consumer is responsible for freeing all valid buffers + used for client data regardless of whether they are + allocated by the caller for input to the function or by + the implementation for output back to the caller. + + @retval EFI_SUCCESS The client information has been accepted by the KMS. + @retval EFI_NOT_READY No connection to the KMS is available. + @retval EFI_NO_RESPONSE There was no response from the device or the key server. + @retval EFI_ACCESS_DENIED Access was denied by the device or the key server. + @retval EFI_DEVICE_ERROR An error occurred when attempting to access the KMS. + @retval EFI_OUT_OF_RESOURCES Required resources were not available to perform the function. + @retval EFI_INVALID_PARAMETER This is NULL. + @retval EFI_UNSUPPORTED The KMS does not support the use of client identifiers. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_KMS_REGISTER_CLIENT) ( + IN EFI_KMS_PROTOCOL *This, + IN EFI_KMS_CLIENT_INFO *Client, + IN OUT UINTN *ClientDataSize OPTIONAL, + IN OUT VOID **ClientData OPTIONAL + ); + +/** + Request that the KMS generate one or more new keys and associate them with key identifiers. + The key value(s) is returned to the caller. + + @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. + @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. + @param[in, out] KeyDescriptorCount Pointer to a count of the number of key descriptors to be + processed by this operation. On return, this number + will be updated with the number of key descriptors + successfully processed. + @param[in, out] KeyDescriptors Pointer to an array of EFI_KMS_KEY_DESCRIPTOR + structures which describe the keys to be generated. + On input, the KeyIdentifierSize and the KeyIdentifier + may specify an identifier to be used for the key, + but this is not required. The KeyFormat field must + specify a key format GUID reported as supported by + the KeyFormats field of the EFI_KMS_PROTOCOL. + The value for this field in the first key descriptor will + be considered the default value for subsequent key + descriptors requested in this operation if those key + descriptors have a NULL GUID in the key format field. + On output, the KeyIdentifierSize and KeyIdentifier fields + will specify an identifier for the key which will be either + the original identifier if one was provided, or an identifier + generated either by the KMS or the KMS protocol + implementation. The KeyFormat field will be updated + with the GUID used to generate the key if it was a + NULL GUID, and the KeyValue field will contain a pointer + to memory containing the key value for the generated + key. Memory for both the KeyIdentifier and the KeyValue + fields will be allocated with the BOOT_SERVICES_DATA + type and must be freed by the caller when it is no longer + needed. Also, the KeyStatus field must reflect the result + of the request relative to that key. + @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of + data specified by the ClientData parameter. This + parameter may be NULL, in which case the ClientData + parameter will be ignored and no data will be + transferred to or from the KMS. If the parameter is + not NULL, then ClientData must be a valid pointer. + If the value pointed to is 0, no data will be transferred + to the KMS, but data may be returned by the KMS. + For all non-zero values *ClientData will be transferred + to the KMS, which may also return data to the caller. + In all cases, the value upon return to the caller will + be the size of the data block returned to the caller, + which will be zero if no data is returned from the KMS. + @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of + *ClientDataSize that is to be passed directly to the + KMS if it supports the use of client data. This + parameter may be NULL if and only if the + ClientDataSize parameter is also NULL. Upon return to + the caller, *ClientData points to a block of data of + *ClientDataSize that was returned from the KMS. + If the returned value for *ClientDataSize is zero, + then the returned value for *ClientData must be NULL + and should be ignored by the caller. The KMS protocol + consumer is responsible for freeing all valid buffers + used for client data regardless of whether they are + allocated by the caller for input to the function or by + the implementation for output back to the caller. + + @retval EFI_SUCCESS Successfully generated and retrieved all requested keys. + @retval EFI_UNSUPPORTED This function is not supported by the KMS. --OR-- + One (or more) of the key requests submitted is not supported by + the KMS. Check individual key request(s) to see which ones + may have been processed. + @retval EFI_OUT_OF_RESOURCES Required resources were not available to perform the function. + @retval EFI_TIMEOUT Timed out waiting for device or key server. Check individual key + request(s) to see which ones may have been processed. + @retval EFI_ACCESS_DENIED Access was denied by the device or the key server; OR a + ClientId is required by the server and either no id was + provided or an invalid id was provided. + @retval EFI_DEVICE_ERROR An error occurred when attempting to access the KMS. Check + individual key request(s) to see which ones may have been + processed. + @retval EFI_INVALID_PARAMETER This is NULL, ClientId is required but it is NULL, + KeyDescriptorCount is NULL, or Keys is NULL. + @retval EFI_NOT_FOUND One or more EFI_KMS_KEY_DESCRIPTOR structures + could not be processed properly. KeyDescriptorCount + contains the number of structures which were successfully + processed. Individual structures will reflect the status of the + processing for that structure. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_KMS_CREATE_KEY) ( + IN EFI_KMS_PROTOCOL *This, + IN EFI_KMS_CLIENT_INFO *Client, + IN OUT UINT16 *KeyDescriptorCount, + IN OUT EFI_KMS_KEY_DESCRIPTOR *KeyDescriptors, + IN OUT UINTN *ClientDataSize OPTIONAL, + IN OUT VOID **ClientData OPTIONAL + ); + +/** + Retrieve an existing key. + + @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. + @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. + @param[in, out] KeyDescriptorCount Pointer to a count of the number of key descriptors to be + processed by this operation. On return, this number + will be updated with the number of key descriptors + successfully processed. + @param[in, out] KeyDescriptors Pointer to an array of EFI_KMS_KEY_DESCRIPTOR + structures which describe the keys to be retrieved + from the KMS. + On input, the KeyIdentifierSize and the KeyIdentifier + must specify an identifier to be used to retrieve a + specific key. All other fields in the descriptor should + be NULL. + On output, the KeyIdentifierSize and KeyIdentifier fields + will be unchanged, while the KeyFormat and KeyValue + fields will be updated values associated with this key + identifier. Memory for the KeyValue field will be + allocated with the BOOT_SERVICES_DATA type and + must be freed by the caller when it is no longer needed. + Also, the KeyStatus field will reflect the result of the + request relative to the individual key descriptor. + @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of + data specified by the ClientData parameter. This + parameter may be NULL, in which case the ClientData + parameter will be ignored and no data will be + transferred to or from the KMS. If the parameter is + not NULL, then ClientData must be a valid pointer. + If the value pointed to is 0, no data will be transferred + to the KMS, but data may be returned by the KMS. + For all non-zero values *ClientData will be transferred + to the KMS, which may also return data to the caller. + In all cases, the value upon return to the caller will + be the size of the data block returned to the caller, + which will be zero if no data is returned from the KMS. + @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of + *ClientDataSize that is to be passed directly to the + KMS if it supports the use of client data. This + parameter may be NULL if and only if the + ClientDataSize parameter is also NULL. Upon return to + the caller, *ClientData points to a block of data of + *ClientDataSize that was returned from the KMS. + If the returned value for *ClientDataSize is zero, + then the returned value for *ClientData must be NULL + and should be ignored by the caller. The KMS protocol + consumer is responsible for freeing all valid buffers + used for client data regardless of whether they are + allocated by the caller for input to the function or by + the implementation for output back to the caller. + + @retval EFI_SUCCESS Successfully retrieved all requested keys. + @retval EFI_OUT_OF_RESOURCES Could not allocate resources for the method processing. + @retval EFI_TIMEOUT Timed out waiting for device or key server. Check individual key + request(s) to see which ones may have been processed. + @retval EFI_BUFFER_TOO_SMALL If multiple keys are associated with a single identifier, and the + KeyValue buffer does not contain enough structures + (KeyDescriptorCount) to contain all the key data, then + the available structures will be filled and + KeyDescriptorCount will be updated to indicate the + number of keys which could not be processed. + @retval EFI_ACCESS_DENIED Access was denied by the device or the key server; OR a + ClientId is required by the server and either none or an + invalid id was provided. + @retval EFI_DEVICE_ERROR Device or key server error. Check individual key request(s) to + see which ones may have been processed. + @retval EFI_INVALID_PARAMETER This is NULL, ClientId is required but it is NULL, + KeyDescriptorCount is NULL, or Keys is NULL. + @retval EFI_NOT_FOUND One or more EFI_KMS_KEY_DESCRIPTOR structures + could not be processed properly. KeyDescriptorCount + contains the number of structures which were successfully + processed. Individual structures will reflect the status of the + processing for that structure. + @retval EFI_UNSUPPORTED The implementation/KMS does not support this function. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_KMS_GET_KEY) ( + IN EFI_KMS_PROTOCOL *This, + IN EFI_KMS_CLIENT_INFO *Client, + IN OUT UINT16 *KeyDescriptorCount, + IN OUT EFI_KMS_KEY_DESCRIPTOR *KeyDescriptors, + IN OUT UINTN *ClientDataSize OPTIONAL, + IN OUT VOID **ClientData OPTIONAL + ); + +/** + Add a new key. + + @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. + @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. + @param[in, out] KeyDescriptorCount Pointer to a count of the number of key descriptors to be + processed by this operation. On normal return, this + number will be updated with the number of key + descriptors successfully processed. + @param[in, out] KeyDescriptors Pointer to an array of EFI_KMS_KEY_DESCRIPTOR + structures which describe the keys to be added. + On input, the KeyId field for first key must contain + valid identifier data to be used for adding a key to + the KMS. The values for these fields in this key + definition will be considered default values for + subsequent keys requested in this operation. A value + of 0 in any subsequent KeyId field will be replaced + with the current default value. The KeyFormat and + KeyValue fields for each key to be added must contain + consistent values to be associated with the given KeyId. + On return, the KeyStatus field will reflect the result + of the operation for each key request. + @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of + data specified by the ClientData parameter. This + parameter may be NULL, in which case the ClientData + parameter will be ignored and no data will be + transferred to or from the KMS. If the parameter is + not NULL, then ClientData must be a valid pointer. + If the value pointed to is 0, no data will be transferred + to the KMS, but data may be returned by the KMS. + For all non-zero values *ClientData will be transferred + to the KMS, which may also return data to the caller. + In all cases, the value upon return to the caller will + be the size of the data block returned to the caller, + which will be zero if no data is returned from the KMS. + @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of + *ClientDataSize that is to be passed directly to the + KMS if it supports the use of client data. This + parameter may be NULL if and only if the + ClientDataSize parameter is also NULL. Upon return to + the caller, *ClientData points to a block of data of + *ClientDataSize that was returned from the KMS. + If the returned value for *ClientDataSize is zero, + then the returned value for *ClientData must be NULL + and should be ignored by the caller. The KMS protocol + consumer is responsible for freeing all valid buffers + used for client data regardless of whether they are + allocated by the caller for input to the function or by + the implementation for output back to the caller. + + @retval EFI_SUCCESS Successfully added all requested keys. + @retval EFI_OUT_OF_RESOURCES Could not allocate required resources. + @retval EFI_TIMEOUT Timed out waiting for device or key server. Check individual key + request(s) to see which ones may have been processed. + @retval EFI_BUFFER_TOO_SMALL If multiple keys are associated with a single identifier, and the + KeyValue buffer does not contain enough structures + (KeyDescriptorCount) to contain all the key data, then + the available structures will be filled and + KeyDescriptorCount will be updated to indicate the + number of keys which could not be processed + @retval EFI_ACCESS_DENIED Access was denied by the device or the key server; OR a + ClientId is required by the server and either none or an + invalid id was provided. + @retval EFI_DEVICE_ERROR Device or key server error. Check individual key request(s) to + see which ones may have been processed. + @retval EFI_INVALID_PARAMETER This is NULL, ClientId is required but it is NULL, + KeyDescriptorCount is NULL, or Keys is NULL. + @retval EFI_NOT_FOUND One or more EFI_KMS_KEY_DESCRIPTOR structures + could not be processed properly. KeyDescriptorCount + contains the number of structures which were successfully + processed. Individual structures will reflect the status of the + processing for that structure. + @retval EFI_UNSUPPORTED The implementation/KMS does not support this function. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_KMS_ADD_KEY) ( + IN EFI_KMS_PROTOCOL *This, + IN EFI_KMS_CLIENT_INFO *Client, + IN OUT UINT16 *KeyDescriptorCount, + IN OUT EFI_KMS_KEY_DESCRIPTOR *KeyDescriptors, + IN OUT UINTN *ClientDataSize OPTIONAL, + IN OUT VOID **ClientData OPTIONAL + ); + +/** + Delete an existing key from the KMS database. + + @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. + @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. + @param[in, out] KeyDescriptorCount Pointer to a count of the number of key descriptors to be + processed by this operation. On normal return, this + number will be updated with the number of key + descriptors successfully processed. + @param[in, out] KeyDescriptors Pointer to an array of EFI_KMS_KEY_DESCRIPTOR + structures which describe the keys to be deleted. + On input, the KeyId field for first key must contain + valid identifier data to be used for adding a key to + the KMS. The values for these fields in this key + definition will be considered default values for + subsequent keys requested in this operation. A value + of 0 in any subsequent KeyId field will be replaced + with the current default value. The KeyFormat and + KeyValue fields are ignored, but should be 0. + On return, the KeyStatus field will reflect the result + of the operation for each key request. + @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of + data specified by the ClientData parameter. This + parameter may be NULL, in which case the ClientData + parameter will be ignored and no data will be + transferred to or from the KMS. If the parameter is + not NULL, then ClientData must be a valid pointer. + If the value pointed to is 0, no data will be transferred + to the KMS, but data may be returned by the KMS. + For all non-zero values *ClientData will be transferred + to the KMS, which may also return data to the caller. + In all cases, the value upon return to the caller will + be the size of the data block returned to the caller, + which will be zero if no data is returned from the KMS. + @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of + *ClientDataSize that is to be passed directly to the + KMS if it supports the use of client data. This + parameter may be NULL if and only if the + ClientDataSize parameter is also NULL. Upon return to + the caller, *ClientData points to a block of data of + *ClientDataSize that was returned from the KMS. + If the returned value for *ClientDataSize is zero, + then the returned value for *ClientData must be NULL + and should be ignored by the caller. The KMS protocol + consumer is responsible for freeing all valid buffers + used for client data regardless of whether they are + allocated by the caller for input to the function or by + the implementation for output back to the caller. + + @retval EFI_SUCCESS Successfully deleted all requested keys. + @retval EFI_OUT_OF_RESOURCES Could not allocate required resources. + @retval EFI_TIMEOUT Timed out waiting for device or key server. Check individual key + request(s) to see which ones may have been processed. + @retval EFI_ACCESS_DENIED Access was denied by the device or the key server; OR a + ClientId is required by the server and either none or an + invalid id was provided. + @retval EFI_DEVICE_ERROR Device or key server error. Check individual key request(s) to + see which ones may have been processed. + @retval EFI_INVALID_PARAMETER This is NULL, ClientId is required but it is NULL, + KeyDescriptorCount is NULL, or Keys is NULL. + @retval EFI_NOT_FOUND One or more EFI_KMS_KEY_DESCRIPTOR structures + could not be processed properly. KeyDescriptorCount + contains the number of structures which were successfully + processed. Individual structures will reflect the status of the + processing for that structure. + @retval EFI_UNSUPPORTED The implementation/KMS does not support this function. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_KMS_DELETE_KEY) ( + IN EFI_KMS_PROTOCOL *This, + IN EFI_KMS_CLIENT_INFO *Client, + IN OUT UINT16 *KeyDescriptorCount, + IN OUT EFI_KMS_KEY_DESCRIPTOR *KeyDescriptors, + IN OUT UINTN *ClientDataSize OPTIONAL, + IN OUT VOID **ClientData OPTIONAL + ); + +/** + Get one or more attributes associated with a specified key identifier. + If none are found, the returned attributes count contains a value of zero. + + @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. + @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. + @param[in] KeyIdentifierSize Pointer to the size in bytes of the KeyIdentifier variable. + @param[in] KeyIdentifier Pointer to the key identifier associated with this key. + @param[in, out] KeyAttributesCount Pointer to the number of EFI_KMS_KEY_ATTRIBUTE + structures associated with the Key identifier. If none + are found, the count value is zero on return. + On input this value reflects the number of KeyAttributes + that may be returned. + On output, the value reflects the number of completed + KeyAttributes structures found. + @param[in, out] KeyAttributes Pointer to an array of EFI_KMS_KEY_ATTRIBUTE + structures associated with the Key Identifier. + On input, the fields in the structure should be NULL. + On output, the attribute fields will have updated values + for attributes associated with this key identifier. + @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of + data specified by the ClientData parameter. This + parameter may be NULL, in which case the ClientData + parameter will be ignored and no data will be + transferred to or from the KMS. If the parameter is + not NULL, then ClientData must be a valid pointer. + If the value pointed to is 0, no data will be transferred + to the KMS, but data may be returned by the KMS. + For all non-zero values *ClientData will be transferred + to the KMS, which may also return data to the caller. + In all cases, the value upon return to the caller will + be the size of the data block returned to the caller, + which will be zero if no data is returned from the KMS. + @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of + *ClientDataSize that is to be passed directly to the + KMS if it supports the use of client data. This + parameter may be NULL if and only if the + ClientDataSize parameter is also NULL. Upon return to + the caller, *ClientData points to a block of data of + *ClientDataSize that was returned from the KMS. + If the returned value for *ClientDataSize is zero, + then the returned value for *ClientData must be NULL + and should be ignored by the caller. The KMS protocol + consumer is responsible for freeing all valid buffers + used for client data regardless of whether they are + allocated by the caller for input to the function or by + the implementation for output back to the caller. + + @retval EFI_SUCCESS Successfully retrieved all key attributes. + @retval EFI_OUT_OF_RESOURCES Could not allocate resources for the method processing. + @retval EFI_TIMEOUT Timed out waiting for device or key server. Check individual key + attribute request(s) to see which ones may have been + processed. + @retval EFI_BUFFER_TOO_SMALL If multiple key attributes are associated with a single identifier, + and the KeyAttributes buffer does not contain enough + structures (KeyAttributesCount) to contain all the key + attributes data, then the available structures will be filled and + KeyAttributesCount will be updated to indicate the + number of key attributes which could not be processed. + @retval EFI_ACCESS_DENIED Access was denied by the device or the key server; OR a + ClientId is required by the server and either none or an + invalid id was provided. + @retval EFI_DEVICE_ERROR Device or key server error. Check individual key attribute + request(s) (i.e. key attribute status for each) to see which ones + may have been processed. + @retval EFI_INVALID_PARAMETER This is NULL, ClientId is required but it is NULL, + KeyIdentifierSize is NULL , or KeyIdentifier + is NULL, or KeyAttributes is NULL, or + KeyAttributesSize is NULL. + @retval EFI_NOT_FOUND The KeyIdentifier could not be found. + KeyAttributesCount contains zero. Individual + structures will reflect the status of the processing for that + structure. + @retval EFI_UNSUPPORTED The implementation/KMS does not support this function. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_KMS_GET_KEY_ATTRIBUTES) ( + IN EFI_KMS_PROTOCOL *This, + IN EFI_KMS_CLIENT_INFO *Client, + IN UINT8 *KeyIdentifierSize, + IN CONST VOID *KeyIdentifier, + IN OUT UINT16 *KeyAttributesCount, + IN OUT EFI_KMS_KEY_ATTRIBUTE *KeyAttributes, + IN OUT UINTN *ClientDataSize OPTIONAL, + IN OUT VOID **ClientData OPTIONAL + ); + +/** + Add one or more attributes to a key specified by a key identifier. + + @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. + @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. + @param[in] KeyIdentifierSize Pointer to the size in bytes of the KeyIdentifier variable. + @param[in] KeyIdentifier Pointer to the key identifier associated with this key. + @param[in, out] KeyAttributesCount Pointer to the number of EFI_KMS_KEY_ATTRIBUTE + structures to associate with the Key. On normal returns, + this number will be updated with the number of key + attributes successfully processed. + @param[in, out] KeyAttributes Pointer to an array of EFI_KMS_KEY_ATTRIBUTE + structures providing the attribute information to + associate with the key. + On input, the values for the fields in the structure + are completely filled in. + On return the KeyAttributeStatus field will reflect the + result of the operation for each key attribute request. + @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of + data specified by the ClientData parameter. This + parameter may be NULL, in which case the ClientData + parameter will be ignored and no data will be + transferred to or from the KMS. If the parameter is + not NULL, then ClientData must be a valid pointer. + If the value pointed to is 0, no data will be transferred + to the KMS, but data may be returned by the KMS. + For all non-zero values *ClientData will be transferred + to the KMS, which may also return data to the caller. + In all cases, the value upon return to the caller will + be the size of the data block returned to the caller, + which will be zero if no data is returned from the KMS. + @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of + *ClientDataSize that is to be passed directly to the + KMS if it supports the use of client data. This + parameter may be NULL if and only if the + ClientDataSize parameter is also NULL. Upon return to + the caller, *ClientData points to a block of data of + *ClientDataSize that was returned from the KMS. + If the returned value for *ClientDataSize is zero, + then the returned value for *ClientData must be NULL + and should be ignored by the caller. The KMS protocol + consumer is responsible for freeing all valid buffers + used for client data regardless of whether they are + allocated by the caller for input to the function or by + the implementation for output back to the caller. + + @retval EFI_SUCCESS Successfully added all requested key attributes. + @retval EFI_OUT_OF_RESOURCES Could not allocate required resources. + @retval EFI_TIMEOUT Timed out waiting for device or key server. Check individual key + attribute request(s) to see which ones may have been + processed. + @retval EFI_BUFFER_TOO_SMALL If multiple keys attributes are associated with a single key + identifier, and the attributes buffer does not contain + enough structures (KeyAttributesCount) to contain all + the data, then the available structures will be filled and + KeyAttributesCount will be updated to indicate the + number of key attributes which could not be processed. The + status of each key attribute is also updated indicating success or + failure for that attribute in case there are other errors for those + attributes that could be processed. + @retval EFI_ACCESS_DENIED Access was denied by the device or the key server; OR a + ClientId is required by the server and either none or an + invalid id was provided. + @retval EFI_DEVICE_ERROR Device or key server error. Check individual key attribute + request(s) (i.e. key attribute status for each) to see which ones + may have been processed. + @retval EFI_INVALID_PARAMETER This is NULL, ClientId is required but it is NULL, + KeyAttributesCount is NULL, or KeyAttributes + is NULL, or KeyIdentifierSize is NULL, or + KeyIdentifer is NULL. + @retval EFI_NOT_FOUND The KeyIdentifier could not be found. On return the + KeyAttributesCount contains the number of attributes + processed. Individual structures will reflect the status of the + processing for that structure. + @retval EFI_UNSUPPORTED The implementation/KMS does not support this function. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_KMS_ADD_KEY_ATTRIBUTES) ( + IN EFI_KMS_PROTOCOL *This, + IN EFI_KMS_CLIENT_INFO *Client, + IN UINT8 *KeyIdentifierSize, + IN CONST VOID *KeyIdentifier, + IN OUT UINT16 *KeyAttributesCount, + IN OUT EFI_KMS_KEY_ATTRIBUTE *KeyAttributes, + IN OUT UINTN *ClientDataSize OPTIONAL, + IN OUT VOID **ClientData OPTIONAL + ); + +/** + Delete attributes to a key specified by a key identifier. + + @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. + @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. + @param[in] KeyIdentifierSize Pointer to the size in bytes of the KeyIdentifier variable. + @param[in] KeyIdentifier Pointer to the key identifier associated with this key. + @param[in, out] KeyAttributesCount Pointer to the number of EFI_KMS_KEY_ATTRIBUTE + structures to associate with the Key. + On input, the count value is one or more. + On normal returns, this number will be updated with + the number of key attributes successfully processed. + @param[in, out] KeyAttributes Pointer to an array of EFI_KMS_KEY_ATTRIBUTE + structures providing the attribute information to + associate with the key. + On input, the values for the fields in the structure + are completely filled in. + On return the KeyAttributeStatus field will reflect the + result of the operation for each key attribute request. + @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of + data specified by the ClientData parameter. This + parameter may be NULL, in which case the ClientData + parameter will be ignored and no data will be + transferred to or from the KMS. If the parameter is + not NULL, then ClientData must be a valid pointer. + If the value pointed to is 0, no data will be transferred + to the KMS, but data may be returned by the KMS. + For all non-zero values *ClientData will be transferred + to the KMS, which may also return data to the caller. + In all cases, the value upon return to the caller will + be the size of the data block returned to the caller, + which will be zero if no data is returned from the KMS. + @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of + *ClientDataSize that is to be passed directly to the + KMS if it supports the use of client data. This + parameter may be NULL if and only if the + ClientDataSize parameter is also NULL. Upon return to + the caller, *ClientData points to a block of data of + *ClientDataSize that was returned from the KMS. + If the returned value for *ClientDataSize is zero, + then the returned value for *ClientData must be NULL + and should be ignored by the caller. The KMS protocol + consumer is responsible for freeing all valid buffers + used for client data regardless of whether they are + allocated by the caller for input to the function or by + the implementation for output back to the caller. + + @retval EFI_SUCCESS Successfully deleted all requested key attributes. + @retval EFI_OUT_OF_RESOURCES Could not allocate required resources. + @retval EFI_TIMEOUT Timed out waiting for device or key server. Check individual key + attribute request(s) to see which ones may have been + processed. + @retval EFI_ACCESS_DENIED Access was denied by the device or the key server; OR a + ClientId is required by the server and either none or an + invalid id was provided. + @retval EFI_DEVICE_ERROR Device or key server error. Check individual key attribute + request(s) (i.e. key attribute status for each) to see which ones + may have been processed. + @retval EFI_INVALID_PARAMETER This is NULL, ClientId is required but it is NULL, + KeyAttributesCount is NULL, or + KeyAttributes is NULL, or KeyIdentifierSize + is NULL, or KeyIdentifer is NULL. + @retval EFI_NOT_FOUND The KeyIdentifier could not be found or the attribute + could not be found. On return the KeyAttributesCount + contains the number of attributes processed. Individual + structures will reflect the status of the processing for that + structure. + @retval EFI_UNSUPPORTED The implementation/KMS does not support this function. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_KMS_DELETE_KEY_ATTRIBUTES) ( + IN EFI_KMS_PROTOCOL *This, + IN EFI_KMS_CLIENT_INFO *Client, + IN UINT8 *KeyIdentifierSize, + IN CONST VOID *KeyIdentifier, + IN OUT UINT16 *KeyAttributesCount, + IN OUT EFI_KMS_KEY_ATTRIBUTE *KeyAttributes, + IN OUT UINTN *ClientDataSize OPTIONAL, + IN OUT VOID **ClientData OPTIONAL + ); + +/** + Retrieve one or more key that has matched all of the specified key attributes. + + @param[in] This Pointer to the EFI_KMS_PROTOCOL instance. + @param[in] Client Pointer to a valid EFI_KMS_CLIENT_INFO structure. + @param[in, out] KeyAttributesCount Pointer to a count of the number of key attribute structures + that must be matched for each returned key descriptor. + On input the count value is one or more. + On normal returns, this number will be updated with + the number of key attributes successfully processed. + @param[in, out] KeyAttributes Pointer to an array of EFI_KMS_KEY_ATTRIBUTE + structure to search for. + On input, the values for the fields in the structure are + completely filled in. + On return the KeyAttributeStatus field will reflect the + result of the operation for each key attribute request. + @param[in, out] KeyDescriptorCount Pointer to a count of the number of key descriptors matched + by this operation. + On entry, this number will be zero. + On return, this number will be updated to the number + of key descriptors successfully found. + @param[in, out] KeyDescriptors Pointer to an array of EFI_KMS_KEY_DESCRIPTOR + structures which describe the keys from the KMS + having the KeyAttribute(s) specified. + On input, this pointer will be NULL. + On output, the array will contain an + EFI_KMS_KEY_DESCRIPTOR structure for each key + meeting the search criteria. Memory for the array + and all KeyValue fields will be allocated with the + EfiBootServicesData type and must be freed by the + caller when it is no longer needed. Also, the KeyStatus + field of each descriptor will reflect the result of the + request relative to that key descriptor. + @param[in, out] ClientDataSize Pointer to the size, in bytes, of an arbitrary block of + data specified by the ClientData parameter. This + parameter may be NULL, in which case the ClientData + parameter will be ignored and no data will be + transferred to or from the KMS. If the parameter is + not NULL, then ClientData must be a valid pointer. + If the value pointed to is 0, no data will be transferred + to the KMS, but data may be returned by the KMS. + For all non-zero values *ClientData will be transferred + to the KMS, which may also return data to the caller. + In all cases, the value upon return to the caller will + be the size of the data block returned to the caller, + which will be zero if no data is returned from the KMS. + @param[in, out] ClientData Pointer to a pointer to an arbitrary block of data of + *ClientDataSize that is to be passed directly to the + KMS if it supports the use of client data. This + parameter may be NULL if and only if the + ClientDataSize parameter is also NULL. Upon return to + the caller, *ClientData points to a block of data of + *ClientDataSize that was returned from the KMS. + If the returned value for *ClientDataSize is zero, + then the returned value for *ClientData must be NULL + and should be ignored by the caller. The KMS protocol + consumer is responsible for freeing all valid buffers + used for client data regardless of whether they are + allocated by the caller for input to the function or by + the implementation for output back to the caller. + + @retval EFI_SUCCESS Successfully retrieved all requested keys. + @retval EFI_OUT_OF_RESOURCES Could not allocate required resources. + @retval EFI_TIMEOUT Timed out waiting for device or key server. Check individual key + attribute request(s) to see which ones may have been + processed. + @retval EFI_BUFFER_TOO_SMALL If multiple keys are associated with the attribute(s), and the + KeyValue buffer does not contain enough structures + (KeyDescriptorCount) to contain all the key data, then + the available structures will be filled and + KeyDescriptorCount will be updated to indicate the + number of keys which could not be processed. + @retval EFI_ACCESS_DENIED Access was denied by the device or the key server; OR a + ClientId is required by the server and either none or an + invalid id was provided. + @retval EFI_DEVICE_ERROR Device or key server error. Check individual key attribute + request(s) (i.e. key attribute status for each) to see which ones + may have been processed. + @retval EFI_INVALID_PARAMETER This is NULL, ClientId is required but it is NULL, + KeyDescriptorCount is NULL, or + KeyDescriptors is NULL or KeyAttributes is + NULL, or KeyAttributesCount is NULL. + @retval EFI_NOT_FOUND One or more EFI_KMS_KEY_ATTRIBUTE structures could + not be processed properly. KeyAttributeCount contains + the number of structures which were successfully processed. + Individual structures will reflect the status of the processing for + that structure. + @retval EFI_UNSUPPORTED The implementation/KMS does not support this function. + +**/ +typedef +EFI_STATUS +(EFIAPI *EFI_KMS_GET_KEY_BY_ATTRIBUTES) ( + IN EFI_KMS_PROTOCOL *This, + IN EFI_KMS_CLIENT_INFO *Client, + IN OUT UINTN *KeyAttributeCount, + IN OUT EFI_KMS_KEY_ATTRIBUTE *KeyAttributes, + IN OUT UINTN *KeyDescriptorCount, + IN OUT EFI_KMS_KEY_DESCRIPTOR *KeyDescriptors, + IN OUT UINTN *ClientDataSize OPTIONAL, + IN OUT VOID **ClientData OPTIONAL + ); + +/// +/// The Key Management Service (KMS) protocol provides services to generate, store, retrieve, +/// and manage cryptographic keys. +/// +struct _EFI_KMS_PROTOCOL { + /// + /// Get the current status of the key management service. If the implementation has not yet + /// connected to the KMS, then a call to this function will initiate a connection. This is the + /// only function that is valid for use prior to the service being marked available. + /// + EFI_KMS_GET_SERVICE_STATUS GetServiceStatus; + /// + /// Register a specific client with the KMS. + /// + EFI_KMS_REGISTER_CLIENT RegisterClient; + /// + /// Request the generation of a new key and retrieve it. + /// + EFI_KMS_CREATE_KEY CreateKey; + /// + /// Retrieve an existing key. + /// + EFI_KMS_GET_KEY GetKey; + /// + /// Add a local key to KMS database. If there is an existing key with this key identifier in the + /// KMS database, it will be replaced with the new key. + /// + EFI_KMS_ADD_KEY AddKey; + /// + /// Delete an existing key from the KMS database. + /// + EFI_KMS_DELETE_KEY DeleteKey; + /// + /// Get attributes for an existing key in the KMS database. + /// + EFI_KMS_GET_KEY_ATTRIBUTES GetKeyAttributes; + /// + /// Add attributes to an existing key in the KMS database. + /// + EFI_KMS_ADD_KEY_ATTRIBUTES AddKeyAttributes; + /// + /// Delete attributes for an existing key in the KMS database. + /// + EFI_KMS_DELETE_KEY_ATTRIBUTES DeleteKeyAttributes; + /// + /// Get existing key(s) with the specified attributes. + /// + EFI_KMS_GET_KEY_BY_ATTRIBUTES GetKeyByAttributes; + /// + /// The version of this EFI_KMS_PROTOCOL structure. This must be set to 0x00020040 for + /// the initial version of this protocol. + /// + UINT32 ProtocolVersion; + /// + /// Optional GUID used to identify a specific KMS. This GUID may be supplied by the provider, + /// by the implementation, or may be null. If is null, then the ServiceName must not be null. + /// + EFI_GUID ServiceId; + /// + /// Optional pointer to a unicode string which may be used to identify the KMS or provide + /// other information about the supplier. + /// + CHAR16 *ServiceName; + /// + /// Optional 32-bit value which may be used to indicate the version of the KMS provided by + /// the supplier. + /// + UINT32 ServiceVersion; + /// + /// TRUE if and only if the service is active and available for use. To avoid unnecessary + /// delays in POST, this protocol may be installed without connecting to the service. In this + /// case, the first call to the GetServiceStatus () function will cause the implementation to + /// connect to the supported service and mark it as available. The capabilities of this service + /// as defined in the reminder of this protocol are not guaranteed to be valid until the service + /// has been marked available. + /// + BOOLEAN ServiceAvailable; + /// + /// TRUE if and only if the service supports client identifiers. Client identifiers may be used + /// for auditing, access control or any other purpose specific to the implementation. + /// + BOOLEAN ClientIdSupported; + /// + /// TRUE if and only if the service requires a client identifier in order to process key requests. + /// FALSE otherwise. + /// + BOOLEAN ClientIdRequired; + /// + /// The maximum size in bytes for the client identifier. + /// + UINT16 ClientIdMaxSize; + /// + /// The client name string type(s) supported by the KMS service. If client names are not + /// supported, this field will be set the EFI_KMS_DATA_TYPE_NONE. Otherwise, it will be set + /// to the inclusive 'OR' of all client name formats supported. Client names may be used for + /// auditing, access control or any other purpose specific to the implementation. + /// + UINT8 ClientNameStringTypes; + /// + /// TRUE if only if the KMS requires a client name to be supplied to the service. + /// FALSE otherwise. + /// + BOOLEAN ClientNameRequired; + /// + /// The maximum number of characters allowed for the client name. + /// + UINT16 ClientNameMaxCount; + /// + /// TRUE if and only if the service supports arbitrary client data requests. The use of client + /// data requires the caller to have specific knowledge of the individual KMS service and + /// should be used only if absolutely necessary. + /// FALSE otherwise. + /// + BOOLEAN ClientDataSupported; + /// + /// The maximum size in bytes for the client data. If the maximum data size is not specified + /// by the KMS or it is not known, then this field must be filled with all ones. + /// + UINTN ClientDataMaxSize; + /// + /// TRUE if variable length key identifiers are supported. + /// FALSE if a fixed length key identifier is supported. + /// + BOOLEAN KeyIdVariableLenSupported; + /// + /// If KeyIdVariableLenSupported is TRUE, this is the maximum supported key identifier length + /// in bytes. Otherwise this is the fixed length of key identifier supported. Key ids shorter + /// than the fixed length will be padded on the right with blanks. + /// + UINTN KeyIdMaxSize; + /// + /// The number of key format/size GUIDs returned in the KeyFormats field. + /// + UINTN KeyFormatsCount; + /// + /// A pointer to an array of EFI_GUID values which specify key formats/sizes supported by + /// this KMS. Each format/size pair will be specified by a separate EFI_GUID. At least one + /// key format/size must be supported. All formats/sizes with the same hashing algorithm + /// must be contiguous in the array, and for each hashing algorithm, the key sizes must be in + /// ascending order. See "Related Definitions" for GUIDs which identify supported key formats/sizes. + /// This list of GUIDs supported by the KMS is not required to be exhaustive, and the KMS + /// may provide support for additional key formats/sizes. Users may request key information + /// using an arbitrary GUID, but any GUID not recognized by the implementation or not + /// supported by the KMS will return an error code of EFI_UNSUPPORTED + /// + EFI_GUID *KeyFormats; + /// + /// TRUE if key attributes are supported. + /// FALSE if key attributes are not supported. + /// + BOOLEAN KeyAttributesSupported; + /// + /// The key attribute identifier string type(s) supported by the KMS service. If key attributes + /// are not supported, this field will be set to EFI_KMS_DATA_TYPE_NONE. Otherwise, it will + /// be set to the inclusive 'OR' of all key attribute identifier string types supported. + /// EFI_KMS_DATA_TYPE_BINARY is not valid for this field. + /// + UINT8 KeyAttributeIdStringTypes; + UINT16 KeyAttributeIdMaxCount; + /// + /// The number of predefined KeyAttributes structures returned in the KeyAttributes + /// parameter. If the KMS does not support predefined key attributes, or if it does not + /// provide a method to obtain predefined key attributes data, then this field must be zero. + /// + UINTN KeyAttributesCount; + /// + /// A pointer to an array of KeyAttributes structures which contains the predefined + /// attributes supported by this KMS. Each structure must contain a valid key attribute + /// identifier and should provide any other information as appropriate for the attribute, + /// including a default value if one exists. This variable must be set to NULL if the + /// KeyAttributesCount variable is zero. It must point to a valid buffer if the + /// KeyAttributesCount variable is non-zero. + /// This list of predefined attributes is not required to be exhaustive, and the KMS may + /// provide additional predefined attributes not enumerated in this list. The implementation + /// does not distinguish between predefined and used defined attributes, and therefore, + /// predefined attributes not enumerated will still be processed to the KMS. + /// + EFI_KMS_KEY_ATTRIBUTE *KeyAttributes; +}; + +extern EFI_GUID gEfiKmsFormatGeneric128Guid; +extern EFI_GUID gEfiKmsFormatGeneric160Guid; +extern EFI_GUID gEfiKmsFormatGeneric256Guid; +extern EFI_GUID gEfiKmsFormatGeneric512Guid; +extern EFI_GUID gEfiKmsFormatGeneric1024Guid; +extern EFI_GUID gEfiKmsFormatGeneric2048Guid; +extern EFI_GUID gEfiKmsFormatGeneric3072Guid; +extern EFI_GUID gEfiKmsFormatMd2128Guid; +extern EFI_GUID gEfiKmsFormatMdc2128Guid; +extern EFI_GUID gEfiKmsFormatMd4128Guid; +extern EFI_GUID gEfiKmsFormatMdc4128Guid; +extern EFI_GUID gEfiKmsFormatMd5128Guid; +extern EFI_GUID gEfiKmsFormatMd5sha128Guid; +extern EFI_GUID gEfiKmsFormatSha1160Guid; +extern EFI_GUID gEfiKmsFormatSha256256Guid; +extern EFI_GUID gEfiKmsFormatSha512512Guid; +extern EFI_GUID gEfiKmsFormatAesxts128Guid; +extern EFI_GUID gEfiKmsFormatAesxts256Guid; +extern EFI_GUID gEfiKmsFormatAescbc128Guid; +extern EFI_GUID gEfiKmsFormatAescbc256Guid; +extern EFI_GUID gEfiKmsFormatRsasha11024Guid; +extern EFI_GUID gEfiKmsFormatRsasha12048Guid; +extern EFI_GUID gEfiKmsFormatRsasha2562048Guid; +extern EFI_GUID gEfiKmsFormatRsasha2563072Guid; +extern EFI_GUID gEfiKmsProtocolGuid; + +#endif |