Socket options for TLS

Socket options for TLS
#define	SOL_TLS   282
	Protocol level for TLS.
#define	TLS_SEC_TAG_LIST   1
	Socket option to select TLS credentials to use.
#define	TLS_HOSTNAME   2
	Write-only socket option to set hostname.
#define	TLS_CIPHERSUITE_LIST   3
	Socket option to select ciphersuites to use.
#define	TLS_CIPHERSUITE_USED   4
	Read-only socket option to read a ciphersuite chosen during TLS handshake.
#define	TLS_PEER_VERIFY   5
	Write-only socket option to set peer verification level for TLS connection.
#define	TLS_DTLS_ROLE   6
	Write-only socket option to set role for DTLS connection.
#define	TLS_ALPN_LIST   7
	Socket option for setting the supported Application Layer Protocols.
#define	TLS_DTLS_HANDSHAKE_TIMEOUT_MIN   8
	Socket option to set DTLS min handshake timeout.
#define	TLS_DTLS_HANDSHAKE_TIMEOUT_MAX   9
	Socket option to set DTLS max handshake timeout.
#define	TLS_CERT_NOCOPY   10
	Socket option for preventing certificates from being copied to the mbedTLS heap if possible.
#define	TLS_NATIVE   11
	TLS socket option to use with offloading.
#define	TLS_SESSION_CACHE   12
	Socket option to control TLS session caching on a socket.
#define	TLS_SESSION_CACHE_PURGE   13
	Write-only socket option to purge session cache immediately.
#define	TLS_DTLS_CID   14
	Write-only socket option to control DTLS CID.
#define	TLS_DTLS_CID_STATUS   15
	Read-only socket option to get DTLS CID status.
#define	TLS_DTLS_CID_VALUE   16
	Socket option to set or get the value of the DTLS connection ID to be used for the DTLS session.
#define	TLS_DTLS_PEER_CID_VALUE   17
	Read-only socket option to get the value of the DTLS connection ID received from the peer.
#define	TLS_DTLS_HANDSHAKE_ON_CONNECT   18
	Socket option to configure DTLS socket behavior on connect().
#define	TLS_PEER_VERIFY_NONE   0
	Peer verification disabled.
#define	TLS_PEER_VERIFY_OPTIONAL   1
	Peer verification optional.
#define	TLS_PEER_VERIFY_REQUIRED   2
	Peer verification required.
#define	TLS_DTLS_ROLE_CLIENT   0
	Client role in a DTLS session.
#define	TLS_DTLS_ROLE_SERVER   1
	Server role in a DTLS session.
#define	TLS_CERT_NOCOPY_NONE   0
	Cert duplicated in heap.
#define	TLS_CERT_NOCOPY_OPTIONAL   1
	Cert not copied in heap if DER.
#define	TLS_SESSION_CACHE_DISABLED   0
	Disable TLS session caching.
#define	TLS_SESSION_CACHE_ENABLED   1
	Enable TLS session caching.
#define	TLS_DTLS_CID_DISABLED   0
	CID is disabled
#define	TLS_DTLS_CID_SUPPORTED   1
	CID is supported.
#define	TLS_DTLS_CID_ENABLED   2
	CID is enabled
#define	TLS_DTLS_CID_STATUS_DISABLED   0
	CID is disabled.
#define	TLS_DTLS_CID_STATUS_DOWNLINK   1
	CID is in use by us.
#define	TLS_DTLS_CID_STATUS_UPLINK   2
	CID is in use by peer.
#define	TLS_DTLS_CID_STATUS_BIDIRECTIONAL   3
	CID is in use by us and peer.

Detailed Description

Macro Definition Documentation

SOL_TLS

#define SOL_TLS   282

#include <zephyr/net/socket.h>

Protocol level for TLS.

Here, the same socket protocol level for TLS as in Linux was used.

TLS_ALPN_LIST

#define TLS_ALPN_LIST   7

#include <zephyr/net/socket.h>

Socket option for setting the supported Application Layer Protocols.

It accepts and returns a const char array of NULL terminated strings representing the supported application layer protocols listed during the TLS handshake.

TLS_CERT_NOCOPY

#define TLS_CERT_NOCOPY   10

#include <zephyr/net/socket.h>

Socket option for preventing certificates from being copied to the mbedTLS heap if possible.

The option is only effective for DER certificates and is ignored for PEM certificates.

TLS_CERT_NOCOPY_NONE

