Skip to main content
Skip table of contents

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:

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

    Description of the elements

    ElementDescription
    InitToken=trueTriggers 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:

    1. a field list
    2. a given fix value
    3. 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:

    4. a middleware/reader inherent PIN retrieving mechanism that is, for instance and typically, a separate reader PINPAD (!FROM_PROTECTED_AUTHENTICATION_PATH).
    5. 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


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


  1. Define like this in the encoding description:

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

    Description of the elements

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

  2. Set the Read attribute in the Encoding Fields tab to get the value into your datamap.
  3. 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:

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

    Description of the elements

    ElementDescription
    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:

    CODE
    [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

    ElementDescription
    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

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: 

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:

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

    Description of the elements

    ElementDescription
    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:

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

    Description of the elements

    ElementDescription
    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()}

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.