Certificate Toolkit

How the Toolkit Works

conflux cert creates and checks X.509 private keys, certificate signing requests, certificates and revocation lists. It can also run a certificate authority from a directory, create and read PKCS#12 bundles, and probe and serve TLS. It covers the parts of OpenSSL's genpkey, req, x509, ca, verify, crl, pkcs12, s_client and s_server that a CA and its users need.

• Every key, signature, digest, key derivation and cipher comes from the Go Cryptographic Module, in FIPS 140-3 mode. See FIPS 140-3 Mode.
• Keys are ML-DSA-87 unless you choose another algorithm, so a whole chain can use ML-DSA, from the root to the leaf.
• It only touches the files you name, and it only uses the network for probe and serve.
• OpenSSL 3.5 can read the files it writes, and it can read the files OpenSSL 3.5 writes.

Use it for TLS and for anything else that needs an X.509 certificate. To create an anchor's identity or credentials, use anchorctl's keygen and issue commands instead. To list a command's flags, run conflux cert COMMAND -h.

A Worked Example

This example creates an ML-DSA root, issues a server certificate from it, and checks that a TLS handshake with the server is post-quantum from end to end.

• The probe's last row reads key exchange yes; authentication yes, and the command exits with code 0.

To revoke the certificate later, pass its serial number, as show prints it, to crl. After that, verify exits with code 3:

$ conflux cert crl --ca root.pem --ca-key root.key --revoke 41:24:71:…:AB:keyCompromise --out root.crl
$ conflux cert verify server.pem --ca root.pem --crl root.crl

Algorithms

Choose a key's algorithm with --alg. A certificate is signed with its issuer's algorithm, so an ML-DSA root signs even an ECDSA leaf with ML-DSA.

Keys are stored as PKCS#8. An ML-DSA key is written as its 32-byte seed, which is the seed form defined in RFC 9881. Conflux also reads the form that OpenSSL 3.5 writes by default, which stores the seed next to the expanded key, and checks that the two match.

Common Flags

You can give flags and arguments in any order. Status messages go to standard error, so standard output carries only the output you asked for. Every command that writes a file takes these flags:

A command that opens or encrypts a private key reads its passphrase from one of these:

• An unencrypted private key is written atomically, with mode 0600 (owner-only on Windows). Conflux never prints a key to a terminal.
• --encrypt writes PKCS#8 under PBES2: PBKDF2 with HMAC-SHA-256, 600,000 iterations, a 16-byte salt and AES-256-CBC. A new passphrase must be at least 8 characters long, and conflux asks for it twice.
• To import a key that another tool encrypted, re-encrypt it through a pipe so that it is never written unencrypted: openssl pkey -in KEY | conflux cert convert - --encrypt --out KEY.new.

Names and Profiles

--subject takes a distinguished name in either OpenSSL's order, /C=AU/O=Example/CN=host.example, or RFC 4514's order, CN=host.example,O=Example,C=AU. The attributes are CN, O, OU, C, ST, L, STREET, POSTALCODE, SERIALNUMBER, DC, UID and emailAddress. Inside a value, put a backslash before any comma, slash, plus sign, equals sign or backslash.

--san adds a subject alternative name, and you can repeat it. Prefix each name with DNS:, IP:, EMAIL: or URI:, or leave the prefix off and conflux works out the type from the value. Without --san, a server certificate or request uses its CN as its only name, if the CN is a host name or an address.

--profile sets what a certificate can be used for. A request carries only the subject and names, and the profile is applied when the certificate is signed:

Every certificate carries a random 128-bit serial number, a subject key identifier and its issuer's key identifier. Its validity starts five minutes in the past, to allow for clocks that are slightly behind. A certificate can't outlive its issuer.

Commands

conflux cert has these commands: genkey, req, selfsign, sign, verify, show, convert, match, fingerprint, crl, ca, p12, probe and serve.

cert genkey

Creates a private key and, if you ask, its public key.

conflux cert genkey --out FILE [--alg ALG] [--encrypt] [--pubout FILE]

cert req

Creates a certificate signing request, signed by the key it is for.

conflux cert req --key KEY --subject DN [--san NAME]... [--out FILE]

cert selfsign

Creates a certificate signed by its own key, such as a root CA or a standalone server certificate.

conflux cert selfsign --key KEY --subject DN [--profile ca] [--days N] [--out FILE]

cert sign

Issues a certificate for a signing request, after checking the request's signature.

conflux cert sign --csr REQ --ca CERT --ca-key KEY [--profile server] [--days N] [--bundle] [--out FILE]

cert verify

Builds a chain from a certificate to a trusted root, and checks it.

conflux cert verify CERT [--ca ROOT]... [--untrusted CERT]... [--crl CRL]... [--name HOST]

If the chain is valid, it prints Valid and the chain, and exits with code 0. If not, it prints Not valid: and the reason, and exits with code 3. Any intermediates after the first certificate in CERT's file are treated as --untrusted.

The authentication is pqc when the leaf's key and every signature below the root are ML-DSA, and classical otherwise.

