Cryptography in NaCl

Cryptography in NaCl Daniel J. Bernstein

?

Department of Computer Science (MC 152) The University of Illinois at Chicago Chicago, IL 60607–7053 [email protected]

1

Introduction

“NaCl” (pronounced “salt”) is the CACE Networking and Cryptography library, a new easy-to-use high-speed high-security public-domain software library for network communication, encryption, decryption, signatures, etc. Of course, other libraries already exist for these core operations; NaCl advances the state of the art by improving security, by improving usability, and by improving speed. The most fundamental operation in a cryptographically protected network protocol is public-key authenticated encryption. The sender, Alice, has a packet of data to send to the receiver, Bob. Alice scrambles the packet using her own secret key and Bob’s public key. Bob unscrambles the packet using his secret key and Alice’s public key. An attacker monitoring the network is unable to understand the scrambled packet; an attacker modifying network packets is unable to change the packet produced by Bob’s unscrambling. With typical cryptographic libraries, public-key authenticated encryption takes several steps. Here is a typical series of steps: • • • • • • • • •

Generate a random AES key. Use the AES key to encrypt the packet. Hash the encrypted packet using SHA-256. Read Alice’s RSA secret key from “wire format.” Use Alice’s RSA secret key to sign the hash. Read Bob’s RSA public key from wire format. Use Bob’s public key to encrypt the AES key, hash, and signature. Convert the encrypted key, hash, and signature to wire format. Concatenate with the encrypted packet.

NaCl provides a high-level function crypto_box that does everything in one step, converting a packet into a boxed packet that is protected against espionage and sabotage. Programmers can use lower-level functions but are encouraged to use crypto_box. In particular, crypto_box_curve25519xsalsa20poly1305 is a specific highspeed high-security combination of the Curve25519 elliptic-curve-Diffie–Hellman ?

Permanent ID of this document: 1ae6a0ecef3073622426b3ee56260d34. Date of this document: 2009.03.10.

function, the Salsa20 stream cipher, and the Poly1305 message-authentication code. This combination is designed for universal use and is shipped in NaCl as the default definition of crypto_box. This document specifies exactly what this combination does: i.e., exactly how the boxed packet produced by crypto_box_curve25519xsalsa20poly1305 relates to the inputs. The specification is expressed as a step-by-step procedure for Alice to encrypt and authenticate a packet; NaCl might compute the boxed packet in a different way but produces exactly the same results. Three of the steps are packet-independent precomputation: • Section 2: Alice creates a 32-byte secret key a and a 32-byte public key A. These keys can be reused for other packets to Bob, for packets to other receivers, and for packets sent back from the receivers. • Section 2, continued: Bob creates a 32-byte secret key b and a 32-byte public key B. These keys can be reused for other packets from Alice, for packets from other senders, and for packets sent back to the senders. • Section 5: Alice, using Alice’s secret key a and Bob’s public key B, computes a 32-byte secret k. Bob can compute the same secret using Bob’s secret key b and Alice’s public key A. The remaining three steps are specific to one packet: • Section 7: Alice, using a 24-byte nonce (unique packet number) n that will never be reused for other packets to (or from) Bob, expands the shared secret k into a long stream of secret bytes. Bob, given the nonce, can compute the same stream. • Section 9: Alice uses the long stream, except for the first 32 bytes, to encrypt the packet m. • Section 9, continued: Alice uses the first 32 bytes of the long stream to compute an authenticator of the encrypted packet. Each section includes security notes and pointers to the relevant literature. This document also contains, in Sections 3, 4, 6, 8, and 10, a complete step-bystep example to illustrate the specification. The intermediate results are printed by various C NaCl programs shown here. This document also contains several tests showing that C NaCl is producing the same results as independent programs in other languages. Some of the tests rely on scripts using the Sage computer-algebra system [20], and some of the tests rely on Python scripts contributed by Matthew Dempsky. This document can be used as a starting point for more comprehensive NaCl validation and verification. In this document, a byte is an element of {0, 1, . . . , 255}. NaCl works with all keys, packets, etc. as strings of bytes. For example, the set of 32-byte strings 32 is the set {0, 1, . . . , 255} .

2

Secret keys and public keys 32