#define TLS_CERT_NOCOPY_NONE   0

#include <zephyr/net/socket.h>

Cert duplicated in heap.

TLS_CERT_NOCOPY_OPTIONAL

#define TLS_CERT_NOCOPY_OPTIONAL   1

#include <zephyr/net/socket.h>

Cert not copied in heap if DER.

TLS_CIPHERSUITE_LIST

#define TLS_CIPHERSUITE_LIST   3

#include <zephyr/net/socket.h>

Socket option to select ciphersuites to use.

It accepts and returns an array of integers with IANA assigned ciphersuite identifiers. If not set, socket will allow all ciphersuites available in the system (mbedTLS default behavior).

TLS_CIPHERSUITE_USED

#define TLS_CIPHERSUITE_USED   4

#include <zephyr/net/socket.h>

Read-only socket option to read a ciphersuite chosen during TLS handshake.

It returns an integer containing an IANA assigned ciphersuite identifier of chosen ciphersuite.

TLS_DTLS_CID

#define TLS_DTLS_CID   14

#include <zephyr/net/socket.h>

Write-only socket option to control DTLS CID.

The option accepts an integer, indicating the setting. Accepted vaules for the option are: 0, 1 and 2. Effective when set before connecting to the socket.

• 0 - DTLS CID will be disabled.
• 1 - DTLS CID will be enabled, and a 0 length CID value to be sent to the peer.
• 2 - DTLS CID will be enabled, and the most recent value set with TLS_DTLS_CID_VALUE will be sent to the peer. Otherwise, a random value will be used.

TLS_DTLS_CID_DISABLED

#define TLS_DTLS_CID_DISABLED   0

#include <zephyr/net/socket.h>

CID is disabled

TLS_DTLS_CID_ENABLED

#define TLS_DTLS_CID_ENABLED   2

#include <zephyr/net/socket.h>

CID is enabled

TLS_DTLS_CID_STATUS

#define TLS_DTLS_CID_STATUS   15

#include <zephyr/net/socket.h>

Read-only socket option to get DTLS CID status.

The option accepts a pointer to an integer, indicating the setting upon return. Returned vaules for the option are:

• 0 - DTLS CID is disabled.
• 1 - DTLS CID is received on the downlink.
• 2 - DTLS CID is sent to the uplink.
• 3 - DTLS CID is used in both directions.

TLS_DTLS_CID_STATUS_BIDIRECTIONAL

#define TLS_DTLS_CID_STATUS_BIDIRECTIONAL   3

#include <zephyr/net/socket.h>

CID is in use by us and peer.

TLS_DTLS_CID_STATUS_DISABLED

#define TLS_DTLS_CID_STATUS_DISABLED   0

#include <zephyr/net/socket.h>

CID is disabled.

TLS_DTLS_CID_STATUS_DOWNLINK

#define TLS_DTLS_CID_STATUS_DOWNLINK   1

#include <zephyr/net/socket.h>

CID is in use by us.

TLS_DTLS_CID_STATUS_UPLINK

#define TLS_DTLS_CID_STATUS_UPLINK   2

#include <zephyr/net/socket.h>

CID is in use by peer.

TLS_DTLS_CID_SUPPORTED

#define TLS_DTLS_CID_SUPPORTED   1

#include <zephyr/net/socket.h>

CID is supported.

TLS_DTLS_CID_VALUE

#define TLS_DTLS_CID_VALUE   16

#include <zephyr/net/socket.h>

Socket option to set or get the value of the DTLS connection ID to be used for the DTLS session.

The option accepts a byte array, holding the CID value.

TLS_DTLS_HANDSHAKE_ON_CONNECT

#define TLS_DTLS_HANDSHAKE_ON_CONNECT   18

#include <zephyr/net/socket.h>

Socket option to configure DTLS socket behavior on connect().

If set, DTLS connect() will execute the handshake with the configured peer. This is the default behavior. Otherwise, DTLS connect() will only configure peer address (as with regular UDP socket) and will not attempt to execute DTLS handshake. The handshake will take place in consecutive send()/recv() call.

TLS_DTLS_HANDSHAKE_TIMEOUT_MAX

#define TLS_DTLS_HANDSHAKE_TIMEOUT_MAX   9

#include <zephyr/net/socket.h>

Socket option to set DTLS max handshake timeout.

The timeout starts at min, and upon retransmission the timeout is doubled util max is reached. Min and max arguments are separate options. The time unit is ms.

