Keystore Troubleshooting Guide (en)

Alison Desktop
AD (+3.2.1)

DigiCert Desktop Client
DDC (+3.2.1)

Updated: Mar-2022

Description

The following guide allows the detection and resolution of problems related to a KeyStore.

Here are some of the symptoms that may be related to a Keystore problem:

  • A previously existing certificate is no longer listed.

  • A Profile corresponding to a KeyStore is not detected.

 

To list the available KeyStores and Profiles in your installation, you can use the Test Panel by completing the following steps:

  • To list Keystores

    • Library [Initialize] >>

    • Listing [List KeyStores]

  • To list Profiles

    • Library [Initialize] >>

    • Listing [List Profiles]

  • To list Certificates

    • Library [Initialize] >>

    • Listing [List Certificates]

1.- Determine if the KeyStore has been loaded

Open Preferences >> Admin KeyStores to see the list of Keystore.


The condition of each error is described below:

Succesful

 

The Keystore has been successfully detected and loaded by AD/DDC. In the case of detecting Profiles of this type of keystores, the list must appear in the second column, as shown in the image for MACOS, NSS-FF and CSK. If the Profile is not in the list, then you should check if it is recognized from the manufacturer's management software.

 

Keystore disabled by user

The Keystore has been disabled by the user. You need to enable it and you don't need to restart AD/DDC.

 

Error during initialization

An error occurred during the initialization of the Keystore and it was not loaded successfully. In 2.- Determine Error during initialization you can find instructions.

 

Driver not detected

The drivers are not installed on the computer. It is necessary that the PKCS#11 drivers are correctly installed and with the correct permissions. AD/DDC does not include Smartcard or Cryptographic Token drivers and must be installed separately. In 3.- Driver not detected you can find more information.

 

 

2.- Determine Error during initialization

This kind of error happens usually on SmartCard or cryptographic tokens. The following list includes the most common reason of problems:

  • The loaded driver does not correspond to the platform or operating system. Verify that 32-bit (AD/DDC < v3.3.x) or 64-bit (AD/DDC >3.3.0) drivers are being used.

  • Driver dependencies are not loaded or referenced.
    Depending on the platform, the drivers may require other libraries to be installed or included in the user's PATH (see details below).

  • The permissions of the driver files are not correct.
    Verify that they have read and execute permissions for the user.

To determine the initialization error, it is convenient to run the application from a terminal or console.

Corresponding error messages can be found in the console that can help determine the reason for the error.

Windows

Open a command console (cmd) and run the corresponding script

%USERPROFILE%\AppData\Local\CertiSur\Alison-Desktop\run_alison_desktop.cmd

%USERPROFILE%\AppData\Local\DigiCert\DigiCert-Desktop\run_digicert_desktop.cmd

MacOS

Open a terminal and run the corresponding script

/Applications/Alison-Desktop.app/Contents/app/start-alison-desktop.sh

/Applications/DigiCert-Desktop.app/Contents/app/start-digicert-desktop.sh

The result can be viewed by running the command: more $USERHOME/nohup.out

 

3.- Driver not detected

Each Keystore requires its corresponding PKCS11 driver provided by the manufacturer. The drivers must be installed respecting the default directory indicated by the manufacturer.

AD/DDC loads the driver as defined in the file config/keystore.user as described in Main Files.

Verify that the referenced file is present, as in the example below.

{ "id": "GEMP15-1", "status": "enabled", "icon": "TOKEN", "friendly_name": "Gemalto Classic Smart Card", "capabilities": "SGI", "filter_mask": -1, "windows": { "driver_path_x86": "%PROGRAMFILES86%\\Gemalto\\Classic Client\\BIN\\gclib.dll", "driver_path_x64": "%PROGRAMFILES%\\Gemalto\\Classic Client\\BIN\\gclib.dll" }, "osx": { "driver_path": "/usr/local/lib/ClassicClient/libgclib.dylib" }, "linux": { "driver_path": "/usr/lib/ClassicClient/libgclib.so" } },