CACHelp

Set up CAC on Linux

Linux CAC support is excellent once the right pieces are in place — pcscd, OpenSC, and an NSS database that actually contains all 49 DoD certificates. ~25 min · 8 steps.

Stuck on a specific error? Describe it to the AI assistant for a tailored fix — or check our error code reference.

How CAC works on Linux

The Linux stack has three layers, and knowing which one is broken saves most of the troubleshooting time. At the bottom, pcscd plus the CCID driver talk to the reader hardware. In the middle, OpenSC provides a PKCS#11 module that understands the CAC applet. At the top, your browser needs both that module registered and the DoD certificate chain in its NSS database. A failure at any layer looks like 'my CAC doesn't work', but the fix is completely different in each case.

Two details trip up almost everyone and are wrong in most published guides. First, pcscd is socket-activated and runs with --auto-exit, so it shuts down when idle; enabling pcscd.socket rather than pcscd.service is what makes it come back on demand. Ubuntu 22.04 in particular shipped with that socket disabled. Second, and more damaging: importing the DoD bundle with certutil straight from the .p7b file silently imports exactly one certificate out of forty-nine and still exits successfully. The bundle has to be split into individual PEM files first.

The certificate bundle itself is PKCS#7 only. There are no loose .cer files and no 'AllCerts.zip' anymore — the current artifact is unclass-certificates_pkcs7_DoD.zip, version 5.14, containing 49 certificates under four roots. Of those roots, DoD Root CA 4 issues nothing and Root CA 5 issues no CAC identity certificates at all, so a working 2026 trust store needs both DoD Root CA 3 (older cards still in circulation) and DoD Root CA 6 (current issuance). Dropping Root CA 3 breaks cards that are perfectly valid.

If you run Ubuntu with the snap-packaged Firefox or Chromium, the situation is better than it used to be but works differently than you would expect. The snap bundles its own copy of OpenSC, and the /usr/lib path you type into Security Devices resolves inside the snap's mount namespace to that bundled copy rather than to the host's file. The one thing you must do is connect the pcscd interface by hand, because it deliberately does not auto-connect.

What you need

  • pcscd, the CCID driver, and pcsc-tools — Debian and Ubuntu: pcscd, libccid, pcsc-tools. Fedora: pcsc-lite, pcsc-lite-ccid, pcsc-tools. Arch: pcsclite, ccid, pcsc-tools. On Ubuntu most of these live in the universe repository.
  • OpenSC — Debian and Ubuntu split this: the opensc package pulls in opensc-pkcs11, which is what actually provides the PKCS#11 module. Installing opensc is the safe choice — installing only opensc-pkcs11 pulls in neither opensc nor pcscd.
  • NSS tools — libnss3-tools on Debian and Ubuntu, nss-tools on Fedora, nss on Arch. This gives you certutil and modutil, which manage the browser certificate database.
  • openssl — Needed to convert the DoD PKCS#7 bundle into individual certificates. This is not optional — see the warning in the import step.

