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 like this in the encoding description:
CODE[Description] InitToken=true InitialPUK=PUK_FIELD InitialLabel=#My Token Label SetPIN=true PIN=PIN_FIELD ClearFields=PIN_FIELD,PUK_FIELDDescription 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.
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:
CODE[Fields] Thumbprint= ... [Description] CardOSSkiThumbPrintField=ThumbprintDescription 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
Fieldssection 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.
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:
CODE[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).
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:
CODE[Fields] MDCardSN= ... [Description] MDCardSerialNumber=MDCardSNDescription 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
Fieldssection 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:
CODE[Fields] MDCardID= CardManagerKey= ... [Description] CardManagerKey=CardManagerKey MDCardID=MDCardIDDescription 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=ICCSNMDCardID=MdCardIdDynamicAnd MdCardIdDynamic is assigned the value
MdCardIdDynamic ← ${Person_Name}-!{ICCSN.substring(0,5).toUpperCase()}