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_buffer_t

sl_se_key_storage_t

sl_se_key_descriptor_t

sl_se_custom_weierstrass_prime_domain_t

Typedefs#

typedef uint32_t

Supported key types.

typedef uint32_t

Key storage method.

typedef uint32_t

Internal SE key slot.

Functions#

sl_status_t
sl_se_validate_key(const sl_se_key_descriptor_t *key)

Validate key descriptor.

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.

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.

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.

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.

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.

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.

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.

Macros#

#define
SL_SE_KEY_FLAG_ASYMMETRIC_SIGNING_ONLY (1UL << 10)

Asymmetric key can only be used for signing (not key exchange)

#define
SL_SE_KEY_FLAG_ASYMMETRIC_USES_CUSTOM_DOMAIN (1UL << 12)

Described key belongs to a custom ECC domain.

#define
SL_SE_KEY_FLAG_ASYMMETRIC_BUFFER_HAS_PUBLIC_KEY (1UL << 13)

Storage buffer contains public part of an asymmetric key.

#define
SL_SE_KEY_FLAG_ASYMMETRIC_BUFFER_HAS_PRIVATE_KEY (1UL << 14)

Storage buffer contains private part of an asymmetric key.

#define
SL_SE_KEY_FLAG_ALLOW_ANY_ACCESS (1UL << 15)

Allow usage of this key by other bus masters or TrustZone levels than the one which created/imported the key.

#define
SL_SE_KEY_FLAG_ASYMMMETRIC_SIGNING_ONLY (SL_SE_KEY_FLAG_ASYMMETRIC_SIGNING_ONLY)

Old definition. Retained for backwards compatibility.

#define
SL_SE_KEY_FLAG_NON_EXPORTABLE (1UL << 24)

Do not allow exporting the key to plaintext.

#define
SL_SE_KEY_FLAG_IS_DEVICE_GENERATED (1UL << 25)

Indicate that the key has been generated by this device.

#define
SL_SE_KEY_FLAG_IS_RESTRICTED (1UL << 25 | 1UL << 24)

Indicate that the key can only be used to sign SE generated content.

#define
SL_SE_KEY_TYPE_ALGORITHM_MASK 0xf0000000

Mask for algorithm field in key type.

#define
SL_SE_KEY_TYPE_ALGORITHM_OFFSET 28

Offset of algorithm field in key type.

#define
SL_SE_KEY_TYPE_ATTRIBUTES_MASK 0x00007fff

Mask for attributes field in key type.

#define
SL_SE_KEY_TYPE_ATTRIBUTES_OFFSET 0

Offset of attributes field in key type.

#define
SL_SE_KEY_TYPE_SYMMETRIC 0x00000000

Symmetric key type.

#define
SL_SE_KEY_TYPE_AES_128 0x00000010

Symmetric key type for AES-128 (16 byte key)

#define
SL_SE_KEY_TYPE_AES_192 0x00000018

Symmetric key type for AES-192 (24 byte key)

#define
SL_SE_KEY_TYPE_AES_256 0x00000020

Symmetric key type for AES-256 (32 byte key)

#define
SL_SE_KEY_TYPE_ECC_WEIERSTRASS_PRIME_CUSTOM (0x8U << SL_SE_KEY_TYPE_ALGORITHM_OFFSET)

ECC Weierstrass Prime key type.

#define
SL_SE_KEY_TYPE_ECC_MONTGOMERY (0xbU << SL_SE_KEY_TYPE_ALGORITHM_OFFSET)

ECC Montgomery key type.

#define
SL_SE_KEY_TYPE_ECC_EDDSA (0xcU << SL_SE_KEY_TYPE_ALGORITHM_OFFSET)

EDDSA key type.

#define
SL_SE_KEY_TYPE_ECC_P192 (SL_SE_KEY_TYPE_ECC_WEIERSTRASS_PRIME_CUSTOM | (0x18))

ECC NIST P-192.

#define
SL_SE_KEY_TYPE_ECC_P224 (SL_SE_KEY_TYPE_ECC_WEIERSTRASS_PRIME_CUSTOM | (0x1C))

ECC NIST P-224.

#define
SL_SE_KEY_TYPE_ECC_P256 (SL_SE_KEY_TYPE_ECC_WEIERSTRASS_PRIME_CUSTOM | (0x20))

ECC NIST P-256.

#define
SL_SE_KEY_TYPE_ECC_ED25519 (SL_SE_KEY_TYPE_ECC_EDDSA | (0x20))

ECC Ed25519 key for EdDSA.

#define
SL_SE_KEY_TYPE_ECC_X25519 (SL_SE_KEY_TYPE_ECC_MONTGOMERY | (0x20))

