US DoD CAC Setup Instructions for Fedora 13
(32-bit x86 version only – a few changes are needed for 64-bit, RISC and PPC setups)


Getting your CAC reader working with DTS, AKO, etc. under Fedora is pretty easy. In this guide I will cover:

tl;dr section is located here – if you don't know what this means don't bother with it.

Software update using yum

Because patches come early and often in the Linux world it is a good general rule to always update your system fully before embarking on a quest to implement undocumented functionality on your system (well, undocumented until just now...). In Fedora there are two main ways to do this, using the updater you can select from the GUI menu, or directly instructing yum to do the update from the command line.

1
GUI method

2
CLI method

If you have a brand-new system it is usually best to call yum from the command line interface (CLI or shell) because it tends to handle all the updates-to-the-updater the best so you only have to direct a single update. The GUI updater can require updates to itself before exposing the full depth of available updates to the user, so you may go through two or three iterations of updates before you've got everything (for a normal user this isn't an issue because over the course of a day this multi-stage update would happen anyway).

For yum to work you need to call it as the root user. The way to switch to being root is to type the su command on the command line and then enter the root password. You will notice your command prompt changes from a $ to a #, indicating that you are now lord and master of whatever system you're on, precisely the way it looks in this screenshot.

Our yum update command should look like this:

su
yum update

Not too difficult. You will see yum query the update repositories, check and see if there is anything new and report back. It will then ask you if its OK to install the updates or not. Just press “y” and let it do its thing. Depending on how fast your connection is and how much updating there is to do, this could take a while. Time for a rum and coke...

Installation of media repositories and GPG keys for them

Because the Fedora project is sponsored by a company much smaller than both Microsoft, the MPAA or the RIAA it must avoid the muscle of the angry litigation machine by absolutely distancing itself from any software that might hurt anyone's feelings or leaglly confuse them. To this end the Fedora Project refuses to include any proprietary software in its distro, but leaves the door open for anyone to add anything they want after installation – which is what we're going to do...

The first thing we need to do is tell yum where the repositories are. The following commands (still run as root) will do just that by asking rpm to install a few repository headers from RPMFusion and Adobe:

rpm -Uvh http://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-stable.noarch.rpm \
  http://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-stable.noarch.rpm
rpm -ivh http://linuxdownload.adobe.com/adobe-release/adobe-release-i386-1.0-1.noarch.rpm

The next thing we have to do is make sure we only ever get authentic packages from these sources. We do that by installing GPG keys from each of these repositories. This way it is incredibly difficult (though not theoretically impossible) for a bad guy to sneak a malicious package in the middle of our update downloads at some point in the future:

rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-adobe-linux

And that's that. Now yum will understand what we are talking about when we start installing packages that aren't part of the official Fedora distribution.

Installation of wget

wget is a tiny little command line program that can download anything from anywhere – or actually many things from manywheres at once and can be scripted to do a whole lot more. This is a super powerful program, but we're just going to use it to automate the download of a few things in simple fashion below.

yum install wget

Installation of media codecs and streaming plugins needed for government websites

