Table of Contents

SCM Microsystems, Inc. makes no representations or warranties, either expressed or implied, by or with respect to anything in this guide, and shall not be liable for any implied warranties of merchant-ability and fitness for a particular purpose or for any indirect, special or consequential damages.

Copyright © 1997, SCM Microsystems Corporation

SCM Microsystems, RSR3, and the SCM Microsystems logo are registered trade names of SCM Microsystems. Many designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Such designations appearing in this manual have been printed in initial caps.

Specifications are subject to change without notice.

All rights reserved. No part of this publication may be reproduced, stored in the retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording or otherwise, without the prior written permission of SCM Microsystems, Inc.

No patent liability is assumed with respect to the use of information contained herein. Further, this publication and features described herein are subject to change without notice.

SCM Microsystems, Inc.
131 Albright Drive
Los Gatos, California 95030-1801
USA

SCM Microsystems GmbH
Luitpoldstr. 6
85276 Pfaffenhofen
Germany

SCM Microsystems France
Argeo-Athelia III
Voie Atlas
13705 La Ciotat Cedex
France
 

The RSR3 serial smart card reader from SCM Microsystems is a universal smart card reader/writer. Because all major smart card architectures are supported, the RSR3 serial smart card reader is suitable for a wide variety of applications that use a smart card as a secure memory token or secure processing device. These applications include:

- Secure payment (e.g. for internet commerce)

- Secure email communication

- Access control (e.g. to computers and networks)

- Smart card-based databases, ID cards

This Smartcard Developers Kit (SDK) provides the necessary software to implement smart card support in new and existing computer applications running under Linux or QNX on i386 platforms. It describes all components of the kit, how to install them, and how to use them for the design of a smart card aware application program.

A source code sample is included in the kit that gives the developer a frist look at how to invoke CT-API functions and test their equipment

This libraries have been tested with

- Linux Kernel 2.0
- QNX Ver. 4.2

on i386 platforms.
For other target platforms or systems (Sun Solaris, PalmOS, Windows) please contact SCM Microsystems !
 
 

Audience

This guide has been written for software design engineers or engineering managers who need detailed technical information for evaluating and/or for developing SmartCard-aware applications.
 
 

The SDK contains one tar package for each platform

for Linux :

for QNX :

This libraries have been tested with Linux Kernel > 2.0 and QNX 4.2 on i386 platforms. Please check for the correct enviroment before install the library !

After the installing the SDK, the following files will reside on your hard disk :
 

The RSR3 API follows the CT-API (Card Terminal Application Programming Interface) specification, which is part of the MCT specification, Multifunctional CardTermionals for Health Care. This specification is an international accepted, standard API for smart card applications.

The CT-API syntax is based on the ISO 7816-4 standard (Identification cards - Integrated circuit(s) cards with contacts Part 4 - Inter-industry commands for interchange) and allows for a unified communications interface to the RSR3 adapter as well as to microprocessor and memory smart cards.

The MCT specification also specifies basic functions of the smart caaard adapter (according the CT-BCS specification, Card Terminal - Basic Command Set) to improve the interoperability of Card Terminal/Smart Card subsystems.

The CT-API defines three basic functions, which are used to controll all functions of the RSR§ Reader and any inserted card :
 

CT-API functions
 
 

When a function is properly executed the function value 0 is returned, otherwise a negative function value shows the cause of the error. The function values for all CT-API functions are listed in th efollowing table :
 

Function values of the CT- API functions

The CT_init function must be called before communications begins with the CardTerminal and the ICC. With this function the host/CT interface is selected and initiated. At the same time the CardTerminal is assigned to a unique logical address in the form of a CardTerminal Number (ctn) which may be free chosen by the programmer. Also a port number (pn) is used. It denotes the physical interface via which the CardTerminal is accessed.
 
 

Function:

Function parameters:
 

Return Codes :

see CT-API Return codes above.

