Selection JSON Specification v1.0

This specification is compliant with the following Keyple server side components:

Keyple Service Library version 3.0.0+

Card selection scenario

The JSON string CardSelectionScenarioJsonString contains a JSON object CardSelectionScenario containing the card selection scenario to be processed when a card is detected.

The following UML class diagram illustrates the format of this object and may help to implement it in the development language of the target terminal.

CardSelectionScenario


`multiSelectionProcessing`	String Can have one of the following values: - “FIRST_MATCH”: the selection process stops as soon as a selection case is successful. - “PROCESS_ALL”: the selection process performs all the selection cases provided (the logical channel is closed at the end of the selection case).
`channelControl`	String Can have one of the following values: - “KEEP_OPEN”: leaves the physical channel open. - “CLOSE_AFTER”: terminates communication with the card.
`cardSelectors`	CardSelector [ ] A non-empty array.
`defaultCardSelections`	DefaultCardSelection [ ] A non-empty array containing the same number of elements as `cardSelectors`.

Please note that additional properties are present, but are useless for a non-Keyple client and are therefore to be ignored!

CardSelector


`logicalProtocolName`	String (optional) An optional “logical” name of the targeted card protocol.
`powerOnDataRegex`	String (optional) An optional regex to use to filter the power-on data.
`aid`	String (optional) An optional Application Identifier (AID) as an hexadecimal string to be sent with ISO7816-4 “Select Application”.
`fileOccurrence`	String Can have one of the following values: "FIRST", “LAST”, “NEXT” or “PREVIOUS” according to the ISO7816-4 standard (only relevant when AID is set).
`fileControlInformation`	String Can have one of the following values: "FCI", “FCP”, “FMD” or “NO_RESPONSE” according to the ISO7816-4 standard (only relevant when AID is set).

DefaultCardSelection


`CardSelectionRequest`	CardSelectionRequest

CardSelectionRequest


`cardRequest`	CardRequest (optional) An optional object containing a list of APDU requests to be sent after a successful card selection.
`successfulSelectionStatusWords`	String [ ] A non-empty array of 2-byte hexadecimal strings containing the status word of the “Select Application” APDU command to be considered successful (only relevant when AID is set).

CardRequest


`apduRequests`	ApduRequest [ ] A non-empty array of APDU requests.
`stopOnUnsuccessfulStatusWord`	Boolean Set to true if the transmission of the APDUs should be interrupted as soon as the status word of a response does not belong to the associated list of successful status words, false otherwise.

ApduRequest


`apdu`	String An hexadecimal string containing the APDU to transmit to the card.
`successfulStatusWords`	String [ ] A non-empty array of 2-byte hexadecimal strings containing the status word to be considered successful.
`info`	String (optional) An optional textual information about the command.

Example

CardSelectionScenarioJsonString

"{\"multiSelectionProcessing\":\"FIRST_MATCH\",\"channelControl\":\"KEEP_OPEN\",\"cardSelectors\":[{\"logicalProtocolName\":\"CALYPSO_CARD_PROTOCOL\",\"powerOnDataRegex\":\".*\",\"aid\":\"1122334455\",\"fileOccurrence\":\"FIRST\",\"fileControlInformation\":\"FCI\"},{\"logicalProtocolName\":\"GENERIC_CARD_PROTOCOL\",\"powerOnDataRegex\":\".*\",\"aid\":\"1122334455\",\"fileOccurrence\":\"FIRST\",\"fileControlInformation\":\"FCI\"}],\"defaultCardSelections\":[{\"cardSelectionRequest\":{\"cardRequest\":{\"apduRequests\":[{\"apdu\":\"00B2020C00\",\"successfulStatusWords\":[\"9000\"],\"info\":\"Read Records - sfi: 01h, rec: 2, read mode: ONE_RECORD, expected length: 0\"},{\"apdu\":\"00B081000A\",\"successfulStatusWords\":[\"9000\"],\"info\":\"Read Binary - sfi: 01h, offset: 0, length: 10\"},{\"apdu\":\"00B2010C03\",\"successfulStatusWords\":[\"9000\"],\"info\":\"Read Records - sfi: 01h, rec: 1, read mode: ONE_RECORD, expected length: 3\"},{\"apdu\":\"008A0302010000\",\"successfulStatusWords\":[\"9000\"],\"info\":\"Open Secure Session - key index: 3, sfi: 00h, rec: 0 - pre-open\"}],\"stopOnUnsuccessfulStatusWord\":false},\"successfulSelectionStatusWords\":[\"9000\",\"6283\"]}},{\"cardSelectionRequest\":{\"successfulSelectionStatusWords\":[\"9000\"]}}]}"

JSON content