Alice’s secret key is a string a ∈ {0, 1, . . . , 255} . Alice’s public key is a string 32 Curve25519(ClampC(a), 9) ∈ {0, 1, . . . , 255} . Similarly, Bob’s secret key is a

32

string b ∈ {0, 1, . . . , 255} , and Bob’s public key is Curve25519(ClampC(b), 9) ∈ 32 {0, 1, . . . , 255} . This section defines the functions ClampC and Curve25519 and the constant 9. Many of the definitions here are copied from [8, Section 2]; in particular, Curve25519 here is the same as the Curve25519 function defined in [8]. Section 3 gives an example of a secret key and corresponding public key that Alice might choose. Section 4 gives an example of a secret key and corresponding public key that Bob might choose. These examples are reused in subsequent sections. The base field and the elliptic curve. Define p = 2255 − 19. This integer is prime: sage: p=2^255-19 sage: p.is_prime() True Define Fp as the prime field Z/p = Z/(2255 − 19). Note that 2 is not a square in Fp : sage: p=2^255-19 sage: k=GF(p) sage: k(2).is_square() False √ Define Fp2 as the field (Z/(2255 − 19))[ 2]. Define a2 = 486662. Note that a22 − 4 is not a square in Fp : sage: sage: sage: sage: False

p=2^255-19 k=GF(p) a2=486662 (k(a2)^2-4).is_square()

Define E as the elliptic curve y 2 = x3 + a2 x2 + x over Fp , and define E(Fp2 ) as the group of points of E with coordinates in Fp2 . Readers not familiar with elliptic curves can find a self-contained definition of E(Fp2 ) in [8, Appendix A]. Define X0 : E(Fp2 ) → Fp2 as follows: X0 (∞) = 0; X0 (x, y) = x. The Curve25519 function. Write s 7→ s for the standard little-endian bi 32 jection from 0, 1, . . . , 2256 − 1 to {0, 1, . . . , 255} . In other words, for each integer s ∈ 0, 1, . . . , 2256 − 1 , define   s = (s mod 256, bs/256c mod 256, . . . , s/25631 mod 256). 32

For example, the constant 9 is (9, 0, 0, . . . , 0) ∈ {0, 1, . . . , 255} . The set of Curve25519 secret keys is, by definition,{0, 8, 16, 24, . . . , 248}× 30 {0, 1, . . . , 255} × {64, 65, 66, . . . , 127}. If n ∈ 2254 + 8 0, 1, 2, 3, . . . , 2251 − 1

then n is a Curve25519 secret key; and  every Curve25519 secret key can be 254 251 written as n for a unique n ∈ 2 + 8 0, 1, 2, 3, . . . , 2 − 1 . Now the function 32

32

Curve25519 : {Curve25519 secret keys} × {0, 1, . . . , 255} → {0, 1, . . . , 255}  is defined asfollows. Fix an integer n ∈ 2254 + 8 0, 1, 2, 3, . . . , 2251 − 1 and an integer 1, . . . , 2256  q ∈ 0,255 − 1 . By [8, Theorem 2.1] there is a unique integer s ∈ 0, 1, . . . , 2 − 20 such that X0 (nQ) = s for all Q ∈ E(Fp2 ) such that X0 (Q) = q mod 2255 − 19. Finally, Curve25519(n, q) is defined as s. The ClampC function. The function ClampC : {0, 1, . . . , 255}

32

→ {Curve25519 secret keys}

maps (a0 , a1 , . . . , a30 , a31 ) to (a0 − (a0 mod 8), a1 , . . . , a30 , 64 + (a31 mod 64)). In other words, ClampC clears bits (7, 0, . . . , 0, 0, 128) and sets bit (0, 0, . . . , 0, 0, 64). Specialization of Curve25519 for secret keys. Note that 93 + a2 · 92 + 9 = 39420360: sage: a2=486662 sage: 9^3+a2*9^2+9 39420360  If n ∈ 2254 + 8 0, 1, 2, 3, . . . , 2251 − 1 then Curve25519(n, 9) = s, where s is √  the unique integer in 0, 1, . . . , 2255 − 20 such that X0 (n(9, ± 39420360)) = s. Consequently, if Alice’s secret key a satisfies ClampC(a) = n, then Alice’s public key is s. √ The range of n implies that n(9, ± 39420360) 6= ∞, so ∞ could be omitted from the definition of X0 for purposes of computing secret keys. However, Alice also applies Curve25519 to network inputs, as discussed in subsequent sections, and there are several ways that attacker-chosen inputs can lead to the ∞ case. ECDLP security notes. The following notes assume additional familiarity with elliptic curves.√ Write Q = (9, 39420360). The choice of square root is not relevant here. This point Q is in the subgroup E(Fp ) of E(Fp2 ): sage: p=2^255-19 sage: k=GF(p) sage: k(39420360).is_square() True Furthermore, Q has p1 th multiple equal to ∞ in E(Fp ), where p1 is the prime number 2252 + 27742317777372353535851937790883648493: sage: p=2^255-19 sage: k=GF(p) sage: p1=2^252+27742317777372353535851937790883648493

