Viscosity supports the PKCS#11 standard, allowing tokens and smartcards to be used with Viscosity. Viscosity makes the process of using PKCS#11 as simple as possible to the end user, however it is still recommended that the initial setup be performed by VPN administrators or advanced users.

An more modern alternative to PKCS#11 is U2F, which does not require a PKCS#11 device driver. For more information please see the U2F Two-Factor Authentication guide.

What is PKCS#11?

PKCS#11 is a standard that defines a way for software to interact with cryptographic tokens. These are typically small portable devices, such as USB tokens and smartcards. PKCS#11 allows Viscosity to use these devices when establishing an OpenVPN connection. Tokens and smartcards can offer several benefits:

• Tokens and smartcards add an extra layer of security by requiring the user have both a computer setup with Viscosity, along with the token or smartcard. The user's private key (used for authentication) is securely stored on the token/smartcard, and can't be extracted.
• Tokens and smartcards can be used to replace manually asking for two-factor credentials to help simplify connecting to a VPN securely.
• By storing cryptographic information on a token/smartcard, a user's VPN account is not comprised if their laptop is stolen or breached.

When selecting a token/smartcard device it is important to ensure that the manufacturer provides the necessary drivers and PKCS#11 interface. If official drivers are not available, the OpenSC project provides generic drivers for a large number of smart cards and USB tokens.

Setting Up PKCS#11

Viscosity provides a user interface for configuring the most common PKCS#11 settings. The instructions below detail how to configure Viscosity's PKCS#11 support using this interface.

Driver software for the token/smartcard hardware must be installed before attempting to configure Viscosity. This software is usually provided by your token/smartcard provider.

1. Open Viscosity's Preferences window.
2. Select your connection from the list and click the Edit button, or create a new connection.
3. Click on the Authentication tab.
4. From the Authentication Type drop down menu, select "SSL/TLS Client (PKCS11)".
5. Select the CA File for your connection
   
   
   
   

    

   
   
6. Click the Add button next to the Providers field and select the PKCS#11 module for your token/smartcard. Multiple providers can be specified.
   
   On macOS, the most common location for modules to be found is in the /usr/lib/ directory. Please refer to the documentation included with your driver software for the location to use. OpenSC's provider driver can be found at /Library/OpenSC/lib/opensc-pkcs11.so. The SafeNet Authentication Client (another popular PKCS#11 driver) can be found at /Library/Frameworks/eToken.framework/Versions/A/libeToken.dylib
   
   On Windows, the most common location for libraries is either in C:\Program Files or C:\Windows\System32. OpenSC libraries are generally located at C:\Program Files\OpenSC Project\OpenSC\pkcs11. There may be more than one library available here, you can try each one or simply add both.
   
   
   
   

    

   
   
7. Next choose a retrieval method from the Retrieval drop down menu:
   
   Use certificate name below: If only one token/smartcard will ever be used on this computer, select "Use certificate name below". If the token/smartcard is currently connected to the computer, click the Detect button for Viscosity to automatically fill in the Name field. Otherwise this field can be completed manually.
   
   
   
   

    

   
   
   
   Prompt for certificate name: If in doubt, or if more than one token/smartcard may be used (i.e. multiple users), then select "Prompt for certificate name". Viscosity will automatically detect any connected tokens/smartcards and prompt the user to select one when connecting.
   
8. Click the Save button

Using PKCS#11

Viscosity simplifies using PKCS#11 for the end user considerably. If the "Use certificate name below" option was selected as the retrieval method during set up, then the user only needs to ensure that their token/smartcard is connected before attempting to connect to their VPN connection. If a password/PIN has been set, either Viscosity, or an interface included in the driver software, should prompt the user for it.

If "Prompt for certificate name" was selected, Viscosity will automatically detect any connected tokens/smartcards using the specified PKCS#11 module/s. The user will then be prompted to select from any of the found devices, or enter the name to use manually. Again, the user should be prompted for a password/PIN if required.

Apple Silicon Support

Viscosity fully supports PKCS#11 on Apple Silicon (M1) Macs. However the PKCS#11 driver being used must have native Apple Silicon support, otherwise it will not be able to be correctly loaded. Please reach out to the manufacturer of your token or smartcard device if you require an updated driver.

Windows on ARM64 Support

Viscosity fully supports PKCS#11 on machines running the ARM64 version of Windows. However, the driver being used must have native ARM64 support, otherwise it will not be able to be correctly loaded. Please reach out to the manufacturer of your token or smartcard device if you require an updated driver.

A temporary workaround is to run Viscosity in x64 emulated mode. This will allow the x64 version of a PKCS#11 driver to load, however Viscosity may run more slowly. This can be done like so:

1. Click on the Windows/Start button, and search for "Registry Editor". Open the Registry Editor app when it appears in the result list.
2. Navigate to HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Image File Execution Options\Viscosity.exe. Please ensure that Viscosity has been installed, otherwise this key will not yet exist.
3. Delete the PreferredMachine value.
4. Restart Viscosity. Please ensure that the x64 version of the PKCS#11 driver is selected and try again.

To restore Viscosity's ARM64 support once an updated driver is available, simply re-run the Viscosity installer.