`com.gemplus.opencard.terminal'

   components/gemplus-terminals/doc/README-GemplusCardTerminals.html

IMPORTANT NOTE: The presented Java software code is a beta-version for developers and IS PROVIDED AS-IS by Gemplus and many contributors (see the RCS log files). 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.

Related Reference Documentation:

• Opencard 1.1.1 Framework documentation: see the Opencard Web Site Documentation for Programmer's Guide, Reference Javadocs, etc.

• com.gemplus.opencard.terminal package Reference Documents generated by the JDK1.2 Javadoc tool.

• com.gemplus.opencard.terminal package Sources generated by the Java2html tool.

• The GemCore and OROS Reference Manuals.

1 Distribution Availibility

This package is distributed freely with sources by Gemplus and can be downloaded from the Gemplus Developer's Web Site OpenCard Home-Page at the following URL:

http://www.gemplus.com/developers/technologies/opencard/

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 Home-Page you will find links to the CardTerminals component distribution Download Page at the following URL:

http://www.gemplus.com/developers/technologies/opencard/cardterminals/download.html.

2 Software Organization

2.1 Source Directory Hierarchy

The files and directories found in the "gemplus-terminals-4.2.{zip,tar.gz}" archive are:

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

    "doc/LICENSE-GemplusCardTerminals": copyright statements

    "lib/gemplus-terminals-4.2.jar": a ready to use Java JAR file

    "components/gemplus-terminals-4.2/doc/": package documentation

    "components/gemplus-terminals-4.2/src/": package source code

    "components/gemplus-terminals-4.2/doc/README-GemplusCardTerminals.html":
       this file (HTML version)

2.2 Features

• Classes related to the ExtendedCommandAPDU functionality (V0.2):

      ExtendedCommandAPDU, APDUDataInputStream, APDUDataOutputStream,
      TestExtendedCommandAPDU
  

• Classes related to the Gemplus Card Terminals drivers (V4.2):

      GemplusCardTerminalFactory, GemplusCardTerminal,
      GemplusBlockProtocol, etc.
  

3 Installation and User's Guide

3.1 For installing Gemplus CardTerminals

3.2 For using Gemplus CardTerminals

1. download and install the distribution.

2. configure your "opencard.properties" file in order to use the Gemplus factory name (i.e., GemplusCardTerminalFactory) and to specify the CardTerminal name, type, and if applicable, port. Currently supported readers types are:

   "EPAD500", "EPAD500-MS0", "EPAD500-MS2", "GCR400", "GCR410",
   "GCR410P", "GCR500", "GCR500-ECM", "GCR500-MS0", "GCR500-MS2",
   "GCR500-MS4", "GCR700", "GCR700-MUB", "GCR700-MS0", "GCR700-MS2",
   "GCR700-MS4", "GCR800", "GCR800-MS0", "GCR800-MS2", "GCR800-MS4",
   "GCI400", "GCI410", "GCI500", "GCI500-MS0", "GCI500-MS2", "GCI500-MS4",
   "GCI400-MS4", "GemPC410", "GemSelf500", "GemSelf500-ECM", "GemSelf500-MS0",
   "GemSelf500-MS2", "GemSelf500-MS4", "GemSelf700", "GemSelf700-MUB",
   "GemSelf700-MS0", "GemSelf700-MS2", "GemSelf700-MS4", "GemSelf800",
   "GemSelf800-MS0", "GemSelf800-MS2", "GemSelf800-MS4"
   

   Example 1: Using a GCR400 under Windows on first port (the line is not cut!):

   
   OpenCard.terminals = com.gemplus.opencard.terminal.
      GemplusCardTerminalFactory|mygcr|GCR400|COM1
   
   

   Example 2: Using a GCR410 under Linux on first port (the line is not cut!):

   
   OpenCard.terminals = com.gemplus.opencard.terminal.
      GemplusCardTerminalFactory|mygcr|GCR410|/dev/ttyS0
   
   

3. test the component with any of the "demos.samples.*" programs of OpenCard.

   Example: printing a card Answer to Reset:

   1. Type ('$' being a shell prompt):

           
           $ java demos.samples.GetCardID
           
           

   2. And insert a Smart Card.

3.3 For using the ExtendedCommandAPDU classes

3.4 Slot IDs

GCR500-MS4

GCR800-MS4

4 Developer's Notes

This section contains notes for CardTerminal developers who whish to enhance the package. More documentation will be made available in the future.

4.1 Architecture of the CardTerminal Package

4.2 Inheritance Diagrams of ExtendedCommandAPDU and related class

4.3 Sources

Otherwise, for looking at the sources of previous versions:

1. $ cd components/gemplus-terminals-4.2/src/

2. and use RCS's command co(1) to check out the files.

For example, to retrieve and compile the previous major version (3.1), type (here in a Unix Shell syntax using JDK tools):

1. $ cd components/gemplus-terminals-4.2/src/

2. $ mkdir tmp ; cd tmp

3. $ ln -s ../RCS .

4. $ co -r3.999 APDUDataInputStream.java APDUDataOutputStream.java APDUDataStreamException.java ConnectionException.java ExtendedCommandAPDU.java GemCoreCardTerminal.java GemplusBlockProtocol.java GemplusCardTerminalFactory.java GemplusSerialCardTerminal.java Makefile OrosCardTerminal.java TestExtendedCommandAPDU.java

5. $ javac -d . *.java

6. $ jar cvf gemplus-terminals-3.1.jar com

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.

Appendix A. Changes

=============================================================================
Log files for MANIFEST (from version 3.1 to now)
=============================================================================
----------------------------
revision 4.1
date: 2000/01/11 18:32:47
V4: Complete new architecture with Interface/Function/Communication Layers.
----------------------------
revision 3.999
date: 2000/01/10 19:12:11
Last Version saved in 3.x branch. Actual Version=3.1
----------------------------
revision 3.1
date: 2000/01/10 19:05:38
Version 3.1. See log file of GemplusSerialCardTerminal.java for details.
=============================================================================
Log files for GemplusSerialCardTerminal.java (from start to version 3.1)
=============================================================================
----------------------------
revision 3.1
date: 1999/06/29 10:54:26
ExtendedCommandAPDU and related files (APDUDataInputStream,
APDUDataOutputStream, APDUDataStreamException) switch from
version 0.1 to version 0.2. These facilities are decoupled
from the OROS/GemCore drivers, they are utility classes that
extend and enhance the OCF APDU classes. IMPORTANT: there is
an API change between 0.1 and 0.2 (write methods change from
for instance writeInt to write). See their log file for more
details.
Also in GemplusSerialCardTerminal.java, a bug has been fixed
in a while loop (test is now strict).
----------------------------
revision 3.0
date: 1999/02/11 17:21:16;
no modifications from 2.99: final 3.0 version.
----------------------------
revision 2.99
date: 1999/02/09 15:38:12;
(3.0 beta) Bug fixed for cards only using T=1 protocol.
----------------------------
revision 2.90
date: 1999/02/08 15:42:20;
Third major version (3.0 alpha) with complete rename of files and
many new features: 1) OROS support, 2) two-slots support (GCR700),
3) sendTerminalCommand support, 4) when available implements
clearDisplay and display (screen management). See the README file
for a detailed list. In addition, GemplusCardTerminalFactory has
been renamed and updated to support all the new terminal names, and
GCR410CardTerminal has been redesigned and splited into an inheritance
tree of three classes: GemplusSerialCardTerminal, and GemCoreCardTerminal
plus OrosCardTerminal. GCR410T1Protocol has been renamed
GemplusBlockProtocol.
----------------------------
revision 2.1
date: 1999/01/11 17:32:14;
Addition of new features and bug fixes by Gilles Pauzie (e.g., the three
ISO 7816-4 Cases, TLP mode disabled, ISO-Card mode selected, baud rates,
powerUp/powerDown fixed, no PTS negociation).
----------------------------
revision 2.0
date: 1998/12/03 14:09:02;
GCR410CardTerminal in com.gemplus zone
----------------------------
revision 1.11
date: 1998/12/01 11:09:31;
Patched by dave.durbin@jcp.co.uk (Mon, 30 Nov 1998) for GemCore
compatibility
----------------------------
revision 1.10
date: 1998/10/22;
IBM version of this package : com.ibm.opencard.terminal.gemplus,
delivered with the official OCF1.1 in reference-terminals-pureJava.jar
========================================================================

Appendix B. GLOSSARY

This appendix is informative.

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.

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, 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

This appendix is informative.

[Design Patterns]

"Design Patterns: Elements of Reusable Object-Oriented Software.", by Gamma, Erich; Helm, Richard; Johnson, Ralph; and Vlissades, John, Addison-Wesley, 1994.

[Frameworks]

"Building Object-Oriented Frameworks", by Adolfo M. Nemirovsky (Taligent).
Available at: http://www.ibm.com/java/education/oobuilding/

[Java Intro]

"The Java Tutorial Second Edition", by Mary Campione, Kathy Walrath, Addison-Wesley, March 1998.
Available at: http://java.sun.com/docs/books/tutorial/index.html

[Java Documentation]

"Java Platform Documentation" Home-page, by Sun Microsystems.
Available at: http://java.sun.com/docs/index.html

[Opencard Intro]

"OpenCard Framework -- General Information Web Document", by "The OpenCard Consortium", October 1998.
Available at: http://www.opencard.org/docs/gim/ocfgim.html

[Opencard Whitepaper]

"OpenCard Framework", by Reto Hermann, Dirk Husemann (IBM Research Division).
Available at: http://www.ibm.com/java/education/opencard-framework/

[Opencard Programming]

"OpenCard Framework 1.1.1 Programmer's Guide", by "The OpenCard Consortium", April 1999.
Available at: http://www.opencard.org/docs/pguide/PGuide.html

[ISO/IEC 7816]

"ISO standard for ICCs with contacts", ISO Standard.
Available at: http://www.iso.ch

[GemCore]

"GemCore Reference Manual", by Gemplus, May 1997.
Available at: http://www.linuxnet.com/

Last changes: Wed Jan 12 11:07:27 WET 2000