ca-certs

Note: This page is based on the current ca-certs README and CLI implementation. It documents the tool as it exists now, including the certdata conversion pipeline and the default symlink layout it manages.

Usage

The command is split into three main areas: adding anchors, extracting trust bundles, and working with Mozilla certdata.txt.

ca-certs add company-root.pem
ca-certs extract
ca-certs certdata fetch
ca-certs certdata convert certdata.txt
ca-certs certdata sync

Command	Purpose
ca-certs add	Adds a PEM CA certificate to the anchors directory and refreshes outputs by default.
ca-certs extract	Regenerates derived trust bundles from the shared trust database.
ca-certs certdata fetch	Downloads Mozilla NSS certdata.txt.
ca-certs certdata parse	Parses a local certdata.txt file and prints a summary.
ca-certs certdata convert	Converts certdata.txt into a Mozilla p11-kit trust source and optionally extracts outputs.
ca-certs certdata sync	Runs the full fetch, convert, and extract pipeline.

Anchors and extraction

ca-certs add validates that the input looks like a PEM certificate, sanitizes the output name, installs the anchor into the trust-source anchors directory, and then runs extraction unless --no-extract is used.

ca-certs add company-root.pem
ca-certs add company-root.pem --name company-root
ca-certs add company-root.pem --force
ca-certs add company-root.pem --no-extract
ca-certs add company-root.pem --dry-run

ca-certs extract rebuilds all derived outputs from the current trust database, similar to update-ca-trust extract.

ca-certs extract
ca-certs extract --output /tmp/ca-extracted
ca-certs extract --dry-run

Tip: Use --dry-run first when changing trust stores in images or chroots. The tool prints the target paths and the trust extract jobs it would run.

Rootfs mode

Most subcommands accept --root so they can operate on another root filesystem. This is intended for image builds, chroots, or staged installations.

ca-certs extract --root /mnt/image
ca-certs add company-root.pem --root /mnt/image
ca-certs certdata convert certdata.txt --root /mnt/image

When a non-default root is used, the tool maps target paths into that root and runs external commands against the target environment. The implementation is designed around Linux trust-store layouts and expects utilities such as trust, openssl, and chroot to be available when needed.

Extracted outputs

The extraction set mirrors a typical update-ca-trust style layout. A standard extraction run generates several bundle formats plus a hashed certificate directory.

Output	Purpose
tls-ca-bundle.pem	PEM CA bundle for server authentication.
email-ca-bundle.pem	PEM CA bundle for email trust purposes.
objsign-ca-bundle.pem	PEM CA bundle for code-signing trust purposes.
ca-bundle.trust.crt	OpenSSL-style trust bundle with trust metadata.
edk2-cacerts.bin	EDK2 certificate bundle output.
java-cacerts.jks	Java truststore output.
cadir/	Hashed OpenSSL-style certificate directory.

Note: These outputs are generated through separate trust extract jobs with different --format, --filter, and --purpose settings.

SSL symlink sync

When extraction uses the standard extracted output directory, ca-certsalso synchronizes a common SSL symlink layout. This includes relinking hashed files into /etc/ssl/certs, pruning broken symlinks, and maintaining bundle links such as /etc/ssl/cert.pem and /etc/ssl/certs/ca-certificates.crt.

It also maintains compatibility links for PKI-style paths such as /etc/pki/tls/certs/ca-bundle.crt, /etc/pki/tls/certs/ca-bundle.trust.crt, and Java cacerts links.

Warning

Symlink synchronization only happens for the standard extraction destination. If you use a custom --output directory, the tool skips the /etc/ssl/certs relink step.

Mozilla certdata workflow

The certdata subcommands handle Mozilla NSS trust data. This allows ca-certs to fetch, parse, convert, and install a Mozilla trust source in p11-kit format.

Fetch

ca-certs certdata fetch
ca-certs certdata fetch --output certdata.txt
ca-certs certdata fetch --force
ca-certs certdata fetch --no-revision-check

The fetch step can check the remote Mercurial log to avoid re-downloading unchanged revisions. When a matching revision is already present locally, it skips the update unless --force is used.

Parse

ca-certs certdata parse certdata.txt
ca-certs certdata parse certdata.txt --limit 10

Convert

ca-certs certdata convert certdata.txt
ca-certs certdata convert certdata.txt --no-extract
ca-certs certdata convert certdata.txt --output /usr/share/ca-certificates/trust-source/mozilla.trust.p11-kit

Conversion writes a Mozilla .trust.p11-kit source file and can then run extraction. If extraction comes back empty, the implementation can retry after installing compatibility trust-source mirrors for layouts that expect trust data in alternate PKI directories.

Sync

ca-certs certdata sync
ca-certs certdata sync --force
ca-certs certdata sync --no-extract

The sync command chains fetch, convert, and extract together. When no explicit output file is given for the downloaded certdata.txt, it uses a temporary workspace and cleans it up afterward.

Notes

• The tool targets Linux trust-store layouts and exits on non-Linux targets.
• add expects PEM input and rejects non-certificate content.
• Name sanitization is applied when generating anchor filenames.
• For some network operations, the implementation can fall back to openssl when needed.
• Artifact generation for packaging exists internally via ca-certs gen-artifacts, which produces a man page and shell completions.

See also

• Docs index
• ca-certs in Features
• Depot