Cryptography in Faraday: specifications, code and checks

Every cryptographic action in Faraday, 110 in all. The index, the actions and the list of libraries below are generated from Faraday's manifest, docs/crypto/actions.toml, at release 0.2.0 (SHA-256 e175b3ab42660df464731639eb087edbc5a6c0fe9d5103890dd3fffe0ae5254c), and none of them is written by hand. Faraday's own checks hold the manifest to the code: a cryptographic function the manifest does not cover, a change to one since its entry was last reviewed, or a change to the cryptographic code since the last passing cross-check fails Faraday's checks. The page is generated again each time the website is published for a new release.

Faraday's approach

Faraday follows published specifications: BIPs, SLIPs, RFCs and conventions other wallets already use. Where a specification has an established implementation, Faraday uses it as a library instead of writing its own. A library is code others wrote, published as a Rust crate and pinned to one version; Faraday's own code calls it, checks what goes in and comes out, refuses what it cannot verify, and does every step the library does not. Faraday writes code of its own only where no established implementation exists or none fits its rules for keys, and says why. Where no specification exists, Faraday writes its own, labelled "Own specification, not yet reviewed outside Faraday" until someone outside reviews it. Each action is checked against its specification's published test vectors where there are any, and its results are compared with a second implementation: code others wrote where it exists, otherwise a second version Faraday's authors wrote, which is not an outside check. Actions with no second implementation are marked not cross-checked.

Each row below is one action. Specification is what it follows. Code is the libraries it uses and the crate of Faraday's code that calls them. Cross-checked with is what its results are compared with. The full rule is on the Standards page.

Key to the terms

Specification

  • Published94A specification others published.
  • Own specification22A specification Faraday's authors wrote.

Code

  • Faraday's own code35Code Faraday's authors wrote rather than took from a library; the action says why.

Cross-checked with

  • Others' code76Compared with code others wrote.
  • Faraday's second version44Compared with a second implementation Faraday's authors wrote, in Python; not checked against an outside source.
  • Not cross-checked26Compared with no second implementation.

Index Filters Standards page The vault's page Keys Wallets Randomness Backups Derived keys and tools Signing Transfer Vaults GPG and Secure Boot The device and the Starter Not in the app Libraries What Faraday writes itself Not established

Index

Each specification with its status, and the actions that follow it.

The vault's specification

Specifications

SpecificationNameStatusActions
BIP 32Hierarchical Deterministic WalletsDeployedMake the master key, Derive a child key, Show an extended private key, Show an address's private key, Convert a key's master seed, Write an xpub spelling, Recognise a secret in a file, Derive a Lightning key, Load a key from a vault, Run the start-up self-test
BIP 39Mnemonic code for generating deterministic keysDeployedRead the words, Make the words, Make the seed, Convert a key's master seed, Compare two keys' words, Make a SeedQR, Check a SeedQR, Split with Seed XOR, Write a backup stick file, Make a key's secret files, Recognise a secret in a file, Read a Core Lightning hsm_secret, Derive a Lightning key, Load a key from a vault, Run the start-up self-test
BIP 44Multi-Account Hierarchy for Deterministic WalletsDeployedDerive a child key, Derive an address
BIP 45Structure for Deterministic P2SH Multisignature WalletsCompleteNo action names it
BIP 48Multi-Script Hierarchy for Multi-Sig WalletsDeployedDerive a cosigner account
BIP 49Derivation scheme for P2WPKH-nested-in-P2SH based accountsDeployedDerive a child key, Derive an address
BIP 67Deterministic Pay-to-script-hash multi-signature addresses through public key sortingCompleteDerive a cosigner account
BIP 84Derivation scheme for P2WPKH based accountsDeployedDerive a child key, Derive an address, Run the start-up self-test
BIP 85Deterministic Entropy From BIP32 KeychainsDeployedDerive a child seed
BIP 86Key Derivation for Single Key P2TR OutputsDeployedDerive a child key, Derive an address
BIP 87Hierarchy for Deterministic Multisig WalletsCompleteNo action names it
BIP 93codex32: Checksummed SSS-able BIP32 SeedsDraftShow the master seed, Convert a key's master seed, Work with codex32 strings, Make codex32 shares, Correct a codex32 string, Make a Codex32QR, Write a backup stick file, Recognise a secret in a file
BIP 125Opt-in Full Replace-by-Fee SignalingDeployedCompare PSBTs and the fee bump
BIP 129Bitcoin Secure Multisig Setup (BSMS)CompleteRead BSMS records
BIP 137Signatures of Messages using Private KeysDeployedRead BSMS records, Sign a message, Check a signed message
BIP 141Segregated Witness (Consensus layer)DeployedRead a transaction
BIP 143Transaction Signature Verification for Version 0 Witness ProgramDeployedReview the sighash types, Sign with ECDSA, Sign a WIF key's sweep, Check a PSBT's signatures
BIP 144Segregated Witness (Peer Services)DeployedRead a transaction
BIP 173Base32 address format for native v0-16 witness outputsDeployedDerive an address, Read an address, Hash and encode text, Review what a PSBT pays
BIP 174Partially Signed Bitcoin Transaction FormatDeployedRead a PSBT, Review what a PSBT pays, Sign with ECDSA, Sign a WIF key's sweep, Check a PSBT's signatures, Compare PSBTs and the fee bump, Finalize a transaction
BIP 321URI Scheme for Bitcoin PaymentsCompleteReceive silent payments
BIP 322Generic Signed Message FormatCompleteSign a message, Check a signed message
BIP 327MuSig2 for BIP340-compatible Multi-SignaturesDeployedAggregate MuSig2 keys, Sign with MuSig2
BIP 328Derivation Scheme for MuSig2 Aggregate KeysCompleteAggregate MuSig2 keys
BIP 340Schnorr Signatures for secp256k1DeployedSign with Schnorr, Sign a message, Run the start-up self-test
BIP 341Taproot: SegWit version 1 spending rulesDeployedDerive an address, Read taproot multisig, Aggregate MuSig2 keys, Review the sighash types, Sign with Schnorr, Sign with MuSig2, Check a PSBT's signatures
BIP 342Validation of Taproot ScriptsDeployedRead taproot multisig, Review the sighash types, Sign with Schnorr
BIP 350Bech32m Format for v1+ Witness AddressesDeployedDerive an address, Read an address, Hash and encode text, Review what a PSBT pays
BIP 352Silent PaymentsCompleteReceive silent payments, Add silent payment shares
BIP 353DNS Payment InstructionsCompleteReceive silent payments
BIP 370PSBT Version 2DeployedRead a version 2 PSBT
BIP 373MuSig2 PSBT FieldsCompleteSign with MuSig2, Check a PSBT's signatures
BIP 374Discrete Log Equality ProofsDraftAdd silent payment shares
BIP 375Sending Silent Payments with PSBTsDraftAdd silent payment shares
BIP 379MiniscriptDraftRead and write a descriptor, Build a recovery wallet, Compile a spending policy
BIP 380Output Script Descriptors General OperationDeployedRead and write a descriptor, Hash and encode text
BIP 381Non-Segwit Output Script DescriptorsDeployedRead and write a descriptor
BIP 382Output Script Descriptors: wshDeployedRead and write a descriptor, Build a recovery wallet
BIP 383Output Script Descriptors: multiDeployedRead and write a descriptor
BIP 386Output Script Descriptors: trDeployedRead and write a descriptor, Build a recovery wallet, Read taproot multisig
BIP 387Tapscript Multisig Output Script DescriptorsDeployedRead taproot multisig
BIP 388Wallet Policies for Descriptor WalletsCompleteRead and write a descriptor, Read a wallet export
BIP 389Multipath Descriptor Key ExpressionsDraftRead and write a descriptor
BIP 390musig() Descriptor Key ExpressionDraftAggregate MuSig2 keys
BIP 392Silent Payment Scanning DescriptorsDraftReceive silent payments
RFC 1924A Compact Representation of IPv6 Addresses (base 85 alphabet)Status not checkedDerive a child seed
RFC 1952GZIP file format specification version 4.3Status not checkedSeal and open KDBX
RFC 2104HMAC: Keyed-Hashing for Message AuthenticationStatus not checkedHash and authenticate bytes, Derive keys with HKDF, Make a vault, Open a vault, Seal and open KDBX, Write a vault back
RFC 4226HOTP: An HMAC-Based One-Time Password AlgorithmInformationalCompute a TOTP code
RFC 4231Identifiers and Test Vectors for HMAC-SHA-224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512Status not checkedHash and authenticate bytes
RFC 4648The Base16, Base32, and Base64 Data EncodingsStatus not checkedDerive a child seed
RFC 4880OpenPGP Message Format, obsoleted by RFC 9580Proposed StandardMake a GPG key, Sign with the GPG key, Make a revocation certificate, Restore a GPG key, Check a GPG signature
RFC 5280Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) ProfileProposed StandardMake Secure Boot keys
RFC 5652Cryptographic Message Syntax (CMS)Internet StandardMake Secure Boot keys, Sign a boot program, Check a boot signature
RFC 5869HMAC-based Extract-and-Expand Key Derivation Function (HKDF)InformationalDerive keys with HKDF, Seal a QR vault's OpenPGP message, Seal a QR vault, Open a QR vault
RFC 6238TOTP: Time-Based One-Time Password AlgorithmInformationalCompute a TOTP code
RFC 6979Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA)InformationalSign with ECDSA, Sign a WIF key's sweep, Check a PSBT's signatures, Sign a message, Run the start-up self-test
RFC 7253The OCB Authenticated-Encryption AlgorithmInformationalSeal a QR vault's OpenPGP message, Seal a QR vault, Open a QR vault
RFC 7914The scrypt Password-Based Key Derivation FunctionStatus not checkedHash and authenticate bytes, Stretch a password with scrypt, Read an aezeed, Run the start-up self-test
RFC 8017PKCS #1: RSA Cryptography Specifications Version 2.2InformationalMake Secure Boot keys, Sign a boot program, Check a boot signature, Check a signed boot file
RFC 8018PKCS #5: Password-Based Cryptography Specification Version 2.1Status not checkedHash and authenticate bytes
RFC 8032Edwards-Curve Digital Signature Algorithm (EdDSA)InformationalMake a GPG key, Sign with the GPG key, Restore a GPG key, Check a GPG signature
RFC 8259The JavaScript Object Notation (JSON) Data Interchange FormatStatus not checkedRead a wallet export
RFC 8439ChaCha20 and Poly1305 for IETF ProtocolsStatus not checkedMake a vault, Open a vault, Seal and open KDBX, Write a vault back, Write a KeePass database
RFC 9106Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work ApplicationsInformationalMake a vault, Open a vault, Seal a QR vault's OpenPGP message, Seal a QR vault, Open a QR vault, Seal and open KDBX, Write a KeePass database, Run the start-up self-test
RFC 9580OpenPGPProposed StandardSeal a QR vault's OpenPGP message, Seal a QR vault, Open a QR vault, Make a GPG key, Sign with the GPG key, Make a revocation certificate, Restore a GPG key, Check a GPG signature
AuthenticodeWindows Authenticode Portable Executable Signature FormatStatus not checkedSign a boot program, Check a boot signature, Check a signed boot file
Base58CheckBase58Check encoding, as Bitcoin Core writes itConventionRead an address, Hash and encode text
BBQrBBQr, a file split across QR codesConventionSplit and join BBQr parts
BCR-2020-005Uniform Resources (UR), the animated-QR transportConventionWrite and read UR codes
BCR-2020-006The crypto-psbt UR typeConventionWrite and read UR codes
BCR-2020-007UR Type Definition for Hierarchical Deterministic (HD) KeysConventionWrite and read UR codes
BCR-2020-010UR Type Definition for Bitcoin Output DescriptorsConventionWrite and read UR codes
BCR-2020-012BytewordsConventionWrite and read UR codes
BCR-2020-015UR Type Definition for BIP44 AccountsConventionWrite and read UR codes
Bitcoin Core wallet.datBitcoin Core's descriptor wallet records and their encrypted keysConventionCheck Core wallet keys
BOLT 11BOLT #11: Invoice Protocol for Lightning PaymentsDeployedRead a Lightning invoice
BOLT 12BOLT #12: Negotiation Protocol for Lightning PaymentsDeployedRead a Lightning offer
Booklet dice de-biasingcodex32 booklet SSS32.ps of 2023-03-07, Dice De-biasing WorksheetConventionRead the booklet's dice
Codex32QR/v1-48Codex32QR/v1-48, one 48-character codex32 string in a QR codeConventionMake a Codex32QR
Core Lightning hsm_secretCore Lightning's hsm_secret, plain or encrypted, and its node keyConventionRead a Core Lightning hsm_secret
Dice hashing of Coldcard and SeedSignerColdcard rolls.py, SeedSigner, EntropyLab, Keystone and BitBox dice proceduresConventionTurn dice into entropy
EFF word listsEFF long and short Diceware word listsConventionChoose Diceware words
EntropyLab vanity counterEntropyLab vanity-wasm counterConventionGrind a vanity address
FIPS 180-4Secure Hash StandardStatus not checkedHash and authenticate bytes, Derive keys with HKDF, Hash and encode text, Hash a file, Write an image to a stick
FIPS 197Advanced Encryption Standard (AES)Status not checkedSeal and open KDBX
ISO/IEC 18004QR Code bar code symbology specificationStatus not checkedMake and read QR codes
KeePass KDBX 4The KeePass database format, version 4ConventionMake a vault, Open a vault, Seal and open KDBX, Write a vault back, Write a KeePass database
KEFKEF, Krux's encrypted codeConventionSeal and open Krux codes
ldk-node node keyldk-node and rust-lightning node key from a BIP-39 seedConventionDerive a Lightning key
LND aezeedLND cipher seed (aezeed) with AEZ v5ConventionRead an aezeed, Derive a Lightning key
OpenTimestampsOpenTimestamps proof files (.ots), as python-opentimestamps reads themConventionCheck a timestamp
otpauth Key URI FormatKey URI Format of Google AuthenticatorConventionCompute a TOTP code
paperkeypaperkey's text and raw forms of an OpenPGP secret keyConventionWrite the GPG key as paperkey, Restore a GPG key
Seed XORSeed XOR, Coldcard's split of a seed into partsConventionConvert a key's master seed, Split with Seed XOR
SeedQRSeedQR and CompactSeedQRConventionConvert a key's master seed, Make a SeedQR, Check a SeedQR, Write a backup stick file, Make a key's secret files
SLIP-0039Shamir's Secret-Sharing for Mnemonic CodesStatus not checkedConvert a key's master seed, Convert a typed SLIP-39 set, Split with SLIP-39, Recognise a secret in a file
SLIP-0132Registered HD version bytes for BIP-0032Status not checkedWrite an xpub spelling
Specter pNofMNumbered text parts, pNofMConventionSplit and join BBQr parts
SQLite file formatThe SQLite database file formatConventionRead a SQLite database
TOML v1.0.0TOML, Tom's Obvious Minimal Language, version 1.0.0Status not checkedRead the items inside a vault
UAX #15Unicode Standard Annex #15: Unicode Normalization FormsCompleteMake a vault, Open a vault
UEFI SpecificationUnified Extensible Firmware Interface Specification: Secure Boot, signature lists and authenticated variablesStatus not checkedMake Secure Boot keys, Sign a boot program

The actions

Grouped as in the app. A filter hides the actions that do not match it; with no filter, every action shows.

Keys

14 actions · 3 own specification · 3 with Faraday's own code · 10 cross-checked with others' code · 3 with Faraday's second version · 4 not cross-checked

Read the words

SpecificationBIP 39PublishedCodeLibrary: unicode-normalization 0.1Library: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-bipFaraday's own codeCross-checked withpython-mnemonicOthers' code
Action

Reads seed words typed, pasted or scanned, and checks their count and checksum.

Specification

BIP 39, Mnemonic code for generating deterministic keys, Deployed

Code

Library: unicode-normalization 0.1.25, by the unicode-rs developers.

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-bip: The sentence is read in NFKD and split on Unicode whitespace; the first word not in the list is reported by position; a word typed by pinyin, zhuyin, kana or hangul is composed to the listed word.

Written by Faraday

BIP-39 entry and display: words typed by pinyin, zhuyin, kana or hangul, the last word's candidates, the explorer's view of the checksum (faraday-bip::bip39) · Faraday's own specification

How a person types and sees the words is Faraday's own.

Decision F178

BIP-39 mnemonics: entropy to words and back, the checksum, a word's place in its list (faraday-bip::bip39) · One exists but does not fit Faraday's rules for keys

The Rust BIP-39 library's word lookup takes a time that follows the secret words; Faraday's looks each word up in constant time and is tested against that library and the reference.

Does not fit: bip39 2.2.2 finds a word by a binary search or a scan that stops at it (find_word) and packs entropy with a branch on each bit (from_entropy_in), so the time it takes follows the secret words

Decision F180

Checked against

tools/vectors/bip39

Published, by Trezor (SatoshiLabs), python-mnemonic's vectors; bip32JP's Japanese vectors.

core/faraday-bip/tests/all/vectors.rs::trezor_vectors_all_languages

core/faraday-bip/tests/all/vectors.rs::japanese_vectors

core/faraday-bip/tests/all/vectors.rs::a_sentence_is_read_in_nfkd_whatever_form_it_is_typed_in

core/faraday-bip/tests/all/api.rs::bad_checksum_is_detected

core/faraday-bip/tests/all/api.rs::parse_locates_unknown_words

core/faraday-bip/tests/all/readings.rs::typing_a_reading_finds_the_character_it_names

self-test bip39_vector

self-test bip39_japanese_vector

fuzz bip39_words

Cross-check

Compared with others' code: python-mnemonic, by Trezor (SatoshiLabs), and bip39_slip39, by the btclib developers (a second reader: wordlists, entropy, indices, checksums and the seed in the ten languages).

Area bip39

Faraday's code faraday_bip::bip39

Compared with python-mnemonic (bip39/); bip39_slip39 (bip39-slip39/) answering every operation beside it.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; python-mnemonic's own to_hd_master_key is checked against the seed's master key, as a second BIP-32 master; its wheel is hashed too, and a published vector's answer is required of bip39_slip39 as well.

Vectors The ten wordlists; every vector of tools/vectors/bip39/vectors.json in Faraday's languages; the Japanese vectors with non-ASCII passphrases.

Random cases Entropy to words and back in every language and length; seeds under random ASCII passphrases; a changed word, an unknown word, a word too many or too few; every valid last word.

Differences Both read a BIP-39 sentence in NFKD, so composed words and the Japanese vectors as published parse on both sides (owner, 2026-10-23).

A passphrase typed in Faraday is printable ASCII, at most 256 bytes; python-mnemonic takes any text. Faraday's vector tests and start-up self-test give a non-ASCII passphrase as its NFKD bytes, and the area checks that a typed one, or one past 256 bytes, is still refused.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Secret handling

none: no secret leaves faraday-keys

A word is found by comparing it with every entry of its list in constant time (subtle), and the entropy's bits are written without a branch; the sentence is gathered by a masked scan, and its length follows the words, as BIP-39 requires; the code states no other timing.

The word buffer and the indices are Secret values, zeroized when dropped; the Mnemonic wipes its indices when dropped.

Limits

Word counts of 12, 15, 18, 21 and 24 only.

A word not in the chosen list is refused and its position reported.

A checksum that fails is refused.

Faraday's own calls

Word entry by readings and kana: typed readings find the listed words. Neutral.

no decision

Make the words

SpecificationBIP 39PublishedCodeLibrary: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-bipCross-checked withpython-mnemonicOthers' code
Action

Turns 16 to 32 bytes of entropy into seed words, with the checksum bits BIP 39 adds.

Specification

BIP 39, Mnemonic code for generating deterministic keys, Deployed

Code

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-bip: Entropy of 16, 20, 24, 28 or 32 bytes only; the buffer holding it is a Secret.

Checked against

tools/vectors/bip39

Published, by Trezor (SatoshiLabs), python-mnemonic's vectors; bip32JP's Japanese vectors.

core/faraday-bip/tests/all/api.rs::entropy_round_trip_all_lengths

core/faraday-bip/tests/all/api.rs::from_entropy_rejects_bad_lengths

core/faraday-bip/tests/all/vectors.rs::trezor_vectors_all_languages

no fuzz target: Takes entropy of a fixed length from the person's own source; no outside text is parsed

Cross-check

Compared with others' code: python-mnemonic, by Trezor (SatoshiLabs), and bip39_slip39, by the btclib developers (a second reader: wordlists, entropy, indices, checksums and the seed in the ten languages).

Area bip39

Faraday's code faraday_bip::bip39

Compared with python-mnemonic (bip39/); bip39_slip39 (bip39-slip39/) answering every operation beside it.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; python-mnemonic's own to_hd_master_key is checked against the seed's master key, as a second BIP-32 master; its wheel is hashed too, and a published vector's answer is required of bip39_slip39 as well.

Vectors The ten wordlists; every vector of tools/vectors/bip39/vectors.json in Faraday's languages; the Japanese vectors with non-ASCII passphrases.

Random cases Entropy to words and back in every language and length; seeds under random ASCII passphrases; a changed word, an unknown word, a word too many or too few; every valid last word.

Differences Both read a BIP-39 sentence in NFKD, so composed words and the Japanese vectors as published parse on both sides (owner, 2026-10-23).

A passphrase typed in Faraday is printable ASCII, at most 256 bytes; python-mnemonic takes any text. Faraday's vector tests and start-up self-test give a non-ASCII passphrase as its NFKD bytes, and the area checks that a typed one, or one past 256 bytes, is still refused.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Source

0.2.0 · core/faraday-bip/src/bip39.rs · Mnemonic::from_entropy

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The bit buffer is a Secret, zeroized when dropped; the Mnemonic wipes its indices when dropped.

Limits

Entropy lengths other than 16, 20, 24, 28 and 32 bytes are refused.

Faraday's own calls

none

Make the seed

SpecificationBIP 39PublishedCodeLibrary: pbkdf2 0.13 (through core/faraday-crypto)Library: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-bipFaraday's own codeCross-checked withpython-mnemonicOthers' code
Action

Makes the 64-byte seed from words and a passphrase by PBKDF2-HMAC-SHA512, 2048 rounds, and adds the key it gives to the session.

Specification

BIP 39, Mnemonic code for generating deterministic keys, Deployed

Code

Library: pbkdf2 0.13.0, by the RustCrypto developers, through core/faraday-crypto.

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-bip: The passphrase is checked to printable ASCII before the derivation; the sentence and salt are built in Secret buffers; a key already held is refused as a duplicate.

Written by Faraday

The BIP-39 seed, PBKDF2-HMAC-SHA512 over the sentence through faraday-crypto (faraday-bip::bip39) · One exists but does not fit Faraday's rules for keys

The seed is derived with the RustCrypto PBKDF2 Faraday uses everywhere, into a buffer that is wiped.

Does not fit: bip39's to_seed returns the seed as a plain [u8; 64], and its own PBKDF2 leaves its HMAC state unwiped (bip39 2.2.2's src/pbkdf2.rs)

Decision F178

Checked against

tools/vectors/bip39

Published, by Trezor (SatoshiLabs), python-mnemonic's vectors; bip32JP's Japanese vectors.

core/faraday-bip/tests/all/vectors.rs::trezor_english_seed_through_public_api

core/faraday-bip/tests/all/vectors.rs::japanese_passphrase_is_rejected_by_public_api

core/faraday-bip/tests/all/api.rs::passphrase_rules

core/faraday-bip/tests/all/accounts.rs::passphrase_changes_everything

faraday/faraday-keys/tests/operations.rs::keys_added_from_words_come_back_with_their_fingerprint_and_word_count

self-test bip39_vector

self-test bip39_japanese_vector

no fuzz target: Takes parsed words and a passphrase typed in a field; words-read fuzzes the text

Cross-check

Compared with others' code: python-mnemonic, by Trezor (SatoshiLabs), and bip39_slip39, by the btclib developers (a second reader: wordlists, entropy, indices, checksums and the seed in the ten languages).

Area bip39

Faraday's code faraday_bip::bip39

Compared with python-mnemonic (bip39/); bip39_slip39 (bip39-slip39/) answering every operation beside it.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; python-mnemonic's own to_hd_master_key is checked against the seed's master key, as a second BIP-32 master; its wheel is hashed too, and a published vector's answer is required of bip39_slip39 as well.

Vectors The ten wordlists; every vector of tools/vectors/bip39/vectors.json in Faraday's languages; the Japanese vectors with non-ASCII passphrases.

Random cases Entropy to words and back in every language and length; seeds under random ASCII passphrases; a changed word, an unknown word, a word too many or too few; every valid last word.

Differences Both read a BIP-39 sentence in NFKD, so composed words and the Japanese vectors as published parse on both sides (owner, 2026-10-23).

A passphrase typed in Faraday is printable ASCII, at most 256 bytes; python-mnemonic takes any text. Faraday's vector tests and start-up self-test give a non-ASCII passphrase as its NFKD bytes, and the area checks that a typed one, or one past 256 bytes, is still refused.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Source

0.2.0 · core/faraday-bip/src/bip39.rs · Mnemonic::to_seed

0.2.0 · faraday/faraday-keys/src/session.rs · Keys::add_words_with

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

A word is found by comparing it with every entry of its list in constant time (subtle), and the entropy's bits are written without a branch; the sentence is gathered by a masked scan, and its length follows the words, as BIP-39 requires; the code states no other timing.

The sentence, the salt and the seed are Secret values, zeroized when dropped; the key holds its words and passphrase in zeroizing buffers until it is removed.

Limits

A passphrase longer than 256 bytes, or with a byte outside 0x20 to 0x7E, is refused.

Nothing is added while a stick is attached.

Faraday's own calls

A passphrase is printable ASCII, at most 256 bytes. BIP 39 allows any NFKD text, so a wallet made elsewhere with another passphrase cannot be restored here; a letter outside the range typed into a passphrase field is refused. Conservative, F155.

Make the master key

SpecificationBIP 32PublishedCodeLibrary: bitcoin 0.32Library: secp256k1 0.29Library: hmac 0.13 (through core/faraday-crypto)2 moreFaraday's code: core/faraday-bipCross-checked withbtclib-wallet's bip32Others' codeFaraday's second version
Action

Makes a master key and its fingerprint from a seed or an extended private key, by BIP 32.

Specification

BIP 32, Hierarchical Deterministic Wallets, Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).

Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-bip: An extended private key typed or scanned is decoded by Faraday's own strict rules (78 bytes, version, zero parent and child number at depth 0, zero pad byte, scalar in 1..n) before bitcoin sees it; the key is kept on a pinned page; the fingerprint and a 32-byte identity (SHA-256 of the public key and chain code) are worked out once.

Checked against

tools/vectors/bip32

Published, by BIP 32's authors (bitcoin/bips).

core/faraday-bip/tests/all/bip32.rs::vectors_1_to_4_through_master_key

core/faraday-bip/tests/all/bip32.rs::vector_5_invalid_keys_are_rejected

core/faraday-bip/tests/all/bip32.rs::vector_master_keys_import_and_derive

core/faraday-bip/tests/all/bip32.rs::a_child_key_is_not_a_master_key

core/faraday-bip/tests/all/accounts.rs::master_fingerprint

faraday/faraday-keys/tests/operations.rs::the_abandon_words_have_the_fingerprint_the_bips_publish

faraday/faraday-keys/tests/operations.rs::a_master_key_is_told_from_another_by_all_of_its_identity

self-test bip32_vector

fuzz xkey

Cross-check

Compared with others' code: btclib-wallet's bip32, by the btclib developers, on btclib's own curve; and hdkeychain from btcd v0.27.0, by the btcd developers, on decred's secp256k1.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the three rules of a strict reader that hdkeychain does not make: which versions it takes (BIP-32's xprv and tprv, xpub and tpub, from btclib's network table; btclib reads SLIP-132's too and hdkeychain any version), a version of the other kind than the key's data, and a depth-0 key with a parent fingerprint or an index, in area_bip32.py and bip32_ref.py.

Area bip32

Faraday's code faraday_bip::keys (master, private derivation), faraday_bip::xkey (strict decoding), bitcoin's Xpub::derive_pub

Compared with btclib-wallet's bip32 over btclib and ecc (btclib/), on btclib's own curve with libsecp256k1 turned off, through bip32_ref.py, and hdkeychain from btcd v0.27.0 (btcd/, Go, decred's secp256k1); the versions a strict reader takes (BIP-32's four, from btclib's network table), a version whose kind differs from the key's data, and a depth-0 key with a parent or an index are ours.

Checked first: The wheels and the vendored Go tree are hashed against references.sha256 before any run; check_driver runs btclib against BIP-32's vectors 1 to 5 and the invalid keys of vector 5 before anything else, and every vector is asked of hdkeychain too.

Vectors BIP-32's vectors 1 to 5 (tools/vectors/bip32/), python-mnemonic's master keys.

Random cases Seeds of 16 to 64 bytes on every network, random paths with every index, public derivation against private, keys broken one rule at a time and the master-key import, each judged by btclib and by hdkeychain.

Differences Hdkeychain reads a key of any version, a key whose version is a private one over a public key's data (or the reverse), and a depth-0 key with a parent fingerprint or an index. Faraday refuses all three, as btclib refuses the last; where one applies and btclib refuses, hdkeychain is not asked (uncovered in area_bip32.py), so Faraday's strict reader is not retired.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 4000 cases

Source

0.2.0 · core/faraday-bip/src/keys.rs · MasterKey::from_seed

0.2.0 · core/faraday-bip/src/keys.rs · MasterKey::decode

0.2.0 · faraday/faraday-keys/src/identity.rs · master_id

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The private key and chain code are overwritten when the key is dropped and where the decoded copy stood; the key lives on a pinned page; copies bitcoin makes inside derivation are outside Faraday's reach (stated in the module).

Limits

Only a depth-0 key is a master key; a key at another depth is refused.

An extended key text that breaks any of BIP 32 test vector 5's rules is refused.

Faraday's own calls

An extended private key is decoded by Faraday's own strict reader because bitcoin accepts seven of the sixteen serialisations vector 5 rejects. Conservative.

no decision

Derive a child key

SpecificationBIP 32 · BIP 44 · BIP 49 · 2 morePublishedCodeLibrary: bitcoin 0.32Library: secp256k1 0.29Faraday's code: core/faraday-bipCross-checked withbtclib-wallet's bip32Others' code
Action

Derives a child key and the extended public key of an account, by BIP 32 and the purposes of BIP 44, 49, 84 and 86.

Specification

BIP 32, Hierarchical Deterministic Wallets, Deployed

BIP 44, Multi-Account Hierarchy for Deterministic Wallets, Deployed

BIP 49, Derivation scheme for P2WPKH-nested-in-P2SH based accounts, Deployed

BIP 84, Derivation scheme for P2WPKH based accounts, Deployed

BIP 86, Key Derivation for Single Key P2TR Outputs, Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).

Faraday's code: core/faraday-bip: The account path is purpose'/coin'/account' with the purpose of the script type; an account or index of 2^31 or more is refused; the key text is [fingerprint/path]xpub with h for hardened. Explore reads a path typed with h or ' for hardened, of at most 10 levels, each index under 2^31, and takes the script type from a hardened purpose of 44, 49, 84 or 86; the account of an address path is the path without its chain and index, and none for the multisig purposes 45 and 48.

Checked against

tools/vectors/bip32

Published, by BIP 32's authors (bitcoin/bips).

core/faraday-bip/tests/all/bip32.rs::vectors_1_to_4_through_master_key

core/faraday-bip/tests/all/bip32.rs::hardened_marker_spellings_are_equivalent

core/faraday-bip/tests/all/accounts.rs::bip44_legacy_mainnet

core/faraday-bip/tests/all/accounts.rs::bip49_nested_segwit_testnet

core/faraday-bip/tests/all/accounts.rs::bip84_native_segwit_mainnet

core/faraday-bip/tests/all/accounts.rs::bip86_taproot_mainnet

core/faraday-bip/tests/all/accounts.rs::other_accounts_and_index_limits

core/faraday-bip/tests/all/accounts.rs::coin_types_and_purposes_decide_the_path

faraday/faraday-core/tests/all/explore.rs::bip84_and_bip86s_first_addresses

faraday/faraday-core/tests/all/explore.rs::a_path_typed_wrongly_is_named

self-test bip32_vector

no fuzz target: Takes a parsed path and a held key; the extended key texts are fuzzed by master's xkey target

Cross-check

Compared with others' code: btclib-wallet's bip32, by the btclib developers, on btclib's own curve; and hdkeychain from btcd v0.27.0, by the btcd developers, on decred's secp256k1.

Area bip32

Faraday's code faraday_bip::keys (master, private derivation), faraday_bip::xkey (strict decoding), bitcoin's Xpub::derive_pub

Compared with btclib-wallet's bip32 over btclib and ecc (btclib/), on btclib's own curve with libsecp256k1 turned off, through bip32_ref.py, and hdkeychain from btcd v0.27.0 (btcd/, Go, decred's secp256k1); the versions a strict reader takes (BIP-32's four, from btclib's network table), a version whose kind differs from the key's data, and a depth-0 key with a parent or an index are ours.

Checked first: The wheels and the vendored Go tree are hashed against references.sha256 before any run; check_driver runs btclib against BIP-32's vectors 1 to 5 and the invalid keys of vector 5 before anything else, and every vector is asked of hdkeychain too.

Vectors BIP-32's vectors 1 to 5 (tools/vectors/bip32/), python-mnemonic's master keys.

Random cases Seeds of 16 to 64 bytes on every network, random paths with every index, public derivation against private, keys broken one rule at a time and the master-key import, each judged by btclib and by hdkeychain.

Differences Hdkeychain reads a key of any version, a key whose version is a private one over a public key's data (or the reverse), and a depth-0 key with a parent fingerprint or an index. Faraday refuses all three, as btclib refuses the last; where one applies and btclib refuses, hdkeychain is not asked (uncovered in area_bip32.py), so Faraday's strict reader is not retired.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 4000 cases

Source

0.2.0 · core/faraday-bip/src/keys.rs · MasterKey::derive

0.2.0 · core/faraday-bip/src/keys.rs · MasterKey::account_xpub

0.2.0 · faraday/faraday-keys/src/texts.rs · key_text

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

A derived private key is overwritten when it is dropped and where its stack copy stood; only the extended public key leaves.

Limits

Account and address indexes of 2^31 or more are refused.

An Explore path of more than 10 levels, or with an empty level or an index of 2^31 or more, is refused.

Faraday's own calls

Hardened steps are written h. Neutral, F66.

The account is asked after the quorum, not on Kind. Neutral, F98.

Restore takes a seed for a wallet's key slot only when its whole extended public key at the slot's path matches the wallet's, not the four bytes of its fingerprint. Conservative, F155.

Hold a key in memory

SpecificationOwn specificationCodeLibrary: subtle 2.6Library: secp256k1 0.29Faraday's code: core/faraday-cryptoFaraday's own codeCross-checked withNot cross-checked
Action

Holds a key in memory blinded and on pinned pages.

Specification

Own specification (no decision)

Code

Library: subtle 2.6.1, by the dalek-cryptography developers.

Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).

Faraday's code: core/faraday-crypto: Each key's signing context is randomized from the session's randomness, again whenever it changes (a key a signing job holds is randomized as soon as the job's answer is applied or dropped), each key's blind drawn by HKDF-Expand under a count so no two are the same; pinned pages hold a long-lived secret apart from other data and are asked to stay out of swap; words, passphrases and seeds are values wiped on drop.

Written by Faraday

WipeOnFree, the allocator that wipes what it frees (faraday-crypto::wipe) · No established implementation exists

No wiping allocator comes from a publisher Faraday's dependency review trusts; this one is installed in no shipped program (F181).

Decision F180

Checked against

not checked against vectors

faraday/faraday-core/tests/all/blinding.rs::a_key_joining_the_session_is_blinded_from_the_sessions_seed

faraday/faraday-core/tests/all/blinding.rs::every_key_is_blinded_again_when_the_person_adds_randomness

core/faraday-crypto/tests/primitives.rs::pinning_a_value_wipes_where_it_came_from

core/faraday-crypto/tests/primitives.rs::secret_zeroizes_on_drop

no fuzz target: Takes values the program holds; no outside input is parsed

Cross-check

Own specification, not yet reviewed outside Faraday.

An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.

not cross-checked: Nothing outside the program reads these values

Secret handling

none: no secret leaves faraday-keys

Secret and Pinned comparison is constant time (subtle's ConstantTimeEq, documented in secret.rs and pinned.rs).

A Secret and a Pinned page are zeroized on drop. Not reached: a secret while it is live in a plain type, the stack and registers, memory other code allocates, a copy in freed heap until the process ends (the next lock on the device), and anything outside the process (none on the device; the computer's own on the desktop).

Limits

Pinning is a feature of the desktop app and of the stick and Pi images (faraday-crypto's pin-pages); a build without it holds the same value unpinned.

Faraday's own calls

A key's signing context is blinded from the session's randomness. Neutral.

no decision

Show the master seed

SpecificationBIP 93PublishedCodeLibrary: base16ct 1.0 (through core/faraday-crypto)Faraday's code: faraday/faraday-keysCross-checked withpython-codex32Others' codeFaraday's second version
Action

Shows the master seed of a key with no words in hex, and its codex32 secret and strings where the set is known.

Specification

BIP 93, codex32: Checksummed SSS-able BIP32 Seeds, Draft, vendored

Code

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: faraday/faraday-keys: Answers only its own reason, and only for a key with no words; the codex32 secret is recovered from the strings held once their count reaches the set's threshold.

Checked against

tools/vectors/bip93

Published, by BIP 93's authors (bitcoin/bips).

faraday/faraday-keys/tests/operations.rs::a_key_from_a_master_seed_has_no_words_to_show

faraday/faraday-keys/tests/operations.rs::explore::a_codex32_keys_seed_is_shown_as_bip93_writes_it

faraday/faraday-keys/tests/operations.rs::explore::each_reason_gives_only_its_own_secret

no fuzz target: Takes a held key and a reason; no outside input is parsed

Cross-check

Compared with others' code: python-codex32, by Ben Westgate, and rust-codex32, by Andrew Poelstra (which decides the threshold of 0 or 2 to 9 and a threshold of 0's share index).

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: two rules BIP 93 states that neither enforces (the seed's lengths, the order shares are handed out), written in area_codex32.py from the BIP's text.

Area codex32

Faraday's code faraday_bip::codex32

Compared with python-codex32 (codex32/); rust-codex32 at a pinned commit (rust-codex32/), a program outside the workspace: parsing, checksums, the threshold and a threshold of 0's share index, interpolate_at for a fresh set's shares; volvelle-website's checksum worksheet run as a program over every worksheet of 48 and 74 characters; the worksheet of 127 characters written in the area from python-codex32's polymod.

Checked first: Its vendored files are hashed against references.sha256 before any run (the Rust programs' sources included, built offline by run.sh with the toolchain on the PATH), and a published vector's answer is required of the reference as well as of Faraday; rust-codex32 and python-codex32 must give the same answer where both are asked; two rules BIP 93 states that neither enforces (the master seed's sizes, the order shares are handed out) are written in the area from the BIP's text, and the worksheet of 127 characters from BIP 93's polymod alone.

Vectors Every vector of tools/vectors/bip93/, the 55 invalid strings included; volvelle-website's worksheet cells (tools/vectors/codex32-volvelle/); the booklet's checksum, derivation, recovery, addition, translation and fusion tables (tools/vectors/codex32-booklet/); the Codex32QR profile's sets (tools/vectors/codex32qr/).

Random cases secrets, splits (the same randomness), recovery, derived shares, corrupted strings; fresh sets of every threshold up to 31 strings at 48, 74 and 127 characters, the checksum worksheets of their strings and of corrupted ones, checksums made on a sheet, translation and recovery symbols, translation worksheets.

Differences Codex32: Faraday recovers only from exactly k shares without the secret, and derives a share only from exactly k strings at an unused index; the reference also takes more strings or a used index.

The codex32 seed sizes, which the references leave to their caller, are written in the area from the BIP's own sentence. Volvelle's sheet works the checksum itself, so a string of 48 or 74 characters whose checksum is not the one the sheet works is judged by that alone (holds false), not by its rows.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 10000 cases

Secret handling

Reveal::SeedShown

not stated by the library.

The result is a Held value that wipes what it holds when dropped.

Limits

Another reason gets nothing.

A key with words gets nothing here; its words are lent by the words reveals.

Faraday's own calls

none

Show an extended private key

SpecificationBIP 32PublishedCodeFaraday's code: faraday/faraday-keysCross-checked withbtclib-wallet's bip32Others' code
Action

Shows an extended private key at a path below a held key.

Specification

BIP 32, Hierarchical Deterministic Wallets, Deployed

Code

Faraday's code: faraday/faraday-keys: Answers only its own reason; the key is derived at the path and written in a fixed buffer. On Explore each eye makes what it shows once, at the press that opens it: the seed's forms, the root's and the account's extended private keys together, or an address's private key. The account is the path's account, or the path itself where it is in none. What is not on screen is dropped after every press and key on Explore, and by closing an eye, leaving Explore, the idle warning and a lock.

Checked against

tools/vectors/bip32

Published, by BIP 32's authors (bitcoin/bips).

faraday/faraday-keys/tests/operations.rs::explore::the_root_extended_private_key_is_bip32s_vector_1

faraday/faraday-keys/tests/operations.rs::explore::the_account_extended_private_key_is_bip84s

faraday/faraday-keys/tests/operations.rs::explore::each_reason_gives_only_its_own_secret

faraday/faraday-core/tests/all/explore.rs::the_extended_private_keys_show_behind_their_eye

faraday/faraday-core/tests/all/explore.rs::everything_is_hidden_after_leaving_and_coming_back

no fuzz target: Takes a held key, a path and a reason; no outside input is parsed

Cross-check

Compared with others' code: btclib-wallet's bip32, by the btclib developers, on btclib's own curve; and hdkeychain from btcd v0.27.0, by the btcd developers, on decred's secp256k1.

Area bip32

Faraday's code faraday_bip::keys (master, private derivation), faraday_bip::xkey (strict decoding), bitcoin's Xpub::derive_pub

Compared with btclib-wallet's bip32 over btclib and ecc (btclib/), on btclib's own curve with libsecp256k1 turned off, through bip32_ref.py, and hdkeychain from btcd v0.27.0 (btcd/, Go, decred's secp256k1); the versions a strict reader takes (BIP-32's four, from btclib's network table), a version whose kind differs from the key's data, and a depth-0 key with a parent or an index are ours.

Checked first: The wheels and the vendored Go tree are hashed against references.sha256 before any run; check_driver runs btclib against BIP-32's vectors 1 to 5 and the invalid keys of vector 5 before anything else, and every vector is asked of hdkeychain too.

Vectors BIP-32's vectors 1 to 5 (tools/vectors/bip32/), python-mnemonic's master keys.

Random cases Seeds of 16 to 64 bytes on every network, random paths with every index, public derivation against private, keys broken one rule at a time and the master-key import, each judged by btclib and by hdkeychain.

Differences Hdkeychain reads a key of any version, a key whose version is a private one over a public key's data (or the reverse), and a depth-0 key with a parent fingerprint or an index. Faraday refuses all three, as btclib refuses the last; where one applies and btclib refuses, hdkeychain is not asked (uncovered in area_bip32.py), so Faraday's strict reader is not retired.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 4000 cases

Secret handling

Reveal::ExtendedPrivateKey

not stated by the library.

The text is a Held value in a buffer that zeroizes on drop; the derived key is erased when it is dropped.

Limits

Another reason gets nothing.

Faraday's own calls

none

Show an address's private key

SpecificationBIP 32PublishedCodeLibrary: bitcoin 0.32 (through core/faraday-bip)Faraday's code: faraday/faraday-keysCross-checked withbtclib-wallet's bip32Others' code
Action

Shows the private key of one address as a compressed WIF.

Specification

BIP 32, Hierarchical Deterministic Wallets, Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers, through core/faraday-bip.

Faraday's code: faraday/faraday-keys: Answers only its own reason; the WIF is compressed and carries the store's network. On Explore's address list an address's key is asked at the account's path, its chain and its index.

Checked against

tools/vectors/bip32

Published, by BIP 32's authors (bitcoin/bips).

faraday/faraday-keys/tests/operations.rs::explore::the_first_addresss_private_key_pays_to_bip84s_first_address

faraday/faraday-keys/tests/operations.rs::explore::each_reason_gives_only_its_own_secret

faraday/faraday-core/tests/all/explore.rs::an_addresss_private_key_shown_is_bip84s

no fuzz target: Takes a held key, a path and a reason; no outside input is parsed

Cross-check

Compared with others' code: btclib-wallet's bip32, by the btclib developers, on btclib's own curve.

Area bip32

Faraday's code faraday_bip::keys (master, private derivation), faraday_bip::xkey (strict decoding), bitcoin's Xpub::derive_pub

Compared with btclib-wallet's bip32 over btclib and ecc (btclib/), on btclib's own curve with libsecp256k1 turned off, through bip32_ref.py, and hdkeychain from btcd v0.27.0 (btcd/, Go, decred's secp256k1); the versions a strict reader takes (BIP-32's four, from btclib's network table), a version whose kind differs from the key's data, and a depth-0 key with a parent or an index are ours.

Checked first: The wheels and the vendored Go tree are hashed against references.sha256 before any run; check_driver runs btclib against BIP-32's vectors 1 to 5 and the invalid keys of vector 5 before anything else, and every vector is asked of hdkeychain too.

Vectors BIP-32's vectors 1 to 5 (tools/vectors/bip32/), python-mnemonic's master keys.

Random cases Seeds of 16 to 64 bytes on every network, random paths with every index, public derivation against private, keys broken one rule at a time and the master-key import, each judged by btclib and by hdkeychain.

Differences Hdkeychain reads a key of any version, a key whose version is a private one over a public key's data (or the reverse), and a depth-0 key with a parent fingerprint or an index. Faraday refuses all three, as btclib refuses the last; where one applies and btclib refuses, hdkeychain is not asked (uncovered in area_bip32.py), so Faraday's strict reader is not retired.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 4000 cases

Secret handling

Reveal::AddressKey

not stated by the library.

The text is a Held value in a buffer that zeroizes on drop; the derived key is erased when it is dropped.

Limits

Another reason gets nothing.

Faraday's own calls

none

Convert a key's master seed

SpecificationBIP 32 · BIP 39 · SLIP-0039 · 3 morePublishedCodeLibrary: base16ct 1.0 (through core/faraday-crypto)Faraday's code: faraday/faraday-keysCross-checked withNot cross-checked
Action

Writes a key's master seed as hex, its master extended private key, a SLIP-39 1 of 1, a SLIP-39 set of k of n or of groups, or a codex32 set, a key's words as Seed XOR parts, and a key's words as words, SeedQR, CompactSeedQR, hex entropy, word numbers or 4-letter starts, each read back through its standard's decoder to the key's wallet.

Specification

BIP 32, Hierarchical Deterministic Wallets, Deployed

BIP 39, Mnemonic code for generating deterministic keys, Deployed

SLIP-0039, Shamir's Secret-Sharing for Mnemonic Codes, Status not checked, vendored

BIP 93, codex32: Checksummed SSS-able BIP32 Seeds, Draft, vendored

SeedQR, SeedQR and CompactSeedQR, Convention, vendored

Seed XOR, Seed XOR, Coldcard's split of a seed into parts, Convention, vendored

Code

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: faraday/faraday-keys: Each conversion is given only for Reveal::PaperForm, and only when its result, read back through the standard's own decoder (hex, the strict xprv importer, SLIP-39's share, every share of a set parsed before any recovery and then a first and a last qualifying subset each recovered, codex32's parse of every share and recover from the first k and the last k), gives the key's master fingerprint; otherwise nothing is returned. A key's words written in another form are read back to the same entropy on the same list, so the same words and the same fingerprint, with no PBKDF2 run; SeedQR forms take English 12 or 24 words, and 4-letter starts English. A key with words is refused for SLIP-39 and codex32; SLIP-39 holds 16 and 32 bytes only; Seed XOR is given for a key on the English list only, the list its parts are restored on. A codex32 set of k above 0 takes its identifier from the randomness passed in, never the one of the key's fingerprint nor of its own set, so two sets of one key are not one set; the secret alone keeps the fingerprint's. A SLIP-39 set is made with an empty passphrase, the extendable flag set and iteration exponent 1, its identifier and shares from the randomness passed in, and a shape the split refuses is refused.

Checked against

tools/vectors/bip39

Published, by Trezor (SatoshiLabs), python-mnemonic's vectors; bip32JP's Japanese vectors.

tools/vectors/bip32

Published, by BIP 32's authors (bitcoin/bips).

tools/vectors/slip39

Published, by Trezor (SatoshiLabs), python-shamir-mnemonic.

tools/vectors/bip93

Published, by BIP 93's authors (bitcoin/bips).

faraday/faraday-keys/src/operations.rs::tests::a_wrong_fingerprint_gives_the_error_and_no_result

faraday/faraday-keys/tests/operations.rs::a_key_of_words_gives_its_seed_and_xprv_and_no_slip39_or_codex32

faraday/faraday-keys/tests/operations.rs::a_key_of_seed_bytes_converts_to_the_same_wallet

faraday/faraday-keys/tests/operations.rs::a_codex32_set_of_a_key_recovers_the_same_wallet

faraday/faraday-keys/tests/operations.rs::a_test_network_gives_a_tprv

faraday/faraday-keys/tests/operations.rs::another_reason_gives_nothing

faraday/faraday-keys/tests/operations.rs::a_slip39_two_of_three_of_a_key_recovers_the_seed_from_any_two

faraday/faraday-keys/tests/operations.rs::a_slip39_set_of_groups_recovers_the_seed_from_every_qualifying_subset

faraday/faraday-keys/tests/operations.rs::a_slip39_set_is_refused_for_the_wrong_key_reason_shape_or_randomness

faraday/faraday-keys/tests/operations.rs::a_key_of_words_is_written_as_the_words_the_entropy_the_numbers_and_the_starts

faraday/faraday-keys/tests/operations.rs::a_key_of_words_is_written_as_a_seedqr_and_a_compact_seedqr

faraday/faraday-keys/tests/operations.rs::a_key_of_another_length_than_12_or_24_words_has_no_seedqr

faraday/faraday-keys/tests/operations.rs::another_list_gives_words_and_numbers_but_no_codes_or_starts_and_seed_bytes_give_none

faraday/faraday-keys/tests/operations.rs::seed_xor_gives_coldcards_published_parts

faraday/faraday-keys/tests/operations.rs::seed_xor_is_refused_for_the_wrong_reason

faraday/faraday-keys/tests/operations.rs::seed_xor_is_not_given_for_a_key_on_another_list

faraday/faraday-keys/tests/operations.rs::a_codex32_set_of_a_key_has_an_identifier_of_its_own_each_time

faraday/faraday-core/tests/all/convert.rs::seed_xor_parts_typed_into_add_a_key_give_the_same_key

faraday/faraday-core/tests/all/convert.rs::a_set_is_checked_part_by_part_saved_whole_and_dropped_on_leaving

faraday/faraday-core/tests/all/convert.rs::a_slip39_two_of_three_recovers_the_published_secret_from_any_two

faraday/faraday-core/tests/all/convert.rs::a_slip39_set_of_groups_recovers_the_secret_and_names_each_shares_group

faraday/faraday-core/tests/all/convert.rs::the_slip39_card_cannot_reach_a_shape_the_split_refuses

faraday/faraday-core/tests/all/convert.rs::the_slip39_card_walked_to_its_limits_makes_a_set_each_time

faraday/faraday-core/tests/all/convert.rs::each_codex32_set_of_a_key_has_an_identifier_of_its_own

faraday/faraday-core/tests/all/convert.rs::a_slip39_copy_is_checked_by_group_and_the_file_has_every_share

no fuzz target: Takes a held key and a reason; no outside input is parsed

Cross-check

not cross-checked: The core functions are judged in their own areas; these wrappers add the gate and the read-back, and are tested here against the published vectors, with no cross-check run of their own

Secret handling

Reveal::PaperForm

not stated by the library.

Each result is a Held value in a zeroizing buffer; the seed read back is a Zeroizing copy dropped at once.

Limits

Another reason gets nothing.

A result that does not read back as the key's wallet is not returned.

Faraday's own calls

Only conversions that keep the same master fingerprint. Conservative, F88.

Convert a typed SLIP-39 set

SpecificationSLIP-0039PublishedCodeLibrary: subtle 2.6Faraday's code: faraday/faraday-keysCross-checked withpython-shamir-mnemonicOthers' codeFaraday's second version
Action

Holds the SLIP-39 shares a person types, and from them writes a share at a member index (adding a share or replacing a lost one) or a new set of the same encrypted master secret, each read back before it is returned.

Specification

SLIP-0039, Shamir's Secret-Sharing for Mnemonic Codes, Status not checked, vendored

Code

Library: subtle 2.6.1, by the dalek-cryptography developers.

Faraday's code: faraday/faraday-keys: The typed shares are held as a transient value, never a key, and each is checked against the others as it is typed (one set; no member typed twice; no more members than the group's threshold). A share at a member index is derived from one group's quorum and read back by swapping it in for one of the quorum, which must give back, word for word, the share displaced; where the whole set is typed the swapped set must also recover the same EMS and parameters. A new set is split from the EMS recovered from the whole set's quorum: with the extendable flag set it takes a new identifier and the old one is refused, with it clear the identifier stays; every share is parsed and every member of every group takes part in a qualifying subset that must recover the same EMS and parameters. No passphrase is taken and nothing is decrypted.

Checked against

tools/vectors/slip39

Published, by Trezor (SatoshiLabs), python-shamir-mnemonic.

faraday/faraday-keys/tests/slip39_set.rs::slip39_a_quorum_of_one_group_of_several_adds_a_share_to_that_group

faraday/faraday-keys/tests/slip39_set.rs::slip39_replace_gives_the_very_share_that_was_lost

faraday/faraday-keys/tests/slip39_set.rs::slip39_a_share_of_another_set_or_typed_twice_is_refused_and_what_was_held_stays

faraday/faraday-keys/tests/slip39_set.rs::slip39_a_group_of_threshold_one_or_a_group_never_typed_makes_no_share

faraday/faraday-keys/tests/slip39_set.rs::slip39_rotating_a_flag_clear_set_keeps_the_wallet_and_the_old_shares_do_not_mix_in

faraday/faraday-keys/tests/slip39_set.rs::slip39_rotating_an_extendable_set_gives_a_new_identifier_and_the_same_wallet

faraday/faraday-keys/tests/slip39_set.rs::slip39_a_set_of_groups_rotates_into_another_shape_and_opens_the_same_wallet

faraday/faraday-keys/tests/slip39_set.rs::slip39_a_rotation_needs_the_whole_set_quorum_not_one_groups

faraday/faraday-keys/tests/slip39_set.rs::slip39_a_forget_leaves_nothing_held_and_the_key_list_is_unchanged

faraday/faraday-keys/tests/slip39_set.rs::slip39_the_rotate_count_counts_a_group_out_of_reach_at_its_threshold

fuzz seed_parts

Cross-check

Compared with others' code: python-shamir-mnemonic, by Trezor (SatoshiLabs), and bip39_slip39, by the btclib developers, for the core functions these wrappers call (shares read, recover_ems, split_ems, derive_member), judged in the slip39 area.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: slip39::check_gathered, Faraday's own rule on the shares typed (one set, no member twice, no more members than the threshold), which no judge in tools/crosscheck runs, and the held set and the read-back, which are tested here against the published vectors.

Area slip39

Faraday's code faraday_bip::slip39

Compared with python-shamir-mnemonic (slip39/), its recover_ems, split_ems and _interpolate for a set's EMS, a new split of it and a member at an index; bip39_slip39 (bip39-slip39/) answering each SLIP-39 operation beside it (not the two codex32 operations); python-codex32 (codex32/) for the codex32 side of the conversions and btclib (bip32_ref.py) for the fingerprint; the refusals of a member at an index before the arithmetic are ours (derive_refused), and so are the lengths the fixed 1 of 1 refuses, which no second judge covers.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday, and of bip39_slip39 too; all 45 of its own vectors are run.

Vectors All 45 of tools/vectors/slip39/, each again through its EMS and its decryption.

Random cases Splits fed the same random bytes, which must match word for word; recovery from qualifying and short subsets and a changed word; the passphrase cipher; a set's EMS from a quorum, refused from a short or changed set, split again on the same random bytes (some under a new identifier where extendable) and a member added or a lost one made again at an index, each recovering the first set's secret, and a member refused at an index given, past 15, from a short quorum and across two groups; random seeds of 16 and 32 bytes through the fixed 1 of 1 against both libraries under the fingerprint's first 15 bits, recovered through both, and the lengths it refuses, against Faraday's own rule; the seed written as codex32 by Faraday and read by python-codex32, and a SLIP-39 set with a passphrase recovered by Faraday and by python-shamir-mnemonic, written as codex32 by Faraday and by python-codex32, the second read by Faraday, the same bytes both ways, the identifier's 20 bits written and the fingerprint (btclib's) compared on both sides.

Differences SLIP-39: Faraday refuses a group threshold of 1 over several groups; python-shamir-mnemonic makes the shares. The area checks that this still holds, so a change either way is seen.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 21000 cases

Source

0.2.0 · faraday/faraday-keys/src/slip39_set.rs · Keys::slip39_set_share

0.2.0 · faraday/faraday-keys/src/slip39_set.rs · Keys::slip39_set_rotated

github.com/bitcoinpasada/faraday

Secret handling

Reveal::PaperForm

not stated by the library.

Each share held is wiped as it drops, and each result is a Held value in a zeroizing buffer.

Limits

Another reason gets nothing.

Nothing is held in Practice or while a stick is attached, and no share or set is made while one is; the held set stays.

The fuzz target `seed_parts` reaches the core SLIP-39 functions these call, not the held set or these wrappers.

A result that does not read back as the same EMS and parameters is not returned.

Faraday's own calls

A SLIP-39 set's actions are in Convert a seed, not with the backup, since no plan or vault tracks a SLIP-39 set; nothing is remembered, and a share is refused where one more member than its group's threshold would be held. Conservative, F204.

Read a WIF private key

SpecificationOwn specificationCodeLibrary: secp256k1 0.29Library: bitcoin 0.32Library: hmac 0.13 (through core/faraday-crypto)1 moreFaraday's code: core/faraday-bipCross-checked withBitcoin Core v31.1Others' code
Action

Reads a single private key written as WIF, typed or scanned for a sweep, and works out the addresses it pays.

Specification

Own specification (F171)

Code

Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-bip: Reads base58check with the bitcoin crate and holds Bitcoin Core's DecodeSecret rules itself: a version of 0x80 or 0xef, 32 bytes of key then nothing or exactly 0x01, a scalar in 1..n; the key is held on a pinned page in a signing context blinded from the key and, in faraday-keys, again from the session's randomness. A key of the other network kind, or read while a stick is attached, is refused; the key pays P2PKH, and if compressed P2WPKH and P2SH-P2WPKH.

Checked against

tools/vectors/wif

Published, by Bitcoin Core's key_io_valid.json and key_io_invalid.json, by the Bitcoin Core developers.

core/faraday-bip/tests/all/wif.rs::cores_valid_private_keys_read_with_their_form_and_chain

core/faraday-bip/tests/all/wif.rs::nothing_else_in_cores_files_reads_as_a_private_key

core/faraday-bip/tests/all/wif.rs::a_wif_breaking_a_rule_core_holds_is_refused

core/faraday-bip/tests/all/wif.rs::the_generators_key_pays_its_published_addresses

faraday/faraday-core/tests/all/sweep.rs::a_typed_key_shows_its_three_addresses_and_is_never_loaded

faraday/faraday-core/tests/all/sweep.rs::a_key_of_the_other_network_and_text_that_is_no_key_are_refused

fuzz xkey

Cross-check

Compared with others' code: Bitcoin Core v31.1, by the Bitcoin Core developers, which signs from descriptors of the same WIF what Faraday reads from it and shares libsecp256k1's curve maths with Faraday's; btclib, by the btclib developers, which decodes the WIF and works out its public key on its own curve.

Area sign

Faraday's code faraday_psbt::sign (every held key selected, deterministic Schnorr, both RFC 6979 nonce rules) and faraday_psbt::finalize

Compared with Bitcoin Core v31.1 on regtest (core_node.py): descriptorprocesspsbt signs from the held masters' keys, finalizepsbt finalizes and extracts, testmempoolaccept judges each finalized transaction over its funding on the node; BIP-340's reference (secp256k1lab) and Core's key.py for the deterministic nonces, over Core's script.py sighashes; python-ecdsa (the distribution's package) and btclib (btclib/, its own curve) as a second curve lineage, beside them: every ECDSA signature again under plain RFC 6979 or verified, every BIP-340 signature verified and made again; btclib-wallet's finalizer (psbt.finalize with its miniscript solver) finalizes every input Faraday finalizes again and gives the same scriptSig and witness; for each sweep, btclib reads the WIF (scalar, compression, public key) and signs and finalizes the sweep on its own curve, and python-ecdsa makes the first-nonce signature of each input again, byte for byte; python-bip380 (miniscript/) reads the leaves. Faraday's refusals and the inputs a wallet's rule leaves unsigned are ours, in area_sign.py.

Checked first: Core is the pinned release, hashed against its pin before every run; the vendored files are hashed against references.sha256; a published vector's answer is required of Core as well as of Faraday; every ECDSA and BIP-340 signature Core makes is checked to verify under the hash the area computes before that hash is used for Faraday's deterministic nonces.

Vectors BIP-174's signer, finalizer and extractor vectors; the Core-built spends of tools/vectors/psbt/ (2-of-3 sortedmulti, the Liana wallet down both paths, a taproot tree by a leaf and by the key path, BIP 387's taproot multisig), signed by every subset of their keys; the finalizer vectors there (or_b's smaller signature, the taproot leaves that tie by count, the taproot multisig and MuSig2 spends).

Random cases PSBTs of one to four inputs, each spending a funding output on the node: P2PKH, P2SH-P2WPKH, P2WPKH, multi/sortedmulti in P2SH, P2WSH and P2SH-P2WSH, P2TR key path, P2TR script path (pk, pkh, timelocked keys, or_d, multi_a) with the key path beside it, miniscript in P2WSH and P2SH-P2WSH; held and foreign keys, cosigners' signatures already on (Core's), every standard sighash type, timelocks met and not; Core's signatures (ECDSA byte for byte, BIP-340 by verification and the deterministic nonce), each final scriptSig and witness and the extracted transaction Core's, the cleared fields, and every finalized transaction accepted by Core's mempool; an origin that derives another key refused; sweeps: a WIF key's P2PKH, P2WPKH and P2SH-P2WPKH outputs (P2PKH alone for an uncompressed key) spent beside another key's, signed by Core from the WIF and by faraday_psbt::sweep::sign, byte for byte, finalized and accepted by the mempool.

Differences PSBT signing: Faraday refuses to sign a SegWit v0 input with no previous transaction in a transaction of more than one input; Core signs it, and BIP-174's own signer vector is such a PSBT. The refusal is ours, checked and counted. Faraday holds a finalized input to the same rule and refuses the PSBT when such an input is final, except a taproot one, whose final witness is the coordinator's.

PSBT signing, wallets: Faraday signs an input spent from a script of several keys (a multi of two or more, a miniscript naming two or more, a taproot script path whose carried leaves name two or more with its internal key, or are not its whole tree) only for a registered wallet that holds one of its keys and whose script it is; Core signs any. The area refuses, by a rule of its own, where no wallet the request registers holds a held key and gives the input, and counts it only where Faraday's refusal is that the wallet is not registered. A miniscript or a taproot tree of one key is signed only through such a wallet, and is otherwise left unsigned while the rest is signed (F141); the area takes Core's signatures off it. Half the corpus's multi, miniscript and taproot-tree inputs come with their wallet registered, so their signatures are still compared. A registered tree's every leaf has its wait met, since Faraday refuses a path that can never be valid, which the area does not work out.

PSBT signing: Faraday refuses a PSBT any input of which asks for a NONE or SINGLE sighash, and one that none of the held keys can sign: dangers no hold accepts (F136). Core signs the first and answers the second with nothing signed. The area expects both refusals by a rule of its own, counting a held key as taking part as Faraday's inspection does (a miniscript or a taproot tree only through a wallet in use), checks that Faraday's refusal names the danger, and counts them.

Taproot pkh leaves: Faraday signs a taproot leaf that checks its key by hash but does not finalize it: miniscript 12's finalizer looks the key up among the ECDSA origins and panics, and would push 33 bytes where the leaf hashed 32. Core finalizes such a leaf; the area takes the signatures under it off before Core finalizes, and counts each input Core would otherwise have finalized another way.

btclib's finalizer writes no taproot leaf that is neither a single key nor multi_a, and refuses to choose among leaves a PSBT signs: an input of another leaf is judged by Core alone (counted as a known difference), and btclib is given only the signatures of the leaf Faraday spent. It writes a plain multisig from the smallest m signatures on hand where Core and Faraday write the first m signers': btclib is given only the signatures Faraday's input carries, so it judges the script written from them and Core judges which were chosen.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 1580 cases

Source

0.2.0 · core/faraday-bip/src/wif.rs · SingleKey::decode

0.2.0 · core/faraday-bip/src/wif.rs · SingleKey::from_payload

0.2.0 · core/faraday-bip/src/wif.rs · SingleKey::scripts

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

libsecp256k1 documents its key multiplication as constant time; the base58 decode is not stated to be.

The decoded buffer is zeroized before the reader returns, but base58ck's own scratch and result vectors are freed unwiped, until the next lock (ESTABLISHED §4.8); the key is held on a pinned page and erased when it is dropped, at Done, a lock or leaving the Sweep sheet.

Limits

A key is swept and never kept: no vault record, no key slot, no backup.

A WIF of the other network kind is refused.

Faraday's own calls

A WIF key is never loaded as a key or kept: it lives for one sweep. Conservative, F171.

Show a key's words

SpecificationOwn specificationCodeFaraday's code: faraday/faraday-keysCross-checked withNot cross-checked
Action

Lends a key's words or passphrase as text for a named reason, and shows them on screen or for copying by hand.

Specification

Own specification (F70)

Code

Faraday's code: faraday/faraday-keys: A key's words and passphrase leave as text only through a Reveal reason from a closed list; the text is lent while a guard lives and the guard cannot be cloned or printed.

Checked against

not checked against vectors

faraday/faraday-keys/tests/operations.rs::explore::each_reason_gives_only_its_own_secret

faraday/faraday-keys/tests/vault.rs::a_secret_leaves_a_record_only_through_a_reveal_that_names_it

faraday/faraday-core/tests/all/explore.rs::the_eye_shows_the_words_and_hides_them

no fuzz target: Takes a held key and a reason; no outside input is parsed

Cross-check

not cross-checked: The reasons are Faraday's own list; no other implementation has one

Secret handling

Reveal::Words

Reveal::Passphrase

Reveal::CopyByHand

not stated by the library.

The lent text is borrowed from a zeroizing buffer held by the key; the guard holds no copy; the key wipes its words when it is removed.

Limits

A reason that lends no stored text, or a key with no words, gives the empty text.

Faraday's own calls

The list of reasons is closed: a new reason is a new variant, seen in review. Conservative, F70.

Compare two keys' words

SpecificationBIP 39PublishedCodeLibrary: sha2 0.11 (through core/faraday-crypto)Library: unicode-normalization 0.1 (through core/faraday-bip)Faraday's code: faraday/faraday-keysCross-checked withNot cross-checked
Action

Tells whether two keys, or a key and a copy of its words, have the same words, by a SHA-256 of their entropy, and orders the copy check's questions.

Specification

BIP 39, Mnemonic code for generating deterministic keys, Deployed

Code

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Library: unicode-normalization 0.1.25, by the unicode-rs developers, through core/faraday-bip.

Faraday's code: faraday/faraday-keys: The id is all 32 bytes of the SHA-256 of the words' entropy, worked out the first time it is asked and kept beside the key, so two seeds never pass for one; the same words with and without a passphrase share it. What is kept of a secret's fingerprint is keyed by SHA-256 of a tag and the secret, so the secret itself is kept nowhere. The copy check's questions are ordered by a small shuffle (xorshift64*) seeded from 8 bytes of the session's generator, which the words do not enter.

Checked against

not checked against vectors

faraday/faraday-keys/tests/operations.rs::keys_added_from_words_come_back_with_their_fingerprint_and_word_count

faraday/faraday-keys/tests/operations.rs::a_master_key_is_told_from_another_by_all_of_its_identity

no fuzz target: Takes held words; no outside input is parsed

Cross-check

not cross-checked: A comparison inside the program; there is no second implementation to compare it with

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The id is a hash of secret entropy, kept only beside its key, wiped when dropped and never written anywhere.

Limits

A key with no words has no id and matches nothing.

Faraday's own calls

The id is all 32 bytes of a hash, so two seeds never pass for one. Conservative.

no decision

Wallets

10 actions · 2 with Faraday's own code · 10 cross-checked with others' code · 4 with Faraday's second version

Derive a cosigner account

SpecificationBIP 48 · BIP 67PublishedCodeLibrary: bitcoin 0.32Faraday's code: core/faraday-bipCross-checked withbtclib-wallet's bip32Others' code
Action

Derives a BIP 48 cosigner account and its extended public key, and lends the account key to sign a BSMS key record.

Specification

BIP 48, Multi-Script Hierarchy for Multi-Sig Wallets, Deployed

BIP 67, Deterministic Pay-to-script-hash multi-signature addresses through public key sorting, Complete

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Faraday's code: core/faraday-bip: The account path is m/48'/coin'/account'/script' with script 1' or 2'; the account node's private key is lent to one closure and erased when it returns.

Checked against

tools/vectors/bip32

Published, by BIP 32's authors (bitcoin/bips).

core/faraday-bip/tests/all/accounts.rs::other_accounts_and_index_limits

core/faraday-bip/tests/all/bsms.rs::the_record_this_device_writes_parses_back_and_verifies

no fuzz target: Takes a held key and an account number; no outside text is parsed

Cross-check

Compared with others' code: btclib-wallet's bip32, by the btclib developers, on btclib's own curve.

Area bip32

Faraday's code faraday_bip::keys (master, private derivation), faraday_bip::xkey (strict decoding), bitcoin's Xpub::derive_pub

Compared with btclib-wallet's bip32 over btclib and ecc (btclib/), on btclib's own curve with libsecp256k1 turned off, through bip32_ref.py, and hdkeychain from btcd v0.27.0 (btcd/, Go, decred's secp256k1); the versions a strict reader takes (BIP-32's four, from btclib's network table), a version whose kind differs from the key's data, and a depth-0 key with a parent or an index are ours.

Checked first: The wheels and the vendored Go tree are hashed against references.sha256 before any run; check_driver runs btclib against BIP-32's vectors 1 to 5 and the invalid keys of vector 5 before anything else, and every vector is asked of hdkeychain too.

Vectors BIP-32's vectors 1 to 5 (tools/vectors/bip32/), python-mnemonic's master keys.

Random cases Seeds of 16 to 64 bytes on every network, random paths with every index, public derivation against private, keys broken one rule at a time and the master-key import, each judged by btclib and by hdkeychain.

Differences Hdkeychain reads a key of any version, a key whose version is a private one over a public key's data (or the reverse), and a depth-0 key with a parent fingerprint or an index. Faraday refuses all three, as btclib refuses the last; where one applies and btclib refuses, hdkeychain is not asked (uncovered in area_bip32.py), so Faraday's strict reader is not retired.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 4000 cases

Source

0.2.0 · core/faraday-bip/src/keys.rs · MasterKey::multisig_account_xpub

0.2.0 · faraday/faraday-keys/src/texts.rs · multisig_account

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The derived account key is erased when the closure that was lent it returns.

Limits

Only BIP 48 script types 1' and 2' are derived; the 3' some wallets use is not.

Account indexes of 2^31 or more are refused.

Faraday's own calls

A multisig key with no origin is refused where a policy reads it. Conservative, F155.

Derive an address

SpecificationBIP 44 · BIP 49 · BIP 84 · 4 morePublishedCodeLibrary: bitcoin 0.32Library: secp256k1 0.29Library: miniscript 12.3Faraday's code: core/faraday-bipCross-checked withBitcoin Core v31.1 itself (deriveaddresses) and its functional-test frameworkOthers' code
Action

Derives the script and the address of a wallet at a chain and an index, and looks for an address among a wallet's first addresses.

Specification

BIP 44, Multi-Account Hierarchy for Deterministic Wallets, Deployed

BIP 49, Derivation scheme for P2WPKH-nested-in-P2SH based accounts, Deployed

BIP 84, Derivation scheme for P2WPKH based accounts, Deployed

BIP 86, Key Derivation for Single Key P2TR Outputs, Deployed

BIP 341, Taproot: SegWit version 1 spending rules, Deployed

BIP 173, Base32 address format for native v0-16 witness outputs, Deployed

BIP 350, Bech32m Format for v1+ Witness Addresses, Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).

Library: miniscript 12.3.7, by the rust-bitcoin developers (rust-miniscript).

Faraday's code: core/faraday-bip: The script is derived from the keys of the policy on a verification-only context; an index of 2^31 or more is refused; the search takes the receive and change address at each index in turn, nearest first. Explore's address list and search derive from the account's extended public key as a single-key wallet and keep up to 10,000 addresses of each chain from index 0; a search looks 100, 1,000 or 10,000 indices deep, and a wallet keeps the scripts it has derived, a lookup after the first.

Checked against

tools/vectors/addresses

Published, by the authors of BIP 173, BIP 350, BIP 380, BIP 49, BIP 84 and BIP 86 (bitcoin/bips).

tools/vectors/bip32

Published, by BIP 32's authors (bitcoin/bips).

core/faraday-bip/tests/all/accounts.rs::bip44_legacy_mainnet

core/faraday-bip/tests/all/accounts.rs::bip49_nested_segwit_testnet

core/faraday-bip/tests/all/accounts.rs::bip84_native_segwit_mainnet

core/faraday-bip/tests/all/accounts.rs::bip86_taproot_mainnet

core/faraday-bip/tests/all/accounts.rs::find_address_scans_both_chains

core/faraday-bip/tests/all/accounts.rs::other_accounts_and_index_limits

core/faraday-bip/src/policy.rs::a_wallet_over_a_bare_key_derives_the_published_addresses

faraday/faraday-core/tests/all/explore_addresses.rs::the_list_gives_the_published_addresses_of_each_account

faraday/faraday-core/tests/all/explore_addresses.rs::a_whole_address_is_found_at_its_index_on_each_chain

self-test bip84_address

fuzz policy

Cross-check

Compared with others' code: Bitcoin Core v31.1 itself (deriveaddresses) and its functional-test framework, by Bitcoin Core's contributors; btclib-wallet's bip32 and slip132, by the btclib developers, on btclib's own curve, for the account keys, and its descriptors (parse, script_pub_key, checksum) for each account descriptor's kind, text, script at an index and checksum; BIP 380's own checksum code, as the BIP prints it; python-mnemonic, by Trezor (SatoshiLabs), for the seeds.

Area addr

Faraday's code faraday_bip::address::parse, bitcoin's Address::from_script, faraday_bip::account (account xpub, SLIP-132, descriptor, addresses), faraday_bip::descriptor's checksum, faraday_bip::policy::WalletPolicy::from_descriptor (an account descriptor's kind, text and script at an index)

Compared with Bitcoin Core's functional-test framework (core/): segwit_addr.py, Base58Check, descriptors.py; BIP 380's own checksum code as the BIP prints it (bip380/); btclib-wallet's bip32 and slip132 (btclib/, on btclib's own curve) for accounts' keys, and its descriptors (descriptors) for each account descriptor's kind, text, script at an index and checksum, and as a third checksum judge; Bitcoin Core v31.1's bitcoind on regtest for every account's address (deriveaddresses) and for reading Faraday's regtest descriptors (getdescriptorinfo).

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; every descriptor checksum is also asked of BIP 380's own code, as the BIP prints it, and of btclib's; Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked.

Vectors BIP-350's and BIP-173's addresses, BIP-380's checksum cases, BIP-49's, 84's and 86's accounts (tools/vectors/addresses/).

Random cases Scripts of every address kind on every network, written and read back, then changed; accounts of every type at random indices, their descriptors read and changed; random descriptors' checksums.

Differences A descriptor with a second # in its body: Faraday and btclib refuse it, as Bitcoin Core's parser does, where BIP 380's code and Core's framework check the last nine characters; its checksum is asked of btclib only. btclib reads descriptors Faraday takes for no account (pk, combo, multi, addr, raw) and other chains than <0;1>; the area asks it for the four account descriptors with both chains only.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 40000 cases

Source

0.2.0 · core/faraday-bip/src/policy.rs · WalletPolicy::script_at

0.2.0 · core/faraday-bip/src/policy.rs · WalletPolicy::address_at

0.2.0 · core/faraday-bip/src/account.rs · AccountXpub::address

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

Only public keys are used; nothing here holds a secret.

Nothing secret is held.

Limits

An address index of 2^31 or more is refused.

A search looks only as far as the index it is given.

A search keeps its first 50 matches and counts the rest.

Faraday's own calls

none

Read and write a descriptor

SpecificationBIP 380 · BIP 382 · BIP 383 · 5 morePublishedCodeLibrary: bitcoin 0.32Library: miniscript 12.3Library: base16ct 1.0 (through core/faraday-crypto)Faraday's code: core/faraday-bipCross-checked withBitcoin Core v31.1 itself (deriveaddresses) and its functional-test frameworkOthers' code
Action

Reads and writes a wallet's descriptor and wallet policy, and works out and checks the descriptor checksum.

Specification

BIP 380, Output Script Descriptors General Operation, Deployed

BIP 382, Output Script Descriptors: wsh, Deployed

BIP 383, Output Script Descriptors: multi, Deployed

BIP 386, Output Script Descriptors: tr, Deployed

BIP 388, Wallet Policies for Descriptor Wallets, Complete

BIP 389, Multipath Descriptor Key Expressions, Draft

BIP 379, Miniscript, Draft

BIP 381, Non-Segwit Output Script Descriptors, Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: miniscript 12.3.7, by the rust-bitcoin developers (rust-miniscript).

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-bip: A wallet policy (BIP 388) and a descriptor are one wallet, written with h for hardened and the multipath /<0;1>/* form; a descriptor with a checksum that does not match is refused; the checksum is BIP 380's, worked out by miniscript; a tr() wallet states who can spend by the key path.

Checked against

tools/vectors/addresses

Published, by the authors of BIP 173, BIP 350, BIP 380, BIP 49, BIP 84 and BIP 86 (bitcoin/bips).

tools/vectors/bip387

Published, by BIP 387's authors (bitcoin/bips).

tools/vectors/miniscript

Published, by Bitcoin Core's miniscript_tests.cpp, v31.1, by the Bitcoin Core developers.

core/faraday-bip/tests/all/descriptor.rs::known_checksums

core/faraday-bip/tests/all/descriptor.rs::single_symbol_errors_are_detected

core/faraday-bip/tests/all/calculators.rs::the_descriptor_checksum_matches_bip_380

core/faraday-bip/src/policy.rs::bip388_examples_produce_their_descriptors

core/faraday-bip/src/policy.rs::bip388_invalid_policies_are_refused

core/faraday-bip/src/policy.rs::a_wrong_checksum_is_refused

core/faraday-bip/tests/all/policy_key_path.rs::an_extended_internal_key_over_nums_is_unspendable

core/faraday-bip/tests/all/miniscript.rs::a_miniscript_that_is_not_sane_is_refused

core/faraday-bip/tests/all/core_import.rs::the_pair_for_core_before_29_is_cores_own_receive_and_change_descriptors

fuzz policy

Cross-check

Compared with others' code: Bitcoin Core v31.1 itself (deriveaddresses) and its functional-test framework, by Bitcoin Core's contributors; python-bip380, by Antoine Poinsot, for Core's vectors that state no script; btclib-wallet's bip32, by the btclib developers, for the cosigners' keys, and its descriptors and miniscript, by the btclib developers, on btclib's own curve, for each descriptor's kind, text and script at an index, Core's vectors' types, sanity and scripts, and the satisfaction of each way a wallet's coins move under its lock times.

Area miniscript

Faraday's code faraday_bip::policy::WalletPolicy (a wallet's descriptor and the script it pays at an index, its kind, text and spend paths), faraday_bip::policy::parse_script_descriptor, a witness script read back as faraday_psbt reads one, faraday_bip::recovery::RecoveryPolicy (a recovery wallet built from its parts and read back)

Compared with Bitcoin Core v31.1's bitcoind on regtest (deriveaddresses) for random wallets, their cosigners' keys from btclib (btclib/, on btclib's own curve); btclib-wallet's descriptors and miniscript (btclib/) for each descriptor's kind, text and script, Core's vectors' types and scripts, and the satisfaction of each way a wallet's coins move under its lock times; Antoine Poinsot's python-bip380 (miniscript/) for Core's vectors that state no script.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; btclib reads Core's 97 miniscripts, in both contexts, before any random wallet (valid exactly when Core says, its properties, sane, script); Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked.

The witness bytes of a satisfaction (btclib assembles one and area sign compares Faraday's finalizer); a wallet with more than 64 ways to spend, for which Faraday states none; hash locks and locks in seconds, which the corpus does not generate; and a wallet btclib cannot read (none yet).

Vectors Bitcoin Core's miniscript unit tests, 97 miniscripts in P2WSH and Tapscript (tools/vectors/miniscript/).

Random cases Wallets of the Liana, Nunchuk, Sparrow and recovery shapes in wsh() and sh(wsh()), multi/sortedmulti in sh(), wsh(), sh(wsh()), tr() with trees of one to six leaves or a lone sortedmulti_a, over random accounts on every network, at random indices of both chains; the same made not sane, refused; recovery wallets of both forms with one to three recovery paths, and the ways each wallet's coins move spent at their lock times.

Differences Miniscript: Faraday reads sortedmulti_a only as a tr()'s one leaf; BIP 387 allows it deeper in a tree, and Core reads it there. Two of Bitcoin Core's sane miniscripts are refused, as miniscript refuses them: or_b(0,a:0), which has no satisfaction, and a d: used as a unit under Tapscript. Each is checked and counted; btclib is not asked the deeper sortedmulti_a. btclib says nothing of "needs a signature" for a malleable miniscript (BIP 379 does not), so that property is compared where Core calls the miniscript non-malleable.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 2500 cases

Source

0.2.0 · core/faraday-bip/src/policy.rs · WalletPolicy::parse

0.2.0 · core/faraday-bip/src/policy.rs · WalletPolicy::to_descriptor

0.2.0 · core/faraday-bip/src/descriptor.rs · descriptor_checksum

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

Only public keys and public text are read; nothing here holds a secret.

Nothing secret is held.

Limits

A threshold above the keys, a key repeated, a key with no origin outside a single-key template, and a miniscript that is not sane are refused.

A key expression's derivation must be /** or /<0;1>/*.

Multisig takes at most 15 keys.

Faraday's own calls

Only BIP 341's H, or an extended key over H, counts as an unspendable internal key. Conservative, F132.

One text is written, with h for hardened. Neutral, F66.

Read taproot multisig

SpecificationBIP 387 · BIP 386 · BIP 341 · 1 morePublishedCodeLibrary: bitcoin 0.32Library: miniscript 12.3Faraday's code: core/faraday-bipCross-checked withbtclib's check_output_pubkeyOthers' codeFaraday's second version
Action

Reads taproot multisig descriptors with multi_a and sortedmulti_a, and builds their scripts at each derivation index.

Specification

BIP 387, Tapscript Multisig Output Script Descriptors, Deployed, vendored

BIP 386, Output Script Descriptors: tr, Deployed

BIP 341, Taproot: SegWit version 1 spending rules, Deployed

BIP 342, Validation of Taproot Scripts, Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: miniscript 12.3.7, by the rust-bitcoin developers (rust-miniscript).

Faraday's code: core/faraday-bip: sortedmulti_a is read here because miniscript has no such fragment: the descriptor is read as its multi_a twin and the script rebuilt at every index with the x-only keys sorted.

Checked against

tools/vectors/bip387

Published, by BIP 387's authors (bitcoin/bips).

core/faraday-bip/tests/all/bip387.rs::every_valid_descriptor_pays_to_its_published_script

core/faraday-bip/tests/all/bip387.rs::every_invalid_descriptor_is_refused

core/faraday-bip/tests/all/bip387.rs::sorting_is_of_the_derived_keys

fuzz policy

Cross-check

Compared with others' code: btclib's check_output_pubkey, by the btclib developers, on btclib's own curve; ParseControlBlock and VerifyTaprootLeafCommitment of btcd v0.27.0, by the btcd developers; and Bitcoin Core's functional-test framework, v31.1, by Bitcoin Core's contributors, for the trees.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the rule that a leaf version is not 0x50, which neither btclib nor btcd makes, written in area_taproot.py.

Area taproot

Faraday's code bitcoin's TaprootBuilder and TaprootSpendInfo (as faraday_bip::tapmulti and miniscript's tr() build trees), ScriptBuf::new_p2tr as faraday_psbt::sign checks a key path, Address::p2tr_tweaked, ControlBlock decoding and verify_taproot_commitment

Compared with Core's taproot_construct, key.py's tweak and segwit_addr.py for the trees; btclib's check_output_pubkey (btclib/, on its own curve) and btcd v0.27.0's txscript.ParseControlBlock and VerifyTaprootLeafCommitment (btcd/, Go) for the control blocks; the rule that a leaf version is not 0x50 is ours.

Checked first: Its vendored files, the btclib wheels and the vendored Go tree are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; each of BIP-341's wallet vectors is checked against the reference first.

Vectors BIP-341's scriptPubKey wallet vectors, all seven (tools/vectors/sighash/).

Random cases Trees of 0 to 12 leaves in random shapes with random scripts and leaf versions over random internal keys: leaf hashes, Merkle root, tweak, output key and parity, script, address, control blocks; each control block checked, then changed eleven ways, each judged by btclib and by btcd; internal keys that are no point, odd leaf versions and 0x50 refused.

Differences Btclib and btcd hash a leaf of version 0x50 like any other, where BIP-341's text and Faraday refuse it (the annex tag): a control block of that version is judged by the area alone, and neither is asked.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 4400 cases

Source

0.2.0 · core/faraday-bip/src/tapmulti.rs · sorted_multi_a_script

0.2.0 · core/faraday-bip/src/tapmulti.rs · output_script

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

Only public keys are used; nothing here holds a secret.

Nothing secret is held.

Limits

A hardened wildcard is parsed but not derived.

Faraday's own calls

The path m/48'/coin'/0'/3' has no standard; it is Faraday's choice. Neutral.

no decision

Only BIP 341's H, or an extended key over H, counts as an unspendable internal key. Conservative, F132.

Read a wallet export

SpecificationBIP 388 · RFC 8259PublishedCodeLibrary: bitcoin 0.32Library: serde_json 1.0Library: base16ct 1.0 (through core/faraday-crypto)Faraday's code: core/faraday-bipFaraday's own codeCross-checked withBitcoin Core v31.1 (deriveaddressesOthers' codeFaraday's second version
Action

Reads another wallet's export (Coldcard JSON and multisig configuration files, Specter DIY's addwallet command) as a wallet and checks the first address it states; writes a native SegWit single-key wallet as Coldcard's file for Wasabi, and any wallet but a MuSig2 or silent payments one as Specter DIY's addwallet command.

Specification

BIP 388, Wallet Policies for Descriptor Wallets, Complete

RFC 8259, The JavaScript Object Notation (JSON) Data Interchange Format, Status not checked

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: serde_json 1.0.151, by David Tolnay.

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-bip: JSON is read by serde_json, behind Faraday's refusal of a key named twice and of a nesting deeper than 32 (and of a text over 1 MiB); a Coldcard export's stated first address is derived and compared; a multisig file with more than fifteen cosigners is refused at the sixteenth. An account key alone becomes a wallet of the kind its path's purpose names (44 legacy, 49 nested SegWit, 84 native SegWit, 86 taproot), and a purpose of 45, 48 or 87 is a cosigner's key and no wallet on its own; a key of a test network is taken as testnet unless the session is already on a test network; the file for Wasabi is written only for a native SegWit single-key wallet whose key has an origin at exactly 84h/0h/0h or 84h/1h/0h. Specter DIY's addwallet command is read with its name before the last `&`, its descriptor's checksum checked where it has one (Specter DIY drops it unread), and keys none of which carries a derivation as the two chains; a single-key or multisig wallet is written without its keys' derivations and with no checksum, as Sparrow writes it, any other with them.

Written by Faraday

The JSON visitor that refuses a key named twice and counts depth (faraday-bip::json) · Only the part used is written

serde_json reads the text; Faraday refuses a key named twice and a nesting deeper than 32.

Decision F180

Checked against

tools/vectors/wallet-files

Published, by the wallets' own test suites: Coldcard's firmware, Caravan, Liana, Sparrow and BlueWallet (the commit, licence and SHA-256 of each file are in the folder's README and the interop vectors' README).

core/faraday-bip/tests/all/coldcard.rs::an_export_is_rooted_at_the_masters_xfp_and_has_its_stated_first_address

core/faraday-bip/tests/all/coldcard.rs::an_export_whose_stated_first_address_is_not_its_wallets_is_refused

core/faraday-bip/tests/all/coldcard.rs::a_multisig_key_in_another_scripts_version_is_refused

core/faraday-bip/src/multisig_config.rs::a_config_of_more_cosigners_than_a_multisig_takes_is_refused

core/faraday-bip/src/multisig_config.rs::slip132_spellings_of_a_key_read_as_the_same_wallet

core/faraday-bip/tests/all/json.rs::a_key_named_twice_too_deep_or_too_long_is_refused

core/faraday-bip/tests/all/json.rs::a_key_written_two_ways_is_still_named_twice

faraday/faraday-intake/tests/all/wallet_files.rs::an_electrum_secret_is_found_wherever_the_file_puts_it

faraday/faraday-core/tests/all/inbox_found.rs::an_account_xpub_alone_becomes_a_watch_only_wallet_of_its_paths_kind

faraday/faraday-core/tests/all/inbox_found.rs::a_cosigners_multisig_xpub_is_not_a_wallet_on_its_own

faraday/faraday-core/tests/all/interop.rs::cores_and_specters_files_of_a_taproot_sortedmulti_a_wallet_read_as_it_with_cores_address

faraday/faraday-core/tests/all/interop.rs::a_taproot_sortedmulti_a_pair_of_two_wallets_or_with_a_wrong_checksum_is_refused

faraday/faraday-intake/tests/all/wallet_files.rs::sparrows_specter_diy_export_reads_as_its_2_of_3_named_sparrow_multisig

faraday/faraday-intake/tests/all/wallet_files.rs::faradays_addwallet_for_sparrows_wallet_is_sparrows_own_text

faraday/faraday-intake/tests/all/wallet_files.rs::an_addwallet_command_faraday_cannot_verify_is_refused

faraday/faraday-core/tests/all/interop.rs::faradays_specter_diy_file_reads_back_with_the_same_first_address_and_its_name

fuzz json

fuzz read_wallet

Cross-check

Compared with others' code: Bitcoin Core v31.1 (deriveaddresses, and BIP-380's checksum in its descriptors.py), by the Bitcoin Core developers, for every wallet's addresses and checksums; btclib-wallet's BIP-32 and btclib's SLIP-132 versions, by the btclib developers, for the keys; and 93 real files from the wallets' own test suites (Sparrow, BlueWallet, Coldcard, Caravan, Liana), read in the same area.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the files the area writes and what each format's fields mean, and the formats no test suite publishes a file for (Nunchuk's, Specter DIY's and Keystone's beyond Sparrow's copies) (Coldcard's export and multisig file, Caravan's, Electrum's, Cobo's, Keystone's, Wasabi's, Specter Desktop's, Specter DIY's addwallet, Core's listdescriptors), written in area_import.py from each format's documentation, which account of a Coldcard export and which pair of a listdescriptors is the wallet, and F155's SLIP-132 refusals.

Area import

Faraday's code faraday_intake::wallet::read_wallet (the wallet a file or text is: descriptors, faraday_bip::coldcard, faraday_bip::multisig_config, Caravan's, Electrum's, Cobo's, Keystone's and Wasabi's files, Specter DIY's addwallet, faraday_bip::bsms::DescriptorRecord), and faraday_bip::bsms::SignerRecord read and verified and faraday_bip::bsms::signer_record over the BIP-48 or BIP-87 account node's key

Compared with Bitcoin Core v31.1's bitcoind on regtest, offline (deriveaddresses), and its descriptors.py (BIP-380's checksum) and address.py, for each wallet's receive and change scripts and every checksum; btclib-wallet 2026.10.29's BIP-32 (btclib's own curve) for every key, btclib 2026.10.24's SLIP-132 versions and addresses, and its bms for every key record's signature, made, verified and written byte for byte; CPython's json for the value of every JSON file read and for a key named twice and a nesting past 32 refused (those two rules are the reader's own, written beside it); the files are written in the area from each format's documentation, and the meaning of their fields is the area's.

Checked first: Core's release tarball against its pinned SHA-256 before every run; btclib's wheels against the hashes btclib-wallet's lock file names (references.sha256), with libsecp256k1 off; BIP 129's own records and the real files of Sparrow, BlueWallet (Nunchuk's, Coldcard's and Unchained's among them), Coldcard, Caravan and Liana, judged in the prelude.

The wallet's name a file carries; Electrum's encrypted files and BSMS's encrypted records, which Faraday refuses by name; a silent payments record; the kind of a refusal.

Vectors BIP 129's key and descriptor records (tools/vectors/bip129/), and 93 real files from the wallets' own test suites, 62 of them a wallet and 31 refused by both sides (faraday/faraday-core/tests/vectors/interop/: Sparrow's and BlueWallet's; tools/vectors/wallet-files/: Coldcard's firmware tests, Caravan's and Liana's): BSMS records, Coldcard setup files and exports, Caravan, Electrum, Cobo, Keystone, Jade, Specter Desktop and Specter DIY files, descriptors and a Core listdescriptors.

Random cases single-key wallets (P2PKH, P2SH-P2WPKH, P2WPKH, P2TR), sortedmulti in P2WSH, P2SH-P2WSH and P2SH of one to fifteen keys, a miniscript in P2WSH, a taproot tree and a taproot sortedmulti_a, on mainnet and testnet keys, each as a descriptor (multipath with and without checksum, receive and change lines, labelled, receive alone, Core's listdescriptors, Specter Desktop's file, Specter DIY's addwallet with and without its keys' derivations) or as the files that state its kind (Coldcard's export and multisig file, Caravan's, Electrum's, Cobo's, Wasabi's, a key alone, a BSMS descriptor record), in BIP-32's or SLIP-132's spelling; damaged by a wrong checksum, a wrong first address, a SLIP-132 version of another script or another paths line; key records signed by btclib in each header form, with or without damage, and Faraday's own record of random seeds.

Differences Still ours, expected from Faraday's rule: a SLIP-132 version that names another script than the file's (F155), a BSMS paths line other than /0/*,/1/* or No path restrictions, which Faraday reads as the two chains (F64), a BSMS descriptor that is not a template, a key record whose description is over eighty characters or whose token is not BIP 129's; and which account of a Coldcard export, which pair of a listdescriptors, and what each field of every format means, the area's reading of each format's documentation; a checksum in Specter DIY's addwallet, which Specter DIY drops unread and Faraday checks, is refused when Core's code calls it wrong; and the reading of each format's documentation.

Real files both sides refuse, each by a named rule: a Caravan file or an Electrum multisig file whose keys lack a path or a fingerprint, a Caravan quorum that is not the keys listed, a multisig setup file with no policy, a key missing or no format line (Coldcard's own P2SH setup files omit Format, which Faraday refuses), a BSMS record with a paths line other than /0/*,/1/*, a derivation other than /** or <0;1>, a missing line, a first address that is not Core's or not an address, a Coldcard cosigner key file, an Unchained key file and a Coldcard stored setting (a key, not a wallet), and a UR text (area ur). Left out and named: a silent payments record (area sp) and a PSBT or transaction file (areas psbt, tx).

Formats with no published file in a test suite: Nunchuk's own files (only BlueWallet's copies of them), Specter DIY's beyond the one Sparrow keeps, Keystone's beyond Sparrow's, and Core's listdescriptors beyond the one in the interop vectors, whose source is not recorded; Electrum's published test wallets carry a seed and are not taken. Those formats stay the area's own reading (Faraday's second version), as above.

A key record's signature in any of BIP-137's header forms is accepted when it recovers the record's key: btclib is asked with the address that form names (Faraday reads no address from the record).

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 4500 cases

Secret handling

none: no secret leaves faraday-keys

Only public keys and public text are read, except that an Electrum file is read to find whether it holds a secret.

An Electrum file's keystore is checked for a private key or seed without its values being kept; the file's own bytes are the caller's.

Limits

A file whose stated first address is not its wallet's is refused.

A key in a SLIP-132 version that disagrees with the script is refused.

A receive and a change descriptor are one wallet only when they are the same but for /0/* and /1/*, each with its checksum, if any, holding; otherwise the file is refused.

A file for Wasabi is written only for a native SegWit single-key wallet at 84h/0h/0h (mainnet) or 84h/1h/0h (test networks).

Faraday's own calls

A SLIP-132 version is checked against the script and the path around the key. Conservative, F155.

A Caravan file whose startingAddressIndex is not 0, and an Electrum multisig keystore with no fingerprint, are refused. Conservative, F155.

Read BSMS records

SpecificationBIP 129 · BIP 137PublishedCodeLibrary: bitcoin 0.32Library: secp256k1 0.29Library: base64ct 1.81 moreFaraday's code: core/faraday-bipCross-checked withbtclib's bms and btclib-wallet's BIP-32Others' codeFaraday's second version
Action

Reads BSMS key and descriptor records, checks the signature on a signer's record and writes this device's own signed record.

Specification

BIP 129, Bitcoin Secure Multisig Setup (BSMS), Complete, vendored

BIP 137, Signatures of Messages using Private Keys, Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).

Library: base64ct 1.8.3, by the RustCrypto developers.

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-bip: The signature is the legacy compact recoverable signature every signer writes: the public key is recovered from it and compared with the record's; a descriptor record's first address is derived and compared; a record signed with a secret that is not the account's is refused rather than written.

Checked against

tools/vectors/bip129

Published, by BIP 129's authors (bitcoin/bips).

core/faraday-bip/tests/all/bsms.rs::every_key_record_the_bip_writes_is_read_and_its_signature_holds

core/faraday-bip/tests/all/bsms.rs::a_key_record_changed_after_signing_does_not_verify

core/faraday-bip/tests/all/bsms.rs::every_descriptor_record_the_bip_writes_is_its_wallet_and_its_first_address

core/faraday-bip/tests/all/bsms.rs::a_descriptor_record_stating_another_address_is_refused

core/faraday-bip/tests/all/bsms.rs::an_encrypted_record_is_refused_as_encrypted

core/faraday-bip/tests/all/bsms.rs::a_record_of_another_version_is_refused

core/faraday-bip/tests/all/bsms.rs::the_record_this_device_writes_parses_back_and_verifies

no fuzz target: Takes a record text; the descriptor it carries is the policy parser, which the policy target fuzzes

Cross-check

Compared with others' code: btclib's bms and btclib-wallet's BIP-32, by the btclib developers, for every key record's signature, made, verified and written; Bitcoin Core v31.1 (deriveaddresses), by the Bitcoin Core developers, for a descriptor record's addresses.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: BIP 129's record lines read in area_import.py, and the rules no outside code has: the paths line (/0/*,/1/* or No path restrictions, read as the two chains, F64), a descriptor that is not a template, a description over eighty characters, a token not BIP 129's, and the header forms a signature is accepted in.

Area import

Faraday's code faraday_intake::wallet::read_wallet (the wallet a file or text is: descriptors, faraday_bip::coldcard, faraday_bip::multisig_config, Caravan's, Electrum's, Cobo's, Keystone's and Wasabi's files, Specter DIY's addwallet, faraday_bip::bsms::DescriptorRecord), and faraday_bip::bsms::SignerRecord read and verified and faraday_bip::bsms::signer_record over the BIP-48 or BIP-87 account node's key

Compared with Bitcoin Core v31.1's bitcoind on regtest, offline (deriveaddresses), and its descriptors.py (BIP-380's checksum) and address.py, for each wallet's receive and change scripts and every checksum; btclib-wallet 2026.10.29's BIP-32 (btclib's own curve) for every key, btclib 2026.10.24's SLIP-132 versions and addresses, and its bms for every key record's signature, made, verified and written byte for byte; CPython's json for the value of every JSON file read and for a key named twice and a nesting past 32 refused (those two rules are the reader's own, written beside it); the files are written in the area from each format's documentation, and the meaning of their fields is the area's.

Checked first: Core's release tarball against its pinned SHA-256 before every run; btclib's wheels against the hashes btclib-wallet's lock file names (references.sha256), with libsecp256k1 off; BIP 129's own records and the real files of Sparrow, BlueWallet (Nunchuk's, Coldcard's and Unchained's among them), Coldcard, Caravan and Liana, judged in the prelude.

The wallet's name a file carries; Electrum's encrypted files and BSMS's encrypted records, which Faraday refuses by name; a silent payments record; the kind of a refusal.

Vectors BIP 129's key and descriptor records (tools/vectors/bip129/), and 93 real files from the wallets' own test suites, 62 of them a wallet and 31 refused by both sides (faraday/faraday-core/tests/vectors/interop/: Sparrow's and BlueWallet's; tools/vectors/wallet-files/: Coldcard's firmware tests, Caravan's and Liana's): BSMS records, Coldcard setup files and exports, Caravan, Electrum, Cobo, Keystone, Jade, Specter Desktop and Specter DIY files, descriptors and a Core listdescriptors.

Random cases single-key wallets (P2PKH, P2SH-P2WPKH, P2WPKH, P2TR), sortedmulti in P2WSH, P2SH-P2WSH and P2SH of one to fifteen keys, a miniscript in P2WSH, a taproot tree and a taproot sortedmulti_a, on mainnet and testnet keys, each as a descriptor (multipath with and without checksum, receive and change lines, labelled, receive alone, Core's listdescriptors, Specter Desktop's file, Specter DIY's addwallet with and without its keys' derivations) or as the files that state its kind (Coldcard's export and multisig file, Caravan's, Electrum's, Cobo's, Wasabi's, a key alone, a BSMS descriptor record), in BIP-32's or SLIP-132's spelling; damaged by a wrong checksum, a wrong first address, a SLIP-132 version of another script or another paths line; key records signed by btclib in each header form, with or without damage, and Faraday's own record of random seeds.

Differences Still ours, expected from Faraday's rule: a SLIP-132 version that names another script than the file's (F155), a BSMS paths line other than /0/*,/1/* or No path restrictions, which Faraday reads as the two chains (F64), a BSMS descriptor that is not a template, a key record whose description is over eighty characters or whose token is not BIP 129's; and which account of a Coldcard export, which pair of a listdescriptors, and what each field of every format means, the area's reading of each format's documentation; a checksum in Specter DIY's addwallet, which Specter DIY drops unread and Faraday checks, is refused when Core's code calls it wrong; and the reading of each format's documentation.

Real files both sides refuse, each by a named rule: a Caravan file or an Electrum multisig file whose keys lack a path or a fingerprint, a Caravan quorum that is not the keys listed, a multisig setup file with no policy, a key missing or no format line (Coldcard's own P2SH setup files omit Format, which Faraday refuses), a BSMS record with a paths line other than /0/*,/1/*, a derivation other than /** or <0;1>, a missing line, a first address that is not Core's or not an address, a Coldcard cosigner key file, an Unchained key file and a Coldcard stored setting (a key, not a wallet), and a UR text (area ur). Left out and named: a silent payments record (area sp) and a PSBT or transaction file (areas psbt, tx).

Formats with no published file in a test suite: Nunchuk's own files (only BlueWallet's copies of them), Specter DIY's beyond the one Sparrow keeps, Keystone's beyond Sparrow's, and Core's listdescriptors beyond the one in the interop vectors, whose source is not recorded; Electrum's published test wallets carry a seed and are not taken. Those formats stay the area's own reading (Faraday's second version), as above.

A key record's signature in any of BIP-137's header forms is accepted when it recovers the record's key: btclib is asked with the address that form names (Faraday reads no address from the record).

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 4500 cases

Source

0.2.0 · core/faraday-bip/src/bsms.rs · SignerRecord::verify

0.2.0 · core/faraday-bip/src/bsms.rs · signer_record

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The account node's private key is lent to the signing closure and erased when it returns.

Limits

Encrypted records are refused by name.

A paths line other than /0/*,/1/* or No path restrictions is refused.

A record of a version other than BSMS 1.0 is refused.

Faraday's own calls

Upper-case bech32 and No path restrictions are accepted. Neutral.

no decision

A descriptor record whose paths line is neither /0/*,/1/* nor No path restrictions is refused. Conservative.

no decision

Compile a spending policy

SpecificationBIP 379PublishedCodeLibrary: miniscript 12.3Library: base16ct 1.0 (through core/faraday-crypto)Faraday's code: core/faraday-bipCross-checked withBitcoin Core v31.1 itself (getdescriptorinfoOthers' codeFaraday's second version
Action

Compiles a spending policy to a miniscript descriptor and lists the ways it can be spent.

Specification

BIP 379, Miniscript, Draft

Code

Library: miniscript 12.3.7, by the rust-bitcoin developers (rust-miniscript).

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-bip: The policy is compiled by rust-miniscript for SegWit or Taproot; Faraday reads the result back as a wallet and lists its spend paths.

Checked against

not checked against vectors

core/faraday-bip/src/compile.rs::a_token_stands_for_its_key_where_a_whole_key_is_written

core/faraday-bip/src/compile.rs::a_token_inside_a_longer_word_is_left_alone

core/faraday-bip/tests/all/miniscript.rs::a_threshold_lists_every_combination_that_satisfies_it

no fuzz target: Takes a policy typed in a field; the descriptor it makes is the policy parser's

Cross-check

Compared with others' code: Bitcoin Core v31.1 itself (getdescriptorinfo, deriveaddresses) and its functional-test framework, by Bitcoin Core's contributors; python-bip380, by Antoine Poinsot, for the miniscript's validity, sanity and script; btclib-wallet's descriptors and miniscript, by the btclib developers, on btclib's own curve, for the descriptor's kind, checksum, script at an index and the miniscript's script.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the lift of a miniscript to a boolean formula over its keys and waits, written in area_compile.py from the fragments' meanings (rust-miniscript's own lift is not used), and the rules by which a policy is refused (a threshold of 0 or above its parts, a lock of 0, a key twice, nothing typed), which no outside compiler states.

Area compile

Faraday's code faraday_bip::compile::compile (a concrete policy to a wsh() or tr() descriptor, the keys it names, the ways it can be spent and the script it pays at an index), over rust-miniscript's policy compiler

Compared with Bitcoin Core v31.1's bitcoind on regtest (getdescriptorinfo and deriveaddresses), with its descriptors.py (BIP-380's checksum); btclib-wallet's descriptors and miniscript (btclib/, on btclib's own curve) for the kind, checksum, script at an index and keys; Antoine Poinsot's python-bip380 (miniscript/) for the miniscript's validity, sanity and script, and its fragments for the lift to a formula, which is ours (lift, in area_compile.py).

Checked first: Its vendored files are hashed against references.sha256 before any run; Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked; the self-test makes Faraday's descriptor wrong and the lift wrong, and each is caught.

The script itself: no other compiler makes rust-miniscript's choice, so only that it is valid, sane and means the policy is judged; hash locks, locks in seconds and the time flag of older, which the corpus does not generate; a policy that names a key by a fingerprint token of a loaded key; policies of more than six keys.

Vectors none: no compiler states a script for a policy (rust-miniscript, sipa's and the Go and Python ones choose differently), so the answers are judged by what the descriptor is and means.

Random cases Policies of and, or (with weights), thresh, pk, after and older of one to six keys, each key written as an account key with its origin, compiled for wsh() and for tr() (a key beside the rest, which the compiler takes as the internal key), on mainnet and testnet keys, read at random indices of both chains; refusals: a threshold of 0 or above its parts, a lock of 0, a key twice, nothing typed.

Differences A single key as a tr() policy: rust-miniscript's compile_tr takes the key as the internal key, is left with no leaf and refuses it (Empty Miniscript compilation); Faraday refuses it too, in its own words, and the area counts the refusal. python-bip380 writes a v: over a multi_a, at any depth, as OP_NUMEQUAL OP_VERIFY where BIP 379 and Core write OP_NUMEQUALVERIFY, so such a leaf must equal btclib's script but for that (counted); the output key, which commits to the leaf, is Core's and btclib's. python-bip380 types and_b's e as f_X s_X f_Y s_Y where BIP 379 has e_X e_Y s_X s_Y, so it calls thresh(1,X,a:and_b(pk(A),s:pk(B))) malleable where BIP 379, Core and btclib call it sane. Its thresh leaves the first part out of e, s and m, so it never calls a thresh expressive and calls an or_c over one malleable, where the same three call it sane. Its 0 is not s where BIP 379's is, so l:X and u:X lose X's s. Such a miniscript is asked of python-bip380 again with those three rules as BIP 379's, must be sane then and is counted; any other reason python-bip380 gives stops the area. Its thresh of 1 never sets its lock fields, so reading one inside a thresh of 2 or more raises a TypeError, where BIP 379, Core and btclib read it. Such a miniscript is read again with those fields set from its parts, as Core keeps them, and is counted; any other error stops the area.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 3000 cases

Secret handling

none: no secret leaves faraday-keys

Only public text and keys are read; nothing here holds a secret.

Nothing secret is held.

Limits

Only SegWit v0 and Taproot are offered.

Faraday's own calls

The script shape is left to rust-miniscript's compiler. Neutral.

no decision

Aggregate MuSig2 keys

SpecificationBIP 327 · BIP 328 · BIP 390 · 1 morePublishedCodeLibrary: secp256k1 0.29Library: bitcoin 0.32Library: sha2 0.11 (through core/faraday-crypto)1 moreFaraday's code: core/faraday-bipFaraday's own codeCross-checked withBIP-327's reference.pyOthers' code
Action

Aggregates MuSig2 public keys (BIP 327), publishes the aggregate as an extended public key (BIP 328) and reads the musig() expression of a wallet (BIP 390).

Specification

BIP 327, MuSig2 for BIP340-compatible Multi-Signatures, Deployed

BIP 328, Derivation Scheme for MuSig2 Aggregate Keys, Complete

BIP 390, musig() Descriptor Key Expression, Draft, vendored

BIP 341, Taproot: SegWit version 1 spending rules, Deployed

Code

Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-bip: Written here over libsecp256k1's point and scalar operations; keys inside a musig() are sorted after derivation and before aggregation as BIP 390 requires, while key_agg itself sorts nothing.

Written by Faraday

BIP-327 MuSig2, with BIP-328 and BIP-390 (faraday-bip::musig) · No established implementation exists

libsecp256k1's MuSig2 is in rust-secp256k1 0.32 and later; bitcoin 0.32, which Faraday uses, is on 0.29, and no miniscript release builds on bitcoin 0.33 yet.

Decision F178

A 32-byte hash reduced modulo the curve order, without a branch (faraday-bip::musig) · Only the part used is written

libsecp256k1's Rust bindings take a scalar only below the order and offer no reduction; Faraday's is a single conditional subtraction.

Decision F178

Checked against

tools/vectors/bip327

Published, by BIP 327's authors (bitcoin/bips).

tools/vectors/bip328

Published, by BIP 328's authors (bitcoin/bips).

tools/vectors/bip390

Published, by BIP 390's authors (bitcoin/bips).

core/faraday-bip/tests/all/musig.rs::bip327_key_agg_vectors

core/faraday-bip/tests/all/musig.rs::bip327_key_agg_error_vectors

core/faraday-bip/tests/all/musig.rs::bip327_key_sort_vectors

core/faraday-bip/tests/all/musig.rs::bip328_synthetic_xpub_vectors

core/faraday-bip/tests/all/musig.rs::bip390_descriptors_produce_their_scripts

core/faraday-bip/tests/all/musig.rs::bip390_refuses_what_it_cannot_build

core/faraday-bip/tests/all/musig.rs::a_nested_or_lone_musig_is_refused

core/faraday-bip/tests/all/musig.rs::a_tweak_out_of_range_is_refused

fuzz policy

Cross-check

Compared with others' code: BIP-327's reference.py, by the BIP's authors, and btclib's MuSig2 (ecc.ecc.musig2), by the btclib developers, on its own curve, for key aggregation, tweaks and the aggregate signature; Bitcoin Core v31.1's musig() descriptors through deriveaddresses, by the Bitcoin Core developers, Core's musig module is libsecp256k1's, as Faraday's point operations are, so it judges BIP-390's descriptors and addresses, not the curve maths.

Area musig

Faraday's code faraday_bip::musig

Compared with BIP-327's reference.py (bip327/); btclib's MuSig2 (btclib/, its own curve) in full, answering every operation beside it and verifying the aggregate signature as BIP-340; btclib-wallet's BIP-373 roles over the Core round trip's PSBTs; Bitcoin Core v31.1 (deriveaddresses) for musig() descriptors.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday.

Vectors All eight files of tools/vectors/bip327/; the valid and invalid descriptors of tools/vectors/bip390/ (Core).

Random cases Sessions of 1 to 3 signers: key sort and aggregation, tweaks, nonces, partial signatures, their verification (and a tampered one), aggregation checked as BIP-340, deterministic signing; tr(musig(…)) wallets of 2 to 4 keys, as xpubs on both chains or as plain keys, whose scripts Core pays too.

Differences None known.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 320 cases

Source

0.2.0 · core/faraday-bip/src/musig.rs · key_agg

0.2.0 · core/faraday-bip/src/musig.rs · aggregate_xpub

0.2.0 · core/faraday-bip/src/musig.rs · parse_tr_musig

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

Only public keys are used; nothing here holds a secret.

Nothing secret is held.

Limits

A nested musig() or one with fewer than two participants is refused.

Key path only: script-path spends are refused; no WIF participant, no tap tree.

Faraday's own calls

Script-path spends of a musig() wallet are refused; only the key path is built. Conservative, F155.

A musig() wallet two of whose keys have one master fingerprint is refused at registration: the MuSig2 check matches one participant to each master fingerprint, so a second account of one seed never signs. Conservative.

no decision

Write an xpub spelling

SpecificationSLIP-0132 · BIP 32PublishedCodeLibrary: bitcoin 0.32Faraday's code: core/faraday-bipCross-checked withbtclib-wallet's slip132 and bip32Others' code
Action

Writes and reads an extended public key in its SLIP-132 spelling, and takes a version only where it agrees with the script and the path around the key.

Specification

SLIP-0132, Registered HD version bytes for BIP-0032, Status not checked

BIP 32, Hierarchical Deterministic Wallets, Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Faraday's code: core/faraday-bip: All ten public versions are read; a key whose version disagrees with the script or the purpose in its path is a mismatch, never converted silently; every key read as text goes through the strict decoder.

Checked against

tools/vectors/bip32

Published, by BIP 32's authors (bitcoin/bips).

core/faraday-bip/tests/all/slip132.rs::every_version_decodes_to_the_account_key_it_names

core/faraday-bip/tests/all/slip132.rs::a_version_that_disagrees_with_its_path_or_script_is_a_mismatch

core/faraday-bip/tests/all/accounts.rs::slip132_round_trip_all_types_and_networks

core/faraday-bip/tests/all/accounts.rs::slip132_decode_errors

core/faraday-bip/tests/all/calculators.rs::one_key_is_shown_in_every_spelling

fuzz xkey

Cross-check

Compared with others' code: btclib-wallet's slip132 and bip32, by the btclib developers.

Area addr

Faraday's code faraday_bip::address::parse, bitcoin's Address::from_script, faraday_bip::account (account xpub, SLIP-132, descriptor, addresses), faraday_bip::descriptor's checksum, faraday_bip::policy::WalletPolicy::from_descriptor (an account descriptor's kind, text and script at an index)

Compared with Bitcoin Core's functional-test framework (core/): segwit_addr.py, Base58Check, descriptors.py; BIP 380's own checksum code as the BIP prints it (bip380/); btclib-wallet's bip32 and slip132 (btclib/, on btclib's own curve) for accounts' keys, and its descriptors (descriptors) for each account descriptor's kind, text, script at an index and checksum, and as a third checksum judge; Bitcoin Core v31.1's bitcoind on regtest for every account's address (deriveaddresses) and for reading Faraday's regtest descriptors (getdescriptorinfo).

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; every descriptor checksum is also asked of BIP 380's own code, as the BIP prints it, and of btclib's; Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked.

Vectors BIP-350's and BIP-173's addresses, BIP-380's checksum cases, BIP-49's, 84's and 86's accounts (tools/vectors/addresses/).

Random cases Scripts of every address kind on every network, written and read back, then changed; accounts of every type at random indices, their descriptors read and changed; random descriptors' checksums.

Differences A descriptor with a second # in its body: Faraday and btclib refuse it, as Bitcoin Core's parser does, where BIP 380's code and Core's framework check the last nine characters; its checksum is asked of btclib only. btclib reads descriptors Faraday takes for no account (pk, combo, multi, addr, raw) and other chains than <0;1>; the area asks it for the four account descriptors with both chains only.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 40000 cases

Secret handling

none: no secret leaves faraday-keys

Only public keys are read; nothing here holds a secret.

Nothing secret is held.

Limits

A key whose version disagrees with its script is refused.

Faraday's own calls

A SLIP-132 version is checked against the script and the path around the key. Conservative, F155.

Read an address

SpecificationBIP 173 · BIP 350 · Base58CheckPublishedCodeLibrary: bitcoin 0.32Faraday's code: core/faraday-bipCross-checked withBitcoin Core's functional-test frameworkOthers' code
Action

Reads an address typed or scanned, and says whether the text so far can still become an address on a network.

Specification

BIP 173, Base32 address format for native v0-16 witness outputs, Deployed

BIP 350, Bech32m Format for v1+ Witness Addresses, Deployed

Base58Check, Base58Check encoding, as Bitcoin Core writes it, Convention

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Faraday's code: core/faraday-bip: An address of another network is told apart from an invalid one, and a silent payment address is told apart from both. A scanned address is told apart as one of a loaded wallet's first 100 receive or change addresses, one of another network, or text of at least 26 characters with an address's prefix that does not parse.

Checked against

tools/vectors/addresses

Published, by the authors of BIP 173, BIP 350, BIP 380, BIP 49, BIP 84 and BIP 86 (bitcoin/bips).

core/faraday-bip/tests/all/silent.rs::text_that_begins_with_other_scripts_is_not_an_address

fuzz encodings

Cross-check

Compared with others' code: Bitcoin Core's functional-test framework, v31.1, by Bitcoin Core's contributors.

Area addr

Faraday's code faraday_bip::address::parse, bitcoin's Address::from_script, faraday_bip::account (account xpub, SLIP-132, descriptor, addresses), faraday_bip::descriptor's checksum, faraday_bip::policy::WalletPolicy::from_descriptor (an account descriptor's kind, text and script at an index)

Compared with Bitcoin Core's functional-test framework (core/): segwit_addr.py, Base58Check, descriptors.py; BIP 380's own checksum code as the BIP prints it (bip380/); btclib-wallet's bip32 and slip132 (btclib/, on btclib's own curve) for accounts' keys, and its descriptors (descriptors) for each account descriptor's kind, text, script at an index and checksum, and as a third checksum judge; Bitcoin Core v31.1's bitcoind on regtest for every account's address (deriveaddresses) and for reading Faraday's regtest descriptors (getdescriptorinfo).

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; every descriptor checksum is also asked of BIP 380's own code, as the BIP prints it, and of btclib's; Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked.

Vectors BIP-350's and BIP-173's addresses, BIP-380's checksum cases, BIP-49's, 84's and 86's accounts (tools/vectors/addresses/).

Random cases Scripts of every address kind on every network, written and read back, then changed; accounts of every type at random indices, their descriptors read and changed; random descriptors' checksums.

Differences A descriptor with a second # in its body: Faraday and btclib refuse it, as Bitcoin Core's parser does, where BIP 380's code and Core's framework check the last nine characters; its checksum is asked of btclib only. btclib reads descriptors Faraday takes for no account (pk, combo, multi, addr, raw) and other chains than <0;1>; the area asks it for the four account descriptors with both chains only.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 40000 cases

Secret handling

none: no secret leaves faraday-keys

Only public text is read; nothing here holds a secret.

Nothing secret is held.

Limits

An address of another network is refused.

A scanned address is looked for among 100 addresses on each chain of each loaded wallet.

Faraday's own calls

none

Randomness

12 actions · 9 own specification · 2 with Faraday's own code · 2 cross-checked with others' code · 10 with Faraday's second version · 2 not cross-checked

Turn dice into entropy

SpecificationDice hashing of Coldcard and SeedSignerPublishedCodeLibrary: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-entropyFaraday's own codeCross-checked withColdcard's rolls.py and rolls12.py (public domain)Others' codeFaraday's second version
Action

Turns dice rolls into entropy by one of three published procedures, and cautions about runs, sequences and skew.

Specification

Dice hashing of Coldcard and SeedSigner, Coldcard rolls.py, SeedSigner, EntropyLab, Keystone and BitBox dice procedures, Convention

Code

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-entropy: Hashed rolls are SHA-256 of the rolls as ASCII digits, truncated to the strength; the second procedure writes every 6 as 0 first; the third names every word from five rolls of 1 to 4 and a sixth read as a coin, and the checksum replaces the last word's low bits.

Written by Faraday

Dice, coin, card, hex and camera entropy accumulation and packing, and the mix of sources (faraday-entropy) · Faraday's own specification

Faraday's own procedures over SHA-256; the card, camera and mix procedures are labelled as not yet reviewed outside Faraday.

Decision F178

Checked against

tools/vectors/entropy

Computed by Coldcard's rolls.py and EntropyLab, run as tools/reference/dice/README.md records.

core/faraday-entropy/src/dice.rs::dice_entropy_is_sha256_of_the_ascii_rolls

core/faraday-entropy/src/dice.rs::six_as_zero_hashes_the_rolls_with_every_six_written_as_a_zero

core/faraday-entropy/src/dice.rs::direct_selection_names_a_word_from_five_faces_and_a_coin

core/faraday-entropy/src/dice.rs::direct_selection_rolls_the_last_word_and_keeps_its_high_bits

faraday/faraday-core/tests/all/keygen.rs::ninety_nine_rolls_make_the_key_coldcard_and_seedsigner_make

faraday/faraday-core/tests/all/keygen.rs::too_few_rolls_make_no_words

no fuzz target: Takes single key presses from a pad, one die face at a time; no text is parsed

Cross-check

Compared with others' code: Coldcard's rolls.py and rolls12.py (public domain), run for the hashed procedure and every rolls commitment; SeedSigner's mnemonic_generation.py (MIT) over embit's BIP-39, run for the hashed procedure at 50 and 99 rolls and for direct selection's entropy, read back from its completed words, at every length.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: EntropyLab's six-as-zero and direct word selection (JavaScript, which needs Node, written out in area_entropy.py from tools/reference/dice/README.md; the wordlist indices from faces are Faraday's rule, SeedSigner has no dice selection), the cut of Coldcard's digest to 20, 24 and 28 bytes, and the roll counts and refused faces.

Area entropy

Faraday's code faraday_entropy: dice under the three procedures, coins, hex, cards, camera frames, the device's answer, a mix

Compared with The procedures written out in area_entropy.py over hashlib, from tools/reference/entropy/README.md and the dice sources quoted in tools/reference/dice/README.md, except that the hashed dice procedure and every rolls commitment are Coldcard's own rolls.py and rolls12.py (tools/reference/coldcard-rolls/, run, public domain) and hex digits become bytes through CPython's bytes.fromhex; SeedSigner's mnemonic_generation.py (tools/reference/seedsigner/) over embit's BIP-39 (tools/reference/embit/) reads the hashed procedure at 50 and 99 rolls and direct selection's last word back.

Checked first: The hashed dice procedure is Coldcard's own scripts run, their files hashed against references.sha256 before any run; SeedSigner's and embit's files are hashed the same way and their functions run; the rest is written in the area over hashlib from the statements of tools/reference/entropy/README.md and tools/reference/dice/README.md, and the published dice answers are required of them as well as of Faraday.

Vectors Coldcard's rolls.py digest, EntropyLab's six-as-zero and direct word selection (tools/vectors/entropy/).

Random cases Runs of every source at every strength, short of the count, at it and past it, with faces, cards, frames and characters the pads refuse and every source past its limit; mixes of one to six sources given by their inputs.

Differences SeedSigner's generate_mnemonic_from_dice cuts to 16 bytes only at exactly 50 rolls and takes every other count as 32 bytes, and its calculate_checksum completes 12 and 24 words only: SeedSigner judges the hashed procedure at 50 and 99 rolls and direct selection's last word at 12 and 24 words (at 15, 18 and 21 embit's checksum through generate_mnemonic_from_bytes), compared as the entropy embit reads back from those words, the checksum itself being area bip39's; it has no six-as-zero, no cut to 20, 24 or 28 bytes, and its dice take no direct selection, which stay the area's own.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Source

0.2.0 · core/faraday-entropy/src/dice.rs · DiceRolls::entropy

0.2.0 · core/faraday-entropy/src/dice.rs · DiceRolls::entropy_under

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The accumulator is a fixed buffer erased when it is dropped; the entropy it makes is a RawEntropy that is wiped when dropped.

Limits

Fewer rolls than the strength needs make no key.

Direct selection rerolls a 5 or a 6 in a word's first five positions.

At most 200 rolls are held.

Faraday's own calls

Cautions about runs and skew are warnings only. Neutral.

no decision

99 rolls give 256 bits, as the other tools accept. Neutral.

no decision

Pack coins and hex

SpecificationOwn specificationCodeLibrary: sha2 0.11 (through core/faraday-crypto)Library: base16ct 1.0 (through core/faraday-crypto)Faraday's code: core/faraday-entropyCross-checked withCPython's bytes.fromhexOthers' codeFaraday's second version
Action

Packs coin flips into entropy most significant bit first, and takes hexadecimal digits as they are.

Specification

Own specification (no decision)

Code

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-entropy: Each flip is one bit, packed most significant bit first without hashing; hex is two digits a byte, 32 to 64 digits, taken as they are; the commitment is a separate SHA-256 of what went in.

Checked against

tools/vectors/entropy

Computed by Coldcard's rolls.py and EntropyLab, run as tools/reference/dice/README.md records.

core/faraday-entropy/src/coins.rs::coins_pack_msb_first_without_hashing

core/faraday-entropy/src/hex.rs::hex_parsing

faraday/faraday-core/tests/all/keygen.rs::one_hundred_twenty_eight_flips_are_a_twelve_word_key_bit_for_bit

no fuzz target: Takes single flips and digits from a pad; no outside text is parsed beyond hex digits

Cross-check

Compared with others' code: CPython's bytes.fromhex, by the CPython developers, for hex digits read as bytes, against base16ct in Faraday.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the packing of flips, the commitments, and which characters and how many digits hex takes, written out in area_entropy.py.

Area entropy

Faraday's code faraday_entropy: dice under the three procedures, coins, hex, cards, camera frames, the device's answer, a mix

Compared with The procedures written out in area_entropy.py over hashlib, from tools/reference/entropy/README.md and the dice sources quoted in tools/reference/dice/README.md, except that the hashed dice procedure and every rolls commitment are Coldcard's own rolls.py and rolls12.py (tools/reference/coldcard-rolls/, run, public domain) and hex digits become bytes through CPython's bytes.fromhex; SeedSigner's mnemonic_generation.py (tools/reference/seedsigner/) over embit's BIP-39 (tools/reference/embit/) reads the hashed procedure at 50 and 99 rolls and direct selection's last word back.

Checked first: The hashed dice procedure is Coldcard's own scripts run, their files hashed against references.sha256 before any run; SeedSigner's and embit's files are hashed the same way and their functions run; the rest is written in the area over hashlib from the statements of tools/reference/entropy/README.md and tools/reference/dice/README.md, and the published dice answers are required of them as well as of Faraday.

Vectors Coldcard's rolls.py digest, EntropyLab's six-as-zero and direct word selection (tools/vectors/entropy/).

Random cases Runs of every source at every strength, short of the count, at it and past it, with faces, cards, frames and characters the pads refuse and every source past its limit; mixes of one to six sources given by their inputs.

Differences SeedSigner's generate_mnemonic_from_dice cuts to 16 bytes only at exactly 50 rolls and takes every other count as 32 bytes, and its calculate_checksum completes 12 and 24 words only: SeedSigner judges the hashed procedure at 50 and 99 rolls and direct selection's last word at 12 and 24 words (at 15, 18 and 21 embit's checksum through generate_mnemonic_from_bytes), compared as the entropy embit reads back from those words, the checksum itself being area bip39's; it has no six-as-zero, no cut to 20, 24 or 28 bytes, and its dice take no direct selection, which stay the area's own.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Source

0.2.0 · core/faraday-entropy/src/coins.rs · CoinFlips::entropy

0.2.0 · core/faraday-entropy/src/hex.rs · RawHex::entropy

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The accumulator is a fixed buffer erased when it is dropped; the entropy it makes is a RawEntropy that is wiped when dropped.

Limits

Coins: 128, 160, 192, 224 or 256 flips; hex: 32, 40, 48, 56 or 64 digits.

A character that is not a hex digit is refused.

Faraday's own calls

Coins and hex are packed or taken as typed, with no hashing. Neutral.

no decision

Turn cards into entropy

SpecificationOwn specificationCodeLibrary: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-entropyCross-checked withFaraday's second version
Action

Turns playing-card draws into entropy as SHA-256 of the draws' indices, one byte each.

Specification

Own specification (F158)

Code

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-entropy: A deck tracker refuses a card already out, so each draw is worth log2 of the cards left; 25, 31, 39, 50 and 58 draws are asked for, the last more than one deck holds.

Checked against

tools/vectors/cards

Faraday's own known answers.

tools/vectors/entropy

Computed by Coldcard's rolls.py and EntropyLab, run as tools/reference/dice/README.md records.

core/faraday-entropy/src/cards.rs::cards_hash_their_indices_and_count_the_deck_down

core/faraday-entropy/src/cards.rs::cards_reach_160_bits_at_the_thirty_first_draw

core/faraday-entropy/src/cards.rs::the_deck_tracker_refuses_a_card_already_out

core/faraday-entropy/src/cards.rs::twenty_four_words_from_cards_asks_for_a_second_deck

core/faraday-entropy/src/cards.rs::a_deck_in_new_deck_order_is_cautioned

faraday/faraday-core/tests/all/keygen.rs::cards_in_the_order_of_a_new_deck_are_cautioned_and_do_not_stop_the_key

no fuzz target: Takes single cards from a pad; no text is parsed

Cross-check

Own specification, not yet reviewed outside Faraday.

An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.

Compared with Faraday's second version, written by Faraday's authors in Python from the specification. Not checked against an outside source.

What it covers: the card procedure, written out in area_entropy.py.

Area entropy

Faraday's code faraday_entropy: dice under the three procedures, coins, hex, cards, camera frames, the device's answer, a mix

Compared with The procedures written out in area_entropy.py over hashlib, from tools/reference/entropy/README.md and the dice sources quoted in tools/reference/dice/README.md, except that the hashed dice procedure and every rolls commitment are Coldcard's own rolls.py and rolls12.py (tools/reference/coldcard-rolls/, run, public domain) and hex digits become bytes through CPython's bytes.fromhex; SeedSigner's mnemonic_generation.py (tools/reference/seedsigner/) over embit's BIP-39 (tools/reference/embit/) reads the hashed procedure at 50 and 99 rolls and direct selection's last word back.

Checked first: The hashed dice procedure is Coldcard's own scripts run, their files hashed against references.sha256 before any run; SeedSigner's and embit's files are hashed the same way and their functions run; the rest is written in the area over hashlib from the statements of tools/reference/entropy/README.md and tools/reference/dice/README.md, and the published dice answers are required of them as well as of Faraday.

Vectors Coldcard's rolls.py digest, EntropyLab's six-as-zero and direct word selection (tools/vectors/entropy/).

Random cases Runs of every source at every strength, short of the count, at it and past it, with faces, cards, frames and characters the pads refuse and every source past its limit; mixes of one to six sources given by their inputs.

Differences SeedSigner's generate_mnemonic_from_dice cuts to 16 bytes only at exactly 50 rolls and takes every other count as 32 bytes, and its calculate_checksum completes 12 and 24 words only: SeedSigner judges the hashed procedure at 50 and 99 rolls and direct selection's last word at 12 and 24 words (at 15, 18 and 21 embit's checksum through generate_mnemonic_from_bytes), compared as the entropy embit reads back from those words, the checksum itself being area bip39's; it has no six-as-zero, no cut to 20, 24 or 28 bytes, and its dice take no direct selection, which stay the area's own.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The accumulator is a fixed buffer erased when it is dropped; the entropy it makes is a RawEntropy that is wiped when dropped.

Limits

A card already out of its deck is refused.

At most two decks (104 cards) are held.

Five cards in a row in the deck's own order, up or down, are cautioned, not refused.

Faraday's own calls

The procedure is Faraday's own: a card is the index suit × 13 + rank, and the entropy is SHA-256 of those one-byte indices; no other wallet's card mode is claimed to match, and the bits counted assume a well-shuffled deck. Novel, F158.

Turn the camera into entropy

SpecificationOwn specificationCodeLibrary: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-entropyCross-checked withFaraday's second version
Action

Commits to camera frames as SHA-256 over the frames' SHA-256 digests, for a mix or the session's randomness, never a key alone.

Specification

Own specification (F158)

Code

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-entropy: A frame is taken only if it has at least 32 distinct luma values and its SHA-256 is not one already taken; three frames are asked for per 128 bits, rounded up, as a guard against a still scene rather than an entropy calculation.

Checked against

tools/vectors/camera

Faraday's own known answers.

tools/vectors/entropy

Computed by Coldcard's rolls.py and EntropyLab, run as tools/reference/dice/README.md records.

core/faraday-entropy/src/camera.rs::a_covered_lens_is_refused_and_frames_hash_in_order

core/faraday-entropy/src/camera.rs::a_frame_already_taken_is_refused

faraday/faraday-core/tests/all/keygen.rs::a_camera_frame_already_taken_is_refused

faraday/faraday-core/tests/all/keygen.rs::the_camera_is_offered_only_among_a_mixs_sources

fuzz v4l2_luma

Cross-check

Own specification, not yet reviewed outside Faraday.

An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.

Compared with Faraday's second version, written by Faraday's authors in Python from the specification. Not checked against an outside source.

What it covers: the frames' commitment, written out in area_entropy.py.

Area entropy

Faraday's code faraday_entropy: dice under the three procedures, coins, hex, cards, camera frames, the device's answer, a mix

Compared with The procedures written out in area_entropy.py over hashlib, from tools/reference/entropy/README.md and the dice sources quoted in tools/reference/dice/README.md, except that the hashed dice procedure and every rolls commitment are Coldcard's own rolls.py and rolls12.py (tools/reference/coldcard-rolls/, run, public domain) and hex digits become bytes through CPython's bytes.fromhex; SeedSigner's mnemonic_generation.py (tools/reference/seedsigner/) over embit's BIP-39 (tools/reference/embit/) reads the hashed procedure at 50 and 99 rolls and direct selection's last word back.

Checked first: The hashed dice procedure is Coldcard's own scripts run, their files hashed against references.sha256 before any run; SeedSigner's and embit's files are hashed the same way and their functions run; the rest is written in the area over hashlib from the statements of tools/reference/entropy/README.md and tools/reference/dice/README.md, and the published dice answers are required of them as well as of Faraday.

Vectors Coldcard's rolls.py digest, EntropyLab's six-as-zero and direct word selection (tools/vectors/entropy/).

Random cases Runs of every source at every strength, short of the count, at it and past it, with faces, cards, frames and characters the pads refuse and every source past its limit; mixes of one to six sources given by their inputs.

Differences SeedSigner's generate_mnemonic_from_dice cuts to 16 bytes only at exactly 50 rolls and takes every other count as 32 bytes, and its calculate_checksum completes 12 and 24 words only: SeedSigner judges the hashed procedure at 50 and 99 rolls and direct selection's last word at 12 and 24 words (at 15, 18 and 21 embit's checksum through generate_mnemonic_from_bytes), compared as the entropy embit reads back from those words, the checksum itself being area bip39's; it has no six-as-zero, no cut to 20, 24 or 28 bytes, and its dice take no direct selection, which stay the area's own.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The accumulator is a fixed buffer erased when it is dropped; the entropy it makes is a RawEntropy that is wiped when dropped.

Limits

A frame of fewer than 32 distinct values is refused.

A frame whose SHA-256 was already taken is refused.

At most 8 frames are held.

Never a key's only source: a mix's member, or added to the session's randomness.

Faraday's own calls

The procedure is Faraday's own, and three frames per 128 bits is a heuristic; the frames only add to a mix or to the system's randomness, never make a key alone. Novel, F158.

Record pointer and keys

SpecificationOwn specificationCodeLibrary: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-entropyCross-checked withFaraday's second version
Action

Records pointer moves and key presses with time and a running count, and commits them in batches of SHA-256 for the session's randomness.

Specification

Own specification (F86)

Code

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-entropy: Each event is a 17-byte record of its kind, a running count, the time and its position or key code; a batch of at most 64 is committed as SHA-256 of the domain and its records and then wiped, and the count goes on across batches.

Checked against

tools/vectors/own-randomness

Faraday's own known answers.

core/faraday-entropy/src/pointer_keys.rs::a_full_batch_asks_to_be_committed_and_the_count_runs_on

faraday/faraday-core/tests/all/own_randomness.rs::the_pointer_and_keys_commitment_and_its_mix_are_the_known_answers

faraday/faraday-core/tests/all/own_randomness.rs::sixty_four_events_are_added_as_a_batch_and_the_rest_as_the_page_goes

no fuzz target: Takes single events from the shell; no text is parsed

Cross-check

Own specification, not yet reviewed outside Faraday.

An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.

Compared with Faraday's second version, written by Faraday's authors in Python from the specification. Not checked against an outside source.

What it covers: docs/OWN-RANDOMNESS.md §2.1 and §2.3, written out in area_own.py.

Area own-randomness

Faraday's code faraday_core's fresh.rs (Own, the session seed and pool) through the testkit's fresh and seed_draw, with faraday_entropy's dice, coin, camera and pointer-and-keys commitments

Compared with docs/OWN-RANDOMNESS.md §2.1 and §2.3 written out in area_own.py over hashlib.

Checked first: The second implementation is written in the area from docs/OWN-RANDOMNESS.md §2.3 over hashlib, and the known answers of faraday/faraday-core/tests/all/own_randomness.rs are required of it as well as of Faraday.

Vectors The known answers of faraday/faraday-core/tests/all/own_randomness.rs: nothing added, dice before and after the system's answers, dice then coins, a batch of pointer moves and keys, a lock.

Random cases Random sessions of system answers, dice, coins, camera frames (some refused, some empty) and pointer moves and keys (none to several batches), locks, seed draws, fresh bytes and counts, in any order.

Differences None known.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 4000 cases

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

A batch's records are zeroized as soon as it is committed.

Limits

Offered only where the shell has a pointer and keys (the desktop app).

Faraday's own calls

Pointer and key timings are added to the session's randomness, never made into a key on their own. Novel, F86.

Mix entropy sources

SpecificationOwn specificationCodeLibrary: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-entropyCross-checked withFaraday's second version
Action

Combines two to five sources, dice or this device among them, by hashing their commitments in the order taken.

Specification

Own specification (F158)

Code

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-entropy: The entropy is SHA-256 over the sources' 32-byte commitments, concatenated in the order taken and truncated to the strength; the same commitments in the same order always give the same key, so they can be written down before the words appear.

Checked against

tools/vectors/entropy

Computed by Coldcard's rolls.py and EntropyLab, run as tools/reference/dice/README.md records.

tools/vectors/mix

Faraday's own known answers.

core/faraday-entropy/src/mix.rs::a_mix_commits_to_its_sources_and_hashes_the_commitments

faraday/faraday-core/tests/all/keygen.rs::a_mix_of_dice_and_coins_is_the_hash_of_both_commitments

faraday/faraday-core/tests/all/keygen.rs::a_mix_without_dice_or_this_device_is_refused

no fuzz target: Takes 32-byte commitments from sources already entered

Cross-check

Own specification, not yet reviewed outside Faraday.

An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.

Compared with Faraday's second version, written by Faraday's authors in Python from the specification. Not checked against an outside source.

What it covers: the mix of commitments, written out in area_entropy.py.

Area entropy

Faraday's code faraday_entropy: dice under the three procedures, coins, hex, cards, camera frames, the device's answer, a mix

Compared with The procedures written out in area_entropy.py over hashlib, from tools/reference/entropy/README.md and the dice sources quoted in tools/reference/dice/README.md, except that the hashed dice procedure and every rolls commitment are Coldcard's own rolls.py and rolls12.py (tools/reference/coldcard-rolls/, run, public domain) and hex digits become bytes through CPython's bytes.fromhex; SeedSigner's mnemonic_generation.py (tools/reference/seedsigner/) over embit's BIP-39 (tools/reference/embit/) reads the hashed procedure at 50 and 99 rolls and direct selection's last word back.

Checked first: The hashed dice procedure is Coldcard's own scripts run, their files hashed against references.sha256 before any run; SeedSigner's and embit's files are hashed the same way and their functions run; the rest is written in the area over hashlib from the statements of tools/reference/entropy/README.md and tools/reference/dice/README.md, and the published dice answers are required of them as well as of Faraday.

Vectors Coldcard's rolls.py digest, EntropyLab's six-as-zero and direct word selection (tools/vectors/entropy/).

Random cases Runs of every source at every strength, short of the count, at it and past it, with faces, cards, frames and characters the pads refuse and every source past its limit; mixes of one to six sources given by their inputs.

Differences SeedSigner's generate_mnemonic_from_dice cuts to 16 bytes only at exactly 50 rolls and takes every other count as 32 bytes, and its calculate_checksum completes 12 and 24 words only: SeedSigner judges the hashed procedure at 50 and 99 rolls and direct selection's last word at 12 and 24 words (at 15, 18 and 21 embit's checksum through generate_mnemonic_from_bytes), compared as the entropy embit reads back from those words, the checksum itself being area bip39's; it has no six-as-zero, no cut to 20, 24 or 28 bytes, and its dice take no direct selection, which stay the area's own.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The accumulator is a fixed buffer erased when it is dropped; the entropy it makes is a RawEntropy that is wiped when dropped.

Limits

Fewer than two sources make no entropy; at most five are held.

A mix without dice or this device among its sources makes no key.

Faraday's own calls

The specification is Faraday's own: SHA-256 over the concatenated commitments. With dice or this device among the sources, each at its full count, it only adds to that member's strength. Novel, F158.

Take the device's entropy

SpecificationOwn specificationCodeLibrary: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-entropyCross-checked withFaraday's second version
Action

Hashes the 32 bytes the shell answered the entropy request with into a key's entropy.

Specification

Own specification (no decision)

Code

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-entropy: The entropy is SHA-256 of the 32 bytes, truncated to the strength, so the key is not the shell's bytes themselves; the source trusts the device. Where the person added randomness of their own, the hash is over a label, the 32 bytes and the accumulator of what was added, so someone who lacks either part cannot predict the key.

Checked against

tools/vectors/entropy

Computed by Coldcard's rolls.py and EntropyLab, run as tools/reference/dice/README.md records.

core/faraday-entropy/src/device.rs::the_device_answers_differently_every_time_and_hashes_what_it_answered

faraday/faraday-core/tests/all/keygen.rs::this_devices_key_is_its_generators_fresh_answer_hashed_and_nothing_else

no fuzz target: Takes one 32-byte answer from the shell

Cross-check

Compared with Faraday's second version, written by Faraday's authors in Python from the specification. Not checked against an outside source.

What it covers: the hash of the shell's answer, written out in area_entropy.py; with what the person added, as area_own.py writes it.

Area entropy

Faraday's code faraday_entropy: dice under the three procedures, coins, hex, cards, camera frames, the device's answer, a mix

Compared with The procedures written out in area_entropy.py over hashlib, from tools/reference/entropy/README.md and the dice sources quoted in tools/reference/dice/README.md, except that the hashed dice procedure and every rolls commitment are Coldcard's own rolls.py and rolls12.py (tools/reference/coldcard-rolls/, run, public domain) and hex digits become bytes through CPython's bytes.fromhex; SeedSigner's mnemonic_generation.py (tools/reference/seedsigner/) over embit's BIP-39 (tools/reference/embit/) reads the hashed procedure at 50 and 99 rolls and direct selection's last word back.

Checked first: The hashed dice procedure is Coldcard's own scripts run, their files hashed against references.sha256 before any run; SeedSigner's and embit's files are hashed the same way and their functions run; the rest is written in the area over hashlib from the statements of tools/reference/entropy/README.md and tools/reference/dice/README.md, and the published dice answers are required of them as well as of Faraday.

Vectors Coldcard's rolls.py digest, EntropyLab's six-as-zero and direct word selection (tools/vectors/entropy/).

Random cases Runs of every source at every strength, short of the count, at it and past it, with faces, cards, frames and characters the pads refuse and every source past its limit; mixes of one to six sources given by their inputs.

Differences SeedSigner's generate_mnemonic_from_dice cuts to 16 bytes only at exactly 50 rolls and takes every other count as 32 bytes, and its calculate_checksum completes 12 and 24 words only: SeedSigner judges the hashed procedure at 50 and 99 rolls and direct selection's last word at 12 and 24 words (at 15, 18 and 21 embit's checksum through generate_mnemonic_from_bytes), compared as the entropy embit reads back from those words, the checksum itself being area bip39's; it has no six-as-zero, no cut to 20, 24 or 28 bytes, and its dice take no direct selection, which stay the area's own.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The accumulator is a fixed buffer erased when it is dropped; the entropy it makes is a RawEntropy that is wiped when dropped.

Limits

Nothing is made before the shell has answered.

Faraday's own calls

The source trusts the device's generator. Neutral.

no decision

Read the system's randomness

SpecificationOwn specificationCodeLibrary: getrandom 0.3 and 0.4Faraday's code: faraday/shells/windowCross-checked withNot cross-checked
Action

Reads 32 bytes from the system's generator for the desktop app and the Starter, and names the source.

Specification

Own specification (F102, F86)

Code

Library: getrandom 0.3.4 and 0.4.3, by the Rand Project developers.

Faraday's code: faraday/shells/window: The bytes come from getrandom(2), ProcessPrng, getentropy(2) or crypto.getRandomValues according to the platform; when the system gives none, nothing is answered.

Checked against

not checked against vectors

faraday/faraday-core/tests/all/keygen.rs::this_device_names_the_source_the_shell_reads

no fuzz target: Takes no input

Cross-check

not cross-checked: The bytes are the operating system's; there is nothing to compare them with

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The bytes are placed in a buffer that wipes them when dropped; the local array they were read into is not wiped.

Limits

Nothing is made from a generator that did not answer.

Faraday's own calls

The stick and the Pi read /dev/random; the Pi's generator is mixed, not credited. Conservative, F102.

The stick's kernel credits neither the CPU's RDRAND nor the firmware's seed; both are still mixed in. Conservative, F86.

Keep the session's randomness

SpecificationOwn specificationCodeLibrary: bitcoin_hashes 0.14Faraday's code: faraday/faraday-coreFaraday's own codeCross-checked withFaraday's second version
Action

Keeps the session's seed and pool from the shell's answers, mixes a person's own randomness in, never in place of the system's, and draws the seed of a MuSig2 round.

Specification

Own specification (F234, F86)

Code

Library: bitcoin_hashes 0.14.101, by the rust-bitcoin developers.

Faraday's code: faraday/faraday-core: The seed is the shell's first answer, hashed with the person's accumulator when there is one and again at each batch added (SHA-256 of a label, the base and the accumulator); the accumulator chains each batch's commitment; a fresh answer is SHA-256 of a label, what it is for, the answer and the accumulator; a signing round's seed is SHA-256 of a label, the session's seed and a count of rounds; nothing is made before the system has answered.

Written by Faraday

The session's random generator: its seed and pool, and the mixing of a person's own randomness (faraday-core::fresh) · Faraday's own specification

Faraday's own procedure over SHA-256, labelled as not yet reviewed outside Faraday.

Decision F178

Checked against

tools/vectors/own-randomness

Faraday's own known answers.

faraday/faraday-core/tests/all/own_randomness.rs::with_nothing_added_the_bytes_are_the_systems_as_before

faraday/faraday-core/tests/all/own_randomness.rs::many_fresh_bytes_are_an_answer_for_every_32

faraday/faraday-core/tests/all/own_randomness.rs::new_keys_this_device_mixes_in_what_was_added_and_says_so

faraday/faraday-core/tests/all/own_randomness.rs::dice_added_are_mixed_into_the_seed_and_the_fresh_bytes_as_defined

faraday/faraday-core/tests/all/own_randomness.rs::a_second_batch_chains_onto_the_first_and_reseeds_again

faraday/faraday-core/tests/all/own_randomness.rs::a_batch_of_nothing_is_not_taken

faraday/faraday-core/tests/all/own_randomness.rs::what_is_added_before_the_system_answers_makes_nothing

faraday/faraday-core/tests/all/own_randomness.rs::a_signing_round_does_not_open_on_what_was_added_alone

faraday/faraday-core/tests/all/own_randomness.rs::a_lock_wipes_what_was_added

no fuzz target: Takes 32-byte answers from the shell

Cross-check

Own specification, not yet reviewed outside Faraday.

An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.

Compared with Faraday's second version, written by Faraday's authors in Python from the specification. Not checked against an outside source.

What it covers: docs/OWN-RANDOMNESS.md §2.1 and §2.3, written out in area_own.py.

Area own-randomness

Faraday's code faraday_core's fresh.rs (Own, the session seed and pool) through the testkit's fresh and seed_draw, with faraday_entropy's dice, coin, camera and pointer-and-keys commitments

Compared with docs/OWN-RANDOMNESS.md §2.1 and §2.3 written out in area_own.py over hashlib.

Checked first: The second implementation is written in the area from docs/OWN-RANDOMNESS.md §2.3 over hashlib, and the known answers of faraday/faraday-core/tests/all/own_randomness.rs are required of it as well as of Faraday.

Vectors The known answers of faraday/faraday-core/tests/all/own_randomness.rs: nothing added, dice before and after the system's answers, dice then coins, a batch of pointer moves and keys, a lock.

Random cases Random sessions of system answers, dice, coins, camera frames (some refused, some empty) and pointer moves and keys (none to several batches), locks, seed draws, fresh bytes and counts, in any order.

Differences None known.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 4000 cases

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The seed, the pool, the accumulator and a drawn signing seed are zeroizing buffers; the lock wipes what was added.

Limits

What a person adds alone makes nothing.

A batch of nothing is refused.

No signing round opens on bytes the system did not give.

Faraday's own calls

Added randomness never replaces the system's bytes. Conservative, F86.

The mixing is Faraday's own specification. Novel, F86.

MuSig2's rand' is HKDF-Expand of the session seed with a draw counter; rounds across a lock are not offered. Neutral, F234.

Read the booklet's dice

SpecificationBooklet dice de-biasingPublishedCodeFaraday's code: core/faraday-entropyCross-checked withFaraday's second version
Action

Reads the codex32 booklet's dice de-biasing worksheet: ten rolls of five dice make one bech32 character.

Specification

Booklet dice de-biasing, codex32 booklet SSS32.ps of 2023-03-07, Dice De-biasing Worksheet, Convention

Code

Faraday's code: core/faraday-entropy: Each die gives one bit by comparing its second value with its first, a die with equal values is rolled twice again, and the five bits walk the booklet's tree to a character; dice of 2 to 20 faces are read by the same comparison.

Checked against

not checked against vectors

core/faraday-entropy/src/booklet.rs::a_character_made_in_the_booklets_order

core/faraday-entropy/src/booklet.rs::all_32_paths_reach_the_booklets_leaf

core/faraday-entropy/src/booklet.rs::a_die_with_equal_values_is_never_read

core/faraday-entropy/src/booklet.rs::a_twenty_faced_die_reads_by_the_same_comparison

no fuzz target: Takes single die faces from a pad

Cross-check

Compared with Faraday's second version, written by Faraday's authors in Python from the specification. Not checked against an outside source.

What it covers: the booklet's dice worksheet, written out in area_roller.py from docs/CODEX32.md §5.5.

Area roller

Faraday's code Faraday Demo's dice rollers (faraday_core's fresh/roller/, through the testkit)

Compared with docs/CODEX32.md §5.6's "The values" and §5.5's worksheet written out in area_roller.py.

Checked first: The second implementation is written in the area from docs/CODEX32.md §5.5 and §5.6 and the booklet's worksheet, and the known answers, the byte distribution and every byte as a face of every die are required of it as well as of Faraday.

Vectors Every byte value as an answer: each face from 42 bytes, the four above 251 skipped; every byte as a face of every die of 2 to 20 faces (faraday_entropy::uniform_face); the booklet's 32 paths on six- and twenty-faced dice and its order with an equal pair (roller.sheet).

Random cases Random answers (some mostly skipped bytes) under clicks of every size into entries of random room, with resets; the five dice of random faces (2 to 20) under clicks of every reach into codex32 shares of random count and length, answers running out part way; rolls of random dice entered by hand, equal pairs among them.

Differences None known.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

Rolls are secret while a character is made; the character's buffer is erased when dropped.

Limits

Faces outside the die's range are refused.

Faraday's own calls

The comparison is the booklet's; reading dice of 2 to 20 faces is an addition. Neutral.

no decision

Roll simulated dice

SpecificationOwn specificationCodeFaraday's code: faraday/faraday-coreCross-checked withFaraday's second version
Action

Rolls simulated dice for Faraday Demo from the session's randomness, one value per byte with no bias.

Specification

Own specification (F96)

Code

Faraday's code: faraday/faraday-core: Each value is one byte of a 32-byte fresh answer taken from the last to the first; a byte among the 256 mod faces highest is skipped so no face is likelier; a new answer is asked for when one is used up.

Checked against

tools/vectors/roller

Faraday's own known answers.

faraday/faraday-core/src/fresh/roller/five_tests.rs::a_character_click_gives_the_character_the_same_faces_typed_give

faraday/faraday-core/src/fresh/roller/five_tests.rs::an_equal_pair_is_rolled_again

faraday/faraday-core/src/fresh/roller/five_tests.rs::twenty_faced_dice_take_a_byte_below_240_as_its_face_plus_one

faraday/faraday-core/tests/all/roller.rs::a_roll_fills_the_rolls_as_the_keys_would

faraday/faraday-core/tests/all/roller.rs::a_device_shell_has_no_roller

faraday/faraday-core/tests/all/roller.rs::rolled_or_typed_demo_puts_faraday_in_place_and_measures_nothing

no fuzz target: Takes 32-byte answers from the session; no text is parsed

Cross-check

Own specification, not yet reviewed outside Faraday.

An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.

Compared with Faraday's second version, written by Faraday's authors in Python from the specification. Not checked against an outside source.

What it covers: Faraday Demo's roller, written out in area_roller.py from docs/CODEX32.md §5.6.

Area roller

Faraday's code Faraday Demo's dice rollers (faraday_core's fresh/roller/, through the testkit)

Compared with docs/CODEX32.md §5.6's "The values" and §5.5's worksheet written out in area_roller.py.

Checked first: The second implementation is written in the area from docs/CODEX32.md §5.5 and §5.6 and the booklet's worksheet, and the known answers, the byte distribution and every byte as a face of every die are required of it as well as of Faraday.

Vectors Every byte value as an answer: each face from 42 bytes, the four above 251 skipped; every byte as a face of every die of 2 to 20 faces (faraday_entropy::uniform_face); the booklet's 32 paths on six- and twenty-faced dice and its order with an equal pair (roller.sheet).

Random cases Random answers (some mostly skipped bytes) under clicks of every size into entries of random room, with resets; the five dice of random faces (2 to 20) under clicks of every reach into codex32 shares of random count and length, answers running out part way; rolls of random dice entered by hand, equal pairs among them.

Differences None known.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The pool of bytes is zeroed as each byte is used and when it is cleared.

Limits

Offered only in Faraday Demo, never on the stick, the Pi or the website.

Its values are labelled simulated dice.

Faraday's own calls

The roller is an exception to Faraday's randomness never making a codex32 seed; it is testnet-only. Neutral, F96.

Choose Diceware words

SpecificationEFF word listsPublishedCodeFaraday's code: core/faraday-bipCross-checked withNot cross-checked
Action

Chooses Diceware words for a passphrase from dice rolls, from the three EFF lists checked by digest.

Specification

EFF word lists, EFF long and short Diceware word lists, Convention, vendored

Code

Faraday's code: core/faraday-bip: The lists are modules written by tools/diceware/gen.py from the committed EFF files and built in; a roll is the index written in base six with one added to each digit; a test checks each list and its SHA-256 against the committed file.

Checked against

tools/vectors/eff

Published, by the Electronic Frontier Foundation.

core/faraday-bip/tests/all/diceware.rs::every_roll_names_the_word_the_file_names

core/faraday-bip/tests/all/diceware.rs::the_digests_match_the_committed_files

core/faraday-bip/tests/all/diceware.rs::a_roll_that_is_not_a_throw_of_this_list_names_no_word

no fuzz target: Takes single die faces from a pad

Cross-check

not cross-checked: The lists are checked by their digests against the committed EFF files

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The lists are public; a passphrase rolled from one is held by the caller.

Limits

A roll that is not a throw of the list names no word.

Faraday's own calls

none

Backups

13 actions · 6 with Faraday's own code · 12 cross-checked with others' code · 9 with Faraday's second version · 1 not cross-checked

Make a SeedQR

SpecificationSeedQR · BIP 39PublishedCodeLibrary: sha2 0.11 (through core/faraday-crypto)Library: unicode-normalization 0.1 (through core/faraday-bip)Faraday's code: core/faraday-codecFaraday's own codeCross-checked withSeedSigner's encoders and DecodeQROthers' codeFaraday's second version
Action

Makes a SeedQR or CompactSeedQR picture from a key's words.

Specification

SeedQR, SeedQR and CompactSeedQR, Convention, vendored

BIP 39, Mnemonic code for generating deterministic keys, Deployed

Code

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Library: unicode-normalization 0.1.25, by the unicode-rs developers, through core/faraday-bip.

Faraday's code: core/faraday-codec: The word indices as four decimal digits each in numeric mode, or the entropy bytes in byte mode, at error-correction level L; the matrix and the digit buffer are wiped; the code is the smallest version that holds the payload. The app writes the picture as an eight-bit greyscale PNG with the key's fingerprint as its title, and wipes the pixels drawn once the file is made; the blank sheet's grid is the SeedQR of an all-zero seed of the same length, so its fixed squares are every seed's.

Written by Faraday

SeedQR (faraday-codec::seedqr) · No established implementation exists

No Rust library implements SeedQR.

Carries a format; it computes nothing on a key.

Decision F178

The PNG writer, with zlib's stored blocks (faraday-codec::png) · One exists but does not fit Faraday's rules for keys

Faraday writes a SeedQR's picture in buffers it wipes; its Adler-32 is the adler2 crate's.

Does not fit: png 0.18.1 needs std, which faraday-codec does not have, and does not wipe a picture's rows

Carries a format; it computes nothing on a key.

Decision F180

Checked against

tools/vectors/seedqr

Published, by SeedSigner's SeedQR specification, by the SeedSigner developers.

core/faraday-codec/src/seedqr.rs::specification_vectors_encode_and_decode

core/faraday-codec/src/seedqr.rs::round_trips_in_every_language

core/faraday-codec/src/qr.rs::seedqr_sizes_follow_the_specification

core/faraday-codec/src/qr.rs::a_seedqr_matrix_is_wiped

fuzz seedqr

Cross-check

Compared with others' code: SeedSigner's encoders and DecodeQR, by the SeedSigner developers, over embit's BIP-39 code, by Stepan Snigirev, and Project Nayuki's qrcodegen.py, by Nayuki, and segno, by Lars Heuer, and the pictures decoded by zbar, by the zbar developers, and zxing-cpp, by the zxing-cpp developers.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the CompactSeedQR of 15, 18 and 21 words, which SeedSigner does not define (the entropy itself).

Area seedqr

Faraday's code faraday_codec::seedqr (SeedQR, CompactSeedQR), faraday_codec::qr, the encoder that draws them, and faraday_codec::qr::codex32qr with the picture faraday_core::picture writes of it

Compared with SeedSigner's own encoders and DecodeQR (seedsigner/, unchanged, with embit's BIP-39 code in embit/); Project Nayuki's qrcodegen.py (qrcodegen/), module for module; segno 1.6 (python3-segno), an encoder of another lineage, at Faraday's mask and at its own; Pillow and CPython's zlib, which read every PNG Faraday writes; zbar (zbarimg) and zxing-cpp, which decode the QR code in every picture and return its payload as bytes (qr_decode.py).

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; SeedSigner's reader is looser than Faraday (it takes 49 digits, a sign inside a group, 20 to 28 bytes, and does not check the checksum of digits), so Faraday's own rule, the lengths and the digits, stands in front of it in area_seedqr.py and the checksum is embit's; SeedSigner runs in English for every language, the indices being the same; the profile's own pictures are read from their pixels and must be Faraday's code module for module; segno is asked for Faraday's version, level and mode and its mask forced, and its mask is read back from it, its padding quirk being modelled in Nayuki's code; rqrr reads Faraday's and segno's codes; the self-test makes each decoder's answer wrong (a payload's last byte changed) and must catch it.

An empty payload, which segno refuses.

Vectors SeedSigner's nine test SeedQRs (tools/vectors/seedqr/); every string and picture of the Codex32QR profile (tools/vectors/codex32qr/), each decoded by zbar and zxing-cpp.

Random cases Keys of every length and language, both codes and the words read back; digits and bytes malformed; payloads in each mode at each level and version limit; 48-character codex32 strings in either case as Codex32QR codes and the pictures written of them read back and decoded by zbar and zxing-cpp, other lengths refused; the pictures of a key's SeedQR and CompactSeedQR decoded by both and read by Faraday to the key's words; greyscale pictures and QR pictures of random size and scale read by Pillow and zlib.

Differences SeedQR digits: SeedSigner reads a string with 1 to 3 digits more than 48 or 96 (it drops the tail) and one with a sign or a space inside a group of four (int() takes them); Faraday refuses both (5 cases, each checked on both sides and counted). SeedSigner takes no CompactSeedQR of 20, 24 or 28 bytes either, and strips checksum bits for 12 and 24 words only; the corpus keeps Faraday's 15, 18 and 21 word compact form on the entropy itself.

Codex32QR: Faraday picks the mask Nayuki's encoder picks; the profile's encoder chose another for 6 of its 22 pictures. For those the area swaps the mask of Faraday's code for the picture's with qrcodegen.py's masking, requires the picture, and counts it.

Segno 1.6 writes a zero codeword where the pad codewords begin when the data, terminator included, ends on a codeword boundary with room left (its write_padding_bits adds 8 zero bits where none are due; ISO/IEC 18004 7.4.10 adds none): its code is Nayuki's with that codeword changed, which rqrr reads, counted as a known difference, the padding; Faraday's is the standard's.

Segno picks a mask by its own penalty rule, and for some payloads another than Nayuki's and Faraday's; the area requires that code to be Faraday's under the mask segno reports (Nayuki's masking swapped to it) and rqrr to read it, and counts each as a known difference, the mask choice, which a reader ignores.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 8000 cases

Secret handling

Reveal::SeedQr

Not stated by the encoder.

The digit buffer is a fixed array inside a Secret and the module grid is zeroizing; both wipe on drop.

Limits

A SeedQR is made for any word count; one is read back only at 12 and 24 words: 48 or 96 digits, or 16 or 32 bytes.

The CompactSeedQR of 15, 18 or 21 words is the entropy itself, a form SeedSigner does not define.

The picture carries no wordlist language.

Faraday's own calls

The picture is a copy only when it is checked by a scan or typed words. Neutral, F29.

Check a SeedQR

SpecificationSeedQR · BIP 39PublishedCodeLibrary: unicode-normalization 0.1 (through core/faraday-bip)Faraday's code: faraday/faraday-keysCross-checked withSeedSigner's encoders and DecodeQROthers' codeFaraday's second version
Action

Checks that a SeedQR read by the scanner is the one a key's words make.

Specification

SeedQR, SeedQR and CompactSeedQR, Convention, vendored

BIP 39, Mnemonic code for generating deterministic keys, Deployed

Code

Library: unicode-normalization 0.1.25, by the unicode-rs developers, through core/faraday-bip.

Faraday's code: faraday/faraday-keys: Parses the key's words, writes their digit stream and compares it with the scanned payload; English words only.

Checked against

tools/vectors/seedqr

Published, by SeedSigner's SeedQR specification, by the SeedSigner developers.

faraday/faraday-core/tests/all/check_copy.rs::a_seedqr_copy_with_a_camera_is_checked_by_the_scan_and_words_alone_do_not

faraday/faraday-core/tests/all/check_copy.rs::a_drawn_standard_seedqr_of_the_seed_matches_and_adds_nothing

faraday/faraday-core/tests/all/check_copy.rs::a_drawn_compact_seedqr_of_the_seed_matches

core/faraday-codec/src/seedqr.rs::rejects_bad_payloads

fuzz seedqr

Cross-check

Compared with others' code: SeedSigner's encoders and DecodeQR, by the SeedSigner developers, over embit's BIP-39 code, by Stepan Snigirev, and Project Nayuki's qrcodegen.py, by Nayuki, and the pictures decoded by zbar, by the zbar developers, and zxing-cpp, by the zxing-cpp developers.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: Faraday's rule written in area_seedqr.py in front of SeedSigner's reader (exactly 48 or 96 digits, 16 or 32 bytes), and the CompactSeedQR of 15, 18 and 21 words, which SeedSigner does not define.

Area seedqr

Faraday's code faraday_codec::seedqr (SeedQR, CompactSeedQR), faraday_codec::qr, the encoder that draws them, and faraday_codec::qr::codex32qr with the picture faraday_core::picture writes of it

Compared with SeedSigner's own encoders and DecodeQR (seedsigner/, unchanged, with embit's BIP-39 code in embit/); Project Nayuki's qrcodegen.py (qrcodegen/), module for module; segno 1.6 (python3-segno), an encoder of another lineage, at Faraday's mask and at its own; Pillow and CPython's zlib, which read every PNG Faraday writes; zbar (zbarimg) and zxing-cpp, which decode the QR code in every picture and return its payload as bytes (qr_decode.py).

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; SeedSigner's reader is looser than Faraday (it takes 49 digits, a sign inside a group, 20 to 28 bytes, and does not check the checksum of digits), so Faraday's own rule, the lengths and the digits, stands in front of it in area_seedqr.py and the checksum is embit's; SeedSigner runs in English for every language, the indices being the same; the profile's own pictures are read from their pixels and must be Faraday's code module for module; segno is asked for Faraday's version, level and mode and its mask forced, and its mask is read back from it, its padding quirk being modelled in Nayuki's code; rqrr reads Faraday's and segno's codes; the self-test makes each decoder's answer wrong (a payload's last byte changed) and must catch it.

An empty payload, which segno refuses.

Vectors SeedSigner's nine test SeedQRs (tools/vectors/seedqr/); every string and picture of the Codex32QR profile (tools/vectors/codex32qr/), each decoded by zbar and zxing-cpp.

Random cases Keys of every length and language, both codes and the words read back; digits and bytes malformed; payloads in each mode at each level and version limit; 48-character codex32 strings in either case as Codex32QR codes and the pictures written of them read back and decoded by zbar and zxing-cpp, other lengths refused; the pictures of a key's SeedQR and CompactSeedQR decoded by both and read by Faraday to the key's words; greyscale pictures and QR pictures of random size and scale read by Pillow and zlib.

Differences SeedQR digits: SeedSigner reads a string with 1 to 3 digits more than 48 or 96 (it drops the tail) and one with a sign or a space inside a group of four (int() takes them); Faraday refuses both (5 cases, each checked on both sides and counted). SeedSigner takes no CompactSeedQR of 20, 24 or 28 bytes either, and strips checksum bits for 12 and 24 words only; the corpus keeps Faraday's 15, 18 and 21 word compact form on the entropy itself.

Codex32QR: Faraday picks the mask Nayuki's encoder picks; the profile's encoder chose another for 6 of its 22 pictures. For those the area swaps the mask of Faraday's code for the picture's with qrcodegen.py's masking, requires the picture, and counts it.

Segno 1.6 writes a zero codeword where the pad codewords begin when the data, terminator included, ends on a codeword boundary with room left (its write_padding_bits adds 8 zero bits where none are due; ISO/IEC 18004 7.4.10 adds none): its code is Nayuki's with that codeword changed, which rqrr reads, counted as a known difference, the padding; Faraday's is the standard's.

Segno picks a mask by its own penalty rule, and for some payloads another than Nayuki's and Faraday's; the area requires that code to be Faraday's under the mask segno reports (Nayuki's masking swapped to it) and rqrr to read it, and counts each as a known difference, the mask choice, which a reader ignores.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 8000 cases

Secret handling

none: no secret leaves faraday-keys

The comparison of the payload with the digit stream is not stated to be constant time.

The digit stream is a Secret and wipes on drop.

Limits

A key whose words are not English is not checked.

A key with no words in the session is not checked.

Faraday's own calls

A copy by hand is checked by its form: typed words, or a scan of a SeedQR. Neutral, F29.

Work with codex32 strings

SpecificationBIP 93PublishedCodeFaraday's code: core/faraday-bipFaraday's own codeCross-checked withpython-codex32Others' codeFaraday's second version
Action

Reads, checksums, splits and recovers codex32 strings, and keeps and gathers the strings of a key's set.

Specification

BIP 93, codex32: Checksummed SSS-able BIP32 Seeds, Draft, vendored

Code

Faraday's code: core/faraday-bip: The BCH checksum and the Lagrange interpolation over GF(32) are written here, with no codex32 crate; the string, its payload and the seed live in fixed arrays wiped on drop. Recovery takes exactly k shares; a further share is derived only from exactly k strings at an index not in use.

Written by Faraday

BIP 93 codex32 (faraday-bip::codex32) · One exists but does not fit Faraday's rules for keys

The reference library keeps the seed in text that is never wiped and needs a full operating system.

Does not fit: codex32 0.1.0 holds the seed in a String that is Clone and Debug and never wiped, which tools/lint-secrets.sh refuses, and needs std, which faraday-bip does not have

Decision F178

Checked against

tools/vectors/bip93

Published, by BIP 93's authors (bitcoin/bips).

core/faraday-bip/tests/all/codex32.rs::a_seed_encodes_to_the_string_the_bip_gives

core/faraday-bip/tests/all/codex32.rs::every_invalid_string_is_refused

core/faraday-bip/tests/all/codex32.rs::shares_recover_the_secret_and_derive_more

core/faraday-bip/tests/all/codex32.rs::a_split_seed_comes_back_from_any_threshold_of_its_shares

core/faraday-bip/tests/all/codex32.rs::a_set_that_does_not_hold_together_is_refused

faraday/faraday-keys/tests/codex32.rs::set::a_key_made_from_codex32_shares_knows_its_set

faraday/faraday-keys/tests/codex32.rs::set::strings_typed_back_rebuild_their_key_and_no_other

fuzz seed_parts

Cross-check

Compared with others' code: python-codex32, by Ben Westgate, and rust-codex32, by Andrew Poelstra (which decides the threshold of 0 or 2 to 9 and a threshold of 0's share index).

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: two rules BIP 93 states that neither enforces (the seed's lengths, the order shares are handed out), written in area_codex32.py from the BIP's text.

Area codex32

Faraday's code faraday_bip::codex32

Compared with python-codex32 (codex32/); rust-codex32 at a pinned commit (rust-codex32/), a program outside the workspace: parsing, checksums, the threshold and a threshold of 0's share index, interpolate_at for a fresh set's shares; volvelle-website's checksum worksheet run as a program over every worksheet of 48 and 74 characters; the worksheet of 127 characters written in the area from python-codex32's polymod.

Checked first: Its vendored files are hashed against references.sha256 before any run (the Rust programs' sources included, built offline by run.sh with the toolchain on the PATH), and a published vector's answer is required of the reference as well as of Faraday; rust-codex32 and python-codex32 must give the same answer where both are asked; two rules BIP 93 states that neither enforces (the master seed's sizes, the order shares are handed out) are written in the area from the BIP's text, and the worksheet of 127 characters from BIP 93's polymod alone.

Vectors Every vector of tools/vectors/bip93/, the 55 invalid strings included; volvelle-website's worksheet cells (tools/vectors/codex32-volvelle/); the booklet's checksum, derivation, recovery, addition, translation and fusion tables (tools/vectors/codex32-booklet/); the Codex32QR profile's sets (tools/vectors/codex32qr/).

Random cases secrets, splits (the same randomness), recovery, derived shares, corrupted strings; fresh sets of every threshold up to 31 strings at 48, 74 and 127 characters, the checksum worksheets of their strings and of corrupted ones, checksums made on a sheet, translation and recovery symbols, translation worksheets.

Differences Codex32: Faraday recovers only from exactly k shares without the secret, and derives a share only from exactly k strings at an unused index; the reference also takes more strings or a used index.

The codex32 seed sizes, which the references leave to their caller, are written in the area from the BIP's own sentence. Volvelle's sheet works the checksum itself, so a string of 48 or 74 characters whose checksum is not the one the sheet works is judged by that alone (holds false), not by its rows.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 10000 cases

Secret handling

Reveal::BackupStick

GF(32) multiplication, the checksum's residue and the alphabet's lookup are written without a branch or a table index on a symbol's value, as the code documents; the code states no other timing.

The string, its payload and the seed are fixed arrays wiped on drop; a codex32 share record's string is a secret. A fresh set's share list is reserved at its full count before the first share is pushed, so no share is left in a block freed by a reallocation.

Limits

Seeds of 128, 160, 192, 224, 256 or 512 bits.

A threshold of 2 to 9, or 0 for the secret alone, and at most 31 strings.

A string that does not hold together, or whose checksum fails, is refused with the reason named.

A key of words is never split into codex32 strings.

Faraday's own calls

Recovery is from exactly k shares only. Conservative, F90.

The set's identifier is the first 20 bits of the master fingerprint, which puts 20 bits of it on every share. Neutral.

no decision

Make codex32 shares

SpecificationBIP 93PublishedCodeFaraday's code: core/faraday-bipCross-checked withvolvelle-website's checksum worksheetOthers' codeFaraday's second version
Action

Fills the codex32 booklet's worksheets one character at a time and makes a fresh set or derived shares from them.

Specification

BIP 93, codex32: Checksummed SSS-able BIP32 Seeds, Draft, vendored

Code

Faraday's code: core/faraday-bip: The checksum and translation worksheets are the booklet's tables as numbers, so every cell is shown as it is worked; a fresh set takes the person's characters as the data of the k initial shares and interpolates the secret and the other shares; faraday-keys lends a work set's rows and strings only as a paper form.

Checked against

tools/vectors/bip93

Published, by BIP 93's authors (bitcoin/bips).

tools/vectors/codex32-booklet

Published, by the codex32 booklet, by Blockstream (SSS32).

tools/vectors/codex32-volvelle

Computed by volvelle-website's checksum worksheet (apoelstra/volvelle-website), run as the folder's harness runs it.

core/faraday-bip/tests/all/codex32_sheets.rs::checksum_worksheets_match_volvelle_cell_for_cell

core/faraday-bip/tests/all/codex32_sheets.rs::translation_worksheets_make_the_published_derived_shares

core/faraday-bip/tests/all/codex32_sheets.rs::a_fresh_set_from_bip93s_initial_shares_is_its_set

core/faraday-bip/tests/all/codex32_sheets.rs::fresh_sets_of_every_threshold_recover_from_any_k_strings

core/faraday-bip/tests/all/codex32_sheets.rs::a_worksheet_refuses_what_is_not_a_codex32_length_or_symbol

faraday/faraday-keys/tests/codex32.rs::characters_typed_one_at_a_time_make_the_published_strings

faraday/faraday-keys/tests/codex32.rs::only_a_paper_form_lends_the_work_sets_rows_and_strings

faraday/faraday-keys/tests/codex32.rs::the_derived_share_is_made_by_its_translation_worksheet

no fuzz target: The characters are typed one at a time into worksheets that refuse a symbol outside the alphabet and a length that is not codex32's

Cross-check

Compared with others' code: volvelle-website's checksum worksheet, by Andrew Poelstra (the worksheets of 48 and 74 characters), and rust-codex32, by Andrew Poelstra (a fresh set's derived shares), beside python-codex32, by Ben Westgate.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the worksheet of 127 characters, which volvelle does not lay out, written in area_codex32.py from python-codex32's polymod.

Area codex32

Faraday's code faraday_bip::codex32

Compared with python-codex32 (codex32/); rust-codex32 at a pinned commit (rust-codex32/), a program outside the workspace: parsing, checksums, the threshold and a threshold of 0's share index, interpolate_at for a fresh set's shares; volvelle-website's checksum worksheet run as a program over every worksheet of 48 and 74 characters; the worksheet of 127 characters written in the area from python-codex32's polymod.

Checked first: Its vendored files are hashed against references.sha256 before any run (the Rust programs' sources included, built offline by run.sh with the toolchain on the PATH), and a published vector's answer is required of the reference as well as of Faraday; rust-codex32 and python-codex32 must give the same answer where both are asked; two rules BIP 93 states that neither enforces (the master seed's sizes, the order shares are handed out) are written in the area from the BIP's text, and the worksheet of 127 characters from BIP 93's polymod alone.

Vectors Every vector of tools/vectors/bip93/, the 55 invalid strings included; volvelle-website's worksheet cells (tools/vectors/codex32-volvelle/); the booklet's checksum, derivation, recovery, addition, translation and fusion tables (tools/vectors/codex32-booklet/); the Codex32QR profile's sets (tools/vectors/codex32qr/).

Random cases secrets, splits (the same randomness), recovery, derived shares, corrupted strings; fresh sets of every threshold up to 31 strings at 48, 74 and 127 characters, the checksum worksheets of their strings and of corrupted ones, checksums made on a sheet, translation and recovery symbols, translation worksheets.

Differences Codex32: Faraday recovers only from exactly k shares without the secret, and derives a share only from exactly k strings at an unused index; the reference also takes more strings or a used index.

The codex32 seed sizes, which the references leave to their caller, are written in the area from the BIP's own sentence. Volvelle's sheet works the checksum itself, so a string of 48 or 74 characters whose checksum is not the one the sheet works is judged by that alone (holds false), not by its rows.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 10000 cases

Secret handling

Reveal::PaperForm

GF(32) multiplication, the checksum's residue and the alphabet's lookup are written without a branch or a table index on a symbol's value, as the code documents; the code states no other timing.

The work set's rows and strings are lent only for a paper form; the strings and the seed are wiped on drop.

Limits

A worksheet refuses a length that is not codex32's and a symbol outside the bech32 alphabet.

A scheme takes any threshold up to 9 and up to 31 strings.

The set is not made before every character is in.

Faraday's own calls

A further share is derived only from exactly k strings at an index not in use. Conservative, F90.

Correct a codex32 string

SpecificationBIP 93PublishedCodeFaraday's code: core/faraday-bipCross-checked withpython-codex32Others' codeFaraday's second version
Action

Proposes the one correction a codex32 checksum justifies for a damaged string, within BIP 93's bound.

Specification

BIP 93, codex32: Checksummed SSS-able BIP32 Seeds, Draft, vendored

Code

Faraday's code: core/faraday-bip: BIP 93 specifies no procedure; the decoder is written here after python-codex32's: up to 4 substituted boxes, up to 8 unreadable boxes, any mix with twice the substitutions plus the unreadable boxes at most 8, or one run of 9 to 13 unreadable boxes (15 on the long checksum); the proposal is parsed again before anything takes it.

Checked against

tools/vectors/codex32-correction

Published, by python-codex32's frozen correction corpus, by Ben Westgate.

core/faraday-bip/tests/all/codex32_correct.rs::the_frozen_corpus_is_corrected_or_refused_as_published

core/faraday-bip/tests/all/codex32_correct.rs::every_mix_within_the_bound_is_corrected_at_every_length

core/faraday-bip/tests/all/codex32_correct.rs::past_the_bound_nothing_is_proposed_that_the_bound_does_not_justify

core/faraday-bip/tests/all/codex32_correct.rs::ms1_and_the_header_the_set_fixes_are_never_changed

fuzz seed_parts

Cross-check

Compared with others' code: python-codex32, by Ben Westgate (its correction.py).

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the bound BIP 93 states (substitutions and unreadable boxes, one run up to the checksum's length) and a held string's fixed header, written in area_codex32_correct.py from the BIP's sentence.

Area codex32-correct

Faraday's code faraday_bip::codex32::correct

Compared with python-codex32's decoder, correction.py at a later commit (codex32/correction/), asked with BIP 93's bound.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; it is asked with the bound BIP 93 states, written in the area from that sentence and nothing else.

Vectors python-codex32's frozen correction corpus, 57 cases (tools/vectors/codex32-correction/).

Random cases Random strings of every length with substitutions and unreadable boxes up to and past the bound, runs of unreadable boxes around the checksum's length, a held string's header fixed, upper case, ms1 damaged.

Differences Codex32 correction: python-codex32 reads a character outside the bech32 alphabet as unreadable, and fills more than 8 unreadable boxes that are not one run when its equations allow; Faraday refuses both (docs/CODEX32.md §8.4). The corpus damages strings with bech32 characters and ? only.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 100000 cases

Secret handling

none: no secret leaves faraday-keys

GF(32) multiplication, the checksum's residue and the alphabet's lookup are written without a branch or a table index on a symbol's value, as the code documents; the code states no other timing.

The strings are fixed arrays wiped on drop.

Limits

ms1 and, where a string of the set is in, the threshold and identifier boxes are never changed.

Insertions, deletions and swapped boxes are not searched for.

A character outside the bech32 alphabet other than ? is refused, not read as unreadable.

More than 8 unreadable boxes that are not one run are refused.

Faraday's own calls

Correction is opt-in, off whenever the form opens, proposes only where the correction is unique, and is never applied: the person types the changed boxes again. Conservative, F94.

A character outside the bech32 alphabet is not read as an erasure, and more than 8 erasures not in one run are refused; BIP 93 makes the first optional, and python-codex32 accepts both. Conservative, F155.

Make a Codex32QR

SpecificationCodex32QR/v1-48 · BIP 93PublishedCodeFaraday's code: core/faraday-codecCross-checked withProject Nayuki's qrcodegen.pyOthers' code
Action

Writes a 48-character codex32 string as a Codex32QR code.

Specification

Codex32QR/v1-48, Codex32QR/v1-48, one 48-character codex32 string in a QR code, Convention, vendored

BIP 93, codex32: Checksummed SSS-able BIP32 Seeds, Draft, vendored

Code

Faraday's code: core/faraday-codec: One upper-case string in alphanumeric mode at level L, version 3, with the standard quiet zone, following the profile's pictures module for module.

Checked against

tools/vectors/codex32qr

Published, by the Codex32QR profile, in FractalEncrypt's SeedSigner fork.

core/faraday-codec/src/qr.rs::a_codex32qr_is_one_code_for_either_case_and_only_at_48_characters

core/faraday-bip/tests/all/codex32_sheets.rs::codex32qr_vectors_recover_to_their_secret_and_key

no fuzz target: The encoder takes a string that Codex32::parse has already accepted; seed_parts fuzzes that reading

Cross-check

Compared with others' code: Project Nayuki's qrcodegen.py, by Nayuki, and segno, by Lars Heuer, and the pictures decoded by zbar, by the zbar developers, and zxing-cpp, by the zxing-cpp developers.

Area seedqr

Faraday's code faraday_codec::seedqr (SeedQR, CompactSeedQR), faraday_codec::qr, the encoder that draws them, and faraday_codec::qr::codex32qr with the picture faraday_core::picture writes of it

Compared with SeedSigner's own encoders and DecodeQR (seedsigner/, unchanged, with embit's BIP-39 code in embit/); Project Nayuki's qrcodegen.py (qrcodegen/), module for module; segno 1.6 (python3-segno), an encoder of another lineage, at Faraday's mask and at its own; Pillow and CPython's zlib, which read every PNG Faraday writes; zbar (zbarimg) and zxing-cpp, which decode the QR code in every picture and return its payload as bytes (qr_decode.py).

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; SeedSigner's reader is looser than Faraday (it takes 49 digits, a sign inside a group, 20 to 28 bytes, and does not check the checksum of digits), so Faraday's own rule, the lengths and the digits, stands in front of it in area_seedqr.py and the checksum is embit's; SeedSigner runs in English for every language, the indices being the same; the profile's own pictures are read from their pixels and must be Faraday's code module for module; segno is asked for Faraday's version, level and mode and its mask forced, and its mask is read back from it, its padding quirk being modelled in Nayuki's code; rqrr reads Faraday's and segno's codes; the self-test makes each decoder's answer wrong (a payload's last byte changed) and must catch it.

An empty payload, which segno refuses.

Vectors SeedSigner's nine test SeedQRs (tools/vectors/seedqr/); every string and picture of the Codex32QR profile (tools/vectors/codex32qr/), each decoded by zbar and zxing-cpp.

Random cases Keys of every length and language, both codes and the words read back; digits and bytes malformed; payloads in each mode at each level and version limit; 48-character codex32 strings in either case as Codex32QR codes and the pictures written of them read back and decoded by zbar and zxing-cpp, other lengths refused; the pictures of a key's SeedQR and CompactSeedQR decoded by both and read by Faraday to the key's words; greyscale pictures and QR pictures of random size and scale read by Pillow and zlib.

Differences SeedQR digits: SeedSigner reads a string with 1 to 3 digits more than 48 or 96 (it drops the tail) and one with a sign or a space inside a group of four (int() takes them); Faraday refuses both (5 cases, each checked on both sides and counted). SeedSigner takes no CompactSeedQR of 20, 24 or 28 bytes either, and strips checksum bits for 12 and 24 words only; the corpus keeps Faraday's 15, 18 and 21 word compact form on the entropy itself.

Codex32QR: Faraday picks the mask Nayuki's encoder picks; the profile's encoder chose another for 6 of its 22 pictures. For those the area swaps the mask of Faraday's code for the picture's with qrcodegen.py's masking, requires the picture, and counts it.

Segno 1.6 writes a zero codeword where the pad codewords begin when the data, terminator included, ends on a codeword boundary with room left (its write_padding_bits adds 8 zero bits where none are due; ISO/IEC 18004 7.4.10 adds none): its code is Nayuki's with that codeword changed, which rqrr reads, counted as a known difference, the padding; Faraday's is the standard's.

Segno picks a mask by its own penalty rule, and for some payloads another than Nayuki's and Faraday's; the area requires that code to be Faraday's under the mask segno reports (Nayuki's masking swapped to it) and rqrr to read it, and counts each as a known difference, the mask choice, which a reader ignores.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 8000 cases

Secret handling

none: no secret leaves faraday-keys

Not stated by the encoder.

The matrix wipes on drop; the caller asks faraday-keys for the string.

Limits

A string of any length but 48 characters is refused; no profile is made up for the 74 and 127 character forms.

Faraday's own calls

No code is drawn for a 74 or 127 character string, and none is read but as plain text, until the profile's author publishes a profile for them. Conservative, F95.

Seal and open Krux codes

SpecificationKEFPublishedCodeLibrary: aes 0.9Library: cbc 0.2Library: ctr 0.104 moreFaraday's code: faraday/faraday-kefFaraday's own codeCross-checked withKrux's kef.pyOthers' codeFaraday's second version
Action

Writes and reads a Krux encrypted code (KEF): a passphrase and a count of PBKDF2-HMAC-SHA-256 rounds over an id give an AES-256 key, and one of twelve versions (ECB, CBC, CTR or GCM, with or without compression) seals the bytes with the format's own check.

Specification

KEF, KEF, Krux's encrypted code, Convention

Code

Library: aes 0.9.3, by the RustCrypto developers.

Library: cbc 0.2.1, by the RustCrypto developers.

Library: ctr 0.10.1, by the RustCrypto developers.

Library: aes-gcm 0.11.1, by the RustCrypto developers.

Library: miniz_oxide 0.8.9 and 0.9.1, by the miniz_oxide developers, a port of Rich Geldreich's miniz.

Library: sha2 0.11.0, by the RustCrypto developers.

Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: faraday/faraday-kef: Only the part used is written: the twelve versions of Krux's table, their padding and their checks, the tolerant reading of Krux's own inconsistencies, and the refusal of what Krux refuses to write (a hidden check ending in 0x00). A compressed code inflates under a limit. The PBKDF2 loop can stop and counts; it is one 32-byte block, checked against the library's PBKDF2 and RFC 7914's vectors.

Written by Faraday

KEF: the envelope, the version table, padding, the two SHA-256 checks and base43 (faraday-codec::kef, faraday-kef), and PBKDF2's loop over HMAC-SHA-256 for one block, with a cancel check (faraday-crypto::hash) · Only the part used is written

No library reads or writes this format. The pbkdf2 crate is one call that cannot stop, and a count of 100 million rounds must be stoppable.

Decision F219

Checked against

tools/vectors/kef

Published, by Krux's test data (tests/test_kef.py and tests/test_encryption.py of selfcustody/krux; the commit, licence and SHA-256 of each file are in the folder's README).

faraday/faraday-kef/tests/kef.rs::krux_ctr_code_opens_to_its_entropy

faraday/faraday-kef/tests/kef.rs::krux_gcm_code_opens_to_its_entropy

faraday/faraday-kef/tests/kef.rs::krux_gcm_code_with_a_wrong_passphrase_or_a_changed_byte_does_not_open

faraday/faraday-kef/tests/kef.rs::krux_version_5_code_opens_and_a_wrong_passphrase_that_passes_gives_other_bytes

faraday/faraday-kef/tests/kef.rs::every_version_opens_what_it_seals

faraday/faraday-kef/tests/kef.rs::what_krux_refuses_to_write_is_refused_and_names_a_version_that_works

faraday/faraday-kef/tests/kef.rs::a_count_of_100_million_stops_when_told

faraday/faraday-keys/tests/operations.rs::kef_entropy::a_12_and_a_24_word_seed_give_16_and_32_bytes_of_entropy

faraday/faraday-keys/tests/operations.rs::kef_entropy::a_seed_of_15_words_is_refused

faraday/faraday-keys/tests/operations.rs::kef_entropy::another_reason_gets_nothing_and_this_one_lends_no_text

fuzz kef

Cross-check

Compared with others' code: Krux's kef.py, by the Krux developers, vendored unchanged and run under CPython, for all twelve versions, written and read.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: Faraday's refusals listed as known differences in area_kef.py (an empty plaintext, an id of 253 bytes, a text that inflates past the limit, a passphrase or count Krux's field does not offer, suggestions over 1,024 bytes), and krux's three shims (ucryptolib, uhashlib_hw and deflate at wbits -10, over hashlib, PyCA and zlib).

Area kef

Faraday's code faraday_kef (seal, seal_with_key, open, open_with_key, suggest_versions), faraday_codec::kef::unwrap

Compared with krux's kef.py (krux/, unchanged), by the krux developers, on three small shims for the firmware's AES, SHA-256 and PBKDF2, and deflate modules (PyCA cryptography's AES, hashlib, zlib at wbits -10).

Checked first: The vendored files are hashed against references.sha256 before any run; krux's own vectors (tools/vectors/kef/) are required of the reference as well as of Faraday; every plaintext Faraday seals is opened by krux's decrypt, and every plaintext krux seals by Faraday, to the plaintext that went in.

The text forms and the classifier (krux's kef.py holds neither), the Reveal variant and the worker; whether Faraday notes that the check passed only after putting NULs back; a key entered as hex that Faraday writes under (it refuses a passphrase that is not printable ASCII), so keys of raw bytes are compared only when Faraday opens.

Vectors krux's test data for versions 5, 15 and 20 (tools/vectors/kef/): a CTR code under key, a GCM code under test key at 100,000 rounds, and the version 5 code opened by abc and by a wrong passphrase that passes its 3-byte check.

Random cases Each of the twelve versions sealed by Faraday and by krux, byte for byte for the ten that do not compress and opened by the other for all twelve, over entropy of 16 and 32 bytes, short and long text, text up to 1,024 bytes, text ending in NUL, text whose hidden check ends in 0x00, repeated blocks, ids of 0, 8, 252 and random lengths, every edge of the count, and wrong IV lengths; codes under a passphrase at 10,000 to 30,000 rounds, one of 200 characters with an id of 252 bytes, and keys of raw bytes (to 200 bytes) krux seals and Faraday opens; codes from a writer that skipped the NUL rules, with 1 to 8 NULs at the end; envelopes cut or changed; the suggested versions for each mode at every length to 1,024.

Differences KEF: Faraday refuses an empty plaintext, a compressed version over 1,024 bytes, an id of 253 bytes or more when reading (krux's unwrap does not check it), a count over 550,000 and a passphrase that is not printable ASCII when it works out the key, and a stream that inflates to over 102,400 bytes; krux does none of these. Each is asked of krux and counted. Faraday does not suggest a compressed version over 1,024 bytes.

KEF: a stream that inflates to exactly 102,400 bytes is read by Faraday and refused by krux's firmware (its read is capped at the limit and raises when it is asked for more before the stream has ended); one of 102,401 bytes or more is refused by both. A stream whose matches reach back more than 1,024 bytes is read by Faraday (any window to 32 KiB) and refused by krux's 1,024-byte window; Faraday writes none.

KEF: Faraday's unwrap refuses at once a payload that holds nothing but the IV, the exposed check and the hidden check; krux's unwrap takes it apart and its decryption then fails. Both end in a code that does not open.

KEF: version 7 (ECB with deflate) is refused for a repeated block by the side whose compressor makes a stream with one; the stream of the other has none, and that side's code is opened by both.

KEF: the compressed versions are not equal byte for byte, as Faraday's deflate and zlib's write different streams. Each opens the other's; krux's decryption inflates under zlib at wbits -10.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 8200 cases

Secret handling

Reveal::KefCode

The GCM tag is compared in constant time by aes-gcm; the check bytes of the other versions are compared as Krux does; AES and PBKDF2 state nothing more.

The key, the passphrase bytes and the opened plaintext are Zeroizing values wiped on drop.

Limits

A written passphrase is printable ASCII of at most 200 characters; a read one is tried as typed, in NFC and in NFD.

A code that inflates past 100 KiB does not open.

A count over 550,000 is not written; PBKDF2 runs in steps of 5,000 rounds and stops when told.

Faraday's own calls

What Krux refuses to write is refused here, and a refusal names a version that works. Conservative, F219.

Read a SQLite database

SpecificationSQLite file formatPublishedCodeFaraday's code: faraday/faraday-sqliteCross-checked withSQLite itselfOthers' codeFaraday's second version
Action

Reads a SQLite database file and never writes one: the header, the schema, the one table of two blob columns (key and value) of a Bitcoin Core wallet and its pages, with every file that is not whole refused. It is not cryptography.

Specification

SQLite file format, The SQLite database file format, Convention

Code

Faraday's code: faraday/faraday-sqlite: Only the part Bitcoin Core writes is read: the 100-byte header, table b-tree interior and leaf pages, overflow pages, varints and the record format, in the rollback-journal form. The write-ahead-log form, a header field SQLite does not allow, a page reached twice, a cell or overflow past its page or the file, a record whose header disagrees with its body, a column that is not a blob, a table other than the wanted one holding records and a tree deeper than 20 are refused.

Checked against

not checked against vectors

faraday/faraday-sqlite/tests/sqlite.rs::every_page_size_reads_the_rows_sqlite_wrote

faraday/faraday-sqlite/tests/sqlite.rs::values_that_spill_onto_overflow_pages_read_whole

faraday/faraday-sqlite/tests/sqlite.rs::deleted_rows_are_not_returned

faraday/faraday-sqlite/tests/sqlite.rs::the_wal_form_is_refused

faraday/faraday-sqlite/tests/sqlite.rs::a_header_field_sqlite_does_not_allow_is_refused

faraday/faraday-sqlite/tests/sqlite.rs::a_page_reached_twice_is_refused

faraday/faraday-sqlite/tests/sqlite.rs::an_overflow_chain_that_ends_early_or_late_or_loops_is_refused

fuzz sqlite

Cross-check

Compared with others' code: SQLite itself, by the SQLite developers, through CPython's sqlite3, which makes each database and returns its rows.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: Faraday's refusals asked of Faraday alone in area_sqlite.py (the write-ahead-log form, auto-vacuum and UTF-16 databases, which SQLite reads).

Area sqlite

Faraday's code faraday_sqlite::Database (open, tables, rows)

Compared with SQLite itself, through CPython's sqlite3 module (the version is printed at the start of the area), by the SQLite developers.

Checked first: The rows SQLite returns for the bytes are the answer, with the table names of sqlite_schema; the databases are made by SQLite, and the cases that SQLite reads and Faraday refuses are asked of Faraday alone.

none; index pages are not read by Faraday and the rows are SQLite's answer.

Vectors none; the reader's tests read databases SQLite made (faraday/faraday-sqlite/tests/).

Random cases Random one-table databases at each page size from 512 to 65,536, with blobs from empty to several pages (overflow chains of every length), several transactions with rows deleted between them, and a second table in some; the same with one byte changed.

Differences SQLite reads the write-ahead-log form, auto-vacuum databases and UTF-16 databases, and a database with a table of any shape; Faraday reads the rollback-journal form with UTF-8 text and a table of two blob columns only, and refuses the rest. Each is asked of Faraday and counted.

SQLite parses the CREATE statements of the schema and refuses a database whose text is not valid SQL; Faraday reads a table's name and root page from its schema row and does not parse the statement. A changed byte in the schema page that SQLite refuses as a malformed schema, and Faraday reads, is not a mismatch.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 8000 cases

Secret handling

none: no secret leaves faraday-keys

Not stated; no secret is computed here.

The reader holds no secrets: it reads the bytes it is given and keeps none.

Limits

A file over 1 GiB, a page size outside 512 to 65,536, a tree deeper than 20 and a database in the write-ahead-log, auto-vacuum or UTF-16 form are refused.

Only the table b-tree is read: an index's pages are not, and not checked against the others.

Faraday's own calls

Whatever the reader does not follow is refused, and a page reached twice is refused. Conservative, F229.

Split with SLIP-39

SpecificationSLIP-0039PublishedCodeLibrary: hmac 0.13 (through core/faraday-crypto)Library: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-bipFaraday's own codeCross-checked withpython-shamir-mnemonicOthers' codeFaraday's second version
Action

Splits a master secret into SLIP-39 shares and recovers it from them, with the passphrase's Feistel encryption.

Specification

SLIP-0039, Shamir's Secret-Sharing for Mnemonic Codes, Status not checked, vendored

Code

Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-bip: Written here over faraday-crypto's HMAC-SHA256 and PBKDF2-HMAC-SHA256: the RS1024 checksum, Shamir over GF(256), the digest share and the Feistel cipher. The recovered master secret is the BIP 32 seed, not BIP 39 entropy. New key's split takes the shares' identifier and the split's randomness from the session's randomness, each 32 bytes from an answer of the system's of its own; the identifier is 15 bits of the first two bytes.

Written by Faraday

SLIP-39 Shamir backup (faraday-bip::slip39) · No established implementation exists

No maintained Rust implementation of SLIP-39 exists.

Decision F178

Checked against

tools/vectors/slip39

Published, by Trezor (SatoshiLabs), python-shamir-mnemonic.

core/faraday-bip/tests/all/slip39.rs::every_published_vector_recovers_or_is_refused

core/faraday-bip/tests/all/slip39.rs::a_recovered_master_secret_is_the_bip32_seed_the_vector_states

core/faraday-bip/tests/all/slip39.rs::a_split_at_slip39s_limits_matches_the_reference

core/faraday-bip/tests/all/slip39.rs::a_set_above_the_highest_iteration_exponent_read_is_refused

core/faraday-bip/tests/all/slip39.rs::nothing_is_computed_above_the_highest_iteration_exponent_read

core/faraday-bip/tests/all/slip39.rs::changing_one_word_of_a_share_is_refused

core/faraday-bip/tests/all/slip39.rs::every_published_vector_gives_its_ems_or_is_refused_without_the_passphrase

core/faraday-bip/tests/all/slip39.rs::a_rotated_set_opens_the_same_wallet

core/faraday-bip/tests/all/slip39.rs::only_an_extendable_set_takes_a_new_identifier

core/faraday-bip/tests/all/slip39.rs::an_added_share_recovers_with_the_old_ones

core/faraday-bip/tests/all/slip39.rs::a_replaced_share_is_the_lost_one_word_for_word

core/faraday-bip/tests/all/slip39.rs::a_share_added_to_a_group_recovers_with_the_other_groups

core/faraday-bip/tests/all/slip39.rs::a_share_is_not_made_from_a_wrong_quorum_or_at_a_taken_index

core/faraday-bip/tests/all/slip39.rs::an_ems_is_not_built_from_parts_a_share_cannot_carry

core/faraday-bip/tests/all/slip39.rs::a_new_set_of_a_bad_shape_is_refused

core/faraday-bip/tests/all/slip39.rs::the_set_functions_refuse_an_exponent_above_the_highest_read

core/faraday-bip/tests/all/slip39.rs::a_seed_gives_the_same_words_twice

core/faraday-bip/tests/all/slip39.rs::sixteen_bytes_are_twenty_words_and_thirty_two_are_thirty_three

core/faraday-bip/tests/all/slip39.rs::other_lengths_are_refused

core/faraday-bip/tests/all/slip39.rs::the_share_recovers_the_seed

core/faraday-bip/tests/all/slip39.rs::the_share_carries_the_fingerprints_identifier_and_the_fixed_parameters

core/faraday-bip/tests/all/slip39.rs::a_one_of_one_matches_the_reference

core/faraday-bip/tests/all/slip39.rs::bip93_seeds_written_as_slip39_read_back_the_same

core/faraday-bip/tests/all/slip39.rs::slip39_vectors_written_as_codex32_read_back_the_same

fuzz seed_parts

Cross-check

Compared with others' code: python-shamir-mnemonic, by Trezor (SatoshiLabs), and bip39_slip39, by the btclib developers (shares read and combined, secrets split under the same random bytes, the passphrase cipher, recover_ems, split_ems and _interpolate).

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: Faraday's refusals of a new member in derive_refused (area_slip39.py), written in front of the references, which have no function for them: shares of more than one group, an index outside 0 to 15, a group of threshold 1, a count other than the threshold, a repeated index, an index among the shares given; the refused lengths of the fixed 1 of 1; the identifier rules one_of_one_identifier and codex32_identifier, which the libraries take as a parameter.

Area slip39

Faraday's code faraday_bip::slip39

Compared with python-shamir-mnemonic (slip39/), its recover_ems, split_ems and _interpolate for a set's EMS, a new split of it and a member at an index; bip39_slip39 (bip39-slip39/) answering each SLIP-39 operation beside it (not the two codex32 operations); python-codex32 (codex32/) for the codex32 side of the conversions and btclib (bip32_ref.py) for the fingerprint; the refusals of a member at an index before the arithmetic are ours (derive_refused), and so are the lengths the fixed 1 of 1 refuses, which no second judge covers.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday, and of bip39_slip39 too; all 45 of its own vectors are run.

Vectors All 45 of tools/vectors/slip39/, each again through its EMS and its decryption.

Random cases Splits fed the same random bytes, which must match word for word; recovery from qualifying and short subsets and a changed word; the passphrase cipher; a set's EMS from a quorum, refused from a short or changed set, split again on the same random bytes (some under a new identifier where extendable) and a member added or a lost one made again at an index, each recovering the first set's secret, and a member refused at an index given, past 15, from a short quorum and across two groups; random seeds of 16 and 32 bytes through the fixed 1 of 1 against both libraries under the fingerprint's first 15 bits, recovered through both, and the lengths it refuses, against Faraday's own rule; the seed written as codex32 by Faraday and read by python-codex32, and a SLIP-39 set with a passphrase recovered by Faraday and by python-shamir-mnemonic, written as codex32 by Faraday and by python-codex32, the second read by Faraday, the same bytes both ways, the identifier's 20 bits written and the fingerprint (btclib's) compared on both sides.

Differences SLIP-39: Faraday refuses a group threshold of 1 over several groups; python-shamir-mnemonic makes the shares. The area checks that this still holds, so a change either way is seen.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 21000 cases

Secret handling

Reveal::PaperForm

The GF(256) arithmetic of the shares and the RS1024 checksum are written without a table indexed by a share's bytes or a branch on them, as the code documents; a word is found by comparing its first four letters with every entry of the list in constant time (subtle), the rest of the word with the entry found, masked; the digest is compared in constant time (subtle's ConstantTimeEq); the code states no other timing.

The master secret is a Secret; the share values and points wipe on drop.

Limits

Secrets of 16 to 32 bytes of even length.

An iteration exponent above 5 is refused before any PBKDF2 round.

A group threshold of 1 over several groups is refused when splitting.

A wrong passphrase opens a different wallet: the passphrase is not a check.

Faraday's own calls

Shares with an iteration exponent above 5 are refused; a split writes exponent 1 with the extendable flag set. Conservative, F90.

A split with a group threshold of 1 over several groups is refused. Conservative, F90.

Secrets above 256 bits are refused. Conservative, F155.

The split's randomness is taken from the session's randomness, an answer for every 32 bytes; SLIP-0039 does not say where a split's randomness comes from. Neutral, F154.

Split with Seed XOR

SpecificationSeed XOR · BIP 39PublishedCodeLibrary: sha2 0.11 (through core/faraday-crypto)Library: unicode-normalization 0.1 (through core/faraday-bip)Faraday's code: core/faraday-entropyFaraday's own codeCross-checked withColdcard's xor and xor_splitOthers' codeFaraday's second version
Action

Splits a seed into Seed XOR parts, each a BIP 39 mnemonic, and combines parts into the seed.

Specification

Seed XOR, Seed XOR, Coldcard's split of a seed into parts, Convention, vendored

BIP 39, Mnemonic code for generating deterministic keys, Deployed

Code

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Library: unicode-normalization 0.1.25, by the unicode-rs developers, through core/faraday-bip.

Faraday's code: core/faraday-entropy: The bitwise XOR of the parts' entropy; the random parts are taken in turn, the seed's length each, from 32 fresh bytes for each random part; every part is a valid mnemonic of the same word count.

Written by Faraday

Seed XOR (faraday-entropy::xor) · Only the part used is written

Faraday writes only the few lines the standard needs, over standard XOR.

Decision F178

Checked against

tools/vectors/xor

Published, by Coldcard's docs/seed-xor.md, by Coinkite. Faraday's own known answers: the two-part and three-part files, made from the definition of Seed XOR.

core/faraday-entropy/tests/xor.rs::twelve_words_in_two_parts_combine_into_the_seed

core/faraday-entropy/tests/xor.rs::twenty_four_words_in_three_parts_combine_into_the_seed

no fuzz target: The parts are BIP 39 mnemonics read by the BIP 39 reader before they combine; bip39_words fuzzes that

Cross-check

Compared with others' code: Coldcard's xor and xor_split, by Coinkite, over python-mnemonic, by Trezor (SatoshiLabs).

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the count of parts (2 to 4) and the five BIP-39 lengths, Faraday's rule written in area_xor.py in front of Coldcard's xor, which asserts only equal lengths.

Area xor

Faraday's code faraday_entropy::SeedXor with faraday_bip::bip39

Compared with Coldcard's own xor and xor_split (coldcard/, unchanged) with python-mnemonic (bip39/) for the words.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; the count of parts (2 to 4) and the five BIP-39 lengths are Faraday's rule, written in the area in front of Coldcard's xor, which asserts only equal lengths.

Vectors Coldcard's two examples (tools/vectors/xor/coldcard.json) and this tree's two.

Random cases Splits and combines in all ten languages and five lengths, with refusals; parts made by Coldcard's xor_split read back to their seed.

Differences None known.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 40000 cases

Secret handling

Reveal::PaperForm

Not stated by the code.

The parts' accumulator zeroizes on drop and the parts handed out are zeroizing strings.

Limits

Two to four parts; one part alone is the seed itself.

Every part is needed: XOR is not a threshold scheme.

Faraday's own calls

none

Write a backup stick file

SpecificationBIP 39 · SeedQR · BIP 93PublishedCodeFaraday's code: faraday/faraday-coreFaraday's own codeCross-checked withzbarOthers' code
Action

Makes the file a backup stick holds for a key: its words or passphrase as one line, its SeedQR as a labelled picture, a codex32 string as one line or as a Codex32QR picture.

Specification

BIP 39, Mnemonic code for generating deterministic keys, Deployed

SeedQR, SeedQR and CompactSeedQR, Convention, vendored

BIP 93, codex32: Checksummed SSS-able BIP32 Seeds, Draft, vendored

Code

Faraday's code: faraday/faraday-core: Each secret is lent by faraday-keys for the reason BackupStick, which names the part (words, passphrase, SeedQR or codex32), and written into a zeroizing buffer; the words and the passphrase are one line each; the SeedQR is made by the SeedQR encoder and drawn as a labelled picture.

Written by Faraday

FAT16 and FAT32, read and written (faraday-fat) · No established implementation exists

No FAT library comes from a publisher Faraday's dependency review trusts.

Carries a format; it computes nothing on a key.

Decision F180

Checked against

not checked against vectors

faraday/faraday-core/tests/all/backup_flow_wallet.rs::a_seed_let_out_unprotected_is_written_to_the_stick_of_files_and_to_no_other

faraday/faraday-core/tests/all/backup_flow_wallet.rs::only_this_wallets_seed_files_go_to_the_stick_of_files_and_public_files_have_their_own

faraday/faraday-core/tests/all/backup_flow_wallet.rs::a_seed_kept_only_as_a_file_is_held_until_its_stick_is_written

faraday/faraday-core/tests/all/save_without_encryption.rs::a_seed_file_placed_on_a_stick_asks_the_hold_once_and_cancel_leaves_it_off

no fuzz target: Takes a held key and a form; no outside input is parsed

Cross-check

Compared with others' code: zbar, by the zbar developers, and zxing-cpp, by the zxing-cpp developers, which decode each picture this writes and whose payload is compared with the key's words.

Area seedqr

Faraday's code faraday_codec::seedqr (SeedQR, CompactSeedQR), faraday_codec::qr, the encoder that draws them, and faraday_codec::qr::codex32qr with the picture faraday_core::picture writes of it

Compared with SeedSigner's own encoders and DecodeQR (seedsigner/, unchanged, with embit's BIP-39 code in embit/); Project Nayuki's qrcodegen.py (qrcodegen/), module for module; segno 1.6 (python3-segno), an encoder of another lineage, at Faraday's mask and at its own; Pillow and CPython's zlib, which read every PNG Faraday writes; zbar (zbarimg) and zxing-cpp, which decode the QR code in every picture and return its payload as bytes (qr_decode.py).

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; SeedSigner's reader is looser than Faraday (it takes 49 digits, a sign inside a group, 20 to 28 bytes, and does not check the checksum of digits), so Faraday's own rule, the lengths and the digits, stands in front of it in area_seedqr.py and the checksum is embit's; SeedSigner runs in English for every language, the indices being the same; the profile's own pictures are read from their pixels and must be Faraday's code module for module; segno is asked for Faraday's version, level and mode and its mask forced, and its mask is read back from it, its padding quirk being modelled in Nayuki's code; rqrr reads Faraday's and segno's codes; the self-test makes each decoder's answer wrong (a payload's last byte changed) and must catch it.

An empty payload, which segno refuses.

Vectors SeedSigner's nine test SeedQRs (tools/vectors/seedqr/); every string and picture of the Codex32QR profile (tools/vectors/codex32qr/), each decoded by zbar and zxing-cpp.

Random cases Keys of every length and language, both codes and the words read back; digits and bytes malformed; payloads in each mode at each level and version limit; 48-character codex32 strings in either case as Codex32QR codes and the pictures written of them read back and decoded by zbar and zxing-cpp, other lengths refused; the pictures of a key's SeedQR and CompactSeedQR decoded by both and read by Faraday to the key's words; greyscale pictures and QR pictures of random size and scale read by Pillow and zlib.

Differences SeedQR digits: SeedSigner reads a string with 1 to 3 digits more than 48 or 96 (it drops the tail) and one with a sign or a space inside a group of four (int() takes them); Faraday refuses both (5 cases, each checked on both sides and counted). SeedSigner takes no CompactSeedQR of 20, 24 or 28 bytes either, and strips checksum bits for 12 and 24 words only; the corpus keeps Faraday's 15, 18 and 21 word compact form on the entropy itself.

Codex32QR: Faraday picks the mask Nayuki's encoder picks; the profile's encoder chose another for 6 of its 22 pictures. For those the area swaps the mask of Faraday's code for the picture's with qrcodegen.py's masking, requires the picture, and counts it.

Segno 1.6 writes a zero codeword where the pad codewords begin when the data, terminator included, ends on a codeword boundary with room left (its write_padding_bits adds 8 zero bits where none are due; ISO/IEC 18004 7.4.10 adds none): its code is Nayuki's with that codeword changed, which rqrr reads, counted as a known difference, the padding; Faraday's is the standard's.

Segno picks a mask by its own penalty rule, and for some payloads another than Nayuki's and Faraday's; the area requires that code to be Faraday's under the mask segno reports (Nayuki's masking swapped to it) and rqrr to read it, and counts each as a known difference, the mask choice, which a reader ignores.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 8000 cases

Source

0.2.0 · faraday/faraday-core/src/backup_flow/wallet.rs · Faraday::seed_stick_bytes

0.2.0 · faraday/faraday-core/src/backups/mod.rs · Faraday::codex32_stick_bytes

github.com/bitcoinpasada/faraday

Secret handling

Reveal::BackupStick

Not applicable: the secret is copied into a file's bytes, not compared or computed on here.

The file's bytes are a zeroizing buffer, and the pixels drawn for a picture are wiped once it is made.

Limits

A SeedQR file is made for English words only.

A key with no words gets no words file, and a key with no passphrase no passphrase file.

A codex32 string this session does not hold gets no file.

Faraday's own calls

A secret goes to a stick only for the backup-stick reason, and only the part that reason names. Conservative.

no decision

Make a key's secret files

SpecificationBIP 39 · SeedQRPublishedCodeFaraday's code: faraday/faraday-coreCross-checked withzbarOthers' code
Action

Makes a key's words file and its SeedQR picture, standard or compact, for the secret sheet to save to the Outbox unprotected.

Specification

BIP 39, Mnemonic code for generating deterministic keys, Deployed

SeedQR, SeedQR and CompactSeedQR, Convention, vendored

Code

Faraday's code: faraday/faraday-core: The words are lent by faraday-keys for the reason OutboxFile and written as one line, as Add a key and other signers read them; a SeedQR picture is added for English words only, and only where the plan copies the seed as a SeedQR, titled with the key's fingerprint; the sheet's warning differs for a wallet that needs more than one key, and says how many more keys whoever holds the file needs.

Checked against

not checked against vectors

faraday/faraday-core/tests/all/seed_backup.rs::the_unprotected_button_does_nothing_until_the_hold

faraday/faraday-core/tests/all/seed_backup.rs::cancelling_the_sheet_lets_nothing_out

faraday/faraday-core/tests/all/seed_backup.rs::the_seedqr_picture_scans_back_as_the_same_key_standard_and_compact

faraday/faraday-core/tests/all/seed_backup.rs::the_words_file_read_from_a_stick_loads_the_same_key

faraday/faraday-core/tests/all/seed_backup.rs::no_file_holds_the_passphrase

faraday/faraday-core/tests/all/save_without_encryption.rs::unprotected_writes_nothing_until_the_hold_is_held_to_its_end

faraday/faraday-core/tests/all/save_without_encryption.rs::cancel_on_the_hold_sends_nothing_out

no fuzz target: Takes a held key and a form; no outside input is parsed

Cross-check

Compared with others' code: zbar, by the zbar developers, and zxing-cpp, by the zxing-cpp developers, which decode the picture this writes and whose payload is compared with the key's words.

Area seedqr

Faraday's code faraday_codec::seedqr (SeedQR, CompactSeedQR), faraday_codec::qr, the encoder that draws them, and faraday_codec::qr::codex32qr with the picture faraday_core::picture writes of it

Compared with SeedSigner's own encoders and DecodeQR (seedsigner/, unchanged, with embit's BIP-39 code in embit/); Project Nayuki's qrcodegen.py (qrcodegen/), module for module; segno 1.6 (python3-segno), an encoder of another lineage, at Faraday's mask and at its own; Pillow and CPython's zlib, which read every PNG Faraday writes; zbar (zbarimg) and zxing-cpp, which decode the QR code in every picture and return its payload as bytes (qr_decode.py).

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; SeedSigner's reader is looser than Faraday (it takes 49 digits, a sign inside a group, 20 to 28 bytes, and does not check the checksum of digits), so Faraday's own rule, the lengths and the digits, stands in front of it in area_seedqr.py and the checksum is embit's; SeedSigner runs in English for every language, the indices being the same; the profile's own pictures are read from their pixels and must be Faraday's code module for module; segno is asked for Faraday's version, level and mode and its mask forced, and its mask is read back from it, its padding quirk being modelled in Nayuki's code; rqrr reads Faraday's and segno's codes; the self-test makes each decoder's answer wrong (a payload's last byte changed) and must catch it.

An empty payload, which segno refuses.

Vectors SeedSigner's nine test SeedQRs (tools/vectors/seedqr/); every string and picture of the Codex32QR profile (tools/vectors/codex32qr/), each decoded by zbar and zxing-cpp.

Random cases Keys of every length and language, both codes and the words read back; digits and bytes malformed; payloads in each mode at each level and version limit; 48-character codex32 strings in either case as Codex32QR codes and the pictures written of them read back and decoded by zbar and zxing-cpp, other lengths refused; the pictures of a key's SeedQR and CompactSeedQR decoded by both and read by Faraday to the key's words; greyscale pictures and QR pictures of random size and scale read by Pillow and zlib.

Differences SeedQR digits: SeedSigner reads a string with 1 to 3 digits more than 48 or 96 (it drops the tail) and one with a sign or a space inside a group of four (int() takes them); Faraday refuses both (5 cases, each checked on both sides and counted). SeedSigner takes no CompactSeedQR of 20, 24 or 28 bytes either, and strips checksum bits for 12 and 24 words only; the corpus keeps Faraday's 15, 18 and 21 word compact form on the entropy itself.

Codex32QR: Faraday picks the mask Nayuki's encoder picks; the profile's encoder chose another for 6 of its 22 pictures. For those the area swaps the mask of Faraday's code for the picture's with qrcodegen.py's masking, requires the picture, and counts it.

Segno 1.6 writes a zero codeword where the pad codewords begin when the data, terminator included, ends on a codeword boundary with room left (its write_padding_bits adds 8 zero bits where none are due; ISO/IEC 18004 7.4.10 adds none): its code is Nayuki's with that codeword changed, which rqrr reads, counted as a known difference, the padding; Faraday's is the standard's.

Segno picks a mask by its own penalty rule, and for some payloads another than Nayuki's and Faraday's; the area requires that code to be Faraday's under the mask segno reports (Nayuki's masking swapped to it) and rqrr to read it, and counts each as a known difference, the mask choice, which a reader ignores.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 8000 cases

Secret handling

Reveal::OutboxFile

Not applicable: the words are copied into a file's bytes, not compared or computed on here.

The words and the file's bytes are zeroizing buffers, and the pixels drawn for a picture are wiped once it is made.

Limits

No file holds the passphrase: the words file and the SeedQR picture carry the words alone.

A key with no words is offered nothing.

A SeedQR picture is made for English words only.

Faraday's own calls

Nothing is written to the Outbox until the hold on the secret sheet is held to its end. Conservative.

no decision

Recognise a secret in a file

SpecificationBIP 39 · BIP 93 · SLIP-0039 · 1 morePublishedCodeLibrary: bitcoin 0.32Library: sha2 0.11 (through core/faraday-crypto)Library: unicode-normalization 0.1 (through core/faraday-bip)Faraday's code: faraday/faraday-coreCross-checked withNot cross-checked
Action

Recognises a seed or a private key in a file, a scan or pasted text, works out the fingerprint of its key, and refuses a secret where one may not go.

Specification

BIP 39, Mnemonic code for generating deterministic keys, Deployed

BIP 93, codex32: Checksummed SSS-able BIP32 Seeds, Draft, vendored

SLIP-0039, Shamir's Secret-Sharing for Mnemonic Codes, Status not checked, vendored

BIP 32, Hierarchical Deterministic Wallets, Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Library: unicode-normalization 0.1.25, by the unicode-rs developers, through core/faraday-bip.

Faraday's code: faraday/faraday-core: A words file is read in whichever BIP 39 word list it is in, checksum included; SLIP-39 shares and codex32 strings are gathered from their files and the codex32 seed is recovered from them. The fingerprint is that of the master key, with the passphrase a passphrase file or the person brings, and is kept by a memo keyed by SHA-256 of a tag and the secret, so the secret is kept nowhere. Pasted text is refused when it is words of any list, checksum or not, a SeedQR's 48 or 96 digits, an extended private key, a WIF key, a codex32 string or a SLIP-39 share; a scanner that loads a seed refuses only a private key.

Checked against

not checked against vectors

faraday/faraday-core/tests/all/inbox_found.rs::a_seed_in_several_backups_is_one_seed

faraday/faraday-core/tests/all/inbox_found.rs::a_passphrase_makes_the_potential_wallet_another_key

faraday/faraday-core/tests/all/inbox_found.rs::codex32_strings_count_once_they_add_up

faraday/faraday-core/tests/all/inbox_found.rs::slip39_shares_count_once_they_add_up

faraday/faraday-core/tests/all/paste_a_seed.rs::a_private_key_pasted_into_a_seed_scanner_is_still_refused

faraday/faraday-core/tests/all/paste_a_seed.rs::seed_words_pasted_into_a_scanner_that_takes_no_seed_are_refused

faraday/faraday-core/tests/all/stick_copy.rs::a_gpg_private_key_block_is_still_offered_as_something_that_may_be_a_secret

no fuzz target: No fuzz target reads a file as a seed; the readers it calls (words, codex32 and SLIP-39 strings) have their own

Cross-check

not cross-checked: The key a seed makes is checked by the bip39, bip32, codex32 and slip39 areas; the recognising of files and pasted text has no second implementation

Secret handling

none: no secret leaves faraday-keys

Not stated; the seed and master key functions it calls state their own.

The text of a file read as a secret and the words made from it are zeroizing; a file that may hold a secret is dropped from the Inbox at a lock.

Limits

Text of a seed's words is read only if the words are in a BIP 39 list and their checksum holds.

A scanner that loads a seed takes the seed's own forms and refuses a private key.

Faraday's own calls

A secret pasted or scanned where a secret may not go is refused, whatever its form. Conservative.

no decision

Derived keys and tools

11 actions · 4 with Faraday's own code · 11 cross-checked with others' code · 4 with Faraday's second version

Hash and authenticate bytes

SpecificationFIPS 180-4 · RFC 2104 · RFC 4231 · 2 morePublishedCodeLibrary: sha2 0.11Library: hmac 0.13Library: pbkdf2 0.13Faraday's code: core/faraday-cryptoCross-checked withPython's hmac and hashlib.pbkdf2_hmac (OpenSSL) for HMAC and PBKDF2Others' code
Action

Hashes and authenticates bytes with SHA-256, HMAC-SHA256 and HMAC-SHA512, and stretches a password with PBKDF2.

Specification

FIPS 180-4, Secure Hash Standard, Status not checked

RFC 2104, HMAC: Keyed-Hashing for Message Authentication, Status not checked

RFC 4231, Identifiers and Test Vectors for HMAC-SHA-224, HMAC-SHA-256, HMAC-SHA-384, and HMAC-SHA-512, Status not checked

RFC 8018, PKCS #5: Password-Based Cryptography Specification Version 2.1, Status not checked

RFC 7914, The scrypt Password-Based Key Derivation Function, Status not checked

Code

Library: sha2 0.11.0, by the RustCrypto developers.

Library: hmac 0.13.0, by the RustCrypto developers.

Library: pbkdf2 0.13.0, by the RustCrypto developers.

Faraday's code: core/faraday-crypto: Thin wrappers, the one entry point the rest of the core uses, so the choice of crate is confined here; any HMAC key length is accepted; the whole-file SHA-256 and the key-stretching calls count themselves on the compute token. The bip39 area reaches SHA-256 and PBKDF2-HMAC-SHA512 only; HMAC-SHA256 and PBKDF2-HMAC-SHA256 are checked by their RFCs' cases here.

Checked against

not checked against vectors

core/faraday-crypto/tests/primitives.rs::sha256_known_answers

core/faraday-crypto/tests/primitives.rs::hmac_sha512_rfc4231_case_1

core/faraday-crypto/tests/primitives.rs::hmac_sha512_rfc4231_case_2

core/faraday-crypto/tests/primitives.rs::hmac_sha256_rfc4231_case_1

core/faraday-crypto/tests/primitives.rs::hmac_sha256_rfc4231_case_2

core/faraday-crypto/tests/primitives.rs::pbkdf2_hmac_sha512_known_answer

core/faraday-crypto/tests/primitives.rs::pbkdf2_hmac_sha256_rfc7914_known_answers

self-test bip39_vector

no fuzz target: Takes bytes from callers that parse their own input

Cross-check

Compared with others' code: Python's hmac and hashlib.pbkdf2_hmac (OpenSSL) for HMAC and PBKDF2, each over SHA-256 and SHA-512, in area hash.

Area hash

Faraday's code faraday_bip::hashes and faraday_codec::encodings (read, the writers and from_hex), faraday_core::file_menu::sha256, and faraday_crypto::hkdf_sha256 and hkdf_sha256_expand, hmac_sha256, hmac_sha512, pbkdf2_hmac_sha256, pbkdf2_hmac_sha512 and scrypt

Compared with Bitcoin Core v31.1's functional-test framework (core/): ripemd160.py, address.py and segwit_addr.py, with hashlib for SHA-256 and bytes.fromhex for hex; PyCA cryptography's HKDF and HKDFExpand (OpenSSL) for the one HKDF; hmac, hashlib.pbkdf2_hmac and hashlib.scrypt (OpenSSL) for HMAC, PBKDF2 and scrypt.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; the order read tries the spellings in, the trimming of the text, hex as an even number of hex digits, plain Base58 (which Core's framework does not read; the area's own few lines) and which prefixes make a segwit address are Faraday's rules, written in the area in front of the reference.

The file hash is file_menu::sha256 over a whole byte slice (it reads in no buffer, so no read size is probed); the Files screen's reading of a file from a stick is the files areas'.

Vectors FIPS 180-4's SHA-256 examples, RIPEMD-160 of abc, BIP-173's key and its HASH160, Bitcoin Core's first key_io_valid.json address, BIP-173's and BIP-350's bech32 strings and their valid and invalid segwit addresses (tools/vectors/addresses).

Random cases Random bytes of every length from 0 to 130 and to 300 hashed (SHA-256, SHA-256d, HASH160) and as a file, files of 4 KiB, 64 KiB and 1 MiB with a byte more and less; random bytes written and read as Base58Check, Base58, bech32 and bech32m, Core's writing read by Faraday, segwit addresses of every version Core's framework writes, and texts changed, cut or made of random characters read by both.

Differences bech32 groups: a string that is not a segwit address of bc, tb or bcrt is read as bytes, all its data groups together, and the bits that do not fill a byte are dropped. BIP-173 has a padding rule only for a segwit address, so Core's convertbits, which applies it to any data, refuses some of these strings, and the area reads them as Faraday does.

bech32 length: Core's decoder refuses more than 90 characters (BIP-173); Faraday accepts any length the checksum covers. The area reads longer strings the same way.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The wrappers keep no state after they return; wiping an input is the caller's; the sha2 and hmac crates are built with their zeroize feature.

Limits

PBKDF2 here is HMAC-SHA256 or HMAC-SHA512 only.

Faraday's own calls

none

Hash and encode text

SpecificationFIPS 180-4 · BIP 173 · BIP 350 · 2 morePublishedCodeLibrary: bitcoin 0.32Library: sha2 0.11 (through core/faraday-crypto)Library: base16ct 1.0 (through core/faraday-crypto)Faraday's code: core/faraday-bipCross-checked withBitcoin Core v31.1's functional-test frameworkOthers' codeFaraday's second version
Action

Hashes bytes with SHA-256, SHA-256d and HASH160, and reads and writes Base58Check, bech32 and bech32m text.

Specification

FIPS 180-4, Secure Hash Standard, Status not checked

BIP 173, Base32 address format for native v0-16 witness outputs, Deployed

BIP 350, Bech32m Format for v1+ Witness Addresses, Deployed

BIP 380, Output Script Descriptors General Operation, Deployed

Base58Check, Base58Check encoding, as Bitcoin Core writes it, Convention

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-bip: The calculator shows the three hashes of any bytes, says which of Base58, Base58Check, bech32, bech32m or hex a text is, reads a segwit address as its witness version and program, and writes the same bytes in the other spellings.

Checked against

tools/vectors/addresses

Published, by the authors of BIP 173, BIP 350, BIP 380, BIP 49, BIP 84 and BIP 86 (bitcoin/bips).

core/faraday-bip/tests/all/calculators.rs::the_hashes_match_the_published_vectors

core/faraday-codec/tests/encodings.rs::the_bech32_vectors_are_read_the_way_the_standards_say

core/faraday-codec/tests/encodings.rs::a_segwit_address_reads_as_its_witness_version_and_program

core/faraday-codec/tests/encodings.rs::bech32_text_that_is_not_a_segwit_address_has_no_version

core/faraday-codec/src/encodings.rs::bech32_and_bech32m_are_told_apart

core/faraday-codec/src/encodings.rs::a_published_base58check_address_is_written_and_read_as_bitcoin_core_has_it

fuzz encodings

Cross-check

Compared with others' code: Bitcoin Core v31.1's functional-test framework, by Bitcoin Core's contributors (ripemd160.py for HASH160, address.py for Base58Check, segwit_addr.py for bech32 and bech32m), and Python's hashlib (SHA-256 and SHA-256d) and bytes.fromhex (hex).

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: plain Base58 with no checksum, which the framework does not read, the order the spellings are tried in, the trimming of the text, hex as an even number of hex digits only, and which prefixes make a segwit address, in area_hash.py; bech32 text that is not a segwit address is read as all its data groups at any length by Faraday and by the area alike, a stated difference.

Area hash

Faraday's code faraday_bip::hashes and faraday_codec::encodings (read, the writers and from_hex), faraday_core::file_menu::sha256, and faraday_crypto::hkdf_sha256 and hkdf_sha256_expand, hmac_sha256, hmac_sha512, pbkdf2_hmac_sha256, pbkdf2_hmac_sha512 and scrypt

Compared with Bitcoin Core v31.1's functional-test framework (core/): ripemd160.py, address.py and segwit_addr.py, with hashlib for SHA-256 and bytes.fromhex for hex; PyCA cryptography's HKDF and HKDFExpand (OpenSSL) for the one HKDF; hmac, hashlib.pbkdf2_hmac and hashlib.scrypt (OpenSSL) for HMAC, PBKDF2 and scrypt.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; the order read tries the spellings in, the trimming of the text, hex as an even number of hex digits, plain Base58 (which Core's framework does not read; the area's own few lines) and which prefixes make a segwit address are Faraday's rules, written in the area in front of the reference.

The file hash is file_menu::sha256 over a whole byte slice (it reads in no buffer, so no read size is probed); the Files screen's reading of a file from a stick is the files areas'.

Vectors FIPS 180-4's SHA-256 examples, RIPEMD-160 of abc, BIP-173's key and its HASH160, Bitcoin Core's first key_io_valid.json address, BIP-173's and BIP-350's bech32 strings and their valid and invalid segwit addresses (tools/vectors/addresses).

Random cases Random bytes of every length from 0 to 130 and to 300 hashed (SHA-256, SHA-256d, HASH160) and as a file, files of 4 KiB, 64 KiB and 1 MiB with a byte more and less; random bytes written and read as Base58Check, Base58, bech32 and bech32m, Core's writing read by Faraday, segwit addresses of every version Core's framework writes, and texts changed, cut or made of random characters read by both.

Differences bech32 groups: a string that is not a segwit address of bc, tb or bcrt is read as bytes, all its data groups together, and the bits that do not fill a byte are dropped. BIP-173 has a padding rule only for a segwit address, so Core's convertbits, which applies it to any data, refuses some of these strings, and the area reads them as Faraday does.

bech32 length: Core's decoder refuses more than 90 characters (BIP-173); Faraday accepts any length the checksum covers. The area reads longer strings the same way.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Secret handling

none: no secret leaves faraday-keys

Public bytes only; nothing here holds a secret.

Nothing secret is held.

Limits

A text that is none of the five spellings gives no reading.

Faraday's own calls

none

Derive a child seed

SpecificationBIP 85 · RFC 4648 · RFC 1924PublishedCodeLibrary: bitcoin 0.32Library: base64ct 1.8Library: hmac 0.13 (through core/faraday-crypto)2 moreFaraday's code: core/faraday-bipCross-checked withbtclib-wallet's bip85Others' code
Action

Derives a BIP 85 child (words, a WIF, an extended private key, hex or a password) from a held key.

Specification

BIP 85, Deterministic Entropy From BIP32 Keychains, Deployed, vendored

RFC 4648, The Base16, Base32, and Base64 Data Encodings, Status not checked

RFC 1924, A Compact Representation of IPv6 Addresses (base 85 alphabet), Status not checked

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: base64ct 1.8.3, by the RustCrypto developers.

Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-bip: The path is m/83696968'/app'/params'/index', fully hardened; the derived private key is run through HMAC-SHA512 with the BIP's key; the passwords' base64 (RFC 4648) is the base64ct crate's and their base85 (RFC 1924's alphabet) is written here; every value is a fixed-size buffer that zeroizes on drop and nothing here allocates.

Checked against

tools/vectors/bip85

Published, by BIP 85's authors (bitcoin/bips).

core/faraday-bip/tests/all/bip85.rs::the_published_children_of_application_39

core/faraday-bip/tests/all/bip85.rs::the_published_hd_seed_wif

core/faraday-bip/tests/all/bip85.rs::the_published_extended_private_key

core/faraday-bip/tests/all/bip85.rs::the_published_hex_entropy

core/faraday-bip/tests/all/bip85.rs::the_published_passwords

core/faraday-bip/tests/all/bip85.rs::a_parameter_outside_the_bips_range_is_refused

core/faraday-bip/tests/all/bip85.rs::a_word_count_bip39_does_not_define_is_refused

faraday/faraday-keys/tests/operations.rs::bip85_children_are_the_ones_the_bip_publishes

no fuzz target: Takes a held key, an application and numbers chosen on a pad; no text is parsed

Cross-check

Compared with others' code: btclib-wallet's bip85, by the btclib developers, on btclib's own curve and run as written over bip39_slip39, by the btclib developers; ethankosakovsky/bip85, by Ethan Kosakovsky, over python-mnemonic, by Trezor (SatoshiLabs), and btclib through a pycoin shim.

Area bip85

Faraday's code faraday_bip::bip85

Compared with btclib-wallet's bip85 (btclib/, on btclib's own curve) run as written over bip39_slip39 (bip39-slip39/); and ethankosakovsky/bip85 over python-mnemonic and a pycoin shim whose every call is btclib's (bip85/, bip39/).

Checked first: Their vendored files and wheels are hashed against references.sha256 before any run, and a published vector's answer is required of each reference as well as of Faraday.

The BIP's reference is not asked the passwords, which it does not have, nor hex bytes of a length outside the BIP's range, which it does not refuse: btclib alone answers those.

Vectors Every application vector of tools/vectors/bip85/.

Random cases Random master keys, indices, languages, word counts and lengths, with refusals.

Differences None known.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Secret handling

Reveal::Bip85Child

The password's base64 is the base64ct crate's, which documents its encoding as constant time with respect to the data; its base85 is shown (§4.10).

The derived private key and the 64 bytes are zeroized before the function returns, and every value returned is a buffer that zeroizes on drop. The copies bitcoin makes inside derivation are freed unwiped, until the next lock (ESTABLISHED §4.8).

Limits

Applications 2', 32', 39', 128169', 707764' and 707785' only; no DICE, RSA or Nostr 128002'.

Hex is 16 to 64 bytes, a base64 password 20 to 86 characters, a base85 password 10 to 80.

An index of 2^31 or more is refused.

Faraday's own calls

Nostr keys by application 128002' are not built. Neutral, F27.

Grind a vanity address

SpecificationEntropyLab vanity counterPublishedCodeLibrary: bitcoin 0.32Library: secp256k1 0.29Faraday's code: core/faraday-bipCross-checked withpython-mnemonicOthers' codeFaraday's second version
Action

Grinds a counter on a key's passphrase or account index until its first address begins with the characters chosen.

Specification

EntropyLab vanity counter, EntropyLab vanity-wasm counter, Convention

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).

Faraday's code: core/faraday-bip: Nothing is random: the counter is written in EntropyLab's alphabet and odometer order, width by width, so a find here is the same find there; one passphrase candidate costs one PBKDF2, one account candidate one hardened derivation.

Checked against

not checked against vectors

core/faraday-bip/tests/all/vanity.rs::the_passphrase_counter_reaches_the_address_entropylab_reaches

core/faraday-bip/tests/all/vanity.rs::the_account_index_reaches_the_address_entropylab_reaches

core/faraday-bip/tests/all/vanity.rs::the_passphrase_a_find_names_is_the_passphrase_that_makes_the_address

core/faraday-bip/tests/all/vanity.rs::a_grind_that_stops_and_goes_on_reaches_the_same_candidate

core/faraday-bip/tests/all/vanity.rs::a_prefix_asks_only_for_characters_an_address_of_that_kind_can_carry

faraday/faraday-core/tests/all/vanity.rs::the_passphrase_dial_loads_the_words_with_the_passphrase_found

no fuzz target: Takes a prefix typed on a pad and a held key; no outside text is parsed

Cross-check

Compared with others' code: python-mnemonic, by Trezor (SatoshiLabs), Bitcoin Core v31.1 (deriveaddresses), by the Bitcoin Core developers, and btclib, by the btclib developers, which derives each candidate's child keys on its own curve (Core judges the script and the address text only, and shares libsecp256k1's curve maths with Faraday's).

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: EntropyLab's counter, the prefix rules, the expected work and the search loop, written out in area_vanity.py from a quotation.

Area vanity

Faraday's code faraday_bip::vanity (the counter, prefixes and their expected work, the search on both dials, for the four script types and a silent payment code)

Compared with EntropyLab's counter as tools/reference/vanity/README.md quotes it, written out in area_vanity.py over python-mnemonic, each candidate's child key derived by btclib on its own curve, and its address by Bitcoin Core v31.1 for the script and address text only (deriveaddresses on regtest, from the bare key) and Core's framework, as the addr area writes it; a silent payment code by the BIP-352 reference's own bech32m from btclib's keys at BIP-352's paths.

Checked first: The search is written in the area from the README's quotation of EntropyLab's counter, and EntropyLab's two finds are required of it as well as of Faraday.

Vectors EntropyLab's two finds.

Random cases Counters at every width's edges; prefixes of every kind on every network, valid and not; searches of random keys on both dials from random starting counters, with budgets ending before a match and after.

Differences Each candidate's child key is derived by btclib on its own curve, not by Bitcoin Core, which shares libsecp256k1's curve maths with Faraday; Core is given the bare key and judges the script and the address text only.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 2000 cases

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The counter's buffer zeroizes on drop; each candidate's passphrase buffer and derived private keys are zeroized or erased after use.

Limits

The counter is at most 8 characters wide.

A prefix may hold only characters an address of that kind can carry.

Faraday's own calls

A passphrase found by grinding becomes key material to back up; the account dial gives a non-zero account. Neutral.

no decision

Read an aezeed

SpecificationLND aezeed · RFC 7914PublishedCodeLibrary: aes 0.9Library: blake2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-bipFaraday's own codeCross-checked withLightning Labs (LND)Others' code
Action

Reads an LND aezeed: 24 words, checksum, scrypt key and AEZ decipher, giving the entropy, version and birthday; a scanner tells one apart by its version and checksum alone.

Specification

LND aezeed, LND cipher seed (aezeed) with AEZ v5, Convention

RFC 7914, The scrypt Password-Based Key Derivation Function, Status not checked

Code

Library: aes 0.9.3, by the RustCrypto developers.

Library: blake2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-bip: AEZ v5 is written here, over the aes crate's AES round; the words are 24 x 11 bits with a CRC-32C checked before scrypt (N 32768, r 8, p 1) runs; reading only: an aezeed is never made, and never loaded as a key.

Written by Faraday

AEZ v5 and aezeed, with aezeed's CRC-32C (faraday-bip::aez, faraday-bip::aezeed) · No established implementation exists

No maintained Rust implementation of AEZ exists; Faraday's follows the Go code LND uses and is tested against LND's vectors. Its AES round is the aes crate's and its BLAKE2b the blake2 crate's.

Decision F178

Checked against

tools/vectors/aezeed

Published, by LND's aezeed test package, by Lightning Labs; the node keys computed with LND's and ldk-node's code, as tools/reference/aezeed/README.md records.

core/faraday-bip/src/aezeed.rs::lnd_vectors_decode_to_their_entropy_version_and_birthday

core/faraday-bip/src/aezeed.rs::a_wrong_passphrase_is_refused_and_a_wrong_word_is_caught_first

core/faraday-bip/src/aezeed.rs::lnd_vectors_are_told_apart_by_their_checksum_and_a_changed_word_is_not

core/faraday-bip/tests/all/aez.rs::extract_vectors

core/faraday-bip/tests/all/aez.rs::hash_vectors

core/faraday-bip/tests/all/aez.rs::prf_vectors

core/faraday-bip/tests/all/aez.rs::encrypt_vectors

fuzz aezeed

Cross-check

Compared with others' code: Lightning Labs (LND), Yawning Angel (AEZ): compared with the processor's AES round on both sides and again with the aes crate's software round against Yawning Angel's AEZ built without assembly.

Area lightning

Faraday's code faraday_bip::aezeed (ldk-node's and LND's node keys, the aezeed read), faraday_codec::bolt11::decode (a BOLT #11 invoice read), faraday_codec::bolt12::decode (a BOLT #12 offer read), faraday_keys::hsm_secret (Core Lightning's node key from its hsm_secret, plain encrypted or the mnemonic form, and from BIP-39 words)

Compared with LND's own code, vendored in Go (tools/reference/lnd/: its aezeed package over Yawning Angel's aez, and the node key over btcd's hdkeychain), one process answering the run's requests (the aezeed also asked of a second build of each side, Faraday's with the aes crate's software round and LND's without assembly); ldk-node's derivation as tools/reference/aezeed/README.md quotes it, written out in area_lightning.py over btclib's BIP-32 (btclib/, on btclib's own curve); for invoices, the bolt11 package by lnbits (2.2.0, tools/reference/bolt11/: its wheels over the bech32, base58 and bitstring packages, with a stand-in for its libsecp256k1 binding coincurve written over btclib's curve), and invoices written in bolt11_enc.py from BOLT #11 and signed with btclib; for offers, Core Lightning's own offer decoder, devtools/bolt12-cli built from its source release by its own configure and make (tools/reference/bolt12/), and offers written in bolt12_enc.py from BOLT #12; Core Lightning's code (tools/reference/cln/: ccan's HKDF-SHA256 compiled as it is, and its common/hsm_secret.c functions written out over the system libsodium, the BIP-39 words and seed of the mnemonic form from python-mnemonic), one process answering the run's requests.

Checked first: LND's code reads the aezeed (wordlist, version, CRC-32C, scrypt, AEZ) and derives the node key, and its published answers (tools/vectors/aezeed/) are required of it as well as of Faraday; the Go program is built offline from the vendored tree (GOFLAGS=-mod=vendor, GOTOOLCHAIN=local) and its version is written into the stamp; the area stops when the program is missing; the software-round pass runs only on programs soft.py has checked to be soft (the tags noasm and purego; no AES-NI instruction in Faraday's command) and the command says it was built soft; ldk-node's derivation is written in the area from the sources the README quotes, and ldk's published answers are required of it as well as of Faraday; the bolt11 package's wheels and its stand-in are hashed against references.sha256 before any run, and each of BOLT #11's 31 published examples is required to be read by Faraday as the BOLT says (a valid one read, an invalid one refused), the package reading the valid ones to the same fields; Core Lightning's HKDF is its compiled code, its salt, limits and calls are those of hsm_secret.c, libsodium itself seals and opens the file, and Core Lightning's two published node ids for words are required of it as well as of Faraday; the area stops when the program is missing and the stamp records libsodium's version; Core Lightning's release archive is hashed against tools/reference/bolt12/release.pin by the fetch and again by every build, the area stops when bolt12-cli is missing, and each of the BOLT #12 vectors is required to be read by Faraday as the vector says (a valid one read, an invalid one refused) and read by Core Lightning's decoder to the same fields where Faraday reads it.

ldk-node's node key is compared with a derivation written here, not with ldk's code (Rust, not vendored): only ldk's five published answers are outside it; LND's key path numbers are written in the Go program from keychain/derivation.go, as LND derives through btcwallet, which is not vendored; the bolt11 package is not asked the fields it does not read (fields BOLT #11 does not define, a fallback of a witness version above 16, a second or later fallback), which are compared with the writer's own list; its signature check runs on btclib's curve, not libsecp256k1's, and refuses a high-S signature as libsecp256k1 does; hsm_secret.c itself is not compiled (it needs tal and libwally): its functions are written out in main.c, and for the mnemonic form libwally's two answers, whether the words validate and their BIP-39 seed, are python-mnemonic's, which takes 12 to 24 words and normalises the words and passphrase (NFKD) where libwally takes 27 and 30 words too and normalises nothing, so the area judges only English 12 to 24-word ASCII cases and Faraday refuses 27 and 30 words (F228); a NUL in the mnemonic form's words is not compared (Core Lightning reads the text up to it, Faraday refuses the file); the words' derivation (lightning-hsmtool generatehsm) is BIP-39's seed, whose first 32 bytes are taken by both sides here; Core Lightning's bolt12-cli reads one Bech32 string, so the area takes out a + between two Bech32 characters and the white space after it, and a lightning: prefix, before asking it, and a text with a NUL byte cannot be given to it (Faraday refuses it); its output is read as text (a short channel id as BxTxO/direction, chain hashes reversed).

Vectors LND's five cipher seeds, LND's two node keys, ldk's five node ids (tools/vectors/aezeed/); BOLT #11's 31 examples, valid and invalid (tools/vectors/lightning-bolt11/); BOLT #12's 53 offer vectors and 12 format strings, valid and invalid (tools/vectors/lightning-bolt12/).

Random cases Random BIP-39 seeds and entropies on every network; every aezeed case again with the aes crate's software round against LND's AEZ without assembly; random words, a wrong version with a right checksum, published seeds under a changed passphrase, a changed enciphered byte or salt with the checksum put right, a changed word, each refused by LND's code; 150 invoices written with every kind of field (amounts in every multiplier, description or its hash, payee key, expiry, final cltv, fallbacks of every version, route hints, features, metadata, fields BOLT #11 does not define) and signed, read by Faraday and by the package field by field, then each with one Bech32 character changed, with one letter in upper case, and with two of these spoiled: a repeated p or x, a wrong-length p, s, h or n, no p, no s, both or neither of d and h, an unknown required feature, a leading zero value in a longer x, c or 9, a leading zero or a fraction of a millisatoshi in the amount, a bad multiplier, an unknown network, a high-S signature, a field cut short, a text over 1023 characters, a description that is not UTF-8; for Core Lightning, random plain and encrypted hsm_secrets under random passphrases (opened by Faraday and by libsodium, node ids compared), a secret sealed by libsodium and opened by Faraday and by Core Lightning's functions, a changed byte, a wrong passphrase and a wrong length each refused by both, random mnemonic-form files with and without a passphrase (node ids compared; a wrong passphrase, a passphrase the file does not have and broken words each refused by both), and random BIP-39 words with a passphrase; 250 rounds of BOLT #12 offers, each an offer written with every kind of field (chains, metadata, a currency or an amount in millisatoshis, description, features, expiry, blinded paths, issuer, quantity, issuer id, unknown odd fields; + joins, upper case and a lightning: prefix) read by Faraday and by Core Lightning's decoder field by field and by the writer's own record, then one with a Bech32 character changed, one in mixed case, and three of thirty-eight spoils: types out of order or repeated, a field cut short or longer than the stream, a BigSize, truncated integer or feature field not minimal, a type outside the offer's ranges or an unknown even one, a text that is not BOLT #1's, an amount without a description, of zero, or a currency without an amount, no issuer id and no path, a path of no hops or a bad point, chains empty or of a wrong length, padding of more than four bits, a bad +, a wrong prefix, characters outside Bech32, and F232's stricter cases (a text over 4,296 characters, a non-zero padding bit, a chain twice or none known, a currency not in ISO 4217, an amount above 21 million bitcoin, an expiry past the year 9999, a first node byte that is no key, an unassigned character).

Differences BOLT #11 invoices: the package skips a p, h, s or n field of the wrong length, reads the first of a repeated p or s, and accepts both or neither of a description and its hash, mixed case, an amount finer than a millisatoshi and a leading zero value in x, c or 9, all of which BOLT #11 makes a refusal or says "should" of and Faraday refuses; it also accepts what BOLT #11 leaves open, which Faraday is stricter on: a repeated x, c, m, 9, d, h or n, a text over 1023 characters, an amount with a leading zero, and a required feature bit Faraday does not know; the area counts each refusal as known, naming its reason.

BOLT #11 route hints: the package reads a hop's fees and delta as signed integers (a fee above 2^31 reads negative); the area reads them modulo 2^32 and 2^16 before comparing, and keeps a hint to three hops, as the package drops the last hop of a hint of a multiple of five.

BOLT #11 fallbacks: the package reads only the first fallback address and writes the others in bech32 for every witness version, no bech32m; the area compares Faraday's whole list of fallbacks with the writer's f fields of versions 0 to 18, in order, and its fields of an unknown version by the writer's list.

BOLT #11 features: the package keeps one state per feature, so a feature with both its required and its supported bit set reads as supported only; the writer sets one bit of each pair.

BOLT #12 offers: Core Lightning's bolt12-cli passes the decoder no feature set, so it reads an offer with an even feature bit that Faraday refuses (BOLT #9 defines no offer feature); it also reads feature bytes with a leading zero byte, which BOLT #9 makes not minimal, and a description, issuer or currency holding a character of Unicode's Cc, Cf, Co, Zl or Zp categories, which BOLT #1 refuses and Faraday refuses; and it refuses what Faraday reads when the currency is missing from its ISO 4217 table (the list of 2018) or an amount in bitcoin has a first chain Faraday does not know (it names the unit by the first chain alone), which Faraday reads as BOLT #12 says; the area counts each as known, naming the reason, and every other difference fails the run.

BOLT #12 offers, F232's stricter cases: Faraday refuses what Core Lightning reads (a text over 4,296 characters, a non-zero padding bit, whitespace after a + that is not a space, tab or line break, a chain twice, no known chain, a currency not in the ISO 4217 list Faraday holds, an amount over 21 million bitcoin, an expiry past the year 9999, a first node that is no key, an unassigned character); the area requires Faraday's refusal and counts it as known.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 14060 cases

Secret handling

none: no secret leaves faraday-keys

AEZ's AES round is the aes crate's, which documents every backend as designed to run in constant time; the rest of AEZ is XOR, shifts and loops of fixed length, and the words are packed without a branch on their bits; the code states no other timing.

The deciphered entropy is held in a Secret that zeroizes on drop; the word bytes and the inner seed buffer are zeroized after use.

Limits

Version 0 only; a seed of another version or a failed checksum is refused before scrypt.

Reading only.

Faraday's own calls

aezeed and AEZ are written here; the cross-check asks LND's own Go aezeed package, over Yawning Angel's AEZ, the same words and passphrases and requires the same answers or refusals, once with the processor's AES round on both sides and once with the aes crate's software round against AEZ built without assembly. Neutral.

no decision

Read a Core Lightning hsm_secret

SpecificationCore Lightning hsm_secret · BIP 39PublishedCodeLibrary: argon2 0.6Library: chacha20 0.10Library: poly1305 0.91 moreFaraday's code: faraday/faraday-keysFaraday's own codeCross-checked withBlockstream and the Core Lightning developers (ccan's HKDF-SHA256Others' code
Action

Reads Core Lightning's hsm_secret, the plain 32 bytes, the 73 bytes encrypted under a passphrase, or the mnemonic form (a passphrase hash, then English BIP-39 words), or BIP-39 words as lightning-hsmtool generatehsm makes it, and gives the node key hsmd derives.

Specification

Core Lightning hsm_secret, Core Lightning's hsm_secret, plain or encrypted, and its node key, Convention

BIP 39, Mnemonic code for generating deterministic keys, Deployed

Code

Library: argon2 0.6.0, by the RustCrypto developers.

Library: chacha20 0.10.2, by the RustCrypto developers.

Library: poly1305 0.9.1, by the RustCrypto developers.

Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: faraday/faraday-keys: A 73-byte file is a 24-byte header and 49 bytes of ciphertext; the key is Argon2id of the passphrase with Core Lightning's salt and libsodium's moderate limits, and libsodium's secretstream pulls one message of it; the node key is HKDF-SHA256 of the 32 bytes with info nodeid and a 4-byte salt counting from 0, retried while it is not a valid key. The mnemonic form is a 32-byte hash (zero without a passphrase, else the SHA-256 of the 64-byte BIP-39 seed) and English words in single-space form, the node key from the first 32 bytes of the seed; the words come from faraday-bip's BIP-39. Reading only; a file shorter than 32 bytes or longer than the mnemonic form can be is refused.

Written by Faraday

libsodium's crypto_secretstream_xchacha20poly1305 pull of one message (faraday-keys::hsm_secret) · No established implementation exists

No maintained Rust crate offers libsodium's secretstream; Faraday's is HChaCha20, ChaCha20 and Poly1305 of RustCrypto's crates, and is tested against a file libsodium sealed and against libsodium itself.

Decision F228

Checked against

not checked against vectors

faraday/faraday-keys/tests/hsm_secret.rs::lightning_a_plain_hsm_secret_gives_its_node_id

faraday/faraday-keys/tests/hsm_secret.rs::lightning_an_encrypted_hsm_secret_opens_under_its_passphrase

faraday/faraday-keys/tests/hsm_secret.rs::lightning_a_wrong_passphrase_or_a_changed_byte_is_one_refusal

faraday/faraday-keys/tests/hsm_secret.rs::lightning_a_file_shorter_than_32_bytes_or_too_long_is_refused

faraday/faraday-keys/tests/hsm_secret.rs::lightning_a_mnemonic_hsm_secret_gives_the_node_id_core_lightning_has

faraday/faraday-keys/tests/hsm_secret.rs::lightning_a_mnemonic_hsm_secret_with_the_wrong_passphrase_is_refused

faraday/faraday-keys/tests/hsm_secret.rs::lightning_a_mnemonic_hsm_secret_with_broken_words_is_refused

faraday/faraday-keys/tests/hsm_secret.rs::lightning_words_give_the_node_id_core_lightning_has_for_them

faraday/faraday-keys/tests/hsm_secret.rs::lightning_words_in_another_language_are_refused

no fuzz target: The mnemonic form's text is read by the BIP-39 words parser, which has its own fuzz target (bip39_words); the rest is a length check and bytes of a fixed length

Cross-check

Compared with others' code: Blockstream and the Core Lightning developers (ccan's HKDF-SHA256, the salt, limits and calls of common/hsm_secret.c written out in tools/reference/cln/main.c), the libsodium developers (Argon2id and the secretstream), python-mnemonic, by Trezor (SatoshiLabs) (the mnemonic form's BIP-39 words and seed).

Area lightning

Faraday's code faraday_bip::aezeed (ldk-node's and LND's node keys, the aezeed read), faraday_codec::bolt11::decode (a BOLT #11 invoice read), faraday_codec::bolt12::decode (a BOLT #12 offer read), faraday_keys::hsm_secret (Core Lightning's node key from its hsm_secret, plain encrypted or the mnemonic form, and from BIP-39 words)

Compared with LND's own code, vendored in Go (tools/reference/lnd/: its aezeed package over Yawning Angel's aez, and the node key over btcd's hdkeychain), one process answering the run's requests (the aezeed also asked of a second build of each side, Faraday's with the aes crate's software round and LND's without assembly); ldk-node's derivation as tools/reference/aezeed/README.md quotes it, written out in area_lightning.py over btclib's BIP-32 (btclib/, on btclib's own curve); for invoices, the bolt11 package by lnbits (2.2.0, tools/reference/bolt11/: its wheels over the bech32, base58 and bitstring packages, with a stand-in for its libsecp256k1 binding coincurve written over btclib's curve), and invoices written in bolt11_enc.py from BOLT #11 and signed with btclib; for offers, Core Lightning's own offer decoder, devtools/bolt12-cli built from its source release by its own configure and make (tools/reference/bolt12/), and offers written in bolt12_enc.py from BOLT #12; Core Lightning's code (tools/reference/cln/: ccan's HKDF-SHA256 compiled as it is, and its common/hsm_secret.c functions written out over the system libsodium, the BIP-39 words and seed of the mnemonic form from python-mnemonic), one process answering the run's requests.

Checked first: LND's code reads the aezeed (wordlist, version, CRC-32C, scrypt, AEZ) and derives the node key, and its published answers (tools/vectors/aezeed/) are required of it as well as of Faraday; the Go program is built offline from the vendored tree (GOFLAGS=-mod=vendor, GOTOOLCHAIN=local) and its version is written into the stamp; the area stops when the program is missing; the software-round pass runs only on programs soft.py has checked to be soft (the tags noasm and purego; no AES-NI instruction in Faraday's command) and the command says it was built soft; ldk-node's derivation is written in the area from the sources the README quotes, and ldk's published answers are required of it as well as of Faraday; the bolt11 package's wheels and its stand-in are hashed against references.sha256 before any run, and each of BOLT #11's 31 published examples is required to be read by Faraday as the BOLT says (a valid one read, an invalid one refused), the package reading the valid ones to the same fields; Core Lightning's HKDF is its compiled code, its salt, limits and calls are those of hsm_secret.c, libsodium itself seals and opens the file, and Core Lightning's two published node ids for words are required of it as well as of Faraday; the area stops when the program is missing and the stamp records libsodium's version; Core Lightning's release archive is hashed against tools/reference/bolt12/release.pin by the fetch and again by every build, the area stops when bolt12-cli is missing, and each of the BOLT #12 vectors is required to be read by Faraday as the vector says (a valid one read, an invalid one refused) and read by Core Lightning's decoder to the same fields where Faraday reads it.

ldk-node's node key is compared with a derivation written here, not with ldk's code (Rust, not vendored): only ldk's five published answers are outside it; LND's key path numbers are written in the Go program from keychain/derivation.go, as LND derives through btcwallet, which is not vendored; the bolt11 package is not asked the fields it does not read (fields BOLT #11 does not define, a fallback of a witness version above 16, a second or later fallback), which are compared with the writer's own list; its signature check runs on btclib's curve, not libsecp256k1's, and refuses a high-S signature as libsecp256k1 does; hsm_secret.c itself is not compiled (it needs tal and libwally): its functions are written out in main.c, and for the mnemonic form libwally's two answers, whether the words validate and their BIP-39 seed, are python-mnemonic's, which takes 12 to 24 words and normalises the words and passphrase (NFKD) where libwally takes 27 and 30 words too and normalises nothing, so the area judges only English 12 to 24-word ASCII cases and Faraday refuses 27 and 30 words (F228); a NUL in the mnemonic form's words is not compared (Core Lightning reads the text up to it, Faraday refuses the file); the words' derivation (lightning-hsmtool generatehsm) is BIP-39's seed, whose first 32 bytes are taken by both sides here; Core Lightning's bolt12-cli reads one Bech32 string, so the area takes out a + between two Bech32 characters and the white space after it, and a lightning: prefix, before asking it, and a text with a NUL byte cannot be given to it (Faraday refuses it); its output is read as text (a short channel id as BxTxO/direction, chain hashes reversed).

Vectors LND's five cipher seeds, LND's two node keys, ldk's five node ids (tools/vectors/aezeed/); BOLT #11's 31 examples, valid and invalid (tools/vectors/lightning-bolt11/); BOLT #12's 53 offer vectors and 12 format strings, valid and invalid (tools/vectors/lightning-bolt12/).

Random cases Random BIP-39 seeds and entropies on every network; every aezeed case again with the aes crate's software round against LND's AEZ without assembly; random words, a wrong version with a right checksum, published seeds under a changed passphrase, a changed enciphered byte or salt with the checksum put right, a changed word, each refused by LND's code; 150 invoices written with every kind of field (amounts in every multiplier, description or its hash, payee key, expiry, final cltv, fallbacks of every version, route hints, features, metadata, fields BOLT #11 does not define) and signed, read by Faraday and by the package field by field, then each with one Bech32 character changed, with one letter in upper case, and with two of these spoiled: a repeated p or x, a wrong-length p, s, h or n, no p, no s, both or neither of d and h, an unknown required feature, a leading zero value in a longer x, c or 9, a leading zero or a fraction of a millisatoshi in the amount, a bad multiplier, an unknown network, a high-S signature, a field cut short, a text over 1023 characters, a description that is not UTF-8; for Core Lightning, random plain and encrypted hsm_secrets under random passphrases (opened by Faraday and by libsodium, node ids compared), a secret sealed by libsodium and opened by Faraday and by Core Lightning's functions, a changed byte, a wrong passphrase and a wrong length each refused by both, random mnemonic-form files with and without a passphrase (node ids compared; a wrong passphrase, a passphrase the file does not have and broken words each refused by both), and random BIP-39 words with a passphrase; 250 rounds of BOLT #12 offers, each an offer written with every kind of field (chains, metadata, a currency or an amount in millisatoshis, description, features, expiry, blinded paths, issuer, quantity, issuer id, unknown odd fields; + joins, upper case and a lightning: prefix) read by Faraday and by Core Lightning's decoder field by field and by the writer's own record, then one with a Bech32 character changed, one in mixed case, and three of thirty-eight spoils: types out of order or repeated, a field cut short or longer than the stream, a BigSize, truncated integer or feature field not minimal, a type outside the offer's ranges or an unknown even one, a text that is not BOLT #1's, an amount without a description, of zero, or a currency without an amount, no issuer id and no path, a path of no hops or a bad point, chains empty or of a wrong length, padding of more than four bits, a bad +, a wrong prefix, characters outside Bech32, and F232's stricter cases (a text over 4,296 characters, a non-zero padding bit, a chain twice or none known, a currency not in ISO 4217, an amount above 21 million bitcoin, an expiry past the year 9999, a first node byte that is no key, an unassigned character).

Differences BOLT #11 invoices: the package skips a p, h, s or n field of the wrong length, reads the first of a repeated p or s, and accepts both or neither of a description and its hash, mixed case, an amount finer than a millisatoshi and a leading zero value in x, c or 9, all of which BOLT #11 makes a refusal or says "should" of and Faraday refuses; it also accepts what BOLT #11 leaves open, which Faraday is stricter on: a repeated x, c, m, 9, d, h or n, a text over 1023 characters, an amount with a leading zero, and a required feature bit Faraday does not know; the area counts each refusal as known, naming its reason.

BOLT #11 route hints: the package reads a hop's fees and delta as signed integers (a fee above 2^31 reads negative); the area reads them modulo 2^32 and 2^16 before comparing, and keeps a hint to three hops, as the package drops the last hop of a hint of a multiple of five.

BOLT #11 fallbacks: the package reads only the first fallback address and writes the others in bech32 for every witness version, no bech32m; the area compares Faraday's whole list of fallbacks with the writer's f fields of versions 0 to 18, in order, and its fields of an unknown version by the writer's list.

BOLT #11 features: the package keeps one state per feature, so a feature with both its required and its supported bit set reads as supported only; the writer sets one bit of each pair.

BOLT #12 offers: Core Lightning's bolt12-cli passes the decoder no feature set, so it reads an offer with an even feature bit that Faraday refuses (BOLT #9 defines no offer feature); it also reads feature bytes with a leading zero byte, which BOLT #9 makes not minimal, and a description, issuer or currency holding a character of Unicode's Cc, Cf, Co, Zl or Zp categories, which BOLT #1 refuses and Faraday refuses; and it refuses what Faraday reads when the currency is missing from its ISO 4217 table (the list of 2018) or an amount in bitcoin has a first chain Faraday does not know (it names the unit by the first chain alone), which Faraday reads as BOLT #12 says; the area counts each as known, naming the reason, and every other difference fails the run.

BOLT #12 offers, F232's stricter cases: Faraday refuses what Core Lightning reads (a text over 4,296 characters, a non-zero padding bit, whitespace after a + that is not a space, tab or line break, a chain twice, no known chain, a currency not in the ISO 4217 list Faraday holds, an amount over 21 million bitcoin, an expiry past the year 9999, a first node that is no key, an unassigned character); the area requires Faraday's refusal and counts it as known.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 14060 cases

Secret handling

Reveal::LightningKey

Poly1305's tag is compared in constant time (subtle); the rest is not stated.

The passphrase, the Argon2id key, the secret and the node key are held in zeroizing buffers; the node key leaves only as hex for a reason that names it.

Limits

Reading only: an hsm_secret is never made and never loaded as a key.

A file shorter than 32 bytes, or longer than the mnemonic form can be, is refused. In the mnemonic form the words are English only, in single-space form with no NUL, newline or other whitespace; Core Lightning's text reading is stricter in no case and looser in some, which Faraday refuses.

Faraday's own calls

none

Derive a Lightning key

SpecificationLND aezeed · ldk-node node key · BIP 32 · 1 morePublishedCodeLibrary: bitcoin 0.32Library: secp256k1 0.29Library: base16ct 1.0 (through core/faraday-crypto)Faraday's code: core/faraday-bipCross-checked withLND's node key by btcd's hdkeychain in LND's vendored treeOthers' codeFaraday's second version
Action

Derives a Lightning node key from words (ldk-node) or from an aezeed (LND).

Specification

LND aezeed, LND cipher seed (aezeed) with AEZ v5, Convention

ldk-node node key, ldk-node and rust-lightning node key from a BIP-39 seed, Convention

BIP 32, Hierarchical Deterministic Wallets, Deployed

BIP 39, Mnemonic code for generating deterministic keys, Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-bip: LND's key is m/1017'/coin'/6'/0/0 of the aezeed's entropy taken as the BIP-32 seed; ldk-node's is m/0' of a second master key made from the first master's private key.

Checked against

tools/vectors/aezeed

Published, by LND's aezeed test package, by Lightning Labs; the node keys computed with LND's and ldk-node's code, as tools/reference/aezeed/README.md records.

faraday/faraday-core/tests/all/lightning.rs::an_lnd_cipher_seed_gives_lnds_node_id

faraday/faraday-core/tests/all/lightning.rs::a_loaded_key_gives_ldk_nodes_node_id

core/faraday-bip/src/aezeed.rs::the_node_key_matches_what_lnd_derives

core/faraday-bip/src/aezeed.rs::the_ldk_node_key_matches_what_ldk_node_derives

fuzz aezeed

Cross-check

Compared with others' code: LND's node key by btcd's hdkeychain in LND's vendored tree, by Lightning Labs and the btcd developers, for LND; btclib-wallet's bip32, by the btclib developers, and python-mnemonic, by Trezor (SatoshiLabs), for each step of ldk-node's key.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: ldk-node's node key, composed in area_lightning.py from the sources tools/reference/aezeed/README.md quotes (each step btclib's), and LND's key-path numbers (1017', coin, 6', 0, 0), written in tools/reference/lnd/main.go from keychain/derivation.go.

Area lightning

Faraday's code faraday_bip::aezeed (ldk-node's and LND's node keys, the aezeed read), faraday_codec::bolt11::decode (a BOLT #11 invoice read), faraday_codec::bolt12::decode (a BOLT #12 offer read), faraday_keys::hsm_secret (Core Lightning's node key from its hsm_secret, plain encrypted or the mnemonic form, and from BIP-39 words)

Compared with LND's own code, vendored in Go (tools/reference/lnd/: its aezeed package over Yawning Angel's aez, and the node key over btcd's hdkeychain), one process answering the run's requests (the aezeed also asked of a second build of each side, Faraday's with the aes crate's software round and LND's without assembly); ldk-node's derivation as tools/reference/aezeed/README.md quotes it, written out in area_lightning.py over btclib's BIP-32 (btclib/, on btclib's own curve); for invoices, the bolt11 package by lnbits (2.2.0, tools/reference/bolt11/: its wheels over the bech32, base58 and bitstring packages, with a stand-in for its libsecp256k1 binding coincurve written over btclib's curve), and invoices written in bolt11_enc.py from BOLT #11 and signed with btclib; for offers, Core Lightning's own offer decoder, devtools/bolt12-cli built from its source release by its own configure and make (tools/reference/bolt12/), and offers written in bolt12_enc.py from BOLT #12; Core Lightning's code (tools/reference/cln/: ccan's HKDF-SHA256 compiled as it is, and its common/hsm_secret.c functions written out over the system libsodium, the BIP-39 words and seed of the mnemonic form from python-mnemonic), one process answering the run's requests.

Checked first: LND's code reads the aezeed (wordlist, version, CRC-32C, scrypt, AEZ) and derives the node key, and its published answers (tools/vectors/aezeed/) are required of it as well as of Faraday; the Go program is built offline from the vendored tree (GOFLAGS=-mod=vendor, GOTOOLCHAIN=local) and its version is written into the stamp; the area stops when the program is missing; the software-round pass runs only on programs soft.py has checked to be soft (the tags noasm and purego; no AES-NI instruction in Faraday's command) and the command says it was built soft; ldk-node's derivation is written in the area from the sources the README quotes, and ldk's published answers are required of it as well as of Faraday; the bolt11 package's wheels and its stand-in are hashed against references.sha256 before any run, and each of BOLT #11's 31 published examples is required to be read by Faraday as the BOLT says (a valid one read, an invalid one refused), the package reading the valid ones to the same fields; Core Lightning's HKDF is its compiled code, its salt, limits and calls are those of hsm_secret.c, libsodium itself seals and opens the file, and Core Lightning's two published node ids for words are required of it as well as of Faraday; the area stops when the program is missing and the stamp records libsodium's version; Core Lightning's release archive is hashed against tools/reference/bolt12/release.pin by the fetch and again by every build, the area stops when bolt12-cli is missing, and each of the BOLT #12 vectors is required to be read by Faraday as the vector says (a valid one read, an invalid one refused) and read by Core Lightning's decoder to the same fields where Faraday reads it.

ldk-node's node key is compared with a derivation written here, not with ldk's code (Rust, not vendored): only ldk's five published answers are outside it; LND's key path numbers are written in the Go program from keychain/derivation.go, as LND derives through btcwallet, which is not vendored; the bolt11 package is not asked the fields it does not read (fields BOLT #11 does not define, a fallback of a witness version above 16, a second or later fallback), which are compared with the writer's own list; its signature check runs on btclib's curve, not libsecp256k1's, and refuses a high-S signature as libsecp256k1 does; hsm_secret.c itself is not compiled (it needs tal and libwally): its functions are written out in main.c, and for the mnemonic form libwally's two answers, whether the words validate and their BIP-39 seed, are python-mnemonic's, which takes 12 to 24 words and normalises the words and passphrase (NFKD) where libwally takes 27 and 30 words too and normalises nothing, so the area judges only English 12 to 24-word ASCII cases and Faraday refuses 27 and 30 words (F228); a NUL in the mnemonic form's words is not compared (Core Lightning reads the text up to it, Faraday refuses the file); the words' derivation (lightning-hsmtool generatehsm) is BIP-39's seed, whose first 32 bytes are taken by both sides here; Core Lightning's bolt12-cli reads one Bech32 string, so the area takes out a + between two Bech32 characters and the white space after it, and a lightning: prefix, before asking it, and a text with a NUL byte cannot be given to it (Faraday refuses it); its output is read as text (a short channel id as BxTxO/direction, chain hashes reversed).

Vectors LND's five cipher seeds, LND's two node keys, ldk's five node ids (tools/vectors/aezeed/); BOLT #11's 31 examples, valid and invalid (tools/vectors/lightning-bolt11/); BOLT #12's 53 offer vectors and 12 format strings, valid and invalid (tools/vectors/lightning-bolt12/).

Random cases Random BIP-39 seeds and entropies on every network; every aezeed case again with the aes crate's software round against LND's AEZ without assembly; random words, a wrong version with a right checksum, published seeds under a changed passphrase, a changed enciphered byte or salt with the checksum put right, a changed word, each refused by LND's code; 150 invoices written with every kind of field (amounts in every multiplier, description or its hash, payee key, expiry, final cltv, fallbacks of every version, route hints, features, metadata, fields BOLT #11 does not define) and signed, read by Faraday and by the package field by field, then each with one Bech32 character changed, with one letter in upper case, and with two of these spoiled: a repeated p or x, a wrong-length p, s, h or n, no p, no s, both or neither of d and h, an unknown required feature, a leading zero value in a longer x, c or 9, a leading zero or a fraction of a millisatoshi in the amount, a bad multiplier, an unknown network, a high-S signature, a field cut short, a text over 1023 characters, a description that is not UTF-8; for Core Lightning, random plain and encrypted hsm_secrets under random passphrases (opened by Faraday and by libsodium, node ids compared), a secret sealed by libsodium and opened by Faraday and by Core Lightning's functions, a changed byte, a wrong passphrase and a wrong length each refused by both, random mnemonic-form files with and without a passphrase (node ids compared; a wrong passphrase, a passphrase the file does not have and broken words each refused by both), and random BIP-39 words with a passphrase; 250 rounds of BOLT #12 offers, each an offer written with every kind of field (chains, metadata, a currency or an amount in millisatoshis, description, features, expiry, blinded paths, issuer, quantity, issuer id, unknown odd fields; + joins, upper case and a lightning: prefix) read by Faraday and by Core Lightning's decoder field by field and by the writer's own record, then one with a Bech32 character changed, one in mixed case, and three of thirty-eight spoils: types out of order or repeated, a field cut short or longer than the stream, a BigSize, truncated integer or feature field not minimal, a type outside the offer's ranges or an unknown even one, a text that is not BOLT #1's, an amount without a description, of zero, or a currency without an amount, no issuer id and no path, a path of no hops or a bad point, chains empty or of a wrong length, padding of more than four bits, a bad +, a wrong prefix, characters outside Bech32, and F232's stricter cases (a text over 4,296 characters, a non-zero padding bit, a chain twice or none known, a currency not in ISO 4217, an amount above 21 million bitcoin, an expiry past the year 9999, a first node byte that is no key, an unassigned character).

Differences BOLT #11 invoices: the package skips a p, h, s or n field of the wrong length, reads the first of a repeated p or s, and accepts both or neither of a description and its hash, mixed case, an amount finer than a millisatoshi and a leading zero value in x, c or 9, all of which BOLT #11 makes a refusal or says "should" of and Faraday refuses; it also accepts what BOLT #11 leaves open, which Faraday is stricter on: a repeated x, c, m, 9, d, h or n, a text over 1023 characters, an amount with a leading zero, and a required feature bit Faraday does not know; the area counts each refusal as known, naming its reason.

BOLT #11 route hints: the package reads a hop's fees and delta as signed integers (a fee above 2^31 reads negative); the area reads them modulo 2^32 and 2^16 before comparing, and keeps a hint to three hops, as the package drops the last hop of a hint of a multiple of five.

BOLT #11 fallbacks: the package reads only the first fallback address and writes the others in bech32 for every witness version, no bech32m; the area compares Faraday's whole list of fallbacks with the writer's f fields of versions 0 to 18, in order, and its fields of an unknown version by the writer's list.

BOLT #11 features: the package keeps one state per feature, so a feature with both its required and its supported bit set reads as supported only; the writer sets one bit of each pair.

BOLT #12 offers: Core Lightning's bolt12-cli passes the decoder no feature set, so it reads an offer with an even feature bit that Faraday refuses (BOLT #9 defines no offer feature); it also reads feature bytes with a leading zero byte, which BOLT #9 makes not minimal, and a description, issuer or currency holding a character of Unicode's Cc, Cf, Co, Zl or Zp categories, which BOLT #1 refuses and Faraday refuses; and it refuses what Faraday reads when the currency is missing from its ISO 4217 table (the list of 2018) or an amount in bitcoin has a first chain Faraday does not know (it names the unit by the first chain alone), which Faraday reads as BOLT #12 says; the area counts each as known, naming the reason, and every other difference fails the run.

BOLT #12 offers, F232's stricter cases: Faraday refuses what Core Lightning reads (a text over 4,296 characters, a non-zero padding bit, whitespace after a + that is not a space, tab or line break, a chain twice, no known chain, a currency not in the ISO 4217 list Faraday holds, an amount over 21 million bitcoin, an expiry past the year 9999, a first node that is no key, an unassigned character); the area requires Faraday's refusal and counts it as known.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 14060 cases

Secret handling

Reveal::LightningKey

not stated by the library.

The node's private key is held in a zeroizing buffer and leaves only as hex for a reason that names it.

Limits

A node key is hot by nature: it is shown, not loaded as a key.

Faraday's own calls

none

Read a Lightning invoice

SpecificationBOLT 11PublishedCodeLibrary: bitcoin 0.32Faraday's code: core/faraday-codecCross-checked withthe bolt11 package (lnbits)Others' code
Action

Reads a BOLT #11 invoice: Bech32, the amount, the timestamp and the tagged fields, and checks the signature against the `n` field or recovers the payee's key from it.

Specification

BOLT 11, BOLT #11: Invoice Protocol for Lightning Payments, Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Faraday's code: core/faraday-codec: The invoice's fields are read here, over the bitcoin crate's Bech32 and secp256k1; reading only, nothing is paid, signed or stored, and every refusal is a named reason.

Checked against

tools/vectors/lightning-bolt11

Published, by BOLT #11's authors (lightning/bolts): the examples of bolt11/invoice-test.json, valid and invalid.

core/faraday-codec/tests/bolt11.rs::every_valid_example_is_read_and_every_invalid_one_refused

core/faraday-codec/tests/bolt11.rs::donation_of_any_amount

core/faraday-codec/tests/bolt11.rs::amounts_and_japanese_description

core/faraday-codec/tests/bolt11.rs::hashed_description_and_fallbacks

core/faraday-codec/tests/bolt11.rs::features_metadata_case_and_ignored_fields

core/faraday-codec/tests/bolt11.rs::recovered_key_with_high_s_and_the_n_field

core/faraday-codec/tests/bolt11.rs::refusals_say_why

core/faraday-codec/tests/bolt11.rs::prefix_and_length

core/faraday-codec/tests/bolt11.rs::expiry_cltv_and_features_with_a_leading_zero_are_refused

fuzz bolt11

Cross-check

Compared with others' code: the bolt11 package (lnbits), over the bech32 and bitstring packages, with a stand-in for its libsecp256k1 binding over btclib; Faraday's stricter refusals are stated differences of the area.

Area lightning

Faraday's code faraday_bip::aezeed (ldk-node's and LND's node keys, the aezeed read), faraday_codec::bolt11::decode (a BOLT #11 invoice read), faraday_codec::bolt12::decode (a BOLT #12 offer read), faraday_keys::hsm_secret (Core Lightning's node key from its hsm_secret, plain encrypted or the mnemonic form, and from BIP-39 words)

Compared with LND's own code, vendored in Go (tools/reference/lnd/: its aezeed package over Yawning Angel's aez, and the node key over btcd's hdkeychain), one process answering the run's requests (the aezeed also asked of a second build of each side, Faraday's with the aes crate's software round and LND's without assembly); ldk-node's derivation as tools/reference/aezeed/README.md quotes it, written out in area_lightning.py over btclib's BIP-32 (btclib/, on btclib's own curve); for invoices, the bolt11 package by lnbits (2.2.0, tools/reference/bolt11/: its wheels over the bech32, base58 and bitstring packages, with a stand-in for its libsecp256k1 binding coincurve written over btclib's curve), and invoices written in bolt11_enc.py from BOLT #11 and signed with btclib; for offers, Core Lightning's own offer decoder, devtools/bolt12-cli built from its source release by its own configure and make (tools/reference/bolt12/), and offers written in bolt12_enc.py from BOLT #12; Core Lightning's code (tools/reference/cln/: ccan's HKDF-SHA256 compiled as it is, and its common/hsm_secret.c functions written out over the system libsodium, the BIP-39 words and seed of the mnemonic form from python-mnemonic), one process answering the run's requests.

Checked first: LND's code reads the aezeed (wordlist, version, CRC-32C, scrypt, AEZ) and derives the node key, and its published answers (tools/vectors/aezeed/) are required of it as well as of Faraday; the Go program is built offline from the vendored tree (GOFLAGS=-mod=vendor, GOTOOLCHAIN=local) and its version is written into the stamp; the area stops when the program is missing; the software-round pass runs only on programs soft.py has checked to be soft (the tags noasm and purego; no AES-NI instruction in Faraday's command) and the command says it was built soft; ldk-node's derivation is written in the area from the sources the README quotes, and ldk's published answers are required of it as well as of Faraday; the bolt11 package's wheels and its stand-in are hashed against references.sha256 before any run, and each of BOLT #11's 31 published examples is required to be read by Faraday as the BOLT says (a valid one read, an invalid one refused), the package reading the valid ones to the same fields; Core Lightning's HKDF is its compiled code, its salt, limits and calls are those of hsm_secret.c, libsodium itself seals and opens the file, and Core Lightning's two published node ids for words are required of it as well as of Faraday; the area stops when the program is missing and the stamp records libsodium's version; Core Lightning's release archive is hashed against tools/reference/bolt12/release.pin by the fetch and again by every build, the area stops when bolt12-cli is missing, and each of the BOLT #12 vectors is required to be read by Faraday as the vector says (a valid one read, an invalid one refused) and read by Core Lightning's decoder to the same fields where Faraday reads it.

ldk-node's node key is compared with a derivation written here, not with ldk's code (Rust, not vendored): only ldk's five published answers are outside it; LND's key path numbers are written in the Go program from keychain/derivation.go, as LND derives through btcwallet, which is not vendored; the bolt11 package is not asked the fields it does not read (fields BOLT #11 does not define, a fallback of a witness version above 16, a second or later fallback), which are compared with the writer's own list; its signature check runs on btclib's curve, not libsecp256k1's, and refuses a high-S signature as libsecp256k1 does; hsm_secret.c itself is not compiled (it needs tal and libwally): its functions are written out in main.c, and for the mnemonic form libwally's two answers, whether the words validate and their BIP-39 seed, are python-mnemonic's, which takes 12 to 24 words and normalises the words and passphrase (NFKD) where libwally takes 27 and 30 words too and normalises nothing, so the area judges only English 12 to 24-word ASCII cases and Faraday refuses 27 and 30 words (F228); a NUL in the mnemonic form's words is not compared (Core Lightning reads the text up to it, Faraday refuses the file); the words' derivation (lightning-hsmtool generatehsm) is BIP-39's seed, whose first 32 bytes are taken by both sides here; Core Lightning's bolt12-cli reads one Bech32 string, so the area takes out a + between two Bech32 characters and the white space after it, and a lightning: prefix, before asking it, and a text with a NUL byte cannot be given to it (Faraday refuses it); its output is read as text (a short channel id as BxTxO/direction, chain hashes reversed).

Vectors LND's five cipher seeds, LND's two node keys, ldk's five node ids (tools/vectors/aezeed/); BOLT #11's 31 examples, valid and invalid (tools/vectors/lightning-bolt11/); BOLT #12's 53 offer vectors and 12 format strings, valid and invalid (tools/vectors/lightning-bolt12/).

Random cases Random BIP-39 seeds and entropies on every network; every aezeed case again with the aes crate's software round against LND's AEZ without assembly; random words, a wrong version with a right checksum, published seeds under a changed passphrase, a changed enciphered byte or salt with the checksum put right, a changed word, each refused by LND's code; 150 invoices written with every kind of field (amounts in every multiplier, description or its hash, payee key, expiry, final cltv, fallbacks of every version, route hints, features, metadata, fields BOLT #11 does not define) and signed, read by Faraday and by the package field by field, then each with one Bech32 character changed, with one letter in upper case, and with two of these spoiled: a repeated p or x, a wrong-length p, s, h or n, no p, no s, both or neither of d and h, an unknown required feature, a leading zero value in a longer x, c or 9, a leading zero or a fraction of a millisatoshi in the amount, a bad multiplier, an unknown network, a high-S signature, a field cut short, a text over 1023 characters, a description that is not UTF-8; for Core Lightning, random plain and encrypted hsm_secrets under random passphrases (opened by Faraday and by libsodium, node ids compared), a secret sealed by libsodium and opened by Faraday and by Core Lightning's functions, a changed byte, a wrong passphrase and a wrong length each refused by both, random mnemonic-form files with and without a passphrase (node ids compared; a wrong passphrase, a passphrase the file does not have and broken words each refused by both), and random BIP-39 words with a passphrase; 250 rounds of BOLT #12 offers, each an offer written with every kind of field (chains, metadata, a currency or an amount in millisatoshis, description, features, expiry, blinded paths, issuer, quantity, issuer id, unknown odd fields; + joins, upper case and a lightning: prefix) read by Faraday and by Core Lightning's decoder field by field and by the writer's own record, then one with a Bech32 character changed, one in mixed case, and three of thirty-eight spoils: types out of order or repeated, a field cut short or longer than the stream, a BigSize, truncated integer or feature field not minimal, a type outside the offer's ranges or an unknown even one, a text that is not BOLT #1's, an amount without a description, of zero, or a currency without an amount, no issuer id and no path, a path of no hops or a bad point, chains empty or of a wrong length, padding of more than four bits, a bad +, a wrong prefix, characters outside Bech32, and F232's stricter cases (a text over 4,296 characters, a non-zero padding bit, a chain twice or none known, a currency not in ISO 4217, an amount above 21 million bitcoin, an expiry past the year 9999, a first node byte that is no key, an unassigned character).

Differences BOLT #11 invoices: the package skips a p, h, s or n field of the wrong length, reads the first of a repeated p or s, and accepts both or neither of a description and its hash, mixed case, an amount finer than a millisatoshi and a leading zero value in x, c or 9, all of which BOLT #11 makes a refusal or says "should" of and Faraday refuses; it also accepts what BOLT #11 leaves open, which Faraday is stricter on: a repeated x, c, m, 9, d, h or n, a text over 1023 characters, an amount with a leading zero, and a required feature bit Faraday does not know; the area counts each refusal as known, naming its reason.

BOLT #11 route hints: the package reads a hop's fees and delta as signed integers (a fee above 2^31 reads negative); the area reads them modulo 2^32 and 2^16 before comparing, and keeps a hint to three hops, as the package drops the last hop of a hint of a multiple of five.

BOLT #11 fallbacks: the package reads only the first fallback address and writes the others in bech32 for every witness version, no bech32m; the area compares Faraday's whole list of fallbacks with the writer's f fields of versions 0 to 18, in order, and its fields of an unknown version by the writer's list.

BOLT #11 features: the package keeps one state per feature, so a feature with both its required and its supported bit set reads as supported only; the writer sets one bit of each pair.

BOLT #12 offers: Core Lightning's bolt12-cli passes the decoder no feature set, so it reads an offer with an even feature bit that Faraday refuses (BOLT #9 defines no offer feature); it also reads feature bytes with a leading zero byte, which BOLT #9 makes not minimal, and a description, issuer or currency holding a character of Unicode's Cc, Cf, Co, Zl or Zp categories, which BOLT #1 refuses and Faraday refuses; and it refuses what Faraday reads when the currency is missing from its ISO 4217 table (the list of 2018) or an amount in bitcoin has a first chain Faraday does not know (it names the unit by the first chain alone), which Faraday reads as BOLT #12 says; the area counts each as known, naming the reason, and every other difference fails the run.

BOLT #12 offers, F232's stricter cases: Faraday refuses what Core Lightning reads (a text over 4,296 characters, a non-zero padding bit, whitespace after a + that is not a space, tab or line break, a chain twice, no known chain, a currency not in the ISO 4217 list Faraday holds, an amount over 21 million bitcoin, an expiry past the year 9999, a first node that is no key, an unassigned character); the area requires Faraday's refusal and counts it as known.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 14060 cases

Secret handling

none: no secret leaves faraday-keys

Not stated; an invoice holds no secret.

Nothing secret is held.

Limits

Reading only: no invoice is written, paid or stored.

A text over 1023 characters, mixed case or a checksum that fails is refused.

Fields of a tag BOLT #11 does not define, and a fallback address of an unknown version, are listed and not used.

Faraday's own calls

BOLT #11 makes mixed case, an amount finer than a millisatoshi and a `c`, `x` or `9` field that begins with a zero value (the minimal form of zero is an empty field) a refusal, and Faraday refuses them. Where BOLT #11 leaves a case open, Faraday refuses the invoice: an amount with a leading zero, a repeated `x`, `c`, `m`, `9`, `d`, `h` or `n`, a malformed fallback of a version it defines, an empty route hint or a hop key that is not a curve point, an `n` key that is not on the curve, a non-zero padding bit, and a text over 1023 characters (what the Bech32 checksum guarantees). Conservative.

no decision

Check a timestamp

SpecificationOpenTimestampsPublishedCodeLibrary: sha1 0.11Library: ripemd 0.2Library: sha3 0.111 moreFaraday's code: faraday/faraday-otsFaraday's own codeCross-checked withpython-opentimestampsOthers' code
Action

Reads an OpenTimestamps proof and follows every path of its operations from the file's hash to its attestations, and says for each Bitcoin one whether it reaches the merkle root of a block header the person gives, whose hash meets its own target.

Specification

OpenTimestamps, OpenTimestamps proof files (.ots), as python-opentimestamps reads them, Convention, vendored

Code

Library: sha1 0.11.0, by the RustCrypto developers.

Library: ripemd 0.2.0, by the RustCrypto developers.

Library: sha3 0.11.0, by the RustCrypto developers.

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: faraday/faraday-ots: The proof's reader and the walk of its operations are written here; the hashes are the RustCrypto crates and SHA-256 is faraday-crypto's. A Bitcoin path is counted only when every hash on it is SHA-256, and the header's own proof of work is checked before it is used.

Written by Faraday

OpenTimestamps proof reader and walk (faraday-ots) · No established implementation exists

No Rust implementation of the OpenTimestamps proof format is established; Faraday's follows python-opentimestamps and is tested against that project's example proofs.

Decision F230

Checked against

tools/vectors/opentimestamps

Published, by the OpenTimestamps client's example proofs (opentimestamps/opentimestamps-client), with the headers of the blocks they name from a public block explorer, each checked against its recorded hash.

faraday/faraday-ots/tests/ots.rs::a_gdp_proof_through_sha256_only_is_committed_by_its_block

faraday/faraday-ots/tests/ots.rs::a_path_through_ripemd160_reaches_its_block_and_is_counted

faraday/faraday-ots/tests/ots.rs::a_proof_taken_with_sha1_is_named_and_not_counted

faraday/faraday-ots/tests/ots.rs::a_path_through_sha1_is_named_and_not_counted

faraday/faraday-ots/tests/ots.rs::a_path_through_keccak_or_sha1_is_named_and_not_counted

faraday/faraday-ots/tests/ots.rs::each_operation_is_applied_in_order

faraday/faraday-ots/tests/ots.rs::the_references_invalid_examples_are_refused

faraday/faraday-ots/tests/ots.rs::what_a_proof_may_not_hold_is_refused

faraday/faraday-ots/tests/ots.rs::a_header_is_80_bytes_and_meets_its_own_target

faraday/faraday-ots/tests/ots.rs::a_header_target_above_its_networks_limit_is_refused

faraday/faraday-ots/tests/ots.rs::a_proof_over_64_kib_is_refused

faraday/faraday-ots/tests/ots.rs::a_tree_whose_operations_make_over_16_mib_is_refused

faraday/faraday-ots/tests/ots.rs::a_tree_of_over_16384_entries_is_refused

faraday/faraday-ots/tests/ots.rs::keccak256_of_nothing_is_the_published_value

fuzz ots

Cross-check

Compared with others' code: python-opentimestamps, by the OpenTimestamps developers (the reference client's own reader and verifier of proofs).

Area ots

Faraday's code faraday_ots (Proof::parse, Proof::verify, Header::parse), asked through the three requests ots.read, ots.verify and ots.header

Compared with python-opentimestamps' core modules, vendored unchanged in tools/reference/opentimestamps/, by the OpenTimestamps developers, on three small shims for what it imports and the repository does not vendor (Keccak-256, RIPEMD-160 over Bitcoin Core's pure-Python hash, and four names of python-bitcoinlib that only its printing routine uses); block headers are read by the area's own transcription of Bitcoin Core's SetCompact and proof-of-work test.

Checked first: The vendored files are hashed against references.sha256 before any run; the client's example proofs (tools/vectors/opentimestamps/) are read by both and the four that reach a block through SHA-256 and RIPEMD-160 alone are required to be committed by both; the shims' hashes are checked against known values before the corpus; each limit is built either side of its edge and both must agree.

The reference's printing of a tree and its stream readers; the order of a node's entries (the walk is compared as a set of paths); whether a header is in the chain; calendars, which neither side asks.

Vectors The OpenTimestamps client's example proofs (all 22, three of them invalid) and the headers of the six blocks they name, each proof walked against each header.

Random cases Proofs built through the reference's classes with every operation, the file hashed with SHA-256, SHA-1 or RIPEMD-160, side branches ending in pending, Bitcoin, Litecoin, Ethereum and unknown attestations, and chains to 255 operations, walked against a header that commits to the main path and one that does not; merkle trees of up to 40 leaves; proofs with a byte changed, inserted, deleted, cut or added to; every limit either side of its edge; headers over every kind of target and lengths other than 80.

Differences OTS: a Bitcoin path through SHA-1 or Keccak-256, or a file taken with SHA-1, is counted by the reference when it reaches the header's merkle root; Faraday names the first such hash and does not count it. Each is asked of the reference and counted.

OTS: an Ethereum attestation is verified by the reference against a block's transactions root; Faraday lists it by height and does not check it. A Litecoin one is listed by both (the reference raises when asked to verify it).

OTS: an attestation repeated at one node is collapsed by the reference and listed twice by Faraday.

OTS: Faraday refuses a proof over 64 KiB, a tree of more than 16,384 entries and a tree whose operations make more than 16 MiB of values; the reference reads each (a tree of 17 appends of one byte to a value of 4,095 bytes, each followed by 250 reversals, makes 17.5 MiB in 8.6 KB; 65 chains of 252 reversals behind distinct appends make over 16,384 entries in 17 KB).

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 5800 cases

Source

0.2.0 · faraday/faraday-ots/src/lib.rs · HashOp::digest

0.2.0 · faraday/faraday-ots/src/lib.rs · HashOp::digest_whole

0.2.0 · faraday/faraday-ots/src/lib.rs · Op::apply

0.2.0 · faraday/faraday-ots/src/lib.rs · Proof::parse

0.2.0 · faraday/faraday-ots/src/lib.rs · Proof::verify

0.2.0 · faraday/faraday-ots/src/lib.rs · Header::parse

0.2.0 · faraday/faraday-ots/src/lib.rs · Header::block_hash

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

Not stated; a proof and a header hold no secret.

Nothing secret is held.

Limits

Reading only: no timestamp is made, upgraded or looked up; a pending attestation is listed with its calendar and not followed.

The header given is checked against its own target and not against the chain: a match says the file is committed to by that header.

An operation's argument or result over 4,096 bytes, a tree deeper than 256 levels, a height over 32 bits, a proof over 64 KiB, a tree of over 16,384 entries, over 16 MiB of values made by the operations in all, a header target above its network's limit and a proof with bytes after its tree are refused.

Faraday's own calls

A Bitcoin path counts only when the file's hash and every hash on it are SHA-256 or RIPEMD-160: a path through SHA-1 or Keccak-256 is named and not counted, where python-opentimestamps counts it. Where the reference leaves a case open, Faraday refuses: an Ethereum attestation whose payload is not one height, a block height over 32 bits, a number over 64 bits, a proof over 64 KiB, a tree of over 16,384 entries or whose operations make over 16 MiB of values in all, and a header whose target is above its network's proof-of-work limit (the reference reads these without a limit). Conservative, F230.

Read a Lightning offer

SpecificationBOLT 12PublishedCodeLibrary: bitcoin 0.32Faraday's code: core/faraday-codecCross-checked withCore Lightning's bolt12-cliOthers' codeFaraday's second version
Action

Reads a BOLT #12 offer: Bech32 without a checksum, its `+` joins, and the TLV fields (chains, amount and currency, description, issuer, expiry, quantity, features, blinded paths, issuer id and the odd fields it does not know).

Specification

BOLT 12, BOLT #12: Negotiation Protocol for Lightning Payments, Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Faraday's code: core/faraday-codec: The offer's fields are read here, over the bitcoin crate's secp256k1 for the points; reading only, an offer carries no signature and nothing is hashed, requested, paid or stored, and every refusal is a named reason.

Checked against

tools/vectors/lightning-bolt12

Published, by BOLT #12's authors (lightning/bolts): the offers of bolt12/offers-test.json and the strings of bolt12/format-string-test.json, valid and invalid, at the commit tools/vectors/lightning-bolt12/README.md names.

core/faraday-codec/tests/bolt12.rs::every_offer_of_the_specification_is_read_or_refused

core/faraday-codec/tests/bolt12.rs::the_text_form_follows_the_format_vectors

core/faraday-codec/tests/bolt12.rs::the_fields_read_as_the_vectors_describe_them

core/faraday-codec/tests/bolt12.rs::paths_show_their_first_node_and_hops

core/faraday-codec/tests/bolt12.rs::unknown_odd_fields_are_listed

core/faraday-codec/tests/bolt12.rs::an_invoice_request_and_other_prefixes_are_refused_with_their_reason

core/faraday-codec/tests/bolt12.rs::what_bolt12_leaves_open_is_refused

core/faraday-codec/tests/bolt12.rs::text_fields_hold_no_control_or_unassigned_characters

core/faraday-codec/tests/bolt12.rs::the_text_is_bounded_and_its_padding_is_zero

core/faraday-codec/tests/bolt12.rs::a_chain_hash_is_the_genesis_block_of_its_network

core/faraday-codec/tests/bolt12.rs::the_currency_table_is_the_published_iso_4217_list

fuzz bolt12

Cross-check

Compared with others' code: Core Lightning's bolt12-cli, by the Core Lightning developers (Blockstream), built from its v26.06.10 source release.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the offers the area reads, written in bolt12_enc.py from BOLT #12, and the stricter refusals of F232 and what Core Lightning's command does not check (a feature set, minimal feature bytes, BOLT #1's refused characters, its 2018 currency table), which are stated differences of the area.

Area lightning

Faraday's code faraday_bip::aezeed (ldk-node's and LND's node keys, the aezeed read), faraday_codec::bolt11::decode (a BOLT #11 invoice read), faraday_codec::bolt12::decode (a BOLT #12 offer read), faraday_keys::hsm_secret (Core Lightning's node key from its hsm_secret, plain encrypted or the mnemonic form, and from BIP-39 words)

Compared with LND's own code, vendored in Go (tools/reference/lnd/: its aezeed package over Yawning Angel's aez, and the node key over btcd's hdkeychain), one process answering the run's requests (the aezeed also asked of a second build of each side, Faraday's with the aes crate's software round and LND's without assembly); ldk-node's derivation as tools/reference/aezeed/README.md quotes it, written out in area_lightning.py over btclib's BIP-32 (btclib/, on btclib's own curve); for invoices, the bolt11 package by lnbits (2.2.0, tools/reference/bolt11/: its wheels over the bech32, base58 and bitstring packages, with a stand-in for its libsecp256k1 binding coincurve written over btclib's curve), and invoices written in bolt11_enc.py from BOLT #11 and signed with btclib; for offers, Core Lightning's own offer decoder, devtools/bolt12-cli built from its source release by its own configure and make (tools/reference/bolt12/), and offers written in bolt12_enc.py from BOLT #12; Core Lightning's code (tools/reference/cln/: ccan's HKDF-SHA256 compiled as it is, and its common/hsm_secret.c functions written out over the system libsodium, the BIP-39 words and seed of the mnemonic form from python-mnemonic), one process answering the run's requests.

Checked first: LND's code reads the aezeed (wordlist, version, CRC-32C, scrypt, AEZ) and derives the node key, and its published answers (tools/vectors/aezeed/) are required of it as well as of Faraday; the Go program is built offline from the vendored tree (GOFLAGS=-mod=vendor, GOTOOLCHAIN=local) and its version is written into the stamp; the area stops when the program is missing; the software-round pass runs only on programs soft.py has checked to be soft (the tags noasm and purego; no AES-NI instruction in Faraday's command) and the command says it was built soft; ldk-node's derivation is written in the area from the sources the README quotes, and ldk's published answers are required of it as well as of Faraday; the bolt11 package's wheels and its stand-in are hashed against references.sha256 before any run, and each of BOLT #11's 31 published examples is required to be read by Faraday as the BOLT says (a valid one read, an invalid one refused), the package reading the valid ones to the same fields; Core Lightning's HKDF is its compiled code, its salt, limits and calls are those of hsm_secret.c, libsodium itself seals and opens the file, and Core Lightning's two published node ids for words are required of it as well as of Faraday; the area stops when the program is missing and the stamp records libsodium's version; Core Lightning's release archive is hashed against tools/reference/bolt12/release.pin by the fetch and again by every build, the area stops when bolt12-cli is missing, and each of the BOLT #12 vectors is required to be read by Faraday as the vector says (a valid one read, an invalid one refused) and read by Core Lightning's decoder to the same fields where Faraday reads it.

ldk-node's node key is compared with a derivation written here, not with ldk's code (Rust, not vendored): only ldk's five published answers are outside it; LND's key path numbers are written in the Go program from keychain/derivation.go, as LND derives through btcwallet, which is not vendored; the bolt11 package is not asked the fields it does not read (fields BOLT #11 does not define, a fallback of a witness version above 16, a second or later fallback), which are compared with the writer's own list; its signature check runs on btclib's curve, not libsecp256k1's, and refuses a high-S signature as libsecp256k1 does; hsm_secret.c itself is not compiled (it needs tal and libwally): its functions are written out in main.c, and for the mnemonic form libwally's two answers, whether the words validate and their BIP-39 seed, are python-mnemonic's, which takes 12 to 24 words and normalises the words and passphrase (NFKD) where libwally takes 27 and 30 words too and normalises nothing, so the area judges only English 12 to 24-word ASCII cases and Faraday refuses 27 and 30 words (F228); a NUL in the mnemonic form's words is not compared (Core Lightning reads the text up to it, Faraday refuses the file); the words' derivation (lightning-hsmtool generatehsm) is BIP-39's seed, whose first 32 bytes are taken by both sides here; Core Lightning's bolt12-cli reads one Bech32 string, so the area takes out a + between two Bech32 characters and the white space after it, and a lightning: prefix, before asking it, and a text with a NUL byte cannot be given to it (Faraday refuses it); its output is read as text (a short channel id as BxTxO/direction, chain hashes reversed).

Vectors LND's five cipher seeds, LND's two node keys, ldk's five node ids (tools/vectors/aezeed/); BOLT #11's 31 examples, valid and invalid (tools/vectors/lightning-bolt11/); BOLT #12's 53 offer vectors and 12 format strings, valid and invalid (tools/vectors/lightning-bolt12/).

Random cases Random BIP-39 seeds and entropies on every network; every aezeed case again with the aes crate's software round against LND's AEZ without assembly; random words, a wrong version with a right checksum, published seeds under a changed passphrase, a changed enciphered byte or salt with the checksum put right, a changed word, each refused by LND's code; 150 invoices written with every kind of field (amounts in every multiplier, description or its hash, payee key, expiry, final cltv, fallbacks of every version, route hints, features, metadata, fields BOLT #11 does not define) and signed, read by Faraday and by the package field by field, then each with one Bech32 character changed, with one letter in upper case, and with two of these spoiled: a repeated p or x, a wrong-length p, s, h or n, no p, no s, both or neither of d and h, an unknown required feature, a leading zero value in a longer x, c or 9, a leading zero or a fraction of a millisatoshi in the amount, a bad multiplier, an unknown network, a high-S signature, a field cut short, a text over 1023 characters, a description that is not UTF-8; for Core Lightning, random plain and encrypted hsm_secrets under random passphrases (opened by Faraday and by libsodium, node ids compared), a secret sealed by libsodium and opened by Faraday and by Core Lightning's functions, a changed byte, a wrong passphrase and a wrong length each refused by both, random mnemonic-form files with and without a passphrase (node ids compared; a wrong passphrase, a passphrase the file does not have and broken words each refused by both), and random BIP-39 words with a passphrase; 250 rounds of BOLT #12 offers, each an offer written with every kind of field (chains, metadata, a currency or an amount in millisatoshis, description, features, expiry, blinded paths, issuer, quantity, issuer id, unknown odd fields; + joins, upper case and a lightning: prefix) read by Faraday and by Core Lightning's decoder field by field and by the writer's own record, then one with a Bech32 character changed, one in mixed case, and three of thirty-eight spoils: types out of order or repeated, a field cut short or longer than the stream, a BigSize, truncated integer or feature field not minimal, a type outside the offer's ranges or an unknown even one, a text that is not BOLT #1's, an amount without a description, of zero, or a currency without an amount, no issuer id and no path, a path of no hops or a bad point, chains empty or of a wrong length, padding of more than four bits, a bad +, a wrong prefix, characters outside Bech32, and F232's stricter cases (a text over 4,296 characters, a non-zero padding bit, a chain twice or none known, a currency not in ISO 4217, an amount above 21 million bitcoin, an expiry past the year 9999, a first node byte that is no key, an unassigned character).

Differences BOLT #11 invoices: the package skips a p, h, s or n field of the wrong length, reads the first of a repeated p or s, and accepts both or neither of a description and its hash, mixed case, an amount finer than a millisatoshi and a leading zero value in x, c or 9, all of which BOLT #11 makes a refusal or says "should" of and Faraday refuses; it also accepts what BOLT #11 leaves open, which Faraday is stricter on: a repeated x, c, m, 9, d, h or n, a text over 1023 characters, an amount with a leading zero, and a required feature bit Faraday does not know; the area counts each refusal as known, naming its reason.

BOLT #11 route hints: the package reads a hop's fees and delta as signed integers (a fee above 2^31 reads negative); the area reads them modulo 2^32 and 2^16 before comparing, and keeps a hint to three hops, as the package drops the last hop of a hint of a multiple of five.

BOLT #11 fallbacks: the package reads only the first fallback address and writes the others in bech32 for every witness version, no bech32m; the area compares Faraday's whole list of fallbacks with the writer's f fields of versions 0 to 18, in order, and its fields of an unknown version by the writer's list.

BOLT #11 features: the package keeps one state per feature, so a feature with both its required and its supported bit set reads as supported only; the writer sets one bit of each pair.

BOLT #12 offers: Core Lightning's bolt12-cli passes the decoder no feature set, so it reads an offer with an even feature bit that Faraday refuses (BOLT #9 defines no offer feature); it also reads feature bytes with a leading zero byte, which BOLT #9 makes not minimal, and a description, issuer or currency holding a character of Unicode's Cc, Cf, Co, Zl or Zp categories, which BOLT #1 refuses and Faraday refuses; and it refuses what Faraday reads when the currency is missing from its ISO 4217 table (the list of 2018) or an amount in bitcoin has a first chain Faraday does not know (it names the unit by the first chain alone), which Faraday reads as BOLT #12 says; the area counts each as known, naming the reason, and every other difference fails the run.

BOLT #12 offers, F232's stricter cases: Faraday refuses what Core Lightning reads (a text over 4,296 characters, a non-zero padding bit, whitespace after a + that is not a space, tab or line break, a chain twice, no known chain, a currency not in the ISO 4217 list Faraday holds, an amount over 21 million bitcoin, an expiry past the year 9999, a first node that is no key, an unassigned character); the area requires Faraday's refusal and counts it as known.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 14060 cases

Secret handling

none: no secret leaves faraday-keys

Not stated; an offer holds no secret.

Nothing secret is held.

Limits

Reading only: no offer is written, requested, paid or stored.

A text over 4,296 characters, mixed case, an invoice request or a field outside the offer's ranges is refused.

An expiry is shown and not judged against the clock; odd fields BOLT #12 does not define are listed and not used.

Faraday's own calls

BOLT #12 and BOLT #1 make mixed case, a misplaced `+`, a malformed TLV stream, a type outside the offer's ranges, an unknown even type, an unknown required feature, text that is not BOLT #1's UTF-8, an amount of zero or without a description, a currency without an amount, an offer naming neither an issuer id nor a path, a path of no hops, a point that is not a curve point, empty chains and more than four bits of padding a refusal, and Faraday refuses them. Where BOLT #12 leaves a case open, Faraday refuses the offer: a text over 4,296 characters (what a QR code holds in capital letters), a non-zero padding bit, whitespace after a `+` other than spaces, tabs and line breaks, a chain named twice, chains naming no Bitcoin network Faraday knows, a currency that is not in its ISO 4217 list, an amount over 21 million bitcoin, an expiry past the year 9999, an offer_paths that holds no path, and a character of Unicode's Cn category. Conservative, F232.

Receive silent payments

SpecificationBIP 352 · BIP 392 · BIP 321 · 1 morePublishedCodeLibrary: bitcoin 0.32Library: secp256k1 0.29Library: sha2 0.11 (through core/faraday-crypto)1 moreFaraday's code: core/faraday-bipFaraday's own codeCross-checked withBIP-352's reference.pyOthers' code
Action

Derives a silent payments address, labels and scan key (BIP 352, 392) and finds the payments a transaction makes to them; reads and writes BIP 392's sp() descriptor.

Specification

BIP 352, Silent Payments, Complete, vendored

BIP 392, Silent Payment Scanning Descriptors, Draft, vendored

BIP 321, URI Scheme for Bitcoin Payments, Complete, vendored

BIP 353, DNS Payment Instructions, Complete, vendored

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-bip: The scan and spend keys are taken at BIP 352's paths; a transaction's eligible inputs give the input hash and shared secret, and every output it pays to the wallet is found with the label it was paid to, up to K_max; the scan private key leaves only as BIP 392's spscan1q text, or the sp() descriptor over it with its key origin, for a named reason. An sp() descriptor, or its key alone after its origin, is read as a silent payments record: the scan key is read for its public key, in constant time, and wiped; an origin that is missing or not BIP 352's path on the key's network is refused, as are sp(KEY,KEY), spspend and a key with a derivation; a text that holds a scan key is a wallet file in Files, and one that holds a spend key a secret no scanner files. The app's check of a transaction takes its previous transactions one at a time and gives the previous outputs, in input order, once every one is known.

Written by Faraday

BIP-352 silent payments (faraday-bip::silent) · No established implementation exists

libsecp256k1's silent payments module is not yet in its Rust bindings.

Decision F178

Checked against

tools/vectors/bip352

Published, by BIP 352's authors (bitcoin/bips).

tools/vectors/bip392

Published, by the authors of BIP 392, BIP 321 and BIP 353 (bitcoin/bips).

core/faraday-bip/tests/all/silent.rs::the_receiver_finds_the_outputs_the_vectors_publish

core/faraday-bip/tests/all/silent.rs::a_labelled_payment_is_found_under_its_label

core/faraday-bip/tests/all/silent.rs::a_transaction_that_does_not_pay_this_wallet_finds_nothing

core/faraday-bip/tests/all/silent.rs::an_address_reads_back_to_the_keys_it_carries

core/faraday-bip/tests/all/silent.rs::the_keys_come_from_the_paths_the_bip_names

faraday/faraday-keys/tests/operations.rs::a_silent_payment_address_is_the_one_bip352_publishes

faraday/faraday-core/tests/all/silent.rs::a_payment_to_this_wallet_is_found_and_one_to_another_is_not

core/faraday-bip/tests/all/silent.rs::a_scan_key_reads_back_to_its_network_and_both_public_keys

core/faraday-bip/tests/all/silent.rs::an_sp_descriptor_faraday_cannot_verify_is_refused

core/faraday-bip/tests/all/silent.rs::keystones_specter_diys_and_coldcards_sp_keystores_are_one_wallet_rooted_at_0f056943

faraday/faraday-core/tests/all/silent.rs::an_sp_descriptor_from_files_loads_as_its_wallet_and_one_whose_keys_are_not_the_keys_is_refused

fuzz silent

Cross-check

Compared with others' code: BIP-352's reference.py, by the BIP's authors, over secp256k1lab, and btclib-wallet's silent_payments.py, by the btclib developers, on btclib's own curve: addresses, labels, input keys and hash, the sender's outputs and the receiver's scan; for BIP 392's spscan key, which has no published code or vectors, that reference's bech32m and curve and btclib's.

Area sp

Faraday's code faraday_bip::silent

Compared with BIP-352's reference.py (bip352/); btclib-wallet's silent_payments.py (btclib/, its own curve) answering every operation beside it.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday.

Vectors Every case of tools/vectors/bip352/, both sides, each answered by btclib-wallet too.

Random cases Inputs of every kind BIP-352 reads, receivers with labels, a sender's outputs and what each receiver finds among them and decoys.

Differences BIP-352: Faraday's sender arithmetic is test-only and has no K_max, so the vector that exceeds it is checked on the receiving side only.

BIP-352's skip of a transaction spending SegWit version 2 or above, which the reference and btclib-wallet leave to their caller, is written in the area from the BIP's own sentence.

BIP-392 publishes no reference code or vectors: its spscan expression is written and read with the BIP-352 reference's bech32m and curve, as BIP-392 states the payload, and the sp() around it is read in the area from the BIP's text. Faraday's own, expected from its rule: an sp() with no key origin, which BIP-392 allows, is refused, as is an origin other than BIP-352's path.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 1000 cases

Source

0.2.0 · core/faraday-bip/src/silent.rs · Receiver::derive

0.2.0 · core/faraday-bip/src/silent.rs · find_payments

0.2.0 · core/faraday-bip/src/silent.rs · decode_scan_key

github.com/bitcoinpasada/faraday

Secret handling

Reveal::VaultEntry

Reveal::OutboxFile

A label tweak times G is libsecp256k1's ecmult_gen through a secret key, in a randomized context; the output tweak is treated as public and multiplied by ecmult, as libsecp256k1's own silent payments module does.

The scan key and the texts that carry it are written in fixed buffers that zeroize on drop. SecretKey is Copy, so every add_tweak, mul_tweak and negate copies the key and only the last copy is erased; the earlier copies are left in memory, later work under the security scope (ESTABLISHED §4.1).

Limits

Scanning stops at K_max, 2323 outputs for one scan key.

A script type the protocol does not list, a taproot input under H, an uncompressed key and a scriptSig holding no key matching its hash are skipped.

The wallet record keeps public values only.

Faraday's own calls

The faraday-silent 1 record holds the kind, the network, the key's origin, the label count and the address. Neutral.

no decision

Signing

14 actions · 4 with Faraday's own code · 13 cross-checked with others' code · 7 with Faraday's second version · 1 not cross-checked

Read a PSBT

SpecificationBIP 174PublishedCodeLibrary: bitcoin 0.32Library: miniscript 12.3 (through core/faraday-bip)Library: sha2 0.11 (through core/faraday-crypto)1 moreFaraday's code: core/faraday-psbtFaraday's own codeCross-checked withBitcoin Core v31.1 (decodepsbtOthers' code
Action

Reads a version 0 PSBT from bytes or base64 and writes it back as it was read.

Specification

BIP 174, Partially Signed Bitcoin Transaction Format, Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: miniscript 12.3.7, by the rust-bitcoin developers (rust-miniscript), through core/faraday-bip.

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Library: base64ct 1.8.3, by the RustCrypto developers, through core/faraday-bip.

Faraday's code: core/faraday-psbt: Refuses a version other than 0, version 2 fields inside a version 0 file, a 65-byte taproot signature whose sighash byte is 0 (BIP 341) and a key origin of more than 16 steps; a field not changed since it was read is written back exactly as read. The app tells a file is a PSBT by reading it once as bytes, else as base64 text, when it comes in.

Written by Faraday

PSBT inspection, signing orchestration and verification logic (faraday-psbt) · Faraday's own specification

What Faraday checks before it signs is Faraday's own rule; the PSBT format itself is rust-bitcoin's.

Decision F178

Checked against

tools/vectors/psbt

Published, by BIP 174's and RFC 6979's authors; the spends and finalized answers Bitcoin Core v31.1 made on regtest. Faraday's own known answers: the wallet policies, the warning PSBTs and the PSBTs this tree signed.

tools/vectors/psbt-bips

Published, by the authors of BIP 174, BIP 370 and BIP 371 (bitcoin/bips).

core/faraday-psbt/tests/all/vectors.rs::bip174_round_trips_and_rejections

core/faraday-psbt/tests/all/vectors.rs::parse_errors

core/faraday-psbt/tests/all/vectors.rs::bip174_role_vectors_round_trip

core/faraday-psbt/tests/all/registered.rs::an_origin_of_more_than_sixteen_steps_is_refused

fuzz psbt_parse

Cross-check

Compared with others' code: Bitcoin Core v31.1 (decodepsbt, and combinepsbt as its writer), by Bitcoin Core's contributors; HWI's psbt.py, by Ava Chow and HWI's contributors, for the version 2 fields BIP-370 refuses in version 0; btclib-wallet's Psbt.parse, by the btclib developers, which also refuses a 65-byte taproot signature whose sighash byte is 0 (BIP-341).

Area psbt

Faraday's code faraday_psbt::Psbt (version 0, over bitcoin), faraday_psbt::v2::PsbtV2 (version 2, Faraday's own)

Compared with Bitcoin Core v31.1's bitcoind on regtest for version 0 (decodepsbt, combinepsbt of one PSBT as its writer, the test framework's taproot_tree_helper); HWI's psbt.py (hwi/) for version 2 and the version 2 fields refused in version 0, its version 0 form read by Core; btclib-wallet's Psbt (btclib/, on btclib's own curve) for both versions: parse, lock_time, tx, to_v0 and to_v2, which also decides the refusals of a taproot signature whose sighash byte is 0, of bytes after the last map and of a stream that ends inside a map.

Checked first: Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked; HWI's vendored files and btclib's wheels are hashed against references.sha256 before any run; a published vector's answer is required of the side that decides.

Whether a PSBT_GLOBAL_VERSION of 0 is written: Core reads a version 0 PSBT alike with it or without it, and Faraday writes it back as read.

Vectors Every PSBT of BIP-174's, 370's and 371's test vectors (tools/vectors/psbt-bips/), with BIP-370's locktimes, read by btclib too.

Random cases Random version 0 and 2 PSBTs with every field Faraday reads, taproot trees among them, in random order, read field for field as Core reads them and written back byte for byte as read and as Core writes them, then broken one rule at a time; each version 0 PSBT made version 2 as HWI's convert_to_v2 and btclib's to_v2 make it, and back to its own bytes; BIP-370's locktime, transaction and version 0 form under every mix of required locktimes, also btclib's lock_time, tx and to_v0; one version 0 PSBT in eight carries fields btclib refuses and btclib is not asked of it.

Differences Version 0 made version 2: HWI's convert_to_v2 leaves out the PSBT_OUT_SCRIPT of an output whose script is empty, which BIP-370 requires; Faraday and btclib write it, and the rest of the PSBT must be the same.

Bitcoin Core reads a version 0 PSBT with a version 2 field as valid, the field as unknown; Faraday refuses it, as BIP-370 does, and so do HWI, which decides it, and btclib.

A taproot signature of 65 bytes whose sighash byte is 0, which neither Core nor HWI refuses, and bytes after a version 2 PSBT's last map or a stream that ends inside one, which HWI reads: Faraday refuses each, as BIP-341 and BIP-174 do, and so does btclib, which decides them (the stream ending inside a map checked, as the specification marked it not checked).

PSBT version 2 (faraday_psbt::v2): a BIP-370 key with key data is an unknown key; BIP-174's and BIP-371's fields inside are checked only when the PSBT is bridged to version 0, except a taproot signature whose sighash byte is 0, refused on reading. HWI checks them on reading; the area requires HWI and btclib to read the PSBT without those pairs, to Faraday's locktime and transaction. Where HWI reads a value shorter than its length says and makes a version 0 PSBT of it, which Faraday does not, Core must refuse the version 0 PSBT of the PSBT's own pairs, and btclib refuses the PSBT.

Btclib reads some PSBTs that Core and Faraday refuse (a key with key data on a field that takes none, for one): btclib is not asked to refuse what Core refuses, only what Core and HWI read and Faraday refuses.

Btclib refuses what the BIPs allow: an ECDSA signature that is not strict DER with a low S and an r that is a point's x, a sighash type of the seven it defines, a BIP-375 field in a version 0 global map, a previous transaction and a witness UTXO that disagree. About one version 0 PSBT in eight carries such a field, and btclib is not asked of it or of what is made from it. Pairs btclib does not write back as read (an empty final witness) and what it writes in their place are left out of the conversions it is compared on, and leaf hashes are compared sorted, as it writes them.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 15000 cases

Source

0.2.0 · core/faraday-psbt/src/psbt.rs · Psbt::parse_bytes

0.2.0 · core/faraday-psbt/src/psbt.rs · Psbt::parse_base64

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

No secret is handled.

Nothing secret is held.

Limits

Version 0 here; a version 2 file is read by psbt-v2 and signed as its version 0 form.

Version 2 fields in a version 0 file are refused.

A 65-byte taproot signature whose sighash byte is 0 is refused.

A key origin of more than 16 steps is refused.

Faraday's own calls

A key origin of more than 16 steps anywhere in a PSBT is refused when it is parsed. Conservative, F155.

Read a version 2 PSBT

SpecificationBIP 370PublishedCodeLibrary: bitcoin 0.32Faraday's code: core/faraday-psbtFaraday's own codeCross-checked withHWI's psbt.py (readingOthers' codeFaraday's second version
Action

Reads a version 2 PSBT as its key-value maps, checks BIP 370's shape and converts it to version 0 and back.

Specification

BIP 370, PSBT Version 2, Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Faraday's code: core/faraday-psbt: bitcoin reads version 0 only, so the maps are read here. Every pair is kept as read and written back with what was set; a version 2 PSBT becomes version 0 once every output has a script, and only the signing fields (partial signatures, final scripts, taproot and MuSig2 signatures and nonces) are taken back from it. A version 0 PSBT becomes version 2 and back to its own bytes. The app reads a version 2 file wherever it reads a PSBT, signs its version 0 form and writes the version 2 PSBT that came in with the signatures added; where they do not go back into it, nothing is written or shown, never the version 0 form.

Written by Faraday

The PSBT version 2 reader (faraday-psbt::v2) · No established implementation exists

rust-bitcoin reads only version 0 PSBTs; its version 2 crate is pre-release.

Decision F178

Checked against

tools/vectors/psbt-bips

Published, by the authors of BIP 174, BIP 370 and BIP 371 (bitcoin/bips).

core/faraday-psbt/tests/all/bips.rs::every_bip_vector_is_read_as_its_bip_says

core/faraday-psbt/tests/all/bips.rs::bip370s_version_0_with_version_2_fields_are_refused

core/faraday-psbt/tests/all/bips.rs::bip370s_invalid_locktimes_and_a_missing_script_are_refused

core/faraday-psbt/tests/all/bips.rs::bytes_after_the_last_map_are_refused

core/faraday-psbt/tests/all/bips.rs::every_valid_version_0_vector_made_version_2_turns_back_into_its_bytes

core/faraday-psbt/tests/all/bips.rs::a_signing_pass_brings_back_its_signatures_and_nothing_else

faraday/faraday-core/tests/all/psbt_v2.rs::bip370s_vectors_read_as_the_bip_says_binary_and_base64

faraday/faraday-core/tests/all/psbt_v2.rs::a_testkit_psbt_made_version_2_and_back_is_byte_identical

faraday/faraday-core/tests/all/psbt_v2.rs::a_version_2_spend_signs_as_its_version_0_form_and_goes_back_out_as_version_2

faraday/faraday-core/tests/all/psbt_v2.rs::signatures_that_do_not_go_back_into_the_version_2_psbt_write_nothing

fuzz psbt_parse

fuzz psbt_v2

Cross-check

Compared with others' code: HWI's psbt.py (reading, compute_lock_time, get_unsigned_tx, convert_to_v0, convert_to_v2), by Ava Chow and HWI's contributors, with both version 0 forms read by Bitcoin Core v31.1; btclib-wallet's Psbt (parse, lock_time, tx, to_v0, to_v2), by the btclib developers, which also refuses bytes after the last map, a stream that ends inside a map and a 65-byte taproot signature whose sighash byte is 0.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the choice of the pairs Faraday leaves to the bridge to version 0, and the version 0 PSBT of a PSBT's own pairs that Core judges where HWI repairs a short value, written in area_psbt.py.

Area psbt

Faraday's code faraday_psbt::Psbt (version 0, over bitcoin), faraday_psbt::v2::PsbtV2 (version 2, Faraday's own)

Compared with Bitcoin Core v31.1's bitcoind on regtest for version 0 (decodepsbt, combinepsbt of one PSBT as its writer, the test framework's taproot_tree_helper); HWI's psbt.py (hwi/) for version 2 and the version 2 fields refused in version 0, its version 0 form read by Core; btclib-wallet's Psbt (btclib/, on btclib's own curve) for both versions: parse, lock_time, tx, to_v0 and to_v2, which also decides the refusals of a taproot signature whose sighash byte is 0, of bytes after the last map and of a stream that ends inside a map.

Checked first: Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked; HWI's vendored files and btclib's wheels are hashed against references.sha256 before any run; a published vector's answer is required of the side that decides.

Whether a PSBT_GLOBAL_VERSION of 0 is written: Core reads a version 0 PSBT alike with it or without it, and Faraday writes it back as read.

Vectors Every PSBT of BIP-174's, 370's and 371's test vectors (tools/vectors/psbt-bips/), with BIP-370's locktimes, read by btclib too.

Random cases Random version 0 and 2 PSBTs with every field Faraday reads, taproot trees among them, in random order, read field for field as Core reads them and written back byte for byte as read and as Core writes them, then broken one rule at a time; each version 0 PSBT made version 2 as HWI's convert_to_v2 and btclib's to_v2 make it, and back to its own bytes; BIP-370's locktime, transaction and version 0 form under every mix of required locktimes, also btclib's lock_time, tx and to_v0; one version 0 PSBT in eight carries fields btclib refuses and btclib is not asked of it.

Differences Version 0 made version 2: HWI's convert_to_v2 leaves out the PSBT_OUT_SCRIPT of an output whose script is empty, which BIP-370 requires; Faraday and btclib write it, and the rest of the PSBT must be the same.

Bitcoin Core reads a version 0 PSBT with a version 2 field as valid, the field as unknown; Faraday refuses it, as BIP-370 does, and so do HWI, which decides it, and btclib.

A taproot signature of 65 bytes whose sighash byte is 0, which neither Core nor HWI refuses, and bytes after a version 2 PSBT's last map or a stream that ends inside one, which HWI reads: Faraday refuses each, as BIP-341 and BIP-174 do, and so does btclib, which decides them (the stream ending inside a map checked, as the specification marked it not checked).

PSBT version 2 (faraday_psbt::v2): a BIP-370 key with key data is an unknown key; BIP-174's and BIP-371's fields inside are checked only when the PSBT is bridged to version 0, except a taproot signature whose sighash byte is 0, refused on reading. HWI checks them on reading; the area requires HWI and btclib to read the PSBT without those pairs, to Faraday's locktime and transaction. Where HWI reads a value shorter than its length says and makes a version 0 PSBT of it, which Faraday does not, Core must refuse the version 0 PSBT of the PSBT's own pairs, and btclib refuses the PSBT.

Btclib reads some PSBTs that Core and Faraday refuse (a key with key data on a field that takes none, for one): btclib is not asked to refuse what Core refuses, only what Core and HWI read and Faraday refuses.

Btclib refuses what the BIPs allow: an ECDSA signature that is not strict DER with a low S and an r that is a point's x, a sighash type of the seven it defines, a BIP-375 field in a version 0 global map, a previous transaction and a witness UTXO that disagree. About one version 0 PSBT in eight carries such a field, and btclib is not asked of it or of what is made from it. Pairs btclib does not write back as read (an empty final witness) and what it writes in their place are left out of the conversions it is compared on, and leaf hashes are compared sorted, as it writes them.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 15000 cases

Source

0.2.0 · core/faraday-psbt/src/v2.rs · PsbtV2::parse_bytes

0.2.0 · core/faraday-psbt/src/v2.rs · PsbtV2::to_v0

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

No secret is handled.

Nothing secret is held.

Limits

A taproot signature with a sighash byte of 0 is refused.

A key twice in a map, and bytes after the last map, are refused.

The fallback locktime, the modifiable flags, the sequence and the required locktimes are held to their sizes and ranges.

A version 2 PSBT with an output that has no script yet (a silent payment's) is not signed.

Faraday's own calls

The reader refuses what BIP 370 marks invalid and keeps every pair as read. Conservative.

no decision

Review what a PSBT pays

SpecificationBIP 174 · BIP 173 · BIP 350PublishedCodeLibrary: bitcoin 0.32Library: miniscript 12.3Library: sha2 0.11 (through core/faraday-crypto)1 moreFaraday's code: core/faraday-psbtCross-checked withbtclib-wallet's descriptor wallet (update_psbt_outputOthers' codeFaraday's second version
Action

Reads what a PSBT spends and pays: amounts, fee, verified change, warnings, and the wallet it defines for registering.

Specification

BIP 174, Partially Signed Bitcoin Transaction Format, Deployed

BIP 173, Base32 address format for native v0-16 witness outputs, Deployed

BIP 350, Bech32m Format for v1+ Witness Addresses, Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: miniscript 12.3.7, by the rust-bitcoin developers (rust-miniscript).

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-psbt: Change is verified only when the output's script is the address a loaded key's account, or a registered wallet, derives at the stated path; a claim on a loaded key that derives another script is a block. Warnings are ranked Info, Caution, Danger and Blocked. A wallet is offered for registering only when the PSBT's global xpubs give every script of its inputs and outputs. A PSBT's network is read from its global xpubs, else from the coin type of a BIP 44, 49, 84, 86 or 48 key path, else it is the session's. The signed-amount memory keeps the SHA-256 of the unsigned transaction and the amount each input states, and only when every input states one. Another device's signatures are merged only into a PSBT of the same transaction that asks the same sighashes, and are refused when one is invalid. The register sheet's hold registers a wallet only once its descriptor gives the spend's scripts and one of its keys is a loaded key's own at its path. An output over 21,000,000 BTC, outputs whose total is over it, or an amount an input states or their total over it, is a block, as Bitcoin Core's CheckTransaction and CheckTxInputs refuse them (`transaction::money_total`).

Checked against

tools/vectors/psbt

Published, by BIP 174's and RFC 6979's authors; the spends and finalized answers Bitcoin Core v31.1 made on regtest. Faraday's own known answers: the wallet policies, the warning PSBTs and the PSBTs this tree signed.

core/faraday-psbt/tests/all/inspect.rs::verified_change_for_every_script_type

core/faraday-psbt/tests/all/inspect.rs::spoofed_change_blocks_signing

core/faraday-psbt/tests/all/inspect.rs::foreign_fingerprint_is_unverified_change

core/faraday-psbt/tests/all/inspect.rs::high_fee_thresholds

core/faraday-psbt/tests/all/inspect.rs::missing_and_lying_utxo

core/faraday-psbt/tests/all/inspect.rs::network_mismatch

core/faraday-psbt/tests/all/inspect.rs::amounts_over_21_million_bitcoin_block_signing_as_core_refuses_them

core/faraday-psbt/tests/all/registered.rs::an_unregistered_two_of_three_input_is_blocked_held_or_not

core/faraday-psbt/tests/all/registered.rs::a_psbt_with_global_xpubs_registers_its_wallet_and_then_signs

faraday/faraday-core/tests/all/register_wallet.rs::register_this_wallet_shows_the_wallet_and_the_hold_registers_it_and_it_signs

fuzz psbt_parse

Cross-check

Compared with others' code: btclib-wallet's descriptor wallet (update_psbt_output, index_of), by the btclib developers, on btclib's own curve; Bitcoin Core v31.1 (decodepsbt, analyzepsbt, deriveaddresses, and a watch-only descriptor wallet's getaddressinfo and walletprocesspsbt), by the Bitcoin Core developers.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the rule that a script of several keys, a miniscript or a taproot tree is change only for a registered wallet, which outputs claim a held key, and the account keys a registered wallet names, derived in the area.

Area psbt-review

Faraday's code faraday_psbt::inspect (amounts in and out, the fee, verified change and the spoofed-change and missing-UTXO warnings), over faraday_psbt::Psbt and the keys and registered wallets the Sign screen holds

Compared with Bitcoin Core v31.1's bitcoind on regtest, offline: decodepsbt and analyzepsbt for amounts and fee, deriveaddresses from tprv descriptors for the addresses the PSBTs pay, createpsbt, createrawtransaction and descriptorprocesspsbt to make the PSBTs; btclib's descriptor wallet (update_psbt_output and index_of, btclib/, its own curve) for which outputs are change; a watch-only descriptor wallet on the same node (getaddressinfo, walletprocesspsbt) for where each change claim's script is; the area adds each input's UTXO fields, splices a spoofed output, derives the account keys a registered wallet names (checked by Core deriving the same addresses from them), and keeps the rule that a script of several keys is change only for a registered wallet.

Checked first: Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked; every PSBT is one Core made and read, and every change decision is btclib's whole-script comparison at the chain and index the output states, which Core's own wallet must find at the same place.

Faraday's other warnings (high fee, dust, address reuse, sighash, network, locktime) and thresholds, which are Faraday's own rules; the estimated virtual size and fee rate (Core's estimate needs signing data the PSBT does not carry).

Vectors none: Core's decoding and btclib's change decision are the references, over each wallet shape with change, spoofed change, a foreign claim and missing UTXO data in the prelude.

Random cases PSBTs of one to three inputs and one to four outputs over single-key accounts (P2PKH, P2SH-P2WPKH, P2WPKH, P2TR) and registered wallets (sortedmulti in P2WSH, a miniscript in P2WSH, a taproot tree, a taproot sortedmulti_a) or the same wallets unregistered: witness UTXOs, previous transactions and no UTXO data, fees from nothing to a third of the inputs, payments, change on either chain, another wallet's change, and spoofed change over the wallet's own script at another index, another wallet's and a stranger's; one key held, two, or none of the wallet's.

Differences Change of a script of several keys, a miniscript or a taproot tree: Faraday verifies it only for a registered wallet that holds a loaded key, and counts it as paid to others otherwise, which btclib's descriptor wallet has no notion of. The area expects the same refusal, and does not compare the spoof warning for an unregistered wallet (Faraday's reading of such a claim depends on the account path it states).

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 2000 cases

Secret handling

none: no secret leaves faraday-keys

Only public account keys are derived from a master key; the review compares public data. The library does not state the derivation's timing.

The review keeps public keys only; the derived private keys are dropped inside the master key's account_xpub.

Limits

Supported input scripts: p2pkh, p2sh-p2wpkh, p2wpkh, p2tr key path, and multi or sortedmulti in p2sh, p2wsh and p2sh-p2wsh, with miniscript and taproot trees through a registered wallet.

Multisig change is verified only by re-deriving it from a registered wallet.

A SegWit v0 input with no previous transaction in a transaction of several inputs is blocked.

Only a high fee and an absurd fee rate can be held past; every other danger and every block has no way past.

Another device's PSBT for another transaction, one that asks another sighash of an input and one with a signature that does not verify are refused, never merged.

An amount or a total over 21,000,000 BTC, in the outputs or the amounts the inputs state, blocks signing.

Faraday's own calls

Change under an unloaded key, or at a path under no loaded account, counts as a payment to others. Conservative, F136.

A script of several keys is signed only for a registered wallet that holds a loaded key. Conservative, F135.

A miniscript or a taproot tree of one key is signed only through its registered wallet. Conservative, F141.

A SegWit v0 input with only a witness UTXO in a transaction of several inputs is refused, which BIP 174 allows. Conservative, F155.

The signed-amount memory refuses one transaction stated again with other amounts. Conservative, F155.

Review the sighash types

SpecificationBIP 143 · BIP 341 · BIP 342PublishedCodeLibrary: bitcoin 0.32Faraday's code: core/faraday-psbtCross-checked withbtclib's sig_hash (legacyOthers' code
Action

Reads each input's sighash type and signs SIGHASH_ALL and SIGHASH_DEFAULT, and ALL with ANYONECANPAY after a caution.

Specification

BIP 143, Transaction Signature Verification for Version 0 Witness Program, Deployed

BIP 341, Taproot: SegWit version 1 spending rules, Deployed

BIP 342, Validation of Taproot Scripts, Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Faraday's code: core/faraday-psbt: Names the sighash kind of every input; ALL|ANYONECANPAY is a caution, NONE, a non-standard value and SINGLE with an output are dangers with no way past, SINGLE with no output of its index is blocked. The tx area checks the signature hashes bitcoin computes for each type; the naming and ranking of a sighash is not cross-checked.

Checked against

tools/vectors/sighash

Published, by Bitcoin Core's sighash.json, v31.1, by the Bitcoin Core developers; BIP 143's and BIP 341's authors.

core/faraday-psbt/tests/all/inspect.rs::unusual_sighash

core/faraday-psbt/tests/all/inspect.rs::single_on_an_input_with_no_output_of_its_index_is_refused_even_held

core/faraday-psbt/tests/all/inspect.rs::single_on_an_input_with_its_output_is_refused_even_held

core/faraday-psbt/tests/all/inspect.rs::all_and_default_still_sign_with_nothing_held

fuzz psbt_parse

Cross-check

Compared with others' code: btclib's sig_hash (legacy, segwit_v0 and taproot), by the btclib developers; and Bitcoin Core's functional-test framework, v31.1, by Bitcoin Core's contributors.

Area tx

Faraday's code faraday_psbt::transaction::read_raw, faraday_core::decode::decode's txid, wtxid and output addresses, bitcoin's SighashCache as faraday_psbt::sign calls it

Compared with btclib's Tx.parse and sig_hash (btclib/); Bitcoin Core v31.1's decoderawtransaction on regtest (core_node.py) for the transactions; Core's messages.py and script.py (core/) for the signature hashes; the refusal of a transaction with no inputs is ours.

Checked first: Its vendored files and the btclib wheels are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; each published signature hash is checked against the framework first.

Vectors Core's 500 legacy sighashes, BIP-143's thirteen, BIP-341's key-path sighashes (tools/vectors/sighash/).

Random cases Random transactions with and without witnesses (txid, wtxid, weight, bytes) read by btclib and Core's decoderawtransaction, cut or lengthened, and shown by Faraday's Decode view (txid, wtxid, each output's address, none where Core gives none) against Core's; every input hashed as legacy, BIP-143 P2WPKH and P2WSH, BIP-341 key and script path under every hash type, by btclib and the framework.

Differences Decode refuses a transaction whose outputs total over 21,000,000 BTC, as Core does not in decoderawtransaction; the corpus asks Decode only of transactions within that total.

Legacy sighash: bitcoin hashes the script code as given, Core and btclib remove every OP_CODESEPARATOR first. Faraday's legacy spends (P2PKH, P2SH multisig) have none.

Core's decoderawtransaction reads bytes whose marker 00 01 it takes as a count of no inputs and one output, a legacy transaction of no inputs; Faraday refuses a transaction with no inputs, and the area counts a case where btclib reads inputs of such bytes as this difference.

BIP-341's refusals (SIGHASH_SINGLE without an output, a hash type it does not list) are btclib's: the framework hashes those anyway and is not asked.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Secret handling

none: no secret leaves faraday-keys

No secret is handled.

Nothing secret is held.

Limits

SIGHASH_ALL and SIGHASH_DEFAULT are signed, and ALL with ANYONECANPAY after a caution; NONE, SINGLE and non-standard sighashes are refused.

SIGHASH_SINGLE on an input with no output of its index is blocked.

Faraday's own calls

NONE, SINGLE and non-standard sighashes are refused for signing; ALL with ANYONECANPAY is signed after a caution. Conservative, F136.

Sign with ECDSA

SpecificationBIP 143 · BIP 174 · RFC 6979PublishedCodeLibrary: secp256k1 0.29Library: bitcoin 0.32Faraday's code: core/faraday-psbtCross-checked withBitcoin Core v31.1Others' codeFaraday's second version
Action

Signs a transaction input with ECDSA, from the key the PSBT's origin names, and checks the key against the script.

Specification

BIP 143, Transaction Signature Verification for Version 0 Witness Program, Deployed

BIP 174, Partially Signed Bitcoin Transaction Format, Deployed

RFC 6979, Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA), Informational

Code

Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Faraday's code: core/faraday-psbt: Derives the key at the origin's path from the matching master key and refuses unless it is the key named and the script holds it; grinds for a low r by default; signs twice and refuses unless the bytes match; verifies the signature before writing it. faraday-keys lends the master keys and passes the default nonce and aux_rand choices.

Checked against

tools/vectors/psbt

Published, by BIP 174's and RFC 6979's authors; the spends and finalized answers Bitcoin Core v31.1 made on regtest. Faraday's own known answers: the wallet policies, the warning PSBTs and the PSBTs this tree signed.

core/faraday-psbt/tests/all/nonce.rs::rfc6979_cross_implementation_vectors

core/faraday-psbt/tests/all/nonce.rs::signing_twice_is_byte_identical

core/faraday-psbt/tests/all/nonce.rs::low_r_gives_the_shortest_signature

core/faraday-psbt/tests/all/sign.rs::sign_verify_finalize_every_script_type

core/faraday-psbt/tests/all/sign.rs::key_origin_that_does_not_match_the_derived_key_is_refused

core/faraday-psbt/tests/all/sign.rs::signing_needs_a_matching_master_key

core/faraday-psbt/tests/all/multisig.rs::a_cosigner_key_under_a_loaded_fingerprint_is_not_ours

self-test ecdsa_vector

no fuzz target: No target runs sign: it needs a master key and a PSBT that inspect accepts; psbt_parse fuzzes the PSBT it reads

Cross-check

Compared with others' code: Bitcoin Core v31.1, by the Bitcoin Core developers (descriptorprocesspsbt signs, testmempoolaccept judges the spend), with Core's key.py and script.py for the first RFC 6979 nonce; python-ecdsa, by Brian Warner and Hubert Kario (no Bitcoin code), which makes that nonce's signature again byte for byte and verifies the low-R ones; Core shares libsecp256k1's curve maths with Faraday's.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: Faraday's refusals (F136, F141) and the inputs a wallet's rule leaves unsigned, the script code of the hash the first RFC 6979 nonce is checked under, in area_sign.py; the keys of those checks are btclib's.

Area sign

Faraday's code faraday_psbt::sign (every held key selected, deterministic Schnorr, both RFC 6979 nonce rules) and faraday_psbt::finalize

Compared with Bitcoin Core v31.1 on regtest (core_node.py): descriptorprocesspsbt signs from the held masters' keys, finalizepsbt finalizes and extracts, testmempoolaccept judges each finalized transaction over its funding on the node; BIP-340's reference (secp256k1lab) and Core's key.py for the deterministic nonces, over Core's script.py sighashes; python-ecdsa (the distribution's package) and btclib (btclib/, its own curve) as a second curve lineage, beside them: every ECDSA signature again under plain RFC 6979 or verified, every BIP-340 signature verified and made again; btclib-wallet's finalizer (psbt.finalize with its miniscript solver) finalizes every input Faraday finalizes again and gives the same scriptSig and witness; for each sweep, btclib reads the WIF (scalar, compression, public key) and signs and finalizes the sweep on its own curve, and python-ecdsa makes the first-nonce signature of each input again, byte for byte; python-bip380 (miniscript/) reads the leaves. Faraday's refusals and the inputs a wallet's rule leaves unsigned are ours, in area_sign.py.

Checked first: Core is the pinned release, hashed against its pin before every run; the vendored files are hashed against references.sha256; a published vector's answer is required of Core as well as of Faraday; every ECDSA and BIP-340 signature Core makes is checked to verify under the hash the area computes before that hash is used for Faraday's deterministic nonces.

Vectors BIP-174's signer, finalizer and extractor vectors; the Core-built spends of tools/vectors/psbt/ (2-of-3 sortedmulti, the Liana wallet down both paths, a taproot tree by a leaf and by the key path, BIP 387's taproot multisig), signed by every subset of their keys; the finalizer vectors there (or_b's smaller signature, the taproot leaves that tie by count, the taproot multisig and MuSig2 spends).

Random cases PSBTs of one to four inputs, each spending a funding output on the node: P2PKH, P2SH-P2WPKH, P2WPKH, multi/sortedmulti in P2SH, P2WSH and P2SH-P2WSH, P2TR key path, P2TR script path (pk, pkh, timelocked keys, or_d, multi_a) with the key path beside it, miniscript in P2WSH and P2SH-P2WSH; held and foreign keys, cosigners' signatures already on (Core's), every standard sighash type, timelocks met and not; Core's signatures (ECDSA byte for byte, BIP-340 by verification and the deterministic nonce), each final scriptSig and witness and the extracted transaction Core's, the cleared fields, and every finalized transaction accepted by Core's mempool; an origin that derives another key refused; sweeps: a WIF key's P2PKH, P2WPKH and P2SH-P2WPKH outputs (P2PKH alone for an uncompressed key) spent beside another key's, signed by Core from the WIF and by faraday_psbt::sweep::sign, byte for byte, finalized and accepted by the mempool.

Differences PSBT signing: Faraday refuses to sign a SegWit v0 input with no previous transaction in a transaction of more than one input; Core signs it, and BIP-174's own signer vector is such a PSBT. The refusal is ours, checked and counted. Faraday holds a finalized input to the same rule and refuses the PSBT when such an input is final, except a taproot one, whose final witness is the coordinator's.

PSBT signing, wallets: Faraday signs an input spent from a script of several keys (a multi of two or more, a miniscript naming two or more, a taproot script path whose carried leaves name two or more with its internal key, or are not its whole tree) only for a registered wallet that holds one of its keys and whose script it is; Core signs any. The area refuses, by a rule of its own, where no wallet the request registers holds a held key and gives the input, and counts it only where Faraday's refusal is that the wallet is not registered. A miniscript or a taproot tree of one key is signed only through such a wallet, and is otherwise left unsigned while the rest is signed (F141); the area takes Core's signatures off it. Half the corpus's multi, miniscript and taproot-tree inputs come with their wallet registered, so their signatures are still compared. A registered tree's every leaf has its wait met, since Faraday refuses a path that can never be valid, which the area does not work out.

PSBT signing: Faraday refuses a PSBT any input of which asks for a NONE or SINGLE sighash, and one that none of the held keys can sign: dangers no hold accepts (F136). Core signs the first and answers the second with nothing signed. The area expects both refusals by a rule of its own, counting a held key as taking part as Faraday's inspection does (a miniscript or a taproot tree only through a wallet in use), checks that Faraday's refusal names the danger, and counts them.

Taproot pkh leaves: Faraday signs a taproot leaf that checks its key by hash but does not finalize it: miniscript 12's finalizer looks the key up among the ECDSA origins and panics, and would push 33 bytes where the leaf hashed 32. Core finalizes such a leaf; the area takes the signatures under it off before Core finalizes, and counts each input Core would otherwise have finalized another way.

btclib's finalizer writes no taproot leaf that is neither a single key nor multi_a, and refuses to choose among leaves a PSBT signs: an input of another leaf is judged by Core alone (counted as a known difference), and btclib is given only the signatures of the leaf Faraday spent. It writes a plain multisig from the smallest m signatures on hand where Core and Faraday write the first m signers': btclib is given only the signatures Faraday's input carries, so it judges the script written from them and Core judges which were chosen.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 1580 cases

Secret handling

none: no secret leaves faraday-keys

libsecp256k1 documents its signing as constant time; the low-R grind repeats the signing until r is small, so the number of signings varies, which the library does not address.

The derived key lives in the signing function's frame and is wiped when it is dropped; no secret leaves faraday-keys.

Limits

ALL is signed, and ALL with ANYONECANPAY after a caution; NONE, SINGLE and non-standard sighashes are refused.

A SegWit v0 input with no previous transaction, in a transaction of several inputs, is refused.

A key comes from the PSBT's origin only; a multisig key with no origin is refused.

The app signs with the low-R nonce; the first RFC 6979 nonce is the library's other choice and is not offered in the app.

Faraday's own calls

A key comes from the PSBT's origin only, under the master key's fingerprint; a key whose derived public key differs from the one named, or that the script does not hold, is refused, and an origin under an account's fingerprint matches no key. Conservative, F155.

A script of several keys is signed only for a registered wallet that holds a loaded key. Conservative, F135.

Only a high fee and an absurd fee rate can be held past; every other danger refuses. Conservative, F136.

Each signature is made twice and compared, and verified before it is written. Neutral.

no decision

Low-R grinding is the default nonce. Neutral.

no decision

Sign a WIF key's sweep

SpecificationBIP 143 · BIP 174 · RFC 6979PublishedCodeLibrary: secp256k1 0.29Library: bitcoin 0.32Faraday's code: core/faraday-psbtCross-checked withBitcoin Core v31.1Others' code
Action

Signs the inputs of a PSBT that spend a WIF key's own outputs, after a review that names each output's loaded wallet.

Specification

BIP 143, Transaction Signature Verification for Version 0 Witness Program, Deployed

BIP 174, Partially Signed Bitcoin Transaction Format, Deployed

RFC 6979, Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA), Informational

Code

Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Faraday's code: core/faraday-psbt: An input is the key's when the output it spends pays one of the key's scripts, not by a key origin; the PSBT is inspected and a block, or a danger that is not holdable, refuses it, but for no loaded master key taking part; every input of the key is checked before the first is signed; each signature is made twice with the low-R nonce, compared and verified before it is written. The review searches each loaded wallet's first hundred addresses on each chain for every output and flags the others.

Checked against

tools/vectors/sighash

Published, by Bitcoin Core's sighash.json, v31.1, by the Bitcoin Core developers; BIP 143's and BIP 341's authors.

core/faraday-psbt/tests/all/sweep.rs::bip143s_nested_segwit_example_sweeps_to_its_published_transaction

core/faraday-psbt/tests/all/sweep.rs::a_sweep_signs_the_keys_inputs_alone_and_finishes_them

core/faraday-psbt/tests/all/sweep.rs::an_uncompressed_key_sweeps_its_legacy_output_and_needs_its_previous_transaction

core/faraday-psbt/tests/all/sweep.rs::a_psbt_of_another_key_signs_nothing

faraday/faraday-core/tests/all/sweep.rs::the_sweeps_psbt_is_reviewed_against_the_wallets_and_signed_with_a_hold

faraday/faraday-core/tests/all/sweep.rs::a_psbt_of_another_key_signs_nothing

no fuzz target: No target runs sign: it needs a key and a PSBT that inspect accepts; psbt_parse fuzzes the PSBT and xkey the WIF it reads

Cross-check

Compared with others' code: Bitcoin Core v31.1, by the Bitcoin Core developers, which signs the same sweep from pkh(), wpkh() and sh(wpkh()) descriptors of the WIF (descriptorprocesspsbt), finalizes it and judges it (testmempoolaccept); BIP-143's published P2SH-P2WPKH example signs to its transaction; Core shares libsecp256k1's curve maths with Faraday's, so python-ecdsa, by Brian Warner and Hubert Kario, signs each sweep again under the first RFC 6979 nonce byte for byte, and btclib, by the btclib developers, signs and finalizes each on its own curve.

Area sign

Faraday's code faraday_psbt::sign (every held key selected, deterministic Schnorr, both RFC 6979 nonce rules) and faraday_psbt::finalize

Compared with Bitcoin Core v31.1 on regtest (core_node.py): descriptorprocesspsbt signs from the held masters' keys, finalizepsbt finalizes and extracts, testmempoolaccept judges each finalized transaction over its funding on the node; BIP-340's reference (secp256k1lab) and Core's key.py for the deterministic nonces, over Core's script.py sighashes; python-ecdsa (the distribution's package) and btclib (btclib/, its own curve) as a second curve lineage, beside them: every ECDSA signature again under plain RFC 6979 or verified, every BIP-340 signature verified and made again; btclib-wallet's finalizer (psbt.finalize with its miniscript solver) finalizes every input Faraday finalizes again and gives the same scriptSig and witness; for each sweep, btclib reads the WIF (scalar, compression, public key) and signs and finalizes the sweep on its own curve, and python-ecdsa makes the first-nonce signature of each input again, byte for byte; python-bip380 (miniscript/) reads the leaves. Faraday's refusals and the inputs a wallet's rule leaves unsigned are ours, in area_sign.py.

Checked first: Core is the pinned release, hashed against its pin before every run; the vendored files are hashed against references.sha256; a published vector's answer is required of Core as well as of Faraday; every ECDSA and BIP-340 signature Core makes is checked to verify under the hash the area computes before that hash is used for Faraday's deterministic nonces.

Vectors BIP-174's signer, finalizer and extractor vectors; the Core-built spends of tools/vectors/psbt/ (2-of-3 sortedmulti, the Liana wallet down both paths, a taproot tree by a leaf and by the key path, BIP 387's taproot multisig), signed by every subset of their keys; the finalizer vectors there (or_b's smaller signature, the taproot leaves that tie by count, the taproot multisig and MuSig2 spends).

Random cases PSBTs of one to four inputs, each spending a funding output on the node: P2PKH, P2SH-P2WPKH, P2WPKH, multi/sortedmulti in P2SH, P2WSH and P2SH-P2WSH, P2TR key path, P2TR script path (pk, pkh, timelocked keys, or_d, multi_a) with the key path beside it, miniscript in P2WSH and P2SH-P2WSH; held and foreign keys, cosigners' signatures already on (Core's), every standard sighash type, timelocks met and not; Core's signatures (ECDSA byte for byte, BIP-340 by verification and the deterministic nonce), each final scriptSig and witness and the extracted transaction Core's, the cleared fields, and every finalized transaction accepted by Core's mempool; an origin that derives another key refused; sweeps: a WIF key's P2PKH, P2WPKH and P2SH-P2WPKH outputs (P2PKH alone for an uncompressed key) spent beside another key's, signed by Core from the WIF and by faraday_psbt::sweep::sign, byte for byte, finalized and accepted by the mempool.

Differences PSBT signing: Faraday refuses to sign a SegWit v0 input with no previous transaction in a transaction of more than one input; Core signs it, and BIP-174's own signer vector is such a PSBT. The refusal is ours, checked and counted. Faraday holds a finalized input to the same rule and refuses the PSBT when such an input is final, except a taproot one, whose final witness is the coordinator's.

PSBT signing, wallets: Faraday signs an input spent from a script of several keys (a multi of two or more, a miniscript naming two or more, a taproot script path whose carried leaves name two or more with its internal key, or are not its whole tree) only for a registered wallet that holds one of its keys and whose script it is; Core signs any. The area refuses, by a rule of its own, where no wallet the request registers holds a held key and gives the input, and counts it only where Faraday's refusal is that the wallet is not registered. A miniscript or a taproot tree of one key is signed only through such a wallet, and is otherwise left unsigned while the rest is signed (F141); the area takes Core's signatures off it. Half the corpus's multi, miniscript and taproot-tree inputs come with their wallet registered, so their signatures are still compared. A registered tree's every leaf has its wait met, since Faraday refuses a path that can never be valid, which the area does not work out.

PSBT signing: Faraday refuses a PSBT any input of which asks for a NONE or SINGLE sighash, and one that none of the held keys can sign: dangers no hold accepts (F136). Core signs the first and answers the second with nothing signed. The area expects both refusals by a rule of its own, counting a held key as taking part as Faraday's inspection does (a miniscript or a taproot tree only through a wallet in use), checks that Faraday's refusal names the danger, and counts them.

Taproot pkh leaves: Faraday signs a taproot leaf that checks its key by hash but does not finalize it: miniscript 12's finalizer looks the key up among the ECDSA origins and panics, and would push 33 bytes where the leaf hashed 32. Core finalizes such a leaf; the area takes the signatures under it off before Core finalizes, and counts each input Core would otherwise have finalized another way.

btclib's finalizer writes no taproot leaf that is neither a single key nor multi_a, and refuses to choose among leaves a PSBT signs: an input of another leaf is judged by Core alone (counted as a known difference), and btclib is given only the signatures of the leaf Faraday spent. It writes a plain multisig from the smallest m signatures on hand where Core and Faraday write the first m signers': btclib is given only the signatures Faraday's input carries, so it judges the script written from them and Core judges which were chosen.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 1580 cases

Secret handling

none: no secret leaves faraday-keys

libsecp256k1 documents its signing as constant time; the low-R grind repeats the signing until r is small, so the number of signings varies, which the library does not address.

The key never leaves faraday-keys; it is erased when the sweep ends.

Limits

P2PKH, P2WPKH and P2SH-P2WPKH outputs of the key are signed; a legacy input needs its previous transaction.

An output to no loaded wallet's address is flagged, and the hold signs past it.

Faraday's own calls

An output to no loaded wallet's first hundred addresses on either chain is flagged on the review, and the hold signs past it. Neutral, F171.

Each signature is made twice and compared, and verified before it is written. Neutral.

no decision

Sign with Schnorr

SpecificationBIP 340 · BIP 341 · BIP 342PublishedCodeLibrary: secp256k1 0.29Library: bitcoin 0.32Library: hmac 0.13 (through core/faraday-crypto)1 moreFaraday's code: core/faraday-psbtCross-checked withBitcoin Core v31.1Others' codeFaraday's second version
Action

Signs a taproot input with BIP 340, by the key path or under a tap leaf's hash.

Specification

BIP 340, Schnorr Signatures for secp256k1, Deployed

BIP 341, Taproot: SegWit version 1 spending rules, Deployed

BIP 342, Validation of Taproot Scripts, Deployed

Code

Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-psbt: Signs the key path with the BIP 341 tweaked key and a leaf with the leaf's own key under its leaf hash; each signature is made twice, compared and verified; aux_rand is zero by default, and fresh bytes a caller passes are expanded for each input with HKDF-Expand (RFC 5869, faraday-crypto), which the app does not use; a miniscript or a tree is signed only through a registered wallet.

Checked against

tools/vectors/psbt

Published, by BIP 174's and RFC 6979's authors; the spends and finalized answers Bitcoin Core v31.1 made on regtest. Faraday's own known answers: the wallet policies, the warning PSBTs and the PSBTs this tree signed.

core/faraday-psbt/tests/all/nonce.rs::fresh_auxiliary_randomness_changes_a_taproot_signature

core/faraday-psbt/tests/all/miniscript.rs::the_tree_key_path_spend_signs_with_the_internal_key

core/faraday-psbt/tests/all/miniscript.rs::the_tree_leaf_spend_signs_under_the_leaf_hash

core/faraday-psbt/tests/all/miniscript.rs::a_miniscript_input_is_not_signed_without_its_wallet

core/faraday-psbt/tests/all/leaf_wallet.rs::a_leaf_without_its_wallet_alone_is_refused

core/faraday-psbt/tests/all/sign.rs::a_taproot_tree_with_no_way_into_it_is_refused

self-test schnorr_vector

no fuzz target: No target runs sign: it needs a master key and a PSBT that inspect accepts; psbt_parse fuzzes the PSBT it reads

Cross-check

Compared with others' code: Bitcoin Core v31.1, by the Bitcoin Core developers (descriptorprocesspsbt signs, testmempoolaccept judges the spend), with BIP-340's reference (secp256k1lab) and Core's script.py for the zero-randomness nonce; btclib, by the btclib developers, on its own curve, which verifies each signature and makes it again byte for byte; Core shares libsecp256k1's curve maths with Faraday's.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: Faraday's refusals (F136, F141) and the inputs a wallet's rule leaves unsigned, in area_sign.py; the keys of the zero-randomness check are btclib's.

Area sign

Faraday's code faraday_psbt::sign (every held key selected, deterministic Schnorr, both RFC 6979 nonce rules) and faraday_psbt::finalize

Compared with Bitcoin Core v31.1 on regtest (core_node.py): descriptorprocesspsbt signs from the held masters' keys, finalizepsbt finalizes and extracts, testmempoolaccept judges each finalized transaction over its funding on the node; BIP-340's reference (secp256k1lab) and Core's key.py for the deterministic nonces, over Core's script.py sighashes; python-ecdsa (the distribution's package) and btclib (btclib/, its own curve) as a second curve lineage, beside them: every ECDSA signature again under plain RFC 6979 or verified, every BIP-340 signature verified and made again; btclib-wallet's finalizer (psbt.finalize with its miniscript solver) finalizes every input Faraday finalizes again and gives the same scriptSig and witness; for each sweep, btclib reads the WIF (scalar, compression, public key) and signs and finalizes the sweep on its own curve, and python-ecdsa makes the first-nonce signature of each input again, byte for byte; python-bip380 (miniscript/) reads the leaves. Faraday's refusals and the inputs a wallet's rule leaves unsigned are ours, in area_sign.py.

Checked first: Core is the pinned release, hashed against its pin before every run; the vendored files are hashed against references.sha256; a published vector's answer is required of Core as well as of Faraday; every ECDSA and BIP-340 signature Core makes is checked to verify under the hash the area computes before that hash is used for Faraday's deterministic nonces.

Vectors BIP-174's signer, finalizer and extractor vectors; the Core-built spends of tools/vectors/psbt/ (2-of-3 sortedmulti, the Liana wallet down both paths, a taproot tree by a leaf and by the key path, BIP 387's taproot multisig), signed by every subset of their keys; the finalizer vectors there (or_b's smaller signature, the taproot leaves that tie by count, the taproot multisig and MuSig2 spends).

Random cases PSBTs of one to four inputs, each spending a funding output on the node: P2PKH, P2SH-P2WPKH, P2WPKH, multi/sortedmulti in P2SH, P2WSH and P2SH-P2WSH, P2TR key path, P2TR script path (pk, pkh, timelocked keys, or_d, multi_a) with the key path beside it, miniscript in P2WSH and P2SH-P2WSH; held and foreign keys, cosigners' signatures already on (Core's), every standard sighash type, timelocks met and not; Core's signatures (ECDSA byte for byte, BIP-340 by verification and the deterministic nonce), each final scriptSig and witness and the extracted transaction Core's, the cleared fields, and every finalized transaction accepted by Core's mempool; an origin that derives another key refused; sweeps: a WIF key's P2PKH, P2WPKH and P2SH-P2WPKH outputs (P2PKH alone for an uncompressed key) spent beside another key's, signed by Core from the WIF and by faraday_psbt::sweep::sign, byte for byte, finalized and accepted by the mempool.

Differences PSBT signing: Faraday refuses to sign a SegWit v0 input with no previous transaction in a transaction of more than one input; Core signs it, and BIP-174's own signer vector is such a PSBT. The refusal is ours, checked and counted. Faraday holds a finalized input to the same rule and refuses the PSBT when such an input is final, except a taproot one, whose final witness is the coordinator's.

PSBT signing, wallets: Faraday signs an input spent from a script of several keys (a multi of two or more, a miniscript naming two or more, a taproot script path whose carried leaves name two or more with its internal key, or are not its whole tree) only for a registered wallet that holds one of its keys and whose script it is; Core signs any. The area refuses, by a rule of its own, where no wallet the request registers holds a held key and gives the input, and counts it only where Faraday's refusal is that the wallet is not registered. A miniscript or a taproot tree of one key is signed only through such a wallet, and is otherwise left unsigned while the rest is signed (F141); the area takes Core's signatures off it. Half the corpus's multi, miniscript and taproot-tree inputs come with their wallet registered, so their signatures are still compared. A registered tree's every leaf has its wait met, since Faraday refuses a path that can never be valid, which the area does not work out.

PSBT signing: Faraday refuses a PSBT any input of which asks for a NONE or SINGLE sighash, and one that none of the held keys can sign: dangers no hold accepts (F136). Core signs the first and answers the second with nothing signed. The area expects both refusals by a rule of its own, counting a held key as taking part as Faraday's inspection does (a miniscript or a taproot tree only through a wallet in use), checks that Faraday's refusal names the danger, and counts them.

Taproot pkh leaves: Faraday signs a taproot leaf that checks its key by hash but does not finalize it: miniscript 12's finalizer looks the key up among the ECDSA origins and panics, and would push 33 bytes where the leaf hashed 32. Core finalizes such a leaf; the area takes the signatures under it off before Core finalizes, and counts each input Core would otherwise have finalized another way.

btclib's finalizer writes no taproot leaf that is neither a single key nor multi_a, and refuses to choose among leaves a PSBT signs: an input of another leaf is judged by Core alone (counted as a known difference), and btclib is given only the signatures of the leaf Faraday spent. It writes a plain multisig from the smallest m signatures on hand where Core and Faraday write the first m signers': btclib is given only the signatures Faraday's input carries, so it judges the script written from them and Core judges which were chosen.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 1580 cases

Secret handling

none: no secret leaves faraday-keys

libsecp256k1 documents its signing as constant time.

bitcoin forces two copies of the key for Schnorr, the untweaked and the tweaked keypair; both are overwritten with secp256k1's non_secure_erase before the function returns, which the library calls best effort.

Limits

SIGHASH_DEFAULT and ALL are signed, and ALL with ANYONECANPAY after a caution; NONE, SINGLE and undefined types are refused.

A taproot input that no key of this device can sign is left unsigned.

A leaf is signed only when the leaf's script checks a signature against the key, read through the miniscript.

Faraday's own calls

aux_rand is zero, so a signature can be made again byte for byte; BIP 340 recommends fresh randomness against fault attacks. The library offers fresh aux_rand, and the app does not use it. Neutral, F156.

A miniscript or a taproot tree of one key is signed only through its registered wallet. Conservative, F141.

Sign with MuSig2

SpecificationBIP 327 · BIP 373 · BIP 341PublishedCodeLibrary: secp256k1 0.29Library: bitcoin 0.32Library: hmac 0.13 (through core/faraday-crypto)2 moreFaraday's code: core/faraday-psbtCross-checked withBIP-327's reference.pyOthers' code
Action

Signs as one MuSig2 participant: draws a nonce, signs with it or signs last, and aggregates the partial signatures.

Specification

BIP 327, MuSig2 for BIP340-compatible Multi-Signatures, Deployed

BIP 373, MuSig2 PSBT Fields, Complete

BIP 341, Taproot: SegWit version 1 spending rules, Deployed

Code

Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-psbt: BIP 327's signing side is written here over libsecp256k1's point and secret-key operations (faraday-bip); the signing orchestration over BIP 373's PSBT fields is faraday-psbt's; a secret nonce is consumed by the signature it makes and held in memory for one transaction only; the wallet must be registered.

Checked against

tools/vectors/bip327

Published, by BIP 327's authors (bitcoin/bips).

tools/vectors/psbt

Published, by BIP 174's and RFC 6979's authors; the spends and finalized answers Bitcoin Core v31.1 made on regtest. Faraday's own known answers: the wallet policies, the warning PSBTs and the PSBTs this tree signed.

core/faraday-psbt/tests/all/musig.rs::the_device_signs_last_after_bitcoin_core

core/faraday-psbt/tests/all/musig.rs::signing_twice_gives_the_same_partial_signature

core/faraday-psbt/tests/all/musig.rs::a_second_signer_and_the_device_finish_the_transaction

core/faraday-psbt/tests/all/musig.rs::a_script_path_musig_field_is_refused

core/faraday-psbt/tests/all/musig.rs::an_unregistered_musig_wallet_is_blocked

core/faraday-psbt/tests/all/musig.rs::a_nonce_no_session_holds_is_replaced_and_earlier_signatures_dropped

core/faraday-bip/tests/all/musig.rs::bip327_nonce_gen_vectors

core/faraday-bip/tests/all/musig.rs::bip327_sign_vectors

core/faraday-bip/tests/all/musig.rs::bip327_partial_sig_verify_vectors

core/faraday-bip/tests/all/musig.rs::bip327_sig_agg_vectors

core/faraday-bip/tests/all/musig.rs::bip327_det_sign_vectors

core/faraday-psbt/tests/all/musig.rs::a_made_up_entry_for_a_participant_whose_nonce_is_held_is_overwritten

core/faraday-psbt/tests/all/musig.rs::a_failing_entry_without_a_held_nonce_gets_a_new_nonce

core/faraday-psbt/tests/all/musig.rs::a_refused_pass_leaves_the_nonce_held

core/faraday-psbt/tests/all/musig.rs::a_refused_pass_over_two_inputs_leaves_both_nonces_held

core/faraday-psbt/tests/all/musig.rs::a_made_up_nonce_for_a_second_held_key_does_not_spoil_the_first_partial

core/faraday-psbt/tests/all/musig.rs::a_made_up_nonce_under_another_aggregate_form_is_not_the_one_used

core/faraday-psbt/tests/all/musig.rs::a_made_up_partial_under_another_aggregate_form_does_not_hide_the_true_one

core/faraday-psbt/tests/all/musig.rs::aggregate_finishes_on_true_partials_and_not_on_a_made_up_one

faraday/faraday-core/tests/all/signer_count.rs::musig_partials::a_cosigners_true_partial_is_in_the_file_unconfirmed_and_one_signed_here_counts

faraday/faraday-core/tests/all/signer_count.rs::musig_partials::a_partial_forged_from_public_data_for_a_held_key_is_the_files_word_and_never_verified

faraday/faraday-core/tests/all/signer_count.rs::musig_partials::a_forged_partial_for_a_participant_whose_nonce_is_held_is_overwritten_by_sign

faraday/faraday-core/tests/all/signer_count.rs::musig_partials::an_output_key_with_an_odd_y_aggregates_from_true_partials

faraday/faraday-core/tests/all/signer_count.rs::musig_partials::a_partial_signature_with_a_flipped_byte_counts_nobody_and_its_master_is_offered_sign

faraday/faraday-core/tests/all/signer_count.rs::musig_partials::a_true_partial_on_one_of_two_inputs_counts_nobody_and_on_both_counts

faraday/faraday-core/tests/all/signer_count.rs::musig_partials::a_partial_this_device_did_not_write_reads_in_file_though_its_master_signed_another_input

faraday/faraday-core/tests/all/signer_count.rs::musig_partials::a_collect_that_replaces_this_devices_entry_with_a_forged_one_reads_in_file

faraday/faraday-core/tests/all/signer_count.rs::musig_partials::a_false_key_path_signature_beside_every_true_partial_is_replaced_by_the_aggregate

faraday/faraday-core/tests/all/signer_count.rs::musig_partials::an_entry_under_a_foreign_aggregate_key_reads_as_none_and_its_master_is_offered_sign

faraday/faraday-core/tests/all/signer_count.rs::musig_partials::an_honest_file_opened_before_its_wallet_is_registered_completes_when_it_is

faraday/faraday-core/tests/all/signer_count.rs::musig_partials::a_collect_that_brings_the_round_in_uses_the_file_after_the_merge

faraday/faraday-core/tests/all/signer_count.rs::musig_partials::collecting_a_cosigners_partial_names_whose_it_added_and_the_same_file_again_adds_nothing

faraday/faraday-core/tests/all/signer_count.rs::musig_partials::two_forms_of_the_aggregate_key_for_one_participant_read_as_the_signer_reads

no fuzz target: No target runs the MuSig2 rounds; psbt_parse fuzzes the PSBT that carries their fields through inspect

Cross-check

Compared with others' code: BIP-327's reference.py, by the BIP's authors, and btclib's MuSig2 (ecc.ecc.musig2) and btclib-wallet's BIP-373 roles (Updater, Signer, Finalizer), by the btclib developers, on btclib's own curve: nonces, signing, verification and aggregation, and the Core round trip's PSBTs read, verified, signed last and finalized again; the Core 31.1 round trip stays as a judge of BIP-373 and the descriptor and shares libsecp256k1's scalar code with Faraday's.

Area musig

Faraday's code faraday_bip::musig

Compared with BIP-327's reference.py (bip327/); btclib's MuSig2 (btclib/, its own curve) in full, answering every operation beside it and verifying the aggregate signature as BIP-340; btclib-wallet's BIP-373 roles over the Core round trip's PSBTs; Bitcoin Core v31.1 (deriveaddresses) for musig() descriptors.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday.

Vectors All eight files of tools/vectors/bip327/; the valid and invalid descriptors of tools/vectors/bip390/ (Core).

Random cases Sessions of 1 to 3 signers: key sort and aggregation, tweaks, nonces, partial signatures, their verification (and a tampered one), aggregation checked as BIP-340, deterministic signing; tr(musig(…)) wallets of 2 to 4 keys, as xpubs on both chains or as plain keys, whose scripts Core pays too.

Differences None known.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 320 cases

Secret handling

none: no secret leaves faraday-keys

Every operation on a secret scalar is libsecp256k1's (SecretKey add, multiply and negate, and a nonce's public key). libsecp256k1's header says its code is written and tested to be constant time whatever the secret values; it states nothing of these functions by name. A hash is reduced to a scalar without a branch; the code documents no other timing.

A SecNonce is wiped on drop and consumed by the signature it makes; the session wipes its nonces when another transaction opens a session, and holds none once each has signed. SecretKey is Copy, so every add_tweak, mul_tweak and negate copies the key and only the last copy is erased; the earlier copies are left in memory, later work under the security scope (ESTABLISHED §4.1).

Limits

Key path only; a nonce or partial signature keyed by a tapleaf hash is a script-path spend and is refused.

The wallet must be registered; a participant set no registered wallet has is blocked.

Rounds across a lock, with the secret nonce kept in a vault, are not offered (F234).

Faraday's own calls

Each nonce's rand' is RFC 5869 HKDF-Expand of the session's seed, with the draw counter, the input's index and the participant's key as info: a fresh value per call, and a refusal when the counter would wrap. Neutral.

no decision

The secret nonce is held in memory for its one session and never serialised. Conservative, F234.

Check a PSBT's signatures

SpecificationRFC 6979 · BIP 143 · BIP 341 · 2 morePublishedCodeLibrary: secp256k1 0.29Library: bitcoin 0.32Library: base16ct 1.0 (through core/faraday-crypto)Faraday's code: core/faraday-psbtCross-checked withpython-ecdsaOthers' codeFaraday's second version
Action

Checks every signature a PSBT or a finished transaction carries, finds a nonce used twice, recomputes this device's signatures and compares two PSBTs.

Specification

RFC 6979, Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA), Informational

BIP 143, Transaction Signature Verification for Version 0 Witness Program, Deployed

BIP 341, Taproot: SegWit version 1 spending rules, Deployed

BIP 174, Partially Signed Bitcoin Transaction Format, Deployed

BIP 373, MuSig2 PSBT Fields, Complete

Code

Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-psbt: Each signature is checked against the key it is under and the sighash the input's fields give, including the ones inside a finalized witness; one r or one R in more than one place is reported, under one key or several, and so is a point of a MuSig2 public nonce; a signature under a key this device holds is recomputed to say which nonce rule produced it.

Checked against

tools/vectors/psbt

Published, by BIP 174's and RFC 6979's authors; the spends and finalized answers Bitcoin Core v31.1 made on regtest. Faraday's own known answers: the wallet policies, the warning PSBTs and the PSBTs this tree signed.

core/faraday-psbt/tests/all/verify.rs::every_signature_the_committed_fixtures_carry_verifies

core/faraday-psbt/tests/all/verify.rs::the_signatures_this_device_writes_verify_when_they_are_read_back

core/faraday-psbt/tests/all/verify.rs::one_byte_changed_in_a_signature_is_invalid

core/faraday-psbt/tests/all/verify.rs::two_signatures_under_one_nonce_are_found

core/faraday-psbt/tests/all/verify.rs::the_devices_own_signatures_are_recognised_by_their_nonce_rule

core/faraday-psbt/tests/all/verify.rs::two_transactions_are_compared_on_what_they_decode_to

core/faraday-psbt/tests/all/verify.rs::a_finalized_taproot_signature_with_sighash_byte_zero_is_invalid

core/faraday-psbt/tests/all/signer.rs::what_core_signed_is_clean

core/faraday-psbt/tests/all/signer.rs::what_core_finalized_is_clean_and_states_the_input

fuzz psbt_parse

fuzz signer_check

Cross-check

Compared with others' code: python-ecdsa, by Brian Warner and Hubert Kario, and btclib, by the btclib developers, on btclib's own curve, verify every signature (ECDSA, and BIP-340 over python-ecdsa's points and btclib's ssa); the signature hashes are btclib's (sig_hash.py); btclib's script engine runs every complete input; Bitcoin Core v31.1 itself (finalizepsbt, testmempoolaccept), by Bitcoin Core's contributors, judges the complete inputs and the transaction, and shares libsecp256k1 with Faraday.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the report of a reused nonce, written in area_sign_check.py from Faraday's own rule, failing closed (signatures that verify with one r or R, differing in key or in message), which no outside library reports.

Area sign-check

Faraday's code faraday_psbt::verify::verify_signatures (every signature of a PSBT, in a partial field or a final scriptSig or witness, checked against its signature hash) and faraday_psbt::verify::repeated_nonces (one r or R under one key in more than one place)

Compared with python-ecdsa (the distribution's package, its own curve) and btclib (btclib/, libsecp256k1 off) verify every signature over btclib's signature hashes (sig_hash.py); btclib's script engine (verify_input, standardness rules on) runs every complete input and, under consensus's rules alone, every final input of the table (CONSENSUS); Bitcoin Core v31.1's finalizepsbt and testmempoolaccept judge the complete inputs and the transaction, and are named as sharing libsecp256k1 with Faraday; the reuse of a nonce is ours (reused, in area_sign_check.py).

Checked first: Its vendored files and the btclib wheels are hashed against references.sha256 before any run; Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked; the self-test makes Faraday's verdict wrong and its report of a nonce wrong, and each is caught.

A PSBT with no previous output for an input (Faraday leaves the signature unchecked); signatures under a pkh leaf or a script that names no key; MuSig2 partial signatures (area musig); the order of the signatures within a reuse report.

Vectors none: BIP-340's and ECDSA's published vectors are in the areas that sign (sign, msg); the signatures here are made for the PSBT in the case, with verdicts given by two verifiers.

Random cases Transactions of one to three inputs of legacy P2PKH, P2WPKH, P2WSH multisig (1 of 2 to 3 of 3), taproot key path and taproot script path, each with its signatures partial (in the PSBT's fields) or complete (in a final scriptSig or witness), good, under the wrong key, over the wrong sighash type, with a high S, or malformed, with every sighash type; nonces reused on purpose across inputs that share a key (ECDSA with k and -k too, Schnorr), one nonce under two keys, and one key under fresh nonces; and, for the verdict on a final input, a table of about ninety rows, each in every wrapping its script allows: and_v, thresh, pk, pkh, an or_d recovery path with older, 2 of 2 over [A,A], 2 of 3 over [A,A,B] and [A,B,A], the dummy empty and not, junk, repeated, swapped and extra signatures, 2 of 17 and 17 of 20, uncompressed keys, bare P2PK and multisig, P2PKH and P2WPKH true and forged, a hash time lock on both branches and three false spends of it, a redeem script of 500 and of 517 bytes, a high S and sighash bytes no standard defines, with keys drawn for each case; and about thirty taproot rows, run under TAPROOT: a key path and a script path on a Tap miniscript leaf, true and forged, an annex signed and not, SIGHASH_SINGLE with no output of its index, a control block that does not commit to the output key, a 65-byte element ending 0x00, and the leaves not run (another leaf version, a hash lock, OP_CODESEPARATOR, OP_DROP).

Differences A partial signature that is not a strict DER signature with a defined sighash byte (or a taproot signature of 64 bytes, or 65 with a sighash byte that is defined and not 0x00): Bitcoin Core reads the PSBT and leaves the input unfinalized, Faraday refuses the PSBT or does not call the signature valid. Counted.

A final input whose script Faraday does not run (a hash time lock, which is no miniscript: a wrong preimage, the key of the other branch, a sequence below the lock, and its true spends; a P2SH puzzle; a segwit pk of an uncompressed key, which Faraday's segwit reading refuses, though a segwit multisig of such keys is read by hand and answers ok; a bare P2PK of a key off the curve; a taproot leaf of a version other than 0xc0, a taproot hash lock, a taproot leaf with OP_CODESEPARATOR or OP_DROP): Faraday answers unjudged, whatever the engine decides. Such a script reads not sound in the nonce check and is not refused, and only these rows may answer so: a miniscript or a multisig answering unjudged fails the area. Counted.

A legacy (bare or P2SH) multisig with a junk element below the dummy: consensus leaves it on the stack and accepts, Faraday refuses it. No wallet writes one, and the refusal stays. Counted.

What no wallet writes and no node relays, which consensus accepts: a P2SH redeem script or signature pushed by PUSHDATA1 where a direct push fits; a P2SH or_i selector 01 01 (a push of one byte, not OP_1); a P2WSH or_i selector [2] (not [1] or empty); an or_d dissatisfied by a wrong DER signature, not an empty element; an element left below a P2SH pk. Faraday's reading of the final fields refuses each, and the refusal stays. Counted.

A final input with a high S, or with a sighash byte no standard defines (0x00, 0x04, 0x05, 0x84), in a signature the script engine accepts under consensus's rules: Faraday refuses it (a mismatch, or an invalid signature) and consensus takes it. Faraday keeps to the standard here on purpose: a node relays neither, so a transaction carrying one does not reach a miner. Counted.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 7000 cases

Secret handling

none: no secret leaves faraday-keys

Private keys are used only to recompute this device's signatures; what comes back is a verdict. The library does not state the recomputation's timing.

The keypairs made to recompute a signature are overwritten with secp256k1's non_secure_erase, which the library calls best effort.

Limits

A signature with no previous output to check against is not checked.

A signature under a sighash type that was not asked for is flagged.

A signature of another device is not recomputed.

A finalized taproot signature of 65 bytes with hash type 0x00 is reported invalid, key path and script path alike (BIP 341): it is a danger card, and the PSBT is not refused.

Faraday's own calls

The nonce check is run on signatures a device writes, comparing them with the RFC 6979 or BIP 340 nonce rule. Neutral.

no decision

Compare PSBTs and the fee bump

SpecificationBIP 174 · BIP 125PublishedCodeLibrary: bitcoin 0.32Faraday's code: core/faraday-psbtCross-checked withNot cross-checked
Action

Compares two PSBTs side by side and says whether a replacement only raises the fee of an original: the same inputs, the same payments, a higher fee.

Specification

BIP 174, Partially Signed Bitcoin Transaction Format, Deployed

BIP 125, Opt-in Full Replace-by-Fee Signaling, Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Faraday's code: core/faraday-psbt: Two PSBTs are read and set side by side; the fee of each is worked out from the amounts of its inputs and outputs, and a replacement is judged to only raise the fee when it spends the same inputs, pays the same outputs and its lock times and sequences allow it; any other case is Cannot tell.

Checked against

tools/vectors/psbt

Published, by BIP 174's and RFC 6979's authors; the spends and finalized answers Bitcoin Core v31.1 made on regtest. Faraday's own known answers: the wallet policies, the warning PSBTs and the PSBTs this tree signed.

core/faraday-psbt/tests/all/bump.rs::only_the_fee_is_raised

core/faraday-psbt/tests/all/bump.rs::pay_less_and_pay_more

core/faraday-psbt/tests/all/bump.rs::other_script_and_payment_added

core/faraday-psbt/tests/all/bump.rs::inputs_added_dropped_foreign

core/faraday-psbt/tests/all/diff.rs::the_same_transaction_has_no_differences

core/faraday-psbt/tests/all/diff.rs::inputs_by_outpoint

faraday/faraday-core/tests/all/compare.rs::the_tile_opens_the_flow

faraday/faraday-core/tests/all/compare.rs::swap_makes_the_comparison_again

faraday/faraday-core/tests/all/fee_bump_review.rs::the_core_replacement_says_only_the_fee_is_raised_from_the_original

no fuzz target: No target runs the comparison; psbt_parse fuzzes the PSBTs it reads

Cross-check

not cross-checked: No cross-check area runs it: the expected results are Bitcoin Core's psbtbumpfee pair (tools/vectors/psbt, bump-core-*), in the tests

Secret handling

none: no secret leaves faraday-keys

Public transaction data only; no secret is used.

No secret is held.

Limits

BIP 125's relay rules are stated or left to the node, not checked.

A case the rules do not know is Cannot tell, not a yes.

Faraday's own calls

Whether a replacement only raises the fee is Faraday's own rule; fails closed, a case it does not know is Cannot tell. Neutral, F233.

Finalize a transaction

SpecificationBIP 174PublishedCodeLibrary: bitcoin 0.32Library: miniscript 12.3Faraday's code: core/faraday-psbtFaraday's own codeCross-checked withBitcoin Core v31.1Others' codeFaraday's second version
Action

Builds the final scriptSig and witness from the partial signatures and extracts the transaction.

Specification

BIP 174, Partially Signed Bitcoin Transaction Format, Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: miniscript 12.3.7, by the rust-bitcoin developers (rust-miniscript).

Faraday's code: core/faraday-psbt: every input goes through miniscript's finalizer with its interpreter check (pkh, wpkh, sh-wpkh, multisig under sh, wsh and sh-wsh, a miniscript, a tree); among satisfactions of a wsh miniscript the smaller by real signature size is chosen, as Bitcoin Core's finalizepsbt chooses it, a multi() inside it keeping its k smallest signatures, and a plain multisig keeps the first m signers' under any wrapper as Core does, each checked by the interpreter again; the signing fields are cleared as BIP 174 requires. The app keeps the finished transaction and writes it as hex.

Written by Faraday

The choice among a script's satisfactions by real signature size (faraday-psbt::finalize) · Faraday's own specification

For a miniscript Faraday picks the smallest witness as Bitcoin Core's finalizepsbt does; a plain multisig carries the first m signers' signatures, as Core writes them; miniscript builds and checks each witness.

Decision F178

Checked against

tools/vectors/psbt

Published, by BIP 174's and RFC 6979's authors; the spends and finalized answers Bitcoin Core v31.1 made on regtest. Faraday's own known answers: the wallet policies, the warning PSBTs and the PSBTs this tree signed.

core/faraday-psbt/tests/all/sign.rs::sign_verify_finalize_every_script_type

core/faraday-psbt/tests/all/multisig.rs::bip174_signer_finalizer_extractor

core/faraday-psbt/tests/all/satisfaction.rs::or_b_carries_the_smaller_signature

core/faraday-psbt/tests/all/satisfaction.rs::multi_inside_or_d_keeps_the_smallest_signatures

core/faraday-psbt/tests/all/satisfaction.rs::legacy_multisig_keeps_the_first_signers

core/faraday-psbt/tests/all/satisfaction.rs::thresh_tie_satisfies_the_later_branches

core/faraday-psbt/tests/all/satisfaction.rs::taproot_leaves_that_weigh_the_same_keep_the_first_script_by_bytes

core/faraday-psbt/tests/all/miniscript.rs::the_liana_spend_completes_with_the_first_key_alone

core/faraday-psbt/tests/all/tapmulti.rs::two_of_the_three_keys_sign_and_the_input_finalizes

fuzz psbt_parse

Cross-check

Compared with others' code: Bitcoin Core v31.1, by the Bitcoin Core developers (finalizepsbt finalizes and extracts, testmempoolaccept judges the transaction over its funding on the node).

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the signatures under a taproot pkh leaf taken off before Core finalizes, as Faraday leaves such a leaf to the coordinator, and the fields BIP-174 keeps on a finalized input, in area_sign.py.

Area sign

Faraday's code faraday_psbt::sign (every held key selected, deterministic Schnorr, both RFC 6979 nonce rules) and faraday_psbt::finalize

Compared with Bitcoin Core v31.1 on regtest (core_node.py): descriptorprocesspsbt signs from the held masters' keys, finalizepsbt finalizes and extracts, testmempoolaccept judges each finalized transaction over its funding on the node; BIP-340's reference (secp256k1lab) and Core's key.py for the deterministic nonces, over Core's script.py sighashes; python-ecdsa (the distribution's package) and btclib (btclib/, its own curve) as a second curve lineage, beside them: every ECDSA signature again under plain RFC 6979 or verified, every BIP-340 signature verified and made again; btclib-wallet's finalizer (psbt.finalize with its miniscript solver) finalizes every input Faraday finalizes again and gives the same scriptSig and witness; for each sweep, btclib reads the WIF (scalar, compression, public key) and signs and finalizes the sweep on its own curve, and python-ecdsa makes the first-nonce signature of each input again, byte for byte; python-bip380 (miniscript/) reads the leaves. Faraday's refusals and the inputs a wallet's rule leaves unsigned are ours, in area_sign.py.

Checked first: Core is the pinned release, hashed against its pin before every run; the vendored files are hashed against references.sha256; a published vector's answer is required of Core as well as of Faraday; every ECDSA and BIP-340 signature Core makes is checked to verify under the hash the area computes before that hash is used for Faraday's deterministic nonces.

Vectors BIP-174's signer, finalizer and extractor vectors; the Core-built spends of tools/vectors/psbt/ (2-of-3 sortedmulti, the Liana wallet down both paths, a taproot tree by a leaf and by the key path, BIP 387's taproot multisig), signed by every subset of their keys; the finalizer vectors there (or_b's smaller signature, the taproot leaves that tie by count, the taproot multisig and MuSig2 spends).

Random cases PSBTs of one to four inputs, each spending a funding output on the node: P2PKH, P2SH-P2WPKH, P2WPKH, multi/sortedmulti in P2SH, P2WSH and P2SH-P2WSH, P2TR key path, P2TR script path (pk, pkh, timelocked keys, or_d, multi_a) with the key path beside it, miniscript in P2WSH and P2SH-P2WSH; held and foreign keys, cosigners' signatures already on (Core's), every standard sighash type, timelocks met and not; Core's signatures (ECDSA byte for byte, BIP-340 by verification and the deterministic nonce), each final scriptSig and witness and the extracted transaction Core's, the cleared fields, and every finalized transaction accepted by Core's mempool; an origin that derives another key refused; sweeps: a WIF key's P2PKH, P2WPKH and P2SH-P2WPKH outputs (P2PKH alone for an uncompressed key) spent beside another key's, signed by Core from the WIF and by faraday_psbt::sweep::sign, byte for byte, finalized and accepted by the mempool.

Differences PSBT signing: Faraday refuses to sign a SegWit v0 input with no previous transaction in a transaction of more than one input; Core signs it, and BIP-174's own signer vector is such a PSBT. The refusal is ours, checked and counted. Faraday holds a finalized input to the same rule and refuses the PSBT when such an input is final, except a taproot one, whose final witness is the coordinator's.

PSBT signing, wallets: Faraday signs an input spent from a script of several keys (a multi of two or more, a miniscript naming two or more, a taproot script path whose carried leaves name two or more with its internal key, or are not its whole tree) only for a registered wallet that holds one of its keys and whose script it is; Core signs any. The area refuses, by a rule of its own, where no wallet the request registers holds a held key and gives the input, and counts it only where Faraday's refusal is that the wallet is not registered. A miniscript or a taproot tree of one key is signed only through such a wallet, and is otherwise left unsigned while the rest is signed (F141); the area takes Core's signatures off it. Half the corpus's multi, miniscript and taproot-tree inputs come with their wallet registered, so their signatures are still compared. A registered tree's every leaf has its wait met, since Faraday refuses a path that can never be valid, which the area does not work out.

PSBT signing: Faraday refuses a PSBT any input of which asks for a NONE or SINGLE sighash, and one that none of the held keys can sign: dangers no hold accepts (F136). Core signs the first and answers the second with nothing signed. The area expects both refusals by a rule of its own, counting a held key as taking part as Faraday's inspection does (a miniscript or a taproot tree only through a wallet in use), checks that Faraday's refusal names the danger, and counts them.

Taproot pkh leaves: Faraday signs a taproot leaf that checks its key by hash but does not finalize it: miniscript 12's finalizer looks the key up among the ECDSA origins and panics, and would push 33 bytes where the leaf hashed 32. Core finalizes such a leaf; the area takes the signatures under it off before Core finalizes, and counts each input Core would otherwise have finalized another way.

btclib's finalizer writes no taproot leaf that is neither a single key nor multi_a, and refuses to choose among leaves a PSBT signs: an input of another leaf is judged by Core alone (counted as a known difference), and btclib is given only the signatures of the leaf Faraday spent. It writes a plain multisig from the smallest m signatures on hand where Core and Faraday write the first m signers': btclib is given only the signatures Faraday's input carries, so it judges the script written from them and Core judges which were chosen.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 1580 cases

Secret handling

none: no secret leaves faraday-keys

No secret is handled.

Nothing secret is held.

Limits

An input that has too few signatures stays partial and the transaction is not extracted.

A timelock the transaction does not meet stops the input in miniscript's interpreter check.

A final input whose funding transaction lacks the spent output is refused.

A taproot leaf holding pkh() is signed but left for the coordinator to finalize.

Faraday's own calls

Of several satisfactions of a wsh miniscript, the one with the smaller real signature size is chosen; where two weigh the same, the one Bitcoin Core keeps: an or's first branch, a multi()'s keys named first, a thresh()'s branches named last, a taproot spend's leaf whose script sorts first by its bytes. Neutral, F161.

Sign a message

SpecificationBIP 137 · BIP 322 · RFC 6979 · 1 morePublishedCodeLibrary: secp256k1 0.29Library: bitcoin 0.32Library: hmac 0.13 (through core/faraday-crypto)1 moreFaraday's code: core/faraday-psbtFaraday's own codeCross-checked withBitcoin Core v31.1 (signmessagewithprivkeyOthers' code
Action

Signs a message with the key at a path, in BIP 137's compact form or as BIP 322 simple.

Specification

BIP 137, Signatures of Messages using Private Keys, Deployed

BIP 322, Generic Signed Message Format, Complete

RFC 6979, Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA), Informational

BIP 340, Schnorr Signatures for secp256k1, Deployed

Code

Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-psbt: The address is derived from the key that signs, so the address in the result is the one the signature verifies against; BIP 137 low-R is ground here, libsecp256k1 having no low-R recoverable signer; the key's own blinded curve context is used. In the app the key is the one behind an address of a loaded single-key wallet's receive chain, and a wallet of several keys is refused.

Written by Faraday

BIP-322 "simple" message signatures (faraday-psbt::message) · No established implementation exists

The bip322 crate is pre-release.

Decision F178

Checked against

tools/vectors/message

Published, by BIP 322's authors (bitcoin/bips); btcd's BIP-322 (pull request 2521); Trezor's and Electrum's test suites, for BIP 137.

core/faraday-psbt/tests/all/message.rs::bip137_vectors

core/faraday-psbt/tests/all/message.rs::bip322_simple_vectors

core/faraday-psbt/tests/all/message.rs::bip322_transaction_vectors

core/faraday-psbt/tests/all/message.rs::sign_then_verify_round_trip

core/faraday-psbt/tests/all/message.rs::a_signature_belongs_to_one_address

no fuzz target: No fuzz target signs: the signer takes the person's own text and key; message_verify fuzzes the reading of a signed message

Cross-check

Compared with others' code: Bitcoin Core v31.1 (signmessagewithprivkey, verifymessage, signrawtransactionwithkey); btclib's bms and btclib-wallet's bip322, by the btclib developers, on btclib's own curve; btcd's bip322 (pull request 2521), by Oliver Gugger and the btcd developers; python-ecdsa, by Brian Warner and Hubert Kario, for the first-nonce ECDSA signature of BIP-137; Core shares libsecp256k1's curve maths with Faraday's.

Area msg

Faraday's code faraday_psbt::message (BIP-137, BIP-322 simple: sign, verify, virtual txids)

Compared with Bitcoin Core v31.1 and btclib for BIP-137, btclib-wallet and btcd for BIP-322: Core's signmessagewithprivkey, verifymessage and signrawtransactionwithkey (the low-R P2WPKH witness); btclib's bms and btclib-wallet's bip322 (btclib/, btclib's own curve); python-ecdsa (the distribution's package) for the first-nonce ECDSA signature of BIP-137; btcd's bip322 from pull request 2521 (btcd-bip322/, Go).

Checked first: The wheels and the Go tree are hashed against references.sha256 before any run, Core's release against its pin; BIP-322's basic and generated vectors and btcd's negative vectors are required of both BIP-322 references, each in the state the vector names, and Trezor's and Electrum's BIP-137 signatures of btclib.

A taproot signature's bytes (BIP-340's auxiliary randomness is the signer's: Faraday's is verified by both BIP-322 references, and btcd's by Faraday); the kind of a refusal (Malformed, Invalid, Unsupported…), Faraday's own words, checked by its tests; Core's reading of a BIP-137 header outside 27 to 42.

Vectors BIP-322's basic and generated vectors (hashes, txids, simple, full and proof-of-funds signatures, errors) and btcd's negative vectors; Trezor's and Electrum's BIP-137 signatures (tools/vectors/message/), Trezor's made again from its keys.

Random cases Random keys, address forms, networks and messages: virtual txids; signatures made byte for byte under both nonce rules and checked by every reference, then checked against a changed message, another address, a changed byte and a moved header; btcd's own simple signatures checked by Faraday.

Differences BIP-137: Faraday reads the address form from the address rather than the header's range and tries a P2PKH address in both key encodings (faraday_psbt::message), as Electrum and Sparrow do; btclib holds the ranges (with Electrum's for SegWit) and Core reads the key encoding from the header. Counted where btclib accepts the signature with the header the address's form names, or Core with the other key encoding.

BIP-322: Faraday refuses the full form and proof of funds, which both references make and accept (for P2PKH and P2SH-P2WPKH addresses they sign in the full form); counted where both accept and Faraday refuses the format.

BIP-322: Faraday checks simple signatures for P2WPKH and P2TR addresses only; a P2WSH script both references accept is refused as an unsupported address, and counted.

Between the references: btclib's interpreter holds witness v0 scripts alone to MINIMALIF, so it accepts btcd's two negative vectors of a legacy P2SH script, in the full form, whose OP_IF takes a non-minimal true; btcd must call them invalid and Faraday, which reads no full form, refuse them, and each is counted.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 6000 cases

Secret handling

none: no secret leaves faraday-keys

libsecp256k1 documents its signing as constant time; the BIP 137 low-R grind repeats the signing until r is small.

The secret key is borrowed for the moment it signs; the two Schnorr copies bitcoin forces for a taproot address are overwritten with secp256k1's non_secure_erase before the function returns, which the library calls best effort.

Limits

BIP 322 simple only: no full form, no proof of funds.

A nested SegWit address has no BIP 322 simple form and is signed as BIP 137 only.

A taproot address is signed as BIP 322 only.

Faraday's own calls

The app signs with the low-R nonce and zero aux_rand for a taproot address. Neutral, F156.

Check a signed message

SpecificationBIP 137 · BIP 322PublishedCodeLibrary: secp256k1 0.29Library: bitcoin 0.32Faraday's code: core/faraday-psbtCross-checked withBitcoin Core v31.1 (signmessagewithprivkeyOthers' code
Action

Checks a signed message against an address, as BIP 137 or BIP 322 simple.

Specification

BIP 137, Signatures of Messages using Private Keys, Deployed

BIP 322, Generic Signed Message Format, Complete

Code

Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Faraday's code: core/faraday-psbt: Reads the recovery id from the BIP 137 header and asks the address itself which form to rebuild, as Electrum and Sparrow do; a P2PKH address is tried in both key encodings. The app requires the address to be on the session's network and looks for it among each loaded wallet's first 100 addresses on both chains.

Checked against

tools/vectors/message

Published, by BIP 322's authors (bitcoin/bips); btcd's BIP-322 (pull request 2521); Trezor's and Electrum's test suites, for BIP 137.

core/faraday-psbt/tests/all/message.rs::bip137_vectors

core/faraday-psbt/tests/all/message.rs::bip322_simple_vectors

core/faraday-psbt/tests/all/message.rs::bip322_error_vectors

core/faraday-psbt/tests/all/message.rs::a_signature_belongs_to_one_address

core/faraday-psbt/tests/all/message.rs::a_witness_signature_that_is_not_der_is_malformed

core/faraday-psbt/tests/all/message.rs::bip322_taproot_signature_with_sighash_byte_zero_is_refused

fuzz message_verify

Cross-check

Compared with others' code: Bitcoin Core v31.1 (signmessagewithprivkey, verifymessage, signrawtransactionwithkey); btclib's bms and btclib-wallet's bip322, by the btclib developers, on btclib's own curve; btcd's bip322 (pull request 2521), by Oliver Gugger and the btcd developers; python-ecdsa, by Brian Warner and Hubert Kario, for the first-nonce ECDSA signature of BIP-137; Core shares libsecp256k1's curve maths with Faraday's.

Area msg

Faraday's code faraday_psbt::message (BIP-137, BIP-322 simple: sign, verify, virtual txids)

Compared with Bitcoin Core v31.1 and btclib for BIP-137, btclib-wallet and btcd for BIP-322: Core's signmessagewithprivkey, verifymessage and signrawtransactionwithkey (the low-R P2WPKH witness); btclib's bms and btclib-wallet's bip322 (btclib/, btclib's own curve); python-ecdsa (the distribution's package) for the first-nonce ECDSA signature of BIP-137; btcd's bip322 from pull request 2521 (btcd-bip322/, Go).

Checked first: The wheels and the Go tree are hashed against references.sha256 before any run, Core's release against its pin; BIP-322's basic and generated vectors and btcd's negative vectors are required of both BIP-322 references, each in the state the vector names, and Trezor's and Electrum's BIP-137 signatures of btclib.

A taproot signature's bytes (BIP-340's auxiliary randomness is the signer's: Faraday's is verified by both BIP-322 references, and btcd's by Faraday); the kind of a refusal (Malformed, Invalid, Unsupported…), Faraday's own words, checked by its tests; Core's reading of a BIP-137 header outside 27 to 42.

Vectors BIP-322's basic and generated vectors (hashes, txids, simple, full and proof-of-funds signatures, errors) and btcd's negative vectors; Trezor's and Electrum's BIP-137 signatures (tools/vectors/message/), Trezor's made again from its keys.

Random cases Random keys, address forms, networks and messages: virtual txids; signatures made byte for byte under both nonce rules and checked by every reference, then checked against a changed message, another address, a changed byte and a moved header; btcd's own simple signatures checked by Faraday.

Differences BIP-137: Faraday reads the address form from the address rather than the header's range and tries a P2PKH address in both key encodings (faraday_psbt::message), as Electrum and Sparrow do; btclib holds the ranges (with Electrum's for SegWit) and Core reads the key encoding from the header. Counted where btclib accepts the signature with the header the address's form names, or Core with the other key encoding.

BIP-322: Faraday refuses the full form and proof of funds, which both references make and accept (for P2PKH and P2SH-P2WPKH addresses they sign in the full form); counted where both accept and Faraday refuses the format.

BIP-322: Faraday checks simple signatures for P2WPKH and P2TR addresses only; a P2WSH script both references accept is refused as an unsupported address, and counted.

Between the references: btclib's interpreter holds witness v0 scripts alone to MINIMALIF, so it accepts btcd's two negative vectors of a legacy P2SH script, in the full form, whose OP_IF takes a non-minimal true; btcd must call them invalid and Faraday, which reads no full form, refuse them, and each is counted.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 6000 cases

Secret handling

none: no secret leaves faraday-keys

No secret is handled.

Nothing secret is held.

Limits

A signature belongs to the one address it was made for.

BIP 322 simple only.

A taproot signature of 65 bytes with hash type 0x00 is refused as malformed (BIP 341).

Faraday's own calls

The address form is read from the address, not from the BIP 137 header's range, and a P2PKH address is tried in both key encodings; more lenient than BIP 137. Neutral.

no decision

Read a transaction

SpecificationBIP 141 · BIP 144PublishedCodeLibrary: bitcoin 0.32Library: base16ct 1.0 (through core/faraday-crypto)Faraday's code: core/faraday-psbtCross-checked withbtclib's Tx.parseOthers' codeFaraday's second version
Action

Reads a raw transaction, or a PSBT's transaction, to its txid, wtxid, weight and the previous outputs its source states.

Specification

BIP 141, Segregated Witness (Consensus layer), Deployed

BIP 144, Segregated Witness (Peer Services), Deployed

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-psbt: A raw transaction is read from hex or bytes by rust-bitcoin, and one it reads to no inputs is refused, as Bitcoin Core refuses those bytes (the segwit flag with no witness); a previous transaction is accepted for an input only when its txid is the one spent. The Decode screen takes the amounts its inputs spend from the spend's PSBT and the Inbox's PSBTs whose unsigned transaction is exactly the one decoded, and uses an input's amount only when no two of them state different ones. An output is named by its script kind (P2WPKH, P2WSH, P2TR, P2SH, P2PKH or OP_RETURN) and marked when it pays to a loaded wallet's first 100 addresses on either chain. A text is taken as a transaction in hex only when it has an even number of at least 120 hex digits that read as a transaction. Decode refuses a transaction with an output over 21,000,000 BTC or outputs whose total is over it, as Bitcoin Core's CheckTransaction does (bad-txns-vout-toolarge, bad-txns-txouttotal-toolarge), and one whose inputs' stated amounts, or their total, are over it, as its CheckTxInputs does (bad-txns-inputvalues-outofrange), so no total or fee it shows overflows.

Checked against

not checked against vectors

core/faraday-psbt/tests/all/transaction.rs::a_raw_transaction_is_wrapped_and_keeps_its_id

core/faraday-psbt/tests/all/transaction.rs::a_previous_transaction_with_another_id_does_not_state_the_spent_output

core/faraday-psbt/tests/all/transaction.rs::a_transaction_core_refuses_for_a_superfluous_witness_flag_is_refused

faraday/faraday-core/tests/all/finish.rs::decode_refuses_amounts_over_21_million_bitcoin_as_core_does

faraday/faraday-core/tests/all/finish.rs::decode_refuses_an_amount_going_in_over_21_million_bitcoin

fuzz transaction

Cross-check

Compared with others' code: btclib's Tx.parse, by the btclib developers; and Bitcoin Core v31.1's decoderawtransaction, by Bitcoin Core's contributors.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the refusal of a transaction with no inputs, which neither judge makes (Core's decoderawtransaction reads bytes that begin with the marker 00 01 as a legacy transaction of no inputs), written in area_tx.py.

Area tx

Faraday's code faraday_psbt::transaction::read_raw, faraday_core::decode::decode's txid, wtxid and output addresses, bitcoin's SighashCache as faraday_psbt::sign calls it

Compared with btclib's Tx.parse and sig_hash (btclib/); Bitcoin Core v31.1's decoderawtransaction on regtest (core_node.py) for the transactions; Core's messages.py and script.py (core/) for the signature hashes; the refusal of a transaction with no inputs is ours.

Checked first: Its vendored files and the btclib wheels are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; each published signature hash is checked against the framework first.

Vectors Core's 500 legacy sighashes, BIP-143's thirteen, BIP-341's key-path sighashes (tools/vectors/sighash/).

Random cases Random transactions with and without witnesses (txid, wtxid, weight, bytes) read by btclib and Core's decoderawtransaction, cut or lengthened, and shown by Faraday's Decode view (txid, wtxid, each output's address, none where Core gives none) against Core's; every input hashed as legacy, BIP-143 P2WPKH and P2WSH, BIP-341 key and script path under every hash type, by btclib and the framework.

Differences Decode refuses a transaction whose outputs total over 21,000,000 BTC, as Core does not in decoderawtransaction; the corpus asks Decode only of transactions within that total.

Legacy sighash: bitcoin hashes the script code as given, Core and btclib remove every OP_CODESEPARATOR first. Faraday's legacy spends (P2PKH, P2SH multisig) have none.

Core's decoderawtransaction reads bytes whose marker 00 01 it takes as a count of no inputs and one output, a legacy transaction of no inputs; Faraday refuses a transaction with no inputs, and the area counts a case where btclib reads inputs of such bytes as this difference.

BIP-341's refusals (SIGHASH_SINGLE without an output, a hash type it does not list) are btclib's: the framework hashes those anyway and is not asked.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Secret handling

none: no secret leaves faraday-keys

No secret is handled.

Nothing secret is held.

Limits

A raw transaction is read only when its bytes are exactly the serialisation of what was read.

A previous transaction with another id does not state the spent output.

Amounts that two PSBTs state differently for an input are not used.

A transaction with an amount or a total over 21,000,000 BTC, in its outputs or the amounts its inputs are stated to spend, is not decoded.

Faraday's own calls

A previous transaction is attached to an input only when its id is the spent one. Conservative.

no decision

Transfer

5 actions · 1 own specification · 3 with Faraday's own code · 4 cross-checked with others' code · 1 with Faraday's second version · 1 not cross-checked

Make and read QR codes

SpecificationISO/IEC 18004PublishedCodeLibrary: rqrr 0.11Library: bitcoin 0.32 (through core/faraday-bip)Faraday's code: core/faraday-codecFaraday's own codeCross-checked withProject Nayuki's qrcodegen.pyOthers' code
Action

Encodes a payload as a QR code, ISO/IEC 18004 model 2, and reads QR codes from a camera frame or a PNG.

Specification

ISO/IEC 18004, QR Code bar code symbology specification, Status not checked

Code

Library: rqrr 0.11.0, by WanzenBug (rust-qr-reader), as copied into third_party/rqrr with the changes third_party/rqrr/PATCHES.md lists.

Library: bitcoin 0.32.102, by the rust-bitcoin developers, through core/faraday-bip.

Faraday's code: core/faraday-codec: The encoder is a port of Project Nayuki's qrcodegen, rewritten for no_std and secret payloads: the module grid and every buffer holding payload bits wipe on drop, and the error-correction level is never raised; the PNG writer is here; reading is rqrr's.

Written by Faraday

The QR encoder, a port of Nayuki's qrcodegen, with its GF(256) and Reed-Solomon (faraday-codec::qr) · No established implementation exists

No QR encoder comes from a publisher Faraday's dependency review trusts; Faraday's port of Nayuki's code wipes a SeedQR's buffers.

Carries a format; it computes nothing on a key.

Decision F178

Checked against

tools/vectors/seedqr

Published, by SeedSigner's SeedQR specification, by the SeedSigner developers.

core/faraday-codec/src/qr.rs::known_answer_version_1

core/faraday-codec/src/qr.rs::capacities_match_the_standard

core/faraday-codec/src/qr.rs::a_seedqr_matrix_is_wiped

core/faraday-codec/src/decode.rs::encoder_and_decoder_agree

core/faraday-codec/src/classify.rs::routing_table

core/faraday-codec/tests/png.rs::a_grey_picture_reads_back_as_its_pixels

fuzz decode_luma

fuzz classify

fuzz png_qr

Cross-check

Compared with others' code: Project Nayuki's qrcodegen.py, by Nayuki, and segno, by Lars Heuer, and the pictures decoded by zbar, by the zbar developers, and zxing-cpp, by the zxing-cpp developers.

Area seedqr

Faraday's code faraday_codec::seedqr (SeedQR, CompactSeedQR), faraday_codec::qr, the encoder that draws them, and faraday_codec::qr::codex32qr with the picture faraday_core::picture writes of it

Compared with SeedSigner's own encoders and DecodeQR (seedsigner/, unchanged, with embit's BIP-39 code in embit/); Project Nayuki's qrcodegen.py (qrcodegen/), module for module; segno 1.6 (python3-segno), an encoder of another lineage, at Faraday's mask and at its own; Pillow and CPython's zlib, which read every PNG Faraday writes; zbar (zbarimg) and zxing-cpp, which decode the QR code in every picture and return its payload as bytes (qr_decode.py).

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; SeedSigner's reader is looser than Faraday (it takes 49 digits, a sign inside a group, 20 to 28 bytes, and does not check the checksum of digits), so Faraday's own rule, the lengths and the digits, stands in front of it in area_seedqr.py and the checksum is embit's; SeedSigner runs in English for every language, the indices being the same; the profile's own pictures are read from their pixels and must be Faraday's code module for module; segno is asked for Faraday's version, level and mode and its mask forced, and its mask is read back from it, its padding quirk being modelled in Nayuki's code; rqrr reads Faraday's and segno's codes; the self-test makes each decoder's answer wrong (a payload's last byte changed) and must catch it.

An empty payload, which segno refuses.

Vectors SeedSigner's nine test SeedQRs (tools/vectors/seedqr/); every string and picture of the Codex32QR profile (tools/vectors/codex32qr/), each decoded by zbar and zxing-cpp.

Random cases Keys of every length and language, both codes and the words read back; digits and bytes malformed; payloads in each mode at each level and version limit; 48-character codex32 strings in either case as Codex32QR codes and the pictures written of them read back and decoded by zbar and zxing-cpp, other lengths refused; the pictures of a key's SeedQR and CompactSeedQR decoded by both and read by Faraday to the key's words; greyscale pictures and QR pictures of random size and scale read by Pillow and zlib.

Differences SeedQR digits: SeedSigner reads a string with 1 to 3 digits more than 48 or 96 (it drops the tail) and one with a sign or a space inside a group of four (int() takes them); Faraday refuses both (5 cases, each checked on both sides and counted). SeedSigner takes no CompactSeedQR of 20, 24 or 28 bytes either, and strips checksum bits for 12 and 24 words only; the corpus keeps Faraday's 15, 18 and 21 word compact form on the entropy itself.

Codex32QR: Faraday picks the mask Nayuki's encoder picks; the profile's encoder chose another for 6 of its 22 pictures. For those the area swaps the mask of Faraday's code for the picture's with qrcodegen.py's masking, requires the picture, and counts it.

Segno 1.6 writes a zero codeword where the pad codewords begin when the data, terminator included, ends on a codeword boundary with room left (its write_padding_bits adds 8 zero bits where none are due; ISO/IEC 18004 7.4.10 adds none): its code is Nayuki's with that codeword changed, which rqrr reads, counted as a known difference, the padding; Faraday's is the standard's.

Segno picks a mask by its own penalty rule, and for some payloads another than Nayuki's and Faraday's; the area requires that code to be Faraday's under the mask segno reports (Nayuki's masking swapped to it) and rqrr to read it, and counts each as a known difference, the mask choice, which a reader ignores.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 8000 cases

Secret handling

none: no secret leaves faraday-keys

Not stated by the encoder or by rqrr.

The module grid, the bit stream and the data and error-correction codewords wipe on drop; a decoded payload is a zeroizing buffer. The caller asks faraday-keys for any secret it encodes.

Limits

One segment per code; the caller picks numeric, alphanumeric or byte mode.

The error-correction level is never raised above the one asked for.

A frame whose byte count is not width times height yields nothing; a code whose error correction fails is skipped.

Faraday's own calls

The error-correction level is never boosted, so a SeedQR comes out at the level its specification names. Neutral.

no decision

Write and read UR codes

SpecificationBCR-2020-005 · BCR-2020-006 · BCR-2020-012 · 3 morePublishedCodeLibrary: bitcoin 0.32 (through core/faraday-bip)Library: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-codecFaraday's own codeCross-checked withfoundation-ur-pyOthers' code
Action

Writes and reads UR codes: bytewords with CRC-32, fountain-coded parts and the CBOR around them.

Specification

BCR-2020-005, Uniform Resources (UR), the animated-QR transport, Convention, vendored

BCR-2020-006, The crypto-psbt UR type, Convention, vendored

BCR-2020-012, Bytewords, Convention, vendored

BCR-2020-007, UR Type Definition for Hierarchical Deterministic (HD) Keys, Convention

BCR-2020-010, UR Type Definition for Bitcoin Output Descriptors, Convention

BCR-2020-015, UR Type Definition for BIP44 Accounts, Convention

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers, through core/faraday-bip.

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-codec: The whole transport is written here: bytewords in the minimal style with their CRC-32, the xoshiro generator that picks a part's fragments, the fountain parts with their CBOR and the ur: text; SHA-256 and CRC-32 come from faraday-crypto. A decoder reduces a mix by any buffered mix whose fragments are a subset of its own. The registry's crypto-hdkey, crypto-account and crypto-output are read as key lines or a descriptor, and a crypto-account is written for one key as SeedSigner shows it.

Written by Faraday

BC-UR, with its CBOR (faraday-codec::ur, faraday-codec::cbor) · No established implementation exists

No library for this format comes from a publisher Faraday's dependency review trusts.

Carries a format; it computes nothing on a key.

Decision F178

CRC-32 (faraday-crypto::crc32) · No established implementation exists

The CRC-32 crate in the tree, crc32fast 1.5.1, is not covered by an outside review at that version; Faraday's is a branch-free loop checked against the published check values.

Carries a format; it computes nothing on a key.

Decision F180

Checked against

tools/vectors/ur

Published, by URKit's encoder vectors, as foundation-ur-py's test.py states them.

core/faraday-codec/src/ur/mod.rs::published_vectors

core/faraday-codec/src/ur/mod.rs::parts_recorded_from_the_reference_crate

core/faraday-codec/src/ur/mod.rs::multi_part_out_of_order_and_with_losses

core/faraday-codec/src/ur/bytewords.rs::a_hundred_bytes_from_the_specification

core/faraday-codec/src/ur/fountain.rs::the_emitted_parts_match_the_specification

core/faraday-codec/src/ur/xoshiro.rs::the_stream_matches_the_reference_implementation

core/faraday-codec/src/ur/fountain.rs::an_encoder_and_a_qr_matrix_are_wiped_on_drop

core/faraday-codec/tests/ur_single.rs::a_single_part_ur_of_any_type_is_the_published_one_and_reads_back

fuzz ur_receive

fuzz ur_registry

Cross-check

Compared with others' code: foundation-ur-py, by Foundation Devices, and CPython's zlib.crc32 and cbor2, by the cbor2 developers, which judge the one CRC-32 and the one CBOR (the parts' and payloads' CBOR and the registry's types).

Area ur

Faraday's code faraday_codec::ur (single-part URs, the animation's parts, the decoder), faraday_crypto::crc32, faraday_codec::cbor and faraday_qr::registry

Compared with Foundation Devices' foundation-ur-py (ur/), URKit ported; CPython's zlib.crc32; cbor2.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; foundation-ur-py is itself a port of URKit checked against URKit's own tests, whose vectors the area also runs.

Vectors URKit's single-part and multipart encoder vectors (tools/vectors/ur/).

Random cases Messages as crypto-psbt and bytes at random fragment lengths, parts byte for byte; sets with fragments dropped, mixes added, shuffled, repeated and upper case, put together by both; URs of other types written, read, changed and cut; CRC-32 of random messages and of the parts; the parts and single-part payloads read by cbor2; registry types built with cbor2 and read; random and mutated CBOR through Faraday's reader beside cbor2.

Differences UR: Faraday has no minimum fragment length, writes a one-fragment message as a part like any other, and refuses to animate an empty message; foundation-ur-py checks a UR type one character's way ('a' <= type <= 'z'). The area asks the reference with a minimum of 1, makes parts with its fountain encoder, and keeps its types to letters, digits and - not starting with z. Faraday's decoder reduces mixes by each other whichever arrived first, and so sometimes finishes a set URKit's does not; the area then checks the message is the one sent and counts the set.

CBOR: Faraday's reader refuses indefinite lengths, floats, simple values other than false, true and null, nesting beyond 16 levels, a key given twice and a stray break, which cbor2 reads; cbor2 reads tags below 300 or from 1000 on as types of its own. The area counts each such input as a known difference, and any other difference is a failure.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 24000 cases

Source

0.2.0 · core/faraday-codec/src/ur/mod.rs · encode_single

0.2.0 · core/faraday-codec/src/ur/mod.rs · decode_single

0.2.0 · faraday/faraday-qr/src/send.rs · ur_psbt_frames

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

Not stated; the code is table and bit arithmetic over public parts.

An encoder and the QR matrix of a part wipe on drop.

Limits

A multi-part UR may claim at most 2048 fragments.

Only the minimal bytewords style is read and written.

crypto-output is read and never written.

A seed or a private key by UR is refused, saying what it is.

Faraday's own calls

Every part is written as ur:<type>/<seq>-<count>/..., a message of one fragment included. Neutral.

no decision

There is no minimum fragment length; a fragment is ceil(length / ceil(length / max)) bytes. Neutral.

no decision

A part of another message, and an empty message to animate, are refused. Conservative.

no decision

Split and join BBQr parts

SpecificationBBQr · Specter pNofMPublishedCodeLibrary: base16ct 1.0 (through core/faraday-crypto)Faraday's code: faraday/faraday-qrFaraday's own codeCross-checked withCoinkite's BBQr libraryOthers' codeFaraday's second version
Action

Splits a file into BBQr or numbered pNofM parts for QR codes and puts received parts together.

Specification

BBQr, BBQr, a file split across QR codes, Convention

Specter pNofM, Numbered text parts, pNofM, Convention

Code

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: faraday/faraday-qr: BBQr is written in base32 only and read in base32, hex and raw DEFLATE (miniz_oxide, decompressed within a bound); the numbered parts are Specter's and SeedSigner's pNofM; every limit fails closed. The assembler keeps a transfer part-way through across scans; a part of another transfer starts that one afresh, and any other refusal leaves the transfer as it was.

Written by Faraday

BBQr (faraday-qr::bbqr) · No established implementation exists

No library for this format comes from a publisher Faraday's dependency review trusts.

Carries a format; it computes nothing on a key.

Decision F178

Checked against

tools/vectors/bbqr

Published, by Coinkite's BBQr repository's test data, by Coinkite (the commit, licence and SHA-256 of each file are in the folder's README).

faraday/faraday-qr/tests/formats.rs::a_psbt_written_as_bbqr_reads_back

faraday/faraday-qr/tests/formats.rs::bbqr_parts_that_do_not_hang_together_are_refused

faraday/faraday-qr/tests/formats.rs::numbered_parts_read_back_and_say_what_is_missing

faraday/faraday-qr/tests/interop.rs::ten_bbqr_parts_are_the_psbt_in_any_order

fuzz qr_assembler

Cross-check

Compared with others' code: Coinkite's BBQr library, by Coinkite, for BBQr; krux's qr.py and bbqr.py, by the krux developers, for writing and reading numbered parts; SeedSigner's SpecterWalletQrDecoder, by the SeedSigner developers, for the numbered parts.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: Faraday's refusals written in area_bbqr.py in front of SeedSigner's decoder (a part number of 0 or past the count, a repeat with other text, a header in upper case or missing, a count over 1,000), the one-table pyqrcode shim checked against qrcodegen.py, and krux's three shims (QR, base32, deflate).

Area bbqr

Faraday's code faraday_qr::bbqr, faraday_qr::specter (numbered text parts)

Compared with Coinkite's BBQr library (bbqr/, with a one-table pyqrcode shim checked against qrcodegen.py); krux's qr.py and bbqr.py (krux/, unchanged, with three small shims for the firmware's QR, base32 and deflate modules); SeedSigner's own SpecterWalletQrDecoder (seedsigner/, unchanged).

Checked first: check_capacities and check_krux_capacities run first, the pyqrcode shim's table of version capacities and krux's two tables against qrcodegen.py's; the vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; where Faraday refuses what SeedSigner's decoder files or misfiles (a part number of 0 or past the count, a repeat with other text, a header in upper case or missing, a count over 1,000) the refusal is written in the area, in front of the decoder.

krux's writing of file types Faraday does not write (C, X, B, R, S, E are refused by both and compared as refusals); a set over 1,295 parts, which krux cannot number; the old cases of Faraday's writing at 1, 5, 7 and 40 bytes a part, gone because writing is now sized by QR version, the size krux chooses.

Vectors Coinkite's BBQr test files (tools/vectors/bbqr/): the 26 parts of a phone's scan, which read as a U file with the text Coinkite's test expects, and its ten PSBTs and transactions, each split in every encoding and read back to the file's bytes.

Random cases Files of every type and size written by krux (at the sizes of QR versions 1 to 20) and split by Coinkite in each encoding, read in any order, with repeats, a part missing, another transfer's part, a conflicting repeat and a part past the count, against Coinkite and krux; what Faraday writes, part for part krux's own writing at the same size, read back by join_qrs and by krux; numbered parts written by krux, written again by Faraday, read in any order against SeedSigner's decoder and krux and refused when malformed.

Differences BBQr: Faraday reads the file types P, T, U and J and frames of at most 4,096 characters; Coinkite's library reads every type BBQr defines and a version 40 part of 4,296 characters. Both refusals are checked and counted, and the corpus splits at version 39 at most. Faraday also refuses a set whose parts are not one length but the last, which Coinkite never writes.

Numbered parts: SeedSigner matches P and OF in upper case; Faraday does not (checked and counted). Faraday also refuses a part number of 0 or past the count, a count over 1,000, a repeat with other text and a part with no header, which SeedSigner's decoder files, fails on or takes whole; those refusals are written in the area, in front of the decoder.

Krux (checked and counted): reads the file types P, T, J and U only, decodes J and U as UTF-8 in 2 and Z only, stops at 160 KiB of characters (Coinkite's signed.txn is over it, in H), and can write a last part longer than the others, which Faraday refuses; its deflate reads a 1,024-byte window on a device, which the shim reads and writes. A set with an empty last part is read by Coinkite and krux and refused by Faraday, which refuses any part with no data.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 15000 cases

Secret handling

none: no secret leaves faraday-keys

Not stated; no secret is computed here.

The parts a transfer is put together from are wiped (zeroize).

Limits

BBQr file types P, T, U and J are read; the others are refused.

A frame is at most 4,096 characters, a transfer at most 1,295 parts and 360 KiB put together or decompressed; numbered parts are at most 1,000.

Parts of two transfers, a part arriving twice with different contents and parts of uneven length are refused.

Faraday's own calls

Every limit fails closed: a frame, a count or a size past it is refused. Conservative, F155.

Wrap a file in an envelope

SpecificationOwn specificationCodeLibrary: bitcoin 0.32Library: base16ct 1.0 (through core/faraday-crypto)Faraday's code: faraday/faraday-qrCross-checked withNot cross-checked
Action

Puts a file in the faraday-file-v1 envelope with its SHA-256 and checks one received, saving a file received once.

Specification

Own specification (no decision)

Code

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: faraday/faraday-qr: The envelope is canonical JSON with sorted keys and no spaces; unpack reads the fields, puts the file in an envelope again and refuses unless the bytes are identical; the SHA-256 of the file is written in the envelope and checked when one is read. A scanned text is taken as an envelope only when it looks like one and unpack accepts it.

Checked against

not checked against vectors

faraday/faraday-qr/tests/interop.rs::faraday_oss_file_transfers_arrive_whole

faraday/faraday-qr/tests/interop.rs::an_envelope_that_does_not_match_its_file_is_refused

fuzz qr_assembler

Cross-check

not cross-checked: Faraday OS's own format; the tests read what Faraday OS writes, and the cross-check has no second implementation

Secret handling

none: no secret leaves faraday-keys

Not stated; a SHA-256 over a file.

A secret received is returned for the hold that saves it, in a Zeroizing buffer; the buffer that joins name, extension and data is zeroized after hashing.

Limits

A file of no bytes or over 256 KiB is refused.

A kind other than file, public-key or signing-subkey is refused.

A name is 1 to 128 letters, digits, dots, hyphens or underscores.

An envelope over BBQr's 360 KiB is refused.

Faraday's own calls

The SHA-256 shows that the file arrived whole, not who sent it. Neutral.

no decision

An envelope is refused unless it is exactly what pack would write for its file. Conservative.

no decision

Hash a file

SpecificationFIPS 180-4PublishedCodeLibrary: sha2 0.11Library: base16ct 1.0Faraday's code: core/faraday-cryptoCross-checked withPython's hashlib (SHA-256)Others' code
Action

Computes the SHA-256 of a whole file to show and keep.

Specification

FIPS 180-4, Secure Hash Standard, Status not checked

Code

Library: sha2 0.11.0, by the RustCrypto developers.

Library: base16ct 1.0.0, by the RustCrypto developers.

Faraday's code: core/faraday-crypto: sha2's SHA-256 over every byte, counted as file-hash work through the compute token. A file in the Inbox is hashed when it comes in and the sum is kept on it, a lookup after; the Files menu and the GPG signing page hash through the same function.

Checked against

not checked against vectors

core/faraday-crypto/tests/primitives.rs::sha256_known_answers

no fuzz target: Takes any bytes and parses nothing

Cross-check

Compared with others' code: Python's hashlib (SHA-256), over random files of every length around the 64-byte blocks and of 4 KiB, 64 KiB and 1 MiB with a byte more and less.

Area hash

Faraday's code faraday_bip::hashes and faraday_codec::encodings (read, the writers and from_hex), faraday_core::file_menu::sha256, and faraday_crypto::hkdf_sha256 and hkdf_sha256_expand, hmac_sha256, hmac_sha512, pbkdf2_hmac_sha256, pbkdf2_hmac_sha512 and scrypt

Compared with Bitcoin Core v31.1's functional-test framework (core/): ripemd160.py, address.py and segwit_addr.py, with hashlib for SHA-256 and bytes.fromhex for hex; PyCA cryptography's HKDF and HKDFExpand (OpenSSL) for the one HKDF; hmac, hashlib.pbkdf2_hmac and hashlib.scrypt (OpenSSL) for HMAC, PBKDF2 and scrypt.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; the order read tries the spellings in, the trimming of the text, hex as an even number of hex digits, plain Base58 (which Core's framework does not read; the area's own few lines) and which prefixes make a segwit address are Faraday's rules, written in the area in front of the reference.

The file hash is file_menu::sha256 over a whole byte slice (it reads in no buffer, so no read size is probed); the Files screen's reading of a file from a stick is the files areas'.

Vectors FIPS 180-4's SHA-256 examples, RIPEMD-160 of abc, BIP-173's key and its HASH160, Bitcoin Core's first key_io_valid.json address, BIP-173's and BIP-350's bech32 strings and their valid and invalid segwit addresses (tools/vectors/addresses).

Random cases Random bytes of every length from 0 to 130 and to 300 hashed (SHA-256, SHA-256d, HASH160) and as a file, files of 4 KiB, 64 KiB and 1 MiB with a byte more and less; random bytes written and read as Base58Check, Base58, bech32 and bech32m, Core's writing read by Faraday, segwit addresses of every version Core's framework writes, and texts changed, cut or made of random characters read by both.

Differences bech32 groups: a string that is not a segwit address of bc, tb or bcrt is read as bytes, all its data groups together, and the bits that do not fill a byte are dropped. BIP-173 has a padding rule only for a segwit address, so Core's convertbits, which applies it to any data, refuses some of these strings, and the area reads them as Faraday does.

bech32 length: Core's decoder refuses more than 90 characters (BIP-173); Faraday accepts any length the checksum covers. The area reads longer strings the same way.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Secret handling

none: no secret leaves faraday-keys

No secret is handled.

Nothing secret is held.

Limits

The digest shows integrity, not origin.

Faraday's own calls

The digest is shown as the file's integrity, not as proof of who made it. Neutral.

no decision

Vaults

11 actions · 7 own specification · 2 with Faraday's own code · 8 cross-checked with others' code · 5 with Faraday's second version · 3 not cross-checked

How the vault is built

SpecificationOwn specificationCodeSpecification · 3 actions

Two layers

A vault has two layers. The lock is the passphrase, Argon2id, ChaCha20 and HMAC. It is what keeps secrets safe. All of it is published, and each algorithm comes from an established library.

The plumbing is the code that lays the file out, reads it back and decides which field holds what. Most of what is Faraday's own is here. A bug in the plumbing usually means a file that does not open. The exception is in writing, under Security.

The file

A vault is one KDBX 4 file, the database format KeePass writes, under one passphrase. Faraday writes it in one shape and reads the shapes a KeePass app saves within limits.

The file holds a plaintext of a whole number of 32 KiB steps, from one step to 128 MiB, framed in blocks and wrapped in a header. A vault is as small as its contents allow, and no size is chosen.

The file's name ends in .kdbx. There is one passphrase and no slots: a file does not hide how many passphrases exist, because there is one.

The keys

The passphrase is put in Unicode Normalization Form C (UAX #15), and its UTF-8 bytes are hashed with SHA-256 twice to make KDBX 4's composite key. Then "é" typed as one character (U+00E9) and as "e" with a combining accent (U+0065 U+0301) open the same vault.

Argon2id version 1.3 (RFC 9106) stretches the composite key under the header's salt, memory, passes and lanes to 32 bytes; SHA-256 and SHA-512 over that and the header make the encryption key and the HMAC base, and each block has its own HMAC key.

Create a vault offers five memory steps, from 64 MiB to 1 GiB, each at 3 passes and 4 lanes. The lanes do not change the work a guess costs.

Sealing and opening

The body is the database's XML, padded to the file's size with line feeds and encrypted with ChaCha20, in blocks of 1 048 576 bytes each with its own HMAC-SHA-256 over its length and bytes. The header carries its own SHA-256 and HMAC-SHA-256.

The reader checks the version, the header's fields, the cost against its limits and the file's length before any memory is asked for, then derives the keys once. Every block's HMAC is checked before its bytes are used; a missing or extra block, a changed byte and a cut file are refused.

A seal writes the file again with a fresh salt, fresh IVs and a fresh inner key, all from one answer the caller draws, and a seal count one more than the last with the time.

A file a KeePass app saved with another cipher or KDF the reader takes, or other settings, opens, and its next seal writes it in Faraday's shape; only a format mark other than the one this build writes or a Meta that reads ambiguously holds a vault read only.

What it promises

Without the passphrase, the file shows its header, which states the cost and the salt, and a length that is a whole number of 32 KiB steps. Nothing in the body can be read or changed without the passphrase: the header's and every block's HMAC fail first.

What it does not promise

Offline guessing. Anyone with the file has its salt and cost and can try passphrases on their own computers. Each guess costs one Argon2id at the vault's cost.

Rollback. An older copy of a vault still opens. Someone who can write to the stick can put an older copy back; they cannot read or change anything in it. The seal count is how an older copy is told from a newer one.

A vault's size and its seal count are in the clear or can be read by whoever opens it; the cost and salt are in the header.

Independent review. Faraday's reader and writer are its own and have been read by pykeepass, keepassxc-cli and keepass-rs, in the vault cross-check area, over the files they write and the files those programs write.

Availability. A changed byte anywhere in the file fails its HMAC and the vault does not open; a backup is how a damaged vault is recovered.

What is Faraday's own, and why

The format and the algorithms are published. These pieces are not. For each: what it does, what could replace it, and why it is not taken.

KDBX reader and writer. Reads and writes the file vault: the header, the block stream, the cipher steps and the XML. Could be replaced by the keepass crate (keepass-rs). It drops the XML elements it does not model, which would disturb what a KeePass app wrote into the file, and it draws a save's randomness itself, with no way to pass the session's in. No audit of it is one Faraday's dependency checks trust. It is used in the tests as an outside reader and writer, never in what ships.

Faraday's names inside the vault. Decides which KeePass field holds a seed's words, a wallet or a GPG key, and keeps Faraday's settings in custom data under names that start with faraday. Could be replaced by nothing, since no standard puts a Bitcoin seed in KeePass. Unavoidable. An item the reader does not expect is named Unreadable and never used.

Padding after the XML. Keeps each file at one of its sizes, by adding line feeds after the XML's closing tag. Could be replaced by nothing, since KDBX has no padding of its own. It uses what XML already allows after its last tag, so a KeePass app reads the padded file as any other. A KeePass app that saves the file drops the padding.

OpenPGP code for the QR vault. Writes and reads the three packets a QR vault is made of. Could be replaced by rPGP (pgp) or Sequoia. Each brings every algorithm OpenPGP has had, with all the libraries those need, for a message that uses AES and OCB alone. rPGP has been audited by outside reviewers, but none of those audits is one Faraday's dependency checks trust, so each library it brings would be Faraday's own to vet.

HKDF (RFC 5869). Turns one key into others; in the vault only the QR vault uses it. Could be replaced by the hkdf crate. It leaves the intermediate key and each output block in freed memory unwiped; Faraday's own wipes them.

QR vault contents. The short TOML inside the code, padded to one length, holding one seed, share, passphrase or note. Could be replaced by nothing, since no standard exists for an encrypted seed QR that other tools read. Unavoidable. The cross-check reads the contents with an outside TOML parser.

Security

What protects secrets is all published. Someone with the file faces Argon2id at the vault's memory step, then the cipher. None of that is Faraday's design.

The main risk is parsing. The device reads files from outside, and a bug in a reader could crash it, hang it, or make it accept or refuse a file wrongly. The guards: a file's memory, passes and lanes are checked against limits before any memory is asked for; every block's HMAC is checked before its bytes are used; anything unexpected is refused, never guessed at; the XML reader refuses a DOCTYPE and an entity it does not know; each reader has a fuzz target; and pykeepass, keepassxc-cli and keepass-rs read what Faraday writes, and Faraday reads what they write.

The QR vault's reader checks the Argon2 cost against the same limits right after the key packet, before the data packet is read, and refuses every packet it does not use.

The one subtle risk is in writing. If Faraday's code reused a value it should draw fresh, a nonce for example, the file would still open everywhere, so the cross-check would not notice, but the encryption would be weaker. A library carries the same risk in its own code. The guard: every seal draws its bytes from one call for the session's randomness, and the specification counts every byte that call returns.

The library trade. A large audited library is more code that Faraday did not write and more to vet, looked at by others. A small piece of Faraday's own is less code and nothing extra to vet, looked at by Faraday, its tests and three outside programs. For one file format the small piece is taken, and keepass-rs would also give up two requirements of the file vault: that what a KeePass app wrote is kept, and that the session's randomness is the only source.

Key commitment. Every HMAC in a file vault is keyed from the key its passphrase makes, so no second passphrase opens the file to other contents.

OCB does not commit to its key. A QR vault someone else made could be built to open to two contents under two passphrases. Faraday makes every QR vault under one passphrase.

Later work. Faraday does not yet wipe every copy of a key left in freed memory, and Argon2id's later passes read memory at places the passphrase decides, which a program on the same computer could time. The device is offline and powered off after use, so both wait.

Opening it elsewhere

This shows the file is standard, and is not the way to use a vault. The cross-check opens a file vault with pykeepass, keepassxc-cli and keepass-rs, and Faraday opens what they write.

A QR vault is read by Sequoia's sq and by rPGP in the cross-check. GnuPG cannot read a QR vault: it follows LibrePGP, not RFC 9580.

Unlocking a vault on a computer that is online shows its seed on that computer. It is a last resort, for when Faraday is gone and the seed is needed back. Move the funds to a new seed afterwards and treat the old seed as exposed. The way to open a vault is Faraday on the offline device.

Passphrase strength

SpecificationOwn specificationCodeSpecification · 1 action

Words from dice

A passphrase of words drawn by dice from a list carries log2 of the list's length in bits for every word. Faraday has the three lists the EFF publishes (EFF word lists):

WordsEFF large list: 7 776 words, 12.9 bits a wordEFF short list 1: 1 296 words, 10.3 bits a wordEFF short list 2: 1 296 words, 10.3 bits a word
451.741.441.4
564.651.751.7
677.562.062.0
790.572.472.4
8103.482.782.7
9116.393.193.1
10129.2103.4103.4

The bits hold when every word is drawn by fair dice or by the computer's randomness, and not when a person chooses a word.

What Argon2id adds

Each guess costs one Argon2id at the vault's memory and passes, on the guesser's own hardware. Faraday states that work as log2(memory in KiB × passes) bits, which Create a vault shows beside each cost. The memory of the vaults Faraday makes ranges over a factor of 16, which is 4 bits; one more word from the large list is 12.9. The figure counts work, not how much more memory costs a guesser than time, and it gives no time per guess.

Other passphrases

A person may use any passphrase. Its strength is then theirs to ensure: Faraday does not measure a typed passphrase. A short passphrase, or one used anywhere else, is not protected by any cost.

Where to learn more

The EFF's page on dice-generated passphrases, eff.org/dice.

Arnold Reinhold's Diceware page, where the method began, theworld.com/~reinhold/diceware.html.

NIST Special Publication 800-63B, Digital Identity Guidelines, on what makes a password strong.

Make a vault

SpecificationKeePass KDBX 4 · RFC 9106 · RFC 8439 · 2 morePublishedOwn specificationCodeLibrary: chacha20 0.10Library: hmac 0.13Library: sha2 0.112 moreFaraday's code: faraday/faraday-vaultCross-checked withNot cross-checked
Action

Makes a vault file: an empty KDBX 4 database with a root group of the given UUID and name, stamped as the first seal, written at the smallest size, 32 KiB of contents, under one passphrase with Argon2id, ChaCha20 and an HMAC per block; the file's salt, IVs and inner key come from one 140-byte answer the caller draws.

Specification

Own specification

KeePass KDBX 4, The KeePass database format, version 4, Convention

RFC 9106, Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications, Informational

RFC 8439, ChaCha20 and Poly1305 for IETF Protocols, Status not checked

RFC 2104, HMAC: Keyed-Hashing for Message Authentication, Status not checked

UAX #15, Unicode Standard Annex #15: Unicode Normalization Forms, Complete

Code

Library: chacha20 0.10.2, by the RustCrypto developers.

Library: hmac 0.13.0, by the RustCrypto developers.

Library: sha2 0.11.0, by the RustCrypto developers.

Library: unicode-normalization 0.1.25, by the unicode-rs developers.

Library: argon2 0.6.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: faraday/faraday-vault: The passphrase is put in NFC; the container is `kdbx::seal` (the `vault-kdbx` action); a size that is not one of the four is refused before any work; a cost whose memory cannot be allocated is an error that names the MiB needed.

Checked against

tools/vectors/vault

Faraday's own known answers.

tools/vectors/vault-primitives

Published, by the Argon2id answer of tools/vectors/kdf (argon2-cffi and OpenSSL agree on it).

tools/vectors/kdf

Published, by RFC 7914 §12, for scrypt; the Argon2id answer computed by argon2-cffi and PyCA cryptography, which agree.

faraday/faraday-vault/tests/vectors.rs::the_committed_vectors_are_what_this_build_writes

faraday/faraday-vault/tests/vectors.rs::an_empty_passphrase_is_refused_at_create

faraday/faraday-vault/tests/file.rs::a_vault_is_made_opened_and_sealed_again_with_its_count_going_up

faraday/faraday-vault/tests/file.rs::a_new_vault_is_one_step_and_the_largest_has_the_length_the_spec_gives

faraday/faraday-vault/tests/file.rs::two_seals_with_different_random_bytes_are_different_files

faraday/faraday-vault/tests/file.rs::a_wrong_passphrase_is_named_and_the_two_forms_of_a_passphrase_are_one

no fuzz target: Creation takes no outside bytes but the passphrase and the caller's answer; kdbx_file and kdbx_body fuzz what a vault is read from

Cross-check

Own specification, not yet reviewed outside Faraday.

An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.

not cross-checked: The `vault` cross-check area judges the Argon2id step (argon2-cffi and PyCA) and the NFC step (Python's `unicodedata`) a vault is made with. The KDBX file `file::create` makes, and the one an export makes (`file::create_holding`), is read by pykeepass, `keepassxc-cli` and keepass-rs in that area, and its changes by them too

Secret handling

none: no secret leaves faraday-keys

Not stated by the argon2, hmac or chacha20 crates.

The Argon2id output, the encryption key, the HMAC base and every block key are Secret values wiped on drop; the Argon2id memory is overwritten before it is released; the passphrase's NFC form is wiped on drop (the normaliser's own buffer of combining marks is not).

Limits

One passphrase, non-empty; no slots, no second passphrase.

File sizes 64 KiB, 256 KiB, 1 MiB and 4 MiB only.

A vault is made at any cost the reader accepts: memory 8 MiB to 1 GiB, 1 to 100 passes, 1 to 64 lanes.

A cost whose memory cannot be allocated is an error that names the MiB needed.

A passphrase is put in Unicode NFC, and Argon2id takes that form's UTF-8 bytes.

Faraday's own calls

The file vault is one KDBX 4 file with one passphrase, padded to a multiple of 32 KiB, so a file's length says how much it holds to within 32 KiB and, between two copies, that it grew or shrank (F206). Conservative, F206.

Every passphrase is put in Unicode NFC before Argon2id, and nothing else is done to it: compatibility characters, case and spaces are kept as typed. Neutral, F159.

Open a vault

SpecificationKeePass KDBX 4 · RFC 9106 · RFC 8439 · 2 morePublishedOwn specificationCodeLibrary: chacha20 0.10Library: hmac 0.13Library: sha2 0.112 moreFaraday's code: faraday/faraday-vaultCross-checked withargon2-cffi (the Argon2 designers' reference code)Others' codeFaraday's second version
Action

Opens a vault file with its passphrase: checks the header and the cost before any memory is asked for, derives the keys once with Argon2id, checks the header's and every block's HMAC, decrypts and inflates the body and reads its items; a wrong passphrase and a damaged file are told apart only where KDBX 4 allows.

Specification

Own specification

KeePass KDBX 4, The KeePass database format, version 4, Convention

RFC 9106, Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications, Informational

RFC 8439, ChaCha20 and Poly1305 for IETF Protocols, Status not checked

RFC 2104, HMAC: Keyed-Hashing for Message Authentication, Status not checked

UAX #15, Unicode Standard Annex #15: Unicode Normalization Forms, Complete

Code

Library: chacha20 0.10.2, by the RustCrypto developers.

Library: hmac 0.13.0, by the RustCrypto developers.

Library: sha2 0.11.0, by the RustCrypto developers.

Library: unicode-normalization 0.1.25, by the unicode-rs developers.

Library: argon2 0.6.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: faraday/faraday-vault: The passphrase is put in NFC; the container is `kdbx::open` (the `vault-kdbx` action); a file longer than the largest vault takes, or whose cost or version is outside the limits, is refused before any work; a file of another length opens with no size stated, and its next seal takes the smallest size that holds the contents; a file a KeePass app saved with a cipher and a KDF the reader takes is opened and its next seal writes it in Faraday's one shape; only a `faraday.format` other than the one this build writes, or a Meta or custom data that cannot be told apart from what was read, holds a vault read only.

Checked against

tools/vectors/vault

Faraday's own known answers.

tools/vectors/vault-primitives

Published, by the Argon2id answer of tools/vectors/kdf (argon2-cffi and OpenSSL agree on it).

tools/vectors/kdf

Published, by RFC 7914 §12, for scrypt; the Argon2id answer computed by argon2-cffi and PyCA cryptography, which agree.

faraday/faraday-vault/tests/vectors.rs::the_vault_of_every_kind_opens_to_what_it_was_made_from

faraday/faraday-vault/tests/vectors.rs::the_small_and_the_codex32_vaults_open

faraday/faraday-vault/tests/vectors.rs::the_nfd_vector_opens_under_either_form

faraday/faraday-vault/tests/vectors.rs::each_refused_file_is_refused_under_its_name

faraday/faraday-vault/tests/vectors.rs::a_stream_that_ends_early_is_damage

faraday/faraday-vault/tests/file.rs::a_wrong_passphrase_is_named_and_the_two_forms_of_a_passphrase_are_one

faraday/faraday-vault/tests/file.rs::a_file_a_keepass_app_saved_opens_and_is_sealed_as_faraday_writes_one

faraday/faraday-vault/tests/open_py.rs::open_py_prints_every_item_under_its_name_with_the_values_pykeepass_reads

faraday/faraday-vault/tests/open_py.rs::open_py_opens_the_nfd_vector_under_either_form

faraday/faraday-vault/tests/open_py.rs::open_py_refuses_damage_and_an_older_version

fuzz vault_header

fuzz kdbx_file

Cross-check

Own specification, not yet reviewed outside Faraday.

An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.

Compared with others' code: argon2-cffi (the Argon2 designers' reference code), for Argon2id, and Python's unicodedata, for the NFC form.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the payload layouts of docs/VAULT.md §7, written in area_vault.py from that document; the KDBX file itself is read by pykeepass, keepassxc-cli and keepass-rs in the area (an outside reader each).

Area vault

Faraday's code faraday_vault's file (file::create, open and seal, the document model and the items of §7), its payload layouts and a passphrase's NFC form with the Unicode version it is made under, file::create_holding (an export), and faraday_crypto::argon2id

Compared with Pykeepass and keepassxc-cli (the distribution's packages) for the vault file, both ways, and keepass-rs for the file format only; docs/VAULT.md §7 written out in area_vault.py, over argon2-cffi and PyCA cryptography's Argon2id (OpenSSL's) (the distribution's packages) and Python's unicodedata, for the payloads.

Checked first: check_primitives runs before anything else: argon2-cffi and PyCA (44 or later over OpenSSL 3.2 or later, or the area stops) against tools/vectors/kdf/'s known answer; pykeepass and keepassxc-cli are the distribution's packages and the area stops and names a missing one, so a run without it fails; their versions are written into the stamp; the area stops where Python's Unicode is newer than unicode-normalization's.

keepass-rs does not count for the primitives and takes no part in the NFD or wrong-passphrase cases of files it did not read; the QR vault and OpenPGP are other areas.

Vectors The Argon2id known answer (tools/vectors/vault-primitives/); the export vector of tools/vectors/backup/, read with a byte changed refused, and with each bit of the version field and bit 44 of the Argon2 iterations changed refused; every file of tools/vectors/vault/, read by Faraday and by both outside readers.

Random cases Argon2id at small random costs and the costs it refuses; payloads made, read and malformed; passphrases in NFC, by case and at random; vaults Faraday writes at small costs with items of every kind of §7 and seals once more, read by pykeepass (every group, entry, field, protected mark and custom data item) and keepassxc-cli (listing and every field), under the passphrase, its NFD form, a wrong one and a changed byte; exports (file::create_holding) of one to eight entries whose Title, Notes and Password hold control characters, read the same way; files pykeepass makes at random (ciphers, KDFs, compression, tags, icons, custom properties, attachments, history, custom data) and keepassxc-cli makes (groups, entries, notes, attachments), opened in Faraday and sealed once more with nothing of the other program's lost; keepass-rs (format only, not counted for the primitives) reads the vaults Faraday writes and seals, with a wrong passphrase, the NFD form and a changed byte refused, and writes files (AES-256 or ChaCha20, Argon2d or Argon2id, compression or not, groups, entries, tags, icons, properties, attachments, custom data) that Faraday opens and seals once more.

Differences Pykeepass strips the characters XML 1.0 cannot hold from a protected value after decrypting it; Faraday keeps a Password's characters as they are put in (and leaves them out of a Title or Notes when it writes). The export loop expects pykeepass's reading of a Password and Faraday's own as put in, and counts the passwords that differ.

Pykeepass opens a file whose major version is neither 3 nor 4 without reading past it, deriving a key or checking a hash; KeePass refuses such a file, and the area counts a file as opened only when pykeepass read a KDBX 4 body (readers.open_kdbx). It also runs the key derivation the header states before it checks the header's SHA-256, so a changed bit in the Argon2 iterations (2^44 passes) holds it for good; KeePass and keepassxc-cli refuse at once, and the area asks pykeepass first with a key given and nothing decrypted.

The vault's passphrase is put in NFC (§3); KeePass apps do not. A vault under an NFC passphrase opens in Faraday under its NFD form and in neither outside reader. The area counts the NFD tries and expects exactly that.

Faraday's reader is stricter than the outside readers' in what it takes of a file (§4, §7.1): a block stream that ends before its empty last block (keepassxc-cli reads it), an XML document with an element after the root (keepassxc-cli), a protected value not canonical Base64, nesting past 64, another root element, a DOCTYPE and another encoding (pykeepass reads these). WIDER names each and the reader that opens it; the area expects exactly that set and counts those opens as known differences.

keepass-rs writes files Faraday refuses (§4): Twofish, AES-KDF and a Salsa20 inner stream (keepass_rs.REFUSED). The area makes one of each, expects Faraday to refuse it and counts the refusals as known differences.

KeePassXC 2.7.10 (and its development branch, November 2026) fails a save of a ChaCha20 file whose plaintext is a multiple of 1024 bytes, "Writing the database failed: Cannot process 0 length data.", and writes nothing: SymmetricCipherStream encrypts each full block of 1024 bytes as it fills and then the empty rest, which SymmetricCipher::process refuses (AES-256's last block is padded). Each save puts a random value of 128 to 1022 hex digits in the file (KPXC_RANDOM_SLUG), so it is chance, compressed or not, about one save in 450 at most. readers.Kpxc makes a command that writes again, once, from the file in a new shell, only on exactly that message and for a ChaCha20 file left byte for byte as it was; the save made again is judged as any other, a second such failure in a row fails the run, and each is counted as a known difference. The prelude shows the condition (kpxc_zero_length): on a file whose plaintext but for the random value is known (its ciphertext's length less the value pykeepass reads), 1500 saves that cannot reach a multiple of 1024 bytes do not fail, of saves that can, one must fail within 20,000, and the same file under AES-256 does not fail; when KeePassXC no longer fails, the run fails and the handling is to go.

keepass-rs decodes a custom data item's value as Base64 when it can, and the program encodes the bytes again (keepass-rs/src/main.rs). A value that is valid Base64 but not canonical (padding or trailing bits the encoder would not write) comes back as another text, so keepass-rs's reading of such a value differs from the file's and from pykeepass's. The area compares custom data as they are, so such a value is a known difference of keepass-rs, not a disagreement about the format.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 26310 cases

Secret handling

none: no secret leaves faraday-keys

The header's and every block's HMAC are compared in constant time (`verify_slice`); Argon2, SHA-2 and ChaCha20 state nothing more.

The keys are Secret values wiped on drop; the decrypted and inflated body are Zeroizing buffers; the passphrase's NFC form is wiped on drop.

Limits

Refuses a file longer than the largest vault takes, and one whose version, cipher, KDF or cost is not one the reader takes, before any derivation; a file of another length is not refused.

Refuses a file in which any block's HMAC or the header's does not verify.

A wrong passphrase and a file that needs a key file as well give the same refusal.

KDBX 3.1, AES-KDF, Twofish and an empty passphrase are named and refused.

Faraday's own calls

A file a KeePass app saved with other settings is opened and changed like any vault, and its next seal writes it in Faraday's one shape; it is held read only only for a `faraday.format` other than the one this build writes or a Meta that reads ambiguously (F190). Conservative, F190.

Seal a QR vault

SpecificationRFC 9580 · RFC 7253 · RFC 9106 · 1 morePublishedCodeFaraday's code: faraday/faraday-keysCross-checked withSequoia's sq and rPGPOthers' codeFaraday's second version
Action

Seals a typed note, a loaded key's words, or a seed, codex32 share, BIP-39 passphrase or note of an open file vault, as a QR vault under a typed passphrase and a memory step, and reads the seal back before the code is given.

Specification

RFC 9580, OpenPGP, Proposed Standard

RFC 7253, The OCB Authenticated-Encryption Algorithm, Informational

RFC 9106, Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications, Informational

RFC 5869, HMAC-based Extract-and-Expand Key Derivation Function (HKDF), Informational

Code

Faraday's code: faraday/faraday-keys: Writes the contents (`faraday-vault::contents`) and seals them as the message of the action above with 95 random bytes the device drew; a key's words are lent for the seal and not kept; a vault item is read once, when the job is made, checked to fit and left in the vault.

Checked against

not checked against vectors

faraday/faraday-core/tests/all/qr_tool.rs::a_note_typed_and_sealed_opens_back_with_the_same_text

faraday/faraday-core/tests/all/qr_tool.rs::a_loaded_key_is_sealed_and_opens_back_as_a_seed

faraday/faraday-core/tests/all/qr_save_item.rs::a_note_is_saved_as_a_qr_vault_that_opens_back_to_it_and_stays_in_the_vault

faraday/faraday-core/tests/all/qr_save_item.rs::a_seed_is_saved_and_its_kept_passphrase_is_said_to_be_left_out

fuzz pgp_qr_vault

Cross-check

Compared with others' code: Sequoia's sq and rPGP, as for the OpenPGP message the code is.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: none beyond the message's own.

Area qrvault

Faraday's code faraday_vault::qr (the QR vault sealed and opened, with faraday_pgp::message)

Compared with Sequoia's sq, the distribution's package, over Nettle (judges the primitives except Argon2, which it shares with the app's lineage); rPGP (tools/crosscheck/rpgp/, a program outside the workspace, on RustCrypto like the app: judges the format only); PyCA cryptography's Argon2id, HKDF-SHA-256 and AES-256-OCB (OpenSSL's), which judge the primitives, under the OpenPGP framing written in the area from RFC 9580 and docs/VAULT.md §1.2 (Faraday's second version, not another program's); the QR TOML qr_toml written in the area from §2.1, each opened item also read by CPython's tomllib.

Checked first: Sq is the distribution's package, built over Nettle (the run stops otherwise, judges.py), its version written into the stamp; rPGP is built from the crates.io release tools/crosscheck/rpgp/Cargo.lock names; PyCA must be 44 or later over OpenSSL 3.2 or later or the area stops, and its Argon2id, HKDF-SHA-256 and AES-OCB are checked against the repository's Argon2id known answer, RFC 5869 test case 1 and RFC 7253's first vector first; sq and rPGP open the repository's vault vectors, and so does the PyCA judge, which reads strictly and refuses anything but a QR vault.

OpenPGP.js, which docs/VAULT.md §10 names, is not run; sq does not seal a QR vault (below); rPGP judges the format only. §1.2's wider reading, which only Faraday's reader is held to, is not compared with a judge: any literal date, padding packets after the SEIPD packet and the literal data, and every length form RFC 9580 allows; of the chunk size octets only 0 (rPGP seals several chunks, Faraday opens them) and 10 are run.

Vectors The seven vaults of tools/vectors/vault/qr/ opened by sq, rPGP and the PyCA judge to the item each holds and by Faraday; the four refused messages refused by Faraday and by the PyCA judge; the PyCA judge refuses a vector with a byte changed in each field.

Random cases An item of every kind of §2.1 (12 and 24 words, a codex32 share, a passphrase, a note with markup, control characters and several scripts, the empty vault) sealed by Faraday and opened by sq, rPGP, the PyCA judge and Faraday, and sealed by rPGP and by the PyCA judge (memory 2^13 to 2^16 KiB) and opened by Faraday, each opened item read by tomllib; each memory step of §3 (2^16 to 2^20 KiB) sealed by Faraday at scale 1, each message equal byte for byte to the PyCA judge's seal of the same random bytes; items at the size limits (a note of 216 and 217 bytes, a passphrase of 193 and 194, a 24-word seed of the longest words); a passphrase in NFD or NFC either way; a wrong passphrase; a 15-word seed and a document of two keys sealed by rPGP, refused by Faraday; the messages sq writes, refused by Faraday and the PyCA judge; two items sealed by rPGP in chunks of 64 bytes (chunk size octet 0), opened by Faraday.

Differences QR vault: sq 1.3.1 writes a SKESK v4 and a SEIPD v1 for a password under either --profile, never the SKESK v6 and SEIPD v2 of RFC 9580, so sq cannot seal a QR vault; rPGP and the PyCA judge seal the other direction, and the area asserts that Faraday and the PyCA judge refuse what sq writes. The PyCA judge's framing is the area's own Python; OpenPGP.js is not run.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 450 cases

Secret handling

Reveal::QrVault

Not stated; the seal is the message's.

The typed note and passphrases are wiped when the code is made; the random bytes and the key's or vault item's words copied into the job are wiped on drop, not lent.

Limits

A note holds the room the contents leave; a key of other than 12 or 24 English words is not offered; a vault item over the same room is refused with the reason, and a note with the characters to take off.

The memory step is one of the steps the message allows; a computer without the room for it refuses.

Faraday's own calls

A passphrase is typed twice and is not measured; the code is only as strong as it. Neutral, F190.

Open a QR vault

SpecificationRFC 9580 · RFC 7253 · RFC 9106 · 1 morePublishedCodeFaraday's code: faraday/faraday-keysCross-checked withSequoia's sq and rPGPOthers' codeFaraday's second version
Action

Opens a scanned QR vault code, or a chosen .pgp file, under a typed passphrase, and holds the one item it holds for the QR vault tool to say what it is and, behind an eye, to show a note or a passphrase; then offers what that item takes: a seed's words to the seed sheet, a share to the codex32 form, a passphrase added to the loaded key whose words make the key it names (with the offer worked out from fingerprints alone), and a note saved in the open file vault.

Specification

RFC 9580, OpenPGP, Proposed Standard

RFC 7253, The OCB Authenticated-Encryption Algorithm, Informational

RFC 9106, Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications, Informational

RFC 5869, HMAC-based Extract-and-Expand Key Derivation Function (HKDF), Informational

Code

Faraday's code: faraday/faraday-keys: Reads the message of the action above with the typed passphrase after its stated Argon2 cost is checked against the limits (the app also checks the cost against the memory this computer has free before it starts the job, and names a code it cannot open at once), and reads the contents (`faraday-vault::contents`) into one held item that leaves `faraday-keys` only through the `Reveal::QrVault` reveals. The offers lend the held words or share once to the seed sheet or the codex32 form; `qr_passphrase_offer` makes the BIP-39 seed and BIP-32 master fingerprint of each loaded key with the held passphrase and returns only fingerprints, and `qr_add_passphrase` adds the key it finds; `qr_save_note` writes the note as a note record of the open vault.

Checked against

tools/vectors/vault

Faraday's own known answers.

faraday/faraday-keys/tests/qr_vault.rs::a_committed_code_opens_and_its_cost_reads_without_a_passphrase

faraday/faraday-core/tests/all/qr_tool.rs::an_empty_qr_vault_reads_empty

faraday/faraday-core/tests/all/qr_tool.rs::a_seed_and_a_passphrase_are_named_and_a_passphrase_is_behind_its_eye

faraday/faraday-core/tests/all/qr_tool.rs::the_right_passphrase_shows_a_note_behind_its_eye

faraday/faraday-core/tests/all/qr_tool.rs::a_wrong_passphrase_says_so_and_a_second_try_opens

faraday/faraday-core/tests/all/qr_tool.rs::an_opened_seed_goes_to_the_seed_sheet_and_loads_as_a_key

faraday/faraday-core/tests/all/qr_tool.rs::an_opened_share_is_typed_into_the_codex32_form

faraday/faraday-core/tests/all/qr_tool.rs::an_opened_passphrase_is_added_to_the_key_its_words_make

faraday/faraday-core/tests/all/qr_tool.rs::an_opened_note_is_saved_as_a_note_last_in_the_open_vault

fuzz pgp_message

Cross-check

Compared with others' code: Sequoia's sq and rPGP, as for the OpenPGP message the code is.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: none beyond the message's own.

Area qrvault

Faraday's code faraday_vault::qr (the QR vault sealed and opened, with faraday_pgp::message)

Compared with Sequoia's sq, the distribution's package, over Nettle (judges the primitives except Argon2, which it shares with the app's lineage); rPGP (tools/crosscheck/rpgp/, a program outside the workspace, on RustCrypto like the app: judges the format only); PyCA cryptography's Argon2id, HKDF-SHA-256 and AES-256-OCB (OpenSSL's), which judge the primitives, under the OpenPGP framing written in the area from RFC 9580 and docs/VAULT.md §1.2 (Faraday's second version, not another program's); the QR TOML qr_toml written in the area from §2.1, each opened item also read by CPython's tomllib.

Checked first: Sq is the distribution's package, built over Nettle (the run stops otherwise, judges.py), its version written into the stamp; rPGP is built from the crates.io release tools/crosscheck/rpgp/Cargo.lock names; PyCA must be 44 or later over OpenSSL 3.2 or later or the area stops, and its Argon2id, HKDF-SHA-256 and AES-OCB are checked against the repository's Argon2id known answer, RFC 5869 test case 1 and RFC 7253's first vector first; sq and rPGP open the repository's vault vectors, and so does the PyCA judge, which reads strictly and refuses anything but a QR vault.

OpenPGP.js, which docs/VAULT.md §10 names, is not run; sq does not seal a QR vault (below); rPGP judges the format only. §1.2's wider reading, which only Faraday's reader is held to, is not compared with a judge: any literal date, padding packets after the SEIPD packet and the literal data, and every length form RFC 9580 allows; of the chunk size octets only 0 (rPGP seals several chunks, Faraday opens them) and 10 are run.

Vectors The seven vaults of tools/vectors/vault/qr/ opened by sq, rPGP and the PyCA judge to the item each holds and by Faraday; the four refused messages refused by Faraday and by the PyCA judge; the PyCA judge refuses a vector with a byte changed in each field.

Random cases An item of every kind of §2.1 (12 and 24 words, a codex32 share, a passphrase, a note with markup, control characters and several scripts, the empty vault) sealed by Faraday and opened by sq, rPGP, the PyCA judge and Faraday, and sealed by rPGP and by the PyCA judge (memory 2^13 to 2^16 KiB) and opened by Faraday, each opened item read by tomllib; each memory step of §3 (2^16 to 2^20 KiB) sealed by Faraday at scale 1, each message equal byte for byte to the PyCA judge's seal of the same random bytes; items at the size limits (a note of 216 and 217 bytes, a passphrase of 193 and 194, a 24-word seed of the longest words); a passphrase in NFD or NFC either way; a wrong passphrase; a 15-word seed and a document of two keys sealed by rPGP, refused by Faraday; the messages sq writes, refused by Faraday and the PyCA judge; two items sealed by rPGP in chunks of 64 bytes (chunk size octet 0), opened by Faraday.

Differences QR vault: sq 1.3.1 writes a SKESK v4 and a SEIPD v1 for a password under either --profile, never the SKESK v6 and SEIPD v2 of RFC 9580, so sq cannot seal a QR vault; rPGP and the PyCA judge seal the other direction, and the area asserts that Faraday and the PyCA judge refuse what sq writes. The PyCA judge's framing is the area's own Python; OpenPGP.js is not run.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 450 cases

Secret handling

Reveal::QrVault

Not stated; the open is the message's.

The typed passphrase is wiped when the open ends, stops or fails; words or a share lent to an offer are wiped as the seed sheet or the form takes them; the item held is wiped on the next open, on leaving the tool, at the idle warning and at a lock.

Limits

A message Faraday does not open, or a stated cost outside the limits, is named before any memory is taken.

A wrong passphrase is told from a changed message and may be tried again.

No key loads with a stick plugged in; the card says so. A key already loaded is not added twice; a vault that is read-only, full or not open takes no note.

Faraday's own calls

none

Seal and open KDBX

SpecificationKeePass KDBX 4 · RFC 9106 · RFC 8439 · 3 morePublishedOwn specificationCodeLibrary: chacha20 0.10Library: aes 0.9Library: cbc 0.26 moreFaraday's code: faraday/faraday-vaultFaraday's own codeCross-checked withNot cross-checked
Action

Writes and reads the KDBX 4 container a file vault is: Argon2id (or, read only, Argon2d) over the SHA-256 of the passphrase's SHA-256, SHA-256 and SHA-512 key steps, ChaCha20 (or, read only, AES-256-CBC) over the body, HMAC-SHA-256 over the header and over every block of the stream, gzip read, and the inner stream's ChaCha20 over protected values. The store's functions listed here make the seal's job: the writes a seal makes from the records changed (a change the seal cannot write refuses it, never dropped), the UUIDs new entries and groups take from the bytes the seal draws (one fresh answer expanded by SHA-256 over a domain string, the answer and a counter: the UUIDs need to differ, not to be secret), and the check that the changes fit the file's size.

Specification

Own specification

KeePass KDBX 4, The KeePass database format, version 4, Convention

RFC 9106, Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications, Informational

RFC 8439, ChaCha20 and Poly1305 for IETF Protocols, Status not checked

RFC 2104, HMAC: Keyed-Hashing for Message Authentication, Status not checked

FIPS 197, Advanced Encryption Standard (AES), Status not checked

RFC 1952, GZIP file format specification version 4.3, Status not checked

Code

Library: chacha20 0.10.2, by the RustCrypto developers.

Library: aes 0.9.3, by the RustCrypto developers.

Library: cbc 0.2.1, by the RustCrypto developers.

Library: base64ct 1.8.3, by the RustCrypto developers.

Library: hmac 0.13.0, by the RustCrypto developers.

Library: quick-xml 0.41.0, by the quick-xml developers.

Library: miniz_oxide 0.8.9 and 0.9.1, by the miniz_oxide developers, a port of Rich Geldreich's miniz.

Library: sha2 0.11.0, by the RustCrypto developers.

Library: argon2 0.6.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: faraday/faraday-vault: The container only, not the meaning of entries: signatures and version (4.0 and 4.1), the header fields (an unknown one refused), the KDF parameters' VariantDictionary with the cost checked against the vault's limits before any memory is asked for, the header's SHA-256 and HMAC, the HMAC block stream (every block's HMAC checked before its bytes are used, a missing or extra block refused), the cipher, gzip read into a buffer sized from its stated length and bounded by the largest vault, and the inner header with its attachments carried. KDBX 3.1, AES-KDF, Twofish, Salsa20 as the inner stream and an empty passphrase are named and refused; a key file or a challenge-response key is not recorded in a KDBX 4 header, so such a file cannot be told from a wrong passphrase (owner, 2026-11-02) and the wrong-passphrase message for a KeePass file says that a file which also needs one cannot be opened here. An Argon2 version missing from the parameters is a damaged file, as KeePass and KeePassXC take it. A file is written as Faraday writes one: 4.0, ChaCha20, Argon2id, no compression, 1 MiB blocks, the plaintext padded with line feeds to the size asked for; the master seed, IV, Argon2 salt and inner stream key are the 140 bytes the caller passes. The XML document (`kdbx::xml`) is read over quick-xml's tokenizer and refused, naming what was found, for a document not well formed, a DOCTYPE, an entity other than XML's five and character references, an XML declaration anywhere but the start, anything after the root other than XML whitespace, comments and processing instructions, nesting past 64, markup inside a text element the model reads, a Meta or Root missing or repeated, and a protected value that is not canonical Base64 (base64ct) of text; a comment or processing instruction is carried, and skipped in text the model reads; an entry or group with two UUIDs or a UUID of other than 16 bytes, a field with two values and the like is marked ambiguous and left as read, not refused; every protected value, those in carried bytes, history and the recycle bin included, is decrypted in document order and, on writing, the ones written are encrypted in document order under the new key from their plaintexts; what the model does not read is carried as the bytes read, and history and the recycle bin (the bin dropped while RecycleBinEnabled is True or absent) are dropped and counted.

Written by Faraday

The KDBX 4 container a file vault is: header, VariantDictionary, HMAC block stream, inner header and gzip framing (faraday-vault::kdbx) · Only the part used is written

Faraday writes only the part of KeePass's format the vault uses, over argon2, chacha20, aes and cbc, hmac, sha2 and miniz_oxide; keepass-rs, which no review Faraday trusts covers, drops the XML elements it does not read and draws a save's randomness itself.

Decision F190

Checked against

tools/vectors/backup

Faraday's own known answers.

tools/vectors/kdbx

Computed by pykeepass 4.1.1 (the distribution's 4.1.1.post1), run by tools/vectors/kdbx/make.py (both ciphers, both Argon2 types, with and without gzip, a header marked 4.1, and a file with a 1.2 MiB attachment, more than one block of the stream); KeePassXC 2.7.12's own KDBX 3.1 file.

faraday/faraday-vault/tests/kdbx.rs::files_pykeepass_wrote_open_with_what_their_headers_state

faraday/faraday-vault/tests/kdbx.rs::the_export_vector_opens_and_is_written_again_byte_for_byte

faraday/faraday-vault/tests/kdbx.rs::a_sealed_file_opens_with_everything_it_was_given

faraday/faraday-vault/tests/kdbx.rs::a_passphrase_opens_in_either_form_of_its_text

faraday/faraday-vault/tests/kdbx.rs::what_is_refused_is_named

faraday/faraday-vault/tests/kdbx.rs::a_file_that_needs_another_passphrase_is_the_wrong_passphrase

faraday/faraday-vault/tests/kdbx.rs::a_cost_outside_the_limits_is_refused_before_any_work

faraday/faraday-vault/tests/kdbx.rs::a_cipher_kdf_or_compression_this_reader_does_not_take_is_named

faraday/faraday-vault/tests/kdbx.rs::a_version_or_field_this_reader_does_not_know_is_refused

faraday/faraday-vault/tests/kdbx.rs::a_file_with_one_byte_changed_or_cut_is_not_opened

faraday/faraday-vault/tests/kdbx.rs::what_does_not_fit_is_not_sealed

faraday/faraday-vault/src/kdbx/tests.rs::a_gzip_member_is_inflated_and_checked

faraday/faraday-vault/src/kdbx/tests.rs::an_inner_header_that_is_not_chacha20_is_refused_by_name

faraday/faraday-vault/src/kdbx/tests.rs::aes_padding_is_taken_off_only_when_it_is_whole

faraday/faraday-vault/tests/kdbx.rs::a_vault_of_several_blocks_is_sealed_and_opened

faraday/faraday-vault/tests/kdbx.rs::a_file_pykeepass_wrote_with_a_megabyte_attachment_opens

faraday/faraday-vault/tests/kdbx_xml.rs::every_file_pykeepass_wrote_opens_to_its_entry

faraday/faraday-vault/tests/kdbx_xml.rs::a_document_not_changed_is_written_as_it_was

faraday/faraday-vault/tests/kdbx_xml.rs::a_document_written_again_is_read_by_pykeepass

faraday/faraday-vault/tests/kdbx_xml.rs::history_and_the_recycle_bin_are_kept_out_of_the_model_and_written_back

faraday/faraday-vault/tests/kdbx_xml.rs::what_a_program_wrote_and_is_not_read_is_kept_in_its_place

faraday/faraday-vault/tests/kdbx_xml.rs::a_new_vault_is_written_and_reads_back

faraday/faraday-vault/tests/kdbx_xml.rs::what_is_refused_is_named

faraday/faraday-vault/tests/kdbx_xml.rs::a_value_a_uuid_or_a_key_that_is_wrong_is_refused

faraday/faraday-vault/tests/file.rs::a_vault_is_made_opened_and_sealed_again_with_its_count_going_up

faraday/faraday-vault/tests/file.rs::a_new_vault_is_one_step_and_the_largest_has_the_length_the_spec_gives

faraday/faraday-vault/tests/file.rs::a_file_a_keepass_app_saved_opens_and_is_sealed_as_faraday_writes_one

faraday/faraday-vault/tests/file.rs::a_seal_pads_to_the_smallest_step_that_holds_it_and_the_vault_shrinks_with_what_it_holds

faraday/faraday-keys/tests/vault.rs::a_vault_sealed_after_a_change_opens_with_it

faraday/faraday-keys/tests/vault.rs::every_edit_moves_the_version_and_a_read_does_not

faraday/faraday-core/tests/all/vault_seal.rs::a_seal_takes_the_answers_the_system_gave

fuzz kdbx_file

fuzz kdbx_body

Cross-check

Own specification, not yet reviewed outside Faraday.

An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.

not cross-checked: Opened from pykeepass's files in both ciphers and both KDFs (read here) and the export's vector written again byte for byte; the file is read by pykeepass, `keepassxc-cli` and keepass-rs, and written by them and read here, in the `vault` cross-check area

Secret handling

none: no secret leaves faraday-keys

The header's and every block's HMAC are compared in constant time (`verify_slice`); Argon2, SHA-2, ChaCha20 and AES-CBC state nothing more.

The composite key, the Argon2 output, the encryption key, the HMAC base and every block key are Secret values wiped on drop; the decrypted body, the inflated body, the document and the attachments are Zeroizing buffers, decrypted and unpadded in place; the Argon2 memory is overwritten before release. Not wiped: the SHA-256 and SHA-512 hashers' state, the ChaCha20 and AES-CBC cipher states and the AES key schedule, the inflater's own state, and the NFC normaliser's buffer of combining marks. The passphrase's first SHA-256 is a Zeroizing value; a seal works out the plaintext length before the buffer is grown, so a refusal as too small leaves no copy.

Limits

Version 4.0 and 4.1 only; KDBX 3.1 and older are named and not opened.

Argon2 version 1.3 with 8 MiB to 1 GiB of memory, 1 to 100 passes and 1 to 64 lanes, no secret key and no associated data; a cost outside is refused before any memory is asked for.

A plaintext of at most 4 MiB; a file too long to hold one is refused before any work, and a gzip body that states more is refused as soon as it is read.

The composite key is the passphrase alone; a key file or a challenge-response key cannot be told from a wrong passphrase (KDBX 4 records neither).

The passphrase arrives in Unicode NFC; the container puts it there.

Faraday's own calls

Only the part of KDBX used is written (F178, F190): the file is written in one shape, and a KeePass app's other choices are read. Conservative, F190.

Write a vault back

SpecificationKeePass KDBX 4 · RFC 8439 · RFC 2104PublishedOwn specificationCodeLibrary: chacha20 0.10Library: hmac 0.13Library: sha2 0.111 moreFaraday's code: faraday/faraday-vaultCross-checked withargon2-cffi (the Argon2 designers' reference code)Others' codeFaraday's second version
Action

Writes an open vault back: applies the changes to its document, stamps the seal count and time, and seals the file at the size the changes fit, with a fresh salt, IVs and inner key from the bytes the caller draws.

Specification

Own specification

KeePass KDBX 4, The KeePass database format, version 4, Convention

RFC 8439, ChaCha20 and Poly1305 for IETF Protocols, Status not checked

RFC 2104, HMAC: Keyed-Hashing for Message Authentication, Status not checked

Code

Library: chacha20 0.10.2, by the RustCrypto developers.

Library: hmac 0.13.0, by the RustCrypto developers.

Library: sha2 0.11.0, by the RustCrypto developers.

Library: argon2 0.6.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: faraday/faraday-vault: The container is `kdbx::seal` (the `vault-kdbx` action); the seal count is one more than the last and the time is the caller's; a change the file cannot write refuses the seal and is never dropped; history and the recycle bin are dropped and counted; a vault under a cost below the first step takes the first step.

Checked against

tools/vectors/vault

Faraday's own known answers.

faraday/faraday-vault/tests/file.rs::a_vault_is_made_opened_and_sealed_again_with_its_count_going_up

faraday/faraday-vault/tests/file.rs::the_clock_is_written_as_utc_across_a_leap_day

faraday/faraday-vault/tests/file.rs::a_seal_pads_to_the_smallest_step_that_holds_it_and_the_vault_shrinks_with_what_it_holds

faraday/faraday-vault/tests/file.rs::a_read_only_vault_refuses_every_change_for_either_reason

faraday/faraday-vault/tests/vectors.rs::the_vault_sealed_through_file_seal_is_at_the_cost_a_seal_writes

faraday/faraday-keys/tests/vault.rs::a_vault_sealed_after_a_change_opens_with_it

faraday/faraday-keys/tests/vault.rs::a_seal_that_fails_leaves_the_vault_open_with_its_changes

no fuzz target: Sealing takes the open vault's own document and the caller's answer; kdbx_file and kdbx_body fuzz the reading

Cross-check

Own specification, not yet reviewed outside Faraday.

An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.

Compared with others' code: argon2-cffi (the Argon2 designers' reference code), for Argon2id, and Python's unicodedata, for the NFC form.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the payload layouts of docs/VAULT.md §7, written in area_vault.py from that document; the KDBX file itself is read by pykeepass, keepassxc-cli and keepass-rs in the area (an outside reader each).

Area vault

Faraday's code faraday_vault's file (file::create, open and seal, the document model and the items of §7), its payload layouts and a passphrase's NFC form with the Unicode version it is made under, file::create_holding (an export), and faraday_crypto::argon2id

Compared with Pykeepass and keepassxc-cli (the distribution's packages) for the vault file, both ways, and keepass-rs for the file format only; docs/VAULT.md §7 written out in area_vault.py, over argon2-cffi and PyCA cryptography's Argon2id (OpenSSL's) (the distribution's packages) and Python's unicodedata, for the payloads.

Checked first: check_primitives runs before anything else: argon2-cffi and PyCA (44 or later over OpenSSL 3.2 or later, or the area stops) against tools/vectors/kdf/'s known answer; pykeepass and keepassxc-cli are the distribution's packages and the area stops and names a missing one, so a run without it fails; their versions are written into the stamp; the area stops where Python's Unicode is newer than unicode-normalization's.

keepass-rs does not count for the primitives and takes no part in the NFD or wrong-passphrase cases of files it did not read; the QR vault and OpenPGP are other areas.

Vectors The Argon2id known answer (tools/vectors/vault-primitives/); the export vector of tools/vectors/backup/, read with a byte changed refused, and with each bit of the version field and bit 44 of the Argon2 iterations changed refused; every file of tools/vectors/vault/, read by Faraday and by both outside readers.

Random cases Argon2id at small random costs and the costs it refuses; payloads made, read and malformed; passphrases in NFC, by case and at random; vaults Faraday writes at small costs with items of every kind of §7 and seals once more, read by pykeepass (every group, entry, field, protected mark and custom data item) and keepassxc-cli (listing and every field), under the passphrase, its NFD form, a wrong one and a changed byte; exports (file::create_holding) of one to eight entries whose Title, Notes and Password hold control characters, read the same way; files pykeepass makes at random (ciphers, KDFs, compression, tags, icons, custom properties, attachments, history, custom data) and keepassxc-cli makes (groups, entries, notes, attachments), opened in Faraday and sealed once more with nothing of the other program's lost; keepass-rs (format only, not counted for the primitives) reads the vaults Faraday writes and seals, with a wrong passphrase, the NFD form and a changed byte refused, and writes files (AES-256 or ChaCha20, Argon2d or Argon2id, compression or not, groups, entries, tags, icons, properties, attachments, custom data) that Faraday opens and seals once more.

Differences Pykeepass strips the characters XML 1.0 cannot hold from a protected value after decrypting it; Faraday keeps a Password's characters as they are put in (and leaves them out of a Title or Notes when it writes). The export loop expects pykeepass's reading of a Password and Faraday's own as put in, and counts the passwords that differ.

Pykeepass opens a file whose major version is neither 3 nor 4 without reading past it, deriving a key or checking a hash; KeePass refuses such a file, and the area counts a file as opened only when pykeepass read a KDBX 4 body (readers.open_kdbx). It also runs the key derivation the header states before it checks the header's SHA-256, so a changed bit in the Argon2 iterations (2^44 passes) holds it for good; KeePass and keepassxc-cli refuse at once, and the area asks pykeepass first with a key given and nothing decrypted.

The vault's passphrase is put in NFC (§3); KeePass apps do not. A vault under an NFC passphrase opens in Faraday under its NFD form and in neither outside reader. The area counts the NFD tries and expects exactly that.

Faraday's reader is stricter than the outside readers' in what it takes of a file (§4, §7.1): a block stream that ends before its empty last block (keepassxc-cli reads it), an XML document with an element after the root (keepassxc-cli), a protected value not canonical Base64, nesting past 64, another root element, a DOCTYPE and another encoding (pykeepass reads these). WIDER names each and the reader that opens it; the area expects exactly that set and counts those opens as known differences.

keepass-rs writes files Faraday refuses (§4): Twofish, AES-KDF and a Salsa20 inner stream (keepass_rs.REFUSED). The area makes one of each, expects Faraday to refuse it and counts the refusals as known differences.

KeePassXC 2.7.10 (and its development branch, November 2026) fails a save of a ChaCha20 file whose plaintext is a multiple of 1024 bytes, "Writing the database failed: Cannot process 0 length data.", and writes nothing: SymmetricCipherStream encrypts each full block of 1024 bytes as it fills and then the empty rest, which SymmetricCipher::process refuses (AES-256's last block is padded). Each save puts a random value of 128 to 1022 hex digits in the file (KPXC_RANDOM_SLUG), so it is chance, compressed or not, about one save in 450 at most. readers.Kpxc makes a command that writes again, once, from the file in a new shell, only on exactly that message and for a ChaCha20 file left byte for byte as it was; the save made again is judged as any other, a second such failure in a row fails the run, and each is counted as a known difference. The prelude shows the condition (kpxc_zero_length): on a file whose plaintext but for the random value is known (its ciphertext's length less the value pykeepass reads), 1500 saves that cannot reach a multiple of 1024 bytes do not fail, of saves that can, one must fail within 20,000, and the same file under AES-256 does not fail; when KeePassXC no longer fails, the run fails and the handling is to go.

keepass-rs decodes a custom data item's value as Base64 when it can, and the program encodes the bytes again (keepass-rs/src/main.rs). A value that is valid Base64 but not canonical (padding or trailing bits the encoder would not write) comes back as another text, so keepass-rs's reading of such a value differs from the file's and from pykeepass's. The area compares custom data as they are, so such a value is a known difference of keepass-rs, not a disagreement about the format.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 26310 cases

Secret handling

none: no secret leaves faraday-keys

Not stated by the argon2, hmac or chacha20 crates.

The plaintext is a Zeroizing buffer, sized before it is grown so a refusal as too small leaves no copy; the keys are Secret values wiped on drop.

Limits

Refuses changes that do not fit the largest size, and names the bytes over and the next size.

Refuses a change the file cannot write, and keeps the vault open with its changes.

A vault held read only (a `faraday.format` other than the one this build writes, or a Meta or custom data that reads ambiguously) refuses every change and every seal (`Error::ReadOnly`); a KeePass app's other settings do not hold it read only.

Nothing is sealed before the session's answer has arrived.

Faraday's own calls

Each seal counts itself and stamps the sealing computer's clock in the file's custom data, so an older copy can be told from a newer one (F159). Neutral, F159.

Reveal a vault secret

SpecificationOwn specificationCodeLibrary: sha2 0.11 (through core/faraday-crypto)Faraday's code: faraday/faraday-keysCross-checked withNot cross-checked
Action

Puts a secret of an open vault's record in the clear for the one reason named: a key's words or passphrase, a kept passphrase, an entry's password, TOTP secret or notes, a note's text.

Specification

Own specification (F70)

Code

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: faraday/faraday-keys: Returns a borrowed text for one named part of one record, or an empty text where the record has no such part; a key's words are parsed again from the record each time and handed back as a value that wipes on drop.

Checked against

not checked against vectors

faraday/faraday-keys/tests/vault.rs::a_secret_leaves_a_record_only_through_a_reveal_that_names_it

faraday/faraday-keys/tests/vault.rs::a_record_shows_its_public_fields_and_only_the_length_of_a_secret_one

faraday/faraday-keys/tests/vault.rs::what_is_read_of_the_words_follows_the_record_it_was_read_from

no fuzz target: Nothing outside the open vault's own records is read

Cross-check

not cross-checked: It computes no value of a standard; it hands back stored text and a parse of stored words

Secret handling

Reveal::VaultEntry

Reveal::SeedQr

Reveal::BackupStick

Reveal::OutboxFile

Not applicable: no secret-dependent comparison is made.

Words come back as a value wiped on drop; a revealed text is borrowed from the record and wiped with it when the vault closes.

Limits

A reason that names another part than the one asked for gives an empty text.

A key record's words are given only for a reason that names the words or the SeedQR.

Faraday's own calls

The list of reasons is closed: a new reason is a new variant, seen in review. Conservative, F70.

Edit a vault's records

SpecificationOwn specificationCodeFaraday's code: faraday/faraday-keysCross-checked withargon2-cffi (the Argon2 designers' reference code)Others' codeFaraday's second version
Action

Adds, changes, copies and makes public the records of an open vault, holding every secret field in a value that wipes on drop.

Specification

Own specification (F97)

Code

Faraday's code: faraday/faraday-keys: Records are typed fields (`docs/VAULT.md` §7); a copy between vaults is the same record bytes; a codex32 set's facts are written without any of its strings. No cryptographic primitive runs here; the functions are found because they hold secret fields and reach functions that do.

Checked against

tools/vectors/vault

Faraday's own known answers.

faraday/faraday-keys/tests/vault.rs::a_key_record_copied_between_vaults_is_the_same_key_there

faraday/faraday-keys/tests/vault.rs::a_secret_field_is_written_as_secret_and_a_public_one_as_public

faraday/faraday-vault/tests/codex32.rs::a_key_record_keeps_the_sets_facts_and_no_string

faraday/faraday-vault/src/tests.rs::records_of_every_type_are_accepted_and_read_back

fuzz kdbx_file

Cross-check

Own specification, not yet reviewed outside Faraday.

An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.

Compared with others' code: argon2-cffi (the Argon2 designers' reference code), for Argon2id, and Python's unicodedata, for the NFC form.

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the payload layouts of docs/VAULT.md §7, written in area_vault.py from that document; the KDBX file itself is read by pykeepass, keepassxc-cli and keepass-rs in the area (an outside reader each).

Area vault

Faraday's code faraday_vault's file (file::create, open and seal, the document model and the items of §7), its payload layouts and a passphrase's NFC form with the Unicode version it is made under, file::create_holding (an export), and faraday_crypto::argon2id

Compared with Pykeepass and keepassxc-cli (the distribution's packages) for the vault file, both ways, and keepass-rs for the file format only; docs/VAULT.md §7 written out in area_vault.py, over argon2-cffi and PyCA cryptography's Argon2id (OpenSSL's) (the distribution's packages) and Python's unicodedata, for the payloads.

Checked first: check_primitives runs before anything else: argon2-cffi and PyCA (44 or later over OpenSSL 3.2 or later, or the area stops) against tools/vectors/kdf/'s known answer; pykeepass and keepassxc-cli are the distribution's packages and the area stops and names a missing one, so a run without it fails; their versions are written into the stamp; the area stops where Python's Unicode is newer than unicode-normalization's.

keepass-rs does not count for the primitives and takes no part in the NFD or wrong-passphrase cases of files it did not read; the QR vault and OpenPGP are other areas.

Vectors The Argon2id known answer (tools/vectors/vault-primitives/); the export vector of tools/vectors/backup/, read with a byte changed refused, and with each bit of the version field and bit 44 of the Argon2 iterations changed refused; every file of tools/vectors/vault/, read by Faraday and by both outside readers.

Random cases Argon2id at small random costs and the costs it refuses; payloads made, read and malformed; passphrases in NFC, by case and at random; vaults Faraday writes at small costs with items of every kind of §7 and seals once more, read by pykeepass (every group, entry, field, protected mark and custom data item) and keepassxc-cli (listing and every field), under the passphrase, its NFD form, a wrong one and a changed byte; exports (file::create_holding) of one to eight entries whose Title, Notes and Password hold control characters, read the same way; files pykeepass makes at random (ciphers, KDFs, compression, tags, icons, custom properties, attachments, history, custom data) and keepassxc-cli makes (groups, entries, notes, attachments), opened in Faraday and sealed once more with nothing of the other program's lost; keepass-rs (format only, not counted for the primitives) reads the vaults Faraday writes and seals, with a wrong passphrase, the NFD form and a changed byte refused, and writes files (AES-256 or ChaCha20, Argon2d or Argon2id, compression or not, groups, entries, tags, icons, properties, attachments, custom data) that Faraday opens and seals once more.

Differences Pykeepass strips the characters XML 1.0 cannot hold from a protected value after decrypting it; Faraday keeps a Password's characters as they are put in (and leaves them out of a Title or Notes when it writes). The export loop expects pykeepass's reading of a Password and Faraday's own as put in, and counts the passwords that differ.

Pykeepass opens a file whose major version is neither 3 nor 4 without reading past it, deriving a key or checking a hash; KeePass refuses such a file, and the area counts a file as opened only when pykeepass read a KDBX 4 body (readers.open_kdbx). It also runs the key derivation the header states before it checks the header's SHA-256, so a changed bit in the Argon2 iterations (2^44 passes) holds it for good; KeePass and keepassxc-cli refuse at once, and the area asks pykeepass first with a key given and nothing decrypted.

The vault's passphrase is put in NFC (§3); KeePass apps do not. A vault under an NFC passphrase opens in Faraday under its NFD form and in neither outside reader. The area counts the NFD tries and expects exactly that.

Faraday's reader is stricter than the outside readers' in what it takes of a file (§4, §7.1): a block stream that ends before its empty last block (keepassxc-cli reads it), an XML document with an element after the root (keepassxc-cli), a protected value not canonical Base64, nesting past 64, another root element, a DOCTYPE and another encoding (pykeepass reads these). WIDER names each and the reader that opens it; the area expects exactly that set and counts those opens as known differences.

keepass-rs writes files Faraday refuses (§4): Twofish, AES-KDF and a Salsa20 inner stream (keepass_rs.REFUSED). The area makes one of each, expects Faraday to refuse it and counts the refusals as known differences.

KeePassXC 2.7.10 (and its development branch, November 2026) fails a save of a ChaCha20 file whose plaintext is a multiple of 1024 bytes, "Writing the database failed: Cannot process 0 length data.", and writes nothing: SymmetricCipherStream encrypts each full block of 1024 bytes as it fills and then the empty rest, which SymmetricCipher::process refuses (AES-256's last block is padded). Each save puts a random value of 128 to 1022 hex digits in the file (KPXC_RANDOM_SLUG), so it is chance, compressed or not, about one save in 450 at most. readers.Kpxc makes a command that writes again, once, from the file in a new shell, only on exactly that message and for a ChaCha20 file left byte for byte as it was; the save made again is judged as any other, a second such failure in a row fails the run, and each is counted as a known difference. The prelude shows the condition (kpxc_zero_length): on a file whose plaintext but for the random value is known (its ciphertext's length less the value pykeepass reads), 1500 saves that cannot reach a multiple of 1024 bytes do not fail, of saves that can, one must fail within 20,000, and the same file under AES-256 does not fail; when KeePassXC no longer fails, the run fails and the handling is to go.

keepass-rs decodes a custom data item's value as Base64 when it can, and the program encodes the bytes again (keepass-rs/src/main.rs). A value that is valid Base64 but not canonical (padding or trailing bits the encoder would not write) comes back as another text, so keepass-rs's reading of such a value differs from the file's and from pykeepass's. The area compares custom data as they are, so such a value is a known difference of keepass-rs, not a disagreement about the format.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 26310 cases

Secret handling

none: no secret leaves faraday-keys

Not applicable: no secret-dependent comparison is made.

A copied-out record is a Held value wiped on drop; a record removed or replaced is wiped; every record of a vault is wiped when it closes.

Limits

A record's size counts against the file; a vault whose records no longer fit the largest size cannot be sealed.

A codex32 set's record holds the threshold, identifier, length and each string's state, and no string.

Faraday's own calls

Faraday's own record layouts (`docs/VAULT.md` §7); the payload layouts are read by a second implementation Faraday's authors wrote from that document (`area_vault.py`) and the items by pykeepass, `keepassxc-cli` and keepass-rs. Novel, F97.

Load a key from a vault

SpecificationBIP 39 · BIP 32PublishedCodeLibrary: sha2 0.11 (through core/faraday-crypto)Library: unicode-normalization 0.1 (through core/faraday-bip)Faraday's code: faraday/faraday-keysCross-checked withpython-mnemonicOthers' code
Action

Loads a key kept in an open vault into the session: its words (BIP 39) and passphrase to the seed and the master key's fingerprint (BIP 32), or its master seed, or its codex32 set.

Specification

BIP 39, Mnemonic code for generating deterministic keys, Deployed

BIP 32, Hierarchical Deterministic Wallets, Deployed

Code

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Library: unicode-normalization 0.1.25, by the unicode-rs developers, through core/faraday-bip.

Faraday's code: faraday/faraday-keys: Reads a record's words or seed from the open vault and hands them to the session's key functions; the vault record only decides which key is loaded and with which passphrase. A key loaded from a master seed, as a codex32 or SLIP-39 key is, is known to a vault by the id of a key record made of its seed.

Checked against

tools/vectors/bip39

Published, by Trezor (SatoshiLabs), python-mnemonic's vectors; bip32JP's Japanese vectors.

tools/vectors/bip32

Published, by BIP 32's authors (bitcoin/bips).

tools/vectors/vault

Faraday's own known answers.

faraday/faraday-keys/tests/vault.rs::a_key_in_a_vault_loads_as_the_key_the_bips_publish

faraday/faraday-vault/tests/codex32.rs::the_codex32_vector_opens_with_its_key_set_and_share

fuzz kdbx_file

Cross-check

Compared with others' code: python-mnemonic, by Trezor (SatoshiLabs), and bip39_slip39, by the btclib developers (a second reader: wordlists, entropy, indices, checksums and the seed in the ten languages).

Area bip39

Faraday's code faraday_bip::bip39

Compared with python-mnemonic (bip39/); bip39_slip39 (bip39-slip39/) answering every operation beside it.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; python-mnemonic's own to_hd_master_key is checked against the seed's master key, as a second BIP-32 master; its wheel is hashed too, and a published vector's answer is required of bip39_slip39 as well.

Vectors The ten wordlists; every vector of tools/vectors/bip39/vectors.json in Faraday's languages; the Japanese vectors with non-ASCII passphrases.

Random cases Entropy to words and back in every language and length; seeds under random ASCII passphrases; a changed word, an unknown word, a word too many or too few; every valid last word.

Differences Both read a BIP-39 sentence in NFKD, so composed words and the Japanese vectors as published parse on both sides (owner, 2026-10-23).

A passphrase typed in Faraday is printable ASCII, at most 256 bytes; python-mnemonic takes any text. Faraday's vector tests and start-up self-test give a non-ASCII passphrase as its NFKD bytes, and the area checks that a typed one, or one past 256 bytes, is still refused.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Secret handling

none: no secret leaves faraday-keys

Not applicable here; the seed and master key functions it calls state their own.

The words are a Held value wiped on drop; the seed and keys it loads are the session's, wiped as the session's keys are.

Limits

A key the session's key store refuses is left out of the loaded list.

A passphrase stored beside a key's words is used with them; a passphrase kept alone applies only to the key it was kept for.

Faraday's own calls

Which passphrase goes with which words is decided by the vault's record, not by a guess; a mismatched fingerprint is not loaded. Conservative.

no decision

Write a KeePass database

SpecificationKeePass KDBX 4 · RFC 9106 · RFC 8439PublishedOwn specificationCodeLibrary: chacha20 0.10Library: hmac 0.13Library: sha2 0.112 moreFaraday's code: faraday/faraday-vaultCross-checked withpykeepassOthers' code
Action

Writes a KeePass database of one entry under a passphrase, as a one-entry vault: the same KDBX 4.0 file the vault is (Argon2id, SHA-256 and SHA-512 key steps, ChaCha20 over the body, HMAC-SHA-256 block authentication), sealed at the smallest size that holds it.

Specification

Own specification

KeePass KDBX 4, The KeePass database format, version 4, Convention

RFC 9106, Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications, Informational

RFC 8439, ChaCha20 and Poly1305 for IETF Protocols, Status not checked

Code

Library: chacha20 0.10.2, by the RustCrypto developers.

Library: hmac 0.13.0, by the RustCrypto developers.

Library: sha2 0.11.0, by the RustCrypto developers.

Library: base64ct 1.8.3, by the RustCrypto developers.

Library: argon2 0.6.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: faraday/faraday-vault: A KeePass export is a vault of one entry (`docs/VAULT.md` section 8): the vault's own container and document model, one group and one entry holding the secret, sealed by the vault's `kdbx::seal` at the smallest of the vault sizes that holds it, under the passphrase put in NFC. The vault id, the seal's salt, seed, IV and inner key, and the entry's UUIDs are three draws of the session's randomness, each with its label (`vault id`, `vault seal`, `vault entries`), and nothing is made until the system has answered.

Checked against

tools/vectors/backup

Faraday's own known answers.

tools/vectors/kdf

Published, by RFC 7914 §12, for scrypt; the Argon2id answer computed by argon2-cffi and PyCA cryptography, which agree.

faraday/faraday-vault/tests/kdbx.rs::the_export_vector_opens_and_is_written_again_byte_for_byte

faraday/faraday-vault/tests/kdbx.rs::a_file_with_one_byte_changed_or_cut_is_not_opened

faraday/faraday-vault/tests/kdbx.rs::a_version_or_field_this_reader_does_not_know_is_refused

faraday/faraday-vault/tests/kdbx.rs::a_cost_outside_the_limits_is_refused_before_any_work

faraday/faraday-vault/tests/kdbx.rs::a_file_that_needs_another_passphrase_is_the_wrong_passphrase

faraday/faraday-core/tests/all/kdbx.rs::an_entry_exported_for_keepass_is_sealed_under_its_passphrase

fuzz kdbx_file

fuzz kdbx_body

Cross-check

Own specification, not yet reviewed outside Faraday.

An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.

Compared with others' code: pykeepass, by the libkeepass project, and KeePassXC's keepassxc-cli (the distribution's packages), and argon2-cffi and PyCA's cryptography over OpenSSL for the Argon2id.

Area vault

Faraday's code faraday_vault's file (file::create, open and seal, the document model and the items of §7), its payload layouts and a passphrase's NFC form with the Unicode version it is made under, file::create_holding (an export), and faraday_crypto::argon2id

Compared with Pykeepass and keepassxc-cli (the distribution's packages) for the vault file, both ways, and keepass-rs for the file format only; docs/VAULT.md §7 written out in area_vault.py, over argon2-cffi and PyCA cryptography's Argon2id (OpenSSL's) (the distribution's packages) and Python's unicodedata, for the payloads.

Checked first: check_primitives runs before anything else: argon2-cffi and PyCA (44 or later over OpenSSL 3.2 or later, or the area stops) against tools/vectors/kdf/'s known answer; pykeepass and keepassxc-cli are the distribution's packages and the area stops and names a missing one, so a run without it fails; their versions are written into the stamp; the area stops where Python's Unicode is newer than unicode-normalization's.

keepass-rs does not count for the primitives and takes no part in the NFD or wrong-passphrase cases of files it did not read; the QR vault and OpenPGP are other areas.

Vectors The Argon2id known answer (tools/vectors/vault-primitives/); the export vector of tools/vectors/backup/, read with a byte changed refused, and with each bit of the version field and bit 44 of the Argon2 iterations changed refused; every file of tools/vectors/vault/, read by Faraday and by both outside readers.

Random cases Argon2id at small random costs and the costs it refuses; payloads made, read and malformed; passphrases in NFC, by case and at random; vaults Faraday writes at small costs with items of every kind of §7 and seals once more, read by pykeepass (every group, entry, field, protected mark and custom data item) and keepassxc-cli (listing and every field), under the passphrase, its NFD form, a wrong one and a changed byte; exports (file::create_holding) of one to eight entries whose Title, Notes and Password hold control characters, read the same way; files pykeepass makes at random (ciphers, KDFs, compression, tags, icons, custom properties, attachments, history, custom data) and keepassxc-cli makes (groups, entries, notes, attachments), opened in Faraday and sealed once more with nothing of the other program's lost; keepass-rs (format only, not counted for the primitives) reads the vaults Faraday writes and seals, with a wrong passphrase, the NFD form and a changed byte refused, and writes files (AES-256 or ChaCha20, Argon2d or Argon2id, compression or not, groups, entries, tags, icons, properties, attachments, custom data) that Faraday opens and seals once more.

Differences Pykeepass strips the characters XML 1.0 cannot hold from a protected value after decrypting it; Faraday keeps a Password's characters as they are put in (and leaves them out of a Title or Notes when it writes). The export loop expects pykeepass's reading of a Password and Faraday's own as put in, and counts the passwords that differ.

Pykeepass opens a file whose major version is neither 3 nor 4 without reading past it, deriving a key or checking a hash; KeePass refuses such a file, and the area counts a file as opened only when pykeepass read a KDBX 4 body (readers.open_kdbx). It also runs the key derivation the header states before it checks the header's SHA-256, so a changed bit in the Argon2 iterations (2^44 passes) holds it for good; KeePass and keepassxc-cli refuse at once, and the area asks pykeepass first with a key given and nothing decrypted.

The vault's passphrase is put in NFC (§3); KeePass apps do not. A vault under an NFC passphrase opens in Faraday under its NFD form and in neither outside reader. The area counts the NFD tries and expects exactly that.

Faraday's reader is stricter than the outside readers' in what it takes of a file (§4, §7.1): a block stream that ends before its empty last block (keepassxc-cli reads it), an XML document with an element after the root (keepassxc-cli), a protected value not canonical Base64, nesting past 64, another root element, a DOCTYPE and another encoding (pykeepass reads these). WIDER names each and the reader that opens it; the area expects exactly that set and counts those opens as known differences.

keepass-rs writes files Faraday refuses (§4): Twofish, AES-KDF and a Salsa20 inner stream (keepass_rs.REFUSED). The area makes one of each, expects Faraday to refuse it and counts the refusals as known differences.

KeePassXC 2.7.10 (and its development branch, November 2026) fails a save of a ChaCha20 file whose plaintext is a multiple of 1024 bytes, "Writing the database failed: Cannot process 0 length data.", and writes nothing: SymmetricCipherStream encrypts each full block of 1024 bytes as it fills and then the empty rest, which SymmetricCipher::process refuses (AES-256's last block is padded). Each save puts a random value of 128 to 1022 hex digits in the file (KPXC_RANDOM_SLUG), so it is chance, compressed or not, about one save in 450 at most. readers.Kpxc makes a command that writes again, once, from the file in a new shell, only on exactly that message and for a ChaCha20 file left byte for byte as it was; the save made again is judged as any other, a second such failure in a row fails the run, and each is counted as a known difference. The prelude shows the condition (kpxc_zero_length): on a file whose plaintext but for the random value is known (its ciphertext's length less the value pykeepass reads), 1500 saves that cannot reach a multiple of 1024 bytes do not fail, of saves that can, one must fail within 20,000, and the same file under AES-256 does not fail; when KeePassXC no longer fails, the run fails and the handling is to go.

keepass-rs decodes a custom data item's value as Base64 when it can, and the program encodes the bytes again (keepass-rs/src/main.rs). A value that is valid Base64 but not canonical (padding or trailing bits the encoder would not write) comes back as another text, so keepass-rs's reading of such a value differs from the file's and from pykeepass's. The area compares custom data as they are, so such a value is a known difference of keepass-rs, not a disagreement about the format.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 26310 cases

Secret handling

none: no secret leaves faraday-keys

The header's and every block's HMAC are compared in constant time (`verify_slice`); Argon2, SHA-2 and ChaCha20 state nothing more.

The Argon2id output, the composite key, the encryption key and the HMAC base are Secret values wiped on drop; the document is built in a zeroizing buffer and encrypted in place; the Argon2id memory is overwritten before release.

Limits

One entry, as large as the largest vault size (4 MiB of plain text) holds with the document around it; a larger one is refused as not fitting and no file is made. The entry comes from an open vault, whose file is no larger. KDBX states no limit of its own.

The file is a vault of the smallest size that holds it.

The export is as safe as its passphrase.

Faraday's own calls

Nostr entries are never exported (F27). Neutral, F27.

The file's seed, IV, salt, inner key and UUIDs are taken from the session's randomness, an answer for every 32 bytes. Neutral, F154.

Compute a TOTP code

SpecificationRFC 6238 · RFC 4226 · otpauth Key URI FormatPublishedCodeLibrary: hmac 0.13Library: sha1 0.11Library: sha2 0.111 moreFaraday's code: faraday/faraday-vaultFaraday's own codeCross-checked withpyotpOthers' code
Action

Computes a TOTP code from an entry's secret at a Unix time: HMAC-SHA1, SHA-256 or SHA-512 over the time step, then dynamic truncation.

Specification

RFC 6238, TOTP: Time-Based One-Time Password Algorithm, Informational

RFC 4226, HOTP: An HMAC-Based One-Time Password Algorithm, Informational

otpauth Key URI Format, Key URI Format of Google Authenticator, Convention

Code

Library: hmac 0.13.0, by the RustCrypto developers.

Library: sha1 0.11.0, by the RustCrypto developers.

Library: sha2 0.11.0, by the RustCrypto developers.

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: faraday/faraday-vault: Reads an otpauth://totp URI or a bare Base32 key, and from an entry's fields KeePass 2's TimeOtp-* fields and older KeePassXC's TOTP Seed and TOTP Settings (docs/TOTP.md section 4.1); SHA1 by default as RFC 6238 does, SHA256 and SHA512 on request; the clock is the person's, checked or set by hand (docs/TOTP.md §1).

Written by Faraday

TOTP code derivation (faraday-vault::totp) · Only the part used is written

Faraday writes only the few lines RFC 6238 needs, over standard HMAC.

Decision F178

Checked against

not checked against vectors

faraday/faraday-vault/tests/totp.rs::rfc_6238_appendix_b_vectors

faraday/faraday-vault/tests/totp.rs::rfc_4226_appendix_d_vectors

faraday/faraday-vault/tests/totp.rs::the_key_uri_example_and_its_typed_form_agree

faraday/faraday-vault/tests/totp.rs::unreadable_and_hotp_values_are_told_apart

faraday/faraday-vault/tests/totp.rs::a_parameter_written_twice_is_not_read

faraday/faraday-vault/tests/totp.rs::every_form_an_entry_holds_gives_rfc_6238_codes

faraday/faraday-vault/tests/totp.rs::keepass_two_algorithm_and_period_fields

faraday/faraday-vault/tests/totp.rs::the_first_form_present_decides

faraday/faraday-vault/tests/totp.rs::hotp_steam_and_malformed_forms_are_not_read

faraday/faraday-core/tests/all/totp.rs::the_code_shown_changes_when_the_tick_crosses_the_period

fuzz vault_entries

Cross-check

Compared with others' code: pyotp, by the pyotp developers, which judges the code, the seconds left, the period and the reading of an otpauth URI's key, digits, period and hash; Faraday's stricter and wider readings of a URI are stated differences of the area.

Area totp

Faraday's code faraday_vault::totp (parse, Totp::code, left and period)

Compared with Pyotp 2.9 (python3-pyotp): TOTP.at and generate_otp for the code, parse_uri for a URI's key, digits, period and hash.

Checked first: RFC 6238 Appendix B's codes are required of pyotp as well as of Faraday, and each pinned URI's answer from each side is stated in the area.

from_fields (KeePass 2's TimeOtp-* fields and KeePassXC's TOTP Seed and TOTP Settings) and normalise (what the entry form writes into field 6), which no pyotp reader covers: the crate's tests hold them; grouped, the display grouping of a code.

Vectors RFC 6238 Appendix B: the codes of the SHA-1, SHA-256 and SHA-512 seeds at its six times, 8 digits.

Random cases Random keys of 1 to 300 bytes in otpauth://totp/ URIs and, from 10 bytes, as bare keys, digits 6 to 8, periods 1 to 3600 (and past it), the three hashes, times from 0 to 2^64 - 1 with the edges of each period, the code, the seconds left and the period; the URIs written in other spellings and damaged (a character changed, added, removed, a cut, a pair dropped or doubled), read by both; the pinned URIs.

Differences Where Faraday reads and pyotp refuses: a scheme, type or algorithm in other than lower (upper for the algorithm) case; a parameter name pyotp does not know, a counter on a TOTP, a label issuer that the issuer parameter does not repeat; Base32 with spaces or hyphens (a bare key) or = in the wrong place, or a length that Base32 cannot have. The area asks both about the URI with that difference taken out and requires the same answer, and Faraday's answer to the original to be that answer.

Where Faraday refuses and pyotp reads: a period over 3600 seconds (Faraday's rule), a parameter of the key URI format written twice or in a case other than lower or with a percent-escape in its name (pyotp keeps the last, or reads the decoded name), a parameter name with a tab or line break in it (pyotp strips them), a pair with no = or no value, a type with no / before its ?, a value written percent-encoded (Faraday reads it as it is), a fragment after the last value, a bare key of fewer than 16 characters, and encoder=steam, which pyotp reads as a Steam code of five characters and Faraday refuses, making no such code. The area asks both about the URI with a period, repeated parameter, name, pair or type difference taken out and requires the same answer; the percent escapes, the fragment, the short key and Steam's code are pinned one URI at a time.

Where both read and the keys differ: an escaped & or = in a value, such as an issuer's a%26secret%3DB. pyotp unquotes the whole URI first and reads a second secret from it; Faraday reads the value as written, one issuer and the key before it, which is the reading the URI's writer meant. Pinned one URI at a time, where the pin judges the kind and not the key.

HOTP: pyotp reads otpauth://hotp/ as a HOTP; Faraday refuses it, naming it HOTP (NotTotp::Hotp) and reading no code.

Times: pyotp works from a datetime, which ends in year 9999; past it the area asks generate_otp for the counter, time // period.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 33000 cases

Secret handling

Reveal::VaultEntry

Not stated by the hmac or sha1 crates.

The decoded secret is held in a zeroizing buffer; the HMAC output is a plain buffer dropped at the end of the call, and hmac's key block is freed unwiped, until the next lock (ESTABLISHED §4.8, §6.7).

Limits

TOTP only: an otpauth://hotp URI is told apart and not computed.

Digits 6 to 8, period 1 to 3600 seconds; a parameter outside that is unreadable.

A bare Base32 key is read as SHA1, 6 digits, 30 seconds; a short key is refused.

No code is shown while the clock is not checked or set.

Faraday's own calls

A manual clock with a fixed-offset time zone, since a device with no network has no other time (F7). Neutral, F7.

A parameter of the otpauth key URI written twice, in a case other than lower, or with a percent-escape in its name, or a parameter name with a space or control character in it, is refused; pyotp keeps the last of a repeated parameter and reads a decoded name. Conservative.

no decision

GPG and Secure Boot

9 actions · 1 own specification · 2 with Faraday's own code · 9 not cross-checked

Make a GPG key

SpecificationRFC 4880 · RFC 9580 · RFC 8032PublishedCodeLibrary: ed25519-dalek 3.0Library: sha1 0.11Library: sha2 0.111 moreFaraday's code: faraday/faraday-pgpFaraday's own codeCross-checked withNot cross-checked
Action

Makes an OpenPGP v4 key from two fresh Ed25519 seeds, a certifying primary key and a signing subkey, with its public certificate and a kept revocation certificate.

Specification

RFC 4880, OpenPGP Message Format, obsoleted by RFC 9580, Proposed Standard

RFC 9580, OpenPGP, Proposed Standard

RFC 8032, Edwards-Curve Digital Signature Algorithm (EdDSA), Informational

Code

Library: ed25519-dalek 3.0.0, by the dalek-cryptography developers.

Library: sha1 0.11.0, by the RustCrypto developers.

Library: sha2 0.11.0, by the RustCrypto developers.

Library: base64ct 1.8.3, by the RustCrypto developers.

Faraday's code: faraday/faraday-pgp: The armoured secret key a KDBX vault's GPG entry holds is the key's own packets (`Key::secret_key`) in ASCII armour, and it is read back only when writing the key it names gives the same bytes. Version-4 packets for one key shape: EdDSALegacy Ed25519 for the primary (certify) and the subkey (sign), SHA-1 fingerprints, self-signatures over SHA-512, the subkey's back signature, and a revocation certificate kept in the vault record as GnuPG 2.1 and later keep one; every signature is deterministic.

Written by Faraday

OpenPGP v4 packets for one key shape, the armour's CRC-24, and the paperkey format (faraday-pgp) · Only the part used is written

Faraday writes only the packets of its one key shape, over Ed25519 from dalek and SHA-1/SHA-2 from RustCrypto, each judged by GnuPG and paperkey; the armour's base64 is the base64ct crate's.

Decision F178

Checked against

tools/vectors/paperkey

Computed by paperkey 1.6 and GnuPG 2.4.8, run by the folder's make.sh.

faraday/faraday-pgp/tests/gnupg.rs::gnupg_takes_the_certificate_signatures_and_revocation

faraday/faraday-pgp/tests/gnupg.rs::gnupg_sees_a_key_expire_and_be_renewed

faraday/faraday-pgp/tests/sequoia.rs::sequoia_reads_the_certificate

faraday/faraday-pgp/tests/sequoia.rs::sequoia_takes_the_revocation_certificate

faraday/faraday-pgp/tests/sequoia.rs::sequoia_sees_a_key_expire_and_be_renewed

faraday/faraday-keys/tests/vault.rs::a_restored_key_signs_renews_and_revokes_as_makes_does

faraday/faraday-pgp/tests/gnupg.rs::gnupg_imports_the_armoured_secret_key_and_it_reads_back

faraday/faraday-pgp/tests/secret.rs::a_key_reads_back_as_written

faraday/faraday-pgp/tests/secret.rs::what_is_not_exactly_the_key_faraday_writes_is_not_read

faraday/faraday-keys/tests/gpg_entry.rs::a_record_becomes_an_entry_and_the_entry_the_same_record

faraday/faraday-keys/tests/gpg_entry.rs::an_entry_that_is_not_faradays_own_key_makes_no_record

fuzz pgp_armor

fuzz pgp_secret

Cross-check

not cross-checked: Judged by real gnupg and paperkey in faraday/faraday-pgp/tests/gnupg.rs, not by an F79 area; those tests fail where the tools are missing

Source

0.2.0 · faraday/faraday-keys/src/gpg.rs · create

0.2.0 · faraday/faraday-pgp/src/lib.rs · Key::certificate

0.2.0 · faraday/faraday-pgp/src/secret.rs · armor_secret

0.2.0 · faraday/faraday-pgp/src/secret.rs · read_secret_at

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

Not stated by the ed25519-dalek crate.

The key's seeds are wiped when it drops; the kept revocation certificate is held in a zeroizing buffer while the record is made.

Limits

One key shape only: an Ed25519 primary that certifies and an Ed25519 subkey that signs.

A key's expiry is counted from its creation; 0 means never.

Faraday's own calls

Signing waits until the backup flow has written every place the key's plan gives it, two or more; GnuPG has no such gate. Conservative, F32.

The primary key's flags are certify only and the signature hash is SHA-512, as GnuPG 2.4 chooses for Ed25519. Neutral, F32.

Sign with the GPG key

SpecificationRFC 4880 · RFC 9580 · RFC 8032PublishedCodeLibrary: ed25519-dalek 3.0Library: sha2 0.11Library: base64ct 1.8Faraday's code: faraday/faraday-pgpCross-checked withNot cross-checked
Action

Signs data with the GPG key's signing subkey: an Ed25519 detached signature over the SHA-512 of the data, armoured.

Specification

RFC 4880, OpenPGP Message Format, obsoleted by RFC 9580, Proposed Standard

RFC 9580, OpenPGP, Proposed Standard

RFC 8032, Edwards-Curve Digital Signature Algorithm (EdDSA), Informational

Code

Library: ed25519-dalek 3.0.0, by the dalek-cryptography developers.

Library: sha2 0.11.0, by the RustCrypto developers.

Library: base64ct 1.8.3, by the RustCrypto developers.

Faraday's code: faraday/faraday-pgp: A version-4 binary signature (type 0x00) by the signing subkey; the digest is signed, not the data, as OpenPGP's EdDSA does; output is `{file}.asc`.

Checked against

not checked against vectors

faraday/faraday-pgp/tests/gnupg.rs::gnupg_takes_the_certificate_signatures_and_revocation

faraday/faraday-pgp/tests/gnupg.rs::a_signature_whose_r_or_s_starts_with_a_zero_byte_verifies

faraday/faraday-pgp/tests/sequoia.rs::sequoia_verifies_the_signatures_and_refuses_other_data

faraday/faraday-pgp/tests/verify_refusals.rs::a_signature_made_here_of_faradays_shape_verifies

no fuzz target: Signing takes the signed bytes and the key; pgp_verify fuzzes the reading of a signature

Cross-check

not cross-checked: Judged by real gnupg in faraday/faraday-pgp/tests/gnupg.rs, not by an F79 area; the test fails where gnupg is missing

Source

0.2.0 · faraday/faraday-pgp/src/lib.rs · Key::sign

0.2.0 · faraday/faraday-keys/src/vault/reveals.rs · OpenVaults::gpg_sign_armored

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

Not stated by the ed25519-dalek crate.

The signing seed is wiped when the key value drops.

Limits

Binary signatures only; no text mode, no clear-signing.

An expired or revoked key, or one made after the clock, is not signed with.

An existing `.asc` of the same name is not overwritten.

Faraday's own calls

Signing takes a hold (F63) and shows the files' names, sizes and SHA-256 first. Conservative, F32.

Make a revocation certificate

SpecificationRFC 4880 · RFC 9580PublishedCodeLibrary: ed25519-dalek 3.0Library: sha1 0.11Library: sha2 0.111 moreFaraday's code: faraday/faraday-pgpCross-checked withNot cross-checked
Action

Makes a revocation certificate for the GPG key and writes it as the `.rev` file GnuPG writes.

Specification

RFC 4880, OpenPGP Message Format, obsoleted by RFC 9580, Proposed Standard

RFC 9580, OpenPGP, Proposed Standard

Code

Library: ed25519-dalek 3.0.0, by the dalek-cryptography developers.

Library: sha1 0.11.0, by the RustCrypto developers.

Library: sha2 0.11.0, by the RustCrypto developers.

Library: base64ct 1.8.3, by the RustCrypto developers.

Faraday's code: faraday/faraday-pgp: A key-revocation signature (type 0x20) by the primary key over SHA-512 with GnuPG's reason codes; the file is laid out as `openpgp-revocs.d/<FPR>.rev` with a colon before the first dashes so `gpg --import` refuses it until the colon is removed.

Checked against

not checked against vectors

faraday/faraday-pgp/tests/gnupg.rs::gnupg_refuses_a_rev_file_until_its_colon_is_removed

faraday/faraday-pgp/tests/gnupg.rs::the_rev_file_lists_the_key_as_gnupg_does

faraday/faraday-keys/tests/vault.rs::a_kept_revocation_leaves_only_as_a_rev_file_asked_for_by_name

no fuzz target: Revocation takes the key's own record and a reason from a menu

Cross-check

not cross-checked: Judged by real gnupg in faraday/faraday-pgp/tests/gnupg.rs, not by an F79 area; the tests fail where gnupg is missing

Source

0.2.0 · faraday/faraday-pgp/src/lib.rs · Key::revocation

0.2.0 · faraday/faraday-pgp/src/lib.rs · Key::revocation_file

github.com/bitcoinpasada/faraday

Secret handling

Reveal::OutboxFile

Not stated by the ed25519-dalek crate.

The primary seed is wiped when the key value drops; a kept revocation is a record field of the open vault, wiped when it closes.

Limits

Reasons are GnuPG's menu: none, compromised, superseded, no longer used.

The kept revocation is not replaced when a new one is made.

The file is a secret file: it goes through the secret sheet, with no code or picture.

Faraday's own calls

The revocation is kept in the key's vault record and nothing is written to the Outbox at key generation. Neutral, F32.

Write the GPG key as paperkey

SpecificationpaperkeyPublishedCodeLibrary: ed25519-dalek 3.0Library: sha1 0.11Library: sha2 0.111 moreFaraday's code: faraday/faraday-pgpCross-checked withNot cross-checked
Action

Writes the GPG key's secret parts in paperkey's text form, for a person to copy onto paper.

Specification

paperkey, paperkey's text and raw forms of an OpenPGP secret key, Convention

Code

Library: ed25519-dalek 3.0.0, by the dalek-cryptography developers.

Library: sha1 0.11.0, by the RustCrypto developers.

Library: sha2 0.11.0, by the RustCrypto developers.

Library: base16ct 1.0.0, by the RustCrypto developers.

Faraday's code: faraday/faraday-pgp: The secret MPIs of the primary and the subkey, each behind its 20-byte fingerprint, in lines with a CRC-24, computed only to be shown and wiped after; the unprotected transferable secret key the tests give to paperkey and Faraday does not put in the Outbox.

Checked against

tools/vectors/paperkey

Computed by paperkey 1.6 and GnuPG 2.4.8, run by the folder's make.sh.

faraday/faraday-pgp/tests/gnupg.rs::paperkey_prints_the_same_lines

faraday/faraday-pgp/tests/paperkey.rs::the_lines_faraday_shows_read_back_to_the_key

faraday/faraday-pgp/tests/paperkey.rs::paperkeys_text_and_raw_output_read_as_faradays_lines

fuzz pgp_paperkey

Cross-check

not cross-checked: Judged by real paperkey 1.6 in faraday/faraday-pgp/tests/gnupg.rs, not by an F79 area; the tests fail where paperkey is missing

Secret handling

Reveal::GpgPaperkey

The armour's and paperkey's CRC-24 runs without a branch on the data; the code states no other timing.

The paperkey text, the secret key packets and the seeds are Zeroizing values wiped on drop; the paperkey is computed only while it is held to show. Copies other crates make while encoding are freed unwiped, until the next lock (ESTABLISHED §4.8).

Limits

Faraday's key shape only: a key of another algorithm, with no subkey or protected by a passphrase is not written.

Faraday's own calls

The paperkey is computed only while it is held to show, and wiped after. Conservative, F32.

Restore a GPG key

Specificationpaperkey · RFC 4880 · RFC 9580 · 1 morePublishedCodeLibrary: ed25519-dalek 3.0Library: sha1 0.11Library: sha2 0.112 moreFaraday's code: faraday/faraday-pgpCross-checked withNot cross-checked
Action

Restores a GPG key from its paperkey lines, typed or scanned as paperkey's text or raw form, and its public certificate: checks every line's CRC, rebuilds the key from the seeds, and makes every signature of the certificate again to compare.

Specification

paperkey, paperkey's text and raw forms of an OpenPGP secret key, Convention

RFC 4880, OpenPGP Message Format, obsoleted by RFC 9580, Proposed Standard

RFC 9580, OpenPGP, Proposed Standard

RFC 8032, Edwards-Curve Digital Signature Algorithm (EdDSA), Informational

Code

Library: ed25519-dalek 3.0.0, by the dalek-cryptography developers.

Library: sha1 0.11.0, by the RustCrypto developers.

Library: sha2 0.11.0, by the RustCrypto developers.

Library: base64ct 1.8.3, by the RustCrypto developers.

Library: base16ct 1.0.0, by the RustCrypto developers.

Faraday's code: faraday/faraday-pgp: The key is rebuilt only if the seeds make the public key and every self-signature of the certificate comes out again byte for byte; a certificate merged or renewed by GnuPG restores from its newest self-signature, and a revoked one restores marked revoked.

Checked against

tools/vectors/paperkey

Computed by paperkey 1.6 and GnuPG 2.4.8, run by the folder's make.sh.

faraday/faraday-pgp/tests/paperkey.rs::paperkey_restores_faradays_lines_to_faradays_secret_key

faraday/faraday-pgp/tests/paperkey.rs::a_secret_that_does_not_make_the_public_key_is_refused

faraday/faraday-pgp/tests/paperkey.rs::a_paperkey_for_another_key_or_subkey_is_refused_at_its_header

faraday/faraday-keys/tests/vault.rs::a_key_restored_from_its_paperkey_is_the_record_make_wrote

faraday/faraday-keys/tests/vault.rs::a_mistyped_line_is_refused_and_typed_again

faraday/faraday-keys/tests/vault.rs::a_paperkey_code_in_either_of_paperkeys_forms_restores_the_key

faraday/faraday-keys/tests/vault.rs::a_paperkey_code_that_does_not_hold_is_refused_and_keeps_the_lines_typed

fuzz pgp_restore

fuzz pgp_paperkey

Cross-check

not cross-checked: Judged by real paperkey 1.6 in faraday/faraday-pgp/tests/paperkey.rs, not by an F79 area; the tests fail where paperkey is missing

Secret handling

none: no secret leaves faraday-keys

Not stated by the ed25519-dalek crate.

The typed lines, a scanned code's lines and the restored seeds are wiped when the restore is wiped or dropped; a code refused keeps nothing.

Limits

Refuses a paperkey protected by a passphrase, one of another algorithm, one for another key or subkey, and one whose secret does not make the public key.

A certification by another key is set aside and counted, not restored.

The public key is read from Files, a scanned one filed there first; a paperkey's code is taken whole or not at all, every line checked as typed, the raw form by its whole CRC.

Faraday's own calls

A restore that cannot reproduce the certificate's own signatures is refused rather than accepted on the public key alone. Conservative, F155.

Check a GPG signature

SpecificationRFC 4880 · RFC 9580 · RFC 8032PublishedCodeLibrary: ed25519-dalek 3.0Library: sha1 0.11Library: sha2 0.111 moreFaraday's code: faraday/faraday-pgpCross-checked withNot cross-checked
Action

Checks a detached OpenPGP signature over data against a certificate: the signing subkey's binding and back signature, the key's life, and the Ed25519 signature over a SHA-256 or SHA-512 digest.

Specification

RFC 4880, OpenPGP Message Format, obsoleted by RFC 9580, Proposed Standard

RFC 9580, OpenPGP, Proposed Standard

RFC 8032, Edwards-Curve Digital Signature Algorithm (EdDSA), Informational

Code

Library: ed25519-dalek 3.0.0, by the dalek-cryptography developers.

Library: sha1 0.11.0, by the RustCrypto developers.

Library: sha2 0.11.0, by the RustCrypto developers.

Library: base64ct 1.8.3, by the RustCrypto developers.

Faraday's code: faraday/faraday-pgp: Takes one armoured block of one version-4 binary signature and refuses everything it does not honour; checks the certificate too, with strict Ed25519 verification of the signature and of the subkey's binding and back signature.

Checked against

tools/vectors/release-sums

Computed by GnuPG 2.4.9, run by the folder's make.sh; faraday-0.1.7/ holds Faraday 0.1.7's published sums.

faraday/faraday-pgp/tests/verify.rs::a_gnupg_signature_over_sha512_and_over_sha256_verifies

faraday/faraday-pgp/tests/verify.rs::a_signature_by_another_key_is_refused_as_another_keys

faraday/faraday-pgp/tests/verify.rs::a_revoked_key_verifies_nothing

faraday/faraday-pgp/tests/verify.rs::a_sequoia_signature_verifies_and_one_over_other_sums_is_refused

faraday/faraday-pgp/tests/verify_refusals.rs::a_text_mode_signature_is_refused

faraday/faraday-pgp/tests/verify_refusals.rs::a_signing_subkey_without_its_back_signature_or_with_a_wrong_one_verifies_nothing

fuzz pgp_verify

Cross-check

not cross-checked: Judged by signatures made with real gnupg and with Sequoia's sq (tools/vectors/release-sums), not by an F79 area

Secret handling

none: no secret leaves faraday-keys

Not applicable: only public keys and signatures are handled.

Nothing secret is held.

Limits

Refuses text-mode signatures, versions 5 and 6, a hashed signature expiry, a creation time outside the hashed area and a critical subpacket it does not understand.

Refuses a certificate that carries a revocation, and a signature made before the subkey or after either key's expiry.

Armour without its checksum, or with anything after it, is refused.

Faraday's own calls

Anything not honoured is refused rather than read, so the release check of F134 cannot be satisfied by a signature of another shape. Conservative, F134.

Make Secure Boot keys

SpecificationUEFI Specification · RFC 5280 · RFC 5652 · 1 morePublishedOwn specificationCodeLibrary: rsa 0.10Library: sha2 0.11Library: chacha20 0.103 moreFaraday's code: faraday/faraday-sbFaraday's own codeCross-checked withNot cross-checked
Action

Makes an owner's Secure Boot keys, PK, KEK and db as RSA-2048 with self-signed certificates, and the enrolment files: signature lists, PKCS #7 signed updates and certificates.

Specification

Own specification

UEFI Specification, Unified Extensible Firmware Interface Specification: Secure Boot, signature lists and authenticated variables, Status not checked

RFC 5280, Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile, Proposed Standard

RFC 5652, Cryptographic Message Syntax (CMS), Internet Standard

RFC 8017, PKCS #1: RSA Cryptography Specifications Version 2.2, Informational

Code

Library: rsa 0.10.0-rc.18, by the RustCrypto developers.

Library: sha2 0.11.0, by the RustCrypto developers.

Library: chacha20 0.10.2, by the RustCrypto developers.

Library: rand_core 0.10.1, by the Rand Project developers.

Library: x509-cert 0.3.0, by the RustCrypto developers.

Library: der 0.8.2, by the RustCrypto developers.

Faraday's code: faraday/faraday-sb: The RSA key generator draws from the chacha20 crate's `ChaCha20Rng`, seeded with a fresh 32-byte draw (a system answer, with the person's own randomness hashed in when they added some), with a stream for the key, one for the GUID and serials and one that blinds the signing; the certificates are `x509-cert`'s builder signing through `rsa`'s `pkcs1v15::SigningKey`, and the CMS SignedData and Authenticode structures are `der` types; the `rsa` crate is a release candidate and pinned.

Written by Faraday

CMS SignedData, Authenticode's image hash and signature, EFI signature lists and .auth files (faraday-sb) · No established implementation exists

No library writes Authenticode signatures or EFI signature lists; the CMS crate for the DER version Faraday uses is a release candidate.

Decision F178

Checked against

not checked against vectors

faraday/faraday-sb/tests/golden.rs::an_owners_secure_boot_keys_are_the_bytes_they_always_were

faraday/faraday-sb/tests/judged.rs::openssl_verifies_the_certificates_and_the_auth_signatures

faraday/faraday-sb/tests/judged.rs::microsoft_certificates_are_what_was_recorded

faraday/faraday-sb/tests/judged.rs::the_generator_gives_the_keystream_of_rfc_8439

faraday/faraday-sb/tests/judged.rs::openssl_checks_every_private_key_made

faraday/faraday-sb/tests/judged.rs::certtool_reads_every_certificate_made

no fuzz target: Key making takes a seed and a name; pe_image fuzzes the reading of images

Cross-check

Own specification, not yet reviewed outside Faraday.

An outside review recorded in a decision ends it; a reproduction from the specification by an outside party is asked for in docs/AUDIT-SUBMISSIONS.md §10.

not cross-checked: Judged by openssl in faraday/faraday-sb/tests/judged.rs, which fails where openssl is missing; not by an F79 area

Secret handling

none: no secret leaves faraday-keys

Not stated by the rsa crate.

The keys are returned to the caller, which keeps them in the vault's type 8 record; the seed is the caller's.

Limits

RSA-2048 only, certificates valid 30 years.

Faraday never writes an EFI variable: enrolment happens in the firmware's own setup screen.

The Windows policy adds Microsoft's KEK and Windows signing CAs, not the third-party CA.

Faraday's own calls

none

Sign a boot program

SpecificationAuthenticode · UEFI Specification · RFC 5652 · 1 morePublishedCodeLibrary: rsa 0.10Library: sha2 0.11Library: x509-cert 0.31 moreFaraday's code: faraday/faraday-sbCross-checked withNot cross-checked
Action

Signs a boot program with the db key, as an Authenticode SHA-256 signature, only when it is the file a release's checked sums name.

Specification

Authenticode, Windows Authenticode Portable Executable Signature Format, Status not checked

UEFI Specification, Unified Extensible Firmware Interface Specification: Secure Boot, signature lists and authenticated variables, Status not checked

RFC 5652, Cryptographic Message Syntax (CMS), Internet Standard

RFC 8017, PKCS #1: RSA Cryptography Specifications Version 2.2, Informational

Code

Library: rsa 0.10.0-rc.18, by the RustCrypto developers.

Library: sha2 0.11.0, by the RustCrypto developers.

Library: x509-cert 0.3.0, by the RustCrypto developers.

Library: der 0.8.2, by the RustCrypto developers.

Faraday's code: faraday/faraday-sb: Signs only the image whose SHA-256 the checked release names (F134); the release is checked from its SHA256SUMS and their OpenPGP signature. The signer of any image exists only under a build feature that no shipped binary turns on.

Checked against

tools/vectors/release-sums

Computed by GnuPG 2.4.9, run by the folder's make.sh; faraday-0.1.7/ holds Faraday 0.1.7's published sums.

faraday/faraday-sb/tests/release.rs::a_release_boot_file_with_genuine_signed_sums_is_signed

faraday/faraday-sb/tests/release.rs::sums_signed_by_another_key_or_changed_are_refused

faraday/faraday-sb/tests/release.rs::a_release_signs_only_the_file_it_names

faraday/faraday-sb/tests/release.rs::the_built_in_release_key_is_the_repositorys_and_checks_faraday_0_1_7s_sums

fuzz release_sums

fuzz pe_image

Cross-check

not cross-checked: Judged by sbverify and openssl in faraday/faraday-sb/tests/judged.rs, which fails where one is missing; not by an F79 area

Secret handling

none: no secret leaves faraday-keys

Not stated by the rsa crate.

The db key is the vault record's, held by the open vault and wiped when it closes; the blinding stream is a ChaCha20 keystream of fresh bytes from the system.

Limits

Signs only a release's own boot program, and not an older release's: the release must be at least as new as the running Faraday.

Refuses a file the sums do not list exactly once, sums whose first line does not name the release, and a text-mode signature.

The signature is appended as one certificate table at the image's end.

Faraday's own calls

A boot program is signed only when it is a release's own. Conservative, F134.

Check a boot signature

SpecificationAuthenticode · RFC 5652 · RFC 8017PublishedCodeLibrary: rsa 0.10Library: sha2 0.11Library: x509-cert 0.31 moreFaraday's code: faraday/faraday-sbCross-checked withNot cross-checked
Action

Checks an image's Authenticode signature against a db certificate: the image hash, the SHA-256 digest in the signed data and the RSA signature.

Specification

Authenticode, Windows Authenticode Portable Executable Signature Format, Status not checked

RFC 5652, Cryptographic Message Syntax (CMS), Internet Standard

RFC 8017, PKCS #1: RSA Cryptography Specifications Version 2.2, Informational

Code

Library: rsa 0.10.0-rc.18, by the RustCrypto developers.

Library: sha2 0.11.0, by the RustCrypto developers.

Library: x509-cert 0.3.0, by the RustCrypto developers.

Library: der 0.8.2, by the RustCrypto developers.

Faraday's code: faraday/faraday-sb: Says whether the signature is valid, signed by another key, or not readable; it says nothing of whether a computer trusts the key, which its db decides.

Checked against

not checked against vectors

faraday/faraday-sb/tests/judged.rs::a_signed_image_checks_and_an_altered_one_does_not

faraday/faraday-sb/tests/judged.rs::images_signed_by_sbsign_and_osslsigncode_are_read_and_their_signer_named

faraday/faraday-sb/tests/judged.rs::an_image_whose_signature_table_is_shorter_than_its_header_reads_as_unreadable

faraday/faraday-sb/tests/judged.rs::real_signed_binaries_are_read_and_their_signer_named_as_pesign_names_it

fuzz pe_image

Cross-check

not cross-checked: Judged by images signed by sbsign and osslsigncode and by sbverify (faraday/faraday-sb/tests/judged.rs), not by an F79 area; sbverify fails the test where it is missing

Secret handling

none: no secret leaves faraday-keys

Not applicable: only public certificates and signatures are handled.

Nothing secret is held.

Limits

Reads the first signature of an image only.

A signature table shorter than its header, or starting inside the image's headers, is refused.

Faraday's own calls

Checks the signature alone and not the chain a computer's db would walk. Neutral.

no decision

The device and the Starter

4 actions · 1 own specification · 2 with Faraday's own code · 4 not cross-checked

Run the start-up self-test

SpecificationBIP 39 · BIP 32 · BIP 84 · 4 morePublishedCodeLibrary: argon2 0.6 (through core/faraday-crypto)Library: bitcoin 0.32 (through core/faraday-bip)Library: hmac 0.13 (through core/faraday-crypto)3 moreFaraday's code: core/faraday-selftestCross-checked withNot cross-checked
Action

Runs eight fixed-vector checks at start-up and from Settings: BIP 39 words and seed in English and Japanese, BIP 32 derivation, a BIP 84 address, an ECDSA and a BIP 340 signature, scrypt and Argon2id.

Specification

BIP 39, Mnemonic code for generating deterministic keys, Deployed

BIP 32, Hierarchical Deterministic Wallets, Deployed

BIP 84, Derivation scheme for P2WPKH based accounts, Deployed

BIP 340, Schnorr Signatures for secp256k1, Deployed

RFC 6979, Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA), Informational

RFC 7914, The scrypt Password-Based Key Derivation Function, Status not checked

RFC 9106, Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications, Informational

Code

Library: argon2 0.6.0, by the RustCrypto developers, through core/faraday-crypto.

Library: bitcoin 0.32.102, by the rust-bitcoin developers, through core/faraday-bip.

Library: hmac 0.13.0, by the RustCrypto developers, through core/faraday-crypto.

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Library: unicode-normalization 0.1.25, by the unicode-rs developers, through core/faraday-bip.

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-selftest: Each check calls the function the product itself calls (the Argon2id check calls `faraday_crypto::argon2id`, which wraps the `faraday_crypto::argon2` the vault calls) and compares with an expected value copied from a vector file; a failure names the check and blocks the app but Exit.

Checked against

tools/vectors/bip39

Published, by Trezor (SatoshiLabs), python-mnemonic's vectors; bip32JP's Japanese vectors.

tools/vectors/psbt

Published, by BIP 174's and RFC 6979's authors; the spends and finalized answers Bitcoin Core v31.1 made on regtest. Faraday's own known answers: the wallet policies, the warning PSBTs and the PSBTs this tree signed.

tools/vectors/kdf

Published, by RFC 7914 §12, for scrypt; the Argon2id answer computed by argon2-cffi and PyCA cryptography, which agree.

core/faraday-selftest/src/lib.rs::every_check_passes_on_its_own

core/faraday-selftest/src/lib.rs::the_first_failure_is_named

faraday/faraday-core/tests/all/selftest.rs::the_self_test_passes_at_start_and_settings_runs_it_again

faraday/faraday-core/tests/all/selftest.rs::a_failed_check_blocks_everything_but_exit

self-test bip39_vector

self-test bip39_japanese_vector

self-test bip32_vector

self-test bip84_address

self-test ecdsa_vector

self-test schnorr_vector

self-test scrypt_vector

self-test argon2id_vector

no fuzz target: It takes no input

Cross-check

not cross-checked: It checks the app's own functions against fixed published answers; the functions it calls are cross-checked in the bip39, bip32, addr, sign, lightning and vault areas

Secret handling

none: no secret leaves faraday-keys

Not applicable: the keys are published test keys.

Nothing secret is held.

Limits

Runs published vectors only, at small costs (scrypt N = 16, Argon2id over 256 KiB).

The curve context is blinded from a fixed seed, since a self-test has no session to derive one from.

Faraday's own calls

No key is accepted until the checks pass. Conservative.

no decision

Write an image to a stick

SpecificationFIPS 180-4PublishedCodeLibrary: sha2 0.11Library: lzma-rust2 0.22Library: getrandom 0.3 and 0.4Faraday's code: faraday/faraday-payloadFaraday's own codeCross-checked withNot cross-checked
Action

Writes an image to a stick and checks it: the SHA-256 of the found image file against the release's image list before any write, of the decompressed bytes against the list as they are written, and of what was read back from the stick, with the stick's own IDs and name taken back out, against the list after; keep data takes a stick as the same build only when its boot partition's SHA-256 is the release's boot partition sum (F244).

Specification

FIPS 180-4, Secure Hash Standard, Status not checked

Code

Library: sha2 0.11.0, by the RustCrypto developers.

Library: lzma-rust2 0.22.0, by hasenbanck (lzma-rust2), a port of the Tukaani project's XZ for Java.

Library: getrandom 0.3.4 and 0.4.3, by the Rand Project developers.

Faraday's code: faraday/faraday-payload: The image file is read whole and its SHA-256 compared before anything is written, then read again and decompressed into the writer; success means the writer received exactly the list's size with the list's SHA-256; a developer's image is hashed when confirmed and refused if it changed after; a Pi card is read back and compared with the stream as written, and the SHA-256 of what was read, with the card's own IDs put back where they went (docs/STICK-IDENTITY.md §4.3), must be the list's. A stick is made for its size, not copied (docs/STICK-IDENTITY.md §4.2): only the image's boot partition reaches it, byte for byte with the release's serial; its protective MBR, GPT (new disk and partition GUIDs from getrandom, the data partition to the last usable sector, every CRC-32 worked out again) and its data partition's FAT32 (faraday-fat's formatter, a new serial from getrandom) are written as regions and every region and the boot partition are read back and compared byte for byte; the GUIDs and serials are identities, not secrets. A stick made or keep data from a found image with no boot file signed first checks that the SHA-256 of the image's boot partition is the list's and writes nothing otherwise. Clearing the whole stick first writes zeros over every sector and reads none back. A name given the data partition (docs/STICK-IDENTITY.md §6) is faraday-fat's label write run over the sectors captured, each byte it changed a patch put back the same way.

Written by Faraday

The FAT32 formatter for the Starter's data partition (faraday-fat::format) · No established implementation exists

No FAT library comes from a publisher Faraday's dependency review trusts; the partition it makes is checked by dosfstools' fsck.fat, against what mkfs.fat makes.

Carries a format; it computes nothing on a key.

Decision F180

GPT and MBR tables, read and rewritten (faraday-starter-shell::gpt, faraday-starter-shell::ids) · No established implementation exists

No partition-table library comes from a publisher Faraday's dependency review trusts.

Carries a format; it computes nothing on a key.

Decision F180

The plist reader for the disk tool's output (faraday/shells/starter) · No established implementation exists

No plist library comes from a publisher Faraday's dependency review trusts.

Carries a format; it computes nothing on a key.

Decision F180

The form of a version 4 UUID (faraday-starter-shell::ids) · Only the part used is written

Four lines setting RFC 9562's version and variant bits over bytes from getrandom.

Carries a format; it computes nothing on a key.

Decision F180

Checked against

not checked against vectors

faraday/faraday-payload/tests/payload.rs::a_payload_made_by_xz_decodes_to_exactly_the_original_bytes

faraday/faraday-payload/tests/payload.rs::a_payload_whose_xz_sum_does_not_match_is_refused_before_anything_is_written

faraday/faraday-payload/tests/payload.rs::decompressed_bytes_that_do_not_match_the_list_are_a_failure

faraday/faraday-payload/tests/payload.rs::a_developers_image_has_the_sum_sha256sum_gives_plain_or_xz

faraday/faraday-payload/tests/payload.rs::a_developers_image_that_changed_after_it_was_confirmed_is_a_failure

faraday/shells/starter/tests/all/ids.rs::two_sticks_written_from_one_image_have_their_own_ids_and_the_same_boot_partition

faraday/shells/starter/tests/all/ids.rs::a_stick_made_for_its_size_reads_clean_in_other_tools_at_1_32_and_256_gb

faraday/shells/starter/tests/all/outside.rs::xz_streams_good_and_damaged_are_decoded_or_refused_as_xz_and_7_zip_do

faraday/shells/starter/tests/all/outside.rs::the_tables_written_on_sticks_and_cards_pass_sgdisk_and_sfdisk

faraday/shells/starter/tests/all/outside.rs::the_answers_diskutil_gives_are_read_as_python_reads_them_or_refused_by_both

faraday/shells/starter/tests/all/outside.rs::the_ids_drawn_for_a_stick_are_version_4_uuids_as_python_reads_them

faraday/shells/starter/tests/all/writer.rs::a_source_one_byte_off_is_refused_and_nothing_is_written

faraday/shells/starter/tests/all/writer.rs::a_boot_partition_read_back_one_byte_off_fails_the_write

faraday/shells/starter/tests/all/writer.rs::keep_data_on_a_stick_made_for_its_size_keeps_its_table_and_data_partition

faraday/shells/starter/tests/all/writer.rs::clearing_first_leaves_every_sector_outside_what_is_then_written_zero

faraday/shells/starter/tests/all/signed_boot.rs::keep_data_refuses_a_boot_partition_that_is_not_the_one_the_release_lists_unless_a_boot_file_is_signed

no fuzz target: The image_list target fuzzes the image list's reading; no target runs the xz decoder or the hash

Cross-check

not cross-checked: The sums are compared with `sha256sum`'s in the tests, and the tests judge the decoder with `xz` and 7-Zip (`7zz` or `7z`) over good and damaged streams, the tables written with `sfdisk --verify` and `sgdisk -v`, the `diskutil` answers with Python's `plistlib` and the GUIDs with Python's `uuid` and the CRC-32 fields of the GPT headers and partition arrays with `zlib.crc32`; each is skipped without its tool in `just` and fails in `just crosscheck`. No F79 area runs the decoder

Secret handling

none: no secret leaves faraday-keys

Not applicable: only public images and sums are handled.

Nothing secret is held.

Limits

An xz stream that asks for more than 128 MiB of memory for one block is refused before it is allocated.

A payload whose xz sum does not match writes nothing.

SHA-256 shows that the bytes are the release's, not who made them.

Faraday's own calls

Both the compressed and the decompressed sums are checked, and a mismatch after writing is reported as a failure. Conservative.

no decision

Check a signed boot file

SpecificationAuthenticode · RFC 8017PublishedCodeLibrary: rsa 0.10Library: sha2 0.11Faraday's code: faraday/faraday-sbCross-checked withNot cross-checked
Action

Checks a boot file the person signed against the release's own: its Authenticode image hash, its one signature at the file's end, and the signature on the file built.

Specification

Authenticode, Windows Authenticode Portable Executable Signature Format, Status not checked

RFC 8017, PKCS #1: RSA Cryptography Specifications Version 2.2, Informational

Code

Library: rsa 0.10.0-rc.18, by the RustCrypto developers.

Library: sha2 0.11.0, by the RustCrypto developers.

Faraday's code: faraday/faraday-sb: Only the signature is taken from the person's file: the file written is the release's own bytes with that file's checksum, certificate-table entry and certificate table, so every byte the signature does not cover is the release's; which key signed it is not judged, a computer's db decides that.

Checked against

not checked against vectors

faraday/shells/starter/tests/all/signed_boot.rs::a_release_boot_file_signed_with_ones_own_db_key_is_written_in_place_of_the_releases

faraday/shells/starter/tests/all/signed_boot.rs::the_same_program_with_one_code_byte_changed_then_signed_is_refused

faraday/shells/starter/tests/all/signed_boot.rs::a_signed_boot_file_with_more_than_one_signature_at_its_end_is_refused

faraday/shells/starter/tests/all/signed_boot.rs::a_signature_that_does_not_hold_is_refused_as_such

faraday/faraday-sb/tests/judged.rs::a_signature_is_moved_onto_the_releases_bytes_only_when_it_is_alone_at_the_end

faraday/faraday-sb/tests/judged.rs::pefile_finds_the_certificate_table_where_faraday_put_it_and_the_moved_checksum_is_right

fuzz pe_transplant

Cross-check

not cross-checked: Judged by images signed by sbsign and osslsigncode and by sbverify (faraday/faraday-sb/tests/judged.rs), not by an F79 area; sbverify fails the test where it is missing

Secret handling

none: no secret leaves faraday-keys

Not applicable: only public images, certificates and signatures are handled.

Nothing secret is held.

Limits

Refuses a file that is not the release's program, an unsigned file, and one whose certificate table is not one signature alone at its end.

The elevated writer reads the file again and refuses it unless it still has the SHA-256 that was chosen.

Faraday's own calls

Anything but the release's own bytes with the person's signature is refused by name. Conservative, F133.

Read a BitLocker recovery key

SpecificationOwn specificationCodeFaraday's code: faraday/faraday-starterFaraday's own codeCross-checked withNot cross-checked
Action

Reads a BitLocker recovery key, eight groups of six digits, for the system drive, holds it until the notes sheet is made and wipes it.

Specification

Own specification (F49)

Code

Faraday's code: faraday/faraday-starter: A key is taken only as eight groups of six digits joined by hyphens, for a drive that is a letter and a colon; it is held in a zeroizing string, printed on the sheet after the other rows with its drive, four groups to a line, and the rows' copies of its text are zeroized once the PDF is made; Debug prints none of it.

Written by Faraday

The PDF writer (faraday-core::pdf, faraday-starter::sheets) · No established implementation exists

No PDF library comes from a publisher Faraday's dependency review trusts.

Carries a format; it computes nothing on a key.

Decision F180

Checked against

not checked against vectors

faraday/faraday-starter/tests/all/bitlocker.rs::a_recovery_key_is_eight_groups_of_six_digits_and_debug_shows_none_of_it

faraday/faraday-starter/tests/all/bitlocker.rs::the_sheet_carries_the_key_only_when_ticked

faraday/faraday-starter/tests/all/bitlocker.rs::a_key_that_cannot_be_read_says_why_and_prints_nothing

faraday/faraday-starter/tests/all/bitlocker.rs::the_key_s_sheet_names_nothing_else_no_path_no_computer_and_holds_no_qr_code

no fuzz target: Takes one drive and one key text from the elevated copy; the shape is checked by tests

Cross-check

not cross-checked: The key is read and printed as text; nothing is computed from it, and there is no second implementation

Source

0.2.0 · faraday/faraday-starter/src/api.rs · RecoveryKey::parse

0.2.0 · faraday/faraday-starter/src/notes.rs · Notes::pdf_with_key

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

Not applicable: the key is read and printed, not used in a computation.

The key is a zeroizing string wiped when dropped, once the sheet is made; the rows' copies of its text are zeroized after the PDF is written, and the PDF is the caller's to wipe.

Limits

A key that is not eight groups of six digits, or a drive that is not a letter and a colon, is not taken.

The key is on the sheet only when the person ticked Include the BitLocker recovery key.

The sheet carries nothing else of BitLocker and no QR code of the key.

Faraday's own calls

The sheet carries the key only when it is ticked, and holds it only until the sheet is made. Conservative, F49.

In the repository, not in the app

Built and checked in the repository, and offered on no screen of the app.

7 actions · 5 with Faraday's own code · 6 cross-checked with others' code · 1 with Faraday's second version · 1 not cross-checked

Build a recovery wallet

SpecificationBIP 379 · BIP 382 · BIP 386PublishedCodeLibrary: miniscript 12.3Library: bitcoin 0.32Library: base16ct 1.0 (through core/faraday-crypto)Faraday's code: core/faraday-bipCross-checked withBitcoin Core v31.1 itself (deriveaddresses) and its functional-test frameworkOthers' code
Action

Builds a timelocked recovery wallet from its parts and reads the parts back out of one.

Specification

BIP 379, Miniscript, Draft

BIP 382, Output Script Descriptors: wsh, Deployed

BIP 386, Output Script Descriptors: tr, Deployed

Code

Library: miniscript 12.3.7, by the rust-bitcoin developers (rust-miniscript).

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-bip: A primary spending path and recovery paths behind relative delays, as Liana writes them; a taproot form puts one primary key on the key path; a wallet no one could recover is refused. The miniscript area builds wallets of these shapes with RecoveryPolicy in both forms and reads them back, and compares their scripts, kinds and ways to spend with Bitcoin Core and btclib.

Checked against

tools/vectors/miniscript

Published, by Bitcoin Core's miniscript_tests.cpp, v31.1, by the Bitcoin Core developers.

core/faraday-bip/tests/all/recovery.rs::a_segwit_recovery_wallet_is_the_descriptor_liana_wrote

core/faraday-bip/tests/all/recovery.rs::liana_s_own_wallet_reads_back_as_its_keys_and_its_delay

core/faraday-bip/tests/all/recovery.rs::every_built_wallet_reads_back_as_the_paths_it_was_built_from

core/faraday-bip/tests/all/recovery.rs::a_wallet_no_one_could_recover_is_refused

core/faraday-bip/tests/all/recovery.rs::the_taproot_recovery_wallets_pay_the_addresses_bitcoin_core_derives

fuzz policy

Cross-check

Compared with others' code: Bitcoin Core v31.1 itself (deriveaddresses) and its functional-test framework, by Bitcoin Core's contributors; python-bip380, by Antoine Poinsot, for Core's vectors that state no script; btclib-wallet's bip32, by the btclib developers, for the cosigners' keys, and its descriptors and miniscript, by the btclib developers, on btclib's own curve, for each descriptor's kind, text and script at an index, Core's vectors' types, sanity and scripts, and the satisfaction of each way a wallet's coins move under its lock times (and, for recovery wallets, each built from its parts).

Area miniscript

Faraday's code faraday_bip::policy::WalletPolicy (a wallet's descriptor and the script it pays at an index, its kind, text and spend paths), faraday_bip::policy::parse_script_descriptor, a witness script read back as faraday_psbt reads one, faraday_bip::recovery::RecoveryPolicy (a recovery wallet built from its parts and read back)

Compared with Bitcoin Core v31.1's bitcoind on regtest (deriveaddresses) for random wallets, their cosigners' keys from btclib (btclib/, on btclib's own curve); btclib-wallet's descriptors and miniscript (btclib/) for each descriptor's kind, text and script, Core's vectors' types and scripts, and the satisfaction of each way a wallet's coins move under its lock times; Antoine Poinsot's python-bip380 (miniscript/) for Core's vectors that state no script.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; btclib reads Core's 97 miniscripts, in both contexts, before any random wallet (valid exactly when Core says, its properties, sane, script); Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run, and the node's version is asked.

The witness bytes of a satisfaction (btclib assembles one and area sign compares Faraday's finalizer); a wallet with more than 64 ways to spend, for which Faraday states none; hash locks and locks in seconds, which the corpus does not generate; and a wallet btclib cannot read (none yet).

Vectors Bitcoin Core's miniscript unit tests, 97 miniscripts in P2WSH and Tapscript (tools/vectors/miniscript/).

Random cases Wallets of the Liana, Nunchuk, Sparrow and recovery shapes in wsh() and sh(wsh()), multi/sortedmulti in sh(), wsh(), sh(wsh()), tr() with trees of one to six leaves or a lone sortedmulti_a, over random accounts on every network, at random indices of both chains; the same made not sane, refused; recovery wallets of both forms with one to three recovery paths, and the ways each wallet's coins move spent at their lock times.

Differences Miniscript: Faraday reads sortedmulti_a only as a tr()'s one leaf; BIP 387 allows it deeper in a tree, and Core reads it there. Two of Bitcoin Core's sane miniscripts are refused, as miniscript refuses them: or_b(0,a:0), which has no satisfaction, and a d: used as a unit under Tapscript. Each is checked and counted; btclib is not asked the deeper sortedmulti_a. btclib says nothing of "needs a signature" for a malleable miniscript (BIP 379 does not), so that property is compared where Core calls the miniscript non-malleable.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 2500 cases

Source

0.2.0 · core/faraday-bip/src/recovery.rs · RecoveryPolicy::to_wallet_policy

github.com/bitcoinpasada/faraday

Secret handling

none: no secret leaves faraday-keys

Only public keys are used; nothing here holds a secret.

Nothing secret is held.

Limits

A wallet no one could recover is refused.

A wallet that never waits is not read back as a recovery wallet.

Not reached from the app: Create makes no recovery wallet, and one is read as any miniscript wallet.

Faraday's own calls

Script shape is left to rust-miniscript's compiler. Neutral.

no decision

Derive keys with HKDF

SpecificationRFC 5869 · RFC 2104 · FIPS 180-4PublishedCodeLibrary: hmac 0.13Faraday's code: core/faraday-cryptoCross-checked withPyCA cryptography's HKDF and HKDFExpand (OpenSSL)Others' code
Action

Derives keys with HKDF over SHA-256, extracting under a salt and expanding, or expanding alone.

Specification

RFC 5869, HMAC-based Extract-and-Expand Key Derivation Function (HKDF), Informational

RFC 2104, HMAC: Keyed-Hashing for Message Authentication, Status not checked

FIPS 180-4, Secure Hash Standard, Status not checked

Code

Library: hmac 0.13.0, by the RustCrypto developers.

Faraday's code: core/faraday-crypto: HKDF (RFC 5869) is written here over `hmac`: `hkdf_sha256` extracts under the salt into a pseudorandom key held in a wiped `Secret` and expands, for the QR vault's message, and `hkdf_sha256_expand` (§2.3) expands alone, for the blinding of the session's keys and Schnorr signing's per-input auxiliary randomness. Both are checked against RFC 5869's test cases 1 to 3 and, in area `hash`, against PyCA's `HKDF` and `HKDFExpand`.

Checked against

not checked against vectors

core/faraday-crypto/tests/primitives.rs::hkdf_sha256_rfc5869_cases

core/faraday-crypto/tests/primitives.rs::hkdf_sha256_expand_rfc5869_cases

core/faraday-crypto/tests/primitives.rs::hkdf_sha256_expand_refuses_more_than_255_blocks

no fuzz target: Takes bytes from callers that parse their own input

Cross-check

Compared with others' code: PyCA cryptography's HKDF and HKDFExpand (OpenSSL).

Area hash

Faraday's code faraday_bip::hashes and faraday_codec::encodings (read, the writers and from_hex), faraday_core::file_menu::sha256, and faraday_crypto::hkdf_sha256 and hkdf_sha256_expand, hmac_sha256, hmac_sha512, pbkdf2_hmac_sha256, pbkdf2_hmac_sha512 and scrypt

Compared with Bitcoin Core v31.1's functional-test framework (core/): ripemd160.py, address.py and segwit_addr.py, with hashlib for SHA-256 and bytes.fromhex for hex; PyCA cryptography's HKDF and HKDFExpand (OpenSSL) for the one HKDF; hmac, hashlib.pbkdf2_hmac and hashlib.scrypt (OpenSSL) for HMAC, PBKDF2 and scrypt.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; the order read tries the spellings in, the trimming of the text, hex as an even number of hex digits, plain Base58 (which Core's framework does not read; the area's own few lines) and which prefixes make a segwit address are Faraday's rules, written in the area in front of the reference.

The file hash is file_menu::sha256 over a whole byte slice (it reads in no buffer, so no read size is probed); the Files screen's reading of a file from a stick is the files areas'.

Vectors FIPS 180-4's SHA-256 examples, RIPEMD-160 of abc, BIP-173's key and its HASH160, Bitcoin Core's first key_io_valid.json address, BIP-173's and BIP-350's bech32 strings and their valid and invalid segwit addresses (tools/vectors/addresses).

Random cases Random bytes of every length from 0 to 130 and to 300 hashed (SHA-256, SHA-256d, HASH160) and as a file, files of 4 KiB, 64 KiB and 1 MiB with a byte more and less; random bytes written and read as Base58Check, Base58, bech32 and bech32m, Core's writing read by Faraday, segwit addresses of every version Core's framework writes, and texts changed, cut or made of random characters read by both.

Differences bech32 groups: a string that is not a segwit address of bc, tb or bcrt is read as bytes, all its data groups together, and the bits that do not fill a byte are dropped. BIP-173 has a padding rule only for a segwit address, so Core's convertbits, which applies it to any data, refuses some of these strings, and the area reads them as Faraday does.

bech32 length: Core's decoder refuses more than 90 characters (BIP-173); Faraday accepts any length the checksum covers. The area reads longer strings the same way.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The pseudorandom key is held in a wiped `Secret`; the output slice is the caller's to wipe.

Limits

HKDF-Expand makes at most 255 blocks of 32 bytes (RFC 5869 §2.3); a longer output is refused and nothing is written.

Faraday's own calls

none

Stretch a password with scrypt

SpecificationRFC 7914PublishedCodeFaraday's code: core/faraday-cryptoFaraday's own codeCross-checked withPython's hashlib.scrypt (OpenSSL) in area hashOthers' code
Action

Stretches a password with scrypt, written in this crate, for LND's aezeed.

Specification

RFC 7914, The scrypt Password-Based Key Derivation Function, Status not checked

Code

Faraday's code: core/faraday-crypto: Written here, with one caller (the aezeed reader), because it is small enough that a crate would cost more than it saves.

Written by Faraday

scrypt (faraday-crypto::scrypt) · One exists but does not fit Faraday's rules for keys

The Rust scrypt library leaves its passphrase-derived working memory unwiped; Faraday's wipes it.

Does not fit: scrypt 0.12.0 frees its passphrase-derived working buffers (b, v, t) without wiping them

Decision F178

Checked against

tools/vectors/kdf

Published, by RFC 7914 §12, for scrypt; the Argon2id answer computed by argon2-cffi and PyCA cryptography, which agree.

core/faraday-crypto/src/scrypt.rs::rfc_7914_vectors

self-test scrypt_vector

no fuzz target: Takes cost parameters fixed by the one caller; aezeed fuzzes the words

Cross-check

Compared with others' code: Python's hashlib.scrypt (OpenSSL) in area hash, and LND's aezeed package, by Lightning Labs, over golang.org/x/crypto's scrypt, vendored in tools/reference/lnd/, in area lightning.

Area hash

Faraday's code faraday_bip::hashes and faraday_codec::encodings (read, the writers and from_hex), faraday_core::file_menu::sha256, and faraday_crypto::hkdf_sha256 and hkdf_sha256_expand, hmac_sha256, hmac_sha512, pbkdf2_hmac_sha256, pbkdf2_hmac_sha512 and scrypt

Compared with Bitcoin Core v31.1's functional-test framework (core/): ripemd160.py, address.py and segwit_addr.py, with hashlib for SHA-256 and bytes.fromhex for hex; PyCA cryptography's HKDF and HKDFExpand (OpenSSL) for the one HKDF; hmac, hashlib.pbkdf2_hmac and hashlib.scrypt (OpenSSL) for HMAC, PBKDF2 and scrypt.

Checked first: Its vendored files are hashed against references.sha256 before any run, and a published vector's answer is required of the reference as well as of Faraday; the order read tries the spellings in, the trimming of the text, hex as an even number of hex digits, plain Base58 (which Core's framework does not read; the area's own few lines) and which prefixes make a segwit address are Faraday's rules, written in the area in front of the reference.

The file hash is file_menu::sha256 over a whole byte slice (it reads in no buffer, so no read size is probed); the Files screen's reading of a file from a stick is the files areas'.

Vectors FIPS 180-4's SHA-256 examples, RIPEMD-160 of abc, BIP-173's key and its HASH160, Bitcoin Core's first key_io_valid.json address, BIP-173's and BIP-350's bech32 strings and their valid and invalid segwit addresses (tools/vectors/addresses).

Random cases Random bytes of every length from 0 to 130 and to 300 hashed (SHA-256, SHA-256d, HASH160) and as a file, files of 4 KiB, 64 KiB and 1 MiB with a byte more and less; random bytes written and read as Base58Check, Base58, bech32 and bech32m, Core's writing read by Faraday, segwit addresses of every version Core's framework writes, and texts changed, cut or made of random characters read by both.

Differences bech32 groups: a string that is not a segwit address of bc, tb or bcrt is read as bytes, all its data groups together, and the bits that do not fill a byte are dropped. BIP-173 has a padding rule only for a segwit address, so Core's convertbits, which applies it to any data, refuses some of these strings, and the area reads them as Faraday does.

bech32 length: Core's decoder refuses more than 90 characters (BIP-173); Faraday accepts any length the checksum covers. The area reads longer strings the same way.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 30000 cases

Secret handling

none: no secret leaves faraday-keys

not stated by the library.

The working memory V, the scratch block and the intermediate block are zeroized before scrypt returns.

Limits

A cost n that is not a power of two above 1, an r or p of zero, an empty output or parameters needing more memory than usize can address are refused.

Faraday's own calls

scrypt is written here rather than taken from a crate. Neutral.

no decision

Check Core wallet keys

SpecificationBitcoin Core wallet.datPublishedCodeLibrary: aes 0.9Library: cbc 0.2Library: sha2 0.11 (through core/faraday-crypto)Faraday's code: faraday/faraday-keysFaraday's own codeCross-checked withBitcoin Core (the pinned release's bitcoind on regtest)Others' code
Action

Checks each private key of a Bitcoin Core descriptor wallet against the public key its record names, and in an encrypted wallet opens the master key from the passphrase and each key with it; says pass or fail for each and gives nothing back.

Specification

Bitcoin Core wallet.dat, Bitcoin Core's descriptor wallet records and their encrypted keys, Convention

Code

Library: aes 0.9.3, by the RustCrypto developers.

Library: cbc 0.2.1, by the RustCrypto developers.

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: faraday/faraday-keys: The master key is SHA-512 of the passphrase and the record's 8-byte salt, hashed again for the rounds less one (at most 10,000,000); its first 32 bytes are the AES-256 key and the next 16 the IV that open the 48-byte mkey under CBC with PKCS#7 padding. Each walletdescriptorckey is opened under AES-256-CBC with the double SHA-256 of its public key as the IV. A key must give the public key its record names (33 bytes, or 65 for an uncompressed key with its 279-byte DER), and in the clear match the stored hash of the public key and the DER. One mkey record is tried; a wallet with more is not whole. Where the keys are checked, each account key Core cached for a descriptor's key at a hardened step (a walletdescriptorlhcache record of 74 bytes) is derived again from the checked master key along the hardened path, one derivation for each account key, and must equal the cached bytes in constant time; a cached key whose depth, child number or parent fingerprint disagrees with its path, or is not a point on the curve, fails its record, and so does a cached key no master key was compared with, whatever the wallet's flags say.

Written by Faraday

Bitcoin Core's key from a passphrase and the opening of its encrypted keys (faraday-keys::core_wallet) · No established implementation exists

No maintained Rust crate offers Bitcoin Core's BytesToKeySHA512AES and DecryptSecret; Faraday's is SHA-512 rounds over faraday-crypto and RustCrypto's aes and cbc, tested against wallets Bitcoin Core made.

Decision F229

Checked against

tools/vectors/core-wallet

Computed by Bitcoin Core (the pinned bitcoind on regtest), run by tools/vectors/core-wallet/gen.py: plain, encrypted (passphrase faraday), watch-only, blank, labelled, imported descriptor and imported uncompressed key wallets, a multisig and a miniscript wallet of keys with further hardened steps, and a wallet Core's migratewallet made of a legacy wallet (its combo() descriptors, which Faraday lists and does not take), with Core's listdescriptors and getwalletinfo.

faraday/faraday-core/tests/all/core_wallet.rs::keys_pass_and_an_encrypted_wallet_needs_its_passphrase

faraday/faraday-core/tests/all/core_wallet.rs::a_changed_byte_is_refused_with_its_record_named

faraday/faraday-keys/tests/core_wallet.rs::core_wallet_the_keys_of_a_plain_wallet_pass

faraday/faraday-keys/tests/core_wallet.rs::core_wallet_a_changed_byte_fails_a_plain_wallets_key

faraday/faraday-keys/tests/core_wallet.rs::core_wallet_an_encrypted_wallets_keys_open_under_its_passphrase

faraday/faraday-keys/tests/core_wallet.rs::core_wallet_a_changed_byte_in_an_encrypted_key_fails_that_key

faraday/faraday-keys/tests/core_wallet.rs::core_wallet_an_uncompressed_key_passes_and_a_changed_byte_fails_it

faraday/faraday-keys/tests/core_wallet.rs::core_wallet_a_private_key_with_a_right_hash_and_another_public_key_fails

faraday/faraday-core/tests/all/core_wallet.rs::a_master_key_that_cannot_open_is_refused_with_or_without_a_passphrase

faraday/faraday-core/tests/all/core_wallet.rs::an_encrypted_wallet_holds_one_master_key_and_no_plain_key

faraday/faraday-core/tests/all/core_wallet.rs::a_wallet_with_an_uncompressed_key_is_read_as_core_wrote_it

no fuzz target: The records are fuzzed through core_wallet_records, which reaches these functions

Cross-check

Compared with others' code: Bitcoin Core (the pinned release's bitcoind on regtest), which makes each wallet and says what it holds (listdescriptors, getwalletinfo, walletpassphrase) and loads or refuses each changed file (loadwallet).

Area core_wallet

Faraday's code faraday_core_wallet::read_file (a wallet.dat read whole through faraday_sqlite, the records read and checked, the private keys checked in faraday-keys)

Compared with Bitcoin Core v31.1's bitcoind on regtest, offline: it makes each wallet (createwallet, encryptwallet, importdescriptors, getnewaddress with labels, generatetoaddress), says what it holds (listdescriptors and listdescriptors true, getwalletinfo), opens the passphrase (walletpassphrase) and loads or refuses a changed file (loadwallet).

Checked first: Core's release tarball is checked against its pinned SHA-256 (tools/reference/core/release.pin) before every run and the node's version is asked; every wallet.dat is one Core wrote and every answer is one Core gave of the same wallet.

Labels and the block locator (counted by Faraday; Core's address book is asked only for a purpose record Faraday refuses), the records Faraday counts and does not read, and the transactions themselves.

Vectors The three wallet.dat files Core made (tools/vectors/core-wallet/), plain, encrypted and migrated from a legacy wallet by migratewallet (made with the older release of tools/reference/core/legacy.pin), with what Core said of them.

Random cases Fresh wallets of eight shapes (plain, encrypted, watch-only, blank, with labels, with an imported descriptor, with an imported uncompressed key, with imported multisig and miniscript descriptors of keys with an origin and further hardened steps, a bare master key with hardened steps, and a hash before a key), with and without a transaction, each read with the right passphrase, a wrong one and none; and the same files with a byte flipped in a record, a record dropped or pages cut off.

Differences Faraday gives each descriptor as Core lists it (the account key from the walletdescriptorlhcache records, the master key's fingerprint and the hardened path as the origin, checksum included), and the area compares that whole text, with Core's listdescriptors without private keys, for every shape.

Faraday checks what Core does not look at when it loads a wallet: a private key's stored hash and public key, a descriptor's id and checksum, and flags and records Core's loader ignores. A changed file Core loads and Faraday does not call whole is counted, and must name a record and fault of the listed set; nothing is asked of Core there beyond that it loads, except where Core's own reading must show the condition: a purpose record Faraday cannot read (Core lists the address's purpose as unknown), a block locator that does not read as one (Core shows it read no locator from the record), a descriptor's range or next index out of order (Core lists it so, loaded with -keypool=1), and a header text encoding other than the three the file format names (SQLite reads it as UTF-8).

Core reads each transaction record as it loads and refuses a wallet one of which does not read; Faraday counts them. Core derives every index of a descriptor's range, and tops it up to its next index, as it loads; it refuses a descriptor that is not ranged whose stored range spans more than one index (the same script twice), and Faraday refuses it too; Faraday also refuses a range of 1,000,000 indexes or more and a next index of 1,000,000 or more (Core's limit on the size of a range). Past 2^16 the area does not wait for Core's answer (past 2^19 it takes minutes), and Faraday, which derives nothing as it reads, reads such a file whole up to that limit; it is counted where Core did not answer. Each is asked of Core in the prelude.

Core runs SQLite's integrity check when it loads a wallet and refuses a file in which a record's key was changed (the unique index beside the table still holds the old key), and refuses one whose walletdescriptorcache record was dropped; Faraday reads the table only, so it reads such a file whole when the changed key is still a record it accepts. Core also refuses a wallet whose block locator ends in another chain's genesis block, as it attaches the wallet to its node's chain; Faraday reads no chain and does not read the locator's hashes. Each is asked of Core in the prelude.

Faraday refuses a wallet of another network than its mode and a file with a journal, log or lock beside it, which Core opens (and recovers); the area reads regtest wallets with nothing beside them, so neither arises.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 380 cases

Secret handling

none: no secret leaves faraday-keys

Not stated; the stored hash and the public key are compared in constant time (subtle), the padding check is not.

The passphrase, the master key, each opened key and the DER are held in zeroizing buffers and wiped as each is checked.

Limits

Checking only: a wallet's private key is never shown, loaded as a key of the session or written.

A master key with another method than SHA-512 rounds, or more than 10,000,000 rounds, is refused.

Faraday's own calls

none

Add silent payment shares

SpecificationBIP 374 · BIP 375 · BIP 352PublishedCodeLibrary: secp256k1 0.29Library: bitcoin 0.32Library: sha2 0.11 (through core/faraday-crypto)Faraday's code: core/faraday-psbtFaraday's own codeCross-checked withBIP-374/375 authors (bitcoin/bips)Others' code
Action

Adds this signer's ECDH shares and BIP 374 proofs to a silent payments PSBT, and sets the output scripts the shares give.

Specification

BIP 374, Discrete Log Equality Proofs, Draft

BIP 375, Sending Silent Payments with PSBTs, Draft

BIP 352, Silent Payments, Complete, vendored

Code

Library: secp256k1 0.29.1, by the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1).

Library: bitcoin 0.32.102, by the rust-bitcoin developers.

Library: sha2 0.11.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: core/faraday-psbt: BIP 374's proofs are written here (faraday-bip); each share a·B_scan carries a proof that it came from the input's key, every private multiplication going through secp256k1's ecdh; the scripts are set once every eligible input has a share, and signable gives the version 0 PSBT that sign signs.

Written by Faraday

BIP-374 DLEQ proofs and BIP-375's sending fields (faraday-bip::dleq, faraday-psbt::silent) · No established implementation exists

No Rust library implements BIP-374 proofs or BIP-375's PSBT fields.

Decision F178

Checked against

tools/vectors/bip374

Published, by BIP 374's authors (bitcoin/bips).

tools/vectors/bip375

Published, by BIP 375's authors (bitcoin/bips).

tools/vectors/bip352

Published, by BIP 352's authors (bitcoin/bips).

core/faraday-bip/tests/all/dleq.rs::generation_vectors

core/faraday-bip/tests/all/dleq.rs::verification_vectors

core/faraday-bip/tests/all/silent.rs::the_sender_makes_the_outputs_the_vectors_publish

core/faraday-psbt/tests/all/silent.rs::the_signer_adds_the_shares_and_sets_the_scripts_of_every_finished_vector

core/faraday-psbt/tests/all/silent.rs::a_key_that_is_not_the_inputs_is_refused

core/faraday-psbt/tests/all/silent.rs::a_master_key_adds_the_share_its_derived_key_gives

no fuzz target: Not reachable from the app: no outside input reaches it

Cross-check

Compared with others' code: BIP-374/375 authors (bitcoin/bips), and btclib's dleq.py (BIP-374) and btclib-wallet's BIP-375 roles (Signer, Extractor), by the btclib developers, on btclib's own curve: proofs, shares, output scripts and the verdict on a PSBT; btclib-wallet counts a taproot input's NUMS claim only against a proof, so a PSBT with an unproved claim is judged by the validator alone.

Area sps

Faraday's code faraday_psbt::silent, faraday_bip::dleq

Compared with BIP-374's reference.py (bip374/) and BIP-375's validator and test_runner.py (bip375/), over secp256k1lab; btclib's dleq.py and btclib-wallet's BIP-375 roles (btclib/, its own curve) answering beside them.

Checked first: Its vendored files are hashed against references.sha256 before any run, the validator is required to give each of BIP-375's 43 vectors its published verdict and the reference to give each of BIP-374's rows its published answer.

Vectors Both CSV files of tools/vectors/bip374/ and tools/vectors/bip375/bip375_test_vectors.json, each judged by btclib too.

Random cases Proofs made and verified, damaged or not, under two generators; version 2 PSBTs of one to four inputs of every kind BIP-375 reads and some it does not, one to three silent payment outputs, shares added by one signer or two, a global share, and each finished PSBT damaged in one of eighteen ways, judged by the BIP's validator.

Differences BIP-375: Faraday takes a key a PSBT states for a P2PKH, P2SH-P2WPKH or P2WPKH input only where the input's script commits to it (F89); the validator takes the first key stated, so a PSBT it accepts with an unbound key is refused by Faraday.

BIP-375: Faraday accepts the scripts of a scan key's outputs numbered in sorted order of their spend keys, as the BIP's text says, and in output order, as its vectors do; the validator accepts output order only.

BIP-375: Faraday refuses an input whose redeem script is not the one its P2SH script hashes, and one whose previous transaction is not the one spent; the validator reads both fields without checking them.

BIP-375: btclib-wallet takes a taproot input's NUMS internal key as a reason to skip the input only against a proof (a merkle root or a control block that tweaks the NUMS point to the output key), and counts the input otherwise; Faraday and the validator skip on the claim. A PSBT with an unproved claim is not asked of btclib-wallet; the run prints how many PSBTs it judged and how many it was not asked. A proved claim only in a control block, with no internal key set, is not detected: btclib-wallet would skip the input, Faraday would count it, and the run would stop on it. The corpus also makes inputs whose claim is proved, which all three skip.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 800 cases

Secret handling

none: no secret leaves faraday-keys

The output tweak is treated as public and multiplied by ecmult, as libsecp256k1's own silent payments module does.

The secret's bytes and the hashes they pass through are zeroized before return; each private key used is erased before its input is done. The nonce is a SecretScalar, erased when it is dropped, but musig.rs's `match (self.0, other.0)`, `self.0.map` and `self.0.and_then` leave copies of it. SecretKey is Copy, so every add_tweak, mul_tweak and negate copies the key and only the last copy is erased; the earlier copies are left in memory, later work under the security scope (ESTABLISHED §4.1).

Limits

Built in core and not reachable from the app: the device does not send.

An eligible input whose public key the PSBT does not state, a P2SH input with no redeem script and a previous transaction that is not the one spent stop the check.

A SegWit version above 1 and a sighash other than ALL are refused.

Faraday's own calls

A key a PSBT states for an input counts only where the input's script commits to it, which is stricter than BIP 375's reference validator. Conservative, F89.

Spends of SegWit above v1 and sighashes other than ALL are refused. Conservative.

no decision

Read the items inside a vault

SpecificationTOML v1.0.0PublishedCodeLibrary: toml_parser 1.1Library: pem-rfc7468 1.0Library: base16ct 1.0 (through core/faraday-crypto)Faraday's code: faraday/faraday-vaultFaraday's own codeCross-checked withNot cross-checked
Action

Reads the TOML a vault holds into its items: the keys of a QR vault (a seed's words, a codex32 share, a passphrase, a note, or nothing), and the three TOML values a file vault keeps in its custom data (a backup plan, a seed's codex32 facts, its BIP-85 facts). What the Spec does not name is refused: a syntax refusal names the line and every other the key; a value read is written again to the same fields. A file vault's KDBX document is mapped to the records the app reads and back (`kdbx::items`): each Faraday item by its `faraday.kind` in its published text form (BIP-39 words of a list or a seed in hex, a BIP-388 policy or a descriptor, PEM keys and certificates, an armored GPG key, a codex32 string), a person's entry by its six fields, and the database's format, seal count, plans and signed amounts; an item that does not read is named Unreadable, never made a record, and written back as read.

Specification

TOML v1.0.0, TOML, Tom's Obvious Minimal Language, version 1.0.0, Status not checked

Code

Library: toml_parser 1.1.3+spec-1.1.0, by the toml-rs developers.

Library: pem-rfc7468 1.0.0, by the RustCrypto developers.

Library: base16ct 1.0.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: faraday/faraday-vault: The parser alone reads TOML v1.0.0 tokens; the tree, the duplicate rules, the key and size limits of docs/VAULT.md sections 2.1 and 7 and the values' meaning are Faraday's own (`contents.rs`, `contents/tree.rs`). Whatever is outside those rules is refused by name. The KDBX mapping (`kdbx/items/`) is Faraday's own over the document model, faraday-bip's BIP-39, wallet policy, descriptor and codex32 readers, the TOTP reader and pem-rfc7468: the field names, the kinds, the labels of related secrets (several shares of one threshold, identifier, index and key) and the Unreadable items of docs/VAULT.md section 7.

Written by Faraday

The TOML tree inside a vault: duplicates, limits and the names of docs/VAULT.md (faraday-vault::contents) · Only the part used is written

toml_parser reads the tokens; Faraday builds the tree and refuses what VAULT.md does not name, as the JSON visitor does over serde_json.

Decision F189, F190

Checked against

tools/vectors/toml

Published, by toml-test (toml-lang/toml-test), the TOML v1.0.0 cases for tables, inline tables, arrays, keys and strings, which the vault's TOML reader is held to.

faraday/faraday-vault/tests/contents.rs::a_qr_vault_holds_one_item_in_one_length

faraday/faraday-vault/tests/contents.rs::a_qr_vault_refuses_what_it_cannot_hold

faraday/faraday-vault/tests/contents.rs::a_qr_vault_may_hold_a_note_or_nothing

faraday/faraday-vault/tests/contents.rs::a_plan_is_written_and_read_back_with_every_field

faraday/faraday-vault/tests/contents.rs::a_hand_edited_plan_reads_as_the_written_one

faraday/faraday-vault/tests/contents.rs::a_plan_refuses_what_section_7_does_not_name

faraday/faraday-vault/tests/contents.rs::a_codex32_set_is_written_and_read_back

faraday/faraday-vault/tests/contents.rs::a_codex32_set_may_be_written_another_way_and_refuses_what_it_does_not_name

faraday/faraday-vault/tests/contents.rs::a_bip85_origin_is_written_and_read_back

faraday/faraday-vault/tests/contents.rs::a_bip85_origin_refuses_what_it_does_not_name

faraday/faraday-vault/src/contents/tree/toml_test.rs::every_invalid_case_of_toml_test_is_refused

faraday/faraday-vault/src/contents/tree/toml_test.rs::every_valid_case_of_toml_test_is_accepted_but_what_faradays_rules_refuse

faraday/faraday-vault/src/contents/tree/toml_test.rs::a_key_part_over_128_bytes_is_refused

faraday/faraday-vault/tests/kdbx_items.rs::a_vault_of_every_kind_reads_back_to_the_same_records

faraday/faraday-vault/tests/kdbx_items.rs::an_item_is_written_in_its_published_form

faraday/faraday-vault/tests/kdbx_items.rs::a_damaged_item_is_unreadable_and_the_others_read

faraday/faraday-vault/tests/kdbx_items.rs::a_damaged_entry_is_written_back_as_it_was

faraday/faraday-vault/tests/kdbx_items.rs::entries_sharing_a_uuid_are_unreadable

faraday/faraday-vault/tests/kdbx_items.rs::a_newer_format_is_read_only_and_its_items_unreadable

faraday/faraday-vault/tests/kdbx_items.rs::custom_data_that_does_not_read_is_named_and_kept

faraday/faraday-vault/tests/kdbx_items.rs::a_file_pykeepass_wrote_opens_with_its_entry

faraday/faraday-vault/tests/kdbx_items.rs::a_persons_entry_keeps_its_other_fields_across_a_change

faraday/faraday-vault/tests/kdbx_items.rs::an_item_moved_or_renamed_in_a_keepass_app_keeps_its_kind

faraday/faraday-vault/tests/kdbx_items.rs::an_entry_with_two_fields_of_one_key_or_in_a_group_sharing_a_uuid_is_unreadable

faraday/faraday-vault/tests/kdbx_items.rs::another_passphrase_of_a_key_is_kept_unlabelled_and_a_second_share_is_labelled

faraday/faraday-vault/tests/kdbx_items.rs::entries_of_one_key_read_unlabelled_and_of_one_share_index_are_labelled

faraday/faraday-vault/tests/kdbx_items.rs::a_persons_entry_with_a_field_of_any_length_reads_and_keeps_it

faraday/faraday-vault/tests/kdbx_items.rs::a_plan_or_signed_amount_that_does_not_read_is_neither_replaced_nor_removed

fuzz contents

fuzz kdbx_xml

Cross-check

not cross-checked: The TOML syntax is checked against toml-test's published cases for TOML v1.0.0, made by the TOML authors' test suite; the vault's own rules (its keys, limits and values) are Faraday's and are not checked against an outside source. The action is not cross-checked as one, since the KDBX vault's items have no such judge; area qrvault compares the QR form's writer byte for byte and its reader by item, tomllib reading the canonical form the area writes

Secret handling

none: no secret leaves faraday-keys

The reader branches on secret text (a seed's words, a passphrase, a note) while it parses, and so does the KDBX mapping over an item's fields; constant-time parsing is later work (docs/SECURITY-MODEL.md, the security scope).

The text read and the values made from it are held in wiping types (docs/KEYS.md); what toml_parser and the word-list parser keep is not wiped (docs/deps/toml_parser.md). The KDBX mapping's words, seed hex and PEM keys are made in wiping buffers (`kdbx/items/forms.rs`); a GPG key's armored text is held in a wiping string.

Limits

A QR vault is exactly 226 bytes; a plan over 1 MiB, an inline table over its size, a key part of more than 128 bytes, a key path of more than 8 parts and a key outside docs/VAULT.md sections 2.1 and 7 are refused.

A QR vault holds one item, a note of at most QR_NOTE_MAX bytes and a passphrase of at most QR_PASSPHRASE_MAX; more is refused as too long, naming the key.

Faraday's own calls

Nothing about Faraday's items refuses a KDBX file: an item that does not read is named Unreadable, by its title, UUID, field and fault, is never made a record and is written back as read; a faraday.format other than 1 makes the vault read-only (owner, 2026-11-03; docs/VAULT.md section 7). Conservative, F194.

Whatever the Spec's TOML does not name is refused, so a value that adds a key is not read (F190 point 3, docs/VAULT.md section 7). Conservative, F194.

A QR vault's contents are the item's keys at the top of a TOML document, padded to 226 bytes with line feeds (F190 point 5, docs/VAULT.md section 2.1). Neutral, F194.

Seal a QR vault's OpenPGP message

SpecificationRFC 9580 · RFC 7253 · RFC 9106 · 1 morePublishedCodeLibrary: aes 0.9Library: ocb3 0.2Library: argon2 0.6 (through core/faraday-crypto)Faraday's code: faraday/faraday-pgpFaraday's own codeCross-checked withSequoia's sqOthers' codeFaraday's second version
Action

Writes and reads an RFC 9580 message under a passphrase: Argon2id (the Argon2 S2K, 3 passes, 4 lanes) over the passphrase gives a key, HKDF-SHA-256 makes the key that AES-256-OCB wraps the session key with in a version 6 symmetric-key encrypted session key packet, and a version 2 data packet holds one literal data packet in AES-256-OCB chunks under a key HKDF-SHA-256 makes from the session key and a 32-byte salt, with a final tag over the plaintext's length.

Specification

RFC 9580, OpenPGP, Proposed Standard

RFC 7253, The OCB Authenticated-Encryption Algorithm, Informational

RFC 9106, Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications, Informational

RFC 5869, HMAC-based Extract-and-Expand Key Derivation Function (HKDF), Informational

Code

Library: aes 0.9.3, by the RustCrypto developers.

Library: ocb3 0.2.0, by the RustCrypto developers.

Library: argon2 0.6.0, by the RustCrypto developers, through core/faraday-crypto.

Faraday's code: faraday/faraday-pgp: Only the part used is written: the version 6 symmetric-key packet with the Argon2 S2K and the version 2 data packet, both AES-256 and OCB, and the one literal data packet, in any length form RFC 9580 allows. The Argon2 cost is checked against the limits right after the key packet, before the data packet is read or any Argon2 memory is taken, padding packets are ignored, every tag is checked before plaintext is returned, and every other packet, version, algorithm or trailing byte is named and not opened. HKDF-SHA-256 is Faraday's own (`faraday-crypto`); Argon2id, AES and OCB are the RustCrypto crates.

Written by Faraday

HKDF-SHA256, one copy (faraday-crypto::hash) · One exists but does not fit Faraday's rules for keys

The Rust HKDF library leaves the pseudorandom key and its output blocks unwiped; Faraday's holds both in buffers it wipes.

Does not fit: hkdf 0.13.0 returns the pseudorandom key and leaves each output block T(i) in plain arrays it does not wipe

Decision F180

The QR vault's OpenPGP message: the version 6 symmetric-key packet with the Argon2 S2K, the version 2 data packet and the literal data packet (faraday-pgp::message) · Only the part used is written

Faraday writes only the three packets a QR vault uses, over argon2, aes and ocb3 and Faraday's HKDF; rPGP, which no review Faraday trusts covers, brings every OpenPGP algorithm.

Decision F190

Checked against

tools/vectors/openpgp

Published, by RFC 9580 Appendix A (A.10, the version 6 symmetric-key session key and the version 2 data packet with AES-128 and OCB; A.12.3, the Argon2 S2K with AES-256), made by the RFC's authors.

faraday/faraday-pgp/src/message/tests.rs::the_rfc_session_key_is_unwrapped_and_wrapped_again

faraday/faraday-pgp/src/message/tests.rs::the_rfc_data_packet_is_decrypted_and_encrypted_again

faraday/faraday-pgp/src/message/tests.rs::a_vault_is_396_bytes_and_opens_to_what_it_holds

faraday/faraday-pgp/src/message/tests.rs::the_packets_are_the_ones_the_spec_names

faraday/faraday-pgp/src/message/tests.rs::a_wrong_passphrase_is_named

faraday/faraday-pgp/src/message/tests.rs::a_changed_byte_in_the_data_is_refused

faraday/faraday-pgp/src/message/tests.rs::a_cost_outside_the_limits_is_refused_before_anything_runs

faraday/faraday-pgp/src/message/tests.rs::another_openpgp_message_is_named

faraday/faraday-pgp/src/message/tests.rs::every_length_form_is_read

faraday/faraday-pgp/src/message/tests.rs::padding_packets_are_ignored

faraday/faraday-pgp/src/message/tests.rs::the_rfc_plaintext_with_its_padding_is_read

faraday/faraday-pgp/src/message/tests.rs::what_else_is_in_the_plaintext_is_named

faraday/faraday-pgp/src/message/tests.rs::a_compressed_first_packet_in_partial_lengths_is_named

fuzz pgp_qr_vault

Cross-check

Compared with others' code: Sequoia's sq, by the Sequoia PGP developers (judges the primitives except Argon2, which it shares with the app's lineage, and opens Faraday's messages), rPGP, by the rPGP developers (judges the format only, on the app's lineage: opens Faraday's messages and seals the ones Faraday opens), and PyCA cryptography over OpenSSL (judges Argon2id, HKDF-SHA-256 and AES-256-OCB).

Compared, for one part, with Faraday's second version, written by Faraday's authors in Python; that part is not checked against an outside source: the OpenPGP framing around PyCA's primitives, read and written strictly in area_qrvault.py from RFC 9580 and docs/VAULT.md §1.2, and the QR TOML (qr_toml) from §2.1, read beside by CPython's tomllib; Faraday's second version of the framing, not another program's.

Area qrvault

Faraday's code faraday_vault::qr (the QR vault sealed and opened, with faraday_pgp::message)

Compared with Sequoia's sq, the distribution's package, over Nettle (judges the primitives except Argon2, which it shares with the app's lineage); rPGP (tools/crosscheck/rpgp/, a program outside the workspace, on RustCrypto like the app: judges the format only); PyCA cryptography's Argon2id, HKDF-SHA-256 and AES-256-OCB (OpenSSL's), which judge the primitives, under the OpenPGP framing written in the area from RFC 9580 and docs/VAULT.md §1.2 (Faraday's second version, not another program's); the QR TOML qr_toml written in the area from §2.1, each opened item also read by CPython's tomllib.

Checked first: Sq is the distribution's package, built over Nettle (the run stops otherwise, judges.py), its version written into the stamp; rPGP is built from the crates.io release tools/crosscheck/rpgp/Cargo.lock names; PyCA must be 44 or later over OpenSSL 3.2 or later or the area stops, and its Argon2id, HKDF-SHA-256 and AES-OCB are checked against the repository's Argon2id known answer, RFC 5869 test case 1 and RFC 7253's first vector first; sq and rPGP open the repository's vault vectors, and so does the PyCA judge, which reads strictly and refuses anything but a QR vault.

OpenPGP.js, which docs/VAULT.md §10 names, is not run; sq does not seal a QR vault (below); rPGP judges the format only. §1.2's wider reading, which only Faraday's reader is held to, is not compared with a judge: any literal date, padding packets after the SEIPD packet and the literal data, and every length form RFC 9580 allows; of the chunk size octets only 0 (rPGP seals several chunks, Faraday opens them) and 10 are run.

Vectors The seven vaults of tools/vectors/vault/qr/ opened by sq, rPGP and the PyCA judge to the item each holds and by Faraday; the four refused messages refused by Faraday and by the PyCA judge; the PyCA judge refuses a vector with a byte changed in each field.

Random cases An item of every kind of §2.1 (12 and 24 words, a codex32 share, a passphrase, a note with markup, control characters and several scripts, the empty vault) sealed by Faraday and opened by sq, rPGP, the PyCA judge and Faraday, and sealed by rPGP and by the PyCA judge (memory 2^13 to 2^16 KiB) and opened by Faraday, each opened item read by tomllib; each memory step of §3 (2^16 to 2^20 KiB) sealed by Faraday at scale 1, each message equal byte for byte to the PyCA judge's seal of the same random bytes; items at the size limits (a note of 216 and 217 bytes, a passphrase of 193 and 194, a 24-word seed of the longest words); a passphrase in NFD or NFC either way; a wrong passphrase; a 15-word seed and a document of two keys sealed by rPGP, refused by Faraday; the messages sq writes, refused by Faraday and the PyCA judge; two items sealed by rPGP in chunks of 64 bytes (chunk size octet 0), opened by Faraday.

Differences QR vault: sq 1.3.1 writes a SKESK v4 and a SEIPD v1 for a password under either --profile, never the SKESK v6 and SEIPD v2 of RFC 9580, so sq cannot seal a QR vault; rPGP and the PyCA judge seal the other direction, and the area asserts that Faraday and the PyCA judge refuse what sq writes. The PyCA judge's framing is the area's own Python; OpenPGP.js is not run.

When it runs Before every release, with a new seed and about ten times the cases.

Last passing run Seed 5be11ec606a76d2767f225b8992c45fe · 450 cases

Secret handling

none: no secret leaves faraday-keys

The tags are compared in constant time by the ocb3 crate; Argon2id, HKDF and AES state nothing more.

The Argon2 output, the wrapping key, the session key, the message key and the opened plaintext are Zeroizing values wiped on drop; the Argon2 memory is overwritten after the run.

Limits

A SKESK v4, a SEIPD v1, a public-key encrypted session key, a second SKESK, compressed data, a signature and trailing data but padding are named "An OpenPGP message Faraday does not open".

Argon2 memory 8 MiB to 1 GiB, passes 1 to 100 and lanes 1 to 64; outside them the message is refused right after the key packet, before the data packet is read or any memory is taken; a QR vault is written at 64 MiB to 1 GiB.

A wrong passphrase is told from a changed message: the session key's tag fails for the first, a data tag for the second.

The passphrase arrives in Unicode NFC; the caller puts it there.

Faraday's own calls

Only AES-256 with OCB and the Argon2 S2K are read: another cipher, AEAD mode or S2K is refused, as are armor and every packet but the three (F178, F190). Conservative, F190.

Libraries

The 36 libraries others wrote that the actions use, each with its version in Faraday's Cargo.lock, its author and the actions that use it.

LibraryVersionAuthorActions
aes0.9.3the RustCrypto developersSeal and open Krux codes, Read an aezeed, Check Core wallet keys, Seal a QR vault's OpenPGP message, Seal and open KDBX
aes-gcm0.11.1the RustCrypto developersSeal and open Krux codes
argon20.6.0the RustCrypto developersRead a Core Lightning hsm_secret, Make a vault, Open a vault, Seal a QR vault's OpenPGP message, Seal and open KDBX, Write a vault back, Write a KeePass database, Run the start-up self-test
base16ct1.0.0the RustCrypto developersMake the master key, Show the master seed, Convert a key's master seed, Read and write a descriptor, Build a recovery wallet, Read a wallet export, Read BSMS records, Compile a spending policy, Aggregate MuSig2 keys, Pack coins and hex, Hash and encode text, Derive a child seed, Derive a Lightning key, Receive silent payments, Review what a PSBT pays, Sign with MuSig2, Check a PSBT's signatures, Read a transaction, Split and join BBQr parts, Wrap a file in an envelope, Hash a file, Read the items inside a vault, Compute a TOTP code, Write the GPG key as paperkey, Restore a GPG key, Run the start-up self-test
base64ct1.8.3the RustCrypto developersRead BSMS records, Derive a child seed, Read a PSBT, Seal and open KDBX, Write a KeePass database, Make a GPG key, Sign with the GPG key, Make a revocation certificate, Restore a GPG key, Check a GPG signature
bitcoin0.32.102the rust-bitcoin developersMake the master key, Derive a child key, Show an address's private key, Read a WIF private key, Derive a cosigner account, Derive an address, Read and write a descriptor, Build a recovery wallet, Read taproot multisig, Read a wallet export, Read BSMS records, Aggregate MuSig2 keys, Write an xpub spelling, Read an address, Recognise a secret in a file, Hash and encode text, Derive a child seed, Grind a vanity address, Derive a Lightning key, Read a Lightning invoice, Read a Lightning offer, Receive silent payments, Add silent payment shares, Read a PSBT, Read a version 2 PSBT, Review what a PSBT pays, Review the sighash types, Sign with ECDSA, Sign a WIF key's sweep, Sign with Schnorr, Sign with MuSig2, Check a PSBT's signatures, Compare PSBTs and the fee bump, Finalize a transaction, Sign a message, Check a signed message, Read a transaction, Make and read QR codes, Write and read UR codes, Wrap a file in an envelope, Run the start-up self-test
bitcoin_hashes0.14.101the rust-bitcoin developersKeep the session's randomness
blake20.11.0the RustCrypto developersRead an aezeed
cbc0.2.1the RustCrypto developersSeal and open Krux codes, Check Core wallet keys, Seal and open KDBX
chacha200.10.2the RustCrypto developersRead a Core Lightning hsm_secret, Make a vault, Open a vault, Seal and open KDBX, Write a vault back, Write a KeePass database, Make Secure Boot keys
ctr0.10.1the RustCrypto developersSeal and open Krux codes
der0.8.2the RustCrypto developersMake Secure Boot keys, Sign a boot program, Check a boot signature
ed25519-dalek3.0.0the dalek-cryptography developersMake a GPG key, Sign with the GPG key, Make a revocation certificate, Write the GPG key as paperkey, Restore a GPG key, Check a GPG signature
getrandom0.3.4 and 0.4.3the Rand Project developersRead the system's randomness, Write an image to a stick
hmac0.13.0the RustCrypto developersMake the master key, Read a WIF private key, Seal and open Krux codes, Split with SLIP-39, Hash and authenticate bytes, Derive keys with HKDF, Derive a child seed, Read a Core Lightning hsm_secret, Sign with Schnorr, Sign with MuSig2, Sign a message, Make a vault, Open a vault, Seal and open KDBX, Write a vault back, Write a KeePass database, Compute a TOTP code, Run the start-up self-test
lzma-rust20.22.0hasenbanck (lzma-rust2), a port of the Tukaani project's XZ for JavaWrite an image to a stick
miniscript12.3.7the rust-bitcoin developers (rust-miniscript)Derive an address, Read and write a descriptor, Build a recovery wallet, Read taproot multisig, Compile a spending policy, Read a PSBT, Review what a PSBT pays, Finalize a transaction
miniz_oxide0.8.9 and 0.9.1the miniz_oxide developers, a port of Rich Geldreich's minizSeal and open Krux codes, Seal and open KDBX
ocb30.2.0the RustCrypto developersSeal a QR vault's OpenPGP message
pbkdf20.13.0the RustCrypto developersMake the seed, Hash and authenticate bytes
pem-rfc74681.0.0the RustCrypto developersRead the items inside a vault
poly13050.9.1the RustCrypto developersRead a Core Lightning hsm_secret
quick-xml0.41.0the quick-xml developersSeal and open KDBX
rand_core0.10.1the Rand Project developersMake Secure Boot keys
ripemd0.2.0the RustCrypto developersCheck a timestamp
rqrr0.11.0WanzenBug (rust-qr-reader), as copied into third_party/rqrr with the changes third_party/rqrr/PATCHES.md listsMake and read QR codes
rsa0.10.0-rc.18the RustCrypto developersMake Secure Boot keys, Sign a boot program, Check a boot signature, Check a signed boot file
secp256k10.29.1the rust-bitcoin developers (rust-secp256k1), over libsecp256k1, by Bitcoin Core's libsecp256k1 project (bitcoin-core/secp256k1)Make the master key, Derive a child key, Hold a key in memory, Read a WIF private key, Derive an address, Read BSMS records, Aggregate MuSig2 keys, Grind a vanity address, Derive a Lightning key, Receive silent payments, Add silent payment shares, Sign with ECDSA, Sign a WIF key's sweep, Sign with Schnorr, Sign with MuSig2, Check a PSBT's signatures, Sign a message, Check a signed message
serde_json1.0.151David TolnayRead a wallet export
sha10.11.0the RustCrypto developersCheck a timestamp, Compute a TOTP code, Make a GPG key, Make a revocation certificate, Write the GPG key as paperkey, Restore a GPG key, Check a GPG signature
sha20.11.0the RustCrypto developersRead the words, Make the words, Make the seed, Make the master key, Read a WIF private key, Compare two keys' words, Aggregate MuSig2 keys, Turn dice into entropy, Pack coins and hex, Turn cards into entropy, Turn the camera into entropy, Record pointer and keys, Mix entropy sources, Take the device's entropy, Make a SeedQR, Seal and open Krux codes, Split with SLIP-39, Split with Seed XOR, Recognise a secret in a file, Hash and authenticate bytes, Hash and encode text, Derive a child seed, Check Core wallet keys, Check a timestamp, Receive silent payments, Add silent payment shares, Read a PSBT, Review what a PSBT pays, Sign with Schnorr, Sign with MuSig2, Sign a message, Write and read UR codes, Hash a file, Make a vault, Open a vault, Seal and open KDBX, Write a vault back, Reveal a vault secret, Load a key from a vault, Write a KeePass database, Compute a TOTP code, Make a GPG key, Sign with the GPG key, Make a revocation certificate, Write the GPG key as paperkey, Restore a GPG key, Check a GPG signature, Make Secure Boot keys, Sign a boot program, Check a boot signature, Run the start-up self-test, Write an image to a stick, Check a signed boot file
sha30.11.0the RustCrypto developersCheck a timestamp
subtle2.6.1the dalek-cryptography developersHold a key in memory, Convert a typed SLIP-39 set
toml_parser1.1.3+spec-1.1.0the toml-rs developersRead the items inside a vault
unicode-normalization0.1.25the unicode-rs developersRead the words, Compare two keys' words, Make a SeedQR, Check a SeedQR, Split with Seed XOR, Recognise a secret in a file, Make a vault, Open a vault, Load a key from a vault, Run the start-up self-test
x509-cert0.3.0the RustCrypto developersMake Secure Boot keys, Sign a boot program, Check a boot signature

What Faraday writes itself

The 43 pieces of code Faraday's authors wrote rather than took from a library, in four lists by reason, each with the action that uses it and the decision that accepts it.

Faraday's own specification

The format or procedure is Faraday's, so nothing outside can implement it. 5 pieces.

PieceActionNoteDecision
BIP-39 entry and display: words typed by pinyin, zhuyin, kana or hangul, the last word's candidates, the explorer's view of the checksum (faraday-bip::bip39)Read the wordsHow a person types and sees the words is Faraday's own.F178
Dice, coin, card, hex and camera entropy accumulation and packing, and the mix of sources (faraday-entropy)Turn dice into entropyFaraday's own procedures over SHA-256; the card, camera and mix procedures are labelled as not yet reviewed outside Faraday.F178
The session's random generator: its seed and pool, and the mixing of a person's own randomness (faraday-core::fresh)Keep the session's randomnessFaraday's own procedure over SHA-256, labelled as not yet reviewed outside Faraday.F178
PSBT inspection, signing orchestration and verification logic (faraday-psbt)Read a PSBTWhat Faraday checks before it signs is Faraday's own rule; the PSBT format itself is rust-bitcoin's.F178
The choice among a script's satisfactions by real signature size (faraday-psbt::finalize)Finalize a transactionFor a miniscript Faraday picks the smallest witness as Bitcoin Core's finalizepsbt does; a plain multisig carries the first m signers' signatures, as Core writes them; miniscript builds and checks each witness.F178

No established implementation exists

No library that is established has it. 22 pieces.

PieceActionNoteDecision
WipeOnFree, the allocator that wipes what it frees (faraday-crypto::wipe)Hold a key in memoryNo wiping allocator comes from a publisher Faraday's dependency review trusts; this one is installed in no shipped program (F181).F180
BIP-327 MuSig2, with BIP-328 and BIP-390 (faraday-bip::musig)Aggregate MuSig2 keyslibsecp256k1's MuSig2 is in rust-secp256k1 0.32 and later; bitcoin 0.32, which Faraday uses, is on 0.29, and no miniscript release builds on bitcoin 0.33 yet.F178
SeedQR (faraday-codec::seedqr)Make a SeedQRNo Rust library implements SeedQR.
Carries a format; it computes nothing on a key.
F178
SLIP-39 Shamir backup (faraday-bip::slip39)Split with SLIP-39No maintained Rust implementation of SLIP-39 exists.F178
FAT16 and FAT32, read and written (faraday-fat)Write a backup stick fileNo FAT library comes from a publisher Faraday's dependency review trusts.
Carries a format; it computes nothing on a key.
F180
AEZ v5 and aezeed, with aezeed's CRC-32C (faraday-bip::aez, faraday-bip::aezeed)Read an aezeedNo maintained Rust implementation of AEZ exists; Faraday's follows the Go code LND uses and is tested against LND's vectors. Its AES round is the aes crate's and its BLAKE2b the blake2 crate's.F178
libsodium's crypto_secretstream_xchacha20poly1305 pull of one message (faraday-keys::hsm_secret)Read a Core Lightning hsm_secretNo maintained Rust crate offers libsodium's secretstream; Faraday's is HChaCha20, ChaCha20 and Poly1305 of RustCrypto's crates, and is tested against a file libsodium sealed and against libsodium itself.F228
Bitcoin Core's key from a passphrase and the opening of its encrypted keys (faraday-keys::core_wallet)Check Core wallet keysNo maintained Rust crate offers Bitcoin Core's BytesToKeySHA512AES and DecryptSecret; Faraday's is SHA-512 rounds over faraday-crypto and RustCrypto's aes and cbc, tested against wallets Bitcoin Core made.F229
OpenTimestamps proof reader and walk (faraday-ots)Check a timestampNo Rust implementation of the OpenTimestamps proof format is established; Faraday's follows python-opentimestamps and is tested against that project's example proofs.F230
BIP-352 silent payments (faraday-bip::silent)Receive silent paymentslibsecp256k1's silent payments module is not yet in its Rust bindings.F178
BIP-374 DLEQ proofs and BIP-375's sending fields (faraday-bip::dleq, faraday-psbt::silent)Add silent payment sharesNo Rust library implements BIP-374 proofs or BIP-375's PSBT fields.F178
The PSBT version 2 reader (faraday-psbt::v2)Read a version 2 PSBTrust-bitcoin reads only version 0 PSBTs; its version 2 crate is pre-release.F178
BIP-322 "simple" message signatures (faraday-psbt::message)Sign a messageThe bip322 crate is pre-release.F178
The QR encoder, a port of Nayuki's qrcodegen, with its GF(256) and Reed-Solomon (faraday-codec::qr)Make and read QR codesNo QR encoder comes from a publisher Faraday's dependency review trusts; Faraday's port of Nayuki's code wipes a SeedQR's buffers.
Carries a format; it computes nothing on a key.
F178
BC-UR, with its CBOR (faraday-codec::ur, faraday-codec::cbor)Write and read UR codesNo library for this format comes from a publisher Faraday's dependency review trusts.
Carries a format; it computes nothing on a key.
F178
CRC-32 (faraday-crypto::crc32)Write and read UR codesThe CRC-32 crate in the tree, crc32fast 1.5.1, is not covered by an outside review at that version; Faraday's is a branch-free loop checked against the published check values.
Carries a format; it computes nothing on a key.
F180
BBQr (faraday-qr::bbqr)Split and join BBQr partsNo library for this format comes from a publisher Faraday's dependency review trusts.
Carries a format; it computes nothing on a key.
F178
CMS SignedData, Authenticode's image hash and signature, EFI signature lists and .auth files (faraday-sb)Make Secure Boot keysNo library writes Authenticode signatures or EFI signature lists; the CMS crate for the DER version Faraday uses is a release candidate.F178
The FAT32 formatter for the Starter's data partition (faraday-fat::format)Write an image to a stickNo FAT library comes from a publisher Faraday's dependency review trusts; the partition it makes is checked by dosfstools' fsck.fat, against what mkfs.fat makes.
Carries a format; it computes nothing on a key.
F180
GPT and MBR tables, read and rewritten (faraday-starter-shell::gpt, faraday-starter-shell::ids)Write an image to a stickNo partition-table library comes from a publisher Faraday's dependency review trusts.
Carries a format; it computes nothing on a key.
F180
The plist reader for the disk tool's output (faraday/shells/starter)Write an image to a stickNo plist library comes from a publisher Faraday's dependency review trusts.
Carries a format; it computes nothing on a key.
F180
The PDF writer (faraday-core::pdf, faraday-starter::sheets)Read a BitLocker recovery keyNo PDF library comes from a publisher Faraday's dependency review trusts.
Carries a format; it computes nothing on a key.
F180

One exists but does not fit Faraday's rules for keys

A library has it, but it fails a rule for handling keys. 6 pieces.

PieceActionNoteDecision
BIP-39 mnemonics: entropy to words and back, the checksum, a word's place in its list (faraday-bip::bip39)Read the wordsThe Rust BIP-39 library's word lookup takes a time that follows the secret words; Faraday's looks each word up in constant time and is tested against that library and the reference.
Does not fit: bip39 2.2.2 finds a word by a binary search or a scan that stops at it (find_word) and packs entropy with a branch on each bit (from_entropy_in), so the time it takes follows the secret words
F180
The BIP-39 seed, PBKDF2-HMAC-SHA512 over the sentence through faraday-crypto (faraday-bip::bip39)Make the seedThe seed is derived with the RustCrypto PBKDF2 Faraday uses everywhere, into a buffer that is wiped.
Does not fit: bip39's to_seed returns the seed as a plain [u8; 64], and its own PBKDF2 leaves its HMAC state unwiped (bip39 2.2.2's src/pbkdf2.rs)
F178
The PNG writer, with zlib's stored blocks (faraday-codec::png)Make a SeedQRFaraday writes a SeedQR's picture in buffers it wipes; its Adler-32 is the adler2 crate's.
Does not fit: png 0.18.1 needs std, which faraday-codec does not have, and does not wipe a picture's rows
Carries a format; it computes nothing on a key.
F180
BIP 93 codex32 (faraday-bip::codex32)Work with codex32 stringsThe reference library keeps the seed in text that is never wiped and needs a full operating system.
Does not fit: codex32 0.1.0 holds the seed in a String that is Clone and Debug and never wiped, which tools/lint-secrets.sh refuses, and needs std, which faraday-bip does not have
F178
scrypt (faraday-crypto::scrypt)Stretch a password with scryptThe Rust scrypt library leaves its passphrase-derived working memory unwiped; Faraday's wipes it.
Does not fit: scrypt 0.12.0 frees its passphrase-derived working buffers (b, v, t) without wiping them
F178
HKDF-SHA256, one copy (faraday-crypto::hash)Seal a QR vault's OpenPGP messageThe Rust HKDF library leaves the pseudorandom key and its output blocks unwiped; Faraday's holds both in buffers it wipes.
Does not fit: hkdf 0.13.0 returns the pseudorandom key and leaves each output block T(i) in plain arrays it does not wipe
F180

Only the part used is written

A few lines of a standard over primitives that are established. 10 pieces.

PieceActionNoteDecision
The JSON visitor that refuses a key named twice and counts depth (faraday-bip::json)Read a wallet exportserde_json reads the text; Faraday refuses a key named twice and a nesting deeper than 32.F180
A 32-byte hash reduced modulo the curve order, without a branch (faraday-bip::musig)Aggregate MuSig2 keyslibsecp256k1's Rust bindings take a scalar only below the order and offer no reduction; Faraday's is a single conditional subtraction.F178
KEF: the envelope, the version table, padding, the two SHA-256 checks and base43 (faraday-codec::kef, faraday-kef), and PBKDF2's loop over HMAC-SHA-256 for one block, with a cancel check (faraday-crypto::hash)Seal and open Krux codesNo library reads or writes this format. The pbkdf2 crate is one call that cannot stop, and a count of 100 million rounds must be stoppable.F219
Seed XOR (faraday-entropy::xor)Split with Seed XORFaraday writes only the few lines the standard needs, over standard XOR.F178
The TOML tree inside a vault: duplicates, limits and the names of docs/VAULT.md (faraday-vault::contents)Read the items inside a vaulttoml_parser reads the tokens; Faraday builds the tree and refuses what VAULT.md does not name, as the JSON visitor does over serde_json.F189, F190
The QR vault's OpenPGP message: the version 6 symmetric-key packet with the Argon2 S2K, the version 2 data packet and the literal data packet (faraday-pgp::message)Seal a QR vault's OpenPGP messageFaraday writes only the three packets a QR vault uses, over argon2, aes and ocb3 and Faraday's HKDF; rPGP, which no review Faraday trusts covers, brings every OpenPGP algorithm.F190
The KDBX 4 container a file vault is: header, VariantDictionary, HMAC block stream, inner header and gzip framing (faraday-vault::kdbx)Seal and open KDBXFaraday writes only the part of KeePass's format the vault uses, over argon2, chacha20, aes and cbc, hmac, sha2 and miniz_oxide; keepass-rs, which no review Faraday trusts covers, drops the XML elements it does not read and draws a save's randomness itself.F190
TOTP code derivation (faraday-vault::totp)Compute a TOTP codeFaraday writes only the few lines RFC 6238 needs, over standard HMAC.F178
OpenPGP v4 packets for one key shape, the armour's CRC-24, and the paperkey format (faraday-pgp)Make a GPG keyFaraday writes only the packets of its one key shape, over Ed25519 from dalek and SHA-1/SHA-2 from RustCrypto, each judged by GnuPG and paperkey; the armour's base64 is the base64ct crate's.F178
The form of a version 4 UUID (faraday-starter-shell::ids)Write an image to a stickFour lines setting RFC 9562's version and variant bits over bytes from getrandom.
Carries a format; it computes nothing on a key.
F180

Libraries that are not established

The 3 libraries the actions use that are not established, each with the reason it is used and the decision that accepts it.

LibraryReasonDecision
lzma-rust2The Starter's xz decoder. No established pure-Rust streaming xz decoder exists, and the Starter's design (docs/STARTER.md) rules out the C library liblzma; what it writes is checked against the signed manifest's SHA-256 and size.F180
rqrrThe camera's QR decoder, vendored and patched against panics on hostile frames (third_party/rqrr/PATCHES.md): the only maintained pure-Rust QR decoder. What it reads is untrusted input that Faraday's parsers check. The same panic is reported upstream as rqrr's issue 54.F180
quick-xmlThe tokenizer under the XML of a KDBX vault file. It does no cryptography and has no outside review; its default features are off and it is already in the dependency graph. Which references are refused, the nesting cap and everything else the reader does are Faraday's own.F213

Contents

Buy me a coffee

Donations to Faraday's development, in bitcoin.

QR code to come
Lightning
QR code to come
Bitcoin