1 /* 2 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 3 * 4 * This Source Code Form is subject to the terms of the Mozilla Public 5 * License, v. 2.0. If a copy of the MPL was not distributed with this 6 * file, you can obtain one at https://mozilla.org/MPL/2.0/. 7 * 8 * See the COPYRIGHT file distributed with this work for additional 9 * information regarding copyright ownership. 10 */ 11 12 #pragma once 13 14 #include <isc/mem.h> 15 #include <isc/region.h> 16 #include <isc/result.h> 17 #include <isc/types.h> 18 19 typedef struct ssl_ctx_st isc_tlsctx_t; 20 typedef struct ssl_st isc_tls_t; 21 22 void 23 isc_tlsctx_free(isc_tlsctx_t **ctpx); 24 /*%< 25 * Free a TLS client or server context. 26 * 27 * Requires: 28 *\li 'ctxp' != NULL and '*ctxp' != NULL. 29 */ 30 31 isc_result_t 32 isc_tlsctx_createserver(const char *keyfile, const char *certfile, 33 isc_tlsctx_t **ctxp); 34 /*%< 35 * Set up a TLS server context, using the key and certificate specified in 36 * 'keyfile' and 'certfile', or a self-generated ephemeral key and 37 * certificdate if both 'keyfile' and 'certfile' are NULL. 38 * 39 * Requires: 40 *\li 'ctxp' != NULL and '*ctxp' == NULL. 41 *\li 'keyfile' and 'certfile' are either both NULL or both non-NULL. 42 */ 43 44 isc_result_t 45 isc_tlsctx_createclient(isc_tlsctx_t **ctxp); 46 /*%< 47 * Set up a TLS client context. 48 * 49 * Requires: 50 *\li 'ctxp' != NULL and '*ctxp' == NULL. 51 */ 52 53 typedef enum isc_tls_protocol_version { 54 /* these must be the powers of two */ 55 ISC_TLS_PROTO_VER_1_2 = 1 << 0, 56 ISC_TLS_PROTO_VER_1_3 = 1 << 1, 57 ISC_TLS_PROTO_VER_UNDEFINED, 58 } isc_tls_protocol_version_t; 59 60 void 61 isc_tlsctx_set_protocols(isc_tlsctx_t *ctx, const uint32_t tls_versions); 62 /*%< 63 * Sets the supported TLS protocol versions via the 'tls_versions' bit 64 * set argument (see `isc_tls_protocol_version_t` enum for the 65 * expected values). 66 * 67 * Requires: 68 *\li 'ctx' != NULL; 69 *\li 'tls_versions' != 0. 70 */ 71 72 bool 73 isc_tls_protocol_supported(const isc_tls_protocol_version_t tls_ver); 74 /*%< 75 * Check in runtime that the specified TLS protocol versions is supported. 76 */ 77 78 isc_tls_protocol_version_t 79 isc_tls_protocol_name_to_version(const char *name); 80 /*%< 81 * Convert the protocol version string into the version of 82 * 'isc_tls_protocol_version_t' type. 83 * Requires: 84 *\li 'name' != NULL. 85 */ 86 87 bool 88 isc_tlsctx_load_dhparams(isc_tlsctx_t *ctx, const char *dhparams_file); 89 /*%< 90 * Load Diffie-Hellman parameters file and apply it to the given TLS context 91 * 'ctx'. 92 * 93 * Requires: 94 * \li 'ctx' != NULL; 95 * \li 'dhaprams_file' a valid pointer to a non empty string. 96 */ 97 98 bool 99 isc_tls_cipherlist_valid(const char *cipherlist); 100 /*%< 101 * Check if cipher list string is valid. 102 * 103 * Requires: 104 * \li 'cipherlist' a valid pointer to a non empty string. 105 */ 106 107 void 108 isc_tlsctx_set_cipherlist(isc_tlsctx_t *ctx, const char *cipherlist); 109 /*%< 110 * Set cipher list string for on the given TLS context 'ctx'. 111 * 112 * Requires: 113 * \li 'ctx' != NULL; 114 * \li 'cipherlist' a valid pointer to a non empty string. 115 */ 116 117 void 118 isc_tlsctx_prefer_server_ciphers(isc_tlsctx_t *ctx, const bool prefer); 119 /*%< 120 * Make the given TLS context 'ctx' to prefer or to not prefer 121 * server side ciphers during the ciphers negotiation. 122 * 123 * Requires: 124 * \li 'ctx' != NULL. 125 */ 126 127 void 128 isc_tlsctx_session_tickets(isc_tlsctx_t *ctx, const bool use); 129 /*%< 130 * Enable/Disable stateless session resumptions tickets on the given 131 * TLS context 'ctx' (see RFC5077). 132 * 133 * Requires: 134 * \li 'ctx' != NULL. 135 */ 136 137 isc_tls_t * 138 isc_tls_create(isc_tlsctx_t *ctx); 139 /*%< 140 * Set up the structure to hold data for a new TLS connection. 141 * 142 * Requires: 143 *\li 'ctx' != NULL. 144 */ 145 146 void 147 isc_tls_free(isc_tls_t **tlsp); 148 /*%< 149 * Free a TLS structure. 150 * 151 * Requires: 152 *\li 'tlsp' != NULL and '*tlsp' != NULL. 153 */ 154 155 #if HAVE_LIBNGHTTP2 156 void 157 isc_tlsctx_enable_http2client_alpn(isc_tlsctx_t *ctx); 158 void 159 isc_tlsctx_enable_http2server_alpn(isc_tlsctx_t *ctx); 160 /*%< 161 * 162 * Enable HTTP/2 Application Layer Protocol Negotation for 'ctx'. 163 * 164 * Requires: 165 *\li 'ctx' is not NULL. 166 */ 167 #endif /* HAVE_LIBNGHTTP2 */ 168 169 void 170 isc_tls_get_selected_alpn(isc_tls_t *tls, const unsigned char **alpn, 171 unsigned int *alpnlen); 172 173 #define ISC_TLS_DOT_PROTO_ALPN_ID "dot" 174 #define ISC_TLS_DOT_PROTO_ALPN_ID_LEN 3 175 176 void 177 isc_tlsctx_enable_dot_client_alpn(isc_tlsctx_t *ctx); 178 void 179 isc_tlsctx_enable_dot_server_alpn(isc_tlsctx_t *ctx); 180 /*%< 181 * 182 * Enable DoT Application Layer Protocol Negotation for 'ctx'. 183 * 184 * Requires: 185 *\li 'ctx' is not NULL. 186 */ 187