CT-BCS(3)

📦 version 2.0.7, in ubuntu jammy

💖 CT-BCS(3) — Cardterminal basic command set, bestie edition 💖

part of the Library Functions Manual ✨

🌸 NAME 🌸

CT-BCS — the Cardterminal basic command set for integrated circuit card applications. periodt.

🦋 DESCRIPTION 🦋

okay so. this manpage is gonna walk you through the subset of the Cardterminal Basic Command Set (aka CT-BCS) that you use to control cardterminals — specifically the ones with one or more integrated circuit card slots, and no keypad, no display. that's the vibe.

real talk though: this is not the whole CT-BCS spec, it's just a general overview of the most common functionalities. so don't come for me if your fave niche command isn't here 💅

the CT-BCS commands are built in compliance with ISO/IEC 7816-4 interindustry commands, and you use them to control a cardterminal by way of the CT-API function CT_data(). that's the whole pipeline, bestie.

🎀 COMMAND STRUCTURE 🎀

a CT-BCS command is an array of bytes that gets sent to the cardterminal to perform an administrative action. the CT-BCS response is an array of bytes that the cardterminal hands back to tell you how it went — aka the completion status of the action you asked for. no cap.

here's the general structure of a CT-BCS command, look at her:

|<------------------------------------------>|
|    Header (4 Bytes)     and body           |
|      (mandatory)       (optional)          |
|<----------------->|<---------------------->|
|___________________|________________________|
|CLA |INS |P1  |P2  |Lc  |Data          |Le  |
|____|____|____|____|____|______________|____|

and here's the general structure of a CT-BCS response:

|<------------------------------>|<--------->|
|           Body                    Trailer  |
|        (optional)                (2 Bytes) |
|                                 (mandatory)|
|________________________________|___________|
|Data                            |SW1-SW2    |
|________________________________|___________|

the fields inside a CT-BCS command and response are equivalent to the ones defined by ISO/IEC 7816-4, so let's go field by field 🔥

  • CLA — Class. the CLA value used for CT-BCS commands is 0x20.
  • INS — Instruction. this defines the action the cardterminal is gonna perform. it's giving "what are we doing today."
  • P1, P2 — Command parameters 1 and 2.
  • Lc — Length of the command data field.
  • Le — Length of expected data:
    • Case 1: no command data, no response data (no Lc and no Le).
    • Case 2: command data, no response data (0<=Lc<=254 and no Le).
    • Case 3: no command data, response data (no Lc and 0<=Le<=254).
    • Case 4: command data, response data (0<=Lc<=254 and 0<=Le<=254).
  • SW1, SW2 — Status bytes. this is the completion status of the command, the moment of truth tbh.

the address value 0x01 (CT) shall be used as the destination address (dad) given to CT_data() when you're sending CT-BCS commands (see CT_data (3)). don't forget it, bestie 🫶

the following commands are present in every CT-BCS implementation:

⭐ Basic CT commands ⭐

  • RESET CT — INS code 0x11
  • REQUEST ICC — INS code 0x12
  • GET STATUS — INS code 0x13
  • EJECT ICC — INS code 0x15

the following general return codes SW1-SW2 may occur:

💀 General return codes 💀

  • 0x6700 — Wrong length
  • 0x6900 — Command not allowed
  • 0x6A00 — Wrong parameters P1, P2
  • 0x6D00 — Wrong instruction
  • 0x6E00 — Class not supported

🧚 FUNCTIONAL UNITS 🧚

functional units are entities that can be addressed as the target of CT-BCS commands. in some CT-BCS commands you have to specify a target functional unit — so like, you can't just vibe your way through those ones.

🌈 Functional units 🌈

  • CT kernel — coding 0x00
  • CT/ICC slot 1 — coding 0x01
  • CT/ICC slot 2 — coding 0x02
  • ... — coding ...
  • CT/ICC slot 14 — coding 0x0E
support for slots 2-14 depends on the cardterminal. functional units for keypad and display are defined for some cardterminals, but they are not described here. 🙈

to be continued, bestie — part 2 is coming and we're not done yet 💜

💫 COMMANDS DESCRIPTION 💫

🔄 RESET CT 🔄

okay so the RESET CT command is literally just you asking the cardterminal to reset one specific functional unit, bestie. If that functional unit happens to be the CT kernel, then what goes down is a software reset — meaning all the status info (like, say, the info about which cards are inserted) gets wiped and then gathered all over again. And for ICC functional units? That's a full-on card reset. slay.

Optionally the answer to reset of the functional unit comes back to you in the response data. cute.

You can fire off a RESET CT command either after the cardterminal has been initialized, or after a communication error has happened. both valid, both iconic. ✨

The command structure is giving:

  • CLA — 0x20
  • INS — 0x11 (=RESET CT)
  • P1 — Functional unit:
    • 0x00 = CT
    • 0x01 - 0x0E = ICC Interface 1-14
  • P2 — Command qualifier:
    • In case P1 = 0x00:
      • 0x00 = No response
    • In case P1 = 0x01 - 0x0E:
      • 0x00 = No response data
      • 0x01 = Return complete ATR
      • 0x02 = Return Historical Bytes
  • Lc field — Empty
  • Le field — Empty or 0x00: return full length of requested information

And the response structure, periodt:

  • Data — Empty, ATR or Historical Bytes
  • SW1-SW2 — Status Bytes

When the functional unit is CT (0x00), these status bytes can come back at you:

  • 0x9000 — Reset successful
  • 0x6400 — Reset not successful

