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