diff options
Diffstat (limited to 'third_party/heimdal/lib/hx509/hxtool.1')
| -rw-r--r-- | third_party/heimdal/lib/hx509/hxtool.1 | 380 |
1 files changed, 380 insertions, 0 deletions
diff --git a/third_party/heimdal/lib/hx509/hxtool.1 b/third_party/heimdal/lib/hx509/hxtool.1 new file mode 100644 index 0000000..040573f --- /dev/null +++ b/third_party/heimdal/lib/hx509/hxtool.1 @@ -0,0 +1,380 @@ +.\" 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 +Verify a certificate and its certification path up to a trust +anchor, possibly checking CRLs. +.It print +Prints a human-readable rendering of certificates in a store. +See +.Sx CERTIFICATE STORES. +.It validate +Validate a certificate (but not a full chain). +.It certificate-copy, cc +Copy ceritificates and possibly private keys from one store to +another. +See +.Sx CERTIFICATE STORES. +.It ocsp-fetch +Fetch an OCSP response. +.It ocsp-verify +Fetch an OCSP response chain. +.It ocsp-print +Prints a human-readable rendering of an OCSP response chain. +.It revoke-print +Prints a human-readable rendering of a CRL or OCSP response +chain. +.It generate-key +Generates a private key. +.It request-create +Generates a Certificate Signing Request (CSR). +.It request-print +Prints a human-readable rendering of a CSR. +.It query +Queries a certificate store. +.It info +Prints information about supported algorithms. +.It random-data +Outputs entropy using a random number generator. +.It crypto-available +Tests if a cryptographic algorithm is available. +.It crypto-select +Selects a supported cryptographic algorithm given a peer's +capabilities. +.It hex +Hex-encode/decode utility. +.It certificate-sign, cert-sign, issue-certificate, ca +Issue a certificate. +.It crl-sign +Sign a CRL. +.It cms-create-sd, cms-sign +Created a CMS SignedData. +.It cms-verify-sd +Verifies a CMS SignedData. +.It cms-unenvelope +Extracts enveloped data from a CMS SignedData. +.It cms-envelope +Creates an enveloped CMS SignedData. +.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 as well as in various configuration parameters and +command-line arguments of Heimdal's Kerberos implementation (for +PKINIT). +.Pp +For example, +.Ql FILE:/path/to/file , +.Ql PEM-FILE:/path/to/file , +.Ql DER-FILE:/path/to/file , +etc. +See below for a full list of store types. +.Pp +A certificate store name starts with a store TYPE followed by a +colon followed by a name of form specific to that store type. +.Pp +Private keys can be stored in the same stores as the certificates +that certify their public keys. +.Pp +Private keys can also be stored in separate files, but still be +referenced in one certificate store name by joining two with a +comma: +.Ql FILE:/path/to/certificate,/path/to/private/key +. +.Pp +Heimdal supports a variety of certificate and private key store +types: +.Bl -tag -width Ds -offset indent +.It PEM-FILE:/path +If writing, PEM will be written (private keys may be written in +algorithm-specific formats or in PKCS#8). +If reading, PEM will be expected (private keys may be in +algorithm-specific formats or in PKCS#8). +.It DER-FILE:/path +If writing, DER will be written. +If reading, DER will be expected. +Private keys will be in algorithm-specific formats. +.It FILE:/path +If writing, PEM will be written as if +.Ql PEM-FILE +had been used. +If reading, PEM or DER will be detected and read as if +.Ql PEM-FILE +or +.Ql DER-FILE +had been used. +.It PKCS12:/path +If writing, PKCS#12 will be written. +If reading, PKCS#12 will be expected. +Note that PKCS#12 support is currently very limited. +.It DIR:/path +OpenSSL-style hashed directory of trust anchors. +.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 PKCS11:/path/to/shared/object[,slot=NUMBER] +Loads the given PKCS#11 provider object and uses the token at the +given slot number, or else the first token found. +.It NULL: +An empty store. +.It MEMORY:name +An in-memory only, ephemeral store, usually never used in +.NM 's +commands. +The MEMORY store name exists primarily for internal +.Sq hx509 +APIs. +.El +.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, removing private keys, adding certificate chains, +and removing root certificates from chains. +.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 +.It Fl Fl content +.It Fl Fl info +.It Fl Fl never-fail +.It Fl Fl pass=password +.It Fl Fl raw-json +.El +.Pp +The +.Fl Fl pass=password +option is for PKCS#8 (PEM), 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, and has support for requesting +subject alternative names and extended key usage extensions. +See its +.Fl Fl help +option, and see +.Sx EXAMPLES +below. +.Pp +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 EXAMPLES +Generate an RSA key: +.Bd -literal -offset indent +hxtool generate-key --type=rsa --key-bits=4096 PEM-FILE:key.pem +.Ed +.Pp +Create a CSR (with an empty name) for some key: +.Bd -literal -offset indent +hxtool request-create --subject= --key=FILE:key.pem csr.der +.Ed +.Pp +Generate a key and create a CSR (with an empty name) for it: +.Bd -literal -offset indent +hxtool request-create \\ + --subject= \\ + --generate-key=rsa \\ + --key-bits=4096 \\ + --key=FILE:key.pem \\ + csr.der +.Ed +.Pp +Generate a key and create a CSR with an empty name but also +requesting a specific dNSName subject alternative name (SAN) for +it: +.Bd -literal -offset indent +hxtool request-create \\ + --subject= \\ + --generate-key=rsa \\ + --dnsname=foo.test.h5l.se \\ + --key=FILE:key.pem \\ + csr.der +.Ed +.Pp +Print a CSR: +.Bd -literal -offset indent +hxtool request-print csr.der +.Ed +which outputs: +.Bd -literal -offset indent +request print +PKCS#10 CertificationRequest: + name: + san: dNSName: foo.test.h5l.se +.Ed +.Pp +Issue a end-entity certificate for an HTTPS server given a CSR: +.Bd -literal -offset indent +hxtool issue-certificate \\ + --type=https-server \\ + --subject= \\ + --hostname=foo.test.h5l.se \\ + --ca-certificate=FILE:cacert.pem \\ + --ca-private-key=FILE:cakey.pem \\ + --req=PKCS10:csr.der \\ + --certificate=PEM-FILE:ee.pem +.Ed +.Pp +Add a chain to a PEM file: +.Bd -literal -offset indent +hxtool copy-certificiate \\ + --no-private-keys \\ + --no-root-certs \\ + FILE:ca.pem FILE:ee.pem +.Ed +.Pp +Create a self-signed end-entity certificate for an HTTPS server: +.Bd -literal -offset indent +hxtool issue-certificate \\ + --self-signed \\ + --type=https-server \\ + --subject= \\ + --hostname=foo.test.h5l.se \\ + --ca-private-key=FILE:key.pem \\ + --certificate-private-key=FILE:key.pem \\ + --certificate=PEM-FILE:cert.pem +.Ed +.Pp +Create a root certification authority certificate: +.Bd -literal -offset indent +hxtool issue-certificate \\ + --issue-ca \\ + --self-signed \\ + --subject=CN=SomeRootCA \\ + --ca-private-key=FILE:rootkey.pem \\ + --certificate=PEM-FILE:rootcert.pem +.Ed +.Pp +Create an intermediate certification authority certificate from a +CSR: +.Bd -literal -offset indent +hxtool issue-certificate \\ + --type=https-server \\ + --subject=CN=SomeIntermediateCA \\ + --ca-certificate=FILE:parent-cert.pem \\ + --ca-private-key=FILE:parent-key.pem \\ + --req=PKCS10:csr.der \\ + --certificate=PEM-FILE:intermediate.pem +.Ed +.Pp +.Sh SEE ALSO +.Xr openssl 1 |