3.3 PKI Settings

3.3.1 Configuring the PKI Device

To use PKI, you must specify a PKCS#11 module for your PKI device. To do this, perform the following steps:

  1. Open the configuration file based on the operating system:

    • Microsoft Windows: C:\ProgramData\NetIQ\Device Service\config.properties.

    • Linux: /opt/NetIQ/Device Service/config.properties.

    • Apple Mac OS X: /Library/LaunchDaemons/NetIQ/Device Service/config.properties.

  2. Remove the hash sign(#) before vendorModule to remove any comments from the parameter.

  3. Set the vendor module specific dll file name to the parameter.

    pki.vendorModule: <filename>.dll

    For example, pki.vendorModule: rtPKCS11.dll.

    NOTE:You can specify more than one PKCS#11 library with semicolon in the format: pki.vendorModule: eToken.dll;rtPKCS11.dll

    If a vendor module is not located in the system32 directory, use \\ to specify the path. If there are any spaces in the path, ensure not to replace the space with \\ in the path.

    For example, pki.vendorModule: C:\\Program Files\\ActivIdentity\\ActivClient\\acpkcs211.dll.

    NOTE:If you have specified some pki.vendorModules separated by a semicolon, you must specify the same number of values for the parameter pki.blockingMode.

    For example, pki.blockingMode: true;false.

    PKI plug-in of the Device Service supports the automatic mode, where a few known vendor modules are auto-detected. You must specify: pki.vendorModule: auto.

  4. (Optional) Specify the additional parameters:

    Table 3-1

    Method

    Syntax

    Description

    Hash

    pki.hashMethod: SHA256

    The default value is SHA256 and you can specify this value, if a parameter is not presented. The following methods are also supported: SHA224, SHA384, SHA512. To set the methods, ensure that the PKCS#11 module supports the required hash method.

    Padding

    pki.padding: PKCS#1

    The default value is PKCS#1 and you can specify this value, if a parameter is not presented.The following options are also supported: PSS, OAEP.

    Key size

    pki.modulusBits: 2048

    The default value is 2048 bit. For example, eToken PRO 32k does not support it and you need to set 1024 to use it.

    Blocking mode

    pki.blockingMode: true

    This parameter is used to detect and monitor the token connected to your system. It is set to true by default. OpenSC does not support the 'waiting for card' mechanism and it requires to change the option to False. Most of the vendors module work appropriately in the default mode.

    NOTE:If you specify the pki.vendorModule: auto and pki.blockingMode parameters, the pki.blockingMode parameter does not overwrite a blocking mode that is pre-defined for an auto-detectable vendor module.

  5. Save the changes.

  6. Restart the Device Service.

3.3.2 Configuring e-Token PRO

  1. Navigate to one of the following paths and open the configuration file based on the operating system:

    • Microsoft Windows: C:\ProgramData\NetIQ\Device Service\config.properties.

    • Linux: /opt/NetIQ/Device Service/config.properties.

    • Apple Mac OS X: /Library/LaunchDaemons/NetIQ/Device Service/config.properties.

  2. Remove the hash sign(#) before vendorModule to remove any comments from the parameter.

  3. Set the vendor module specific dll file name to the parameter based on the operating system:

    • Microsoft Windows:

      • pki.vendorModule: eToken.dll

      • pki.blockingMode: true

    • Linux:

      • pki.vendorModule: /usr/lib/libeTPkcs11.so

      • pki.blockingMode: true

    • Mac OS X:

      • pki.vendorModule: libeTPkcs11.dylib

      • pki.blockingMode: true

  4. Save the changes.

  5. Restart the Device Service.

3.3.3 Configuring the YubiKey PKI

Before configuring the YubiKey PKI, ensure to download the Yubico PIV tools. You can unpack the zip file and navigate to bin directory.

To configure the PIV compliant Yubikey for public key authentication with OpenSC through PKCS11, perform the following steps:

  1. Open the configuration file based on the operating system:

    • Microsoft Windows: C:\ProgramData\NetIQ\Device Service\config.properties.

    • Linux: /opt/NetIQ/Device Service/config.properties.

    • Apple Mac OS X: /Library/LaunchDaemons/NetIQ/Device Service/config.properties.

  2. Add hash symbol (#) as a prefix to the existing parameters that start with pki to set the parameter as a comment.

    For example:

    • #pki.vendorModule=auto

    • #pki.forceVirtualChannels=false

  3. Add the following parameter specific to the operating system:

    • Microsoft Windows:

      • pki.vendorModule=libykcs11-1.dll

      • pki.blockingMode=false

    • Linux:

      • pki.vendorModule=/usr/local/lib/libykcs11.so

      • pki.blockingMode=false

    • Mac OS X:

      • pki.vendorModule=/usr/lib/Libykcs11.1.dylib

      • pki.blockingMode=false

  4. Save the changes.

  5. Perform one of following based on the operating system:

    • Microsoft Windows: Open the Services app and restart the Device Service.

    • Linux: Run the following commands:

      sudo service deviceservice stop

      sudo service deviceservice start

    • Mac OS X: Run the following commands:

      sudo launchctl unload /Library/LaunchDaemons/com.netiq.deviceservice.plist

      sudo launchctl load /Library/LaunchDaemons/com.netiq.deviceservice.plist

    IMPORTANT:The YubiKey PKCS module supports only the Generate a key pair mode and does not work with the existing certificates on the PKI token or smart card.

    NOTE:If you are not able to enroll the PKI method using YubiKey PKI or import a certificate to YubiKey token, see PKI Related Issues to resolve these issues.

    NOTE:

    • Sometimes the vendor specific module may stop working on Mac OS.

    • Some certificates may not be accessible through the vendor specific module. The issue with certificate may display an error message Operation failed exception. This issue occurs when the vendor module does not retrieve the certificate body for some certificates.

3.3.4 Configuring OpenSC

OpenSC is a third party software that provides a set of libraries and utilities to work with different PKCS#11 tokens and cards. OpenSC implements the standard APIs to smart cards and tokens if these devices do not have the vendor specific PKCS module.

Before configuring the OpenSC on any PKCS#11 based tokens and cards, ensure that the following requirements are met:

  • Download and install OpenSC.

    NOTE:For Microsoft Windows, you must install and use a 32bit version of OpenSC.

  • Import a certificate to the token or card.

To configure token for public key authentication with OpenSC through PKCS11, perform the following steps:

  1. Open the OpenSC configuration file based on the operating system:

    • Microsoft Windows: c:\Program Files (x86)\OpenSC Project\OpenSC\opensc.conf

    • Linux: /usr/local/etc/opensc.conf

    • Apple Mac OS X: /Library/OpenSC/etc/opensc.conf

  2. Remove the hash symbol from following parameter to uncomment:

    pin_cache_ignore_user_consent = true;

    You can also see the following comments in the configuration file:

    # Older PKCS#11 applications not supporting CKA_ALWAYS_AUTHENTICATE

    # may need to set this to get signatures to work with some cards.

    # Default: false

  3. Open the configuration file based on the operating system:

    • Microsoft Windows: C:\ProgramData\NetIQ\Device Service\config.properties

    • Linux: /opt/NetIQ/Device Service/config.properties

    • Apple Mac OS X: /Library/LaunchDaemons/NetIQ/Device Service/config.properties

  4. Add the following parameters specific to the operating system:

    • Microsoft Windows:

      • pki.vendorModule=C:\\Program Files (x86)\\OpenSC Project\\OpenSC\\pkcs11\\opensc-pkcs11.dll

      • pki.blockingMode=false

    • Linux:

      • pki.vendorModule=/usr/local/lib/opensc-pkcs11.so

      • pki.blockingMode=false

    • Mac OS X:

      • pki.vendorModule=/Library/OpenSC/lib/opensc-pkcs11.so

      • pki.blockingMode=false

  5. Save the changes.

  6. Perform one of following based on the operating system:

    • Microsoft Windows: Open the Services app and restart the Device Service.

    • Linux: Run the following commands:

      sudo service deviceservice stop

      sudo service deviceservice start

    • Mac OS X: Run the following commands:

      sudo launchctl unload /Library/LaunchDaemons/com.netiq.deviceservice.plist

      sudo launchctl load /Library/LaunchDaemons/com.netiq.deviceservice.plist

    IMPORTANT:While using OpenSC, the Generate a key pair mode is not supported for Yubikeys and allows to work with the certificates that are existing on the PKI token or smart card.

3.3.5 Configuring Gemalto Smart Card with Advanced Authentication

This section provides the configuration information of the following Gemalto smart cards:

  • IDPrime .NET Smart cards

  • SafeNet eToken 51x0

To configure the Advanced Authentication with Gemalto smart card, perform the following configuration tasks:

Installing the SafeNet Authentication Client 10

  1. Download the SafeNet Authentication Client 10.

  2. Navigate to the Customization Package folder and execute the SACCustomizationPackage-10.0.msi file.

    The SafeNet Authentication Client Customization Package Installation wizard is displayed.

  3. Click Next.

  4. Read and accept the license agreement.

  5. Click Next.

  6. Click Change to select a different destination folder or install the Customization Tool’s into the default folder:

    C:\Program Files\SafeNet\Authentication\

  7. Click Install.

  8. Click Finish.

Generating the Customized MSI file

  1. Click Start and navigate to Programs > SafeNet > SACAdmin > SAC Customization Tool.

  2. Select Features to install in the left pane.

  3. Select IDGo 800 Compatible Mode from the list.

  4. Click Actions > Generate MSI.

  5. Specify the file name and save files in the preferred folder.

    The generated msi files are as follows:

    • <file name>msi-x32-10.0

    • <file name>msi-x64-10.0

  6. Install the msi file according to the bits of your operating system.

    The Installation wizard is displayed.

  7. Follow the installation steps and click Finish.

    NOTE:Ensure that the file IDPrimePKCS11.dll is available in one of the following paths:

    • C:\Program Files (x86)\Gemalto\IDGo 800 PKCS#11

    • C:\Program Files\Gemalto\IDGo 800 PKCS#11

Configuring PKCS Path in the Device Service

  1. Install NetIQ Advanced Authentication Device Service.

  2. Navigate to C:\ProgramData\NetIQ\Device Service\config.properties.

  3. Set the pki.vendorModule to the customized PKCS file path as follows:

    pki.vendorModule= C:\\Program Files (x86)\\Gemalto\\IDGo 800 PKCS#11\\IDPrimePKCS11.dll.

    NOTE:Do not use a 64 bit library file (IDPrimePKCS1164.dll).

  4. Save and Restart Device Service.

NOTE:If you have SafeNet Authentication Client (SAC) version v8.x, set the pki.vendorModule to auto. The SAC uses eToken.dll library for IDPrime cards.

3.3.6 Configuring the Security Settings

To secure the user information that is stored in the digital certificates of PKI authenticator, you can control and process the HTTPS requests from a preferred domain. With this approach, you can grant the access to secured resources only for the requests from the Advanced Authentication server and deny access for any requests from an unidentified domain. With the security settings, you can also avoid the cross-origin HTTPS request and click-jacking vulnerabilities.

To configure the security settings for the Device Service, perform the following steps:

  1. Open the configuration file based on the operating system:

    • Microsoft Windows: C:\ProgramData\NetIQ\Device Service\config.properties

    • Linux: /opt/NetIQ/Device Service/config.properties

    • Apple Mac OS X: /Library/LaunchDaemons/NetIQ/Device Service/config.properties

  2. Specify the following parameters:

    • host.accessControlOrigin=<origin>.

      Where, <origin> is secured domain. Default value is asterisk symbol (*). With the default value, the HTTPS request from any origin can access the secured resource. This may be vulnerable and cause issues to the secured resource.

      For example, set the parameter as host.accessControlOrigin=https://myexample.company.com then the HTTPS requests from specified origin can only access the digital certificates list.

    • host.xFrameOptions=allow-from <domain URL>.

      Where, <origin> is secured domain.

      For example, host.xFrameOptions=allow-from https://sample.company.com. This allows the PKI related pages to be loaded in a frame only on the specified origin or domain.

  3. Save the changes.

  4. Restart the Device Service.