- 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 to use Application Protocol Data Unit (APDU) commands in an encoding description.
This feature is specific to PKI cards and still requires a PKCS#11 middleware for certain operations. RFID cards are not supported - refer to Nexus Card SDK for encoding of RFID cards.
Smart ID 20.11 introduces breaking changes to the syntax of APDU scripts. Existing scripts must be changed to the new syntax - see section PIN line format for details.
Important information regarding Smart ID 20.11
Some encoding description parameters were renamed with Smart ID 20.11, so you must adjust any encoding description which includes APDU scripts:
Two supported channels
Since Smart ID 20.11 there are two supported channels for sending APDUs within a PKI card encoding:
Prerequisites and features
About APDU commands
You can have spaces in APDU commands for better readability:
Smart ID 20.11 allows input and output variables (with some exceptions in PIN lines) to use a format other than hex strings.
To configure the format, set the prefix <hex> / <string> / <base64> in front of the variable name (hex is default if no prefix is given).
The output field name is optional and can be omitted if you are not interested in the response data, for example:
This format is for non-parameterized APDUs only, which are passed in full as hex-string, with the output type being configurable, see this example:
This format allows for parametrization of the APDU's command data, which can be read from fields and concatenated, for example:
If a field has an empty or null value, it will resolve to an empty byte array, otherwise the field value will be parsed according to the specified input format (refer to the section "Configure format for variables").
The expected result length is given as a decimal value, for example:
You can have just the header plus field(s) and/or result length, for example:
You can include fixed hex values (prefixed with 0x) in the command-data as well, for example:
This custom format allows for displaying a PIN dialog where the user can choose a new PIN.
Optionally input of an existing transport PIN can be requested and/or a PIN validation rule can be specified. Specifying a PIN validation rule is highly recommended to avoid wasting cards due to repeated entering of an incorrect PIN.
Also, you can now specify the format of the output variables to be something other than a hex string, if desired.
This custom format allows for calculating a response to a challenge based on a given key (see GET CHALLENGE / EXTERNAL AUTHENTICATION commands in the CardOS firmware docs).
It supports three C/R algorithms, none of which use any padding, so make sure the input has the proper size:
The format in an APDU script looks as follows:
A suitable challenge can be acquired as follows:
Each challenge is valid within the same session until it is used by an authentication command or replaced with a new challenge.
Since Smart ID 20.11, response data can be returned as UTF-8 string or base64 string instead of hex, so you do not have to do such conversion in the process anymore.
Refer to section "Configure format for variables" for details.
Examples of APDU scripts
The examples below are valid for Smart ID 20.11 and are not backwards compatible.
Read version and patch
Write ef gdo (Elementary File Global Data Object)
Change ma key
Encodings using APDU scripts
The examples below are valid for Smart ID 20.11 (dropping the prefix CardOS from APDU parameter names) and are not backwards compatible. Also they are configured for exclusive use with Smart ID Desktop App (Devices=8711).
These are example encoding using the script examples above (set the "read" flag on CARDOS_VERSION, PACKAGE_VERSION and APDU_RESPONSE_CODES_*, as those provide output. The Application_X section represents an application, that is, one part of the chip that should be encoded in a certain way.
This article is valid for Smart ID 20.11 and later.