Card Reader Access Services (CRAS)
File Name:
Z:\pr\cardman\sw\crastst\crastst.doc
Document Version:
1.00.00 final
Document Type:
Tool Description
Project Id:
P574
Author(s):
Office / Company:
Abstract:
Disclaimer:
K. Kritzinger
Utimaco Safeware AG
This document describes the Card Reader Access Services (CRAS) test program
Last modified: 28.08.2000
Copyright 2000 by Utimaco Safeware AG
All Rights Reserved.
The information in this document may not be changed without express written agreement of Utimaco Safeware AG.
Confidential information
Table Of Contents
1Document Information
1.1Owner / Master Location
1.2Change History
1.3Distribution & Approval History
1.4Related higher level document
2General Description
3Usage of the crastst Program
3.1CRAS Commands – Card Reader Access Services
3.1.1CRASConnect, CRASReconnect, CRASDisconnect
3.1.2CRASCardState, CRASReaderState
3.1.3CRASGetSelectedProtocol, CRASGetAtr
3.1.4CRASCommunicate with Script
3.2CL7816-4 Commands
3.3CRBS Commands – Card Reader Binding Services
3.3.1CRBSSetBinding, CRBSClearBinding
3.3.2CRBSListAssignedCardReaders, CRBSListSystemCardReaders
3.3.3CRBSGetArchitecture
4Example
4.1.1Get necessary information about your reader
4.1.2Look which card is TCOS and which is SetCos
4.1.3Write second key-pair
5Advanced
5.1CL7816SelectFile
5.1.1Prototype
5.1.2Description
5.1.3Parameters
5.1.4Return Values
5.2CL7816WriteBinary
5.2.1Prototype
5.2.2Description
5.2.3Parameters
5.2.4Return Values
1Document Information[H1]
1.1Owner / Master Location
Owner of this document is KK.
The location of the master copy is Z:\pr\cardman\sw\crastst\crastst.doc.
1.2Change History
Version / Author / Date / Description1.00.00 / KK / 2000-08-28 / Initial Version
1.3Distribution & Approval History
Version / Distributed to / approved by / Date distributed / Date approved1.4Related higher level document[H2]
2General Description
The main purpose of the craststn.exe was, of course, to serve as test program for the CardMan API’s low level interface – the CRAS Interface (CRAS = Card Reader Access Services).
The CRAS interface provides an uniform access to smartcards for applications and high level APIs, and it abstracts the underlying driver architecture. Additionally, it provides basic smart card commands defined in ISO 7816-4, and EN 726-3.
Currently supported methods to communicate with a smartcard reader are via the PC/SC Resource Manager or via CT-API.
To use this interface, and also the crastst tool, detailed information about the data structure on the smartcard and about the used card operating system are required.
This document, however, will mainly describe, how the crastst program can also be used by non smartcard experts, to manipulate data on the card, and to get some information. For simple tasks it would be enough just to look to the Example. It should not be necessary to read the whole document. References to the corresponding section of more detailed information will be given there.
In order to use this program the cardmanx.ini file must have at least the following section:
[Load CRAS]
crpcscn.dll=1
This means that the PC/SC architecture should be used for communication, and its ID is 1. The ID is free choose able, but it must be an exponent of two (1, 2, 4, 8, 16, 32, 64, etc.). It’s also possible that more than just one architecture are used simultaneously. Then an entry must exist for each architecture, and the ID must be unique.
However, it’s something like an “Utimaco intern standard” that PC/SC architecture gets the ID 1.
3Usage of the crastst Program
When the program is started it can be chosen between three main menus:
1)“Display CRAS commands”
The CRAS commands itself are functions to setup a connection to the smartcard reader, and to communicate with smartcards independent of the underlying driver architecture, like PC/SC or CT-API.
2)“Display CL7816-4 commands”
The command layer for ISO 7816-4 (CL7816) provides basic smart card commands defined in ISO 7816-4.
3)“Display CRBS commands”
The Card Reader Binding Services (CRBS) provide commands for assigning a logical card reader ID (e.g. A, B, ...) to a physical card reader. This enables applications, and high-level interfaces an uniform access to card readers of different driver architecture, and different vendors. In fact the cardmanx.ini file is manipulated with these commands.
Each of these three main menus is described in more detail in the following sections.
3.1CRAS Commands – Card Reader Access Services
The submenu that is shown when the program is started, is the menu for the CRAS commands. It provides the following 13 commands:
10)CRASInitThis is the first command that has to be called. If it has not been called, all other commands will fail.
11)CRASCloseThis command should be called before the application is closed in order to avoid memory leaks. Please keep also in mind, that other applications that may run in parallel will lose the access rights when this application is terminated without executing the CRASClose command, as the Resource Manager resets the card in this case.
12)CRASConnectThis command sets up a connection to the smartcard in a certain reader. This command is explained in more detail in section 3.1.1CRASConnect, CRASReconnect, CRASDisconnect
13)CRASReconnectThis command reconnects the smartcard when it has been removed and re-inserted. For detailed information see section section 3.1.1CRASConnect, CRASReconnect, CRASDisconnect
14)CRASDisconnectWith this command the card is disconnected again. Detailed information about this command are given in section section 3.1.1CRASConnect, CRASReconnect, CRASDisconnect
15)CRASBeginTransactionThis command locks the card reader, so that no other application has access to it until CRASEndTransaction is called. It is usually be used when a set of commands is send to the card that should not be interrupted in order to keep the state consistent.
16)CRASEndTransactionThis command unlocks the card reader when it has been locked with CRASBeginTransaction
17)CRASCardStateThis command gives some state information about the card. For more information see section 3.1.2CRASCardState, CRASReaderState.
18)CRASCommunicateHerewith any APDU can be send to the smartcard. A very deep knowledge about the card operating system is necessary to use this command.
19)CRASControlWith command control codes can be send to the card (e.g. set SAMOS card in high speed mode). A very deep knowledge about the card operating system is necessary to use this command.
20)CRASReaderStateThis command returns the state of the card reader. More information can be received in section 3.1.2CRASCardState, CRASReaderState.
21)CRASGetSelectedProtocolWith this command the currently selected protocol can be retrieved. For detailed information see section 3.1.3CRASGetSelectedProtocol, CRASGetAtr.
22)CRASGetAtrThis command retrieves the card’s ATR (answer to reset). For more information see section 3.1.3CRASGetSelectedProtocol, CRASGetAtr.
23)CRASCommunicate with ScriptThis command allows to send a set of APDU commands to the card. More information about this function is given in section 3.1.4CRASCommunicate with Script.
3.1.1CRASConnect, CRASReconnect, CRASDisconnect
CRASConnect
This command sets up a connection to a smartcard in a certain reader. Before this command can be called, CRASInit has to be called, and a smartcard has to be inserted. This command must be called before any other command except CRASReaderState.
If the command is executed, it asks for the ID of the architecture (“Architecture(s):”). The help suggests “1..PC/SC”, and “2..CardMan API”. However, this must not necessarily be correct. It depends on the entry in the cardmanx.ini file. (See 2General Description) If the ID of the architecture is not known, its possible to add the IDs of all architectures and provide this sum. The command scans all architectures, and chooses the correct one.
After the architecture has been entered the reader name (“CardReaderID:”) should be provided. This is the name provided by the driver. If the reader name is not known, a list of all available readers can be retrieved with the CRBS command CRBSListSystemCardReaders (see 3.3.2CRBSListAssignedCardReaders, CRBSListSystemCardReaders), with the Control Panel Applet, with the CardInfo Tool, or with the CMDiag Tool. If just one card reader is attached, and the used architecture is PC/SC, the reader’s name is mostly “Utimaco CardMan 0”.
At last parameter the protocol (“Protocol(s):”) should be entered. The protocol (T=0, T=1) depends on the card operating system. If it is not known, it’s possible to add the protocol IDs (1 for T=0 and 2 for T=1) and provide 3 to the function. The program chooses the right one.
The command returns a handle that has to be provided to all other functions that are called afterwards.
CRASReconnect
This command reconnects the smartcard when it has been removed and re-inserted (even if it is not the same card). CRASInit and CRASConnect have to be called before, and a smartcard has to be inserted.
When executing the command it is asked to enter the handle (“Handle:”) received with CRASConnect. Afterwards the protocol (“Protocol(s):”) has to be provided. Like with CRASConnect the protocol IDs can be added.
CRASDisconnect
With this command the card is disconnected again. It should be called when no more communication with the card is necessary, and before CRASClose is called. CRASInit and CRASConnect have to be called before.
This command also asked for the handle (“Handle:”) retrieved with CRASConnect. Afterwards an action (“Action:”) has to be specified. Usually it’s the best thing to do nothing. Please keep in mind when the card is rested or unpowered, that other applications that may run in parallel lose their access rights.
3.1.2CRASCardState, CRASReaderState
CRASCardState
This command gives some state information about the card. CRASInit and CRASConnect have to be called before.
For executing this command, the handle (“Handle:”) received with CRASConnect has to be provided.
The command returns the card state as well as the ATR (answer to reset). The following states are possible:
CRAS_STATE_SWALLOWED3An unpowered card is in reading position.
CRAS_STATE_POWERED4A powered card is in the reader, but the software is not aware of the protocol of the card.
CRAS_STATE_NEGOTIABLE5The card has been reset and is awaiting PTS (= Protocol Type Selection) negotiation.
CRAS_STATE_SPECIFIC6A powered and initialized card is in the card reader.
CRAS_STATE_INUSE256The card is used (and powered) by some application.
The most time the state will be specific, as the other states (except in use) are only possible when the card is not connected, and it’s not possible to call this command without being connected.
CRASReaderState
This command returns the state of the card reader. CRASInit must be called before.
For the parameters architecture (“Architecture(s):”), and the card reader name (“CardReaderID:”) the same is true as for the corresponding parameters within the CRASConnect command.
One of the following states will be returned:
CRAS_STATE_ABSENT1No card in the reader.
CRAS_STATE_SWALLOWED3An unpowered card is in reading position.
CRAS_STATE_POWERED4A powered card is in the reader, but the software is not aware of the protocol of the card.
CRAS_STATE_INUSE256The card is used (and powered) by some application.
3.1.3CRASGetSelectedProtocol, CRASGetAtr
CRASGetSelectedProtocol
With this command the currently selected protocol can be retrieved. CRASInit and CRASConnect have to be executed before.
The hande (“Handle:”) received by CRASConnect has to be provided to this function. The retrieved protocol can either be CRAS_PROTOCOL_T1 or CRAS_PROTOCOL_T0.
CRASGetAtr
This command retrieves the card’s ATR (answer to reset). The ATR gives information about the capabilities of the card, like baud rate, clock rate, supported protocol(s), etc., but also general information that can freely be chosen by the card manufacturer (the so called historical bytes). This can be data like, card operating system version, chip type, etc. The ATR can be used to distinct the different card operating systems.
CRASInit and CRASConnect have to be executed before this command.
The handle (“Handle:”) received by CRASConnect has to be provided to this function.
Following a list of different card operating systems and their ATR:
ATR / Card Operating System3b b0 11 00 81 31 90 73 f2 / SAMOS
3b b4 11 00 81 31 90 73 xx xx xx xx xx / SAMOS (SBG variant)
3b ba 14 00 81 31 86 5d 00 64 05 14 02 02 31 80 90 00 91 / TCOS 2.0 (CX160S)
3b ba 13 00 81 31 86 5d 00 64 05 0a 02 01 31 80 90 00 8b / TCOS 2.0 (CR80S)
3b 1f 11 80 6a 80 34 46 49 53 45 53 94 36 ff 07 90 00 / SetCos 3.4
3b 6e 00 00 00 62 16 43 57 41 56 41 4e 54 10 81 90 00 / SetCos 4.3.0
3b 9f 94 40 1e 00 67 16 43 46 49 53 45 10 52 66 ff 81 90 00 / SetCos 4.3.1
3b 88 40 30 00 57 69 6e 43 61 72 64 / Windows for Smart Cards 1.0 (T=0)
3b b8 13 00 81 31 20 5d 00 57 69 6e 43 61 72 64 02 / Windows for Smart Cards 1.1 (T=1)
3b 04 02 04 ff ff / SLE4428
3f 67 25 04 21 20 00 07 20 90 00 / CP8
3b b7 11 00 81 31 90 43 a5 xx xx xx xx xx xx xx / CardOS 1.4 (CR80S)
3b b7 11 00 81 31 90 53 b5 xx xx xx xx xx xx xx / CardOS/EM 1.4(CR80S)
3b e9 00 ff c1 10 31 fe 55 c8 01 20 50 4e 34 30 31 32 ad / CardOS/M3
3b e2 00 ff c1 10 31 fe 55 c8 02 9c / CardOS/M4
3b a7 00 40 14 80 65 a2 14 01 01 37 / GPK
3b 27 00 80 65 a2 14 01 01 37
3b 2a 00 80 65 a2 01 01 01 3d 72 d6 41 / GPK 4000
3b a7 00 40 18 80 65 a2 08 01 01 52 / GPK 8000
3b ef 00 ff 81 31 66 45 7e 09 00 04 49 42 4d 20 43 43 43 30 30 31 20 c4 / IBM MFC 4.20
3.1.4CRASCommunicate with Script
This function allows to send a set of APDU commands to the card. The commands are specified in a script file which can be written by a member of the CardMan API team. On this way, also support engineers or others can manipulate data on the card when the have a script file.
In order to communicate with the card CRASInit and CRASConnect have to be executed.
The command takes two parameters. The first one is the handle (“Handle:”) received by calling CRASConnect. The other one is the script file (“Filename:”). In the current version of CardMan API the environment variable CRASSCRIPTS must be set to the directory where the script files are located. In future versions it should also be possible to enter a path.
When the script is executed, it’s firstly in a single step mode, where each command has to be acknowledged with the enter key. However, it’s possible to run through all commands in different speeds. This can be done with the keys “0” – “9”, whereas “0” is the fastest version, and “9” the slowest. To go back to single step mode press enter.
The program shows the command APDU (“Send:”) which are the data sent to the card, as well as the response APDU (“Receive:”). That are the data the card returns. Also the time needed for executing the command is shown. Thus, also simple performance tests can be performed with that tool. If the author of the script has added some comments, like meaning of the current command, they are shown before the command APDU (“Command:”).
The last two bytes of the response APDU are the so called status bytes. They show the error code of the card. A status 9000 means no error. When the program is not in single step mode, it runs through the commands until an error occurs (status bytes unequal to 9000 are returned). In this case it stops, or better goes back to single step mode. To perform the rest of the commands press “0” – “9” again or stay in single step mode. If the following commands should not be executed any more press escape. The meaning of the status bytes is in general defined by the ISO 7816-4 standard. However, the cards use also proprietary status codes.
The most important status bytes of ISO, which are used (in the “correct” meaning due to ISO) by all cards supported Utimaco are the following:
6381Last write operation filled the file. (no error, just a hint; can therefore be accepted)
63cXPIN verification failed. X is the number of still possible attempts. (probably the script
file tries to present the standard PIN (e.g “1234” for USER0), but the card has a
different PIN. In this case you can try the search in the script file for the string “1234”
and replace it by the correct PIN.)
6700Wrong length is specified in command APDU
6982Security status not satisfied (present the PIN with another tool, and try again)
6a82File not found
6a83Record not found
3.2CL7816-4 Commands
This submenu provides a function for each command defined in ISO 7816-4. There are commands defined for:
- Selecting files on the smartcard.
- Reading binary files, and record oriented files from the smartcard.
- Manipulating binary files (write, update, erase) and record oriented files (write, append, update) on the smartcard.
- Authentication with different mechanisms (PIN, Challenge/Response).
All of these functions are on a very low level, so that the user must be familiar with APDUs. So, we don’t go into more detail with this menu.
For more experienced users this menu is described in more detailed in chapter 5Advanced.
3.3CRBS Commands – Card Reader Binding Services
The binding services store persistent information in an INI-file, which is located in the Utimaco Shared Components directory. For each operating system a separate INI-file exists, which allow to use different settings. The files have the name "cardmanx.ini", where the "x" shall be replaced by an operating system specific letter ("w" for Win16, "n" for Win32, "o" for OS/2, "d" for DOS and "s" for Solaris - other OSes are currently not supported).
For a more detailed description the cardmanx.ini file, we refer to the functional specification of the CRBS module.
The CRBS submenu shows 17 commands, but only a few of them are of interest for this document.
60)CRBSInitThis is the first command that has to be called. If it has not been called, all other commands will fail.
61)CRBSCloseThis command should be called before the application is closed in order to avoid memory leaks.
62)CRBSSetBindingAn entry for a card reader can be made in the ini-file. (An ID is assigned to that card reader.) For a detailed description see 3.3.1CRBSSetBinding, CRBSClearBinding.
63)CRBSClearBindingThe entry in the ini-file for a card reader can be deleted again. More info is given in 3.3.1CRBSSetBinding, CRBSClearBinding.
67)CRBSListAssignedCardReadersShows a list of all card readers that have an entry in the ini-file, or in other words: Shows all readers to that an ID has been assigned. This function is explained in more detail in 3.3.2CRBSListAssignedCardReaders, CRBSListSystemCardReaders.
68)CRBSListSystemCardReadersShows a list of all readers that are installed. For more information see 3.3.2CRBSListAssignedCardReaders, CRBSListSystemCardReaders.
70)CRBSGetArchitectureThis function retrieves the architecture of a given card reader. For usage see 3.3.3CRBSGetArchitecture.
3.3.1CRBSSetBinding, CRBSClearBinding
CRBSSetBinding
An entry for a card reader can be made in the ini-file with this command. (An ID is assigned to that card reader.) CRBSInit has to be called before that command can be executed.
However, this entry can also be made by hand in the ini-file, or with the Control Panel Applet, which would be the best way.
The first parameter is the ID (“Logical Card Reader ID:”) to which the card reader should be assigned. This must be a letter between ‘A’ and ‘Z’. If the ID already exists for another reader, the old assignment is automatically be replaced by the new one.
The next parameter is the reader name (“Card Reader Name:”) due to the driver. Installed card readers can be retrieved with CRBSListSystemCardReaders (see 3.3.2CRBSListAssignedCardReaders, CRBSListSystemCardReaders).
The last parameter is the driver architecture ID (“Architecture:”). If you don’t know the architecture of your reader use CRBSGetArchitecture described in 3.3.3CRBSGetArchitecture. More information about the architecture ID are given in chapter 2General Description.
CRBSClearBinding
The entry in the ini-file for a card reader can be deleted again. CRBSInit has to be called before being able to execute this function.