US DoD CAC Setup Instructions for Ubuntu 10.4 LTS (32-bit)

2013-04-21: I received a lot of mail recently about problems on Debian derived distros about Firefox crashing on CAC insertion. Please see this post about it. I need more information about the problem before I can do anything or recommend a fix. If you have this problem please leave a note on the post indicating your distro name, version, Firefox version, coolkey package version, etc. to help others out.

Getting your CAC working with Ubuntu 10.4 is not difficult at all. Below I will detail how to get everything to work correctly step by step, with even more screenshots than I include in the (really easy) Fedora 13 32-bit guide as I recognize most Ubuntu users are not generally as tech-oriented as the Fedora crowd (which is too bad because Fedora 13 was an absolutely amazing distro... whereas Ubuntu 9.10 beat Fedora 12 hands-down).

Below I will cover:

  1. Software update using apt
  2. Installation and activation of media codecs and streaming plugins needed for government websites
  3. Installation of GIMP
  4. Installation and checking of Coolkey
  5. Installation of Sun's version of the Java Virtual Machine (necessary for DBSign work properly)
  6. Installation of DoD CA certificates in Firefox
  7. Linking the CAC reader to Coolkey in Firefox
  8. First login to each system (just what to expect and how it will look -- a little different from Windows)
  9. Known issues

tl;dr version is located here.

Software update using apt

Folks unfamiliar with the command line will have an easy introduction to it in this guide. The first thing we will do is update the system using apt. (We will not be using the graphical update utility as it has had a checkered history with fresh-installation updates being incomplete, but if your system is not a brand new install then feel free to use it.)

So where is the CLI? The terminal? The command line went where?

Finding it the first time is a lot easier on Ubuntu than on, say, Mac OS X. Just follow the screenshot on the left. The screenshot on the right shows you were the graphical (GUI) update utility is:

And here it is! Just go to “Applications -> Accessories -> Terminal”

Not used in this tutorial, but great for everyday use, the GUI updater is located here

