Key handling#
Secure Engine key handling API.
API for using cryptographic keys with the SE. Contains functionality to generate, import and export keys to and from protected types like wrapped or volatile keys.
Modules#
sl_se_custom_weierstrass_prime_domain_t
Typedefs#
Supported key types.
Key storage method.
Internal SE key slot.
Functions#
Validate key descriptor.
Generate a random key adhering to the given key descriptor.
Import a key using the SE.
Export a volatile or wrapped key back to plaintext.
Transfer a volatile or wrapped key to another protected storage.
Export the public part of an ECC keypair.
Delete a key from a volatile SE storage slot.
Returns the required storage size for the given key.
Macros#
Asymmetric key can only be used for signing (not key exchange)
Described key belongs to a custom ECC domain.
Storage buffer contains public part of an asymmetric key.
Storage buffer contains private part of an asymmetric key.
Allow usage of this key by other bus masters or TrustZone levels than the one which created/imported the key.
Old definition. Retained for backwards compatibility.
Do not allow exporting the key to plaintext.
Indicate that the key has been generated by this device.
Indicate that the key can only be used to sign SE generated content.
Mask for algorithm field in key type.
Offset of algorithm field in key type.
Mask for attributes field in key type.
Offset of attributes field in key type.
Symmetric key type.
Symmetric key type for AES-128 (16 byte key)
Symmetric key type for AES-192 (24 byte key)
Symmetric key type for AES-256 (32 byte key)
ECC Weierstrass Prime key type.
ECC Montgomery key type.
EDDSA key type.
ECC NIST P-192.
ECC NIST P-224.
ECC NIST P-256.
ECC Ed25519 key for EdDSA.
ECC X25519 key for ECDH.
Symmetric key type for ChaCha20.
ECC NIST P-384.
ECC NIST P-521.
ECC X448 key for ECDH.
ECC Ed448 key for EdDSA.
Key storage methods.
Key is stored encrypted in application memory.
Key is stored inside the SE, and will persist until system reset or explicitly deleted.
Key is one of the pre-defined keys (pre-loaded or write-once) available in the SE.
List of available internal SE key slots.
Internal volatile slot 1.
Internal volatile slot 2.
Internal volatile slot 3.
Minimum key slot value for internal keys.
Internal TrustZone root key.
Internal immutable application secure debug key.
Internal immutable application AES-128 key (bootloader key)
Internal immutable application secure boot key.
Internal immutable application attestation key.
Internal immutable SE attestation key.
Size overhead for wrapped keys.
Typedef Documentation#
sl_se_key_type_t#
typedef uint32_t sl_se_key_type_t
Supported key types.
213 of file platform/security/sl_component/se_manager/inc/sl_se_manager_types.hsl_se_storage_method_t#
typedef uint32_t sl_se_storage_method_t
Key storage method.
Can have one of SL_SE_KEY_STORAGE_EXTERNAL_PLAINTEXT, SL_SE_KEY_STORAGE_EXTERNAL_WRAPPED, SL_SE_KEY_STORAGE_INTERNAL_VOLATILE or SL_SE_KEY_STORAGE_INTERNAL_IMMUTABLE.
219 of file platform/security/sl_component/se_manager/inc/sl_se_manager_types.hsl_se_key_slot_t#
typedef uint32_t sl_se_key_slot_t
Internal SE key slot.
222 of file platform/security/sl_component/se_manager/inc/sl_se_manager_types.hFunction Documentation#
sl_se_validate_key#
sl_status_t sl_se_validate_key (const sl_se_key_descriptor_t * key)
Validate key descriptor.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| const sl_se_key_descriptor_t * | [in] | key | The key to validate. |
Takes a key descriptor and checks if all required properties have been set for the specific key type.
Returns
Status code, sl_status.h.
80 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_handling.hsl_se_generate_key#
sl_status_t sl_se_generate_key (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key_out)
Generate a random key adhering to the given key descriptor.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_se_command_context_t * | [in] | cmd_ctx | Pointer to an SE command context object. |
| const sl_se_key_descriptor_t * | [in] | key_out | Description of the key to generate. Sets key parameters and describes the storage location for the key. |
The SE takes a key descriptor and generates a key with the given properties in the location specified by the descriptor.
If the key size is not aligned to a multiple of words the key representation is padded in front of the key.
Returns
Status code, sl_status.h.
103 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_handling.hsl_se_import_key#
sl_status_t sl_se_import_key (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key_in, const sl_se_key_descriptor_t * key_out)
Import a key using the SE.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_se_command_context_t * | [in] | cmd_ctx | Pointer to an SE command context object. |
| const sl_se_key_descriptor_t * | [in] | key_in | A plaintext key. |
| const sl_se_key_descriptor_t * | [in] | key_out | Either a volatile or a wrapped key with similar properties as key_in. |
Protect a key using the SE. Import a plaintext key and store it either in a volatile slot or as a wrapped key.
Returns
Status code, sl_status.h.
126 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_handling.hsl_se_export_key#
sl_status_t sl_se_export_key (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key_in, const sl_se_key_descriptor_t * key_out)
Export a volatile or wrapped key back to plaintext.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_se_command_context_t * | [in] | cmd_ctx | Pointer to an SE command context object. |
| const sl_se_key_descriptor_t * | [in] | key_in | Either a volatile or a wrapped key with similar properties as key_out. |
| const sl_se_key_descriptor_t * | [in] | key_out | The exported key in plaintext. |
Attempt to have the SE export a volatile or wrapped key back to plaintext if allowed.
Returns
Status code, sl_status.h. SL_STATUS_INVALID_PARAMETER if key does not exist.
151 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_handling.hsl_se_transfer_key#
sl_status_t sl_se_transfer_key (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key_in, const sl_se_key_descriptor_t * key_out)
Transfer a volatile or wrapped key to another protected storage.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_se_command_context_t * | [in] | cmd_ctx | Pointer to an SE command context object. |
| const sl_se_key_descriptor_t * | [in] | key_in | Either a volatile or a wrapped key with similar properties as key_out. |
| const sl_se_key_descriptor_t * | [in] | key_out | Either a volatile or a wrapped key with similar properties as key_in. |
Attempt to have the SE transfer a volatile or wrapped key if allowed.
Note
The key stored in the source protected storage will not be deleted.
Transferring a key between the same volatile slot is not allowed.
Returns
Status code, sl_status.h. SL_STATUS_INVALID_PARAMETER if key does not exist.
180 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_handling.hsl_se_export_public_key#
sl_status_t sl_se_export_public_key (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key_in, const sl_se_key_descriptor_t * key_out)
Export the public part of an ECC keypair.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_se_command_context_t * | [in] | cmd_ctx | Pointer to an SE command context object. |
| const sl_se_key_descriptor_t * | [in] | key_in | An asymmetric key with either a private or public part. |
| const sl_se_key_descriptor_t * | [out] | key_out | Describes output key parameters. Should only be set to contain the public part of the key. |
The output key must be specified to only contain a public key.
Returns
Status code, sl_status.h.
204 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_handling.hsl_se_delete_key#
sl_status_t sl_se_delete_key (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key)
Delete a key from a volatile SE storage slot.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| sl_se_command_context_t * | [in] | cmd_ctx | Pointer to an SE command context object. |
| const sl_se_key_descriptor_t * | [in] | key | Key to delete. |
The given key will be removed from the SE. The key descriptor is not modified and can be used to generate a new key without any updates.
Returns
Status code, sl_status.h.
225 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_handling.hsl_se_get_storage_size#
sl_status_t sl_se_get_storage_size (const sl_se_key_descriptor_t * key, uint32_t * storage_size)
Returns the required storage size for the given key.
| Type | Direction | Argument Name | Description |
|---|---|---|---|
| const sl_se_key_descriptor_t * | [in] | key | The sl_se_key_descriptor_t to find the required storage size for. |
| uint32_t * | [out] | storage_size | The required storage size in bytes. |
Finds the total storage size required for a given key. This includes storage for the public and private part of asymmetric keys, as well as overhead for wrapping keys.
Returns
Status code, sl_status.h.
246 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_handling.h