The user enters a seed phrase, a benefactor key, and a
beneficiary key.
The benefactor and beneficiary keys are joined — with an
untypeable 0x1F separator between them — to
form a single combined password, which PBKDF2 stretches
into one AES-256 key. Both halves are required to decrypt,
and the order must match. To be clear about what this is:
it is one password split into two parts, not threshold
cryptography or secret-sharing — "neither key alone
decrypts" is a property of any split password. The
separator keeps the boundary unambiguous:
"ab" + "c" and "a" + "bc"
derive different keys.
Each key is canonicalized before use, on both encrypt and
decrypt: curly quotes become straight quotes, tabs, line
breaks and no-break spaces become spaces, repeated spaces
collapse to one, and leading/trailing spaces are dropped.
Keys must then be non-empty printable ASCII (what a
standard US keyboard, and the SeedSigner keyboard, can
type). Anything else is refused at encryption time, so a
key can always be retyped exactly by an heir.
The seed phrase must be a valid 12- or 24-word BIP-39
mnemonic, checksum included. It is stored as lowercase
words separated by single spaces.
Key Derivation:
A random salt (16 bytes) is generated using
window.crypto.getRandomValues().
The combined key and salt are used in the deriveKey()
function, which employs PBKDF2 (Password-Based Key
Derivation Function 2) to derive a 256-bit AES key.
PBKDF2 is configured with:
600,000 iterations
SHA-256 as the hashing algorithm
The resulting AES key is suitable for AES-GCM encryption
(Advanced Encryption Standard - Galois/Counter Mode)
Encryption Process:
A random Initialization Vector (IV) of 12 bytes is
generated using window.crypto.getRandomValues().
The seed phrase is encoded into a Uint8Array using a
TextEncoder.
AES-GCM encryption is performed using
window.crypto.subtle.encrypt():
Algorithm: AES-GCM
Key: Derived AES key from PBKDF2
IV: Randomly generated IV
Plaintext: Encoded seed phrase
Data Formatting:
Before encryption, the plaintext is laid out as one
byte holding the padding length (0–4), then the seed
phrase, then that many random padding bytes.
The output is the 16-byte salt, the 12-byte IV and the
AES-GCM ciphertext (including its 16-byte
authentication tag), concatenated and
base64url-encoded (URL/filename-safe,
trailing = stripped).
All parameters (PBKDF2-SHA256, 600,000 iterations,
AES-256-GCM) are fixed by the format, so nothing about
them is stored.
Output:
A single string:
base64url(salt || iv || ciphertext)
Every visible byte is random. There is no prefix,
version number or fixed header, so an encrypted seed
phrase cannot be recognized as Legacy-generated. Whoever
holds it needs to know what it is.
This is the only Legacy format. Before handing out a
payload, the encryptor parses it back and decrypts it,
and only releases it if it yields exactly the seed
phrase. The full specification and published test
vectors are in
PROTOCOL-SPEC.md.
Summary of Functions:
canonicalizeKey(key): Applies the key rules above, or
rejects the key.
seedPhraseError(seed): Validates a 12/24-word BIP-39
mnemonic, including its checksum.
parsePayload(payload): Rejects anything that cannot be a
Legacy payload (wrong characters or length) before any
key derivation.
encryptSeedPhrase(seed, benefactorKey, beneficiaryKey):
Validates the inputs, derives the key with PBKDF2,
encrypts with AES-256-GCM, then self-checks the result.
decryptSeedPhrase(payload, benefactorKey, beneficiaryKey):
The reverse; the result must be a valid seed phrase.
Security Considerations:
AES-GCM: This is a modern, authenticated encryption
mode, providing both confidentiality and integrity.
PBKDF2: Using PBKDF2 with a high iteration count
(600,000) strengthens the key derivation process against
brute-force attacks.
Random Salt and IV: Using random salts and IVs is
crucial for the security of the encryption scheme.
Base64 Encoding: Base64 encoding is used for
representing binary data as strings but does not provide
any encryption.
Key Management: The security of this system relies
heavily on the secrecy and strength of the benefactor
and beneficiary keys.
Honest framing of the "dual key": the two keys are simply
the two halves of one password. This is not Shamir secret
sharing, a 2-of-2 multisig, or threshold cryptography —
it provides no cryptographic guarantee beyond "you need
the whole password." Its value is operational (two people
each hold a part, neither can act alone), not a stronger
cipher. If you want on-chain, enforced inheritance,
Bitcoin multisig and timelocks are the right tools; this
is a simpler, offline, off-chain alternative.