sage: p1.is_prime() True sage: E=EllipticCurve([k(0),486662,0,1,0]) sage: Q=[k(9),sqrt(k(39420360))] sage: p1*E(Q) (0 : 1 : 0) Consequently all multiples of Q are in the subgroup of E(Fp ) of order p1 . If Alice’s secret key a is a uniform random 32-byte string then ClampC(a) is a uniform random Curve25519 secret key; i.e., n, where n/8 is a uniform random integer between 2251 and 2252 − 1. Alice’s public key is nQ compressed to the xcoordinate (as recommended in [17, page 425, fourth paragraph] in 1986). Note that n is not a multiple of p1 ; this justifies the statement above that nQ 6= ∞. The problem of finding Alice’s secret key from Alice’s public key is exactly the elliptic-curve 251-bit-discrete-logarithm problem for the subgroup of E(Fp ) of order p1 ≈ 2252 . The curve E meets all of the standard security criteria, as discussed in detail in [8, Section 3]. The fastest known attacks use, on average, about 2125 additions in E(Fp ), and have success chance degrading quadratically as the number of additions decreases. It is standard in the literature to restrict attention to uniform random secret keys. What if the key distribution is not uniform? The answer depends on the distribution. For example, a key derived from an 8-byte string can be found by brute-force search in roughly 264 operations; and a key derived in an extremely weak way from a 16-byte string, for example by concatenating a 16-byte public constant, can also be found in roughly 264 operations. On the other hand, it is easy to prove that slightly non-uniform keys have essentially full security. Furthermore, I am not aware of any feasible attacks against 32-byte keys of the form (s, MD5(s)), where s is a uniform random 16-byte string; none of the weaknesses of MD5 seem relevant here. Constructions of this type allow secretkey compression and might merit further study if there are any applications where memory is filled with secret keys.

3

Example of the sender’s keys

The following program uses C NaCl to compute the public key corresponding to a particular secret key: #include #include "crypto_scalarmult_curve25519.h" unsigned char alicesk[32] = { 0x77,0x07,0x6d,0x0a,0x73,0x18,0xa5,0x7d ,0x3c,0x16,0xc1,0x72,0x51,0xb2,0x66,0x45 ,0xdf,0x4c,0x2f,0x87,0xeb,0xc0,0x99,0x2a ,0xb1,0x77,0xfb,0xa5,0x1d,0xb9,0x2c,0x2a } ;

unsigned char alicepk[32]; main() { int i; crypto_scalarmult_curve25519_base(alicepk,alicesk); for (i = 0;i < 32;++i) { if (i > 0) printf(","); else printf(" "); printf("0x%02x",(unsigned int) alicepk[i]); if (i % 8 == 7) printf("\n"); } return 0; } The secret key bytes 0xc7,0x6e,... embedded into the program were copied from output of od -t x1 /dev/urandom | head -2. The output of the program is the corresponding public key: 0x85,0x20,0xf0,0x09,0x89,0x30,0xa7,0x54 ,0x74,0x8b,0x7d,0xdc,0xb4,0x3e,0xf7,0x5a ,0x0d,0xbf,0x3a,0x0d,0x26,0x38,0x1a,0xf4 ,0xeb,0xa4,0xa9,0x8e,0xaa,0x9b,0x4e,0x6a The remaining sections of this document will reuse this example, assuming that Alice’s keys are the particular secret key and public key shown here. Testing: Sage vs. scalarmult_curve25519_base. A short Sage script clamps Alice’s √ secret key shown above, converts the result to an integer n, computes n(9, 39420360) in E(Fp ), and checks that the resulting x-coordinate matches the public key computed by C NaCl: sage: ....: ....: ....: sage: sage: sage: sage: sage: sage: sage: sage: sage: ....: ....: ....:

