Botan 2.19.3
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*
6* Botan is released under the Simplified BSD License (see license.txt)
7*/
8
9#ifndef BOTAN_TLS_POLICY_H_
10#define BOTAN_TLS_POLICY_H_
11
12#include <botan/tls_version.h>
13#include <botan/tls_algos.h>
14#include <botan/tls_ciphersuite.h>
15#include <vector>
16#include <map>
17
18namespace Botan {
19
20class Public_Key;
21
22namespace TLS {
23
24/**
25* TLS Policy Base Class
26* Inherit and overload as desired to suit local policy concerns
27*/
29 {
30 public:
31
32 /**
33 * Returns a list of ciphers we are willing to negotiate, in
34 * order of preference.
35 */
36 virtual std::vector<std::string> allowed_ciphers() const;
37
38 /**
39 * Returns a list of hash algorithms we are willing to use for
40 * signatures, in order of preference.
41 */
42 virtual std::vector<std::string> allowed_signature_hashes() const;
43
44 /**
45 * Returns a list of MAC algorithms we are willing to use.
46 */
47 virtual std::vector<std::string> allowed_macs() const;
48
49 /**
50 * Returns a list of key exchange algorithms we are willing to
51 * use, in order of preference. Allowed values: DH, empty string
52 * (representing RSA using server certificate key)
53 */
54 virtual std::vector<std::string> allowed_key_exchange_methods() const;
55
56 /**
57 * Returns a list of signature algorithms we are willing to
58 * use, in order of preference. Allowed values RSA and DSA.
59 */
60 virtual std::vector<std::string> allowed_signature_methods() const;
61
62 virtual std::vector<Signature_Scheme> allowed_signature_schemes() const;
63
64 /**
65 * The minimum signature strength we will accept
66 * Returning 80 allows RSA 1024 and SHA-1. Values larger than 80 disable SHA-1 support.
67 * Returning 110 allows RSA 2048.
68 * Return 128 to force ECC (P-256) or large (~3000 bit) RSA keys.
69 * Default is 110
70 */
71 virtual size_t minimum_signature_strength() const;
72
73 /**
74 * Return if cert revocation info (CRL/OCSP) is required
75 * If true, validation will fail unless a valid CRL or OCSP response
76 * was examined.
77 */
78 virtual bool require_cert_revocation_info() const;
79
80 bool allowed_signature_method(const std::string& sig_method) const;
81 bool allowed_signature_hash(const std::string& hash) const;
82
83 /**
84 * Return list of ECC curves and FFDHE groups we are willing to
85 * use in order of preference.
86 */
87 virtual std::vector<Group_Params> key_exchange_groups() const;
88
89 /**
90 * Request that ECC curve points are sent compressed
91 */
92 virtual bool use_ecc_point_compression() const;
93
94 /**
95 * Select a key exchange group to use, from the list of groups sent by the
96 * peer. If none are acceptable, return Group_Params::NONE
97 */
98 virtual Group_Params choose_key_exchange_group(const std::vector<Group_Params>& peer_groups) const;
99
100 /**
101 * Allow renegotiation even if the counterparty doesn't
102 * support the secure renegotiation extension.
103 *
104 * @warning Changing this to true exposes you to injected
105 * plaintext attacks. Read RFC 5746 for background.
106 */
107 virtual bool allow_insecure_renegotiation() const;
108
109 /**
110 * The protocol dictates that the first 32 bits of the random
111 * field are the current time in seconds. However this allows
112 * client fingerprinting attacks. Set to false to disable, in
113 * which case random bytes will be used instead.
114 */
115 virtual bool include_time_in_hello_random() const;
116
117 /**
118 * Consulted by server side. If true, allows clients to initiate a new handshake
119 */
120 virtual bool allow_client_initiated_renegotiation() const;
121
122 /**
123 * Consulted by client side. If true, allows servers to initiate a new handshake
124 */
125 virtual bool allow_server_initiated_renegotiation() const;
126
127 /**
128 * If true, a request to renegotiate will close the connection with
129 * a fatal alert. Otherwise, a warning alert is sent.
130 */
131 virtual bool abort_connection_on_undesired_renegotiation() const;
132
133 virtual bool only_resume_with_exact_version() const;
134
135 /**
136 * Allow TLS v1.0
137 */
138 virtual bool allow_tls10() const;
139
140 /**
141 * Allow TLS v1.1
142 */
143 virtual bool allow_tls11() const;
144
145 /**
146 * Allow TLS v1.2
147 */
148 virtual bool allow_tls12() const;
149
150 /**
151 * Allow DTLS v1.0
152 */
153 virtual bool allow_dtls10() const;
154
155 /**
156 * Allow DTLS v1.2
157 */
158 virtual bool allow_dtls12() const;
159
160 virtual Group_Params default_dh_group() const;
161
162 /**
163 * Return the minimum DH group size we're willing to use
164 * Default is currently 1024 (insecure), should be 2048
165 */
166 virtual size_t minimum_dh_group_size() const;
167
168 /**
169 * For ECDSA authenticated ciphersuites, the smallest key size the
170 * client will accept.
171 * This policy is currently only enforced on the server by the client.
172 */
173 virtual size_t minimum_ecdsa_group_size() const;
174
175 /**
176 * Return the minimum ECDH group size we're willing to use
177 * for key exchange
178 *
179 * Default 255, allowing x25519 and larger
180 * x25519 is the smallest curve we will negotiate
181 * P-521 is the largest
182 */
183 virtual size_t minimum_ecdh_group_size() const;
184
185 /**
186 * Return the minimum bit size we're willing to accept for RSA
187 * key exchange or server signatures.
188 *
189 * It does not place any requirements on the size of any RSA signature(s)
190 * which were used to check the server certificate. This is only
191 * concerned with the server's public key.
192 *
193 * Default is 2048 which is smallest RSA key size still secure
194 * for medium term security.
195 */
196 virtual size_t minimum_rsa_bits() const;
197
198 /**
199 * Minimum DSA group size, default 2048 bits
200 */
201 virtual size_t minimum_dsa_group_size() const;
202
203 /**
204 * Throw an exception if you don't like the peer's key.
205 * Default impl checks the key size against minimum_rsa_bits, minimum_ecdsa_group_size,
206 * or minimum_ecdh_group_size depending on the key's type.
207 * Override if you'd like to perform some other kind of test on
208 * (or logging of) the peer's keys.
209 */
210 virtual void check_peer_key_acceptable(const Public_Key& public_key) const;
211
212 /**
213 * If this function returns false, unknown SRP/PSK identifiers
214 * will be rejected with an unknown_psk_identifier alert as soon
215 * as the non-existence is identified. Otherwise, a false
216 * identifier value will be used and the protocol allowed to
217 * proceed, causing the handshake to eventually fail without
218 * revealing that the username does not exist on this system.
219 */
220 virtual bool hide_unknown_users() const;
221
222 /**
223 * Return the allowed lifetime of a session ticket. If 0, session
224 * tickets do not expire until the session ticket key rolls over.
225 * Expired session tickets cannot be used to resume a session.
226 */
227 virtual uint32_t session_ticket_lifetime() const;
228
229 /**
230 * If this returns a non-empty vector, and DTLS is negotiated,
231 * then we will also attempt to negotiate the SRTP extension from
232 * RFC 5764 using the returned values as the profile ids.
233 */
234 virtual std::vector<uint16_t> srtp_profiles() const;
235
236 /**
237 * @return true if and only if we are willing to accept this version
238 * Default accepts TLS v1.0 and later or DTLS v1.2 or later.
239 */
240 virtual bool acceptable_protocol_version(Protocol_Version version) const;
241
242 /**
243 * Returns the more recent protocol version we are willing to
244 * use, for either TLS or DTLS depending on datagram param.
245 * Shouldn't ever need to override this unless you want to allow
246 * a user to disable use of TLS v1.2 (which is *not recommended*)
247 */
248 virtual Protocol_Version latest_supported_version(bool datagram) const;
249
250 /**
251 * When offering this version, should we send a fallback SCSV?
252 * Default returns true iff version is not the latest version the
253 * policy allows, exists to allow override in case of interop problems.
254 */
255 virtual bool send_fallback_scsv(Protocol_Version version) const;
256
257 /**
258 * Allows policy to reject any ciphersuites which are undesirable
259 * for whatever reason without having to reimplement ciphersuite_list
260 */
261 virtual bool acceptable_ciphersuite(const Ciphersuite& suite) const;
262
263 /**
264 * @return true if servers should choose the ciphersuite matching
265 * their highest preference, rather than the clients.
266 * Has no effect on client side.
267 */
268 virtual bool server_uses_own_ciphersuite_preferences() const;
269
270 /**
271 * Indicates whether the encrypt-then-MAC extension should be negotiated
272 * (RFC 7366)
273 */
274 virtual bool negotiate_encrypt_then_mac() const;
275
276 /**
277 * Indicates whether certificate status messages should be supported
278 */
279 virtual bool support_cert_status_message() const;
280
281 /**
282 * Indicate if client certificate authentication is required.
283 * If true, then a cert will be requested and if the client does
284 * not send a certificate the connection will be closed.
285 */
286 virtual bool require_client_certificate_authentication() const;
287
288 /**
289 * Indicate if client certificate authentication is requested.
290 * If true, then a cert will be requested.
291 */
292 virtual bool request_client_certificate_authentication() const;
293
294 /**
295 * If true, then allow a DTLS client to restart a connection to the
296 * same server association as described in section 4.2.8 of the DTLS RFC
297 */
298 virtual bool allow_dtls_epoch0_restart() const;
299
300 /**
301 * Return allowed ciphersuites, in order of preference
302 */
303 virtual std::vector<uint16_t> ciphersuite_list(Protocol_Version version,
304 bool have_srp) const;
305
306 /**
307 * @return the default MTU for DTLS
308 */
309 virtual size_t dtls_default_mtu() const;
310
311 /**
312 * @return the initial timeout for DTLS
313 */
314 virtual size_t dtls_initial_timeout() const;
315
316 /**
317 * @return the maximum timeout for DTLS
318 */
319 virtual size_t dtls_maximum_timeout() const;
320
321 /**
322 * @return the maximum size of the certificate chain, in bytes.
323 * Return 0 to disable this and accept any size.
324 */
325 virtual size_t maximum_certificate_chain_size() const;
326
327 virtual bool allow_resumption_for_renegotiation() const;
328
329 /**
330 * Convert this policy to a printable format.
331 * @param o stream to be printed to
332 */
333 virtual void print(std::ostream& o) const;
334
335 /**
336 * Convert this policy to a printable format.
337 * Same as calling `print` on a ostringstream and reading o.str()
338 */
339 std::string to_string() const;
340
341 virtual ~Policy() = default;
342 };
343
345
346/**
347* NSA Suite B 128-bit security level (RFC 6460)
348*
349* @warning As of August 2015 NSA indicated only the 192-bit Suite B
350* should be used for all classification levels.
351*/
353 {
354 public:
355 std::vector<std::string> allowed_ciphers() const override
356 { return std::vector<std::string>({"AES-128/GCM"}); }
357
358 std::vector<std::string> allowed_signature_hashes() const override
359 { return std::vector<std::string>({"SHA-256"}); }
360
361 std::vector<std::string> allowed_macs() const override
362 { return std::vector<std::string>({"AEAD"}); }
363
364 std::vector<std::string> allowed_key_exchange_methods() const override
365 { return std::vector<std::string>({"ECDH"}); }
366
367 std::vector<std::string> allowed_signature_methods() const override
368 { return std::vector<std::string>({"ECDSA"}); }
369
370 std::vector<Group_Params> key_exchange_groups() const override
371 { return {Group_Params::SECP256R1}; }
372
373 size_t minimum_signature_strength() const override { return 128; }
374
375 bool allow_tls10() const override { return false; }
376 bool allow_tls11() const override { return false; }
377 bool allow_tls12() const override { return true; }
378 bool allow_dtls10() const override { return false; }
379 bool allow_dtls12() const override { return false; }
380 };
381
382/**
383* NSA Suite B 192-bit security level (RFC 6460)
384*/
386 {
387 public:
388 std::vector<std::string> allowed_ciphers() const override
389 { return std::vector<std::string>({"AES-256/GCM"}); }
390
391 std::vector<std::string> allowed_signature_hashes() const override
392 { return std::vector<std::string>({"SHA-384"}); }
393
394 std::vector<std::string> allowed_macs() const override
395 { return std::vector<std::string>({"AEAD"}); }
396
397 std::vector<std::string> allowed_key_exchange_methods() const override
398 { return std::vector<std::string>({"ECDH"}); }
399
400 std::vector<std::string> allowed_signature_methods() const override
401 { return std::vector<std::string>({"ECDSA"}); }
402
403 std::vector<Group_Params> key_exchange_groups() const override
404 { return {Group_Params::SECP384R1}; }
405
406 size_t minimum_signature_strength() const override { return 192; }
407
408 bool allow_tls10() const override { return false; }
409 bool allow_tls11() const override { return false; }
410 bool allow_tls12() const override { return true; }
411 bool allow_dtls10() const override { return false; }
412 bool allow_dtls12() const override { return false; }
413 };
414
415/**
416* BSI TR-02102-2 Policy
417*/
419 {
420 public:
421 std::vector<std::string> allowed_ciphers() const override
422 {
423 return std::vector<std::string>({"AES-256/GCM", "AES-128/GCM", "AES-256/CCM", "AES-128/CCM", "AES-256", "AES-128"});
424 }
425
426 std::vector<std::string> allowed_signature_hashes() const override
427 {
428 return std::vector<std::string>({"SHA-512", "SHA-384", "SHA-256"});
429 }
430
431 std::vector<std::string> allowed_macs() const override
432 {
433 return std::vector<std::string>({"AEAD", "SHA-384", "SHA-256"});
434 }
435
436 std::vector<std::string> allowed_key_exchange_methods() const override
437 {
438 return std::vector<std::string>({"ECDH", "DH", "ECDHE_PSK", "DHE_PSK"});
439 }
440
441 std::vector<std::string> allowed_signature_methods() const override
442 {
443 return std::vector<std::string>({"ECDSA", "RSA", "DSA"});
444 }
445
446 std::vector<Group_Params> key_exchange_groups() const override
447 {
448 return std::vector<Group_Params>({
449 Group_Params::BRAINPOOL512R1,
450 Group_Params::BRAINPOOL384R1,
451 Group_Params::BRAINPOOL256R1,
452 Group_Params::SECP384R1,
453 Group_Params::SECP256R1,
454 Group_Params::FFDHE_4096,
455 Group_Params::FFDHE_3072,
456 Group_Params::FFDHE_2048
457 });
458 }
459
460 bool allow_insecure_renegotiation() const override { return false; }
461 bool allow_server_initiated_renegotiation() const override { return true; }
462 bool server_uses_own_ciphersuite_preferences() const override { return true; }
463 bool negotiate_encrypt_then_mac() const override { return true; }
464
465 size_t minimum_rsa_bits() const override { return 2000; }
466 size_t minimum_dh_group_size() const override { return 2000; }
467 size_t minimum_dsa_group_size() const override { return 2000; }
468
469 size_t minimum_ecdh_group_size() const override { return 250; }
470 size_t minimum_ecdsa_group_size() const override { return 250; }
471
472 bool allow_tls10() const override { return false; }
473 bool allow_tls11() const override { return false; }
474 bool allow_tls12() const override { return true; }
475 bool allow_dtls10() const override { return false; }
476 bool allow_dtls12() const override { return false; }
477 };
478
479/**
480* Policy for DTLS. We require DTLS v1.2 and an AEAD mode.
481*/
483 {
484 public:
485 std::vector<std::string> allowed_macs() const override
486 { return std::vector<std::string>({"AEAD"}); }
487
488 bool allow_tls10() const override { return false; }
489 bool allow_tls11() const override { return false; }
490 bool allow_tls12() const override { return false; }
491 bool allow_dtls10() const override { return false; }
492 bool allow_dtls12() const override { return true; }
493 };
494
495/*
496* This policy requires a secure version of TLS and disables all insecure
497* algorithms. It is compatible with other botan TLSes (including those using the
498* default policy) and with many other recent implementations. It is a great idea
499* to use if you control both sides of the protocol and don't have to worry
500* about ancient and/or bizarre TLS implementations.
501*/
503 {
504 public:
505 std::vector<std::string> allowed_ciphers() const override;
506
507 std::vector<std::string> allowed_signature_hashes() const override;
508
509 std::vector<std::string> allowed_macs() const override;
510
511 std::vector<std::string> allowed_key_exchange_methods() const override;
512
513 bool allow_tls10() const override;
514 bool allow_tls11() const override;
515 bool allow_tls12() const override;
516 bool allow_dtls10() const override;
517 bool allow_dtls12() const override;
518 };
519
521 {
522 public:
523
524 std::vector<std::string> allowed_ciphers() const override;
525
526 std::vector<std::string> allowed_signature_hashes() const override;
527
528 std::vector<std::string> allowed_macs() const override;
529
530 std::vector<std::string> allowed_key_exchange_methods() const override;
531
532 std::vector<std::string> allowed_signature_methods() const override;
533
534 std::vector<Group_Params> key_exchange_groups() const override;
535
536 bool use_ecc_point_compression() const override;
537
538 bool allow_tls10() const override;
539
540 bool allow_tls11() const override;
541
542 bool allow_tls12() const override;
543
544 bool allow_dtls10() const override;
545
546 bool allow_dtls12() const override;
547
548 bool allow_insecure_renegotiation() const override;
549
550 bool include_time_in_hello_random() const override;
551
552 bool allow_client_initiated_renegotiation() const override;
553 bool allow_server_initiated_renegotiation() const override;
554
555 bool server_uses_own_ciphersuite_preferences() const override;
556
557 bool negotiate_encrypt_then_mac() const override;
558
559 bool support_cert_status_message() const override;
560
561 bool require_client_certificate_authentication() const override;
562
563 size_t minimum_ecdh_group_size() const override;
564
565 size_t minimum_ecdsa_group_size() const override;
566
567 size_t minimum_dh_group_size() const override;
568
569 size_t minimum_rsa_bits() const override;
570
571 size_t minimum_signature_strength() const override;
572
573 size_t dtls_default_mtu() const override;
574
575 size_t dtls_initial_timeout() const override;
576
577 size_t dtls_maximum_timeout() const override;
578
579 bool require_cert_revocation_info() const override;
580
581 bool hide_unknown_users() const override;
582
583 uint32_t session_ticket_lifetime() const override;
584
585 bool send_fallback_scsv(Protocol_Version version) const override;
586
587 std::vector<uint16_t> srtp_profiles() const override;
588
589 void set(const std::string& k, const std::string& v);
590
591 explicit Text_Policy(const std::string& s);
592
593 explicit Text_Policy(std::istream& in);
594
595 protected:
596
597 std::vector<std::string> get_list(const std::string& key,
598 const std::vector<std::string>& def) const;
599
600 size_t get_len(const std::string& key, size_t def) const;
601
602 bool get_bool(const std::string& key, bool def) const;
603
604 std::string get_str(const std::string& key, const std::string& def = "") const;
605
606 bool set_value(const std::string& key, const std::string& val, bool overwrite);
607
608 private:
609 std::map<std::string, std::string> m_kv;
610 };
611
612}
613
614}
615
616#endif
bool allow_dtls12() const override
Definition tls_policy.h:476
bool allow_tls11() const override
Definition tls_policy.h:473
size_t minimum_ecdh_group_size() const override
Definition tls_policy.h:469
size_t minimum_dsa_group_size() const override
Definition tls_policy.h:467
std::vector< std::string > allowed_signature_hashes() const override
Definition tls_policy.h:426
bool negotiate_encrypt_then_mac() const override
Definition tls_policy.h:463
std::vector< std::string > allowed_ciphers() const override
Definition tls_policy.h:421
std::vector< std::string > allowed_signature_methods() const override
Definition tls_policy.h:441
bool allow_server_initiated_renegotiation() const override
Definition tls_policy.h:461
bool server_uses_own_ciphersuite_preferences() const override
Definition tls_policy.h:462
bool allow_tls10() const override
Definition tls_policy.h:472
bool allow_tls12() const override
Definition tls_policy.h:474
std::vector< std::string > allowed_macs() const override
Definition tls_policy.h:431
size_t minimum_rsa_bits() const override
Definition tls_policy.h:465
bool allow_dtls10() const override
Definition tls_policy.h:475
std::vector< Group_Params > key_exchange_groups() const override
Definition tls_policy.h:446
size_t minimum_dh_group_size() const override
Definition tls_policy.h:466
bool allow_insecure_renegotiation() const override
Definition tls_policy.h:460
size_t minimum_ecdsa_group_size() const override
Definition tls_policy.h:470
std::vector< std::string > allowed_key_exchange_methods() const override
Definition tls_policy.h:436
bool allow_dtls12() const override
Definition tls_policy.h:492
bool allow_dtls10() const override
Definition tls_policy.h:491
bool allow_tls11() const override
Definition tls_policy.h:489
bool allow_tls10() const override
Definition tls_policy.h:488
bool allow_tls12() const override
Definition tls_policy.h:490
std::vector< std::string > allowed_macs() const override
Definition tls_policy.h:485
std::vector< std::string > allowed_macs() const override
Definition tls_policy.h:361
bool allow_dtls12() const override
Definition tls_policy.h:379
bool allow_tls11() const override
Definition tls_policy.h:376
std::vector< Group_Params > key_exchange_groups() const override
Definition tls_policy.h:370
bool allow_tls10() const override
Definition tls_policy.h:375
size_t minimum_signature_strength() const override
Definition tls_policy.h:373
bool allow_dtls10() const override
Definition tls_policy.h:378
std::vector< std::string > allowed_signature_methods() const override
Definition tls_policy.h:367
std::vector< std::string > allowed_key_exchange_methods() const override
Definition tls_policy.h:364
std::vector< std::string > allowed_signature_hashes() const override
Definition tls_policy.h:358
std::vector< std::string > allowed_ciphers() const override
Definition tls_policy.h:355
bool allow_tls12() const override
Definition tls_policy.h:377
bool allow_dtls10() const override
Definition tls_policy.h:411
std::vector< Group_Params > key_exchange_groups() const override
Definition tls_policy.h:403
bool allow_tls10() const override
Definition tls_policy.h:408
bool allow_tls12() const override
Definition tls_policy.h:410
std::vector< std::string > allowed_macs() const override
Definition tls_policy.h:394
bool allow_tls11() const override
Definition tls_policy.h:409
bool allow_dtls12() const override
Definition tls_policy.h:412
std::vector< std::string > allowed_ciphers() const override
Definition tls_policy.h:388
std::vector< std::string > allowed_key_exchange_methods() const override
Definition tls_policy.h:397
size_t minimum_signature_strength() const override
Definition tls_policy.h:406
std::vector< std::string > allowed_signature_methods() const override
Definition tls_policy.h:400
std::vector< std::string > allowed_signature_hashes() const override
Definition tls_policy.h:391
virtual ~Policy()=default
#define BOTAN_PUBLIC_API(maj, min)
Definition compiler.h:31
Policy Default_Policy
Definition tls_policy.h:344
MechanismType hash