# Page History

## Key

• This line was removed.
• Formatting was changed.
Comment: Updates regarding PIN and PUK for 21.04.3

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.

Expandall

# Mandatory middleware configuration

Anchor
 Configure PIN encryption certificate Configure PIN encryption certificate
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:

Expand
title Configure PIN encryption certificate
1. Edit C:\Program Files (x86)\Personal\config\iD2ppa.cfg and set the following (with the appropriate path instead of the example given here):

Code Block
title Example: Set path to PIN encryption certificate
[PIN Encryption]
File=C:\path\to\the\certificate.crt

Note

The certificate you reference here can be an arbitrary dummy certificate, unless you need a specific certificate for non-Identity Manager use-cases.

Anchor
 Disable caching of card content Disable caching of card content

Expand
title Disable caching of card content

Caching can cause problems during encoding due to outdated data, so you have to disable it.

1. Set the following in C:\Program Files (x86)\Personal\config\Personal.cfg (system-wide base config) and/or in %APPDATA%\Personal\config\Personal.cfg (per-user override config - this takes precedence, if set in both):

Code Block
title Disable caching of card content
[Cache]
CacheValidity=0

# Encodings

Anchor
 Middleware DLL configuration Middleware DLL configuration

Expand
title Middleware DLL configuration

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.

1. Set the following in the encoding description (note the explicit use of PKCS11LibraryWindows32 and the absence of PKCS11Library and PKCS11LibraryWindows64 definitions):

Code Block
title Configure DLL
[Description]
PKCS11LibraryWindows32=C:/Program Files (x86)/Personal/bin/personal.dll

Note

For encodings that use JPKIEncoder (usually via Nexus Card SDK), you also need to set the JAVA_HOME environment variable to the root folder of a 32 bit JRE, as a 64 bit JRE cannot load 32 bit DLLs.

This does not apply for encodings using Smart ID Desktop app, as it does not use Java.

Expand

Nexus Personal Desktop Client can create cards that require the operator PIN instead of the PUK as credential which use different credentials to log in as administrative user (user type CKU_SO as defined in the PKCS#11 standard). For those cards

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.

1. Define like this in the encoding description:

Code Block
[Description]
Operator_Pin=...
OperatorPinIsSOCredential=#true

Description of the elements:

ElementDescription
OperatorPinIsSOCredential=The default value is false, which works for the standard Identity Manager PCM encodings, that use the PUK as SO credential.

2. Instead of setting the value to true or false directly in the the encoding description file (the DSC file), you can also use a mapped field, like this:

Code Block
[Fields]
UseOpPin=

[Description]
Operator_Pin=...
OperatorPinIsSOCredential=UseOpPin

Expand
title Limited support for changing the PUK

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:

• Cosmo 7
• Cosmo 8.2

For all other cards there is no way to change the PUK with this middleware.

Note

This feature requires Identity Manager 21.04.3 or higher - changing the PUK with Nexus Personal Desktop client is blocked in previous Identity Manager versions.

Expand
title Set CMSCardSerialNumber with Personal Desktop Client

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.

1. Define like this in the encoding description:

Code Block
[Encoding]
Type=1024,Chip
Devices=8710

[Fields]
AppList=
ICCSN=
PIN_FIELD=
PUK_FIELD=
OP_PIN_FIELD=
P12CERTIFICATE_B=
PRIME_FIELD_WITH_CARD_SERIAL=

[Description]
32BitPKCS11Library=true
PKCS11Library=personal.dll
iccsnfield=ICCSN
UseSelectCriteriaIccsn=false
InitToken=true
InitialPUK=PUK_FIELD
Operator_Pin=OP_PIN_FIELD
InitialLabel=#01234567890123456789012345678901
ChipProfile=PRIME_CardOS5_personal.cpf
PIN=PIN_FIELD
CMSCardSerialNumber=PRIME_FIELD_WITH_CARD_SERIAL
ApplicationListField=AppList

[Application_A]
CardSerialNumberField=PRIME_FIELD_WITH_CARD_SERIAL
CertTempl=EncHardCodedValuesP10
ObjectCriteria=CKO_PUBLIC_KEY,CKA_LABEL,string,"Digital Signature"

[Application_B]
CardSerialNumberField=PRIME_FIELD_WITH_CARD_SERIAL
CertTempl=EncHardCodedValues
KeyArchivalRequest=true
WriteP12Data=true
Certificate=P12CERTIFICATE_B
P12PASSWORD=P12PASSWORD_B

Description of the elements:

ElementDescription
InitToken=trueThis is the trigger to run the CardProductionPostProcessor which actually sets the card secrets for the token on the Nexus CM.
CMSCardSerialNumber=PRIME_FIELD_WITH_CARD_SERIALMaps the card serial number to be written on the physical smart card and the token on the Nexus CM for setting the card secrets.

These two mappings are used to ensure that a generated (either by Identity Manager or by Certificate Manager) card serial number can be used over several applications.

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)".)

Expand
title Delete token profile

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

1. Define like this in the encoding description:

Code Block
[Description]
DeleteProfile=true

This flag is currently not supported on other middlewares and its use will result in an error.

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.

Examples

• MakeCardEraseable() at the start and BurnFuse() at the end => anonymous erase should work
• Neither MakeCardEraseable() at the start nor BurnFuse()  => anonymous erase should work
• BurnFuse() at the end, MakeCardEraseable() missing => anonymous erase will fail

An exception will be thrown if the "Card Eraser" object is not found.

# Troubleshooting

Expand
title Certain operations fail if virtual smartcard is present

The Personal Desktop Client middleware can sometimes get confused by virtual smartcards on Windows (for example, GENERAL_ERROR on C_GetProperty). To avoid this you can exclude the respective reader names.

1. Set the following in C:\Program Files (x86)\Personal\config\Personal.cfg (system-wide base config) and/or in %APPDATA%\Personal\config\Personal.cfg (per-user override config - this takes precedence, if set in both):

Code Block
[Reader]
SkipReader=Microsoft Virtual Smart Card .*

Expand
title InitTokenPPA fails

If the above error shows up in the jpki_encoder log when trying to initialize a card, this is usually caused by one of the following:

• PIN encryption certificate is not correctly configured in the middleware
• Card profile configuration file (CPF) used in the Identity Manager encoding description does not match the card type to be initialized
use a CPF file that is properly configured for the given card type
• JPKIEncoder runs on a 64 bit JRE or the DLL path is incorrect

Expand
title Miscellaneous error causes

Other errors can be caused by the following:

• Caching is erroneously enabled
• The wrong middleware DLL is set in the encoding description