1 /** 2 * @file 3 * Application layered TCP/TLS connection API (to be used from TCPIP thread) 4 * 5 * @defgroup altcp_tls TLS layer 6 * @ingroup altcp 7 * This file contains function prototypes for a TLS layer. 8 * A port to ARM mbedtls is provided in the apps/ tree 9 * (LWIP_ALTCP_TLS_MBEDTLS option). 10 */ 11 12 /* 13 * Copyright (c) 2017 Simon Goldschmidt 14 * All rights reserved. 15 * 16 * Redistribution and use in source and binary forms, with or without modification, 17 * are permitted provided that the following conditions are met: 18 * 19 * 1. Redistributions of source code must retain the above copyright notice, 20 * this list of conditions and the following disclaimer. 21 * 2. Redistributions in binary form must reproduce the above copyright notice, 22 * this list of conditions and the following disclaimer in the documentation 23 * and/or other materials provided with the distribution. 24 * 3. The name of the author may not be used to endorse or promote products 25 * derived from this software without specific prior written permission. 26 * 27 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED 28 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 29 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 30 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 31 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 32 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 34 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 35 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY 36 * OF SUCH DAMAGE. 37 * 38 * This file is part of the lwIP TCP/IP stack. 39 * 40 * Author: Simon Goldschmidt <goldsimon@gmx.de> 41 * 42 */ 43 #ifndef LWIP_HDR_ALTCP_TLS_H 44 #define LWIP_HDR_ALTCP_TLS_H 45 46 #include "lwip/opt.h" 47 48 #if LWIP_ALTCP /* don't build if not configured for use in lwipopts.h */ 49 50 #if LWIP_ALTCP_TLS 51 52 #include "lwip/altcp.h" 53 54 #ifdef __cplusplus 55 extern "C" { 56 #endif 57 58 /** @ingroup altcp_tls 59 * ALTCP_TLS configuration handle, content depends on port (e.g. mbedtls) 60 */ 61 struct altcp_tls_config; 62 63 /** @ingroup altcp_tls 64 * Create an ALTCP_TLS server configuration handle prepared for multiple certificates 65 */ 66 struct altcp_tls_config *altcp_tls_create_config_server(uint8_t cert_count); 67 68 /** @ingroup altcp_tls 69 * Add a certificate to an ALTCP_TLS server configuration handle 70 */ 71 err_t altcp_tls_config_server_add_privkey_cert(struct altcp_tls_config *config, 72 const u8_t *privkey, size_t privkey_len, 73 const u8_t *privkey_pass, size_t privkey_pass_len, 74 const u8_t *cert, size_t cert_len); 75 76 /** @ingroup altcp_tls 77 * Create an ALTCP_TLS server configuration handle with one certificate 78 * (short version of calling @ref altcp_tls_create_config_server and 79 * @ref altcp_tls_config_server_add_privkey_cert) 80 */ 81 struct altcp_tls_config *altcp_tls_create_config_server_privkey_cert(const u8_t *privkey, size_t privkey_len, 82 const u8_t *privkey_pass, size_t privkey_pass_len, 83 const u8_t *cert, size_t cert_len); 84 85 /** @ingroup altcp_tls 86 * Create an ALTCP_TLS client configuration handle 87 */ 88 struct altcp_tls_config *altcp_tls_create_config_client(const u8_t *cert, size_t cert_len); 89 90 /** @ingroup altcp_tls 91 * Create an ALTCP_TLS client configuration handle with two-way server/client authentication 92 */ 93 struct altcp_tls_config *altcp_tls_create_config_client_2wayauth(const u8_t *ca, size_t ca_len, const u8_t *privkey, size_t privkey_len, 94 const u8_t *privkey_pass, size_t privkey_pass_len, 95 const u8_t *cert, size_t cert_len); 96 97 /** @ingroup altcp_tls 98 * Free an ALTCP_TLS configuration handle 99 */ 100 void altcp_tls_free_config(struct altcp_tls_config *conf); 101 102 /** @ingroup altcp_tls 103 * Free an ALTCP_TLS global entropy instance. 104 * All ALTCP_TLS configuration are linked to one altcp_tls_entropy_rng structure 105 * that handle an unique system entropy & ctr_drbg instance. 106 * This function allow application to free this altcp_tls_entropy_rng structure 107 * when all configuration referencing it were destroyed. 108 * This function does nothing if some ALTCP_TLS configuration handle are still 109 * active. 110 */ 111 void altcp_tls_free_entropy(void); 112 113 /** @ingroup altcp_tls 114 * Create new ALTCP_TLS layer wrapping an existing pcb as inner connection (e.g. TLS over TCP) 115 */ 116 struct altcp_pcb *altcp_tls_wrap(struct altcp_tls_config *config, struct altcp_pcb *inner_pcb); 117 118 /** @ingroup altcp_tls 119 * Create new ALTCP_TLS pcb and its inner tcp pcb 120 */ 121 struct altcp_pcb *altcp_tls_new(struct altcp_tls_config *config, u8_t ip_type); 122 123 /** @ingroup altcp_tls 124 * Create new ALTCP_TLS layer pcb and its inner tcp pcb. 125 * Same as @ref altcp_tls_new but this allocator function fits to 126 * @ref altcp_allocator_t / @ref altcp_new.\n 127 'arg' must contain a struct altcp_tls_config *. 128 */ 129 struct altcp_pcb *altcp_tls_alloc(void *arg, u8_t ip_type); 130 131 /** @ingroup altcp_tls 132 * Return pointer to internal TLS context so application can tweak it. 133 * Real type depends on port (e.g. mbedtls) 134 */ 135 void *altcp_tls_context(struct altcp_pcb *conn); 136 137 #ifdef __cplusplus 138 } 139 #endif 140 141 #endif /* LWIP_ALTCP_TLS */ 142 #endif /* LWIP_ALTCP */ 143 #endif /* LWIP_HDR_ALTCP_TLS_H */ 144