{
   "multiSelectionProcessing": "FIRST_MATCH",
   "channelControl": "KEEP_OPEN",
   "cardSelectors": [
      {
         "logicalProtocolName": "CALYPSO_CARD_PROTOCOL",
         "powerOnDataRegex": ".*",
         "aid": "1122334455",
         "fileOccurrence": "FIRST",
         "fileControlInformation": "FCI"
      },
      {
         "logicalProtocolName": "GENERIC_CARD_PROTOCOL",
         "powerOnDataRegex": ".*",
         "aid": "1122334455",
         "fileOccurrence": "FIRST",
         "fileControlInformation": "FCI"
      }
   ],
   "defaultCardSelections": [
      {
         "cardSelectionRequest": {
            "cardRequest": {
               "apduRequests": [
                  {
                     "apdu": "00B2020C00",
                     "successfulStatusWords": ["9000"],
                     "info": "Read Records - sfi: 01h, rec: 2, read mode: ONE_RECORD, expected length: 0"
                  },
                  {
                     "apdu": "00B081000A",
                     "successfulStatusWords": ["9000"],
                     "info": "Read Binary - sfi: 01h, offset: 0, length: 10"
                  },
                  {
                     "apdu": "00B2010C03",
                     "successfulStatusWords": ["9000"],
                     "info": "Read Records - sfi: 01h, rec: 1, read mode: ONE_RECORD, expected length: 3"
                  },
                  {
                     "apdu": "008A0302010000",
                     "successfulStatusWords": ["9000"],
                     "info": "Open Secure Session - key index: 3, sfi: 00h, rec: 0 - pre-open"
                  }
               ],
               "stopOnUnsuccessfulStatusWord": false
            },
            "successfulSelectionStatusWords": ["9000", "6283"]
         }
      },
      {
         "cardSelectionRequest": {
            "successfulSelectionStatusWords": ["9000"]
         }
      }
   ],
   ... additional properties are to be ignored
}

Processed card selection scenario

The JSON string ProcessedCardSelectionScenarioJsonString contains a JSON array of JSON objects CardSelectionResponse containing the result of each processed case of the card selection scenario.

Depending on the configuration of the selection scenario, the result list may contain fewer elements than the number of selection cases present in the scenario (e.g. if the multiSelectionProcessing property is set to FIRST_MATCH).

The following UML class diagram illustrates the format of this object and may help to implement it in the development language of the target terminal.

CardSelectionResponse


`hasMatched`	Boolean Set to true if the associated selection case has matched, false otherwise.
`powerOnData`	String (optional) Data from the initialization phase of the communication with the card. E.g. the Answer To Reset (ATR) in the case of a contact card or any other string informing about the low level communication. This string can be used for filtering by power-on data defined in the command (absent if the protocol filter failed).
`selectApplicationResponse`	ApduResponse (optional) Data received in response to the ISO7816-4 “Select Application” command (absent if no AID filtering).
`cardResponse`	CardResponse (optional) Data received in response to additional commands (absent if no additional commands were provided).

CardResponse


`isLogicalChannelOpen`	Boolean Set to true if the logical channel is left open, false otherwise.
`apduResponses`	ApduResponse [ ] A list containing the APDU responses for each request in the command.

ApduResponse


`apdu`	String An hexadecimal string containing the APDU received from the card (including the status word).
`statusWord`	String A 2-byte hexadecimal string containing the status word of the received APDU.

Example

ProcessedCardSelectionScenarioJsonString

"[{\"hasMatched\":false,\"powerOnData\":\"1234\",\"selectApplicationResponse\":{\"apdu\":\"6400\",\"statusWord\":\"6400\"},\"cardResponse\":{\"apduResponses\":[],\"isLogicalChannelOpen\":false}},{\"hasMatched\":true,\"powerOnData\":\"1234\",\"selectApplicationResponse\":{\"apdu\":\"6F238409315449432E49434131A516BF0C13C708000000001122334453070A3C20051410019000\",\"statusWord\":\"9000\"},\"cardResponse\":{\"apduResponses\":[{\"apdu\":\"ABCD9000\",\"statusWord\":\"9000\"}],\"isLogicalChannelOpen\":true}}]"

JSON content

[
   {
      "hasMatched": false,
      "powerOnData": "1234",
      "selectApplicationResponse": {
         "apdu": "6400",
         "statusWord": "6400"
      },
      "cardResponse": {
         "apduResponses": [],
         "isLogicalChannelOpen": false
      }
   },
   {
      "hasMatched": true,
      "powerOnData": "1234",
      "selectApplicationResponse": {
         "apdu": "6F238409315449432E49434131A516BF0C13C708000000001122334453070A3C20051410019000",
         "statusWord": "9000"
      },
      "cardResponse": {
         "apduResponses": [
            {
               "apdu": "ABCD9000",
               "statusWord": "9000"
            }
         ],
         "isLogicalChannelOpen": true
      }
   }
]