...
| Info |
|---|
This article is valid for Smart ID 23.04.1 and later. |
| Excerpt | ||
|---|---|---|
| ||
An encoding description contains the information for the electronic personalization of a card. |
...
Smart ID Identity Manager supports a variety of authentication technologies such as RFID and PKI. You can combine several technologies or RFID variants on a multi-functional or hybrid card. |
...
You import the encoding |
...
description from a file. The encoding description has a proprietary syntax and describes the information that will be sent to |
...
the identity Manager Production Client and hence to the encoding unit in the card printer or to the card terminal during electronic personalization. |
See also Set up an encoding description file in Identity Manager.
Format of an encoding description
...
...
The format of an encoding description
...
| title | Format of an encoding description |
|---|
The format of an encoding description is an INI file using sections, elements and values. There are standard sections in the file that contain information:
...
The Fields section is a list of fields that are used to hold variables in other sections. This is the data "interface" description which is parsed by the server applications to show a list of configurable values to the administrator.
...
The Description section is a collection of values that do not belong to a certain application.
...
The Application_X section represents an application, that is, one part of the chip that should be encoded in a certain way. The X stands for characters that identify the application in order to control the order of applications in which they are processed.
The encoding description file includes a header and basic definitions, explained below.
Header
...
| title | The Encoding section in the header |
|---|
Each encoding description file has a header, consisting of the Encoding section, for example:
| Code Block |
|---|
[Encoding]
Type=1024,Chip
Devices=8710
MessagingServerField=#LocalTestServer |
The header contains the following elements:
...
Type
...
Defines the identifier in decimal format for the encoding technology (1024 is used for smart cards), then separated by a comma, the corresponding descriptive and human readable name.
...
Devices
...
Defines the device identifier of the device type that can be used to process the encoding description.
It is a list of comma separated identifiers, though for PKI card encodings only a singe value is used, which must be one of the following:
- 8710 (standard value for most PKI encodings in PRIME)
- 8711 (single card operation in PRIME Explorer via Personal Desktop App - not applicable for any other use-case at the moment)
...
Subtype
...
As an alternative to Devices, the element Subtype may be used (but currently not for smart cards):
Contains an identifier in decimal format, that describes the sub group of the encoding. This is typically used for RFID encodings (for example, for the RFID encoding Mifare, there exist identifiers for Mifare Classic, Mifare DESfire, Mifare DESFire EV2, ...). Nexus Card SDK internally uses a mechanism to look for suitable devices, using a function like GetSupportedDevices(Type, SubType) to select a device for the processing of an encoding description. All these definitions are typically handled by tools (DSCBuilder) and runtime software (im2card32.dll, com32.dll) and therefore not further described here. Defined values are listed in the source files of Nexus Card SDK, globals.h and encodings.h.
...
MessagingServerField
...
is an INI file using sections, elements and values. There are standard sections in the file that contain information:
Section | Description |
|---|---|
Encoding | The |
Fields | The |
Description | The |
Application_X | The |
The encoding description file includes a header and basic definitions, explained below.
Header
Each encoding description file has a header, consisting of the Encoding section, for example:
| Code Block |
|---|
[Encoding]
Type=1024,Chip
Devices=8710
SkipEject=true
MessagingServerField=#LocalTestServer |
The header contains the following elements:
Element | Description |
|---|---|
Type | Defines the identifier in decimal format for the encoding technology (1024 is used for smart cards), then separated by a comma, the corresponding descriptive and human readable name. |
Devices | Defines the device identifier of the device type that can be used to process the encoding description. It is a list of comma separated identifiers, though for PKI card encodings only a singe value is used, which must be one of the following:
|
Subtype | As an alternative to Devices, the element Subtype may be used (but currently not for smart cards): Contains an identifier in decimal format, that describes the sub group of the encoding. This is typically used for RFID encodings (for example, for the RFID encoding Mifare, there exist identifiers for Mifare Classic, Mifare DESfire, Mifare DESFire EV2, ...). Nexus Card SDK internally uses a mechanism to look for suitable devices, using a function like GetSupportedDevices(Type, SubType) to select a device for the processing of an encoding description. All these definitions are typically handled by tools (DSCBuilder) and runtime software (im2card32.dll, com32.dll) and therefore not further described here. Defined values are listed in the source files of Nexus Card SDK, globals.h and encodings.h. |
SkipEject | This flag is useful for encoding the same card through multiple card jobs on a printer with integrated encoder. If present and set to true this will instruct Nexus Card SDK to leave the card in the printer after processing the card job containing this encoding (by default the card would be ejected after each card job). This flag is only relevant for encodings via Nexus Card SDK through card printers. For other use-cases it has no effect. |
MessagingServerField | Allows to select a Smart ID Messaging to be used with this encoding. This is optional and can be omitted if there is exactly one configuration available. You can refer to a field name like this: |
...
|
...
|
...
|
...
Alternatively, you can provide a fixed name via the # prefix: |
...
|
...
|
Basic definitions
...
...
Define PKCS#11 library
Some basic definitions are needed for PKI card encoding use cases.
Define the PKCS#11 library like this:
| Code Block |
|---|
[Description]
...
PKCS11Library=siecap11.dll
... |
Description of the elements:
Element | Description |
|---|---|
PKCS11Library | Defines the PKCS#11 library to be used (for example, siecap11.dll). You can also specify additional/alternative variants that specify the operating system and CPU architecture, for example, PKCS11LibraryWindows32= for 32 bit processes running on Windows. JPKIEncoder will select the most precise match. |
PKCSLibraryField | Can alternatively be used to refer to a mapped field containing the value. |
Depending on the requirements for an operating system and/or platform specific definition, use the following library definitions (as many definitions as required):
PKCS11LibraryWindows[64|32]=<library name>
PKCS11LibraryWindows[64|32]Field=<library name>
Recommendations:
Notations without 'Windows' are not recommended. Other operating systems are not supported at the moment.
Always state whether you refer to a 64Bit DLL or to a 32Bit one.
Operating system is always required when platform is specified.
Examples:
| Code Block |
|---|
[Fields]
P11LIB_32=
P11LIB_64=
...
[Description]
PKCS11LibraryWindows64=cardos_64.dll // if your middleware doesn't provide a 64-bit DLL just skip this entry
PKCS11LibraryWindows32=cardos.dll // if you don't need a 32-bit DLL just skip this entry
...
PKCS11LibraryWindows64Field=P11LIB_64 // It's recommended to provide the fields always as a pair and use null for the architecture, that doesn't apply
PKCS11LibraryWindows32Field=P11LIB_32
... |
| Note |
|---|
The You can provide |
...
PKCS#11 library definition for use with Nexus Personal Desktop App
Nexus PRIME uses Nexus Personal Desktop App to encode cards with PRIME Self-Service as well as optionally with PRIME Explorer.
For this use case you need to specify the middleware DLL as follows:
...
If the middleware requires a 32 bit DLL to operate properly (like Nexus Personal Desktop Client), make sure that PKCS11LibraryWindows32 is the only library definition in the encoding description. You also need to specify the absolute path with forward-slashes (even if the containing folder is in the PATH environment variable), for example:
| Code Block |
|---|
PKCS11LibraryWindows32=C:/Program Files (x86)/Personal/bin/personal.dll |
For other middlewares, define both PKCS11LibraryWindows32 and PKCS11LibraryWindows64, for example:
| Code Block |
|---|
PKCS11LibraryWindows32=cardos11.dll
PKCS11LibraryWindows64=cardos11_64.dll |
...
| title | Define MiniDriverLibrary |
|---|
Currently, MiniDriver support in PRIME is limited to the JPKIEncoder (that is, no support for Nexus Personal Desktop App), CardOS middleware and certain specific use cases (SKI, reading MDCardSerialNumber, writing CardD).
PRIME uses it to complement PKCS#11, not as a replacement - hence you still need to specify the PKCS#11 library definition shown above as well.
This is an example of a MiniDriver definition:
| Code Block |
|---|
[Description]
...
MiniDriverLibraryWindows32=cardoscm.dll
MiniDriverLibraryWindows64=cardoscm64.dll
... |
Description of the elements:
...
MiniDriverLibrary
...
Defines the MiniDriver library to be used (for example, cardoscm64). You can also specify additional/alternative variants that specify the operating system and CPU architecture, for example, MiniDriverLibraryWindows32= for 32 bit processes running on Windows. JPKIEncoder will select the most precise match.
Recommendations:
As MiniDriver libraries are specific to Windows, it is highly recommended to use this more specific nomenclature:
...
multiple of these parameters in your description file and even through the mapped fields at the same time. The best match will automatically be selected, that is, the more specific parameter wins. However, if a parameter in the description file defines the exact same as a parameter defined in the mapped fields, then the one from the mapped fields wins and will be selected because of higher priority. |
PKCS#11 library definition for use with Smart ID Desktop App
Identity Manager uses Smart ID Desktop App to encode cards with Smart ID Self-Service as well as optionally with the Identity Manager Operator.
For this use case you need to specify the middleware DLL as follows:
Always use the DLL suffix of the name and be clear what type of DLL you are referring to.
If the middleware requires a 32 bit DLL to operate properly (like Nexus Personal Desktop Client), make sure that PKCS11LibraryWindows32 is the only library definition in the encoding description. You also need to specify the absolute path with forward-slashes (even if the containing folder is in the PATH environment variable), for example:
Code Block PKCS11LibraryWindows32=C:/Program Files (x86)/Personal/bin/personal.dllFor other middlewares, define both PKCS11LibraryWindows32 and PKCS11LibraryWindows64, for example:
Code Block PKCS11LibraryWindows32=cardos11.dll PKCS11LibraryWindows64=cardos11_64.dll
Define MiniDriverLibrary
MiniDriver support in card encodings is limited to certain use-cases for the CardOS middleware (Secure Key Injection, reading MDCardSerialNumber, writing CardID).
Identity Manager uses it to complement PKCS#11, not as a replacement - hence you still need to specify the PKCS#11 library definition shown above as well.
This is an example of a MiniDriver definition:
The same definition also applies for while using Smart ID Desktop App.
| Code Block |
|---|
[Description]
...
MiniDriverLibraryWindows32=cardoscm.dll
MiniDriverLibraryWindows64=cardoscm64.dll
... |
Description of the elements:
Element | Description |
|---|---|
MiniDriverLibrary | Defines the MiniDriver library to be used (for example, cardoscm64). You can also specify additional/alternative variants that specify the operating system and CPU architecture, for example, MiniDriverLibraryWindows32= for 32 bit processes running on Windows. JPKIEncoder will select the most precise match. |
Recommendations:
As MiniDriver libraries are specific to Windows, it is highly recommended to use this more specific nomenclature:
MiniDriverLibraryWindows[platform]=<library name>
MiniDriverLibraryWindows[platform]Field=<library name>
where platform is 32 or 64.
Supported versions for SKI
Identity Manager version 23.0.4.1 has limited SKI support, only use-cases for Identity Manager Operator were possible.
Full SKI support, including Self-Service-based process execution, is available from IDM 23.04.8 and onward.
Smart ID Desktop App supports SKI from version 1.8.12 and onward.
Example:
Same as with PKCS#11 library definitions, you can also specify absolute paths and use
...
the Field variants to specify mapped fields containing the name of the library:
| Code Block |
|---|
MiniDriverLibraryWindows32=c:\windows\SysWoW64\cardoscm.dll MiniDriverLibraryWindows64=c:\windows\system32\cardoscm64.dll MiniDriverLibraryWindows32Field=MD32_FIELD MiniDriverLibraryWindows64Field=MD64_FIELD |
...
Define ApplicationList
This is an example of ApplicationList definition:
| Code Block |
|---|
[Description]
...
ApplicationList=ABC
... |
Description of the elements:
Element | Description |
|---|---|
ApplicationList | Contains the list of applications that is used to access a card. Each digit activates the corresponding Application. For example, ABC > Application_A, Application_B, Application_C. Each application typically (but not exclusively) represents a single certificate to be encoded. There are also non-certificate applications (for example, CardOS APDU scripts). |
...
Encode a subset of applications
You can encode a subset of all applications defined in your encoding description file through mapped fields. Define there, for example, just “BC” to encode just application B and C without application A. You set a field and a special element ApplicationListField which points to the field instead the regular property ApplicationList:
| Code Block |
|---|
[Fields]
AppList=
[Description]
ApplicationListField=AppList
[Application_A]
...
[Application_B]
...
[Application_C]
... |
Description of the elements:
Element | Description |
|---|---|
ApplicationListField | Defines that the application list will be taken from a field mapping. |
Certificate template related definition
You must define a certificate template in order to perform any certificate or key related operation for a user (for example, key archival, key recovery, etc.).
...
There are two ways to define certificate template details in the encoding description file.
...
Certificate template definition without field mapping
Certificate template definition can be defined via
...
the CertTempl element in the
...
respective Application
...
section of the encoding description:
| Code Block |
|---|
[Fields]
...
[Description]
...
[Application_A]
CertTempl=MyCertTemplate |
Description of the elements:
Element | Description |
|---|---|
CertTempl | Defines the |
...
Identity Manager certificate template name to be used, which is configured to reference the CA and the Token Procedure on the CA. |
...
Certificate template definition with field mapping
Certificate template definition can also be defined via field mapping fields. This can be achieved via
...
the CertTemplField element in the
...
respective Application
...
section of the encoding description. Also add the field names to
...
the Fields
...
section.
| Code Block |
|---|
[Fields]
...
MyCertTemplField1=
MyCertTemplField2=
[Description]
...
[Application_A]
...
CertTemplField=MyCertTemplField1
[Application_B]
...
CertTemplField=MyCertTemplField2 |
Description of the elements:
Element | Description |
|---|---|
CertTemplField | Defines the certificate template mapped field name. This mapped field value will be considered as cert template name. You can also use a JUEL expression as shown above for MyCertTemplate1 to reference a datapool field. Non-datapool process variables currently are not fully supported. |
| Note |
|---|
|
...
and |
...
Additional information
| Expand | ||
|---|---|---|
| ||
...