wdFpAzVD

1# Cryptographic Best Practices
2
3Putting cryptographic primitives together is a lot like putting a jigsaw
4puzzle together, where all the pieces are cut exactly the same way, but there
5is only one correct solution. Thankfully, there are some projects out there
6that are working hard to make sure developers are getting it right.
7
8The following advice comes from years of research from leading security
9researchers, developers, and cryptographers. This Gist was [forked from Thomas
10Ptacek's Gist][1] to be more readable. Additions have been added from
11[Latacora's Cryptographic Right Answers][2].
12
13[1]: https://gist.github.com/tqbf/be58d2d39690c3b366ad
14[2]: http://latacora.singles/2018/04/03/cryptographic-right-answers.html
15
16Some others have been added from years of discussions on Twitter, IRC, and
17mailing lists that would be too difficult to pin down, or exhaustively list
18here.
19
20If at any point, I disagree with some of the advice, I will note it and provide
21reasoning why. If you have any questions, or disagreements, [let me know][3].
22
23[3]: https://twitter.com/AaronToponce
24
25### TL;DR
26
27If you take only one thing away from this post, it should be to use a library
28that puts these puzzle pieces together correctly for you. Pick one of for your
29project:
30
311. [NaCl][4] - By cryptographer Daniel Bernstein
322. [libsodium][5] - NaCl fork by developer Frank Denis
333. [monocypher][6]- libsodium fork by developer Loup Vaillant 
34
35[4]: https://nacl.cr.yp.to/
36[5]: https://download.libsodium.org/doc/
37[6]: https://monocypher.org/
38
39Throughout this document, when I refer to "just use NaCl", I mean one of these
40libraries.
41
42### Symmetric Encryption
43
44If you are in a position to use a [key management system (KMS)][7], then you
45should use KMS. If you are not in a position to use KMS, then you should use
46[authenticated encryption with associated data (AEAD)][8].
47
48[7]: https://en.wikipedia.org/wiki/Key_management#Key_management_system
49[8]: https://en.wikipedia.org/wiki/Authenticated_encryption
50
51Currently, [the CAESAR competition][9] is being held to find an AEAD algorithm
52that doesn't have some of the sharp edges of AES-GCM while also improving
53performance. When the announcement of the final portfolio drops, this document
54will be updated.
55
56[9]: https://competitions.cr.yp.to/caesar.html
57
58Some notes on AEAD:
59
60* ChaCha20-Poly1305 is faster in software than AES-GCM.
61* AES-GCM will be faster than ChaCha20-Poly1305 with AES-NI.
62* AES-CTR with HMAC will be faster in software than AES-GCM.
63* Poly1305 is also easier than GCM for library designers to implement safely.
64* AES-GCM is the industry standard.
65
66The NaCl libraries will handle AEAD for you natively.
67
68**Use, in order of preference:**
69
701. KMS, if available.
712. The NaCL, libsodium, or monocypher default
723. Chacha20-Poly1305
734. AES-GCM
745. AES-CTR with HMAC
75
76**Avoid:**
77
781. AES-CBC, AES-CTR by itself
792. [Block ciphers with 64-bit blocks][10], such as Blowfish.
803. OFB mode
814. RC4, which is comically broken
82
83[10]: https://sweet32.info/
84
85### Symmetric Key Length
86
87See my blog post about [The Physics of Brute Force][11] to understand why
88256-bit keys is more than sufficient. But rememeber: your AES key is far less
89likely to be broken than your public key pair, so the latter key size should be
90larger if you're going to obsess about this.
91
92[11]: https://pthree.org/2016/06/19/the-physics-of-brute-force/
93
94If your symmetric key is based on user input, such as a passphrase, then it
95should provide at least as many bits of theoretical entropic security as the
96symmetric key length. In other words, if your AES key is 128-bits, and is built
97from a password, then that passwourd should provide at least 128-bits of
98entropy.
99
100As with asymmetric encryption, symmetric encryption key length is a vital
101security parameter. Academic, private, and government organizations provide
102different recommendations with mathematical formulas to approimate the minimum
103key size requirement for security. See [BlueKcrypt's Cryptographyc Key Length
104Recommendation][12] for other recommendations and dates.
105
106[12]: https://keylength.com/
107
108To protect data up through 2050, it is recommended to meet the minimum
109requirements for symmetric key lengths:
110
111* [Lenstra/Verheul][13]- 109 bits
112* [Lenstra Updated][14]- 102 bits
113* [ECRYPT II][15]- 256 bits
114* [NIST][16]- 192 bits
115* [ANSSI][17]- 128 bits
116* [IAD-NSA][18]- 256 bits
117* [BSI][19]- 128 bits
118
119[13]: http://infoscience.epfl.ch/record/164526/files/NPDF-22.pdf
120[14]: http://infoscience.epfl.ch/record/164539/files/NPDF-32.pdf
121[15]: http://www.ecrypt.eu.org/ecrypt2/documents/D.SPA.20.pdf
122[16]: http://csrc.nist.gov/groups/ST/toolkit/key_management.html
123[17]: http://www.ssi.gouv.fr/uploads/2015/01/RGS_v-2-0_B1.pdf
124[18]: https://www.iad.gov/iad/library/ia-guidance/ia-solutions-for-classified/algorithm-guidance/commercial-national-security-algorithm-suite-factsheet.cfm
125[19]: https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf?__blob=publicationFile
126
127See also the NSA [Fact Sheet Suite B Cryptography][20] and [RFC 3766][21] for
128additional recommendations and math algorithms for calculating strengths based
129on calendar year.
130
131[20]: https://www.nsa.gov/ia/programs/suiteb_cryptography/index.shtml
132[21]: https://tools.ietf.org/html/rfc3766
133
134Personally, I don't see any problem with using 256-bit key lengths. So, my
135recommendation would be:
136
137**Use:**
138
1391. Minimum- 128-bit keys
1402. Maximum- 256-bit keys
141
142**Avoid:**
143
1441. Constructions with huge keys
1452. Cipher "cascades"
1463. Key sizes under 128 bits
147
148### Symmetric Signatures
149
150If you're authenticating but not encrypting, as with API requests, don't do
151anything complicated. There is a class of crypto implementation bugs that arises
152from how you feed data to your MAC, so, if you're designing a new system from
153scratch, Google "crypto canonicalization bugs". Also, use a secure compare
154function. 
155
156If you use HMAC, people will feel the need to point out that SHA-3 (and the
157truncated SHA-2 hashes) can do “KMAC”, which is to say you can just concatenate
158the key and data, and hash them to be secure. This means that in theory, HMAC
159is doing unnecessary extra work with SHA-3 or truncated SHA-2. But who cares?
160Think of HMAC as cheap insurance for your design, in case someone switches to
161non-truncated SHA-2.
162
163**Use:**
164
1651. HMAC-SHA-512/256
1662. HMAC-SHA-512/224
1673. HMAC-SHA-384
1684. HMAC-SHA-224
1695. HMAC-SHA-512
1706. HMAC-SHA-256
171
172**Alternately, use in order of preference:**
173
1741. Keyed BLAKE2b
1752. Keyed BLAKE2s
1763. Keyed SHA3-512
1774. Keyed SHA3-256
178
179**Avoid:**
180
1811. HMAC-MD5
1822. HMAC-SHA1
1833. Custom "keyed hash" constructions
1844. Complex polynomial MACs
1855. Encrypted hashes
1866. Anything CRC
187
188### Hashing
189
190If you can get away with it you want to use hashing algorithms that truncate
191their output and sidesteps length extension attacks. Meanwhile: it's less likely
192that you'll upgrade from SHA-2 to SHA-3 than it is that you'll upgrade from
193SHA-2 to BLAKE2, which is faster than SHA-3, and SHA-2 looks great right now, so
194get comfortable and cuddly with SHA-2.
195
196**Use (pick one):**
197
1981. SHA-2 (fast, time-tested, industry standard)
1992. BLAKE2 (fastest, SHA-3 finalist)
2003. SHA-3 (slowest, industry standard)
201
202**Avoid:**
203
2041. SHA-1
2052. MD5
2063. MD6
2074. EDON-R (I'm looking at you OpenZFS)
208
209### Random Numbers
210
211When creating random IDs, numbers, URLs, initialization vectors, or anything
212that is *random*, then you should [always use your operating system's
213kernelspace CSPRNG][31] On GNU/Linux (including Android), BSD, or Mac (including
214iOS), this is `/dev/urandom`. On Windows, this is [CryptGenRandom][32].
215
216**NOTE:** [/dev/random is **_not_** more secure then /dev/urandom][33]. They
217use the same CSPRNG. They only time you would obsess over this, is when working
218on an information theoretic cryptographic primitive that exploits the blocking
219aspects of `/dev/random`, which you aren't doing (you would know it when you're
220doing it).
221
222The only time you should ever use a userspace RNG, is when you're in a
223constrained environment, such as embedded firmware, where the OS RNG is not
224available. In that case, use [fast-key erasure][34]. The problem here, however,
225is making sure that it is properly seeded with entropy on each boot. This is
226harder than it sounds, so really, at all costs, this should only be used as a
227worst-scenario fallback.
228
229[31]: http://sockpuppet.org/blog/2014/02/25/safely-generate-random-numbers/
230[32]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa379942(v=vs.85).aspx
231[33]: https://security.stackexchange.com/a/3939
232[34]: https://blog.cr.yp.to/20170723-random.html
233
234**Use:**
235
2361. Your operating system's CSPRNG (Cryptographically Secure Psuedo Random Number Generator),
237   that in GNU/Linux is /dev/urandom
2382. Fast key erasure (as a fallback).
239
240**Create:** 256-bit random numbers
241
242**Avoid:**
243
2441. Userspace random number generators
2452. `/dev/random`
246
247### Password Hashing
248
249When using scrypt for password hashing, be aware that it is very [sensitive to
250the parameters][35], making it possible to end up weaker than bcrypt, and
251suffers from time-memory trade-off ([source #1][36] and [source #2][37]). When
252using bcrypt, make sure to use the following algorithm to prevent [the leading
253NULL byte problem][38]. and the 72-character password limit:
254
255    bcrypt(base64(sha-512(password)))
256
257[35]: http://blog.ircmaxell.com/2014/03/why-i-dont-recommend-scrypt.html
258[36]: http://www.openwall.com/lists/crypt-dev/2013/03/21/1
259[37]: http://www.openwall.com/lists/crypt-dev/2013/03/17/1
260[38]: http://blog.ircmaxell.com/2015/03/security-issue-combining-bcrypt-with.html
261
262Initially, I was hesitant to recommend Argon2 for general production use. I no
263longer feel that way. It was the winner of the [Password Hashing
264Competition][39], has had ample analysis, even before the competition finished,
265and is showing no signs of serious weaknesses.
266
267[39]: https://password-hashing.net/
268
269Each password hashing algorithm requires a "cost" to implement correctly. For
270Argon2, this is using a sufficient time on the CPU and a sufficient amount of
271RAM. For scrypt, this is using at least 16 MB of RAM. For bcrypt, this is a
272cost of at least "5". For sha512crypt and sha256crypt, this it at least 5,000
273rounds. For PBKDF2, this is at least 1,000 rounds.
274
275Jeremi Gonsey, a professional password cracker, publishes benchmarks with
276Nvidia GPU clusters, such as with [8x Nvidia GTX 1080 Ti GPUs][40]. It's worth
277looking over those numbers.
278
279[40]: https://gist.github.com/epixoip/ace60d09981be09544fdd35005051505
280
281**Use, in order of preference:**
282
2831. Argon2 (tune appropriately)
2842. scrypt (>= 16 MB)
2853. bcrypt (>= 5)
2864. sha512crypt (>= 5,000 rounds)
2875. sha256crypt (>= 5,000 rounds)
2886. PBKDF2 (>= 1,000 rounds)
289
290**Avoid:**
291
2921. Plaintext
2932. Naked SHA-2, SHA-1, MD5
2943. Complex homebrew algorithms
2954. Any encryption algorithm
296
297### Asymmetric Encryption
298
299It's time to stop using anything RSA, and start using NaCL. Of all the
300cryptographic "best practices", this is the one you're least likely to get
301right on your own. NaCL has been designed to prevent you from making stupid
302mistakes, it's highly favored among the cryptographic community, and focuses on
303modern, highly secure cryptographic primitives.
304
305It's time to start using ECC. Here are several reasons you should stop using
306RSA and switch to elliptic curve software:
307
308* Progress in attacking RSA --- really, all the classic multiplicative group
309  primitives, including DH and DSA and presumably ElGamal --- is proceeding
310  faster than progress against elliptic curves.
311* RSA (and DH) drag you towards "backwards compatibility" (ie: downgrade-attack
312  compatibility) with insecure systems. Elliptic curve schemes generally don't
313  need to be vigilant about accidentally accepting 768-bit parameters.
314* RSA begs implementors to encrypt directly with its public key primitive,
315  which is usually not what you want to do: not only does accidentally
316  designing with RSA encryption usually forfeit forward-secrecy, but it also
317  exposes you to new classes of implementation bugs. Elliptic curve systems
318  don't promote this particular foot-gun. 
319* The weight of correctness/safety in elliptic curve systems falls primarily on
320  cryptographers, who must provide a set of curve parameters optimized for
321  security at a particular performance level; once that happens, there aren't
322  many knobs for implementors to turn that can subvert security. The opposite
323  is true in RSA. Even if you use RSA-KEM or RSA-OAEP, there are additional
324  parameters to supply and things you have to know to get right.
325
326If you absolutely have to use RSA, do use RSA-KEM. But don't use RSA. Use ECC.
327
328**Use:** NaCL, libsodium, or monocypher
329
330**Avoid:**
331
3321. Really, anything RSA
3332. ElGamal
3343. OpenPGP, OpenSSL, BouncyCastle, etc.
335
336### Asymmetric Key Length
337
338As with symmetric encryption, asymmetric encryption key length is a vital
339security parameter. Academic, private, and government organizations provide
340different recommendations with mathematical formulas to approimate the minimum
341key size requirement for security. See [BlueKcrypt's Cryptographyc Key Length
342Recommendation][41] for other recommendations and dates.
343
344[41]: https://keylength.com
345
346To protect data up through 2050, it is recommended to meet the minimum
347requirements for asymmetric key lengths:
348
349Method | RSA | ECC | D-H Key | D-H Group
350------ | --- | --- | ------- | ---------
351[Lenstra/Verheul][42] | 4047 | 206 | 193 | 4047 
352[Lenstra Updated][43] | 2440 | 203 | 203 | 2440
353[ECRYPT II][44] | 15424 | 512 | 512 | 15424
354[NIST][45] | 7680 | 384 | 384 | 7680
355[ANSSI][46] | 3072 | 256 | 200 | 3072
356[BSI][47] | 3000 | 250 | 250 | 3000
357
358[42]: http://infoscience.epfl.ch/record/164526/files/NPDF-22.pdf
359[43]: http://infoscience.epfl.ch/record/164539/files/NPDF-32.pdf
360[44]: http://www.ecrypt.eu.org/ecrypt2/documents/D.SPA.20.pdf
361[45]: http://csrc.nist.gov/groups/ST/toolkit/key_management.html
362[46]: http://www.ssi.gouv.fr/uploads/2015/01/RGS_v-2-0_B1.pdf
363[47]: https://www.bsi.bund.de/SharedDocs/Downloads/DE/BSI/Publikationen/TechnischeRichtlinien/TR02102/BSI-TR-02102.pdf?__blob=publicationFile
364
365See also the NSA [Fact Sheet Suite B Cryptography][48] and [RFC 3766][49] for
366additional recommendations and math algorithms for calculating strengths based
367on calendar year.
368
369[48]: https://www.nsa.gov/ia/programs/suiteb_cryptography/index.shtml
370[49]: https://tools.ietf.org/html/rfc3766
371
372Personally, I don't see any problem with using 2048-bit RSA/DH group and 256-bit
373ECC/DH key lengths. So, my recommendation would be:
374
375**Use:**
376
3771. 256-bit minimum for ECC/DH Keys
3782. 2048-bit minimum for RSA/DH Group (but you're not using RSA, right?)
379
380**Avoid:** Not following the above recommendations.
381
382### Asymmetric Signatures
383
384The two dominating use cases within the last 10 years for asymmetric signatures
385are cryptocurrencies and forward-secret key agreement, as with ECDHE-TLS. The
386dominating algorithms for these use cases are all elliptic-curve based. Be wary
387of new systems that use RSA signatures.
388
389In the last few years there has been a major shift away from conventional DSA
390signatures and towards misuse-resistent "deterministic" signature schemes, of
391which EdDSA and RFC6979 are the best examples. You can think of these schemes
392as "user-proofed" responses to the Playstation 3 ECDSA flaw, in which reuse of
393a random number leaked secret keys. Use deterministic signatures in preference
394to any other signature scheme. 
395
396Ed25519, the NaCl default, is by far the most popular public key signature
397scheme outside of Bitcoin. It’s misuse-resistant and carefully designed in
398other ways as well. You shouldn’t freelance this either; get it from NaCl.
399
400**Use, in order of preference:**
401
4021. NaCL, libsodium, or monocypher
4032. Ed25519
4043. RFC6979 (deterministic DSA/ECDSA)
405
406**Avoid:**
407
4081. Anything RSA
4094. ECDSA
4105. DSA
411
412### Diffie-Hellman
413
414Developers should not freelance their own encrypted transports. To get a sense
415of the complexity of this issue, read the documentation for the [Noise Protocol
416Framework][50]. If you're doing a key-exchange with Diffie-Hellman, you
417probably want an authenticated key exchange (AKE) that resists key compromise
418impersonation (KCI), and so the primitive you use for Diffie-Hellman is not the
419only important security concern.
420
421[50]: http://noiseprotocol.org/
422
423It remains the case: if you can just use NaCl, use NaCl. You don’t even have to
424care what NaCl does. That’s the point of NaCl.
425
426Otherwise: use Curve25519. There are libraries for virtually every language. In
4272015, we were worried about encouraging people to write their own Curve25519
428libraries, with visions of Javascript bignum implementations dancing in our
429heads. But really, part of the point of Curve25519 is that the entire curve was
430carefully chosen to minimize implementation errors. Don’t write your own! But
431really, just use Curve25519.
432
433[Don’t do ECDH with the NIST curves][51], where you’ll have to carefully verify
434elliptic curve points before computing with them to avoid leaking secrets. That
435attack is very simple to implement, easier than a CBC padding oracle, and far
436more devastating.
437
438[51]: https://safecurves.cr.yp.to/
439
440The previos edition of this document included a clause about using DH-1024 in
441preference to sketchy curve libraries. You know what? That’s still a valid
442point. Valid and stupid. The way to solve the “DH-1024 vs. sketchy curve
443library” problem is, the same as the “should I use Blowfish or IDEA?” problem.
444Don’t have that problem. Use Curve25519.
445
446**Use, in order of preference:**
447
4481. NaCL, libsodium, or monocypher
4492. Curve25519
4503. 2048-bit Diffie-Hellman Group #14
451
452**Avoid:**
453
4541. Conventional DH
4552. SRP
4563. J-PAKE
4574. Handshakes and negotiation
4585. Elaborate key negotiation schemes that only use block ciphers
4596. srand(time())
460
461### Website security
462
463By "website security", we mean "the library you use to make your web server
464speak HTTPS". If you can pay a web hosting provider to worry about this
465problem for you, then you do that. Otherwise, use OpenSSL.
466
467There was a dark period between 2010 and 2016 where OpenSSL might not have been
468the right answer, but that time has passed. OpenSSL has gotten better, and,
469more importantly, OpenSSL is on-the-ball with vulnerability disclosure and
470response.
471
472Using anything besides OpenSSL will drastically complicate your system for
473little, no, or even negative security benefit. This means avoid [LibreSSL][52],
474[BoringSSL][53], or [BearSSL][54] for the time being. Not because they're bad,
475but because OpenSSL really is the Right Answer here. Just keep it simple; use
476OpenSSL.
477
478[52]: https://www.libressl.org/
479[53]: https://boringssl.googlesource.com/boringssl/
480[54]: https://bearssl.org/
481
482Speaking of simple: [LetsEncrypt][55] is free and automated. Set up a cron job
483to re-fetch certificates regularly, and test it.
484
485[55]: https://letsencrypt.org/
486
487**Use:**
488
4891. A web hosting provider, like AWS.
4902. OpenSSL with Let's Encrypt
491
492**Avoid:**
493
4941. PolarSSL
4952. GnuTLS
4963. MatrixSSL
4974. LibreSSL
4985. BoringSSL
4996. BearSSL
500
501### Client-Server Application Security
502
503What happens when you design your own custom RSA protocol is that 1-18 months
504afterwards, hopefully sooner but often later, you discover that you made a
505mistake and your protocol had virtually no security. A good example is Salt
506Stack. [Salt managed to deploy e=1 RSA][56].
507
508[56]: http://www.cryptofails.com/post/70059600123/saltstack-rsa-e-d-1
509
510It seems a little crazy to recommend TLS given its recent history:
511
512* The Logjam DH negotiation attack
513* The FREAK export cipher attack
514* The POODLE CBC oracle attack
515* The RC4 fiasco
516* The CRIME compression attack
517* The Lucky13 CBC padding oracle timing attack
518* The BEAST CBC chained IV attack
519* Heartbleed
520* Renegotiation
521* Triple Handshakes
522* Compromised CAs
523
524Here's why you should still use TLS for your custom transport problem:
525
526* Many of these attacks only work against browsers, because they rely on the
527  victim accepting and executing attacker-controlled Javascript in order to
528  generate repeated known/chosen plaintexts. 
529* Most of these attacks can be mitigated by hardcoding TLS 1.2+, ECDHE and
530  AES-GCM. That sounds tricky, and it is, but it's less tricky than designing
531  your own transport protocol with ECDHE and AES-GCM! 
532* In a custom transport scenario, you don't need to depend on CAs: you can
533  self-sign a certificate and ship it with your code, just like Colin suggests
534  you do with RSA keys.
535
536**Use:** TLS
537
538**Avoid:**
539
5401. Designing your own encrypted transport, which is a genuinely hard
541   engineering problem;
5422. Using TLS but in a default configuration, like, with "curl"
5433. Using "curl"
5444. IPSEC
545
546### Online Backups
547
548Of course, you should host your own backups in house. The best security is the
549security where others just don't get access to your data.
550
551The best solution, IMO, is OpenZFS. Not only do you get data integrity with
552256-bit checksums, but you get redundancy, volume management, network
553transport, and many other options, all for free. [FreeNAS][57] makes setting this up
554trivial. [Setting it up with Debian GNU/Linux][58] isn't too difficult.
555
556[57]: http://www.freenas.org/
557[58]: https://pthree.org/2012/04/17/install-zfs-on-debian-gnulinux/
558
559If using an online backup service, rather than hosting your own, use
560[Tarsnap][59]. It's withstood the test of time.
561
562[59]: https://www.tarsnap.com/
563
564Alternatively, [Keybase][60] has its own keybase filesystem (KBFS) that
565supports public, private, and team repositories. The [specification is
566sound][61], but they only provide 10 GB for free, without any paid plans
567currently. All data is end-to-end encrypted in your KBFS client before being
568stored on the filesystem, using the NaCl library.
569
570[60]: https://keybase.io/
571[61]: https://keybase.io/docs/crypto/kbfs
572
573**Use:**
574
5751. OpenZFS
5762. Tarsnap
5773. Keybase
578
579**Avoid:**
580
5811. Google
5822. Apple
5833. Microsoft
5844. Dropbox
5855. Amazon S3