DoD Common Access Card (CAC) Reader
tagline: From openSUSE
|Tested on openSUSE||Recommended articles||Related articles|
- 1 Preface
- 2 Smart Card Reader Driver
- 3 Configure Firefox
- 4 Configure Chrome / Chromium
- 5 Test out your browser
- 6 Additional Notes
- 7 External Links
- 8 See also
US Department of Defense (DoD) now limits access to many of its websites to be via a smart Common Access Card (CAC) authenticated with a Personal Identification Number (PIN). The following is a guide to assist in setting up openSUSE to access CAC-enabled DoD websites.
Install the middleware
The Linux CAC Reader stack is based on a set of middleware called PCSC (Personal Computer Smart Card), written by the MUSCLE (Movement for the Use of Smart Cards in a Linux Environment) project.
Packages available through openSUSE
In order to use the DoD CAC you must install the the following packages:
- pcsc-lite - PCSC Smart Cards Library
- pcsc-ccid - generic USB CCID (Chip/Smart Card Interface Devices) driver
- perl-pcsc - Abstraction layer to smart card readers
- pcsc-tools - Optional but highly recommended, these tools are used to test a PCSC driver, card and reader
- Note: Be sure to select the package that corresponds with your distribution version.
PKCS #11 module
There are three working modules to access the PKCS #11 keys on your CAC. Each have their strengths and limitations. You will need to choose which version works best for you. In most situations, CoolKey is preferred.
Coolkey is available through the openSUSE software repository. This is arguably the most stable method for accessing your CAC. The downside is, Dual Persona individuals that have the activated PIV certificate will not be able to access it rendering you not able to access the DoD Enterprise Email certificates. If you are not Dual Persona this is by far the best module to use as it is stable, accesses certificates quickly and does not cause the pcsc daemon to hang. Direct link to the software package:
CACkey is available from DISA's on the Forge.mil Linux development site. This works but is very slow to access the CAC certificates. The system will hang long enough that the sites may time out. It does work and sometimes requires an untimely page refresh. A machine with working CAC authentication is required for the DISA download. Once obtained, the RPM will install without issue.
Forge.mil hosts both CACkey and the DoD Configuration extension, but it also needs CAC authentication to download the packages. Easiest may be to download all on a CAC enabled machine and then transfer to the Linux machine via thumb drive. From forge.mil download:
- the latest version of CACkey
- the DoD Configuration extension for Firefox has been deprecated and has been replaced with these Instructions from DISA.
Recommend these be stored on AKO Cloud, Dropbox, portable media, or other location to ensure continued access.
This seems to be the most reliable option if you are a dual persona. The CACkey was recently updated which addressed performance issues.
CACkey Alternate download
This location is not CAC Protected and has the source available for download as well
OpenSC provides a set of utilities to access smart cards. It facilitates their use in security applications such as mail encryption, authentication, and digital signature. This module has a broader feature set than CoolKey or CACkey and you are able to access your PIV certificate for those individuals that are Dual Persona. This module is speedy like CoolKey and doesn't lag like CACkey. The downside is, this module does cause the pcsc daemon to require restarts from time to time. It may become more stable but at the time of this update (20 Sep 2016), there are reliability issues. This may be the best option if you are dual persona and do not wish to use CACkey for DISA.
If you find that the pcsc daemon has crashed you can run this in terminal to restart the daemon:
sudo systemctl restart pcscd
To check and see if the daemon has indeed crashed execute this in terminal:
If you remove and insert your card with no response during the scan, the daemon has crashed.
Smart Card Reader Driver
Without installing any additional drivers the following card readers are tested and work without issue:
SCR3310 by SCM Microsystems (Currently being issued to members by the US Army for use on personal computers) SCR3500 by SCM Microsystems (Many members purchase this as a more compact alternative to the SCR3310) O2 Micro, Inc (built-in to many Dell laptops)
- You may have to install additional drivers for your hardware. Check your hardware and search using the key word pcsc.
Starting up the daemon
- From YaST:
- Open YaST
- System Services (Runlevel)
- Select the Expert Mode Radio button
- Search for pcscd, select from the drop down Start/Stop/Refresh select Start
- Select "OK" to close the window
Testing your Smart Card Driver
Open a terminal (ie konsole, x-term or other) and type/enter. You might have to insert a smart card in order for the message to pop-up.
Similar to the following means the card reader is working properly:
PC/SC device scanner V 1.4.18 (c) 2001-2011, Ludovic Rousseau <email@example.com> Compiled with PC/SC lite version: 1.8.8 Using reader plug'n play mechanism Scanning present readers... 0: O2 Micro Oz776 00 00 Sun Mar 24 11:40:07 2013 Reader 0: O2 Micro Oz776 00 00 Card state: Card removed,
Similar to this:
PC/SC device scanner V 1.4.18 (c) 2001-2011, Ludovic Rousseau <firstname.lastname@example.org> Compiled with PC/SC lite version: 1.8.8 Using reader plug'n play mechanism Scanning present readers... Waiting for the first reader...
indicates a need to check for additional driver requirements for your hardware. Then check again to see if the PCSC Daemon (pcscd) is running.
Firefox requires a plug-in and some tweaking.
The plug-in is the aforementioned DoD Configuration extension for Firefox obtained from DISA
Once installed it may need configuring:
- Select from the menu, Tools > Add-ons
- Once the Add-ons page is loaded, Select Extensions > DOD Configuration [version] and click Preferences.
- Click the certificate buttons to update the certificate cache with the necessary DOD certificates, then click Redetect Smart Card Reader.
- If it fails to find the reader all is not lost--go to us.army.mil or some other CAC-requiring site and give it a try--it often works.
Ensure that Firefox doesn’t automatically select certificates (optional)
- When accessing multiple CAC protected pages, some pages will require different certificates from the card. Some require the non-email certificate while Enterprise Email will require the email certificate.
- To remedy this:
- In the Menu Select Preferences > Advanced > Certificates
- Select the radio button in front of "Ask me every time."
If the CAC Module is not working:
- Select from the menu, Edit > Preferences > Advanced > Encryption > Security Devices
- Check the left column. It should show an entry similar to "CAC Module" along with certificate(s) as a sub-item. If it doesn't work then the entries are wrong.
- Select the entry and select Unload to remove the security device
- To install/reinstall the CAC driver in Firefox using the above listed Security Devices
- Select Load on the dialog box
- Module name should be something like: DoD CAC
- Module filename: either type in or browse to the location of the libcoolkeypk11.so, libcackey.so or opensc-pkcs11.so drivers
- The files will be located under either:
Configure Chrome / Chromium
Unfortunately, Chrome (Chromium) doesn't automatically recognize the CAC once you've completed all the previous steps but it doesn't take much more work to get Chrome to work with the CAC.
In order to utilize the CAC within Chrome it is necessary to install mozilla-nss-tools. You can do so through the openSUSE software installation site or through terminal:
sudo zypper install mozilla-nss-tools
While in a terminal in your home directory run one of the two following commands as your user:
- For 32-bit systems:
modutil -dbdir sql:.pki/nssdb/ -add "CAC Module" -libfile /usr/lib/libcoolkeypk11.so
- For 64-bit systems:
modutil -dbdir sql:.pki/nssdb/ -add "CAC Module" -libfile /usr/lib64/libcoolkeypk11.so
Make sure that the utility is properly installed
modutil -dbdir sql:.pki/nssdb/ -list
If it is properly installed there will be an entry with "CAC Module" and details of the library, slot and status. If you were not in your home directory when configuring modutil you will receive an error like "modutil: function failed: SEC_ERROR_BAD_DATABASE: security library: bad database."
Chrome should now be able to utilize the CAC without any issues
Removing CAC Module
If you have previously installed libcackey.so and you wish to utilize coolkey instead, you will have to unload the "CAC Module":
modutil -dbdir sql:.pki/nssdb/ -delete "CAC Module"
Test out your browser
Go to a CAC-enabled web site (www.us.army.mil) and test the CAC login.
Be patient as there may be a delay while authenticating with the CAC.
The PIN and certificate selection authentication process is in the reverse of what you may be used to when using non-Linux machines. Expect to be prompted first for PIN and then certificate selection.
The Defense Travel System no longer requires Oracle Java in order to function correctly.
If you have previously used the CACkey module for accessing the Defense Travel System and now use Coolkey, you will have to edit the configuration file:
Alter the line that contains the following information (/usr/lib64/ for 64bit and /usr/lib/ for 32bit):
It should reflect the coolkey module: