redwax-tool - Man Page

redwax-tool [-v] [-h] [in options ...] [filter options ...] [out options ...]

The redwax tool allows certificates and keys in a range of formats to be read and converted into other formats as needed by common services.

Options are read in order in three phases. All input options are read, then all filter options, and then all output options.

-h,  --help

Display this help message.

-v,  --version

Display the version number.

-q,  --quiet

Be quiet. Errors are suppressed.

-d,  --debug

Be loud. Print additional details of our progress.

--dns-server=ip

If specified, supplies the IP address of the upstream DNS server. May be specified more than once. If unspecified, will read from /etc/resolv.conf.

--dns-trust-anchor=file

Specify the file containing the DNSSEC trust anchor. If unspecified, the key may be read from an OS specific default location.

--secret-suffix-in=suffix

If specified, secrets will be read from a file with the same name as the source file, and the suffix specified. With value 'secret', a file 'key.pem' will have the secret loaded from 'key.secret' in the same directory.

--secret-suffix-out=suffix

If specified, secrets will be read from a file with the same name as the target file, and the suffix specified. With value 'secret', a file 'key.pem' will have the secret loaded from 'key.secret' in the same directory.

--secret-token-in=file

If specified, secrets needed to read certificates and keys from tokens will be read from a file one secret per line. Each secret is preceded by the name of the token and a colon, as per the NSS pwdfile.txt file.

--secret-token-out=file

If specified, secrets needed to write certificates and keys to tokens (PKCS11 and NSS) will be read from a file one secret per line. Each secret is preceded by the name of the token and a colon, as per the NSS pwdfile.txt file.

--label-out=label

Set the name of the label to be applied to the leaf certificates. If unspecified, the label is set to the subject of the certificate.

--pem-in=wildcard

Read pem files from here. Use '-' for stdin.

--trust-pem-in=wildcard

Read pem files containing trusted certificates from here. Use '-' for stdin.

--pkcs12-in=file

Read certificates, intermediate certificates, root certificates, crls, and keys from a PKCS12 file. Use '-' for stdin. Provide the secret using --secret-suffix-in.

--pkcs11-in=url

Read certificates, intermediate certificates, root certificates, crls, and keys from a PKCS11 token identified by the given url.

--pkcs11-module-in=mod

Specify the name of the PKCS11 module to be used, overriding system defaults. If relative, use the default PKCS11 module path, otherwise specify the absolute path. Include the extension of the module.

--keychain-in=keychain

Read certificates, intermediate certificates, root certificates, crls, and keys from a MacOS keychain identified by the given name.

--tls-in=url

Read certificates and intermediate certificates from a TLS or DTLS endpoint at the given url.

--filter=type

Apply the given filter to pass inputs to the outputs. "search" will pass through all certificates matching the given hostname, email or ip address. "verify" will pass all leaf certificates that can be successfully verified through the certificate chain to a trusted root certificate. With the default "passthrough", all certificates, csrs, and keys are passed through.

--filter-email=address

Search/verify by the given email address. Leaf certificates matching the email address will be included. Can be specified more than once.

--filter-hostname=domain

Search/verify by the given hostname. Leaf certificates matching the hostname will be kept, taking into account wildcards where present.

--filter-ip=address

Search/verify by the given IP address. Leaf certificates matching the IP address will be included. Can be specified more than once.

--filter-current

Match the top ranking leaf certificate, and ignore all other leaf certificates. The top certificate is valid, and has the longest time to expiry.

--filter-verify-params=name

Specify the name of the set of parameters used for verification. If unspecified, set to ’default'.

--filter-verify-tlsa=url

