Header file to use the SHW driver. More...
Header file to use the SHW driver.
The SHW driver is used in two modes: By a user, from the FSL SHW API in user space, which goes through /dev/fsl_shw to make open(), ioctl(), and close() calls; and by other kernel modules/drivers, which use the FSL SHW API, parts of which are supported directly by the SHW driver.
Testing is performed by using the apitest and kernel api test routines developed for the Sahara2 driver.
#define fsl_shw_gen_random_pf_key | ( | user_ctx | ) | FSL_RETURN_NO_RESOURCE_S |
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. It will not be made active without a call to fsl_shw_select_pf_key().
user_ctx | A user context from fsl_shw_register_user(). |
#define fsl_shw_pco_check_pk_supported | ( | pcobject | ) | 0 |
Determine whether Programmed Key features are available
pcobject | The Platform Capabilities Object to query. |
Referenced by run_wrap().
#define fsl_shw_pco_check_sw_keys_supported | ( | pcobject | ) | 0 |
Determine whether Software Key features are available
pc_info | The Platform Capabilities Object to query. |
Referenced by run_wrap().
#define fsl_shw_pco_get_scc_driver_version | ( | pcobject, | |||
pcmajor, | |||||
pcminor | ) |
{ \ *(pcmajor) = (pcobject)->scc_driver_major; \ *(pcminor) = (pcobject)->scc_driver_minor; \ }
Get FSL SHW SCC driver version
pcobject | The Platform Capababilities Object to query. | |
[out] | pcmajor | A pointer to where the major version of the SCC driver is to be stored. |
[out] | pcminor | A pointer to where the minor version of the SCC driver is to be stored. |
#define fsl_shw_read_tamper_event | ( | user_ctx, | |||
tamperp, | |||||
timestampp | ) | FSL_RETURN_NO_RESOURCE_S |
Retrieve the detected tamper event.
Note that if more than one event was detected, this routine will only ever return one of them.
[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. |
#define fsl_shw_sko_calculate_wrapped_size | ( | wkeyinfo, | |||
wkeylen | ) |
{ \ register fsl_shw_sko_t* kp = wkeyinfo; \ register uint32_t kl = kp->key_length; \ int key_blocks; \ int base_size = 35; /* ICV + T' + ALG + LEN + FLAGS */ \ \ if (kp->flags & FSL_SKO_KEY_SELECT_PF_KEY) { \ kl = 21; /* 168-bit 3DES key */ \ } \ key_blocks = (kl + 7) / 8; \ /* Round length up to 3DES block size for CBC mode */ \ *(wkeylen) = base_size + 8 * key_blocks; \ }
Determine the size of a wrapped key based upon the cleartext key's length.
This function can be used to calculate the number of octets that fsl_shw_extract_key() will write into the location at covered_key.
If zero is returned at length, this means that the key length in key_info is not supported.
wkeyinfo | Information about a key to be wrapped. | |
wkeylen | Location to store the length of a wrapped version of the key in key_info. |
Referenced by extract_reestablish_key(), run_user_wrap(), run_wrap(), and test_software_key().
#define fsl_shw_sko_init | ( | skobject, | |||
skalgorithm | ) |
{ \ fsl_shw_sko_t* skop = skobject; \ \ skop->algorithm = skalgorithm; \ skop->flags = 0; \ skop->keystore = NULL; \ skop->pf_key = FSL_SHW_PF_KEY_PRG; \ }
Initialize a Secret Key Object.
This function must be called before performing any other operation with the Object.
skobject | The Secret Key Object to be initialized. | |
skalgorithm | DES, AES, etc. |
Referenced by init_key_and_sym_ctx(), and test_software_key().
#define fsl_shw_sko_init_pf_key | ( | skobject, | |||
skalgorithm, | |||||
skhwkey | ) |
{ \ fsl_shw_sko_t* skop = skobject; \ fsl_shw_key_alg_t alg = skalgorithm; \ fsl_shw_pf_key_t key = skhwkey; \ \ skop->algorithm = alg; \ if (alg == FSL_KEY_ALG_TDES) { \ skop->key_length = 21; \ } \ skop->keystore = NULL; \ skop->flags = FSL_SKO_KEY_SELECT_PF_KEY; \ skop->pf_key = key; \ if ((key == FSL_SHW_PF_KEY_IIM) || (key == FSL_SHW_PF_KEY_PRG) \ || (key == FSL_SHW_PF_KEY_IIM_PRG) \ || (key == FSL_SHW_PF_KEY_IIM_RND) \ || (key == FSL_SHW_PF_KEY_RND)) { \ skop->flags |= FSL_SKO_KEY_ESTABLISHED; \ } \ }
Initialize a Secret Key Object to use a Platform Key register.
This function must be called before performing any other operation with the Object.
skobject | The Secret Key Object to be initialized. | |
skalgorithm | DES, AES, etc. | |
skhwkey | one of the fsl_shw_pf_key_t values. |
#define fsl_shw_sko_set_flags | ( | skobject, | |||
skflags | ) | (skobject)->flags |= (skflags) |
Set some flags in the key object.
Turns on the flags specified in flags. Other flags are untouched.
skobject | A variable of type fsl_shw_sko_t. | |
skflags | (One or more) ORed members of fsl_shw_key_flags_t which are to be set. |
Referenced by init_key_and_sym_ctx(), run_user_wrap(), run_wrap(), and test_software_key().
#define fsl_shw_sko_set_key | ( | skobject, | |||
skkey, | |||||
skkeylen | ) |
{ \ (skobject)->key_length = skkeylen; \ copy_bytes((skobject)->key, skkey, skkeylen); \ (skobject)->flags |= FSL_SKO_KEY_PRESENT; \ (skobject)->flags &= ~FSL_SKO_KEY_ESTABLISHED; \ }
Store a cleartext key in the key object.
This has the side effect of setting the FSL_SKO_KEY_PRESENT flag and resetting the FSL_SKO_KEY_ESTABLISHED flag.
skobject | A variable of type fsl_shw_sko_t. | |
skkey | A pointer to the beginning of the key. | |
skkeylen | The length, in octets, of the key. The value should be appropriate to the key size supported by the algorithm. 64 octets is the absolute maximum value allowed for this call. |
#define SHW_IOCTL_REQUEST 21 |
Perform a security function.
Referenced by OS_DEV_IOCTL().
typedef enum fsl_shw_acc_mode_t fsl_shw_acc_mode_t |
The type of Authentication-Cipher function which will be performed.
typedef enum fsl_shw_cypher_mode_t fsl_shw_cypher_mode_t |
Select the cypher mode to use for partition cover/uncover operations.
They currently map directly to the values used in the SCC2 driver, but this is not guarinteed behavior.
typedef enum fsl_shw_hash_alg_t fsl_shw_hash_alg_t |
Algorithm selector for Cryptographic Hash functions.
Selection of algorithm determines how large the context and digest will be. Context is the same size as the digest (resulting hash), unless otherwise specified.
typedef enum fsl_shw_hash_ctx_flags_t fsl_shw_hash_ctx_flags_t |
Flags which control a Hash operation.
typedef enum fsl_shw_hmac_ctx_flags_t fsl_shw_hmac_ctx_flags_t |
Flags which control an HMAC operation.
These may be combined by ORing them together. See fsl_shw_hmco_set_flags() and fsl_shw_hmco_clear_flags().
typedef enum fsl_shw_key_alg_t fsl_shw_key_alg_t |
Algorithm Identifier.
Selection of algorithm will determine how large the block size of the algorithm is. Context size is the same length unless otherwise specified. Selection of algorithm also affects the allowable key length.
typedef enum fsl_shw_pf_key_t fsl_shw_pf_key_t |
Which platform key should be presented for cryptographic use.
typedef enum fsl_shw_return_t fsl_shw_return_t |
Return code for FSL_SHW library.
These codes may be returned from a function call. In non-blocking mode, they will appear as the status in a Result Object.
typedef enum fsl_shw_sym_mode_t fsl_shw_sym_mode_t |
Mode selector for Symmetric Ciphers.
The selection of mode determines how a cryptographic algorithm will be used to process the plaintext or ciphertext.
For all modes which are run block-by-block (that is, all but FSL_SYM_MODE_STREAM), any partial operations must be performed on a text length which is multiple of the block size. Except for FSL_SYM_MODE_CTR, these block-by-block algorithms must also be passed a total number of octets which is a multiple of the block size.
In modes which require that the total number of octets of data be a multiple of the block size (FSL_SYM_MODE_ECB and FSL_SYM_MODE_CBC), and the user has a total number of octets which are not a multiple of the block size, the user must perform any necessary padding to get to the correct data length.
typedef enum fsl_shw_tamper_t fsl_shw_tamper_t |
The various security tamper events
typedef enum fsl_shw_user_ctx_flags_t fsl_shw_user_ctx_flags_t |
Flags for the state of the User Context Object (fsl_shw_uco_t).
typedef enum shw_user_request_t shw_user_request_t |
This is part of the IOCTL request type passed between kernel and user space. It is added to SHW_IOCTL_REQUEST to generate the actual value.
enum fsl_shw_acc_mode_t |
The type of Authentication-Cipher function which will be performed.
enum fsl_shw_ctr_mod_t |
Select the cypher mode to use for partition cover/uncover operations.
They currently map directly to the values used in the SCC2 driver, but this is not guarinteed behavior.
enum fsl_shw_hash_alg_t |
Algorithm selector for Cryptographic Hash functions.
Selection of algorithm determines how large the context and digest will be. Context is the same size as the digest (resulting hash), unless otherwise specified.
Flags which control a Hash operation.
FSL_HASH_FLAGS_INIT |
Context is empty. Hash is started from scratch, with a message-processed count of zero. |
FSL_HASH_FLAGS_SAVE |
Retrieve context from hardware after hashing. If used with the FSL_HASH_FLAGS_FINALIZE flag, the final digest value will be saved in the object. |
FSL_HASH_FLAGS_LOAD |
Place context into hardware before hashing. |
FSL_HASH_FLAGS_FINALIZE |
PAD message and perform final digest operation. If user message is pre-padded, this flag should not be used. |
FSL_HASH_FLAGS_INIT |
Context is empty. Hash is started from scratch, with a message-processed count of zero. |
FSL_HASH_FLAGS_SAVE |
Retrieve context from hardware after hashing. If used with the FSL_HASH_FLAGS_FINALIZE flag, the final digest value will be saved in the object. |
FSL_HASH_FLAGS_LOAD |
Place context into hardware before hashing. |
FSL_HASH_FLAGS_FINALIZE |
PAD message and perform final digest operation. If user message is pre-padded, this flag should not be used. |
FSL_HASH_FLAGS_INIT |
Context is empty. Hash is started from scratch, with a message-processed count of zero. |
FSL_HASH_FLAGS_SAVE |
Retrieve context from hardware after hashing. If used with the FSL_HASH_FLAGS_FINALIZE flag, the final digest value will be saved in the object. |
FSL_HASH_FLAGS_LOAD |
Place context into hardware before hashing. |
FSL_HASH_FLAGS_FINALIZE |
PAD message and perform final digest operation. If user message is pre-padded, this flag should not be used. |
FSL_HASH_FLAGS_INIT |
Context is empty. Hash is started from scratch, with a message-processed count of zero. |
FSL_HASH_FLAGS_SAVE |
Retrieve context from hardware after hashing. If used with the FSL_HASH_FLAGS_FINALIZE flag, the final digest value will be saved in the object. |
FSL_HASH_FLAGS_LOAD |
Place context into hardware before hashing. |
FSL_HASH_FLAGS_FINALIZE |
PAD message and perform final digest operation. If user message is pre-padded, this flag should not be used. |
FSL_HASH_FLAGS_INIT |
Context is empty. Hash is started from scratch, with a message-processed count of zero. |
FSL_HASH_FLAGS_SAVE |
Retrieve context from hardware after hashing. If used with the FSL_HASH_FLAGS_FINALIZE flag, the final digest value will be saved in the object. |
FSL_HASH_FLAGS_LOAD |
Place context into hardware before hashing. |
FSL_HASH_FLAGS_FINALIZE |
PAD message and perform final digest operation. If user message is pre-padded, this flag should not be used. |
Flags which control an HMAC operation.
These may be combined by ORing them together. See fsl_shw_hmco_set_flags() and fsl_shw_hmco_clear_flags().
FSL_HMAC_FLAGS_INIT |
Message context is empty. HMAC is started from scratch (with key) or from precompute of inner hash, depending on whether FSL_HMAC_FLAGS_PRECOMPUTES_PRESENT is set. |
FSL_HMAC_FLAGS_SAVE |
Retrieve ongoing context from hardware after hashing. If used with the FSL_HMAC_FLAGS_FINALIZE flag, the final digest value (HMAC) will be saved in the object. |
FSL_HMAC_FLAGS_LOAD |
Place ongoing context into hardware before hashing. |
FSL_HMAC_FLAGS_FINALIZE |
PAD message and perform final HMAC operations of inner and outer hashes. |
FSL_HMAC_FLAGS_PRECOMPUTES_PRESENT |
This means that the context contains precomputed inner and outer hash values. |
FSL_HMAC_FLAGS_INIT |
Message context is empty. HMAC is started from scratch (with key) or from precompute of inner hash, depending on whether FSL_HMAC_FLAGS_PRECOMPUTES_PRESENT is set. |
FSL_HMAC_FLAGS_SAVE |
Retrieve ongoing context from hardware after hashing. If used with the FSL_HMAC_FLAGS_FINALIZE flag, the final digest value (HMAC) will be saved in the object. |
FSL_HMAC_FLAGS_LOAD |
Place ongoing context into hardware before hashing. |
FSL_HMAC_FLAGS_FINALIZE |
PAD message and perform final HMAC operations of inner and outer hashes. |
FSL_HMAC_FLAGS_PRECOMPUTES_PRESENT |
This means that the context contains precomputed inner and outer hash values. |
FSL_HMAC_FLAGS_INIT |
Message context is empty. HMAC is started from scratch (with key) or from precompute of inner hash, depending on whether FSL_HMAC_FLAGS_PRECOMPUTES_PRESENT is set. |
FSL_HMAC_FLAGS_SAVE |
Retrieve ongoing context from hardware after hashing. If used with the FSL_HMAC_FLAGS_FINALIZE flag, the final digest value (HMAC) will be saved in the object. |
FSL_HMAC_FLAGS_LOAD |
Place ongoing context into hardware before hashing. |
FSL_HMAC_FLAGS_FINALIZE |
PAD message and perform final HMAC operations of inner and outer hashes. |
FSL_HMAC_FLAGS_PRECOMPUTES_PRESENT |
This means that the context contains precomputed inner and outer hash values. |
FSL_HMAC_FLAGS_INIT |
Message context is empty. HMAC is started from scratch (with key) or from precompute of inner hash, depending on whether FSL_HMAC_FLAGS_PRECOMPUTES_PRESENT is set. |
FSL_HMAC_FLAGS_SAVE |
Retrieve ongoing context from hardware after hashing. If used with the FSL_HMAC_FLAGS_FINALIZE flag, the final digest value (HMAC) will be saved in the object. |
FSL_HMAC_FLAGS_LOAD |
Place ongoing context into hardware before hashing. |
FSL_HMAC_FLAGS_FINALIZE |
PAD message and perform final HMAC operations of inner and outer hashes. |
FSL_HMAC_FLAGS_PRECOMPUTES_PRESENT |
This means that the context contains precomputed inner and outer hash values. |
enum fsl_shw_key_alg_t |
Algorithm Identifier.
Selection of algorithm will determine how large the block size of the algorithm is. Context size is the same length unless otherwise specified. Selection of algorithm also affects the allowable key length.
enum fsl_shw_key_flags_t |
enum fsl_shw_key_wrap_t |
enum fsl_shw_permission_t |
enum fsl_shw_pf_key_t |
Which platform key should be presented for cryptographic use.
enum fsl_shw_return_t |
Return code for FSL_SHW library.
These codes may be returned from a function call. In non-blocking mode, they will appear as the status in a Result Object.
FSL_SYM_CTX_INIT |
Context is empty. In ARC4, this means that the S-Box needs to be generated from the key. In FSL_SYM_MODE_CBC mode, this allows an IV of zero to be specified. In FSL_SYM_MODE_CTR mode, it means that an initial CTR value of zero is desired. |
FSL_SYM_CTX_LOAD |
Load context from object into hardware before running cipher. In FSL_SYM_MODE_CTR mode, this would refer to the Counter Value. |
FSL_SYM_CTX_SAVE |
Save context from hardware into object after running cipher. In FSL_SYM_MODE_CTR mode, this would refer to the Counter Value. |
FSL_SYM_CTX_PROTECT |
Context (SBox) is to be unwrapped and wrapped on each use. This flag is unsupported. |
FSL_SYM_CTX_INIT |
Context is empty. In ARC4, this means that the S-Box needs to be generated from the key. In FSL_SYM_MODE_CBC mode, this allows an IV of zero to be specified. In FSL_SYM_MODE_CTR mode, it means that an initial CTR value of zero is desired. |
FSL_SYM_CTX_LOAD |
Load context from object into hardware before running cipher. In FSL_SYM_MODE_CTR mode, this would refer to the Counter Value. |
FSL_SYM_CTX_SAVE |
Save context from hardware into object after running cipher. In FSL_SYM_MODE_CTR mode, this would refer to the Counter Value. |
FSL_SYM_CTX_PROTECT |
Context (SBox) is to be unwrapped and wrapped on each use. This flag is unsupported. |
FSL_SYM_CTX_INIT |
Context is empty. In ARC4, this means that the S-Box needs to be generated from the key. In FSL_SYM_MODE_CBC mode, this allows an IV of zero to be specified. In FSL_SYM_MODE_CTR mode, it means that an initial CTR value of zero is desired. |
FSL_SYM_CTX_LOAD |
Load context from object into hardware before running cipher. In FSL_SYM_MODE_CTR mode, this would refer to the Counter Value. |
FSL_SYM_CTX_SAVE |
Save context from hardware into object after running cipher. In FSL_SYM_MODE_CTR mode, this would refer to the Counter Value. |
FSL_SYM_CTX_PROTECT |
Context (SBox) is to be unwrapped and wrapped on each use. This flag is unsupported. |
FSL_SYM_CTX_INIT |
Context is empty. In ARC4, this means that the S-Box needs to be generated from the key. In FSL_SYM_MODE_CBC mode, this allows an IV of zero to be specified. In FSL_SYM_MODE_CTR mode, it means that an initial CTR value of zero is desired. |
FSL_SYM_CTX_LOAD |
Load context from object into hardware before running cipher. In FSL_SYM_MODE_CTR mode, this would refer to the Counter Value. |
FSL_SYM_CTX_SAVE |
Save context from hardware into object after running cipher. In FSL_SYM_MODE_CTR mode, this would refer to the Counter Value. |
FSL_SYM_CTX_PROTECT |
Context (SBox) is to be unwrapped and wrapped on each use. This flag is unsupported. |
enum fsl_shw_sym_mode_t |
Mode selector for Symmetric Ciphers.
The selection of mode determines how a cryptographic algorithm will be used to process the plaintext or ciphertext.
For all modes which are run block-by-block (that is, all but FSL_SYM_MODE_STREAM), any partial operations must be performed on a text length which is multiple of the block size. Except for FSL_SYM_MODE_CTR, these block-by-block algorithms must also be passed a total number of octets which is a multiple of the block size.
In modes which require that the total number of octets of data be a multiple of the block size (FSL_SYM_MODE_ECB and FSL_SYM_MODE_CBC), and the user has a total number of octets which are not a multiple of the block size, the user must perform any necessary padding to get to the correct data length.
enum fsl_shw_tamper_t |
The various security tamper events
Flags for the state of the User Context Object (fsl_shw_uco_t).
FSL_UCO_BLOCKING_MODE |
API will block the caller until operation completes. The result will be available in the return code. If this is not set, user will have to get results using fsl_shw_get_results(). |
FSL_UCO_CALLBACK_MODE |
User wants callback (at the function specified with fsl_shw_uco_set_callback()) when the operation completes. This flag is valid only if FSL_UCO_BLOCKING_MODE is not set. |
FSL_UCO_SAVE_DESC_CHAIN |
Do not free descriptor chain after driver (adaptor) finishes |
FSL_UCO_CALLBACK_SETUP_COMPLETE |
User has made at least one request with callbacks requested, so API is ready to handle others. |
FSL_UCO_CHAIN_PREPHYSICALIZED |
(virtual) pointer to descriptor chain is completely linked with physical (DMA) addresses, ready for the hardware. This flag should not be used by FSL SHW API programs. |
FSL_UCO_CONTEXT_CHANGED |
The user has changed the context but the changes have not been copied to the kernel driver. |
FSL_UCO_USERMODE_USER |
Internal Use. This context belongs to a user-mode API user. |
FSL_UCO_BLOCKING_MODE |
API will block the caller until operation completes. The result will be available in the return code. If this is not set, user will have to get results using fsl_shw_get_results(). |
FSL_UCO_CALLBACK_MODE |
User wants callback (at the function specified with fsl_shw_uco_set_callback()) when the operation completes. This flag is valid only if FSL_UCO_BLOCKING_MODE is not set. |
FSL_UCO_SAVE_DESC_CHAIN |
Do not free descriptor chain after driver (adaptor) finishes |
FSL_UCO_CALLBACK_SETUP_COMPLETE |
User has made at least one request with callbacks requested, so API is ready to handle others. |
FSL_UCO_CHAIN_PREPHYSICALIZED |
(virtual) pointer to descriptor chain is completely linked with physical (DMA) addresses, ready for the hardware. This flag should not be used by FSL SHW API programs. |
FSL_UCO_CONTEXT_CHANGED |
The user has changed the context but the changes have not been copied to the kernel driver. |
FSL_UCO_USERMODE_USER |
Internal Use. This context belongs to a user-mode API user. |
FSL_UCO_BLOCKING_MODE |
API will block the caller until operation completes. The result will be available in the return code. If this is not set, user will have to get results using fsl_shw_get_results(). |
FSL_UCO_CALLBACK_MODE |
User wants callback (at the function specified with fsl_shw_uco_set_callback()) when the operation completes. This flag is valid only if FSL_UCO_BLOCKING_MODE is not set. |
FSL_UCO_SAVE_DESC_CHAIN |
Do not free descriptor chain after driver (adaptor) finishes |
FSL_UCO_CALLBACK_SETUP_COMPLETE |
User has made at least one request with callbacks requested, so API is ready to handle others. |
FSL_UCO_CHAIN_PREPHYSICALIZED |
(virtual) pointer to descriptor chain is completely linked with physical (DMA) addresses, ready for the hardware. This flag should not be used by FSL SHW API programs. |
FSL_UCO_CONTEXT_CHANGED |
The user has changed the context but the changes have not been copied to the kernel driver. |
FSL_UCO_USERMODE_USER |
Internal Use. This context belongs to a user-mode API user. |
FSL_UCO_BLOCKING_MODE |
API will block the caller until operation completes. The result will be available in the return code. If this is not set, user will have to get results using fsl_shw_get_results(). |
FSL_UCO_CALLBACK_MODE |
User wants callback (at the function specified with fsl_shw_uco_set_callback()) when the operation completes. This flag is valid only if FSL_UCO_BLOCKING_MODE is not set. |
FSL_UCO_SAVE_DESC_CHAIN |
Do not free descriptor chain after driver (adaptor) finishes |
FSL_UCO_CALLBACK_SETUP_COMPLETE |
User has made at least one request with callbacks requested, so API is ready to handle others. |
FSL_UCO_CHAIN_PREPHYSICALIZED |
(virtual) pointer to descriptor chain is completely linked with physical (DMA) addresses, ready for the hardware. This flag should not be used by FSL SHW API programs. |
FSL_UCO_CONTEXT_CHANGED |
The user has changed the context but the changes have not been copied to the kernel driver. |
FSL_UCO_USERMODE_USER |
Internal Use. This context belongs to a user-mode API user. |
FSL_UCO_BLOCKING_MODE |
API will block the caller until operation completes. The result will be available in the return code. If this is not set, user will have to get results using fsl_shw_get_results(). |
FSL_UCO_CALLBACK_MODE |
User wants callback (at the function specified with fsl_shw_uco_set_callback()) when the operation completes. This flag is valid only if FSL_UCO_BLOCKING_MODE is not set. |
FSL_UCO_SAVE_DESC_CHAIN |
Do not free descriptor chain after driver (adaptor) finishes |
FSL_UCO_CALLBACK_SETUP_COMPLETE |
User has made at least one request with callbacks requested, so API is ready to handle others. |
FSL_UCO_CHAIN_PREPHYSICALIZED |
(virtual) pointer to descriptor chain is completely linked with physical (DMA) addresses, ready for the hardware. This flag should not be used by FSL SHW API programs. |
FSL_UCO_CONTEXT_CHANGED |
The user has changed the context but the changes have not been copied to the kernel driver. |
FSL_UCO_USERMODE_USER |
Internal Use. This context belongs to a user-mode API user. |
enum shw_user_request_t |
This is part of the IOCTL request type passed between kernel and user space. It is added to SHW_IOCTL_REQUEST to generate the actual value.
fsl_shw_return_t do_scc_decrypt_region | ( | fsl_shw_uco_t * | user_ctx, | |
void * | partition_base, | |||
uint32_t | offset_bytes, | |||
uint32_t | byte_count, | |||
const uint8_t * | black_data, | |||
uint32_t * | IV, | |||
fsl_shw_cypher_mode_t | cypher_mode | |||
) |
Decrypt a region of secure memory using the hardware secret key.
user_ctx | User context | |
partition_base | Base address of the partition | |
offset_bytes | Offset of data from the partition base | |
byte_count | Length of the data to encrypt | |
black_data | Location to store the encrypted data | |
IV | IV to use for the encryption routine | |
cypher_mode | Cyphering mode to use, specified by type fsl_shw_cypher_mode_t |
Call the proper function to decrypt a region of encrypted secure memory
user_ctx | User context of the partition owner (NULL in kernel) | |
partition_base | Base address (physical) of the partition | |
offset_bytes | Offset from base address that the decrypted data shall be placed | |
byte_count | Length of the message (bytes) | |
black_data | Pointer to where the encrypted data is stored | |
IV | IV to use for decryption | |
cypher_mode | Cyphering mode to use, specified by type fsl_shw_cypher_mode_t |
Call the proper function to decrypt a region of encrypted secure memory
user_ctx | User context of the partition owner (NULL in kernel) | |
partition_base | Base address (physical) of the partition | |
offset_bytes | Offset from base address that the decrypted data shall be placed | |
byte_count | Length of the message (bytes) | |
black_data | Pointer to where the encrypted data is stored | |
owner_id |
fsl_shw_return_t do_scc_encrypt_region | ( | fsl_shw_uco_t * | user_ctx, | |
void * | partition_base, | |||
uint32_t | offset_bytes, | |||
uint32_t | byte_count, | |||
uint8_t * | black_data, | |||
uint32_t * | IV, | |||
fsl_shw_cypher_mode_t | cypher_mode | |||
) |
Encrypt a region of secure memory using the hardware secret key.
user_ctx | User context | |
partition_base | Base address of the partition | |
offset_bytes | Offset of data from the partition base | |
byte_count | Length of the data to encrypt | |
black_data | Location to store the encrypted data | |
IV | IV to use for the encryption routine | |
cypher_mode | Cyphering mode to use, specified by type fsl_shw_cypher_mode_t |
Call the proper function to encrypt a region of encrypted secure memory
user_ctx | User context of the partition owner (NULL in kernel) | |
partition_base | Base address (physical) of the partition | |
offset_bytes | Offset from base address of the data to be encrypted | |
byte_count | Length of the message (bytes) | |
black_data | Pointer to where the encrypted data is stored | |
IV | IV to use for encryption | |
cypher_mode | Cyphering mode to use, specified by type fsl_shw_cypher_mode_t |
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.
user_ctx | A user context from fsl_shw_register_user(). | |
length | Number of bytes at data. | |
data | Entropy to add to random number generator. |
Add entropy to a random number generator
user_ctx | ||
length | ||
data |
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.
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. |
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 |
fsl_shw_return_t fsl_shw_deregister_user | ( | fsl_shw_uco_t * | user_ctx | ) |
Destroy the association between the user and the provider of the API.
user_ctx | The user context which is no longer needed. |
Destroy the association between the the user and the provider of the API.
user_ctx | The user context which is no longer needed. |
Referenced by OS_DEV_CLOSE().
fsl_shw_return_t fsl_shw_diminish_perms | ( | fsl_shw_uco_t * | user_ctx, | |
void * | address, | |||
uint32_t | permissions | |||
) |
Diminish the permissions of a block of secure memory. Note that permissions can only be revoked.
user_ctx | User context | |
address | Base address of the secure memory to work with | |
permissions | Permissions to initialize the partition with. Can be made by ORing flags from the fsl_shw_permission_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.
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.
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. |
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.
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). |
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.
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). |
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.
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. |
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.
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 |
fsl_shw_pco_t * fsl_shw_get_capabilities | ( | fsl_shw_uco_t * | user_ctx | ) |
Determine the hardware security capabilities of this platform.
Though a user context object is passed into this function, it will always act in a non-blocking manner.
user_ctx | The user context which will be used for the query. |
Referenced by run_user_wrap(), and run_wrap().
fsl_shw_return_t fsl_shw_get_random | ( | fsl_shw_uco_t * | user_ctx, | |
uint32_t | length, | |||
uint8_t * | data | |||
) |
Get random data.
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. |
Get random data.
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. |
Get a random number
user_ctx | ||
length | ||
data |
fsl_shw_return_t fsl_shw_get_results | ( | fsl_shw_uco_t * | user_ctx, | |
unsigned | result_size, | |||
fsl_shw_result_t | results[], | |||
unsigned * | result_count | |||
) |
Retrieve results from earlier operations.
user_ctx | The user's context. | |
result_size | The number of array elements of results. | |
[in,out] | results | Pointer to first of the (array of) locations to store results. |
[out] | result_count | Pointer to store the number of results which were returned. |
Referenced by get_results().
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.
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. |
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 | |||
) |
Get the hmac
user_ctx | Info for acquiring memory | |
key_info | ||
hmac_ctx | ||
msg | ||
length | ||
result | ||
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.
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. |
Get the hmac
user_ctx | Info for acquiring memory | |
key_info | ||
hmac_ctx | ||
msg | ||
length | ||
result | ||
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 | |||
) |
Get the precompute information
user_ctx | ||
key_info | ||
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.
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. |
Get the precompute information
user_ctx | ||
key_info | ||
hmac_ctx |
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.
user_ctx | A user context from fsl_shw_register_user(). | |
key_info | The referenced key. | |
[out] | key | The location to store the key value. |
fsl_shw_return_t fsl_shw_register_user | ( | fsl_shw_uco_t * | user_ctx | ) |
Create an association between the user and the provider of the API.
user_ctx | The user context which will be used for this association. |
Create an association between the the user and the provider of the API.
user_ctx | The user context which will be used for this association. |
Referenced by OS_DEV_MMAP(), and OS_DEV_OPEN().
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.
user_ctx | A user context from fsl_shw_register_user(). | |
key_info | The information about the key to be deleted. |
fsl_shw_return_t fsl_shw_sfree | ( | fsl_shw_uco_t * | user_ctx, | |
void * | address | |||
) |
Free a block of secure memory that was allocated with fsl_shw_smalloc
user_ctx | User context | |
address | Address of the block of secure memory to be released. |
void * fsl_shw_smalloc | ( | fsl_shw_uco_t * | user_ctx, | |
uint32_t | size, | |||
const uint8_t * | UMID, | |||
uint32_t | permissions | |||
) |
Allocate a block of secure memory
user_ctx | User context | |
size | Memory size (octets). Note: currently only supports only single-partition sized blocks. | |
UMID | User Mode ID to use when registering the partition. | |
permissions | Permissions to initialize the partition with. Can be made by ORing flags from the fsl_shw_permission_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.
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. |
Compute symmetric decryption
user_ctx | ||
key_info | ||
sym_ctx | ||
length | ||
pt | ||
ct |
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.
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. |
Compute symmetric encryption
user_ctx | ||
key_info | ||
sym_ctx | ||
length | ||
pt | ||
ct |
© Freescale Semiconductor, Inc., 2007.
All rights reserved. Freescale Confidential Proprietary NDA Required |
![]() |