Common Access Card Installation Guide

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:

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.

BASH

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.

BASH

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.

BASH

#!/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.

BASH

<VirtualHost *:443>
...
    # Optionally add request logging
    CustomLog logs/ssl_client_request_log "%h %l %u %t %{SSL_CLIENT_I_DN}x %{SSL_CLIENT_S_DN}x"

	# These directives should already be set. Adjust SSLCipherSuite if necessary.
    SSLEngine on
    SSLProtocol -all +TLSv1.2 +SSLv3
    SSLCipherSuite ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL

    # There should already be a SSLCertificateFile and SSLCertificateKeyFile for your server certificates
    SSLCertificateFile /etc/pki/tls/certs/example.com.crt
    SSLCertificateKeyFile /etc/pki/tls/private/example.com.key

    # Add the DoD CA Root Certificates 
    SSLCACertificateFile /etc/pki/tls/certs/DoD_CAs.pem

    # Add the CA CRL File. Again, this adds a significant amount to the Apache startup 
    # time and has a sight impact on overall performance.
    SSLCARevocationFile /etc/pki/tls/certs/allDoDCRLs.pem

    <Location />
        SSLRequireSSL

        # For setup and testing purposes, you can set this value to "require". If you do so, and there's a certificate problem,
        # the user will see a browser error (ERR_BAD_SSL_CLIENT_AUTH_CERT) rather than a PCR-360 authentication error.
        # Ensure this value is "optional" once you verify that the server is receiving the certificate. If it's "required", 
        # the browser can/will get stuck in a redirect loop.
        SSLVerifyClient optional

        SSLVerifyDepth 10
        SSLUserName SSL_CLIENT_S_DN_CN
        SSLOptions +ExportCertData +FakeBasicAuth +StdEnvVars
    </Location>
...
</VirtualHost>

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:

BASH

; auth.AUTH_ADAPTER = "Native"
auth.AUTH_ADAPTER = "Cac"
auth.AUTH_CREATE_USERS = BOOLEAN_FALSE
auth.AUTH_UPDATE_USERS = BOOLEAN_TRUE
auth.AUTH_ROLEMAPPING = BOOLEAN_FALSE

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.