Because the RSR3 library is a static library, only one application is allowed to access the physical interface. The logical terminal number isn't used.

The RSR3-Reader and the serial port is exclusively assigned to one application. The application will close the session and release the reader by calling  function "CT_close".
 
 

Function CT_close - Close Card Terminal

The function CT_close is the counterpart to the function CT_init. It terminates the communication with the RSR3-Reader.

The function shall be called before the end of the program in order to free resources if necessary.
 
 

Function:

Function parameters:
 

Return Codes :

see CT-API Return codes above.
 
 

Function CT_data - Send Command

The function CT_data is used to send an ICC command to a card or a CardTerminal command to the RSR3-Reader and returns the command response to the calling program.
 
 

Function:

Function parameters:
 

Return Codes :

see CT-API Return codes above.
 
 

If the CT-API Return code is "0", CT_Data also returns a status word rsp from either the CardTerminal or the ICC. If the CT-API Return code has a negative value, no response rsp is returned (i.e. lr = 0).

In addition, the CT_data functions updates the parameters dad and sad during the return of the command response. This is a way to check wether the command response is coming from the CardTerminal or the ICC. For details please refer to the specification of the ICC used with your application.
 
 

Syntax of Application Commands
 
 

Application commands are constructed in compliance with the ISO/IEC 7816-4 Inter-industry commands.
 
 

Typical commands are RESET ICC, SELECT FILE, VERIFY PIN, READ BINARY, etc. The response will inform about any occuring problems like syntax or transmission errors.

The SDK consists of include files and libraries for use in swap card aware applications. They are located in the following directories:

/usr/scm/ctapi/lib
/usr/scm/ctapi/include

Link the appropriate file to your application project and include the ct_api.h header file in all your application source files which call the API.

In the directory /usr/scm/ctapi/sample you find a sample application called sample including the source code. This code is written in ANSI-C language an runs on a terminal window or console and allows the user to run some basic tests/demos with the a smart card.

The source code provides useful information about how to use CT-API commands in application programs.

You can build the sample with the installed Makefile. You can also build it

- on Linux use the GNU C-Compiler :

- on QNX use the Watcom C-Compiler :

Command Syntax

There are 2 kinds of application commands: CardTerminal Application commands are used to communicate with the RSR3 adapter and to control its functions. ICC Application Commands are used to communicate with an inserted smart card.

In general, all application commands are coded according to the ISO7816-4 standard as a socalled APDU. This applies to all versions of SDKs for RSR3, i.e. regardless of the target platform.

Because the library can use from only one process at the same time, the application programmer only needs to deal with the destination of the command, i.e. the "NAD" field. Please refer to section Function CT_data: Send Command of the CT-API Programmers Handbook for further details. In case of a RSR3 application command the destination of a command is always the SwapSmart adapter, so sad is always "2" and dad is always "1" (within the "NAD" field).

In other cases, some additional ISO7816-4 fields must be accompany the APDU command:
 

The command itself is coded in the "APDU" field, the syntax is compliant to ISO7816-4. All commands found in this manual are described according to this syntax.
 

The response from SwapSmart resp. the smart card also coded in a ISO7816-4 manner.
 

Which smart card are you going to use for your application? The RSR3 reader uses the same command syntax for all asynchronous smart cards, but the command set for a specific smart card depends on the smart card operating system specific type of smart card chip (synchronous cards). Please refer to the ICC specification for further details.
 
 

CT applications commands are used to communicate with the RSR3 reader and to control and its function. In general, application commands are coded according to the ISO7816-4 standard as a socalled APDU.

The CLA value used for CT-BCS commands is '20' to ensure compatibility with CT commands already being used.

The address value '01' (address of the CardTerminal) shall be used as destination address (DAD) at the CT-API for all CT commands (see CT-API specification).
 
 

CardTerminal command overview and general return codes

The following table gives a overview for the supported CT commands:
 

