If you need urgent consulting help click here

BSD Sockets

Overview

Zephyr offers an implementation of a subset of the BSD Sockets API (a part of the POSIX standard). This API allows to reuse existing programming experience and port existing simple networking applications to Zephyr.

Here are the key requirements and concepts which governed BSD Sockets compatible API implementation for Zephyr:

  • Has minimal overhead, similar to the requirement for other Zephyr subsystems.

  • Is namespaced by default, to avoid name conflicts with well-known names like close(), which may be part of libc or other POSIX compatibility libraries. If enabled by CONFIG_NET_SOCKETS_POSIX_NAMES, it will also expose native POSIX names.

BSD Sockets compatible API is enabled using CONFIG_NET_SOCKETS config option and implements the following operations: socket(), close(), recv(), recvfrom(), send(), sendto(), connect(), bind(), listen(), accept(), fcntl() (to set non-blocking mode), getsockopt(), setsockopt(), poll(), select(), getaddrinfo(), getnameinfo().

Based on the namespacing requirements above, these operations are by default exposed as functions with zsock_ prefix, e.g. zsock_socket() and zsock_close(). If the config option CONFIG_NET_SOCKETS_POSIX_NAMES is defined, all the functions will be also exposed as aliases without the prefix. This includes the functions like close() and fcntl() (which may conflict with functions in libc or other libraries, for example, with the filesystem libraries).

Another entailment of the design requirements above is that the Zephyr API aggressively employs the short-read/short-write property of the POSIX API whenever possible (to minimize complexity and overheads). POSIX allows for calls like recv() and send() to actually process (receive or send) less data than requested by the user (on SOCK_STREAM type sockets). For example, a call recv(sock, 1000, 0) may return 100, meaning that only 100 bytes were read (short read), and the application needs to retry call(s) to receive the remaining 900 bytes.

The BSD Sockets API uses file descriptors to represent sockets. File descriptors are small integers, consecutively assigned from zero, shared among sockets, files, special devices (like stdin/stdout), etc. Internally, there is a table mapping file descriptors to internal object pointers. The file descriptor table is used by the BSD Sockets API even if the rest of the POSIX subsystem (filesystem, stdin/stdout) is not enabled.

Secure Sockets

Zephyr provides an extension of standard POSIX socket API, allowing to create and configure sockets with TLS protocol types, facilitating secure communication. Secure functions for the implementation are provided by mbedTLS library. Secure sockets implementation allows use of both TLS and DTLS protocols with standard socket calls. See net_ip_protocol_secure type for supported secure protocol versions.

To enable secure sockets, set the CONFIG_NET_SOCKETS_SOCKOPT_TLS option. To enable DTLS support, use CONFIG_NET_SOCKETS_ENABLE_DTLS option.

TLS credentials subsystem

TLS credentials must be registered in the system before they can be used with secure sockets. See tls_credential_add() for more information.

When a specific TLS credential is registered in the system, it is assigned with numeric value of type sec_tag_t, called a tag. This value can be used later on to reference the credential during secure socket configuration with socket options.

The following TLS credential types can be registered in the system:

  • TLS_CREDENTIAL_CA_CERTIFICATE

  • TLS_CREDENTIAL_SERVER_CERTIFICATE

  • TLS_CREDENTIAL_PRIVATE_KEY

  • TLS_CREDENTIAL_PSK

  • TLS_CREDENTIAL_PSK_ID

An example registration of CA certificate (provided in ca_certificate array) looks like this:

ret = tls_credential_add(CA_CERTIFICATE_TAG, TLS_CREDENTIAL_CA_CERTIFICATE,
                         ca_certificate, sizeof(ca_certificate));

By default certificates in DER format are supported. PEM support can be enabled in mbedTLS settings.

Secure Socket Creation

A secure socket can be created by specifying secure protocol type, for instance:

sock = socket(AF_INET, SOCK_STREAM, IPPROTO_TLS_1_2);

Once created, it can be configured with socket options. For instance, the CA certificate and hostname can be set:

sec_tag_t sec_tag_opt[] = {
        CA_CERTIFICATE_TAG,
};

ret = setsockopt(sock, SOL_TLS, TLS_SEC_TAG_LIST,
                 sec_tag_opt, sizeof(sec_tag_opt));
char host[] = "google.com";

