Credentials and Renewal

Credential Sources

A credential admits a machine to its realm, and every credential expires. Conflux keeps the credential and the identity it belongs to in one file, manifest.b64.

How the file arrives, and how the credential renews, depend on where the machine joined:

To check a credential, run sudo conflux status. The credential row shows when it expires. A renewal or clock row appears when something needs your attention.

  credential   valid until 2026-10-06T06:35:43Z (29d 23h)

The Instance VeilNet Hosts

On the instance VeilNet hosts, a machine enrols with one HTTPS call to https://api.veilnet.com.au. There is no account, no sign-up and no session.

The machine asks for the taints it wants, up to 32 of them. The instance creates an identity, signs a credential for it with those taints and returns both. It keeps no record of either.

A machine enrols once, the first time it runs up or proxy. Later runs, including a switch between modes, reuse the same identity.

Automatic Renewal

A credential from the instance VeilNet hosts lasts thirty days. Conflux renews it at day twenty, two thirds of the way through. This leaves ten days to recover from an outage.

Conflux renews at every start and on a timer while the anchor runs. The running anchor picks up the new credential without dropping a session.

Renewal follows these rules:

• A failed renewal is retried every minute. The timer never waits more than six hours, so a laptop catches up soon after it wakes.
• A failed renewal never falls back to enrolling. A new enrolment would change the machine's overlay address, and peers that knew the old address would lose track of it.
• Conflux refuses a clock that is more than ten minutes fast or slow. Nothing connects until you correct the clock. See Clock Skew.

Renewal failures

sudo conflux status shows the last error:

  credential   valid until 2026-10-06T06:35:43Z (8d 4h)
  renewal      failing since 2026-09-26T08:10:00Z: dial tcp: no route to host

When you have fixed the cause, renew now instead of waiting for the next attempt:

$ sudo conflux renew
  credential renewed, valid until 2026-10-28T02:35:43Z (29d 23h)
  was          valid until 2026-10-06T06:35:43Z (8d 4h)

renew exits with status 69 when it can do nothing: on a machine that was never configured, when nothing is running, or with a fixed-term credential. After conflux down, run sudo conflux start instead, because every start renews.

Sovereign Networks

On a sovereign network, the guardian commissions each machine and signs its credential with the realm's key. You receive one file, the manifest, with the machine's identity, its credential and its bootstrap nodes.

Install the manifest with conflux enrol, as Joining a Sovereign Network describes:

$ sudo conflux enrol --manifest node-14.b64
$ sudo conflux up

Renewal on a sovereign network works as follows:

• The machine renews through the guardian, at the address on the renewal row that enrol printed. It authenticates with a secret in the manifest, minted for that machine alone. Timing and retries work as on the instance VeilNet hosts.
• The operator chooses how long each credential is valid and which taints it grants. The operator may also allocate the IPv4 address.
• Every renewal also updates the bootstrap list in the manifest.
• The guardian signs every renewal itself, so renewal never depends on anything outside the organisation.
• enrol copies the IPv4 address and any telemetry export settings into the configuration once. You can change them later. The taints are not copied, because every start checks them against the credential.
• enrol refuses a manifest that asks for a renewal method this version of conflux does not support. It also refuses a manifest that requires a secret but does not contain one. Upgrade conflux, or ask for the machine to be commissioned again.

To remove a machine, use the guardian. See Renewal and Revocation and Blocks in the guardian docs.

Fixed-Term Credentials (Advanced)

A fixed-term credential has no renewal details. It runs until it expires, and you then replace it.

On a sovereign network, the guardian normally issues and renews every credential. If you mint a credential yourself, with anchor's anchorctl and the realm's key, it is fixed-term. Conflux says so when it installs one:

$ sudo conflux enrol --manifest gateway-3.b64
credential installed
  from         gateway-3.b64
  renewal      none: it runs to its expiry and is then replaced
  expires      2026-11-07 09:00 UTC
  taint        site-a
  bootstrap    bootstrap-1.example.net:4700, bootstrap-2.example.net:4700

Next: sudo conflux up

A fixed-term credential behaves as follows:

• Nothing tries to renew it. conflux renew exits with status 69 and says that the credential is replaced, not renewed. Conflux does not report this as a failure.
• enrol refuses an expired fixed-term credential. On a running machine, the next start after expiry is refused for good, with exit status 70. The service shows as failed until you replace the credential.
• If the file contains exit: true, conflux reports it but does not act on it. The machine serves an exit only when you pass --serve-exit.

Replacing a fixed-term credential

enrol never replaces an installed credential, and uninstall also removes the configuration and the boot service. To replace a credential, reinstall the machine with the same settings:

Changing a Machine's Taints

A machine's credential fixes its taints for the life of its identity. Renewal keeps the same taints and cannot change them. If the configuration asks for other taints, conflux refuses to start:

conflux: this machine's credential grants the taint "brhk-2mq9-tzva-6pjs-k4xe-nw7d-qf", and it is configured for the taint "office".
  A credential's taints are its issuer's to grant and never change, so a different one is a new
  identity -- a new AnchorID and a new overlay address:

      conflux uninstall --yes
      conflux up --taint office        (or conflux proxy ... --taint office)

On the instance VeilNet hosts

To move a machine to another compartment, give it a new identity. Run sudo conflux uninstall --yes, then sudo conflux up --taint NEW. The machine gets a new AnchorID and overlay address, so tell its peers the new address.

Credentials from this instance grant no powers, so nobody else can move your machine.

On a sovereign network

The guardian can move a running machine. The guardian's root node, its own anchor in the realm, sends a Taints order. The machine's anchor keeps the order and applies it again at every start.

The machine keeps its identity, and its credential keeps the taints it was commissioned with. The taint row of conflux status shows the commissioned taints, not the result of the move.

To change the commissioned taints, have the guardian commission a new credential. Then run sudo conflux uninstall --yes, sudo conflux enrol --manifest FILE and sudo conflux up.

Protecting the Manifest

The manifest holds the machine's identity, so anyone with a copy can act as that machine. A manifest from a guardian also holds the renewal secret, so its holder can keep the credential current.

Treat the manifest like a private key. Keep it off shared storage and out of backups that leave the machine, and keep the permissions that conflux sets:

• Conflux keeps the file at mode 0600 in a 0700 directory. On Windows, only SYSTEM and Administrators can access it.
• The manifest never appears on a command line, so it never shows up in ps. It never appears in a log either.

Stolen manifests

A stolen manifest lets its holder act as that machine for as long as its credential keeps being renewed. What to do depends on where the machine joined:

• On the instance VeilNet hosts, nothing can revoke the stolen identity, and the thief can renew it indefinitely. Stop using it: run sudo conflux uninstall --yes and then sudo conflux up --taint NEW. The thief keeps the old taint, so move every machine that the thief must not reach to the new taint.
• On a sovereign network, ask the guardian's operator to stop renewing the machine and to block it. Then have a new identity commissioned, and install it with uninstall --yes, enrol and up.

Moving a machine

To move a machine's identity and overlay address to another host, copy manifest.b64 to it. Then delete the original, or the same anchor exists twice.

If the address does not matter, run sudo conflux uninstall on the old host and sudo conflux up on the new one.