Botan  2.6.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 */
315  {
316  public:
317  std::vector<std::string> allowed_ciphers() const override
318  { return std::vector<std::string>({"AES-128/GCM"}); }
319 
320  std::vector<std::string> allowed_signature_hashes() const override
321  { return std::vector<std::string>({"SHA-256"}); }
322 
323  std::vector<std::string> allowed_macs() const override
324  { return std::vector<std::string>({"AEAD"}); }
325 
326  std::vector<std::string> allowed_key_exchange_methods() const override
327  { return std::vector<std::string>({"ECDH"}); }
328 
329  std::vector<std::string> allowed_signature_methods() const override
330  { return std::vector<std::string>({"ECDSA"}); }
331 
332  std::vector<Group_Params> key_exchange_groups() const override
333  { return {Group_Params::SECP256R1}; }
334 
335  size_t minimum_signature_strength() const override { return 128; }
336 
337  bool allow_tls10() const override { return false; }
338  bool allow_tls11() const override { return false; }
339  bool allow_tls12() const override { return true; }
340  bool allow_dtls10() const override { return false; }
341  bool allow_dtls12() const override { return false; }
342  };
343 
344 /**
345 * BSI TR-02102-2 Policy
346 */
348  {
349  public:
350  std::vector<std::string> allowed_ciphers() const override
351  {
352  return std::vector<std::string>({"AES-256/GCM", "AES-128/GCM", "AES-256", "AES-128" });
353  }
354 
355  std::vector<std::string> allowed_signature_hashes() const override
356  {
357  return std::vector<std::string>({"SHA-384", "SHA-256"});
358  }
359 
360  std::vector<std::string> allowed_macs() const override
361  {
362  return std::vector<std::string>({"AEAD", "SHA-384", "SHA-256"});
363  }
364 
365  std::vector<std::string> allowed_key_exchange_methods() const override
366  {
367  return std::vector<std::string>({"ECDH", "DH", "PSK", "ECDHE_PSK", "DHE_PSK"});
368  }
369 
370  std::vector<std::string> allowed_signature_methods() const override
371  {
372  return std::vector<std::string>({"ECDSA", "RSA", "DSA"});
373  }
374 
375  std::vector<Group_Params> key_exchange_groups() const override
376  {
377  return std::vector<Group_Params>({
388  });
389  }
390 
391  bool allow_insecure_renegotiation() const override { return false; }
392  bool allow_server_initiated_renegotiation() const override { return true; }
393  bool server_uses_own_ciphersuite_preferences() const override { return true; }
394  bool negotiate_encrypt_then_mac() const override { return true; }
395 
396  size_t minimum_rsa_bits() const override { return 2000; }
397  size_t minimum_dh_group_size() const override { return 2000; }
398  size_t minimum_dsa_group_size() const override { return 2000; }
399 
400  size_t minimum_ecdh_group_size() const override { return 250; }
401  size_t minimum_ecdsa_group_size() const override { return 250; }
402 
403  bool allow_tls10() const override { return false; }
404  bool allow_tls11() const override { return false; }
405  bool allow_tls12() const override { return true; }
406  bool allow_dtls10() const override { return false; }
407  bool allow_dtls12() const override { return false; }
408  };
409 
410 /**
411 * Policy for DTLS. We require DTLS v1.2 and an AEAD mode.
412 */
414  {
415  public:
416  std::vector<std::string> allowed_macs() const override
417  { return std::vector<std::string>({"AEAD"}); }
418 
419  bool allow_tls10() const override { return false; }
420  bool allow_tls11() const override { return false; }
421  bool allow_tls12() const override { return false; }
422  bool allow_dtls10() const override { return false; }
423  bool allow_dtls12() const override { return true; }
424  };
425 
426 /*
427 * This policy requires a secure version of TLS and disables all insecure
428 * algorithms. It is compatible with other botan TLSes (including those using the
429 * default policy) and with many other recent implementations. It is a great idea
430 * to use if you control both sides of the protocol and don't have to worry
431 * about ancient and/or bizarre TLS implementations.
432 */
434  {
435  public:
436  std::vector<std::string> allowed_ciphers() const override;
437 
438  std::vector<std::string> allowed_signature_hashes() const override;
439 
440  std::vector<std::string> allowed_macs() const override;
441 
442  std::vector<std::string> allowed_key_exchange_methods() const override;
443 
444  bool allow_tls10() const override;
445  bool allow_tls11() const override;
446  bool allow_tls12() const override;
447  bool allow_dtls10() const override;
448  bool allow_dtls12() const override;
449  };
450 
452  {
453  public:
454 
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  std::vector<std::string> allowed_signature_methods() const override;
464 
465  std::vector<Group_Params> key_exchange_groups() const override;
466 
467  bool use_ecc_point_compression() const override;
468 
469  bool allow_tls10() const override;
470 
471  bool allow_tls11() const override;
472 
473  bool allow_tls12() const override;
474 
475  bool allow_dtls10() const override;
476 
477  bool allow_dtls12() const override;
478 
479  bool allow_insecure_renegotiation() const override;
480 
481  bool include_time_in_hello_random() const override;
482 
483  bool allow_client_initiated_renegotiation() const override;
484  bool allow_server_initiated_renegotiation() const override;
485 
486  bool server_uses_own_ciphersuite_preferences() const override;
487 
488  bool negotiate_encrypt_then_mac() const override;
489 
490  bool support_cert_status_message() const override;
491 
492  size_t minimum_ecdh_group_size() const override;
493 
494  size_t minimum_ecdsa_group_size() const override;
495 
496  size_t minimum_dh_group_size() const override;
497 
498  size_t minimum_rsa_bits() const override;
499 
500  size_t minimum_signature_strength() const override;
501 
502  size_t dtls_default_mtu() const override;
503 
504  size_t dtls_initial_timeout() const override;
505 
506  size_t dtls_maximum_timeout() const override;
507 
508  bool require_cert_revocation_info() const override;
509 
510  bool hide_unknown_users() const override;
511 
512  uint32_t session_ticket_lifetime() const override;
513 
514  bool send_fallback_scsv(Protocol_Version version) const override;
515 
516  std::vector<uint16_t> srtp_profiles() const override;
517 
518  void set(const std::string& k, const std::string& v);
519 
520  explicit Text_Policy(const std::string& s);
521 
522  explicit Text_Policy(std::istream& in);
523 
524  protected:
525 
526  std::vector<std::string> get_list(const std::string& key,
527  const std::vector<std::string>& def) const;
528 
529  size_t get_len(const std::string& key, size_t def) const;
530 
531  bool get_bool(const std::string& key, bool def) const;
532 
533  std::string get_str(const std::string& key, const std::string& def = "") const;
534 
535  bool set_value(const std::string& key, const std::string& val, bool overwrite);
536 
537  private:
538  std::map<std::string, std::string> m_kv;
539  };
540 
541 }
542 
543 }
544 
545 #endif
std::vector< Group_Params > key_exchange_groups() const override
Definition: tls_policy.h:332
bool allow_tls10() const override
Definition: tls_policy.h:419
bool allow_tls12() const override
Definition: tls_policy.h:405
bool allow_dtls10() const override
Definition: tls_policy.h:340
std::vector< std::string > allowed_signature_hashes() const override
Definition: tls_policy.h:320
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:27
bool allow_tls11() const override
Definition: tls_policy.h:420
std::vector< std::string > allowed_macs() const override
Definition: tls_policy.h:416
bool allow_tls12() const override
Definition: tls_policy.h:421
size_t minimum_dsa_group_size() const override
Definition: tls_policy.h:398
size_t minimum_signature_strength() const override
Definition: tls_policy.h:335
bool allow_dtls10() const override
Definition: tls_policy.h:406
std::vector< std::string > allowed_macs() const override
Definition: tls_policy.h:323
std::vector< Group_Params > key_exchange_groups() const override
Definition: tls_policy.h:375
bool allow_tls11() const override
Definition: tls_policy.h:404
std::vector< std::string > allowed_signature_methods() const override
Definition: tls_policy.h:329
bool allow_tls10() const override
Definition: tls_policy.h:337
bool allow_dtls12() const override
Definition: tls_policy.h:423
bool allow_server_initiated_renegotiation() const override
Definition: tls_policy.h:392
size_t minimum_ecdh_group_size() const override
Definition: tls_policy.h:400
size_t minimum_dh_group_size() const override
Definition: tls_policy.h:397
Definition: alg_id.cpp:13
bool allow_dtls10() const override
Definition: tls_policy.h:422
bool allow_tls10() const override
Definition: tls_policy.h:403
std::vector< std::string > allowed_macs() const override
Definition: tls_policy.h:360
std::vector< std::string > allowed_ciphers() const override
Definition: tls_policy.h:317
std::vector< std::string > allowed_key_exchange_methods() const override
Definition: tls_policy.h:326
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:396
bool allow_tls12() const override
Definition: tls_policy.h:339
bool server_uses_own_ciphersuite_preferences() const override
Definition: tls_policy.h:393
std::vector< std::string > allowed_signature_hashes() const override
Definition: tls_policy.h:355
bool allow_dtls12() const override
Definition: tls_policy.h:407
bool allow_insecure_renegotiation() const override
Definition: tls_policy.h:391
std::vector< std::string > allowed_signature_methods() const override
Definition: tls_policy.h:370
bool allow_tls11() const override
Definition: tls_policy.h:338
bool negotiate_encrypt_then_mac() const override
Definition: tls_policy.h:394
std::vector< std::string > allowed_ciphers() const override
Definition: tls_policy.h:350
size_t minimum_ecdsa_group_size() const override
Definition: tls_policy.h:401
MechanismType hash
std::vector< std::string > allowed_key_exchange_methods() const override
Definition: tls_policy.h:365
bool allow_dtls12() const override
Definition: tls_policy.h:341
Policy Default_Policy
Definition: tls_policy.h:309