Operational Functions

Functions

fsl_shw_return_t fsl_shw_symmetric_encrypt (fsl_shw_uco_t *user_ctx, fsl_shw_sko_t *key_info, fsl_shw_scco_t *sym_ctx, uint32_t length, const uint8_t *pt, uint8_t *ct)
fsl_shw_return_t fsl_shw_symmetric_decrypt (fsl_shw_uco_t *user_ctx, fsl_shw_sko_t *key_info, fsl_shw_scco_t *sym_ctx, uint32_t length, const uint8_t *ct, uint8_t *pt)
fsl_shw_return_t fsl_shw_hash (fsl_shw_uco_t *user_ctx, fsl_shw_hco_t *hash_ctx, const uint8_t *msg, uint32_t length, uint8_t *result, uint32_t result_len)
fsl_shw_return_t fsl_shw_hmac_precompute (fsl_shw_uco_t *user_ctx, fsl_shw_sko_t *key_info, fsl_shw_hmco_t *hmac_ctx)
fsl_shw_return_t fsl_shw_hmac (fsl_shw_uco_t *user_ctx, fsl_shw_sko_t *key_info, fsl_shw_hmco_t *hmac_ctx, const uint8_t *msg, uint32_t length, uint8_t *result, uint32_t result_len)
fsl_shw_return_t fsl_shw_get_random (fsl_shw_uco_t *user_ctx, uint32_t length, uint8_t *data)
fsl_shw_return_t fsl_shw_add_entropy (fsl_shw_uco_t *user_ctx, uint32_t length, uint8_t *data)
fsl_shw_return_t fsl_shw_gen_encrypt (fsl_shw_uco_t *user_ctx, fsl_shw_acco_t *auth_ctx, fsl_shw_sko_t *cipher_key_info, fsl_shw_sko_t *auth_key_info, uint32_t auth_data_length, const uint8_t *auth_data, uint32_t payload_length, const uint8_t *payload, uint8_t *ct, uint8_t *auth_value)
fsl_shw_return_t fsl_shw_auth_decrypt (fsl_shw_uco_t *user_ctx, fsl_shw_acco_t *auth_ctx, fsl_shw_sko_t *cipher_key_info, fsl_shw_sko_t *auth_key_info, uint32_t auth_data_length, const uint8_t *auth_data, uint32_t payload_length, const uint8_t *ct, const uint8_t *auth_value, uint8_t *payload)
fsl_shw_return_t fsl_shw_establish_key (fsl_shw_uco_t *user_ctx, fsl_shw_sko_t *key_info, fsl_shw_key_wrap_t establish_type, const uint8_t *key)
fsl_shw_return_t fsl_shw_read_key (fsl_shw_uco_t *user_ctx, fsl_shw_sko_t *key_info, uint8_t *key)
fsl_shw_return_t fsl_shw_extract_key (fsl_shw_uco_t *user_ctx, fsl_shw_sko_t *key_info, uint8_t *covered_key)
fsl_shw_return_t fsl_shw_release_key (fsl_shw_uco_t *user_ctx, fsl_shw_sko_t *key_info)
fsl_shw_return_t fsl_shw_gen_random_pf_key (fsl_shw_uco_t *user_ctx)
fsl_shw_return_t fsl_shw_read_tamper_event (fsl_shw_uco_t *user_ctx, fsl_shw_tamper_t *tamperp, uint64_t *timestampp)

Detailed Description

These functions request that the underlying hardware perform cryptographic operations. They are the heart of the API.


Function Documentation

fsl_shw_return_t fsl_shw_add_entropy ( fsl_shw_uco_t user_ctx,
uint32_t  length,
uint8_t *  data 
)

Add entropy to random number generator.

Parameters:
user_ctx A user context from fsl_shw_register_user().
length Number of bytes at data.
data Entropy to add to random number generator.
Returns:
A return code of type fsl_shw_return_t.

Add entropy to a random number generator

Parameters:
user_ctx 
length 
data 
Returns:
A return code of type fsl_shw_return_t.
fsl_shw_return_t fsl_shw_auth_decrypt ( fsl_shw_uco_t user_ctx,
fsl_shw_acco_t auth_ctx,
fsl_shw_sko_t cipher_key_info,
fsl_shw_sko_t auth_key_info,
uint32_t  auth_data_length,
const uint8_t *  auth_data,
uint32_t  payload_length,
const uint8_t *  ct,
const uint8_t *  auth_value,
uint8_t *  payload 
)

