Access Server: PKCS#11 hardware tokens for VPN connections

Description: OpenVPN Connect supports external certificates on PKCS#11 hardware tokens for VPN connections. This page provides an overview of setting it up on your device. The instructions are applicable for Yubikey hardware tokens with PKCS#11 support, such as Yubikey 5 NFC. You can try the same steps with modules for hardware tokens of other vendors.

Note: Support for PKCS#11 hardware tokens requires Windows or macOS and OpenVPN Connect 3.3 and newer.

Important note: OpenVPN Connect 3.5 supports loading ECC certificates when using hardware tokens such as Yubikey. Use RSA-based certificates for other versions. OpenVPN Access Server 2.9 and newer supports multiple CAs per server.

Before you begin

1. Installed OpenVPN Connect on Windows or macOS.
2. Hardware tokens with PKCS#11 support. In this guide, we will use Yubikey 5 NFC.
3. Installed hardware token management software CLI Tool (Yubico PIV Tool). (Refer to the Yubikey site: Yubico PIV Tool.)
4. Installed hardware token management software UI Tool (YubiKey Manager). (Refer to the Yubikey site: YubiKey Manager.)

Note: In this guide, we will use YubiKey as a hardware token. If you're using another hardware token, refer to the vendor documentation for instructions about how to use their software and import the client certificate and private key.

Step by Step

Edit the Client Profile

1. Download a user-locked or auto-login connection profile from your Access Server.
2. Open the connection profile (.ovpn file) with a text editor, copy the content between "<cert>" and "</cert>", and paste it into a new file like this:

   -----BEGIN CERTIFICATE-----
   MIIBnjCCASWgAwIBAgIIWZHeXiokANswCgYIKoZIzjXEAwIwFTETMBEGAXUEAwwK
   TXBlblZQTiBDQTAeFwXyNDAXMDQxOTMXMzdaFwXzNDAXMDMxOTMXMzdaMBIxEDAO
   BgNVBAMMBXXwZWXXcGXwdjAQBgcqhkjOPQIBBgUrgQQAIgNiAATWGXrEXwZXRtsP
   NtTynxSnXXy+XMdhEEvNXNxEODPGmubXXwQMSXzHfWXXhMFAkJalrdXNIAIqLarg
   YytVxQDXKINlIo+bDXXzUiXXBnUGudSAXeXXfABVtE/XImSs/TWjRTBDMAwGAXUd
   EwEB/wQCMAAwCwYDVRXPBAQDAgeAMBMGAXUdJQQMMAoGCCsGAQUFBwMCMBEGCWCG
   SAGG+EIBAQQEAwIHgDAKBggqhkjOPQQDAgNnADBkAjBuQKXNOWcDGYCXfXjcRk+W
   pX+G+cMIXwxeqPNQfXBgXyiXvsdzSX/CrKiTctrUeqYCMGXXBSXJkgkXmYJEkWcO
   cAyXclSXnAXfgnXzojsXilXXXyFXXXcXBLXTkXPzXXqLkA==
   -----END CERTIFICATE-----

3. Save this file as "yubico-cert.crt".
4. Also, copy the content between "<key>" and "</key>":

   -----BEGIN PRIVATE KEY-----
   MIGXAgEAMBAGByqGSMXXAgEGBSuBBAAiBIGeMIGbAgEBBDDXHhJXYZbXfGXcbVuP
   XOKwGCXqXPgNHL/XBTHXSXANXgqrKYl/viYhdRXAKTa+gMKhZANiAATWGXrEXwZX
   RtsPNtTynxSnXXy+XMdhEEvNXNxEODPGmubXXwQMSXzHfWXXhMFAkJalrdXNIAIq
   LargYytVxQDXKINlIo+bDXXzUiXXBnUGudSAXeXXfABVtE/XImSs/TU=
   -----END PRIVATE KEY-----

5. Save this file as "yubico-private.key".
6. Remove the content from "<cert>" to "</cert>" and "<key>" to "</key>" from the connection profile (.ovpn file) and save the file as "yubico-profile.ovpn".

You should now have three files:

1. The connection profile ("yubico-profile.ovpn").
2. The client certificate ("yubico-cert.crt").
3. The private key ("yubico-private.key").

Import the Client Certificate and Private Key into the Hardware Token (Yubikey)

Note: For this step, we can use either "Yubico PIV Tool" (CLI) or "YubiKey Manager" (UI).

You have two options to import the client certificate and private key:

1. Import the client certificate and private key as two separate files.
2. Import the client certificate and private key as a single file with either the .p12 or .pfx extension.