ret = setsockopt(sock, SOL_TLS, TLS_HOSTNAME, host, sizeof(host) - 1);

Once configured, socket can be used just like a regular TCP socket.

Several samples in Zephyr use secure sockets for communication. For a sample use see e.g. echo-server sample application or HTTP GET sample application.

Secure Sockets options

Secure sockets offer the following options for socket management:

group secure_sockets_options

Defines

TLS_SEC_TAG_LIST

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_HOSTNAME

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_CIPHERSUITE_LIST

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

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_PEER_VERIFY

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_DTLS_ROLE

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_ALPN_LIST

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_DTLS_HANDSHAKE_TIMEOUT_MIN

Socket option to set DTLS 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_MAX
TLS_CERT_NOCOPY

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_NATIVE

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_SESSION_CACHE

Socket option to control TLS session caching on a socket. Accepted values:

  • 0 - Disabled.

  • 1 - Enabled.

TLS_SESSION_CACHE_PURGE

Write-only socket option to purge session cache immediately. This option accepts any value.

Socket offloading

Zephyr allows to register custom socket implementations (called offloaded sockets). This allows for seamless integration for devices which provide an external IP stack and expose socket-like API.

Socket offloading can be enabled with CONFIG_NET_SOCKETS_OFFLOAD option. A network driver that wants to register a new socket implementation should use NET_SOCKET_OFFLOAD_REGISTER macro. The macro accepts the following parameters:

  • socket_name - an arbitrary name for the socket implementation.

  • prio - socket implementation priority, the higher priority is, the earlier

    particular implementation is processed when creating a new socket. Lower numeric value indicate higher priority.

  • _family - socket family implemented by the offloaded socket. AF_UNSPEC

    indicate any family.

  • _is_supported - a filtering function, used to verify whether particular

    socket family, type and protocol are supported by the offloaded socket implementation.

  • _handler - a function compatible with socket() API, used to create

    an offloaded socket.

Every offloaded socket implementation should also implement a set of socket APIs, specified in socket_op_vtable struct.

The function registered for socket creation should allocate a new file descriptor using z_reserve_fd() function. Any additional actions, specific to the creation of a particular offloaded socket implementation should take place after the file descriptor is allocated. As a final step, if the offloaded socket was created successfully, the file descriptor should be finalized with z_finalize_fd() function. The finalize function allows to register a socket_op_vtable structure implementing socket APIs for an offloaded socket along with an optional socket context data pointer.

Finally, when an offloaded network interface is initialized, it should indicate that the interface is offloaded with net_if_socket_offload_set() function. The function registers the function used to create an offloaded socket (the same as the one provided in NET_SOCKET_OFFLOAD_REGISTER) at the network interface.

Offloaded socket creation

When application creates a new socket with socket() function, the network stack iterates over all registered socket implementations (native and offloaded). Higher priority socket implementations are processed first. For each registered socket implementation, an address family is verified, and if it matches (or the socket was registered as AF_UNSPEC), the corresponding _is_supported function is called to verify the remaining socket parameters. The first implementation that fulfills the socket requirements (i. e. _is_supported returns true) will create a new socket with its _handler function.

The above indicates the importance of the socket priority. If multiple socket implementations support the same set of socket family/type/protocol, the first implementation processed by the system will create a socket. Therefore it’s important to give the highest priority to the implementation that should be the system default.

The socket priority for native socket implementation is configured with Kconfig. Use CONFIG_NET_SOCKETS_TLS_PRIORITY to set the priority for the native TLS sockets. Use CONFIG_NET_SOCKETS_PRIORITY_DEFAULT to set the priority for the remaining native sockets.

Dealing with multiple offloaded interfaces

As the socket() function does not allow to specify which network interface should be used by a socket, it’s not possible to choose a specific implementation in case multiple offloaded socket implementations, supporting the same type of sockets, are available. The same problem arises when both native and offloaded sockets are available in the system.

To address this problem, a special socket implementation (called socket dispatcher) was introduced. The sole reason for this module is to postpone the socket creation for until the first operation on a socket is performed. This leaves an opening to use SO_BINDTODEVICE socket option, to bind a socket to a particular network interface (and thus offloaded socket implementation). The socket dispatcher can be enabled with CONFIG_NET_SOCKETS_OFFLOAD_DISPATCHER Kconfig option.

