Tutorial: OpenVPN Connect Integration with Futurex CryptoHub
Overview
This tutorial shows how to store OpenVPN client certificates and private keys on a Futurex CryptoHub and use them with OpenVPN Connect through PKCS #11 integration.
By storing the private key on the CryptoHub, the key never resides in the OpenVPN profile or local file system, reducing the risk of credential theft and unauthorized VPN access.
Even if an attacker obtains a user's OpenVPN profile, they still need access to the Futurex CryptoHub configuration and the required PIN to authenticate successfully.
The goal of this integration is to provide hardware-backed protection for VPN client credentials and add an additional layer of security to VPN authentication.
Architecture overview
In this integration:
OpenVPN Connect uses a PKCS #11 module.
The PKCS #11 module communicates with the Futurex CryptoHub.
The client certificate and private key are stored on the CryptoHub.
OpenVPN Connect uses the CryptoHub-hosted key to authenticate to Access Server.
This tutorial consists of the following phases:
Deploy the OpenVPN Connect service in CryptoHub.
Deploy a client endpoint.
Install and validate the Futurex PKCS #11 module.
Create an RSA certificate authority in Access Server.
Generate a client profile and PKCS #12 package.
Import the certificate and key into CryptoHub.
Configure OpenVPN Connect to use the CryptoHub certificate.
Test the VPN connection.
Prerequisites
OpenVPN Connect requirements
Windows or macOS
OpenVPN Connect 3.3 or newer
Access Server requirements
Console access with root privileges
Admin Web UI access
CryptoHub requirements
Futurex CryptoHub 7.0.3.x or newer
Platform Master Key loaded
Network configuration completed
Administrator access
Network requirements
Connectivity from the OpenVPN Connect host to the CryptoHub
Outbound TCP 2001 allowed
CryptoHub reachable by FQDN or CIDR
CryptoHub exempt from TLS inspection or proxy filtering
Sign in to the CryptoHub under dual control using your administrator identities.
In the left navigation panel, select Services, and find the service called OpenVPN Connect.
Select Deploy.
Configure the following Service Setup settings:
Service Name: Leave as default (application name).
Service Category: Leave as default.
Select Next.
Configure the following Access Control settings:
Authorized Resources: Your role has access to this service by default.
Add Additional Resources: Optional.
Select Next.
Configure the following Service Info setting:
Authentication Mechanisms: Leave as default.
Select Deploy.
This endpoint is a device authorized to access the OpenVPN service you deployed in the previous step.
In the left navigation panel, select Home.
Under Deployed Services, locate and select OpenVPN Connect.
Select ENDPOINTS.
Under Manage Endpoints, select Add New.
In the Add Endpoint dialog:
Endpoint Identifier: Enter an identifier or leave it empty for auto-generation.
CryptoHub Hostname: Leave as default.
Platform: Select the Platform for the endpoint.
Select Add Endpoint.
The browser prompts you to download a ZIP file containing the Futurex PKCS #11 module, TLS certificates, and a preconfigured configuration file to connect to your CryptoHub instance.
Save this ZIP file. You'll use it in the next step to install and configure the Futurex PKCS #11 module.
Use the endpoint package ZIP file downloaded in the previous step.
Choose the platform where OpenVPN Connect is installed:
Windows
macOS
Step 1: Extract the CryptoHub package
Locate the endpoint package ZIP file downloaded in Step 2.
Extract the ZIP file to a temporary directory.
Verify that the package contains the following files:
File
Description
PKCS11Manager.exeTests connectivity to CryptoHub and performs basic PKCS #11 operations, such as signing in and generating random data.
ca-chain.pemCA certificate bundle.
client-cert.pemClient TLS certificate.
client.p12Encrypted PKCS #12 bundle containing the client certificate, private key, and CA chain.
configTest.exeValidates the PKCS #11 configuration and CryptoHub connectivity.
fxpkcs11.cfgFuturex PKCS #11 configuration file.
fxpkcs11.dllFuturex PKCS #11 library.
CryptoHub <number>.cerAuto-generated CryptoHub CA certificate.
Futurex Test Root CA (ECC.cerorFuturex Test Root SSL CA.cerFuturex test root certificate.
Step 2: Install the PKCS #11 files
Create a Futurex directory as an administrator:
C:\Program Files\Futurex\fxpkcs11.Copy all extracted files into:
C:\Program Files\Futurex\fxpkcs11.Verify that
fxpkcs11.cfgexists in the directory.
Optional: Use a custom configuration location
If you want to store the configuration file in a different location:
Open PowerShell as Administrator.
Set the environment variable for the current PowerShell session:
$env:FXPKCS11_CFG = "C:\custom\path\to\fxpkcs11.cfg"Or, create a permanent machine-wide setting:
[System.Environment]::SetEnvironmentVariable("FXPKCS11_CFG", "C:\custom\path\to\fxpkcs11.cfg", "Machine")If you use a custom configuration location, ensure all TLS files referenced in the config are in the same directory.
Configure certificate locations
By default, the FXPKCS11 module expects the certificate files referenced in the configuration file to be located in the same directory. This applies regardless of the configuration file location.
If you store your certificate files elsewhere, you can update the certificate paths in the configuration file:
Open
fxpkcs11.cfgin a text editor.Review the following settings:
PROD-TLS-KEY: Path to theclient.p12PKCS#12 file.PROD-TLS-CA: Path to theCryptoHub <number>.cerfile.PROD-TLS-CA: Path to theFuturex test Root CA (ECC).cerorFuturex Test Root SSL CA.cerfile (depending on your CryptoHub connection type).
Verify the paths point to the correct certificate files.
If you moved the certificate files to another location, update the paths accordingly.
Save the configuration file.
Step 3: Secure the PKCS #12 password
To improve security, store the PKCS #12 password as a machine-level environment variable instead of keeping it in plaintext (the default setting).
Open PowerShell as an Administrator.
Extract the password from
fxpkcs11.cfg:$pass = (Get-Content "C:\Program Files\Futurex\fxpkcs11\fxpkcs11.cfg" | Select-String "PROD-TLS-KEY-PASS").Line -replace '.*<PROD-TLS-KEY-PASS>\s*(.*?)\s*<\/PROD-TLS-KEY-PASS>.*', '$1'Store the password as a machine-level environment variable:
[System.Environment]::SetEnvironmentVariable("PKCS11_P12", $pass, "Machine")Close PowerShell and open a new PowerShell session as Administrator.
Verify the variable was created successfully:
[System.Environment]::GetEnvironmentVariable("PKCS11_P12", "Machine")Update
fxpkcs11.cfgto reference the environment variable:$config = Get-Content "C:\Program Files\Futurex\fxpkcs11\fxpkcs11.cfg" -Raw $config = $config -replace '<PROD-TLS-KEY-PASS>.*?</PROD-TLS-KEY-PASS>', '<PROD-TLS-KEY-PASS> env:PKCS11_P12 </PROD-TLS-KEY-PASS>' Set-Content "C:\Program Files\Futurex\fxpkcs11\fxpkcs11.cfg" $configVerify the update was applied successfully:
Select-String -Path "C:\Program Files\Futurex\fxpkcs11\fxpkcs11.cfg" -Pattern "<PROD-TLS-KEY-PASS> env:PKCS11_P12 </PROD-TLS-KEY-PASS>"
Step 4: Remove plaintext credentials
The <CRYPTO-OPR-PASS> entry contains the plaintext password used to authenticate the crypto user. Comment out or remove this entry from the configuration file:
Comment out (prepend a
#) or delete this entry infxpkcs11.cfg:$configPath = "C:\Program Files\Futurex\fxpkcs11\fxpkcs11.cfg" (Get-Content $configPath) -replace '^\s*(<CRYPTO-OPR-PASS>)', '# $1' | Set-Content $configPath
Step 5: Register the PKCS #11 module
Open PowerShell as Administrator.
Add the Futurex directory to the system PATH:
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "Machine") + ";C:\Program Files\Futurex\fxpkcs11","Machine")Create the OpenVPN Connect PKCS #11 module directory:
New-Item -Path "C:\Program Files\OpenVPN Connect\pkcs11_modules" -ItemType DirectoryCopy the Futurex PKCS #11 library:
Copy-Item "C:\Program Files\Futurex\fxpkcs11\fxpkcs11.dll" -Destination "C:\Program Files\OpenVPN Connect\pkcs11_modules\fxpkcs11.dll"Continue to validation.
Step 6: Validate the installation with configTest
Open PowerShell as Administrator.
Run the validation tool:
& "C:\Program Files\Futurex\fxpkcs11\configTest.exe"Confirm that the connection test succeeds.
Step 7: Validate the installation with PKCS11Manager
Open PowerShell as Administrator.
Run PKCS11Manager:
& "C:\Program Files\Futurex\fxpkcs11\PKCS11Manager.exe"Confirm that the connection test succeeds.
Perform a simple operation, such as generating random data (option 8).
Step 1: Extract the CryptoHub package
On the macOS hosting OpenVPN Connect, open a terminal window.
Create the fxpkcs11 directory:
sudo mkdir -p /usr/local/lib/fxpkcs11Extract the ZIP file:
sudo unzip /path/to/Identifier-OpenVPN.zip -d /usr/local/lib/fxpkcs11Update the path to the actual filepath and filename of your CryptoHub package.
Verify that the package contains the following files:
File
Description
PKCS11ManagerTests connectivity to CryptoHub and performs basic PKCS #11 operations, such as signing in and generating random data.
ca-chain.pemCA certificate bundle.
client-cert.pemClient TLS certificate.
client.p12Encrypted PKCS #12 bundle containing the client certificate, private key, and CA chain.
configTestValidates the PKCS #11 configuration and CryptoHub connectivity.
fxpkcs11.cfgFuturex PKCS #11 configuration file.
libfxpkcs11.dylibFuturex PKCS #11 library.
CryptoHub <number>.cerAuto-generated CryptoHub CA certificate.
Futurex Test Root CA (ECC.cerorFuturex Test Root SSL CA.cerFuturex test root certificate.
Remove the macOS quarantine attribute from the extracted files:
sudo xattr -dr com.apple.quarantine /usr/local/lib/fxpkcs11
Step 2: Install the PKCS #11 files
Navigate to the FXPKCS11 directory:
cd /usr/local/lib/fxpkcs11Move the following files to
/etc(default, expected location):CryptoHub <number>.cerFuturex Test Root CA (ECC)orFuturex Test Root SSL CA.cerclient.p12fxpkcs11.cfg
sudo mv 'CryptoHub '*.cer 'Futurex Test Root '*.cer client.p12 fxpkcs11.cfg /etc/
Optional: Use a custom configuration location
If you want to store the configuration files in a different location:
Open a terminal window.
Define the environment variable for the current terminal session:
export FXPKCS11_CFG=/path/to/your/fxpkcs11.cfg
Configure certificate locations
By default, the FXPKCS11 module expects the certificate files referenced in the configuration file to be located in the same directory. This applies regardless of the configuration file location.
If you store your certificate files elsewhere, you can update the certificate paths in the configuration file:
Open
fxpkcs11.cfgin a text editor.Review the following settings:
PROD-TLS-KEY: Path to theclient.p12PKCS#12 file.PROD-TLS-CA: Path to theCryptoHub <number>.cerfile.PROD-TLS-CA: Path to theFuturex test Root CA (ECC).cerorFuturex Test Root SSL CA.cerfile (depending on your CryptoHub connection type).
Verify the paths point to the correct certificate files.
If you moved the certificate files to another location, update the paths accordingly.
Save the configuration file.
Step 3: Secure the PKCS #12 password
To improve security, store the PKCS #12 password separately from within the configuration file in plaintext (the default setting). On macOS, you can use either:
Session environment variable: Temporary and only available for the current shell session.
macOS Keychain: Persistent across sessions and available after the shell loads it into the environment.
Option 1: Use a session environment variable
Use this option for temporary testing.
Extract the password from
fxpkcs11.cfgand store it as a session environment variable:export PKCS11_P12=$(grep PROD-TLS-KEY-PASS /etc/fxpkcs11.cfg | sed 's/.*<PROD-TLS-KEY-PASS>\s*\(.*\)\s*<\/PROD-TLS-KEY-PASS>.*/\1/')Confirm the environment variable was set correctly:
echo $PKCS11_P12Update the
<PROD-TLS-KEY-PASS>entry infxpkcs11.cfgto reference the environment variable:sudo sed -i '' 's|<PROD-TLS-KEY-PASS>.*</PROD-TLS-KEY-PASS>|<PROD-TLS-KEY-PASS> env:PKCS11_P12 </PROD-TLS-KEY-PASS>|' /etc/fxpkcs11.cfgConfirm the change was applied:
grep "PROD-TLS-KEY-PASS" /etc/fxpkcs11.cfgThe configuration file should now reference
env:PKCS11_P12instead of storing the PKCS #12 password directly.
Option 2: Use macOS Keychain
Use this option for a persistent setup.
Extract the password from
fxpkcs11.cfgand store it in the macOS Keychain:security add-generic-password -a "pkcs12" -s "fxpkcs11" -w "$(grep PROD-TLS-KEY-PASS /etc/fxpkcs11.cfg | sed 's/.*<PROD-TLS-KEY-PASS>\s*\(.*\)\s*<\/PROD-TLS-KEY-PASS>.*/\1/')"Add a command to
~/.zshrcto load the password from Keychain automatically:echo 'export PKCS11_P12=$(security find-generic-password -a "pkcs12" -s "fxpkcs11" -w)' >> ~/.zshrc source ~/.zshrcConfirm the environment variable was set correctly:
echo $PKCS11_P12Update the
<PROD-TLS-KEY-PASS>entry infxpkcs11.cfgto reference the environment variable:sudo sed -i '' 's|<PROD-TLS-KEY-PASS>.*</PROD-TLS-KEY-PASS>|<PROD-TLS-KEY-PASS> env:PKCS11_P12 </PROD-TLS-KEY-PASS>|' /etc/fxpkcs11.cfgConfirm the change was applied:
grep "PROD-TLS-KEY-PASS" /etc/fxpkcs11.cfg
Step 4: Remove plaintext credentials
The <CRYPTO-OPR-PASS> entry contains the plaintext password used to authenticate the crypto user. Comment out or remove this entry from the configuration file:
Comment out the
<CRYPTO-OPR-PASS>entry:sudo sed -i '' '/<CRYPTO-OPR-PASS>.*<\/CRYPTO-OPR-PASS>/s/^/#/' /etc/fxpkcs11.cfgVerify the line was commented out successfully:
grep "CRYPTO-OPR-PASS" /etc/fxpkcs11.cfgConfirm the output begins with
#:#<CRYPTO-OPR-PASS>password</CRYPTO-OPR-PASS>
Step 5: Register the PKCS #11 module
OpenVPN Connect needs to find the Futurex PKCS #11 library before it can use the CryptoHub certificate.
Locate the library:
/usr/local/lib/fxpkcs11/libfxpkcs11.dylibOpen the terminal.
Create the OpenVPN Connect PKCS #11 module directory if it doesn't already exist:
mkdir -p ~/.pkcs11_modulesCreate a symlink to the library:
ln -s /usr/local/lib/fxpkcs11/libfxpkcs11.dylib ~/.pkcs11_modules/libfxpkcs11.dylibConfirm the symlink was created:
ls -al ~/.pkcs11_modulesExample output:
lrwxr-xr-x 1 username staff 45 Jan 1 12:00 libfxpkcs11.dylib -> /usr/local/lib/fxpkcs11/libfxpkcs11.dylib
Step 6: Validate the installation with configTest
Run the configuration test tool:
/usr/local/lib/fxpkcs11/configTestConfirm the connection test succeeds.
If you see this permission error:
-bash: /usr/local/lib/fxpkcs11/configTest: Permission deniedmake the file executable:
sudo chmod +x /usr/local/lib/fxpkcs11/configTestRun the test again:
/usr/local/lib/fxpkcs11/configTest
Step 7: Validate the installation with PKCS11Manager
Run
PKCS11Manager:/usr/local/lib/fxpkcs11/PKCS11ManagerConfirm the connection test succeeds.
If you see this permission error:
-bash: /usr/local/lib/fxpkcs11/PKCS11Manager: Permission deniedmake the file executable:
sudo chmod +x /usr/local/lib/fxpkcs11/PKCS11ManagerRun
PKCS11Manageragain:/usr/local/lib/fxpkcs11/PKCS11ManagerPerform a simple operation, such as generating random data (option 8).
Step 8: Troubleshoot validation issues
Use this section if configTest or PKCS11Manager fails.
Check the FXPKCS11 log file:
Default location: same directory as
fxpkcs11.cfg.To customize, modify the
LOG-FILEsetting infxpkcs11.cfg.
Verify the following:
The PKCS #11 PIN is correct.
fxpkcs11.cfgis in the correct location.PKCS11_P12has the correct value.The referenced TLS files are in the expected location:
client.p12CryptoHub <number>.cerFuturex Test Root CA (ECC).cerfor ECC connections, orFuturex Test Root SSL CA.cerfor RSA connections
If you customized the certificate paths in
fxpkcs11.cfg, verify each file exists in its configured location.If macOS blocks
libfxpkcs11.dylib,configTest, orPKCS11Manager, remove the quarantine attribute again:sudo xattr -dr com.apple.quarantine /usr/local/lib/fxpkcs11Restart OpenVPN Connect and test again.
Futurex PKCS #11 integration requires an RSA certificate authority (CA). In this step, you'll create a new RSA 2048-bit or 4096-bit CA in Access Server.
Choose one of the following methods:
Admin Web UI
Command-line interface (CLI)
Create an RSA CA from the Admin Web UI
Sign in to the Access Server Admin Web UI.
Select Certificate Management → VPN Server Certificate Authority.
Select New CA Certificate.
Configure the certificate authority:
Common name: Enter a name for the CA.
Signing algorithm: Under RSA (best compatibility), select either:
rsa2048rsa4096
Select Add New CA and Restart.
Access Server creates the new RSA certificate authority and restarts its services.
Create an RSA CA from the command line
Connect to the console and get root privileges.
Create the certificate authority:
/usr/local/openvpn_as/scripts/sa --key_algorithm=rsa --keysize=2048 --newca_cn=Futurex_CA AddCAGenerationParameter
Value
key_algorithmrsakeysize2048or4096newca_cnEnter the name for the CA Certificate (replace
Futurex_CAwith your desired name)Restart Access Server:
systemctl restart openvpnasVerify the new certificate authority:
sacli showCAsThe newly created RSA certificate authority appears in the command output.
In this step, you'll create an OpenVPN connection profile, extract the certificate components, and package the client certificate and private key into a PKCS #12 file for import into the CryptoHub.
Create the client profile
Connect to your Access Server console and get root privileges.
Generate a user-locked profile:
sacli --prefer-tls-crypt-v2 --user brandonqa GetUserlogin > brandonqa_futurex.ovpnReplace
brandonqawith your VPN username andbrandonqa_futurex.ovpnwith your preferred connection profile name.
Result: A new OpenVPN connection profile is created.
Extract the certificate components
Extract the CA certificate:
sed -n '/<ca>/,/<\/ca>/p' brandonqa_futurex.ovpn | sed '1d;$d' > ca.crtExtract the client certificate:
sed -n '/<cert>/,/<\/cert>/p' brandonqa_futurex.ovpn | sed '1d;$d' > client.crtExtract the client private key:
sed -n '/<key>/,/<\/key>/p' brandonqa_futurex.ovpn | sed '1d;$d' > client.keyRemove the client's certificate and private key from the connection profile:
sed -i '/<cert>/,/<\/cert>/d' brandonqa_futurex.ovpn sed -i '/<key>/,/<\/key>/d' brandonqa_futurex.ovpn
Result: The certificate authority certificate, client certificate, and client private key are extracted into separate files.
Create the PKCS #12 package
Create a PKCS #12 package containing the client certificate, private key, and CA certificate.
openssl pkcs12 -export -inkey client.key -in client.crt -certfile ca.crt -out futurex.p12 -name "brandonqa"When prompted, create an export password.
Record the password securely.
Result: A PKCS #12 package (futurex.p12) is created and ready for import into the CryptoHub.
In this step, you'll import the client certificate, private key, and CA certificate into a CryptoHub X.509 Certificate Container.
Create an approval group
Sign in to the CryptoHub using your administrator identities.
Navigate to PKI and CA → PKI Signing Approvals.
Select Add Approval Group.
Enter a name for the approval group, then select OK.
Right-click the new approval group and select Permission.
From the drop-down list, select Service - OpenVPN.
Select Add.
Grant the Use permission.
Select Save.
Result: An approval group is created and assigned to the OpenVPN service.
Create an X.509 Certificate Container
Navigate to PKI and CA → Certificate Management.
Select Add CA.
Configure the container:
Name: OpenVPN (or another name of your choice)
Host: None
Type: X.509
Owner Group: Select the OpenVPN service created above.
Select OK.
Result: An X.509 Certificate Container is created.
Allow importing certificates using passwords
Navigate to Classic Tools → Administration → Configuration Tasks → Options.
On the Main tab of the Options menu:
Select the Allow import of certificates using passwords checkbox.
Select Save.
Result: CryptoHub now allows importing certificates using passwords.
Import the PKCS #12 package
Navigate to PKI and CA → Certificate Management.
Right-click the X.509 Certificate Container.
Select: Import → PKCS#12.
Browse to and select the
futurex.p12file.Select Next.
Enter the password for the PKCS #12 and select Next.
Select Finish.
Result: The client certificate, private key, and certificate chain are imported into the Certificate Container.
Create an issuance policy
The Futurex PKCS #11 library uses the issuance policy to locate the client certificate stored on the CryptoHub.
Navigate to PKI and CA → Certificate Management.
Right-click the client certificate beneath the CA certificate.
Select: Issuance Policy → Add.
On the Basic Info tab:
Set Approvals to
0.
On the X.509 tab:
Select Default approval group.
Select the approval group created earlier.
On the Object Signing tab:
Enable Allow object signing.
Select OK.
Result: The client certificate is assigned an issuance policy.
Allow anonymous signing
Navigate to PKI and CA → Certificate Management.
Right-click the client certificate.
Select Change Security Usage.
Select: Anonymous Signing.
Select OK.
Result: The client certificate can now be accessed by the Futurex PKCS #11 library.
Assign the CryptoHub certificate to the profile
Close OpenVPN Connect if it's running.
Launch OpenVPN Connect v3.
Import the profile created in Step 5.
Navigate to Menu → My Profiles.
Select the edit icon next to the imported profile.
Under Certificates, select Select.
Under Hardware Tokens, select the CryptoHub device. The name appears similar to
HSM 1830884596.Select Authorize.
Enter the PIN configured in the Futurex PKCS #11 configuration.
Select Enter.
Select the imported client certificate and private key.
Select Select.
Select Save Changes.
Result: The OpenVPN profile is configured to use the certificate and private key stored in CryptoHub.
Test the VPN connection
Select Connect for the connection profile.
Enter the VPN user password.
Enter the CryptoHub PIN.
Select Enter.
Result: The VPN connection succeeds and OpenVPN Connect displays connection statistics.