Skip to main content
These steps are typically performed by the CryptoHub Admin on the device that will be hosting the OpenVPN Connect v3 application. See Underlying Responsibility Roles for more information.

​
Windows

Perform the following steps to install and configure FxPKCS11 on your OpenVPN Connect Windows host.

​
Step 1: Extract the CryptoHub package and create the FxPKCS11 directory

1
On the Windows hosting OpenVPN Connect, open PowerShell as Administrator.
2
Extract Identifier-OpenVPN.zip into C:\Program Files\Futurex\fxpkcs11. If the fxpkcs11 folder doesn’t exist, it will be created automatically
PowerShell
Expand-Archive -Path "C:\path\to\Identifier-OpenVPN.zip" -DestinationPath "C:\Program Files\Futurex\fxpkcs11" -Force
Update -Path to the actual filepath, the filename of your CryptoHub package, and -DestinationPath to your preferred extraction location.The -Force flag creates the destination directory if it does not already exist and overwrites any existing files if it does.
The endpoint zip file downloaded from your browser contains the following files:
FilenameDescription
PKCS11Manager.exeProgram to test the connection to the CryptoHub and perform basic functions through the FXPKCS11 module, such as logging in and generating random data.
ca-chain.pemCA certificate bundle
client-cert.pemClient TLS certificate
client.p12Full Client PKI in encrypted PKCS #12 format (contains the CA chain, client certificate, and client private key)
configTest.exeProgram to test the configuration and connection to the CryptoHub
fxpkcs11.cfgConfiguration file for the Futurex PKCS #11 library
fxpkcs11.dllThe Futurex PKCS #11 library file.
CryptoHub <number>.cerAuto-generated self-signed CA certificate used to issue client endpoint TLS certs (number is random)
Futurex Test Root CA (ECC).cer or Futurex Test Root SSL CA.cerFuturex Test Root CA for embedded Futurex Test TLS certs (ECC or RSA, based on the algorithm configured for the connection pair)

​
Optional: Use a custom configuration location

By default, fxpkcs11.dll looks for fxpkcs11.cfg in C:\Program Files\Futurex\fxpkcs11. If you have moved fxpkcs11.cfg to a custom location, set the FXPKCS11_CFG environment variable to point to it. For the current PowerShell session only:
PowerShell
$env:FXPKCS11_CFG = "C:\custom\path\to\fxpkcs11.cfg"
For a permanent system-wide setting that persists across all sessions:
PowerShell
[System.Environment]::SetEnvironmentVariable("FXPKCS11_CFG", "C:\custom\path\to\fxpkcs11.cfg", "Machine")
If you choose the permanent option, you will need to restart your PowerShell session for the changes to take effect.

​
Optional: Use custom certificate paths

By default, the FxPKCS11 module expects certificate files to be in the same directory as the fxpkcs11.cfg file (whether at the default C:\Program Files\Futurex\fxpkcs11 location or your custom location via FXPKCS11_CFG). You can customize the paths to your certificate files directly in the fxpkcs11.cfg file by modifying the following settings:
  • PROD-TLS-KEY: Path to the client.p12 PKCS#12 file
  • PROD-TLS-CA: Path to the CryptoHub 1234567890.cer file
  • PROD-TLS-CA: Path to the Futurex Test Root CA (ECC).cer or Futurex Test Root SSL CA.cer file (depending on your CryptoHub connection type)
Make sure to enter the path without quotes, so an example path would be C:\ProgramData\fxpkcs11\certs\CryptoHub 1234567890.cer instead of "C:\ProgramData\fxpkcs11\certs\CryptoHub 1234567890.cer"

​
Step 2: Securing the PKCS #12 password

By default, the PKCS #12 password resides in plaintext inside fxpkcs11.cfg. To improve security, the recommended approach is to extract the password and store it separately, reducing the risk of accidental exposure. On Windows, the recommended approach is to store the password as a system environment variable at the Machine scope, which persists across all sessions and is available to all shells and services without needing to be re-set.
Update the path to fxpkcs11.cfg in the commands below if you have changed it from the default location.
1
Extract the password from fxpkcs11.cfg:
PowerShell
$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'
2
Store it as a permanent system environment variable at the Machine scope
PowerShell
[System.Environment]::SetEnvironmentVariable("PKCS11_P12", $pass, "Machine")
3
Close the current PowerShell session and open a new one with administrator privileges. Confirm the environment variable was set correctly:
PowerShell
[System.Environment]::GetEnvironmentVariable("PKCS11_P12", "Machine")
4
Update the <PROD-TLS-KEY-PASS> entry in fxpkcs11.cfg to reference the environment variable:
PowerShell
$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" $config
5
Confirm the change was applied correctly in fxpkcs11.cfg:
PowerShell
Select-String -Path "C:\Program Files\Futurex\fxpkcs11\fxpkcs11.cfg" -Pattern "<PROD-TLS-KEY-PASS> env:PKCS11_P12 </PROD-TLS-KEY-PASS>"
It should have env:PKCS11_P12 in the line now instead of the plaintext password.