Authenticate and decrypt a (CCM) stream.

Perform Authentication-Decryption in Cipher + Hash.

This function will perform a one-shot decryption of a data stream as well as authenticate the authentication value. This is a one-shot function, so all of the auth_data and the total message payload must passed in one call. This also means that the flags in the auth_ctx must be FSL_ACCO_CTX_INIT and FSL_ACCO_CTX_FINALIZE.

Parameters:
user_ctx A user context from fsl_shw_register_user().
auth_ctx Controlling object for Authenticate-decrypt.
cipher_key_info The key being used for the cipher part of this operation. In CCM mode, this key is used for both parts.
auth_key_info The key being used for the authentication part of this operation. In CCM mode, this key is ignored and may be NULL.
auth_data_length Length, in octets, of auth_data.
auth_data Data to be authenticated but not decrypted.
payload_length Length, in octets, of ct and pt.
ct Pointer to the encrypted input stream.
auth_value The (encrypted) authentication value which will be authenticated. This is the same data as the (output) auth_value argument to fsl_shw_gen_encrypt().
[out] payload Pointer to where the plaintext resulting from the decryption will be stored.
Returns:
A return code of type fsl_shw_return_t.
Parameters:
user_ctx The user's context
auth_ctx Info on this Auth operation
cipher_key_info Key to encrypt payload
auth_key_info (unused - same key in CCM)
auth_data_length Length in bytes of auth_data
auth_data Any auth-only data
payload_length Length in bytes of payload
ct The encrypted data
auth_value The authentication code to validate
[out] payload The location to store decrypted data
Returns:
A return code of type fsl_shw_return_t.
fsl_shw_return_t fsl_shw_establish_key ( fsl_shw_uco_t user_ctx,
fsl_shw_sko_t key_info,
fsl_shw_key_wrap_t  establish_type,
const uint8_t *  key 
)

Establish the key in a protected location, which can be the system keystore, user keystore, or (on platforms that support it) as a Platform Key.

By default, keys initialized with fsl_shw_sko_init() will be placed into the system keystore. The user can cause the key to be established in a user keystore by first calling fsl_shw_sko_set_keystore() on the key. Normally, keys in the system keystore can only be used for hardware encrypt or decrypt operations, however if the FSL_SKO_KEY_SW_KEY flag is applied using fsl_shw_sko_set_flags(), the key will be established as a software key, which can then be read out using fsl_shw_read_key().

Keys initialized with fsl_shw_sko_init_pf_key() are established as a Platform Key. Their use is covered in Hardware key-select extensions - DryIce.

This function only needs to be used when unwrapping a key, setting up a key which could be wrapped with a later call to fsl_shw_extract_key(), or setting up a key as a Platform Key. Normal cleartext keys can simply be placed into fsl_shw_sko_t key objects with fsl_shw_sko_set_key() and used directly.

The maximum key size supported for wrapped/unwrapped keys is 32 octets. (This is the maximum reasonable key length on Sahara - 32 octets for an HMAC key based on SHA-256.) The key size is determined by the key_info. The expected length of key can be determined by fsl_shw_sko_calculate_wrapped_size()

The protected key will not be available for use until this operation successfully completes.

This feature is not available for all platforms, nor for all algorithms and modes.

Parameters:
user_ctx A user context from fsl_shw_register_user().
[in,out] key_info The information about the key to be which will be established. In the create case, the key length must be set.
establish_type How key will be interpreted to establish a key for use.
key If establish_type is FSL_KEY_WRAP_UNWRAP, this is the location of a wrapped key. If establish_type is FSL_KEY_WRAP_CREATE, this parameter can be NULL. If establish_type is FSL_KEY_WRAP_ACCEPT, this is the location of a plaintext key.

Place a key into a protected location for use only by cryptographic algorithms.

This only needs to be used to a) unwrap a key, or b) set up a key which could be wrapped with a later call to fsl_shw_extract_key(). Normal cleartext keys can simply be placed into fsl_shw_sko_t key objects with fsl_shw_sko_set_key() and used directly.

The maximum key size supported for wrapped/unwrapped keys is 32 octets. (This is the maximum reasonable key length on Sahara - 32 octets for an HMAC key based on SHA-256.) The key size is determined by the key_info. The expected length of key can be determined by fsl_shw_sko_calculate_wrapped_size()