TLS_DTLS_HANDSHAKE_TIMEOUT_MIN

#define TLS_DTLS_HANDSHAKE_TIMEOUT_MIN   8

#include <zephyr/net/socket.h>

Socket option to set DTLS min handshake timeout.

The timeout starts at min, and upon retransmission the timeout is doubled util max is reached. Min and max arguments are separate options. The time unit is ms.

TLS_DTLS_PEER_CID_VALUE

#define TLS_DTLS_PEER_CID_VALUE   17

#include <zephyr/net/socket.h>

Read-only socket option to get the value of the DTLS connection ID received from the peer.

The option accepts a pointer to a byte array, holding the CID value upon return. The optlen returned will be 0 if the peer did not provide a connection ID, otherwise will contain the length of the CID value.

TLS_DTLS_ROLE

#define TLS_DTLS_ROLE   6

#include <zephyr/net/socket.h>

Write-only socket option to set role for DTLS connection.

This option is irrelevant for TLS connections, as for them role is selected based on connect()/listen() usage. By default, DTLS will assume client role. This option accepts an integer with a TLS role, compatible with mbedTLS values:

• 0 - client
• 1 - server

TLS_DTLS_ROLE_CLIENT

#define TLS_DTLS_ROLE_CLIENT   0

#include <zephyr/net/socket.h>

Client role in a DTLS session.

TLS_DTLS_ROLE_SERVER

#define TLS_DTLS_ROLE_SERVER   1

#include <zephyr/net/socket.h>

Server role in a DTLS session.

TLS_HOSTNAME

#define TLS_HOSTNAME   2

#include <zephyr/net/socket.h>

Write-only socket option to set hostname.

It accepts a string containing the hostname (may be NULL to disable hostname verification). By default, hostname check is enforced for TLS clients.

TLS_NATIVE

#define TLS_NATIVE   11

#include <zephyr/net/socket.h>

TLS socket option to use with offloading.

The option instructs the network stack only to offload underlying TCP/UDP communication. The TLS/DTLS operation is handled by a native TLS/DTLS socket implementation from Zephyr.

Note, that this option is only applicable if socket dispatcher is used (CONFIG_NET_SOCKETS_OFFLOAD_DISPATCHER is enabled). In such case, it should be the first socket option set on a newly created socket. After that, the application may use SO_BINDTODEVICE to choose the dedicated network interface for the underlying TCP/UDP socket.

TLS_PEER_VERIFY

#define TLS_PEER_VERIFY   5

#include <zephyr/net/socket.h>

Write-only socket option to set peer verification level for TLS connection.

This option accepts an integer with a peer verification level, compatible with mbedTLS values:

• 0 - none
• 1 - optional
• 2 - required

If not set, socket will use mbedTLS defaults (none for servers, required for clients).

TLS_PEER_VERIFY_NONE

#define TLS_PEER_VERIFY_NONE   0

#include <zephyr/net/socket.h>

Peer verification disabled.

TLS_PEER_VERIFY_OPTIONAL

#define TLS_PEER_VERIFY_OPTIONAL   1

#include <zephyr/net/socket.h>

Peer verification optional.

TLS_PEER_VERIFY_REQUIRED

#define TLS_PEER_VERIFY_REQUIRED   2

#include <zephyr/net/socket.h>

Peer verification required.

TLS_SEC_TAG_LIST

#define TLS_SEC_TAG_LIST   1

#include <zephyr/net/socket.h>

Socket option to select TLS credentials to use.

It accepts and returns an array of sec_tag_t that indicate which TLS credentials should be used with specific socket.

TLS_SESSION_CACHE

#define TLS_SESSION_CACHE   12

#include <zephyr/net/socket.h>

Socket option to control TLS session caching on a socket.

Accepted values:

• 0 - Disabled.
• 1 - Enabled.

TLS_SESSION_CACHE_DISABLED

#define TLS_SESSION_CACHE_DISABLED   0

#include <zephyr/net/socket.h>

Disable TLS session caching.

TLS_SESSION_CACHE_ENABLED

#define TLS_SESSION_CACHE_ENABLED   1

#include <zephyr/net/socket.h>

Enable TLS session caching.

TLS_SESSION_CACHE_PURGE

#define TLS_SESSION_CACHE_PURGE   13

#include <zephyr/net/socket.h>

Write-only socket option to purge session cache immediately.

This option accepts any value.