1/**
2 * \file net_sockets.h
3 *
4 * \brief   Network sockets abstraction layer to integrate Mbed TLS into a
5 *          BSD-style sockets API.
6 *
7 *          The network sockets module provides an example integration of the
8 *          Mbed TLS library into a BSD sockets implementation. The module is
9 *          intended to be an example of how Mbed TLS can be integrated into a
10 *          networking stack, as well as to be Mbed TLS's network integration
11 *          for its supported platforms.
12 *
13 *          The module is intended only to be used with the Mbed TLS library and
14 *          is not intended to be used by third party application software
15 *          directly.
16 *
17 *          The supported platforms are as follows:
18 *              * Microsoft Windows and Windows CE
19 *              * POSIX/Unix platforms including Linux, OS X
20 *
21 */
22/*
23 *  Copyright The Mbed TLS Contributors
24 *  SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
25 */
26#ifndef MBEDTLS_NET_SOCKETS_H
27#define MBEDTLS_NET_SOCKETS_H
28#include "mbedtls/private_access.h"
29
30#include "mbedtls/build_info.h"
31
32#include "mbedtls/ssl.h"
33
34#include <stddef.h>
35#include <stdint.h>
36
37/** Failed to open a socket. */
38#define MBEDTLS_ERR_NET_SOCKET_FAILED                     -0x0042
39/** The connection to the given server / port failed. */
40#define MBEDTLS_ERR_NET_CONNECT_FAILED                    -0x0044
41/** Binding of the socket failed. */
42#define MBEDTLS_ERR_NET_BIND_FAILED                       -0x0046
43/** Could not listen on the socket. */
44#define MBEDTLS_ERR_NET_LISTEN_FAILED                     -0x0048
45/** Could not accept the incoming connection. */
46#define MBEDTLS_ERR_NET_ACCEPT_FAILED                     -0x004A
47/** Reading information from the socket failed. */
48#define MBEDTLS_ERR_NET_RECV_FAILED                       -0x004C
49/** Sending information through the socket failed. */
50#define MBEDTLS_ERR_NET_SEND_FAILED                       -0x004E
51/** Connection was reset by peer. */
52#define MBEDTLS_ERR_NET_CONN_RESET                        -0x0050
53/** Failed to get an IP address for the given hostname. */
54#define MBEDTLS_ERR_NET_UNKNOWN_HOST                      -0x0052
55/** Buffer is too small to hold the data. */
56#define MBEDTLS_ERR_NET_BUFFER_TOO_SMALL                  -0x0043
57/** The context is invalid, eg because it was free()ed. */
58#define MBEDTLS_ERR_NET_INVALID_CONTEXT                   -0x0045
59/** Polling the net context failed. */
60#define MBEDTLS_ERR_NET_POLL_FAILED                       -0x0047
61/** Input invalid. */
62#define MBEDTLS_ERR_NET_BAD_INPUT_DATA                    -0x0049
63
64#define MBEDTLS_NET_LISTEN_BACKLOG         10 /**< The backlog that listen() should use. */
65
66#define MBEDTLS_NET_PROTO_TCP 0 /**< The TCP transport protocol */
67#define MBEDTLS_NET_PROTO_UDP 1 /**< The UDP transport protocol */
68
69#define MBEDTLS_NET_POLL_READ  1 /**< Used in \c mbedtls_net_poll to check for pending data  */
70#define MBEDTLS_NET_POLL_WRITE 2 /**< Used in \c mbedtls_net_poll to check if write possible */
71
72#ifdef __cplusplus
73extern "C" {
74#endif
75
76/**
77 * Wrapper type for sockets.
78 *
79 * Currently backed by just a file descriptor, but might be more in the future
80 * (eg two file descriptors for combined IPv4 + IPv6 support, or additional
81 * structures for hand-made UDP demultiplexing).
82 */
83typedef struct mbedtls_net_context {
84    /** The underlying file descriptor.
85     *
86     * This field is only guaranteed to be present on POSIX/Unix-like platforms.
87     * On other platforms, it may have a different type, have a different
88     * meaning, or be absent altogether.
89     */
90    int fd;
91}
92mbedtls_net_context;
93
94/**
95 * \brief          Initialize a context
96 *                 Just makes the context ready to be used or freed safely.
97 *
98 * \param ctx      Context to initialize
99 */
100void mbedtls_net_init(mbedtls_net_context *ctx);
101
102/**
103 * \brief          Initiate a connection with host:port in the given protocol
104 *
105 * \param ctx      Socket to use
106 * \param host     Host to connect to
107 * \param port     Port to connect to
108 * \param proto    Protocol: MBEDTLS_NET_PROTO_TCP or MBEDTLS_NET_PROTO_UDP
109 *
110 * \return         0 if successful, or one of:
111 *                      MBEDTLS_ERR_NET_SOCKET_FAILED,
112 *                      MBEDTLS_ERR_NET_UNKNOWN_HOST,
113 *                      MBEDTLS_ERR_NET_CONNECT_FAILED
114 *
115 * \note           Sets the socket in connected mode even with UDP.
116 */
117int mbedtls_net_connect(mbedtls_net_context *ctx, const char *host, const char *port, int proto);
118
119/**
120 * \brief          Create a receiving socket on bind_ip:port in the chosen
121 *                 protocol. If bind_ip == NULL, all interfaces are bound.
122 *
123 * \param ctx      Socket to use
124 * \param bind_ip  IP to bind to, can be NULL
125 * \param port     Port number to use
126 * \param proto    Protocol: MBEDTLS_NET_PROTO_TCP or MBEDTLS_NET_PROTO_UDP
127 *
128 * \return         0 if successful, or one of:
129 *                      MBEDTLS_ERR_NET_SOCKET_FAILED,
130 *                      MBEDTLS_ERR_NET_UNKNOWN_HOST,
131 *                      MBEDTLS_ERR_NET_BIND_FAILED,
132 *                      MBEDTLS_ERR_NET_LISTEN_FAILED
133 *
134 * \note           Regardless of the protocol, opens the sockets and binds it.
135 *                 In addition, make the socket listening if protocol is TCP.
136 */
137int mbedtls_net_bind(mbedtls_net_context *ctx, const char *bind_ip, const char *port, int proto);
138
139/**
140 * \brief           Accept a connection from a remote client
141 *
142 * \param bind_ctx  Relevant socket
143 * \param client_ctx Will contain the connected client socket
144 * \param client_ip Will contain the client IP address, can be NULL
145 * \param buf_size  Size of the client_ip buffer
146 * \param cip_len   Will receive the size of the client IP written,
147 *                  can be NULL if client_ip is null
148 *
149 * \return          0 if successful, or
150 *                  MBEDTLS_ERR_NET_SOCKET_FAILED,
151 *                  MBEDTLS_ERR_NET_BIND_FAILED,
152 *                  MBEDTLS_ERR_NET_ACCEPT_FAILED, or
153 *                  MBEDTLS_ERR_NET_BUFFER_TOO_SMALL if buf_size is too small,
154 *                  MBEDTLS_ERR_SSL_WANT_READ if bind_fd was set to
155 *                  non-blocking and accept() would block.
156 */
157int mbedtls_net_accept(mbedtls_net_context *bind_ctx,
158                       mbedtls_net_context *client_ctx,
159                       void *client_ip, size_t buf_size, size_t *cip_len);
160
161/**
162 * \brief          Check and wait for the context to be ready for read/write
163 *
164 * \note           The current implementation of this function uses
165 *                 select() and returns an error if the file descriptor
166 *                 is \c FD_SETSIZE or greater.
167 *
168 * \param ctx      Socket to check
169 * \param rw       Bitflag composed of MBEDTLS_NET_POLL_READ and
170 *                 MBEDTLS_NET_POLL_WRITE specifying the events
171 *                 to wait for:
172 *                 - If MBEDTLS_NET_POLL_READ is set, the function
173 *                   will return as soon as the net context is available
174 *                   for reading.
175 *                 - If MBEDTLS_NET_POLL_WRITE is set, the function
176 *                   will return as soon as the net context is available
177 *                   for writing.
178 * \param timeout  Maximal amount of time to wait before returning,
179 *                 in milliseconds. If \c timeout is zero, the
180 *                 function returns immediately. If \c timeout is
181 *                 -1u, the function blocks potentially indefinitely.
182 *
183 * \return         Bitmask composed of MBEDTLS_NET_POLL_READ/WRITE
184 *                 on success or timeout, or a negative return code otherwise.
185 */
186int mbedtls_net_poll(mbedtls_net_context *ctx, uint32_t rw, uint32_t timeout);
187
188/**
189 * \brief          Set the socket blocking
190 *
191 * \param ctx      Socket to set
192 *
193 * \return         0 if successful, or a non-zero error code
194 */
195int mbedtls_net_set_block(mbedtls_net_context *ctx);
196
197/**
198 * \brief          Set the socket non-blocking
199 *
200 * \param ctx      Socket to set
201 *
202 * \return         0 if successful, or a non-zero error code
203 */
204int mbedtls_net_set_nonblock(mbedtls_net_context *ctx);
205
206/**
207 * \brief          Portable usleep helper
208 *
209 * \param usec     Amount of microseconds to sleep
210 *
211 * \note           Real amount of time slept will not be less than
212 *                 select()'s timeout granularity (typically, 10ms).
213 */
214void mbedtls_net_usleep(unsigned long usec);
215
216/**
217 * \brief          Read at most 'len' characters. If no error occurs,
218 *                 the actual amount read is returned.
219 *
220 * \param ctx      Socket
221 * \param buf      The buffer to write to
222 * \param len      Maximum length of the buffer
223 *
224 * \return         the number of bytes received,
225 *                 or a non-zero error code; with a non-blocking socket,
226 *                 MBEDTLS_ERR_SSL_WANT_READ indicates read() would block.
227 */
228int mbedtls_net_recv(void *ctx, unsigned char *buf, size_t len);
229
230/**
231 * \brief          Write at most 'len' characters. If no error occurs,
232 *                 the actual amount read is returned.
233 *
234 * \param ctx      Socket
235 * \param buf      The buffer to read from
236 * \param len      The length of the buffer
237 *
238 * \return         the number of bytes sent,
239 *                 or a non-zero error code; with a non-blocking socket,
240 *                 MBEDTLS_ERR_SSL_WANT_WRITE indicates write() would block.
241 */
242int mbedtls_net_send(void *ctx, const unsigned char *buf, size_t len);
243
244/**
245 * \brief          Read at most 'len' characters, blocking for at most
246 *                 'timeout' seconds. If no error occurs, the actual amount
247 *                 read is returned.
248 *
249 * \note           The current implementation of this function uses
250 *                 select() and returns an error if the file descriptor
251 *                 is \c FD_SETSIZE or greater.
252 *
253 * \param ctx      Socket
254 * \param buf      The buffer to write to
255 * \param len      Maximum length of the buffer
256 * \param timeout  Maximum number of milliseconds to wait for data
257 *                 0 means no timeout (wait forever)
258 *
259 * \return         The number of bytes received if successful.
260 *                 MBEDTLS_ERR_SSL_TIMEOUT if the operation timed out.
261 *                 MBEDTLS_ERR_SSL_WANT_READ if interrupted by a signal.
262 *                 Another negative error code (MBEDTLS_ERR_NET_xxx)
263 *                 for other failures.
264 *
265 * \note           This function will block (until data becomes available or
266 *                 timeout is reached) even if the socket is set to
267 *                 non-blocking. Handling timeouts with non-blocking reads
268 *                 requires a different strategy.
269 */
270int mbedtls_net_recv_timeout(void *ctx, unsigned char *buf, size_t len,
271                             uint32_t timeout);
272
273/**
274 * \brief          Closes down the connection and free associated data
275 *
276 * \param ctx      The context to close
277 *
278 * \note           This function frees and clears data associated with the
279 *                 context but does not free the memory pointed to by \p ctx.
280 *                 This memory is the responsibility of the caller.
281 */
282void mbedtls_net_close(mbedtls_net_context *ctx);
283
284/**
285 * \brief          Gracefully shutdown the connection and free associated data
286 *
287 * \param ctx      The context to free
288 *
289 * \note           This function frees and clears data associated with the
290 *                 context but does not free the memory pointed to by \p ctx.
291 *                 This memory is the responsibility of the caller.
292 */
293void mbedtls_net_free(mbedtls_net_context *ctx);
294
295#ifdef __cplusplus
296}
297#endif
298
299#endif /* net_sockets.h */
300