| blob | 040573f4cde99da1cbb0cace7e6fc1d86f62d11f |
1 .\" Copyright (c) 2022 Kungliga Tekniska Högskolan
2 .\" (Royal Institute of Technology, Stockholm, Sweden).
3 .\" All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
8 .\"
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\"
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\"
16 .\" 3. Neither the name of the Institute nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .\" $Id$
33 .\"
34 .Dd February 22, 2022
35 .Dt HXTOOL 1
36 .Os HEIMDAL
37 .Sh NAME
38 .Nm hxtool
39 .Nd PKIX command-line utility
40 .Sh SYNOPSIS
41 .Nm
42 .Bk -words
43 .Oo Fl Fl version Oc
44 .Oo Fl Fl help Oc
45 .Op Ar sub-command
46 .Ek
47 .Sh DESCRIPTION
48 .Nm
49 is a utility for making certificate sigining requests (CSRs),
50 displaying CSRs, signing certificates, etc.
51 are given, then the value will be parsed and displayed using just
52 the self-describing nature of DER.
53 .Pp
54 All sub-commands have their own help message, shown when invoked
55 with the
56 .Fl Fl help
57 or
58 .Fl h
59 option.
60 .Pp
61 Supported commands:
62 .Bl -tag -width Ds -offset indent
63 .It help
64 .It list-oids
65 .It verify
66 Verify a certificate and its certification path up to a trust
67 anchor, possibly checking CRLs.
68 .It print
69 Prints a human-readable rendering of certificates in a store.
70 See
71 .Sx CERTIFICATE STORES.
72 .It validate
73 Validate a certificate (but not a full chain).
74 .It certificate-copy, cc
75 Copy ceritificates and possibly private keys from one store to
76 another.
77 See
78 .Sx CERTIFICATE STORES.
79 .It ocsp-fetch
80 Fetch an OCSP response.
81 .It ocsp-verify
82 Fetch an OCSP response chain.
83 .It ocsp-print
84 Prints a human-readable rendering of an OCSP response chain.
85 .It revoke-print
86 Prints a human-readable rendering of a CRL or OCSP response
87 chain.
88 .It generate-key
89 Generates a private key.
90 .It request-create
91 Generates a Certificate Signing Request (CSR).
92 .It request-print
93 Prints a human-readable rendering of a CSR.
94 .It query
95 Queries a certificate store.
96 .It info
97 Prints information about supported algorithms.
98 .It random-data
99 Outputs entropy using a random number generator.
100 .It crypto-available
101 Tests if a cryptographic algorithm is available.
102 .It crypto-select
103 Selects a supported cryptographic algorithm given a peer's
104 capabilities.
105 .It hex
106 Hex-encode/decode utility.
107 .It certificate-sign, cert-sign, issue-certificate, ca
108 Issue a certificate.
109 .It crl-sign
110 Sign a CRL.
111 .It cms-create-sd, cms-sign
112 Created a CMS SignedData.
113 .It cms-verify-sd
114 Verifies a CMS SignedData.
115 .It cms-unenvelope
116 Extracts enveloped data from a CMS SignedData.
117 .It cms-envelope
118 Creates an enveloped CMS SignedData.
119 .El
120 Other sub-commands reported by the
121 .Nm help
122 sub-command are not stable or fully supported at this time.
123 .Sh CERTIFICATE STORES
124 Stores of certificates and/or keys have string names that can be
125 used with
126 .Nm 's
127 commands as well as in various configuration parameters and
128 command-line arguments of Heimdal's Kerberos implementation (for
129 PKINIT).
130 .Pp
131 For example,
132 .Ql FILE:/path/to/file ,
133 .Ql PEM-FILE:/path/to/file ,
134 .Ql DER-FILE:/path/to/file ,
135 etc.
136 See below for a full list of store types.
137 .Pp
138 A certificate store name starts with a store TYPE followed by a
139 colon followed by a name of form specific to that store type.
140 .Pp
141 Private keys can be stored in the same stores as the certificates
142 that certify their public keys.
143 .Pp
144 Private keys can also be stored in separate files, but still be
145 referenced in one certificate store name by joining two with a
146 comma:
147 .Ql FILE:/path/to/certificate,/path/to/private/key
148 .
149 .Pp
150 Heimdal supports a variety of certificate and private key store
151 types:
152 .Bl -tag -width Ds -offset indent
153 .It PEM-FILE:/path
154 If writing, PEM will be written (private keys may be written in
155 algorithm-specific formats or in PKCS#8).
156 If reading, PEM will be expected (private keys may be in
157 algorithm-specific formats or in PKCS#8).
158 .It DER-FILE:/path
159 If writing, DER will be written.
160 If reading, DER will be expected.
161 Private keys will be in algorithm-specific formats.
162 .It FILE:/path
163 If writing, PEM will be written as if
164 .Ql PEM-FILE
165 had been used.
166 If reading, PEM or DER will be detected and read as if
167 .Ql PEM-FILE
168 or
169 .Ql DER-FILE
170 had been used.
171 .It PKCS12:/path
172 If writing, PKCS#12 will be written.
173 If reading, PKCS#12 will be expected.
174 Note that PKCS#12 support is currently very limited.
175 .It DIR:/path
176 OpenSSL-style hashed directory of trust anchors.
177 .It KEYCHAIN:system-anchors
178 On OS X this refers to the system's trust anchors.
179 .It KEYCHAIN:FILE:/path
180 On OS X this refers to an OS X keychain at the given path.
181 .It PKCS11:/path/to/shared/object[,slot=NUMBER]
182 Loads the given PKCS#11 provider object and uses the token at the
183 given slot number, or else the first token found.
184 .It NULL:
185 An empty store.
186 .It MEMORY:name
187 An in-memory only, ephemeral store, usually never used in
188 .NM 's
189 commands.
190 The MEMORY store name exists primarily for internal
191 .Sq hx509
192 APIs.
193 .El
194 .Pp
195 Use the
196 .Nm certificate-copy
197 command to copy certificates from one store to another.
198 This is useful for, e.g., converting DER files to PEM or
199 vice-versa, removing private keys, adding certificate chains,
200 and removing root certificates from chains.
201 .Sh CERTIFICATES
202 You can validate a certificate with the
203 .Nm validate
204 sub-command, or verify a certificate and its certification path
205 with the
206 .Nm verify
207 sub-command.
208 .Pp
209 You can display a certificate using the
210 .Nm print
211 sub-command:
212 .Pp
213 .Nm print
214 .Oo options Oc
215 .Ar STORE
216 .Pp
217 Options:
218 .Bl -tag -width Ds -offset indent
219 .It Fl Fl content
220 .It Fl Fl info
221 .It Fl Fl never-fail
222 .It Fl Fl pass=password
223 .It Fl Fl raw-json
224 .El
225 .Pp
226 The
227 .Fl Fl pass=password
228 option is for PKCS#8 (PEM), PKCS#12 and PKCS#11 stores, and if
229 needed and not given, will be prompted for.
230 Note that it's not secure to pass passwords as command-line
231 arguments on multi-tenant systems.
232 .Pp
233 The
234 .Fl Fl raw-json
235 option prints the certificate(s) in the given
236 .Ar STORE
237 as a JSON dump of their DER using an experimental (i.e.,
238 unstable) schema.
239 .Sh KEYS
240 The
241 .Nm generate-key
242 sub-command will generate a key.
243 .Sh CERTIFICATE SIGNING REQUESTS
244 The
245 .Nm request-create
246 sub-command will create a CSR, and has support for requesting
247 subject alternative names and extended key usage extensions.
248 See its
249 .Fl Fl help
250 option, and see
251 .Sx EXAMPLES
252 below.
253 .Pp
254 The
255 .Nm request-print
256 sub-command will display a CSR.
257 .Sh CERTIFICATE ISSUANCE / CERTIFICATION AUTHORITY
258 The
259 .Nm certificate-sign
260 sub-command will issue a certificate.
261 See its usage message.
262 .Sh ONLINE CERTIFICATE STATUS PROTOCOL
263 The
264 .Nm ocsp-fetch
265 sub-command will fetch OCSP Responses for the given
266 certificates.
267 .Pp
268 The
269 .Nm ocsp-verify
270 sub-command will verify OCSP Responses.
271 .Pp
272 The
273 .Nm ocsp-print
274 sub-command will display OCSP Responses.
275 .Sh CERTIFICATE REVOCATION LIST
276 The
277 .Nm crl-sign
278 sub-command will add certificates to a certificate revocation
279 list.
280 .Sh EXAMPLES
281 Generate an RSA key:
282 .Bd -literal -offset indent
283 hxtool generate-key --type=rsa --key-bits=4096 PEM-FILE:key.pem
284 .Ed
285 .Pp
286 Create a CSR (with an empty name) for some key:
287 .Bd -literal -offset indent
288 hxtool request-create --subject= --key=FILE:key.pem csr.der
289 .Ed
290 .Pp
291 Generate a key and create a CSR (with an empty name) for it:
292 .Bd -literal -offset indent
293 hxtool request-create \\
294 --subject= \\
295 --generate-key=rsa \\
296 --key-bits=4096 \\
297 --key=FILE:key.pem \\
298 csr.der
299 .Ed
300 .Pp
301 Generate a key and create a CSR with an empty name but also
302 requesting a specific dNSName subject alternative name (SAN) for
303 it:
304 .Bd -literal -offset indent
305 hxtool request-create \\
306 --subject= \\
307 --generate-key=rsa \\
308 --dnsname=foo.test.h5l.se \\
309 --key=FILE:key.pem \\
310 csr.der
311 .Ed
312 .Pp
313 Print a CSR:
314 .Bd -literal -offset indent
315 hxtool request-print csr.der
316 .Ed
317 which outputs:
318 .Bd -literal -offset indent
319 request print
320 PKCS#10 CertificationRequest:
321 name:
322 san: dNSName: foo.test.h5l.se
323 .Ed
324 .Pp
325 Issue a end-entity certificate for an HTTPS server given a CSR:
326 .Bd -literal -offset indent
327 hxtool issue-certificate \\
328 --type=https-server \\
329 --subject= \\
330 --hostname=foo.test.h5l.se \\
331 --ca-certificate=FILE:cacert.pem \\
332 --ca-private-key=FILE:cakey.pem \\
333 --req=PKCS10:csr.der \\
334 --certificate=PEM-FILE:ee.pem
335 .Ed
336 .Pp
337 Add a chain to a PEM file:
338 .Bd -literal -offset indent
339 hxtool copy-certificiate \\
340 --no-private-keys \\
341 --no-root-certs \\
342 FILE:ca.pem FILE:ee.pem
343 .Ed
344 .Pp
345 Create a self-signed end-entity certificate for an HTTPS server:
346 .Bd -literal -offset indent
347 hxtool issue-certificate \\
348 --self-signed \\
349 --type=https-server \\
350 --subject= \\
351 --hostname=foo.test.h5l.se \\
352 --ca-private-key=FILE:key.pem \\
353 --certificate-private-key=FILE:key.pem \\
354 --certificate=PEM-FILE:cert.pem
355 .Ed
356 .Pp
357 Create a root certification authority certificate:
358 .Bd -literal -offset indent
359 hxtool issue-certificate \\
360 --issue-ca \\
361 --self-signed \\
362 --subject=CN=SomeRootCA \\
363 --ca-private-key=FILE:rootkey.pem \\
364 --certificate=PEM-FILE:rootcert.pem
365 .Ed
366 .Pp
367 Create an intermediate certification authority certificate from a
368 CSR:
369 .Bd -literal -offset indent
370 hxtool issue-certificate \\
371 --type=https-server \\
372 --subject=CN=SomeIntermediateCA \\
373 --ca-certificate=FILE:parent-cert.pem \\
374 --ca-private-key=FILE:parent-key.pem \\
375 --req=PKCS10:csr.der \\
376 --certificate=PEM-FILE:intermediate.pem
377 .Ed
378 .Pp
379 .Sh SEE ALSO
380 .Xr openssl 1