Skip to content

docs(reference): write the reference pages from the alpha - #35

Merged
Bugs5382 merged 5 commits into
docs/stub-pagesfrom
docs/20-reference-pages
Sep 30, 2026
Merged

Bugs5382 merged 5 commits into
docs/stub-pagesfrom
docs/20-reference-pages

Conversation

@Bugs5382

Copy link
Copy Markdown
Contributor

What and why

Writes the Reference pages that were still stubs, for an operator who has never seen CryptOS. Every field, value, error string and command is taken from cryptos, api and manager on main.

  • machine-config: the document header, metadata, role, network, bootstrap, install, state_key and management, with types, defaults, every validation rule and its exact error, plus how an apply works (live versus reboot, and what the MachineConfig message can't carry).
  • machine-config-pki (new): the CA key, subject and lifetime, parent, revocation, Root leaf issuance, and certificate profiles.
  • machine-config-enrollment (new): the pki.acme and pki.est blocks, with key and digest commands in Linux / macOS and Windows (PowerShell) tabs.
  • root-cert-profile: every field and extension the ceremony's self-signed Root carries, what it leaves out and why, and how to check a Root with cryptosctl and openssl. The sample output comes from a Root built by the real signing code.
  • audit-log: the node's line format, fields, details keys, chain and signature rules, the signing key, what isn't possible yet, and the Fleet Manager's own audit record.
  • glossary: plain definitions for the terms the site uses, with planned features marked.

The schema didn't fit one page, so machine-config is split into three, with the two new pages added to the sidebar right after it. Titles, emoji and the existing sidebar positions are unchanged. The cryptosctl and grpc-api pages are left alone; this PR only links to them.

Closes #20

Verification

  • Build succeeds
  • Documentation updated (if behavior or API changed)

How this was verified

  • npm run build and npm run typecheck on this branch: success, with no broken link or anchor warnings.
  • The example configs were run through the node's own parser (config.Parse) and pass. The unknown-field error, the extra_extensions byte-list format and the revocation resolver warning are the real parser output.
  • The Root sample output is openssl x509 -text on certificates made by the node's SelfSignRoot with ECDSA P-384 and RSA-3072 keys.
  • The audit lines are real output of the node's audit logger, and they pass its chain verifier.
  • The bash commands were run on macOS; the PowerShell commands use only RandomNumberGenerator, Convert and Get-FileHash, which exist in PowerShell 5.1 and 7.
  • The repo's forbidden-text list finds nothing in the changed files.

@Bugs5382 Bugs5382 added this to the v0.1.0 milestone Sep 30, 2026
@Bugs5382 Bugs5382 added the documentation Documentation only (docs). label Sep 30, 2026
@Bugs5382 Bugs5382 self-assigned this Sep 30, 2026
@Bugs5382
Bugs5382 marked this pull request as ready for review September 30, 2026 02:17
@Bugs5382

Copy link
Copy Markdown
Contributor Author

Commit 89e398b updates the pages that said an RSA CA key can't be held in the TPM. It depends on CryptOS-PKI/cryptos-node#282, which adds TPM-held RSA-3072 and RSA-4096 CA keys and the FailedPrecondition refusal on TPMs without the size. Merge the two together.

@Bugs5382

Copy link
Copy Markdown
Contributor Author

Added 3a1ae8d for CryptOS-PKI/cryptos-node#286: the ACME and EST blocks now travel in MachineConfig, so machine-config-enrollment and machine-config describe switching them on and off, the reboot and maintenance-window callout, the write-only secrets, the Root refusal and the new error messages. It depends on CryptOS-PKI/cryptos-node#286 and should merge with it.

Replace the machine config, audit log, Root certificate profile and
glossary stubs with pages written from the code on main. The machine
config schema is split into three pages (overview, pki, ACME and EST)
to keep each one readable, with sidebar entries for the two new pages.

Refs #20

Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com>
Drop the Planned callouts and the Planned and Root Mode glossary entries, and say plainly what isn't available without promising it. The Fleet Manager audit table now lists the step-up approval kinds and fields the manager records.

Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com>
Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com>
machine-config-pki and machine-config said the TPM path holds ECDSA P-384 keys only and quoted the old refusal. With CryptOS-PKI/cryptos-node#282 an RSA-3072 or RSA-4096 CA key is created in the TPM when the TPM implements that size, and key creation fails with FailedPrecondition, never falling back, when it does not. The callouts now say that. Depends on CryptOS-PKI/cryptos-node#282 and should merge with it.

Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com>
The enrolment page and the machine-config apply section now say the
blocks travel in MachineConfig: switching a protocol is a
reboot-required change best done in a maintenance window, the secrets
are write-only, and a Root refuses both blocks. Adds the two new
refusal messages to each error table.

Depends on CryptOS-PKI/cryptos-node#286.

Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com>
@Bugs5382
Bugs5382 force-pushed the docs/20-reference-pages branch from 3a1ae8d to ca1bdb5 Compare September 30, 2026 10:12
@Bugs5382

Copy link
Copy Markdown
Contributor Author

Closing summary: writes the Reference pages (machine config, the new machine-config PKI and enrollment pages with their sidebar entries, the audit log, the Root certificate profile and the glossary), with every field, value, error string and command taken from cryptos, api and manager on main. Rebased onto docs/stub-pages (now level with main, including the theme, the VMCA pages and the install pages) with every commit signed off; npm run build passes with no broken links. Merged with a merge commit so each signed-off commit reaches the parent PR's DCO check intact.

@Bugs5382
Bugs5382 merged commit 57454ff into docs/stub-pages Sep 30, 2026
@Bugs5382
Bugs5382 deleted the docs/20-reference-pages branch September 30, 2026 10:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Documentation only (docs).

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant