Tutorial: Configure External PKI with Futurex CryptoHub for Access Server⁠

Install FXPKCS11 on the Access Server host⁠

Perform the following steps to install and configure FXPKCS11 on your Access Server Linux host.

export FXPKCS11_CFG=/path/to/your/fxpkcs11.cfg

Install on Ubuntu / Debian⁠

1. Install the required packages:

   sudo apt update && sudo apt upgrade -y
   sudo apt install -y git build-essential meson libssl-dev pkg-config python3-asn1crypto opensc libnss3 libnss3-dev libnss3-tools p11-kit libp11-kit-dev

2. Create a source directory and change into it:

   mkdir -p ~/src
   cd ~/src

3. Clone the pkcs11-provider repository:

   git clone https://github.com/latchset/pkcs11-provider.git
   cd pkcs11-provider

4. Build the provider:

   meson setup builddir
   meson compile -C builddir

5. Install the provider:

   sudo meson install -C builddir

Install on RHEL⁠

1. Enable EPEL and CodeReady Builder (CRB):

   • RHEL 9:

     subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms
     dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm

   • Alma and Rocky Linux 9:

     dnf config-manager --set-enabled crb
     dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm

2. Refresh metadata:

   sudo dnf makecache

3. Install the prerequisites:

   sudo dnf check-update
   sudo dnf install -y git gcc gcc-c++ meson ninja-build pkgconfig openssl-devel nss-devel p11-kit-devel opensc python3-asn1crypto

4. Change to a source directory:

   cd /usr/local/src

5. Clone the repository:

   git clone https://github.com/latchset/pkcs11-provider.git
   cd pkcs11-provider

6. Build the provider:

   meson setup builddir
   meson compile -C builddir

7. Install the provider:

   sudo meson install -C builddir

Configure OpenSSL to load the provider⁠

1. Locate the OpenSSL configuration file. You can verify it with the following command openssl version -d. For instance:

   • For Ubuntu/Debian:

     root@openvpnas:~# openssl version -d
     OPENSSLDIR: "/usr/lib/ssl"

   • For RHEL:

     root@openvpnas:~# openssl version -d
     OPENSSLDIR: "/etc/pki/tls"

2. Create a backup of the OpenSSL configuration file before making changes:

   cp /usr/lib/ssl/openssl.cnf /usr/lib/ssl/openssl-backup.cnf

3. Open the OpenSSL configuration file for editing:

   nano /usr/lib/ssl/openssl.cnf

4. At the top of the file, add the following line if it's not already present:

   openssl_conf = openssl_init

5. At the bottom of the file, add the following configuration block. Update the paths as needed for your system:

   [openssl_init]
   providers = provider_init
   
   [provider_init]
   default = default_init
   pkcs11 = pkcs11_init
   
   [default_init]
   activate = 1
   
   [pkcs11_init]
   module = /path/to/pkcs11-provider/pkcs11.so
   pkcs11-module-path = /usr/local/lib/fxpkcs11/libfxpkcs11.so
   pkcs11-module-token-pin = file:/path/to/file_with_pin.txt
   activate = 1

   1. 1

      Update the paths accordingly. In our example:

      • Replace /path/to/pkcs11-provider/pkcs11.so with /usr/lib/x86_64-linux-gnu/ossl-modules/pkcs11.so

      • Replace /path/to/file_with_pin.txt with /root/pkcs11-pin.txt

6. Save the file and exit — Ctrl-X, Y, then Enter.

7. Verify that the PKCS#11 provider loads correctly:

   openssl list -providers

   • You should see both default and pkcs11 listed.

   • Example output:

     root@openvpnas:~# openssl list -providers
     Providers:
       default
         name: OpenSSL Default Provider
         version: 3.0.13
         status: active
       pkcs11
         name: PKCS#11 Provider
         version: 1.1
         status: active

8. Reboot the Access Server host:

   reboot