Steps

  1. 1

    Install the packages

    Debian / Ubuntu: sudo apt install pcscd libccid pcsc-tools opensc libnss3-tools openssl — Fedora: sudo dnf install pcsc-lite pcsc-lite-ccid pcsc-tools opensc nss-tools openssl — Arch: sudo pacman -S pcsclite ccid pcsc-tools opensc nss openssl

    • On Ubuntu these packages are in universe; enable it first if your install is unusually minimal.
    • On Debian and Ubuntu, opensc has a hard dependency on opensc-pkcs11, so installing opensc is enough.
  2. 2

    Enable the pcscd socket (not the service)

    Run sudo systemctl enable --now pcscd.socket. The daemon is designed to be socket-activated and starts with --auto-exit, so it terminates when idle and only an enabled socket brings it back. Enabling pcscd.service alone installs no boot symlink of its own, because that unit has no WantedBy of its own.

    • Ubuntu 22.04 shipped with pcscd.socket disabled, which is why so many 22.04 users see the reader work once and never again after a reboot.
    • The ArchWiki contradicts itself on this point between its Smartcards and Common Access Card pages. The socket is correct.
  3. 3

    Verify the reader and the card

    With the CAC inserted, run pcsc_scan. You should see the reader name, 'Card inserted', and an ATR. Then confirm OpenSC recognises it: opensc-tool --list-readers and opensc-tool --reader 0 --name, which should report 'Common Access Card (CAC)'.

    • If pcsc_scan reports no reader at all, the problem is hardware or pcscd — stop here, because no amount of certificate work will help.
    • If OpenSC identifies the card as 'Personal Identity Verification Card' rather than CAC and things misbehave, you can force the driver in /etc/opensc.conf with card_drivers = cac and force_card_driver = cac.
  4. 4

    Download and split the DoD certificate bundle

    Download unclass-certificates_pkcs7_DoD.zip from DISA and unzip it. Then convert the PKCS#7 archive to PEM and split it into individual certificates: openssl pkcs7 -print_certs -inform DER -in Certificates_PKCS7_v5_14_DoD.der.p7b | awk '/-----BEGIN CERTIFICATE-----/{n++} n{print > sprintf("dod-%02d.pem", n)}'

    • The -inform DER flag is mandatory. OpenSSL 3.x defaults to PEM and fails with 'unable to load PKCS7 object' if you omit it. Use -inform PEM for the .pem.p7b variant.
    • The archive unpacks to a version-named directory, so glob Certificates_PKCS7_v*_DoD/ in any script rather than hard-coding 5.14.
    • The .sha256 file in the zip is not a text checksum — it is a signed CMS object. DISA's README gives the openssl smime -verify recipe to check it against DoD_PKE_CA_chain.pem.
  5. 5

    Import the certificates into the NSS database

    First find your database: ls -d ~/.pki/nssdb ~/.local/share/pki/nssdb. Then import every split file, for example: for f in dod-*.pem; do certutil -d sql:$HOME/.pki/nssdb -A -t "CT,C,C" -n "$(basename $f .pem)" -i "$f"; done — and confirm with certutil -d sql:$HOME/.pki/nssdb -L

    • Do not point certutil -A at the .p7b directly. NSS reads only the first certificate out of a PKCS#7 package and discards the rest, so you get 1 certificate out of 49, silently, with a success exit code. This single mistake explains a large share of 'I imported the certs and it still fails' reports.
    • Chromium changed its NSS database location in M146 (stable March 2026) to ~/.local/share/pki/nssdb for fresh profiles, while continuing to use ~/.pki/nssdb when it already exists. On a new machine, a database created at the old path may never be read.
    • The trust argument "CT,C,C" sets SSL, email and object-signing trust. The three fields are positional.
  6. 6

    Register the OpenSC PKCS#11 module

    For Chromium and for Firefox on the command line: modutil -dbdir sql:$HOME/.pki/nssdb -add "OpenSC" -libfile /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so then verify with modutil -dbdir sql:$HOME/.pki/nssdb -list. In the Firefox GUI, use Settings → Privacy & Security → Security Devices → Load and give the same path.

    • Module paths differ by distro: /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so on Debian and Ubuntu amd64, /usr/lib64/opensc-pkcs11.so on Fedora, /usr/lib/opensc-pkcs11.so on Arch. On other architectures run dpkg -L opensc-pkcs11 or your distro's equivalent to locate it.
    • Close the browser before running modutil. A 'failure to load dynamic library' message is benign if -list subsequently shows the module as loaded.
  7. 7

    On Ubuntu, connect the pcscd interface for snap browsers

    If you use the snap-packaged Firefox or Chromium — the default on Ubuntu 22.04 and later — run sudo snap connect firefox:pcscd (or chromium:pcscd). This interface does not auto-connect by design, and without it the browser cannot reach the pcscd socket at all.

    • The snap bundles its own OpenSC. The host path you type into Security Devices is bind-mounted to the snap's copy, so upgrading OpenSC on the host does not change what the snap uses.
    • Because of that bundling, a vendor or proprietary PKCS#11 driver still cannot be loaded into a snap browser — that limitation is unresolved.
    • Ignore older guides that edit /etc/apparmor.d/abstractions/p11-kit.d/snap. That workaround is obsolete and is overwritten on the next snap refresh.
  8. 8

    Test against a real site

    Insert the CAC, open your browser, and go to a .mil site. The browser asks you to unlock the OpenSC token with your CAC PIN, then prompts you to pick a certificate. Choose EMAIL for webmail, IDENTITY or AUTH for general sign-on, SIGNATURE for signing.

    • Before typing a PIN anywhere, read the PIN retry warning under Common problems. Command-line PIN operations decrement the real counter on the card.

Verify it worked

  • pcsc_scan with the card inserted — Reader name, 'Card inserted', and an ATR. This confirms the hardware layer and pcscd.
  • opensc-tool --reader 0 --name — 'Common Access Card (CAC)'. This confirms OpenSC has the right driver for the card.
  • pkcs11-tool --module /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so -O — Your certificates and keys are listed. This confirms the PKCS#11 layer independently of any browser.
  • certutil -d sql:$HOME/.pki/nssdb -L | wc -l — Dozens of DoD entries, not one or two. A count in the single digits means the p7b import problem bit you.
  • pkcs15-tool --list-pins — The PIN object and a 'Tries left' count read from the card itself — the authoritative number for your card.

Common problems

I imported the certs but sites still reject me

Almost always the PKCS#7 import trap. certutil -A reads only the first certificate from a .p7b and discards the other 48, exiting successfully. Split the bundle with openssl pkcs7 -print_certs first, import the individual PEMs, then check the count with certutil -L.

Reader works, then stops after a reboot

pcscd is socket-activated and exits when idle. Run sudo systemctl enable --now pcscd.socket — enabling pcscd.service alone is not equivalent, and Ubuntu 22.04 shipped with the socket disabled.

Snap Firefox or Chromium cannot see the card

The pcscd snap interface does not auto-connect. Run sudo snap connect firefox:pcscd or sudo snap connect chromium:pcscd, then restart the browser. Note the snap uses its own bundled OpenSC regardless of what is installed on the host.

Certificates imported to the wrong NSS database

Chromium moved to ~/.local/share/pki/nssdb for fresh profiles in M146 while still preferring ~/.pki/nssdb when it exists. Run ls -d ~/.pki/nssdb ~/.local/share/pki/nssdb and import into whichever the browser actually uses.

pcsc_scan shows the reader but no card

Reseat the CAC chip-first and confirm the contacts are clean. If pcsc_scan sees the reader but never reports an ATR with a known-good card, suspect the reader.

Only some .mil sites work

You are probably missing a root. Trust both DoD Root CA 3 and DoD Root CA 6 — cards issued before roughly 2023 chain to Root CA 3 and are still valid, while current issuance chains to Root CA 6. Root CA 4 issues nothing and Root CA 5 issues no CAC identity certificates.

Firefox does not prompt for the PIN

The module is not registered in the profile Firefox is actually using. Reload it under Settings → Privacy & Security → Security Devices, confirm the path matches your distro, and restart. On Ubuntu also confirm the snap pcscd connection.

Careful: PIN attempts are real

pkcs11-tool and pkcs15-tool PIN operations decrement the card's actual retry counter, so it is entirely possible to lock a CAC in three commands while debugging. The limit is typically three consecutive failures. Check the live count with pkcs15-tool --list-pins, which reads 'Tries left' from the card, and note that unblocking requires an in-person RAPIDS visit.

Frequently asked questions

Do I enable pcscd or pcscd.socket?

pcscd.socket. The daemon starts with --auto-exit and terminates when idle, so socket activation is what restarts it on demand. The service unit carries no WantedBy of its own, which is why enabling only the service can leave you with a reader that works until the next reboot.

Why did importing the DoD bundle not work?

Because NSS reads only the first certificate from a PKCS#7 package. certutil -A -i on a .p7b imports 1 of 49 certificates and exits with success, so nothing looks wrong. Split the bundle into individual PEM files with openssl pkcs7 -print_certs and import those.

Where is AllCerts.zip?

It is not what DISA publishes any more. The current artifact is unclass-certificates_pkcs7_DoD.zip, which contains PKCS#7 archives rather than loose .cer files, along with a signed SHA-256 manifest and a README. The current DoD group version is 5.14; version numbers differ per group, so a JITC or ECA version number is not comparable.

Which DoD roots do I need to trust?

Both DoD Root CA 3 and DoD Root CA 6 at minimum. Current CAC issuance chains to Root CA 6, but cards issued earlier chain to Root CA 3 and remain valid, so removing it breaks working cards. Root CA 4 has no subordinates in the bundle, and Root CA 5 issues software CAs only, no CAC identity certificates.

Does CAC work with the Firefox snap on Ubuntu?

Yes, since late 2024, but you must run sudo snap connect firefox:pcscd first because that interface does not auto-connect. The snap ships its own OpenSC, and the /usr/lib path you enter in Security Devices resolves to the snap's bundled copy — so upgrading OpenSC on the host has no effect on it.

How many PIN attempts do I get?

Typically three consecutive incorrect attempts before the card blocks, but the authoritative number for your specific card is on the card: run pkcs15-tool --list-pins and read the 'Tries left' value. Be aware that command-line PIN operations decrement that counter for real, and unblocking a locked CAC requires an in-person visit to a RAPIDS or ID card office.

Is my ~/.pki/nssdb still the right database?

If it already exists, yes — Chromium continues to prefer it. But from M146 onward a fresh profile uses ~/.local/share/pki/nssdb instead, so on a new machine you can import certificates into a database the browser never reads. Check which exists before importing.

Official sources

Other platforms