Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Minor changes

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 middleware.

Two Gemalto middlewares are used for different Gemalto 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.

Expandall

Gemalto cards

Expand
titleCard types

Tested card types include the following (this list is not complete):

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)

  • 940 USB Token (tested with version 10.7 and 10.8 R2)

    Note

    SAC 10.8 R2 no longer ships with dedicated drivers for USB tokens and uses the standard smartcard drivers from Windows, resulting in different reader and slot names.



Expand
titleCard properties


Note

PUK is permanently blocked after 5 consecutive failed attempts. The card can not be used anymore.

  • 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 header "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 contain a secondary slot for digital signatures, using its own set of credentials. 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.

Expand
titleChange main slot credentials
  1. For cards with a signature slot you cannot use InitToken=true to set the PIN and CardManagerKey of the main slot. Instead, use SetPin=true, as shown in this example:
Code Block
titleExample: change CardManagerKey from default and set PIN for main slot
[Fields]
NEW_CARD_MANAGER_KEY=
NEW_PIN=
 
[Description]
PKCS11LibraryWindows32=cC:/Program Files (x86)/Gemalto/IDGo 800 PKCS#11/IDPrimePKCS11.dll
PKCS11LibraryWindows64=IDPrimePKCS1164C:/Program Files (x86)/Gemalto/IDGo 800 PKCS#11/IDPrimePKCS1164.dll
SetPin=true
CardManagerKey=#000000000000000000000000000000000000000000000000
NewCardManagerKey=NEW_CARD_MANAGER_KEY
PIN=NEW_PIN



Expand
titleChange signature slot credentials

The factory default for the signature PIN and PUK is 000000 for each.

Handling is similar to standard P11 PIN/PUK handling on other middlewares, but with different keywords:

Standard P11 PIN/PUK keywords on other middlewareSignature PIN/PUK keywords on Gemalto middleware

PIN

SignPIN
PUK SignPUK
InitialPUKInitialSignPUK
Pin_ValidationSignPin_Validation

Examples

Code Block
titleExample: Change signature PUK from default to 12345678 and set new signature PIN from field NEW_SIGN_PIN
[Fields]
NEW_SIGN_PIN=
 
[Description]
PKCS11LibraryWindows32=cC:/Program Files (x86)/Gemalto/IDGo 800 PKCS#11/IDPrimePKCS11.dll
PKCS11LibraryWindows64=C:/Program Files (x86)/Gemalto/IDGo 800 PKCS#11/IDPrimePKCS1164.dll
setpin=true
InitialSignPUK=#000000
SignPUK=#12345678
SignPIN=NEW_SIGN_PIN


Code Block
titleExample: User changes signature PIN by entering old and new values, validated to be at least 4 digits long
[Description]
PKCS11LibraryWindows32=cC:/Program Files (x86)/Gemalto/IDGo 800 PKCS#11/IDPrimePKCS11.dll
PKCS11LibraryWindows64=IDPrimePKCS1164
setpin=true
C:/Program Files (x86)/Gemalto/IDGo 800 PKCS#11/IDPrimePKCS1164.dll
setpin=true
SignPIN=!FROM_USER_DIALOG_3_FIELD
SignPin_Validation=reg_exp([0-9]{4,})



Expand
titleWrite to signature slot
  1. To select the signature slot as target for your application, specify Location=#signature in the respective Application_* section.

In the following example, a signature certificate is written to the signature slot (authenticated by SIGN_PIN) and an authentication certificate to the primary slot (authenticated by PIN).


Code Block
titleExample: Write signature cert to signature slot (via SIGN_PIN) and auth cert to primary slot (via PIN)
[Fields]
SIGN_PIN=
PIN=
 
[Description]
PKCS11LibraryWindows32=cC:/Program Files (x86)/Gemalto/IDGo 800 PKCS#11/IDPrimePKCS11.dll
PKCS11LibraryWindows64=C:/Program Files (x86)/Gemalto/IDGo 800 PKCS#11/IDPrimePKCS1164.dll

SignPIN=SIGN_PIN
PIN=PIN
ApplicationList=AB
 
[Application_A]
KeySize=2048
CertTempl=mySigCertTemplate
Location=#signature
 
[Application_B]
KeySize=2048
CertTempl=myAuthCertTemplate
# the following line is optional
Location=#default


Encodings

