OpenCard

OCF, the OpenCard Framework is a standard Java framework for working with Smart Cards.

PC/SC Wrapper CardTerminal

`com.ibm.opencard.terminal.pcsc10'

Note: If you are reading the text (ASCII) version of this page (doc/README-PCSCWrapper.txt), be informed that there is an hypertext (HTML) version which exactly matches the text version at the following location:

   components/pcsc-wrapper-2.0/doc/README-PCSCWrapper.html

This page is intended for "OpenCard Framework" users and developers; it is dedicated to the Java packages that provide useful code for using the PC/SC Resource Manager, to access Smart Card Readers. It allows to acces potentially all Smart Card Readers that have a valid PC/SC driver for the given platform.

E.g., concerning Gemplus readers, the following readers have PC/SC drivers: on Windows all PC-link readers: Serial (GemPC410), Parallel (GemPC-Touch 440), PCMCIA (GemPC400), USB (GemPC430), or contactless (GemEasy family), and on Linux and MacOS X: Serial (GemPC410), PCMCIA (GemPC400), USB (GemPC430).

Among other things, this page describes how to download/install the CardTerminal and use it, and also what new features are available.

These packages ("CardTerminal" in the OpenCard vocabulary) provides the OCF CardService or application developer with a high level API compliant with OpenCard 1.2 in order to communicate with the card using ISO protocols (i.e., using APDU data packets).

This is a second version with enhancements for T=0 and many other new features (e.g., internalReset, PowerManagement), and it is provided AS-IS. See the Important Note section below.

IMPORTANT NOTE: The presented Java software code is a beta-version and IS PROVIDED AS-IS by IBM, Gemplus, and potentially other contributors. Please see the LICENSE file for more details. Therefore, this code has not been tested by many people yet; it may contain bugs or even semantic misbehaviour; and it has not been reviewed as a supported Gemplus or IBM product; so comments, suggestions, problem reports, or even enhancements are highly welcome.

Distribution Availibility

License Policy

This package is free software provided with sources by IBM and Gemplus. This means that you should have received a copy of the source code with the executable form of this component (i.e., the JAR files), or if it is not the case, you can get it at the location given just below. Also, you have the rights to use it, adapt it for your needs, and redistribute copies of the component, whether it has been modified or not. See the BSD-style IBM LICENSE file, compliant with the OpenSource definition, for more details on redistributions conditions (basically do not advertise using the IBM name and retain the original copyright, even in the case of modifications).

This package is provided AS-IS. See the Important Note section above. A disclaimer of warranty and limitation of liability is included in the License.

You are free to use the generic PC/SC Wrapper CardTerminal, or write your own, starting from scratch, or adapt it. In the case where you have fixed problems or make enhancements to this package, we would like to get those changes back in order to integrate them for the benefit of most people.

Primary Web Location

This component primary web location is the official OpenCard Consortium Download Page as it is included into the official OpenCard Framework distribution (see the following package: "OpenCard Framework Reference Implementaion V1.2").

However, the version provided here includes additional features and bug fixes. It will be forwarded to the official OCF distribution maintener so that it can be available in the next major release of OCF.

In the meanwhile, it can be downloaded from the Gemplus Developer's Web Site OpenCard Page (in the "Technologies" section)

This web site is the developer's section of the general Gemplus web and it needs a registration before any downloading of code. It is a simple form requesting an email address and a password (similar to the Java developer's section).

In the OpenCard Page, you will find links to the PC/SC Wrapper CardTerminal Download Page. In case you are reading the ASCII version of this README file, the download page location is the following URL:

http://www.gemplus.com/technoopencard/cardterminals/ pcsc/download.html.

Software Organization

Archive Contents

The PC/SC Wrapper CardTerminal are distributed in a ZIP or in a TAR.GZ archive file. A detailed content of the archive can be found in the following automatically-generated Directory Hierarchy.

To summarize this hierarchy, the major files and directories found in the "pcsc-wrapper-2.0.{zip,tar.gz}" archive are:

    "doc/README-PCSCWrapper.txt": the ASCII version of this file,

    "doc/LICENSE-Reference-Impl.txt": copyright statements,

    "lib/pcsc-wrapper-2.0.jar": a ready to use Java JAR file,

    "components/pcsc-wrapper-2.0/doc/": package documentation,

    "components/pcsc-wrapper-2.0/src/": package source code,

    "components/pcsc-wrapper-2.0/doc/README-PCSCWrapper.html":
       this file (HTML version),

    "images/": miscellaneous icons.

Features

The PC/SC Wrapper CardTerminal provides to the client CardServices or applications, an OCF CardTerminal communication API in order to access to the card and reader through standardized protocols such as ISO7816-3 (i.e., T=0 or T=1 protocols).

In addition to this fundamental functionality, Gemplus has made some changes that were needed in the PC/SC CardTerminal so that it could handle the long APDUs (i.e., of T=0 case 4). In addition to this new feature, we also have made some other improvements. The list of all new features is:

automatic handling of T=0 case 4 long APDUs (as recently specified by the OCF Technical Committee, see the RFP1 for more details),
implementation of the optional "PowerManagement" interface,
"internalReset" can now return the first or the second ATR of the card. The ATR that is returned depends on the Power status of the card: if the PC/SC card handle is available (i.e., the card is already powered on), it retrieves the second ATR, otherwise (i.e., the card is powered off), it retrieves the first ATR.
the Factory support both the mode of accessing to all readers by default (which was the case in the previous version) and a more fine-grained mode in which we specify the readers and their mode of access. The mode of access, following the PC/SC specs can be SHARED or EXCLUSIVE.
addition of new exception messages,
addition of a public method "setISOTPDUMode" to select a method of APDU chaining that is full-ISO (i.e., when a card returns a 0x9000, then the terminal sends a GetResponse to extract the "le" bytes requested inside the APDU command) or non-ISO but common (i.e., when a card returns a 0x9000 to inform a good transfer of the APDU command, then the terminal terminates the transaction and returns the "sw1" and "sw2" to the user).

Missing features, for this first release (in the 2.x serie) are:

The newly developed version (from OCF 1.2) that allows to lock the entire reader (implementing a new feature of OCF1.2, see RFC 17 for more details) is not yet available with the automatic handling of T=0 case 4 long APDUs feature.

Installation

For installing the PC/SC Wrapper CardTerminal

See the Download Page for instructions on how to download and install the PC/SC Wrapper CardTerminal component on your platform.

For using the PC/SC Wrapper CardTerminal

In order to use the PC/SC Wrapper CardTerminal, you must:

Download and install it (see its Download Page), and
configure your "opencard.properties" in order to use the Pcsc10CardTerminalFactory factory.
Example 1: Using any reader declared for PC/SC (the list of available readers is automatically computed), type in your "opencard.properties" file (on one line):
```
OpenCard.terminals = com.ibm.opencard.terminal.pcsc10.
   Pcsc10CardTerminalFactory
