Botan 3.14.1
Crypto and TLS for C&
tls_policy.h
Go to the documentation of this file.
1/*
2* Hooks for application level policies on TLS connections
3* (C) 2004-2006,2013 Jack Lloyd
4* 2017 Harry Reimann, Rohde & Schwarz Cybersecurity
5* 2022 René Meusel, Rohde & Schwarz Cybersecurity
6*
7* Botan is released under the Simplified BSD License (see license.txt)
8*/
9
10#ifndef BOTAN_TLS_POLICY_H_
11#define BOTAN_TLS_POLICY_H_
12
13#include <botan/tls_algos.h>
14#include <botan/tls_version.h>
15#include <chrono>
16#include <map>
17#include <optional>
18#include <vector>
19
20namespace Botan {
21
22class Public_Key;
23
24namespace TLS {
25
26class Ciphersuite;
28
29/**
30* TLS Policy Base Class
31* Inherit and overload as desired to suit local policy concerns
32*/
33class BOTAN_PUBLIC_API(2, 0) Policy /* NOLINT(*-special-member-functions) */ {
34 public:
35 /**
36 * Allow ssl key log file
37 * @note If function returns true, then Callbacks::tls_ssl_key_log_data
38 * will be invoked containing secret information for logging purposes
39 */
40 virtual bool allow_ssl_key_log_file() const;
41
42 /**
43 * Returns a list of ciphers we are willing to negotiate, in
44 * order of preference.
45 */
46 virtual std::vector<std::string> allowed_ciphers() const;
47
48 /**
49 * Returns a list of hash algorithms we are willing to use for
50 * signatures, in order of preference.
51 */
52 virtual std::vector<std::string> allowed_signature_hashes() const;
53
54 /**
55 * Returns a list of MAC algorithms we are willing to use.
56 */
57 virtual std::vector<std::string> allowed_macs() const;
58
59 /**
60 * Returns a list of key exchange algorithms we are willing to
61 * use, in order of preference. Allowed values: DH, empty string
62 * (representing RSA using server certificate key)
63 */
64 virtual std::vector<std::string> allowed_key_exchange_methods() const;
65
66 /**
67 * Returns a list of signature algorithms we are willing to
68 * use, in order of preference.
69 */
70 virtual std::vector<std::string> allowed_signature_methods() const;
71
72 /**
73 * Returns a list of signature schemes we are willing to use, in order of
74 * preference. By default, this list contains all supported schemes that
75 * comply with the outputs of allowed_signature_methods() and
76 * allowed_signature_hashes().
77 */
78 virtual std::vector<Signature_Scheme> allowed_signature_schemes() const;
79
80 /**
81 * Return a list of schemes we are willing to accept
82 */
83 virtual std::vector<Signature_Scheme> acceptable_signature_schemes() const;
84
85 /**
86 * Return a list of schemes we are willing to accept for signatures in
87 * certificates.
88 *
89 * By default, the same restrictions as in acceptable_signature_schemes()
90 * apply.
91 *
92 * @return std::nullopt if the same restrictions as defined in
93 * acceptable_signature_schemes() should apply
94 */
95 virtual std::optional<std::vector<Signature_Scheme>> acceptable_certificate_signature_schemes() const;
96
97 /**
98 * The minimum signature strength we will accept
99 *
100 * Returning 80 allows RSA 1024 and SHA-1. Values larger than 80 disable
101 * SHA-1 support. Returning 110 allows RSA 2048. Return 128 to force ECC
102 * (P-256) or large (~3000 bit) RSA keys.
103 *
104 * Default is 110
105 */
106 virtual size_t minimum_signature_strength() const;
107
108 /**
109 * Return if certificate revocation info (CRL/OCSP) is required
110 *
111 * If true, certificates won't be trusted unless a valid CRL or OCSP
112 * response was examined.
113 *
114 * Default: true
115 */
116 virtual bool require_cert_revocation_info() const;
117
118 bool allowed_signature_method(std::string_view sig_method) const;
119 bool allowed_signature_hash(std::string_view hash) const;
120
121 /**
122 * Return a list of ECC curve and DH group TLS identifiers we are willing
123 * to use, in order of preference. The default ordering puts the best
124 * performing ECC first.
125 *
126 * Default: Group_Params::X25519, Group_Params::SECP256R1,
127 * Group_Params::BRAINPOOL256R1, Group_Params::SECP384R1,
128 * Group_Params::BRAINPOOL384R1, Group_Params::SECP521R1,
129 * Group_Params::BRAINPOOL512R1, Group_Params::FFDHE_2048,
130 * Group_Params::FFDHE_3072, Group_Params::FFDHE_4096,
131 * Group_Params::FFDHE_6144, Group_Params::FFDHE_8192
132 *
133 * No other values are currently defined.
134 */
135 virtual std::vector<Group_Params> key_exchange_groups() const;
136
137 /**
138 * Return a list of groups to provide prepared key share offers in the
139 * initial client hello for. Groups in this list must be reflected in
140 * key_exchange_groups() and in the same order.
141 * If an empty list is returned, no prepared key share offers are sent
142 * and the decision of the group to use is left to the server.
143 *
144 * Default: the most preferred group from key_exchange_groups().
145 *
146 * @note Has an effect on TLS 1.3 clients, only.
147 */
148 virtual std::vector<Group_Params> key_exchange_groups_to_offer() const;
149
150 /**
151 * Request that ECC curve points are sent compressed
152 *
153 * Signals that we prefer ECC points to be compressed when transmitted to
154 * us. The other party may not support ECC point compression and therefore
155 * may still send points uncompressed.
156 *
157 * Note that the certificate used during authentication must also follow
158 * the other party's preference.
159 *
160 * @note Support for EC point compression is deprecated and will be removed
161 * in a future major release. TLS 1.3 does not support point compression
162 * at all (see RFC 8446 4.2.8.2)
163 */
164 virtual bool use_ecc_point_compression() const;
165
166 /**
167 * Select a key exchange group to use, from the list of groups sent by the
168 * peer. In TLS 1.3 handshakes the peer might have provided cryptographic material
169 * for a subset of its available groups. Choosing a group for which no share was
170 * provided will result in an additional round trip. If none are acceptable, return
171 * Group_Params::NONE.
172 *
173 * By default this will try to optimize for less round trips even if this results
174 * in the usage of a less preferred group.
175 */
176 virtual Group_Params choose_key_exchange_group(const std::vector<Group_Params>& supported_by_peer,
177 const std::vector<Group_Params>& offered_by_peer) const;
178
179 /**
180 * Allow renegotiation even if the counterparty doesn't support the secure
181 * renegotiation extension.
182 *
183 * Default: false
184 *
185 * @warning Changing this to true exposes you to injected plaintext
186 * attacks. Read RFC 5746 for background.
187 *
188 * @note Has no effect for TLS 1.3 connections.
189 */
190 virtual bool allow_insecure_renegotiation() const;
191
192 /**
193 * The protocol dictates that the first 32 bits of the random
194 * field are the current time in seconds. However this allows
195 * client fingerprinting attacks. Set to false to disable, in
196 * which case random bytes will be used instead.
197 *
198 * Default: true
199 */
200 virtual bool include_time_in_hello_random() const;
201
202 /**
203 * Consulted by server side. If true, allows clients to initiate a new
204 * handshake
205 *
206 * If this function returns true, a server will accept a client-initiated
207 * renegotiation attempt. Otherwise it will send the client a non-fatal
208 * TLS::AlertType::NoRenegotiation alert.
209 *
210 * Default: false
211 *
212 * @note Has no effect for TLS 1.3 connections.
213 */
214 virtual bool allow_client_initiated_renegotiation() const;
215
216 /**
217 * Consulted by client side. If true, allows servers to initiate a new
218 * handshake
219 *
220 * If this function returns true, a client will accept a server-initiated
221 * renegotiation attempt. Otherwise it will send the server a non-fatal
222 * TLS::AlertType::NoRenegotiation alert.
223 *
224 * Default: false
225 *
226 * @note Has no effect for TLS 1.3 connections.
227 */
228 virtual bool allow_server_initiated_renegotiation() const;
229
230 /**
231 * If true, a request to renegotiate will close the connection with
232 * a fatal alert. Otherwise, a warning alert is sent.
233 *
234 * @sa allow_client_initiated_renegotiation
235 * @sa allow_server_initiated_renegotiation
236 *
237 * Default: false
238 *
239 * @note Has no effect for TLS 1.3 connections.
240 */
242
243 /**
244 * Only resume sessions when their original protocol version matches
245 * the current version exactly.
246 *
247 * Default: true
248 */
249 virtual bool only_resume_with_exact_version() const;
250
251 /**
252 * Allow TLS v1.2
253 */
254 virtual bool allow_tls12() const;
255
256 /**
257 * Allow TLS v1.3
258 */
259 virtual bool allow_tls13() const;
260
261 /**
262 * Allow DTLS v1.2
263 */
264 virtual bool allow_dtls12() const;
265
266 /**
267 * For ephemeral Diffie-Hellman key exchange, the server sends a group
268 * parameter. Return the 2 Byte TLS group identifier specifying the group
269 * parameter a server should use.
270 *
271 * Default: 2048 bit IETF IPsec group ("modp/ietf/2048")
272 *
273 * @note Has no effect for TLS 1.3 connections.
274 */
275 virtual Group_Params default_dh_group() const;
276
277 /**
278 * Return the minimum DH group size we're willing to use
279 *
280 * Return the minimum size in bits for a Diffie-Hellman group that a client
281 * will accept. Due to the design of the protocol the client has only two
282 * options - accept the group, or reject it with a fatal alert then attempt
283 * to reconnect after disabling ephemeral Diffie-Hellman.
284 *
285 * Default: 2048 bits
286 *
287 * This only affects the TLS 1.2 client
288 */
289 virtual size_t minimum_dh_group_size() const;
290
291 /**
292 * Largest DH group size (in bits) the client will accept from a server.
293 *
294 * Default: 8192 bits (the largest FFDHE group)
295 *
296 * This only affects the TLS 1.2 client
297 */
298 virtual size_t maximum_dh_group_size() const;
299
300 /**
301 * For ECDSA authenticated ciphersuites, the smallest key size the
302 * client will accept.
303 * This policy is currently only enforced on the server by the client.
304 *
305 * Default: 256
306 */
307 virtual size_t minimum_ecdsa_group_size() const;
308
309 /**
310 * Return the minimum ECDH group size we're willing to use
311 * for key exchange
312 *
313 * Default 255, allowing x25519 and larger
314 * x25519 is the smallest curve we will negotiate
315 * P-521 is the largest
316 */
317 virtual size_t minimum_ecdh_group_size() const;
318
319 /**
320 * Return the minimum bit size we're willing to accept for RSA
321 * key exchange or server signatures.
322 *
323 * It does not place any requirements on the size of any RSA signature(s)
324 * which were used to check the server certificate. This is only
325 * concerned with the server's public key.
326 *
327 * Default is 2048 which is smallest RSA key size still secure
328 * for medium term security.
329 */
330 virtual size_t minimum_rsa_bits() const;
331
332 /**
333 * Allows the policy to examine peer public keys. Throw an exception if the
334 * key should be rejected. Default implementation checks against policy
335 * values minimum_dh_group_size(), minimum_rsa_bits(),
336 * minimum_ecdsa_group_size(), and minimum_ecdh_group_size().
337 *
338 * Override if you'd like to perform some other kind of test on (or logging
339 * of) the peer's keys.
340 */
341 virtual void check_peer_key_acceptable(const Public_Key& public_key) const;
342
343 /**
344 * The PSK suites work using an identifier along with a shared secret. If
345 * this function returns true, when an identifier that the server does not
346 * recognize is provided by a client, a random shared secret will be
347 * generated in such a way that a client should not be able to tell the
348 * difference between the identifier not being known and the secret being
349 * wrong. This can help protect against some username probing attacks. If
350 * it returns false, the server will instead send an
351 * TLS::AlertType::UnknownPSKIdentity alert when an unknown identifier is
352 * used.
353 *
354 * Default: false
355 */
356 virtual bool hide_unknown_users() const;
357
358 /**
359 * Defines the maximum number of session tickets a client might
360 * offer in a single resumption attempt. Must be greater than 0.
361 *
362 * TODO: Currently, the TLS 1.3 client implementation supports
363 * exactly one ticket per handshake. RFC 8446 allows for
364 * an arbitrary amount, though.
365 *
366 * Default: 1
367 *
368 * @note Has an effect on TLS 1.3 connections, only.
369 */
370 virtual size_t maximum_session_tickets_per_client_hello() const;
371
372 /**
373 * Return the allowed lifetime of a session ticket. If 0, session
374 * tickets do not expire until the session ticket key rolls over.
375 * For TLS 1.3 session tickets the lifetime must not be longer than
376 * seven days. Expired session tickets cannot be used to resume a
377 * session.
378 *
379 * Default: 1 day
380 */
381 virtual std::chrono::seconds session_ticket_lifetime() const;
382
383 /**
384 * Decides whether stored session tickets should be used multiple
385 * times (until their lifetime runs out). This might allow passive
386 * observers to correlate connections (RFC 8446 Appendix C.4). This
387 * has no effect on TLS 1.2 resumptions based on session IDs as those
388 * are negotiated in the clear anyway.
389 *
390 * Default: false
391 */
392 virtual bool reuse_session_tickets() const;
393
394 /**
395 * Return the number of new session tickets a TLS 1.3 server should issue
396 * automatically upon a successful handshake. Note that applications can
397 * use `TLS::Server::send_new_session_tickets()` regardless of this policy.
398 *
399 * For convenience (and compatibility with the TLS 1.2 behaviour), this
400 * returns '1' by default.
401 *
402 * @note Has an effect on TLS 1.3 connections, only.
403 */
404 virtual size_t new_session_tickets_upon_handshake_success() const;
405
406 /**
407 * If this returns a non-empty vector, and DTLS is negotiated,
408 * then we will also attempt to negotiate the SRTP extension from
409 * RFC 5764 using the returned values as the profile ids.
410 */
411 virtual std::vector<uint16_t> srtp_profiles() const;
412
413 /**
414 * @return true if and only if we are willing to accept this version
415 * Default accepts TLS v1.2 and later or DTLS v1.2 or later.
416 */
417 virtual bool acceptable_protocol_version(Protocol_Version version) const;
418
419 /**
420 * Returns the most recent protocol version we are willing to
421 * use, for either TLS or DTLS depending on datagram param.
422 * Shouldn't ever need to override this unless you want to allow
423 * a user to disable specific TLS versions.
424 */
425 virtual Protocol_Version latest_supported_version(bool datagram) const;
426
427 /**
428 * Allows policy to reject any ciphersuites which are undesirable
429 * for whatever reason without having to reimplement ciphersuite_list
430 */
431 virtual bool acceptable_ciphersuite(const Ciphersuite& suite) const;
432
433 /**
434 * Default: true
435 *
436 * @return true if servers should choose the ciphersuite matching
437 * their highest preference, rather than the clients.
438 * Has no effect on client side.
439 */
440 virtual bool server_uses_own_ciphersuite_preferences() const;
441
442 /**
443 * Indicates whether the encrypt-then-MAC extension should be negotiated
444 * (RFC 7366)
445 *
446 * @note Has no effect for TLS 1.3 connections.
447 */
448 virtual bool negotiate_encrypt_then_mac() const;
449
450 /**
451 * Require that TLS 1.2 / DTLS 1.2 handshakes use the Extended Master
452 * Secret extension (RFC 7627). When true, both the server and the client
453 * abort fresh handshakes whose peer did not negotiate EMS. RFC 9325 4.4
454 * recommends requiring this extension.
455 *
456 * @note Has no effect for TLS 1.3 connections, where the equivalent
457 * binding is built in.
458 */
459 virtual bool require_extended_master_secret() const;
460
461 /**
462 * Defines the maximum TLS record length for TLS connections.
463 * This is based on the Record Size Limit extension described in RFC 8449.
464 * By default (i.e. if std::nullopt is returned), TLS clients will omit
465 * this extension altogether.
466 *
467 * This value may be between 64 and 16385 (TLS 1.3) or 16384 (TLS 1.2).
468 *
469 * @note This is currently not implemented for TLS 1.2, hence the limit
470 * won't be negotiated by TLS 1.3 clients that support downgrading
471 * to TLS 1.2 (i.e. #allow_tls12() returning true).
472 */
473 virtual std::optional<uint16_t> record_size_limit() const;
474
475 /**
476 * Defines the number of padding octets added to a protected TLS 1.3
477 * record that contains @p plaintext_bytes of plaintext. The plaintext
478 * size is counted like the record size limit, i.e. per RFC 8449 4.:
479 * "The value includes the content type and padding added in TLS 1.3
480 * (that is, the complete length of TLSInnerPlaintext)."
481 *
482 * This may be used to reduce the amount of information leaked by the
483 * length of TLS records.
484 *
485 * Padding that would grow a record beyond the negotiated record size
486 * limit is truncated to reach exactly that limit.
487 *
488 * @note This feature is available in TLS 1.3 only (see RFC 9846 5.4).
489 *
490 * Default: 0 (records are not padded)
491 */
492 virtual size_t record_padding_bytes(size_t plaintext_bytes) const;
493
494 /**
495 * Indicates whether certificate status messages should be supported
496 */
497 virtual bool support_cert_status_message() const;
498
499 /**
500 * Indicate if client certificate authentication is required.
501 * If true, then a cert will be requested and if the client does
502 * not send a certificate the connection will be closed.
503 *
504 * Externally provided PSKs are not used while this is set, and a
505 * session is only resumed if the client authenticated with a
506 * certificate when the session was established.
507 */
509
510 /**
511 * Indicate if client certificate authentication is requested.
512 * If true, then a cert will be requested, but the handshake also
513 * succeeds without one.
514 *
515 * PSKs and session resumption are not restricted by this, so it is
516 * the application's responsibility to check that the peer was
517 * sufficiently authenticated, either by a client certificate or by
518 * the PSK or resumed session.
519 *
520 * Default: the value of require_client_certificate_authentication()
521 */
523
524 /**
525 * Returns a list of accepted certificate types for client authentication
526 * in order of preference. See RFC 7250 and RFC 8446 4.4.2 for details.
527 * Defaults to X509 only.
528 *
529 * Note that it is the application's responsibility to provide public keys
530 * and/or certificates according to the specification in this list via the
531 * Credentials_Manager.
532 */
533 virtual std::vector<Certificate_Type> accepted_client_certificate_types() const;
534
535 /**
536 * Returns a list of accepted certificate types for server authentication
537 * in order of preference. See RFC 7250 and RFC 8446 4.4.2 for details.
538 * Defaults to X509 only.
539 *
540 * Note that it is the application's responsibility to provide public keys
541 * and/or certificates according to the specification in this list via the
542 * Credentials_Manager.
543 */
544 virtual std::vector<Certificate_Type> accepted_server_certificate_types() const;
545
546 /**
547 * If true, then allow a DTLS client to restart a connection to the
548 * same server association as described in section 4.2.8 of the DTLS RFC
549 */
550 virtual bool allow_dtls_epoch0_restart() const;
551
552 /**
553 * DTLS defines an cookie exchange protocol which is used to ensure routability on
554 * the path between the server and client. This is especially useful when using a
555 * connectionless datagram layer like UDP, where a client's source address can
556 * easily be spoofed.
557 *
558 * This cookie exchange prevents abusing the server for DoS amplification attacks,
559 * and additionally provides assurance for the server that the client's purported
560 * address is theirs, which can be helpful for attribution/logging purposes.
561 *
562 * The server creates cookies by hashing the original client hello and the peer's
563 * source address along with a secret key. The cookie value is then sent back to
564 * the client address. The client can then retry the connection, with their updated
565 * client hello including the cookie value. So this cookie exchange implies one
566 * extra round trip during the handshake.
567 *
568 * By default this function returns true. If this function returns true then the
569 * DTLS session cookie `Credentials_Manager::dtls_cookie_secret` must be set, and
570 * `TLS::Callbacks::tls_peer_network_identity` must return a non-empty string.
571 *
572 * It is unsafe to disable this cookie exchange if the server is exposed to
573 * arbitrary Internet traffic.
574 */
575 virtual bool dtls_server_require_cookie_exchange() const;
576
577 /**
578 * Return allowed ciphersuites, in order of preference for the provided
579 * protocol version.
580 *
581 * @param version the exact protocol version to select supported and allowed
582 * ciphersuites for
583 */
584 virtual std::vector<uint16_t> ciphersuite_list(Protocol_Version version) const;
585
586 /**
587 * @return the default MTU for DTLS
588 */
589 virtual size_t dtls_default_mtu() const;
590
591 /**
592 * @return the initial timeout for DTLS
593 */
594 virtual size_t dtls_initial_timeout() const;
595
596 /**
597 * @return the maximum timeout for DTLS
598 */
599 virtual size_t dtls_maximum_timeout() const;
600
601 /**
602 * @return the maximum number of times a DTLS handshake flight will be
603 * retransmitted on timeouts before the handshake is abandoned. After this
604 * many timer-driven retransmissions without progress, timeout_check()
605 * throws to signal the handshake has failed. Return nullopt to retransmit
606 * indefinitely (the historical behavior).
607 *
608 * RFC 6347 4.2.4.1 gives the retransmission timer schedule but states no
609 * condition for giving up, so this bound is local policy rather than a
610 * protocol requirement.
611 */
612 virtual std::optional<size_t> dtls_maximum_retransmissions() const;
613
614 /**
615 * @return the number of HelloVerifyRequest messages a DTLS client will act
616 * on within one handshake before abandoning it. Return nullopt to accept
617 * them without limit; return 0 to reject any cookie exchange.
618 *
619 * RFC 6347 4.2.1 requires more than one to be tolerated: "This may result
620 * in clients receiving multiple HelloVerifyRequest messages with different
621 * cookies. Clients SHOULD handle this by sending a new ClientHello with a
622 * cookie in response to the new HelloVerifyRequest." A HelloVerifyRequest
623 * is unauthenticated and carries no retransmission state of its own, so
624 * without a bound a forged stream of them makes a client re-send its
625 * ClientHello indefinitely.
626 */
627 virtual std::optional<size_t> dtls_maximum_hello_verify_requests() const;
628
629 /**
630 * @return the maximum size of a single handshake message, in bytes.
631 * Messages larger than this will be rejected prior to processing.
632 * Return 0 to disable this and accept any size.
633 */
634 virtual size_t maximum_handshake_message_size() const;
635
636 /**
637 * @return the maximum size of the certificate chain, in bytes.
638 * Return 0 to disable this and accept any size.
639 */
640 virtual size_t maximum_certificate_chain_size() const;
641
642 /**
643 * @return the minimum number of milliseconds that must elapse between
644 * two received KeyUpdate messages. If a KeyUpdate arrives sooner than
645 * this interval after the previous one, the connection is terminated.
646 * A KeyUpdate reciprocating one we sent with "update_requested" is
647 * not counted. Return 0 to disable rate limiting.
648 * @note Only applies to TLS 1.3 connections.
649 */
650 virtual uint64_t minimum_key_update_interval_ms() const;
651
652 /**
653 * @return the maximum number of records to encrypt with a single traffic
654 * key before the channel initiates a KeyUpdate on its own. Such automatic
655 * KeyUpdates request a reciprocal key update from the peer. Return 0 to
656 * disable automatic key updates.
657 * @note Only applies to TLS 1.3 connections.
658 */
659 virtual uint64_t records_per_traffic_key() const;
660
661 /**
662 * @return the maximum number of NewSessionTicket messages to accept
663 * from a server on a single connection. Return 0 to disable the limit.
664 * @note Only applies to TLS 1.3 client connections.
665 */
666 virtual size_t maximum_session_tickets_per_connection() const;
667
668 /**
669 * @return the maximum number of consecutive records received from the
670 * peer which are dropped without any effect: empty records, warning
671 * alerts other than close_notify, and in TLS 1.3 the compatibility mode
672 * ChangeCipherSpec. If more than this many arrive
673 * without some useful record in between, the connection is closed with
674 * an unexpected_message alert. Return std::nullopt to disable the limit.
675 * @note Unauthenticated DTLS records (epoch 0) are not counted.
676 */
677 virtual std::optional<size_t> max_useless_records() const;
678
679 /**
680 * @note Has no effect for TLS 1.3 connections.
681 */
682 virtual bool allow_resumption_for_renegotiation() const;
683
684 /**
685 * Defines whether or not the middlebox compatibility mode should be
686 * used. Enabled by default.
687 *
688 * RFC 8446 Appendix D.4
689 * [This makes] the TLS 1.3 handshake resemble TLS 1.2 session resumption,
690 * which improves the chance of successfully connecting through middleboxes.
691 *
692 * Default: true
693 *
694 * @note Has an effect on TLS 1.3 connections, only.
695 */
696 virtual bool tls_13_middlebox_compatibility_mode() const;
697
698 /**
699 * Hash the RNG output for the client/server hello random. This is a pre-caution
700 * to avoid writing "raw" RNG output to the wire.
701 *
702 * There's not normally a reason to disable this, except when deterministic output
703 * is required for testing.
704 *
705 * Default: true
706 */
707 virtual bool hash_hello_random() const;
708
709 /**
710 * Convert this policy to a printable format.
711 * @param o stream to be printed to
712 */
713 virtual void print(std::ostream& o) const;
714
715 /**
716 * Convert this policy to a printable format.
717 * Same as calling `print` on a ostringstream and reading o.str()
718 */
719 std::string to_string() const;
720
721 virtual ~Policy() = default;
722};
723
725
726/**
727* NSA Suite B 128-bit security level (RFC 6460)
728*
729* @warning As of August 2015 NSA indicated only the 192-bit Suite B
730* should be used for all classification levels.
731*/
733 public:
734 BOTAN_DEPRECATED("This suite is no longer approved") NSA_Suite_B_128() = default;
735
736 std::vector<std::string> allowed_ciphers() const override { return std::vector<std::string>({"AES-128/GCM"}); }
737
738 std::vector<std::string> allowed_signature_hashes() const override {
739 return std::vector<std::string>({"SHA-256"});
740 }
741
742 std::vector<std::string> allowed_macs() const override { return std::vector<std::string>({"AEAD"}); }
743
744 std::vector<std::string> allowed_key_exchange_methods() const override {
745 return std::vector<std::string>({"ECDH"});
746 }
747
748 std::vector<std::string> allowed_signature_methods() const override {
749 return std::vector<std::string>({"ECDSA"});
750 }
751
752 std::vector<Group_Params> key_exchange_groups() const override { return {Group_Params::SECP256R1}; }
753
754 size_t minimum_signature_strength() const override { return 128; }
755
756 bool allow_tls12() const override { return true; }
757
758 bool allow_tls13() const override { return false; }
759
760 bool allow_dtls12() const override { return false; }
761};
762
763/**
764* NSA Suite B 192-bit security level (RFC 6460)
765*/
767 public:
768 std::vector<std::string> allowed_ciphers() const override { return std::vector<std::string>({"AES-256/GCM"}); }
769
770 std::vector<std::string> allowed_signature_hashes() const override {
771 return std::vector<std::string>({"SHA-384"});
772 }
773
774 std::vector<std::string> allowed_macs() const override { return std::vector<std::string>({"AEAD"}); }
775
776 std::vector<std::string> allowed_key_exchange_methods() const override {
777 return std::vector<std::string>({"ECDH"});
778 }
779
780 std::vector<std::string> allowed_signature_methods() const override {
781 return std::vector<std::string>({"ECDSA"});
782 }
783
784 std::vector<Group_Params> key_exchange_groups() const override { return {Group_Params::SECP384R1}; }
785
786 size_t minimum_signature_strength() const override { return 192; }
787
788 bool allow_tls12() const override { return true; }
789
790 bool allow_tls13() const override { return false; }
791
792 bool allow_dtls12() const override { return false; }
793};
794
795/**
796* BSI TR-02102-2 Policy
797*/
799 public:
800 std::vector<std::string> allowed_ciphers() const override {
801 return std::vector<std::string>(
802 {"AES-256/GCM", "AES-128/GCM", "AES-256/CCM", "AES-128/CCM", "AES-256", "AES-128"});
803 }
804
805 std::vector<std::string> allowed_signature_hashes() const override {
806 return std::vector<std::string>({"SHA-512", "SHA-384", "SHA-256"});
807 }
808
809 std::vector<std::string> allowed_macs() const override {
810 return std::vector<std::string>({"AEAD", "SHA-384", "SHA-256"});
811 }
812
813 std::vector<std::string> allowed_key_exchange_methods() const override {
814 return std::vector<std::string>({"ECDH", "DH", "ECDHE_PSK"});
815 }
816
817 std::vector<std::string> allowed_signature_methods() const override {
818 return std::vector<std::string>({"ECDSA", "RSA", "DSA"});
819 }
820
821 std::vector<Group_Params> key_exchange_groups() const override {
822 return std::vector<Group_Params>({Group_Params::BRAINPOOL512R1,
823 Group_Params::BRAINPOOL512R1TLS13,
824 Group_Params::BRAINPOOL384R1,
825 Group_Params::BRAINPOOL384R1TLS13,
826 Group_Params::BRAINPOOL256R1,
827 Group_Params::BRAINPOOL256R1TLS13,
828 Group_Params::SECP521R1,
829 Group_Params::SECP384R1,
830 Group_Params::SECP256R1,
831 Group_Params::FFDHE_4096,
832 Group_Params::FFDHE_3072});
833 }
834
835 size_t minimum_signature_strength() const override { return 120; }
836
837 bool allow_insecure_renegotiation() const override { return false; }
838
839 bool allow_server_initiated_renegotiation() const override { return true; }
840
841 bool server_uses_own_ciphersuite_preferences() const override { return true; }
842
843 bool negotiate_encrypt_then_mac() const override { return true; }
844
845 size_t minimum_rsa_bits() const override { return 3000; }
846
847 size_t minimum_dh_group_size() const override { return 3000; }
848
849 size_t minimum_ecdh_group_size() const override { return 250; }
850
851 size_t minimum_ecdsa_group_size() const override { return 250; }
852
853 bool allow_tls12() const override { return true; }
854
855 bool allow_tls13() const override { return true; }
856
857 bool allow_dtls12() const override { return false; }
858};
859
860/**
861* Policy for DTLS. We require DTLS v1.2 and an AEAD mode.
862*/
864 public:
865 std::vector<std::string> allowed_macs() const override { return std::vector<std::string>({"AEAD"}); }
866
867 bool allow_tls12() const override { return false; }
868
869 bool allow_tls13() const override { return false; }
870
871 bool allow_dtls12() const override { return true; }
872};
873
874/*
875* This policy requires a secure version of TLS and disables all insecure
876* algorithms. It is compatible with other botan TLSes (including those using the
877* default policy) and with many other recent implementations. It is a great idea
878* to use if you control both sides of the protocol and don't have to worry
879* about ancient and/or bizarre TLS implementations.
880*/
882 public:
883 std::vector<std::string> allowed_ciphers() const override;
884
885 std::vector<std::string> allowed_signature_hashes() const override;
886
887 std::vector<std::string> allowed_macs() const override;
888
889 std::vector<std::string> allowed_key_exchange_methods() const override;
890};
891
892class BOTAN_PUBLIC_API(2, 0) Text_Policy : public Policy {
893 public:
894 bool allow_ssl_key_log_file() const override;
895
896 std::vector<std::string> allowed_ciphers() const override;
897
898 std::vector<std::string> allowed_signature_hashes() const override;
899
900 std::vector<std::string> allowed_macs() const override;
901
902 std::vector<std::string> allowed_key_exchange_methods() const override;
903
904 std::vector<std::string> allowed_signature_methods() const override;
905
906 std::vector<Signature_Scheme> allowed_signature_schemes() const override;
907
908 std::vector<Signature_Scheme> acceptable_signature_schemes() const override;
909
910 std::vector<Group_Params> key_exchange_groups() const override;
911
912 std::vector<Group_Params> key_exchange_groups_to_offer() const override;
913
914 bool use_ecc_point_compression() const override;
915
916 bool allow_tls12() const override;
917
918 bool allow_tls13() const override;
919
920 bool allow_dtls12() const override;
921
922 bool allow_insecure_renegotiation() const override;
923
924 bool include_time_in_hello_random() const override;
925
926 bool allow_client_initiated_renegotiation() const override;
927 bool allow_server_initiated_renegotiation() const override;
928
929 bool server_uses_own_ciphersuite_preferences() const override;
930
931 bool negotiate_encrypt_then_mac() const override;
932
933 bool require_extended_master_secret() const override;
934
935 std::optional<uint16_t> record_size_limit() const override;
936
937 size_t record_padding_bytes(size_t plaintext_bytes) const override;
938
939 bool support_cert_status_message() const override;
940
941 bool require_client_certificate_authentication() const override;
942
943 std::vector<Certificate_Type> accepted_client_certificate_types() const override;
944 std::vector<Certificate_Type> accepted_server_certificate_types() const override;
945
946 size_t minimum_ecdh_group_size() const override;
947
948 size_t minimum_ecdsa_group_size() const override;
949
950 size_t minimum_dh_group_size() const override;
951
952 size_t minimum_rsa_bits() const override;
953
954 size_t minimum_signature_strength() const override;
955
956 size_t dtls_default_mtu() const override;
957
958 size_t dtls_initial_timeout() const override;
959
960 size_t dtls_maximum_timeout() const override;
961
962 std::optional<size_t> dtls_maximum_hello_verify_requests() const override;
963
964 std::optional<size_t> max_useless_records() const override;
965
966 bool require_cert_revocation_info() const override;
967
968 bool hide_unknown_users() const override;
969
970 size_t maximum_session_tickets_per_client_hello() const override;
971
972 std::chrono::seconds session_ticket_lifetime() const override;
973
974 bool reuse_session_tickets() const override;
975
976 size_t new_session_tickets_upon_handshake_success() const override;
977
978 uint64_t records_per_traffic_key() const override;
979
980 bool tls_13_middlebox_compatibility_mode() const override;
981
982 bool hash_hello_random() const override;
983
984 std::vector<uint16_t> srtp_profiles() const override;
985
986 void set(const std::string& key, const std::string& value);
987
988 explicit Text_Policy(std::string_view s);
989
990 explicit Text_Policy(std::istream& in);
991
992 protected:
993 std::vector<std::string> get_list(const std::string& key, const std::vector<std::string>& def) const;
994
995 std::vector<Group_Params> read_group_list(std::string_view group_str) const;
996 std::vector<Certificate_Type> read_cert_type_list(const std::string& cert_type_str) const;
997 std::vector<Signature_Scheme> read_sig_scheme_list(std::string_view sig_scheme_str) const;
998
999 size_t get_len(const std::string& key, size_t def) const;
1000
1001 std::chrono::seconds get_duration(const std::string& key, std::chrono::seconds def) const;
1002
1003 bool get_bool(const std::string& key, bool def) const;
1004
1005 std::string get_str(const std::string& key, const std::string& def = "") const;
1006
1007 bool set_value(const std::string& key, std::string_view val, bool overwrite);
1008
1009 private:
1010 std::map<std::string, std::string> m_kv;
1011};
1012
1013} // namespace TLS
1014
1015} // namespace Botan
1016
1017#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
#define BOTAN_DEPRECATED(msg)
Definition api.h:73
bool allow_dtls12() const override
Definition tls_policy.h:857
size_t minimum_ecdh_group_size() const override
Definition tls_policy.h:849
std::vector< std::string > allowed_signature_hashes() const override
Definition tls_policy.h:805
bool negotiate_encrypt_then_mac() const override
Definition tls_policy.h:843
std::vector< std::string > allowed_ciphers() const override
Definition tls_policy.h:800
std::vector< std::string > allowed_signature_methods() const override
Definition tls_policy.h:817
bool allow_server_initiated_renegotiation() const override
Definition tls_policy.h:839
bool server_uses_own_ciphersuite_preferences() const override
Definition tls_policy.h:841
bool allow_tls12() const override
Definition tls_policy.h:853
std::vector< std::string > allowed_macs() const override
Definition tls_policy.h:809
size_t minimum_rsa_bits() const override
Definition tls_policy.h:845
bool allow_tls13() const override
Definition tls_policy.h:855
std::vector< Group_Params > key_exchange_groups() const override
Definition tls_policy.h:821
size_t minimum_dh_group_size() const override
Definition tls_policy.h:847
bool allow_insecure_renegotiation() const override
Definition tls_policy.h:837
size_t minimum_ecdsa_group_size() const override
Definition tls_policy.h:851
std::vector< std::string > allowed_key_exchange_methods() const override
Definition tls_policy.h:813
size_t minimum_signature_strength() const override
Definition tls_policy.h:835
bool allow_dtls12() const override
Definition tls_policy.h:871
bool allow_tls13() const override
Definition tls_policy.h:869
bool allow_tls12() const override
Definition tls_policy.h:867
std::vector< std::string > allowed_macs() const override
Definition tls_policy.h:865
std::vector< std::string > allowed_macs() const override
Definition tls_policy.h:742
bool allow_dtls12() const override
Definition tls_policy.h:760
std::vector< Group_Params > key_exchange_groups() const override
Definition tls_policy.h:752
size_t minimum_signature_strength() const override
Definition tls_policy.h:754
std::vector< std::string > allowed_signature_methods() const override
Definition tls_policy.h:748
std::vector< std::string > allowed_key_exchange_methods() const override
Definition tls_policy.h:744
std::vector< std::string > allowed_signature_hashes() const override
Definition tls_policy.h:738
std::vector< std::string > allowed_ciphers() const override
Definition tls_policy.h:736
bool allow_tls12() const override
Definition tls_policy.h:756
bool allow_tls13() const override
Definition tls_policy.h:758
std::vector< Group_Params > key_exchange_groups() const override
Definition tls_policy.h:784
bool allow_tls12() const override
Definition tls_policy.h:788
bool allow_tls13() const override
Definition tls_policy.h:790
std::vector< std::string > allowed_macs() const override
Definition tls_policy.h:774
bool allow_dtls12() const override
Definition tls_policy.h:792
std::vector< std::string > allowed_ciphers() const override
Definition tls_policy.h:768
std::vector< std::string > allowed_key_exchange_methods() const override
Definition tls_policy.h:776
size_t minimum_signature_strength() const override
Definition tls_policy.h:786
std::vector< std::string > allowed_signature_methods() const override
Definition tls_policy.h:780
std::vector< std::string > allowed_signature_hashes() const override
Definition tls_policy.h:770
virtual bool include_time_in_hello_random() const
virtual void check_peer_key_acceptable(const Public_Key &public_key) const
virtual bool abort_connection_on_undesired_renegotiation() const
virtual size_t maximum_dh_group_size() const
virtual size_t dtls_maximum_timeout() const
virtual size_t minimum_ecdh_group_size() const
virtual size_t maximum_handshake_message_size() const
virtual size_t record_padding_bytes(size_t plaintext_bytes) const
virtual size_t dtls_default_mtu() const
virtual std::optional< size_t > max_useless_records() const
virtual bool allow_tls12() const
virtual std::vector< Signature_Scheme > allowed_signature_schemes() const
std::string to_string() const
virtual bool reuse_session_tickets() const
virtual std::vector< uint16_t > ciphersuite_list(Protocol_Version version) const
virtual std::vector< Certificate_Type > accepted_server_certificate_types() const
virtual std::vector< Certificate_Type > accepted_client_certificate_types() const
bool allowed_signature_method(std::string_view sig_method) const
virtual bool require_client_certificate_authentication() const
virtual std::vector< Group_Params > key_exchange_groups() const
virtual size_t new_session_tickets_upon_handshake_success() const
virtual uint64_t records_per_traffic_key() const
virtual std::vector< Group_Params > key_exchange_groups_to_offer() const
bool allowed_signature_hash(std::string_view hash) const
virtual size_t minimum_rsa_bits() const
virtual std::optional< size_t > dtls_maximum_hello_verify_requests() const
virtual bool tls_13_middlebox_compatibility_mode() const
virtual bool only_resume_with_exact_version() const
virtual bool allow_client_initiated_renegotiation() const
virtual std::optional< size_t > dtls_maximum_retransmissions() const
virtual bool allow_ssl_key_log_file() const
virtual ~Policy()=default
virtual bool allow_dtls_epoch0_restart() const
virtual bool request_client_certificate_authentication() const
virtual bool require_cert_revocation_info() const
virtual bool negotiate_encrypt_then_mac() const
virtual bool require_extended_master_secret() const
virtual bool server_uses_own_ciphersuite_preferences() const
virtual Protocol_Version latest_supported_version(bool datagram) const
virtual bool acceptable_protocol_version(Protocol_Version version) const
virtual std::vector< uint16_t > srtp_profiles() const
virtual bool support_cert_status_message() const
virtual bool acceptable_ciphersuite(const Ciphersuite &suite) const
virtual std::vector< std::string > allowed_macs() const
virtual bool hide_unknown_users() const
virtual std::optional< std::vector< Signature_Scheme > > acceptable_certificate_signature_schemes() const
virtual bool hash_hello_random() const
virtual bool allow_tls13() const
virtual std::vector< std::string > allowed_key_exchange_methods() const
virtual size_t dtls_initial_timeout() const
virtual size_t maximum_session_tickets_per_connection() const
virtual size_t maximum_session_tickets_per_client_hello() const
virtual std::vector< Signature_Scheme > acceptable_signature_schemes() const
virtual bool use_ecc_point_compression() const
virtual bool allow_dtls12() const
virtual size_t minimum_dh_group_size() const
virtual bool allow_insecure_renegotiation() const
virtual std::optional< uint16_t > record_size_limit() const
virtual std::vector< std::string > allowed_ciphers() const
virtual std::chrono::seconds session_ticket_lifetime() const
virtual size_t minimum_signature_strength() const
virtual uint64_t minimum_key_update_interval_ms() const
virtual Group_Params default_dh_group() const
virtual bool dtls_server_require_cookie_exchange() const
virtual size_t maximum_certificate_chain_size() const
virtual std::vector< std::string > allowed_signature_methods() const
virtual size_t minimum_ecdsa_group_size() const
virtual Group_Params choose_key_exchange_group(const std::vector< Group_Params > &supported_by_peer, const std::vector< Group_Params > &offered_by_peer) const
virtual bool allow_resumption_for_renegotiation() const
virtual std::vector< std::string > allowed_signature_hashes() const
virtual bool allow_server_initiated_renegotiation() const
virtual void print(std::ostream &o) const
std::vector< std::string > allowed_macs() const override
std::vector< std::string > allowed_ciphers() const override
std::vector< std::string > allowed_key_exchange_methods() const override
std::vector< std::string > allowed_signature_hashes() const override
size_t dtls_initial_timeout() const override
bool allow_dtls12() const override
bool server_uses_own_ciphersuite_preferences() const override
bool hash_hello_random() const override
std::chrono::seconds session_ticket_lifetime() const override
size_t record_padding_bytes(size_t plaintext_bytes) const override
std::optional< uint16_t > record_size_limit() const override
bool allow_ssl_key_log_file() const override
bool include_time_in_hello_random() const override
bool allow_client_initiated_renegotiation() const override
std::string get_str(const std::string &key, const std::string &def="") const
bool support_cert_status_message() const override
std::vector< std::string > allowed_signature_methods() const override
std::vector< Group_Params > key_exchange_groups() const override
bool require_cert_revocation_info() const override
std::vector< std::string > allowed_key_exchange_methods() const override
size_t minimum_ecdsa_group_size() const override
bool set_value(const std::string &key, std::string_view val, bool overwrite)
bool allow_tls13() const override
size_t maximum_session_tickets_per_client_hello() const override
std::vector< Certificate_Type > accepted_server_certificate_types() const override
std::vector< Group_Params > key_exchange_groups_to_offer() const override
std::chrono::seconds get_duration(const std::string &key, std::chrono::seconds def) const
size_t new_session_tickets_upon_handshake_success() const override
bool require_extended_master_secret() const override
std::vector< std::string > allowed_signature_hashes() const override
std::vector< uint16_t > srtp_profiles() const override
bool hide_unknown_users() const override
std::vector< std::string > allowed_ciphers() const override
Text_Policy(std::string_view s)
size_t minimum_ecdh_group_size() const override
void set(const std::string &key, const std::string &value)
bool allow_server_initiated_renegotiation() const override
bool get_bool(const std::string &key, bool def) const
size_t minimum_signature_strength() const override
std::vector< Certificate_Type > accepted_client_certificate_types() const override
uint64_t records_per_traffic_key() const override
bool negotiate_encrypt_then_mac() const override
std::optional< size_t > dtls_maximum_hello_verify_requests() const override
bool require_client_certificate_authentication() const override
std::optional< size_t > max_useless_records() const override
bool tls_13_middlebox_compatibility_mode() const override
std::vector< Signature_Scheme > acceptable_signature_schemes() const override
size_t dtls_maximum_timeout() const override
bool reuse_session_tickets() const override
size_t get_len(const std::string &key, size_t def) const
bool allow_insecure_renegotiation() const override
bool allow_tls12() const override
std::vector< Signature_Scheme > allowed_signature_schemes() const override
bool use_ecc_point_compression() const override
std::vector< Certificate_Type > read_cert_type_list(const std::string &cert_type_str) const
std::vector< Signature_Scheme > read_sig_scheme_list(std::string_view sig_scheme_str) const
size_t dtls_default_mtu() const override
std::vector< Group_Params > read_group_list(std::string_view group_str) const
size_t minimum_rsa_bits() const override
std::vector< std::string > allowed_macs() const override
size_t minimum_dh_group_size() const override
std::vector< std::string > get_list(const std::string &key, const std::vector< std::string > &def) const
Policy Default_Policy
Definition tls_policy.h:724