TLS credentials management

TLS credentials management. More...

Macros
#define	SEC_TAG_TLS_INVALID   (-1)
	Invalid secure tag value.

Typedefs
typedef int	sec_tag_t
	Secure tag, a reference to TLS credential.

Enumerations
enum	tls_credential_type {   TLS_CREDENTIAL_NONE , TLS_CREDENTIAL_CA_CERTIFICATE , TLS_CREDENTIAL_PUBLIC_CERTIFICATE , TLS_CREDENTIAL_PRIVATE_KEY ,   TLS_CREDENTIAL_PSK , TLS_CREDENTIAL_PSK_ID , TLS_CREDENTIAL_PRIVATE_KEY_PSA , TLS_CREDENTIAL_PSK_PSA }
	TLS credential types. More...

Functions
int	tls_credential_add (sec_tag_t tag, enum tls_credential_type type, const void *cred, size_t credlen)
	Add a TLS credential.
int	tls_credential_get (sec_tag_t tag, enum tls_credential_type type, void *cred, size_t *credlen)
	Get a TLS credential.
int	tls_credential_delete (sec_tag_t tag, enum tls_credential_type type)
	Delete a TLS credential.
int	tls_credential_expiry (sec_tag_t tag, enum tls_credential_type type, time_t *expiry)
	Get the expiry time of a TLS credential.

Detailed Description

TLS credentials management.

Since

1.13

Version

0.8.0

Macro Definition Documentation

SEC_TAG_TLS_INVALID

#define SEC_TAG_TLS_INVALID   (-1)

#include <zephyr/net/tls_credentials.h>

Invalid secure tag value.

Typedef Documentation

sec_tag_t

typedef int sec_tag_t

#include <zephyr/net/tls_credentials.h>

Secure tag, a reference to TLS credential.

Secure tag can be used to reference credential after it was registered in the system.

Note

Some TLS credentials come in pairs:

• TLS_CREDENTIAL_PUBLIC_CERTIFICATE with TLS_CREDENTIAL_PRIVATE_KEY,
• TLS_CREDENTIAL_PSK with TLS_CREDENTIAL_PSK_ID. Such pairs of credentials should generally be assigned the same secure tag when used with subsystems that support fetching multiple credentials per tag, such as TLS sockets. However, note that certain subsystems or implementations may expect only one credential per secure tag.

Negative values are reserved for internal use.

Enumeration Type Documentation

tls_credential_type

enum tls_credential_type

#include <zephyr/net/tls_credentials.h>

TLS credential types.

Enumerator
TLS_CREDENTIAL_NONE	Unspecified credential.
TLS_CREDENTIAL_CA_CERTIFICATE	A trusted CA certificate. Use this to authenticate remote servers. Used with certificate-based ciphersuites.
TLS_CREDENTIAL_PUBLIC_CERTIFICATE	A public client or server certificate. Use this to register your own certificate. Should be registered together with a corresponding private key. Used with certificate-based ciphersuites.
TLS_CREDENTIAL_PRIVATE_KEY	Private key. Should be registered together with a corresponding public certificate. Used with certificate-based ciphersuites.
TLS_CREDENTIAL_PSK	Pre-shared key. Should be registered together with a corresponding PSK identity. Used with PSK-based ciphersuites.
TLS_CREDENTIAL_PSK_ID	Pre-shared key identity. Should be registered together with a corresponding PSK. Used with PSK-based ciphersuites.
TLS_CREDENTIAL_PRIVATE_KEY_PSA	Private key resident in PSA. The credential buffer holds a psa_key_id_t referencing a key already present in PSA (for example one generated on-device with psa_generate_key()), not the key material itself. The key never leaves PSA: handshake signatures are performed through psa_sign_hash(). Should be registered together with a corresponding public certificate, in place of TLS_CREDENTIAL_PRIVATE_KEY.
TLS_CREDENTIAL_PSK_PSA	Pre-shared key resident in PSA. It should be registered together with a corresponding PSK identity (TLS_CREDENTIAL_PSK_ID) and it should be used with PSK-based ciphersuites. The credential buffer holds a psa_key_id_t referencing a key already present in PSA. Key material never leaves PSA.

Function Documentation

tls_credential_add()

int tls_credential_add	(	sec_tag_t	tag,
		enum tls_credential_type	type,
		const void *	cred,
		size_t	credlen )

#include <zephyr/net/tls_credentials.h>

Add a TLS credential.

This function adds a TLS credential, that can be used by TLS/DTLS for authentication.

Parameters

tag	A security tag that credential will be referenced with.
type	A TLS/DTLS credential type.
cred	A TLS/DTLS credential.
credlen	A TLS/DTLS credential length.

Note

With the volatile backend ( CONFIG_TLS_CREDENTIALS_BACKEND_VOLATILE), the credential data is not copied. Only the cred pointer is stored, so the buffer must stay valid and unchanged for as long as the tag is in use, that is, until the credential is removed with tls_credential_delete.

Return values

0	TLS credential successfully added.
-EACCES	Access to the TLS credential subsystem was denied.
-ENOMEM	Not enough memory to add new TLS credential.
-EEXIST	TLS credential of specific tag and type already exists.

tls_credential_delete()

int tls_credential_delete	(	sec_tag_t	tag,
		enum tls_credential_type	type )

#include <zephyr/net/tls_credentials.h>

Delete a TLS credential.

This function removes a TLS credential, referenced by tag secure tag of type.

Parameters

tag	A security tag corresponding to removed credential.
type	A TLS/DTLS credential type of removed credential.

Return values

0	TLS credential successfully deleted.
-EACCES	Access to the TLS credential subsystem was denied.
-ENOENT	Requested TLS credential was not found.

tls_credential_expiry()

int tls_credential_expiry	(	sec_tag_t	tag,
		enum tls_credential_type	type,
		time_t *	expiry )

#include <zephyr/net/tls_credentials.h>

Get the expiry time of a TLS credential.

Parameters

tag	The security tag of the TLS credential.
type	The type of the TLS credential.
expiry	Pointer to store the expiry time.

Return values

0	TLS credential expiry time successfully obtained.
-EACCES	Access to the TLS credential subsystem was denied.
-ENOENT	Requested TLS credential was not found.
-ENOTSUP	TLS credential storage does not support expiry time retrieval.

tls_credential_get()

int tls_credential_get	(	sec_tag_t	tag,
		enum tls_credential_type	type,
		void *	cred,
		size_t *	credlen )

#include <zephyr/net/tls_credentials.h>

Get a TLS credential.

This function gets an already registered TLS credential, referenced by tag secure tag of type.

Parameters

tag	A security tag of requested credential.
type	A TLS/DTLS credential type of requested credential.
cred	A buffer for TLS/DTLS credential.
credlen	A buffer size on input. TLS/DTLS credential length on output.

Return values

0	TLS credential successfully obtained.
-EACCES	Access to the TLS credential subsystem was denied.
-ENOENT	Requested TLS credential was not found.
-EFBIG	Requested TLS credential does not fit in the buffer provided. Check *credlen for size required.