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_POSIX_API, 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_POSIX_API 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.

See Echo server (advanced) and Echo client (advanced) sample applications to learn how to create a simple server or client BSD socket based application.

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));

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:

Related code samples

HTTP Client: Implement an HTTP(S) client that issues a variety of HTTP requests.
HTTP GET using plain sockets: Implement an HTTP(S) client using plain BSD sockets.

group secure_sockets_options

Socket options for TLS

SOL_TLS

Protocol level for TLS.

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

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 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_HANDSHAKE_TIMEOUT_MAX

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_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.

TLS_DTLS_CID

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_STATUS

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_VALUE

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_PEER_CID_VALUE

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_HANDSHAKE_ON_CONNECT

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_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.

TLS_DTLS_CID_DISABLED: CID is disabled

TLS_DTLS_CID_SUPPORTED: CID is supported.

TLS_DTLS_CID_ENABLED: CID is enabled

TLS_DTLS_CID_STATUS_DISABLED: CID is disabled.

TLS_DTLS_CID_STATUS_DOWNLINK: CID is in use by us.

TLS_DTLS_CID_STATUS_UPLINK: CID is in use by peer.

TLS_DTLS_CID_STATUS_BIDIRECTIONAL: CID is in use by us and peer.

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’s priority. The higher the priority, the earlier this particular implementation will be processed when creating a new socket. Lower numeric value indicates higher priority.

_family
Socket family implemented by the offloaded socket. AF_UNSPEC indicates any family.

_is_supported
A filtering function, used to verify whether a 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 

Related code samples

AWS IoT Core MQTT: Connect to AWS IoT Core and publish messages using MQTT.
Asynchronous echo server using poll(): Implement an asynchronous IPv4/IPv6 TCP echo server using BSD sockets and poll()
Asynchronous echo server using select(): Implement an asynchronous IPv4/IPv6 TCP echo server using BSD sockets and select()
Dumb HTTP server: Implement a simple, portable, HTTP server using BSD sockets.
Dumb HTTP server (multi-threaded): Implement a simple HTTP server supporting simultaneous connections using BSD sockets.
Echo client (advanced): Implement a client that sends IP packets, waits for data to be sent back, and verifies it.
Echo server (advanced): Implement a UDP/TCP server that sends received packets back to the sender.
Echo server (service): Implements a simple IPv4/IPv6 TCP echo server using BSD sockets and socket service API.
Echo server (simple): Implements a simple IPv4/IPv6 TCP echo server using BSD sockets.
HTTP Client: Implement an HTTP(S) client that issues a variety of HTTP requests.
HTTP GET using plain sockets: Implement an HTTP(S) client using plain BSD sockets.
Large HTTP download: Download a large file from a web server using BSD sockets.
Microsoft Azure IoT Hub MQTT: Connect to Azure IoT Hub and publish messages using MQTT.
Modbus TCP server: Implement a Modbus TCP server exposing Modbus commands to control LEDs.
Modbus TCP-to-serial gateway: Implement a gateway between an Ethernet TCP-IP network and a Modbus serial line.
Network management socket: Listen to network management events using a network management socket.
Packet socket: Use raw packet sockets over Ethernet.
SNTP client: Use SNTP to get the current time from the host.
SocketCAN: Send and receive raw CAN frames using BSD sockets API.
Socketpair: Implement communication between threads using socket pairs.
TCP sample for TTCN-3 based sanity check: Use TTCN-3 to validate the functionality of the TCP stack.
TagoIO HTTP Post: Send random temperature values to TagoIO IoT Cloud Platform using HTTP.
UDP sender using SO_TXTIME: Control the transmission time of a packet using SO_TXTIME socket option.
Video TCP server sink: Capture video frames and send them over the network to a TCP client.
WebSocket Client: Implement a Websocket client that connects to a Websocket server.
mDNS responder: Listen and respond to mDNS queries.

group bsd_sockets

BSD Sockets compatible API.

Socket APIs available if CONFIG_NET_SOCKETS_POSIX_NAMES is enabled

static inline int socket(int family, int type, int proto): POSIX wrapper for zsock_socket.

static inline int socketpair(int family, int type, int proto, int sv[2]): POSIX wrapper for zsock_socketpair.

static inline int close(int sock): POSIX wrapper for zsock_close.

static inline int shutdown(int sock, int how): POSIX wrapper for zsock_shutdown.

static inline int bind(int sock, const struct sockaddr *addr, socklen_t addrlen): POSIX wrapper for zsock_bind.

static inline int connect(int sock, const struct sockaddr *addr, socklen_t addrlen): POSIX wrapper for zsock_connect.

static inline int listen(int sock, int backlog): POSIX wrapper for zsock_listen.

static inline int accept(int sock, struct sockaddr *addr, socklen_t *addrlen): POSIX wrapper for zsock_accept.

static inline ssize_t send(int sock, const void *buf, size_t len, int flags): POSIX wrapper for zsock_send.

static inline ssize_t recv(int sock, void *buf, size_t max_len, int flags): POSIX wrapper for zsock_recv.

static inline ssize_t sendto(int sock, const void *buf, size_t len, int flags, const struct sockaddr *dest_addr, socklen_t addrlen): POSIX wrapper for zsock_sendto.

static inline ssize_t sendmsg(int sock, const struct msghdr *message, int flags): POSIX wrapper for zsock_sendmsg.

static inline ssize_t recvfrom(int sock, void *buf, size_t max_len, int flags, struct sockaddr *src_addr, socklen_t *addrlen): POSIX wrapper for zsock_recvfrom.

static inline ssize_t recvmsg(int sock, struct msghdr *msg, int flags): POSIX wrapper for zsock_recvmsg.

static inline int poll(struct zsock_pollfd *fds, int nfds, int timeout): POSIX wrapper for zsock_poll.

static inline int getsockopt(int sock, int level, int optname, void *optval, socklen_t *optlen): POSIX wrapper for zsock_getsockopt.

static inline int setsockopt(int sock, int level, int optname, const void *optval, socklen_t optlen): POSIX wrapper for zsock_setsockopt.

static inline int getpeername(int sock, struct sockaddr *addr, socklen_t *addrlen): POSIX wrapper for zsock_getpeername.

static inline int getsockname(int sock, struct sockaddr *addr, socklen_t *addrlen): POSIX wrapper for zsock_getsockname.

static inline int getaddrinfo(const char *host, const char *service, const struct zsock_addrinfo *hints, struct zsock_addrinfo **res): POSIX wrapper for zsock_getaddrinfo.

static inline void freeaddrinfo(struct zsock_addrinfo *ai): POSIX wrapper for zsock_freeaddrinfo.

static inline const char *gai_strerror(int errcode): POSIX wrapper for zsock_gai_strerror.

static inline int getnameinfo(const struct sockaddr *addr, socklen_t addrlen, char *host, socklen_t hostlen, char *serv, socklen_t servlen, int flags): POSIX wrapper for zsock_getnameinfo.

static inline int gethostname(char *buf, size_t len): POSIX wrapper for zsock_gethostname.

static inline int inet_pton(sa_family_t family, const char *src, void *dst): POSIX wrapper for zsock_inet_pton.

static inline char *inet_ntop(sa_family_t family, const void *src, char *dst, size_t size): POSIX wrapper for zsock_inet_ntop.

pollfd: POSIX wrapper for zsock_pollfd.

addrinfo: POSIX wrapper for zsock_addrinfo.

POLLIN: POSIX wrapper for ZSOCK_POLLIN.

POLLOUT: POSIX wrapper for ZSOCK_POLLOUT.

POLLERR: POSIX wrapper for ZSOCK_POLLERR.

POLLHUP: POSIX wrapper for ZSOCK_POLLHUP.

POLLNVAL: POSIX wrapper for ZSOCK_POLLNVAL.

MSG_PEEK: POSIX wrapper for ZSOCK_MSG_PEEK.

MSG_CTRUNC: POSIX wrapper for ZSOCK_MSG_CTRUNC.

MSG_TRUNC: POSIX wrapper for ZSOCK_MSG_TRUNC.

MSG_DONTWAIT: POSIX wrapper for ZSOCK_MSG_DONTWAIT.

MSG_WAITALL: POSIX wrapper for ZSOCK_MSG_WAITALL.

SHUT_RD: POSIX wrapper for ZSOCK_SHUT_RD.

SHUT_WR: POSIX wrapper for ZSOCK_SHUT_WR.

SHUT_RDWR: POSIX wrapper for ZSOCK_SHUT_RDWR.

EAI_BADFLAGS: POSIX wrapper for DNS_EAI_BADFLAGS.

EAI_NONAME: POSIX wrapper for DNS_EAI_NONAME.

EAI_AGAIN: POSIX wrapper for DNS_EAI_AGAIN.

EAI_FAIL: POSIX wrapper for DNS_EAI_FAIL.

EAI_NODATA: POSIX wrapper for DNS_EAI_NODATA.

EAI_MEMORY: POSIX wrapper for DNS_EAI_MEMORY.

EAI_SYSTEM: POSIX wrapper for DNS_EAI_SYSTEM.

EAI_SERVICE: POSIX wrapper for DNS_EAI_SERVICE.

EAI_SOCKTYPE: POSIX wrapper for DNS_EAI_SOCKTYPE.

EAI_FAMILY: POSIX wrapper for DNS_EAI_FAMILY.

Options for poll()

ZSOCK_POLLIN: zsock_poll: Poll for readability

ZSOCK_POLLPRI: zsock_poll: Poll for exceptional condition

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)

Options for sending and receiving data

ZSOCK_MSG_PEEK: zsock_recv: Read data without removing it from socket input queue

ZSOCK_MSG_CTRUNC: zsock_recvmsg: Control data buffer too small.

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

Options for shutdown() function

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

Flags for getaddrinfo() hints

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.

AI_EXTFLAGS: Extra flags present (see RFC 5014)

Flags for getnameinfo()

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

Network interface name description

IFNAMSIZ: Network interface name length.

