1UACME(1) User Commands UACME(1)
2
6 uacme - ACMEv2 client written in plain C with minimal dependencies
7
9 uacme [-a|--acme-url URL] [-b|--bits BITS] [-c|--confdir DIR]
10 [-d|--days DAYS] [-e|--eab KEYID:KEY] [-f|--force] [-h|--hook PROGRAM]
11 [-l|--alternate N | FP] [-m|--must-staple] [-n|--never-create]
12 [-o|--no-ocsp] [-r|--reason CODE] [-s|--staging] [-t|--type RSA|EC]
13 [-v|--verbose ...] [-V|--version] [-y|--yes] [-?|--help] new [EMAIL] |
14 update [EMAIL] | deactivate | newkey | issue IDENTIFIER [ALTNAME ...]]
15 | issue CSRFILE | revoke CERTFILE [CERTKEYFILE]
16
18 uacme is a client for the ACMEv2 protocol described in RFC8555, written
19 in plain C with minimal dependencies (libcurl and one of GnuTLS,
20 OpenSSL or mbedTLS). The ACMEv2 protocol allows a Certificate Authority
21 (https://letsencrypt.org is a popular one) and an applicant to automate
22 the process of verification and certificate issuance. The protocol also
23 provides facilities for other certificate management functions, such as
24 certificate revocation. For more information see
25 https://tools.ietf.org/html/rfc8555
26
28 -a, --acme-url URL
29 ACMEv2 server directory object URL. If not specified uacme uses one
30 of the following:
31 https://acme-v02.api.letsencrypt.org/directory
33 production URL
34 https://acme-staging-v02.api.letsencrypt.org/directory
36 staging URL (see -s, --staging below)
37 -b, --bits BITS
39 key bit length (default 2048 for RSA, 256 for EC). Only applies to
40 newly generated keys. RSA key length must be a multiple of 8
41 between 2048 and 8192. EC key length must be either 256
42 (NID_X9_62_prime256v1 curve) or 384 (NID_secp384r1 curve).
43 -c, --confdir CONFDIR
45 Use configuration directory CONFDIR (default /etc/ssl/uacme). The
46 structure is as follows (multiple IDENTIFIERs allowed)
47 CONFDIR/private/key.pem
49 ACME account private key
50 CONFDIR/private/IDENTIFIER/key.pem
52 certificate key for IDENTIFIER
53 CONFDIR/IDENTIFIER/cert.pem
55 certificate for IDENTIFIER
56 -d, --days DAYS
58 Do not reissue certificates that are still valid for longer than
59 DAYS (default 30). See also -o, --no-ocsp.
60 -e, --eab KEYID:KEY
62 Specify RFC8555 External Account Binding credentials according to
63 https://tools.ietf.org/html/rfc8555#section-7.3.4, in order to
64 associate a new ACME account with an existing account in a non-ACME
65 system such as a CA customer database. KEYID must be an ASCII
66 string. KEY must be base64url-encoded.
67 -f, --force
69 Force certificate reissuance regardless of expiration date.
70 -h, --hook PROGRAM
72 Challenge hook program. If not specified uacme interacts with the
73 user for every ACME challenge, printing information about the
74 challenge type, token and authorization on stderr. If specified
75 uacme executes PROGRAM (a binary, a shell script or any file that
76 can be executed by the operating system) for every challenge with
77 the following 5 string arguments:
78 METHOD
80 one of begin, done or failed.
81 begin
83 is called at the beginning of the challenge. PROGRAM must
84 return 0 to accept it. Any other return code declines the
85 challenge. Neither done nor failed method calls are made
86 for declined challenges.
87 done
89 is called upon successful completion of an accepted
90 challenge.
91 failed
93 is called upon failure of an accepted challenge.
94 TYPE
96 challenge type (dns-01, http-01 or tls-alpn-01)
97 IDENT
99 The identifier the challenge refers to
100 TOKEN
102 The challenge token
103 AUTH
105 The key authorization (for dns-01 and tls-alpn-01 already
106 converted to the base64url-encoded SHA256 digest format)
107 -l, --alternate N | FP
109 According to https://tools.ietf.org/html/rfc8555#section-7.4.2 the
110 server MAY provide one or more additional certificate download
111 URLs, each pointing to alternative certificate chains starting with
112 the same end-entity certificate. This option allows selecting one
113 such chain in one of two ways. A positive integer N makes uacme
114 select the Nth alternative chain in the order presented by the
115 server. A colon (:) separated list of two or more 2-digit
116 hexadecimal numbers FP makes uacme select the first alternative
117 chain containing a certificate whose SHA256 fingerprint begins with
118 FP. In both cases uacme falls back to the main certificate URL if
119 it cannot match an alternative chain or the download thereof fails.
120 -m, --must-staple
122 Request certificates with the RFC7633 Certificate Status Request
123 TLS Feature Extension, informally also known as "OCSP Must-Staple".
124 This option is ignored when using an externally supplied
125 Certificate Signing Request file (see USAGE below).
126 -n, --never-create
128 By default uacme creates directories/keys if they do not exist.
129 When this option is specified uacme never does so and instead exits
130 with an error if anything required is missing.
131 -o, --no-ocsp
133 When this flag is not specified and the certificate has an
134 Authority Information Access extension with an OCSP server location
135 according to https://tools.ietf.org/html/rfc5280#section-4.2.2.1
136 uacme makes an OCSP request to the server; if the certificate is
137 reported as revoked uacme forces reissuance regardless of the
138 expiration date. See also -d, --days.
139 -r, --reason CODE
141 Use CODE (default 0) as reason code in revocation requests. A list
142 of values is at https://tools.ietf.org/html/rfc5280#section-5.3.1.
143 -s, --staging
145 Use Let’s Encrypt staging URL for testing. This only works if -a,
146 --acme-url is NOT specified.
147 -t, --type=RSA | EC
149 Key type, either RSA or EC. Only applies to newly generated keys.
150 The bit length can be specified with -b, --bits.
151 -v, --verbose
153 By default uacme only produces output upon errors or when user
154 interaction is required. When this option is specified uacme prints
155 information about what is going on on stderr. This option can be
156 specified more than once to increase verbosity.
157 -V, --version
159 Print program version on stderr and exit.
160 -y, --yes
162 Autoaccept ACME server terms (if any) upon new account creation.
163 -?, --help
165 Print a brief usage text on stderr and exit.
166
168 uacme [OPTIONS ...] new [EMAIL]
169 Create a new ACME account with optional EMAIL contact. If the
170 account private key does not exist at CONFDIR/private/key.pem a new
171 key is generated unless -n, --never-create is specified. A valid
172 account must be created before any other operation can succeed
173 (with the exception of certificate revocation requests signed by
174 the certificate private key). Any certificate issued by the ACME
175 server is associated with a single account. An account can be
176 associated with multiple certificates, subject of course to the
177 rate limits imposed by the ACME server.
178 uacme [OPTIONS ...] update [EMAIL]
180 Update the EMAIL associated with the ACME account corresponding to
181 the account private key. If EMAIL is not specified the account
182 contact email is removed.
183 uacme [OPTIONS ...] deactivate
185 Deactivate the ACME account corresponding to the account private
186 key. WARNING this action is irreversible. Users may wish to do
187 this when the account key is compromised or decommissioned. A
188 deactivated account can no longer request certificate issuances and
189 revocations or access resources related to the account.
190 uacme [OPTIONS ...] newkey
192 Change the ACME account private key. If the new account private key
193 does not exist at CONFDIR/private/newkey.pem it is generated unless
194 -n, --never-create is specified. The new key is then submitted to
195 the server and if the operation succeeds the old key is hardlinked
196 to CONFDIR/private/key-TIMESTAMP.pem before renaming
197 CONFDIR/private/newkey.pem to CONFDIR/private/key.pem.
198 uacme [OPTIONS ...] issue IDENTIFIER [ALTNAME ...]
200 Issue a certificate for IDENTIFIER with zero or more ALTNAMEs. If a
201 certificate is already available at CONFDIR/IDENTIFIER/cert.pem for
202 the specified IDENTIFIER and ALTNAMEs and is still valid for longer
203 than DAYS no action is taken unless -f, --force is specified or -o,
204 --no-ocsp is not specified and the certificate is reported as
205 revoked by the OCSP server. The new certificate is saved to
206 CONFDIR/IDENTIFIER/cert.pem. If the certificate file already exists
207 it is hardlinked to CONFDIR/IDENTIFIER/cert-TIMESTAMP.pem before
208 overwriting. The private key for the certificate is loaded from
209 CONFDIR/private/IDENTIFIER/key.pem. If no such file exists, a new
210 key is generated unless -n, --never-create is specified. Wildcard
211 IDENTIFIERs or ALTNAMEs are dealt with correctly, as long as the
212 ACME server supports them; note that any such wildcards are
213 automatically removed from the configuration subdirectory name: for
214 example a certificate for *.test.com is saved to
215 CONFDIR/test.com/cert.pem. IP address IDENTIFIERs and ALTNAMEs are
216 also supported according to
217 https://tools.ietf.org/html/rfc8738#section-3
218 uacme [OPTIONS ...] issue CSRFILE
220 Issue a certificate based on a RFC2986 Certificate Signing Request
221 contained in CSRFILE, which must be in PEM format. In this mode of
222 issuance uacme neither needs nor generates the certificate private
223 key, but it is of course the responsibility of the user to ensure
224 that the CSR is constructed and signed appropriately. If a
225 certificate file CSRBASE-cert.pem (where CSRBASE is obtained by
226 stripping the extension, if any, from CSRFILE) is already available
227 in the same directory containing CSRFILE, and is still valid for
228 longer than DAYS no action is taken unless -f, --force is specified
229 or -o, --no-ocsp is not specified and the certificate is reported
230 as revoked by the OCSP server. If the certificate file already
231 exists it is hardlinked to BASENAME-cert-TIMESTAMP.pem before
232 overwriting. Wildcard identifiers in the CSR are dealt with
233 correctly, as long as the ACME server supports them. IP addresses
234 are also supported according to
235 https://tools.ietf.org/html/rfc8738#section-3
236 uacme [OPTIONS ...] revoke CERTFILE [CERTKEYFILE]
238 Revoke the certificate stored in CERTFILE. The revocation request
239 is signed with the private key of either the certificate, when
240 CERTKEYFILE is specified; or the ACME account associated with the
241 certificate, when only CERTFILE is specified. In the first instance
242 the account key and the configuration directory are not required.
243 If successful CERTFILE is renamed to revoked-TIMESTAMP.pem. The
244 reason code in the revocation request defaults to 0 but it can be
245 specified by the user with -r, --reason.
246
248 0
249 Success
250 1
252 Certificate not reissued because it is still current
253 2
255 Failure (syntax or usage error; configuration error; processing
256 failure; unexpected error).
257
259 The uacme.sh hook script included in the distribution can be used to
260 automate the certificate issuance with http-01 challenges, provided a
261 web server for the domain being validated runs on the same machine,
262 with webroot at /var/www
263 #!/bin/sh
265 CHALLENGE_PATH=/var/www/.well-known/acme-challenge
266 ARGS=5
267 E_BADARGS=85
268 if test $# -ne "$ARGS"
270 then
271 echo "Usage: $(basename "$0") method type ident token auth" 1>&2
272 exit $E_BADARGS
273 fi
274 METHOD=$1
276 TYPE=$2
277 IDENT=$3
278 TOKEN=$4
279 AUTH=$5
280 case "$METHOD" in
282 "begin")
283 case "$TYPE" in
284 http-01)
285 echo -n "${AUTH}" > "${CHALLENGE_PATH}/${TOKEN}"
286 exit $?
287 ;;
288 *)
289 exit 1
290 ;;
291 esac
292 ;;
293 "done"|"failed")
294 case "$TYPE" in
295 http-01)
296 rm "${CHALLENGE_PATH}/${TOKEN}"
297 exit $?
298 ;;
299 *)
300 exit 1
301 ;;
302 esac
303 ;;
304 *)
305 echo "$0: invalid method" 1>&2
306 exit 1
307 esac
308
310 If you believe you have found a bug, please create a new issue at
311 https://github.com/ndilieto/uacme/issues with any applicable
312 information.
313
315 ualpn(1)
316
318 uacme was written by Nicola Di Lieto
319
321 Copyright © 2019-2023 Nicola Di Lieto <nicola.dilieto@gmail.com>
322 This file is part of uacme.
324 uacme is free software: you can redistribute it and/or modify it under
326 the terms of the GNU General Public License as published by the Free
327 Software Foundation, either version 3 of the License, or (at your
328 option) any later version.
329 uacme is distributed in the hope that it will be useful, but WITHOUT
331 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
332 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
333 for more details.
334 You should have received a copy of the GNU General Public License along
336 with this program. If not, see http://www.gnu.org/licenses/.
337uacme 1.7.4 07/22/2023 UACME(1)