Client Device Certificate Authentication Requirements

With the client device certificate authentication feature, you can set up certificate authentication for client systems to Horizon Client for Linux. Unified Access Gateway authenticates the client systems. The SoftHSM2 library manages the distribution and deployment of certificates to the client system. After successful device authentication, the user must still perform user authentication.

Prerequisites

This feature has the following requirements.

Unified Access Gateway 2.6 or later
Client system is equipped with a root Certification Authority (CA) certificate that Unified Access Gateway accepts

For information about configuring Unified Access Gateway, see the Unified Access Gateway Documentation.

Set up the Linux Client System for Device Certificate Authentication

To set up device certificate authentication, you must perform these high-level tasks:

Install the SoftHSM2 library on the system.
Create a cryptographic token for the SoftHSM2 library.
Prepare the device certificate and public and private keys.
Import the certificate and keys file into the SoftHSM2 database.
Configure the SoftHSM2 library for use by Horizon Client.

The following procedure provides guidelines for completing the setup on a general Linux client system. Specific steps might vary depending on your Linux distribution.

Note: Device certificate authentication is also supported on thin clients running Becrypt Paradox. For setup information, refer to the documentation for Becrypt Paradox.

Install the SoftHSM2 library on the Linux client system using one of the following methods.
1. Method 1: Use package management tools.
  For example, on an Ubuntu system you can run the following command.
```
sudo apt-get install softhsm2
```
2. Method 2: Compile and install the SoftHSM2 library manually.
  1. Clone the SoftHSM2 source code repository to the system.
```
git clone https://github.com/opendnssec/SoftHSMv2.git
```
  2. Compile, configure, and install the SoftHSM2 library from the cloned source code.
    Note: Horizon Client installs its own OpenSSL library and also consumes the OpenSSL library that is linked to SoftHSM2. To avoid conflict during runtime, ensure that you link SoftHSM2 to the same OpenSSL library installed by Horizon Client.
    In the following command example, the <path to OpenSSL library> should contain the "include" and "lib" path.
```
cd SoftHSMv2/
sh autogen.sh
./configure --with-crypto-backend=openssl --with-openssl=<path to OpenSSL library>
make
sudo make install
```
Create a cryptographic token for the SoftHSM2 library.
By default, SoftHSM2 has one token slot. When you initialize a token in the first slot, a second slot is automatically added. Subsequent slots are added as you initialize a new token in each slot.
1. Run the command to create the token.
```
softhsm2-util --init-token --slot 0 --label "<your token label>"
```
2. Make a note of the slot ID returned by the token creation command. You will need this slot ID later when you import X.509 device certificate and key files into the SoftHSM2 database.
Prepare the X.509 device certificate and public and private keys.
1. Get the device certificate in PFX format which contains the private key.
2. Convert the PFX file to a keys file in PEM format. For example, the following command transforms client.pfx to client-keys.pem.
```
openssl pkcs12 -in client.pfx -nocerts -nodes -out client-keys.pem
```
3. Convert the PEM keys file to a PKCS8 keys file.
```
openssl pkcs8 -in client-keys.pem -topk8 -nocrypt -out client-keys.pk8
```
4. Convert the PFX file to a X.509 certificate in DER format.
```
openssl pkcs12 -in client.pfx -nokeys -nodes -out client-cert.pem
openssl x509 -outform der -in client-cert.pem -out client-cert.der
```
Import the X.509 certificate and keys file into the SoftHSM2 certificate database.
1. Import the keys file into the SoftHSM2 database.
  For example, the following command imports the client-key.pk8 file. Replace <your token label> and <slot ID> with the values you got in step 2.
```
softhsm2-util --import client-key.pk8 --token "<your token label>" --slot <slot ID> --label "client" --id 0001
```
2. Import the X.509 certificate into the SoftHSM2 database.
  For example, the following command imports the client-cert.der file. Replace <softhsm2-pin> with the PIN required to access the SoftHSM2 database.
```
pkcs11-tool --module /usr/local/lib/softhsm/libsofthsm2.so -l -p <softhsm2-pin> --write-object client-cert.der --type cert --id 0001
```
3. Verify that the X.509 certificate, public key, and private key are all stored in the SoftHSM2 database.
```
pkcs11-tool --module /usr/local/lib/softhsm/libsofthsm2.so -l -p <softhsm2-pin> --token-label "<your token label>" --list-objects
```

Configure the SoftHSM2 library for use by Horizon Client.

sudo mkdir /usr/lib/vmware/view/pkcs11
sudo ln -s /usr/local/lib/softhsm/libsofthsm2.so /usr/lib/vmware/view/pkcs11/libsofhsm2.so

FIPS Compliance Mode Support

If you want to use device certificate authentication in an environment that is compliant with the Federal Information Processing Standard (FIPS), first complete the steps described in Enabling FIPS Compatible Mode. Then perform the setup procedure described in the previous section, Set up the Linux Client System for Device Certificate Authentication, with the following modification.

To compile the SoftHSM2 library with FIPS Compliance Mode, run the following sequence of commands.

cd SoftHSMv2/
sh autogen.sh
./configure --with-crypto-backend=openssl --with-openssl=<path to OpenSSL library>  --enable-fips
make
sudo make install

Note: If you encounter missing header issues during the compilation, you can download the source code for FIPS-related headers from www.openssl.org/source/. Copy the headers into the path to the OpenSSL library and repeat the command sequence to compile the SoftHSM2 library with FIPS Compliance Mode.