When enabled, the application can specify the network interface to use with setsockopt() function:

/* A "dispatcher" socket is created */
sock = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);

struct ifreq ifreq = {
   .ifr_name = "SimpleLink"
};

/* The socket is "dispatched" to a particular network interface
 * (offloaded or not).
 */
setsockopt(sock, SOL_SOCKET, SO_BINDTODEVICE, &ifreq, sizeof(ifreq));

Similarly, if TLS is supported by both native and offloaded sockets, TLS_NATIVE socket option can be used to indicate that a native TLS socket should be created. The underlying socket can then be bound to a particular network interface:

/* A "dispatcher" socket is created */
sock = socket(AF_INET, SOCK_STREAM, IPPROTO_TLS_1_2);

int tls_native = 1;

/* The socket is "dispatched" to a native TLS socket implmeentation.
 * The underlying socket is a "dispatcher" socket now.
 */
setsockopt(sock, SOL_TLS, TLS_NATIVE, &tls_native, sizeof(tls_native));

struct ifreq ifreq = {
   .ifr_name = "SimpleLink"
};

/* The underlying socket is "dispatched" to a particular network interface
 * (offloaded or not).
 */
setsockopt(sock, SOL_SOCKET, SO_BINDTODEVICE, &ifreq, sizeof(ifreq));

In case no SO_BINDTODEVICE socket option is used on a socket, the socket will be dispatched according to the default priority and filtering rules on a first socket API call.

API Reference

BSD Sockets

group bsd_sockets

BSD Sockets compatible API.

Defines

ZSOCK_POLLIN

zsock_poll: Poll for readability

ZSOCK_POLLPRI

zsock_poll: Compatibility value, ignored

ZSOCK_POLLOUT

zsock_poll: Poll for writability

ZSOCK_POLLERR

zsock_poll: Poll results in error condition (output value only)

ZSOCK_POLLHUP

zsock_poll: Poll detected closed connection (output value only)

ZSOCK_POLLNVAL

zsock_poll: Invalid socket (output value only)

ZSOCK_MSG_PEEK

zsock_recv: Read data without removing it from socket input queue

ZSOCK_MSG_TRUNC

zsock_recv: return the real length of the datagram, even when it was longer than the passed buffer

ZSOCK_MSG_DONTWAIT

zsock_recv/zsock_send: Override operation to non-blocking

ZSOCK_MSG_WAITALL

zsock_recv: block until the full amount of data can be returned

ZSOCK_SHUT_RD

zsock_shutdown: Shut down for reading

ZSOCK_SHUT_WR

zsock_shutdown: Shut down for writing

ZSOCK_SHUT_RDWR

zsock_shutdown: Shut down for both reading and writing

SOL_TLS

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

TLS_PEER_VERIFY_NONE

Peer verification disabled.

TLS_PEER_VERIFY_OPTIONAL

Peer verification optional.

TLS_PEER_VERIFY_REQUIRED

Peer verification required.

TLS_DTLS_ROLE_CLIENT

Client role in a DTLS session.

TLS_DTLS_ROLE_SERVER

Server role in a DTLS session.

TLS_CERT_NOCOPY_NONE

Cert duplicated in heap

TLS_CERT_NOCOPY_OPTIONAL

Cert not copied in heap if DER

TLS_SESSION_CACHE_DISABLED

Disable TLS session caching.

TLS_SESSION_CACHE_ENABLED

Enable TLS session caching.

AI_PASSIVE

Address for bind() (vs for connect())

AI_CANONNAME

Fill in ai_canonname

AI_NUMERICHOST

Assume host address is in numeric notation, don’t DNS lookup

AI_V4MAPPED

May return IPv4 mapped address for IPv6

AI_ALL

May return both native IPv6 and mapped IPv4 address for IPv6

AI_ADDRCONFIG

IPv4/IPv6 support depends on local system config

AI_NUMERICSERV

Assume service (port) is numeric

NI_NUMERICHOST

zsock_getnameinfo(): Resolve to numeric address.

NI_NUMERICSERV

zsock_getnameinfo(): Resolve to numeric port number.

NI_NOFQDN

zsock_getnameinfo(): Return only hostname instead of FQDN

NI_NAMEREQD

zsock_getnameinfo(): Dummy option for compatibility

NI_DGRAM

