blob: 1b59d18c05ce61d2cf17bf5b1e5fbfbc59e74b89 [file] [log] [blame]
Paul Bakker5121ce52009-01-03 21:22:43 +00001/**
2 * \file net.h
Paul Bakkere0ccd0a2009-01-04 16:27:10 +00003 *
Paul Bakkercce9d772011-11-18 14:26:47 +00004 * \brief Network communication functions
Paul Bakker37ca75d2011-01-06 12:28:03 +00005 *
Manuel Pégourié-Gonnard6fb81872015-07-27 11:11:48 +02006 * Copyright (C) 2006-2015, ARM Limited, All Rights Reserved
Manuel Pégourié-Gonnard37ff1402015-09-04 14:21:07 +02007 * SPDX-License-Identifier: Apache-2.0
8 *
9 * Licensed under the Apache License, Version 2.0 (the "License"); you may
10 * not use this file except in compliance with the License.
11 * You may obtain a copy of the License at
12 *
13 * http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing, software
16 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
17 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 * See the License for the specific language governing permissions and
19 * limitations under the License.
Paul Bakkerb96f1542010-07-18 20:36:00 +000020 *
Manuel Pégourié-Gonnardfe446432015-03-06 13:17:10 +000021 * This file is part of mbed TLS (https://tls.mbed.org)
Paul Bakker5121ce52009-01-03 21:22:43 +000022 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020023#ifndef MBEDTLS_NET_H
24#define MBEDTLS_NET_H
Paul Bakker5121ce52009-01-03 21:22:43 +000025
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020026#if !defined(MBEDTLS_CONFIG_FILE)
Manuel Pégourié-Gonnard9d9b0032014-09-18 11:22:45 +020027#include "config.h"
28#else
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020029#include MBEDTLS_CONFIG_FILE
Manuel Pégourié-Gonnard9d9b0032014-09-18 11:22:45 +020030#endif
31
Manuel Pégourié-Gonnard88369942015-05-06 16:19:31 +010032#include "ssl.h"
33
Rich Evans00ab4702015-02-06 13:43:58 +000034#include <stddef.h>
Manuel Pégourié-Gonnardab229102015-04-15 11:53:16 +020035#include <stdint.h>
Manuel Pégourié-Gonnardc8d8e972014-10-01 15:01:39 +020036
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020037#define MBEDTLS_ERR_NET_SOCKET_FAILED -0x0042 /**< Failed to open a socket. */
38#define MBEDTLS_ERR_NET_CONNECT_FAILED -0x0044 /**< The connection to the given server / port failed. */
39#define MBEDTLS_ERR_NET_BIND_FAILED -0x0046 /**< Binding of the socket failed. */
40#define MBEDTLS_ERR_NET_LISTEN_FAILED -0x0048 /**< Could not listen on the socket. */
41#define MBEDTLS_ERR_NET_ACCEPT_FAILED -0x004A /**< Could not accept the incoming connection. */
42#define MBEDTLS_ERR_NET_RECV_FAILED -0x004C /**< Reading information from the socket failed. */
43#define MBEDTLS_ERR_NET_SEND_FAILED -0x004E /**< Sending information through the socket failed. */
44#define MBEDTLS_ERR_NET_CONN_RESET -0x0050 /**< Connection was reset by peer. */
Manuel Pégourié-Gonnard88369942015-05-06 16:19:31 +010045#define MBEDTLS_ERR_NET_UNKNOWN_HOST -0x0052 /**< Failed to get an IP address for the given hostname. */
Manuel Pégourié-Gonnard0b104b02015-05-14 21:52:40 +020046#define MBEDTLS_ERR_NET_BUFFER_TOO_SMALL -0x0043 /**< Buffer is too small to hold the data. */
Manuel Pégourié-Gonnard9bd0afd2015-07-01 19:03:27 +020047#define MBEDTLS_ERR_NET_INVALID_CONTEXT -0x0045 /**< The context is invalid, eg because it was free()ed. */
Paul Bakker5121ce52009-01-03 21:22:43 +000048
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020049#define MBEDTLS_NET_LISTEN_BACKLOG 10 /**< The backlog that listen() should use. */
Paul Bakker192381a2011-05-20 12:31:31 +000050
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020051#define MBEDTLS_NET_PROTO_TCP 0 /**< The TCP transport protocol */
52#define MBEDTLS_NET_PROTO_UDP 1 /**< The UDP transport protocol */
Manuel Pégourié-Gonnardf5a13122014-03-23 17:38:16 +010053
Paul Bakker5121ce52009-01-03 21:22:43 +000054#ifdef __cplusplus
55extern "C" {
56#endif
57
58/**
Manuel Pégourié-Gonnard91895852015-06-30 13:34:45 +020059 * Wrapper type for sockets.
60 *
61 * Currently backed by just a file descriptor, but might be more in the future
62 * (eg two file descriptors for combined IPv4 + IPv6 support, or additional
63 * structures for hand-made UDP demultiplexing).
64 */
65typedef struct
66{
67 int fd; /**< The underlying file descriptor */
68}
69mbedtls_net_context;
70
71/**
72 * \brief Initialize a context
73 * Just makes the context ready to be used or freed safely.
74 *
75 * \param ctx Context to initialize
76 */
77void mbedtls_net_init( mbedtls_net_context *ctx );
78
79/**
Manuel Pégourié-Gonnardf5a13122014-03-23 17:38:16 +010080 * \brief Initiate a connection with host:port in the given protocol
Paul Bakker5121ce52009-01-03 21:22:43 +000081 *
Manuel Pégourié-Gonnard91895852015-06-30 13:34:45 +020082 * \param ctx Socket to use
Paul Bakker13e2dfe2009-07-28 07:18:38 +000083 * \param host Host to connect to
84 * \param port Port to connect to
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020085 * \param proto Protocol: MBEDTLS_NET_PROTO_TCP or MBEDTLS_NET_PROTO_UDP
Paul Bakker13e2dfe2009-07-28 07:18:38 +000086 *
Paul Bakker5121ce52009-01-03 21:22:43 +000087 * \return 0 if successful, or one of:
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +020088 * MBEDTLS_ERR_NET_SOCKET_FAILED,
89 * MBEDTLS_ERR_NET_UNKNOWN_HOST,
90 * MBEDTLS_ERR_NET_CONNECT_FAILED
Manuel Pégourié-Gonnardf5a13122014-03-23 17:38:16 +010091 *
92 * \note Sets the socket in connected mode even with UDP.
Paul Bakker5121ce52009-01-03 21:22:43 +000093 */
Manuel Pégourié-Gonnard91895852015-06-30 13:34:45 +020094int mbedtls_net_connect( mbedtls_net_context *ctx, const char *host, const char *port, int proto );
Paul Bakker5121ce52009-01-03 21:22:43 +000095
96/**
Manuel Pégourié-Gonnardf5a13122014-03-23 17:38:16 +010097 * \brief Create a receiving socket on bind_ip:port in the chosen
98 * protocol. If bind_ip == NULL, all interfaces are bound.
Paul Bakker5121ce52009-01-03 21:22:43 +000099 *
Manuel Pégourié-Gonnard91895852015-06-30 13:34:45 +0200100 * \param ctx Socket to use
Paul Bakker13e2dfe2009-07-28 07:18:38 +0000101 * \param bind_ip IP to bind to, can be NULL
102 * \param port Port number to use
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200103 * \param proto Protocol: MBEDTLS_NET_PROTO_TCP or MBEDTLS_NET_PROTO_UDP
Paul Bakker13e2dfe2009-07-28 07:18:38 +0000104 *
Paul Bakker5121ce52009-01-03 21:22:43 +0000105 * \return 0 if successful, or one of:
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200106 * MBEDTLS_ERR_NET_SOCKET_FAILED,
107 * MBEDTLS_ERR_NET_BIND_FAILED,
108 * MBEDTLS_ERR_NET_LISTEN_FAILED
Manuel Pégourié-Gonnardf5a13122014-03-23 17:38:16 +0100109 *
110 * \note Regardless of the protocol, opens the sockets and binds it.
111 * In addition, make the socket listening if protocol is TCP.
Paul Bakker5121ce52009-01-03 21:22:43 +0000112 */
Manuel Pégourié-Gonnard91895852015-06-30 13:34:45 +0200113int mbedtls_net_bind( mbedtls_net_context *ctx, const char *bind_ip, const char *port, int proto );
Paul Bakker5121ce52009-01-03 21:22:43 +0000114
115/**
Paul Bakker13e2dfe2009-07-28 07:18:38 +0000116 * \brief Accept a connection from a remote client
Paul Bakker5121ce52009-01-03 21:22:43 +0000117 *
Manuel Pégourié-Gonnard91895852015-06-30 13:34:45 +0200118 * \param bind_ctx Relevant socket
119 * \param client_ctx Will contain the connected client socket
Ivan Krylovc501f9c2018-03-28 17:21:54 +0300120 * \param client_ip Will contain the client IP address, can be NULL
Manuel Pégourié-Gonnard0b104b02015-05-14 21:52:40 +0200121 * \param buf_size Size of the client_ip buffer
Ivan Krylovc501f9c2018-03-28 17:21:54 +0300122 * \param ip_len Will receive the size of the client IP written,
123 * can be NULL if client_ip is null
Paul Bakker13e2dfe2009-07-28 07:18:38 +0000124 *
Manuel Pégourié-Gonnard0b104b02015-05-14 21:52:40 +0200125 * \return 0 if successful, or
126 * MBEDTLS_ERR_NET_ACCEPT_FAILED, or
127 * MBEDTLS_ERR_NET_BUFFER_TOO_SMALL if buf_size is too small,
128 * MBEDTLS_ERR_SSL_WANT_READ if bind_fd was set to
Manuel Pégourié-Gonnarddad1ad72015-05-14 21:54:55 +0200129 * non-blocking and accept() would block.
Paul Bakker5121ce52009-01-03 21:22:43 +0000130 */
Manuel Pégourié-Gonnard91895852015-06-30 13:34:45 +0200131int mbedtls_net_accept( mbedtls_net_context *bind_ctx,
132 mbedtls_net_context *client_ctx,
Manuel Pégourié-Gonnard0b104b02015-05-14 21:52:40 +0200133 void *client_ip, size_t buf_size, size_t *ip_len );
Paul Bakker5121ce52009-01-03 21:22:43 +0000134
135/**
136 * \brief Set the socket blocking
137 *
Manuel Pégourié-Gonnard91895852015-06-30 13:34:45 +0200138 * \param ctx Socket to set
Paul Bakker13e2dfe2009-07-28 07:18:38 +0000139 *
Paul Bakker5121ce52009-01-03 21:22:43 +0000140 * \return 0 if successful, or a non-zero error code
141 */
Manuel Pégourié-Gonnard91895852015-06-30 13:34:45 +0200142int mbedtls_net_set_block( mbedtls_net_context *ctx );
Paul Bakker5121ce52009-01-03 21:22:43 +0000143
144/**
145 * \brief Set the socket non-blocking
146 *
Manuel Pégourié-Gonnard91895852015-06-30 13:34:45 +0200147 * \param ctx Socket to set
Paul Bakker13e2dfe2009-07-28 07:18:38 +0000148 *
Paul Bakker5121ce52009-01-03 21:22:43 +0000149 * \return 0 if successful, or a non-zero error code
150 */
Manuel Pégourié-Gonnard91895852015-06-30 13:34:45 +0200151int mbedtls_net_set_nonblock( mbedtls_net_context *ctx );
Paul Bakker5121ce52009-01-03 21:22:43 +0000152
153/**
154 * \brief Portable usleep helper
155 *
Paul Bakker13e2dfe2009-07-28 07:18:38 +0000156 * \param usec Amount of microseconds to sleep
157 *
Paul Bakker5121ce52009-01-03 21:22:43 +0000158 * \note Real amount of time slept will not be less than
159 * select()'s timeout granularity (typically, 10ms).
160 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200161void mbedtls_net_usleep( unsigned long usec );
Paul Bakker5121ce52009-01-03 21:22:43 +0000162
163/**
Paul Bakker13e2dfe2009-07-28 07:18:38 +0000164 * \brief Read at most 'len' characters. If no error occurs,
165 * the actual amount read is returned.
166 *
167 * \param ctx Socket
168 * \param buf The buffer to write to
169 * \param len Maximum length of the buffer
Paul Bakker5121ce52009-01-03 21:22:43 +0000170 *
Manuel Pégourié-Gonnard81abefd2015-05-29 12:53:47 +0200171 * \return the number of bytes received,
Manuel Pégourié-Gonnard88369942015-05-06 16:19:31 +0100172 * or a non-zero error code; with a non-blocking socket,
Manuel Pégourié-Gonnarddad1ad72015-05-14 21:54:55 +0200173 * MBEDTLS_ERR_SSL_WANT_READ indicates read() would block.
Paul Bakker5121ce52009-01-03 21:22:43 +0000174 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200175int mbedtls_net_recv( void *ctx, unsigned char *buf, size_t len );
Paul Bakker5121ce52009-01-03 21:22:43 +0000176
177/**
Paul Bakker13e2dfe2009-07-28 07:18:38 +0000178 * \brief Write at most 'len' characters. If no error occurs,
179 * the actual amount read is returned.
180 *
181 * \param ctx Socket
Paul Bakkerff60ee62010-03-16 21:09:09 +0000182 * \param buf The buffer to read from
183 * \param len The length of the buffer
Paul Bakker5121ce52009-01-03 21:22:43 +0000184 *
Manuel Pégourié-Gonnard81abefd2015-05-29 12:53:47 +0200185 * \return the number of bytes sent,
Manuel Pégourié-Gonnard88369942015-05-06 16:19:31 +0100186 * or a non-zero error code; with a non-blocking socket,
Manuel Pégourié-Gonnarddad1ad72015-05-14 21:54:55 +0200187 * MBEDTLS_ERR_SSL_WANT_WRITE indicates write() would block.
Paul Bakker5121ce52009-01-03 21:22:43 +0000188 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200189int mbedtls_net_send( void *ctx, const unsigned char *buf, size_t len );
Paul Bakker5121ce52009-01-03 21:22:43 +0000190
Manuel Pégourié-Gonnard9d9b0032014-09-18 11:22:45 +0200191/**
192 * \brief Read at most 'len' characters, blocking for at most
193 * 'timeout' seconds. If no error occurs, the actual amount
194 * read is returned.
195 *
196 * \param ctx Socket
197 * \param buf The buffer to write to
198 * \param len Maximum length of the buffer
Manuel Pégourié-Gonnardc8d8e972014-10-01 15:01:39 +0200199 * \param timeout Maximum number of milliseconds to wait for data
Manuel Pégourié-Gonnard07617332015-06-24 23:00:03 +0200200 * 0 means no timeout (wait forever)
Manuel Pégourié-Gonnard9d9b0032014-09-18 11:22:45 +0200201 *
Manuel Pégourié-Gonnard81abefd2015-05-29 12:53:47 +0200202 * \return the number of bytes received,
Manuel Pégourié-Gonnard9d9b0032014-09-18 11:22:45 +0200203 * or a non-zero error code:
Manuel Pégourié-Gonnard88369942015-05-06 16:19:31 +0100204 * MBEDTLS_ERR_SSL_TIMEOUT if the operation timed out,
205 * MBEDTLS_ERR_SSL_WANT_READ if interrupted by a signal.
Manuel Pégourié-Gonnard9d9b0032014-09-18 11:22:45 +0200206 *
207 * \note This function will block (until data becomes available or
208 * timeout is reached) even if the socket is set to
209 * non-blocking. Handling timeouts with non-blocking reads
210 * requires a different strategy.
211 */
Manuel Pégourié-Gonnard2cf5a7c2015-04-08 12:49:31 +0200212int mbedtls_net_recv_timeout( void *ctx, unsigned char *buf, size_t len,
Manuel Pégourié-Gonnardc8d8e972014-10-01 15:01:39 +0200213 uint32_t timeout );
Manuel Pégourié-Gonnard9d9b0032014-09-18 11:22:45 +0200214
Paul Bakker5121ce52009-01-03 21:22:43 +0000215/**
Manuel Pégourié-Gonnard3d7d00a2015-06-30 15:55:03 +0200216 * \brief Gracefully shutdown the connection and free associated data
Paul Bakker13e2dfe2009-07-28 07:18:38 +0000217 *
Manuel Pégourié-Gonnard3d7d00a2015-06-30 15:55:03 +0200218 * \param ctx The context to free
Paul Bakker5121ce52009-01-03 21:22:43 +0000219 */
Manuel Pégourié-Gonnard3d7d00a2015-06-30 15:55:03 +0200220void mbedtls_net_free( mbedtls_net_context *ctx );
Paul Bakker5121ce52009-01-03 21:22:43 +0000221
222#ifdef __cplusplus
223}
224#endif
225
226#endif /* net.h */