Document toolboxDocument toolbox

Common Access Card Installation Guide

Owned by Brian Dixon
Last updated: Mar 19, 2024 by Brian Dixon
4 min read

Users are identified with a special 10 digit identifier provided by the DoD called the Electronic Data Interchange Personal Identifier (EDIPI). The EDIPI is a unique number assigned to each User. When a User swipes their CAC, this information is transmitted to the application in the form of a Common Name (CN).

The web server is configured to enable X509 certificate-based authentication.  X509 certificates are files that prove that the User is who they claim to be. The CAC contains one or more of these certificates and presents them to the web server when the User logs in.  X509 user security needs two files.  The first is the X509 certificate file, which is issued to every User by the DoD Certificate Authority (CA).  The second is the CA file.  For CAC, this file comes from the DoD and gets refreshed on a regular basis. These CA files are installed on the web server and lets us know if the User can be trusted or not.

Installation

Note: The links contained herein were current at the time this document was published. Professional Computing Resources, Inc (PCR) does not control them and they are subject to change.

Preface

  • The instructions presented here are tailored for CentOS & Apache 2.4, however other than filenames, there is nothing specific to any particular Linux distribution or version.

  • For simplicity, we're using OpenSSL/mod_ssl but NSS/mod_nss can be used in its place. The Apache directives are very similar. Installation of NSS/mod_nss is distribution-specific and outside the scope of this document.

  • These instructions also apply to using any client certificate for authentication - not just CAC certificates. The difference is in where the client certificates and Certificate Authority (CA) Root Certificates are obtained.

  • These instructions assume that PCR-360 is already installed and the regular (https) server certificates are installed and working.

Summary

The steps necessary to enable CAC authentication in PCR-360 are as follows:

  1. Install the Client Certificates

  2. Install the Server Certificates

  3. Configure Apache

  4. Configure PCR-360

Client Certificates

Note: You may already have these installed.

The current, recommended method for installing the DoD certificates locally is by using the InstallRoot Tool provided by the DoD. They also provide a full User Guide with installation instructions.

Server Certificates

Certificate Authority (CA) Root Certificates

Note: These certificates are updated (roughly) annually and the new ones must be re-installed on your server manually.

The CA Root Certificates are usually provided to you by your card issuer. The public DoD Cyber Exchange also has them available. Direct download links are as follows:

Once you've downloaded the certificates, they need to be placed on the server, unzipped, converted to PEM encoding and bundled into a single file.

wget https://dl.dod.cyber.mil/wp-content/uploads/pki-pke/zip/certificates_pkcs7_DoD.zip unzip certificates_pkcs7_DoD.zip openssl pkcs7 -in Certificates_PKCS7_v5.7_DoD/Certificates_PKCS7_v5.7_DoD.pem.p7b \ -print_certs -out DoD_CAs.pem mv DoD_CAs.pem /etc/pki/tls/certs/

Note: If you need more than one set of the CA Root Certificates, for example, both DoD and JITC, they can be concatenated into a single file by order of precedence. This step may also be necessary if your regular server certificate is already using an SSLCACertificateFile.

cat My_CAs.pem DoD_CAs.pem JITC_CAs.pem > ALL_CAs.pem

Certification Authority (CA) Revocation List (CRL)

Note: The current size of all the CRL Certificates is ~500MB and it continues to grow. Using the CRL significantly increases the Apache startup time. In our testing, it adds approximately 30-60 seconds. Results will vary depending on the server's resources.

If you are required to or choose to, use the CRLs, they can be obtained here.

Once you have the file, it must be unzipped, all certificates converted from DER to PEM, and then bundled into a single file. The following script does everything for you, The resultant file is located at /etc/pki/tls/certs/allDoDCRLs.pem.

#!/bin/bash # Get the zip file wget --no-check-certificate https://crl.chamb.disa.mil/getcrlzip?ALL+CRL+ZIP \ --output-document allCrl.zip # Unpack it in a directory if [ -d crls ]; then rm -rf crls fi mkdir crls unzip allCrl.zip mv *.crl crls cd crls # Convert all the crl files from DER to PEM FILES=`ls *.crl` for A_FILE in $FILES; do echo converting $A_FILE openssl crl -inform DER -outform PEM -in $A_FILE -out $A_FILE.pem done # Bundle everything together cat *.pem > ../allDoDCRLs.pem cd .. # Remove old bundle if it exists rm -f /etc/pki/tls/certs/allDoDCRLs.pem # Copy new bundle to cert directory mv allDoDCRLs.pem /etc/pki/tls/certs/ # Finish cleanup rm -rf crls allCrl.zip

Apache Configuration

Here is an example (partial) Apache Virtual Host configuration. Only the necessary directives are shown.

FIPS 140-2

FIPS 140-2 cryptography can be enabled in Apache with OpenSSL by using the "SSLFIPS on" directive. This must be placed in the main httpd.conf file. Installation and configuration are outside the scope of this document.

PCR-360 Configuration

Note: Unlike the other PCR-360 authentication interfaces, CAC does not create User records. The User record must exist in the application prior to authentication.

Configuration is as simple as adding a few options to the INI:

Troubleshooting

  • ERR_BAD_SSL_CLIENT_AUTH_CERT

    • If the browser does not request which certificate to use, the client does not have the proper certificates installed.