Secret Key Object Operations
[Object-Manipulation Operations]

Functions

void fsl_shw_sko_init (fsl_shw_sko_t *key_info, fsl_shw_key_alg_t algorithm)
void fsl_shw_sko_init_pf_key (fsl_shw_sko_t *key_info, fsl_shw_key_alg_t algorithm, fsl_shw_pf_key_t pf_key)
void fsl_shw_sko_set_key (fsl_shw_sko_t *key_object, const uint8_t *key, uint16_t key_length)
void fsl_shw_sko_set_key_length (fsl_shw_sko_t *key_object, uint16_t key_length)
void fsl_shw_sko_set_user_id (fsl_shw_sko_t *key_object, key_userid_t userid)
void fsl_shw_sko_set_keystore (fsl_shw_sko_t *key_object, fsl_shw_kso_t *keystore)
void fsl_shw_sko_set_established_info (fsl_shw_sko_t *key_object, key_userid_t userid, uint32_t handle)
void fsl_shw_sko_get_algorithm (const fsl_shw_sko_t *key_info, fsl_shw_key_alg_t *algorithm)
void fsl_shw_sko_get_key (const fsl_shw_sko_t *skobject, void *skkey)
void fsl_shw_sko_get_established_info (fsl_shw_sko_t *key_object, uint32_t *handle)
void fsl_shw_sko_calculate_wrapped_size (const fsl_shw_sko_t *key_info, uint32_t *length)
void fsl_shw_sko_set_flags (fsl_shw_sko_t *key_object, uint32_t flags)
void fsl_shw_sko_clear_flags (fsl_shw_sko_t *key_object, uint32_t flags)

Detailed Description

These operations should be the only access to the fsl_shw_sko_t type/struct, as the internal members of that object are subject to change.


Function Documentation

void fsl_shw_sko_calculate_wrapped_size ( const fsl_shw_sko_t key_info,
uint32_t *  length 
)

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.

Parameters:
key_info Information about a key to be wrapped.
length Location to store the length of a wrapped version of the key in key_info.
void fsl_shw_sko_clear_flags ( fsl_shw_sko_t key_object,
uint32_t  flags 
)

Clear some flags in the key object.

Turns off the flags specified in flags. Other flags are untouched.

Parameters:
key_object A variable of type fsl_shw_sko_t.
flags (One or more) ORed members of fsl_shw_key_flags_t which are to be reset.
void fsl_shw_sko_get_algorithm ( const fsl_shw_sko_t key_info,
fsl_shw_key_alg_t algorithm 
)

Extract the algorithm from a key object.

Parameters:
key_info The Key Object to be queried.
[out] algorithm A pointer to the location to store the algorithm.
void fsl_shw_sko_get_established_info ( fsl_shw_sko_t key_object,
uint32_t *  handle 
)

Retrieve the established-key handle from a key object.

Parameters:
key_object A variable of type fsl_shw_sko_t.
handle The location to store the handle of the unwrapped key.
void fsl_shw_sko_get_key ( const fsl_shw_sko_t skobject,
void *  skkey 
)

Retrieve the cleartext key from a key object that is stored in a user keystore.

Parameters:
skobject The Key Object to be queried.
[out] skkey A pointer to the location to store the key. NULL if the key is not stored in a user keystore.
void fsl_shw_sko_init ( fsl_shw_sko_t key_info,
fsl_shw_key_alg_t  algorithm 
)

Initialize a Secret Key Object.

This function or fsl_shw_sko_init_pf_key() must be called before performing any other operation with the Object.

Parameters:
key_info The Secret Key Object to be initialized.
algorithm DES, AES, etc.
void fsl_shw_sko_init_pf_key ( fsl_shw_sko_t key_info,
fsl_shw_key_alg_t  algorithm,
fsl_shw_pf_key_t  pf_key 
)

Initialize a Secret Key Object to use a Platform Key register.

This function or fsl_shw_sko_init() must be called before performing any other operation with the Object. fsl_shw_sko_set_key() does not work on a key object initialized in this way.

If this function is used to initialize the key object, but no key is established with the key object, then the object will refer strictly to the key value specified by the pf_key selection.

If the pf key is FSL_SHW_PF_KEY_PRG or FSL_SHW_PF_KEY_IIM_PRG, then the key object may be used with fsl_shw_establish_key() to change the Program Key value. When the pf key is neither FSL_SHW_PF_KEY_PRG nor FSL_SHW_PF_KEY_IIM_PRG, it is an error to call fsl_shw_establish_key().

Parameters:
key_info The Secret Key Object to be initialized.
algorithm DES, AES, etc.
pf_key Which platform key is referenced.
void fsl_shw_sko_set_established_info ( fsl_shw_sko_t key_object,
key_userid_t  userid,
uint32_t  handle 
)

Set the establish key handle into a key object.

The userid field will be used to validate the access to the unwrapped key. This feature is not available for all platforms, nor for all algorithms and modes.

The FSL_SKO_KEY_ESTABLISHED will be set (and the FSL_SKO_KEY_PRESENT flag will be cleared).

Parameters:
key_object A variable of type fsl_shw_sko_t.
userid The User ID to verify this user is an authorized user of the key.
handle A handle from fsl_shw_sko_get_established_info.
void fsl_shw_sko_set_flags ( fsl_shw_sko_t key_object,
uint32_t  flags 
)

Set some flags in the key object.

Turns on the flags specified in flags. Other flags are untouched.

Parameters:
key_object A variable of type fsl_shw_sko_t.
flags (One or more) ORed members of fsl_shw_key_flags_t which are to be set.
void fsl_shw_sko_set_key ( fsl_shw_sko_t key_object,
const uint8_t *  key,
uint16_t  key_length 
)

Store a cleartext key in the key object.

This has the side effect of setting the FSL_SKO_KEY_PRESENT flag. It should not be used if there is a key established with the key object. If there is, a call to fsl_shw_release_key() should be made first.

Parameters:
key_object A variable of type fsl_shw_sko_t.
key A pointer to the beginning of the key.
key_length 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.
void fsl_shw_sko_set_key_length ( fsl_shw_sko_t key_object,
uint16_t  key_length 
)

Set a size for the key.

This function would normally be used when the user wants the key to be generated from a random source.

Parameters:
key_object A variable of type fsl_shw_sko_t.
key_length 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.
void fsl_shw_sko_set_keystore ( fsl_shw_sko_t key_object,
fsl_shw_kso_t keystore 
)

Set the keystore that the key will be stored in.

Parameters:
key_object A variable of type fsl_shw_sko_t.
keystore The keystore to place the key in. This is a variable of type fsl_shw_kso_t.
void fsl_shw_sko_set_user_id ( fsl_shw_sko_t key_object,
key_userid_t  userid 
)

Set the User ID associated with the key.

Parameters:
key_object A variable of type fsl_shw_sko_t.
userid The User ID to identify authorized users of the key.
footer
©  Freescale Semiconductor, Inc., 2007.  All rights reserved.
Freescale Confidential Proprietary
NDA Required
doxygen