​
Step 3: Comment out or remove the plaintext password in fxpkcs11.cfg

The <CRYPTO-OPR-PASS> entry in fxpkcs11.cfg contains the plaintext password used to authenticate the crypto user. Since we’re defining the password in the OpenVPN Connect application (required for this integration), comment out this line by adding a # at the beginning, or delete the line entirely from fxpkcs11.cfg. To comment out the line:
PowerShell
$configPath = "C:\Program Files\Futurex\fxpkcs11\fxpkcs11.cfg"
(Get-Content $configPath) -replace '^\s*(<CRYPTO-OPR-PASS>)', '# $1' | Set-Content $configPath
If you remove the <CRYPTO-OPR-PASS> line, store the password in a secure location of your choice for future reference.

​
Step 4: Create the pkcs11_modules directory and copy the Futurex PKCS #11 module for OpenVPN Connect to recognize it

1
Open PowerShell terminal as an Administrator.
2
Add fxpkcs11 to the system PATH:
PowerShell
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "Machine") + ";C:\Program Files\Futurex\fxpkcs11","Machine")
3
Create the pkcs11_modules in OpenVPN Connect folder:
PowerShell
New-Item -Path "C:\Program Files\OpenVPN Connect\pkcs11_modules" -ItemType Directory
4
Copy the fxpkcs11.dll to the newly created directory:
PowerShell
Copy-Item "C:\Program Files\Futurex\fxpkcs11\fxpkcs11.dll" -Destination "C:\Program Files\OpenVPN Connect\pkcs11_modules\fxpkcs11.dll"
1
Run the configuration test tool:
PowerShell
 & 'C:\Program Files\Futurex\fxpkcs11\configTest.exe'
2
Confirm the connection test succeeds.
If you see the message Windows protected your PC, click on More info, and click on Run anyway to allow the test to run.
If you encounter issues during validation, check the Troubleshoot validation issues steps at the end of this guide.

​
macOS

Perform the following steps to install and configure FxPKCS11 on your OpenVPN Connect macOS host.

​
Step 1: Create the FxPKCS11 directory and extract the CryptoHub package

1
On the macOS hosting OpenVPN Connect, open a terminal window.
2
Create the following directory:
zsh
sudo mkdir -p /usr/local/lib/fxpkcs11
-p flag creates parent directories as needed and does not throw an error if the directory already exists.
3
Extract the ZIP file.
zsh
sudo unzip /path/to/Identifier-OpenVPN.zip -d /usr/local/lib/fxpkcs11
Update the path to the actual filepath and filename of your CryptoHub package.
4
The endpoint zip file downloaded from your browser contains the following files:
FilenameDescription
PKCS11ManagerProgram to test the connection to the CryptoHub and perform basic functions through the FXPKCS11 module, such as logging in and generating random data.
ca-chain.pemCA certificate bundle
client-cert.pemClient TLS certificate
client.p12Full Client PKI in encrypted PKCS #12 format (contains the CA chain, client certificate, and client private key)
configTestProgram to test the configuration and connection to the CryptoHub
fxpkcs11.cfgConfiguration file for the Futurex PKCS #11 library
libfxpkcs11.dylibThe Futurex PKCS #11 library file.
CryptoHub <number>.cerAuto-generated self-signed CA certificate used to issue client endpoint TLS certs (number is random)
Futurex Test Root CA (ECC).cer or Futurex Test Root SSL CA.cerFuturex Test Root CA for embedded Futurex Test TLS certs (ECC or RSA, based on the algorithm configured for the connection pair)
5
Remove the macOS quarantine attribute from the extracted files:
zsh
sudo xattr -dr com.apple.quarantine /usr/local/lib/fxpkcs11
When files are downloaded through a browser, macOS attaches a com.apple.quarantine extended attribute that triggers Gatekeeper to block them on first use. This command strips the attribute from the PKCS #11 library and helper binaries in one pass so that OpenVPN Connect can load the module and configTest can run without being blocked by macOS Privacy & Security warnings. Skipping this step will require you to manually approve each binary in [ System Settings ] > [ Privacy & Security ] and restart OpenVPN Connect before the integration will work.
6
Navigate to the /usr/local/lib/fxpkcs11 directory:
zsh
cd /usr/local/lib/fxpkcs11
7
Move the following files to /etc (the default expected location):
  • CryptoHub 1234567890.cer
  • Futurex Test Root CA (ECC).cer or Futurex Test Root SSL CA.cer
  • client.p12
  • fxpkcs11.cfg
zsh
sudo mv 'CryptoHub '*.cer 'Futurex Test Root '*.cer client.p12 fxpkcs11.cfg /etc/

​
Optional: Use a custom configuration location

If you prefer to store the configuration file elsewhere, define the environment variable for the current terminal session:
zsh
export FXPKCS11_CFG=/path/to/your/fxpkcs11.cfg

