Skip to main content

Certificate Renewal

Every Fabric-X node carries a signing certificate and a TLS certificate, both signed by the organization's CA. ChainLaunch supports renewing these certificates without rotating the underlying key pair — matching the renewal semantics used by Fabric peer and orderer nodes.

This page covers when to renew, what gets restarted, and how the same-keypair guarantee works.

Same-keypair renewal​

When you renew a Fabric-X node's certificates, ChainLaunch reuses the existing private keys and re-signs them with the same CA. Only the certificate PEMs change. This matches the behavior of LocalPeer.RenewCertificates in classic Fabric and means:

  • Genesis-block-bound public keys stay valid — no genesis regeneration is needed.
  • Other parties don't need to be notified or reconfigured.
  • The renewed cert covers the same subject, organization, and SANs as the original (localhost, 127.0.0.1, host.docker.internal are always included).
  • New notAfter is one year from the renewal time.

The keys stay in the same database rows (SignKeyID, TLSKeyID on the deployment config). The only DB write is the new Certificate blob on those key rows plus the updated signCert/tlsCert columns on the node_groups row.

If you ever need to rotate to a fresh key pair (post-compromise recovery), you must currently delete and recreate the node — there's no UI/API toggle for key-pair rotation yet.

When to renew​

  • Approaching expiry. Fabric-X certs are issued for one year by default; renew before the renewal window closes.
  • Trust store rotation. When the issuing CA's intermediate is rolled, peers need fresh leaf certs.
  • Security policy. Some compliance regimes require periodic re-issuance even on a stable key pair.

ChainLaunch does not yet surface cert expiry in the UI or events, so renewal is operator-driven today. A monitoring rule on the issuing CA's certificate inventory is the simplest stopgap.

How to renew​

From the web UI​

Open the node detail page → Certificates tab → Renew certificates. The button is wired to POST /api/v1/nodes/{id}/certificates/renew.

From the API​

curl -X POST -u admin:admin123 \
  http://localhost:8100/api/v1/nodes/12/certificates/renew

The endpoint blocks until the renewal-and-restart sequence finishes. Expect ~10 seconds for an orderer group, ~20 seconds for a committer (more containers to restart).

The endpoint accepts any of:

  • A monolithic FabricX node row (FABRICX_ORDERER_GROUP, FABRICX_COMMITTER) — pre-node_groups installs.
  • A per-role child node (FABRICX_ORDERER_ROUTER, FABRICX_COMMITTER_SIDECAR, …). Renewing a child triggers a group-wide renewal because every child shares one identity by design.

What happens during renewal​

For an orderer group (4 children share one identity):

  1. ChainLaunch emits a RENEWING_CERTIFICATES event on the node.
  2. All four containers (router, batcher, consenter, assembler) are stopped.
  3. The signing cert is re-issued against the existing SignKeyID with the orderer OU.
  4. The TLS cert is re-issued against the existing TLSKeyID with the saved domain SANs plus the always-present localhost, 127.0.0.1, host.docker.internal.
  5. The four msp/ and tls/ directories on disk are rewritten from the new certs and the unchanged keys.
  6. The updated deployment config (with new signCert/tlsCert) is persisted to the parent node_groups row.
  7. All four containers start again.
  8. ChainLaunch emits a RENEWED_CERTIFICATES event.

For a committer (5 children share one identity, plus postgres):

1–7 follow the same pattern. The on-disk rewrite only touches sidecar/msp and sidecar/tls because the other four committer roles run on the per-group bridge network without per-role MSP material. Postgres is untouched.

Downtime​

Renewal stops the entire group atomically — Stop(cfg) → Start(cfg). For a single-party network, that's full ordering or commit downtime for the duration of the restart.

For a multi-party network, only the renewing party is offline. Arma consensus tolerates f party failures out of 3f+1 total, so a 4-party network keeps making progress while one orderer group is being renewed.

A rolling renewal that brings one role at a time back up (so consensus can continue end-to-end on a single-party network) is not implemented today.

Auditing renewals​

Each renewal emits two events visible in the node detail page's Events tab and via GET /api/v1/nodes/{id}/events:

EventPayload action
RENEWING_CERTIFICATESrenewing_certificates
RENEWED_CERTIFICATESrenewing_certificates

If renewal fails midway (e.g. CA key inaccessible, disk write failure), an ERROR event is emitted with the underlying error message and the node status is set to ERROR. The keys themselves are not modified on failure — you can retry the renewal once the underlying issue is fixed.

Pinning a child's signing CA​

If a key was minted before signing_key_id became authoritative on the keys table, ChainLaunch's renewal code populates it with the org's signing CA on first renewal. This is a one-time migration; subsequent renewals find the link already set.

You'll see this in the logs as set signing key id on sign key / set signing key id on TLS key on the first renewal of an old node. Nothing needs to be done by the operator.

Limitations​

  • Same key pair only. No UI/API for issuing a fresh key pair.
  • Full-group restart. No rolling renewal across child roles.
  • No pre-expiry warning. The UI doesn't surface notAfter and there are no events for upcoming expiry. Track this externally for now.
  • CA renewal not supported. ChainLaunch renews leaf certs against the same CA. Renewing the CA itself (signing or TLS root) requires regenerating every derived cert — this is currently a delete-and-recreate operation.

See also​