Briefly put, the following commands will download and install a set of codecs to handle various media formats used in podcasts, video demos, online training, VTCs and other multimedia functions which operate through the browser. (Additionally I provide instructions at the bottom of this guide for enabling DVD playback on Fedora, as it is required for various DoD training and open-source collection tasks.) Yes, I too have mixed feelings about setting my computer up to to access the most mind-numbingly boring government content ever created (like the DTS web training modules or the Army's "force protection" training series...) but to keep your online training certificates up to date you need this stuff. The upside is you can now watch YouTube, be bombarded with overwrought Flash-based animated advertisements and screw off on the internet just like you used to on Windows but without the constant security problems (like script viruses, trojan Active-X installer from pr0nz sites, key loggers that target your WoW or EVE Online accounts, etc.):

yum install flash-plugin gstreamer-plugins-ugly gstreamer-plugins-bad \
  gstreamer-ffmpeg vlc
wget http://www.mplayerhq.hu/MPlayer/releases/codecs/all-20100303.tar.bz2
mkdir -p /usr/lib/codecs
tar -jxvf all-20100303.tar.bz2 --strip-components 1 -C /usr/lib/codecs/
rm all-20100303.tar.bz2

Installation of OpenOffice.org and GIMP

The gub'ment is still hooked on anti-productivity software yet Microsoft has not yet relented and ported Microsoft Office to Linux just yet. OpenOffice covers for this quite nicely and happens to be included in the standard Fedora distribution (and is a lot smaller and faster than Microsoft Office, despite being a very similar user experience). The other area we should cover is professional-level image manipulation. There is no market for Photoshop on Linux because of an awesome program called GIMP (the interface is a little different from Photoshop as it was designed for animation professionals who use electric sketch pads, though, so it can take a little getting used to at first if you are a long-time Photoshop mouse-based user). We will install that as well to make sure we're covering all of our bases.

Run this command to receive all the office and shoop glory you have ever wanted but didn't want to pay for on your own:

yum install openoffice.org-writer openoffice.org-base openoffice.org-calc \
  openoffice.org-draw openoffice.org-emailmerge openoffice.org-extendedPDF \
  openoffice.org-graphicfilter openoffice.org-impress openoffice.org-javafilter \
  openoffice.org-math gimp

Installation of the Dogtag certificate system

[Note: Before getting started it is best to plug in your CAC reader now if it is not already connected. It is not specifically required to be plugged in at DogTag install time, but it is easy to forget to plug it in before the required restart coming up in the next few minutes, so do it now and be safe rather than sorry.]

While not required for AKO, the Dogtag certificate system has a huge number of excellent utilities (and gives you powers that rival the fat guy at the RAPIDS station that made your ID, incidentally...) all wrapped up in a polite bundle. It implements most of the features that ActiveClient provides as well as all the certificate enrollment and management systems that expensive smartcard management solutions provide (try playing with phone SIM chips in it sometime... and cry a little inside because DoD pays closed-source companies some amazing money to develop closed source crap when they could pay people like me to develop this stuff for far less and leave the intellectual rewards in the realm of public knowledge forever instead...). DTS requires some of the functionality provided here.

yum install dogtag*

This is a rather large set of packages, so its best to go make yourself another rum and coke now...

Installation of Sun's version of the Java Virtual Machine

And now that we've blown through all of the open source solutions here (CLI commands are pretty fast if you didn't read all my blather, actually...) we will have to return to the GUI, fire up the browser and hit the web a bit for some proprietary software fun.

Our first order of business is getting a hold of Sun's version of the Java Virtual Machine (JVM) Standard Runtime Environment (SRE).**

Point your browser at http://www.oracle.com/technetwork/java/javase/downloads/index.html and select the most recent version of the Linux 32-bit SRE as indicated by the screenshots below.
[Note for the curious: Distinct from the SRE, the SDK is the "Standard Development Kit" and is for people who want to write Java programs. It includes the SRE and so will also work for our purposes here, but also includes Sun's version of the Java compiler. If you were curious enough to read this note, you are probably curious enough to enjoy looking up some tutorials online or buying a Java book and toying with some code yourself...]

1
Select the JVM

2
Agree to give the soul of your firstborn to the devil Larry Ellison

3
Select the correct version

4
Save it to your “Downloads” folder

Now that we've got a hold of the right bits (unintended pun, lulz) we can execute the following commands from the command line to unwrap and unstall it:

[NOTE: the JRE version changed on 2010.10.14 from "build 1.6.0_21" to "build 1.6.0_22-b04". This tutorial has been updated to reflect that, but if you received your Java package from an old source you will need to change the commands to target jre-6u21-i586-rpm.bin and jre-6u21-i586.rpm where needed.]

cd Downloads
sh jre-6u22-linux-i586-rpm.bin
rm jre-6u22-linux-i586-rpm.bin
rm jre-6u22-linux-i586.rpm
cd ..

Seems easy... too easy. And it was. We have installed the Sun version of Java but it is merely sitting parallel to the original standard OpenJava installation. What we must do next is redirect calls to “Java, Version whatever.0” so that they are interpreted by the system as calls to “Sun's version of Java we just installed.” Instead of uninstalling OpenJava (it is of use to many other systems so we won't mess with uninstalling it) we will simply use the alternatives command to create a symbolic link that Firefox and related packages will pay attention to:

