3Macs GateKeeper (GK) Documentation

Look here for practical examples to start you off.

Misc

All traffic with the smartcard is put between rectangular brackets [...]. The traffic between decoder and GK is not put between brackets.

GateKeeper works with a Smartcard Reader/Writer on one COM port and a Season Interface on another COM port. If you only have two COM ports, you can use a mouse on PS/2 (if you have such a port).

All bytes send over the serial port are expected to echo on the input of the respective serial ports!!

Serial lines used in the Smartcard Reader/Writer:

• Tx for sending instruction bytes
• Rx for receiving bytes
• Gnd for ground
• RTS for resetting the card

Serial lines used in the Season Interface:

• Tx for sending instruction bytes
• Rx for receiving bytes
• Gnd for ground
• DCD (Receive Line Signal Detector) for catching a RESET

ATR

When (Re)Start is pressed, GK resets the smartcard and displays it in the log. Now the decoder can be startup. The ATR sent to the decoder is the ATR that is set by "Set ATR". It is not the ATR given by the card. The ATR can easily be set to the one from the card by looking at the log window.

Edit smartcard instruction

Make sure to check the GateKeeper "mode of operation" when editing an instruction. An instruction can be edited by double clicking it in the instruction window (tab SCC config). The edit window will have some additional controls to activate the functionality of GateKeeper:

• "compare message": if an instruction matches this data exactly, this instruction will be chosen. It can be used to target specific instructions.
• "link instruction": this is used to link the execution of one instruction with another one. It is only supported for instruction from decoder to smartcard.
• "route through": if this is checked the instruction is forwarded to the smartcard or decoder "as is". The edit box "instruction message" does not need to be filled in.

Smartcard instructions from decoder to smartcard

This is the sequence of events:

1. GK gets the 5 byte instruction header from the decoder.
2. GK looks up the instruction. If the instruction is not known, GK replies with 90 00 (standard OK). If the instruction (or at least one of possible multiple versions) is found, GK will know the direction, in this case from decoder to smartcard.
3. GK sends the ACK (which is equal to the INS) to the decoder. This ACK means: "OK, send the P3 bytes of the instruction".
4. GK analyzes the received bytes and determines a way of handling:
   • if the instruction matches with the "compare message" from one in the instruction list the instruction message of that instruction will be sent. Unless "route through" was checked.
   • if no such match is found, the last instruction that matches at least the 5-byte header will be selected.  The instruction must not contain a "compare message". Depending on "route through" the correct instruction message will be sent.
   • if in one of these two cases "link instruction" was used, the respective instruction's flag will be set.
5. GK will the instruction and will give as reply to the decoder not the one from the smartcard but the one from the instruction list.

Smartcard instructions from smartcard to decoder

This is the sequence of events:

1. GK gets the 5 byte instruction header from the decoder.
2. GK looks up the instruction. If the instruction is not known, GK replies with 90 00 (standard OK). If the instruction (or at least one of possible multiple versions) is found, GK will know the direction, in this case from smartcard to decoder.
3. GK sends the 5 bytes header to the smartcard, thus executing the instruction.
4. GK analyzes the bytes received by executing the instruction and determines a way of handling:
   • if the instruction matches with the "compare message" from one in the instruction list the instruction message of that instruction will be sent. Unless "route through" was checked.
   • if an instruction with such a 5-byte header is found with an active flag, this one will be selected. Depending on "route through" the correct instruction message will be sent.
   • if no such match is found, the last instruction that matches at least the 5-byte header will be selected. The instruction must not contain a "compare message". Depending on "route through" the correct instruction message will be sent.
5. GK sends the ACK (equal to INS) to the decoder indicating that it will start sending the instruction message. This message includes the status SW1&SW2.

Examples

How to block an instruction

All instructions with a certain 5-byte header will be blocked automatically, if they are unknown. This means that there is no such instruction present in the instruction list. So if you would want to block C1 40 01 00 26, just don't put it in the list. You can put it in the list, as long as the "compare message" doesn't equal the instruction you want to block.

How to block only some instructions of a certain type

If you would like to block some C1 40 01 00 4E's and route through some others than use the "compare message".

How to enable all instruction of a certain type

Just input the 5 byte header in a new instruction and check "route through".

How to modify an instruction "on the fly"

Use the "compare message" to lock on to a certain instruction and input your message into "instruction message" as usual.

How to work with the 0x34&0x32 pairs

For this you'll need "link instruction". The idea is this: the instruction message of 0x34 determines the reponse of the 0x32 instruction. For example C1 32 01 00 20 can have several instruction messages depending on the contents of the previous 0x34 instruction. You will need to add an instruction to the list for each 0x34 option and use "link instruction" to select the correct 0x32 response.