​
Optional: Use custom certificate paths

By default, the FxPKCS11 module expects certificate files to be in the same directory as the fxpkcs11.cfg file (whether at the default /etc/ location or your custom location via FXPKCS11_CFG). You can customize the paths to your certificate files directly in the fxpkcs11.cfg file by modifying the following settings:
  • PROD-TLS-KEY: Path to the client.p12 PKCS#12 file
  • PROD-TLS-CA: Path to the CryptoHub 1234567890.cer file
  • PROD-TLS-CA: Path to the Futurex Test Root CA (ECC).cer or Futurex Test Root SSL CA.cer file (depending on your CryptoHub connection type)

​
Step 2: Configure secrets (PKCS #12 password)

By default, the PKCS #12 password resides in plaintext inside fxpkcs11.cfg. To improve security, the recommended approach is to extract the password and store it separately, reducing the risk of accidental exposure. On macOS, there are two ways to achieve this:
  • Session environment variable: Temporary, only available for the current shell session. Must be re-set each time a new shell is opened.
  • macOS Keychain: Permanent, persists across all sessions and is available to all shells and services without needing to be re-set.
Update the path to fxpkcs11.cfg in the commands below if you have changed it from the default location.
1
Extract the password from fxpkcs11.cfg and store it as a session environment variable:
zsh
export PKCS11_P12=$(grep PROD-TLS-KEY-PASS /etc/fxpkcs11.cfg | sed 's/.*<PROD-TLS-KEY-PASS>\s*\(.*\)\s*<\/PROD-TLS-KEY-PASS>.*/\1/')
2
Confirm the environment variable was set correctly:
zsh
echo $PKCS11_P12
3
Update the <PROD-TLS-KEY-PASS> entry in fxpkcs11.cfg to point to the environment variable:
zsh
sed -i '' 's|<PROD-TLS-KEY-PASS>.*</PROD-TLS-KEY-PASS>|<PROD-TLS-KEY-PASS> env:PKCS11_P12 </PROD-TLS-KEY-PASS>|' /etc/fxpkcs11.cfg
4
Confirm the change was applied correctly in fxpkcs11.cfg:
zsh
grep "PROD-TLS-KEY-PASS" /etc/fxpkcs11.cfg

​
Step 3: Comment out or remove the plaintext password in fxpkcs11.cfg

The <CRYPTO-OPR-PASS> entry in fxpkcs11.cfg contains the plaintext password used to authenticate the crypto user. Since we’re defining the password in the OpenVPN Connect application (required for this integration), comment out this line by adding a # at the beginning, or delete the line entirely from fxpkcs11.cfg.
If you remove the <CRYPTO-OPR-PASS> line, store the password in a secure location of your choice for future reference.
1
Locate the library at /usr/local/lib/fxpkcs11/libfxpkcs11.dylib.
2
Open Terminal and create the .pkcs11_modules directory if it does not already exist:
zsh
mkdir -p ~/.pkcs11_modules
3
Create a symlink to the library file:
zsh
ln -s /usr/local/lib/fxpkcs11/libfxpkcs11.dylib ~/.pkcs11_modules/libfxpkcs11.dylib
4
Confirm the symlink was created successfully:
zsh
ls -al ~/.pkcs11_modules
You should see output similar to the following:
Output
lrwxr-xr-x  1 username  staff  45 Jan 1 12:00 libfxpkcs11.dylib -> /usr/local/lib/fxpkcs11/libfxpkcs11.dylib
1
Run the configuration test tool:
zsh
/usr/local/lib/fxpkcs11/configTest
2
Confirm the connection test succeeds.If you see:
zsh
-bash: /usr/local/lib/fxpkcs11/configTest: Permission denied
Make the file executable:
zsh
chmod +x /usr/local/lib/fxpkcs11/configTest
Then, run the test again.

​
Troubleshoot validation issues

If configTest fails:
1
Check the FxPKCS11 log file:
  • Default location: same directory as fxpkcs11.cfg.
  • To customize, modify the LOG-FILE setting in fxpkcs11.cfg.
2
Ensure that:
  • The PKCS #11 PIN is correct.
  • fxpkcs11.cfg resides at /etc/fxpkcs11.cfg (or confirm FXPKCS11_CFG points to the correct location).
  • By default, all TLS files listed below must reside in the same directory as fxpkcs11.cfg. If you customized the file paths in fxpkcs11.cfg, place each file in its configured location instead:
    • client.p12
    • CryptoHub 1234567890.cer
    • Futurex Test Root CA (ECC).cer (for ECC connections) or Futurex Test Root SSL CA.cer (for RSA connections)
  • PKCS11_P12 has the correct value.
3
If you see a macOS dialog stating that libfxpkcs11.dylib or configTest was blocked or could not be verified, the quarantine attribute was not removed during Step 1. Re-run:
zsh
sudo xattr -dr com.apple.quarantine /usr/local/lib/fxpkcs11
Then restart OpenVPN Connect and try again.