/* * Hooks for application level policies on TLS connections * (C) 2004-2006,2013 Jack Lloyd * 2017 Harry Reimann, Rohde & Schwarz Cybersecurity * * Botan is released under the Simplified BSD License (see license.txt) */ #ifndef BOTAN_TLS_POLICY_H_ #define BOTAN_TLS_POLICY_H_ #include #include #include #include #include namespace Botan { class Public_Key; namespace TLS { /** * TLS Policy Base Class * Inherit and overload as desired to suit local policy concerns */ class BOTAN_PUBLIC_API(2,0) Policy { public: /** * Returns a list of ciphers we are willing to negotiate, in * order of preference. */ virtual std::vector allowed_ciphers() const; /** * Returns a list of hash algorithms we are willing to use for * signatures, in order of preference. */ virtual std::vector allowed_signature_hashes() const; /** * Returns a list of MAC algorithms we are willing to use. */ virtual std::vector allowed_macs() const; /** * Returns a list of key exchange algorithms we are willing to * use, in order of preference. Allowed values: DH, empty string * (representing RSA using server certificate key) */ virtual std::vector allowed_key_exchange_methods() const; /** * Returns a list of signature algorithms we are willing to * use, in order of preference. Allowed values RSA and DSA. */ virtual std::vector allowed_signature_methods() const; virtual std::vector allowed_signature_schemes() const; /** * The minimum signature strength we will accept * Returning 80 allows RSA 1024 and SHA-1. Values larger than 80 disable SHA-1 support. * Returning 110 allows RSA 2048. * Return 128 to force ECC (P-256) or large (~3000 bit) RSA keys. * Default is 110 */ virtual size_t minimum_signature_strength() const; /** * Return if cert revocation info (CRL/OCSP) is required * If true, validation will fail unless a valid CRL or OCSP response * was examined. */ virtual bool require_cert_revocation_info() const; bool allowed_signature_method(const std::string& sig_method) const; bool allowed_signature_hash(const std::string& hash) const; /** * Return list of ECC curves and FFDHE groups we are willing to * use in order of preference. */ virtual std::vector key_exchange_groups() const; /** * Request that ECC curve points are sent compressed */ virtual bool use_ecc_point_compression() const; /** * Select a key exchange group to use, from the list of groups sent by the * peer. If none are acceptable, return Group_Params::NONE */ virtual Group_Params choose_key_exchange_group(const std::vector& peer_groups) const; /** * Allow renegotiation even if the counterparty doesn't * support the secure renegotiation extension. * * @warning Changing this to true exposes you to injected * plaintext attacks. Read RFC 5746 for background. */ virtual bool allow_insecure_renegotiation() const; /** * The protocol dictates that the first 32 bits of the random * field are the current time in seconds. However this allows * client fingerprinting attacks. Set to false to disable, in * which case random bytes will be used instead. */ virtual bool include_time_in_hello_random() const; /** * Consulted by server side. If true, allows clients to initiate a new handshake */ virtual bool allow_client_initiated_renegotiation() const; /** * Consulted by client side. If true, allows servers to initiate a new handshake */ virtual bool allow_server_initiated_renegotiation() const; /** * Allow TLS v1.0 */ virtual bool allow_tls10() const; /** * Allow TLS v1.1 */ virtual bool allow_tls11() const; /** * Allow TLS v1.2 */ virtual bool allow_tls12() const; /** * Allow DTLS v1.0 */ virtual bool allow_dtls10() const; /** * Allow DTLS v1.2 */ virtual bool allow_dtls12() const; virtual Group_Params default_dh_group() const; /** * Return the minimum DH group size we're willing to use * Default is currently 1024 (insecure), should be 2048 */ virtual size_t minimum_dh_group_size() const; /** * For ECDSA authenticated ciphersuites, the smallest key size the * client will accept. * This policy is currently only enforced on the server by the client. */ virtual size_t minimum_ecdsa_group_size() const; /** * Return the minimum ECDH group size we're willing to use * for key exchange * * Default 255, allowing x25519 and larger * x25519 is the smallest curve we will negotiate * P-521 is the largest */ virtual size_t minimum_ecdh_group_size() const; /** * Return the minimum bit size we're willing to accept for RSA * key exchange or server signatures. * * It does not place any requirements on the size of any RSA signature(s) * which were used to check the server certificate. This is only * concerned with the server's public key. * * Default is 2048 which is smallest RSA key size still secure * for medium term security. */ virtual size_t minimum_rsa_bits() const; /** * Minimum DSA group size, default 2048 bits */ virtual size_t minimum_dsa_group_size() const; /** * Throw an exception if you don't like the peer's key. * Default impl checks the key size against minimum_rsa_bits, minimum_ecdsa_group_size, * or minimum_ecdh_group_size depending on the key's type. * Override if you'd like to perform some other kind of test on * (or logging of) the peer's keys. */ virtual void check_peer_key_acceptable(const Public_Key& public_key) const; /** * If this function returns false, unknown SRP/PSK identifiers * will be rejected with an unknown_psk_identifier alert as soon * as the non-existence is identified. Otherwise, a false * identifier value will be used and the protocol allowed to * proceed, causing the handshake to eventually fail without * revealing that the username does not exist on this system. */ virtual bool hide_unknown_users() const; /** * Return the allowed lifetime of a session ticket. If 0, session * tickets do not expire until the session ticket key rolls over. * Expired session tickets cannot be used to resume a session. */ virtual uint32_t session_ticket_lifetime() const; /** * If this returns a non-empty vector, and DTLS is negotiated, * then we will also attempt to negotiate the SRTP extension from * RFC 5764 using the returned values as the profile ids. */ virtual std::vector srtp_profiles() const; /** * @return true if and only if we are willing to accept this version * Default accepts TLS v1.0 and later or DTLS v1.2 or later. */ virtual bool acceptable_protocol_version(Protocol_Version version) const; /** * Returns the more recent protocol version we are willing to * use, for either TLS or DTLS depending on datagram param. * Shouldn't ever need to override this unless you want to allow * a user to disable use of TLS v1.2 (which is *not recommended*) */ virtual Protocol_Version latest_supported_version(bool datagram) const; /** * When offering this version, should we send a fallback SCSV? * Default returns true iff version is not the latest version the * policy allows, exists to allow override in case of interop problems. */ virtual bool send_fallback_scsv(Protocol_Version version) const; /** * Allows policy to reject any ciphersuites which are undesirable * for whatever reason without having to reimplement ciphersuite_list */ virtual bool acceptable_ciphersuite(const Ciphersuite& suite) const; /** * @return true if servers should choose the ciphersuite matching * their highest preference, rather than the clients. * Has no effect on client side. */ virtual bool server_uses_own_ciphersuite_preferences() const; /** * Indicates whether the encrypt-then-MAC extension should be negotiated * (RFC 7366) */ virtual bool negotiate_encrypt_then_mac() const; /** * Indicates whether certificate status messages should be supported */ virtual bool support_cert_status_message() const; /** * Return allowed ciphersuites, in order of preference */ virtual std::vector ciphersuite_list(Protocol_Version version, bool have_srp) const; /** * @return the default MTU for DTLS */ virtual size_t dtls_default_mtu() const; /** * @return the initial timeout for DTLS */ virtual size_t dtls_initial_timeout() const; /** * @return the maximum timeout for DTLS */ virtual size_t dtls_maximum_timeout() const; /** * Convert this policy to a printable format. * @param o stream to be printed to */ virtual void print(std::ostream& o) const; /** * Convert this policy to a printable format. * Same as calling `print` on a ostringstream and reading o.str() */ std::string to_string() const; virtual ~Policy() = default; }; typedef Policy Default_Policy; /** * NSA Suite B 128-bit security level (RFC 6460) * * @warning As of August 2015 NSA indicated only the 192-bit Suite B * should be used for all classification levels. */ class BOTAN_PUBLIC_API(2,0) NSA_Suite_B_128 : public Policy { public: std::vector allowed_ciphers() const override { return std::vector({"AES-128/GCM"}); } std::vector allowed_signature_hashes() const override { return std::vector({"SHA-256"}); } std::vector allowed_macs() const override { return std::vector({"AEAD"}); } std::vector allowed_key_exchange_methods() const override { return std::vector({"ECDH"}); } std::vector allowed_signature_methods() const override { return std::vector({"ECDSA"}); } std::vector key_exchange_groups() const override { return {Group_Params::SECP256R1}; } size_t minimum_signature_strength() const override { return 128; } bool allow_tls10() const override { return false; } bool allow_tls11() const override { return false; } bool allow_tls12() const override { return true; } bool allow_dtls10() const override { return false; } bool allow_dtls12() const override { return false; } }; /** * NSA Suite B 192-bit security level (RFC 6460) */ class BOTAN_PUBLIC_API(2,7) NSA_Suite_B_192 : public Policy { public: std::vector allowed_ciphers() const override { return std::vector({"AES-256/GCM"}); } std::vector allowed_signature_hashes() const override { return std::vector({"SHA-384"}); } std::vector allowed_macs() const override { return std::vector({"AEAD"}); } std::vector allowed_key_exchange_methods() const override { return std::vector({"ECDH"}); } std::vector allowed_signature_methods() const override { return std::vector({"ECDSA"}); } std::vector key_exchange_groups() const override { return {Group_Params::SECP384R1}; } size_t minimum_signature_strength() const override { return 192; } bool allow_tls10() const override { return false; } bool allow_tls11() const override { return false; } bool allow_tls12() const override { return true; } bool allow_dtls10() const override { return false; } bool allow_dtls12() const override { return false; } }; /** * BSI TR-02102-2 Policy */ class BOTAN_PUBLIC_API(2,0) BSI_TR_02102_2 : public Policy { public: std::vector allowed_ciphers() const override { return std::vector({"AES-256/GCM", "AES-128/GCM", "AES-256", "AES-128" }); } std::vector allowed_signature_hashes() const override { return std::vector({"SHA-384", "SHA-256"}); } std::vector allowed_macs() const override { return std::vector({"AEAD", "SHA-384", "SHA-256"}); } std::vector allowed_key_exchange_methods() const override { return std::vector({"ECDH", "DH", "PSK", "ECDHE_PSK", "DHE_PSK"}); } std::vector allowed_signature_methods() const override { return std::vector({"ECDSA", "RSA", "DSA"}); } std::vector key_exchange_groups() const override { return std::vector({ Group_Params::BRAINPOOL512R1, Group_Params::BRAINPOOL384R1, Group_Params::BRAINPOOL256R1, Group_Params::SECP384R1, Group_Params::SECP256R1, Group_Params::FFDHE_8192, Group_Params::FFDHE_6144, Group_Params::FFDHE_4096, Group_Params::FFDHE_3072, Group_Params::FFDHE_2048 }); } bool allow_insecure_renegotiation() const override { return false; } bool allow_server_initiated_renegotiation() const override { return true; } bool server_uses_own_ciphersuite_preferences() const override { return true; } bool negotiate_encrypt_then_mac() const override { return true; } size_t minimum_rsa_bits() const override { return 2000; } size_t minimum_dh_group_size() const override { return 2000; } size_t minimum_dsa_group_size() const override { return 2000; } size_t minimum_ecdh_group_size() const override { return 250; } size_t minimum_ecdsa_group_size() const override { return 250; } bool allow_tls10() const override { return false; } bool allow_tls11() const override { return false; } bool allow_tls12() const override { return true; } bool allow_dtls10() const override { return false; } bool allow_dtls12() const override { return false; } }; /** * Policy for DTLS. We require DTLS v1.2 and an AEAD mode. */ class BOTAN_PUBLIC_API(2,0) Datagram_Policy : public Policy { public: std::vector allowed_macs() const override { return std::vector({"AEAD"}); } bool allow_tls10() const override { return false; } bool allow_tls11() const override { return false; } bool allow_tls12() const override { return false; } bool allow_dtls10() const override { return false; } bool allow_dtls12() const override { return true; } }; /* * This policy requires a secure version of TLS and disables all insecure * algorithms. It is compatible with other botan TLSes (including those using the * default policy) and with many other recent implementations. It is a great idea * to use if you control both sides of the protocol and don't have to worry * about ancient and/or bizarre TLS implementations. */ class BOTAN_PUBLIC_API(2,0) Strict_Policy : public Policy { public: std::vector allowed_ciphers() const override; std::vector allowed_signature_hashes() const override; std::vector allowed_macs() const override; std::vector allowed_key_exchange_methods() const override; bool allow_tls10() const override; bool allow_tls11() const override; bool allow_tls12() const override; bool allow_dtls10() const override; bool allow_dtls12() const override; }; class BOTAN_PUBLIC_API(2,0) Text_Policy : public Policy { public: std::vector allowed_ciphers() const override; std::vector allowed_signature_hashes() const override; std::vector allowed_macs() const override; std::vector allowed_key_exchange_methods() const override; std::vector allowed_signature_methods() const override; std::vector key_exchange_groups() const override; bool use_ecc_point_compression() const override; bool allow_tls10() const override; bool allow_tls11() const override; bool allow_tls12() const override; bool allow_dtls10() const override; bool allow_dtls12() const override; bool allow_insecure_renegotiation() const override; bool include_time_in_hello_random() const override; bool allow_client_initiated_renegotiation() const override; bool allow_server_initiated_renegotiation() const override; bool server_uses_own_ciphersuite_preferences() const override; bool negotiate_encrypt_then_mac() const override; bool support_cert_status_message() const override; size_t minimum_ecdh_group_size() const override; size_t minimum_ecdsa_group_size() const override; size_t minimum_dh_group_size() const override; size_t minimum_rsa_bits() const override; size_t minimum_signature_strength() const override; size_t dtls_default_mtu() const override; size_t dtls_initial_timeout() const override; size_t dtls_maximum_timeout() const override; bool require_cert_revocation_info() const override; bool hide_unknown_users() const override; uint32_t session_ticket_lifetime() const override; bool send_fallback_scsv(Protocol_Version version) const override; std::vector srtp_profiles() const override; void set(const std::string& k, const std::string& v); explicit Text_Policy(const std::string& s); explicit Text_Policy(std::istream& in); protected: std::vector get_list(const std::string& key, const std::vector& def) const; size_t get_len(const std::string& key, size_t def) const; bool get_bool(const std::string& key, bool def) const; std::string get_str(const std::string& key, const std::string& def = "") const; bool set_value(const std::string& key, const std::string& val, bool overwrite); private: std::map m_kv; }; } } #endif