|
Zephyr API Documentation 4.5.99
A Scalable Open Source RTOS
|
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. | |
TLS credentials on-device key generation.
| #define TLS_CREDENTIAL_KEYGEN_CSR_SIZE | ( | subject_len | ) |
#include <zephyr/net/tls_credentials_keygen.h>
Buffer size that fits a DER CSR of any supported key type.
| subject_len | Length of the subject name string, without the NUL terminator. |
| #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.
#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. |
| 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.
| tag | Security tag of the key that signs the CSR. |
| subject | X.509 subject name, for example "CN=my-device,O=Nordic". |
| out | Buffer for the DER-encoded CSR. |
| out_size | Size of out in bytes. TLS_CREDENTIAL_KEYGEN_CSR_SIZE gives a size that always fits. |
| out_len | Number of bytes written to out. |
| 0 | On success. |
| -EINVAL | Invalid argument or subject name. |
| -EFBIG | out is too small. |
| -ENOENT | No key exists for the security tag. |
| -EPERM | The registered key was not generated by this library. |
| -ENOTSUP | The key type is not supported. |
| -EIO | PSA or Mbed TLS operation failed. |
| 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.
| tag | Security tag the key is registered for. |
| 0 | On success. |
| -ENOENT | The security tag has no generated key. |
| -EPERM | The registered key was not generated by this library. |
| -EIO | PSA operation failed. The registration is kept, so the call can be repeated. |
| 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.
| tag | Security tag the key is registered for. |
| type | Type of the key pair. |
| 0 | On success. |
| -EINVAL | Invalid key type. |
| -EEXIST | The security tag already has a private key. |
| -ENOSPC | No free key ID in the key store. |
| -ENOTSUP | The key type is not enabled, or the key store does not support it. |
| -EIO | PSA operation failed. |
| 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.
| tag | Security tag the key is registered for. |
| key_id | PSA key ID of the key. |
| 0 | On success. |
| -EINVAL | key_id is NULL. |
| -ENOENT | No key exists for the security tag. |
| -EPERM | The registered key was not generated by this library. |
| -EIO | PSA initialization failed. |
| 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.
| tag | Security tag of the key. |
| out | Buffer for the public key. |
| out_size | Size of out in bytes. TLS_CREDENTIAL_KEYGEN_PUBKEY_MAX_SIZE always fits. |
| out_len | Number of bytes written to out. |
| 0 | On success. |
| -EINVAL | Invalid argument. |
| -EFBIG | out is too small. |
| -ENOENT | No key exists for the security tag. |
| -EPERM | The registered key was not generated by this library. |
| -EIO | PSA or Mbed TLS operation failed. |