death.box Memo Format v1
This specification is enough to decrypt death.box messages without the death.box website.
Download
Download SPEC.md917a20ebfa07674b93914710571b5cedd1f074ed4edd67f65cd86070b0528c2fOverview
| Element | Value |
|---|---|
| Cipher | AES-256-GCM (WebCrypto AES-GCM, 256-bit key) |
| Key derivation | PBKDF2, hash SHA-256, 250000 iterations, 256-bit output |
| Passphrase | UTF-8 bytes of the entered passphrase (see note on Unicode normalization) |
| Salt | 16 random bytes per message |
| IV / nonce | 12 random bytes per message |
| Auth tag | 16 bytes (128 bits), appended to the ciphertext by WebCrypto |
| Additional authenticated data (AAD) | none |
| Plaintext | UTF-8 encoded JSON: {"message":"..."} |
Binary layout
bytes 0..15 salt (16 bytes)
bytes 16..27 IV (12 bytes)
bytes 28..end ciphertext; the last 16 bytes are the GCM auth tag
Text format (memo)
"death.box:v1:" + Base64(salt || IV || ciphertext+tag)
Base64 uses the standard alphabet with = padding (not Base64url).
On the XRP Ledger
The memo is stored in the transaction's MemoData field. The XRPL stores MemoData as a hex string: the UTF-8 bytes of the text format above, hex-encoded. To read a message:
- Convert MemoData (hex) to bytes and read them as UTF-8. The result is
death.box:v1:<Base64>. - Strip the
death.box:v1:prefix and Base64-decode the rest. - Split into salt, IV and ciphertext according to the binary layout.
- Derive the key with PBKDF2 from the passphrase and salt.
- Decrypt with AES-256-GCM and parse the plaintext as JSON.
The website accepts three input forms when reading: hex MemoData, text with the prefix, and bare Base64 data. The bundled decrypt.html behaves the same way.
Notes
- A wrong passphrase and a damaged memo cannot be told apart: GCM reports an authentication failure in both cases.
- In v1 the passphrase is not Unicode-normalized: the exact bytes as typed are used. Characters such as "ü" can be entered either as one code point (NFC) or as "u" plus a combining accent (NFD), which produce different keys. When decrypting, also try
passphrase.normalize('NFC')andpassphrase.normalize('NFD').decrypt.htmldoes this automatically. - The passphrase is not stored anywhere. Without it there is no recovery.
- If the format ever changes, it will get a new prefix (
death.box:v2:). Existing v1 memos remain readable with this specification.
Test vector
Passphrase: correct horse battery staple
Salt: bytes 1 to 16 (01 02 … 10), IV: bytes 101 to 112 (65 66 … 70)
Plaintext:
{"message":"Hello from the future – death.box test message ✓"}
Memo (text):
death.box:v1:AQIDBAUGBwgJCgsMDQ4PEGVmZ2hpamtsbW5vcKNuFkQ0Wourx8UGY5poYm7R3KRS8k3zcwrtI49Rig4BiTEg7WRxH2cB60ZsZ+Yr67fKteqMt7qLpP74xF9CdQMRMhD8i/J5DgxGMW6aKFTfjUg=
MemoData (hex, as stored on the XRPL):
64656174682E626F783A76313A41514944424155474277674A4367734D445134504547566D5A326870616D747362573576634B4E75466B5130576F7572783855475935706F596D3752334B5253386B337A63777274493439526967344269544567375752784832634236305A735A2B59723637664B7465714D7437714C705037347846394364514D524D684438692F4A35446778474D5736614B4654666A55673D
If your implementation turns this memo and passphrase back into the plaintext above, it is correct.