Validate with PKCS11Manager (recommended)⁠

1. Run PKCS11Manager and confirm that the connection test succeeds:

   /usr/local/lib/fxpkcs11/PKCS11Manager

   • If you see a permission error, such as:

     -bash: /usr/local/lib/fxpkcs11/PKCS11Manager: Permission denied

   • This indicates that the file may not be executable. To fix this, run:

     chmod +x /usr/local/lib/fxpkcs11/PKCS11Manager

   • Then run the test again. You can perform a simple action (for example, select option 8 Generate Random Data).

Troubleshoot the validation with PKCS11Manager⁠

1. Check the FxPKCS11 log file:

   • Default location: same directory as fxpkcs11.cfg.

   • To customize, modify the LOG-FILE setting in fxpkcs11.cfg.

2. Verify that the PKCS #11 PIN is correct.

3. To update the PKCS #11 PIN:

   • Sign in to the CryptoHub dashboard.

   • Navigate to Identity and Access.

   • Select the Applications & Partitions tab.

   • Locate your deployed application.

   • In the Manage section, select Authentication.

   • Update the PIN/password for the endpoint in the dialog.

Set FXPKCS11 environment variables⁠

1. Export the PKCS #11 module path:

   export FXPKCS11_MODULE=/path/to/libfxpkcs11.so

   1. 1

      Update the path accordingly. For our example, we use /usr/local/lib/fxpkcs11/libfxpkcs11.so.

Configure Access Server for external PKI⁠

1. Connect to the Access Server console and get root privileges.

2. Edit as.conf for external PKI usage:

   nano /usr/local/openvpn_as/etc/as.conf

3. Comment out certs_db:

   # certificates database
   # certs_db=sqlite:///~/db/certs.db

4. Save and exit the file — Ctrl-X, Y, then Enter.

   • Access Server no longer uses the certificate database. Instead, an external system must handle this.

Generate the server key and certificate⁠

1. Generate the server private key on CryptoHub:

   pkcs11-tool --module $FXPKCS11_MODULE --login --key-type rsa:2048 --pin "$(cat /root/pkcs11-pin.txt)" --label "OpenVPN-Server-Key" --id 02 --keypairgen --usage-sign

2. Generate the PKCS #11 URI reference file for the server key:

   • For Ubuntu/Debian:

     python3 ~/src/pkcs11-provider/tools/uri2pem.py "pkcs11:type=private;object=OpenVPN-Server-Key" > server.key

   • For RHEL:

     python3 /usr/local/src/pkcs11-provider/tools/uri2pem.py "pkcs11:type=private;object=OpenVPN-Server-Key" > server.key

3. Generate the server CSR:

   openssl req -new -key server.key -out server.csr -subj "/CN=OpenVPN Server" -config /usr/lib/ssl/openssl-server.cnf

4. Sign the server certificate:

   openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 365 -extfile /usr/lib/ssl/openssl-server.cnf -extensions v3_req

   • From the above commands, you get three files:

     • Server key (server.key)

     • Server certificate (server.crt)

     • Server CSR (server.csr)

Generate the client certificate and package⁠

1. Generate the client private key:

   openssl genpkey -algorithm RSA -out client.key -pkeyopt rsa_keygen_bits:2048

2. Generate the client CSR:

   openssl req -new -key client.key -out client.csr -subj "/CN=etest" -config /usr/lib/ssl/openssl-client.cnf

3. (Optional) Generate the client CSR compatible with auto-login:

   openssl req -new -key client.key -out client.csr -subj "/role=AUTOLOGIN/CN=etest" -config /usr/lib/ssl/openssl-client.cnf

4. Sign the client certificate:

   openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt -days 365 -extfile /usr/lib/ssl/openssl-client.cnf -extensions v3_req

5. Create the P12 bundle:

   openssl pkcs12 -export -inkey client.key -in client.crt -out etest.p12 -name "etest"

