Mailbox keys

See Mailboxes for why mail is sealed to your wallet address by default and when a delegated encryption key is needed. This page covers the sithbit mailbox key commands that publish, rotate, read, and clear that optional on-chain key.

CLI build note: key create and key set are gated behind the CLI’s rand feature, which is on by default — a stock cargo build -p mail-client has them, and only a --no-default-features build that leaves rand out drops the pair. key get and key close are ungated. See sithbit mailbox reading-secret for the full note on what else that feature carries.

`mailbox key create`

Generates a delegated X25519 keypair client-side and writes it to a file — this does not touch the chain:

sithbit mailbox key create <output path>

The secret key file is written owner-only (unix 0o600) at creation — the umask can only tighten it further, never loosen it — and a file already at the target path is tightened to 0o600 before the new key is written, so an old looser-mode file left over from before this hardening never has a fresh secret written into it at its old mode. Non-unix targets set no mode bits; guard the file’s location yourself there.

`mailbox key set`

Publishes (or replaces) the delegated key on your mailbox:

sithbit mailbox key set <keypair path> \
  [--keypair <path>] \
  [--skip-preflight]

Arguments

<keypair path> (required) — the delegated X25519 keypair file to publish, as generated by mailbox key create.
--keypair <path> (optional) — the mailbox owner’s keypair, used to sign the transaction. Defaults to the keypair in your Solana CLI config when omitted.
--skip-preflight (optional) — submits the transaction without a local simulation pass first.

Re-running mailbox key set with a fresh keypair file rotates the key: senders start sealing to the new public key immediately, and mail already sealed to the old key still opens with the old key file.

Loading <keypair path> also tightens its permissions. Every successful load re-chmod’s the file to owner-only (unix 0o600) before publishing its public half, so a file that predates this hardening, or was loosened by some other process, does not stay readable forever. A chmod failure (e.g. a readable file this process doesn’t own) only prints a warning — the command still completes. Reading from stdin (-) has no file to tighten.

`--derive`

sithbit mailbox key set --derive [<keypair path>] \
  [--keypair <path>] \
  [--skip-preflight]

With --derive, no key file is read. Instead the wallet that signs the transaction (--keypair, or your default Solana CLI keypair) derives the recoverable reading key: it signs one fixed message, and the signature is stretched through a KDF into the X25519 secret. The derived public half — not a random one — is what gets published on-chain, in the same form as a mailbox key created key; only the origin of the secret differs.

<keypair path> becomes optional and changes meaning: give it to also persist the derived secret to that file (.json is appended if the path doesn’t already end in it), for the file-based decrypt tooling; omit it to only publish. When a path is given, the secret is written owner-only (unix 0o600) at creation, and an existing file already at that path is tightened to 0o600 before the new bytes are written — the same create-or-tighten guarantee mailbox key create gives its output file. Non-unix targets set no mode bits.

`mailbox key get`

Reads the published key back, if one exists:

sithbit mailbox key get [owner_address]

[owner_address] (optional) — the address whose mailbox to look up. Defaults to your own configured keypair’s address.

Prints the delegated X25519 public key as base58 when one is published, or reports that the mailbox has no delegated key (i.e. mail is sealed to the wallet address).

`mailbox key close`

Removes the delegated key account and reclaims its rent, returning the mailbox to wallet-sealed mail:

sithbit mailbox key close \
  [--keypair <path>] \
  [--skip-preflight]

Examples

Generate a delegated key, publish it, then confirm it’s live:

sithbit mailbox key create my_delegated_key.json
sithbit mailbox key set my_delegated_key.json --keypair <path to wallet keypair>
sithbit mailbox key get

Rotate to a fresh key:

sithbit mailbox key create my_new_key.json
sithbit mailbox key set my_new_key.json --keypair <path to wallet keypair>

Stop using a delegated key and fall back to wallet-sealed mail:

sithbit mailbox key close --keypair <path to wallet keypair>

Looking up a mailbox — inspect a mailbox’s other settings.
Create a mailbox — create the mailbox that a delegated key attaches to.
Update a mailbox — change postage, domain, or the no-IPFS flag.

See Appendix: How sealed-box encryption works for the full protocol, and Closing accounts for mailbox key close alongside other account-closing commands.

Keyboard shortcuts

SithBit Mail