EFI CRYPT KEY MANAGEMENT PROTOCOL

From PhoenixWiki

Jump to: navigation, search

This protocol provides Key management functions for all ciphers supported by the driver that implements this protocol.

Contents

GUID

Protocol Interface Structure

typedef struct _EFI_CRYPT_KEY_MANAGEMENT_PROTOCOL  {
  EFI_CRYPT_KEYMAN_GENERATE_KEY          GenerateKey;
  EFI_CRYPT_KEYMAN_DERIVE_KEY            DeriveKey;
  EFI_CRYPT_KEYMAN_DESTROY_KEY           DestroyKey;
  EFI_CRYPT_KEYMAN_IMPORT_KEY            ImportKey;
  EFI_CRYPT_KEYMAN_EXPORT_KEY            ExportKey;
  EFI_CRYPT_KEYMAN_HASH_KEY              HashKey;
  EFI_CRYPT_OBJECT_GET_PARAM             GetKeyParam;
} EFI_CRYPT_KEY_MANAGEMENT_PROTOCOL;

Parameters

Parameter Description
GenerateKey Generates a key for a specified algorithm.
DeriveKey Derives a key from a hash object for the specified algorithm.
DestroyKey Destroys a key object, zero out all sensitive data and release all resources allocation for the key object.
ImportKey Creates a key object from a key blob previously created by ExportKey
ExportKey Saves a key into a blob.
HashKey Updates a hash object with the key data identified by a key object.
GetKeyParam Gets various key parameters from a key object, such as the algorithm id or the length of the key.

Description

GenerateKey(), DeriveKey() and ImportKey() can all be used to initialize a key object and obtain a key handle. The returned key handle could then be used in the encrypt/decrypt operation (BlockCipher or StreamCipher Protocols) or the sign/verify operation (Digital Signature Protocol), depending on the type of the key. The DestroyKey function destroys the key handle and releases all allocated resources.

Normally the material (raw data) of the key could not be exposed to the application, unless the flag EfiCryptKeyFlagArchivable is set when generating the key. In that case, the ExportKey function could be used to export the key into blob (a stream of bytes) in plain text. It is the caller’s responsibility to keep the blob in a safe place or encrypt the blob using other keys. The format of the blob is specific to implementers and out of the scope of this document.

The flags of the key handle are passed in as a parameter during the call to GenerateKey; and after this call the flags can not be changed by any means. ImportKey() and ExportKey() preserve all these flags.

HashKey updates a hash object with a key object, and requires the key object to have the EfiCryptKeyFlagHash flag set. Commonly, no cipher algorithm would set this flag, thus, the implementer should expose a special algorithm to generate keys with this flag set, especially when HMAC support is wanted.

All functions in this protocol are algorithm dependent and crypto-provider dependent as well.

The HashKey() function is here, instead of in the EFI_CRYPT_HASH_PROTOCOL because the operation is key related but neutral to the underlying hash algorithm. ImportKey and ExportKey are implementation dependent and the key format will not be specified in the EFI 1.2 Specification. When implementing HMAC on the EFI_CRYPT_HASH_PROTOCOL and the HashKey() function, it is strongly recommended that the key length not exceed the block size of the underlying hash. If the key length does exceed the block size of the underlying hash, the key is hashed first as specified in RFC2104, and is exposed in plaintext out side of the crypto-provider (since there is no native support for HMAC inside the provider). This may result in security vulnerability.

GenerateKey()

Generates a key for a specified cipher algorithm.

Prototype

typedef
EFI_STATUS

(EFIAPI *EFI_CRYPT_KEYMAN_GENERATE_KEY) (

  IN  CONST EFI_CRYPT_KEY_MANAGEMENT_PROTOCOL *This,
  OUT EFI_CRYPT_HANDLE                        *Key,
  IN  EFI_GUID                                *AlgId,
  IN  UINTN                                   KeyLen,
  IN  UINT32                                  Flags
  );

Parameters

Parameter Description
This Points to this instance of the protocol.
Key Pointer to a handle to receive the handle of the newly generated key.
AlgId GUID identifying the cipher algorithm wanted. The generated key can then only be used with this algorithm.
KeyLen Size of the key in bits.
Flags Specifies additional flags to be assigned to the key handle or control the generation process. Flags assigned to a key could only be specified here, and could not be changed afterwards.

Description
This function generates a key which could be used with a specified algorithm. Normally, the key is generated randomly, except for some key exchange algorithms, such as Diffie-Hellman key exchange.

Defined key flags are described as follows.

  • EfiCryptKeyFlagArchivable. The key could be exported to blobs when set.
  • EfiCryptKeyFlagEncryption. The key could be used in encryption when set. The caller should specify this flag explicitly. It would be set automatically if an encryption algorithm is used.
  • EfiCryptKeyFlagSignature. The key could be used in signature operations. The caller should not specify this flag explicitly. It would be set automatically if a signature algorithm is used.
  • EfiCryptKeyFlagHash. The key could be used in the HashKey function when set.

Status Codes Returned

Status Code Description
EFI_SUCCESS The operation completed successfully.
EFI_OUT_OF_RESOURCE Out of resource.
EFI_UNSUPPORTED The specified algorithm is not supported.
EFI_INVALID_PARAMETER The specified algorithm does not support the specified key length or one or more of the specified flags.

DeriveKey()

Creates a key for a specified cipher algorithm from the result of a hash algorithm.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_CRYPT_KEYMAN_DERIVE_KEY) (
  IN  CONST EFI_CRYPT_KEY_MANAGEMENT_PROTOCOL *This,
  OUT EFI_CRYPT_HANDLE                        *Key,
  IN  EFI_GUID                                *AlgId,
  IN  EFI_CRYPT_HANDLE                        Hash,
  IN  UINTN                                   KeyLen,
  IN  UINT32                                  Flags
  );

Parameters

Parameter Description
Key Pointer to a handle to receive the handle of the newly created key.
AlgId GUID identifying the cipher algorithm wanted. The created key can then only be used with this algorithm.
Hash Handle to a hash object. The value of the hash object would be used to create the key.
KeyLen Size of the key in bits.
Flags Specify additional flags to be assigned to the key handle or control the generation process. Flags assigned to a key could only be specified here, and could not be changed afterwards.

Description
The EFI_CRYPT_KEY_MANAGEMENT_PROTOCOL.DeriveKey() function generates a key which could be used with a specified algorithm. Refer to GenerateKey for the defined key flags and their explanations.

Status Codes Returned

Status Code Description
EFI_SUCCESS The operation completed successfully.
EFI_OUT_OF_RESOURCE Out of resource.
EFI_UNSUPPORTED The specified algorithm is not supported.
EFI_INVALID_PARAMETER The specified algorithm does not support the specified key length or one or more of the specified flags.

DestroyKey()

Destroys a key object, zeroes out all sensitive data, and releases all resources.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_CRYPT_KEYMAN_DESTROY_KEY) (
  IN CONST EFI_CRYPT_KEY_MANAGEMENT_PROTOCOL *This,
  IN EFI_CRYPT_HANDLE                        Key
  );

Parameters

Parameter Description
Key Handle to the key to be destroyed.

Status Codes Returned

Status Code Description
EFI_SUCCESS The operation completed successfully.
EFI_INVALID_PARAMETER The handle does not identify a valid key object.

ImportKey()

Recreates a key object from a blob (sequence of bytes).

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_CRYPT_KEYMAN_IMPORT_KEY) (
  IN  CONST EFI_CRYPT_KEY_MANAGEMENT_PROTOCOL *This,
  OUT EFI_CRYPT_HANDLE                        *Key,
  IN  EFI_GUID                                *AlgGuid,
  IN  UINT32                                  Flags,
  IN  VOID                                    *KeyBlob,
  IN  UINTN                                   KeyBlobSize
  );