```
Example 2: Specify SHARED or EXCLUSIVE options and/or specify a specific reader, type instead (on one line):
```
OpenCard.terminals=com.ibm.opencard.terminal.pcsc10.
   Pcsc10CardTerminalFactory|my|GCR410|SHARED
```

Developer's Notes

As this component is more aimed at users than developers, limited Developer's documentation is provided in this release. You can either directly browse the sources (see below), or look at the Javadocs for details on the package APIs.

Sources

The sources of the current version (V 2.0) have been compiled into hypertext (HTML) versions in the "components/pcsc-wrapper-2.0/doc/sources/" subdirectory.

Otherwise, for looking at the sources of previous versions, e.g., the one that is distributed with OCF 1.2, tagged "1.0" here:

$ cd components/pcsc-wrapper-2.0/src/
and use RCS's command co(1) to check out the files.

If you intend to work with RCS in order to retrieve, install, and/or edit previous versions, see also the RCS change logs that are provided in Appendix.

Appendixes

Appendix A. Change Logs

In order to help tracking new features and bug fixes, a listing of previous RCS change logs for the main file of the package (i.e., for MANIFEST) is provided below.

==================================================================
Log files for MANIFEST (from version 1.0 to now)
==================================================================
----------------------------
revision 2.0
date: 2001/06/14 13:32:36;
Distributed V2 with long APDU support.
Added support for <space> in names.
----------------------------
revision 1.99
date: 2001/06/14 13:13:36;
Alpha Version with long APDU support and other features.
Distributed 20/12/00
----------------------------
revision 1.0
date: 2001/06/14 09:12:45;
Official Version Distributed in OCF 1.2
==================================================================

Appendix B. GLOSSARY

This appendix is informative.

APDU

An APDU, Application Protocol Data Unit, is the basic command unit for a smart card. An APDU contains either a command message or a response message, sent from the card reader to the smart card or from the card to the reader.

API

An API, Application Programming Interface, is an abstract definition of a service that can be provided either by a server, a component, an object class, etc. In the Java world, an API can be a Java Interface or a set of interfaces and abstract or concrete classes. For servers or other computing languages, it can be a set or functions (such as the C-based PKCS#11 API) or a language independent API defined in an IDL, such as the OMG IDL.

OCF, OpenCard Framework

OCF, the OpenCard Framework, is a standardized, easy-to-use framework for implementing Smartcard-enabled solutions and Smartcard-based services. OpenCard Framework capitalizes on the broad, cross-platform benefits of Java, providing an open architecture and a set of common APIs (Application Program Interfaces) geared for this purpose. For more details about the basic architecture, concepts, and objectives of the OpenCard Framework, see the General Information Web Document and other documentation.

Appendix C. References