Glossary

Introduction

This is the interface definition for the Freescale Security Hardware API (FSL SHW API) for User Mode and Kernel Mode to access Freescale Security Hardware components for cryptographic acceleration. The API is intended to provide cross-platform access to security hardware components of Freescale.

This documentation has not been approved, and should not be taken to mean anything definite about future direction.

Some example code is provided to give some idea of usage of this API.

Note: This first version has been defined around the capabilities of the Sahara2 cryptographic accelerator, and may be expanded in the future to provide support for other platforms. The Platform Capabilities Object is intended as a way to allow programs to adapt to different platforms.

The i.MX25 is an example of a platform without a SAHARA but yet has capabilities supported by this API. These include fsl_shw_get_random() and fsl_shw_add_entropy(), and the use of Triple-DES (TDEA) cipher algorithm (with no checking of key parity supported) in ECB and CBC modes with Symmetric-Key Encryption and Decryption. See also the Hardware key-select extensions - DryIce for information on key handling, and Device Tamper-Detection for detection of Tamper Events. Only the random functions are available from user space on this platform.

The User Context

The User Context Object (fsl_shw_uco_t) controls the interaction between the user program and the API. It is initialized as part of user registration (fsl_shw_register_user()), and is part of every interaction thereafter.

Platform Capabilities

Since this API is not tied to one specific type of hardware or even one given version of a given type of hardware, the platform capabilities object could be used by a portable program to make choices about using software instead of hardware for certain operations.

See the fsl_shw_pco_t, returned by fsl_shw_get_capabilities().

Platform Context Object Operations are provided to query its contents.

Symmetric-Key Encryption and Decryption

Symmetric-Key encryption support is provided for the block cipher algorithms AES, DES, and Triple DES. Modes supported are FSL_SYM_MODE_ECB, FSL_SYM_MODE_CBC, and FSL_SYM_MODE_CTR, though not necessarily all modes for all algorithms. There is also support for the stream cipher algorithm commonly known as ARC4.

Encryption and decryption are performed by using the functions fsl_shw_symmetric_encrypt() and fsl_shw_symmetric_decrypt(), respectively. There are two objects which provide information about the operation of these functions. They are the fsl_shw_sko_t, to provide key and algorithm information; and the fsl_shw_scco_t, to provide (and store) initial context or counter value information.

CCM is not supported by these functions. For information CCM support, see Combined Cipher and Authentication.

Cryptographic Hashing

Hashing is performed by fsl_shw_hash(). Control of the function is through flags in the fsl_shw_hco_t. The algorithms which are supported are listed in fsl_shw_hash_alg_t.

The hashing function works on octet streams. If a user application needs to hash a bitstream, it will need to do its own padding of the last block.

Hashed Message Authentication Codes

An HMAC is a method of combining a hash and a key so that a message cannot be faked by a third party.

The fsl_shw_hmac() can be used by itself for one-shot or multi-step operations, or in combination with fsl_shw_hmac_precompute() to provide the ability to compute and save the beginning hashes from a key one time, and then use fsl_shw_hmac() to calculate an HMAC on each message as it is processed.

The maximum key length which is directly supported by this API is 64 octets. If a longer key size is needed for HMAC, the user will have to hash the key and present the digest value as the key to be used by the HMAC functions.

Random Numbers

Support is available for acquiring random values from a cryptographically-strong random number generator. See fsl_shw_get_random(). The function fsl_shw_add_entropy() may be used to add entropy to the random number generator.

Combined Cipher and Authentication

Some schemes require that messages be encrypted and that they also have an authentication code associated with the message. The function fsl_shw_gen_encrypt() will generate the authentication code and encrypt the message.

Upon receipt of such a message, the message must be decrypted and the authentication code validated. The function fsl_shw_auth_decrypt() will perform these steps.

Only AES-CCM is supported.

Wrapped Keys

On platforms with a Secure Memory, the function fsl_shw_establish_key() can be used to place a key into the System Keystore. This key then can be used directly by the cryptographic hardware. It later then be wrapped (cryptographically obscured) by fsl_shw_extract_key() and stored for later use. If a software key (FSL_SKO_KEY_SW_KEY) was established, then its value can be retrieved with a call to fsl_shw_read_key().

The wrapping and unwrapping functions provide security against unauthorized use and detection of tampering.

The functions can also be used with a User Keystore.

Secure Memory Allocation

On platforms with multiple partitions of Secure Memory, the function fsl_shw_smalloc() can be used to acquire a partition for private use. The function fsl_shw_diminish_perms() can then be used to revoke specific permissions on the partition, and fsl_shw_sfree() can be used to release the partition.

User Keystore

User Keystore functionality is defined in fsl_shw_keystore.h. See User Keystore API for details. This is not supported on platforms without SCC2.

Hardware key-select extensions - DryIce

Some platforms have a component called DryIce which allows the software to control which key will be used by the secure memory encryption hardware. The choices are the secret per-chip Fused (IIM) Key, an unknown, hardware- generated Random Key, a software-written Programmed Key, or the IIM Key in combination with one of the others. fsl_shw_pco_check_pk_supported() can be used to determine whether this feature is available on the platform. The rest of this section will explain the symmetric ciphering and key operations which are available on such a platform.

The function fsl_shw_sko_init_pf_key() will set up a Secret Key Object to refer to one of the system's platform keys. All keys which reference a platform key must use this initialization function, including a user- provided key value. Keys which are intended for software encryption must use fsl_shw_sko_init().

To change the setting of the Programmed Key of the DryIce module, fsl_shw_establish_key() must be called with a platform key object of type FSL_SHW_PF_KEY_PRG or FSL_SHW_PF_KEY_IIM_PRG. The key will be go into the PK register of DryIce and not to the keystore. Any symmetric operation which references either FSL_SHW_PF_KEY_PRG or FSL_SHW_PF_KEY_IIM_PRG will use the current PK value (possibly modified by the secret fused IIM key). Before the Flatform Key can be changed, a call to fsl_shw_release_key() or fsl_shw_extract_key() must be made. Neither function will change the value in the PK registers, and further ciphering can take place.

When fsl_shw_establish_key() is called to change the PK value, a plaintext key can be passed in with the FSL_KEY_WRAP_ACCEPT argument or a previously wrapped key can be passed in with the FSL_KEY_WRAP_UNWRAP argument. If FSL_KEY_WRAP_CREATE is passed in, then a random value will be loaded into the PK register. The PK value can be wrapped by a call to fsl_shw_extract_key() for later use with the FSL_KEY_WRAP_UNWRAP argument.

As an alternative to using only the fused key for Wrapped Keys, fsl_shw_uco_set_wrap_key() can be used to select either the random key or the random key with the fused key as the key which will be used to protect the one-time value used to wrap the key. This allows for these wrapped keys to be dependent upon and therefore unrecoverable after a tamper event causes the erasure of the DryIce Random Key register.

The software can request that the hardware generate a (new) Random Key for DryIce by calling fsl_shw_gen_random_pf_key().

Device Tamper-Detection

Some platforms have a component which can detect certain types of tampering with the hardware. fsl_shw_read_tamper_event() API will allow the retrieval of the type of event which caused a tamper-detection failure.

footer
©  Freescale Semiconductor, Inc., 2007.  All rights reserved.
Freescale Confidential Proprietary
NDA Required
doxygen