The Department of Defense (DoD) issues Common Access Cards (CACs) which are smart cards set up in a particular way. You can use these cards for Public Key Infrastructure (PKI) authentication and email. Overwhelmingly, the first thing most users need is PKI authentication.

Basic PKI Authentication

Get a card reader

Obtain a compatible smart card reader. Known compatible readers are:

  • SCM Micro SCR3310 - Stand alone reader
  • O2 Micro OZ776 - Built-in laptop reader
  • Gemplus GemPC Card - PCMCIA card reader

  • ActivCard USB Reader 2.0 - Stand alone reader (outdated)

    • Note: Double check version number on bottom of device. You must flash the reader to the latest firmware. Currently, this must be done from a windows machine.

Info <!> Note: If you have trouble with your reader, review device compatibility

Packages

You need middleware to access a smart card using the SCard API (PC/SC), and a PKCS#11 standard interface for smartcards connected to a PC/SC compliant reader. US government smartcards may also need support for the Government Smartcard Interoperability Specification (GSC-IS) v2.1 or newer. The pcsclite project provides the middleware layer. Ubuntu splits pcsclite into a few packages. As of this writing, the average user needs libpcsclite1 and pcscd. For the PKCS#11 interface, users can choose between coolkey and cackey. US Government users are probably better off with cackey instead of coolkey, so the coolkey package is omitted here. Since you're downloading packages, you may as well download pcsc-tools now too, as you'll want it soon enough, for testing.

sudo apt-get install libpcsclite1 pcscd pcsc-tools

Other items

You will need the DoD certificates.

You will almost certainly want want the cackey package instead of coolkey. Even if you prefer Chrome for your primary browser, you will probably want the DoD Configuration extension for Firefox, if for no other reason than testing.

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 Ubuntu machine (thumb drive, dropbox, etc). Here's your forge.mil shopping list:

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.

Applications

pcsc_tools

Yes, grasshopper, we know you want Firefox. We're getting there. First, it's prudent to make sure your card reader is talking to the operating system. The pcsc_tools package provides an especially handy utility, pcsc_scan, which can help verify that your CAC reader really is talking to the OS, regardless of what any application is telling you:

$ pcsc_scan

It should output something like this:

name@computer_name:~$ pcsc_scan
PC/SC device scanner
V 1.4.16 (c) 2001-2009, Ludovic Rousseau <ludovic.rousseau@free.fr>
Compiled with PC/SC lite version: 1.5.3
Scanning present readers...
0: SCM SCR 3310 (21120839GXXXXX) 00 00

Mon Aug 15 11:47:42 2011
 Reader 0: SCM SCR 3310 (21120839GXXXXX) 00 00
  Card state: Card inserted,
  ATR: 3B 7D 96 00 00 80 XX XX XX XX XX XX XX XX XX XX XX XX

ATR: 3B 7D 96 00 00 80 XX XX XX XX XX XX XX XX XX XX XX XX
+ TS = 3B --> Direct Convention
+ T0 = 7D, Y(1): 0111, K: 13 (historical bytes)
  TA(1) = 96 --> Fi=512, Di=32, 16 cycles/ETU
    250000 bits/s at 4 MHz, fMax for Fi = 5 MHz => 312500 bits/s
  TB(1) = 00 --> VPP is not electrically connected
  TC(1) = 00 --> Extra guard time: 0
+ Historical bytes: 80 31 80 65 B0 XX XX XX XX XX XX XX XX
  Category indicator byte: 80 (compact TLV data object)
    Tag: 3, len: 1 (card service data byte)
      Card service data byte: 80
        - Application selection: by full DF name
        - EF.DIR and EF.ATR access services: by GET RECORD(s) command
        - Card with MF
    Tag: 6, len: 5 (pre-issuing data)
      Data: B0 XX XX XX XX
    Tag: 8, len: 3 (status indicator)
      LCS (life card cycle): 00 (No information given)
      SW: 9000 (Normal processing.)

Possibly identified card (using /home/user_name/.smartcard_list.txt):
3B 7D 96 00 00 80 XX XX XX XX XX XX XX XX XX XX XX XX
        DoD CAC card issued Jan XX, 2010

If you see this instead:

SCardListReader: Cannot find a smart card reader. (0x8010002E)
Waiting for the first reader...

You probably did not update your firmware properly. See symbolik's instructions to see how to update your firmware.

Firefox

To setup Firefox to authenticate with sites via SSL/PKI, you must:

  • download the DoD Certificates so that you can verify the server, and
  • setup firefox to read your client certificates from your CAC card.