sk=[0x77,0x07,0x6d,0x0a,0x73,0x18,0xa5,0x7d ,0x3c,0x16,0xc1,0x72,0x51,0xb2,0x66,0x45 ,0xdf,0x4c,0x2f,0x87,0xeb,0xc0,0x99,0x2a ,0xb1,0x77,0xfb,0xa5,0x1d,0xb9,0x2c,0x2a] clampsk=sk clampsk[0]=clampsk[0]-(clampsk[0]%8) clampsk[31]=64+(clampsk[31]%64) n=sum(clampsk[i]*256^i for i in range(32)) p=2^255-19 k=GF(p) E=EllipticCurve([k(0),486662,0,1,0]) s=lift((n*E([k(9),sqrt(k(39420360))]))[0]) pk=[0x85,0x20,0xf0,0x09,0x89,0x30,0xa7,0x54 ,0x74,0x8b,0x7d,0xdc,0xb4,0x3e,0xf7,0x5a ,0x0d,0xbf,0x3a,0x0d,0x26,0x38,0x1a,0xf4 ,0xeb,0xa4,0xa9,0x8e,0xaa,0x9b,0x4e,0x6a]

sage: s == sum(pk[i]*256^i for i in range(32)) True Testing: Python vs. scalarmult_curve25519_base. This Python script, contributed by Matthew Dempsky, includes self-contained Curve25519 functions independent of the Sage implementation of elliptic curves: P = 2 ** 255 - 19 A = 486662 def expmod(b, e, m): if e == 0: return 1 t = expmod(b, e / 2, m) ** 2 % m if e & 1: t = (t * b) % m return t def inv(x): return expmod(x, P - 2, P) # Addition and doubling formulas taken # from Appendix D of "Curve25519: # new Diffie-Hellman speed records". def add((xn,zn), (xm,zm), (xd,zd)): x = 4 * (xm * xn - zm * zn) ** 2 * zd z = 4 * (xm * zn - zm * xn) ** 2 * xd return (x % P, z % P) def double((xn,zn)): x = (xn ** 2 - zn ** 2) ** 2 z = 4 * xn * zn * (xn ** 2 + A * xn * zn + zn ** 2) return (x % P, z % P) def curve25519(n, base): one = (base,1) two = double(one) # f(m) evaluates to a tuple # containing the mth multiple and the # (m+1)th multiple of base. def f(m): if m == 1: return (one, two) (pm, pm1) = f(m / 2) if (m & 1): return (add(pm, pm1, one), double(pm1)) return (double(pm), add(pm, pm1, one)) ((x,z), _) = f(n)

return (x * inv(z)) % P def unpack(s): if len(s) != 32: raise ValueError(’Invalid Curve25519 argument’) return sum(ord(s[i]) > (8 * i)) & 255) for i in range(32)]) def clamp(n): n &= ~7 n &= ~(128 0) printf(","); else printf(" "); printf("0x%02x",(unsigned int) k[i]); if (i % 8 == 7) printf("\n"); } return 0; } The program produces the following output: 0x4a,0x5d,0x9d,0x5b,0xa4,0xce,0x2d,0xe1 ,0x72,0x8e,0x3b,0xf4,0x80,0x35,0x0f,0x25 ,0xe0,0x7e,0x21,0xc9,0x47,0xd1,0x9e,0x33 ,0x76,0xf0,0x9b,0x3c,0x1e,0x16,0x17,0x42 The following program, starting from Section 4’s example of Bob’s secret key and Section 3’s example of Alice’s public key, uses C NaCl to compute the secret shared between Alice and Bob:

