Nexus' software components have new names:

Nexus PRIME -> Smart ID Identity Manager
Nexus Certificate Manager -> Smart ID Certificate Manager
Nexus Hybrid Access Gateway -> Smart ID Digital Access component
Nexus Personal -> Smart ID clients

Go to Nexus homepage for overviews of Nexus' solutions, customer cases, news and more.


Skip to end of metadata
Go to start of metadata

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.

Expand/Collapse All

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:

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

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

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

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

    Disable caching of card content
    [Cache]
    CacheValidity=0

Encodings

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

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

    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.

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.

  1. Define like this in the encoding description:

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

    [Fields]
    UseOpPin=
     
    [Description]
    Operator_Pin=...
    OperatorPinIsSOCredential=UseOpPin

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.

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.

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:

    [Encoding]
    Type=1024,Chip
    Devices=8710
     
    [Fields]
    AppList=
    ICCSN=
    PIN_FIELD=
    PUK_FIELD=
    OP_PIN_FIELD=
    P12CERTIFICATE_B=
    P12PASSWORD_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)".)

See also "Use operator PIN vs. PUK to log in" above.

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:

    [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

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

    Example: Exclude reader names
    [Reader]
    SkipReader=Microsoft Virtual Smart Card .*

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
    → follow 60524123 above.
  • 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
    follow 60524123 above

Other errors can be caused by the following:

  • Caching is erroneously enabled
    follow 60524123 above
  • The wrong middleware DLL is set in the encoding description
    follow 60524123 above
  • JAVA_HOME is not set or points to the wrong path
    follow 60524123 above

By default log files are written to %APPDATA%\Personal\log\ .