Option 1: Importing the client certificate and private key as two separate files

Using "Yubico PIV Tool"

1. Ensure that your hardware token (Yubikey) is connected to your PC.
2. Open Windows CMD and run this command:
   

   cd C:\Program Files\Yubico\Yubico PIV Tool\bin

3. Now we can run "yubico-piv-tool" commands to import the client certificate and private key.
4. We now have two files in the below directories:
   

   C:\Users\Brandon\Documents\YUBICO\yubico-cert.crt
   C:\Users\Brandon\Documents\YUBICO\yubico-private.key

   Run these commands to import the client certificate and private key (replacing values where appropriate for your setup):
   

   yubico-piv-tool -a import-certificate -s 9a -i C:\Users\Brandon\Documents\YUBICO\yubico-cert.crt
   yubico-piv-tool -a import-key -s 9a -i C:\Users\Brandon\Documents\YUBICO\yubico-private.key

   If everything goes well, you will see something like this:

   C:\Program Files\Yubico\Yubico PIV Tool\bin>yubico-piv-tool -a import-certificate -s 9a -i C:\Users\Brandon\Documents\YUBICO\yubico-cert.crt
   Successfully imported a new certificate.
   
   C:\Program Files\Yubico\Yubico PIV Tool\bin>yubico-piv-tool -a import-key -s 9a -i C:\Users\Brandon\Documents\YUBICO\yubico-private.key
   Successfully imported a new private key.

Using "YubiKey Manager"

1. Make sure that your hardware token (Yubikey) is connected to your PC.
2. Open the "YubiKey Manager" program from your PC and confirm that your hardware token is connected:
   
   
   
3. Go to Applications > PIV:
   
4. Click Configure Certificates:
   
5. Click Import under the Authentication tab:
   
6. Select the client certificate file ("yubico-cert.crt") and click Import. If everything goes well, you will see something like this:
   
7. Click Import on the Authentication tab.
8. Select the private key file ("yubico-private.key") and click Import. If everything goes well, you will see something like this:
   
   
   Note: You won't see any private key under the authentication tab, but if you see the "Private key was imported to slot 9a", then you're good to go.

Option 2: Importing the client certificate and private key as one single file with .p12 or .pfx extension

Using "YubiKey Manager"

1. Ensure that your hardware token (Yubikey) is connected to your PC.
2. Open the "YubiKey Manager" program from your PC and confirm that your hardware token is connected:
   
   
   
3. Go to "Applications > PIV":
   
4. Click on Configure Certificates:
   
5. Click Import on the Authentication tab:
   
6. Select the bundled file (.p12 or .pfx) and click Import. If everything goes well, you will see something like this:
   

Locate and copy the vendor module so the OpenVPN Connect v3 can recognize it

Find your operating system below and follow the steps.

Windows

1. Press Windows + R to launch the Windows Run prompt.
2. Enter sysdm.cpl and press Enter to launch the System Properties window:
   
3. ClickAdvanced to access the Environment Variables button:
   
4. Under System Variables, highlight Path and click Edit…:
   
5. Click New and add C:\Program Files\Yubico\Yubico PIV Tool\bin then click OK:
   
6. Go to C:\Program Files\Yubico\Yubico PIV Tool\bin and copy the file named libykcs11.dll:
   
   
7. Go to C:\Program Files\OpenVPN Connect and create a new folder named pkcs11_modules:
   
8. Open the new directory and paste the file named libykcs11.dll you copied in step 6.
   

Assign an external certificate to the profile

1. Shut down OpenVPN Connect. if it's running.
2. Launch OpenVPN Connect.
3. Import the connection profile, yubico-profile.ovpn.
4. Click or tap the Edit icon for the profile:
   
5. Under Certificate and Key, click or tap Assign
   :
6. Click or tap Hardware Tokens.
7. Select the hardware token from the list and click Authorize.
   
8. Enter a PIN for the desired hardware token and click OK.
   
9. After successful authorization, choose the certificate and key for connection with the profile and click Confirm.
   In our case, the client certificate has the VPN username (yubico-user), and the private key is "Private Key for PIV Authentication".
   
10. Save the profile configuration.
    
    

Connect with a profile and the hardware token

Now that you have a proper certificate and key assigned to the profile, let's connect using the profile and the hardware token (Yubikey).

1. Click or tap the profile toggle to connect.
   
2. Enter a PIN for the desired hardware token and click OK.
   
3. After a successful connection, OpenVPN Connect displays connection statistics: