Zephyr API Documentation 4.5.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
TLS credentials on-device key generation

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

Topics

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

Macros

#define TLS_CREDENTIAL_KEYGEN_PUBKEY_MAX_SIZE   120
 Maximum size of the public key in SubjectPublicKeyInfo DER format, for a P-384 key.
#define TLS_CREDENTIAL_KEYGEN_CSR_SIZE(subject_len)
 Buffer size that fits a DER CSR of any supported key type.

Enumerations

enum  tls_credential_keygen_type { TLS_CREDENTIAL_KEYGEN_ECDSA_SECP256R1 , TLS_CREDENTIAL_KEYGEN_ECDSA_SECP384R1 }
 Type of the generated key pair. More...

Functions

int tls_credential_keygen_generate (sec_tag_t tag, enum tls_credential_keygen_type type)
 Generate a device private key for a security tag.
int tls_credential_keygen_delete (sec_tag_t tag)
 Delete the device private key of a security tag.
int tls_credential_keygen_key_id_get (sec_tag_t tag, psa_key_id_t *key_id)
 Get the PSA key ID of the device private key of a security tag.
int tls_credential_keygen_csr (sec_tag_t tag, const char *subject, uint8_t *out, size_t out_size, size_t *out_len)
 Generate a Certificate Signing Request (CSR) for the device private key.
int tls_credential_keygen_pubkey_get (sec_tag_t tag, uint8_t *out, size_t out_size, size_t *out_len)
 Export the public key of the device key pair.

Detailed Description

TLS credentials on-device key generation.

Since
4.6
Version
0.1.0

Macro Definition Documentation

◆ TLS_CREDENTIAL_KEYGEN_CSR_SIZE

#define TLS_CREDENTIAL_KEYGEN_CSR_SIZE ( subject_len)

#include <zephyr/net/tls_credentials_keygen.h>

Value:
(256 + 6 * (subject_len))

Buffer size that fits a DER CSR of any supported key type.

Parameters
subject_lenLength of the subject name string, without the NUL terminator.

◆ TLS_CREDENTIAL_KEYGEN_PUBKEY_MAX_SIZE

#define TLS_CREDENTIAL_KEYGEN_PUBKEY_MAX_SIZE   120

#include <zephyr/net/tls_credentials_keygen.h>

Maximum size of the public key in SubjectPublicKeyInfo DER format, for a P-384 key.

Enumeration Type Documentation

◆ tls_credential_keygen_type

#include <zephyr/net/tls_credentials_keygen.h>

Type of the generated key pair.

Enumerator
TLS_CREDENTIAL_KEYGEN_ECDSA_SECP256R1 

ECDSA key on the secp256r1 (P-256) curve.

TLS_CREDENTIAL_KEYGEN_ECDSA_SECP384R1 

ECDSA key on the secp384r1 (P-384) curve.

Function Documentation

◆ tls_credential_keygen_csr()

int tls_credential_keygen_csr ( sec_tag_t tag,
const char * subject,
uint8_t * out,
size_t out_size,
size_t * out_len )

#include <zephyr/net/tls_credentials_keygen.h>

Generate a Certificate Signing Request (CSR) for the device private key.

The CSR is a PKCS#10 request in DER format, signed by the device key through PSA. The hash of the signature follows the curve of the key: SHA-256 for P-256 and SHA-384 for P-384.

Parameters
tagSecurity tag of the key that signs the CSR.
subjectX.509 subject name, for example "CN=my-device,O=Nordic".
outBuffer for the DER-encoded CSR.
out_sizeSize of out in bytes. TLS_CREDENTIAL_KEYGEN_CSR_SIZE gives a size that always fits.
out_lenNumber of bytes written to out.
Return values
0On success.
-EINVALInvalid argument or subject name.
-EFBIGout is too small.
-ENOENTNo key exists for the security tag.
-EPERMThe registered key was not generated by this library.
-ENOTSUPThe key type is not supported.
-EIOPSA or Mbed TLS operation failed.