zsock_getnameinfo(): Dummy option for compatibility

NI_MAXHOST

zsock_getnameinfo(): Max supported hostname length

IFNAMSIZ
SOL_SOCKET

sockopt: Socket-level option

SO_DEBUG

sockopt: Recording debugging information (ignored, for compatibility)

SO_REUSEADDR

sockopt: address reuse (ignored, for compatibility)

SO_TYPE

sockopt: Type of the socket

SO_ERROR

sockopt: Async error (ignored, for compatibility)

SO_DONTROUTE

sockopt: Bypass normal routing and send directly to host (ignored, for compatibility)

SO_BROADCAST

sockopt: Transmission of broadcast messages is supported (ignored, for compatibility)

SO_SNDBUF

sockopt: Size of socket socket send buffer (ignored, for compatibility)

SO_RCVBUF

sockopt: Size of socket recv buffer

SO_KEEPALIVE

sockopt: Enable sending keep-alive messages on connections (ignored, for compatibility)

SO_OOBINLINE

sockopt: Place out-of-band data into receive stream (ignored, for compatibility)

SO_REUSEPORT

sockopt: Allow multiple sockets to reuse a single port (ignored, for compatibility)

SO_RCVTIMEO

sockopt: Receive timeout Applies to receive functions like recv(), but not to connect()

SO_SNDTIMEO

sockopt: Send timeout

SO_BINDTODEVICE

sockopt: Bind a socket to an interface

SO_ACCEPTCONN

sockopt: Socket accepts incoming connections (ignored, for compatibility)

SO_TIMESTAMPING

sockopt: Timestamp TX packets

SO_PROTOCOL

sockopt: Protocol used with the socket

SO_DOMAIN

sockopt: Domain used with SOCKET (ignored, for compatibility)

TCP_NODELAY

End Socket options for SOL_SOCKET level sockopt: Disable TCP buffering (ignored, for compatibility)

IPV6_V6ONLY

sockopt: Don’t support IPv4 access (ignored, for compatibility)

SO_PRIORITY

sockopt: Socket priority

SO_TXTIME

sockopt: Socket TX time (when the data should be sent)

SCM_TXTIME
SO_SOCKS5

sockopt: Enable SOCKS5 for Socket

ZSOCK_FD_SETSIZE

Number of file descriptors which can be added to zsock_fd_set

zsock_timeval

Typedefs

typedef struct zsock_fd_set zsock_fd_set

Functions

void *zsock_get_context_object(int sock)

Obtain a file descriptor’s associated net context.

With CONFIG_USERSPACE enabled, the kernel’s object permission system must apply to socket file descriptors. When a socket is opened, by default only the caller has permission, access by other threads will fail unless they have been specifically granted permission.

