Skip to main content
Skip table of contents

Reader/card selection and information in Identity Manager

This article includes updates for Identity Manager 5.0.1. Old releases are not affected.

An encoding description contains the information for the electronic personalization of a card. You import the encoding description from a file. This article describes how you create descriptions that handle general card information as well as reader/card selection. This can be used in Smart ID Identity Manager.

See also Structure of an encoding description in Identity Manager.

Read ICCSNs from inserted cards

This describes how to find out all Integrated Circuit Card Serial Numbers (ICCSN) of all smartcards inserted into a card reader, or to have an overview of them, and read and return them into a field. The values will be separated by ',' (comma). If no token is found the action will fail.

This can and shall not be combined with other encoding description options. Reading all ICCSN of all inserted smartcards is a single operation and skips other encoding parts!

Define like this in the encoding description:

CODE
[Fields]
ICCSNS_OF_ALL_TOKEN=
...
 
[Description]
RetrieveAllTokens=true
AllTokensIccsnsField=ICCSNS_OF_ALL_TOKEN

Description of the elements

Element

Description

RetrieveAllTokens=true

Triggers to read all ICCSNs of inserted smartcards.

AllTokensIccsnsField

Defines the field into which the ICCSNs of all smartcards are written.

UseICCSNwithATR=true

Triggers to suffix the Answer To Reset (ATR) to the ICCSN, separated by a hyphen, like [ICCSN]-[ATR], for example, 2153000082960364-3BF99600008131FE45454F4E43617264563173

Select card to be used by ICCSN

You can select the smartcard to be used for the defined applications of the encoding description via ICCSN.

Define like this in the encoding description:

CODE
[Fields]
ICCSN=
...
 
[Description]
UseSelectCriteriaIccsn=true
SelectCriteriaIccsn=ICCSN
UseICCSNwithATR=true

Description of the elements

Element

Description

UseSelectCriteriaIccsn=true

Triggers to use the ICCSN as the criteria for selecting a smartcard for this encoding description.

SelectCriteriaIccsn

Defines to use the ICCSN of the related field that also has to be defined in the Fields section.

UseICCSNwithATR=true

Expects  the Answer To Reset (ATR) to be suffixed to the ICCSN, separated by a hyphen, like [ICCSN]-[ATR], for example, 2153000082960364-3BF99600008131FE45454F4E43617264563173. This is done to uniquely identify a token, even so different models are used, and the ICCSN is only expected to be unique within the same model.

Limitation: When encoding via the Nexus Card SDK, the reader selected by the Nexus Card SDK overrides selection by ICCSN unless that reader is integrated into a card-printer.

Note:

For PKCS#11 middlewares the target ICCSN is validated when opening a user- or SO-session on the token - encoding will abort on ICCSN mismatch.

Add ICCSN of a card to the mapped fields

You can add the ICCSN of the used smartcard to the mapped fields, right after the encoding has finished.

Define like this in the encoding description:

CODE
[Fields]
ICCSN=
...
 
[Description]
IccsnField=ICCSN

Description of the elements

Element

Description

IccsnField

Defines the field into which the ICCSN of the used smartcard has to be written. If this definition is missing, no ICCSN will be returned. Note that the related field also has to be defined in the Fields section and have the Read attribute (see below).

UseICCSNwithATR=true

Triggers to suffix the Answer To Reset (ATR) to the ICCSN, separated by a hyphen, like [ICCSN]-[ATR], for example, 2153000082960364-3BF99600008131FE45454F4E43617264563173

Set the Read attribute in the Encoding Fields tab to get the value into your datamap:

ReadIccsn.jpg

Add ATR of a card to the mapped fields

You can add the Answer To Reset (ATR) of the used smartcard to the mapped fields right after the encoding has finished.

Define like this in the encoding description:

CODE
[Fields]
ATR=
...
 
[Description]
AtrField=ATR

Description of the elements

Element

Description

AtrField

Defines the field into which the ATR of the used smartcard has to be written. If this definition is missing, no ATR will be returned. Note that the related field also has to be defined in the Fields section and have the Read attribute (see below).

Set the Read-attribute in the Encoding Fields tab to get the value into your datamap:

readatr.jpg

Read the smartcard's OS version

Support for the OsVersionField field definition has been removed from encoding descriptions.

This was only intended for CardOS smartcards and reading the OS version can be achieved via APDU command instead.

This functionality is supported for CardOS smartcards only.

Sample APDU command for reading OS version which can be specified in an APDU script file:

CODE
RAW[VERSION]:00CA018202 

Where

[00] - denotes class

[CA] - denotes instruction

[01] - first parameter

[82] - second parameter

[02] - expected length

This APDU command will allow to read the value from the card and return it in a mapped field named VERSION.

Return values

If the command is successful, it will return two bytes as hex values representing the OS version in ATR coding. Otherwise it will return an empty string.

  • Byte 1: OS Class (1st historical byte in Default ATR)

  • Byte 2: OS Version (2nd historical byte in Default ATR)

  • For CardOS V5.0: C901

Read the smartcard's package information

Support for the PackageInformationField field definition has been removed from encoding descriptions.

This was only intended for CardOS smartcards and reading the package information can be achieved via APDU command instead.

This functionality is supported for CardOS smartcards only.

Sample APDU command for reading package info which can be specified in an APDU script file:

CODE
RAW[PACKAGEINFO]:00CA0188FF 

Where

[00] - denotes class

[CA] - denotes instruction

[01] - first Parameter

[88] - second parameter

[FF] - expected length

