Friday, June 1, 2012

How to install DOD Common Access Card Reader under SuSE 12.1

There are numerous sites addressing the problem in general.
    https://help.ubuntu.com/community/CommonAccessCard
    http://symbolik.wordpress.com/2007/02/25/using-dod-cac-and-smartcard-readers-on-linux/
    http://ubuntuforums.org/showthread.php?t=1221961
    http://pcsclite.alioth.debian.org/
    http://zxq9.com/dodcac/

This summarizes my experience.

Step 1: 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:
    http://pcsclite.alioth.debian.org/
    http://ludovic.rousseau.free.fr/softwares/index.html

Part of the stack is pscs-tools, not available in the SuSE 12.1 repositories. You can find an RPM at:
    http://ludovic.rousseau.free.fr/softwares/pcsc-tools/index.html

In particular, this is needed to provide pcsc_scan, which is a tool to detect and interpret the reader parameters.

The rest of the stack is available in the repositories, in particular:
    http://download.opensuse.org/repositories/security:/chipcard/openSUSE_12.1/
where it appears as pcsc-lite.rpm.

Step 2: Add the correct plugin module
In addition to the core pcscd daemon pcsc-lite contains a long list of pcsc-xxxxx modules for different types of card readers. The correct one for most modern readers is the pcsc-ccid module.

Step 3: Add the correct PKCS #11 module
The original module to read PKCS #11 keys was coolkeys. Allegedly (I haven't tried) it no longer works, you need cackeys, available from DISA's Linux development site:
    http://militarycac.com/files/Ubuntu11_04cacsetup.pdf
    http://www.forge.mil/Community.html?uri=/sf/go/projects.community_cac/frs.cackey

From the first reference at the top of the page:
Forge.mil hosts both cackey and the DoD Configuration extension, but it presents a chicken and egg problem: you need CAC authentication to get the packages. The easiest thing to do is just download them all at work and figure out how to get them to your {Linux} machine(thumb drive, dropbox, etc). Here's your forge.mil shopping list:
  • the latest version of cackey
  • the latest version of the DoD Configuration extension for Firefox
I recommend stashing these two on Dropbox somewhere, just to make sure you have access to them later, when that thumb drive gets lost in your car seat and you want to set this up for your buddy on a Saturday, or something like that. Trust me. Just do it.
We address the second item later, but like he says, "just do it."

Step 4: Get the correct CAC reader
The next step is the driver. There seems not to be a Linux one anywhere for the ActivCard. You might be able to use a Windows driver with ndiswrapper but that is an act of self-flagellation most would prefer to avoid. Better to get a supported reader. Lists of readers and their support status are here:
    http://pcsclite.alioth.debian.org/ccid/section.html
    http://pcsclite.alioth.debian.org/ccid/unsupported.html

The latter confirms that ActivCard is a problem child.

Step 5: Get and install the driver
I traded in the (unsupported) ActivCard for an SCM SCR-3310, for which there are Linux drivers here:
    https://alioth.debian.org/frs/?group_id=30105

Additionally you can download the "Latest SCR" Linux driver from
    http://www.identive-infrastructure.com/en/products-solutions/smart-card-readers-a-terminals/smart-card-readers/scr3310


Step 6: Test it
Run pcsc_scan.  You should see something like the output shown in:
    http://militarycac.com/files/Ubuntu11_04cacsetup.pdf
    ~ # pcsc_scan
        PC/SC device scanner
    V 1.4.18 (c) 2001-2011, Ludovic Rousseau
    Compiled with PC/SC lite version: 1.8.3
    Using reader plug'n play mechanism
    Scanning present readers...
    0: SCR3310 Smart Card Reader [CCID Interface] 00 00
    ...
    Possibly identified card (using /usr/share/pcsc/smartcard_list.txt):
    3B DB 96 00 80 1F 03 00 31 C0 64 B0 F3 10 00 07 90 00 80
            DoD CAC, Oberthur ID One 128 v5.5 Dual 


If your output stops at "Scanning present readers..." then you've got it wrong.

Step 7: Set up the browser
Now, this depends on the browser. You wouldn't be here unless you hate Microsoft, so if not figure out IE on your own... That leaves Firefox and Chrome.

I am using Firefox.

Firefox requires a plugin and some tweaking.

The plugin is the aforementioned DOD Configuration addon obtained from DISA in Step 3


Once installed it may have to be configured:
  • Go to Tools > Add-ons > DOD Configuration x.y.z (x.y.z is the version you have installed) and click Preferences
  • Click the certificate buttons to update your certificate cache with the necessary DOD certificates (yes, it's that easy), then the acid test: Redetect Smart Card Reader
  • If it fails to find the reader all is not lost. First, just for grins, go to email.usnwc.edu or some other CAC-requiring site. It may just fly anyhow.
  • If not then the following:
    https://help.ubuntu.com/community/CommonAccessCard#Gemplus_GemPC_Card_.28PCMCIA.29
    http://symbolik.wordpress.com/2007/02/25/using-dod-cac-and-smartcard-readers-on-linux/

give the answer: 
  • Do Edit > Preferences > Advanced > Encryption > Security Devices
  • Check the left column. It should show an entry for CAC Module or some such term with your certificate(s) as a subitem. If it doesn't work then these entries are wrong. 
  • Select them and click Unload to remove them. 
  • Use locate from a terminal to find the location of the libcackey.so drivers and then use Load to specify their location. Mine are at
    /usr/lib/libcackey.so
    /usr/lib/libcackey_g.so


Now try the CAC-requiring site again. This time it should request a Master Password. Enter your CAC Personal Identification Number (PIN). It then will provide a dialog box with a list of your certificates. As always, choose the email certificate for accessing email, the DOD certificate for accessing DOD web sites.

Done. Enjoy.