Parameters

Parameter Description
Key Pointer to a handle to receive the imported key.
AlgGuid Specify the algorithm. This argument must match the algorithm associated with key.
Flags Controls the importation of the key.
EfiCryptKeyTypeSymmetric The key blob is symmetric and creates a symmetric key object.
EfiCryptKeyTypePublicKey The key blob is public or private and creates a public key object.
EfiCryptKeyTypePrivateKey The key blob is private and creates a private key.
KeyBlob Pointer to a buffer containing the blob.
KeyBlobSize Size of the blob in bytes.

Description
This function imports a key from a key blob (a stream of bytes) generated by the ExportKey() function.

Status Codes Returned

Status Code Description
EFI_SUCCESS The operation completed successfully.
EFI_INVALID_PARAMETER The GUID specified in the AlgGuid parameter does not match that associated with the key. The caller is trying to import a private key from a public blob. The key blob’s format is not recognized by the crypto driver.

ExportKey()

Export a key object into a stream of bytes, which could be used to recreate the key.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_CRYPT_KEYMAN_EXPORT_KEY) (
  IN     CONST EFI_CRYPT_KEY_MANAGEMENT_PROTOCOL *This,
  IN     EFI_CRYPT_HANDLE            Key,
  IN     UINT32                      Flags,
  OUT    VOID                        **KeyBlob,
  IN OUT UINTN                       *KeyBlobSize
  );

Parameters

Parameter Description
Key Handle to a key object to be exported.
Flags Controls the importation of the key. See related definition section of function ImportKey() for more information.
KeyBlob Pointer to a pointer variable to receive the key blob. It is the caller’s responsibility to free this buffer using FreePool() when it is no longer needed.
KeyBlobSize Pointer to a UINTN variable to received the size of the blob.

Description
This function exported a key into a key blob (a stream of bytes).

Flags recognized by this function are described in the related definition section of ImportKey().

Status Codes Returned

Status Code Description
EFI_SUCCESS The operation completed successfully.
EFI_OUT_OF_RESOURCE Out of resource.
EFI_INVALID_PARAMETER The handle does not refer to a valid key object. One or more flags are not recognized by the crypto driver.

HashKey()

Uses the key material to update a hash object.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_CRYPT_KEYMAN_HASH_KEY) (
  IN CONST EFI_CRYPT_KEY_MANAGEMENT_PROTOCOL *This,
  IN EFI_CRYPT_HANDLE                        Key,
  IN EFI_CRYPT_HANDLE                        Hash,
  IN UINT32                                  Flags
  );

Parameters

Parameter Description
Key Handle to a key object to be hashed.
Hash Handle to a hash object to be updated.
Flags This parameter is actually divided into 3 parts.

Bit 0~15: Flags to control how the key is hashed. Now there has been only one flag defined, EfiCryptKeyHashReversed, which would cause the function to hash key in reversed order. Bit 16~23: Mask to be exclusive-ored with the key before hashing. Bit 24~31: Specify the count of 0s padded after the key.

Description
This function hashes the key using the passed in hashed object. The key must have the flag EfiCryptKeyFlagHash set, or the function would fail.

Normally, the key is treated as an array of bytes, and passed to the hash object from lower address to higher address, unless the flag EfiCryptKeyHashReversed is set, in which case, the byte residing at the highest address would be passed to update the hash first.

If bit 24~31 of Flags is not zero, the key would be padded with 0 first, and then XORed with the bits 16~23, and finally hashed to the hash object.

Status Codes Returned

Status Code Description
EFI_SUCCESS The operation completed successfully.
EFI_ACCESS_DENIED The flag EfiCryptKeyFlagHash is not set in the key object.
EFI_INVALID_PARAMETER The key handle does not refer to a valid key object. The hash handle does not refer to a valid hash object. One or more flags are not recognized by the crypto driver.

Copyright (C) 2008 Phoenix Technologies Ltd. All Rights Reserved.

Personal tools