redwax-tool(1)

📦 version 1.0.0, in epel 10, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

redwax-tool 💅

okay bestie, welcome to redwax-tool(1) — the manual page for redwax-tool, and honestly? it's giving main character energy. sit down, grab a strawberry 🍓, and let's get into it.

✨ NAME ✨

redwax-tool — the Redwax tool. that's it, that's the name, periodt. 💖

🦋 SYNOPSIS 🦋

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

🌸 DESCRIPTION 🌸

so the tea is: redwax-tool lets you read certificates and keys in a whole range of formats and convert them into other formats, whatever the common services need. it's the versatile icon of the group chat. 🔥

here's the thing you actually gotta internalize: options are read in order, in three phases. first all the input options get read, then all the filter options, then all the output options. in order. no skipping, no reordering, no chaos. it's structured, and we respect that. 👑

🎀 OPTIONS 🎀

general vibes ✨

  • -h, --help — display this help message. the "help me bestie" button. 🫶
  • -v, --version — display the version number. show me the numbers. ⭐
  • -q, --quiet — be quiet. errors are suppressed. shy girlie mode. 🙈
  • -d, --debug — be loud. prints extra details of our progress. main character announcement mode. 📣

DNS stuff 🧚

  • --dns-server=ip — if you specify it, it supplies the IP address of the upstream DNS server. you can specify it more than once, she's flexible. if you don't specify it, it reads from /etc/resolv.conf instead.
  • --dns-trust-anchor=file — specify the file containing the DNSSEC trust anchor. if you don't specify it, the key may be read from an OS-specific default location. it'll find its own way home. 🏠

secrets 🤫

  • --secret-suffix-in=suffix — if specified, secrets get read from a file with the same name as the source file plus the suffix you gave. so with the value secret, a file key.pem has its secret loaded from key.secret in the same directory. cute matching set, honestly. 🎀
  • --secret-suffix-out=suffix — same deal but for the target file: if specified, secrets get read from a file with the same name as the target file plus the suffix. with the value secret, a file key.pem has 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 get 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) get 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.

labels 🏷️

  • --label-out=label — sets the name of the label applied to the leaf certificates. if you don't specify it, the label is set to the subject of the certificate. it picks for you, slay.

input options 📥

  • --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 it's relative, use the default PKCS11 module path; otherwise specify the absolute path. include the extension of the module. don't forget the extension, bestie, it matters. ⚠️
  • --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 options 🔍

  • --filter=type — apply the given filter to pass inputs through to the outputs. "search" passes through all certificates matching the given hostname, email or ip address. "verify" passes all leaf certificates that can be successfully verified through the certificate chain to a trusted root certificate. and with the default, "passthrough", all certificates, csrs, and keys are passed through. no gatekeeping. ✨
  • --filter-email=address — search/verify by the given email address. leaf certificates matching the email address get included. can be specified more than once.
  • --filter-hostname=domain — search/verify by the given hostname. leaf certificates matching the hostname get kept, taking into account wildcards where present. wildcards are valid, ok?! 🦄
  • --filter-ip=address — search/verify by the given IP address. leaf certificates matching the IP address get 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. only the winner survives, it's giving competitive. 👑
  • --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, an optional scheme defaulting to tcp, and an 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 defaults to the current time. date format is generalized time syntax as defined in RFC 4517 section 3.3.13. very specific, very demure. 📅
  • --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 defaults to any purpose. she's open-minded like that. 🌈

output toggles 🎚️

  • --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 can't be created through intermediate certificates to a trusted root certificate, the leaf certificate is ignored. no chain, no service. 💀
  • --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 can't 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). she's efficient, she's not doing duplicates. 💅
  • --no-auto-out — output everything as specified.

output destinations 📤

  • --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. order matters, bestie, don't test her. ⚠️
  • --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, and 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 it's relative, use the default PKCS11 module path; otherwise specify the absolute path. include the extension of the module. again: extension. include it. 🫶
  • --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. pick your aesthetic. ✨
  • --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. 🗓️

okay that's part 1 bestie, there's more coming — don't go anywhere 🦋

  • --reminder-out=file — drops a whole calendar of reminders into the given file or directory, one reminder per certificate, all keyed to that cert's expiry date. Point it at a directory instead and it'll scatter the entries into separate little .ICS files, one vibe per file. 🗓️
  • --calendar-alarm=duration — say the word and every calendar entry gets an alarm slapped on it (only if it doesn't already have one, no double-dipping). The alarm wants an RFC5545 DURATION, exactly as described in section 3.3.6. Example: -P1W = one whole week before expiry. ⏰
  • --user-in=user — read certificates and keys while wearing this user's privileges. ✨
  • --user-out=user — write certificates and keys while wearing this user's privileges. 💅
  • --group-in=group — read certificates and keys with this group's privileges. Heads up bestie: if you already set a user before setting a group, you might not have permission to set the group anymore. So if you're doing both, set the group first. Order matters, fr fr. ⚠️
  • --group-out=group — write certificates and keys with this group's privileges. Same deal: set a user before a group and you may lose the permission to set that group. Recommended: if user and group are both in play, group goes first. 🙈
  • --order-out=[all|key-first|key-last] — controls the order that keys and certs show up in the output. The tea:
    • all — every leaf certificate, then all intermediates, then all roots, then all the keys. Grouped by type, very tidy, very organised.
    • key-first — outputs all certificates that have a matching private key, with the private key first, then the certificate, then intermediates and roots, then the private key of the next certificate, and so on down the line.
    • key-last — same matching-private-key certificates, but the certificate comes first, then intermediates and roots, then that certificate's key, and finally the next certificate-with-a-private-key, and so on. Basically the mirror of key-first. 🪞
  • --ssh-public-out=file — writes an SSH public key out to the given file. 🔑

🌈 RETURN VALUE 🌈

okay so when the redwax tool finishes, it tells you exactly how it went with one of these numbers:

  • 0 — we completed our task successfully. ate and left no crumbs. 👑
  • 1 — we failed to initialise. rough start. 😭
  • 2 — the command line options were not valid. bestie the flags... 😬
  • 3 — no certificates were passed through the filter. empty handed. 💀
  • 4 — could not become user or group. the privilege glow-up did not happen. 🙈
  • 5 — capability not implemented on this platform. not a thing here, sorry. 🫶
  • 6 — processing of certificates failed. it's giving error energy. 🔥

✨ EXAMPLES ✨

okay so in this one: we read every PEM file matching the wildcard, we pass all the certificates through the filter, and then we write chain certificates only to the file intermediates.pem in PEM format. slay.

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

💖 AUTHOR 💖

Graham Leggett <minfrin@sharp.fm> — the icon, the legend, the main character who wrote this whole thing. 🫶

and that's the page bestie!! this was redwax-tool-1.0.0, dated 23 June 2025, and the manual page is redwax-tool(1) 💅✨ go forth and wrangle those certificates, no cap 🎀🦋

📦 where this page comes from