6. Enter the P12 password when prompted.

   • From the above commands, you get four files:

     • Client key (client.key)

     • Client certificate (client.crt)

     • Client CSR (client.csr)

     • Client P12 file (etest.p12)

Prepare the Access Server key directory⁠

1. Connect to the Access Server console and get root privileges.

2. Create a directory for your external PKI files:

   mkdir epki && cd epki

3. Copy the required files into the directory:

   cp ../ca.crt ./
   cp ../server.crt ./
   cp ../server.key ./

Generate required OpenVPN keys and parameters⁠

1. Generate a tls_auth key:

   /usr/local/openvpn_as/scripts/certool --tls_auth

2. Generate Diffie-Hellman parameters for the OpenVPN server:

   openssl dhparam -out dh.pem 2048

3. Generate your auth token and add the generated file:

   /usr/local/openvpn_as/scripts/certool --auth_token

4. Configure X509 explicit/extended key usage based on RFC3280 TLS rules:

   /usr/local/openvpn_as/scripts/sacli --key "external_pki.remote_cert_usage" --value eku ConfigPut

5. Configure the use of the X509 “role” attribute for the declaration of auto-login permission:

   /usr/local/openvpn_as/scripts/sacli --key "external_pki.autologin_x509_spec" --value "role,,AUTOLOGIN" ConfigPut

6. Generate the tls-crypt-v2 key:

   /usr/local/openvpn_as/scripts/certool --tls_crypt2_server

Import certificates and keys into Access Server⁠

1. Load the files into the Access Server configuration database:

   /usr/local/openvpn_as/scripts/sacli --key "external_pki.ta_key" --value_file ta.key ConfigPut
   /usr/local/openvpn_as/scripts/sacli --key "external_pki.ca_crt" --value_file ca.crt ConfigPut
   /usr/local/openvpn_as/scripts/sacli --key "external_pki.server_crt" --value_file server.crt ConfigPut
   /usr/local/openvpn_as/scripts/sacli --key "external_pki.server_key" --value_file server.key ConfigPut
   /usr/local/openvpn_as/scripts/sacli --key "external_pki.dh_pem" --value_file dh.pem ConfigPut
   /usr/local/openvpn_as/scripts/sacli --key "external_pki.auth_token_key" --value_file auth_token.key ConfigPut
   /usr/local/openvpn_as/scripts/sacli --key "external_pki.tls_cryptv2_server" --value_file tls_crypt2.key ConfigPut

2. Restart Access Server:

   systemctl restart openvpnas

Create and configure a test client⁠

To test our example, we generate a test client, etest.

1. Sign in to the Admin Web UI.

2. Click Users.

3. Click Add New User.

4. Create the new user, etest, and click Save.

5. (Optional, for environments using auto-login profiles.) Under Permissions, set Allow Auto-login to Enabled, then Save.

6. Click Reset Password.

7. Enter a password and click Reset.

8. Click Restart.

9. Finally, generate a server-locked profile. The profile will be stored in etest.ovpn:

   sacli GetGeneric >etest.ovpn

   For generating an auto-login profile:

   sacli --user etest GetAutologin >etest.ovpn

10. Copy these two files to the client machine:

    • Client P12 file (etest.p12)

    • Client profile (etest.ovpn)

Install the profile and certificate in OpenVPN Connect v3⁠

1. Launch OpenVPN Connect v3.

2. Import the connection profile, etest.ovpn.

3. Select Menu → Certificate & Tokens.

4. Under PKCS#12, Select the Add icon.

5. Select your client P12 file (etest.p12).

6. Enter the password for this file that you previously configured, then select OK.

7. Go back to the Home.

8. Select Menu → My Profiles.

9. Select the Edit icon for the profile.

10. Under Certificates, use the Select button to add the external certificate to the profile.

11. Select the P12 file.

12. Select Save Changes.

13. Select Connect to start the profile's connection.