Smartcard Library
From OpenAlchemy.org
Contents |
Introduction
Smart cards are plastic cards embedded with computer chips that can hold a wide variety of data types, including security access information, applications, and records. They offer several key advantages over traditional magnetic stripe cards. They are more difficult to clone than traditional cards; the information they hold can be considerably more complex; and they can be updated.
Interoperability between systems is key to the success of the smart card technology. The idea is not for businesses to produce smart cards based on proprietary software as a turnkey product, but to produce applications that will run on any card. In order for that to happen, technical standards must be in place to ensure interoperability. Currently, three platforms are dominant, but no single one of them has the lead. They are Microsoft, Java, and MULTOS.
Smartcard Controller
Philips TDA 8008 is the smartcard controller on Amida Simputer that helps StrongArm processor communicate with the smartcard. This controller is connected to Serial 3 of StrongARM processor. It can handle two smartcards. The communication between the controller and the two asynchronous cards follow (T=0, T=1) protocol.
File System in Smart Cards
Smart cards contain a central file system which follows the ISO/IEC 7816-4 standards. The file system is arranged hierarchical like many modern day operating systems. Files are named by a 2-byte file identifier. Smart Cards contain 3 major file types:
- Master File (MF)
- Dedicated File (DF)
- Elementary File (EF)
A Root or Master File (MF) is the peak of the hierarchy. It is identified by 3F 00 as it¿s 2-byte identifier. It contains information and locations of files contained within it. Dedicated Files (DF) contain the actual data files. Dedicated files are like directories on smart cards. They subdivide the cards to hold files called Elementary Files (EF). The elementary file is where the actual data is stored. It can be of four different types.
- Transparent File
- Linear, Variable Length Record File
- Linear, Fixed Length Record File
- Cyclic, Fixed Length Record File
Each type is unique in how the data is stored and it¿s actual purpose. Transparent files are commonly just fixed byte files used for storing information. Linear Record Files contain subdivisions called records which hold a certain amount of bytes each. Cyclic Files are Smart Card specific. They contain a cycle of information where records are written and read in a ring like manner.
Alpar Library
Alpar library supports the following functions and their functional behaviours are explained subsequently.
short int alpar_recv(int fd, unsigned char *ack, unsigned char *command, unsigned char **data, unsigned char *lrc );
int alpar_send(int fd, unsigned char command, unsigned short int length, const unsigned char *data );
int send_num_mask(int fd, char *mask);
int power_up_iso(int fd, char *atr);
int power_up_3V(int fd, char *atr);
int power_up_5V(int fd, char *atr);
int power_off(int fd);
int select_card(int fd, unsigned char cardno);
int card_command(int fd, const char *iso_cmd, int cmd_len, char *iso_resp);
int show_fidi(int fd, char *fidi);
int negotiate(int fd, unsigned char protocol, unsigned char fidi);
int ifs_request(int fd, unsigned char ifsd);
int set_clock_card(int fd, unsigned char par);
int set_serial_baud_rate(int fd, int par)l;
int idle_mode_low(int fd);
int idle_mode_high(int fd);
int power_down_mode(int fd);
The functions alpar send, alpar recv communicated to TDA chip follow alpar protocol. On the top of that the functions apdu send, apdu recv are written. If you are interested in writing your own smartcard library, you can use these internal functions. The sources for alpar, portions of iso7816.c are under GPL, they can be downloaded from http://www.simputer.org under downloads->smartcards.
1. send_num_mask This command is used to identify the software version which is masked in TDA8008 ROM. For example the current software will be coded as : "C250 Release 1.2" (16 ASCII characters)
System to TDA8008 : 60 00 00 0A 6A
TDA8008 to System : 60 00 10 0A 43 32 35 30 20 52 65 6C 65 61 73 65 20 31 2E 32 6A
2. power_up commands There are three different power up commands (1.8V, 3V, 5V or ISO). Three of them (power up 1.8V, power up 3V and power up 5V) have to be followed by a parameter :
00H indicates that all the parameters of the ATR of the card compliant with ISO7816-3 will be taken into account.
01H indicates that only the ATR of cards whose parameters are inside the E.M.V.3.1.1 specification scope will be taken into account; cards having an ATR which does not comply with EMV3.1.1 requirements will be rejected.
System to TDA8008 60 00 01 6E 01 0E ACK length code EMV LRC
TDA8008 to System 60 XX XX 6E nnnnnnnnnnnnnnnnnnnn ZZ ACK length code ATR parameters LRC
- power_up_5V
This command allows to activate the selected card at a VCC of 5V. All the signals going to the card will be referenced to this VCC=5V. If the card does not answer to the reset, a status giving an error code is returned to the application.
In the case of EMV compliant power up, if the card is using T=1 protocol, just after having received the ATR, TDA8008 sends an IFSD request to the card indicating that the reader can manage a data buffer of 254 bytes (FEH). The power_up_5V command can be used to generate a warm reset if the card is already activated.
- tt_power_up_1.8V
This command allows to activate the selected card at a VCC of 1.8V. Every signal going to the card will be referenced to this VCC=1.8V. See power up 5V for the other characteristics.
- power_up_3V
This command allows to activate the selected card at a VCC of 3V. Every signal going to the card will be referenced to this VCC=3V. See power up 5V for the other characteristics.
- power_up_iso
This command does not need any argument. The principle consists to activate the selected card as described in ISO 7816-3 :
- attempt to activate the card at a VCC of 3V, if the cards answers correctly and if it indicates in its ATR that it is a class A or a class AB card (TAi with T=15), then the command is finished and the ATR is returned to the host,
- if in the previous stage, the card did not answer correctly or did not specify in its ATR that it was a class A or a class AB card, a new activation of the card is launched at 5V. If the card does not answer to the reset, a status giving an error code is returned to the application, otherwise the answer contains all the parameters of the card. See power up 5V for the other characteristics (when parameter of the command is ISO, not EMV).
3. power_off
This command is used to deactivate the selected card whatever it has been activated for 1.8V, 3V or 5V operation. A deactivation sequence is processed following the ISO 7816-3 normalization in about 100s.
System to TDA8008 : 60 00 00 4D 2D
TDA8008 to System : 60 00 00 4D 2D
4. card_command (APDU)
This command is used to transmit card commands under APDU format from system to TDA8008 whatever T=0 or T=1 protocol are used. Short or extended commands (see limitations in 8.1) can be used. An answer to such a command is also made in APDU format from TDA8008 to the system. As an Example :
System to TDA8008 : 60 00 07 00 00 A4 00 00 02 4F 00 8E
TDA8008 to System : 60 00 02 00 90 00 F2
5. process_T=1 command
This command may be used if the application layer provides the complete T=1 frame including prologue, information and epilogue fields. If it is not the case, the above card command opcode shall be used.
This command is used from the application layer in order to send a complete T=1 frame to the selected card. This command includes the specific framing used in T=1 protocol (Prologue Field, Information Field, Epilogue Field) and will be sent transparently to the card. The answer from the card will be sent as a complete T=1 frame to the application layer. The internal timing of a block (Character Waiting Time) will be handled by TDA8008. The block Waiting Time will also be controlled by TDA8008. In case of Waiting Time Extension request (WTX) from the card, it will be taken into account by the TDA8008.
System to TDA8008 60 XX XX 01 NAD PCB LEN A1 A2 ...... AN EDC LRC
TDA8008 to System 60 00 06 01 NAD PCB LEN SW1 SW2 EDC LRC
where A1 A2.....An is information field sent to the card
XX XX is the length of the frame from NAD to EDC
In case of chaining :
System to TDA8008 60 00 XX 01 NAD 20 LEN A1 A2 ...... AN EDC LRC
TDA8008 to System 60 00 04 01 NAD 90 00 EDC LRC
System to TDA8008 60 00 YY 01 NAD 40 LEN AN+1 AN+2 ... ... AZ EDC LRC
TDA8008 to System 60 00 ZZ 01 NAD PCB LEN D1 D2 ... ... DN EDC LRC
6. negotiate
This command is used to make a PPS (Protocol and Parameter Selection) to the selected card, if in its ATR the card proposes a different Fi/Di or 2 different protocols. By using this command a PPS will be made to the card with the Fi or Di and protocol type entered as a parameter (PP). It is up to the host to make the correct Fi/Di submission to the card.
Example :
System to TDA8008 : 60 00 02 10 PP FD LRC
TDA8008 to System : 60 00 00 10 70
Where FD is the ratio Fi/Di given by TA1 parameter of the ATR and PP is the protocol to be used. If the command is acknowledged, any subsequent exchanges between the card and TDA8008 will be made by using the new parameters.
7. IFSD request
This command is used to send a S(IFS request) block to the selected card indicating the maximum length of information field of blocks which can be received by the interface device in T=1 protocol. The initial size following the answer to reset is 32 bytes and this size shall be used throughout the rest of the card session or until a new value is negotiated by the terminal by sending a S(IFS request) block to the card.
Note: In EMV mode, the IFSD size is automatically negotiated to 254 just after the ATR has been received.
System to TDA8008 : 60 00 01 0C PAR LRC
TDA8008 to System : 60 00 00 0C 6C
where PAR is the IFSD size.
8. set_clock_card
This command is used for changing the selected card clock frequency. The default value is set to FXTAL/4 which is 3.68625 MHz. A parameter has to be transmitted in order to choose the card clock frequency:
System to TDA8008 : 60 00 01 11 FREQ LRC
Frequency FREQ
Fxtal =14.745MHz 00
Fxtal/2=7.37MHz 02
Fxtal/4=3.68MHz 04
Fxtal/8=1.84MHz 06
After a card clock frequency change, all the waiting times are internally set to the new value. Before applying the requested clock, the compatibility of the frequency with the current Fi used by the card is checked as described in ISO7816-3. For example, if the card has answered in its ATR a Fi parameter of 372 or 558 (fmax 6MHz), a change of the card clock frequency to Fxtal (14.745MHz) or Fxtal/2 (7.37MHz) will not be processed and an error status will be sent to the application.
9. select_card
This command is used to select the card 1 or 2.
System to TDA8008 : 60 00 01 6A CARD LRC
TDA8008 to System : 60 00 00 6A CARD LRC
Parameter CARD is used to choose the card. Values 1 or 2 are accepted. When calling this function several operations are executed.
- all parameters of the current card are saved.
- parameter emv
- parameter FiDi
- parameter Protocol_type
- operating class
- clock stop indicator
- for T=0 protocol : W I
- for T=1 protocol : CW I, BW I, ifsc, ifsd, NAD
- the new card is selected.
- all parameters of the new card are restored.
10. set_serial_baud_rate
This command is used for changing the baud rate onto the serial link between the host and the interf card. The default value is set to 38400 baud.
System to TDA8008 : 60 00 01 0D PAR LRC
TDA8008 to System : 60 00 00 0D 6D
The parameter BR defines the baud rate to be applied :
Baud rate (Baud) PAR
4800 00
9600 01
19200 02
38400 03
57600 04
76800 05
115200 06
After a baud rate change, the new value takes place for the next command sent by the host.
11. idle_mode (clock stop low)
This command is used to set the controller in idle mode. The card, if activated, has its clock (CLK) set to low level but is still active. Any command from the host on the serial line will wake up the device.
System to TDA8008 : 60 00 00 A2 C2
TDA8008 to System : 60 00 00 A2 C2
7.1.8 idle_mode (clock stop high)
This command is used to set the controller in idle mode. The card, if activated, has its clock (CLK) set to high level but is still active. Any command from the host on the serial line will wake up the device.
System to TDA8008 : 60 00 00 A4 C4
TDA8008 to System : 60 00 00 A4 C4
12. power_down_mode
This command is used to set the controller in power down mode. If activated before sending this command, the card(s) may optionally stay activated. Waking up conditions :
- Any command from the host on the serial line. In that case, the TDA8008 can not interpret the frame (due to waking up delay) and the first command frame sent by the host is lost (no answer from the TDA8008).
- Any hardware event on the cards side. In that case, an outgoing command is sent to the host to warn it of the event occurred.
- An external interrupt generated on the INT1 line (P3.3).
- An hardware reset
System to TDA8008 : 60 00 00 A3 DEACT CLK LRC
TDA8008 to System : 60 00 00 A3 C3
where DEACT is used to deactivate or not the card
DEACT = 0x00 card is kept activated, with the clock specified in CLK parameter
DEACT = 0x01 card is deactivated, in that case the CLK parameter is not significant
CLK is the clock to be used if the card is not deactivated
CLK = 0x00 clock is switched to Fint/2
CLK = 0x01 clock is stopped at low level
CLK = 0x02 clock is stopped at high level