Socket level options (SOL_SOCKET)

SOL_SOCKET: Socket-level option.

SO_DEBUG: Recording debugging information (ignored, for compatibility)

SO_REUSEADDR: address reuse

SO_TYPE: Type of the socket.

SO_ERROR: Async error.

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

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

SO_SNDBUF: Size of socket send buffer.

SO_RCVBUF: Size of socket recv buffer.

SO_KEEPALIVE: Enable sending keep-alive messages on connections.

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

SO_PRIORITY: Socket priority.

SO_LINGER: Socket lingers on close (ignored, for compatibility)

SO_REUSEPORT: Allow multiple sockets to reuse a single port.

SO_RCVLOWAT: Receive low watermark (ignored, for compatibility)

SO_SNDLOWAT: Send low watermark (ignored, for compatibility)

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

SO_SNDTIMEO: Send timeout.

SO_BINDTODEVICE: Bind a socket to an interface.

SO_ACCEPTCONN: Socket accepts incoming connections (ignored, for compatibility)

SO_TIMESTAMPING: Timestamp TX packets.

SO_PROTOCOL: Protocol used with the socket.

SO_DOMAIN: Domain used with SOCKET.

SO_SOCKS5: Enable SOCKS5 for Socket.

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

SCM_TXTIME: Socket TX time (same as SO_TXTIME)

TCP level options (IPPROTO_TCP)

TCP_NODELAY: Disable TCP buffering (ignored, for compatibility)

TCP_KEEPIDLE: Start keepalives after this period (seconds)

TCP_KEEPINTVL: Interval between keepalives (seconds)

TCP_KEEPCNT: Number of keepalives before dropping connection.

IPv4 level options (IPPROTO_IP)

IP_TOS: Set or receive the Type-Of-Service value for an outgoing packet.

IP_TTL: Set or receive the Time-To-Live value for an outgoing packet.

IP_PKTINFO: Pass an IP_PKTINFO ancillary message that contains a pktinfo structure that supplies some information about the incoming packet.

IP_MULTICAST_TTL: Set IPv4 multicast TTL value.

IP_ADD_MEMBERSHIP: Join IPv4 multicast group.

IP_DROP_MEMBERSHIP: Leave IPv4 multicast group.

IPv6 level options (IPPROTO_IPV6)

IPV6_UNICAST_HOPS: Set the unicast hop limit for the socket.

IPV6_MULTICAST_HOPS: Set the multicast hop limit for the socket.

IPV6_ADD_MEMBERSHIP: Join IPv6 multicast group.

IPV6_DROP_MEMBERSHIP: Leave IPv6 multicast group.

IPV6_V6ONLY: Don’t support IPv4 access.

IPV6_RECVPKTINFO

Pass an IPV6_RECVPKTINFO ancillary message that contains a in6_pktinfo structure that supplies some information about the incoming packet.

See RFC 3542.

IPV6_ADDR_PREFERENCES: RFC5014: Source address selection.

IPV6_PREFER_SRC_TMP: Prefer temporary address as source.

IPV6_PREFER_SRC_PUBLIC: Prefer public address as source.

IPV6_PREFER_SRC_PUBTMP_DEFAULT

Either public or temporary address is selected as a default source depending on the output interface configuration (this is the default value).

This is Linux specific option not found in the RFC.

IPV6_PREFER_SRC_COA

Prefer Care-of address as source.

Ignored in Zephyr.

IPV6_PREFER_SRC_HOME

Prefer Home address as source.

Ignored in Zephyr.

IPV6_PREFER_SRC_CGA

Prefer CGA (Cryptographically Generated Address) address as source.

Ignored in Zephyr.

IPV6_PREFER_SRC_NONCGA

Prefer non-CGA address as source.

Ignored in Zephyr.

IPV6_TCLASS: Set or receive the traffic class value for an outgoing packet.

Backlog size for listen()

SOMAXCONN: listen: The maximum backlog queue length

Defines

ZSOCK_FD_SETSIZE: Number of file descriptors which can be added to 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_POSIX_API is defined.

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

TLS Credentials 

Related code samples

AWS IoT Core MQTT: Connect to AWS IoT Core and publish messages using MQTT.
Dumb HTTP server (multi-threaded): Implement a simple HTTP server supporting simultaneous connections using BSD sockets.
Echo client (advanced): Implement a client that sends IP packets, waits for data to be sent back, and verifies it.
Echo server (advanced): Implement a UDP/TCP server that sends received packets back to the sender.
HTTP Client: Implement an HTTP(S) client that issues a variety of HTTP requests.
HTTP GET using plain sockets: Implement an HTTP(S) client using plain BSD sockets.
HTTP Server: Implement an HTTP(s) Server demonstrating various resource types.
Large HTTP download: Download a large file from a web server using BSD sockets.
Microsoft Azure IoT Hub MQTT: Connect to Azure IoT Hub and publish messages using MQTT.
TagoIO HTTP Post: Send random temperature values to TagoIO IoT Cloud Platform using HTTP.

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.

Note

Negative values are reserved for internal use.

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.