Card initialization and credentials in Identity Manager

This article includes updates for 23.10.2.

This article describes how you create descriptions to initialize a card as well as how to handle credentials. An encoding description contains the information for the electronic personalization of a card. You must import the encoding description from a file. For more information, see Structure of an encoding description in Identity Manager.

Define initialization of a card

Define like this in the encoding description:

[Description]
InitToken=true
InitialPUK=PUK_FIELD
InitialLabel=#My Token Label
SetPIN=true
PIN=PIN_FIELD
ClearFields=PIN_FIELD,PUK_FIELD

Description of the elements

Element	Description
InitToken=true	Triggers the card initialization and sets the PUK from the mandatory description element InitialPUK.
InitialPUK=...	This is mandatory and it is either taken from a field list or it is a fix value, starting with the hash key: InitialPUK=PUK_FIELD InitialPUK=#12345678
InitialLabel=...	This is optional (but recommended) and it is either taken from a field list or it is a fix value, starting with the hash key: InitialLabel=MY_TOKEN_LABEL_FIELD InitialLabel=#My Token Label
SetPIN=true	This is optional and sets the PIN using the corresponding PIN description key from one of these: a field list a given fix value a Pin Request Dialog (!FROM_USER_DIALOG_x_FIELD) with 1-3 PIN fields (1: field for simple authentication, 2: fields for entering it twice for a new confirmed PIN or 3: fields for a new confirmed PIN including its old one). See the illustrations: PIN field 1 - Simple authentication: PIN field 2 - Enter new PIN twice: PIN field 3 - Enter current PIN and new PIN twice: a middleware/reader inherent PIN retrieving mechanism that is, for instance and typically, a separate reader PINPAD (!FROM_PROTECTED_AUTHENTICATION_PATH). auto-detection of reader type (!FROM_USER_DIALOG_x_FIELD_AUTO), which behaves either like !FROM_USER_DIALOG_x_FIELD (for normal reader) or like !FROM_PROTECTED_AUTHENTICATION_PATH (for pinpad reader) - requires Identity Manager 23.04.9 or later. Examples: PIN=PIN_FIELD PIN=#123456 PIN=!FROM_USER_DIALOG_1_FIELD PIN=!FROM_USER_DIALOG_2_FIELD PIN=!FROM_USER_DIALOG_3_FIELD PIN=!FROM_PROTECTED_AUTHENTICATION_PATH PIN=!FROM_USER_DIALOG_1_FIELD_AUTO PIN=!FROM_USER_DIALOG_2_FIELD_AUTO PIN=!FROM_USER_DIALOG_3_FIELD_AUTO
ClearFields	This is optional and can be used to reset specific fields before returning. This would be used to avoid usage of these fields in the application afterwards (deletes them from the data map). Those fields are considered secrets and thus logged in an obfuscated way.

Return key exchange thumbprint to mapped fields

Identity Manager does not yet support this feature with Smart ID Desktop App.

To establish a trust anchor for Secure Key Injection (SKI) with CardOS 5.3 cards, you must connect a CardOS-specific key exchange thumbprint (CKP_KEYX_THUMB_PRINT) with the card. To read that thumbprint as hex-string into the mapped fields, use the following encoding description.

This will only work with CardOS 5.3 cards and it also requires CardOS 5.4 middleware or later on the Identity Manager server.

Define like this in the encoding description:

[Fields]
Thumbprint=
...
 
[Description]
CardOSSkiThumbPrintField=Thumbprint

Description of the elements

Element	Description
CardOSSkiThumbPrintField=...	Defines the field into which the thumbprint of the used smartcard has to be written. If this is missing, no thumbprint will be returned. Note that the related field also must be defined in the `Fields` section and have the Read attribute.

Set the Read attribute in the Encoding Fields tab to get the value into your datamap.
Make sure you have defined a field in the Card datapool where the thumbprint will be stored and assign it in the Encoding Fields tab. These SKI thumbprints are not considered secrets, but they should be protected against manipulation.

Use CardManagerKey vs. PUK to log in

In some cases is is required to use a CardManagerKey key in addition to, or instead of, a PUK. The term CardManagerKey is also known as AdminKey (especially in Microsoft Minidriver context), CardMasterKey (legacy name) or simply challenge/response key, though the latter sometimes isn't 100% accurate. This relates to the article Block and unblock card in Identity Manager, see "Produce an offline-unblockable card".

Examples:

Cryptovision can use the CardManagerKey to derive special keys for securing communication with the card - in this special case the CardManagerKey actually is not the challenge/response key but it is used to derive that key.

