App Support.

We're here to help.

Using Tokens/Smartcards (PKCS#11)

Viscosity 1.1 and later support 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 initial setup only be performed by VPN administrators or advanced users.

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/smartcards add an extra layer of security by requiring the user have both a computer setup with Viscosity any needed certificates, along with the token or smartcard.
  • Tokens/smartcards can be used to replace asking for a username and password to help simplify connecting to a VPN.
  • 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 producer it is important to ensure that they provide the necessary drivers and PKCS#11 interface for both Mac OS 10.5 and Mac OS 10.6. Some may only provide drivers for Windows, or have incomplete support for the newer versions of Mac OS X.

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. Alternatively, if your hardware is supported by OpenSC, you can download the OpenSC drivers.

  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 module can be found at /Library/OpenSC/lib/

    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.