1f7167e0eSDag-Erling SmørgravThis document describes the chacha20-poly1305@openssh.com authenticated 2f7167e0eSDag-Erling Smørgravencryption cipher supported by OpenSSH. 3f7167e0eSDag-Erling Smørgrav 4f7167e0eSDag-Erling SmørgravBackground 5f7167e0eSDag-Erling Smørgrav---------- 6f7167e0eSDag-Erling Smørgrav 7f7167e0eSDag-Erling SmørgravChaCha20 is a stream cipher designed by Daniel Bernstein and described 8f7167e0eSDag-Erling Smørgravin [1]. It operates by permuting 128 fixed bits, 128 or 256 bits of key, 9f7167e0eSDag-Erling Smørgrava 64 bit nonce and a 64 bit counter into 64 bytes of output. This output 10f7167e0eSDag-Erling Smørgravis used as a keystream, with any unused bytes simply discarded. 11f7167e0eSDag-Erling Smørgrav 12f7167e0eSDag-Erling SmørgravPoly1305[2], also by Daniel Bernstein, is a one-time Carter-Wegman MAC 13f7167e0eSDag-Erling Smørgravthat computes a 128 bit integrity tag given a message and a single-use 14f7167e0eSDag-Erling Smørgrav256 bit secret key. 15f7167e0eSDag-Erling Smørgrav 16f7167e0eSDag-Erling SmørgravThe chacha20-poly1305@openssh.com combines these two primitives into an 17f7167e0eSDag-Erling Smørgravauthenticated encryption mode. The construction used is based on that 18f7167e0eSDag-Erling Smørgravproposed for TLS by Adam Langley in [3], but differs in the layout of 19190cef3dSDag-Erling Smørgravdata passed to the MAC and in the addition of encryption of the packet 20f7167e0eSDag-Erling Smørgravlengths. 21f7167e0eSDag-Erling Smørgrav 22f7167e0eSDag-Erling SmørgravNegotiation 23f7167e0eSDag-Erling Smørgrav----------- 24f7167e0eSDag-Erling Smørgrav 25f7167e0eSDag-Erling SmørgravThe chacha20-poly1305@openssh.com offers both encryption and 26f7167e0eSDag-Erling Smørgravauthentication. As such, no separate MAC is required. If the 27f7167e0eSDag-Erling Smørgravchacha20-poly1305@openssh.com cipher is selected in key exchange, 28f7167e0eSDag-Erling Smørgravthe offered MAC algorithms are ignored and no MAC is required to be 29f7167e0eSDag-Erling Smørgravnegotiated. 30f7167e0eSDag-Erling Smørgrav 31f7167e0eSDag-Erling SmørgravDetailed Construction 32f7167e0eSDag-Erling Smørgrav--------------------- 33f7167e0eSDag-Erling Smørgrav 34f7167e0eSDag-Erling SmørgravThe chacha20-poly1305@openssh.com cipher requires 512 bits of key 35f7167e0eSDag-Erling Smørgravmaterial as output from the SSH key exchange. This forms two 256 bit 36f7167e0eSDag-Erling Smørgravkeys (K_1 and K_2), used by two separate instances of chacha20. 37*19261079SEd MasteThe first 256 bits constitute K_2 and the second 256 bits become 38076ad2f8SDag-Erling SmørgravK_1. 39f7167e0eSDag-Erling Smørgrav 40f7167e0eSDag-Erling SmørgravThe instance keyed by K_1 is a stream cipher that is used only 41f7167e0eSDag-Erling Smørgravto encrypt the 4 byte packet length field. The second instance, 42f7167e0eSDag-Erling Smørgravkeyed by K_2, is used in conjunction with poly1305 to build an AEAD 43f7167e0eSDag-Erling Smørgrav(Authenticated Encryption with Associated Data) that is used to encrypt 44f7167e0eSDag-Erling Smørgravand authenticate the entire packet. 45f7167e0eSDag-Erling Smørgrav 46f7167e0eSDag-Erling SmørgravTwo separate cipher instances are used here so as to keep the packet 47f7167e0eSDag-Erling Smørgravlengths confidential but not create an oracle for the packet payload 48f7167e0eSDag-Erling Smørgravcipher by decrypting and using the packet length prior to checking 49f7167e0eSDag-Erling Smørgravthe MAC. By using an independently-keyed cipher instance to encrypt the 50f7167e0eSDag-Erling Smørgravlength, an active attacker seeking to exploit the packet input handling 51f7167e0eSDag-Erling Smørgravas a decryption oracle can learn nothing about the payload contents or 52f7167e0eSDag-Erling Smørgravits MAC (assuming key derivation, ChaCha20 and Poly1305 are secure). 53f7167e0eSDag-Erling Smørgrav 54f7167e0eSDag-Erling SmørgravThe AEAD is constructed as follows: for each packet, generate a Poly1305 55f7167e0eSDag-Erling Smørgravkey by taking the first 256 bits of ChaCha20 stream output generated 56f7167e0eSDag-Erling Smørgravusing K_2, an IV consisting of the packet sequence number encoded as an 57f7167e0eSDag-Erling Smørgravuint64 under the SSH wire encoding rules and a ChaCha20 block counter of 58f7167e0eSDag-Erling Smørgravzero. The K_2 ChaCha20 block counter is then set to the little-endian 59f7167e0eSDag-Erling Smørgravencoding of 1 (i.e. {1, 0, 0, 0, 0, 0, 0, 0}) and this instance is used 60f7167e0eSDag-Erling Smørgravfor encryption of the packet payload. 61f7167e0eSDag-Erling Smørgrav 62f7167e0eSDag-Erling SmørgravPacket Handling 63f7167e0eSDag-Erling Smørgrav--------------- 64f7167e0eSDag-Erling Smørgrav 65f7167e0eSDag-Erling SmørgravWhen receiving a packet, the length must be decrypted first. When 4 66f7167e0eSDag-Erling Smørgravbytes of ciphertext length have been received, they may be decrypted 67f7167e0eSDag-Erling Smørgravusing the K_1 key, a nonce consisting of the packet sequence number 68f7167e0eSDag-Erling Smørgravencoded as a uint64 under the usual SSH wire encoding and a zero block 69f7167e0eSDag-Erling Smørgravcounter to obtain the plaintext length. 70f7167e0eSDag-Erling Smørgrav 71f7167e0eSDag-Erling SmørgravOnce the entire packet has been received, the MAC MUST be checked 72f7167e0eSDag-Erling Smørgravbefore decryption. A per-packet Poly1305 key is generated as described 73f7167e0eSDag-Erling Smørgravabove and the MAC tag calculated using Poly1305 with this key over the 74f7167e0eSDag-Erling Smørgravciphertext of the packet length and the payload together. The calculated 75f7167e0eSDag-Erling SmørgravMAC is then compared in constant time with the one appended to the 76f7167e0eSDag-Erling Smørgravpacket and the packet decrypted using ChaCha20 as described above (with 77f7167e0eSDag-Erling SmørgravK_2, the packet sequence number as nonce and a starting block counter of 78f7167e0eSDag-Erling Smørgrav1). 79f7167e0eSDag-Erling Smørgrav 80f7167e0eSDag-Erling SmørgravTo send a packet, first encode the 4 byte length and encrypt it using 81f7167e0eSDag-Erling SmørgravK_1. Encrypt the packet payload (using K_2) and append it to the 82f7167e0eSDag-Erling Smørgravencrypted length. Finally, calculate a MAC tag and append it. 83f7167e0eSDag-Erling Smørgrav 84f7167e0eSDag-Erling SmørgravRekeying 85f7167e0eSDag-Erling Smørgrav-------- 86f7167e0eSDag-Erling Smørgrav 87f7167e0eSDag-Erling SmørgravChaCha20 must never reuse a {key, nonce} for encryption nor may it be 88f7167e0eSDag-Erling Smørgravused to encrypt more than 2^70 bytes under the same {key, nonce}. The 89f7167e0eSDag-Erling SmørgravSSH Transport protocol (RFC4253) recommends a far more conservative 90f7167e0eSDag-Erling Smørgravrekeying every 1GB of data sent or received. If this recommendation 91f7167e0eSDag-Erling Smørgravis followed, then chacha20-poly1305@openssh.com requires no special 92f7167e0eSDag-Erling Smørgravhandling in this area. 93f7167e0eSDag-Erling Smørgrav 94f7167e0eSDag-Erling SmørgravReferences 95f7167e0eSDag-Erling Smørgrav---------- 96f7167e0eSDag-Erling Smørgrav 97f7167e0eSDag-Erling Smørgrav[1] "ChaCha, a variant of Salsa20", Daniel Bernstein 98f7167e0eSDag-Erling Smørgrav http://cr.yp.to/chacha/chacha-20080128.pdf 99f7167e0eSDag-Erling Smørgrav 100f7167e0eSDag-Erling Smørgrav[2] "The Poly1305-AES message-authentication code", Daniel Bernstein 101f7167e0eSDag-Erling Smørgrav http://cr.yp.to/mac/poly1305-20050329.pdf 102f7167e0eSDag-Erling Smørgrav 103f7167e0eSDag-Erling Smørgrav[3] "ChaCha20 and Poly1305 based Cipher Suites for TLS", Adam Langley 104f7167e0eSDag-Erling Smørgrav http://tools.ietf.org/html/draft-agl-tls-chacha20poly1305-03 105f7167e0eSDag-Erling Smørgrav 106*19261079SEd Maste$OpenBSD: PROTOCOL.chacha20poly1305,v 1.5 2020/02/21 00:04:43 dtucker Exp $ 107f7167e0eSDag-Erling Smørgrav 108