/usr/sbin/alternatives --install /usr/bin/java java /usr/java/default/bin/java 20000
/usr/sbin/alternatives --install /usr/lib/mozilla/plugins/libjavaplugin.so \
  libjavaplugin.so /usr/java/default/lib/i386/libnpjp2.so 20000

(**Fedora comes with a JVM of its own called OpenJava, which is supposed to become the new industry standard (well, since Sun was bought by Oracle we'll see what comes of that promise...), but DBSign, the DTS login applet, assumes Sun's version of Java is on everyone's system and so relies on the relatively insecure method of storing every user's certificate keys in the same place. Since the OpenJava developers (correctly) believe that keeping keys segregated by user is more secure and DBSign does not make a general call to the crypto interface the way all the other signature software we've messed with up to now does, we are left with no choice but to install Sun's JVM. Yay! Before beating up too bad on DBSign it should be noted that assuming everyone has Sun's JVM is an improvement on the previous (even more shallow) assumption that DBSign made that everyone everywhere would only ever access DTS from XP and Vista forever and ever, amen. Anyway we shouldn't be too hard on the makers of DBSign for getting an incredibly overblown government contract to implement a CAC function which can already be performed by ActiveClient or Coolkey – sort of reminds me of the > $1,000,000 contract to “develop” a few button plugins for FalconView – yes, I'm talking about the insanely overpriced software contract for the Raven UAV toolbar... that I could have written drunk in a weekend. Ironically, FalconView itself is open source and the toolbar plugin could have been had for beer money if the right person had asked the right person...)

Installation of DoD CA certificates in Firefox

We've come so far. Now its time to let Firefox know that we trust want to use Uncle Sam's websites. The first place we have to go is http://dodpki.c3pki.chamb.disa.mil/rootca.html to get the certificates themselves. You will need to click on each certificate link from top to bottom and tell Firefox to register them the way you see in the screenshots below:

1
Click the top one

2
Let Firefox know what you want that certificate to be allowed to certify (as in “everything”)

3
Let it fuss about expired or untrusted certificates on the 1st and 3rd CAs...(wtf, DoD, get with the program...)

The first certificate will (usually) give two warnings and the third one will give one, but other than that this is pretty straight forward. Once this is done the CA stack that DoD systems require is in place and registered on your browser.

At this point you will need to reboot (or for the technically inclined this really means restart most of the Gnome, Mozilla, and authentication services; a cycle through runlevel 2 works fine as it fully shuts down networking and authentication). I'll say "reboot!" again so nobody misses this.

Linking the CAC reader to CoolKey in Firefox

Now comes the part that gets most people tripped up and turned around. As stated above, before you proceed you should restart your system – otherwise some DogTag-related services will tell Firefox that the PKCS#11 device (your CAC reader) is already claimed, and Firefox will in turn tell you that you can't create the hardware profile below.

To get Firefox to connect AKO, OWA, RMT and similar authentication requests with your CAC through CoolKey you will have to tell it where the plugin is located by creating an encryption device profile. Without getting into too much wordiness, I'm just going to give you a series of explicit screenshots to follow:

1
1. Select “Edit -> Preferences”

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

3
3. Click “Load” and then “Browse”

4
4. Navigate to /usr/lib/pkcs11/
and select “libcoolkeypk11.so


5
5. Once you added the profile check it.
If you're CAC is not in the reader you should see something similar to this.

6
6. The first time you insert a new CAC you will get this message

7
7. By the time you pull it out DogTag should have enrolled it on your system and give you an accurate removal message

8
8. Whenever you insert an enrolled card you should get an accurate insertion message

Ultimately you must link CoolKey's plugin (located at /usr/lib/pkcs11/libcoolkeypk11.so on 32-bit systems) to a hardware encryption device profile in the Firefox "edit -> Preferences -> Advanced -> Encryption -> Security Devices" area by adding a new module and linking it yourself. Because Firefox is a sweet piece of coding and has human-readable configuration files I could eventually write a script to do this (and the rest of the GUI-required shenanigans here) for you – but since I've already spent a day writing and testing this setup instructional for free*** you're just going to have to suck it up until I feel like writing such a script.

(***If someone actually paid me for this I could write several of nice scripts and cover lots of subjects in more detail for DoD and clean things up quite a bit... [!hint hint!])

First login on each system

Now that everything is set up you need to try using (at a minimum) AKO, DTS and your unit's OWA mail. This may require another restart (if you did not perform the one I recommended prior, that is, and still managed to get away with registering CoolKey with Firefox).

AKO should give you the least trouble. Point Firefox here and let's give it a spin. AKO should query only one key (your DoD identification key, not your email one), enter your PIN and everything should work smoothly, like so:

1
Once you click “CAC Login” you should
be prompted for you PIN like normal

2
There will normally be only one certificate
option available. Select OK and login.

DTS is a little more involved because DBSign sucks. But we can get around that. 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 (still located at /usr/lib/pkcs11/libcoolkeypk11.so on 32-bit systems) and also ask us to accept its bogus-looking CA keys. I would caution folks not to permanently store your PIN in the DBSign registry where it shows you that you can. There are two reasons for this: (1) you might wind up having a bunch of people sign or authorize stuff in your name the next time you run to the doo-doo hole (yikes!), and (2) you would be storing your PIN inside a machine and not in your head (or a vault), which is less secure.

Anyway, for first login follow the screenshots below and you should be fine:

1
1. Head over to DTS and login

2
2. Accept that Big Brother loves watching you

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

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


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

6
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
7. Find our old friend libcoolkeypk11.so in the /usr/lib/pkcs11/ directory

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


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

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

11
11. You will encounter one problem later: Firefox will block the needless horde of DTS popups (which are entirely unnecessary for DTS to function, btw...). 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)****. OWA confuses some people, but not because their systems aren't working properly. The OWA Exchange server (for some reason) queries both the ID and the email certificate keys, and most users think “Ah, I'm logging in and since I'm me, I'll use the ID one just like on AKO...” but this would be wrong. OWA doesn't know about your AKO certificate and only knows you by your digital email signature, so make sure to select that one whenever you head to OWA (if you screw up you'll have about a 15 minute wait before you can try logging in to OWA again the way most servers are set up). I know there is a little box at the bottom that says “remember this selection” but that's just a little joke – it won't remember a thing no matter what you select:

