Dear OCFers,
The GPK8000 CardServices for OCF 1.1.1 and 1.2 are now available in
a technology preview version. You can download them now or read more
about them on our OpenCard pages.
o License : these CardServices are relased under a Gemplus
OpenSource/Free Software license (you name it).
o Download
The Home-Page of OpenCard Framework technology for the Gemplus
Developer's web site is:
http://www.gemplus.fr/developers/technologies/opencard/
From it, you will find links to the:
1. "CardTerminal Download Page", and
2. "CardServices Download Page"
the latter page containing both packages that you need for
GPK8000: 1) Generic CardServices and 2) GPK8000 CardServices.
Note: you still need to be registered before accessing these
pages, if not, then you have to visit the Developer's web
Home-Page (http://www.gemplus.fr/developers) before and register.
o More Information: see the attached ASCII file, README-GemplusGPK.txt
or browse its hypertext version from the Gemplus Developer's web
"CardServices Download Page". There is a section on contacts
(email, forum, or this mailing-list) at the end of the README file.
Please keep in mind that this is an alpha version.
However, as it is a quite big software package (11 java packages,
16.000 lines of code), we think that it will be useful for applications
or CardServices developpers that need crypto functionalities (Signature,
KeyImport, KeyGeneration, etc.).
Cheers,
Christophe.
= All truth passes through three stages. First it is ridiculed. =
= Second it is violently opposed. Third it is accepted as being =
= self-evident. -- Arthur Schopenhauer (1788-1860) =
--
-------------------------------------------------------------
[EMAIL PROTECTED] - Gemplus Research Lab
Phone: +33 4-42-36-57-83 | Fax: +33 4-42-36-55-55
-------------------------------------------------------------
Gemplus Developers OpenCard Framework
CardServices for Gemplus GPK Smartcards
`com.gemplus.opencard.service.gpk'
Note: If you are reading the text (ASCII) version of this page
(doc/README-GemplusGPK.txt), be informed that there is an hypertext
(HTML) version which exactly matches the text version at the following
location:
components/gemplus-gpk-0.1/doc/README-GemplusGPK.html
_________________________________________________________________
Abstract
This page is intended for Smartcards-aware applications developers; it
is dedicated to the Gemplus GPK Smart Cards Java packages that can be
used with the "OpenCard Framework". 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 GPK
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.
If you want to order some GPK8000 sample cards, contact your local
Gemplus sales representative or Yann LEBORGNE and Regis CALMES
_________________________________________________________________
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.
Related Reference Documentation:
- The LICENSE file for this packages.
- Opencard 1.1.1 Framework documentation: see the Opencard Web Site for
Programmer's Guide, Reference Javadocs, etc.
- com.gemplus.opencard.service.gpk package Reference Documents generated
by the JDK1.2 Javadoc tool.
- com.gemplus.opencard.service.gpk package Sources generated by the
Java2html tool.
- The GPK Reference Manual V2.2.
_________________________________________________________________
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 GPK 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 GPK 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/g
pk/download.html.
_________________________________________________________________
Software Organization
---------------------
Archive Contents
The GPK 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-gpk-0.1.{zip,tar.gz}" archive are:
"doc/README-GemplusGPK.txt": the ASCII version of this file,
"doc/LICENSE-GemplusGPK": copyright statements,
"lib/gemplus-gpk-0.1.jar": a ready to use Java JAR file,
"lib/CardID.class": a patch for OCF1.1.1 (see below),
"components/gemplus-gpk-0.1/doc/": package documentation,
"components/gemplus-gpk-0.1/src/": package source code,
"components/gemplus-gpk-0.1/doc/README-GemplusGPK.html":
this file (HTML version),
"images/": miscellaneous icons.
Features
The GPK CardServices provide a high-level pure java API in order to
access the Gemplus GPK8000 Smart Cards. There are eight GPK
CardServices available in the component. Their function are detailed
below.
GPKAdministrativeService
Access to GPK administrative commands that are not ISO defined, (e.g.,
getInfo, setCardStatus, setSecretCode, etc.),
_________________________________________________________________
GPKFileAccessService
ISO 7816-4 file access commands, as defined by the ISO standard, see
the OpenCard FileAcess APIs for more details, (e.g., exists, read,
write, etc.),
_________________________________________________________________
GPKFileSystemService
Proprietary creational commands, for complete file management, see the
OpenCard FileSystem APIs for more details, (e.g., create, delete,
invalidate),
_________________________________________________________________
GPKFileUtilityService
High-level functional API based on the previous one, i.e., commands
using files for security settings (e.g., createSecretKeyFile,
import3DESKey, importSecretCode, createTransparentFile,
createSecretCodeFile, etc.)
_________________________________________________________________
GPKSignatureService
Public key signature and verification commands, see the OpenCard
Signature APIs for more details, (e.g., signData, signHash,
verifySignature, etc.)
_________________________________________________________________
GPKKeyImportService
Public and private RSA keys importation commands, see OpenCard
KeyImport APIs, (e.g., importAndValidatePrivateKey,
importPublicKey,etc.)
_________________________________________________________________
GPKKeyGenerationService
On-board key generation commands, see OpenCard KeyGeneration APIs,
(e.g., generateKeyPair, readPublicKey)
_________________________________________________________________
GPKKeyManagementService
Other Proprietary commands related to PK (e.g., unwrapSecretKey,
createCardKeyFile, etc.),
_________________________________________________________________
As mentionned in the table, five of these CardService classes
implement the standard OCF interfaces (for their respective class of
functionality).
These CardServices provide a high-level API to the Smart Card-aware
application developer since most of the low-level and complex
sequences of APDU data packets are formated by the CardService layer.
Some security mechanisms (e.g., secure messaging, data ciphering, PIN
code verification) are also transparently handled by the CardService
layer. The application developer/user has only to supply data that is
necessary to security mechanisms, i.e., 3DES keys (Credentials) and
secret codes.
Backward Compatibility
Administrative, FileAccess, FileSystem and FileUtility classes and
interfaces are compatible with the following Gemplus Smart Cards:
* MPCOS-EMV,
* GPK2000,
* GPK4000, and
* GPK8000.
However, public key APIs (i.e., Signature, KeyImport, KeyGeneration
and KeyManagement) are not designed to operate with GPK4000 or earlier
cards, they should only work with GPK8000 and future cards.
Compatibility with GPK earlier cards for this set of features was not
in the scope of the project.
_________________________________________________________________
Installation and User's Guide
-----------------------------
For installing GPK CardServices
See the Download Page for instructions on how to download and install
the GPK CardServices component on your platform. Remember that, as
mentioned by the download page, an other component, "gemplus-service",
is required by the GPK CardServices. See also additional prerequisites
that are required by the GPK CardServices package (see below).
Additional Prerequisites
In addition to the prerequisites listed for all OCF components (i.e.,
JRE, Comm API, and OCF), there are some additional required software
packages:
* For the OpenCard Framework layer, you must use either OCF 1.2 or a
patched version of OCF 1.1.1. In fact, OCF 1.1.1 has a bug in ATR
recognition, so you must make sure you use the right CardID.class
patch. One is provided in the "lib/CardID.class" file of the
current component, you can patch the default version of OCF 1.1.1
by typing ('$' being a shell prompt):
$ jar uf lib/base-core.jar lib/CardID.class
* The use of a CardTerminal with the T=0 long APDU chaining
implemented is recommended (e.g., the pure-java
GemplusCardTerminal).
* Also, you will need a JCE provider, such as Cryptix. Next
paragraph explains how to declare this provider.
Crypto Engine Settings
The GPK CardServices rely on an external JCE provider for 3DES
security mechanisms (e.g., MAC, Ciphering). The used security
providers must be defined in the "jre/lib/security/java.security" file
as follows:
security.provider.1=cryptix.jce.provider.Cryptix
For using GPKCardService
This section shows how to run a simple test with a GPK card.
1. download and install the distribution.
2. configure your "opencard.properties" file in order to use the
Gemplus GPK factory name (i.e., GPKCardServiceFactory) and to
configure the trace level (it is recommended to lower it to 6 to
see the test outputs!).
Example: Using a GPK card (the line is not cut!):
OpenCard.services = com.gemplus.opencard.service.gpk.factory.GPKCardServiceFact
ory
OpenCard.trace = opencard:6 com.gemplus:6
3. test the component with the "GPKTest" program.
Example:
1. Type ('$' being a shell prompt):
$ java com.gemplus.opencard.service.gpk.test.GPKTest
2. Insert a GPK Smart Card,
3. For CHV1 and CHV2, enter respectively 01234567 and 44444444.
If during this test you encounter any error message, check the
Troubleshooting Section to see if hints are available for this error.
Note that this code is currently in alpha version and so limited
User's documentation is provided at this stage.
Please See the Javadocs for more details on the package API.
Limitations
This section provides a list of known limitations of the component.
* No purse API is provided for accessing the GPK8000 purse commands.
* When raising an administrative session key, the SelectFileKey APDU
always uses the first Administration Key (number 0).
* External and Internal Authentication APDUs always use the first
Authentication Key (number 0).
* The following commands sometimes involve 3DES data ciphering:
+ "Load Secret Key" for RSA secret key file importation.
Automatic key ciphering is done by the CardService layer.
+ "Update Binary" and "Write Binary" on secret keys and secret
codes files according to access conditions. The data
encryption is not yet implemented.
+ "Verify" and "Set Secret Code". The data encryption is not
yet implemented.
Actually, for secret key importation, secret code importation and
verification, the data field encryption is not handled by the
CardService layer. For secret codes the main reason is due to the
fact that the "Mode" flag indicating if secret codes have to be
presented plain or ciphered is embedded into the file. This
information is not returned in the file descriptor after a select
command and thus can't always be detected by the CardService
(since the file can be unreadable). When importing or verifying
secret keys and codes, the data ciphering should be done at the
application level.
* Access Conditions of public key files (up to 2 PINs) preliminary
verification is not automated and should not be used. The PK
additional secret codes references are contained in the file data,
not in the descriptor.
* External Authentication process is a little bit cumbersome.
* Card file names must be compliant with the following rule: like
"XX00" for DFs and "XXYY" for EFs. File Symbolic names are not
allowed.
_________________________________________________________________
Developer's Notes
-----------------
Sample Code
Many types of CardService API calls are implemented in the class named
com.gemplus.opencard.service.gpk.test.GPKTest contained in the
package.
Complete Sources
Sources of the current version (V 0.1) have been compiled into
hypertext (HTML) versions in the
"components/gemplus-gpk-0.1/doc/sources/" subdirectory.
Otherwise, for looking at the sources of previous versions:
1. $ cd components/gemplus-gpk-0.1/src/
2. 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.
Troubleshooting
This section provides tricks that are nice to know when using the
component. It should also be enhanced in the future with a FAQ of
common encountered problems.
* Automatic raise of an administrative session key when importing a
secret key is achieved by associating the "Load Private Key"
command with Access Group 1 (this is arbitrary and not specified
in the GPK Manual). Thus, public files have a CardFilePath
argument in constructor (the path to the secret key file
protecting the public key file).
* If you have a NoClassDefFoundError error on:
+ an OpenCard object (e.g., CardService), check that
base-cor.jar and base-opt.jar OpenCard distributions have
been installed in your CLASSPATH (or in the jre/lib/ext
directory when using a 1.2 Java).
+ GemplusCardTerminalFactory or an other CardTerminal factory,
check that what you have specified in the property file as a
CardTerminal component has been installed and that it is
properly suited for the current reader.
+ Idem for GPKCardServiceFactory.
* If you have a "Warning, PK operations tests can't be performed
with this card" warning message, it means that you have inserted a
card of the GPK family but from a previous version. See the
Backward Compatibility Section for more details.
* If you see no test outputs, only the creations of "File
CardServices" and "GPK8000 CardServices" and then everything stops
without any message, it might be because you have no JCE provider
installed into your CLASSPATH or jre/lib/ext directory. For
instance, if you are using cryptix, you should have
cryptix-jce-api-1.2.jar and cryptix-jce-provider-1.2.jar
installed.
* If you have a: "java.security.NoSuchAlgorithmException: Algorithm
not found. [Cipher.DESede/ECB/None]" error message, it means that
you have not declared the JCE provider into you global
"java.security" file (see the Crypto Engine Settings Section for
more details).
* Note: the card accessor component handles T=0 protocol issues if the
CardTerminal does not.
Known problems
Some known problems are still present due to a lack of time for fixes:
* Under Linux with JDK1.2 from Blackdown, the test program waits
forever after the first PIN code AWT window has been closed. A
workaround is to comment this test out (i.e., the call to
testSecretCodes() in the "TEST_ALL" declaration) and recompile.
* In the previous cryptix JCE releases, a NullPointerException was
caught when using "DESede/CBC/None". This is why, in the
cryptographic checksum (CRYCKS) computation made in CryptoUtils
class, the CBC mode is emulated with actual ECB and XOR
operations. With the latest cryptix release, the CBC mode is
available and should therefore be used rather than ECB. It would
also allow to suppress the following problem.
* 3DES ciphering does not work so far if Left DES Key is different
from Right DES Key. This problem fix should be a priority since it
means 3DES is reduced to DES.
* RSA CRT keys importation and signing works. Unfortunatly not
verification.
_________________________________________________________________
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.1
date: 2000/02/03 14:51:22
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.
_________________________________________________________________
Authentication
The process whereby a card, terminal or person proves who they are. A
fundamental part of many cryptography systems. We distinguish between
the following two types:
- External Authentication
In a smart card environment, this is the procedure used to
authenticate the external world (e.g., terminal) to the card.
- Internal Authentication
In a smart card environment, this is the procedure used to prove that
the card is genuine by means of an algorithm, a random value and a
secret key (or a pair of public/private keys).
The authentication process can be further distinguished between
passive procedures in which the same values are used each time (e.g.,
PIN) and active procedures in which an algorithm and variable values
are used.
_________________________________________________________________
GPK
GPK, Gemplus Public Key, is a Smart Card Operating System adapted to
multi-purpose applications and payment applications.
_________________________________________________________________
Key
A key is a value that is used with a cryptographic algorithm to
encrypt (or sign) data. The longer the key, the more secure the
encryption. Secret Key Cryptosystems use only one secret key. Public
Key Cryptosystems used a public key to encrypt (or verify) data and a
secret key to decrypt (or sign) it.
_________________________________________________________________
MAC
MAC is a 3DES computed Message Authentication Code used to ensure
integrity in secure messaging.
_________________________________________________________________
PIN
PIN, the Personal Identification Number, is the number or code that a
cardholder must type in to confirm that he or she is the genuine
cardholder.
_________________________________________________________________
PKCS#11
PKCS, the Public-Key Cryptography Standard, is a set of informal
inter-vendor standards developed in 1991 under the impetus of RSA.
PKCS#11 is the Cryptographic Token Interface Standard. See the
References on PKCS11 for more details.
_________________________________________________________________
Public Key Algorithm
Also known as asymmetric algoritm. This uses different keys to encrypt
and decrypt data. Furthermore, the decryption key cannot be calculated
from the encryption key. See the References on Cryptography for more
details.
_________________________________________________________________
Purse
A purse is a conceptual entity with which financial transactions are
performed. A Purse file on the card contains purse date such as
balance, credit and debit security attributes, and the pointer to the
cryptographic key used to generate credit certificates.
_________________________________________________________________
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.
_________________________________________________________________
Secure Messaging
Process used by the GPK Smart Card to protect administration command
transmissions between cards and terminals. This can be done either by
encrypting the data that is sent to the card or by sending three bytes
of a cryptographic checksum with the command.
_________________________________________________________________
Signature
A numeric cryptogram calculated with a given algorithm and a key.
_________________________________________________________________
DES, 3DES
DES (Data Encryption Standard) is the most widely used Private Key
encryption algorithm (56-bit key). A strengthened version of DES
called triple DES (or 3DES) is commonly used in cards. 3DES produces
the most secure cryptographic mode in GPK cards.
_________________________________________________________________
3DES Key
Cryptographic keys that GPK uses for encrypting and decrypting data
along with the 3DES algorithm.
_________________________________________________________________
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
[Java JCE]
"Java Cryptography Extension" Home-page, by Sun Microsystems.
Available at: http://www.javasoft.com/products/jce/
Providers list:
http://www.javasoft.com/products/jce/jce12_providers.html
Cryptix: http://www.cryptix.org
[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
[Smart Card Application Development Using Java]
"Smart Card Application Development Using Java", by Hansmann,
Uwe; Nicklous, Martin S.; Sch�ck, Thomas and Seliger, Frank,
ISBN 3-540-65829-7, Springer Heidelberg, 1999.
Information about this book is available at:
http://www.opencard.org/SCJavaBook
[ISO/IEC 7816]
"ISO standard for ICCs with contacts", ISO Standard.
Available at: http://www.iso.ch
[Javacard]
"Java Card Technology" Home-Page, by Sun Microsystems.
Available at:
http://java.sun.com/products/javacard/index.html#presentations
[Applied Crypto]
"Applied Cryptography Second Edition", by B. Schneier, John
Wiley & Sons, 1996. ISBN 0-471-11709-9.
An introduction to cryptography for all ages. See the Applied
Cryptography Home-Page.
[Crypto Papers]
"Research Publications", Gemplus.
(Research papers that have been published by the Gemplus
cryptographic department).
Available at:
http://www.gemplus.fr/smart/r_d/publications/index.htm
[PKCS#11]
"PKCS #11: Cryptographic Token Interface Standard.", RSA.
Available at:
http://www.rsa.com/rsalabs/pubs/PKCS/html/pkcs-11.html
[GPK]
"GPK8000 Reference Manual V2.2", Gemplus.
Available in the GPK8000 SDK sold by Gemplus.
_________________________________________________________________
Contacts
Several communications tools are available, please select the right
one according to your needs, i.e.,:
* For submitting source code enhancements or patches to problems,
send an email directly to the component author.
* For help on usage, or submissions of suggestions/problem reports,
post your comments or questions to the Gemplus Developer's Site
Forum (in the topic named "OCF"),
* At last, for any comments on the OpenCard framework (i.e., not
directly related to GPK issues), post your comments or questions
to the OpenCard mailing-list (instructions on how to subscribe are
available on the OpenCard Home-Page).
_________________________________________________________________
Last changes: Thu Jan 27 2000
