2 The UEFI Inline Cryptographic Interface protocol provides services to abstract
3 access to inline cryptographic capabilities.
5 Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>
6 This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16 #ifndef __BLOCK_IO_CRYPTO_H__
17 #define __BLOCK_IO_CRYPTO_H__
19 #include <Protocol/BlockIo.h>
21 #define EFI_BLOCK_IO_CRYPTO_PROTOCOL_GUID \
23 0xa00490ba, 0x3f1a, 0x4b4c, {0xab, 0x90, 0x4f, 0xa9, 0x97, 0x26, 0xa1, 0xe8} \
26 typedef struct _EFI_BLOCK_IO_CRYPTO_PROTOCOL EFI_BLOCK_IO_CRYPTO_PROTOCOL
;
29 /// The struct of Block I/O Crypto Token.
33 // If Event is NULL, then blocking I/O is performed. If Event is not NULL and
34 // non-blocking I/O is supported, then non-blocking I/O is performed, and
35 // Event will be signaled when the read request is completed and data was
36 // decrypted (when Index was specified).
40 // Defines whether or not the signaled event encountered an error.
42 EFI_STATUS TransactionStatus
;
43 } EFI_BLOCK_IO_CRYPTO_TOKEN
;
47 Reset the block device hardware.
49 The Reset() function resets the block device hardware.
51 As part of the initialization process, the firmware/device will make a quick but
52 reasonable attempt to verify that the device is functioning.
54 If the ExtendedVerificationflag is TRUE the firmware may take an extended amount
55 of time to verify the device is operating on reset. Otherwise the reset operation
56 is to occur as quickly as possible.
58 The hardware verification process is not defined by this specification and is left
59 up to the platform firmware or driver to implement.
61 @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance.
62 @param[in] ExtendedVerification Indicates that the driver may perform a more exhausive
63 verfication operation of the device during reset.
65 @retval EFI_SUCCESS The block device was reset.
66 @retval EFI_DEVICE_ERROR The block device is not functioning correctly and could
68 @retval EFI_INVALID_PARAMETER This is NULL.
73 (EFIAPI
*EFI_BLOCK_IO_CRYPTO_RESET
) (
74 IN EFI_BLOCK_IO_CRYPTO_PROTOCOL
*This
,
75 IN BOOLEAN ExtendedVerification
79 Get the capabilities of the underlying inline cryptographic interface.
81 The GetCapabilities() function determines whether pre-OS controllable inline crypto
82 is supported by the system for the current disk and, if so, returns the capabilities
85 The caller is responsible for providing the Capabilities structure with a sufficient
88 If the structure is too small, the EFI_BUFFER_TOO_SMALL error code is returned and the
89 CapabilityCount field contains the number of entries needed to contain the capabilities.
91 @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance.
92 @param[out] Capabilities Pointer to the EFI_BLOCK_IO_CRYPTO_CAPABILITIES structure.
94 @retval EFI_SUCCESS The ICI is ready for use.
95 @retval EFI_BUFFER_TOO_SMALL The Capabilities structure was too small. The number of
96 entries needed is returned in the CapabilityCount field
98 @retval EFI_NO_RESPONSE No response was received from the ICI.
99 @retval EFI_DEVICE_ERROR An error occurred when attempting to access the ICI.
100 @retval EFI_INVALID_PARAMETER This is NULL.
101 @retval EFI_INVALID_PARAMETER Capabilities is NULL.
106 (EFIAPI
*EFI_BLOCK_IO_CRYPTO_GET_CAPABILITIES
) (
107 IN EFI_BLOCK_IO_CRYPTO_PROTOCOL
*This
,
108 OUT EFI_BLOCK_IO_CRYPTO_CAPABILITIES
*Capabilities
112 Set the configuration of the underlying inline cryptographic interface.
114 The SetConfiguration() function allows the user to set the current configuration of the
115 inline cryptographic interface and should be called before attempting any crypto operations.
117 This configures the configuration table entries with algorithms, key sizes and keys. Each
118 configured entry can later be referred to by index at the time of storage transaction.
120 The configuration table index will refer to the combination ofKeyOwnerGuid, Algorithm, and
123 KeyOwnerGuid identifies the component taking ownership of the entry. It helps components to
124 identify their own entries, cooperate with other owner components, and avoid conflicts. This
125 Guid identifier is there to help coordination between cooperating components and not a security
126 or synchronization feature. The Nil GUID can be used by a component to release use of entry
127 owned. It is also used to identify potentially available entries (see GetConfiguration).
129 CryptoKey specifies algorithm-specific key material to use within parameters of selected crypto
132 This function is called infrequently typically once, on device start, before IO starts. It
133 can be called at later times in cases the number of keysused on the drive is higher than what
134 can be configured at a time or a new key has to be added.
136 Components setting or changing an entry or entries for a given index or indices must ensure
137 that IO referencing affected indices is temporarily blocked (run-down) at the time of change.
139 Indices parameters in each parameter table entry allow to set only a portion of the available
140 table entries in the crypto module anywhere from single entry to entire table supported.
142 If corresponding table entry or entries being set are already in use by another owner the call
143 should be failed and none of the entries should be modified. The interface implementation must
144 enforce atomicity of this operation (should either succeed fully or fail completely without
147 Note that components using GetConfiguration command to discover available entries should be
148 prepared that by the time of calling SetConfiguration the previously available entry may have
149 become occupied. Such components should be prepared to re-try the sequence of operations.
151 Alternatively EFI_BLOCK_IO_CRYPTO_INDEX_ANY can be used to have the implementation discover
152 and allocate available,if any, indices atomically.
154 An optional ResultingTable pointer can be provided by the caller to receive the newly configured
155 entries. The array provided by the caller must have at least ConfigurationCount of entries.
157 @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance.
158 @param[in] ConfigurationCount Number of entries being configured with this call.
159 @param[in] ConfigurationTable Pointer to a table used to populate the configuration table.
160 @param[out] ResultingTable Optional pointer to a table that receives the newly configured
163 @retval EFI_SUCCESS The ICI is ready for use.
164 @retval EFI_NO_RESPONSE No response was received from the ICI.
165 @retval EFI_DEVICE_ERROR An error occurred when attempting to access the ICI.
166 @retval EFI_INVALID_PARAMETER This is NULL.
167 @retval EFI_INVALID_PARAMETER ConfigurationTable is NULL.
168 @retval EFI_INVALID_PARAMETER ConfigurationCount is 0.
169 @retval EFI_OUT_OF_RESOURCES Could not find the requested number of available entries in the
175 (EFIAPI
*EFI_BLOCK_IO_CRYPTO_SET_CONFIGURATION
) (
176 IN EFI_BLOCK_IO_CRYPTO_PROTOCOL
*This
,
177 IN UINT64 ConfigurationCount
,
178 IN EFI_BLOCK_IO_CRYPTO_CONFIGURATION_TABLE_ENTRY
*ConfigurationTable
,
179 OUT EFI_BLOCK_IO_CRYPTO_RESPONSE_CONFIGURATION_ENTRY
*ResultingTable OPTIONAL
184 Get the configuration of the underlying inline cryptographic interface.
186 The GetConfiguration() function allows the user to get the configuration of the inline
187 cryptographic interface.
189 Retrieves, entirely or partially, the currently configured key table. Note that the keys
190 themselves are not retrieved, but rather just indices, owner GUIDs and capabilities.
192 If fewer entries than specified by ConfigurationCount are returned, the Index field of the
193 unused entries is set to EFI_BLOCK_IO_CRYPTO_INDEX_ANY.
195 @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance.
196 @param[in] StartIndex Configuration table index at which to start the configuration
198 @param[in] ConfigurationCount Number of entries to return in the response table.
199 @param[in] KeyOwnerGuid Optional parameter to filter response down to entries with a
200 given owner. A pointer to the Nil value can be used to return
201 available entries. Set to NULL when no owner filtering is required.
202 @param[out] ConfigurationTable Table of configured configuration table entries (with no CryptoKey
203 returned): configuration table index, KeyOwnerGuid, Capability.
204 Should have sufficient space to store up to ConfigurationCount
207 @retval EFI_SUCCESS The ICI is ready for use.
208 @retval EFI_NO_RESPONSE No response was received from the ICI.
209 @retval EFI_DEVICE_ERROR An error occurred when attempting to access the ICI.
210 @retval EFI_INVALID_PARAMETER This is NULL.
211 @retval EFI_INVALID_PARAMETER Configuration table is NULL.
212 @retval EFI_INVALID_PARAMETER StartIndex is out of bounds.
217 (EFIAPI
*EFI_BLOCK_IO_CRYPTO_GET_CONFIGURATION
) (
218 IN EFI_BLOCK_IO_CRYPTO_PROTOCOL
*This
,
219 IN UINT64 StartIndex
,
220 IN UINT64 ConfigurationCount
,
221 IN EFI_GUID
*KeyOwnerGuid OPTIONAL
,
222 OUT EFI_BLOCK_IO_CRYPTO_RESPONSE_CONFIGURATION_ENTRY
*ConfigurationTable
226 Reads the requested number of blocks from the device and optionally decrypts
229 TheReadExtended() function allows the caller to perform a storage device read
230 operation. The function reads the requested number of blocks from the device
231 and then if Index is specified decrypts them inline. All the blocks are read
232 and decrypted (if decryption requested), or an error is returned.
234 If there is no media in the device, the function returns EFI_NO_MEDIA. If the
235 MediaId is not the ID for the current media in the device, the function returns
238 If EFI_DEVICE_ERROR, EFI_NO_MEDIA, or EFI_MEDIA_CHANGED is returned and nonblocking
239 I/O is being used, the Event associated with this request will not be signaled.
241 In addition to standard storage transaction parameters (LBA, IO size, and buffer),
242 this command will also specify a configuration table Index and CryptoIvInput
243 when data has to be decrypted inline by the controller after being read from
244 the storage device. If an Index parameter is not specified, no decryption is
247 @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance.
248 @param[in] MediaId The media ID that the read request is for.
249 @param[in] LBA The starting logical block address to read from on
251 @param[in, out] Token A pointer to the token associated with the transaction.
252 @param[in] BufferSize The size of the Buffer in bytes. This must be a multiple
253 of the intrinsic block size of the device.
254 @param[out] Buffer A pointer to the destination buffer for the data. The
255 caller is responsible for either having implicit or
256 explicit ownership of the buffer.
257 @param[in] Index A pointer to the configuration table index. This is
259 @param[in] CryptoIvInput A pointer to a buffer that contains additional
260 cryptographic parameters as required by the capability
261 referenced by the configuration table index, such as
262 cryptographic initialization vector.
264 @retval EFI_SUCCESS The read request was queued if Token-> Event is not NULL.
265 The data was read correctly from the device if the
266 Token->Event is NULL.
267 @retval EFI_DEVICE_ERROR The device reported an error while attempting to perform
268 the read operation and/or decryption operation.
269 @retval EFI_NO_MEDIA There is no media in the device.
270 @retval EFI_MEDIA_CHANGED The MediaId is not for the current media.
271 @retval EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the intrinsic
272 block size of the device.
273 @retval EFI_INVALID_PARAMETER This is NULL, or the read request contains LBAs that are
274 not valid, or the buffer is not on proper alignment.
275 @retval EFI_INVALID_PARAMETER CryptoIvInput is incorrect.
276 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of
282 (EFIAPI
*EFI_BLOCK_IO_CRYPTO_READ_EXTENDED
) (
283 IN EFI_BLOCK_IO_CRYPTO_PROTOCOL
*This
,
286 IN OUT EFI_BLOCK_IO_CRYPTO_TOKEN
*Token
,
287 IN UINT64 BufferSize
,
289 IN UINT64
*Index OPTIONAL
,
290 IN VOID
*CryptoIvInput OPTIONAL
294 Optionally encrypts a specified number of blocks inline and then writes to the
297 The WriteExtended() function allows the caller to perform a storage device write
298 operation. The function encrypts the requested number of blocks inline if Index
299 is specified and then writes them to the device. All the blocks are encrypted
300 (if encryption requested) and written, or an error is returned.
302 If there is no media in the device, the function returns EFI_NO_MEDIA. If the
303 MediaId is not the ID for the current media in the device, the function returns
306 If EFI_DEVICE_ERROR, EFI_NO_MEDIA, or EFI_MEDIA_CHANGED is returned and nonblocking
307 I/O is being used, the Event associated with this request will not be signaled.
309 In addition to standard storage transaction parameters (LBA, IO size, and buffer),
310 this command will also specify a configuration table Index and a CryptoIvInput
311 when data has to be decrypted inline by the controller before being written to
312 the storage device. If no Index parameter is specified, no encryption is performed.
314 @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance.
315 @param[in] MediaId The media ID that the read request is for.
316 @param[in] LBA The starting logical block address to read from on
318 @param[in, out] Token A pointer to the token associated with the transaction.
319 @param[in] BufferSize The size of the Buffer in bytes. This must be a multiple
320 of the intrinsic block size of the device.
321 @param[in] Buffer A pointer to the source buffer for the data.
322 @param[in] Index A pointer to the configuration table index. This is
324 @param[in] CryptoIvInput A pointer to a buffer that contains additional
325 cryptographic parameters as required by the capability
326 referenced by the configuration table index, such as
327 cryptographic initialization vector.
329 @retval EFI_SUCCESS The request to encrypt (optionally) and write was queued
330 if Event is not NULL. The data was encrypted (optionally)
331 and written correctly to the device if the Event is NULL.
332 @retval EFI_WRITE_PROTECTED The device cannot be written to.
333 @retval EFI_NO_MEDIA There is no media in the device.
334 @retval EFI_MEDIA_CHANGED The MediaId is not for the current media.
335 @retval EFI_DEVICE_ERROR The device reported an error while attempting to encrypt
336 blocks or to perform the write operation.
337 @retval EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the intrinsic
338 block size of the device.
339 @retval EFI_INVALID_PARAMETER This is NULL, or the write request contains LBAs that are
340 not valid, or the buffer is not on proper alignment.
341 @retval EFI_INVALID_PARAMETER CryptoIvInput is incorrect.
342 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of
348 (EFIAPI
*EFI_BLOCK_IO_CRYPTO_WRITE_EXTENDED
) (
349 IN EFI_BLOCK_IO_CRYPTO_PROTOCOL
*This
,
352 IN OUT EFI_BLOCK_IO_CRYPTO_TOKEN
*Token
,
353 IN UINT64 BufferSize
,
355 IN UINT64
*Index OPTIONAL
,
356 IN VOID
*CryptoIvInput OPTIONAL
360 Flushes all modified data toa physical block device.
362 The FlushBlocks() function flushes all modified data to the physical block device.
363 Any modified data that has to be encrypted must have been already encrypted as a
364 part of WriteExtended() operation - inline crypto operation cannot be a part of
367 All data written to the device prior to the flush must be physically written before
368 returning EFI_SUCCESS from this function. This would include any cached data the
369 driver may have cached, and cached data the device may have cached. A flush may
370 cause a read request following the flush to force a device access.
372 If EFI_DEVICE_ERROR, EFI_NO_MEDIA, EFI_WRITE_PROTECTED or EFI_MEDIA_CHANGED is
373 returned and non-blocking I/O is being used, the Event associated with this request
374 will not be signaled.
376 @param[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance.
377 @param[in, out] Token A pointer to the token associated with the transaction.
379 @retval EFI_SUCCESS The flush request was queued if Event is not NULL. All
380 outstanding data was written correctly to the device if
382 @retval EFI_DEVICE_ERROR The device reported an error while attempting to write data.
383 @retval EFI_WRITE_PROTECTED The device cannot be written to.
384 @retval EFI_NO_MEDIA There is no media in the device.
385 @retval EFI_MEDIA_CHANGED The MediaId is not for the current media.
386 @retval EFI_INVALID_PARAMETER This is NULL.
387 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of
393 (EFIAPI
*EFI_BLOCK_IO_CRYPTO_FLUSH
) (
394 IN EFI_BLOCK_IO_CRYPTO_PROTOCOL
*This
,
395 IN OUT EFI_BLOCK_IO_CRYPTO_TOKEN
*Token
400 // GUID of the algorithm.
404 // Specifies KeySizein bits used with this Algorithm.
408 // Specifies bitmask of block sizes supported by this algorithm.
409 // Bit j being set means that 2^j bytes crypto block size is supported.
411 UINT64 CryptoBlockSizeBitMask
;
412 } EFI_BLOCK_IO_CRYPTO_CAPABILITY
;
415 /// EFI_BLOCK_IO_CRYPTO_IV_INPUT structure is used as a common header in CryptoIvInput
416 /// parameters passed to the ReadExtended and WriteExtended methods for Inline
417 /// Cryptographic Interface.
418 /// Its purpose is to pass size of the entire CryptoIvInputparameter memory buffer to
419 /// the Inline Cryptographic Interface.
423 } EFI_BLOCK_IO_CRYPTO_IV_INPUT
;
425 #define EFI_BLOCK_IO_CRYPTO_ALGO_GUID_AES_XTS \
427 0x2f87ba6a, 0x5c04, 0x4385, {0xa7, 0x80, 0xf3, 0xbf, 0x78, 0xa9, 0x7b, 0xec} \
430 extern EFI_GUID gEfiBlockIoCryptoAlgoAesXtsGuid
;
433 EFI_BLOCK_IO_CRYPTO_IV_INPUT Header
;
434 UINT64 CryptoBlockNumber
;
435 UINT64 CryptoBlockByteSize
;
436 } EFI_BLOCK_IO_CRYPTO_IV_INPUT_AES_XTS
;
438 #define EFI_BLOCK_IO_CRYPTO_ALGO_GUID_AES_CBC_MICROSOFT_BITLOCKER \
440 0x689e4c62, 0x70bf, 0x4cf3, {0x88, 0xbb, 0x33, 0xb3, 0x18, 0x26, 0x86, 0x70} \
443 extern EFI_GUID gEfiBlockIoCryptoAlgoAesCbcMsBitlockerGuid
;
446 EFI_BLOCK_IO_CRYPTO_IV_INPUT Header
;
447 UINT64 CryptoBlockByteOffset
;
448 UINT64 CryptoBlockByteSize
;
449 } EFI_BLOCK_IO_CRYPTO_IV_INPUT_AES_CBC_MICROSOFT_BITLOCKER
;
451 #define EFI_BLOCK_IO_CRYPTO_INDEX_ANY 0xFFFFFFFFFFFFFFFF
455 // Is inline cryptographic capability supported on this device.
459 // Maximum number of keys that can be configured at the same time.
463 // Number of supported capabilities.
465 UINT64 CapabilityCount
;
467 // Array of supported capabilities.
469 EFI_BLOCK_IO_CRYPTO_CAPABILITY Capabilities
[1];
470 } EFI_BLOCK_IO_CRYPTO_CAPABILITIES
;
474 // Configuration table index. A special Index EFI_BLOCK_IO_CRYPTO_INDEX_ANY can be
475 // used to set any available entry in the configuration table.
479 // Identifies the owner of the configuration table entry. Entry can also be used
480 // with the Nil value to clear key from the configuration table index.
482 EFI_GUID KeyOwnerGuid
;
484 // A supported capability to be used. The CryptoBlockSizeBitMask field of the
485 // structure should have only one bit set from the supported mask.
487 EFI_BLOCK_IO_CRYPTO_CAPABILITY Capability
;
489 // Pointer to the key. The size of the key is defined by the KeySize field of
490 // the capability specified by the Capability parameter.
493 } EFI_BLOCK_IO_CRYPTO_CONFIGURATION_TABLE_ENTRY
;
497 // Configuration table index.
501 // Identifies the current owner of the entry.
503 EFI_GUID KeyOwnerGuid
;
505 // The capability to be used. The CryptoBlockSizeBitMask field of the structure
506 // has only one bit set from the supported mask.
508 EFI_BLOCK_IO_CRYPTO_CAPABILITY Capability
;
509 } EFI_BLOCK_IO_CRYPTO_RESPONSE_CONFIGURATION_ENTRY
;
513 /// The EFI_BLOCK_IO_CRYPTO_PROTOCOL defines a UEFI protocol that can be used by UEFI
514 /// drivers and applications to perform block encryption on a storage device, such as UFS.
516 struct _EFI_BLOCK_IO_CRYPTO_PROTOCOL
{
517 EFI_BLOCK_IO_MEDIA
*Media
;
518 EFI_BLOCK_IO_CRYPTO_RESET Reset
;
519 EFI_BLOCK_IO_CRYPTO_GET_CAPABILITIES GetCapabilities
;
520 EFI_BLOCK_IO_CRYPTO_SET_CONFIGURATION SetConfiguration
;
521 EFI_BLOCK_IO_CRYPTO_GET_CONFIGURATION GetConfiguration
;
522 EFI_BLOCK_IO_CRYPTO_READ_EXTENDED ReadExtended
;
523 EFI_BLOCK_IO_CRYPTO_WRITE_EXTENDED WriteExtended
;
524 EFI_BLOCK_IO_CRYPTO_FLUSH FlushBlocks
;
527 extern EFI_GUID gEfiBlockIoCryptoProtocolGuid
;