The protected key will not be available for use until this operation successfully completes.

This feature is not available for all platforms, nor for all algorithms and modes.

Parameters:
user_ctx A user context from fsl_shw_register_user().
[in,out] key_info The information about the key to be which will be established. In the create case, the key length must be set.
establish_type How key will be interpreted to establish a key for use.
key If establish_type is FSL_KEY_WRAP_UNWRAP, this is the location of a wrapped key. If establish_type is FSL_KEY_WRAP_CREATE, this parameter can be NULL. If establish_type is FSL_KEY_WRAP_ACCEPT, this is the location of a plaintext key.
Returns:
A return code of type fsl_shw_return_t.
fsl_shw_return_t fsl_shw_extract_key ( fsl_shw_uco_t user_ctx,
fsl_shw_sko_t key_info,
uint8_t *  covered_key 
)

Wrap a key and retrieve the wrapped value.

A wrapped key is a key that has been cryptographically obscured. It is only able to be used with keys that have been established by fsl_shw_establish_key().

For keys established in the system or user keystore, this function will also release the key (see fsl_shw_release_key()) so that it must be re- established before reuse. This function will not release keys that are established as a Platform Key, so a call to fsl_shw_release_key() is necessary to release those keys.

This feature is not available for all platforms, nor for all algorithms and modes.

Parameters:
user_ctx A user context from fsl_shw_register_user().
key_info The information about the key to be deleted.
[out] covered_key The location to store the wrapped key. (This size is based upon the maximum key size of 32 octets).
Returns:
A return code of type fsl_shw_return_t.

Wrap a key and retrieve the wrapped value.

A wrapped key is a key that has been cryptographically obscured. It is only able to be used with fsl_shw_establish_key().

This function will also release the key (see fsl_shw_release_key()) so that it must be re-established before reuse.

This feature is not available for all platforms, nor for all algorithms and modes.

Parameters:
user_ctx A user context from fsl_shw_register_user().
key_info The information about the key to be deleted.
[out] covered_key The location to store the 48-octet wrapped key. (This size is based upon the maximum key size of 32 octets).
Returns:
A return code of type fsl_shw_return_t.
fsl_shw_return_t fsl_shw_gen_encrypt ( fsl_shw_uco_t user_ctx,
fsl_shw_acco_t auth_ctx,
fsl_shw_sko_t cipher_key_info,
fsl_shw_sko_t auth_key_info,
uint32_t  auth_data_length,
const uint8_t *  auth_data,
uint32_t  payload_length,
const uint8_t *  payload,
uint8_t *  ct,
uint8_t *  auth_value 
)

Generate a (CCM) auth code and encrypt the payload.

Perform Generation-Encryption by doing a Cipher and a Hash.

Generate the authentication value auth_value as well as encrypt the payload into ct (the ciphertext). This is a one-shot function, so all of the auth_data and the total message payload must passed in one call. This also means that the flags in the auth_ctx must be FSL_ACCO_CTX_INIT and FSL_ACCO_CTX_FINALIZE.

Parameters:
user_ctx A user context from fsl_shw_register_user().
auth_ctx Controlling object for Authenticate-decrypt.
cipher_key_info The key being used for the cipher part of this operation. In CCM mode, this key is used for both parts.
auth_key_info The key being used for the authentication part of this operation. In CCM mode, this key is ignored and may be NULL.
auth_data_length Length, in octets, of auth_data.
auth_data Data to be authenticated but not encrypted.
payload_length Length, in octets, of payload.
payload Pointer to the plaintext to be encrypted.
[out] ct Pointer to the where the encrypted payload will be stored. Must be payload_length octets long.
[out] auth_value Pointer to where the generated authentication field will be stored. Must be as many octets as indicated by MAC length in the function_ctx.
Returns:
A return code of type fsl_shw_return_t.

This is a very complicated function. Seven (or eight) descriptors are required to perform a CCM calculation.

First: Load CTR0 and key.