Once you have opened a terminal window, copy and paste the following commands:
(I am aware, by the way, that I update and upgrade through apt-get twice below. I'm just staying on the safe side as the Ubuntu update cycle had experienced issues in the past updating the updater. Staying on the safe side – never know what patches will be released in the future.)

sudo apt-get update
sudo apt-get upgrade
sudo apt-get update
sudo apt-get upgrade

You will notice that the first time you run a command the system will ask you for your password. That is because we are not running these commands as the true root user, instead we are running them as the pseudo root user through a little command aptly named sudo. Once we enter the password of someone authorized to alter system-level details (you) we will have a brief period where we can enter a bunch of sudo commands without continuing to be asked for validation. This brief period of authority is what we will use to get through the rest of the commands below without endlessly typing in our passwords:

sudo in action

This is one of the contrasts between Fedora and Debian security paradigms (the distro Ubuntu is based on): Debian allows you to sudo into root access, whereas Fedora strictly enforces root user authority by keeping everything about the root user segregated. The Fedora thinking is that you are less likely to compromise the root password than you are your own – and this makes a lot of sense, even if it is a bit paranoid for home users. The Debian (Ubuntu) thinking is that control of our passwords is an individual responsibility and actually logging on as root with another password (omg! a whole 'nother password!) using su is too much of a pain to bother with (its really not these days). Regardless, either approach is a huge step forward over the Windows “do you really want to do this?” “no, really?” “no, I mean for real, for real?” approach which drove me up the wall – and ultimately did nothing to protect my system from all the fundamental architectural security flaws anyway.

Installation and activation of media codecs and streaming plugins needed for government websites

Now that our system is all up to date, we need to get our media house in order. As Ubuntu is based in South Africa it can afford a more realistic view of the world than bizarro-legal-land American-based Fedora can. This eases the installation process as Ubuntu does not have any emotional hangups dealing with proprietary formats (on the flip-side of this, Canonical also has lots of deals with proprietary vendors, which for historical GNU/Linux reasons is controversial).

Still in the terminal, we will need to enter the following commands:

sudo apt-get install ubuntu-restricted-extras flashplugin-nonfree
sudo /usr/share/doc/libdvdread4/

The first line installs all of the distastefully patented codecs which are legally white to run, but upset the serious free-media thinkers out there (this is, perhaps, the majority of Linux users, so this is a big enough deal for Ubuntu to decide to make codec installation a separate step). We also installed the Flash player plugin from Adobe, so you can waste time on YouTube now with the rest of the Internet (and it also allows you to use the TraX/Passport DTS support site...).

The second line does something more legally ambiguous depending on your jurisdiction. What we have done in this step is enable your Linux system to play DVDs. Whoa! Did your roof come crashing down? No?

Admittedly, this is not that big of a deal. I have lots of DVDs and want to play them. I also have DoD training materials I need to view, some of which are (strangely) region coded using the CSS encryption system – which sucks because my DVD players at home are all Region 2 (Japan) and I'm not going to buy a different DVD player to watch work materials unless they start paying me more.

You can look into this more yourself, but the arguments behind making it illegal for someone to perform mathematical functions on a physical device they bought and own is preposterous. It is directly equivalent to me selling you a car with a lock on the hood, and making it illegal for you to open that hood or even express your understanding of the lock (which you bought and now own). That is a fundamental re-definition of property law and also flies in the face of reality: the collective mind of information society is smarter than anything a media company is going to throw at them, so legal or not, all such DRM protections will be circumvented. This trend is unstoppable and is more akin to a force of nature than a strictly human phenomenon (implying there is no choice involved in whether DRM will be circumvented). So it is time to look for a new business model to exploit the mass communications of the future, not time to start imposing unnatural and unenforceable laws on mathematical processes which have technical implications far beyond their original intent just to force the survival of business based on outdated technology.

Installation of GIMP

GIMP is commonly known as "the Photoshop killer" because it provides the same functionality as Photoshop but its free. Long-time mouse-only users of Photoshop tend to deride GIMP, thinking it is either not as powerful or too cumbersome to use because the menu style is unfamiliar to them. GIMP is as powerful as the plugins you've installed and there are literally thousands of them if you know where to look. The menu interface is designed with the electronic sketchpad user in mind (it was made for digital artists, not photographers) so the time spent locating something to click with a mouse was not taken into account when designing the main, multi-window style interface. To make things faster for mouse users almost the entire GIMP menu has been made available by right clicking anywhere in the edit window (the one containing the image you are editing).

I spend the time to explain all of that because while it is a powerful tool in the right hands it can be a frustrating one for a newcomer approaching it for the first time with a pile Photoshop-based preconceptions in their head. That all being said, installation is as easy as the following tiny command:

sudo apt-get install gimp

Installation of Coolkey

Coolkey is the little piece of code we are going to use to communicate with our CACs through our CAC readers. It replaces the functionality we get from ActivClient and related software on Windows. We are going to install it and then just make sure it is working and talking to our CAC readers. Before you perform the following steps it is probably a good idea to have your reader plugged in, otherwise Coolkey will wonder what it is supposed to be doing until you do.
[NOTE: I am using a USB SCR331 smartcard reader. This seems to be the standard across the military these days, but older models do still turn up. If you have something other than an SCR331, and particularly if you have a non-USB card reader your mileage may vary with these instructions. Feel free to contact me to relate your experiences, workarounds or trouble spots with these alternate readers.]

To install Coolkey and related tools simply run the following command:

sudo apt-get install coolkey pcscd pcsc-tools

Once we've done that make sure your CAC reader is plugged in, insert a card and run the following command to make sure everything is talking properly:


You should see some output similar to this (at least this is what mine looked like):

iyagami@Seawall:~$ pcsc_scan
PC/SC device scanner
V 1.4.16 (c) 2001-2009, Ludovic Rousseau <>
Compiled with PC/SC lite version: 1.5.3
Scanning present readers...
0:SCM SCR 331 (21120812208165) 00 00

Tue Oct 12 22:09:20 2010
 Reader 0: SCM SCR 331 (21120812208165) 00 00
  Card state: Card inserted,
  ATR: 3B DB 96 00 80 1F 03 00 31 C0 64 77 E3 03 00 82 90 00 C1

ATR: 3B DB 96 00 80 1F 03 00 31 C0 64 77 E3 03 00 82 90 00 C1
+ TS = 3B --> Direct Convention
+ T0 = DB, Y(1): 1101, K: 11 (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
  TC(1) = 00 --> Extra guard time: 0
  TD(1) = 80 --> Y(i+1) = 1000, Protocol T = 0
  TD(2) = 1F --> Y(i+1) = 0001, Protocol T = 15 - Global interface bytes following
  TA(3) = 03 --> Clock stop: not supported - Class accepted by the card: (3G) A 5V B 3V
+ Historical bytes: 00 31 C0 64 77 E3 03 00 82 90 00
  Category indicator byte: 00 (compact TLV data object)
    Tag: 3, len: 1 (card service data byte)
      Card service data byte: C0
        - Application selection: by full DF name
        - Application selection: by partial DF name
        - EF.DIR and EF.ATR access services: by GET RECORD(s) command
        - Card with MF
    Tag: 6, len: 4 (pre-issuing data)
      Data: 77 E3 03 00
    Mandatory status indicator (3 last bytes)
      LCS (life card cycle): 82 (Proprietary)
      SW: 9000 (Normal processing.)
+ TCK = C1 (correct checksum)

Possibly identified card (using /usr/share/pcsc/smartcard_list.txt):
3B DB 96 00 80 1F 03 00 31 C0 64 77 E3 03 00 82 90 00 C1
        CAC (Common Access Card)

One quirk to the pcsc_scan command is its lack of self termination. To exit the status above press [Ctrl]+[C] and you will be back at your command prompt. (If you check out the screen dump I recorded from this process you will see a little “^C” on line 1922 which is what prints on the screen when you [Ctrl]+[C].)

If you got something similar on your screen (as opposed to a simple message saying something along the lines of “Card reader? What card reader?” or “Card? What card?”) then you should be ready to proceed.

Installation of Sun's version of the Java Virtual Machine (necessary for DBSign work properly)

Installing Sun's JVM is easier than on Fedora, simply because Ubuntu does not mind partnerships with evil empires. The way we install the Sun/Oracle version of Java is to tell apt-get where the proprietary partner repository is (first command), update apt-get's list of available software (second command), and then install the ones that include the closed-source version of Java we need for DBSign to work correctly (third command):

sudo add-apt-repository "deb lucid partner"
sudo apt-get update
sudo apt-get install sun-java6-jre sun-java6-plugin

Be forewarned that you will encounter some ridiculous licensing notifications and have to sign your soul away to Larry Ellison in the process, but its a small price to pay for Java... (or is it?)

Sun (now owned by Oracle) wants to tell you something... well, a lot of somethings

Just say OK and walk on by quickly.
Don't make eye contact with the lawyer
mad-dogging you through your screen...

Once you navigate through the legal goo your
screen should be full of techno blah blah blah,
indicating progress

And that was easy, right?

But we have a problem. Most free systems do not use the closed source version of Java by default. In fact, we already had a JVM installed called OpenJRE. Most of the time it doesn't matter which JVM you use to run Java programs, but at this point in DBSign's development life, it does. Interestingly enough, the product manager of DBSign wrote me about this to explain his position and precisely why/how DBSign does not work with OpenJRE/IcedTea*. As things stand right now the DoD "feel more comfortable relying on Oracle's support when needed as opposed to community driven support from OpenJDK". While that is an irony of the highest order in light of the history of serious computing systems from the 1960's to today (consider broad industry standards such as PostgreSQL, Kerberos, the Linux kernel, OpenLDAP, SELinux, Dovecot/Postfix, Fetchmail, Evolution, Firefox, etc.) that is simply the way things are for now, and it leaves us in need of the Oracle JVM and all the creepiness that goes along with it.

So let's check which version we have running now:

[*In the original version of this instructional I incorrectly asserted that the method of key storage/retrieval within OpenJRE was incompatible with how DBSign worked. I had been led to believe that the lump storage of the Oracle JRE versus the segregated storage of OpenJRE was the problem. This was wrong. Mike Prevost, the DBSign product manager, kindly explained to me that the actual reason is that OpenJava's NSS implementation does not work with DBSign. He went on to say very encouraging things about the future, and that Gradkell Systems is looking forward to claiming full OpenJRE support in the future.]

java -version

We will probably see something similar to the following:

java version "1.6.0_18"
OpenJDK Runtime Environment (IcedTea6 1.8.1) (6b18-1.8.1-0ubuntu1)
OpenJDK Client VM (build 16.0-b13, mixed mode, sharing)

And now let's run the following command which will switch which JVM calls go to:

sudo update-java-alternatives -s java-6-sun

Don't panic at all the crazy error messages. A number of new features and calls have been added to the OpenJRE implementation of Java which are not available on Sun's JRE (and likely aren't even installed on the system currently, but are being checked for just the same). Those calls will still go to OpenJRE and not be affected by our change, but their nonavailability is something the system feels is important to let you know about as you try to shift gears with the command above. Now that we've switched our primary Java engine, let's check the version again:

java -version

And we should get something similar to the following:

java version "1.6.0_20"
Java(TM) SE Runtime Environment (build 1.6.0_20-b02)
Java HotSpot(TM) Client VM (build 16.3-b01, mixed mode, sharing)

And now life is delicious (if heavily licensed) cake.

[NOTE: Sun released a new build, 1.6.0-22-b04, on 2010.10.14. This is the version Fedora folks are running, but that is just because Fedora is always a little ahead of Ubuntu on package currency. Don't sweat it. Let your system run whatever the Ubuntu partner repository installs and everything will be OK.]

Installation of DoD CA certificates in Firefox

Now its time to leave the command line and play with Firefox. We need to install the DoD's CA certificates before Firefox will trust any DoD website (and for good reason). I'm assuming you're reading this in Firefox (or maybe Lynx? You get two Cool PointsTM from me if this is true...) already, so open this link in a new tab and follow the screenshots below:
[Firefox poweruser skill: to open any link in a new pop-under tab without right-clicking and selecting "Open Link in New Tab", try clicking the link by pressing down on your scroll-wheel (or middle mouse button). Life is more convenient when you know things like this.]

1. Click the top one

2. Let firefox know what you want that
certificate to certify (as in “everything”)

3. Let it fuss about expired or otherwise
unverifiable certificates when you try to install the 1st
and 3rd ones (the first one will probably throw two
warnings and the third one will throw one)

At this point your computer knows and wants very badly to believe that DoD websites are really DoD websites. Congratulations! Now a narrow, shallow world of incredible boredom is available for you to browse!

Before proceeding to the next step it may be a good idea to restart your computer and make sure your CAC reader is plugged in if it isn't already.

[Sad note for the Unix savvy: Debian/Ubuntu assumes that every user will want a windowed interface, always. There is no available “hit runlevel 3 and come back to 5 to restart X-related services without a reboot” process on a default install...]

Linking the CAC reader to Coolkey in Firefox

So now we have all the software and devices in place, but we don't have everything tied together because the browser doesn't know about all these components yet. What we need to do is tell Firefox what plugin to use to talk with the CAC reader, and after that everything else we've done will fall in place.

We need to open the Firefox options tab, create a new hardware encryption device and link that to the Coolkey plugin profile located at /usr/lib/pkcs11/ (on 32-bit systems). Just follow the screenshots and make sure your system looks like mine by the end:

1. Select “Edit -> Preferences”

2. Select “Advanced -> Encryption -> Security Devices”

3. Click on the “Load” button

4. Rename the “New PKCS#11 Device” item “CAC Reader” and click the “Browse...” button

5. Navigate to /usr/lib/pkcs11/ and select

6. If your screen looks like mine when you're done, click “OK”!

And now Firefox knows where to look when a call to a PKCS11 certificate comes in from somewhere.

First login to each system

We are going to do three test logins, one to each of three different, very common DoD systems: AKO/DKO, DTS and an OWA server. Fortunately the military is standardizing this process slowly and most web applications (with the strange exception of DTS) use the AKO/DKO authentication process, so if you can log on to AKO with no problem you should also be able to log on to RMT, online military libraries, TraX/Passport, and most other web-based applications.

Since it is statistically the most important (and also the simplest) we'll hit AKO first. Point Firefox at this: and let's try it out. Air Force and Navy users should have a similar experience with their own systems, but I have not yet personally tested them (I'm loathe to maintain too many DoD accounts that I don't use at once...). If you have feedback please let me know; I'm curious.

AKO will ask you for only one key, which makes this pretty easy. Just follow along:

Once you click “CAC Login” you should
be prompted for your PIN like normal.
Note here that AKO calls your PIN the
"master password"

There should be only one certificate
option available. Select OK and login.

DTS is a little more involved because DBSign does not yet play well with OpenJava (yet), as discussed above. Point Firefox here and let's give this a whirl. DBSign will ask us which device we are using, so we will connect it with the Coolkey plugin the same way we connected Firefox in the last step above. DBSign will also leave a blank available where you can store your PIN/password for hassle-free DTS signing (see screenshot #8). I strongly advise against entering anything in the blank (the makers of DBSign tell me that this makes them nervous as well), just because it opens the door for someone to sign as you (and maybe obligate or disburse lots of money in your name if you're an AO) the next time you aren't at your desk and your CAC is...

Follow the screenshots below and you'll be all straight:

1. Head to DTS and login

2. Accept that Big Brother is allowed to watch you do your thing... (eh?)

3. Let the JVM know that you trust things from the DTS website

4. Let the JVM know that you trust DBSign enough to let it access your hardware

5. The first time you login you should get a configuration prompt like this one. Click the “...” button to browse for the Coolkey plugin (again)

6. To simplify your life, start browsing from the root directory “/” as shown here (now you know where the website “Slashdot” got its name...)

7. Find our old friend in the /usr/lib/pkcs11/ directory

8. I recommend you leave the password/PIN line blank and just click “Save”

9. You should then get a funkier-than-on-before authentication dialogue asking for your CAC PIN

10. If victory is delicious we should now see the familiar DBSign “Signing Data” logo

11. You will encounter one problem later: Firefox will block the needless horde of DTS pop-ups (which are entirely unnecessary for DTS to function, btw... bad web design makes me angry). To allow pop-ups from the DTS website only *strongly recommended), click where the screenshot shows.

And last up is OWA, (if you use it at your unit, that is). OWA is a little weird in that it queries both your email signature and user ID certificates, but you are only supposed to be using the mail signature one to sign in with. This doesn't make a lot of sense, but a lot of people try logging in with their ID certificate (make sense, as every other website wants that one, right?) but Exchange kicks you out whenever you do that. (Of course, using Exchange Server at all doesn't make a whole lot of sense in the first place, as the only feature most DoD sites are permitted to enable is email and meetings anyway -- and there are far superior, smaller and cheaper email and meeting schedule servers to cover those uses. But that is probably a hopeless argument in Government at the moment...)

Follow the screenshots and you should be fine:

Make sure you're “CAC Email Signature Certificate” is selected

Click “OK” and remember, the little check box in
the lower left is just a bad joke,
Firefox won't remember a thing... (>.<)

Known Issues

So far we don't have any real known issues with this process, though there have been some issues with Ubuntu 10.4 as a system in the past. Fortunately it seems that Ubuntu has sorted itself out and things are working pretty smoothly. These days both on Fedora and on Ubuntu I tend to see far fewer problems in general than on Windows-based systems. If you additionally need to install Ekiga, Skype or whatever, I recommend using the GUI software installation tool from here on out.

If you encounter issues, have something to add or have extra DoD web based things you think it would be useful to include, please let me know.

CAC Guide IndexMain zxq9 page

All contents copyright 2010 zxq9.
If you want to reuse something, just contact me.
I'm nice.