Zephyr API Documentation 4.5.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

TLS credentials on-device key generation key store. More...

Functions

int tls_credential_keygen_store_attr_set (enum tls_credential_keygen_type type, psa_key_attributes_t *attr)
 Set the lifetime of a key that is generated.
int tls_credential_keygen_store_id_alloc (sec_tag_t tag, enum tls_credential_keygen_type type, const psa_key_id_t *used, size_t used_count, psa_key_id_t *key_id)
 Allocate a key ID for a key that is generated.
int tls_credential_keygen_store_id_pick (size_t count, psa_key_id_t(*key_id_at)(size_t index), const psa_key_id_t *used, size_t used_count, psa_key_id_t *key_id)
 Pick a free key ID for a key store.
bool tls_credential_keygen_store_id_is_own (psa_key_id_t key_id)
 Check whether a key ID belongs to the key store.

Detailed Description

TLS credentials on-device key generation key store.

Since
4.6
Version
0.1.0

The key store decides where the generated keys are stored and which PSA key IDs they get. With CONFIG_TLS_CREDENTIALS_KEYGEN_KEY_STORE_DEFAULT, the keys are persistent keys in the default PSA key location, with key IDs from the range that zephyr/psa/key_ids.h reserves. With CONFIG_TLS_CREDENTIALS_KEYGEN_KEY_STORE_CUSTOM, the application or the vendor implements the functions below, for example to store the keys in a hardware key location.

The functions are called with the TLS credentials locked.

The keys of one key store do not belong to another key store. Delete the keys with tls_credential_keygen_delete before the key store is changed. After a change, remove the registration of an earlier key with tls_credential_delete, and destroy the key with psa_destroy_key().

Function Documentation

◆ tls_credential_keygen_store_attr_set()

int tls_credential_keygen_store_attr_set ( enum tls_credential_keygen_type type,
psa_key_attributes_t * attr )

#include <zephyr/net/tls_credentials_keygen_store.h>

Set the lifetime of a key that is generated.

The type, size, algorithm and usage of the key are already set. The key store sets only the lifetime, which also gives the location of the key. It must not change the other attributes, because TLS, the CSR and other users of the key need them. If the key location cannot store such a key, the key store returns -ENOTSUP.

Parameters
typeType of the key pair.
attrAttributes of the key.
Return values
0On success.
-ENOTSUPThe key store does not support the key type.

◆ tls_credential_keygen_store_id_alloc()

int tls_credential_keygen_store_id_alloc ( sec_tag_t tag,
enum tls_credential_keygen_type type,
const psa_key_id_t * used,
size_t used_count,
psa_key_id_t * key_id )

#include <zephyr/net/tls_credentials_keygen_store.h>

Allocate a key ID for a key that is generated.

A key with an ID of the key store that is not in used is left over, for example after its registration was removed with tls_credential_delete. The key store must not destroy it, because it cannot be recovered, and must not allocate its key ID. tls_credential_keygen_store_id_pick does that.

Parameters
tagSecurity tag the key is generated for.
typeType of the key pair.
usedKey IDs that security tags are registered for. Each of them belongs to the key store, see tls_credential_keygen_store_id_is_own.
used_countNumber of entries in used.
key_idAllocated key ID.
Return values
0On success.
-ENOSPCNo free key ID.

◆ tls_credential_keygen_store_id_is_own()

bool tls_credential_keygen_store_id_is_own ( psa_key_id_t key_id)

#include <zephyr/net/tls_credentials_keygen_store.h>

Check whether a key ID belongs to the key store.

The key generation only uses and deletes keys with an ID of the key store.

Parameters
key_idPSA key ID.
Return values
trueThe key ID belongs to the key store.
falseOtherwise.

◆ tls_credential_keygen_store_id_pick()

int tls_credential_keygen_store_id_pick ( size_t count,
psa_key_id_t(* key_id_at )(size_t index),
const psa_key_id_t * used,
size_t used_count,
psa_key_id_t * key_id )

#include <zephyr/net/tls_credentials_keygen_store.h>

Pick a free key ID for a key store.

Returns the first key ID of the key store that is not in used and that no key uses. A key that exists is never destroyed. A key store can call it from tls_credential_keygen_store_id_alloc.

Parameters
countNumber of key IDs of the key store.
key_id_atReturns the key ID with an index from 0 to count - 1.
usedKey IDs that security tags are registered for.
used_countNumber of entries in used.
key_idFree key ID.
Return values
0On success.
-ENOSPCNo free key ID.