KB5066835: KSP vs CSP transition and recommendations for Personal Desktop Client. Read more ->
Nexus Documentation
Nexus Documentation
Breadcrumbs

Encodings using IDplug middleware in Identity Manager

This article is new for Identity Manager 6.0.0.

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 IDplug version 4.6.1 and later versions.

IDplug versions below 4.6.1 are incompatible with Identity Manager.

Mandatory middleware configuration

After installing IDplug, make the configuration changes below for proper operation of the middleware with Identity Manager.

Ensure reliable card detection

The default cache policy of IDplug can cause stale card information to be reported to Identity Manager and other applications.
The middleware configuration needs to be adjusted to prevent this.

  1. Set the CheckCardModification property to true in C:\ProgramData\IDEMIA\IDPlugClassic\idplug.cfg :

    XML
    <?xml version="1.0"?>
<Settings Name="idplug_pkcs11" Type="Pkcs11Settings" Version="1.0">
    <!-- clear cached data if "lastupdate" value of card changes -->
    <Property Name="CheckCardModification">true</Property>
  
    <!-- ...other settings... -->
</Settings>

Card Types

Supported cards:

  • Cosmo X R6 (Model: ID-A, Applet Version: 1.1, 3DES admin key)

Encodings

Middleware DLL configuration

Configure the middleware DLLs as follows:

[Description]
PKCS11Library=C:/Program Files/IDEMIA/IDPlugClassic/DLLs/idplug-pkcs11.dll
MiniDriverLibraryWindows64=IdaMinidriver64.dll

Use the exact filenames/paths as given above.

You can also use PKCS11LibraryField=SOME_FIELD and MiniDriverLibraryWindows64Field=SOME_OTHER_FIELD to map external field values, as long as the fields are defined and their values resolve to the required filenames/paths.

Cosmo X R6 ID-A 1.1 Card Specifics

Card Properties

From the perspective of Identity Manager, the following admin and user credentials are supported:

  • CardManagerKey (also known as Admin Key or SO KEY in IDplug)

    • default usually 000000000000000000000000000000000000000000000000 (hex representation of 24-bytes 3DES key. Other key types are not supported)

    • change via CardManagerKey

  • PUK

    • default usually 12345678

    • change via current PUK

  • PIN

    • default usually 1234

    • change via current PIN

    • change and unblock via PUK

    • change and unblock via CardManagerKey

The following asymmetric key types are supported by Identity Manager on these cards:

Card Initialization

Card initialization will use the current PUK and CardManagerKey and set new values for PIN, PUK and CardManagerKey .

Furthermore, the PKCS#15 structure is reset, discarding any asymmetric keys and certificates.

  1. Set the following in the encoding description (making sure the fields are mapped to the correct values):

    # ... header goes here ...

[Fields]
OLD_PUK=
OLD_CARD_MANAGER_KEY=
NEW_PIN=
NEW_PUK=
NEW_CARD_MANAGER_KEY=

[Description]
# ... DLL setup goes here ...

InitToken=true
InitialPUK=CURRENT_PUK
PUK=NEW_PUK
PIN=NEW_PIN
CardManagerKey=OLD_CARD_MANAGER_KEY
NewCardManagerKey=NEW_CARD_MANAGER_KEY

If used on a blank card fresh from the factory, you may speed up the process by setting SetPin=true instead of InitToken=true, but this will NOT reset the PKCS#15 structure and thus retain asymmetric keys and certificates.

PIN Unblocking

Identity Manager supports both online and offline PIN unblocking of Cosmo X cards.

Offline

Offline PIN unblocking is handled in Credentials - Standard service tasks in Identity Manager by “Credentials: Calculate Minidriver Offline Unblocking Response” in combination with external software, such as IDplug Manager.

The blockCount value of the service task must be set to 3 for a correct 3DES response to be calculated.

Example workflow:

  1. user plugs in card with blocked PIN

  2. user opens IDplug Manager

  3. user selects “Unblock Password” tab

  4. user selects “SO KEY” as unblocking means
    => a challenge value is displayed

  5. user provides challenge to helpdesk

  6. helpdesk starts unblocking process in IDM Operator

  7. helpdesk enters the challenge as one continuous HEX string in process form

  8. service-tasks calculates response

  9. response is displayed in process form for helpdesk

  10. helpdesk provides response to user

  11. user enters response into IDplug manager, chooses a new PIN and unblocks

Online

Online PIN unblocking can be done by providing the new PIN and either the PUK or CardManager key, as shown in the examples below

  1. Unblock with PUK (making sure the fields are mapped to the correct values):

    # ... header goes here ...

[Fields]
PUK=

[Description]
# ... DLL setup goes here ...

SetPin=true
PIN=!FROM_USER_DIALOG_2_FIELD
InitialPUK=PUK

  2. Unblock with CardManagerKey (making sure the fields are mapped to the correct values):

    # ... header goes here ...

[Fields]
CARD_MANAGER_KEY=

[Description]
# ... DLL setup goes here ...

SetPin=true
PIN=!FROM_USER_DIALOG_2_FIELD
CardManagerKey=CARD_MANAGER_KEY

Troubleshooting

Certain operations fail if unsupported smart card is present

If cards (virtual or physical) that are not supported by IDplug are present, this can cause card encoding failures.
To avoid this, you can exclude the respective reader names.

  1. Set the IgnoredReaders collection in C:\ProgramData\IDEMIA\IDPlugClassic\idplug.cfg as follows:

    XML
    <?xml version="1.0"?>
<Settings Name="idplug_pkcs11" Type="Pkcs11Settings" Version="1.0">
    <!-- ignore all readers names containing "Virtual" or starting with "Micro", adjust as needed -->
    <Collection Name="IgnoredReaders">
        <Class Type="ReaderPattern" Version="1">
            <Property Name="Pattern">*Virtual*</Property>
        </Class>
        <Class Type="ReaderPattern" Version="1">
            <Property Name="Pattern">Micro*</Property>
        </Class>
    </Collection>
  
    <!-- ... other settings ... -->
</Settings>

Instead of blocking specific readers via IgnoredReaders, you can specify AllowedReaders to limit IDplug to a specific set of reader names, ignoring all others.

Middleware Logging

For troubleshooting purposes you can configure logging in the IDplug middleware.

  1. Set the LogPath property (and optionally LogLevel as well) in C:\ProgramData\IDEMIA\IDPlugClassic\idplug.cfg as follows:

    XML
    <?xml version="1.0"?>
<Settings Name="idplug_pkcs11" Type="Pkcs11Settings" Version="1.0">
    <!-- set the path to an existing folder you want the logs to be written to -->
    <Property Name="LogPath">C:\path\to\log\folder</Property>
    
    <!-- optional: specify log level from 0 (off) thru 7 (maximum), default: 4
    WARNING: increasing the log level can expose sensitive data! -->  
    <Property Name="LogLevel">4</Property>
  
    <!-- ...other settings... -->
</Settings>

Limitations

The following list is non-exhaustive:

  • Support is validated for the following card type only: Cosmo X R6 (Model: ID-A, Applet Version: 1.1, 3DES admin key) .

    • AES admin keys are unsupported.

    • 2-key 3DES admin keys are unsupported.

  • SM-protocols (PACE, Opacity) and features that depend on it, such as the signature slot (QSCD application), are unsupported.

  • Biometrics are unsupported.

  • Brainpool curves are unsupported.

  • Card labels are fixed and any attempt to change them is ignored by IDplug.