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