MdePkg/Include/Protocol/BlockIoCrypto.h File Reference


Data Structures

struct  EFI_BLOCK_IO_CRYPTO_TOKEN
struct  EFI_BLOCK_IO_CRYPTO_CAPABILITY
struct  EFI_BLOCK_IO_CRYPTO_IV_INPUT
struct  EFI_BLOCK_IO_CRYPTO_IV_INPUT_AES_XTS
struct  EFI_BLOCK_IO_CRYPTO_IV_INPUT_AES_CBC_MICROSOFT_BITLOCKER
struct  EFI_BLOCK_IO_CRYPTO_CAPABILITIES
struct  EFI_BLOCK_IO_CRYPTO_CONFIGURATION_TABLE_ENTRY
struct  EFI_BLOCK_IO_CRYPTO_RESPONSE_CONFIGURATION_ENTRY
struct  _EFI_BLOCK_IO_CRYPTO_PROTOCOL

Defines

#define EFI_BLOCK_IO_CRYPTO_PROTOCOL_GUID
#define EFI_BLOCK_IO_CRYPTO_ALGO_GUID_AES_XTS
#define EFI_BLOCK_IO_CRYPTO_ALGO_GUID_AES_CBC_MICROSOFT_BITLOCKER
#define EFI_BLOCK_IO_CRYPTO_INDEX_ANY   0xFFFFFFFFFFFFFFFF

Typedefs

typedef struct
_EFI_BLOCK_IO_CRYPTO_PROTOCOL 
EFI_BLOCK_IO_CRYPTO_PROTOCOL
typedef IN BOOLEAN ExtendedVerification
typedef OUT
EFI_BLOCK_IO_CRYPTO_CAPABILITIES
Capabilities
typedef IN UINT64 ConfigurationCount
typedef IN UINT64 IN
EFI_BLOCK_IO_CRYPTO_CONFIGURATION_TABLE_ENTRY
ConfigurationTable
typedef IN UINT64 IN
EFI_BLOCK_IO_CRYPTO_CONFIGURATION_TABLE_ENTRY
OUT
EFI_BLOCK_IO_CRYPTO_RESPONSE_CONFIGURATION_ENTRY
ResultingTable
typedef IN UINT64 StartIndex
typedef IN UINT64 IN UINT64 IN
EFI_GUID
KeyOwnerGuid
typedef IN UINT32 MediaId
typedef IN UINT32 IN EFI_LBA LBA
typedef IN UINT32 IN EFI_LBA
IN OUT
EFI_BLOCK_IO_CRYPTO_TOKEN
Token
typedef IN UINT32 IN EFI_LBA
IN OUT
EFI_BLOCK_IO_CRYPTO_TOKEN IN
UINT64 
BufferSize
typedef IN UINT32 IN EFI_LBA
IN OUT
EFI_BLOCK_IO_CRYPTO_TOKEN IN
UINT64 OUT VOID * 
Buffer
typedef IN UINT32 IN EFI_LBA
IN OUT
EFI_BLOCK_IO_CRYPTO_TOKEN IN
UINT64 OUT VOID IN UINT64
Index
typedef IN UINT32 IN EFI_LBA
IN OUT
EFI_BLOCK_IO_CRYPTO_TOKEN IN
UINT64 OUT VOID IN UINT64 IN
VOID * 
CryptoIvInput

Functions

