1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
|
.TH ACMED 8
.SH NAME
auth/acmed \- acme certificate client
.SH SYNOPSIS
.B auth/acmed
[
.B -a
.I acctkey
]
[
.B -e
.I cmd
|
.B -o
.I chalout
.B -t
.I type
]
[
.B -p
.I provider
]
.I acctname
.I csr
>
.I crt
.SH DESCRIPTION
Acmed fetches and renews a TLS certificate
using the
.I ACME (RFC8555)
protocol.
It requires a pre-generated account key in
.IR factotum (4)
that is identified by
.I acctname
or an
.I acctkey
file.
It also needs a certificate signing request file
.I csr
in binary X.509 ASN.1/DER format
that contains the public key and subjects (domain names)
that we want to get a certificate for.
On success,
.I acmed
outputs the new certificate in
PEM format to stdandard output.
.PP
.I Acmed
accepts the following options:
.TP
.B -a
.I acctkey
Specifies that
.I acctkey
is used to sign requests to the
.I provider
in place of the default
.BI /sys/lib/tls/acme/ acctname .pub
file.
The key must be a JWK formatted RSA public key
(see
.IR rsa (8)).
.TP
.B -e
.I cmd
Specifies that an external command should be run to
install the challenge material.
The
.I cmd
is run with the following four arguments:
The challenge method,
the subject (domain),
the token,
and last the challenge response.
If
.I cmd
returns an error status,
it is assumed that it does not support the
challenge method for the given subject (domain)
and another method might be tried.
Because of this, the
.B -o
and
.B -t
options are unnecessary.
.TP
.B -o
.I chalout
Specifies that the challenge material is
placed in the location
.IR chalout .
Its behavior depends on the challenge type,
as specified with the
.B -t
flag.
.IP
For HTTP challenges,
.I chalout
must be a directory that your webserver will serve at
.br
.BI http:// mydomain.com /.well-known/acme-challenge .
.br
It defaults to
.BR /usr/web/.well-known/acme-challenge .
.IP
For DNS challenges,
.I chalout
is a file that should be included in your
.IR ndb (6)
database.
It defaults to
.BR /lib/ndb/dnschallenge .
.TP
.B -t
.I type
Specifies that the challenge type. Supported challenge
types are currently
.B http
and
.BR dns .
.TP
.B -p
.I provider
Specifies that
.I provider
is used as the provider URL, in place of the default
.BR https://acme-v02.api.letsencrypt.org/directory .
This must be the directory URL for the desired
.I RFC8555
compliant provider.
.SH EXAMPLES
Before
.I acmed
can be used, the account key must be generated:
.IP
.EX
auth/rsagen -t \\
'service=acme role=sign hash=sha256 acct=me@example.com' \\
> acct.key
auth/rsa2jwk acct.key > /sys/lib/tls/acmed/me@example.com.pub
.EE
.PP
Then the
.B acct.key
must be loaded into
.IR factotum (4).
It is recommended to put
.B acct.key
into
.IR secstore (1)
instead of saving it unencrypted on the file system.
.IP
.EX
cat acct.key > /mnt/factotum/ctl
.EE
.PP
On the TLS server side, you can generate a RSA key
and certificate signing request file like this:
.IP
.EX
auth/rsagen -t 'service=tls role=client owner=*' > cert.key
auth/rsa2csr 'CN=mydomain.com' cert.key \\
> /sys/lib/tls/acmed/mydomain.com.csr
.EE
.PP
See
.IR rsa (8)
and
.IR tlssrv (8)
for more examples on how to use RSA keys.
.IP
.PP
The certificate for the domain can now be fetched.
This requires
.IR webfs (4)
to be mounted as the ACME protocol uses HTTP
to talk to the provider.
.IP
.EX
auth/acmed me@example.com /sys/lib/tls/acmed/mydomain.com.csr \\
> /sys/lib/tls/acmed/mydomain.com.crt
.EE
.PP
When using the DNS challenge method,
your DNS server
(see
.IR ndb (8))
must be configured,
and
.IR ndb (6)
must be setup to include the
.I chalout
file that
.I acmed
can write to:
.IP
.EX
database=
file=/net/ndb
file=/lib/ndb/local
file=/lib/ndb/common
file=/lib/ndb/dnschallenge
.EE
.PP
In addition, the domains that you like to get verified
needs to have a certificate authority authorization record
of your ACME provider declared:
.IP
.EX
dom=mydomain.com caa=letsencrypt.org
.EE
.PP
Then
.I acmed
can be invoked to fetch the certificate using the
DNS challenge method:
.IP
.EX
auth/acmed -t dns me@example.com mydomain.com.csr \\
> /sys/lib/tls/acmed/mydomain.com.crt
.EE
.SH FILES
.BI /sys/lib/tls/acmed/ * .pub
Account public keys.
.SH SOURCE
.B /sys/src/cmd/auth/acmed.c
.SH SEE ALSO
.IR factotum (4),
.IR ndb (6),
.IR ndb (8),
.IR rsa (8),
.IR secstore (1),
.IR tlssrv (8),
.IR webfs (4).
.SH BUGS
.PP
When using DNS challenge,
the
.B -t
.B dns
method assumes that the DNS server runs
on the same machine as
.I acmed
and that it is mounted on
.B /net
and that we have hostowner permissions to
write the
.B refresh
command to
.BR /net/dns .
Also, when using multi-domain certificates,
the usable challenge methods might be different for
individual domains.
Using the
.B -e
.I cmd
option to customize the challenge installation procedure
can be used to work around this.
.PP
.B https://bugzilla.mozilla.org/show_bug.cgi?id=647959
.SH HISTORY
.PP
.I Auth/acmed
first appeared in 9front (Oct 2021)
|
