File net_sockets.h

Network sockets abstraction layer to integrate Mbed TLS into a BSD-style sockets API.

The network sockets module provides an example integration of the Mbed TLS library into a BSD sockets implementation. The module is intended to be an example of how Mbed TLS can be integrated into a networking stack, as well as to be Mbed TLS’s network integration for its supported platforms.

The module is intended only to be used with the Mbed TLS library and is not intended to be used by third party application software directly.

The supported platforms are as follows:

  • Microsoft Windows and Windows CE

  • POSIX/Unix platforms including Linux, OS X

Defines

MBEDTLS_ERR_NET_SOCKET_FAILED

Failed to open a socket.

MBEDTLS_ERR_NET_CONNECT_FAILED

The connection to the given server / port failed.

MBEDTLS_ERR_NET_BIND_FAILED

Binding of the socket failed.

MBEDTLS_ERR_NET_LISTEN_FAILED

Could not listen on the socket.

MBEDTLS_ERR_NET_ACCEPT_FAILED

Could not accept the incoming connection.

MBEDTLS_ERR_NET_RECV_FAILED

Reading information from the socket failed.

MBEDTLS_ERR_NET_SEND_FAILED

Sending information through the socket failed.

MBEDTLS_ERR_NET_CONN_RESET

Connection was reset by peer.

MBEDTLS_ERR_NET_UNKNOWN_HOST

Failed to get an IP address for the given hostname.

MBEDTLS_ERR_NET_BUFFER_TOO_SMALL

Buffer is too small to hold the data.

MBEDTLS_ERR_NET_INVALID_CONTEXT

The context is invalid, eg because it was free()ed.

MBEDTLS_ERR_NET_POLL_FAILED

Polling the net context failed.

MBEDTLS_ERR_NET_BAD_INPUT_DATA

Input invalid.

MBEDTLS_NET_LISTEN_BACKLOG

The backlog that listen() should use.

MBEDTLS_NET_PROTO_TCP

The TCP transport protocol

MBEDTLS_NET_PROTO_UDP

The UDP transport protocol

MBEDTLS_NET_POLL_READ

Used in mbedtls_net_poll to check for pending data

MBEDTLS_NET_POLL_WRITE

Used in mbedtls_net_poll to check if write possible

Typedefs

typedef struct mbedtls_net_context mbedtls_net_context

Wrapper type for sockets.

Currently backed by just a file descriptor, but might be more in the future (eg two file descriptors for combined IPv4 + IPv6 support, or additional structures for hand-made UDP demultiplexing).

Functions

void mbedtls_net_init(mbedtls_net_context *ctx)

Initialize a context Just makes the context ready to be used or freed safely.

Parameters

ctx – Context to initialize

int mbedtls_net_connect(mbedtls_net_context *ctx, const char *host, const char *port, int proto)

Initiate a connection with host:port in the given protocol.

Note

Sets the socket in connected mode even with UDP.

Parameters

  • ctx – Socket to use

  • host – Host to connect to

  • port – Port to connect to

  • proto – Protocol: MBEDTLS_NET_PROTO_TCP or MBEDTLS_NET_PROTO_UDP

Returns

0 if successful, or one of: MBEDTLS_ERR_NET_SOCKET_FAILED, MBEDTLS_ERR_NET_UNKNOWN_HOST, MBEDTLS_ERR_NET_CONNECT_FAILED

int mbedtls_net_bind(mbedtls_net_context *ctx, const char *bind_ip, const char *port, int proto)

Create a receiving socket on bind_ip:port in the chosen protocol. If bind_ip == NULL, all interfaces are bound.

Note

Regardless of the protocol, opens the sockets and binds it. In addition, make the socket listening if protocol is TCP.

Parameters

  • ctx – Socket to use

  • bind_ip – IP to bind to, can be NULL

  • port – Port number to use

  • proto – Protocol: MBEDTLS_NET_PROTO_TCP or MBEDTLS_NET_PROTO_UDP

Returns

0 if successful, or one of: MBEDTLS_ERR_NET_SOCKET_FAILED, MBEDTLS_ERR_NET_UNKNOWN_HOST, MBEDTLS_ERR_NET_BIND_FAILED, MBEDTLS_ERR_NET_LISTEN_FAILED

int mbedtls_net_accept(mbedtls_net_context *bind_ctx, mbedtls_net_context *client_ctx, void *client_ip, size_t buf_size, size_t *cip_len)

Accept a connection from a remote client.

Parameters

  • bind_ctx – Relevant socket

  • client_ctx – Will contain the connected client socket

  • client_ip – Will contain the client IP address, can be NULL

  • buf_size – Size of the client_ip buffer

  • cip_len – Will receive the size of the client IP written, can be NULL if client_ip is null

Returns

