From 1e6c7a2601f41bf1ac36f5d6e0083cd06cc4d23d Mon Sep 17 00:00:00 2001 From: Bugs5382 <12115015+Bugs5382@users.noreply.github.com> Date: Wed, 30 Sep 2026 20:17:41 -0400 Subject: [PATCH 1/2] docs(fleet-manager): manage operator CAs in the web UI A task page for the web UI's Operator CAs page: what it lists, the CRL and OCSP banners, registering a CA with the fingerprint confirm, changing the CRL source, uploading a CRL, setting the OCSP mode, and retiring a CA with the lockout guard. The web UI page lists the new section. Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com> --- docs/fleet-manager/web-operator-cas.md | 104 +++++++++++++++++++++++++ docs/fleet-manager/web-ui.md | 2 +- sidebars.ts | 1 + 3 files changed, 106 insertions(+), 1 deletion(-) create mode 100644 docs/fleet-manager/web-operator-cas.md diff --git a/docs/fleet-manager/web-operator-cas.md b/docs/fleet-manager/web-operator-cas.md new file mode 100644 index 0000000..7513259 --- /dev/null +++ b/docs/fleet-manager/web-operator-cas.md @@ -0,0 +1,104 @@ +--- +title: "🏛️ Managing operator CAs in the web UI" +--- + +# 🏛️ Managing operator CAs in the web UI + +:::info[In flight] +This page is new in the web UI and needs a Fleet Manager that serves the operator CA admin calls. An older manager refuses them. +::: + +This page covers one task: looking after the external operator CAs the Fleet Manager trusts, from the web UI's **Operator CAs** page. You can register a new CA, retire an old one, and change how the manager learns about each CA's revocations. What an operator CA is, and the config keys, are in [The operator CA and revocation](./operator-ca.md). + +:::caution[Before you start] +You need an `admin` operator certificate and a working login (see [Logging in](./web-ui.md#logging-in)). When the manager takes its operator CA from the config file (`operatorCAPath`), the page is read-only: it says so, offers no actions, and the manager refuses changes with error 1607. Change the config instead. +::: + +## What the page shows + +Each row is a CA the manager trusts or has trusted: + +| Column | What it shows | +|---|---| +| **CA** | The CA's subject, any warning the manager raised (for example that a CryptOS node's CA issued it), and `from the config file` for a config CA. | +| **State** | `active` (new credentials are recorded under it), `retiring` (still trusted during a rotation) or `retired` (no longer trusted). | +| **Fingerprint** | The start of the CA certificate's SHA-256 fingerprint. | +| **Not after** | When the CA certificate expires. | +| **CRL** | The source (`url`, `upload`, `file` or `none`), the URL, the CRL's next update (marked `(expired)` once it has passed) and the last fetch error. | +| **OCSP** | The mode (`aia`, `url` or `off`), the responder URL, and the last OCSP error this manager instance saw. | + +Banners above the table name what needs your attention, for the active and retiring CAs. Admins see the same banners on **Operators**. + +| Banner | What it means and what to do | +|---|---| +| `CA revocations not observed` | The CA has no CRL and no OCSP. Revocations made at the CA aren't seen, so deny credentials in the Fleet Manager as well, or set a CRL source. MCP is refused under it. | +| `CA revocations seen through OCSP only` | No CRL, but OCSP is on: revocations are seen only while the responder answers. MCP is refused under it. | +| `CRL expiring` | The CRL is in the last 20% of its validity. Publish a new one at the CA, or upload it for an upload-source CA, before the time shown. | +| `CRL expired` | The CRL is past its next update. MCP is refused under the CA until a new CRL is loaded; the web UI follows `operatorRevocationPolicy`. | +| `OCSP responder unreachable` | OCSP is on, but the responder isn't answering. The message gives the error. | + +## Register a CA + +Registering a new CA is how you rotate: the new CA becomes `active`, and the current active CA becomes `retiring`, still trusted until you retire it. The manager refuses a new registration while a retiring CA exists (`ROTATION_IN_PROGRESS`). + +1. Select **Register operator CA…**. +2. Paste the **Operator CA certificate (PEM)**, or choose the file (PEM or DER). Use the CA that directly signs operator certificates, never a CryptOS node's CA. +3. Choose the **CRL source**: + - **URL**: the manager fetches the CRL from an http or https URL, now and on a schedule. + - **Upload**: choose an initial CRL file. Later CRLs go through **Upload CRL…**. + - **No CRL**: tick the acknowledgement. Revocations made at the CA aren't seen, and MCP is refused under this CA. +4. Choose the **OCSP mode**: `aia` (the default) uses the responder named in each certificate, `url` uses a **Responder URL** you give, and `off` checks no OCSP. The manager probes a `url` responder before it accepts it. +5. Select **Check the CA**. The manager checks the certificate, fetches or verifies the CRL, and shows a preview: subject, issuer, expiry, CRL status, the OCSP probe result for `url`, any warnings and the full SHA-256 fingerprint. +6. On the CA machine, print the CA certificate's fingerprint: + + ```bash + openssl x509 -in operator-ca.crt -noout -fingerprint -sha256 + ``` + +7. Paste the output into **Paste the fingerprint from the CA machine**. + + :::danger[Trusting a CA lets its key sign in as admin] + Anyone who holds the key of a CA you trust can sign themselves an admin certificate. **Confirm and trust this CA** stays disabled until the pasted fingerprint matches the preview. If it doesn't match, stop: you have the wrong certificate, or someone swapped it. + ::: + +8. Select **Confirm and trust this CA**. + +:::tip[Expected output] +The dialog closes and the list shows the new CA as `active`, and the previous active CA as `retiring`. +::: + +If the manager refuses, the dialog says why and quotes the code, for example `Operator CA refused: That is a CryptOS node's CA. ... (error 1605 IS_NODE_CA)`. + +## Change the CRL source + +1. Select **CRL source…** on the CA. +2. Choose **URL**, **Upload** (with an initial CRL file) or **No CRL** (with the acknowledgement), then **Save**. + +The manager verifies a new URL or CRL against the CA before saving it. + +:::warning[No CRL cuts off MCP] +Switching a CA to no CRL makes every MCP key bound to its certificates fail on its next call, and the manager stops seeing revocations made at the CA. +::: + +## Upload a CRL + +For a CA whose source is **Upload**, select **Upload CRL…**, choose the CRL file (PEM or DER) and select **Upload**. The CRL must be signed by the CA and newer than the one the manager holds (`CRL_ROLLBACK` otherwise). Upload a new one before the next update shown on the page. + +## Set the OCSP mode + +Select **OCSP…**, choose the mode and, for `url`, the **Responder URL**, then **Save**. For `url` the dialog shows who signed the probe response: the CA itself or a delegated responder, and how long that responder certificate is valid. OCSP only ever adds revocations; it never overrides the denylist or the CRL. + +## Retire a CA + +1. Select **Retire…** on the CA. +2. Read the warning. If your own certificate comes only from this CA, retiring it signs you out for good: the manager refuses unless you tick **Retire it even if this would lock myself out**. +3. Select **Retire this CA**. + +:::danger[Retiring stops every certificate under the CA] +Every certificate the CA issued is refused from its next request, and MCP keys bound to them stop working. The manager refuses to retire the last active CA (error 1609): register its replacement first. +::: + +## Where to go next + +- [The operator CA and revocation](./operator-ca.md): the CA, the CRL, the denylist and the config keys. +- [Adding operators in the web UI](./web-operator-credentials.md): requesting and denying operator certificates. diff --git a/docs/fleet-manager/web-ui.md b/docs/fleet-manager/web-ui.md index 316640e..951812e 100644 --- a/docs/fleet-manager/web-ui.md +++ b/docs/fleet-manager/web-ui.md @@ -72,7 +72,7 @@ If the manager turns you away, the page says why and offers **Try again**: ## Finding your way around -The header holds the CryptOS mark (back to the Dashboard), your certificate's name, **Copy diagnostics** and a light and dark theme switch. The bar under it has every section: Dashboard, Fleet, Root, Nodes, Adopt, Certificates, Enrollment, Profiles, Protocols, Operators, Agent keys, Approvals and Audit. +The header holds the CryptOS mark (back to the Dashboard), your certificate's name, **Copy diagnostics** and a light and dark theme switch. The bar under it has every section: Dashboard, Fleet, Root, Nodes, Adopt, Certificates, Enrollment, Profiles, Protocols, Operator CAs, Operators, Agent keys, Approvals and Audit. **Operator CAs** is its own task: see [Managing operator CAs in the web UI](./web-operator-cas.md). Lists refresh every 10 seconds. Every table has filters and a search box. diff --git a/sidebars.ts b/sidebars.ts index f5d9e9e..47e1c18 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -108,6 +108,7 @@ const sidebars: SidebarsConfig = { 'fleet-manager/web-operator-credentials', 'fleet-manager/make-a-credential-request', 'fleet-manager/approvals', + 'fleet-manager/web-operator-cas', ], }, { From 15203c6d3ac5b63b42c2203a24ffd2ca6711d1b4 Mon Sep 17 00:00:00 2001 From: Bugs5382 <12115015+Bugs5382@users.noreply.github.com> Date: Thu, 1 Oct 2026 09:33:52 -0400 Subject: [PATCH 2/2] docs(fleet-manager): point the credentials page at the web UI's Operators page The web UI's request and record screens have shipped, so the note saying they weren't in this release now links to the page that walks through them. Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com> --- docs/fleet-manager/operator-credentials.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/fleet-manager/operator-credentials.md b/docs/fleet-manager/operator-credentials.md index fbb8a76..979a407 100644 --- a/docs/fleet-manager/operator-credentials.md +++ b/docs/fleet-manager/operator-credentials.md @@ -19,8 +19,8 @@ Adding an operator takes four steps: You need an admin certificate from the operator CA, and the manager needs `database_url`: requests and recorded credentials live in Postgres. Without it every step fails with error 1603 (`DATABASE_REQUIRED`). With no operator CA configured at all, requesting, listing and recording fail with error 1400. ::: -:::info[Not in the web UI yet] -The web UI's screens for requesting and recording credentials are not in this release. Until they are, call the `FleetService` RPCs named below with your admin certificate. +:::tip[In the web UI] +The web UI's **Operators** page does each step below: see [Adding operators in the web UI](./web-operator-credentials.md). This page names the `FleetService` RPCs behind it, for scripting. ::: ## 1. Request a credential