From 9c0bc47efc6bb933049b916d5f72c1b97f29da42 Mon Sep 17 00:00:00 2001 From: Nicolas Williams Date: Sun, 7 Aug 2022 18:49:33 -0500 Subject: [PATCH] Add hxtool(1) manual page --- lib/hx509/hxtool.1 | 207 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 lib/hx509/hxtool.1 diff --git a/lib/hx509/hxtool.1 b/lib/hx509/hxtool.1 new file mode 100644 index 000000000..377500784 --- /dev/null +++ b/lib/hx509/hxtool.1 @@ -0,0 +1,207 @@ +.\" Copyright (c) 2022 Kungliga Tekniska Högskolan +.\" (Royal Institute of Technology, Stockholm, Sweden). +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 3. Neither the name of the Institute nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $Id$ +.\" +.Dd February 22, 2022 +.Dt HXTOOL 1 +.Os HEIMDAL +.Sh NAME +.Nm hxtool +.Nd PKIX command-line utility +.Sh SYNOPSIS +.Nm +.Bk -words +.Oo Fl Fl version Oc +.Oo Fl Fl help Oc +.Op Ar sub-command +.Ek +.Sh DESCRIPTION +.Nm +is a utility for making certificate sigining requests (CSRs), +displaying CSRs, signing certificates, etc. +are given, then the value will be parsed and displayed using just +the self-describing nature of DER. +.Pp +All sub-commands have their own help message, shown when invoked +with the +.Fl Fl help +or +.Fl h +option. +.Pp +Supported commands: +.Bl -tag -width Ds -offset indent +.It help +.It list-oids +.It verify +.It print +.It validate +.It certificate-copy, cc +.It ocsp-fetch +.It ocsp-verify +.It ocsp-print +.It revoke-print +.It generate-key +.It request-create +.It request-print +.It query +.It info +.It random-data +.It crypto-available +.It crypto-select +.It hex +.It certificate-sign, cert-sign, issue-certificate, ca +.It crl-sign +.El +Other sub-commands reported by the +.Nm help +sub-command are not stable or fully supported at this time. +.Sh CERTIFICATE STORES +Stores of certificates and/or keys have string names that can be +used with +.Nm 's +commands. +Sub-commands use these certificate store names to refer to files +and tokens where keys and/or certificates are to be found or +written. +For example, +.Sq FILE:/path/to/some/file . +.Pp +Use the +.Nm certificate-copy +command to copy certificates from one store to another. +This is useful for, e.g., converting DER files to PEM or +vice-versa. +.Pp +Heimdal supports a variety of certificate and key store types: +.Bl -tag -width Ds -offset indent +.It PEM-FILE:/path +If writing, PEM will be written. +If reading, PEM will be expected. +.It DER-FILE:/path +If writing, DER will be written. +If reading, DER will be expected. +.It FILE:/path +If writing, PEM will be written. +If reading, PEM or DER will be detected. +.It PKCS12:/path +Barely supported at this time. +.It DIR:/path +OpenSSL-style hashed directory of trust anchors. +.It MEMORY:name +An in-memory only store, usually never used in +.NM 's +commands. +.It KEYCHAIN:system-anchors +On OS X this refers to the system's trust anchors. +.It KEYCHAIN:FILE:/path +On OS X this refers to an OS X keychain at the given path. +.It NULL: +An empty store. +.It PKCS11:/path/to/shared/object,slot=NUMBER +Loads the given PKCS#11 provider object and uses the token at the +given slot number. +.El +.Sh CERTIFICATES +You can validate a certificate with the +.Nm validate +sub-command, or verify a certificate and its certification path +with the +.Nm verify +sub-command. +.Pp +You can display a certificate using the +.Nm print +sub-command: +.Pp +.Nm print +.Oo options Oc +.Ar STORE +.Pp +Options: +.Bl -tag -width Ds -offset indent +.Op Fl Fl content +.Op Fl Fl info +.Op Fl Fl never-fail +.Op Fl Fl pass=password +.Op Fl Fl raw-json +.El +.Pp +The +.Fl Fl pass=password +option is for PKCS#12 and PKCS#11 stores, and if needed and not +given, will be prompted for. +Note that it's not secure to pass passwords as command-line +arguments on multi-tenant systems. +.Pp +The +.Fl Fl raw-json +option prints the certificate(s) in the given +.Ar STORE +as a JSON dump of their DER using an experimental (i.e., +unstable) schema. +.Sh KEYS +The +.Nm generate-key +sub-command will generate a key. +.Sh CERTIFICATE SIGNING REQUESTS +The +.Nm request-create +sub-command will create a CSR. +The +.Nm request-print +sub-command will display a CSR. +.Sh CERTIFICATE ISSUANCE / CERTIFICATION AUTHORITY +The +.Nm certificate-sign +sub-command will issue a certificate. +See its usage message. +.Sh ONLINE CERTIFICATE STATUS PROTOCOL +The +.Nm ocsp-fetch +sub-command will fetch OCSP Responses for the given +certificates. +.Pp +The +.Nm ocsp-verify +sub-command will verify OCSP Responses. +.Pp +The +.Nm ocsp-print +sub-command will display OCSP Responses. +.Sh CERTIFICATE REVOCATION LIST +The +.Nm crl-sign +sub-command will add certificates to a certificate revocation +list. +.Sh SEE ALSO +.Xr openssl 1