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

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:

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.)

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:

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:

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:

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:

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):

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):

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?)

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.]

We will probably see something similar to the following:

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

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:

And we should get something similar to the following:

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 Points^TM from me if this is true...) already, so open this link in a new tab and follow the screenshots below: http://dodpki.c3pki.chamb.disa.mil/rootca.html
[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.]

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/libcoolkeypk11.so (on 32-bit systems). Just follow the screenshots and make sure your system looks like mine by the end:

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: http://www.us.army.mil 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:

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:

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:

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 Index – Main zxq9 page

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