Proof of concept which prepares a Yubikey NEO to be used in a HID pivCLASS physical access control system.

The instructions in the Usage section below only cover using the code in this repository to build the certificate authorities and client certs. It will also load the client certs onto a YubiKey NEO. For full documentation on how to get this to work with a physical access control system, see https://docs.google.com/document/d/1fOFzxfpgi8P-HVRdtnWiTNGCDRgeXcvorEqoSXA_4sE

Tested with: Mac OS X 10.10.5, HID pivCLASS PACS Service v1.2.297.0, HID pivCLASS Authentication Module (PAM) v5.1.8

On Mac:

1. You'll need a recent version of openssl that includes full elliptic curve support. Run brew install openssl then find the openssl binary with find /usr/local/Cellar -regex '.*/bin/openssl'

2. Edit make.bash and set OPENSSL= to the location that the find(1) command returned

3. Download at least version 1.3.0 of Yubico's yubico-piv-tool, available from https://github.com/Yubico/yubico-piv-tool/releases

4. Place the yubico-piv-tool binary in ~/bin/ (or change YUBICO_PIV_TOOL= in make.bash to point to where yours is located).

5. Insert a blank Yubikey NEO and run make cleanall ; make ca ; make client ; make yubikey

6. On the Windows machine where your HID pivCLASS PACS Service is running, import the CA certificates generated by make ca (trustanchor-ca.pem, eccp256issuing-ca.pem and eccp256pivcontentsigner.pem) into the Windows Certificate Store. HID makes a tool called cpvtool that assists with this, or you can just use certmgr.msc.

7. In the HID pivCLASS PACS Service program, make sure the card reader is set to use the CAK assurance profile (PACS Service Administration > Tools > Configure PACS Service > Reader Services tab > Panels > Panel #1 > Reader #1, Assurance Profile = CAK (PIV)). Note that the CHUID assurance profile provides the same level of security as a proximity card because the CHUID object can be cloned onto a different card. CAK authentication uses PKI to verify that the private key on the Yubikey is tied to the certificate and that the cert was signed by a trusted Certificate Authority.

8. The HID pivCLASS Authentication Module (PAM) checks in with the pivCLASS PACS Service periodically and will download the certs within a few minutes.

9. Use a card reader like the Gemalto Prox-DU along with HID pivCLASS Registration Workstation to register the Yubikey into the pivCLASS system. After this is done, the card's GUID will be loaded onto the PAM.

10. You can now present the Yubikey NEO to a HID pivCLASS reader connected to the PAM, which will:

    1. Verify that the cardholder unique ID (CHUID) is on the Yubikey and was signed by a known certificate authority.

    2. The cert in slot 9E (card auth) was signed by a trusted CA

    3. Generate a nonce and ask the Yubikey to sign it using the private key in slot 9E. The command used is GENERAL AUTHENTICATE.

If all those things are successful, then depending on the configuration, the PAM will open a relay on the PAM or it will transmit the GUID to a door controller via wiegand. The latter is more common, since it allows the door controller to make a decision as to whether that Yubikey is authorized to open the door in question at the current time. If you want a simple single door controller that doesn't require Physical Access Control system software, you can use a HID Edge EVO Solo.

If you want to put together a proof of concept yourself, the easiest way is to purchase a pivCLASS evaluation kit from HID. The part number for the evaluation kit as of this writing is D91920ANN.