OpenCard

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

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.3/doc/README-GemplusGPK.html

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.

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/techno/opencard/cardservices/gpk/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.3.{zip,tar.gz}" archive are:

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

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

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

    "lib/CardID.class": a patch for OCF1.1.1 (see below),

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

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

    "components/gemplus-gpk-0.3/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, PK Directory, etc.), plus Public Key Files Creation APIs.

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.

download and install the distribution.
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.GPKCardServiceFactory
OpenCard.trace = opencard:6 com.gemplus:6
```
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.
4. Then, for an other CHV1, enter 11111111.

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.3) have been compiled into hypertext (HTML) versions in the "components/gemplus-gpk-0.3/doc/sources/" subdirectory.

Otherwise, for looking at the sources of previous versions:

$ cd components/gemplus-gpk-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.

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.3
date: 2001/07/10 14:01:16
Bug fix release: PKFiles PIN protections. mgmt of access conditions.

Details:

 - in GPKTest.java, Change the CardRequest object creation to conform
   to OCF 1.2 API. Add a log of the tests.
 - in GPKKeyGenerationService.java, in the "generateKeyPair" method,
   replace the loop with just one wait of GPK_MAX_GENERATION_TIME
   (was provoking a CardTerminalException on some readers).
   (fix from Thimo.Rauchhaupt@heitec.de)
 - in GPKAuthenticationCredential.java, in "externalAuthenticate",
   replace '0x00;' by '(byte)0x00;' (potential problem with JBuilder).
   (fix from Thimo.Rauchhaupt@heitec.de)
 - in GPKAuthorityKeyFile.java, GPKRSAKeyFile.java, GPKSignatureKeyFile.java,
   GPKSignatureUnwrapKeyFile.java, and GPKUnwrapKeyFile.java, Patched by
   Karl.Scheibelhofer@iaik.at and sadiq.mohammed@gemplus.com:
   Added management of PKFiles PIN protections: i.e., added constructors
   with rights and access conditions; change "GetRights" by "GetType"
   method; change all _RIGHTS constants by _TYPE constants, and compute
   both value, type, and rights.
----------------------------
revision 0.2
date: 2000/04/06 17:50:40
Second version. Lots of bugs fixes. Enhanced Signature Service and Factory.

Details:

GPKCardServiceFactory
 - the major new feature is a better compatibility of the 
   factory with non-GPK8000 cards (MPCOS, etc.). See below.
 - many enhancements in the "setupSmartCard" method that retrieves
   card specific information. This method has been adapted to
   recognize between MPCOS-EMV, GPK4000 (s, sp, su40, su256, or sd)
   and GPK8000 cards.
 - use of GPKAPDU instead of ISOAPDU
 - fix some method name in tracer outputs

GPKSignatureService
 - New feature by Alain Origlia (alain.origlia@gemplus.com), the sighHash
   feature has been implemented (off-card sign of a hash).
 - The card's signature is inverted, so the CardService has to inverse
   the response data to get the true signature

GPKTest
 - Patched by Dominique Morel (Dominique.Morel@gemplus.com): bug fixed
   in Public Keys tests "testPK()" when unwrapping features of the card
   are limited to 512 bits instead of 1024 (for export reasons): now
   unwrap only if RSA key modulus size equals digital envelope length.
 - In public keys test, display generated modulus and public exponent

GPKFileAccessService and GPKCardService
 - CastException in GPKCardService.provideCredentials()
 - a useless loop in has been removed in
   GPKFileAccessService.provideCredentials()

GPKFileUtilityService
 - New feature: add a lockUpdates(CardFilePath) method that locks
   updates on a file
 - in localizeAC, first verify that the file exists

GPKPINVerifier
 - We now allow the user to change the default PIN holder (by default,
   we use a GPKTransientPINHolder that reads secret codes from
   the keyboard and forgets them).

GPKId
 - during creation of the BigInteger, specifies that the sign
   must be positive

GPKKeyGeneration
 - the generated public key was stored inverted! It is now fixed.
 - during creation of the BigInteger, specifies that the sign
   must be positive
 - after generating a key pair, return a RSA public key with
   public exponent fixed to GPK8000's default value

GPKRSAKeyFile
 - use of java.security:
   CardServiceException replaced by InvalidKeyException
 - many new constants declared for cleaner code, e.g.,
   SIGNATURE_RIGHTS, SIGNATURE_UNWRAP_RIGHTS, UNWRAP_RIGHTS,
   AUTHORITY_RIGHTS, ENCODED_512, ENCODED_768, ENCODED_1024.
 - new feature: fromEncoding(byte[]) constructs a subinstance
   of GPKRSAKeyFile from the proprietaty encoding. The format
   is Rights/Path/Length encoded/Certification.

 - getEncoded() now returns the key file in its proprietaty
   encoding format.

GPKAuthorityKeyFile, GPKSignatureKeyFile.java, GPKUnwrapKeyFile
and GPKSignatureUnwrapKeyFile
 - use of "java.security" package: CardServiceExceptions replaced by
   InvalidKeyExceptions
 - use of constants (e.g., AUTHORITY_RIGHTS, SIGNATURE_RIGHTS, etc.)
----------------------------
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, 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