This section contains the following configurations:
To use PKI, you must specify a PKCS#11 module for your PKI device. To do this, perform the following steps:
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/Application\ Support/NetIQ/DeviceService.app/Contents/Resources/config.properties.
Remove the hash sign(#) before vendorModule to remove any comments from the parameter.
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.vendorModule 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.
(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.detectionMode=vendor |
The pki.detectionMode parameter is used to detect and monitor the token connected to your system. It is set to vendor by default. OpenSC does not support the 'waiting for card' mechanism, and it requires to change the option to system. Most of the vendors module work appropriately in the default mode. NOTE:If you specify more than one library in pki.vendorModule, you must specify all the libraries in pki.detectionMode separating by a semicolon (library1;library2). If you specify only one library in pki.detectionMode, that value will be ignored, and the default values will be used |
|
Initiating library |
pki.reinitRequired=false |
This parameter is used to configure whether the PKI service reloads the PKCS#11 library after every operation, such as getting certificates, generating key pairs, and so on. It is set to false by default. For some OpenSC libraries, you need to set this parameter to true. NOTE:If you specify more than one library in "it's recommended to use, you must specify all the libraries in pki.reinitRequired separated by a semicolon (library1;library2). If you specify only one library in pki.reinitRequired, that value will be ignored, and the default values will be used |
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.
Save the changes.
Restart the Device Service.
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/Application\ Support/NetIQ/DeviceService.app/Contents/Resources/config.properties.
Remove the hash sign(#) before vendorModule to remove any comments from the parameter.
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
Save the changes.
Restart the Device Service.
Before configuring the YubiKey PKI, ensure to download the Yubico PIV tools.
NOTE:On Windows, the Device Service is an x86 app, therefore the x86 PIV tools are required.
To configure the PIV compliant Yubikey for public key authentication with OpenSC through PKCS11, perform the following steps:
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/Application\ Support/NetIQ/DeviceService.app/Contents/Resources/config.properties.
Disable the default mode. Delete or comment by adding hash symbol (#) as a prefix to the existing parameter.
For example, #pki.vendorModule=auto
Add the following parameter specific to the operating system:
Microsoft Windows:
pki.vendorModule=C:\\Program Files (x86)\\Yubico\\Yubico PIV Tool\\bin\\libykcs11.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
Save the changes.
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 Unable to Import a Certificate to the YubiKey Token to resolve these issues.
NOTE:Points to remember:
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.
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:
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
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
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/Application\ Support/NetIQ/DeviceService.app/Contents/Resources/config.properties.
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
Save the changes.
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.
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:
Download the SafeNet Authentication Client 10.
Navigate to the Customization Package folder and execute the SACCustomizationPackage-10.0.msi file.
The SafeNet Authentication Client Customization Package Installation wizard is displayed.
Click Next.
Read and accept the license agreement.
Click Next.
Click Change to select a different destination folder or install the Customization Tool’s into the default folder:
C:\Program Files\SafeNet\Authentication\
Click Install.
Click Finish.
Click Start and navigate to Programs > SafeNet > SACAdmin > SAC Customization Tool.
Select Features to install in the left pane.
Select IDGo 800 Compatible Mode from the list.
Click Actions > Generate MSI.
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
Install the msi file according to the bits of your operating system.
The Installation wizard is displayed.
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
Install NetIQ Advanced Authentication Device Service.
Navigate to C:\ProgramData\NetIQ\Device Service\config.properties.
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).
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.
This section provides the configuration information for the following cards:
Giesecke+Devrient (G&D) PKCS#11 protocol supported card
Bit4id PKCS#11 protocol supported card
NOTE:PKCS#11 library smart card is supported only on Windows Client.
To configure the Smart Card with a token supporting the PKCS#11 library, perform the following steps:
Open the configuration file on the Microsoft Windows: C:\ProgramData\NetIQ\Device Service\config.properties
Set the following details of the device:
Set the vendor module specific dll file name to the parameter. You can specify more than one PKCS#11 library with a semicolon.
For example, pki.vendorModule=bit4ipki.dll;aetpkss1.dll
NOTE:If you have specified more than one library in pki.vendorModule separated by a semicolon, you must specify the same number of values for the pki.detectionMod and pki.reintRequired parameters.
Set value for the pki.detectionMode parameter.
For example, pki.detectionMode=vendor;system
Set value for the pki.reintRequired parameter.
For example, pki.reinitRequired=true;false
Set the manufacturer ID of the card that you are using.
For example,
pki.manufacturerID.bit4ipki=IDEMIA for IDEMIA manufacturer
pki.manufacturerID.aetpkss1=A.E.T. Europe B.V. for A.E.T Europe B. V. manufacturer
Save the changes.
Restart the Device Service.
To enable the Device Service to identify and select the right PKI devices, you can configure the PKI module with library name that helps the Device Service to detect the respective device and get the inputs.
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/Application\ Support/NetIQ/DeviceService.app/Contents/Resources/config.properties
Set the following details of the device:
pki.manufacturerID.<pki_lib_name>
pki.model.<pki_lib_name>
The <pki_lib_name> is the library name and get from the configured pki.vendorModule
For example, pki.vendorModule=bit4ipki.dll
pki.manufacturerID.bit4ipki for IDEMIA
Save the changes.
Restart the Device Service.