OpenCard

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

Generic CardServices for Gemplus ISO7816-4 Smartcards

`com.gemplus.opencard.service'

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

   components/gemplus-service-0.3/doc/README-GemplusService.html

This page is intended for "OpenCard Framework" CardService developers; it is dedicated to the Java packages that provide useful code for FileSystem-based Gemplus Smart Cards, compliant with ISO7816-4, in order to develop higher-level CardServices for these cards. Among other things, it describes how to download, install, and use them.

These packages ("CardServices" in the OpenCard vocabulary) provides the Java developer with a high level API compliant with the ISO standard; they use the CardTerminal layer of OpenCard in order to communicate with the card using ISO protocols (i.e., using APDU data packets).

This is a first version and is provided AS-IS. See the Important Note section below.

IMPORTANT NOTE: The presented Java software code is an alpha-version for developers and IS PROVIDED AS-IS by Gemplus. 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 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 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 our LICENSE file, compliant with the OpenSource definition, for more details on redistributions conditions (basically do not advertise using the Gemplus 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 Gemplus CardServices, or write your own, starting from scratch, or adapt them. 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 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 Generic CardServices 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/developers/technologies/opencard/cardservices/service/download.html.

Software Organization

Archive Contents

The Generic CardServices 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 "gemplus-service-0.3.{zip,tar.gz}" archive are:

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

    "doc/LICENSE-GemplusService.txt": copyright statements,

    "lib/gemplus-service-0.3.jar": a ready to use Java JAR file,

    "components/gemplus-service-0.3/doc/": package documentation,

    "components/gemplus-service-0.3/src/": package source code,

    "components/gemplus-service-0.3/doc/README-GemplusService.html":
       this file (HTML version),

    "images/": miscellaneous icons.

Features

The Generic CardServices for FileSystem-based cards provide a high-level pure java API in order to access features of ISO7816-4-compliant cards. We can distinguish three major Java packages each of which providing a class of functionality:

'access' package

This package defines base classes and interafces for "Card Accessors". A Card Accessor provides low-level methods to work with a filesystem-based smart card (e.g., getCurrentFile, selectFile, etc.).

'file' package

This package defines base class for Gemplus filesystem-based CardServices. An abstract class for ISO 7816-4 file access functionalities is defined (see OpenCard FileAccess interface for more details).

'util' package

This package includes several utility classes for: manipulating arrays, and computing cryptographic keys or cryptograms. It also defines a CommandAPDU class that knows ISO 7816-4 constants.

These CardServices provide tools for the developer of CardServices that work with ISO7816-4 cards. Starting from these base classes and interfaces allow to leverage on previously developed CardServices.

Backward Compatibility

These generic CardServices should be compatible with the following Gemplus Smart Cards:

MPCOS-EMV,
GPK2000,
GPK4000, and
GPK8000.

But not with the GemXplore cards family because the GSM11.11 standard is not compatible with the ISO7816-4 norm (i.e., several features, such as the coding of error messages, are incompatible).

Installation

For installing the Generic CardServices

See the Download Page for instructions on how to download and install the Generic CardServices component on your platform.

Developer's Notes

The three packages provided by this component should be considered as a developer's library to develop future CardServices. As it is a first alpha version, 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 packages APIs.

Sources

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

Otherwise, for looking at the sources of previous versions:

$ cd components/gemplus-service-0.3/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 0.0 to now)
=============================================================================
----------------------------
revision 0.3
date: 2001/07/10 14:02:41;
Bug fix release: new method to concatenate multiple readings.
----------------------------
revision 0.2
date: 2000/03/30 15:55:53;
Patched by Karl Scheibelhofer (Karl.Scheibelhofer@iaik.at) in
CryptoUtils.java. The Triple DES constants have been changed
for better JCE compliance (change of "None" by "NoPadding").
----------------------------
revision 0.1
date: 2000/02/03 14:59:47
First web-distributed version.
=============================================================================

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