1.. 2 Sphinx complains that this file isn't included in any toctree, however, we 3 currently link to it in the section about installing Certbot through Docker. 4 Setting :orphan: below suppresses this warning. See 5 https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html#special-metadata-fields. 6 7:orphan: 8 9============ 10Ciphersuites 11============ 12 13.. contents:: Table of Contents 14 :local: 15 16 17.. _ciphersuites: 18 19Introduction 20============ 21 22Autoupdates 23----------- 24 25Within certain limits, TLS server software can choose what kind of 26cryptography to use when a client connects. These choices can affect 27security, compatibility, and performance in complex ways. Most of 28these options are independent of a particular certificate. Certbot 29tries to provide defaults that we think are most useful to our users. 30 31As described below, Certbot will default to modifying 32server software's cryptographic settings to keep these up-to-date with 33what we think are appropriate defaults when new versions of the Certbot 34are installed (for example, by an operating system package manager). 35 36When this feature is implemented, this document will be updated 37to describe how to disable these automatic changes. 38 39 40Cryptographic choices 41--------------------- 42 43Software that uses cryptography must inevitably make choices about what 44kind of cryptography to use and how. These choices entail assumptions 45about how well particular cryptographic mechanisms resist attack, and what 46trade-offs are available and appropriate. The choices are constrained 47by compatibility issues (in order to interoperate with other software, 48an implementation must agree to use cryptographic mechanisms that the 49other side also supports) and protocol issues (cryptographic mechanisms 50must be specified in protocols and there must be a way to agree to use 51them in a particular context). 52 53The best choices for a particular application may change over time in 54response to new research, new standardization events, changes in computer 55hardware, and changes in the prevalence of legacy software. Much important 56research on cryptanalysis and cryptographic vulnerabilities is unpublished 57because many researchers have been working in the interest of improving 58some entities' communications security while weakening, or failing to 59improve, others' security. But important information that improves our 60understanding of the state of the art is published regularly. 61 62When enabling TLS support in a compatible web server (which is a separate 63step from obtaining a certificate), Certbot has the ability to 64update that web server's TLS configuration. Again, this is *different 65from the cryptographic particulars of the certificate itself*; the 66certificate as of the initial release will be RSA-signed using one of 67Let's Encrypt's 2048-bit RSA keys, and will describe the subscriber's 68RSA public key ("subject public key") of at least 2048 bits, which is 69used for key establishment. 70 71Note that the subscriber's RSA public key can be used in a wide variety 72of key establishment methods, most of which do not use RSA directly 73for key exchange, but only for authenticating the server! For example, 74in DHE and ECDHE key exchanges, the subject public key is just used to 75sign other parameters for authentication. You do not have to "use RSA" 76for other purposes just because you're using an RSA key for authentication. 77 78The certificate doesn't specify other cryptographic or ciphersuite 79particulars; for example, it doesn't say whether or not parties should 80use a particular symmetric algorithm like 3DES, or what cipher modes 81they should use. All of these details are negotiated between client 82and server independent of the content of the ciphersuite. The 83Let's Encrypt project hopes to provide useful defaults that reflect 84good security choices with respect to the publicly-known state of the 85art. However, the Let's Encrypt certificate authority does *not* 86dictate end-users' security policy, and any site is welcome to change 87its preferences in accordance with its own policy or its administrators' 88preferences, and use different cryptographic mechanisms or parameters, 89or a different priority order, than the defaults provided by Certbot. 90 91If you don't use Certbot to configure your server directly, because the 92client doesn't integrate with your server software or because you chose 93not to use this integration, then the cryptographic defaults haven't been 94modified, and the cryptography chosen by the server will still be whatever 95the default for your software was. For example, if you obtain a 96certificate using *standalone* mode and then manually install it in an IMAP 97or LDAP server, your cryptographic settings will not be modified by the 98client in any way. 99 100 101Sources of defaults 102------------------- 103 104Initially, Certbot will configure users' servers to use the cryptographic 105defaults recommended by the Mozilla project. These settings are well-reasoned 106recommendations that carefully consider client software compatibility. They 107are described at 108 109https://wiki.mozilla.org/Security/Server_Side_TLS 110 111and the version implemented by Certbot will be the 112version that was most current as of the release date of each client 113version. Mozilla offers three separate sets of cryptographic options, 114which trade off security and compatibility differently. These are 115referred to as the "Modern", "Intermediate", and "Old" configurations 116(in order from most secure to least secure, and least-backwards compatible 117to most-backwards compatible). The client will follow the Mozilla defaults 118for the *Intermediate* configuration by default, at least with regards to 119ciphersuites and TLS versions. Mozilla's web site describes which client 120software will be compatible with each configuration. You can also use 121the Qualys SSL Labs site to test your server and see whether it 122will be compatible with particular software versions. 123 124The Let's Encrypt project expects to follow the Mozilla recommendations 125in the future as those recommendations are updated. (For example, some 126users have proposed prioritizing a new ciphersuite known as ``0xcc13`` 127which uses the ChaCha and Poly1305 algorithms, and which is already 128implemented by the Chrome browser. Mozilla has delayed recommending 129``0xcc13`` over compatibility and standardization concerns, but is likely 130to recommend it in the future once these concerns have been addressed. At 131that point, Certbot would likely follow the Mozilla recommendations and favor 132the use of this ciphersuite as well.) 133 134The Let's Encrypt project may deviate from the Mozilla recommendations 135in the future if good cause is shown and we believe our users' 136priorities would be well-served by doing so. In general, please address 137relevant proposals for changing priorities to the Mozilla security 138team first, before asking the Certbot developers to change 139Certbot's priorities. The Mozilla security team is likely to have more 140resources and expertise to bring to bear on evaluating reasons why its 141recommendations should be updated. 142 143The Let's Encrypt project will entertain proposals to create a *very* 144small number of alternative configurations (apart from Modern, 145Intermediate, and Old) that there's reason to believe would be widely 146used by sysadmins; this would usually be a preferable course to modifying 147an existing configuration. For example, if many sysadmins want their 148servers configured to track a different expert recommendation, Certbot 149could add an option to do so. 150 151 152Resources for recommendations 153----------------------------- 154 155In the course of considering how to handle this issue, we received 156recommendations with sources of expert guidance on ciphersuites and other 157cryptographic parameters. We're grateful to everyone who contributed 158suggestions. The recommendations we received are available under Feedback_. 159 160Certbot users are welcome to review these authorities to 161better inform their own cryptographic parameter choices. We also 162welcome suggestions of other resources to add to this list. Please keep 163in mind that different recommendations may reflect different priorities 164or evaluations of trade-offs, especially related to compatibility! 165 166Feedback 167======== 168We receive lots of feedback on the type of ciphersuites that Let's Encrypt supports and list some collated feedback below. This section aims to track suggestions and references that people have offered or identified to improve the ciphersuites that Let's Encrypt enables when configuring TLS on servers. 169 170Because of the Chatham House Rule applicable to some of the discussions, people are *not* individually credited for their suggestions, but most suggestions here were made or found by other people, and I thank them for their contributions. 171 172Some people provided rationale information mostly having to do with compatibility of particular user-agents (especially UAs that don't support ECC, or that don't support DH groups > 1024 bits). Some ciphersuite configurations have been chosen to try to increase compatibility with older UAs while allowing newer UAs to negotiate stronger crypto. For example, some configurations forego forward secrecy entirely for connections from old UAs, like by offering ECDHE and RSA key exchange, but no DHE at all. (There are UAs that can fail the negotiation completely if a DHE ciphersuite with prime > 1024 bits is offered.) 173 174References 175---------- 176 177RFC 7575 178~~~~~~~~ 179 180IETF has published a BCP document, RFC 7525, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)" 181 182https://datatracker.ietf.org/doc/rfc7525/ 183 184BetterCrypto.org 185~~~~~~~~~~~~~~~~ 186 187BetterCrypto.org, a collaboration of mostly European IT security experts, has published a draft paper, "Applied Crypto Hardening" 188 189https://bettercrypto.org/ 190 191FF-DHE Internet-Draft 192~~~~~~~~~~~~~~~~~~~~~ 193 194Gillmor's Internet-Draft "Negotiated Discrete Log Diffie-Hellman Ephemeral Parameters for TLS" is being developed at the IETF TLS WG. It advocates using *standardized* DH groups in all cases, not individually-chosen ones (mostly because of the Triple Handshake attack which can involve maliciously choosing invalid DH groups). The draft provides a list of recommended groups, with primes beginning at 2048 bits and going up from there. It also has a new protocol mechanism for agreeing to use these groups, with the possibility of backwards compatibility (and use of weaker DH groups) for older clients and servers that don't know about this mechanism. 195 196https://tools.ietf.org/html/draft-ietf-tls-negotiated-ff-dhe-10 197 198Mozilla 199~~~~~~~ 200 201Mozilla's general server configuration guidance is available at https://wiki.mozilla.org/Security/Server_Side_TLS 202 203Mozilla has also produced a configuration generator: https://ssl-config.mozilla.org 204 205Dutch National Cyber Security Centre 206~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 207 208The Dutch National Cyber Security Centre has published guidance on "ICT-beveiligingsrichtlijnen voor Transport Layer Security (TLS)" ("IT Security Guidelines for Transport Layer Security (TLS)"). These are available only in Dutch at 209 210https://web.archive.org/web/20190516085116/https://www.ncsc.nl/actueel/whitepapers/ict-beveiligingsrichtlijnen-voor-transport-layer-security-tls.html 211 212I have access to an English-language summary of the recommendations. 213 214Keylength.com 215~~~~~~~~~~~~~ 216 217Damien Giry collects recommendations by academic researchers and standards organizations about keylengths for particular cryptoperiods, years, or security levels. The keylength recommendations of the various sources are summarized in a chart. This site has been updated over time and includes expert guidance from eight sources published between 2000 and 2017. 218 219https://www.keylength.com/ 220 221NIST 222~~~~ 223NIST published its "NIST Special Publication 800-52 Revision 2: Guidelines for the Selection, Configuration, and Use of Transport Layer Security (TLS) Implementations" 224 225https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-52r2.pdf 226 227and its "NIST Special Publication 800-57: Recommendation for Key Management – Part 1: General (Revision 5)" 228 229https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57pt1r5.pdf 230 231ENISA 232~~~~~ 233 234ENISA published its "Algorithms, Key Sizes and Parameters Report - 2013" 235 236https://www.enisa.europa.eu/activities/identity-and-trust/library/deliverables/algorithms-key-sizes-and-parameters-report 237 238WeakDH/Logjam 239------------- 240 241The WeakDH/Logjam research has thrown into question the safety of some existing practice using DH ciphersuites, especially the use of standardized groups with a prime ≤ 1024 bits. The authors provided detailed guidance, including ciphersuite lists, at 242 243https://weakdh.org/sysadmin.html 244 245These lists may have been derived from Mozilla's recommendations. 246One of the authors clarified his view of the priorities for various changes as a result of the research at 247 248https://web.archive.org/web/20150526022820/https://www.ietf.org/mail-archive/web/tls/current/msg16496.html 249 250In particular, he supports ECDHE and also supports the use of the standardized groups in the FF-DHE Internet-Draft mentioned above (which isn't clear from the group's original recommendations). 251 252Particular sites' opinions or configurations 253-------------------------------------------- 254 255Amazon ELB 256~~~~~~~~~~ 257 258Amazon ELB explains its current ciphersuite choices at 259 260https://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/elb-security-policy-table.html 261 262U.S. Government 18F 263~~~~~~~~~~~~~~~~~~~ 264 265The 18F site (https://18f.gsa.gov/) is using 266 267:: 268 269 ssl_ciphers 'kEECDH+ECDSA+AES128 kEECDH+ECDSA+AES256 kEECDH+AES128 kEECDH+AES256 kEDH+AES128 kEDH+AES256 DES-CBC3-SHA +SHA !aNULL !eNULL !LOW !MD5 !EXP !DSS !PSK !SRP !kECDH !CAMELLIA !RC4 !SEED'; 270 271Duraconf 272~~~~~~~~ 273 274The Duraconf project collects particular configuration files, with an apparent focus on avoiding the use of obsolete symmetric ciphers and hash functions, and favoring forward secrecy while not requiring it. 275 276https://github.com/ioerror/duraconf 277 278Site scanning or rating tools 279----------------------------- 280 281Qualys SSL Labs 282~~~~~~~~~~~~~~~ 283 284Qualys offers the best-known TLS security scanner, maintained by Ivan Ristić. 285 286https://www.ssllabs.com/ 287 288Dutch NCSC 289~~~~~~~~~~ 290 291The Dutch NCSC, mentioned above, has also made available its own site security scanner which indicates how well sites comply with the recommendations. 292 293https://en.internet.nl/ 294 295Java compatibility issue 296------------------------ 297 298A lot of backward-compatibility concerns have to do with Java hard-coding DHE primes to a 1024-bit limit, accepting DHE ciphersuites in negotiation, and then aborting the connection entirely if a prime > 1024 bits is presented. The simple summary is that servers offering a Java-compatible DHE ciphersuite in preference to other Java-compatible ciphersuites, and then presenting a DH group with a prime > 1024 bits, will be completely incompatible with clients running some versions of Java. (This may also be the case with very old MSIE versions...?) There are various strategies for dealing with this, and maybe we can document the options here. 299