Release Notes

Development Kit for the Java Card™ Platform
Version 2.2.2


Binary Release


March 2006
 

[Skip TOC]

Table of Contents

Introduction
Supported Platforms
Installation Instructions and Setting Up Your Environment
Documentation Roadmap For The Binary Release
Development Kit Documentation Bundle, Binary Release
Ant Tasks Bundle
Specification Documentation Bundle
White Papers
New Features and Improvements
Known Bugs and Issues
Where to Find Product Information and News

Introduction

These release notes describe the Development Kit for the Java Card™ Platform, Version 2.2.2. This binary release is available in separate bundles for the Solaris™, Linux, and Microsoft Windows operating systems.  These release notes pertain to both the development kit binary release and the development kit binary release with cryptography extensions. Issues that are marked (Development Kit with Cryptography Extensions only) pertain only to the Development Kit Binary Release with Cryptography Extensions, Version 2.2.2.

The development kit runs on a workstation using a Java™ Virtual Machine (VM). The virtual machine for the Java Card platform, version 2.2.2, is written in the "C" programming language.  For more details on the reference implementation (RI), please refer to the User's Guide that is installed with this kit.

Supported Platforms

Java Development Kit software: Java™ 2 Standard Edition (J2SE™) SDK, version 1.5. You can download the supported SDK from http://java.sun.com/j2se/.

This release was built using gcc version 3.2.3 on Windows, 3.2.2 on Linux, and the Sun™ Studio 10: C 5.7 Compiler on Solaris.  The GNU Compiler Collection, gcc, can be obtained at http://gcc.gnu.org.

NOTE: The Linux platform version was tested on the English language SuSE Linux, kernel 2.6.5-7.139, and gcc version 3.2.2. The Linux platform version is unsupported;  Sun Microsystems may choose not to address problems or bug reports submitted against the Linux platform version.

No specific card readers are supported.

[Top]

Installation Instructions and Setting Up Your Environment

For detailed instructions on installing the binary release, see Chapter 2, "Installation" in the Development Kit User's Guide that is included with this development kit. That chapter also describes any additional tools you might need for setting up your environment, such as Apache Ant.  See the Development Kit User's Guide or Ant Tasks User's Guide for more information on Apache Ant installation and setup.

[Top]

Documentation Roadmap For The Binary Release

These release notes are at the base of a hierarchy of files in the unzipped download bundle.  Within the subdirectory java_card_kit-2_2_2 you will find several additional bundles: the Java Card specifications, the development kit documentation, the Ant Tasks, and the Java Card platform binary code itself.  You must unzip all these bundles in the subdirectory java_card_kit-2_2_2 to have full use of this development kit.

Documentation for version 2.2.2 of the Java Card platform binary release can be found in the development kit documentation bundle, the Ant tasks bundle, and the specification bundle. Note that the specifications within this download bundle are identical to the specifications available for separate download from the Java Card technology download web site.

Most documents are available in both HTML and PDF formats. HTML can be viewed with any CSS-compliant browser, such as:

PDF files can be viewed in your web browser with an appropriate plugin or in Adobe® Acrobat Reader. Most recent browsers include the PDF reader plugin. If your browser does not, you can download the plugin from the browser vendor's web site or the Adobe web site at

http://www.adobe.com/products/acrobat/readstep.html

Documentation files packaged in the release were current when the release shipped. See any updates for the Java Card technology web site at

http://java.sun.com/products/javacard

Development Kit Documentation Bundle, Binary Release

The following table lists the main binary release documentation, which is in the subdirectory java_card_kit-2_2_2/doc.
 

Document Description
Development Kit User’s Guide, Version 2.2.2 
Describes how to run the binary release for the Java Card Platform, Version 2.2.2.  You will find a User's Guide is in this bundle that corresponds to the type of development kit you have downloaded, either with or without the cryptography extensions.
The Javadoc™ tool files for the Java Card remote method invocation (Java Card RMI) client-side API are also included in HTML format and in PDF format.
Application Programming Notes, Version 2.2.2
 Contains tips and guidelines for the applet developer who is using the Java Card Application Programming Interface for the Java Card Platform, Version 2.2.2, to implement applet management, multiselectable applets, logical channels and Java Card RMI. It is also for developers who are considering creating a vendor-specific framework based on any of the version 2.2.2 Java Card technology specifications.
The Javadoc tool files for the APDU I/O API are also included in HTML format and in PDF format.

Ant Tasks Bundle

The development kit tools require the use of Apache Ant.  However, the Ant tasks in the Ant tasks bundle are not part of the development kit and their use is optional and unsupported. See the Apache web site at http://ant.apache.org for information on Ant.

The Ant tasks bundle unzips within the binary release bundle at java_card_kit-2_2_2/ant-tasks.  When you unzip the Ant tasks bundle, the Ant tasks' Java Archive (JAR) file is extracted into the subdirectory java_card_kit-2_2_2/ant-tasks/lib/jctasks.jar. The user's guide for the Ant tasks is extracted into the subdirectory java_card_kit-2_2_2/ant-tasks/docs. For more information, see Ant Tasks User's Guide.

NOTE: The use of Ant is supported only for use with the development kit tools. The use of Ant outside the development kit is optional and not supported. Furthermore, the Ant tasks documented in the Ant Tasks User's Guide have not been thoroughly tested. 