This APDU command will allow to read the value from the card and return it in a mapped field named PACKAGEINFO.

Return values

If the command is successful, it will return the package information in TLV encoding. If no package information is available or the command failed, it will return an empty string. If more than one package is loaded, these will be concatenated in the response.

Example with a single package:

  • A string for a single package will look like this (spaces added for better readability):

    • E1 0B 53 06 03 04 13 01 C9 01 8F 01 00

    • Response (Tag: E1; Length: 0B)

    • Package Information (Tag: 53; Length: 06)

    • PID (Tag: here 03, represents the MID; Length 04; Value is the PID: 13 01 C9 01)

    • State (Tag: 8F; Length: 01; Value: 00)

  • Summary: Manufacturer ID (MID): 03; Package ID (PID): 13 01 C9 01; State: 00

Example with multiple packages:

  • A string for a single package will look like this (spaces added for better readability):

    • E1 0B 53 06 11 04 06 01 C9 03 8F 01 01E1 0B 53 06 11 04 09 01 C9 03 8F 01 01E1 0B 53 06 03 04 13 01 C9 03 8F 01 01

    • Each package starts with the tag "E1". Split at this package and proceed as in the example with a single package.

  • MIDs: 01..3F used for Atos packages.

  • States: 0 = disabled; 1 = enabled; 2 = terminated

Select card with reader selection popup

To select a specific card when multiple cards are attached to the system, you have two options:

  • provide the specific ICCSN or

  • use a card selection popup.

The latter is described here. This will display the CN attributes of the first found user certificate available on the card (however, at the maximum of currently 100 characters to limit the popup width). 

Define like this in the encoding description:

CODE
[Description]
RetrieveTokenByUserSelection=true
...

Description of the elements

Element

Description

RetrieveTokenByUserSelection=true

Triggers to use a reader selection popup.

Features

  • The syntax of each option is: [PC/SC reader name] [CN of the first user certificate or the text "empty card"]

  • An empty card is defined by having no user certificate, for example, a blank (not initialized) card, a just initialized card, ...

  • Currently, a reader having a card without a user certificate but with just intermediate and root certificates will be also regarded as empty card.

  • Contactless slots are also displayed.

  • The read operations on the smartcard are limited for performance, that is, we stop reading as soon as we find the first user certificate.

  • The displayed options are sorted by their reader names alphabetically.

  • An option can have a maximum of currently 100 characters to limit the popup width. If longer, 97 character plus "..." will be displayed.

  • If just one possible option could be found (for example, multiple readers available but only one card inserted) that option will automatically be selected (and logged) and the encoding further processed on it without displaying the reader selection popup.

  • When having no cards inserted into one of the available readers in a system, an EndProcessException with a detailed message will be thrown: "No inserted cards could be found while searching all available reader slots!"

  • Reader selection gets displayed before any optional PIN or PUK popups.

  • When aborting the reader selection popup by clicking on the "cancel" button, an EndprocessException will be thrown and logged.

Read token info as JSON

You can read the token info structure from the card as JSON.

Define like this in the encoding description:

CODE
[Fields]
TOKEN_INFO_OUTPUT=
(...)
[Description]
TokenInfoJsonField=TOKEN_INFO_OUTPUT

In the configuration of the mapped fields, map it to a process variable and set the Read attribute (like in the examples for reading ICCSN / ATR above).

Return values for most middlewares

Example token info JSON (standard PKCS#11 middlewares)
CODE
{
    "label": "Example Label",
    "manufacturerID": "Example Company",
    "model": "Example Card",
    "serialNumber": "17460000021011",
    "flags": 13108229,
    "flagNames":["RNG","LOGIN_REQUIRED","TOKEN_INITIALIZED","USER_PIN_TO_BE_CHANGED","SO_PIN_LOCKED","SO_PIN_TO_BE_CHANGED"],
    "ulMaxSessionCount": 4294967295,
    "ulSessionCount": 0,
    "ulMaxRwSessionCount": 4294967295,
    "ulRwSessionCount": 1,
    "ulMaxPinLen": 24,
    "ulMinPinLen": 6,
    "ulTotalPublicMemory": 198144,
    "ulFreePublicMemory": 12091,
    "ulTotalPrivateMemory": 198144,
    "ulFreePrivateMemory": 12091,
    "firmwareVersion": {
        "major": 1,
        "minor": 2
    },
    "hardwareVersion": {
        "major": 3,
        "minor": 4
    },
    "utcTime": "2022123123554100"
}

utcTime is empty unless the token is equipped with a clock.
Flag names are listed without the "CKF_"-prefix.

Return values for Idopte middleware

example token info JSON (idopte middleware)
JS
{
  "label":"Example Label",
  "manufacturerID":"Example Company",
  "model":"ChipDoc",
  "serialNumber":"2222000020014711",
  "jcopVersion":"4.5"
}

The values of model and jcopVersion are fixed (usually serialNumber is fixed as well, except for rare cases), but other values may change during the lifetime of the card.
Even manufacturerID can change after ADF activation on JCOP 4.5 cards.
The value of jcopVersion is either "3" or "4.5" for supported cards.

If you want to use conditional process flows based on the JCOP version, you can use a script-task to extract the jcopVersion value into its own process variable. See the example below:

Groovy script: extract jcopVersion from TokenInfoJson
GROOVY
String json = binding.variables["TokenInfoJson"].toString();
binding.variables["jcopVersion"] = de.nexus.encodingutils.remote.p11.json.Json.of(json).get("jcopVersion").asString().value();
JavaScript errors detected

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

If this problem persists, please contact our support.