Second: Run an octet of data through to bump to CTR1. (This could be done in software, but software will have to bump and later decrement - or copy and bump.

Third: (in Virtio) Load a descriptor with data of zeros for CBC IV.

Fourth: Run any (optional) "additional data" through the CBC-mode portion of the algorithm.

Fifth: Run the payload through in CCM mode.

Sixth: Extract the unencrypted MAC.

Seventh: Load CTR0.

Eighth: Encrypt the MAC.

Parameters:
user_ctx The user's context
auth_ctx Info on this Auth operation
cipher_key_info Key to encrypt payload
auth_key_info (unused - same key in CCM)
auth_data_length Length in bytes of auth_data
auth_data Any auth-only data
payload_length Length in bytes of payload
payload The data to encrypt
[out] ct The location to store encrypted data
[out] auth_value The location to store authentication code
Returns:
A return code of type fsl_shw_return_t.
fsl_shw_return_t fsl_shw_gen_random_pf_key ( fsl_shw_uco_t user_ctx  )  [inline]

Cause the hardware to create a new random key for use by the secure memory encryption hardware.

Have the hardware use the secure hardware random number generator to load a new secret key into the system's Random Key register.

Parameters:
user_ctx A user context from fsl_shw_register_user().
Returns:
A return code of type fsl_shw_return_t.

Cause the hardware to create a new random key for secure memory use.

Have the hardware use the secure hardware random number generator to load a new secret key into the hardware random key register.

Parameters:
user_ctx A user context from fsl_shw_register_user().
Returns:
A return code of type fsl_shw_return_t.

Cause the hardware to create a new random key for use by the secure memory encryption hardware.

Have the hardware use the secure hardware random number generator to load a new secret key into the system's Random Key register.

Parameters:
user_ctx A user context from fsl_shw_register_user().
Returns:
A return code of type fsl_shw_return_t.

References FSL_RETURN_ERROR_S.

fsl_shw_return_t fsl_shw_get_random ( fsl_shw_uco_t user_ctx,
uint32_t  length,
uint8_t *  data 
)

Get random data.

Parameters:
user_ctx A user context from fsl_shw_register_user().
length The number of octets of data being requested.
[out] data A pointer to a location of length octets to where random data will be returned.
Returns:
A return code of type fsl_shw_return_t.

Get random data.

Parameters:
user_ctx A user context from fsl_shw_register_user().
length The number of octets of data being requested.
data A pointer to a location of length octets to where random data will be returned.
Returns:
FSL_RETURN_NO_RESOURCE_S A return code of type fsl_shw_return_t. FSL_RETURN_OK_S

Get random data.

Parameters:
user_ctx A user context from fsl_shw_register_user().
length The number of octets of data being requested.
[out] data A pointer to a location of length octets to where random data will be returned.
Returns:
A return code of type fsl_shw_return_t.

Get random data.

Parameters:
user_ctx A user context from fsl_shw_register_user().
length The number of octets of data being requested.
data A pointer to a location of length octets to where random data will be returned.
Returns:
FSL_RETURN_NO_RESOURCE_S A return code of type fsl_shw_return_t. FSL_RETURN_OK_S

Get a random number

Parameters:
user_ctx 
length 
data 
Returns:
A return code of type fsl_shw_return_t.
fsl_shw_return_t fsl_shw_hash ( fsl_shw_uco_t user_ctx,
fsl_shw_hco_t hash_ctx,
const uint8_t *  msg,
uint32_t  length,
uint8_t *  result,
uint32_t  result_len 
)

Hash a stream of data with a cryptographic hash algorithm.

The flags in the hash_ctx control the operation of this function.

Hashing functions work on 64 octets of message at a time. Therefore, when any partial hashing of a long message is performed, the message length of each segment must be a multiple of 64. When ready to FSL_HASH_FLAGS_FINALIZE the hash, the length may be any value.

With the FSL_HASH_FLAGS_INIT and FSL_HASH_FLAGS_FINALIZE flags on, a one-shot complete hash, including padding, will be performed. The length may be any value.

The first octets of a data stream can be hashed by setting the FSL_HASH_FLAGS_INIT and FSL_HASH_FLAGS_SAVE flags. The length must be a multiple of 64.

The flag FSL_HASH_FLAGS_LOAD is used to load a context previously saved by FSL_HASH_FLAGS_SAVE. The two in combination will allow a (multiple-of-64 octets) 'middle sequence' of the data stream to be hashed with the beginning. The length must again be a multiple of 64.

Since the flag FSL_HASH_FLAGS_LOAD is used to load a context previously saved by FSL_HASH_FLAGS_SAVE, the FSL_HASH_FLAGS_LOAD and FSL_HASH_FLAGS_FINALIZE flags, used together, can be used to finish the stream. The length may be any value.

If the user program wants to do the padding for the hash, it can leave off the FSL_HASH_FLAGS_FINALIZE flag. The length must then be a multiple of 64 octets.

Parameters:
user_ctx A user context from fsl_shw_register_user().
[in,out] hash_ctx Hashing algorithm and state of the cipher.
msg Pointer to the data to be hashed.
length Length, in octets, of the msg.
[out] result If not null, pointer to where to store the hash digest.
result_len Number of octets to store in result.
Returns:
A return code of type fsl_shw_return_t.
fsl_shw_return_t fsl_shw_hmac ( fsl_shw_uco_t user_ctx,
fsl_shw_sko_t key_info,
fsl_shw_hmco_t hmac_ctx,
const uint8_t *  msg,
uint32_t  length,
uint8_t *  result,
uint32_t  result_len 
)

Continue, finalize, or one-shot an HMAC operation.

There are a number of ways to use this function. The flags in the hmac_ctx object will determine what operations occur.

If FSL_HMAC_FLAGS_INIT is set, then the hash will be started either from the key_info, or from the precomputed inner hash value in the hmac_ctx, depending on the value of FSL_HMAC_FLAGS_PRECOMPUTES_PRESENT.

If, instead, FSL_HMAC_FLAGS_LOAD is set, then the hash will be continued from the ongoing inner hash computation in the hmac_ctx.

If FSL_HMAC_FLAGS_FINALIZE are set, then the msg will be padded, hashed, the outer hash will be performed, and the result will be generated.

If the FSL_HMAC_FLAGS_SAVE flag is set, then the (ongoing or final) digest value will be stored in the ongoing inner hash computation field of the hmac_ctx.

Parameters:
user_ctx A user context from fsl_shw_register_user().
key_info If FSL_HMAC_FLAGS_INIT is set in the hmac_ctx, this is the key being used in this operation, and the IPAD. If FSL_HMAC_FLAGS_INIT is set in the hmac_ctx and key_info is NULL, then fsl_shw_hmac_precompute() has been used to populate the inner_precompute and outer_precompute contexts. If FSL_HMAC_FLAGS_INIT is not set, this parameter is ignored.
[in,out] hmac_ctx The context which controls, by its flags and algorithm, the operation of this function.
msg Pointer to the message to be hashed.
length Length, in octets, of the msg.
[out] result Pointer, of result_len octets, to where to store the HMAC.
result_len Length of result buffer.
Returns:
A return code of type fsl_shw_return_t.

Get the hmac

Parameters:
user_ctx Info for acquiring memory
key_info 
hmac_ctx 
msg 
length 
result 
result_len 
Returns:
A return code of type fsl_shw_return_t.

Continue, finalize, or one-shot an HMAC operation.

There are a number of ways to use this function. The flags in the hmac_ctx object will determine what operations occur.

If FSL_HMAC_FLAGS_INIT is set, then the hash will be started either from the key_info, or from the precomputed inner hash value in the hmac_ctx, depending on the value of FSL_HMAC_FLAGS_PRECOMPUTES_PRESENT.

If, instead, FSL_HMAC_FLAGS_LOAD is set, then the hash will be continued from the ongoing inner hash computation in the hmac_ctx.

If FSL_HMAC_FLAGS_FINALIZE are set, then the msg will be padded, hashed, the outer hash will be performed, and the result will be generated.

If the FSL_HMAC_FLAGS_SAVE flag is set, then the (ongoing or final) digest value will be stored in the ongoing inner hash computation field of the hmac_ctx.

Parameters:
user_ctx A user context from fsl_shw_register_user().
key_info If FSL_HMAC_FLAGS_INIT is set in the hmac_ctx, this is the key being used in this operation, and the IPAD. If FSL_HMAC_FLAGS_INIT is set in the hmac_ctx and key_info is NULL, then fsl_shw_hmac_precompute() has been used to populate the inner_precompute and outer_precompute contexts. If FSL_HMAC_FLAGS_INIT is not set, this parameter is ignored.
[in,out] hmac_ctx The context which controls, by its flags and algorithm, the operation of this function.
msg Pointer to the message to be hashed.
length Length, in octets, of the msg.
[out] result Pointer, of result_len octets, to where to store the HMAC.
result_len Length of result buffer.
Returns:
A return code of type fsl_shw_return_t.

Get the hmac

Parameters:
user_ctx Info for acquiring memory
key_info 
hmac_ctx 
msg 
length 
result 
result_len 
Returns:
A return code of type fsl_shw_return_t.
fsl_shw_return_t fsl_shw_hmac_precompute ( fsl_shw_uco_t user_ctx,
fsl_shw_sko_t key_info,
fsl_shw_hmco_t hmac_ctx 
)

Precompute the Key hashes for an HMAC operation.

This function may be used to calculate the inner and outer precomputes, which are the hash contexts resulting from hashing the XORed key for the 'inner hash' and the 'outer hash', respectively, of the HMAC function.

After execution of this function, the hmac_ctx will contain the precomputed inner and outer contexts, so that they may be used by fsl_shw_hmac(). The flags of hmac_ctx will be updated with FSL_HMAC_FLAGS_PRECOMPUTES_PRESENT to mark their presence. In addition, the FSL_HMAC_FLAGS_INIT flag will be set.

Parameters:
user_ctx A user context from fsl_shw_register_user().
key_info The key being used in this operation. Key must be 1 to 64 octets long.
[in,out] hmac_ctx The context which controls, by its flags and algorithm, the operation of this function.
Returns:
A return code of type fsl_shw_return_t.

Get the precompute information

Parameters:
user_ctx 
key_info 
hmac_ctx 
Returns:
A return code of type fsl_shw_return_t.

Precompute the Key hashes for an HMAC operation.

This function may be used to calculate the inner and outer precomputes, which are the hash contexts resulting from hashing the XORed key for the 'inner hash' and the 'outer hash', respectively, of the HMAC function.

After execution of this function, the hmac_ctx will contain the precomputed inner and outer contexts, so that they may be used by fsl_shw_hmac(). The flags of hmac_ctx will be updated with FSL_HMAC_FLAGS_PRECOMPUTES_PRESENT to mark their presence. In addition, the FSL_HMAC_FLAGS_INIT flag will be set.

Parameters:
user_ctx A user context from fsl_shw_register_user().
key_info The key being used in this operation. Key must be 1 to 64 octets long.
[in,out] hmac_ctx The context which controls, by its flags and algorithm, the operation of this function.
Returns:
A return code of type fsl_shw_return_t.

Get the precompute information

Parameters:
user_ctx 
key_info 
hmac_ctx 
Returns:
A return code of type fsl_shw_return_t.
fsl_shw_return_t fsl_shw_read_key ( fsl_shw_uco_t user_ctx,
fsl_shw_sko_t key_info,
uint8_t *  key 
)

Read the key value from a key object.

Only a key marked as a software key (FSL_SKO_KEY_SW_KEY) can be read with this call. It has no effect on the status of the key store.

Parameters:
user_ctx A user context from fsl_shw_register_user().
key_info The referenced key.
[out] key The location to store the key value.
Returns:
A return code of type fsl_shw_return_t.
static fsl_shw_return_t fsl_shw_read_tamper_event ( fsl_shw_uco_t user_ctx,
fsl_shw_tamper_t tamperp,
uint64_t *  timestampp 
) [inline]

Retrieve the detected tamper event.

Note that if more than one event was detected, this routine will only ever return one of them.

Parameters:
[in] user_ctx A user context from fsl_shw_register_user().
[out] tamperp Location to store the tamper information.
[out] timestampp Locate to store timestamp from hardwhare when an event was detected.
Returns:
A return code of type fsl_shw_return_t (for instance, if the platform is not in a fail state.

References FSL_RETURN_NO_RESOURCE_S.

fsl_shw_return_t fsl_shw_release_key ( fsl_shw_uco_t user_ctx,
fsl_shw_sko_t key_info 
)

De-establish a key so that it can no longer be accessed.

The key will need to be re-established before it can again be used.

This feature is not available for all platforms, nor for all algorithms and modes.

Parameters:
user_ctx A user context from fsl_shw_register_user().
key_info The information about the key to be deleted.
Returns:
A return code of type fsl_shw_return_t.
fsl_shw_return_t fsl_shw_symmetric_decrypt ( fsl_shw_uco_t user_ctx,
fsl_shw_sko_t key_info,
fsl_shw_scco_t sym_ctx,
uint32_t  length,
const uint8_t *  ct,
uint8_t *  pt 
)

Decrypt a stream of data with a symmetric-key algorithm.

In ARC4, and also in FSL_SYM_MODE_CBC and FSL_SYM_MODE_CTR modes, the flags of the sym_ctx object will control part of the operation of this function. The FSL_SYM_CTX_INIT flag means that there is no context info in the object. The FSL_SYM_CTX_LOAD means to use information in the sym_ctx at the start of the operation, and the FSL_SYM_CTX_SAVE flag means to update the object's context information after the operation has been performed.

All of the data for an operation can be run through at once using the FSL_SYM_CTX_INIT or FSL_SYM_CTX_LOAD flags, as appropriate, and then using a length for the whole of the data.

If a FSL_SYM_CTX_SAVE flag were added, an additional call to the function would "pick up" where the previous call left off, allowing the user to perform the larger function in smaller steps.

In FSL_SYM_MODE_CBC and FSL_SYM_MODE_ECB modes, the length must always be a multiple of the block size for the algorithm being used. For proper operation in FSL_SYM_MODE_CTR mode, the length must be a multiple of the block size until the last operation on the total octet stream.

Some users of ARC4 may want to compute the context (S-Box and pointers) from the key before any data is available. This may be done by running this function with a length of zero, with the FSL_SYM_CTX_INIT & FSL_SYM_CTX_SAVE flags on in the sym_ctx. Subsequent operations would then run as normal with the load & save flags. Note that they key object is still required.

Parameters:
user_ctx A user context from fsl_shw_register_user().
key_info The key and algorithm being used in this operation.
[in,out] sym_ctx Info on cipher mode, state of the cipher.
length Length, in octets, of the ct (and pt).
ct pointer to ciphertext to be decrypted.
[out] pt pointer to where to store the resulting plaintext.
Returns:
A return code of type fsl_shw_return_t

Compute symmetric decryption

Parameters:
user_ctx 
key_info 
sym_ctx 
length 
pt 
ct 
Returns:
A return code of type fsl_shw_return_t.
fsl_shw_return_t fsl_shw_symmetric_encrypt ( fsl_shw_uco_t user_ctx,
fsl_shw_sko_t key_info,
fsl_shw_scco_t sym_ctx,
uint32_t  length,
const uint8_t *  pt,
uint8_t *  ct 
)

Encrypt a stream of data with a symmetric-key algorithm.

In ARC4, and also in FSL_SYM_MODE_CBC and FSL_SYM_MODE_CTR modes, the flags of the sym_ctx object will control part of the operation of this function. The FSL_SYM_CTX_INIT flag means that there is no context info in the object. The FSL_SYM_CTX_LOAD means to use information in the sym_ctx at the start of the operation, and the FSL_SYM_CTX_SAVE flag means to update the object's context information after the operation has been performed.

All of the data for an operation can be run through at once using the FSL_SYM_CTX_INIT or FSL_SYM_CTX_LOAD flags, as appropriate, and then using a length for the whole of the data.

If a FSL_SYM_CTX_SAVE flag were added, an additional call to the function would "pick up" where the previous call left off, allowing the user to perform the larger function in smaller steps.

In FSL_SYM_MODE_CBC and FSL_SYM_MODE_ECB modes, the length must always be a multiple of the block size for the algorithm being used. For proper operation in FSL_SYM_MODE_CTR mode, the length must be a multiple of the block size until the last operation on the total octet stream.

Some users of ARC4 may want to compute the context (S-Box and pointers) from the key before any data is available. This may be done by running this function with a length of zero, with the init & save flags flags on in the sym_ctx. Subsequent operations would then run as normal with the load and save flags. Note that they key object is still required.

Parameters:
user_ctx A user context from fsl_shw_register_user().
key_info Key and algorithm being used for this operation.
[in,out] sym_ctx Info on cipher mode, state of the cipher.
length Length, in octets, of the pt (and ct).
pt pointer to plaintext to be encrypted.
[out] ct pointer to where to store the resulting ciphertext.
Returns:
A return code of type fsl_shw_return_t.

Compute symmetric encryption

Parameters:
user_ctx 
key_info 
sym_ctx 
length 
pt 
ct 
Returns:
A return code of type fsl_shw_return_t.
footer
©  Freescale Semiconductor, Inc., 2007.  All rights reserved.
Freescale Confidential Proprietary
NDA Required
doxygen