HXTOOL(1)

NAME
hxtool - PKIX command-line utility

SYNOPSIS
hxtool [- -version] [- -help] [sub-command]

DESCRIPTION
hxtool 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.

All sub-commands have their own help message, shown when invoked with the - -help or -h option.

Supported commands:

help

list-oids

verify
    Verify a certificate and its certification path up to a trust anchor, possibly checking CRLs.

print
    Prints a human-readable rendering of certificates in a store. See CERTIFICATE STORES.

validate
    Validate a certificate (but not a full chain).

certificate-copy, cc
    Copy ceritificates and possibly private keys from one store to another. See CERTIFICATE STORES.

ocsp-fetch
    Fetch an OCSP response.

ocsp-verify
    Fetch an OCSP response chain.

ocsp-print
    Prints a human-readable rendering of an OCSP response chain.

revoke-print
    Prints a human-readable rendering of a CRL or OCSP response chain.

generate-key
    Generates a private key.

request-create
    Generates a Certificate Signing Request (CSR).

request-print
    Prints a human-readable rendering of a CSR.

query
    Queries a certificate store.

info
    Prints information about supported algorithms.

random-data
    Outputs entropy using a random number generator.

crypto-available
    Tests if a cryptographic algorithm is available.

crypto-select
    Selects a supported cryptographic algorithm given a peer's capabilities.

hex Hex-encode/decode utility.

certificate-sign, cert-sign, issue-certificate, ca
    Issue a certificate.

crl-sign
    Sign a CRL.

cms-create-sd, cms-sign
    Created a CMS SignedData.

cms-verify-sd
    Verifies a CMS SignedData.

cms-unenvelope
    Extracts enveloped data from a CMS SignedData.

cms-envelope
    Creates an enveloped CMS SignedData.
Other sub-commands reported by the help sub-command are not stable or fully supported at this time.

CERTIFICATE STORES
Stores of certificates and/or keys have string names that can be used with 's commands as well as in various configuration parameters and command-line arguments of Heimdal's Kerberos implementation (for PKINIT).

For example, ‘FILE:/path/to/file’, ‘PEM-FILE:/path/to/file’, ‘DER-FILE:/path/to/file’, etc. See below for a full list of store types.

A certificate store name starts with a store TYPE followed by a colon followed by a name of form specific to that store type.

Private keys can be stored in the same stores as the certificates that certify their public keys.

Private keys can also be stored in separate files, but still be referenced in one certificate store name by joining two with a comma: ‘FILE:/path/to/certificate,/path/to/private/key’

Heimdal supports a variety of certificate and private key store types:

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).

DER-FILE:/path
    If writing, DER will be written. If reading, DER will be expected. Private keys will be in algorithm-specific formats.

FILE:/path
    If writing, PEM will be written as if ‘PEM-FILE’ had been used. If reading, PEM or DER will be detected and read as if ‘PEM-FILE’ or ‘DER-FILE’ had been used.

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.

DIR:/path
    OpenSSL-style hashed directory of trust anchors.

KEYCHAIN:system-anchors
    On OS X this refers to the system's trust anchors.

KEYCHAIN:FILE:/path
    On OS X this refers to an OS X keychain at the given path.

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.

NULL:
    An empty store.

MEMORY:name
    An in-memory only, ephemeral store, usually never used in commands. The MEMORY store name exists primarily for internal ‘hx509’ APIs.

Use the 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.

CERTIFICATES
You can validate a certificate with the validate sub-command, or verify a certificate and its certification path with the verify sub-command.

You can display a certificate using the print sub-command:

print [options] STORE

Options:

- -content

- -info

- -never-fail

- -pass=password

- -raw-json

The - -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.

The - -raw-json option prints the certificate(s) in the given STORE as a JSON dump of their DER using an experimental (i.e., unstable) schema.

KEYS
The generate-key sub-command will generate a key.

CERTIFICATE SIGNING REQUESTS
The request-create sub-command will create a CSR, and has support for requesting subject alternative names and extended key usage extensions. See its - -help option, and see EXAMPLES below.

The request-print sub-command will display a CSR.

CERTIFICATE ISSUANCE / CERTIFICATION AUTHORITY
The certificate-sign sub-command will issue a certificate. See its usage message.

ONLINE CERTIFICATE STATUS PROTOCOL
The ocsp-fetch sub-command will fetch OCSP Responses for the given certificates.

The ocsp-verify sub-command will verify OCSP Responses.

The ocsp-print sub-command will display OCSP Responses.

CERTIFICATE REVOCATION LIST
The crl-sign sub-command will add certificates to a certificate revocation list.

EXAMPLES
Generate an RSA key:

    hxtool generate-key --type=rsa --key-bits=4096 PEM-FILE:key.pem

Create a CSR (with an empty name) for some key:

    hxtool request-create --subject= --key=FILE:key.pem csr.der

Generate a key and create a CSR (with an empty name) for it:

    hxtool request-create       \
    	--subject=          \
    	--generate-key=rsa  \
    	--key-bits=4096     \
    	--key=FILE:key.pem  \
    	csr.der

Generate a key and create a CSR with an empty name but also requesting a specific dNSName subject alternative name (SAN) for it:

    hxtool request-create               \
    	--subject=                  \
    	--generate-key=rsa          \
    	--dnsname=foo.test.h5l.se   \
    	--key=FILE:key.pem          \
    	csr.der

Print a CSR:

    hxtool request-print csr.der

which outputs:

    request print
    PKCS#10 CertificationRequest:
      name:
        san: dNSName: foo.test.h5l.se

Issue a end-entity certificate for an HTTPS server given a CSR:

    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

Add a chain to a PEM file:

    hxtool copy-certificiate    \
    	--no-private-keys   \
    	--no-root-certs     \
    	FILE:ca.pem FILE:ee.pem

Create a self-signed end-entity certificate for an HTTPS server:

    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

Create a root certification authority certificate:

    hxtool issue-certificate                            \
    	--issue-ca                                  \
    	--self-signed                               \
    	--subject=CN=SomeRootCA                     \
    	--ca-private-key=FILE:rootkey.pem           \
    	--certificate=PEM-FILE:rootcert.pem

Create an intermediate certification authority certificate from a CSR:

    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

SEE ALSO
openssl(1)