As of Onereic, running Firefox 9.0.1, the DoD Configuation extension (version 1.3.6) sets all this up for you, assuming your card reader is interacting with Ubuntu. The following directions are mainly preserved for folks running older versions. YMMV.

DoD Certificates in Firefox

The DoD has created a hierarchy of certificates. The top level certificate signs the intermediate certificate and the intermediate certificate signs the site's certificate in most cases. If you import and trust the top most certificate, it saves you from having to install and trust a significantly higher number of certificates.

The original way to install DoD root certificates, even on Windows XP, was to visit http://dodpki.c3pki.chamb.disa.mil/rootca.html and just click on each one to install.

You may also download the certificates and install each one using the following procedure.

  1. Preferences Menu

  2. Advanced Section

  3. Encryption Tab

  4. View Certificates Button

  5. Authorities Tab

  6. Import Button

Places to download the certificates are:

Firefox Client Certificate Setup

  1. Insert CAC into reader - the green light should flash.
  2. Add CAC Module to Firefox as a Security Device

    1. Preferences Menu

    2. Advanced Section

    3. Encryption Tab

    4. Security Devices Button

    5. Load Button

    6. Enter CAC Module as the module name, and browse to /usr/lib/pkcs11/libcoolkeypk11.so for the module filename (or /usr/bin/libcackey.so or /usr/lib/libcackey.so if using the CACKey custom PKCS#11 library available from cackey).

Info <!> NOTE: If you are updating from an existing install, or are having issues getting Firefox to play nice when trying to login in with CAC, you may need to remove all existing libcoolkeypk11.so modules and start from the beginning. For example: $ sudo updatedb, $ locate libcool, and delete all modules found.

Testing Firefox

You can test Firefox by going to https://teamware.dt.navy.mil/ and clicking on New Account at the top. If it works, you should be prompted to enter your PIN and the site should say Your PKI Certificate has been detected.

Google Chrome/Chromium Setup

For SSL certificate management, Google Chrome on Linux uses NSS. No UI is provided to install PKCS11 modules. It is important to complete the initial steps above for the CAC reader and Firefox setup prior to Google Chrome setup.

1. Install NSS tools

Debian/Ubuntu:

sudo apt-get install libnss3-tools

2. Add the "CAC Module" pkcs11 library

2b. Close Chrome

3. Make sure you are in your home directory and your CAC card is inserted, Open a terminal window and enter this:

cd
modutil -dbdir sql:.pki/nssdb/ -add "CAC Module" -libfile /usr/lib/libcackey.so

4. Check if the library was successfully added

modutil -dbdir sql:.pki/nssdb/ -list

5. You should see something like this:

Listing of PKCS #11 Modules

1. NSS Internal PKCS #11 Module
     slots: 2 slots attached
     status:loaded

     slot: NSS Internal Cryptographic Services
     token: NSS Generic Crypto Services

     slot: NSS User Private Key and Certificate Services
     token: NSS Certificate DB

2. CAC Module
     library name: /usr/lib/libcackey.so
     slots: 1 slot attached
     status: loaded

     slot: CACKey Slot
     token: LASTNAME.FIRSTNAME.NMN.123456789

6. Now you can start using your certs in Chrome.

Evolution

The Evolution email client does not currently have a means to configure the security device (CAC reader) through the GUI as does Firefox or Thunderbird.

However, there is a fairly simple (but obscure) workaround that can be executed from the command line. Mozilla's certificate database can be imported into Evolution by copying three files within a terminal window:

cd ~/.mozilla/firefox/*.default
cp cert8.db key3.db secmod.db ~/.evolution/

This appears to import in all the DoD certificates and security devices (CAC reader) previously configured in Firefox as outlined in the above instructions. Look under the 'U.S. Government' heading to confirm ('Edit/Preferences.../Certificates/Authorities tab'). You'll need to select each individual certificate (ie "DOD CA-11"), click the 'Edit' button, and then select the boxes for both trust to ID sites, and trust to ID email users. Do this for all the certificates under the U.S. Government heading. This step is tedious, but you'll only need to do it once.

Next, select the appropriate certificate for signing and encrypting email. From 'Edit/Preferences', click on 'Mail Accounts', select your previously configured AKO/DKO account (either POP or IMAP), click the 'Edit' button, and then the 'Security' tab. Under the 'Secure MIME (S/MIME)' heading, select both the signing and encryption certificates, and any of the option check boxes desired.

When composing a new message, pull down the 'Security' menu and select 'S/MIME Sign' and/or 'S/MIME Encrypt' as appropriate.

Please note the author of the above section has not yet fully tested this functionality, but initial testing was successful. Nevertheless, implement with caution.

Note: There is currently no way to authenticate to the Exchange server though Evolution with a CaC and the above instructions are only to use the CaC for signing and encrypting the messages. This has been requested in Bug 253574 and may be implemented in version 2.23.x. The bug tracker has a patch for those wishing to recompile Evolution with untested code.

Machine and Screensaver login with CAC

With a little work you can also use your CAC card to log into Ubuntu or un-screenlock.

Note: If you are using cackey for CAC middleware, it's highly recommended to use cackey with CAC login. Using coolkey for login will most likely result in authentication conflict, resulting in CAC lockout.

Needed libraries:

sudo apt-get install libssl-dev libpam0g-dev pkg-config libpcsclite-dev

Needed tools to build pam_pkcs11:

sudo apt-get install libtool autoconf automake

Get the latest version of pam_pkcs11 from https://github.com/OpenSC/pam_pkcs11.git and build pam_pkcs:

git clone https://github.com/OpenSC/pam_pkcs11.git
cd pam_pkcs11
./bootstrap
./configure --prefix=/usr --exec-prefix=/usr
make
sudo make install
sudo ln -s /usr/lib/security/pam_pkcs11.so /lib/security/pam_pkcs11.so

Make sure that the directories /usr/lib/pam_pkcs11 and /usr/share/pam are present and populated.

Although documentation states that make install should create a directory structure at /etc/pam_pkcs11 it doesn't seem to.

Create said directories:

sudo mkdir /etc/pam_pkcs11
sudo mkdir /etc/pam_pkcs11/crls
sudo mkdir /etc/pam_pkcs11/cacerts
sudo cp /usr/share/doc/pam_pkcs11/pam_pkcs11.conf.example /etc/pam_pkcs11/pam_pkcs11.conf
sudo touch /etc/pam_pkcs11/subject_mapping

Edit pam_pkcs11.conf for use with cackey:

sudo gedit /etc/pam_pkcs11/pam_pkcs11.conf

Change the line that reads:

use_pkcs11_module = opensc;

to be

use_pkcs11_module = cackey;

Then directly after the aforementioned changed line:

  # Cackey Support
  pkcs11_module cackey {
    module = /usr/lib64/libcackey.so;
    description = "Cackey";
    slot_num = 0;
    support_threads = false;
    ca_dir = /etc/pam_pkcs11/cacerts;
    crl_dir = /etc/pam_pkcs11/crls;
    cert_policy = signature;
  }

Find and change the line:

use_mappers = digest, cn, pwent, uid, mail, subject, null;

to

use_mappers = subject;

Save. LDAP or other mappings will most likely be used in the future, but the above will work for now.

Information to unlock your system with your CAC can be obtained via the following:

Run:

pkcs11_inspect debug

Find where it says your name with the syntax LASTNAME.FIRSTNAME.MIDDLENAME.DODID and take note of it.

Open /etc/pam_pkcs11/subject_mappping:

sudo gedit /etc/pam_pkcs11/subject_mapping

Add the line:

/C=US/O=U.S. Government/OU=DoD/OU=PKI/OU=CONTRACTOR-or-USN-or-USMC-etc/CN=LASTNAME.FIRSTNAME.MIDDLENAME.DODID -> local_username

Edit to allow your system to use CAC authentication for unlocking:

Add the line:

auth sufficient pam_pkcs11.so

to the top of the following files:

/etc/pam.d/gdm
/etc/pam.d/gnome-screensaver

If you want to have your system try to use CAC authentication for everything including ssh, su, sudo, etc, add the line to the top of /etc/pam.d/common-auth.

Try rebooting and logging in with your CAC card. At the username prompt I had to just hit enter, then it asked me for my CAC PIN.

One thing to note. If you are using a Windows virtual machine under VMware Player or Server with CAC authentication in the virtual machine - the virtual machine will tie up the reader so Ubuntu can't get access to it. You'll get errors like token unavailable.

Lock Gnome Screensaver on Card Removal

The package pcsc-tools includes the tool pcsc_scan. This command line application will print the insertion and removal of a Smart Card to the stdout. Using this information, a script can be written to recognize this change. The following script requires the package inotify-tools.

#!/bin/bash

if [ $(pidof pcsc_scan) ]; then
       echo pcsc_scan is running
else
       pcsc_scan -n > ~/cardscan.txt &
fi

while inotifywait ~/cardscan.txt

do

tail -n 3 ~/cardscan.txt | grep "XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX"

if [ $? == 0 ]; then
        echo unlocked
        gnome-screensaver-command -d
else
        tail -n 3 ~/cardscan.txt | grep removed
        if [ $? == 0 ]; then
                gnome-screensaver-command --lock -a
        fi
fi
done

After saving this script, you need to update line 13. Run pcsc_scan and look for the line that says "ATR: XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX XX". This number is unique to your card. Update the XX's in the script with your unique line.

Make the script executable:

chmod +x caclock.sh

Add it to your Startup Applications.

This script will only unlock the screensaver if your CAC is inserted however, if you do not desire the unlock behavior, simply comment line 17: "gnome-screensaver-command -d".

Using CAs and CRLs

Surrender all hope, ye who enter here...

There seems to be a problem with pam_pkcs11 verifying the certificates with valid CAs and CRLs (the project has had little activity in the past few years.) For now, using the cert_policy = signature setting in pam_pkcs11.conf will work to log you in via CAC, but it won't actually be running checks to verify with the locally stored certificates.

If you want to try to experiment with getting certificates to work, use the CA and CRL instrutions below as a starting point, and set cert_policy = ca in pam_pkcs.conf.

CAs

With CAs, you're mostly on your own. You may be able to find what you need from here. If you get another x.509 format like .pfx, you can use openssl to change it to .pem.

sudo cp CAcert.pem /etc/pam_pkcs11/cacerts/
cd /etc/pam_pkcs11/cacerts
sudo chmod a+r *
sudo pkcs11_make_hash_link

Certificate Revocation Lists

wget --no-check-certificate https://crl.chamb.disa.mil/getcrlzip?ALL+CRL+ZIP
sudo cp ~/Downloads/ALLCRLZIP.zip /etc/pam_pkcs11/crls
sudo unzip ALLCRLZIP.zip -d /etc/pam_pkcs11/crls
rm getcrlzip\?ALL+CRL+ZIP

Special considerations

ActivCard USB Reader v2.0

ActivCard USB Reader v2.0 P/N ZFG-9800-AD was flashed using the instructions at http://symbolik.wordpress.com/2007/02/26/scm-scr-331-usb-smartcard-reader-firmware-upgrade/. The rest of this guide was then followed without issue.

Gemplus GemPC Card (PCMCIA)

This card reader uses the ccid driver. Since it uses a serial port connection, you must tell pcscd where it is located. Before you begin, you need to install the software as shown in the next step. Once the apt-get procedure is completed, come back here to configure your reader.

First, determine which serial port on which it has loaded. Insert the card into the pc card slot and run dmesg in a terminal. You should get output similar to the following; note the tty.

[ 5924.740035] pcmcia_socket pcmcia_socket0: pccard: PCMCIA card inserted into slot 0
[ 5924.740307] pcmcia 0.0: pcmcia: registering new device pcmcia0.0
[ 5924.881176] 0.0: ttyS1 at I/O 0x3f8 (irq = 16) is a 16450

Next, edit /etc/reader.conf.d/libccidtwin to add the following lines:

FRIENDLYNAME      "GemPCTwin serial"
DEVICENAME        /dev/ttyS1
LIBPATH           /usr/lib/pcsc/drivers/serial/libccidtwin.so
CHANNELID         1

Then run sudo update-reader.conf, followed by sudo service pcscd restart. If everything worked correctly, you may proceed with the next step.

LPS

LPS-Public is a thin Linux LiveCD with a PIV/CAC-enabled Firefox browser that cannot mount the harddrive.It aims to open all DoD websites and OWA (webmail) clients. The developer at SAIC will roll custom versions on request, however, LPS is also very locked down. Experience suggests the typical user is far better off with Ubuntu (circa late 2011, early 2012).

Coolkey

Warning /!\ Note that coolkey, a Red Hat project, does not always work on Ubuntu in a US government environment. One bug in coolkey can be tracked here

You can get coolkey from Fedora's BuildSystem. Its an RPM. Just extract the lib folder and copy to /usr/, overwriting existing files. Follow this procedure:

  1. $ wget http://kojipkgs.fedoraproject.org/packages/coolkey/1.1.0/17.fc15/i686/coolkey-1.1.0-17.fc15.i686.rpm

  2. $ sudo apt-get install rpm2cpio

  3. $ rpm2cpio coolkey-1.1.0-17.fc15.i686.rpm | sudo cpio -idmv

  4. $ sudo rsync -va ./usr/lib/ /usr/lib/

OpenSC

In rare cases, you may be the first to use a new card. In the path to diagnosing that and pushing the information upstream, you may find the OpenSC project helpful.

References

Big thanks to symbolik and his article Using DoD CAC and smartcard Readers on Linux

Department of Defense PKI Management https://crl.chamb.disa.mil/

Naval Research Laboratory DoD PKI Notes and accompanying PDF

Relevant Discussion Threads

CommonAccessCard (last edited 2014-07-17 20:29:34 by c-67-183-69-78)