Botan  2.18.1
Crypto and TLS for C++11
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 
18 namespace Botan {
19 
20 class Public_Key;
21 
22 namespace 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>({
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
std::vector< Group_Params > key_exchange_groups() const override
Definition: tls_policy.h:370
bool allow_tls10() const override
Definition: tls_policy.h:488
bool allow_tls12() const override
Definition: tls_policy.h:474
bool allow_tls12() const override
Definition: tls_policy.h:410
bool allow_dtls10() const override
Definition: tls_policy.h:378
std::vector< std::string > allowed_ciphers() const override
Definition: tls_policy.h:388
std::vector< std::string > allowed_macs() const override
Definition: tls_policy.h:394
std::vector< std::string > allowed_signature_hashes() const override
Definition: tls_policy.h:391
std::vector< std::string > allowed_signature_hashes() const override
Definition: tls_policy.h:358
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:31
bool allow_tls11() const override
Definition: tls_policy.h:489
std::vector< std::string > allowed_macs() const override
Definition: tls_policy.h:485
std::vector< std::string > allowed_signature_methods() const override
Definition: tls_policy.h:400
bool allow_tls12() const override
Definition: tls_policy.h:490
size_t minimum_dsa_group_size() const override
Definition: tls_policy.h:467
bool allow_tls11() const override
Definition: tls_policy.h:409
size_t minimum_signature_strength() const override
Definition: tls_policy.h:373
std::string to_string(ErrorType type)
Convert an ErrorType to string.
Definition: exceptn.cpp:11
bool allow_dtls10() const override
Definition: tls_policy.h:475
std::vector< std::string > allowed_macs() const override
Definition: tls_policy.h:361
std::vector< Group_Params > key_exchange_groups() const override
Definition: tls_policy.h:446
bool allow_tls11() const override
Definition: tls_policy.h:473
std::vector< std::string > allowed_signature_methods() const override
Definition: tls_policy.h:367
bool allow_tls10() const override
Definition: tls_policy.h:375
bool allow_dtls12() const override
Definition: tls_policy.h:492
bool allow_server_initiated_renegotiation() const override
Definition: tls_policy.h:461
size_t minimum_ecdh_group_size() const override
Definition: tls_policy.h:469
size_t minimum_dh_group_size() const override
Definition: tls_policy.h:466
Definition: alg_id.cpp:13
bool allow_dtls10() const override
Definition: tls_policy.h:491
bool allow_tls10() const override
Definition: tls_policy.h:472
std::vector< std::string > allowed_macs() const override
Definition: tls_policy.h:431
size_t minimum_signature_strength() const override
Definition: tls_policy.h:406
std::vector< std::string > allowed_ciphers() const override
Definition: tls_policy.h:355
bool allow_dtls12() const override
Definition: tls_policy.h:412
bool allow_tls10() const override
Definition: tls_policy.h:408
std::vector< std::string > allowed_key_exchange_methods() const override
Definition: tls_policy.h:364
size_t minimum_rsa_bits() const override
Definition: tls_policy.h:465
bool allow_tls12() const override
Definition: tls_policy.h:377
std::vector< std::string > allowed_key_exchange_methods() const override
Definition: tls_policy.h:397
bool server_uses_own_ciphersuite_preferences() const override
Definition: tls_policy.h:462
std::vector< std::string > allowed_signature_hashes() const override
Definition: tls_policy.h:426
bool allow_dtls12() const override
Definition: tls_policy.h:476
bool allow_insecure_renegotiation() const override
Definition: tls_policy.h:460
std::vector< std::string > allowed_signature_methods() const override
Definition: tls_policy.h:441
bool allow_tls11() const override
Definition: tls_policy.h:376
bool allow_dtls10() const override
Definition: tls_policy.h:411
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
size_t minimum_ecdsa_group_size() const override
Definition: tls_policy.h:470
MechanismType hash
std::vector< Group_Params > key_exchange_groups() const override
Definition: tls_policy.h:403
std::vector< std::string > allowed_key_exchange_methods() const override
Definition: tls_policy.h:436
bool allow_dtls12() const override
Definition: tls_policy.h:379
Policy Default_Policy
Definition: tls_policy.h:344