An encoding description contains the information for the electronic personalization of a card. You import the encoding description from a file. This can be used in Smart ID Identity Manager.

This article describes how you create descriptions for Gemalto/SafeNet/Thales middleware.

Two Gemalto/SafeNet/Thales middlewares are used for different Gemalto/SafeNet/Thales cards:

• IDPrimePKCS11 (original Gemalto middleware)

• eTPKCS11 (original SafeNet middleware)

Both were originally distributed separately, but are now combined into the SafeNet Authentication Client installer package (for example, versions 10.6 and 10.7). Most of the information in this article applies to both DLL variants, but certain features may only be available on one of them.

Gemalto cards

Card types

Tested card types include the following:

IDPrimePKCS11 DLL from IDGo 800 Installer

• 830 Card

eTPKCS11 DLL from SAC Installer

• 830 Card (tested with version 10.6 and 10.7)

• 840 Card (tested with version 10.6)

IDPrimePKCS11 DLL from SAC Installer

• 940 Card (tested with version 10.7)

• 3940 Card (tested with version 10.8 R2)

• 3940 FIDO Card (tested with version 10.8 R2)

• 940 USB Token, e.g. SafeNet eToken 5110 CC (tested with version 10.7 and 10.8 R2)

Card properties

• Initial PUK is a byte-array with 24 zero bytes. The PUK is identical to the Card Manager Key.

• Initial PIN is 0000.

• The PUK is referred to as "Admin PIN".

• The PIN is referred to as "User PIN"

• If multipin is enabled during installation and ForcePinUser is set to false (that is, set to 0) (see heading "Configuration" below), when creating a keypair you will be prompted to select its PIN.

Support for cards with signature slot

Gemalto IDPrime 940 cards and USB tokens (like SafeNet eToken 5110 CC) contain a secondary slot for digital signatures, using its own set of credentials. The factory default for the signature PIN and PUK is 000000 for each. From PRIME 3.12, these are supported on the IDPrimePKCS11 DLLs that are included with a recent Safenet Authentication Client (SAC) Installer. SAC version 10.7 or later is required, see above for tested versions.

Encodings

DLL locations

The PKCS11 library setting depends on the DLL and installer you used:

1. Define like this in the encoding description for the most compatible PKCS11Library setting for IDPrimePKCS11 (this one works with Smart ID Desktop App as well):

   Recommended: most compatible PKCS11Library setting for IDPrimePKCS11

   [Description] PKCS11LibraryWindows32=C:/Program Files (x86)/Gemalto/IDGo 800 PKCS#11/IDPrimePKCS11.dll PKCS11LibraryWindows64=C:/Program Files (x86)/Gemalto/IDGo 800 PKCS#11/IDPrimePKCS1164.dll

2. Version 10.8R2 of the SafeNet  Authentication Client installer also uses these new locations in addition to the ones listed under 1.) above, and you may choose to reference the new locations (this works with Smart ID Desktop App as well):

   Alternate SAC 10.8R2 PKCS11Library setting for IDPrimePKCS11 DLLs from SafeNet Authentication Client installer

   [Description] PKCS11LibraryWindows32=C:/Program Files/SafeNet/Authentication/SAC/x32/IDPrimePKCS11.dll PKCS11LibraryWindows64=C:/Program Files/SafeNet/Authentication/SAC/x64/IDPrimePKCS1164.dll

3. Define like this in the encoding description for eTPKCS11 DLL from SafeNet Authentication Client installer (recommended only if you do not need the signature slot):

   PKCS11Library setting for eTPKCS11 DLLs from SafeNet Authentication Client installer

   [Description] # this does *not* support the signature slot! PKCS11Library=eTPKCS11.dll

Administrative Credentials

Do not use the PUK in encodings, use only the Card Manager Key (CMK). The two keys are identical but using a PUK with our implementation would only limit the effective key size.

• To set the current CMK, use the keyword CardManagerKey.

• To set a new CMK, use the keyword NewCardManagerKey, the same way as a new PUK is set.

The CMK must always be a sequence of 24 bytes. To set this value, specify the hex values of the bytes.

• Define like this in the encoding description to set the CMK:

  Set the CMK

• Define like this in the encoding description to reset the CMK:

  Reset the CMK to its default value

Deviations from PKCS#11 standard

C_InitToken

Tokens are always preinitialized. The initial PUK is a bytearray consisting of 24 nullbytes.

C_SetPin

A new PUK must always be 24 bytes long.

C_GenerateKeyPair

The following restrictions apply:

• For RSA keys, the only supported key size values are 1024 and 2048 bits.

• For RSA key pairs, the only value supported for the public exponent is 0x010001.

• If this function is called on a main slot (not virtual slot) and if the ForcePinUser option is set to 0 in the configuration file, then a dialog window is displayed in order to choose which PIN the resulting key pair should be associated with.

Configuration

To configure logging behavior:

1. Edit C:\ProgramData\Gemalto\PKCS11\Gemalto.PKCS11.ini.
   Lines 8, 10 and 13 are used to configure logging behavior.

2. Set ForcePinUser to 1 to force any generated keys to be associated to the user PIN. This is how other cards generally behave. If set to 0, the user will be prompted to select which PIN the keypair should be associated with every time a keypair is generated, see heading "C_GenerateKeyPair" above.

Known issues and troubleshooting

Related information

• Smart ID Identity Manager

• Encoding description in Identity Manager

• Set up an encoding description file in Identity Manager

• Structure of an encoding description in Identity Manager