- This line was added.
- This line was removed.
- Formatting was changed.
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 Nexus Personal Desktop Client.
Mandatory middleware configuration
After installing and updating Nexus Personal Desktop Client, make the following configuration changes for proper operation of the Nexus Personal Desktop Client middleware with Identity Manager:
Caching can cause problems during encoding due to outdated data, so you have to disable it.
As the 64 bit version of the Nexus Personal Desktop Client middleware DLL cannot initialize cards, it is necessary to set only the path to the 32 bit DLL in the encoding description.
Nexus Personal Desktop Client can create cards which use different credentials to log in as administrative user (user type CKU_SO as defined in the PKCS#11 standard).
Depending on the settings in the card profile (CPF) used to initialize the card, either the PUK or the operator PIN will be used.
In case of the latter, the PUK is only used for the Personal-specific PIN unblocking method, but not as administrative login.
Nexus Personal Desktop Client 5.7.1 or lower does not support changing the PUK.
Nexus Personal Desktop Client 5.7.2 or higher does support changing the PUK, but only for specific cards:
For all other cards there is no way to change the PUK with this middleware.
The serial number is created with a number range in Identity Manager and then set on the card, the certificates and in the CM token. The handling of the card secrets is done on the server by CardProductionPostProcessor. This ensures that both possible certificate request processes (P12 requests, P10 requests) together with token creation on Nexus Certificate Manager can be handled.
Usually you need an administrative login to write the card serial number. This mechanism is described in Certificates and keys in Identity Manager (heading "Create external card serial number and reuse value (CM)".)
See also "Use operator PIN vs. PUK to log in" above.
By setting the "CMSCardSerialNumber", you override the chip serial number, which acts as a default value of the ICCSN. Most applications identify the card with this overridden number. However, in some cases the original chip serial number is needed. There are three use cases working on the ICCSN:
The three use cases above are fully supported by the "useChipSerialAslccsn" flag, which allows to ignore the overridden value provided via "CMSCardSerialNumber".
There is a flag that allows to delete the entire token profile, and return the card to the uninitialized state. This is done by using a virtual object called "Card Eraser" available on certain cards (for example, CardOS 4.4, 5.x, certain Gemalto cards...).
If a PIN or PUK is also passed with the encoding description, the highest of those is used to log in, otherwise, an attempt to delete anonymously is done.
Neither PIN nor PUK provides a benefit over anonymous deletion - there is a third credential (operator PIN), which Personal Desktop Client requires to delete the card, but Identity Manager does not yet support to log in with that.
Whether or not you will be able to anonymously erase the card depends on the CPF file that was used to initialize the card.
An exception will be thrown if the "Card Eraser" object is not found.
When pre-personalizing a card via Key Generation System (KGS) (see Produce smart cards in Certificate Manager), you can store a set of PINs on the card, which are encrypted with the public key of a so-called PIN Encryption Certificate.
An example card profile (CPF) for pre-personalization could look like this:
See the PPA Scripting Language documentation PDF for more details (available in the doc.zip file for every Personal Desktop Client release in the support portal.)
Configure encoding description
If a virtual smartcards are present on Windows, this can cause failures when using the Personal Desktop Client middleware (for example, GENERAL_ERROR on C_GetProperty). To avoid this, you can exclude the respective reader names.
If this error shows up in the jpki_encoder log, when trying to initialize a card, this is usually caused by one of the following:
Other errors can be caused by the following:
By default log files are written to %APPDATA%\Personal\log\ .
This article is valid for Smart ID 22.04.1 2 and later