Skip to content

Commit 95847f3

Browse files
authored
feat(config): switch ACME and EST on and off through machine config (#286)
* feat(config): switch ACME and EST on and off through machine config Map pki.acme and pki.est in FromProto and ToProto, following the protocol-block rules in the api contract, and drop CarryForwardProtoGaps. - enabled=false, or a block that was never set, is off. An absent block in an apply keeps the stored one, so an older client cannot switch a protocol off by leaving it out. - Secrets are write-only: GetConfig returns hmac_key_base64 and password_sha256 blank, an apply with a blank secret keeps the stored value for the same key_id or username, and a blank secret for an unknown identifier is refused. config apply accepts the blanks client-side so config get output can be fed back. - A Root refuses an enabled protocol in config validation, which covers config apply, the maintenance install, re-provision and ceremony start --config. - The maintenance install and re-provision carry the blocks. - The listeners still start only at boot from the stored config, and every protocol change answers requires_reboot. - GetStatus fills NodeStatus.protocols (configured, running, reboot_pending) and config_reboot_pending, and cryptosctl status prints a Protocols line and flags a pending reboot. - NeedsReboot compares the stored YAML form, so an unchanged re-apply over the wire (empty lists arrive as nil) no longer asks for a reboot. The api module is pinned to a development merge of the CryptOS-PKI/api PR heads this needs; it re-pins to api main once they merge. Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com> * test(config): build the EST digest fixture instead of hard-coding it Gitleaks reads the hard-coded SHA-256 test digest as a generic API key. Use the package's testPasswordDigest helper, and record the one finding in the earlier commit of this branch in .gitleaksignore, since that commit stays in the history the scan reads. Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com> * build(deps): pin the api module to main The ACME and EST contract and GetIssuedCertificate are both merged on api main, so the branch no longer needs the combined development pin. Api main also carries the SCEP challenge and approval RPCs and ListTsaCertificates, which this node does not serve yet; they answer Unimplemented until their servers land. Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com> * chore(gitleaks): point the test digest entry at the rebased commit Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com> * docs(est): list ACME before EST in the status example, as cryptosctl prints it Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com> --------- Signed-off-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com> Co-authored-by: Bugs5382 <12115015+Bugs5382@users.noreply.github.com>
1 parent 0c657fb commit 95847f3

28 files changed

Lines changed: 1851 additions & 170 deletions

‎.gitleaksignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
205dd6475254419977b831d4b9feb35bc2b37caa:internal/config/protocols_test.go:generic-api-key:30

‎cmd/cryptosctl/config.go‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -58,10 +58,12 @@ func newConfigGetCmd(opts *globalOpts) *cobra.Command {
5858
Short: "Print the node's current machine configuration",
5959
Long: "Print the node's current machine configuration as YAML, ready to edit and " +
6060
"feed back to `config apply -f`.\n\n" +
61-
"The acme and est blocks are not returned: they carry secrets and are " +
62-
"deliberately absent from the wire format. That does not break a " +
63-
"read-edit-apply cycle, because the node carries those blocks forward from " +
64-
"its existing config when a new one is applied.",
61+
"The acme and est blocks are returned with their secrets blank: " +
62+
"hmac_key_base64 and password_sha256 are write-only. Leave a blank secret " +
63+
"as it is and `config apply` keeps the one the node stores for that key_id " +
64+
"or username; set it to replace it. A new key_id or username needs its " +
65+
"secret. Switching a protocol on or off, or changing its settings, takes " +
66+
"effect at the next reboot.",
6567
Args: cobra.NoArgs,
6668
RunE: func(cmd *cobra.Command, _ []string) error {
6769
client, closeConn, err := dial(opts)
@@ -117,7 +119,9 @@ func newConfigApplyCmd(opts *globalOpts) *cobra.Command {
117119
}
118120
// Validate client-side so the operator gets a clear error
119121
// before the round-trip; the node re-validates authoritatively.
120-
cfg, err := config.Parse(raw)
122+
// A blank protocol secret passes here because the node fills it
123+
// from the one it stores.
124+
cfg, err := config.ParseForApply(raw)
121125
if err != nil {
122126
return err
123127
}

‎cmd/cryptosctl/protocols_test.go‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
package main
2+
3+
/*
4+
Apache License 2.0
5+
6+
Copyright 2026 Shane
7+
8+
Licensed under the Apache License, Version 2.0 (the "License");
9+
you may not use this file except in compliance with the License.
10+
You may obtain a copy of the License at
11+
12+
http://www.apache.org/licenses/LICENSE-2.0
13+
14+
Unless required by applicable law or agreed to in writing, software
15+
distributed under the License is distributed on an "AS IS" BASIS,
16+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17+
See the License for the specific language governing permissions and
18+
limitations under the License.
19+
*/
20+
21+
import (
22+
"encoding/base64"
23+
"os"
24+
"path/filepath"
25+
"strings"
26+
"testing"
27+
28+
cryptosv1 "github.com/CryptOS-PKI/api/go/cryptos/v1"
29+
)
30+
31+
func TestHumanStatusShowsProtocols(t *testing.T) {
32+
s := &cryptosv1.NodeStatus{
33+
Role: cryptosv1.NodeRole_NODE_ROLE_ISSUING,
34+
Protocols: []*cryptosv1.ProtocolStatus{
35+
{Protocol: cryptosv1.ServiceProtocol_SERVICE_PROTOCOL_ACME, Configured: true, Running: true},
36+
{Protocol: cryptosv1.ServiceProtocol_SERVICE_PROTOCOL_EST, Configured: true, Running: false, RebootPending: true},
37+
},
38+
ConfigRebootPending: true,
39+
}
40+
out := humanStatus(s)
41+
for _, want := range []string{
42+
"Protocols:", "ACME on", "EST on (not running, reboot pending)",
43+
"Reboot:", "pending",
44+
} {
45+
if !strings.Contains(out, want) {
46+
t.Errorf("humanStatus missing %q in:\n%s", want, out)
47+
}
48+
}
49+
50+
off := humanStatus(&cryptosv1.NodeStatus{
51+
Protocols: []*cryptosv1.ProtocolStatus{
52+
{Protocol: cryptosv1.ServiceProtocol_SERVICE_PROTOCOL_ACME},
53+
{Protocol: cryptosv1.ServiceProtocol_SERVICE_PROTOCOL_EST, Running: true, RebootPending: true},
54+
},
55+
})
56+
for _, want := range []string{"ACME off", "EST off (still running, reboot pending)"} {
57+
if !strings.Contains(off, want) {
58+
t.Errorf("humanStatus missing %q in:\n%s", want, off)
59+
}
60+
}
61+
if strings.Contains(off, "Reboot:") {
62+
t.Errorf("humanStatus flagged a reboot the node did not report:\n%s", off)
63+
}
64+
65+
// A node that does not report protocols (maintenance mode, an older node)
66+
// prints no Protocols line rather than an empty one.
67+
if bare := humanStatus(&cryptosv1.NodeStatus{}); strings.Contains(bare, "Protocols:") {
68+
t.Errorf("humanStatus printed unreported protocols:\n%s", bare)
69+
}
70+
}
71+
72+
const protocolsConfig = `apiVersion: cryptos.dev/v1alpha1
73+
kind: MachineConfig
74+
metadata:
75+
name: pki-issuing-test
76+
role:
77+
kind: issuing
78+
network:
79+
interface: eth0
80+
address: 192.0.2.30/24
81+
gateway: 192.0.2.1
82+
pki:
83+
root_key_alg: ECDSA-P384
84+
root_subject:
85+
common_name: Protocols Issuing CA
86+
parent:
87+
ca_cert_sha256: abababababababababababababababababababababababababababababababab
88+
profiles:
89+
- name: leaf-server
90+
key_alg: ECDSA-P384
91+
validity_days: 90
92+
key_usage: [digital_signature]
93+
ext_key_usage: [server_auth]
94+
acme:
95+
base_url: https://ca.example.org/acme
96+
profile: leaf-server
97+
external_account_keys:
98+
- key_id: ops
99+
hmac_key_base64: EAB_KEY
100+
bootstrap:
101+
admin_cert_sha256: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
102+
`
103+
104+
// config get prints the EAB secret blank, and feeding that output back to
105+
// config apply keeps the secret the node holds.
106+
func TestConfigGetApply_KeepsWriteOnlySecret(t *testing.T) {
107+
ts := startTestServer(t)
108+
dir := t.TempDir()
109+
secret := base64.RawURLEncoding.EncodeToString([]byte("0123456789abcdef0123456789abcdef"))
110+
path := filepath.Join(dir, "machine.yaml")
111+
if err := os.WriteFile(path, []byte(strings.Replace(protocolsConfig, "EAB_KEY", secret, 1)), 0o600); err != nil {
112+
t.Fatalf("WriteFile: %v", err)
113+
}
114+
out, err := ts.run(t, "config", "apply", "-f", path)
115+
if err != nil {
116+
t.Fatalf("config apply: %v (out=%s)", err, out)
117+
}
118+
if !strings.Contains(out, "requires_reboot=true") {
119+
t.Errorf("switching ACME on did not report requires_reboot:\n%s", out)
120+
}
121+
122+
got, err := ts.run(t, "config", "get")
123+
if err != nil {
124+
t.Fatalf("config get: %v (out=%s)", err, got)
125+
}
126+
if strings.Contains(got, secret) {
127+
t.Fatalf("config get printed the EAB secret:\n%s", got)
128+
}
129+
if !strings.Contains(got, "key_id: ops") {
130+
t.Errorf("config get dropped the key_id:\n%s", got)
131+
}
132+
133+
back := filepath.Join(dir, "back.yaml")
134+
if err := os.WriteFile(back, []byte(got), 0o600); err != nil {
135+
t.Fatalf("WriteFile: %v", err)
136+
}
137+
out, err = ts.run(t, "config", "apply", "-f", back)
138+
if err != nil {
139+
t.Fatalf("config apply of the config get output: %v (out=%s)", err, out)
140+
}
141+
if !strings.Contains(out, "requires_reboot=false") {
142+
t.Errorf("an unchanged re-apply reported a reboot:\n%s", out)
143+
}
144+
}

‎cmd/cryptosctl/status.go‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,9 +72,44 @@ func humanStatus(s *cryptosv1.NodeStatus) string {
7272
if r := s.GetResolver(); r != nil {
7373
fmt.Fprintf(&b, "DNS: %s\n", humanResolver(r))
7474
}
75+
if ps := s.GetProtocols(); len(ps) > 0 {
76+
fmt.Fprintf(&b, "Protocols: %s\n", humanProtocols(ps))
77+
}
78+
if s.GetConfigRebootPending() {
79+
fmt.Fprintf(&b, "Reboot: pending (the stored config changes take effect at the next boot)\n")
80+
}
7581
return b.String()
7682
}
7783

84+
// humanProtocols renders the enrolment protocols as one line: each one on or
85+
// off as stored, with a note when this boot does not match it yet.
86+
func humanProtocols(ps []*cryptosv1.ProtocolStatus) string {
87+
parts := make([]string, 0, len(ps))
88+
for _, p := range ps {
89+
part := trimEnum(p.GetProtocol().String(), "SERVICE_PROTOCOL_")
90+
if p.GetConfigured() {
91+
part += " on"
92+
} else {
93+
part += " off"
94+
}
95+
var notes []string
96+
switch {
97+
case p.GetConfigured() && !p.GetRunning():
98+
notes = append(notes, "not running")
99+
case !p.GetConfigured() && p.GetRunning():
100+
notes = append(notes, "still running")
101+
}
102+
if p.GetRebootPending() {
103+
notes = append(notes, "reboot pending")
104+
}
105+
if len(notes) > 0 {
106+
part += " (" + strings.Join(notes, ", ") + ")"
107+
}
108+
parts = append(parts, part)
109+
}
110+
return strings.Join(parts, ", ")
111+
}
112+
78113
// humanPreflight renders the revocation preflight as one line: the state, the
79114
// base URL checked, when, and the last error while failing.
80115
func humanPreflight(p *cryptosv1.RevocationPreflight) string {

‎docs/acme.md‎

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,42 @@ Accepted reason codes are `unspecified` (0), `keyCompromise` (1),
137137
`privilegeWithdrawn` (9). `certificateHold` is refused: this CA has no hold
138138
workflow, and accepting the request would imply one.
139139

140+
## Switching it on, changing it and switching it off
141+
142+
ACME runs on an intermediate or issuing node only. A Root serves no enrolment
143+
protocol, so a config that sets `pki.acme` on a Root is refused by
144+
`config apply`, by the maintenance install and by `ceremony start --config`.
145+
146+
> [!CAUTION]
147+
> Don't add `pki.acme` to a Root's config. It is refused, and nothing is
148+
> stored. Serve ACME from an issuing node under that Root instead.
149+
150+
To switch ACME on, add the `pki.acme` block and run `config apply`. To
151+
switch it off, remove the block and apply again. Over the API the block is
152+
`Pki.acme` with an explicit `enabled` flag: `enabled: false` switches it
153+
off, and leaving the block out of an `ApplyConfig` keeps what the node has.
154+
155+
> [!WARNING]
156+
> Every ACME change, switching it on or off included, takes effect at the
157+
> next reboot, not when you apply it. `config apply` stores the change and
158+
> prints `requires_reboot=true`; the listener starts, stops or picks up the new
159+
> settings only when the node boots again. Plan the reboot for a maintenance
160+
> window, because the node stops issuing while it restarts, then use
161+
> `cryptosctl reboot`.
162+
163+
`cryptosctl status` shows what is stored against what is running until then:
164+
165+
```text
166+
Protocols: ACME on (not running, reboot pending), EST off
167+
Reboot: pending (the stored config changes take effect at the next boot)
168+
```
169+
170+
`hmac_key_base64` is write-only. `cryptosctl config get` prints it blank, with its
171+
`key_id`. Leave a blank value as it is and `config apply` keeps the one the
172+
node stores for that `key_id`; set a value to replace it. A new `key_id`
173+
needs its value, and an apply that leaves it blank is refused. Removing an
174+
entry revokes it.
175+
140176
## Limits worth knowing before you deploy
141177

142178
- **Key change is not implemented.** RFC 8555 section 7.3.5 is absent from the
@@ -148,5 +184,3 @@ workflow, and accepting the request would imply one.
148184
order that justified it.
149185
- **Validation runs inline on the challenge POST**, bounded by a ten-second
150186
timeout. The client's first poll already carries the answer.
151-
- **The `pki.acme` block is not yet carried in the proto machine config**, so
152-
it survives a staged YAML boot but not an `ApplyConfig` from a manager.

‎docs/est.md‎

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,42 @@ operation. Set `label: issuing` and every path moves under
199199
`/.well-known/est/issuing/`. The unlabelled paths then return 404, so a label
200200
is routing rather than decoration.
201201

202+
## Switching it on, changing it and switching it off
203+
204+
EST runs on an intermediate or issuing node only. A Root serves no enrolment
205+
protocol, so a config that sets `pki.est` on a Root is refused by
206+
`config apply`, by the maintenance install and by `ceremony start --config`.
207+
208+
> [!CAUTION]
209+
> Don't add `pki.est` to a Root's config. It is refused, and nothing is
210+
> stored. Serve EST from an issuing node under that Root instead.
211+
212+
To switch EST on, add the `pki.est` block and run `config apply`. To
213+
switch it off, remove the block and apply again. Over the API the block is
214+
`Pki.est` with an explicit `enabled` flag: `enabled: false` switches it
215+
off, and leaving the block out of an `ApplyConfig` keeps what the node has.
216+
217+
> [!WARNING]
218+
> Every EST change, switching it on or off included, takes effect at the
219+
> next reboot, not when you apply it. `config apply` stores the change and
220+
> prints `requires_reboot=true`; the listener starts, stops or picks up the new
221+
> settings only when the node boots again. Plan the reboot for a maintenance
222+
> window, because the node stops issuing while it restarts, then use
223+
> `cryptosctl reboot`.
224+
225+
`cryptosctl status` shows what is stored against what is running until then:
226+
227+
```text
228+
Protocols: ACME off, EST on (not running, reboot pending)
229+
Reboot: pending (the stored config changes take effect at the next boot)
230+
```
231+
232+
`password_sha256` is write-only. `cryptosctl config get` prints it blank, with its
233+
`username`. Leave a blank value as it is and `config apply` keeps the one the
234+
node stores for that `username`; set a value to replace it. A new `username`
235+
needs its value, and an apply that leaves it blank is refused. Removing an
236+
entry revokes it.
237+
202238
## Limits worth knowing before you deploy
203239

204240
- **Wildcards are refused.** Nothing in EST establishes control of a label
@@ -211,5 +247,3 @@ is routing rather than decoration.
211247
say answers 204.
212248
- **Issuance is synchronous.** There is no 202 Retry-After manual-approval
213249
flow; a request either yields a certificate or fails.
214-
- **The `pki.est` block is not yet carried in the proto machine config**, so
215-
it survives a staged YAML boot but not an `ApplyConfig` from a manager.

‎go.mod‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ module github.com/CryptOS-PKI/cryptos
33
go 1.25.0
44

55
require (
6-
github.com/CryptOS-PKI/api v0.0.0-20260929181434-442c13e13c15
6+
github.com/CryptOS-PKI/api v0.0.0-20260930142054-81494db99991
77
github.com/google/go-tpm v0.9.8
88
github.com/google/go-tpm-tools v0.4.8
99
github.com/spf13/cobra v1.10.2

‎go.sum‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
github.com/CryptOS-PKI/api v0.0.0-20260929181434-442c13e13c15 h1:ZSw1gdY7yy2872QDzCnNfchRPA3+d5Bgm4bYVvNZ55A=
2-
github.com/CryptOS-PKI/api v0.0.0-20260929181434-442c13e13c15/go.mod h1:tmeaYhNoUblqPYYNtTbGBGIUsZ7xLATgLdKq4S33rmE=
1+
github.com/CryptOS-PKI/api v0.0.0-20260930142054-81494db99991 h1:gRd3iY+smHPGl98k/T9Ezc9wG9/8hh+kJ8eZoGOOkW8=
2+
github.com/CryptOS-PKI/api v0.0.0-20260930142054-81494db99991/go.mod h1:tmeaYhNoUblqPYYNtTbGBGIUsZ7xLATgLdKq4S33rmE=
33
github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
44
github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
55
github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8=

‎internal/ceremony/ceremony.go‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -180,7 +180,10 @@ func (e *Engine) Start(ctx context.Context, req *cryptosv1.StartCeremonyRequest,
180180
return status.Error(codes.FailedPrecondition, "IDENTITY_EXISTS")
181181
}
182182

183-
// Parse + validate the operator's machine config from the request.
183+
// Parse + validate the operator's machine config from the request. The
184+
// raw YAML is stored below and the Root boots from it, so this is the
185+
// check that keeps an enrolment protocol off a Root: config.Parse refuses
186+
// a Root with pki.acme or pki.est set.
184187
if len(req.MachineConfigYaml) == 0 {
185188
return status.Error(codes.InvalidArgument, "ceremony: machine_config_yaml is required")
186189
}

0 commit comments

Comments
 (0)