Linux CAC

   

A project for configuring Linux distributions to work with Common Access Cards (CACs). Supports Debian/Ubuntu, Fedora/RHEL/CentOS, and Arch Linux. On Debian-family systems, the snap version of Firefox is not compatible with the certificate import method — the script can replace it with the apt version automatically. Before using this project, please review the Known Issues section.

Note

This project has moved from using Cackey to OpenSC, which seems to be more stable. If you previously installed Cackey, you can remove it:

• Debian/Ubuntu: sudo apt purge cackey
• Fedora/RHEL: sudo dnf remove cackey
• Arch: sudo pacman -R cackey

Table of Contents

Click to Toggle Expansion

1. Supported Configurations
2. Installation
   1. Methods
3. Known Issues
4. Troubleshooting
   1. Microsoft Teams
5. License
6. References

Supported Configurations

Regardless of how similar two distributions may be, I will only list distributions and versions here that I know have been tested with this method. On Debian-family systems since Ubuntu 22.04, Firefox will only work if you allow the script to remove the snap version and reinstall the browser with apt.

Family	Distribution	Versions	Browsers
Debian	Debian	12.5	Firefox ESR, Chrome, Edge
	Mint	21.2	Firefox, Chrome
	Parrot OS	6.0.0-2	Firefox, Brave
	PopOS!	20.04 LTS, 22.04 LTS	Firefox, Chrome
	Ubuntu	20.04 LTS, 22.04 LTS	Firefox, Chrome
Fedora	Fedora, RHEL, CentOS	—	Firefox, Chrome
Arch	Arch Linux	—	Firefox, Chrome

Note

Fedora/RHEL/CentOS and Arch Linux are supported via auto-detection but have had limited community testing. There are also reports of this script working with other distributions and browsers not listed above.

Installation

Warning

Please make sure all browsers are closed before running the script.

This script requires root privileges since it installs the opensc package and its dependencies. Feel free to review the script here if this makes you uncomfortable. For transparency, the DoD certificates are downloaded from here, which are recommended by militarycac.

Note

• The automated installation requires wget and unzip to run and will install both during the setup if they are not already installed. If you don't want either tool, remove it after the setup is complete using your package manager (e.g., sudo apt remove <command>, sudo dnf remove <command>, or sudo pacman -R <command>).
• The scripted installation has only been tested on the configurations listed in the Supported Configurations

Methods

• wget

sudo bash -c "$(wget https://raw.githubusercontent.com/jdjaxon/linux_cac/main/cac_setup.sh -O -)"

• curl

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/jdjaxon/linux_cac/main/cac_setup.sh)"

Known Issues

• The pkcs11-register command sometimes does not behave as expected when run in a script. Users may need to reboot or run pkcs11-register upon the completion of this setup script.

• Firefox and Chrome both need to be started at least once to initialize their respective certificate databases/profiles.

• Ubuntu 21.10 and greater (to include the latest LTS 22.04) have Firefox installed via snap by default. There is an outstanding bug (https://bugzilla.mozilla.org/show_bug.cgi?id=1734371) that prevents Firefox from being able to read the certificates. One solution could be to uninstall Firefox from snap and reinstall it via apt. This current version of the script will attempt to do the reinstallation for you.

• If you run into any issues with Firefox after running the script, clear your data and history in Privacy & Security and then restart Firefox. If your troubles are with MS Teams, see the section for troubleshooting teams. Chrome is recommended for MS Teams since Firefox does not currently support Teams meetings. You can see more about this here.

• Firefox will likely start up a bit slower after running this installation.

Troubleshooting

Microsoft Teams

If you run into issues with MS Teams, try the following steps:

1. In the Firefox Settings window, select the Privacy & Security tab
2. Under Cookies and Site Data, select Manage Exceptions
3. In the Address of website text box, enter the following URLs, and then select Allow

   https://microsoft.com
   https://microsoftonline.com
   https://teams.skype.com
   https://teams.microsoft.com
   https://sfbassets.com
   https://skypeforbusiness.com
   

4. Select Save Changes

Note

strict security settings in Firefox may cause a loading loop

See the official documentation for this issue here.

Contributing

Thank you for your interest in contributing to linux_cac! Whether you're fixing a bug, improving documentation, or adding a new feature, your help is appreciated.

How to Contribute

1. Fork the repository Create your own copy of the project by clicking the "Fork" button at the top right of this page.

2. Clone your fork

   git clone https://github.com/YOUR_USERNAME/linux_cac.git
   cd linux_cac
   

3. Create a branch for your changes

   git checkout -b <your-branch-name>
   

   OR

   git switch -c <your-branch-name>
   

4. Make your changes Keep commits focused and meaningful. Update or add documentation if needed.

5. Test your changes Ensure your changes don’t break existing functionality. If applicable, add tests.

6. Push to your fork and open a Pull Request

   git push origin <your-branch-name>
   

   Then, open a Pull Request on GitHub against the main branch of this repository.

Guidelines

• Follow existing code style and conventions.
• Keep changes atomic and well-documented in commit messages.
• For larger changes or features, please open an issue first to discuss your proposal.

Need Help?

If you run into any issues or have questions, feel free to open an issue or reach out.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Warning

This software is provided as-is without any warranty. Use it at your own risk, especially in sensitive or production environments. Always review scripts before running them.

References

• https://militarycac.com/linux.htm (this was my starting point)
• https://chromium.googlesource.com/chromium/src.git/+/refs/heads/main/docs/linux/cert_management.md
• https://firefox-source-docs.mozilla.org/security/nss/legacy/tools/nss_tools_certutil/index.html
• https://firefox-source-docs.mozilla.org/security/nss/legacy/tools/certutil/index.html
• https://askubuntu.com/questions/244582/add-certificate-authorities-system-wide-on-firefox
• https://stackoverflow.com/questions/1435000/programmatically-install-certificate-into-mozilla
• https://docs.microsoft.com/en-us/microsoftteams/troubleshoot/teams-sign-in/sign-in-loop#mozilla-firefox