The syntax of the response is in accordance to the ISO7816-4. The same applies to the coding of the status word. The table below gives an overview of the general status messages (SW1-SW2) and their causes.
 

RESET CT

The RESET CT command causes the CardTerminal to carry out a reset of the specified unit (CT or CT functional units). If a software reset is to be carried out at the CardTerminal itself (functional unit = '00'), then the basic state has to be recovered (i.e. reset of all status information, deactivation of the contacts).

Optionally the complete ATR or a part of the ATR (the historical bytes) can be requested, if for the unit addressed an ATR has been defined.

A reset of the CardTerminal should only be initiated

A reset to the ICC can also be made by the application system, if this should be necessary on the application level.
 
 

Command structure :
 

Response structure :
 

Status Bytes :
 

REQUEST ICC

An ICC is requested with the REQUEST ICC command, whereby optionally the time allowed for the insertion of the card can be specified. After insertion of the IC card a reset of the card is automatically carried out.
 
 

Command structure :
 

Response structure :
 

Status Bytes :
 

EJECT ICC

The EJECT ICC command effects the deactivation of the electric interface.

The command should usually only be given at the end of the communication with the ICC. If an irreparable error occurs in the communication with the ICC, then the communication with the ICC may be aborted with this command.
 
 

Command structure :
 

Response structure :
 

Status Bytes :
 

GET STATUS

The GET STATUS command allows the retrieval of status information which is returned as BER-TLV encoded data objects (DO).
 
 

Command structure :
 

Response structure :
 

Status Bytes :
 

a) CardTerminal Manufacturer data object

The data elements are to be encoded in ASCII and, where necessary, to be padded with leading blanks.
The information CTT and CTSV are manufacturer specific.

The encoding for CTM is shall be determined in cooperation with a national registration authority (e.g. the national standardisation body or its agent) and registered there. It consists of

b) ICC status data object

The ICC status DO contains a status byte with the following structure:
 

ICC application commands are used to communicate with a smart card via the CardTerminal adapter. Application commands are transported as the cmd parameter of the CT_data function of the CT-API.

Please refer to "Function CT_data: Send Command" for further details. In case of an ICC application command the destination of a command is always the smart card, so sad is always "2" and dad is always "0."

As a general rule, the CardTerminal attempts to forward the ICC application command to the smart card in transparent mode. CardTerminal usually does not interfere in this communication. In this case a status response would be generated by the smart card and sent to the host (sad=0 and dad=2). There are one exceptions to this rule:

If a problem occurs during transmission of a command to an ICC, the CardTerminal generates and returns a corresponding error code. The CT_data function updates the parameters dad and sad during the return of the command response. This is a way how the application can check whether the command response is coming from CardTerminal or the ICC. So, if an application command is sent to ICC (i.e. sad=2, dad=0) and a response is coming back with sad=1 and dad=2 then CardTerminal was the source of the error message.

The current firmware revision of the RSR3-Reader supports asynchronous Smart Cards with the following protocols:

T=0 (ISO 7816-3)

T=1 (ISO 7816-3)

Error Messages from CardTerminal
 

Using Asynchronous ICCs

If the CardTerminal recognizes an asynchronous ICC during the reset of the ICC, it checks the ATR information and automatically selects the correct communication protocol (T=0, T=1).

In addition, ISO7816-3 parameters like the CWT, GT or the communication buffer size is automatically adjusted according to the requested values given in the card's ATR. Then the CardTerminal switches to "transparent mode." This means that the CardTerminal passes all ICC application commands to the card which will return the response to the host. The CardTerminal usually does not interfere in this communication. Only if a communication problem occurs, the CardTerminal will return a corresponding status word. The application program can check the source of the error message (refer to Function CT_data - Send Command)

For asynchronous smart cards the application command set is defined by the card's operating system and its specific personalization (e.g. file access rights). The command syntax is defined by the ISO7816-4 specification. Please refer to the documentation of the used smart card for further information.