Perform DANE verification on the server certificate. The parameter is an URL, with a hostname, optional scheme defaulting to tcp, and optional port defaulting to 443 (example: tcp://example.com:443). If unspecified, no DANE verification is performed.

--filter-date=date

Set the date to be used for certificate verification. If unset, it will default to the current time. Date format is generalized time syntax as defined in RFC 4517 section 3.3.13.

--filter-expiry=[option]

Verify certificate expiry. 'check' does expiry verification. 'ignore' allows expired certificates. 'ignore-leaf' allows expired leaf certificates. 'ignore-chain' allows expired chain certificates. Default is 'check'.

--filter-dane=[option]

Verify certificate DANE records. 'check' does dane verification. 'ignore' allows certificates with mismatched DANE TLSA or SMIMEA records. Default is 'check'.

--filter-purpose=purpose

Set the purpose of the certificate to verify. If unset, it will default to any purpose.

--text-out

Include additional text in certificate PEM and metadata output.

--no-text-out

Exclude additional text in certificate PEM and metadata output.

--cert-out

Include leaf certificates in certificate output.

--no-cert-out

Exclude leaf certificates from certificate output.

--chain-out

Search for and include intermediate certificates belonging to leaf certificates in certificate output. When verifying, if a chain cannot be created through intermediate certificates to a trusted root certificate, the leaf certificate is ignored.

--no-chain-out

Exclude intermediate certificates belonging to leaf certificates in certificate output.

--root-out

Search for and include root certificates at the end of the certificate chain. When verifying, if a chain cannot be created through intermediate certificates to a root certificate, the leaf certificate is ignored.

--no-root-out

Exclude root certificates at the end of the certificate chain in output.

--trust-out

Identical to the 'root' option, however where supported the output certificates will be exported as a "TRUSTED CERTIFICATE" as recognised by OpenSSL.

--no-trust-out

Exclude root certificates that would otherwise be output as OpenSSL "TRUSTED CERTIFICATE".

--crl-out

Include certificate revocation lists in the output.

--no-crl-out

Exclude certificate revocation lists from the output.

--parameter-out

Include key parameters in the output.

--no-parameter-out

Exclude key parameters from the output.

--key-in

Read private keys in the input. This will trigger a login attempt if needed.

--no-key-in

Exclude keys from the input.

--key-out

Include keys in the output.

--no-key-out

Exclude keys from the output.

--auto-out

Output selectively. If a key or a certificate already exists in a PKCS11 token, skip writing the key or certificate. A key is considered to already exist if the Subject Key Info of the incoming key matches the Subject Key Info field of an existing key on the token. A certificate is considered to already exist if another certificate with the same value is present on the token. When adding a certificate, look up the ID of any corresponding key and use that ID for the certificate (unless an ID is explicitly specified in a target URL).

--no-auto-out

Output everything as specified.

--nss-out=directory

Write certificates, intermediate certificates, root certificates, crls, and keys to an NSS database.

--nss-token-out=token

Specify the token to which certificates, intermediate certificates, root certificates, crls, and keys will be written to an NSS database. Must appear after the --nss-out option.

--der-out=prefix

Write certificates, intermediate certificates, root certificates, crls, and keys. Each one is written to a file with a suffix indicating type and index. Use '-' for stdout, output will be concatenated.

--pem-out=file

Write certificates, intermediate certificates, root certificates, crls, and keys. Use '-' for stdout.

--pkcs12-out=file

Write certificates, intermediate certificates, root certificates, crls, and keys into a PKCS12 file. Use '-' for stdout.

--pkcs11-out=url

Write certificates, intermediate certificates, root certificates, crls, and keys into a PKCS11 token identified by the given url.

--pkcs11-module-out=mod

Specify the name of the PKCS11 module to be used, overriding system defaults. If relative, use the default PKCS11 module path, otherwise specify the absolute path. Include the extension of the module.

--metadata-out=file

Write metadata of each certificate and key to the given file in the format given by the format parameter.

--metadata-threshold=days

Set the threshold in days below which an expiry becomes a warning. If unset, defaults to no warning.

--format-out=xml|json|yaml

Format of output metadata.

--calendar-out=file

Write a calendar containing entries until the expiry date of each certificate to the given file or directory. If a directory is specified, entries will be created in discrete ICS files.

--reminder-out=file

Write a calendar containing reminders at the expiry date of each certificate to the given file or directory. If a directory is specified, entries will be created in discrete ICS files.

--calendar-alarm=duration

If specified, add an alarm to each calendar entry if not already present. The alarm format is a RFC5545 DURATION as described in section 3.3.6. Example: -P1W is one week prior to expiry.

--user-in=user

Use the privileges of this user when reading certificates and keys.

--user-out=user

Use the privileges of this user when writing certificates and keys.

--group-in=group

Use the privileges of this group when reading certificates and keys. If you have set a user before setting a group, you may no longer have permission to set the group. It is recommended that if user and group are set, the group is set first.

--group-out=group

Use the privileges of this group when writing certificates and keys. If you have set a user before setting a group, you may no longer have permission to set the group. It is recommended that if user and group are set, the group is set first.

--order-out=[all|key-first|key-last]

Controls the order of keys and certificates in the output. 'all' outputs all leaf certificates, followed by all intermediate certificates, followed by all root certificates, followed by all keys. 'key-first' outputs all certificates with a matching private key, with the private key first, followed by the certificate, followed by intermediates and roots, followed by the private key of the next certificate and so on. ’key-last' outputs all certificates with a matching private key, with the certificate first, followed by intermediates and roots, followed by the key of the certificate, finally followed by the next certificate with a private key and so on.

--ssh-public-out=file

Write an SSH public key to the given file.

The redwax tool returns the following values.

• 0: We completed our task successfully.
• 1: We failed to initialise.
• 2: The command line options were not valid.
• 3: No certificates were passed through the filter.
• 4: Could not become user or group.
• 5: Capability not implemented on this platform.
• 6: Processing of certificates failed.

In this example, we read all PEM files matching the wildcard, we pass all certificates through the filter, then we write chain certificates only to the file intermediates.pem in PEM format.

        ~$ redwax-tool --pem-in *.pem --filter passthrough --chain-out 
                --pem-out intermediates.pem

Graham Leggett <minfrin@sharp.fm>