1 /* $NetBSD: transport.h,v 1.3 2025/01/26 16:25:28 christos Exp $ */ 2 3 /* 4 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 5 * 6 * SPDX-License-Identifier: MPL-2.0 7 * 8 * This Source Code Form is subject to the terms of the Mozilla Public 9 * License, v. 2.0. If a copy of the MPL was not distributed with this 10 * file, you can obtain one at https://mozilla.org/MPL/2.0/. 11 * 12 * See the COPYRIGHT file distributed with this work for additional 13 * information regarding copyright ownership. 14 */ 15 16 #pragma once 17 18 #include <isc/tls.h> 19 20 #include <dns/types.h> 21 22 typedef enum { 23 DNS_TRANSPORT_NONE = 0, 24 DNS_TRANSPORT_UDP = 1, 25 DNS_TRANSPORT_TCP = 2, 26 DNS_TRANSPORT_TLS = 3, 27 DNS_TRANSPORT_HTTP = 4, 28 DNS_TRANSPORT_COUNT = 5, 29 } dns_transport_type_t; 30 31 typedef enum { 32 DNS_HTTP_GET = 0, 33 DNS_HTTP_POST = 1, 34 } dns_http_mode_t; 35 36 dns_transport_t * 37 dns_transport_new(const dns_name_t *name, dns_transport_type_t type, 38 dns_transport_list_t *list); 39 /*%< 40 * Create a new transport object with name 'name' and type 'type', 41 * and append it to 'list'. 42 */ 43 44 dns_transport_type_t 45 dns_transport_get_type(const dns_transport_t *transport); 46 char * 47 dns_transport_get_certfile(const dns_transport_t *transport); 48 char * 49 dns_transport_get_keyfile(const dns_transport_t *transport); 50 char * 51 dns_transport_get_cafile(const dns_transport_t *transport); 52 char * 53 dns_transport_get_remote_hostname(const dns_transport_t *transport); 54 char * 55 dns_transport_get_endpoint(const dns_transport_t *transport); 56 dns_http_mode_t 57 dns_transport_get_mode(const dns_transport_t *transport); 58 char * 59 dns_transport_get_ciphers(const dns_transport_t *transport); 60 char * 61 dns_transport_get_cipher_suites(const dns_transport_t *transport); 62 char * 63 dns_transport_get_tlsname(const dns_transport_t *transport); 64 uint32_t 65 dns_transport_get_tls_versions(const dns_transport_t *transport); 66 bool 67 dns_transport_get_prefer_server_ciphers(const dns_transport_t *transport, 68 bool *preferp); 69 bool 70 dns_transport_get_always_verify_remote(dns_transport_t *transport); 71 /*%< 72 * Getter functions: return the type, cert file, key file, CA file, 73 * hostname, HTTP endpoint, HTTP mode (GET or POST), ciphers, cipher suites, 74 * TLS name, TLS version, server ciphers preference mode, and always enabling 75 * authentication mode for 'transport'. 76 * 77 * dns_transport_get_prefer_server_ciphers() returns 'true' is value 78 * was set, 'false' otherwise. The actual value is returned via 79 * 'preferp' pointer. 80 */ 81 82 isc_result_t 83 dns_transport_get_tlsctx(dns_transport_t *transport, const isc_sockaddr_t *peer, 84 isc_tlsctx_cache_t *tlsctx_cache, isc_mem_t *mctx, 85 isc_tlsctx_t **pctx, 86 isc_tlsctx_client_session_cache_t **psess_cache); 87 /*%< 88 * Get the transport's TLS Context and the TLS Client Session Cache associated 89 * with it. 90 * 91 * When neither the TLS hostname, nor the TLS certificates authorities (CA) 92 * file are set for the 'transport', then Opportunistic TLS (no authentication 93 * of the remote peer) will be used, unless the 'always_verify_remote' mode is 94 * enabled on the 'transport', in which case the remote peer will be 95 * authenticated by its IP address using the system's default certificates 96 * authorities store. 97 * 98 * Requires: 99 *\li 'transport' is a valid, 'DNS_TRANSPORT_TLS' type transport. 100 *\li 'peer' is not NULL. 101 *\li 'tlsctx_cache' is not NULL. 102 *\li 'mctx' is not NULL. 103 *\li 'pctx' is not NULL and '*pctx' is NULL. 104 *\li 'psess_cache' is not NULL and '*psess_cache' is NULL. 105 */ 106 107 void 108 dns_transport_set_certfile(dns_transport_t *transport, const char *certfile); 109 void 110 dns_transport_set_keyfile(dns_transport_t *transport, const char *keyfile); 111 void 112 dns_transport_set_cafile(dns_transport_t *transport, const char *cafile); 113 void 114 dns_transport_set_remote_hostname(dns_transport_t *transport, 115 const char *hostname); 116 void 117 dns_transport_set_endpoint(dns_transport_t *transport, const char *endpoint); 118 void 119 dns_transport_set_mode(dns_transport_t *transport, dns_http_mode_t mode); 120 void 121 dns_transport_set_ciphers(dns_transport_t *transport, const char *ciphers); 122 void 123 dns_transport_set_cipher_suites(dns_transport_t *transport, 124 const char *cipher_suites); 125 void 126 dns_transport_set_tlsname(dns_transport_t *transport, const char *tlsname); 127 128 void 129 dns_transport_set_tls_versions(dns_transport_t *transport, 130 const uint32_t tls_versions); 131 void 132 dns_transport_set_prefer_server_ciphers(dns_transport_t *transport, 133 const bool prefer); 134 void 135 dns_transport_set_always_verify_remote(dns_transport_t *transport, 136 const bool always_verify_remote); 137 /*%< 138 * Setter functions: set the type, cert file, key file, CA file, 139 * hostname, HTTP endpoint, HTTP mode (GET or POST), ciphers, cipher suites, TLS 140 *name, TLS version, server ciphers preference mode, and always enabling 141 * authentication mode for 'transport'. 142 * 143 * Requires: 144 *\li 'transport' is valid. 145 *\li 'transport' is of type DNS_TRANSPORT_TLS or DNS_TRANSPORT_HTTP 146 * (for certfile, keyfile, cafile, or hostname). 147 *\li 'transport' is of type DNS_TRANSPORT_HTTP (for endpoint or mode). 148 */ 149 150 void 151 dns_transport_attach(dns_transport_t *source, dns_transport_t **targetp); 152 /*%< 153 * Attach to a transport object. 154 * 155 * Requires: 156 *\li 'source' is a valid transport. 157 *\li 'targetp' is not NULL and '*targetp' is NULL. 158 */ 159 160 void 161 dns_transport_detach(dns_transport_t **transportp); 162 /*%< 163 * Detach a transport object; destroy it if there are no remaining 164 * references. 165 * 166 * Requires: 167 *\li 'transportp' is not NULL. 168 *\li '*transportp' is a valid transport. 169 */ 170 171 dns_transport_t * 172 dns_transport_find(const dns_transport_type_t type, const dns_name_t *name, 173 dns_transport_list_t *list); 174 /*%< 175 * Find a transport matching type 'type' and name `name` in 'list'. 176 * 177 * Requires: 178 *\li 'list' is valid. 179 *\li 'list' contains a table of type 'type' transports. 180 */ 181 182 dns_transport_list_t * 183 dns_transport_list_new(isc_mem_t *mctx); 184 /*%< 185 * Create a new transport list. 186 */ 187 188 void 189 dns_transport_list_attach(dns_transport_list_t *source, 190 dns_transport_list_t **targetp); 191 /*%< 192 * Attach to a transport list. 193 * 194 * Requires: 195 *\li 'source' is a valid transport list. 196 *\li 'targetp' is not NULL and '*targetp' is NULL. 197 */ 198 199 void 200 dns_transport_list_detach(dns_transport_list_t **listp); 201 /*%< 202 * Detach a transport list; destroy it if there are no remaining 203 * references. 204 * 205 * Requires: 206 *\li 'listp' is not NULL. 207 *\li '*listp' is a valid transport list. 208 */ 209
Indexes created Sat Jun 13 00:24:39 UTC 2026