ECC X25519 key for ECDH.

#define
SL_SE_KEY_TYPE_CHACHA20 0x00000020

Symmetric key type for ChaCha20.

#define
SL_SE_KEY_TYPE_ECC_P384 (SL_SE_KEY_TYPE_ECC_WEIERSTRASS_PRIME_CUSTOM | (0x30))

ECC NIST P-384.

#define
SL_SE_KEY_TYPE_ECC_P521 (SL_SE_KEY_TYPE_ECC_WEIERSTRASS_PRIME_CUSTOM | (0x42))

ECC NIST P-521.

#define
SL_SE_KEY_TYPE_ECC_X448 (SL_SE_KEY_TYPE_ECC_MONTGOMERY | (0x38))

ECC X448 key for ECDH.

#define
SL_SE_KEY_TYPE_ECC_ED448 (SL_SE_KEY_TYPE_ECC_EDDSA | (0x38))

ECC Ed448 key for EdDSA.

#define
SL_SE_KEY_STORAGE_EXTERNAL_PLAINTEXT 0x00

Key storage methods.

#define
SL_SE_KEY_STORAGE_EXTERNAL_WRAPPED 0x01

Key is stored encrypted in application memory.

#define
SL_SE_KEY_STORAGE_INTERNAL_VOLATILE 0x02

Key is stored inside the SE, and will persist until system reset or explicitly deleted.

#define
SL_SE_KEY_STORAGE_INTERNAL_IMMUTABLE 0x03

Key is one of the pre-defined keys (pre-loaded or write-once) available in the SE.

#define
SL_SE_KEY_SLOT_VOLATILE_0 0x00

List of available internal SE key slots.

#define
SL_SE_KEY_SLOT_VOLATILE_1 0x01

Internal volatile slot 1.

#define
SL_SE_KEY_SLOT_VOLATILE_2 0x02

Internal volatile slot 2.

#define
SL_SE_KEY_SLOT_VOLATILE_3 0x03

Internal volatile slot 3.

#define
SL_SE_KEY_SLOT_INTERNAL_MIN 0xF7

Minimum key slot value for internal keys.

#define
SL_SE_KEY_SLOT_TRUSTZONE_ROOT_KEY 0xF7

Internal TrustZone root key.

#define
SL_SE_KEY_SLOT_APPLICATION_SECURE_DEBUG_KEY 0xF8

Internal immutable application secure debug key.

#define
SL_SE_KEY_SLOT_APPLICATION_AES_128_KEY 0xFA

Internal immutable application AES-128 key (bootloader key)

#define
SL_SE_KEY_SLOT_APPLICATION_SECURE_BOOT_KEY 0xFC

Internal immutable application secure boot key.

#define
SL_SE_KEY_SLOT_APPLICATION_ATTESTATION_KEY 0xFE

Internal immutable application attestation key.

#define
SL_SE_KEY_SLOT_SE_ATTESTATION_KEY 0xFF

Internal immutable SE attestation key.

#define
SLI_SE_WRAPPED_KEY_OVERHEAD (12 + 16)

Size overhead for wrapped keys.

Typedef Documentation#

sl_se_key_type_t#

typedef uint32_t sl_se_key_type_t

Supported key types.


Definition at line 213 of file platform/security/sl_component/se_manager/inc/sl_se_manager_types.h

sl_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.


Definition at line 219 of file platform/security/sl_component/se_manager/inc/sl_se_manager_types.h

sl_se_key_slot_t#

typedef uint32_t sl_se_key_slot_t

Internal SE key slot.


Definition at line 222 of file platform/security/sl_component/se_manager/inc/sl_se_manager_types.h

Function Documentation#

sl_se_validate_key#

sl_status_t sl_se_validate_key (const sl_se_key_descriptor_t * key)

Validate key descriptor.

Parameters
[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.


Definition at line 80 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_handling.h

sl_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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[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.


Definition at line 103 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_handling.h

sl_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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key_in

A plaintext key.

[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.


Definition at line 126 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_handling.h

sl_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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key_in

Either a volatile or a wrapped key with similar properties as key_out.

[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.


Definition at line 151 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_handling.h

sl_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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key_in

Either a volatile or a wrapped key with similar properties as key_out.

[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.


Definition at line 180 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_handling.h

sl_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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key_in

An asymmetric key with either a private or public part.

[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.


Definition at line 204 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_handling.h

sl_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.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[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.


Definition at line 225 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_handling.h

sl_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.

Parameters
[in]key

The sl_se_key_descriptor_t to find the required storage size for.

[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.


Definition at line 246 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_handling.h