Document Description
Ant Tasks User's Guide, Version 2.2.2 Describes how to use the Ant tasks in the development kit to create your own, customized Ant tasks.  The Javadoc tool files for the Ant tasks API are also included in HTML format and in PDF format.
Ant Tasks Release Notes, Version 2.2.2 Describes the purpose and limitations of the Ant tasks provided with the development kit. While the Ant tasks are necessary to run the development kit, they are unsupported for use outside the development kit.

Specification Documentation Bundle

These documents are included in the specification bundle that is included with this binary release, as well as in the separately downloadable specification bundle. The specification bundle unzips into the subdirectory java_card_kit-2_2_2/jc_specification.

Document Description
Release Notes for the Java Card Specifications, Version 2.2.2
Describes changes to the specifications since Version 2.2.1 of the specifications.
Application Programming Interface for the Java Card Platform, Version 2.2.2 Provides the documentation for the Java Card API in PDF and HTML formats.
Virtual Machine Specification for the Java Card Platform, Version 2.2.2 Assists developers in creating an implementation, developing a specification to extend the Java Card technology specifications, or in creating an extension to the Java Card runtime environment. The specification is provided in PDF and HTML formats.
Runtime Environment Specification for the Java Card Platform, Version 2.2.2 Assists Java Card runtime environment implementers in creating an implementation, developing a specification to extend the Java Card technology specifications, or in creating an extension to the Java Card runtime environment. The specification is provided in PDF and HTML formats.

White Papers

The development kit documentation references the following white papers. You can obtain these white papers from the Java Card technology web site at http://java.sun.com/products/javacard.

Document Description
Off-Card Verifier White Paper This white paper describes the off-card verifier for the Java Card platform. The off-card verifier provides the functionality for verifying that Java Card applets (CAP files) and export files conform to the Java Card specifications and platform interoperability standards.
Java Card RMI Client Application Programming Interface This white paper describes a sample client-side API to be used in client applications which access a Java Card Remote Method Invocation (RMI) server applet executing on the smart card. This API is presented as an aid to developers who are writing their own client-side API.

[Top]

New Features and Improvements

[Top]

Known Bugs and Issues

This section describes release limitations and issues.

BUG ID
 DESCRIPTION
6301113 Error T=0 CASE 2 APDU with Le > 0xF9 : CadT0Client.isoOut only supports Le up to 249.
6316626 Apdutool script must follow ISO format.
6324856 Apduio/apdutool cannot handle T=0, Case 4 with Lc < 256, Le > 256.
6322909 T=0, CASE 4 with Le=00 (256) should be short case (4S).
6393099
 Maskgen builds mask with negative remaining ROM space.
6395309
 In T=0 apdu.setOutgoingNoChaining() does not return 256, applet implements ExtendedLength interface.
6357521
 Contactless interface activation before contacted interface activation is not supported in the C-language Java Card Runtime Environment (cref) or the Java Card WDE at this time.
6328483
For case 4E, APDU in T=0.  Section 11.2.3 in the ISO 7816-3 spec describes the Command APDU structure for case 4.  In case 4E, the entire command APDU structure is encapsulated in a series of envelope commands. Section 11.3.7 never says that LE should not be included; it only says that the entire APDU command should be the envelope. The specification is ambiguous whether LE should be included.  For the Java Card Platform, v2.2.2 release, LE is included in the encapsulated APDU.

T=1/T=0 Protocol Differences in API Behavior

There are significant differences in layering between the T=1 and T=0 protocols. The Java Card API behavior can substantially vary depending on the protocol implemented underneath. Specifically, T=0 depends greatly on the application to be able to correctly interpret an APDU because it is virtually impossible to tell by simply examining the buffer,  whether an APDU is case 1 or case 2E, for example. T=1 corrects these deficiencies by making the protocol self-contained because all information to correctly interpret an APDU is in the T=1 data structures themselves.

As a result of these low-level differences, certain API calls might behave differently, or return different results, depending on the underlying protocol. Incorrectly interpreting an APDU in T=0 might result in desynchronized I/O, and thus lead to errors or applet exceptions thrown by the Java Card runtime environment. It is important that programmers take care on using the API calls correctly in order to help the Java Card runtime environment  to better interpret APDUs in T=0, and to adhere to API call semantics in order to ensure correct interpretation of results, and also isolate the applets from low-level protocol differences.

T=CL Protocol Dual Interface Only

The T=CL protocol is not supported in single interface configurations.  You cannot build cref with a single interface protocol that supports T=CL.  You can build it only with a dual interface.

Using a Contactless cref

Although the Java Card specification specifically allows you to simulate use cases where a contactless interface is powered up before a contacted interface, when simulating a dual-interface use case and using cref or Java Card WDE, it is not supported to power up a contactless interface before a contacted interface. In the binary release, the cref and Java Card WDE implementations require that a contacted interface is powered up before a contactless interface. In the binary release, you can power up the contacted interface, then power up the contactless, and then use the contactless interface to exchange APDUs.

Where to Find Product Information and News

Visit the product web site at:

http://java.sun.com/products/javacard/

For the most up-to-date information on:

[Top]

Copyright © 2005 Sun Microsystems, Inc. All rights reserved.