death.box Memo Format v1

This specification is enough to decrypt death.box messages without the death.box website.

Download

Download SPEC.md
917a20ebfa07674b93914710571b5cedd1f074ed4edd67f65cd86070b0528c2f

Overview

ElementValue
CipherAES-256-GCM (WebCrypto AES-GCM, 256-bit key)
Key derivationPBKDF2, hash SHA-256, 250000 iterations, 256-bit output
PassphraseUTF-8 bytes of the entered passphrase (see note on Unicode normalization)
Salt16 random bytes per message
IV / nonce12 random bytes per message
Auth tag16 bytes (128 bits), appended to the ciphertext by WebCrypto
Additional authenticated data (AAD)none
PlaintextUTF-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:

  1. Convert MemoData (hex) to bytes and read them as UTF-8. The result is death.box:v1:<Base64>.
  2. Strip the death.box:v1: prefix and Base64-decode the rest.
  3. Split into salt, IV and ciphertext according to the binary layout.
  4. Derive the key with PBKDF2 from the passphrase and salt.
  5. 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') and passphrase.normalize('NFD'). decrypt.html does 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.