How the protocol works

Identity and addressing#

An address such as alice@example.com is a keypair: an Ed25519 signing key and an X25519 key-agreement key, bound in a self-certifying IdentityRecord that any reader can verify on its own. No certificate authority issues it.

The record has two ownership zones. The identity core (address, keys, validity, tier and revision) is covered by the owner's self-signature, so only the key holder can change it. The operational side is mailbox routing. It travels as an operator-signed credential that is deliberately excluded from the self-signature, so a domain operator can re-point or rebalance routing without ever holding the owner's key. That credential verifies against the domain authority instead (see Credentials and authority).

The owner-signed revision never goes down. Fleets and readers reject any record whose revision is lower than one they've already verified, so a replayed old record can never roll an identity back.

Resolving an address#

The record format, and what a resolver checks. The design behind it is under Why there's no global directory.

_dmcn.<domain>  TXT  "dmcn-verification=v1; fp=<40-hex>[; fleet=<domain>][; seed=<multiaddr>]..."

fp     trust anchor: first 20 bytes of SHA-256(ed25519_pub ‖ x25519_pub), uppercase hex
fleet  optional deferral to a hosting fleet's domain, for discovery only; spoofing it is DoS, never forgery
seed   bootstrap multiaddrs; each ends /p2p/<peerID>, so the transport handshake authenticates the endpoint

$ dig +short TXT _dmcn.example.com
"dmcn-verification=v1; fp=9F2A…C41E; seed=/dns4/id1.example.com/tcp/4001/p2p/12D3Koo…"

A resolver dials a seed, fetches the domain authority record and the identity record, and verifies them in this order:

1. the domain authority record's root self-signature is valid;
2. the authority's fingerprint equals the DNS fp= anchor (fail-closed);
3. if the authority declares a fleet domain, it matches the DNS fleet= deferral (opt-in pinning);
4. the identity record's owner self-signature is valid;
5. the address credential chains to the domain authority (Credentials and authority);
6. neither key is blocked and the address is not tombstoned.

Failures are strict on purpose. No _dmcn record means the address doesn't exist, and a transient DNS failure fails closed rather than downgrading trust.

Messages and encryption#

A message is written in plaintext, signed with the sender's key, then sealed once with a fresh per-message key that's wrapped separately for each recipient. That makes three layers: PlaintextMessage → SignedMessage → EncryptedEnvelope.

Envelope version 2 seals the content in two parts. The header is small and listable: sender, subject, snippet, recipient lists, and signed commitments to the body. The body holds the content and attachments and is fetched separately, so a mailbox can list mail without pulling bodies. The bcc list appears only on the sender's own Sent copy. Recipient copies carry an empty one.

cek = random 32 bytes                              # one per message
for each recipient device:
    eph         = fresh X25519 keypair
    shared      = X25519(eph_priv, recipient_pub)
    kwk         = HKDF-SHA256(shared, salt="", info=<context>)
    wrapped_cek = AES-256-GCM(kwk, cek)            # nonce 12, tag 16
content = AES-256-GCM(cek, plaintext, aad)         # header and body sealed separately in v2

# each wrap declares its own derivation in recipient_record.kdf; absent means 1
kdf=1: info = "dmcn-cek-wrap-v1"                              # bare label, binds nothing
kdf=2: info = "dmcn-cek-wrap-v2" ‖ eph_pub ‖ recipient_pub    # RFC 9180 §4.1 kem_context

# header and body share one CEK, so each seal binds a label to keep them apart.
# the labels are selected by the same kdf value, so blobs and wraps cannot disagree.
kdf=1: aad = none
kdf=2: aad = "dmcn-aad-hdr-v1\0"  |  "dmcn-aad-body-v1\0"

A reader dispatches on the declared value and never tries derivations in turn. The field sits on the recipient record rather than the envelope because the record is what survives storage. A mailbox keeps per-recipient entries and drops the envelope's version, message id and timestamp.

A reader must also check that the sender addressed the message to the mailbox reading it, meaning some address in the signed audience (recipient_address, to, cc) resolves to the key the envelope was sealed to. That check, not the encryption, is what catches a message re-targeted at someone it wasn't addressed to. A legitimate recipient holds the message key, so it can re-seal the same signed header to a third party, but it can't change the audience the sender signed. The comparison is on the key rather than the address text, so several addresses sharing one mailbox need no special case.