0 if successful, or MBEDTLS_ERR_NET_SOCKET_FAILED, MBEDTLS_ERR_NET_BIND_FAILED, MBEDTLS_ERR_NET_ACCEPT_FAILED, or MBEDTLS_ERR_NET_BUFFER_TOO_SMALL if buf_size is too small, MBEDTLS_ERR_SSL_WANT_READ if bind_fd was set to non-blocking and accept() would block.

int mbedtls_net_poll(mbedtls_net_context *ctx, uint32_t rw, uint32_t timeout)

Check and wait for the context to be ready for read/write.

Note

The current implementation of this function uses select() and returns an error if the file descriptor is FD_SETSIZE or greater.

Parameters

  • ctx – Socket to check

  • rw – Bitflag composed of MBEDTLS_NET_POLL_READ and MBEDTLS_NET_POLL_WRITE specifying the events to wait for:

    • If MBEDTLS_NET_POLL_READ is set, the function will return as soon as the net context is available for reading.

    • If MBEDTLS_NET_POLL_WRITE is set, the function will return as soon as the net context is available for writing.

  • timeout – Maximal amount of time to wait before returning, in milliseconds. If timeout is zero, the function returns immediately. If timeout is -1u, the function blocks potentially indefinitely.

Returns

Bitmask composed of MBEDTLS_NET_POLL_READ/WRITE on success or timeout, or a negative return code otherwise.

int mbedtls_net_set_block(mbedtls_net_context *ctx)

Set the socket blocking.

Parameters

ctx – Socket to set

Returns

0 if successful, or a non-zero error code

int mbedtls_net_set_nonblock(mbedtls_net_context *ctx)

Set the socket non-blocking.

Parameters

ctx – Socket to set

Returns

0 if successful, or a non-zero error code

void mbedtls_net_usleep(unsigned long usec)

Portable usleep helper.

Note

Real amount of time slept will not be less than select()’s timeout granularity (typically, 10ms).

Parameters

usec – Amount of microseconds to sleep

int mbedtls_net_recv(void *ctx, unsigned char *buf, size_t len)

Read at most ‘len’ characters. If no error occurs, the actual amount read is returned.

Parameters

  • ctx – Socket

  • buf – The buffer to write to

  • len – Maximum length of the buffer

Returns

the number of bytes received, or a non-zero error code; with a non-blocking socket, MBEDTLS_ERR_SSL_WANT_READ indicates read() would block.

int mbedtls_net_send(void *ctx, const unsigned char *buf, size_t len)

Write at most ‘len’ characters. If no error occurs, the actual amount read is returned.

Parameters

  • ctx – Socket

  • buf – The buffer to read from

  • len – The length of the buffer

Returns

the number of bytes sent, or a non-zero error code; with a non-blocking socket, MBEDTLS_ERR_SSL_WANT_WRITE indicates write() would block.

int mbedtls_net_recv_timeout(void *ctx, unsigned char *buf, size_t len, uint32_t timeout)

Read at most ‘len’ characters, blocking for at most ‘timeout’ seconds. If no error occurs, the actual amount read is returned.

Note

The current implementation of this function uses select() and returns an error if the file descriptor is FD_SETSIZE or greater.

Note

This function will block (until data becomes available or timeout is reached) even if the socket is set to non-blocking. Handling timeouts with non-blocking reads requires a different strategy.

Parameters

  • ctx – Socket

  • buf – The buffer to write to

  • len – Maximum length of the buffer

  • timeout – Maximum number of milliseconds to wait for data 0 means no timeout (wait forever)

Returns

The number of bytes received if successful. MBEDTLS_ERR_SSL_TIMEOUT if the operation timed out. MBEDTLS_ERR_SSL_WANT_READ if interrupted by a signal. Another negative error code (MBEDTLS_ERR_NET_xxx) for other failures.

void mbedtls_net_close(mbedtls_net_context *ctx)

Closes down the connection and free associated data.

Note

This function frees and clears data associated with the context but does not free the memory pointed to by ctx. This memory is the responsibility of the caller.

Parameters

ctx – The context to close

void mbedtls_net_free(mbedtls_net_context *ctx)

Gracefully shutdown the connection and free associated data.

Note

This function frees and clears data associated with the context but does not free the memory pointed to by ctx. This memory is the responsibility of the caller.

Parameters

ctx – The context to free

struct mbedtls_net_context
#include <net_sockets.h>

Wrapper type for sockets.

Currently backed by just a file descriptor, but might be more in the future (eg two file descriptors for combined IPv4 + IPv6 support, or additional structures for hand-made UDP demultiplexing).

Public Members

int fd

The underlying file descriptor.

This field is only guaranteed to be present on POSIX/Unix-like platforms. On other platforms, it may have a different type, have a different meaning, or be absent altogether.