Skip to main content

TLS encryption

TLS (Transport Layer Security) encrypts and authenticates the traffic in a Zaris cluster. This page covers how to turn it on, what changes when you do, and the moving parts — certificates, mutual TLS, and peer verification. It assumes you have read the Security overview. The choice of who signs the certificates is covered separately in CA and trust modes.

What TLS protects​

TLS in Zaris covers three channels. Data-plane channels carry store traffic; the control-plane channel secures management and browser access.

ChannelPlaneAuthentication
Client to nodeData planeThe node presents a certificate, which the client validates against the cluster CA. The client is identified by its token.
Node to nodeData planeMutual: both sides present and validate certificates (Mode: MutualTls).
Management Service and Web ConsoleControl planeServer-authenticated HTTPS, enabled independently with Enable-ZrManagementHttps.

Data-plane TLS is a per-store setting. You can run an encrypted orders store and a plaintext scratch store in the same cluster.

Enable TLS on a store​

In the supervisor model, one command provisions the cluster CA (if one does not yet exist), enrolls every node with a freshly issued certificate, and restarts the nodes to pick it up. When you omit -Mode, Zaris applies MutualTls.

Enable-ZrStoreTls -Store orders -Mode MutualTls -Restart
  • Omit -Restart to stage the change and roll the nodes yourself later. TLS does not take effect on a node until it restarts.
  • Add -CaFile and -CaPassword to enable with your own CA in the same step. See CA and trust modes.
  • -IssuerNodeId selects which node holds the CA and signs leaves, if you need to pin it.

From the Web Console, the equivalent lives on the store's Encryption (TLS) tab: toggle encryption, optionally import a CA, and apply with a rolling restart.

Verify it​

Always confirm the cluster is presenting the certificates you expect before you rely on it.

Get-ZrStoreTlsStatus -Store orders -ShowCertificates

This reports, per node, the certificate subject, thumbprint, and expiry, plus the cluster-CA trust-anchor thumbprint. It does not write a file — to export the public CA for clients, use Get-ZrClusterCaCert -OutFile cluster-ca.crt.

How a node gets its certificate​

When Clustron signs the certificates (Modes 0 through 2), enrollment keeps every node's private key on the node. A leaf certificate is the end-entity certificate a node presents at the handshake, as opposed to the CA certificate that signs it.

  1. The node generates its keypair locally.
  2. It sends a CSR (certificate-signing request — its public key plus the identity it requests) to the Management Service endpoint /security/tls/sign-csr, authorized by a one-time enrollment token.
  3. The manager signs the CSR with the cluster CA and returns the public leaf, plus the intermediate chain in Mode 2.
  4. The node combines the leaf with its local private key and presents it at every handshake.

Because only the CSR and the public leaf ever cross the network, the private key never leaves the node. Enrollment tokens are single-use and node-bound. You mint one with New-ZrEnrollmentToken -Node <nodeId> when adding a node manually; the supervisor issues them automatically for nodes it creates.

A node that self-enrolls at boot (for example an attach-model node) reads its inputs from environment variables, which take precedence over config: ZARIS_TLS_ENROLL, ZARIS_TLS_ISSUER_URL, ZARIS_TLS_ENROLL_TOKEN, and ZARIS_TLS_CA_THUMBPRINT. Set ZARIS_TLS_CA_THUMBPRINT so the node pins the expected CA and aborts enrollment if a different CA answers.

note

Restarts and routine certificate renewal do not re-spend an enrollment token. A node proves possession of its current certificate to renew (against the issuer's /security/tls/renew-csr endpoint), so the one-time token is used only on a node's very first boot. See Certificate management.

In Mode 3 (pre-issued leaves) there is no enrollment. Each node loads a certificate that was mounted for it.

Mutual TLS and peer verification​

With Mode: MutualTls, node-to-node connections are mutually authenticated: a joining node must present a certificate that its peers accept, so only enrolled members participate in the data plane. How strictly peers are checked is governed by PeerVerification, which has three values.

PeerVerificationA peer is accepted when…
CaOnlyIts certificate chains to a trusted anchor. No identity check.
CaAndIdentityIt chains to a trusted anchor and its identity matches — the common name (CN, the node id) or a subject alternative name (SAN) entry (host or IP). This is the default.
FullHostnameIt chains to a trusted anchor and a SAN entry (host or IP) matches strictly. For static-IP deployments.
warning

Do not use CaOnly in production. With CaOnly, any certificate your CA signed is accepted as any node, so a valid-but-stolen certificate can impersonate a different node. CaAndIdentity (the default) binds the certificate to the node identity and closes that gap.

Configuration reference​

You rarely edit this JSON by hand — the cmdlets and Console write it for you — but here is the full data-plane TLS block (zaris.security.tls) for a store so the behavior is never a mystery.

{
  "Enabled": true,
  "Mode": "MutualTls",
  "MinProtocol": "Tls12",
  "PeerVerification": "CaAndIdentity",
  "IssuerNodeId": "orders-n0",
  "Ca": {
    "Source": "Generate",
    "ProvidedRootPath": "",
    "ProvidedRootPasswordRef": ""
  },
  "Lifetimes": {
    "CaValidityDays": 3650,
    "LeafValidityDays": 90,
    "RenewAtFraction": 0.66,
    "EnrollmentTokenTtlMinutes": 15
  },
  "TrustAnchors": [ { "KeyId": "", "Pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" } ],
  "NodeCertificate": { "Path": "", "PasswordRef": "" },
  "Enrollment": { "Enabled": false, "IssuerUrl": "", "Token": "", "CaThumbprint": "", "LeafValidityDays": null }
}
FieldMeaning
EnabledTLS on or off for this store.
ModeOff, ServerAuth, or MutualTls (node-to-node mutual authentication).
MinProtocolMinimum TLS version: Tls12 (permits 1.2 and 1.3) or Tls13 (permits 1.3 only).
PeerVerificationCaOnly, CaAndIdentity, or FullHostname (see above).
IssuerNodeIdNode id of the CA-holding issuer that signs leaves.
Ca.SourceGenerate (Mode 0) or Provided (Modes 1 and 2).
Ca.ProvidedRootPathPath to your CA PKCS#12 when Source = Provided.
Ca.ProvidedRootPasswordRefReference to the PKCS#12 password (never a literal secret).
Lifetimes.CaValidityDaysCA validity window (default 3650).
Lifetimes.LeafValidityDaysLeaf validity window (default 90).
Lifetimes.RenewAtFractionFraction of a leaf's life after which it renews (default 0.66).
Lifetimes.EnrollmentTokenTtlMinutesHow long an enrollment token is valid (default 15).
TrustAnchors[]Trusted CA roots, each { KeyId, Pem }. A list, so rotation can trust old and new during overlap.
NodeCertificate.PathPath to the mounted leaf (Mode 3, or an enrolled node's local leaf).
EnrollmentBoot-time self-enrollment settings (see above); the secret inputs are normally supplied by environment variables.

Control-plane HTTPS​

Encrypting store traffic is separate from securing the Management Service and Web Console. Enable control-plane HTTPS independently with Enable-ZrManagementHttps (or from the Console). Doing so mints a server certificate — from the cluster CA by default, or one you supply with -CertSource provided -CertPath server.pfx — and a service restart activates it. Check state with Get-ZrManagementHttpsStatus. You can run either plane encrypted without the other, though production clusters usually run both.

Enable-ZrManagementHttps -Restart

Next steps​