Sealed blobs are padded into standard size buckets so ciphertext length gives away as little as possible. The padded layout is [4-byte BE length][payload][zero padding]. The body blob also carries a cleartext content address that any relay can verify without a key:

body_content_address = 0x01 0x55 0x12 0x20 ‖ SHA-256(body_nonce ‖ encrypted_body ‖ body_tag)
                       CIDv1(raw, sha2-256), 36 bytes; the signed copy inside the header is authoritative

v1 gives at-rest and in-transit confidentiality with per-message keys, but not full forward secrecy. The ratchet_pub_key field is reserved for a double-ratchet upgrade and is zero today.

Wire protocols (libp2p)#

Every DMCN conversation is a libp2p stream, an authenticated and encrypted transport whose handshake proves the peer's identity. A peer ID can't be spoofed without its key.

Three protocol IDs carry the core. Device pairing has no protocol of its own, on purpose. The pairing exchange uses the ordinary relay mailbox path, under a synthetic pairing.local domain.

Relay operations#

One protocol carries all relay work. Every core operation authorizes in one of three ways, and none of them is a password.

Message-authenticated ops carry their proof in the message itself. A store is valid because the sender signed the envelope, and a fetch is valid because the client answers the relay's nonce challenge with a signature from the account key. Connection-gated ops need the calling peer to have presented a valid credential at the join handshake. Public reads return signed records the reader verifies for itself. The one public write, put_record, re-verifies every record on ingest, so a record that doesn't verify can't be stored.

The operator surface (fleet administration and operator-attached entitlements) uses separate extension protocols, /dmcn/operate and /dmcn/mailbox-ext, outside the core. The arm numbers it once used here are reserved, and the table marks them.

Credentials and authority#

Trust is anchored in the domain and spelled out in credentials. A credential's roles say what a key is and its grants say what it may do. No key can sign anything its grants don't cover.

Every credential chain leads back to the domain's root key, the one the DNS fingerprint anchors (Resolving an address). Delegation is monotone: an issuer can never grant more than it holds, scope can only narrow (a subdomain scope covers its children, never its parents), and chains are capped at depth 8. By convention the powerful grants stay on offline keys, and the busy online services carry only what they need to run.

The domain authority record is the domain's administrative root. It holds the issuer set, reserved local-parts, key-rotation history and policy flags. Administrative authority over an address is separate from cryptographic ownership of it. A domain authority can provision, attest and revoke bindings in its namespace, but it never holds private keys and can never read mail. How a domain owner lets a fleet operator host it is an operator extension, outside this core reference.

Signing convention#

Every signature in DMCN follows one rule.

sig = Ed25519(priv, ctx ‖ deterministic_protobuf(message_without_signature))

The canonical form is deterministic protobuf serialization (stable map ordering) of the message with its signature field cleared. ctx is a per-type, NUL-terminated domain-separation tag, so a signature over one record type can never be replayed as another. There's one deliberate exception. The whole-message SignedMessage signature is computed over the canonical plaintext with no context tag.

Onion routing (optional)#

An optional delivery mode that hides who is talking to whom from the relays in between. The packet format below is implemented and the design default is multi-hop, but today's deployments run single-hop, so don't count on the metadata privacy described here yet.

A route is 3 hops by default, ending at the recipient's home relay. Hops must sit in distinct /24 networks and distinct domains, so no two hops share an operator, and an optional stable guard can be the entry. Each relay publishes a RelayDescriptor with its onion key and addresses, signed by its own libp2p key. That key can be recovered from the relay's peer ID, so a descriptor verifies without trusting whoever served it.

OnionPacket { version, ephemeral_pub (32), nonce (12), tag (16), encrypted_layer }
OnionLayer  { next_hop | "DELIVER", ttl_unix, inner_packet | delivery }

each relay: derive layer key from ephemeral_pub + own X25519 key → peel → forward (or deliver)

Only the innermost delivery layer is padded to its own bucket classes (up to 36 MB, matching the message ceiling). Forwarding layers add routing overhead only. A mailbox sets require_onion (or its domain sets the REQUIRE_ONION policy) to make the relay reject direct stores with ONION_REQUIRED.