Skip to content

feat(tsa): switch the time-stamp authority on from machine config - #354

Merged
Bugs5382 merged 1 commit into
mainfrom
feat/287-tsa-config
Oct 6, 2026
Merged

Bugs5382 merged 1 commit into
mainfrom
feat/287-tsa-config

Conversation

@Bugs5382

@Bugs5382 Bugs5382 commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

What and why

Last of the RFC 3161 time-stamp authority PRs (task 5 of the issue): the pki.tsa config mapping, the
boot-time start, status, the ListTsaCertificates RPC and cryptosctl tsa certificates. With this the
TSA can be switched on from machine config.

Config (internal/config/tsa.go):

  • pki.tsa follows the protocol block rules ACME and EST use. A block without enabled (YAML) or with
    enabled=true (proto) is on. enabled=false keeps the settings in an off block that is never served
    and never checked for completeness. An apply that leaves the block out keeps the stored one.
  • A Root refuses enabled=true and accepts an off block.
  • An enabled block needs a valid policy_oid. There is no default, as the contract says. It is at
    least two decimal arcs without leading zeros, a first arc of 0 to 2, and a second arc below 40 under
    0 or 1.
  • Other checks on an enabled block: accuracy_ms of at most 60000, a port in range, parseable
    allowed_networks (CIDR prefixes or bare addresses), and certificate.validity_days of at most 365
    with a shorter overlap.
  • Every change is reboot-required (NeedsReboot), and changing only an off block stays live.
  • Defaults: accuracy 1000 ms, 60 requests a minute, burst equal to the rate, validity 365 days, overlap
    30 days.

Boot (internal/init/tsa.go, run.go 12f):

  • On an Intermediate or Issuing node whose boot config has the block on, the TSA certificate is ensured
    before the listener starts. The key is created through the CA key backend (TPM-held on a TPM node)
    with the CA key's configured algorithm.
  • The certificate is signed with the CA key, loaded and released, and recorded in the issued set under
    the profile tsa. It carries CDP and AIA pointers when revocation_base_url is set.
  • The listener starts on port 318 by default (IANA's Time Stamp Protocol port), and the certificate is
    re-checked every hour.
  • The clock gate reads the time-sync engine's status.
  • If set-up fails, the TSA is off for this boot and the reason is logged, as SCEP does, rather than
    failing the boot.

Status and RPC:

  • NodeStatus.protocols reports SERVICE_PROTOCOL_TSA: configured from the stored config, running
    from this boot, and a pending reboot when they differ.
  • ListTsaCertificates is served on the local and mTLS servers, authorized like ListIssued. It reads
    the store whether or not the TSA runs this boot, newest first. Only the certificate in use while the
    TSA runs is current, and every past certificate stays listed.
  • The maintenance servers answer FailedPrecondition.
  • cryptosctl tsa certificates prints the list, and --pem prints the certificates.

Removed, because the RPC is now served:

  • internal/grpc/unserved.go (the Unimplemented stub) and internal/grpc/unserved_test.go
    (TestUnservedRPCs_ReturnUnimplemented, which pinned the stub's answer).
  • The ListTsaCertificates entry in unservedByDesign in internal/apiconformance/roundtrip_test.go.

Docs: docs/tsa.md (new) and the README. The companion site PR is CryptOS-PKI/website#97 (the TSA
how-to, the policy OID walkthrough, the pki.tsa reference and the cryptosctl reference).

Closes #287

Merge order: after #351, #352 and #353 (merged). Merge CryptOS-PKI/website#97
first, then this one.

Verification

  • Lint clean
  • Tests pass
  • Build succeeds
  • Documentation updated (if behavior or API changed)

How this was verified

task ci and task license pass locally. New tests:

  • internal/config: every validation rule, including the OID grammar and a Root with an on or off
    block; defaults; proto and YAML round trips of on and off blocks; the block rules (absent keeps, off
    keeps settings, an off block is not checked, on without a policy is refused); reboot classification.
  • internal/node: status reports the TSA configured, running and pending across a config apply that
    switches it off, and that apply needs a reboot.
  • internal/init: with the real software key backend and an embedded etcd, the built TSA answers a
    query over its handler. The token's signer chains to the CA and is not the CA certificate, and the CA
    key is released. The TSA certificate is in the issued set under tsa, a client outside
    allowed_networks gets 403, and an unsynced clock gives timeNotAvailable. The catalog marks the
    current certificate only while running and still lists it when not.
  • internal/grpc: maintenance FailedPrecondition, non-admin PermissionDenied, the list over mTLS
    and the local socket, and a read failure as Internal.
  • cmd/cryptosctl: the table (newest first, current marked), --pem, and the empty case.

No QEMU or lab run here. The image suite on this PR and the integration lane cover the boot path.

Map pki.tsa into the config with the protocol block rules: an absent
block keeps the stored one, enabled=false keeps the settings off, a
Root refuses enabled=true, and an enabled block needs a valid policy
OID (there is no default), an accuracy of at most 60 s, a certificate
validity of at most 365 days with a shorter overlap, and parseable
allowed networks. Every change is reboot-required.

At boot an Intermediate or Issuing node with the block on issues its TSA
certificate with a key from the CA key backend, starts the listener (port
318 by default), and re-checks the certificate hourly. Status reports the
TSA's configured and running state and a pending reboot.
ListTsaCertificates is served from the store whether or not the TSA
runs, and cryptosctl tsa certificates lists them.

Closes #287

Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com>
@Bugs5382 Bugs5382 self-assigned this Oct 6, 2026
@Bugs5382
Bugs5382 marked this pull request as ready for review October 6, 2026 20:14
@github-actions github-actions Bot added the enhancement New feature (feat). Minor version bump. label Oct 6, 2026
@Bugs5382

Bugs5382 commented Oct 6, 2026

Copy link
Copy Markdown
Contributor Author

Closing summary: maps pki.tsa into the config under the protocol block rules (policy OID required, Root refuses enabled, reboot-required), starts the TSA at boot on Intermediate/Issuing nodes with a CA-backend (TPM where present) key and an hourly certificate check, reports SERVICE_PROTOCOL_TSA in status, serves ListTsaCertificates, and adds cryptosctl tsa certificates plus docs/tsa.md. Companion docs CryptOS-PKI/website#97 merged. CI green.

@Bugs5382
Bugs5382 merged commit fe614e7 into main Oct 6, 2026
32 checks passed
@Bugs5382
Bugs5382 deleted the feat/287-tsa-config branch October 6, 2026 20:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature (feat). Minor version bump.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(tsa): serve RFC 3161 timestamps for code signing

1 participant