User Keystore API

Functions

void fsl_shw_init_keystore (fsl_shw_kso_t *keystore, fsl_shw_return_t(*data_init)(fsl_shw_uco_t *user_ctx, void **user_data), void(*data_cleanup)(fsl_shw_uco_t *user_ctx, void **user_data), fsl_shw_return_t(*slot_alloc)(void *user_data, uint32_t size, uint64_towner_id, uint32_t *slot), fsl_shw_return_t(*slot_dealloc)(void *user_data, uint64_towner_id, uint32_tslot), fsl_shw_return_t(*slot_verify_access)(void *user_data, uint64_towner_id, uint32_tslot), void *(*slot_get_address)(void *user_data, uint32_t handle), uint32_t(*slot_get_base)(void *user_data, uint32_t handle), uint32_t(*slot_get_offset)(void *user_data, uint32_t handle), uint32_t(*slot_get_slot_size)(void *user_data, uint32_thandle))
void fsl_shw_init_keystore_default (fsl_shw_kso_t *keystore)
fsl_shw_return_t fsl_shw_establish_keystore (fsl_shw_uco_t *user_ctx, fsl_shw_kso_t *keystore)
void fsl_shw_release_keystore (fsl_shw_uco_t *user_ctx, fsl_shw_kso_t *keystore)
fsl_shw_return_t keystore_slot_alloc (fsl_shw_kso_t *keystore, uint32_t size, uint64_t owner_id, uint32_t *slot)
fsl_shw_return_t keystore_slot_dealloc (fsl_shw_kso_t *keystore, uint64_t owner_id, uint32_t slot)
fsl_shw_return_t keystore_slot_load (fsl_shw_kso_t *keystore, uint64_t owner_id, uint32_t slot, const uint8_t *key_data, uint32_t key_length)
fsl_shw_return_t keystore_slot_read (fsl_shw_kso_t *keystore, uint64_t owner_id, uint32_t slot, uint32_t key_length, uint8_t *key_data)
fsl_shw_return_t keystore_slot_encrypt (fsl_shw_uco_t *user_ctx, fsl_shw_kso_t *keystore, uint64_t owner_id, uint32_t slot, uint32_t length, uint8_t *destination)
fsl_shw_return_t keystore_slot_decrypt (fsl_shw_uco_t *user_ctx, fsl_shw_kso_t *keystore, uint64_t owner_id, uint32_t slot, uint32_t length, const uint8_t *source)

Detailed Description

Keystore API

These functions define the generic keystore API, which can be used in conjunction with a keystore implementation backend to support a user keystore.


Function Documentation

fsl_shw_return_t fsl_shw_establish_keystore ( fsl_shw_uco_t user_ctx,
fsl_shw_kso_t keystore 
)

Establish a Keystore Object.

This function establishes a keystore object that has been set up by a call to fsl_shw_init_keystore(). It is a wrapper for the user-defined data_init() function, which is specified during keystore initialization.

Parameters:
user_ctx The user context that this keystore should be attached to
keystore The Keystore object to operate on.
Returns:
A return code of type fsl_shw_return_t.

References FSL_RETURN_NO_RESOURCE_S.

Referenced by OS_DEV_INIT(), and run_user_wrap().

void fsl_shw_init_keystore ( fsl_shw_kso_t keystore,
fsl_shw_return_t(*)(fsl_shw_uco_t *user_ctx, void **user_data)  data_init,
void(*)(fsl_shw_uco_t *user_ctx, void **user_data)  data_cleanup,
fsl_shw_return_t(*)(void *user_data, uint32_t size, uint64_towner_id, uint32_t *slot)  slot_alloc,
fsl_shw_return_t(*)(void *user_data, uint64_towner_id, uint32_tslot)  slot_dealloc,
fsl_shw_return_t(*)(void *user_data, uint64_towner_id, uint32_tslot)  slot_verify_access,
void *(*)(void *user_data, uint32_t handle)  slot_get_address,
uint32_t(*)(void *user_data, uint32_t handle)  slot_get_base,
uint32_t(*)(void *user_data, uint32_t handle)  slot_get_offset,
uint32_t(*)(void *user_data, uint32_thandle)  slot_get_slot_size 
)

Size of each key slot, in octets. This sets an upper bound on the size of a key that can placed in the keystore.

Initialize a Keystore Object.

This function must be called before performing any other operation with the Object. It allows the user to associate a custom keystore interface by specifying the correct set of functions that will be used to perform actions on the keystore object. To use the default keystore handler, the function fsl_shw_init_keystore_default() can be used instead.

Parameters:
keystore The Keystore object to operate on.
data_init Keystore initialization function. This function is responsible for initializing the keystore. A user-defined object can be assigned to the user_data pointer, and will be passed to any function acting on that keystore. It is called during fsl_shw_establish_keystore().
data_cleanup Keystore cleanup function. This function cleans up any data structures associated with the keyboard. It is called by fsl_shw_release_keystore().
slot_alloc Slot allocation function. This function allocates a key slot, potentially based on size and owner id. It is called by fsl_shw_establish_key().
slot_dealloc Slot deallocation function.
slot_verify_access Function to verify that a given Owner ID credential matches the given slot.
slot_get_address For SCC2: Get the virtual address (kernel or userspace) of the data stored in the slot. For SCC: Get the physical address of the data stored in the slot.
slot_get_base For SCC2: Get the (virtual) base address of the partition that the slot is located on. For SCC: Not implemented.
slot_get_offset For SCC2: Get the offset from the start of the partition that the slot data is located at (in octets) For SCC: Not implemented.
slot_get_slot_size Get the size of the key slot, in octets.
void fsl_shw_init_keystore_default ( fsl_shw_kso_t keystore  ) 

Initialize a Keystore Object.

This function must be called before performing any other operation with the Object. It sets the user keystore object up to use the default keystore handler. If a custom keystore handler is desired, the function fsl_shw_init_keystore() can be used instead.

Parameters:
keystore The Keystore object to operate on.

Referenced by OS_DEV_INIT(), and run_user_wrap().

void fsl_shw_release_keystore ( fsl_shw_uco_t user_ctx,
fsl_shw_kso_t keystore 
)

Release a Keystore Object.

This function releases an established keystore object. It is a wrapper for the user-defined data_cleanup() function, which is specified during keystore initialization.

Parameters:
user_ctx The user context that this keystore should be attached to.
keystore The Keystore object to operate on.

Referenced by OS_DEV_SHUTDOWN(), and run_user_wrap().

fsl_shw_return_t keystore_slot_alloc ( fsl_shw_kso_t keystore,
uint32_t  size,
uint64_t  owner_id,
uint32_t *  slot 
)

Allocate a slot in the Keystore.

This function attempts to allocate a slot to hold a key in the keystore. It is called by fsl_shw_establish_key() when establishing a Secure Key Object, if the key has been flagged to be stored in a user keystore by the fsl_shw_sko_set_keystore() function. It is a wrapper for the implementation-specific function slot_alloc().

Parameters:
keystore The Keystore object to operate on.
[in] size Size of the key to be stored (octets).
[in] owner_id ID of the key owner.
[out] slot If successful, assigned slot ID
Returns:
A return code of type fsl_shw_return_t.

References FSL_RETURN_NO_RESOURCE_S.

Referenced by fsl_shw_establish_key().

fsl_shw_return_t keystore_slot_dealloc ( fsl_shw_kso_t keystore,
uint64_t  owner_id,
uint32_t  slot 
)

Deallocate a slot in the Keystore.

This function attempts to allocate a slot to hold a key in the keystore. It is called by fsl_shw_extract_key() and fsl_shw_release_key() when the key that it contains is to be released. It is a wrapper for the implmentation-specific function slot_dealloc().

Parameters:
keystore The Keystore object to operate on.
[in] owner_id ID of the key owner.
[in] slot If successful, assigned slot ID.
Returns:
A return code of type fsl_shw_return_t.

References FSL_RETURN_NO_RESOURCE_S.

Referenced by fsl_shw_establish_key(), fsl_shw_extract_key(), and fsl_shw_release_key().

fsl_shw_return_t keystore_slot_decrypt ( fsl_shw_uco_t user_ctx,
fsl_shw_kso_t keystore,
uint64_t  owner_id,
uint32_t  slot,
uint32_t  length,
const uint8_t *  source 
)

Decrypt a keyslot

This function decrypts a key using the hardware secret key.

Parameters:
user_ctx User context
keystore The Keystore object to operate on.
[in] owner_id ID of the key owner.
[in] slot Slot ID of the key to encrypt.
[in] length Length of the key
[in] source Pointer to the location where the encrypted data is stored.
Returns:
A return code of type fsl_shw_return_t.

References FSL_RETURN_NO_RESOURCE_S.

fsl_shw_return_t keystore_slot_encrypt ( fsl_shw_uco_t user_ctx,
fsl_shw_kso_t keystore,
uint64_t  owner_id,
uint32_t  slot,
uint32_t  length,
uint8_t *  destination 
)

Encrypt a keyslot

This function encrypts a key using the hardware secret key.

Parameters:
user_ctx User context
keystore The Keystore object to operate on.
[in] owner_id ID of the key owner.
[in] slot Slot ID of the key to encrypt.
[in] length Length of the key
[out] destination Pointer to the location where the encrypted data is to be stored.
Returns:
A return code of type fsl_shw_return_t.

References FSL_RETURN_NO_RESOURCE_S.

fsl_shw_return_t keystore_slot_load ( fsl_shw_kso_t keystore,
uint64_t  owner_id,
uint32_t  slot,
const uint8_t *  key_data,
uint32_t  key_length 
)

Load cleartext key data into a key slot

This function loads a key slot with cleartext data.

Parameters:
keystore The Keystore object to operate on.
[in] owner_id ID of the key owner.
[in] slot If successful, assigned slot ID.
[in] key_data Pointer to the location of the cleartext key data.
[in] key_length Length of the key data (octets).
Returns:
A return code of type fsl_shw_return_t.

References FSL_RETURN_NO_RESOURCE_S.

Referenced by fsl_shw_establish_key().

fsl_shw_return_t keystore_slot_read ( fsl_shw_kso_t keystore,
uint64_t  owner_id,
uint32_t  slot,
uint32_t  key_length,
uint8_t *  key_data 
)

Read cleartext key data from a key slot

This function returns the key in a key slot.

Parameters:
keystore The Keystore object to operate on.
[in] owner_id ID of the key owner.
[in] slot ID of slot where key resides.
[in] key_length Length of the key data (octets).
[out] key_data Pointer to the location of the cleartext key data.
Returns:
A return code of type fsl_shw_return_t.

References FSL_RETURN_NO_RESOURCE_S.

Referenced by fsl_shw_read_key().

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