Key handling
Secure Element Manager

Description

Secure Element 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.

Data Structures

struct sl_se_buffer_t
Describes where the key is or should be stored.
struct sl_se_key_storage_t
Describes the storage location of keys.
struct sl_se_key_descriptor_t
Contains a full description of a key used by an SE command.
struct sl_se_custom_weierstrass_prime_domain_t
Custom Weierstrass curve structure.

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_ASYMMMETRIC_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_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_P192 ( SL_SE_KEY_TYPE_ECC_WEIERSTRASS_PRIME_CUSTOM | (0x18))
ECC NIST P-192.
#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_CHACHA20 0x00000020
Symmetric key type for ChaCha20.
#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_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_X25519 ( SL_SE_KEY_TYPE_ECC_MONTGOMERY | (0x20))
ECC X25519 key for ECDH.
#define SL_SE_KEY_TYPE_ECC_X448 ( SL_SE_KEY_TYPE_ECC_MONTGOMERY | (0x38))
ECC X448 key for ECDH.
#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_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.

Typedefs

typedef uint32_t sl_se_key_type_t
Supported key types.
typedef uint32_t sl_se_storage_method_t
Key storage method.
typedef uint32_t sl_se_key_slot_t
Internal SE key slot.

Function Documentation

◆ sl_se_validate_key()

sl_status_t sl_se_validate_key ( const sl_se_key_descriptor_t * key )

Validate key descriptor.

Takes a key descriptor and checks if all required properties have been set for the specific key type.

Parameters
[in] key The key to validate.
Returns
Status code, sl_status.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.

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.

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.
Returns
Status code, sl_status.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.

Protect a key using the SE. Import a plaintext key and store it either in a volatile slot or as a wrapped key.

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.
Returns
Status code, sl_status.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.

Attempt to have the SE export a volatile or wrapped key back to plaintext if allowed.

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.
Returns
Status code, sl_status.h. SL_STATUS_INVALID_PARAMETER if key does not exist.

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

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.

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.
Returns
Status code, sl_status.h. SL_STATUS_INVALID_PARAMETER if key does not exist.

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

The output key must be specified to only contain a public key.

Parameters
[in] cmd_ctx Pointer to an SE command context object.
[in] key_in An asymmetric key with either a private or public part.
[in] key_out Describes output key parameters. Should only be set to contain the public part of the key.
Returns
Status code, sl_status.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.

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.

Parameters
[in] cmd_ctx Pointer to an SE command context object.
[in] key Key to delete.
Returns
Status code, sl_status.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.

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.

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.
Returns
Status code, sl_status.h.

Macro Definition Documentation

◆ SL_SE_KEY_FLAG_ASYMMMETRIC_SIGNING_ONLY

#define SL_SE_KEY_FLAG_ASYMMMETRIC_SIGNING_ONLY   (1UL << 10)

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

◆ SL_SE_KEY_FLAG_ASYMMETRIC_USES_CUSTOM_DOMAIN

#define SL_SE_KEY_FLAG_ASYMMETRIC_USES_CUSTOM_DOMAIN   (1UL << 12)

Described key belongs to a custom ECC domain.

◆ SL_SE_KEY_FLAG_ASYMMETRIC_BUFFER_HAS_PUBLIC_KEY

#define SL_SE_KEY_FLAG_ASYMMETRIC_BUFFER_HAS_PUBLIC_KEY   (1UL << 13)

Storage buffer contains public part of an asymmetric key.

◆ SL_SE_KEY_FLAG_ASYMMETRIC_BUFFER_HAS_PRIVATE_KEY

#define SL_SE_KEY_FLAG_ASYMMETRIC_BUFFER_HAS_PRIVATE_KEY   (1UL << 14)

Storage buffer contains private part of an asymmetric key.

◆ SL_SE_KEY_FLAG_ALLOW_ANY_ACCESS

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

◆ SL_SE_KEY_FLAG_NON_EXPORTABLE

#define SL_SE_KEY_FLAG_NON_EXPORTABLE   (1UL << 24)

Do not allow exporting the key to plaintext.

◆ SL_SE_KEY_FLAG_IS_DEVICE_GENERATED

#define SL_SE_KEY_FLAG_IS_DEVICE_GENERATED   (1UL << 25)

Indicate that the key has been generated by this device.

This flag is only valid when using the SE to generate a key and makes it non-exportable.

◆ SL_SE_KEY_FLAG_IS_RESTRICTED

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

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

This flag is only valid when using the SE to generate a key and makes it non-exportable.

◆ SL_SE_KEY_TYPE_ALGORITHM_MASK

#define SL_SE_KEY_TYPE_ALGORITHM_MASK   0xf0000000

Mask for algorithm field in key type.

◆ SL_SE_KEY_TYPE_ALGORITHM_OFFSET

#define SL_SE_KEY_TYPE_ALGORITHM_OFFSET   28

Offset of algorithm field in key type.

◆ SL_SE_KEY_TYPE_ATTRIBUTES_MASK

#define SL_SE_KEY_TYPE_ATTRIBUTES_MASK   0x00007fff

Mask for attributes field in key type.

◆ SL_SE_KEY_TYPE_ATTRIBUTES_OFFSET

#define SL_SE_KEY_TYPE_ATTRIBUTES_OFFSET   0

Offset of attributes field in key type.

◆ SL_SE_KEY_TYPE_SYMMETRIC

#define SL_SE_KEY_TYPE_SYMMETRIC   0x00000000

Symmetric key type.

◆ SL_SE_KEY_TYPE_AES_128

#define SL_SE_KEY_TYPE_AES_128   0x00000010

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

◆ SL_SE_KEY_TYPE_AES_192

#define SL_SE_KEY_TYPE_AES_192   0x00000018

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

◆ SL_SE_KEY_TYPE_AES_256

#define SL_SE_KEY_TYPE_AES_256   0x00000020

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

◆ SL_SE_KEY_TYPE_ECC_WEIERSTRASS_PRIME_CUSTOM

#define SL_SE_KEY_TYPE_ECC_WEIERSTRASS_PRIME_CUSTOM   (0x8U << SL_SE_KEY_TYPE_ALGORITHM_OFFSET )

ECC Weierstrass Prime key type.

◆ SL_SE_KEY_TYPE_ECC_P192

#define SL_SE_KEY_TYPE_ECC_P192   ( SL_SE_KEY_TYPE_ECC_WEIERSTRASS_PRIME_CUSTOM | (0x18))

ECC NIST P-192.

◆ SL_SE_KEY_TYPE_ECC_P256

#define SL_SE_KEY_TYPE_ECC_P256   ( SL_SE_KEY_TYPE_ECC_WEIERSTRASS_PRIME_CUSTOM | (0x20))

ECC NIST P-256.

◆ SL_SE_KEY_TYPE_CHACHA20

#define SL_SE_KEY_TYPE_CHACHA20   0x00000020

Symmetric key type for ChaCha20.

◆ SL_SE_KEY_TYPE_ECC_MONTGOMERY

#define SL_SE_KEY_TYPE_ECC_MONTGOMERY   (0xbU << SL_SE_KEY_TYPE_ALGORITHM_OFFSET )

ECC Montgomery key type.

◆ SL_SE_KEY_TYPE_ECC_EDDSA

#define SL_SE_KEY_TYPE_ECC_EDDSA   (0xcU << SL_SE_KEY_TYPE_ALGORITHM_OFFSET )

EDDSA key type.

◆ SL_SE_KEY_TYPE_ECC_P384

#define SL_SE_KEY_TYPE_ECC_P384   ( SL_SE_KEY_TYPE_ECC_WEIERSTRASS_PRIME_CUSTOM | (0x30))

ECC NIST P-384.

◆ SL_SE_KEY_TYPE_ECC_P521

