Contents

1. Scope
2. Normative references
3. Abbreviations
4. CT-API
4.1 CT-API structure
4.2 Type definition
4.3 CT-API functions
4.3.1 CT_init
4.3.2 CT_data
4.3.3 CT_close
4.4 General function values of the CT-PAI functions

1. Scope

This specification describes the application inde-pendent CardTerminal functions that are required to simplify the handling of and communication with IC cards.
The CT-API functions are constructed so that

• memory cards and processor cards can be used
• the necessary commands to control the CardTerminal can be transmitted and
• CardTerminals can be addressed independent of the port.

A CT-API function library is a software compo-nent of the CardTerminal and should be provided by the CT manufacturer for those system environments that are considered relevant.

[top]

2. Normative references

ISO 3166: 1994 Codes for the representation of names of countries

ISO/IEC 7816-3: 1989/1993 Identification cards - Integrated circuit(s) cards with contacts
Part 3 - Electronic signals and transmission pro-tocols

ISO/IEC 7816-4: 1995 Identification cards - Integrated circuit(s) cards with contacts
Part 4 - Inter-industry commands for in-terchange

[top]

3. Abbreviations
 

API	Application Programming Interface
CT	Card Terminal
ctn	Card Terminal Number
CTM	Card Terminal Manufacturer
dad	Destination ADdress
ICC	Integrated Circuit(s) Card
HTSI	Host Transport Service Interface
lenc	LENgth Command
lenr	LENgth Response
OS	Operating System
pn	Port Number
res	RESult of function
RFU	Reserved for Future Use
RID	Registered application provider identifier
sad	Source ADdress
wki	Well Known Identifier

[top]

4.1 CT-API structure

The CT-API functions are provided by a so-called HTSI module (Host-Transport-Service-lnterface). The embedding of an HTSI module in its system environment is shown in fig.1.

Fig.1 The embedding of an HTSI Module in its system enviroment

[top]

4.2 Type definition

The CT API uses functions whose parameters and function results are described in the following notation:
 
 

 Tab. 1: Type Notation

Ordinal Type	Meaning
IUx	Integer unsigned  Index x shows the used bit length in decimal form  (i.e.: IU16 = 0 ... 65535)
ISx	Integer unsigned  Index x shows the used bit length in decimal form  (i.e.: IU8 = -127 ... 128)

[top]

4.3 CT-API functions

The CT-API contains of the following functions which are provided by a HTSI module.
 

Tab. 2: CT-API functions 

CT-API-Function	Meaning
CT_init	Initiation of the host/CT connection
CT_data	Transmission of a command to a CardTerminal or to an ICC and give back the response
CT_close	Close the host/CT connection

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 section 4.4.

In order to ensure compatibility CT-API functions shall have the same name and parameters in every implementation.

Additionally in the case of simultaneous use of several CT-API libraries in one application system a CT-API library with 'well known identifier' shall be provided (see annex A).

[top]

4.3.1 CT_init

With the function CT_init the host/CT interface is selected (e.g. COM1: or COM2: for MS-DOS and e.g. ttyS0 or ttyS1 for LINUX) and initiated. The de-fault values for the communication are herewith automatically set. The CT_init function must be called before communication begins with the CardTerminal and the ICC. At the same time the CardTerminal is assigned to a unique logical address in the form of a CardTerminal Number (ctn) which may be freely chosen by the programmer. Also a port number (pn) is used. It denotes the physical interface via which the CardTerminal is accessed.
The port number is not regulated by this specification and may be chosen according to the manufacturer’s description.
The assignment or the assigning principle of the port number to the physical interface can be seen from the manufacturer's documentation.
One CardTerminal manufacturer for example may assign the port number 1 to a keyboard in-terface, while another manufacturer may use port number 1 for the outlet 1 of an 8 bit wide I/O or for the serial interface COM1: of a PC.
The application program can nevertheless address these different port models with CardTerminal number 1 and port number 1 as long as  the manufacturer's API library is linked. Thus the modules concerned in the application program do not need to be modified.

Function:

CT_init(ctn, pn)

Function parameters:
 

Tab. 3: Parameters for CT_init

Prameter name	Parameter type	Meaning
ctn	Inputparameter, type IU8	logical CardTerminal number
pn	Inputparameter, type IU8	Port number of the physical interface.   0 -> /dev/ttyS0 1 -> /dev/ttyS1

Functions values:
 

Tab. 4: Function values of CT_init

Parameter type	Meaning
Output paramter, Type IS8	Function values see section 4.4

[top]

4.3.2 CT_data
 
The function CT_data is used to send an ICC command to a card or a CardTerminal command to an integrated or connected CardTerminal and returns the command response to the calling program.

Function:

