READ THE CODE

Inside Bitcoin

The code behind the network, with room to understand it.

Stable release v32.1bitcoin/bitcoin · f0de87f04062 ↗3,020 source files · 47.5 MB stored on the server440 file guides

Release published 2026-10-28 · Snapshot fetched 2026-11-01. Latest stable release at fetch time; development branches and Git history are excluded. Only the selected code window and visible folders load here.

7,574 bytes · SHA-256 c0b383e8c1ee47cd… · View upstream ↗

1#!/usr/bin/env python3
2# Copyright (c) 2022-present The Bitcoin Core developers
3# Distributed under the MIT software license, see the accompanying
4# file COPYING or http://www.opensource.org/licenses/mit-license.php.
5
6"""Test-only implementation of ChaCha20 cipher and FSChaCha20 for BIP 324
7
8It is designed for ease of understanding, not performance.
9
10WARNING: This code is slow and trivially vulnerable to side channel attacks. Do not use for
11anything but tests.
12"""
13
14import unittest
15
16CHACHA20_INDICES = (
17    (0, 4, 8, 12), (1, 5, 9, 13), (2, 6, 10, 14), (3, 7, 11, 15),
18    (0, 5, 10, 15), (1, 6, 11, 12), (2, 7, 8, 13), (3, 4, 9, 14)
19)
20
21CHACHA20_CONSTANTS = (0x61707865, 0x3320646e, 0x79622d32, 0x6b206574)
22REKEY_INTERVAL = 224 # packets
23
24
25def rotl32(v, bits):
26    """Rotate the 32-bit value v left by bits bits."""
27    bits %= 32  # Make sure the term below does not throw an exception
28    return ((v << bits) & 0xffffffff) | (v >> (32 - bits))
29
30
31def chacha20_doubleround(s):
32    """Apply a ChaCha20 double round to 16-element state array s.
33    See https://cr.yp.to/chacha/chacha-20080128.pdf and https://tools.ietf.org/html/rfc8439
34    """
35    for a, b, c, d in CHACHA20_INDICES:
36        s[a] = (s[a] + s[b]) & 0xffffffff
37        s[d] = rotl32(s[d] ^ s[a], 16)
38        s[c] = (s[c] + s[d]) & 0xffffffff
39        s[b] = rotl32(s[b] ^ s[c], 12)
40        s[a] = (s[a] + s[b]) & 0xffffffff
41        s[d] = rotl32(s[d] ^ s[a], 8)
42        s[c] = (s[c] + s[d]) & 0xffffffff
43        s[b] = rotl32(s[b] ^ s[c], 7)
44
45
46def chacha20_block(key, nonce, cnt):
47    """Compute the 64-byte output of the ChaCha20 block function.
48    Takes as input a 32-byte key, 12-byte nonce, and 32-bit integer counter.
49    """
50    # Initial state.
51    init = [0] * 16
52    init[:4] = CHACHA20_CONSTANTS[:4]
53    init[4:12] = [int.from_bytes(key[i:i+4], 'little') for i in range(0, 32, 4)]
54    init[12] = cnt
55    init[13:16] = [int.from_bytes(nonce[i:i+4], 'little') for i in range(0, 12, 4)]
56    # Perform 20 rounds.
57    state = list(init)
58    for _ in range(10):
59        chacha20_doubleround(state)
60    # Add initial values back into state.
61    for i in range(16):
62        state[i] = (state[i] + init[i]) & 0xffffffff
63    # Produce byte output
64    return b''.join(state[i].to_bytes(4, 'little') for i in range(16))
65
66class FSChaCha20:
67    """Rekeying wrapper stream cipher around ChaCha20."""
68    def __init__(self, initial_key, rekey_interval=REKEY_INTERVAL):
69        self._key = initial_key
70        self._rekey_interval = rekey_interval
71        self._block_counter = 0
72        self._chunk_counter = 0
73        self._keystream = b''
74
75    def _get_keystream_bytes(self, nbytes):
76        while len(self._keystream) < nbytes:
77            nonce = ((0).to_bytes(4, 'little') + (self._chunk_counter // self._rekey_interval).to_bytes(8, 'little'))
78            self._keystream += chacha20_block(self._key, nonce, self._block_counter)
79            self._block_counter += 1
80        ret = self._keystream[:nbytes]
81        self._keystream = self._keystream[nbytes:]
82        return ret
83
84    def crypt(self, chunk):
85        ks = self._get_keystream_bytes(len(chunk))
86        ret = bytes([ks[i] ^ chunk[i] for i in range(len(chunk))])
87        if ((self._chunk_counter + 1) % self._rekey_interval) == 0:
88            self._key = self._get_keystream_bytes(32)
89            self._block_counter = 0
90            self._keystream = b''
91        self._chunk_counter += 1
92        return ret
93
94
95# Test vectors from RFC7539/8439 consisting of 32 byte key, 12 byte nonce, block counter
96# and 64 byte output after applying `chacha20_block` function
97CHACHA20_TESTS = [
98    ["000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f", [0x09000000, 0x4a000000], 1,
99     "10f1e7e4d13b5915500fdd1fa32071c4c7d1f4c733c068030422aa9ac3d46c4e"
100     "d2826446079faa0914c2d705d98b02a2b5129cd1de164eb9cbd083e8a2503c4e"],
101    ["0000000000000000000000000000000000000000000000000000000000000000", [0, 0], 0,
102     "76b8e0ada0f13d90405d6ae55386bd28bdd219b8a08ded1aa836efcc8b770dc7"
103     "da41597c5157488d7724e03fb8d84a376a43b8f41518a11cc387b669b2ee6586"],
104    ["0000000000000000000000000000000000000000000000000000000000000000", [0, 0], 1,
105     "9f07e7be5551387a98ba977c732d080dcb0f29a048e3656912c6533e32ee7aed"
106     "29b721769ce64e43d57133b074d839d531ed1f28510afb45ace10a1f4b794d6f"],
107    ["0000000000000000000000000000000000000000000000000000000000000001", [0, 0], 1,
108     "3aeb5224ecf849929b9d828db1ced4dd832025e8018b8160b82284f3c949aa5a"
109     "8eca00bbb4a73bdad192b5c42f73f2fd4e273644c8b36125a64addeb006c13a0"],
110    ["00ff000000000000000000000000000000000000000000000000000000000000", [0, 0], 2,
111     "72d54dfbf12ec44b362692df94137f328fea8da73990265ec1bbbea1ae9af0ca"
112     "13b25aa26cb4a648cb9b9d1be65b2c0924a66c54d545ec1b7374f4872e99f096"],
113    ["0000000000000000000000000000000000000000000000000000000000000000", [0, 0x200000000000000], 0,
114     "c2c64d378cd536374ae204b9ef933fcd1a8b2288b3dfa49672ab765b54ee27c7"
115     "8a970e0e955c14f3a88e741b97c286f75f8fc299e8148362fa198a39531bed6d"],
116    ["000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f", [0, 0x4a000000], 1,
117     "224f51f3401bd9e12fde276fb8631ded8c131f823d2c06e27e4fcaec9ef3cf78"
118     "8a3b0aa372600a92b57974cded2b9334794cba40c63e34cdea212c4cf07d41b7"],
119    ["0000000000000000000000000000000000000000000000000000000000000001", [0, 0], 0,
120     "4540f05a9f1fb296d7736e7b208e3c96eb4fe1834688d2604f450952ed432d41"
121     "bbe2a0b6ea7566d2a5d1e7e20d42af2c53d792b1c43fea817e9ad275ae546963"],
122    ["0000000000000000000000000000000000000000000000000000000000000000", [0, 1], 0,
123     "ef3fdfd6c61578fbf5cf35bd3dd33b8009631634d21e42ac33960bd138e50d32"
124     "111e4caf237ee53ca8ad6426194a88545ddc497a0b466e7d6bbdb0041b2f586b"],
125    ["000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f", [0, 0x0706050403020100], 0,
126     "f798a189f195e66982105ffb640bb7757f579da31602fc93ec01ac56f85ac3c1"
127     "34a4547b733b46413042c9440049176905d3be59ea1c53f15916155c2be8241a"],
128]
129
130FSCHACHA20_TESTS = [
131    ["000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
132     "0000000000000000000000000000000000000000000000000000000000000000", 256,
133     "a93df4ef03011f3db95f60d996e1785df5de38fc39bfcb663a47bb5561928349"],
134    ["01", "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f", 5, "ea"],
135    ["e93fdb5c762804b9a706816aca31e35b11d2aa3080108ef46a5b1f1508819c0a",
136     "8ec4c3ccdaea336bdeb245636970be01266509b33f3d2642504eaf412206207a", 4096,
137     "8bfaa4eacff308fdb4a94a5ff25bd9d0c1f84b77f81239f67ff39d6e1ac280c9"],
138]
139
140
141class TestFrameworkChacha(unittest.TestCase):
142    def test_chacha20(self):
143        """ChaCha20 test vectors."""
144        for test_vector in CHACHA20_TESTS:
145            hex_key, nonce, counter, hex_output = test_vector
146            key = bytes.fromhex(hex_key)
147            nonce_bytes = nonce[0].to_bytes(4, 'little') + nonce[1].to_bytes(8, 'little')
148            keystream = chacha20_block(key, nonce_bytes, counter)
149            self.assertEqual(hex_output, keystream.hex())
150
151    def test_fschacha20(self):
152        """FSChaCha20 test vectors."""
153        for test_vector in FSCHACHA20_TESTS:
154            hex_plaintext, hex_key, rekey_interval, hex_ciphertext_after_rotation = test_vector
155            plaintext = bytes.fromhex(hex_plaintext)
156            key = bytes.fromhex(hex_key)
157            fsc20 = FSChaCha20(key, rekey_interval)
158            for _ in range(rekey_interval):
159                fsc20.crypt(plaintext)
160
161            ciphertext = fsc20.crypt(plaintext)
162            self.assertEqual(hex_ciphertext_after_rotation, ciphertext.hex())
163

src/wallet/receive.cpp

src/wallet/coinselection.cpp

src/consensus/validation.h

src/primitives/transaction.cpp

src/script/descriptor.cpp

src/bitcoin-cli.cpp

src/rpc/blockchain.cpp

src/rpc/rawtransaction.cpp

src/init.cpp

src/crypto/sha256.cpp

src/consensus/merkle.h

src/consensus/tx_check.h

src/consensus/tx_verify.h

src/policy/feerate.h

src/policy/feerate.cpp

src/primitives/transaction_identifier.h

src/chainparamsbase.h

src/chainparamsbase.cpp

src/util/moneystr.cpp

src/crypto/ripemd160.h

src/crypto/sha1.h

src/crypto/sha512.h

src/crypto/hmac_sha256.h

src/crypto/hmac_sha512.h

src/crypto/hmac_sha256.cpp

src/crypto/hmac_sha512.cpp

src/crypto/hkdf_sha256_32.h

src/crypto/hkdf_sha256_32.cpp

src/support/cleanse.h

src/support/cleanse.cpp

src/crypto/siphash.cpp

src/crypto/muhash.h

src/crypto/chacha20.h

src/crypto/poly1305.h

src/crypto/chacha20poly1305.h

src/crypto/chacha20poly1305.cpp

src/util/chaintype.cpp

src/util/obfuscation.h

src/util/byte_units.h

src/util/overflow.h

src/blockencodings.cpp

src/net_permissions.cpp

src/policy/packages.cpp

src/policy/rbf.cpp

src/policy/truc_policy.cpp

src/policy/ephemeral_policy.cpp

src/policy/settings.cpp

src/policy/policy.cpp

src/node/transaction.cpp

src/node/coin.cpp

src/rpc/client.cpp

src/rpc/external_signer.cpp

src/rpc/request.cpp

src/rpc/server_util.cpp

src/rpc/fees.cpp

src/rpc/output_script.cpp

src/rpc/rawtransaction_util.cpp

src/rpc/rawtransaction_util.h

src/rpc/register.h

src/rpc/request.h

src/rpc/server_util.h

src/rpc/protocol.h

src/rpc/server.h

src/rpc/signmessage.cpp

src/rpc/txoutproof.cpp

src/rpc/util.cpp

src/rpc/util.h

src/wallet/rpc/addresses.cpp

src/wallet/rpc/backup.cpp

src/wallet/rpc/coins.cpp

src/wallet/rpc/encrypt.cpp

src/wallet/rpc/signmessage.cpp

src/wallet/rpc/util.cpp

src/wallet/rpc/util.h

src/wallet/coincontrol.cpp

src/wallet/coincontrol.h

src/wallet/context.cpp

src/wallet/context.h

src/wallet/crypter.cpp

src/wallet/crypter.h

src/wallet/db.cpp

src/wallet/export.cpp

src/wallet/external_signer_scriptpubkeyman.cpp

src/wallet/rpc/spend.cpp

src/wallet/rpc/transactions.cpp

src/wallet/rpc/wallet.cpp

src/wallet/feebumper.cpp

src/wallet/feebumper.h

src/index/base.h

src/index/base.cpp

src/index/txindex.h

src/index/txindex.cpp

src/index/txindex_key.h

src/index/txospenderindex.h

src/index/txospenderindex.cpp

src/index/blockfilterindex.h

src/index/blockfilterindex.cpp

src/index/coinstatsindex.h

src/index/coinstatsindex.cpp

src/index/db_key.h

src/index/disktxpos.h

src/kernel/chain.cpp

src/kernel/chain.h

src/kernel/checks.cpp

src/kernel/checks.h

src/kernel/context.cpp

src/kernel/context.h

src/kernel/cs_main.cpp

src/kernel/cs_main.h

src/kernel/disconnected_transactions.cpp

src/kernel/disconnected_transactions.h

src/kernel/mempool_removal_reason.cpp

src/kernel/mempool_removal_reason.h

src/kernel/coinstats.cpp

src/kernel/coinstats.h

src/kernel/chainparams.cpp

src/kernel/chainparams.h

src/wallet/sqlite.cpp

src/wallet/sqlite.h

src/wallet/transaction.cpp

src/wallet/transaction.h

src/wallet/dump.cpp

src/wallet/dump.h

src/wallet/init.cpp

src/wallet/walletutil.cpp

src/wallet/walletutil.h

src/wallet/wallettool.cpp

src/wallet/wallettool.h

src/wallet/export.h

src/wallet/migrate.cpp

src/wallet/migrate.h

src/wallet/db.h

src/wallet/walletdb.cpp

src/wallet/interfaces.cpp

src/wallet/scriptpubkeyman.cpp

src/wallet/scriptpubkeyman.h

src/kernel/bitcoinkernel.cpp

src/kernel/bitcoinkernel.h

src/kernel/bitcoinkernel_wrapper.h

src/node/chainstate.cpp

src/node/chainstate.h

src/node/blockstorage.cpp

src/node/blockstorage.h

src/node/mempool_persist.cpp

src/node/mempool_persist.h

src/node/utxo_snapshot.cpp

src/node/utxo_snapshot.h

src/node/kernel_notifications.cpp

src/node/kernel_notifications.h

src/node/blockmanager_args.cpp

src/kernel/blockmanager_opts.h

src/util/expected.cpp

src/policy/settings.h

src/util/types.h

src/kernel/messagestartchars.h

src/kernel/warning.h

src/util/exception.h

src/common/license_info.h

src/node/coins_view_args.h

src/node/database_args.h

src/util/batchpriority.h

src/util/ui_change_type.h

src/node/coins_view_args.cpp

src/node/peerman_args.h

src/util/serfloat.h

src/node/blockmanager_args.h

src/node/database_args.cpp

src/util/overloaded.h

src/interfaces/types.h

src/node/chainstatemanager_args.h

src/node/minisketchwrapper.h

src/util/macros.h

src/util/syserror.h

src/common/run_command.h

src/util/bytevectorhash.cpp

src/node/mempool_persist_args.cpp

src/util/exec.h

src/util/rbf.h

src/crypto/hex_base.h

src/node/mempool_persist_args.h

src/interfaces/echo.h

src/util/any.h

src/util/batchpriority.cpp

src/util/threadnames.h

src/node/coin.h

src/node/mempool_args.h

src/util/asmap.h

src/util/bytevectorhash.h

src/node/context.cpp

src/util/insert.h

src/util/readwritefile.h

src/node/peerman_args.cpp

src/node/interface_ui.cpp

src/interfaces/handler.h

src/node/mining_args.h

src/util/hasher.cpp

src/common/init.h

src/kernel/mempool_limits.h

src/common/system.h

src/crypto/sha3.h

src/util/threadinterrupt.cpp

src/node/protocol_version.h

src/util/exception.cpp

src/common/messages.h

src/node/connection_types.cpp

src/util/bip32.h

src/common/license_info.cpp

src/util/stdmutex.h

src/common/run_command.cpp

src/util/check.cpp

src/util/golombrice.h

src/node/types.h

src/node/timeoffsets.h

src/util/readwritefile.cpp

src/util/fastrange.h

src/util/signalinterrupt.h

src/util/task_runner.h

src/util/syserror.cpp

src/common/interfaces.cpp

src/common/types.h

src/util/threadinterrupt.h

src/kernel/chainstatemanager_opts.h

src/node/psbt.h

src/policy/ephemeral_policy.h

src/util/trace.h

src/common/url.cpp

src/kernel/mempool_options.h

src/util/serfloat.cpp

src/kernel/notifications_interface.h

src/node/timeoffsets.cpp

src/node/warnings.cpp

src/util/hash_type.h

src/crypto/hex_base.cpp

src/node/eviction.h

src/util/tokenbucket.h

src/crypto/aes.h

src/common/pcp.h

src/util/feefrac.cpp

src/node/transaction.h

src/util/threadnames.cpp

src/common/signmessage.h

src/util/exec.cpp

src/util/signalinterrupt.cpp

src/clientversion.cpp

src/common/signmessage.cpp

src/compat/assumptions.h

src/compat/byteswap.h

src/deploymentinfo.cpp

src/deploymentinfo.h

src/deploymentstatus.cpp

src/deploymentstatus.h

src/dummywallet.cpp

src/external_signer.h

src/init/bitcoin-gui.cpp

src/init/bitcoin-node.cpp

src/init/bitcoin-qt.cpp

src/init/bitcoin-wallet.cpp

src/init/bitcoind.cpp

src/init/common.h

src/interfaces/init.h

src/interfaces/ipc.h

src/key_io.h

src/logging/categories.h

src/logging/timer.h

src/mapport.h

src/musig.h

src/net_permissions.h

src/netgroup.h

src/netmessagemaker.h

src/node/chainstatemanager_args.cpp

src/node/connection_types.h

src/node/context.h

src/node/interface_ui.h

src/node/mempool_args.cpp

src/node/mining_args.cpp

src/node/minisketchwrapper.cpp

src/node/txreconciliation.h

src/policy/fees/estimator_args.cpp

src/policy/fees/estimator_args.h

src/policy/fees/estimator_man.cpp

src/policy/fees/estimator_man.h

src/policy/packages.h

src/policy/rbf.h

src/policy/truc_policy.h

src/pow.h

src/primitives/block.cpp

src/randomenv.h

src/rest.h

src/script/keyorigin.h

src/script/parsing.cpp

src/script/parsing.h

src/script/script_error.h

src/script/sigcache.cpp

src/script/sigcache.h

src/script/solver.h

src/script/verify_flags.h

src/semaphore_grant.h

src/signet.h

src/span.h

src/support/allocators/secure.h

src/support/allocators/zeroafterfree.h

src/util/tokenpipe.cpp

src/util/translation.h

src/util/vector.h

src/versionbits.h

src/versionbits_impl.h

src/wallet/external_signer_scriptpubkeyman.h

src/wallet/fees.h

src/wallet/load.h

src/wallet/receive.h

src/wallet/rpc/wallet.h

src/wallet/types.h

src/walletinitinterface.h

src/zmq/zmqabstractnotifier.cpp

Independent explanations by MyBitcoinExplorer. Not affiliated with or endorsed by Bitcoin Core. Guides are educational and do not replace the source or its tests.

Bitcoin Core source © its contributors, distributed under the MIT license. Original notices and bundled third-party licenses are retained in the source tree.