Using Tokens/Smartcards (PKCS#11)
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.
- Open Viscosity's Preferences window.
- Select your connection from the list and click the Edit button, or create a new connection.
- Click on the Authentication tab.
- From the Authentication Type drop down menu, select "SSL/TLS Client (PKCS11)".
- Select the CA File for your connection
- 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
On Windows, the most common location for libraries is either in
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.
- 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.
- Click the Save button
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.
At the time of writing OpenSC has not fully released an update with Apple Silicon support, however early "nightly" builds will support are available. The OpenSC project expect to have a full release (version 0.22) available soon.