The DMCN protocol, on the wire.

1. Status of this document

This is a reference snapshot of the running implementation — versioned with the code, generated in part from it, and corrected by it: where this page and the implementation disagree, the implementation wins.

Scope: core protocol only. This page documents what an implementation needs to interoperate — resolve, verify, send, receive. The protocol also defines operator surfaces (fleet provisioning and administration, operator-attached quotas and access windows); those are optional segments a fleet may run, never requirements for interoperation, and are deliberately left out here until they are documented as proper extensions. Where they touch a shared structure below, rows are marked (extension) so the schema stays fully accounted for.

The wire-reference tables below (identity record, credential, envelope, relay operations, tiers) are built from the protocol's protobuf schema — the same definitions the implementation compiles against — so field names and numbers on this page are correct by construction. The core protocol spec and an Apache-2.0 reference implementation are published in full at github.com/dmcnp/open-dmcn — anyone can read the wire format, audit it, or run their own server. It is an early release that tracks the implementation rather than a frozen standard: formal versioning and a conformance suite are on the roadmap.

Conventions: messages use the protobuf3 wire format; byte lengths appear in parentheses; where the protocol frames data by hand, integers are big-endian; signature context tags are NUL-terminated strings, written here as \0. Reserved field numbers must not be reused.

2. Identity & addressing

An address — alice@yourcompany.com — is a keypair: an Ed25519 signing key and an X25519 key-agreement key, bound in a self-certifying IdentityRecord that proves itself to any reader. No certificate authority issues it.

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

The owner-signed revision is monotonic: fleets and readers reject any record whose revision is lower than one they have already verified, so a replayed old record can never roll an identity back.

3. Resolution: the _dmcn record

Addresses resolve against the domain's own infrastructure, discovered through DNS — the same delegation model MX records use for mail routing. There is no global directory, so no foreign majority can censor or dominate resolution.

_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 — 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.yourcompany.com
"dmcn-verification=v1; fp=9F2A…C41E; seed=/dns4/id1.yourcompany.com/tcp/4001/p2p/12D3Koo…"

A resolver dials a seed and fetches the domain authority record and the identity record, then verifies — in 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 (§7);
6. neither key is blocked and the address is not tombstoned.

Because every record is self-certifying and anchored in the mailbox domain's DNS, a wrong or hostile server can only fail to answer — it can never fabricate or tamper undetected. Failure semantics are deliberate: no _dmcn record means the address does not exist; a transient DNS failure fails closed rather than downgrading trust.

4. Message model & encryption

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

Envelope version 2 splits the sealed content in two: a small, listable header (sender, subject, snippet, recipient lists, and signed commitments to the body) and the body (content and attachments), fetchable independently — 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 rides 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 — that 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 detects a message re-targeted at someone it was not addressed to: a legitimate recipient holds the message key, so it can re-seal the same signed header to a third party — but it cannot 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 reveals as little as possible; the padded layout is [4-byte BE length][payload][zero padding]. The body blob also carries a cleartext content address 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

Honest edge: v1 provides 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.

5. Wire protocols (libp2p)

Every DMCN conversation is a libp2p stream: authenticated, encrypted transport where the peer's identity is cryptographically proven in the handshake — a peer ID cannot be spoofed without its key.

Three protocol IDs carry the core. Device pairing deliberately has no protocol of its own — the pairing exchange rides the ordinary relay mailbox path (under a synthetic pairing.local domain), with the human-verified SAS code committed under the dmcn-pair-sas-v1\0 context.

6. Relay operations & authorization

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

Message-authenticated ops carry their proof in the message itself: a store is valid because the sender signed the envelope; a fetch is valid because the client answers the relay's nonce challenge with a signature from the account key. Connection-gated ops require the calling peer to have presented a valid credential at the join handshake. Public reads return signed records the reader verifies independently; the one public write, put_record, self-gates by re-verifying every record on ingest — an unverifiable record simply cannot be stored. The operator surface — fleet administration and operator-attached entitlements — rides two separate product-side protocols (/dmcn/operate, /dmcn/mailbox-ext) outside the core; the arm numbers it once occupied here are reserved, and the table marks them so.

7. Credentials, authority & permits

Trust is domain-anchored and explicit: a credential's roles say what a key is, its grants say what it may do — and no key can sign anything its grants don't cover.

Every credential chain resolves to the domain's root key — the one anchored by the DNS fingerprint (§3). 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. Powerful grants stay on offline keys by convention; the high-traffic online services carry only what they operationally need.

The domain authority record is the domain's administrative root: its issuer set, reserved local-parts, key-rotation history, and policy flags. Administrative authority over an address is distinct from cryptographic ownership of it — a domain authority can provision, attest and revoke bindings on its namespace, but it never holds private keys and can never read mail. Hosting-consent mechanics between domain owners and fleet operators exist as an operator extension, outside this core reference.

8. 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. One deliberate exception: the whole-message SignedMessage signature is computed over the canonical plaintext with no context tag.

9. 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; today's deployments run single-hop, and multi-hop is the design default — stated plainly so nobody buys metadata privacy this page hasn't earned 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 (no two hops share an operator), with an optional stable guard as the entry. Each relay publishes a RelayDescriptor — its onion key and addresses — signed by its own libp2p key, which is recoverable from its peer ID, so descriptors verify without trusting whoever served them.

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.