Post-Quantum PKI Tree

Membership in a VeilNet network is a chain of post-quantum signatures, from your organisation's realm key down to each machine.

Levels of the Tree

A realm is defined by its key. Whoever holds a realm's key can admit machines to the realm and delegate realms beneath it. A realm needs no other configuration.

A sovereign network is one tree of realms. Your organisation's realm is at the top, its sub-realms sit beneath it, and each realm admits its own machines. Every signature in the tree uses ML-DSA, ML-DSA-87 by default.

Fig. 02 — A post-quantum PKI tree

Each link is a signature from the level above, made with ML-DSA-87 in the default suite. An anchor presents its chain, and every peer checks it back to the root before any data flows. The tree has no shared secret and no ledger. It is a certificate tree, not a blockchain.

Level	What it is	What its key signs
Your organisation's realm	The top of your tree. The console calls it the guardian realm. VeilNet mints its realm credential and hands it over on hard media, and its key stays sealed inside your guardian.	Credentials for its own machines, including your bootstrap nodes, and a delegation for each sub-realm, with the renewals of both. Your guardian's signer makes all of these signatures.
Sub-realm	A realm one level down, with its own key and a delegation from the realm above	Credentials for its own machines, and further delegations if its own delegation allows them
Machine	An anchor whose identity is its own ML-DSA key, admitted by its realm	No credentials. It signs only statements about itself, such as its knock and its route offers. If its credential carries a power, it also signs orders. See Signing.

Your guardian keeps the sub-realms' keys sealed, just as it keeps your realm key sealed. Its signer unseals a key only to make one signature.

Every credential in your tree is therefore signed in one place, on your own infrastructure. No machine on the network holds a realm key.

Anchor and Realm Credentials

A credential makes one of two statements, and its subject shows which:

Credential	Its subject	What it says	What it carries
Anchor credential	A machine's AnchorID	This machine is a member of the issuer's realm	An expiry, any powers and the machine's taints
Realm credential, or delegation	Another realm's key	This key may run its own realm and issue credentials within it	An expiry, powers, a depth limit and the subject's public key, which the next link is checked against

A machine's realm is the realm that issued its anchor credential. Realms have no name field, and there is no registry of names.

A machine in a sub-realm presents its whole chain: the delegations from the top of the tree down to its sub-realm, then its own credential.

Every credential has an expiry, because a member that could never lapse could never be removed. A credential without one is refused.

Checking a Chain

A peer checks every chain it is shown, from the top down, and refuses the chain at the first check that fails:

Check	What must hold
1. The top	The first link verifies against the single root that every member pins. Nothing inside a chain can add a different root.
2. Each link	Each later link is signed by the key named in the link before it.
3. The shape	Every link except the last delegates a realm, and the last link admits the machine that presents the chain.
4. The depth	No link goes deeper than the link above it allows.

Eight links at most. A peer refuses a longer chain without reading any of it.
Each link is verified once. A peer remembers verified links until they expire. The delegations that every member of a sub-realm presents are therefore checked only once.
Powers narrow down the chain. A chain grants only the powers that every link on it grants. A delegation grants every power unless it names fewer. An anchor credential grants no power unless it names some, and nearly every machine should have none.

Depth Limits

Every delegation carries a depth limit. At 0, the realm can admit machines but cannot delegate. At 1, it can delegate sub-realms, but those sub-realms cannot delegate further.

A delegation is made at depth 0 unless you choose another limit, so leaving the limit unset never creates an unbounded delegation.

The depth limit in your realm credential decides whether your guardian can mint sub-realms at all. To learn how to use them, see Sub-realms in Sovereign Networks.

Cryptographic Suites

Every key and signature in a tree uses the suite that the tree was created in. The default suite meets NIST security category 5. If you want smaller handshakes, you can create a tree in category 3 instead:

Suite	Signature	Key exchange	AEAD	TLS hybrid group	NIST category
`0x01`	ML-DSA-87	ML-KEM-1024	AES-256-GCM	`SecP384r1MLKEM1024`	5 (the default)
`0x02`	ML-DSA-65	ML-KEM-768	AES-256-GCM	`X25519MLKEM768`	3

A sub-realm's key uses its parent's suite, and a machine's identity uses its realm's suite. A peer that uses a different suite is refused at the handshake.

One part of each handshake is classical by design. The short-lived TLS certificate uses Ed25519, but only to prove possession of its key within one handshake. ML-DSA signatures bind the machine's identity to that certificate and prove who is at the other end.

Derived Values

An anchor computes many of the values a realm needs instead of reading them from configuration. It derives them from public values that every member already holds:

Overlay IPv6 addresses. Each machine's address comes from its identity, inside one /48 in fd00::/8 that is never routed on the internet. A machine's address is known before the machine first starts.
Connection tags. Each connection carries a tag that changes every hour. Machines whose clocks are an hour apart still connect, but machines two hours apart cannot. Keep every host on NTP, because conflux refuses to start if its clock is more than ten minutes wrong.
Taint tags. A taint is a label that puts a machine in a compartment. On the network, each taint name is replaced by a tag, and the name itself never leaves the machine.

These values come from an identifier built into the released software, not from each realm's own key. A sub-realm therefore needs only its key and its credential, and nobody has to coordinate an address plan.

All of these values are public, and none of them admits a machine. Only a credential chain admits a machine.

Reading Your Chain

To see where a machine sits in your tree, run:

$ sudo conflux status

anchor is the machine's AnchorID, which names the machine in every chain.
credential shows when the machine's own credential expires, as valid until followed by a time.
Under anchor:, the anchor names its realm and shows cut depth, renew by and works until. A cut depth of 0 means that every delegation above the machine is current.