Authenticated encryption for transport messages

1// Copyright (c) 2023-present The Bitcoin Core developers
2// Distributed under the MIT software license, see the accompanying
3// file COPYING or http://www.opensource.org/licenses/mit-license.php.
4
5#ifndef BITCOIN_CRYPTO_CHACHA20POLY1305_H
6#define BITCOIN_CRYPTO_CHACHA20POLY1305_H
7
8#include <cstddef>
9#include <cstdint>
10#include <span>
11
12#include <crypto/chacha20.h>
13#include <crypto/poly1305.h>
14
15/** The AEAD_CHACHA20_POLY1305 authenticated encryption algorithm from RFC8439 section 2.8. */
16class AEADChaCha20Poly1305
17{
18    /** Internal stream cipher. */
19    ChaCha20 m_chacha20;
20
21public:
22    /** Expected size of key argument in constructor. */
23    static constexpr unsigned KEYLEN = 32;
24
25    /** Expansion when encrypting. */
26    static constexpr unsigned EXPANSION = Poly1305::TAGLEN;
27
28    /** Initialize an AEAD instance with a specified 32-byte key. */
29    AEADChaCha20Poly1305(std::span<const std::byte> key) noexcept;
30
31    /** Switch to another 32-byte key. */
32    void SetKey(std::span<const std::byte> key) noexcept;
33
34    /** 96-bit nonce type. */
35    using Nonce96 = ChaCha20::Nonce96;
36
37    /** Encrypt a message with a specified 96-bit nonce and aad.
38     *
39     * Requires cipher.size() = plain.size() + EXPANSION.
40     */
41    void Encrypt(std::span<const std::byte> plain, std::span<const std::byte> aad, Nonce96 nonce, std::span<std::byte> cipher) noexcept
42    {
43        Encrypt(plain, {}, aad, nonce, cipher);
44    }
45
46    /** Encrypt a message (given split into plain1 + plain2) with a specified 96-bit nonce and aad.
47     *
48     * Requires cipher.size() = plain1.size() + plain2.size() + EXPANSION.
49     */
50    void Encrypt(std::span<const std::byte> plain1, std::span<const std::byte> plain2, std::span<const std::byte> aad, Nonce96 nonce, std::span<std::byte> cipher) noexcept;
51
52    /** Decrypt a message with a specified 96-bit nonce and aad. Returns true if valid.
53     *
54     * Requires cipher.size() = plain.size() + EXPANSION.
55     */
56    bool Decrypt(std::span<const std::byte> cipher, std::span<const std::byte> aad, Nonce96 nonce, std::span<std::byte> plain) noexcept
57    {
58        return Decrypt(cipher, aad, nonce, plain, {});
59    }
60
61    /** Decrypt a message with a specified 96-bit nonce and aad and split the result. Returns true if valid.
62     *
63     * Requires cipher.size() = plain1.size() + plain2.size() + EXPANSION.
64     */
65    bool Decrypt(std::span<const std::byte> cipher, std::span<const std::byte> aad, Nonce96 nonce, std::span<std::byte> plain1, std::span<std::byte> plain2) noexcept;
66
67    /** Get a number of keystream bytes from the underlying stream cipher.
68     *
69     * This is equivalent to Encrypt() with plain set to that many zero bytes, and dropping the
70     * last EXPANSION bytes off the result.
71     */
72    void Keystream(Nonce96 nonce, std::span<std::byte> keystream) noexcept;
73};
74
75/** Forward-secure wrapper around AEADChaCha20Poly1305.
76 *
77 * This implements an AEAD which automatically increments the nonce on every encryption or
78 * decryption, and cycles keys after a predetermined number of encryptions or decryptions.
79 *
80 * See BIP324 for details.
81 */
82class FSChaCha20Poly1305
83{
84private:
85    /** Internal AEAD. */
86    AEADChaCha20Poly1305 m_aead;
87
88    /** Every how many iterations this cipher rekeys. */
89    const uint32_t m_rekey_interval;
90
91    /** The number of encryptions/decryptions since the last rekey. */
92    uint32_t m_packet_counter{0};
93
94    /** The number of rekeys performed so far. */
95    uint64_t m_rekey_counter{0};
96
97    /** Update counters (and if necessary, key) to transition to the next message. */
98    void NextPacket() noexcept;
99
100public:
101    /** Length of keys expected by the constructor. */
102    static constexpr auto KEYLEN = AEADChaCha20Poly1305::KEYLEN;
103
104    /** Expansion when encrypting. */
105    static constexpr auto EXPANSION = AEADChaCha20Poly1305::EXPANSION;
106
107    // No copy or move to protect the secret.
108    FSChaCha20Poly1305(const FSChaCha20Poly1305&) = delete;
109    FSChaCha20Poly1305(FSChaCha20Poly1305&&) = delete;
110    FSChaCha20Poly1305& operator=(const FSChaCha20Poly1305&) = delete;
111    FSChaCha20Poly1305& operator=(FSChaCha20Poly1305&&) = delete;
112
113    /** Construct an FSChaCha20Poly1305 cipher that rekeys every rekey_interval operations. */
114    FSChaCha20Poly1305(std::span<const std::byte> key, uint32_t rekey_interval) noexcept :
115        m_aead(key), m_rekey_interval(rekey_interval) {}
116
117    /** Encrypt a message with a specified aad.
118     *
119     * Requires cipher.size() = plain.size() + EXPANSION.
120     */
121    void Encrypt(std::span<const std::byte> plain, std::span<const std::byte> aad, std::span<std::byte> cipher) noexcept
122    {
123        Encrypt(plain, {}, aad, cipher);
124    }
125
126    /** Encrypt a message (given split into plain1 + plain2) with a specified aad.
127     *
128     * Requires cipher.size() = plain.size() + EXPANSION.
129     */
130    void Encrypt(std::span<const std::byte> plain1, std::span<const std::byte> plain2, std::span<const std::byte> aad, std::span<std::byte> cipher) noexcept;
131
132    /** Decrypt a message with a specified aad. Returns true if valid.
133     *
134     * Requires cipher.size() = plain.size() + EXPANSION.
135     */
136    bool Decrypt(std::span<const std::byte> cipher, std::span<const std::byte> aad, std::span<std::byte> plain) noexcept
137    {
138        return Decrypt(cipher, aad, plain, {});
139    }
140
141    /** Decrypt a message with a specified aad and split the result. Returns true if valid.
142     *
143     * Requires cipher.size() = plain1.size() + plain2.size() + EXPANSION.
144     */
145    bool Decrypt(std::span<const std::byte> cipher, std::span<const std::byte> aad, std::span<std::byte> plain1, std::span<std::byte> plain2) noexcept;
146};
147
148#endif // BITCOIN_CRYPTO_CHACHA20POLY1305_H
149