cert show

Describes each certificate, request, revocation list or key, as openssl x509 -text does.

conflux cert show FILE... [--json]

For a private key, it shows the public key. For an encrypted key, it shows how the key is encrypted. With --json, it prints an array with one element for each object.

cert convert

Re-encodes a file, encrypts or decrypts a private key, or extracts a public key.

conflux cert convert IN --out FILE [--to pem|der] [--encrypt | --decrypt] [--pubout FILE]

IN can be - for standard input. Keys are written as PKCS#8, in the same form that conflux writes elsewhere.

cert match

Checks that two files hold the same key, such as a key and its certificate.

conflux cert match A B

Each file can be a private key, a certificate, a request or a public key. If the keys differ, it prints No match: and exits with code 3.

cert fingerprint

Prints a digest of a certificate, request, revocation list or key.

conflux cert fingerprint FILE... [--alg sha256] [--spki] [--json]

A key's fingerprint is always the fingerprint of its public key.

cert crl

Creates the revocation list that an issuer publishes.

conflux cert crl --ca CERT --ca-key KEY [--revoke SERIAL[:REASON]]... [--from CRL] [--out FILE]

The reasons are unspecified, keyCompromise, cACompromise, affiliationChanged, superseded, cessationOfOperation, privilegeWithdrawn and aACompromise. A revocation is permanent.

cert ca

Runs a certificate authority from a directory, which holds a root, an optional issuing CA, every certificate they issued, what they revoked and their revocation lists.

conflux cert ca init|issue|revoke|list|crl DIR ...

$ conflux cert ca init ./ca --name Example --intermediate --crl-url http://ca.example/crl.pem
$ conflux cert ca issue ./ca --csr server.csr --bundle --out server.pem
$ conflux cert ca list ./ca
$ conflux cert ca revoke ./ca 41:24:71:…:AB --reason keyCompromise
$ conflux cert ca crl ./ca

The table above lists the flags of init. The directory is created with mode 0700. It holds ca.json, the root and issuing CA with their keys, chain.pem, one file for each issued certificate under issued/, index.json and the revocation lists. A lock makes sure only one command works on the CA at a time.

cert p12

Writes and reads PKCS#12 bundles, using the one profile that FIPS 140-3 approves throughout.

conflux cert p12 export (--key KEY --cert CERT [--chain CHAIN] | --in PEM) --out FILE [--name NAME]
conflux cert p12 import BUNDLE --key-out KEY --cert-out CERT [--chain-out CHAIN] [--encrypt]

$ conflux cert p12 export --key server.key --cert server.pem --chain chain.pem --out server.p12
$ conflux cert p12 import server.p12 --key-out server.key --cert-out server.pem --chain-out chain.pem

The key is stored in a shrouded key bag under PBES2: PBKDF2-HMAC-SHA-256, 600,000 iterations, a 16-byte salt and AES-256-CBC. The certificates are encrypted the same way. A PBMAC1 MAC (RFC 9579) with HMAC-SHA-256 protects the bundle, and conflux checks it before opening any bag.

To import a bundle from another tool, rewrite it through a pipe so that the key is never written unencrypted:

$ openssl pkcs12 -in OLD.p12 -nodes | conflux cert p12 export --in - --out NEW.p12

cert probe

Connects as a TLS client in FIPS 140-3 mode, completes the handshake without sending anything else, and reports what was negotiated.

conflux cert probe HOST[:PORT] [--ca ROOT]... [--groups pq] [--require-pq] [--json]

$ conflux cert probe server.example:8443 --ca root.pem --require-pq
Connected to server.example:8443 (192.0.2.10:8443), as server.example
  tls             TLS 1.3, TLS_AES_128_GCM_SHA256
  key exchange    SecP384r1MLKEM1024 (hybrid)
  signature       ML-DSA-65 (pqc)
  certificate     CN=server.example, issued by CN=Example Root,O=Example
                  valid 2026-10-01 to 2027-01-01
  chain           verified for server.example, authentication pqc
    leaf          CN=server.example: ML-DSA-65 key, signed ML-DSA-87
    root          CN=Example Root,O=Example: ML-DSA-87 key, signed ML-DSA-87
  post-quantum    key exchange yes; authentication yes

The key exchange is shown as hybrid for ML-KEM combined with a classical group, such as X25519MLKEM768, as pqc for ML-KEM-1024 on its own, and as classical for P-256, P-384 and P-521. The certificate row shows the name and dates of the leaf the server sent, whether or not its chain verifies.

It exits with code 0 on success, 3 if the chain does not verify or a requirement is not met, and 1 if no handshake took place.

cert serve

Runs a TLS server in FIPS 140-3 mode, and reports what each client offered and what was negotiated.

conflux cert serve --cert CHAIN --key KEY [--listen ADDR] [--client-ca ROOT]... [--once]

A client that sends an HTTP request receives the same report as text/plain, so curl or a browser can show it. To stop the server, press Ctrl-C.

Exit Codes

For the exact messages, see Error Messages.

Next Steps