• APDU scripts have to be bundled in the DSZ file that is uploaded. The file extension shall be apdu.
• CardOS middleware version needs to be at least 5.4W14
• For APDU encodings through Nexus CardSDK, you need at least CardSDK version 5.4.0.17.

• APDU commands can either be given as full hex string or with parameterized command data read from field(s).
• APDU commands have support for challenge response algorithms.
• Comments are allowed, starting with #.
• Empty lines are allowed.
• Do not do other things in the application (like requesting certificates), use dedicated applications for APDUs instead.
• Applications reference a script by filename.
• You can execute one script containing potentially multiple APDUs per application-
• An anonymous session is used, PRIME 3.10.2 introduces authentication with challenge/response keys via APDU.

PRIME 3.10.2 allows spaces within the APDU commands for better readability, which older versions do not:

RAW[OUT]:00CA018202     # this is always OK
RAW [OUT]: 00CA0182 02  # this fails in 3.10 but is allowed in 3.10.2

This format is for non-parameterized APDUs only, which are passed in full as hex-string, for example:

RAW[MY_OUT_FIELD]:00CA018202

The output field name is optional and can be omitted if you are not interested in the response data, for example:

RAW[]:00AABBCC

This format allows for parametrization of the APDU's command data, which can be read from fields and concatenated, for example:

DYN[]:002C0001;NEW_PUK+NEW_PIN

If a field has an empty or null value, it will resolve to an empty byte array, otherwise the field value will be parsed as hex string.

The expected result length is given as a decimal value, for example:

DYN[OUTPUT]:00CA0188;;255	

You can have just the header plus field(s) and/or result length, for example:

PRIME 3.10.2 extends the DYN format to include fixed hex values 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.

PIN[OUTPUT]:TARGET_PIN_DESCRIPTION_FIELD;TRANSPORT_PIN_FIELD;VALIDATION_RULE;OLD_VALUE_OUTPUT

For example:

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:

CR[OUTPUT]:ALGORITHM;KEY;CHALLENGE

For example:

A suitable challenge can be acquired as follows:

DYN[CHALLENGE]:00840000;;16 # get 16 bytes challenge, store in CHALLENGE var

Each challenge is valid within the same session until it is used by an authentication command or replaced with a new challenge.

As response data can be arbitrary binary data, and they are always stored as hex string in the output field.

If they are to be interpreted as, for example, UTF-8 string, conversion has to be done on the process side.

Read version and patch

# this is an APDU script
 
RAW[CARDOS_VERSION]:00CA018202  # read CardOS version into field CARDOS_VERSION
DYN[PACKAGE_INFO]:00CA0188;;255 # read package info into field PACKAGE_INFO

Write ef gdo (Elementary File Global Data Object)

# this is an APDU script (written for a specific card profile, yours may vary)
 
RAW[]:00A4080C022F02                        # select EF GDO file
DYN[]:00D60000;HELLO+CARDOS_VERSION+WORLD;  # write values of fields HELLO, CARDOS_VERSION and WORLD (concatenated) to selected file

Change ma key

# PRIME 3.10.2 is needed for this one!
# this is an APDU script (written for a specific card profile, yours may vary)
# this changes the 3DES key with ID 8 from the default FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF to the value of the NEW_KEY field
 
DYN[CHALLENGE]:00840000;;16              # get 16 bytes challenge
CR[RESPONSE]:MAC_DES3;0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF;CHALLENGE # calc response
DYN[]:008200 08;RESPONSE;                # EXTERNAL AUTHENTICATE APDU for keyId 8
DYN[]:902410 08;0x8F18+NEW_KEY           # change key with keyId 8 to NEW_KEY with options 8F18

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.

1. Define like this is the encoding description:
   

   [Encoding]
   Type=1024,Chip
   Devices=8710
    
   [Fields]
   APDU_RESPONSE_CODES_A=
   APDU_RESPONSE_CODES_B=
   APDU_RESPONSE_CODES_C=
   NEW_KEY=
   HELLO=
   WORLD=
   CARDOS_VERSION=
   PACKAGE_INFO=
    
   [Description]
   PKCS11LibraryWindows32=cardos11.dll
   PKCS11LibraryWindows64=cardos11_64.dll
   ApplicationList=ABC
    
   [Application_A]
   CardOsApduFile=read_version_and_patch.apdu
   CardOsApduResponseCodesField=APDU_RESPONSE_CODES_A
    
   [Application_B]
   CardOsApduFile=write_ef_gdo.apdu
   CardOsApduResponseCodesField=APDU_RESPONSE_CODES_B
    
   [Application_C]
   CardOsApduFile=change_ma_key.apdu
   CardOsApduResponseCodesField=APDU_RESPONSE_CODES_C

2. Specify the correct order in ApplicationList=, especially if one script depends on the output of another.

3. It is optional to set the CardOsApduResultField for execution, but it is needed if you want to process the result code data.
   Result code data uses the following format:
   
   

   hexResponseCodeOfFirst;hexResponseCodeOfSecond;etc.

   For example, these are the values if all scripts in the above encoding returned code 0x9000:

   APDU_RESPONSE_CODES_A

   9000;

   APDU_RESPONSE_CODES_B

   9000;9000;

   There is no response code for the CR command from the third script, as it does not execute an APDU:

   APDU_RESPONSE_CODES_C

   9000;;9000;9000;