CT_data(ctn, dad, sad, lenc, command, lenr, response)

Function parameters:
 

 Tab. 5: Paramters for CT_data

Parameter name	Parameter type	Meaning
ctn	Input-parameter, type IU8	Logical CardTerminal number
dad	Input / Output-parameter, type IU8	Destination address
sad	Input / Output-parameter, type IU8	Source address
lenc	Input-parameter	Command length in byte
command	Input-paramter Reference address of a field with elements of type IU8 which contain the command	ICC-command or CT-command
lenr	Input / Output-parameter, type IU8	Passing of the max. buffer size of the response field to the function and return of the actual length of the response in byte
response	Input paramter reference address of a filed with elements of type IU8 in which the response is entered (field declaration in the application)	Reponse to the command

When the function CT_data is called, the source address field usually contains the address value for 'Host'. In some applications, however, the address value for 'Remote Host' may occur. When a CT command is sent, the address value for the CardTerminal occurs as the destination address. When an ICC command is sent, the address value for the ICC has to be used. As a CardTer-minal may have more than one ICC CardTerminal may have more than one ICC interface the address value for the respective ICC must be given. On the return of the response by the called function, the values in the parameters dad and sad are set respectively by the receiver and the sender.

Tab. 6 and 7 show the address values defined until now.
 

Tab. 6: sad and dad values when sending commands

sad in sedecimal noration (Hex)	Sender
02	HOST
05	REMOTE HOST
dad in sedecimal noration (Hex)	Receiver
00	ICC1
01	CT
02	ICC2
...	...
0E	ICC14
xx	other values reserved

 
 

Tab. 7: sad and dad values when receiving commands

sad in sedecimal noration (Hex)	Sender
00	ICC1
01	CT
02	ICC2
...	...
0E	ICC14
dad in sedecimal noration (Hex)	Receiver
02	HOST
05	REMOTE HOST
xx	other values reserved

 
Note:
ICC1 has the value ‘00’ and not the value ‘01’ due to com-patibility requirements with CT-API version 1.0.

Functions values:
 

Tab. 8: Function values of CT_data

Parameter type	Meaning
Output paramter, Type IS8	Function values see section 4.4

 
 

Notes for the user:

a) CardTerminal commands

The CT-data function allows the use of both inter-industry commands and manufacturer specific commands.

b) Commands to memory IC cards

If the CardTerminal supports communication with memory ICC, the commands shall comply with the designated conventions (e.g. use of inter-industry commands, if a corresponding trans-formation function to chip specific commands is available).

c) Commands to Processor IC Cards

Commands to processor ICC are passed through to the ICC in a transparent mode (i.e. without any changes). Implementation overheads (e.g. transmission protocol) are added automatically.

Fig. 1 in Annex D shows the transport of an ICC command and its response using the CT-API function CT_data.

[top]

4.3.3 CT_close

The function CT_close is the counterpart to the function CT_init. It terminates the commu-nication with the CardTerminal which has been assigned to a logical CardTerminal number by the function CT_init.
The function shall be called before the end of the program in order to free resources if necessary.

Function Parameter:
 

Tab. 9: Paramters for CT_close

Paramter name	Parameter type	Meaning
ctn	Input-parameter, type IU16	Logical CardTerminal number

Functions values:
 

Tab. 10: Function values of CT_data

Parameter type	Meaning
Output paramter, Type IS8	Function values see section 4.4

 
 
 

4.4 General function values of the CT-API functions

The function values are generally of the type IS₈.
 

Tab. 11: Function values of the CT-API functions

Return Code	Function value	Meaning
OK	0	Function call was successful
ERR_INVALID	-1	Invalid parameter or value
ERR_CT	-8	CT error 1)
ERR_TRANS	-10	Non-eliminable trnamission error 2)
ERR_MEMORY	-11	Memory assignment error in HTSI 3)
ERR_HOST	-127	Abort of function by host/OS
ERR_HTSI	-128	HTSI error

1) The CT is temporarily not accessible (busy with  other or internal processes). The problem can be solved by the application.

2) Transmission errors due to mechanical, electrical or protocol failures. Reset of the CT is necessary.

3) A memory error occurred (e.g. the allocated buffer (memory) is too small for the data set).
 

Subsequent actions in error situations shall be implemented in accordance with HTSI manufac-turers' recommendations.

[top]

Authors:
Deutsche Telekom AG / PZ Telesec
GMD - Forschungszentrum Informationstechnik GmbH
TÜV Informationstechnik GmbH
TELETRUST Deutschland e.V.
Date: 30.10.1996

Converted to HTML by Gregor A. Panstruga
Original document can be found at http://www.quasi-niere.org/mkt/spec/ctapi11e.doc.gz