This is achieved by tagging data structure definitions that implement the underlying object associated with a network socket file descriptor with ‘__net_socket`. All pointers to instances of these will be known to the kernel as kernel objects with type K_OBJ_NET_SOCKET.

This API is intended for threads that need to grant access to the object associated with a particular file descriptor to another thread. The returned pointer represents the underlying K_OBJ_NET_SOCKET and may be passed to APIs like k_object_access_grant().

In a system like Linux which has the notion of threads running in processes in a shared virtual address space, this sort of management is unnecessary as the scope of file descriptors is implemented at the process level.

However in Zephyr the file descriptor scope is global, and MPU-based systems are not able to implement a process-like model due to the lack of memory virtualization hardware. They use discrete object permissions and memory domains instead to define thread access scope.

User threads will have no direct access to the returned object and will fault if they try to access its memory; the pointer can only be used to make permission assignment calls, which follow exactly the rules for other kernel objects like device drivers and IPC.

Parameters
  • sock – file descriptor

Returns

pointer to associated network socket object, or NULL if the file descriptor wasn’t valid or the caller had no access permission

int zsock_socket(int family, int type, int proto)

Create a network socket.

See POSIX.1-2017 article for normative description. This function is also exposed as socket() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

If CONFIG_USERSPACE is enabled, the caller will be granted access to the context object associated with the returned file descriptor.

int zsock_socketpair(int family, int type, int proto, int *sv)

Create an unnamed pair of connected sockets.

See POSIX.1-2017 article for normative description. This function is also exposed as socketpair() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

int zsock_close(int sock)

Close a network socket.

Close a network socket. This function is also exposed as close() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined (in which case it may conflict with generic POSIX close() function).

int zsock_shutdown(int sock, int how)

Shutdown socket send/receive operations.

See POSIX.1-2017 article for normative description, but currently this function has no effect in Zephyr and provided solely for compatibility with existing code. This function is also exposed as shutdown() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

int zsock_bind(int sock, const struct sockaddr *addr, socklen_t addrlen)

Bind a socket to a local network address.

See POSIX.1-2017 article for normative description. This function is also exposed as bind() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

int zsock_connect(int sock, const struct sockaddr *addr, socklen_t addrlen)

Connect a socket to a peer network address.

See POSIX.1-2017 article for normative description. This function is also exposed as connect() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

int zsock_listen(int sock, int backlog)

Set up a STREAM socket to accept peer connections.

See POSIX.1-2017 article for normative description. This function is also exposed as listen() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

int zsock_accept(int sock, struct sockaddr *addr, socklen_t *addrlen)

Accept a connection on listening socket.

See POSIX.1-2017 article for normative description. This function is also exposed as accept() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

ssize_t zsock_sendto(int sock, const void *buf, size_t len, int flags, const struct sockaddr *dest_addr, socklen_t addrlen)

Send data to an arbitrary network address.

See POSIX.1-2017 article for normative description. This function is also exposed as sendto() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

static inline ssize_t zsock_send(int sock, const void *buf, size_t len, int flags)

Send data to a connected peer.

See POSIX.1-2017 article for normative description. This function is also exposed as send() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

ssize_t zsock_sendmsg(int sock, const struct msghdr *msg, int flags)

Send data to an arbitrary network address.

See POSIX.1-2017 article for normative description. This function is also exposed as sendmsg() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

ssize_t zsock_recvfrom(int sock, void *buf, size_t max_len, int flags, struct sockaddr *src_addr, socklen_t *addrlen)

Receive data from an arbitrary network address.

See POSIX.1-2017 article for normative description. This function is also exposed as recvfrom() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

static inline ssize_t zsock_recv(int sock, void *buf, size_t max_len, int flags)

Receive data from a connected peer.

See POSIX.1-2017 article for normative description. This function is also exposed as recv() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

int zsock_fcntl(int sock, int cmd, int flags)

Control blocking/non-blocking mode of a socket.

This functions allow to (only) configure a socket for blocking or non-blocking operation (O_NONBLOCK). This function is also exposed as fcntl() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined (in which case it may conflict with generic POSIX fcntl() function).

int zsock_poll(struct zsock_pollfd *fds, int nfds, int timeout)

Efficiently poll multiple sockets for events.

See POSIX.1-2017 article for normative description. (In Zephyr this function works only with sockets, not arbitrary file descriptors.) This function is also exposed as poll() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined (in which case it may conflict with generic POSIX poll() function).

int zsock_getsockopt(int sock, int level, int optname, void *optval, socklen_t *optlen)

Get various socket options.

See POSIX.1-2017 article for normative description. In Zephyr this function supports a subset of socket options described by POSIX, but also some additional options available in Linux (some options are dummy and provided to ease porting of existing code). This function is also exposed as getsockopt() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

int zsock_setsockopt(int sock, int level, int optname, const void *optval, socklen_t optlen)

Set various socket options.

See POSIX.1-2017 article for normative description. In Zephyr this function supports a subset of socket options described by POSIX, but also some additional options available in Linux (some options are dummy and provided to ease porting of existing code). This function is also exposed as setsockopt() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

int zsock_getpeername(int sock, struct sockaddr *addr, socklen_t *addrlen)

Get peer name.

See POSIX.1-2017 article for normative description. This function is also exposed as getpeername() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

int zsock_getsockname(int sock, struct sockaddr *addr, socklen_t *addrlen)

Get socket name.

See POSIX.1-2017 article for normative description. This function is also exposed as getsockname() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

int zsock_gethostname(char *buf, size_t len)

Get local host name.

See POSIX.1-2017 article for normative description. This function is also exposed as gethostname() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

static inline char *zsock_inet_ntop(sa_family_t family, const void *src, char *dst, size_t size)

Convert network address from internal to numeric ASCII form.

See POSIX.1-2017 article for normative description. This function is also exposed as inet_ntop() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

int zsock_inet_pton(sa_family_t family, const char *src, void *dst)

Convert network address from numeric ASCII form to internal representation.

See POSIX.1-2017 article for normative description. This function is also exposed as inet_pton() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

int zsock_getaddrinfo(const char *host, const char *service, const struct zsock_addrinfo *hints, struct zsock_addrinfo **res)

Resolve a domain name to one or more network addresses.

See POSIX.1-2017 article for normative description. This function is also exposed as getaddrinfo() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

void zsock_freeaddrinfo(struct zsock_addrinfo *ai)

Free results returned by zsock_getaddrinfo()

See POSIX.1-2017 article for normative description. This function is also exposed as freeaddrinfo() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

const char *zsock_gai_strerror(int errcode)

Convert zsock_getaddrinfo() error code to textual message.

See POSIX.1-2017 article for normative description. This function is also exposed as gai_strerror() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

int zsock_getnameinfo(const struct sockaddr *addr, socklen_t addrlen, char *host, socklen_t hostlen, char *serv, socklen_t servlen, int flags)

Resolve a network address to a domain name or ASCII address.

See POSIX.1-2017 article for normative description. This function is also exposed as getnameinfo() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

int zsock_select(int nfds, zsock_fd_set *readfds, zsock_fd_set *writefds, zsock_fd_set *exceptfds, struct zsock_timeval *timeout)

Legacy function to poll multiple sockets for events.

See POSIX.1-2017 article for normative description. This function is provided to ease porting of existing code and not recommended for usage due to its inefficiency, use zsock_poll() instead. In Zephyr this function works only with sockets, not arbitrary file descriptors. This function is also exposed as select() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined (in which case it may conflict with generic POSIX select() function).

void ZSOCK_FD_ZERO(zsock_fd_set *set)

Initialize (clear) fd_set.

See POSIX.1-2017 article for normative description. This function is also exposed as FD_ZERO() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

int ZSOCK_FD_ISSET(int fd, zsock_fd_set *set)

Check whether socket is a member of fd_set.

See POSIX.1-2017 article for normative description. This function is also exposed as FD_ISSET() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

void ZSOCK_FD_CLR(int fd, zsock_fd_set *set)

Remove socket from fd_set.

See POSIX.1-2017 article for normative description. This function is also exposed as FD_CLR() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

void ZSOCK_FD_SET(int fd, zsock_fd_set *set)

Add socket to fd_set.

See POSIX.1-2017 article for normative description. This function is also exposed as FD_SET() if CONFIG_NET_SOCKETS_POSIX_NAMES is defined.

struct zsock_pollfd
#include <socket.h>
struct zsock_addrinfo
#include <socket.h>
struct ifreq
#include <socket.h>

Interface description structure

struct zsock_fd_set
#include <socket_select.h>

TLS Credentials

group tls_credentials

TLS credentials management.

Typedefs

typedef int sec_tag_t

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_SERVER_CERTIFICATE with TLS_CREDENTIAL_PRIVATE_KEY,

  • TLS_CREDENTIAL_PSK with TLS_CREDENTIAL_PSK_ID. Such pairs of credentials must be assigned the same secure tag to be correctly handled in the system.

Enums

enum tls_credential_type

TLS credential types

Values:

enumerator TLS_CREDENTIAL_NONE

Unspecified credential.

enumerator TLS_CREDENTIAL_CA_CERTIFICATE

A trusted CA certificate. Use this to authenticate remote servers. Used with certificate-based ciphersuites.

enumerator TLS_CREDENTIAL_SERVER_CERTIFICATE

A public server certificate. Use this to register your own server certificate. Should be registered together with a corresponding private key. Used with certificate-based ciphersuites.

enumerator TLS_CREDENTIAL_PRIVATE_KEY

Private key. Should be registered together with a corresponding public certificate. Used with certificate-based ciphersuites.

enumerator TLS_CREDENTIAL_PSK

Pre-shared key. Should be registered together with a corresponding PSK identity. Used with PSK-based ciphersuites.

enumerator TLS_CREDENTIAL_PSK_ID

Pre-shared key identity. Should be registered together with a corresponding PSK. Used with PSK-based ciphersuites.

Functions

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

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.

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.

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

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.

int tls_credential_delete(sec_tag_t tag, enum tls_credential_type type)

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.