#define SL_SE_KEY_TYPE_ECC_P521   ( SL_SE_KEY_TYPE_ECC_WEIERSTRASS_PRIME_CUSTOM | (0x42))

ECC NIST P-521.

◆ SL_SE_KEY_TYPE_ECC_X25519

#define SL_SE_KEY_TYPE_ECC_X25519   ( SL_SE_KEY_TYPE_ECC_MONTGOMERY | (0x20))

ECC X25519 key for ECDH.

◆ SL_SE_KEY_TYPE_ECC_X448

#define SL_SE_KEY_TYPE_ECC_X448   ( SL_SE_KEY_TYPE_ECC_MONTGOMERY | (0x38))

ECC X448 key for ECDH.

◆ SL_SE_KEY_STORAGE_EXTERNAL_PLAINTEXT

#define SL_SE_KEY_STORAGE_EXTERNAL_PLAINTEXT   0x00

Key storage methods.

Key is stored in a plaintext buffer in application memory. Application can save its in-memory buffer to non-volatile memory as needed to provide key persistence.

◆ SL_SE_KEY_STORAGE_EXTERNAL_WRAPPED

#define SL_SE_KEY_STORAGE_EXTERNAL_WRAPPED   0x01

Key is stored encrypted in application memory.

This ensures the key in wrapped form is only usable on a specific device. If the key additionally needs to be prevented from ever being output as plaintext, also set the corresponding permission bit. Application can save its in-memory buffer to non-volatile memory as needed to provide key persistence. Keys stored in this way should use the flag SL_SE_KEY_FLAG_NON_EXPORTABLE unless there is a specific need to access the key value outside the SE.

◆ SL_SE_KEY_STORAGE_INTERNAL_VOLATILE

#define SL_SE_KEY_STORAGE_INTERNAL_VOLATILE   0x02

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

Keys stored in this way should use the flag SL_SE_KEY_FLAG_NON_EXPORTABLE unless there is a specific need to access the key value outside the SE.

◆ SL_SE_KEY_STORAGE_INTERNAL_IMMUTABLE

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

See documentation for a list of available keys.

◆ SL_SE_KEY_SLOT_VOLATILE_0

#define SL_SE_KEY_SLOT_VOLATILE_0   0x00

List of available internal SE key slots.

Internal volatile slot 0

◆ SL_SE_KEY_SLOT_VOLATILE_1

#define SL_SE_KEY_SLOT_VOLATILE_1   0x01

Internal volatile slot 1.

◆ SL_SE_KEY_SLOT_VOLATILE_2

#define SL_SE_KEY_SLOT_VOLATILE_2   0x02

Internal volatile slot 2.

◆ SL_SE_KEY_SLOT_VOLATILE_3

#define SL_SE_KEY_SLOT_VOLATILE_3   0x03

Internal volatile slot 3.

◆ SL_SE_KEY_SLOT_APPLICATION_SECURE_DEBUG_KEY

#define SL_SE_KEY_SLOT_APPLICATION_SECURE_DEBUG_KEY   0xF8

Internal immutable application secure debug key.

◆ SL_SE_KEY_SLOT_APPLICATION_AES_128_KEY

#define SL_SE_KEY_SLOT_APPLICATION_AES_128_KEY   0xFA

Internal immutable application AES-128 key (bootloader key)

◆ SL_SE_KEY_SLOT_APPLICATION_SECURE_BOOT_KEY

#define SL_SE_KEY_SLOT_APPLICATION_SECURE_BOOT_KEY   0xFC

Internal immutable application secure boot key.

◆ SL_SE_KEY_SLOT_APPLICATION_ATTESTATION_KEY

#define SL_SE_KEY_SLOT_APPLICATION_ATTESTATION_KEY   0xFE

Internal immutable application attestation key.

Typedef Documentation

◆ sl_se_key_type_t

typedef uint32_t sl_se_key_type_t

Supported key types.

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

◆ sl_se_key_slot_t

typedef uint32_t sl_se_key_slot_t

Internal SE key slot.