Deploying the software with tokens or smart cards

Introduction

The SN VPN Client Exclusive supports a great number of tokens and smart cards that can be used for strong multi-factor authentication (MFA) using one of the following APIs: CNG (default) or PKCS#11.

NOTE
The list of tokens and smart cards compatible with the SN VPN Client Exclusive is available on TheGreenBow’s website at: https://www.thegreenbow.com/en/support/integration-guides/compatible-vpn-tokens/.

CNG

CNG stands for “Cryptography API: Next Generation”. It is an API to access cryptographic tokens and smart cards, currently provided by Microsoft. The SN VPN Client Exclusive uses it by default, and it does not require any additional configuration.

PKCS#11

PKCS#11 is an API to access cryptographic tokens and smart cards that has been standardized by RSA Labs. Most tokens and smart cards are compatible with PKCS#11. For the SN VPN Client Exclusive to be able to use the PKCS#11 API, a middleware provided by the manufacturer of the token or smart card must first be installed on the target computer.

To force the SN VPN Client Exclusive to use the PKCS#11 API instead of the CNG API, use the Force PKCS#11 API usage option (refer to the section entitled “PKI Options” in the SN VPN Client Exclusive “Administrator’s Guide”) or the MSI property PKCS11ONLY when installing the software (see section PKCS11ONLY).

The SN VPN Client Exclusive supports PKCS#11-compatible tokens or smart cards from leading manufacturers (Gemalto, IN Groupe, Neowave, Feitian, Yubico, etc.) without any additional configuration.

The tokens and smart cards compatible with the SN VPN Client Exclusive are the ones listed on TheGreenBow’s website at: https://www.thegreenbow.com/en/support/integration-guides/compatible-vpn-tokens/ and for which the PKCS11 box is checked.

For tokens or smart cards that are not recognized as standard by the SN VPN Client Exclusive, the software allows you to specify their characteristics in a PKCS#11 initialization file called vpnconf.ini, described below.

vpnconf.ini file

To enable the SN VPN Client Exclusive to support tokens or smart cards that are not recognized as standard, you must create a vpnconf.ini file in the VPN Client’s installation directory (C:\Program Files\Stormshield\Network VPN Client Exclusive\ by default). You can create the file using a standard text editor (e.g. Notepad).

The parameters to be specified in the vpnconf.ini file are broken down into several sections:

A series of (optional) ATR sections used to define the attributes of tokens or smart cards that are not recognized as standard by the software
An (optional) ROAMING section to specify the token or smart card to be used when initializing the software

ATR sections

ATR stands for “Answer To Reset”. It is an identifier that the token or smart card returns upon receiving a reset command. This identifier is related to the manufacturer and model of the token or smart card.

Each ATR section describes the required characteristics to access a token or smart card, or a family of tokens or smart cards that are not yet known to the software.

The parameters to be specified in the ATR section are detailed in the following table:

Parameter	Meaning
[ATR#]	ATR of the token or smart card to be added
mask	Mask to be used with this ATR. Details regarding ATRs and ATR masks are provided by the manufacturers of tokens or smart cards. If in doubt, you can configure a mask containing only FF. The lengths of the ATR and the mask must be identical. The mask line can thus be as follows: mask=FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF:FF
scname	Name of the token or smart card (strictly descriptive field)
manufacturer	Name of the manufacturer (strictly descriptive field)
pkcs11dllname	Name of the PKCS#11 DLL
dllpath	Path to the PKCS#11 DLL. The path is the complete path. It must also contain the DLL name. At least one of the two parameters dllpath or registry must be defined.
registry	Name of the key in the registry specifying the path to the middleware. At least one of the two parameters dllpath or registry must be defined

EXAMPLE
[3B:0F:52:4E:42:4F:24:00:23:00:00:00:00:00:00:00:01]
mask="FF:FF:FF:FF:FF:FF:FF:00:FF:00:00:FF:FF:00:00:00:FF"
scname="Card Name"
manufacturer="Company Name"
pkcs11dllname="mdlw.dll"
dllpath=”C:\path\to\middleware\mdlw.dll"

ROAMING section

The ROAMING section is used to specify the token or smart card reader to be used when the option Use the token or SC reader specified in the VPN Config. is selected (refer to the section entitled “PKI Options” in the SN VPN Client Exclusive “Administrator’s Guide”) or when the software has been installed with the SMARTCARDROAMING property set to 2 or 3 (see section SMARTCARDROAMING).

The parameters to be specified in the ROAMING section are detailed in the following table:

Parameter	Meaning
SmartCardReader	Name of the smart card reader or token to use
SmartCardMiddleware	DLL file used to communicate with the token or smart card
SmartCardMiddlewareType	Type of middleware. PKCS#11 is the only value possible for the SmartCardMiddlewareType parameter.
SmartCardMiddelwarePath	Path to the middleware including the middleware name. At least one of the two parameters SmartCardMiddlewarePath or SmartCardMiddlewareRegistry must be defined.
SmartCardMiddlewareRegistry	Name of the key in the registry specifying the path to the middleware. At least one of the two parameters SmartCardMiddlewarePath or SmartCardMiddlewareRegistry must be defined.

NOTE
The parameters for accessing the Windows registry must comply with the following syntax:
PRIMARY_KEY:path\\to\\specific\\key:value

EXAMPLE
[ROAMING]
SmartCardReader="Card Name"
SmartCardMiddleware="mdlw.dll"
SmartCardMiddlewareType="PKCS#11"
SmartCardMiddlewareRegistry=”HKEY_LOCAL_MACHINE:SOFTWARE\\Vendor\\Prod\\CK:PKCS#11DLL"