The FreeRADIUS server $Id: a4e7f8c94e8038b7627bcf52356b7ed15955c1d7 $
Loading...
Searching...
No Matches
conf.h
Go to the documentation of this file.
1#pragma once
2/*
3 * This program is free software; you can redistribute it and/or modify
4 * it under the terms of the GNU General Public License as published by
5 * the Free Software Foundation; either version 2 of the License, or
6 * (at your option) any later version.
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License
14 * along with this program; if not, write to the Free Software
15 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
16 */
17#ifdef WITH_TLS
18/**
19 * $Id: d1758b5b1cc0cfe9e4e03bba4570e99c46255dac $
20 *
21 * @file lib/tls/conf.h
22 * @brief Structures for session-resumption management.
23 *
24 * @copyright 2021 Arran Cudbard-Bell (a.cudbardb@freeradius.org)
25 */
26RCSIDH(conf_h, "$Id: d1758b5b1cc0cfe9e4e03bba4570e99c46255dac $")
27
28#include "openssl_user_macros.h"
29
30#include <openssl/ssl.h>
31#include <openssl/err.h>
32
33#ifdef __cplusplus
34extern "C" {
35#endif
36typedef struct fr_tls_conf_s fr_tls_conf_t;
37#ifdef __cplusplus
38}
39#endif
40
41#include "verify.h"
42
43#ifdef __cplusplus
44extern "C" {
45#endif
46
47/** Different chain building modes
48 *
49 */
50typedef enum : uint8_t {
51 FR_TLS_CHAIN_VERIFY_INVALID = 0,
52
53 FR_TLS_CHAIN_VERIFY_HARD, //!< Fail if we can't build a complete chain from
54 ///< the leaf cert back to a root.
55 FR_TLS_CHAIN_VERIFY_SOFT, //!< Warn if we can't build a complete chain from
56 ///< the leaf cert back to a root.
57 FR_TLS_CHAIN_VERIFY_NONE //!< Don't verify/build the chain.
58} fr_tls_chain_verify_mode_t;
59
60/** Structure representing a certificate chain configuration
61 *
62 */
63typedef struct {
64 int file_format; //!< Whether the file is expected to be PEM encoded.
65 ///< This allows us to load multiple chained PEM certificates
66 ///< from a single file.
67
68 char const *certificate_file; //!< Path to certificate.
69
70 char const *password; //!< Password to decrypt the certificate(s).
71 char const *private_key_file; //!< Path to certificate.
72
73 char const **ca_files; //!< Extra certificates to load.
74 fr_tls_chain_verify_mode_t verify_mode; //!< How hard we try to build up a complete certificate
75 ///< chain.
76 bool include_root_ca; //!< Include the root ca in the chain we built.
77
78 /** @name Certificate data
79 *
80 * @{
81 */
82 X509 *leaf; //!< The certificate that we present to the peer, the
83 ///< first certificate in `certificate_file`.
84 STACK_OF(X509) *extra; //!< The remaining certificates in `certificate_file`,
85 ///< then one certificate from each `ca_file`.
86 EVP_PKEY *private_key; //!< The private key from `private_key_file`.
87 fr_unix_time_t valid_until; //!< The earliest notAfter of any certificate in `leaf` or `extra`.
88 /** @} */
89} fr_tls_chain_conf_t;
90
91/** Control what types of session resumption we allow
92 *
93 */
94typedef enum {
95 FR_TLS_TICKET_DISABLED = 0x00, //!< Disabled
96 FR_TLS_TICKET_STATEFUL = 0x01, //!< Session resumption information is stored on the server
97 ///< and an identifier is provided to the client.
98 FR_TLS_TICKET_STATELESS = 0x02, //!< A session ticket is provided to the client.
99 FR_TLS_TICKET_AUTO = FR_TLS_TICKET_STATEFUL | //!< We pick the correct cache type
100 ///< based on the TLS version and current
101 FR_TLS_TICKET_STATELESS ///< configuration.
102} fr_tls_ticket_mode_t;
103
104/** Maximum lifetime of a TLS session ticket.
105 *
106 * RFC 8446 mandates this for TLS. RFC 9190 mandates it for EAP-TLS.
107 */
108#define FR_TLS_MAX_SESSION_LIFETIME (7 * 86400)
109
110/** TLS 1.3 allows for padding, but it needs to be limited.
111 *
112 * Records will be padded to a multiple of the block size. It doesn't
113 * make a lot of sense to allow for large amounts of padding, so we
114 * limit that here.
115 */
116#define FR_TLS_MAX_BLOCK_PADDING (256)
117
118/** TLS 1.3 block sizes are a multiple of 16
119 *
120 * If we padd to any other multiple, then it will end up being 16 anyways.
121 */
122#define FR_TLS_BLOCK_PADDING_MULTIPLE (16)
123
124/** Cache configuration
125 *
126 */
127typedef struct {
128 fr_tls_ticket_mode_t mode; //!< What type of session resumption we're going to use.
129 bool mode_is_auto; //!< The configuration said `auto`. `mode` may have been
130 ///< rewritten to `stateless`, and this field keeps the original.
131
132 tmpl_t *id_name; //!< Context ID to allow multiple sessions stores to be defined.
133 char context_id[SSL_MAX_SSL_SESSION_ID_LENGTH];
134
135 fr_time_delta_t lifetime; //!< The maximum period a session can be resumed after.
136
137 fr_time_delta_t min_lifetime; //!< The minimum lifetime of a session ticket.
138 ///< Tickets which has less than this lifetime are not resumed.
139 bool min_lifetime_is_set; //!< Whether `min_lifetime` came from the configuration
140
141 bool require_extms; //!< Only allow session resumption if the client/server
142 //!< supports the extended master session key. This protects
143 //!< against the triple handshake attack.
144
145 bool require_pfs; //!< Only allow session resumption if a cipher suite that
146 //!< supports perfect forward secrecy.
147
148 uint8_t const *session_ticket_key; //!< Raw input data. Is fed through HKDF to produce the
149 ///< actual session key we use.
150} fr_tls_ticket_conf_t;
151
152/** Certificate verification configuration
153 *
154 */
155typedef struct {
156 fr_tls_verify_mode_t mode; //!< What certificates we apply OpenSSL's pre-validation
157 ///< mode to.
158
159 fr_tls_verify_mode_t attribute_mode; //!< What set of certificates we're going to convert to
160 ///< pairs for verification.
161
162 bool der_decode; //!< Should certificates be passed to the DER decoder.
163} fr_tls_verify_conf_t;
164
165#ifdef PSK_MAX_IDENTITY_LEN
166/** A fixed pre-shared key
167 *
168 * A client sends the identity and uses the key. A server does not
169 * accept any other identity, and uses the key.
170 */
171typedef struct {
172 char const *identity; //!< The identity that selects the key.
173 uint8_t const *key; //!< The key as raw bytes. talloc_array_length()
174 ///< gives the length.
175} fr_tls_psk_conf_t;
176#endif
177
178/* configured values goes right here */
179struct fr_tls_conf_s {
180 CONF_SECTION *virtual_server; //!< The virtual server containing certificate validation
181 ///< policies, and cache control sections.
182
183 fr_tls_chain_conf_t **chains; //!< One or more certificates
184
185 char const *random_file; //!< If set, we read 10K of data (or the complete file)
186 //!< and use it to seed OpenSSL's PRNG.
187 char const *ca_path;
188 char const *ca_file;
189
190 char const *dh_file; //!< File to load DH Parameters from.
191
192 uint32_t verify_depth; //!< Maximum number of certificates we can traverse
193 //!< when attempting to reach the presented certificate
194 //!< from our Root CA.
195 bool disable_single_dh_use;
196
197 float tls_max_version; //!< Maximum TLS version allowed.
198 float tls_min_version; //!< Minimum TLS version allowed.
199
200 uint32_t fragment_size; //!< Maximum record fragment, or record size.
201 uint32_t padding_block_size; //!< for TLS 1.3, pad blocks to multiple of this size.
202 ///< Zero means no padding.
203
204 char const *cipher_list; //!< Acceptable ciphers.
205 char const *cipher_suites; //!< Acceptable TLS 1.3 cipher suites.
206 bool cipher_server_preference; //!< use server preferences for cipher selection
207#ifdef SSL3_FLAGS_NO_RENEGOTIATE_CIPHERS
208 bool allow_renegotiation; //!< Whether or not to allow cipher renegotiation.
209#endif
210 char const *group_list; //!< Supported groups.
211
212 bool require_client_cert;
213
214#ifndef OPENSSL_NO_ECDH
215 char const *ecdh_curve;
216#endif
217
218#ifdef PSK_MAX_IDENTITY_LEN
219 fr_tls_psk_conf_t psk; //!< A fixed pre-shared key. Both fields are NULL when the
220 ///< configuration sets neither `identity` nor `key`.
221#endif
222
223 char const *keylog_file; //!< for SSLKEYLOGFILE functionality.
224
225 fr_tls_ticket_conf_t cache; //!< Session cache configuration.
226 fr_tls_verify_conf_t verify;
227
228 bool delayed_tickets; //!< do we delay session tickets to after application data?
229 bool verify_certificate; //!< Does the "verify certificate" section exist.
230 bool new_session; //!< Does the "new session" section exist.
231 bool establish_session; //!< Does the "establish session" section exist.
232 bool fail_session; //!< Does the "fail session" section exist.
233
234 bool encode_session; //!< Does the "encode session" section exist.
235 bool decode_session; //!< Does the "decode session" section exist.
236 bool load_session; //!< Does the "load session" section exist.
237 bool store_session; //!< Does the "store session" section exist.
238 bool clear_session; //!< Does the "clear session" section exist.
239#ifdef PSK_MAX_IDENTITY_LEN
240 bool load_psk; //!< Does the "load psk" section exist.
241#endif
242 bool client_hello_parse; //!< Should attributes be extracted from Client Hello.
243
244 /** Application Layer Protocol Negotiation
245 *
246 * The ALPN strings (for now) must be set by the application. Only the application knows what the
247 * ALPN strings mean, and how to interpret them. Plus, the ALPN format used by OpenSSL is the raw
248 * wire format, which has a "length" prefix followed by the actual data. That's not trivially
249 * supportable by the configuration file parser.
250 *
251 * What we'd like to do is for the application to provide some kind of array of allowed ALPN
252 * strings, and then use that. The TLS code can then set a flag indicating which string was
253 * negotiated.
254 */
255 unsigned char const *alpn; //!< Protocol names, in the wire format ALPN uses: each
256 ///< name is one length octet followed by that many
257 ///< octets. NULL means we don't use ALPN.
258 size_t sizeof_alpn; //!< Length of `alpn`, which carries no terminator.
259 bool alpn_required; //!< Fail if no ALPN was negotiated.
260
261 /** Underlying transport.
262 *
263 * The TLS library does NOT manage any IO itself. However, it
264 * does need to know whether it's supposed to do TLS or DTLS.
265 * Instead of having a separate flag / enum, we just re-use
266 * SOCK_*. Only the application knows what IO method it's using,
267 * so it has to this field manually, just as with ALPN.
268 *
269 * If it's unset (i.e. zero), then we default to SOCK_STREAM.
270 */
271 int socket_type;
272};
273
274#ifdef __cplusplus
275}
276#endif
277#endif /* WITH_TLS */
#define RCSIDH(h, id)
Definition build.h:604
A section grouping multiple CONF_PAIR.
Definition cf_priv.h:106
unsigned int uint32_t
unsigned char uint8_t
A time delta, a difference in time measured in nanoseconds.
Definition time.h:80
"Unix" time.
Definition time.h:95