#include #include "crypto_scalarmult_curve25519.h" unsigned char bobsk[32] = { 0x5d,0xab,0x08,0x7e,0x62,0x4a,0x8a,0x4b ,0x79,0xe1,0x7f,0x8b,0x83,0x80,0x0e,0xe6 ,0x6f,0x3b,0xb1,0x29,0x26,0x18,0xb6,0xfd ,0x1c,0x2f,0x8b,0x27,0xff,0x88,0xe0,0xeb } ; unsigned char alicepk[32] = { 0x85,0x20,0xf0,0x09,0x89,0x30,0xa7,0x54 ,0x74,0x8b,0x7d,0xdc,0xb4,0x3e,0xf7,0x5a ,0x0d,0xbf,0x3a,0x0d,0x26,0x38,0x1a,0xf4 ,0xeb,0xa4,0xa9,0x8e,0xaa,0x9b,0x4e,0x6a } ; unsigned char k[32]; main() { int i; crypto_scalarmult_curve25519(k,bobsk,alicepk); for (i = 0;i < 32;++i) { if (i > 0) printf(","); else printf(" "); printf("0x%02x",(unsigned int) k[i]); if (i % 8 == 7) printf("\n"); } return 0; } This program produces the same output as the previous program. Testing: Sage vs. scalarmult_curve25519. A short Sage script clamps Alice’s secret key, converts the result to an integer n,√clamps Bob’s secret key, converts the result to an integer m, computes mn(9, 39420360) in E(Fp ), and checks that the x-coordinate of the result matches the shared secret computed by C NaCl: sage: ....: ....: ....: sage: sage: sage: sage:

alicesk=[0x77,0x07,0x6d,0x0a,0x73,0x18,0xa5,0x7d ,0x3c,0x16,0xc1,0x72,0x51,0xb2,0x66,0x45 ,0xdf,0x4c,0x2f,0x87,0xeb,0xc0,0x99,0x2a ,0xb1,0x77,0xfb,0xa5,0x1d,0xb9,0x2c,0x2a] clampsk=alicesk clampsk[0]=clampsk[0]-(clampsk[0]%8) clampsk[31]=64+(clampsk[31]%64) n=sum(clampsk[i]*256^i for i in range(32))

sage: ....: ....: ....: sage: sage: sage: sage: sage: sage: sage: sage: sage: ....: ....: ....: sage: True

bobsk=[0x5d,0xab,0x08,0x7e,0x62,0x4a,0x8a,0x4b ,0x79,0xe1,0x7f,0x8b,0x83,0x80,0x0e,0xe6 ,0x6f,0x3b,0xb1,0x29,0x26,0x18,0xb6,0xfd ,0x1c,0x2f,0x8b,0x27,0xff,0x88,0xe0,0xeb] clampsk=bobsk clampsk[0]=clampsk[0]-(clampsk[0]%8) clampsk[31]=64+(clampsk[31]%64) m=sum(clampsk[i]*256^i for i in range(32)) p=2^255-19 k=GF(p) E=EllipticCurve([k(0),486662,0,1,0]) s=lift((m*n*E([k(9),sqrt(k(39420360))]))[0]) shared=[0x4a,0x5d,0x9d,0x5b,0xa4,0xce,0x2d,0xe1 ,0x72,0x8e,0x3b,0xf4,0x80,0x35,0x0f,0x25 ,0xe0,0x7e,0x21,0xc9,0x47,0xd1,0x9e,0x33 ,0x76,0xf0,0x9b,0x3c,0x1e,0x16,0x17,0x42] s == sum(shared[i]*256^i for i in range(32))