◆ tls_credential_keygen_delete()

int tls_credential_keygen_delete ( sec_tag_t tag)

#include <zephyr/net/tls_credentials_keygen.h>

Delete the device private key of a security tag.

Destroys the PSA key and removes the registration with the TLS credentials module. The other credentials of the security tag, for example the device certificate, are kept.

Note
A TLS socket that is open keeps the key ID, so its next handshake fails.
Parameters
tagSecurity tag the key is registered for.
Return values
0On success.
-ENOENTThe security tag has no generated key.
-EPERMThe registered key was not generated by this library.
-EIOPSA operation failed. The registration is kept, so the call can be repeated.
Returns
Other negative errno from tls_credential_delete, or from reading the TLS credentials. If the registration cannot be removed, the key is already destroyed, and the call can be repeated.

◆ tls_credential_keygen_generate()

int tls_credential_keygen_generate ( sec_tag_t tag,
enum tls_credential_keygen_type type )

#include <zephyr/net/tls_credentials_keygen.h>

Generate a device private key for a security tag.

Creates a persistent, non-exportable key pair in PSA key storage and registers it with the TLS credentials module as TLS_CREDENTIAL_PRIVATE_KEY_PSA. The private key never leaves the device. The key store gives the location and the PSA key ID of the key, see TLS credentials on-device key generation key store. The default key store allocates the key ID from the range reserved for this library, see ZEPHYR_PSA_TLS_CREDENTIALS_KEYGEN_KEY_ID_RANGE_BEGIN in zephyr/psa/key_ids.h.

Delete the key with tls_credential_keygen_delete. A key whose registration is removed with tls_credential_delete is not destroyed, and its key ID is not used again.

Note
Do not add a TLS_CREDENTIAL_PRIVATE_KEY for the same security tag afterwards. A TLS socket cannot use two private keys for one security tag.
Parameters
tagSecurity tag the key is registered for.
typeType of the key pair.
Return values
0On success.
-EINVALInvalid key type.
-EEXISTThe security tag already has a private key.
-ENOSPCNo free key ID in the key store.
-ENOTSUPThe key type is not enabled, or the key store does not support it.
-EIOPSA operation failed.
Returns
Other negative errno from tls_credential_add, or from reading the TLS credentials.

◆ tls_credential_keygen_key_id_get()

int tls_credential_keygen_key_id_get ( sec_tag_t tag,
psa_key_id_t * key_id )

#include <zephyr/net/tls_credentials_keygen.h>

Get the PSA key ID of the device private key of a security tag.

Use it to sign with the key outside of TLS, for example a JSON Web Token. The key ID is valid only until the key is deleted. A key generated later can get the same key ID.

Parameters
tagSecurity tag the key is registered for.
key_idPSA key ID of the key.
Return values
0On success.
-EINVALkey_id is NULL.
-ENOENTNo key exists for the security tag.
-EPERMThe registered key was not generated by this library.
-EIOPSA initialization failed.

◆ tls_credential_keygen_pubkey_get()

int tls_credential_keygen_pubkey_get ( sec_tag_t tag,
uint8_t * out,
size_t out_size,
size_t * out_len )

#include <zephyr/net/tls_credentials_keygen.h>

Export the public key of the device key pair.

The key is exported as a SubjectPublicKeyInfo structure in DER format, which also names the curve. It is 91 bytes for P-256 and 120 bytes for P-384. Host tools can compare it with the SubjectPublicKeyInfo of the installed device certificate.

Parameters
tagSecurity tag of the key.
outBuffer for the public key.
out_sizeSize of out in bytes. TLS_CREDENTIAL_KEYGEN_PUBKEY_MAX_SIZE always fits.
out_lenNumber of bytes written to out.
Return values
0On success.
-EINVALInvalid argument.
-EFBIGout is too small.
-ENOENTNo key exists for the security tag.
-EPERMThe registered key was not generated by this library.
-EIOPSA or Mbed TLS operation failed.