Key handling#

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.

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.

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.

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.

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.

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.

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.

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.

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.

Returns

• Status code, sl_status.h.

SL_SE_KEY_FLAG_ASYMMETRIC_SIGNING_ONLY#

#define SL_SE_KEY_FLAG_ASYMMETRIC_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_ASYMMMETRIC_SIGNING_ONLY#

#define SL_SE_KEY_FLAG_ASYMMMETRIC_SIGNING_ONLY

  (SL_SE_KEY_FLAG_ASYMMETRIC_SIGNING_ONLY)

Old definition. Retained for backwards compatibility.

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_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_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_P224#

#define SL_SE_KEY_TYPE_ECC_P224

(SL_SE_KEY_TYPE_ECC_WEIERSTRASS_PRIME_CUSTOM | (0x1C))

ECC NIST P-224.

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

#define SL_SE_KEY_TYPE_ECC_ED25519

(SL_SE_KEY_TYPE_ECC_EDDSA | (0x20))

ECC Ed25519 key for EdDSA.

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

#define SL_SE_KEY_TYPE_CHACHA20

0x00000020

Symmetric key type for ChaCha20.

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

#define SL_SE_KEY_TYPE_ECC_X448

(SL_SE_KEY_TYPE_ECC_MONTGOMERY | (0x38))

ECC X448 key for ECDH.

SL_SE_KEY_TYPE_ECC_ED448#

#define SL_SE_KEY_TYPE_ECC_ED448

(SL_SE_KEY_TYPE_ECC_EDDSA | (0x38))

ECC Ed448 key for EdDSA.

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

#define SL_SE_KEY_SLOT_INTERNAL_MIN

0xF7

Minimum key slot value for internal keys.

SL_SE_KEY_SLOT_TRUSTZONE_ROOT_KEY#

#define SL_SE_KEY_SLOT_TRUSTZONE_ROOT_KEY

0xF7

Internal TrustZone root key.

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.

SL_SE_KEY_SLOT_SE_ATTESTATION_KEY#

#define SL_SE_KEY_SLOT_SE_ATTESTATION_KEY

0xFF

Internal immutable SE attestation key.

SLI_SE_WRAPPED_KEY_OVERHEAD#

#define SLI_SE_WRAPPED_KEY_OVERHEAD

(12 + 16)

Size overhead for wrapped keys.