The CMK is a 16 byte 2DES key for Cryptovision, the derived challenge/response key is a 24 bytes 3DES key.
Gemalto cards combine PUK and challenge/response 3DES key and ship with it pre-initialized to 24 null-bytes. The existing PUK interface for those cards is not supported to avoid restricting the effective key length.

Do the following:

Define like this in the encoding description:

[Description]
CardManagerKey=...
NewCardManagerKey=...

Description of the elements

Element	Description
CardManagerKey=	Hex-string, defines the current CardManagerKey key already on the card, corresponds to InitialPUK=...
NewCardManagerKey=	Hex-string, when used with SetPIN=true, defines the new cardmanager key, corresponds to PUK=...

For Cryptovision, changing the CardManagerKey is not supported (NewCardManagerKey is ignored).

Validate PIN policy

Use a regular expression to validate a PIN, for example, when entered by PIN-Popup.

Define like this in the encoding description:
```
[Description]
#Pin_Validation=reg_exp([0-9a-zA-Z]{4,8})
Pin_Validation=reg_exp((?:(?!012|123|234|345|456|567|678|789|987|876|765|654|543|432|321|210|000|111|222|333|444|555|666|777|888|999)\d){6,10})
```
Description of the elements
Element Description
Pin_Validation=... Defines the validation rule, for example, a regular expression specified by the call to reg_exp(...)
Example:
The second mentioned regular expression above disallows some repeating, ascending or descending digits (using look-ahead regular expression syntax). It also sets the limits between 6 and 10 digits in total, that is, min-length and max-length.

Evaluation of regular expressions

If you use Smart ID Self-Service (with Smart ID Desktop App), regular expressions are evaluated using Javascript.
If you use Identity Manager Operator, regular expressions are evaluated using Java.

There are some differences, as Javascript does not support all constructs that Java does. Be aware when using Smart ID Self-Service with regular expressions containing one of the following:

(?< (Look-behind, see https://www.regular-expressions.info/lookaround.html)
(?> (Atomic groups, see https://www.regular-expressions.info/atomic.html)
(?i or (?d or (?m or (?s or (?u or (?x or (?U (Directives, see https://www.regular-expressions.info/modifiers.html)
(?<name>group) or (?'name'group) where name and group are some arbitrary string (Named groups, see https://www.regular-expressions.info/named.html)
(?#comment) where comment is some arbitrary string (Comments, see https://www.regular-expressions.info/freespacing.html)
\uxxxx where xxxx is some arbitryry digit or \p (Unicode, see https://www.regular-expressions.info/unicode.html)

Handle MiniDriver serial number

Identity Manager does not yet support this feature with Smart ID Desktop App.

Return the MiniDriver's card serial number property

For cards where the ICCSN does not supply useful information (for example, all-zero on the Siemens testcards), you can use the MiniDriver (currently, only with CardOS middleware) to read the card serial number property.

Define like this in the encoding description:

[Fields]
MDCardSN=
...
 
[Description]
MDCardSerialNumber=MDCardSN

Description of the elements

Element	Description
MDCardSerialNumber=...	Defines the field into which the MD card serial number of the used smartcard has to be written. If this is missing, no serial number will be returned. Note that the related field also must be defined in the `Fields` section and have the Read attribute.

This command is executed as finalization command (just like reading the ICCSN).

Write the cardid via the MiniDriver

Define like this in the encoding description:

[Fields]
MDCardID=
CardManagerKey=
...
 
[Description]
CardManagerKey=CardManagerKey
MDCardID=MDCardID

Description of the elements

Element	Description
MDCardID=...	The new cardid (can be given as fieldname or as fixed value via #C0FFEEEEBEEFF00D). You can also use expressions that will be evaluated during the card operation as noted below
CardManagerKey=...	The 3DES challenge-response key (admin key) to authenticate.

This command is executed as a finalization command.

If you read the ICCSN in the same encoding, you will get the value of the ICCSN prior to the change of the cardid.

Dynamic MDCardID values

The configured field for the MDCardID command can contain expressions that will be evaluated during the encoding, for example in order to use a value read during the same encoding.

Values enclosed in ${} will, as usually, be replaced with values from the process map before the encoding.
Values enclosed in !{} will be evaluated during the encoding. They can contain values read from the encoding and can also perform String operations on values.

Note that you can also combine ${} and !{}.

The following example uses a person's last name (from the process map) and a capitalized substring of the just read ICCSN:

[Fields]

MdCardIdDynamic=

(...)

[Description]

ICCSNField=ICCSN

MDCardID=MdCardIdDynamic

And MdCardIdDynamic is assigned the value

MdCardIdDynamic ← ${Person_Name}-!{ICCSN.substring(0,5).toUpperCase()}