Expand
titleDLL locations

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

  1. Define like this in the encoding description for backwards-for the most compatible PKCS11Library setting for IDPrimePKCS11 :

    code

    (this one works with Smart ID Desktop App as well):

    Code Block
    titleBackwards-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. The SafeNet Authentication Client installer additionally installs the IDPrimePKCS1164 DLL in the standard Windows system folder. The 32 bit DLL is only installed in the legacy location.
    Define like this in the encoding description for IDPrimePKCS11 DLLs from SafeNet Authentication Client installer, and if compatibility with the IDGo 800 installer is not needed and you only encode via Card SDK and JPKIEncoder ( (warning) not compatible with Smart ID Desktop App):

    Code Block
    titleNOT recommended: Alternate PKCS11Library setting for IDPrimePKCS11 DLLs from SafeNet Authentication Client installer
    [Description]
    PKCS11LibraryWindows32=C:/Program Files (x86)/Gemalto/IDGo 800 PKCS#11/IDPrimePKCS11.dll
    PKCS11LibraryWindows64=IDPrimePKCS1164.dll
    Define like this in the encoding description for eTPKCS11
    # this is *not* compatible with Smart ID Desktop App!
    PKCS11LibraryWindows64=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):

    Code Block
    titlePKCS11Library setting for eTPKCS11 DLLs from SafeNet Authentication Client installer
    [Description]
    PKCS11Library=eTPKCS11.dll# this does *not* support the signature slot!
    PKCS11Library=eTPKCS11.dll



Expand
titleAdministrative 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.

  1. Define like this in the encoding description to set the CMK:

    Code Block
    titleSet the CMK
    [Description]
    # 24xNullbyte, the initial factory PUK/CMK value
    CardManagerKey=#000000000000000000000000000000000000000000000000
    # change the value for Card Manager Key to the 24 char long String 123456789012345678901234 (31 -> 1, 32 -> 2, ...)
    NewCardManagerKey=#313233343536373839303132333435363738393031323334


  2. Define like this in the encoding description to reset the CMK:

    Code Block
    titleReset the CMK to its default value
    [Description]
    # current PUK/CMK value after the change above
    CardManagerKey=#313233343536373839303132333435363738393031323334
    # Reset the PUK/CMK to factory settings
    NewCardManagerKey=#000000000000000000000000000000000000000000000000


Deviations from PKCS#11 standard

Expand
titleC_InitToken

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


Expand
titleC_SetPin

A new PUK must always be 24 bytes long.


Expand
titleC_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

Expand
titleConfiguration

To configure logging behaviour:

  1. Edit C:\ProgramData\Gemalto\PKCS11\Gemalto.PKCS11.ini.
    Lines 8, 10 and 13 are used to configure logging behaviour.
  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.

This is an example of a configuration file:

Code Block
titleC:\ProgramData\Gemalto\PKCS11\Gemalto.PKCS11.ini
1  ; ===============================================
2  ; === Gemalto IDGo PKCS#11 configuration file ===
3  ; ===============================================
4  ; === Log Section
5  [Log]
6  ; Enable the log
7  ; Value: 0 to disable the log or 1 to enable the log
8  Enable = 1
9  ; Override the default path of the logs
10 Path=c:\temp
11 ; Trace non-sensitive APDU in the log
12 ; Value: 0 to disable or 1 to enable
13 ;Apdu=0
14 ; === Cache Section
15 [Cache]
16 ; Enable the disk cache
17 ; Value: 0 to disable the cache or 1 to enable the cache
18 Enable = 1
19 ; === Enrollment Section
20 [Enrollment]
21 ForcePinUser=0
22 ; Force generated keys to be associated to PIN User
23 ; Value: 0 to disable or 1 to enable
24 ;ForcePinUser=0
25 ; === Miscellaneous Section
26 [Misc]
27 HideStaticSlots=0
28 ; Hide virtual slots for cards with static profile
29 ; Value: 1 to hide slots or 0 to not hide slots
30 ;HideStaticSlots = 0
31 [LABEL]
32 PIN_USER=PIN
33 PIN_ADMIN=SO PIN
34 PIN_3=Digital Signature PIN
35 PIN_4=PIN 4
36 PIN_5=PIN 5
37 PIN_6=PIN 6
38 PIN_7=PIN 7
39 [ATR]
40 Count = 18
41 ATR1 = 3BFF0000008131004380318065B000000000120FFE82900000 / FFFF00FFFFFFFF00FFFFFFFFFFFF00000000FFFFFFFFFFFF00
42 ATR2 = 3B7F00000080318065B000000000120FFE829000 / FFFF00FFFFFFFFFFFFFF00000000FFFFFFFFFFFF
43 ATR3 = 3B8A80010031C173C8400000900090
44 ATR4 = 3B9F96C00A3FC0A08031E073FE211065D001000000000000 / FFFFFFFFFFFFF0FFFFFFFFFFFFFFF0FFFFFF000000000000
45 ATR5 = 3B8F800180318065B000000000120FFE82900000 / FFFFFFFFFFFFFFFFFF00000000FFFFFFFFFFFF00
46 ATR6 = 3B8180018080
47 ATR7 = 3B80800101
48 ATR8 = 3BEE00008131804380318066B1A11101A0F6830090008F
49 ATR9 = 3B888001000000000001000000 / FFFFFFFF0F0000FF000F000000
50 ATR10 = 3B0000417374726964 / FF0000FFFFFFFFFFFF
51 ATR11 = 3B6E000080318066B1A11101A0F683009000
52 ATR12 = 3B86800106778077028003
53 ATR13 = 3B6E000080318066B0870C016E0183009000
54 ATR14 = 3B8E800180318066B1840C016E018300900000 / FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF00
55 ATR15 = 3B6F00008066B0070101070000000000009000 / FFFFFFFFFFFFFFFFFFFFFF000000000000FFFF
56 ATR16 = 3B8F80018066B007010107000000000000900000 / FFFFFFFFFFFFFFFFFFFFFF000000000000FFFF00
57 ATR17 = 3B6800008066B00701010707
58 ATR18 = 3B8880018066B0070101070000 / FFFFFFFFFFFFFFFFFFFFFF0000


Known issues and troubleshooting

Expand
titleIdentity Manager versions before 3.10.6 / 3.11 will not detect the eTPKCS11 middleware type correctly

Problem

Identity Manager versions before 3.10.6 / 3.11 have a bug that fails to detect the eTPKCS11 middleware type correctly. This causes a change to the PUK/cardManagerKey to silently fail. Therefore the PUK/cardManagerKey on the card is still the old one, but Identity Manager thinks it was changed, thus breaking the unblocking process.

Solution

Upgrade to Identity Manager 3.10.6 or 3.11 to solve the issue. Note that this will not automatically fix cards which were produced with the broken version.


Expand
titleLow CKR_DEVICE_MEMORY returned

Problem

With a lot of certificates on the card, but about 9Kb on the card still free according to the Mini-Driver Manager, InitToken or DestroyObject returned CKR_DEVICE_MEMORY. Even the Mini-Driver Manager crashed when attempting "Erase Card".

Solution

Delete single containers through the GUI. At 11Kb free, InitToken succeeded again (with 830 rev.A cards).


Expand
titleCreate object failed

Trying to write a CA certificate that is already on the card fails with C_CreateObject failed with CKR_FUNCTION_FAILED. JPKIEncoder will notice this and will avoid trying to rewrite it.


Expand
titleEncoding fails with Smart ID Desktop App (PKCS11 is not defined)

Problem

You get an error like this in the log when trying to encode a card through Smart ID Desktop App:

Code Block
(2021-09-16 09:28:21,033) ERROR pool-4-thread-7 (HermodEncodingService.java:261) tid[1]: production with PDA failed
de.nexus.act.jpkiencoder.failure.GeneralEndProcessException: Error Accessing Smartcard (PKCS11 is not defined)

Solution

Make sure the DLLs are present and not specified in a way that is incompatible with Smart ID Desktop app - see DLL Locations above.


Expand
titleCA certificate deletion inconsistencies

Problem

Trying to delete a CA certificate can sometimes result in a state in which the certificate is no longer visible through PKCS#11, but still present on the card and visible through the SafeNet Authentication Client (SAC).

Observed e.g. with IDPrime DLLs from SAC 10.7 .

Solution

Manually delete the certificate with SAC (multiple attempts might be needed) to fully remove it.

Problem

Similarly, trying to delete a CA certificate can sometimes result in a state where the certificate is not deleted but its label changed to a UUID.

Observed e.g. with IDPrime DLLs from SAC 10.8 R2 and eTPKCS11 DLLs from SAC 10.7 .

Solution

Either manually delete the certificate with SAC or re-run the deletion (provided you are not using LABEL as deletion criteria, which would now fail to find the certificate).