Testing: Python vs. scalarmult_curve25519. After the Python script shown in Section 3, the extra commands alicesk=[0x77,0x07,0x6d,0x0a,0x73,0x18,0xa5,0x7d ,0x3c,0x16,0xc1,0x72,0x51,0xb2,0x66,0x45 ,0xdf,0x4c,0x2f,0x87,0xeb,0xc0,0x99,0x2a ,0xb1,0x77,0xfb,0xa5,0x1d,0xb9,0x2c,0x2a] a=’’.join([chr(alicesk[i]) for i in range(32)]) bobpk=[0xde,0x9e,0xdb,0x7d,0x7b,0x7d,0xc1,0xb4 ,0xd3,0x5b,0x61,0xc2,0xec,0xe4,0x35,0x37 ,0x3f,0x83,0x43,0xc8,0x5b,0x78,0x67,0x4d ,0xad,0xfc,0x7e,0x14,0x6f,0x88,0x2b,0x4f] b=’’.join([chr(bobpk[i]) for i in range(32)]) shared=[0x4a,0x5d,0x9d,0x5b,0xa4,0xce,0x2d,0xe1 ,0x72,0x8e,0x3b,0xf4,0x80,0x35,0x0f,0x25 ,0xe0,0x7e,0x21,0xc9,0x47,0xd1,0x9e,0x33 ,0x76,0xf0,0x9b,0x3c,0x1e,0x16,0x17,0x42] s=’’.join([chr(shared[i]) for i in range(32)]) print s == crypto_scalarmult_curve25519(a,b) print true, and the extra commands bobsk=[0x5d,0xab,0x08,0x7e,0x62,0x4a,0x8a,0x4b ,0x79,0xe1,0x7f,0x8b,0x83,0x80,0x0e,0xe6 ,0x6f,0x3b,0xb1,0x29,0x26,0x18,0xb6,0xfd ,0x1c,0x2f,0x8b,0x27,0xff,0x88,0xe0,0xeb] b=’’.join([chr(bobsk[i]) for i in range(32)]) alicepk=[0x85,0x20,0xf0,0x09,0x89,0x30,0xa7,0x54

,0x74,0x8b,0x7d,0xdc,0xb4,0x3e,0xf7,0x5a ,0x0d,0xbf,0x3a,0x0d,0x26,0x38,0x1a,0xf4 ,0xeb,0xa4,0xa9,0x8e,0xaa,0x9b,0x4e,0x6a] a=’’.join([chr(alicepk[i]) for i in range(32)]) shared=[0x4a,0x5d,0x9d,0x5b,0xa4,0xce,0x2d,0xe1 ,0x72,0x8e,0x3b,0xf4,0x80,0x35,0x0f,0x25 ,0xe0,0x7e,0x21,0xc9,0x47,0xd1,0x9e,0x33 ,0x76,0xf0,0x9b,0x3c,0x1e,0x16,0x17,0x42] s=’’.join([chr(shared[i]) for i in range(32)]) print s == crypto_scalarmult_curve25519(b,a) print true.

7

Nonce and stream 32

At this point Alice and Bob have a shared secret k ∈ {0, 1, . . . , 255} . This secret can be used to protect a practically infinite sequence of packets exchanged between Alice and Bob. 24 Alice and Bob assign to each packet a nonce n ∈ {0, 1, . . . , 255} : a unique message number that will never be reused for other packets exchanged between Alice and Bob. For example, the nonce can be chosen as a simple counter: 0 for Alice’s first packet, 1 for Bob’s first packet, 2 for Alice’s second packet, 3 for Bob’s second packet, 4 for Alice’s third packet, 5 for Bob’s third packet, etc. Choosing the nonce as a counter followed by (e.g.) 32 random bits helps protect some protocols against denial-of-service attacks. In many applications it is better to increase the counter to, e.g., the number of nanoseconds that have passed since a standard epoch in the local clock, so that the current value of the counter does not leak the traffic rate. Note that “increase” does not mean “increase or decrease”; if the clock jumps backwards, the counter must continue to increase. Alice uses the shared secret k to expand the nonce n into a long stream. Specifically, Alice computes a first-level key HSalsa20(k, 0); uses the first 16 bytes n1 of the nonce to compute a second-level key HSalsa20(HSalsa20(k, 0), n1 ); and uses the remaining 8 bytes n2 of the nonce to compute a long stream Salsa20(HSalsa20(HSalsa20(k, 0), n1 ), n2 ). This stream is then used to encrypt and authenticate the packet, as described in subsequent sections. This section defines HSalsa20 and Salsa20. Many of the definitions here are copied from the original Salsa20 specification [7]. Section 8 gives an example of nonce expansion, starting from the key examples used in Sections 4, 3, and 6.  Words. A word is an element of 0, 1, . . . , 232 − 1 . The sum of two words u, v is u + v mod 232 . The sum is denoted u + v; there is no risk of confusion. For example, 0xc0a8787e + 0x9fd1161d = 0x60798e9b. The exclusive-or of two words u, v, denoted sum of u and v with P i u⊕v, is theP carries suppressed. In other words, if u = 2 u and v = 2i vi then u ⊕ v = i i P i i 2 (ui + vi − 2ui vi ). For example, 0xc0a8787e ⊕ 0x9fd1161d = 0x5f796e63.

For each c ∈ {0, 1, 2, 3, . . .}, the c-bit left rotation of a word u, denoted u