--- title: 'Tutorial: Use PKCS#11 Hardware Tokens for VPN Connections (YubiKey)' canonical: https://openvpn.net/as-docs/tutorials/tutorial--pkcs-11-hardware-tokens/ product: Access Server Docs description: Use hardware tokens like YubiKey with PKCS#11 to authenticate VPN connections in OpenVPN Access Server. Learn how to import certificates and configure OpenVPN Connect for secure login. --- # Tutorial: Use PKCS#11 Hardware Tokens for VPN Connections (YubiKey) ## Overview This tutorial shows how to use hardware tokens, such as YubiKey, for certificate-based authentication in OpenVPN Access Server using PKCS#11. You'll learn how to: - Create a connection profile. - Move certificates and keys to a hardware token. - Configure OpenVPN Connect to use the token. - Connect securely using the hardware token. > **Note** > > PKCS#11 hardware token support requires OpenVPN Connect 3.3 or newer and is available on Windows and macOS. > **Important** > > OpenVPN Connect 3.5 supports loading ECC certificates when you use hardware tokens such as YubiKey. Use RSA-based certificates for other versions. Access Server 2.9 and newer supports multiple CAs per server. ## Prerequisites - Access Server installed. - OpenVPN Connect installed on [Windows](https://openvpn.net/connect-docs/connect-for-windows.md) or [macOS](https://openvpn.net/connect-docs/connect-for-macos.md). - A hardware token with PKCS#11 support (for example, YubiKey 5 NFC). - [Yubico PIV Tool](https://developers.yubico.com/yubico-piv-tool/Releases/) (CLI) installed. - [YubiKey Manager](https://www.yubico.com/support/download/yubikey-manager/) (CLI) installed. > **Note** > > This guide uses YubiKey as an example. If you use another hardware token, refer to the vendor's documentation for equivalent steps. ## Step 1: Create and prepare the connection profile > **Important** > > In these steps, replace `` with the target VPN username. 1. Connect to the Access Server console and get root privileges. 2. Run this command to create a new user-locked connection profile for your user: ``` sacli --prefer-tls-crypt-v2 --user GetUserlogin > yubico-profile.ovpn ``` Optional: Run this command to create a new auto-login connection profile for your user: ``` sacli --prefer-tls-crypt-v2 --user GetAutologin > yubico-profile.ovpn ``` 3. Extract the client certificate: ``` sed -n '//,/<\/cert>/p' yubico-profile.ovpn | sed '1d;$d' > yubico-cert.crt ``` 4. Extract the private key: ``` sed -n '//,/<\/key>/p' yubico-profile.ovpn | sed '1d;$d' > yubico-private.key ``` 5. Remove the client's certificate and private key from the connection profile: ``` sed -i '//,/<\/cert>/d' yubico-profile.ovpn sed -i '//,/<\/key>/d' yubico-profile.ovpn ``` 6. Create a PKCS #12 file containing the client certificate and private key: ``` openssl pkcs12 -export -inkey yubico-private.key -in yubico-cert.crt -out yubico.p12 -name "" ``` 7. When prompted (twice), enter a password for the P2 file. 8. Transfer the files to the client device via WinSCP or SCP: - `yubico-profile.ovpn` (connection profile) - `yubico-cert.crt` (client certificate) - `yubico-private.key` (private key) - `yubico.p12` (client P12 file) ## Step 2: Import the certificate into the hardware token You can use either a CLI tool, **Yubico PIV Tool**, or a UI tool, **YubiKey Manager**. You have two ways to import the certificate and key: - Import as **two separate files** (`.crt` and `.key`). - Import as a **single file** (`.p12` or `.pfx`). ### Option 1: Import certificate and key as separate files #### Using Yubico PIV Tool (CLI) 1. Ensure your hardware token (YubiKey) is connected to your PC. 2. Open Command Prompt and navigate to: ``` cd C:\Program Files\Yubico\Yubico PIV Tool\bin ``` 3. Run **yubico-piv-tool** commands to import the client certificate and private key. 4. Confirm your files are available, for example: ``` C:\Users\\Documents\YUBICO\yubico-cert.crt C:\Users\\Documents\YUBICO\yubico-private.key ``` 5. Import the client certificate and private key (replace values where appropriate for your setup): ``` yubico-piv-tool -a import-certificate -s 9a -i yubico-piv-tool -a import-key -s 9a -i ``` - If the process succeeds, you should see messages like: ``` C:\Program Files\Yubico\Yubico PIV Tool\bin>yubico-piv-tool -a import-certificate -s 9a -i C:\Users\\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\\Documents\YUBICO\yubico-private.key Successfully imported a new private key. ``` > **Important** > > Ensure you import the private key and certificate into the same slot on the token (for example, slot `9a`). #### Using YubiKey Manager (UI) 1. Ensure your hardware token (YubiKey) is connected to your PC. 2. Open **YubiKey Manager** and confirm that your hardware token is connected. 3. Go to **Applications → PIV**. 4. Click **Configure Certificates**. 5. Under the **Authentication** tab: - Click **Import** and select `yubico-cert.crt`. - Click **Import** again and select `yubico-private.key`. > **Note** > > You won't see the private key listed, but if you see a message like, "**Private key was imported into slog 9a**", the import was successful. ### Option 2: Import certificate and key as a single file (.p12 or .pfx) #### Using YubiKey Manager (UI) 1. Ensure your hardware token (YubiKey) is connected to your PC. 2. Open **YubiKey Manager** and confirm that your hardware token is connected. 3. Go to **Applications → PIV**. 4. Click **Configure Certificates**. 5. Under the **Authentication** tab: - Click **Import**. - Select the `.p12` file (for example, `yubico.p12`). ## Step 3: Configure the PKCS#11 module Follow these steps to ensure OpenVPN Connect can recognize the vendor module. ### 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. Click **Advanced** 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 `libykcs11.dll` file you copied in step 6. ### macOS 1. Locate the library: `/usr/local/lib/libykcs11.x.x.x.dylib` Example: **libykcs11.2.3.1.dylib**. Ensure it's a file, not a symlink. 2. Open Terminal and execute this command to create a symlink to the library file. ``` ln -s /usr/local/lib/libykcs11.x.x.x.dylib ~/.pkcs11_modules/libykcs11.dylib ``` > **Note** > > Use the version number (x.x.x) from step 1. - If the **.pkcs11\_modules** directory doesn't exist, an error is displayed. ``` ln: /Users/brandon/.pkcs11_modules/libykcs11.dylib: No such file or directory ``` If an error appears, create the directory: ``` mkdir ~/.pkcs11_modules ``` 3. Open Terminal and execute this command to create a symlink to the library file. ``` ln -s /usr/local/lib/libykcs11.2.3.1.dylib ~/.pkcs11_modules/libykcs11.dylib ``` 4. Verify the setup: ``` ls -al .pkcs11_modules ``` > **Note** > > In this guide, we use version 2.3.1 from the Yubico PIV Tool website. If you use a different version, verify your version in the `/usr/local/lib/` directory and adjust the file name accordingly (`libykcs11.x.x.x.dylib`). ## Step 4: Assign the hardware token to the connection profile 1. Close OpenVPN Connect if it's running. 2. Open OpenVPN Connect v3. 3. Import the connection profile, `yubico-profile.ovpn`. 4. Click **Menu → My Profiles**. 5. Click or tap the **Edit** icon for the profile. 6. Under **Certificate and Key**, click **Assign**. 7. Under **Hardware Tokens**, select the hardware token from the list and click **Authorize**. 8. Enter a PIN for the hardware token, then click **OK**. 9. After successful authorization, select the certificate and key for the connection profile, then click **Confirm**. **In our example, the client certificate has the username yubico-user, and the private key is Private Key for PIV Authentication.** 10. Save the connection profile configuration. ## Step 5: Connect with a connection profile and hardware token Now that you have a certificate and key assigned to the profile, you can connect using the connection profile and the hardware token (YubiKey). 1. Start the connection. 2. Enter your user credentials (if required). 3. Enter the hardware token PIN, then click **Enter**. - ✅ **Pass:** Connection succeeds and displays connection statistics. - ❌ **Fail:** Authentication fails → verify certificate import, module setup, and profile configuration > **Important** > > Keep the hardware token connected during the connection process. --- Prev: [Tutorial: Configure External PKI with Futurex CryptoHub for Access Server](https://openvpn.net/as-docs/tutorials/tutorial--epki-with-futurex-cryptohub.md) Next: [Encryption and Data Channel Security](https://openvpn.net/as-docs/tutorials/encryption-and-data-channel-security.md) Index: https://openvpn.net/as-docs/llms.txt