Botan  2.7.0
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  * Allow TLS v1.0
129  */
130  virtual bool allow_tls10() const;
131 
132  /**
133  * Allow TLS v1.1
134  */
135  virtual bool allow_tls11() const;
136 
137  /**
138  * Allow TLS v1.2
139  */
140  virtual bool allow_tls12() const;
141 
142  /**
143  * Allow DTLS v1.0
144  */
145  virtual bool allow_dtls10() const;
146 
147  /**
148  * Allow DTLS v1.2
149  */
150  virtual bool allow_dtls12() const;
151 
152  virtual Group_Params default_dh_group() const;
153 
154  /**
155  * Return the minimum DH group size we're willing to use
156  * Default is currently 1024 (insecure), should be 2048
157  */
158  virtual size_t minimum_dh_group_size() const;
159 
160  /**
161  * For ECDSA authenticated ciphersuites, the smallest key size the
162  * client will accept.
163  * This policy is currently only enforced on the server by the client.
164  */
165  virtual size_t minimum_ecdsa_group_size() const;
166 
167  /**
168  * Return the minimum ECDH group size we're willing to use
169  * for key exchange
170  *
171  * Default 255, allowing x25519 and larger
172  * x25519 is the smallest curve we will negotiate
173  * P-521 is the largest
174  */
175  virtual size_t minimum_ecdh_group_size() const;
176 
177  /**
178  * Return the minimum bit size we're willing to accept for RSA
179  * key exchange or server signatures.
180  *
181  * It does not place any requirements on the size of any RSA signature(s)
182  * which were used to check the server certificate. This is only
183  * concerned with the server's public key.
184  *
185  * Default is 2048 which is smallest RSA key size still secure
186  * for medium term security.
187  */
188  virtual size_t minimum_rsa_bits() const;
189 
190  /**
191  * Minimum DSA group size, default 2048 bits
192  */
193  virtual size_t minimum_dsa_group_size() const;
194 
195  /**
196  * Throw an exception if you don't like the peer's key.
197  * Default impl checks the key size against minimum_rsa_bits, minimum_ecdsa_group_size,
198  * or minimum_ecdh_group_size depending on the key's type.
199  * Override if you'd like to perform some other kind of test on
200  * (or logging of) the peer's keys.
201  */
202  virtual void check_peer_key_acceptable(const Public_Key& public_key) const;
203 
204  /**
205  * If this function returns false, unknown SRP/PSK identifiers
206  * will be rejected with an unknown_psk_identifier alert as soon
207  * as the non-existence is identified. Otherwise, a false
208  * identifier value will be used and the protocol allowed to
209  * proceed, causing the handshake to eventually fail without
210  * revealing that the username does not exist on this system.
211  */
212  virtual bool hide_unknown_users() const;
213 
214  /**
215  * Return the allowed lifetime of a session ticket. If 0, session
216  * tickets do not expire until the session ticket key rolls over.
217  * Expired session tickets cannot be used to resume a session.
218  */
219  virtual uint32_t session_ticket_lifetime() const;
220 
221  /**
222  * If this returns a non-empty vector, and DTLS is negotiated,
223  * then we will also attempt to negotiate the SRTP extension from
224  * RFC 5764 using the returned values as the profile ids.
225  */
226  virtual std::vector<uint16_t> srtp_profiles() const;
227 
228  /**
229  * @return true if and only if we are willing to accept this version
230  * Default accepts TLS v1.0 and later or DTLS v1.2 or later.
231  */
232  virtual bool acceptable_protocol_version(Protocol_Version version) const;
233 
234  /**
235  * Returns the more recent protocol version we are willing to
236  * use, for either TLS or DTLS depending on datagram param.
237  * Shouldn't ever need to override this unless you want to allow
238  * a user to disable use of TLS v1.2 (which is *not recommended*)
239  */
240  virtual Protocol_Version latest_supported_version(bool datagram) const;
241 
242  /**
243  * When offering this version, should we send a fallback SCSV?
244  * Default returns true iff version is not the latest version the
245  * policy allows, exists to allow override in case of interop problems.
246  */
247  virtual bool send_fallback_scsv(Protocol_Version version) const;
248 
249  /**
250  * Allows policy to reject any ciphersuites which are undesirable
251  * for whatever reason without having to reimplement ciphersuite_list
252  */
253  virtual bool acceptable_ciphersuite(const Ciphersuite& suite) const;
254 
255  /**
256  * @return true if servers should choose the ciphersuite matching
257  * their highest preference, rather than the clients.
258  * Has no effect on client side.
259  */
260  virtual bool server_uses_own_ciphersuite_preferences() const;
261 
262  /**
263  * Indicates whether the encrypt-then-MAC extension should be negotiated
264  * (RFC 7366)
265  */
266  virtual bool negotiate_encrypt_then_mac() const;
267 
268  /**
269  * Indicates whether certificate status messages should be supported
270  */
271  virtual bool support_cert_status_message() const;
272 
273  /**
274  * Return allowed ciphersuites, in order of preference
275  */
276  virtual std::vector<uint16_t> ciphersuite_list(Protocol_Version version,
277  bool have_srp) const;
278 
279  /**
280  * @return the default MTU for DTLS
281  */
282  virtual size_t dtls_default_mtu() const;
283 
284  /**
285  * @return the initial timeout for DTLS
286  */
287  virtual size_t dtls_initial_timeout() const;
288 
289  /**
290  * @return the maximum timeout for DTLS
291  */
292  virtual size_t dtls_maximum_timeout() const;
293 
294  /**
295  * Convert this policy to a printable format.
296  * @param o stream to be printed to
297  */
298  virtual void print(std::ostream& o) const;
299 
300  /**
301  * Convert this policy to a printable format.
302  * Same as calling `print` on a ostringstream and reading o.str()
303  */
304  std::string to_string() const;
305 
306  virtual ~Policy() = default;
307  };
308 
310 
311 /**
312 * NSA Suite B 128-bit security level (RFC 6460)
313 *
314 * @warning As of August 2015 NSA indicated only the 192-bit Suite B
315 * should be used for all classification levels.
316 */
318  {
319  public:
320  std::vector<std::string> allowed_ciphers() const override
321  { return std::vector<std::string>({"AES-128/GCM"}); }
322 
323  std::vector<std::string> allowed_signature_hashes() const override
324  { return std::vector<std::string>({"SHA-256"}); }
325 
326  std::vector<std::string> allowed_macs() const override
327  { return std::vector<std::string>({"AEAD"}); }
328 
329  std::vector<std::string> allowed_key_exchange_methods() const override
330  { return std::vector<std::string>({"ECDH"}); }
331 
332  std::vector<std::string> allowed_signature_methods() const override
333  { return std::vector<std::string>({"ECDSA"}); }
334 
335  std::vector<Group_Params> key_exchange_groups() const override
336  { return {Group_Params::SECP256R1}; }
337 
338  size_t minimum_signature_strength() const override { return 128; }
339 
340  bool allow_tls10() const override { return false; }
341  bool allow_tls11() const override { return false; }
342  bool allow_tls12() const override { return true; }
343  bool allow_dtls10() const override { return false; }
344  bool allow_dtls12() const override { return false; }
345  };
346 
347 /**
348 * NSA Suite B 192-bit security level (RFC 6460)
349 */
351  {
352  public:
353  std::vector<std::string> allowed_ciphers() const override
354  { return std::vector<std::string>({"AES-256/GCM"}); }
355 
356  std::vector<std::string> allowed_signature_hashes() const override
357  { return std::vector<std::string>({"SHA-384"}); }
358 
359  std::vector<std::string> allowed_macs() const override
360  { return std::vector<std::string>({"AEAD"}); }
361 
362  std::vector<std::string> allowed_key_exchange_methods() const override
363  { return std::vector<std::string>({"ECDH"}); }
364 
365  std::vector<std::string> allowed_signature_methods() const override
366  { return std::vector<std::string>({"ECDSA"}); }
367 
368  std::vector<Group_Params> key_exchange_groups() const override
369  { return {Group_Params::SECP384R1}; }
370 
371  size_t minimum_signature_strength() const override { return 192; }
372 
373  bool allow_tls10() const override { return false; }
374  bool allow_tls11() const override { return false; }
375  bool allow_tls12() const override { return true; }
376  bool allow_dtls10() const override { return false; }
377  bool allow_dtls12() const override { return false; }
378  };
379 
380 /**
381 * BSI TR-02102-2 Policy
382 */
384  {
385  public:
386  std::vector<std::string> allowed_ciphers() const override
387  {
388  return std::vector<std::string>({"AES-256/GCM", "AES-128/GCM", "AES-256", "AES-128" });
389  }
390 
391  std::vector<std::string> allowed_signature_hashes() const override
392  {
393  return std::vector<std::string>({"SHA-384", "SHA-256"});
394  }
395 
396  std::vector<std::string> allowed_macs() const override
397  {
398  return std::vector<std::string>({"AEAD", "SHA-384", "SHA-256"});
399  }
400 
401  std::vector<std::string> allowed_key_exchange_methods() const override
402  {
403  return std::vector<std::string>({"ECDH", "DH", "PSK", "ECDHE_PSK", "DHE_PSK"});
404  }
405 
406  std::vector<std::string> allowed_signature_methods() const override
407  {
408  return std::vector<std::string>({"ECDSA", "RSA", "DSA"});
409  }
410 
411  std::vector<Group_Params> key_exchange_groups() const override
412  {
413  return std::vector<Group_Params>({
424  });
425  }
426 
427  bool allow_insecure_renegotiation() const override { return false; }
428  bool allow_server_initiated_renegotiation() const override { return true; }
429  bool server_uses_own_ciphersuite_preferences() const override { return true; }
430  bool negotiate_encrypt_then_mac() const override { return true; }
431 
432  size_t minimum_rsa_bits() const override { return 2000; }
433  size_t minimum_dh_group_size() const override { return 2000; }
434  size_t minimum_dsa_group_size() const override { return 2000; }
435 
436  size_t minimum_ecdh_group_size() const override { return 250; }
437  size_t minimum_ecdsa_group_size() const override { return 250; }
438 
439  bool allow_tls10() const override { return false; }
440  bool allow_tls11() const override { return false; }
441  bool allow_tls12() const override { return true; }
442  bool allow_dtls10() const override { return false; }
443  bool allow_dtls12() const override { return false; }
444  };
445 
446 /**
447 * Policy for DTLS. We require DTLS v1.2 and an AEAD mode.
448 */
450  {
451  public:
452  std::vector<std::string> allowed_macs() const override
453  { return std::vector<std::string>({"AEAD"}); }
454 
455  bool allow_tls10() const override { return false; }
456  bool allow_tls11() const override { return false; }
457  bool allow_tls12() const override { return false; }
458  bool allow_dtls10() const override { return false; }
459  bool allow_dtls12() const override { return true; }
460  };
461 
462 /*
463 * This policy requires a secure version of TLS and disables all insecure
464 * algorithms. It is compatible with other botan TLSes (including those using the
465 * default policy) and with many other recent implementations. It is a great idea
466 * to use if you control both sides of the protocol and don't have to worry
467 * about ancient and/or bizarre TLS implementations.
468 */
470  {
471  public:
472  std::vector<std::string> allowed_ciphers() const override;
473 
474  std::vector<std::string> allowed_signature_hashes() const override;
475 
476  std::vector<std::string> allowed_macs() const override;
477 
478  std::vector<std::string> allowed_key_exchange_methods() const override;
479 
480  bool allow_tls10() const override;
481  bool allow_tls11() const override;
482  bool allow_tls12() const override;
483  bool allow_dtls10() const override;
484  bool allow_dtls12() const override;
485  };
486 
488  {
489  public:
490 
491  std::vector<std::string> allowed_ciphers() const override;
492 
493  std::vector<std::string> allowed_signature_hashes() const override;
494 
495  std::vector<std::string> allowed_macs() const override;
496 
497  std::vector<std::string> allowed_key_exchange_methods() const override;
498 
499  std::vector<std::string> allowed_signature_methods() const override;
500 
501  std::vector<Group_Params> key_exchange_groups() const override;
502 
503  bool use_ecc_point_compression() const override;
504 
505  bool allow_tls10() const override;
506 
507  bool allow_tls11() const override;
508 
509  bool allow_tls12() const override;
510 
511  bool allow_dtls10() const override;
512 
513  bool allow_dtls12() const override;
514 
515  bool allow_insecure_renegotiation() const override;
516 
517  bool include_time_in_hello_random() const override;
518 
519  bool allow_client_initiated_renegotiation() const override;
520  bool allow_server_initiated_renegotiation() const override;
521 
522  bool server_uses_own_ciphersuite_preferences() const override;
523 
524  bool negotiate_encrypt_then_mac() const override;
525 
526  bool support_cert_status_message() const override;
527 
528  size_t minimum_ecdh_group_size() const override;
529 
530  size_t minimum_ecdsa_group_size() const override;
531 
532  size_t minimum_dh_group_size() const override;
533 
534  size_t minimum_rsa_bits() const override;
535 
536  size_t minimum_signature_strength() const override;
537 
538  size_t dtls_default_mtu() const override;
539 
540  size_t dtls_initial_timeout() const override;
541 
542  size_t dtls_maximum_timeout() const override;
543 
544  bool require_cert_revocation_info() const override;
545 
546  bool hide_unknown_users() const override;
547 
548  uint32_t session_ticket_lifetime() const override;
549 
550  bool send_fallback_scsv(Protocol_Version version) const override;
551 
552  std::vector<uint16_t> srtp_profiles() const override;
553 
554  void set(const std::string& k, const std::string& v);
555 
556  explicit Text_Policy(const std::string& s);
557 
558  explicit Text_Policy(std::istream& in);
559 
560  protected:
561 
562  std::vector<std::string> get_list(const std::string& key,
563  const std::vector<std::string>& def) const;
564 
565  size_t get_len(const std::string& key, size_t def) const;
566 
567  bool get_bool(const std::string& key, bool def) const;
568 
569  std::string get_str(const std::string& key, const std::string& def = "") const;
570 
571  bool set_value(const std::string& key, const std::string& val, bool overwrite);
572 
573  private:
574  std::map<std::string, std::string> m_kv;
575  };
576 
577 }
578 
579 }
580 
581 #endif
std::vector< Group_Params > key_exchange_groups() const override
Definition: tls_policy.h:335
bool allow_tls10() const override
Definition: tls_policy.h:455
bool allow_tls12() const override
Definition: tls_policy.h:441
bool allow_tls12() const override
Definition: tls_policy.h:375
bool allow_dtls10() const override
Definition: tls_policy.h:343
std::vector< std::string > allowed_ciphers() const override
Definition: tls_policy.h:353
std::vector< std::string > allowed_macs() const override
Definition: tls_policy.h:359
std::vector< std::string > allowed_signature_hashes() const override
Definition: tls_policy.h:356
std::vector< std::string > allowed_signature_hashes() const override
Definition: tls_policy.h:323
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:27
bool allow_tls11() const override
Definition: tls_policy.h:456
std::vector< std::string > allowed_macs() const override
Definition: tls_policy.h:452
std::vector< std::string > allowed_signature_methods() const override
Definition: tls_policy.h:365
bool allow_tls12() const override
Definition: tls_policy.h:457
size_t minimum_dsa_group_size() const override
Definition: tls_policy.h:434
bool allow_tls11() const override
Definition: tls_policy.h:374
size_t minimum_signature_strength() const override
Definition: tls_policy.h:338
bool allow_dtls10() const override
Definition: tls_policy.h:442
std::vector< std::string > allowed_macs() const override
Definition: tls_policy.h:326
std::vector< Group_Params > key_exchange_groups() const override
Definition: tls_policy.h:411
bool allow_tls11() const override
Definition: tls_policy.h:440
std::vector< std::string > allowed_signature_methods() const override
Definition: tls_policy.h:332
bool allow_tls10() const override
Definition: tls_policy.h:340
bool allow_dtls12() const override
Definition: tls_policy.h:459
bool allow_server_initiated_renegotiation() const override
Definition: tls_policy.h:428
size_t minimum_ecdh_group_size() const override
Definition: tls_policy.h:436
size_t minimum_dh_group_size() const override
Definition: tls_policy.h:433
Definition: alg_id.cpp:13
bool allow_dtls10() const override
Definition: tls_policy.h:458
bool allow_tls10() const override
Definition: tls_policy.h:439
std::vector< std::string > allowed_macs() const override
Definition: tls_policy.h:396
size_t minimum_signature_strength() const override
Definition: tls_policy.h:371
std::vector< std::string > allowed_ciphers() const override
Definition: tls_policy.h:320
bool allow_dtls12() const override
Definition: tls_policy.h:377
bool allow_tls10() const override
Definition: tls_policy.h:373
std::vector< std::string > allowed_key_exchange_methods() const override
Definition: tls_policy.h:329
std::string to_string(const secure_vector< uint8_t > &bytes)
Definition: stl_util.h:25
size_t minimum_rsa_bits() const override
Definition: tls_policy.h:432
bool allow_tls12() const override
Definition: tls_policy.h:342
std::vector< std::string > allowed_key_exchange_methods() const override
Definition: tls_policy.h:362
bool server_uses_own_ciphersuite_preferences() const override
Definition: tls_policy.h:429
std::vector< std::string > allowed_signature_hashes() const override
Definition: tls_policy.h:391
bool allow_dtls12() const override
Definition: tls_policy.h:443
bool allow_insecure_renegotiation() const override
Definition: tls_policy.h:427
std::vector< std::string > allowed_signature_methods() const override
Definition: tls_policy.h:406
bool allow_tls11() const override
Definition: tls_policy.h:341
bool allow_dtls10() const override
Definition: tls_policy.h:376
bool negotiate_encrypt_then_mac() const override
Definition: tls_policy.h:430
std::vector< std::string > allowed_ciphers() const override
Definition: tls_policy.h:386
size_t minimum_ecdsa_group_size() const override
Definition: tls_policy.h:437
MechanismType hash
std::vector< Group_Params > key_exchange_groups() const override
Definition: tls_policy.h:368
std::vector< std::string > allowed_key_exchange_methods() const override
Definition: tls_policy.h:401
bool allow_dtls12() const override
Definition: tls_policy.h:344
Policy Default_Policy
Definition: tls_policy.h:309