1
Make sure when you access your OWA site that you
select the “CAC Email Signature Certificate”
It is the only one your mail server knows you by

(****And in other news... why the hell are we still using Microsoft Exchange Server anyway? Almost all of the sweet scripting and groupware functionality Microsoft thought to include has to be disabled to dodge architectural security vulnerabilities in Microsoft systems. Most people just use the Exchange server to do what any other (better and cheaper) email server could do: bombard ourselves with worthless A-to-Z traffic marked as "very important" or "urgent" and tagged with receipt notifications that everybody has already disabled in preferences (or in their mind) anyway... But here I think I am talking to the Void.)

Enabling DVD functionality

When we enabled media functionality at the beginning of this fabulous journey we added everything except the ability to play DVDs. There are three reasons for this: (1) the ability to play DVDs on Linux controversial to people who do not understand that math can never be made truly secret, (2) playing DVDs is not necessary for about half of the government employees for whom this instructional is being written, and (3) the Livna repository – which carries the most well-maintained DVD decryption package for Fedora – faces a suspicious number of "DNS outages" and DDoS attacks and therefore is not something you can always get to work at any given moment, but can easily be put off for another day.

For those who do need DVD functionality (like me), simply execute the following commands. If the first one works then you're in business. If not, then just try again tomorrow or next week – it'll come back up eventually***** and you can proceed:

rpm -ivh http://rpm.livna.org/livna-release.rpm
rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-livna
yum install libdvdcss

And that's all there is to it.

(*****If its down, and you're impatient, curious and adventurous, give this a read and move on.)

Known issues

I have thoroughly tested the above steps on different machines and ironed out the issues I found (and isolated the one occasional hangup: the Livna repository). My screendump of everything that came across the terminal during the process can be found here. If you get significantly different results (and problems) then please let me know.

Livna being down can be a pain in the ass. Fortunately viewing DVDs is not a frequent requirement for the majority – most of us have time to try catching Livna when its up.

At the moment the only truly broken functionality is the failure of the “remember this selection” box to actually remember anything. I have not tracked down the source of this bug (because I have been too lazy to try). Lucky for us this is merely a cosmetic issue.

If you encounter problems following these instructions or if any of the links above have have gone stale (don't work) 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.