When the functional unit is a ICC slot (0x01 - 0x0E), these status bytes can come back:

  • 0x9000 — Synchronous ICC, reset successful
  • 0x9001 — Asynchronous ICC, reset successful
  • 0x6400 — Reset not successful

🃏 REQUEST ICC 🃏

The REQUEST ICC command is you telling the cardterminal: bestie, wait for an ICC to show up on this specific slot, for this specific amount of time. The command synchronously blocks the caller application — yes, it just sits there and waits, no cap — unless a time limit of 0 is specified. And the moment an ICC is presented, it gets automatically activated and reset. it's giving main character energy fr fr. 🔥

The command structure is as follows:

  • CLA — 0x20
  • INS — 0x12 (=REQUEST ICC)
  • P1 — Functional unit:
    • 0x01 - 0x0E = ICC-Interface 1 - 14
  • P2 — Command qualifier: Request handling instructions for the CT
  • Lc field — Empty or length of subsequent data field
  • Data field — Empty (= immediate response required) or max. waiting time in seconds (1 byte, binary coding) for presenting the ICC
  • Le field — Empty or 0x00 = Return full length of requested information

The parameter P2 carries the request handling instructions for the CT. The value of P2 is constructed of two 4-bits subfields:

  • Bits b8-b5
    • 0x0 = No meaning
    • Other values reserved for future use
  • Bits b4-b1
    • 0x0 = No response data
    • 0x1 = Return complete ATR
    • 0x2 = Return Historical Bytes

The response structure is as follows:

  • Data — Empty, ATR or Historical Bytes
  • SW1-SW2 — Status Bytes

The following status bytes can be returned:

  • 0x9000 — Synchronous ICC presented, reset successful
  • 0x9001 — Asynchronous ICC, reset successful
  • 0x6200 — No card presented within specified time
  • 0x6201 — Card already present and activated
  • 0x6400 — Reset not successful
  • 0x6900 — Command with timer not supported

🔍 GET STATUS 🔍

The GET STATUS command is your lil info-gathering moment: it pulls cardterminal manufacturer information and ICC status information straight from the cardterminal. The info is represented by TLV (tag, length, value) encoded data objects. You specify the tag of the data object you want in the command, and the value comes back to you in the response. obsessed. 💖

The command structure is as follows:

  • CLA — 0x20
  • INS — 0x13 (=GET STATUS)
  • P1 — Functional unit:
    • 0x00 = CT
  • P2 — Command qualifier: Tag of data object to be returned
  • Lc field — Empty
  • Data field — Empty
  • Le field — Hx00 = Return full length of requested information

The response structure is as follows:

  • Data — Status information (only value field of data object)
  • SW1-SW2 — Status Bytes

The following data objects are defined. Note that only value field is returned in the response:

Cardterminal manufacturer data object

  • Tag = 0x46
  • Length >= 15
  • Value:
    • CTM: Cardterminal manufacturer (5 bytes ASCII encoded). It consists of 2 bytes with the country code and 3 bytes with the manufacturer acronym
    • CTT: Cardterminal type (5 bytes ASCII encoded). The value is manufacturer dependant
    • CTSV: Cardterminal software version (5 bytes ASCII encoded). The value is manufacturer dependant
    • DD: Discretionary data (any number of bytes including 0)

ICC status data object

  • Tag = 0x80
  • Length
  • Value: One ICC status byte per ICC slot in the cardterminal.
    • If b8-b1 = 0x00 then no ICC is present in the slot.
    • If b1 = 1 and ICC is present in the slot and the bytes b3-b2 indicate whether the ICC is electrically connected (value 10) or electrically disconnected (value 01).

The following status bytes can be returned:

  • 0x9000 — Command successful

📤 EJECT ICC 📤

The EJECT ICC command asks the cardterminal to deactivate the ICC. bestie, you must use this at the end of your communication with the card, or whenever an irreparable communication error occurs. like, not optional. it's the responsible thing to do. 💅

The command structure is as follows:

  • CLA — 0x20
  • INS — 0x15 (=EJECT ICC)
  • P1 — Functional unit:
    • 0x01 - 0x0E = ICC-Interface 1-14
  • P2 — Command qualifier: Eject handling instructions for the CT (0x00 for cardterminals without keypad and display)
  • Lc field — Empty or length of subsequent data field
  • Data field — Empty or time in seconds for removing the ICC
  • Le field — Empty

The response structure is as follows:

  • Data — Empty
  • SW1-SW2 — Status Bytes

The following status bytes can be returned

  • 0x9000 — Command successful
  • 0x9001 — Command successful, card removed
  • 0x6200 — Card not removed within specified time

🌈 SEE ALSO 🌈

  • ctapi (3).

The MKT (Multifunktionale KartenTerminals) specifications, available for download from Teletrust web site http://www.teletrust.de (link to URL http://www.teletrust.de). In special the documents:

  • Part 3: CT-API. Cardterminal Applications Programming Interface.
  • Part 4: CT-BCS. Cardterminal Basic Command Set.
  • Part 7: IC cards with synchronous transmission Part3: Usage of interindustry Commands.

ISO/IEC 7816: Identification cards - Integrated circuit(s) cards with contacts:

  • Part 4: Interindustry commands for interchange.

👑 AUTHOR 👑

This manual page was written by Carlos Prados <cprados@yahoo.com>. 💖

and that's a wrap on the whole thing, bestie 🎀 the footer of this page is just CT-BCS(3) — that's your source/version tag and the date stamp hanging out at the bottom, so if you're citing it, that's the vibe to reference. go forth and reset some functional units. you ate. 🦋✨

📦 where this page comes from