typedef EFI_STATUS (EFIAPI *EFI_BLOCK_IO_CRYPTO_RESET)(IN EFI_BLOCK_IO_CRYPTO_PROTOCOL *This

Variables

EFI_GUID gEfiBlockIoCryptoAlgoAesXtsGuid
EFI_GUID gEfiBlockIoCryptoAlgoAesCbcMsBitlockerGuid
EFI_GUID gEfiBlockIoCryptoProtocolGuid

Detailed Description

The UEFI Inline Cryptographic Interface protocol provides services to abstract access to inline cryptographic capabilities.

Copyright (c) 2015, Intel Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License which accompanies this distribution. The full text of the license may be found at http://opensource.org/licenses/bsd-license.php

THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.


Define Documentation

#define EFI_BLOCK_IO_CRYPTO_ALGO_GUID_AES_CBC_MICROSOFT_BITLOCKER

Value:

{ \
      0x689e4c62, 0x70bf, 0x4cf3, {0x88, 0xbb, 0x33, 0xb3, 0x18, 0x26, 0x86, 0x70} \
    }

#define EFI_BLOCK_IO_CRYPTO_ALGO_GUID_AES_XTS

Value:

{ \
      0x2f87ba6a, 0x5c04, 0x4385, {0xa7, 0x80, 0xf3, 0xbf, 0x78, 0xa9, 0x7b, 0xec} \
    }

#define EFI_BLOCK_IO_CRYPTO_INDEX_ANY   0xFFFFFFFFFFFFFFFF

#define EFI_BLOCK_IO_CRYPTO_PROTOCOL_GUID

Value:

{ \
      0xa00490ba, 0x3f1a, 0x4b4c, {0xab, 0x90, 0x4f, 0xa9, 0x97, 0x26, 0xa1, 0xe8} \
    }


Typedef Documentation

typedef IN UINT32 IN EFI_LBA IN OUT EFI_BLOCK_IO_CRYPTO_TOKEN IN UINT64 IN VOID* Buffer

typedef IN UINT32 IN EFI_LBA IN OUT EFI_BLOCK_IO_CRYPTO_TOKEN IN UINT64 IN VOID IN UINT64 IN VOID * CryptoIvInput

typedef IN UINT32 IN EFI_LBA IN OUT EFI_BLOCK_IO_CRYPTO_TOKEN IN UINT64 IN VOID IN UINT64 * Index

typedef IN UINT64 IN UINT64 IN EFI_GUID* KeyOwnerGuid

typedef IN UINT32 IN EFI_LBA LBA

typedef IN UINT32 MediaId

typedef IN UINT64 StartIndex


Function Documentation

typedef EFI_STATUS ( EFIAPI EFI_BLOCK_IO_CRYPTO_FLUSH  ) 

Reset the block device hardware.

The Reset() function resets the block device hardware.

As part of the initialization process, the firmware/device will make a quick but reasonable attempt to verify that the device is functioning.

If the ExtendedVerificationflag is TRUE the firmware may take an extended amount of time to verify the device is operating on reset. Otherwise the reset operation is to occur as quickly as possible.

The hardware verification process is not defined by this specification and is left up to the platform firmware or driver to implement.

Parameters:
[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance.
[in] ExtendedVerification Indicates that the driver may perform a more exhausive verfication operation of the device during reset.
Return values:
EFI_SUCCESS The block device was reset.
EFI_DEVICE_ERROR The block device is not functioning correctly and could not be reset.
EFI_INVALID_PARAMETER This is NULL.
Get the capabilities of the underlying inline cryptographic interface.

The GetCapabilities() function determines whether pre-OS controllable inline crypto is supported by the system for the current disk and, if so, returns the capabilities of the crypto engine.

The caller is responsible for providing the Capabilities structure with a sufficient number of entries.

If the structure is too small, the EFI_BUFFER_TOO_SMALL error code is returned and the CapabilityCount field contains the number of entries needed to contain the capabilities.

Parameters:
[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance.
[out] Capabilities Pointer to the EFI_BLOCK_IO_CRYPTO_CAPABILITIES structure.
Return values:
EFI_SUCCESS The ICI is ready for use.
EFI_BUFFER_TOO_SMALL The Capabilities structure was too small. The number of entries needed is returned in the CapabilityCount field of the structure.
EFI_NO_RESPONSE No response was received from the ICI.
EFI_DEVICE_ERROR An error occurred when attempting to access the ICI.
EFI_INVALID_PARAMETER This is NULL.
EFI_INVALID_PARAMETER Capabilities is NULL.
Set the configuration of the underlying inline cryptographic interface.

The SetConfiguration() function allows the user to set the current configuration of the inline cryptographic interface and should be called before attempting any crypto operations.

This configures the configuration table entries with algorithms, key sizes and keys. Each configured entry can later be referred to by index at the time of storage transaction.

The configuration table index will refer to the combination ofKeyOwnerGuid, Algorithm, and CryptoKey.

KeyOwnerGuid identifies the component taking ownership of the entry. It helps components to identify their own entries, cooperate with other owner components, and avoid conflicts. This Guid identifier is there to help coordination between cooperating components and not a security or synchronization feature. The Nil GUID can be used by a component to release use of entry owned. It is also used to identify potentially available entries (see GetConfiguration).

CryptoKey specifies algorithm-specific key material to use within parameters of selected crypto capability.

This function is called infrequently typically once, on device start, before IO starts. It can be called at later times in cases the number of keysused on the drive is higher than what can be configured at a time or a new key has to be added.

Components setting or changing an entry or entries for a given index or indices must ensure that IO referencing affected indices is temporarily blocked (run-down) at the time of change.

Indices parameters in each parameter table entry allow to set only a portion of the available table entries in the crypto module anywhere from single entry to entire table supported.

If corresponding table entry or entries being set are already in use by another owner the call should be failed and none of the entries should be modified. The interface implementation must enforce atomicity of this operation (should either succeed fully or fail completely without modifying state).

Note that components using GetConfiguration command to discover available entries should be prepared that by the time of calling SetConfiguration the previously available entry may have become occupied. Such components should be prepared to re-try the sequence of operations.

Alternatively EFI_BLOCK_IO_CRYPTO_INDEX_ANY can be used to have the implementation discover and allocate available,if any, indices atomically.

An optional ResultingTable pointer can be provided by the caller to receive the newly configured entries. The array provided by the caller must have at least ConfigurationCount of entries.

Parameters:
[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance.
[in] ConfigurationCount Number of entries being configured with this call.
[in] ConfigurationTable Pointer to a table used to populate the configuration table.
[out] ResultingTable Optional pointer to a table that receives the newly configured entries.
Return values:
EFI_SUCCESS The ICI is ready for use.
EFI_NO_RESPONSE No response was received from the ICI.
EFI_DEVICE_ERROR An error occurred when attempting to access the ICI.
EFI_INVALID_PARAMETER This is NULL.
EFI_INVALID_PARAMETER ConfigurationTable is NULL.
EFI_INVALID_PARAMETER ConfigurationCount is 0.
EFI_OUT_OF_RESOURCES Could not find the requested number of available entries in the configuration table.
Get the configuration of the underlying inline cryptographic interface.

The GetConfiguration() function allows the user to get the configuration of the inline cryptographic interface.

Retrieves, entirely or partially, the currently configured key table. Note that the keys themselves are not retrieved, but rather just indices, owner GUIDs and capabilities.

If fewer entries than specified by ConfigurationCount are returned, the Index field of the unused entries is set to EFI_BLOCK_IO_CRYPTO_INDEX_ANY.

Parameters:
[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance.
[in] StartIndex Configuration table index at which to start the configuration query.
[in] ConfigurationCount Number of entries to return in the response table.
[in] KeyOwnerGuid Optional parameter to filter response down to entries with a given owner. A pointer to the Nil value can be used to return available entries. Set to NULL when no owner filtering is required.
[out] ConfigurationTable Table of configured configuration table entries (with no CryptoKey returned): configuration table index, KeyOwnerGuid, Capability. Should have sufficient space to store up to ConfigurationCount entries.
Return values:
EFI_SUCCESS The ICI is ready for use.
EFI_NO_RESPONSE No response was received from the ICI.
EFI_DEVICE_ERROR An error occurred when attempting to access the ICI.
EFI_INVALID_PARAMETER This is NULL.
EFI_INVALID_PARAMETER Configuration table is NULL.
EFI_INVALID_PARAMETER StartIndex is out of bounds.
Reads the requested number of blocks from the device and optionally decrypts them inline.

TheReadExtended() function allows the caller to perform a storage device read operation. The function reads the requested number of blocks from the device and then if Index is specified decrypts them inline. All the blocks are read and decrypted (if decryption requested), or an error is returned.

If there is no media in the device, the function returns EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the device, the function returns EFI_MEDIA_CHANGED.

If EFI_DEVICE_ERROR, EFI_NO_MEDIA, or EFI_MEDIA_CHANGED is returned and nonblocking I/O is being used, the Event associated with this request will not be signaled.

In addition to standard storage transaction parameters (LBA, IO size, and buffer), this command will also specify a configuration table Index and CryptoIvInput when data has to be decrypted inline by the controller after being read from the storage device. If an Index parameter is not specified, no decryption is performed.

Parameters:
[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance.
[in] MediaId The media ID that the read request is for.
[in] LBA The starting logical block address to read from on the device.
[in,out] Token A pointer to the token associated with the transaction.
[in] BufferSize The size of the Buffer in bytes. This must be a multiple of the intrinsic block size of the device.
[out] Buffer A pointer to the destination buffer for the data. The caller is responsible for either having implicit or explicit ownership of the buffer.
[in] Index A pointer to the configuration table index. This is optional.
[in] CryptoIvInput A pointer to a buffer that contains additional cryptographic parameters as required by the capability referenced by the configuration table index, such as cryptographic initialization vector.
Return values:
EFI_SUCCESS The read request was queued if Token-> Event is not NULL. The data was read correctly from the device if the Token->Event is NULL.
EFI_DEVICE_ERROR The device reported an error while attempting to perform the read operation and/or decryption operation.
EFI_NO_MEDIA There is no media in the device.
EFI_MEDIA_CHANGED The MediaId is not for the current media.
EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the intrinsic block size of the device.
EFI_INVALID_PARAMETER This is NULL, or the read request contains LBAs that are not valid, or the buffer is not on proper alignment.
EFI_INVALID_PARAMETER CryptoIvInput is incorrect.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
Optionally encrypts a specified number of blocks inline and then writes to the device.

The WriteExtended() function allows the caller to perform a storage device write operation. The function encrypts the requested number of blocks inline if Index is specified and then writes them to the device. All the blocks are encrypted (if encryption requested) and written, or an error is returned.

If there is no media in the device, the function returns EFI_NO_MEDIA. If the MediaId is not the ID for the current media in the device, the function returns EFI_MEDIA_CHANGED.

If EFI_DEVICE_ERROR, EFI_NO_MEDIA, or EFI_MEDIA_CHANGED is returned and nonblocking I/O is being used, the Event associated with this request will not be signaled.

In addition to standard storage transaction parameters (LBA, IO size, and buffer), this command will also specify a configuration table Index and a CryptoIvInput when data has to be decrypted inline by the controller before being written to the storage device. If no Index parameter is specified, no encryption is performed.

Parameters:
[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance.
[in] MediaId The media ID that the read request is for.
[in] LBA The starting logical block address to read from on the device.
[in,out] Token A pointer to the token associated with the transaction.
[in] BufferSize The size of the Buffer in bytes. This must be a multiple of the intrinsic block size of the device.
[in] Buffer A pointer to the source buffer for the data.
[in] Index A pointer to the configuration table index. This is optional.
[in] CryptoIvInput A pointer to a buffer that contains additional cryptographic parameters as required by the capability referenced by the configuration table index, such as cryptographic initialization vector.
Return values:
EFI_SUCCESS The request to encrypt (optionally) and write was queued if Event is not NULL. The data was encrypted (optionally) and written correctly to the device if the Event is NULL.
EFI_WRITE_PROTECTED The device cannot be written to.
EFI_NO_MEDIA There is no media in the device.
EFI_MEDIA_CHANGED The MediaId is not for the current media.
EFI_DEVICE_ERROR The device reported an error while attempting to encrypt blocks or to perform the write operation.
EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the intrinsic block size of the device.
EFI_INVALID_PARAMETER This is NULL, or the write request contains LBAs that are not valid, or the buffer is not on proper alignment.
EFI_INVALID_PARAMETER CryptoIvInput is incorrect.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
Flushes all modified data toa physical block device.

The FlushBlocks() function flushes all modified data to the physical block device. Any modified data that has to be encrypted must have been already encrypted as a part of WriteExtended() operation - inline crypto operation cannot be a part of flush operation.

All data written to the device prior to the flush must be physically written before returning EFI_SUCCESS from this function. This would include any cached data the driver may have cached, and cached data the device may have cached. A flush may cause a read request following the flush to force a device access.

If EFI_DEVICE_ERROR, EFI_NO_MEDIA, EFI_WRITE_PROTECTED or EFI_MEDIA_CHANGED is returned and non-blocking I/O is being used, the Event associated with this request will not be signaled.

Parameters:
[in] This Pointer to the EFI_BLOCK_IO_CRYPTO_PROTOCOL instance.
[in,out] Token A pointer to the token associated with the transaction.
Return values:
EFI_SUCCESS The flush request was queued if Event is not NULL. All outstanding data was written correctly to the device if the Event is NULL.
EFI_DEVICE_ERROR The device reported an error while attempting to write data.
EFI_WRITE_PROTECTED The device cannot be written to.
EFI_NO_MEDIA There is no media in the device.
EFI_MEDIA_CHANGED The MediaId is not for the current media.
EFI_INVALID_PARAMETER This is NULL.
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.


Variable Documentation


Generated on Thu Sep 24 23:14:19 2015 for MdePkg[ALL] by  doxygen 1.5.7.1