# Release Notes ## Development Kit for the Java Card™ 3 Platform ## Version 3.0.2, Connected Edition ## Binary Release #### December 2009

## Table of Contents

Introduction
Requirements
Contents of This Release
  Application Support
  Tools
  Java Card Runtime Environment (cjcre.exe) Features
  Web Application Features
  Extended Java Card Applet Application Features
Installation
System Setup
Uninstalling the Development Kit
Known Bugs
Where to Find Product Information and News
Sending Feedback

## Introduction

These release notes describe the development kit for the Java Card™ 3 Platform, Version 3.0.2, Connected Edition, binary release.

Java Card technology combines a subset of the Java™ programming language with a runtime environment optimized for smart cards and similar small-memory embedded devices. The goal of Java Card technology is to bring many of the benefits of the Java programming language to the resource-constrained world of smart cards. The Java Card API is compatible with international standards such as ISO 7816, and industry-specific standards such as Europay, Master Card, and Visa (EMV).

Java Card platform version 3.0.2 is the latest evolution of Java Card technology. This development kit is based on the Version 3.0.1 of the Java Card Specifications, which includes their errata sheets located at http://java.sun.com/javacard/3.0.1/jc-connected-spec-errata.html. The Java Card 3 Platform consists of versions 3.0 and 3.0.1 of the specifications and versions 3.0.1 and 3.0.2 of the development kit.

For the first time, the Java Card platform is available in two editions, both of which are backward compatible with previous versions and share key security features:

- Classic Edition is based on an evolution of the Java Card Platform, Version 2.2.2, architecture. The Classic Edition targets more resource-constrained devices than the Connected Edition.

- Connected Edition contains a new architecture compared to the Java Card technology released in version 2.2.2, which is now known as the "Classic Edition." The Connected Edition enables the integration of smart cards within IP networks and web services architectures. To do so, it features a significantly enhanced runtime environment and virtual machine (VM), and it includes new network-oriented features, such as support for Java Servlet APIs and Java Card applets with extended and advanced capabilities. As of this release, the Connected Edition has a new file system. These release notes are for the Connected Edition.

## Requirements

Platform

- Operating system. This release is targeted for use on the Microsoft Windows XP SP2 operating system.

Required Software

The following software must be installed for the Java Card development kit to work:

- Java Development Kit. The commercial version of Java Development Kit (JDK™) version 6, Update 10 or later is required. You can download the supported JDK software, JDK 6 Update 10 or later, from http://java.sun.com/javase/downloads/index.jsp.
- GCC compiler. To build the VM, this release requires Minimal GNU for Windows (MinGW) version 5.1.4 or later. MinGW can be obtained from http://prdownloads.sourceforge.net/mingw. For information on MinGW go to http://www.mingw.org.
- Apache Ant. Apache Ant version 1.6.5 or later is required. Latest version of Apache Ant can be obtained http://ant.apache.org.
- NetBeans IDE. The NetBeans IDE Version 6.8 or later is required to run the samples. The NetBeans IDE is available at http://www.netbeans.org/index.html.
- For use with the samples, the Firefox browser is considered a trusted client by the RI. Firefox is available at http://www.mozilla.com.

Note — Do not install any software in a directory that contains a space in its name. For example, do not install software in any subdirectory of `c:\program files` because of the space in the `program files` element.

## Contents of This Release

This source release contains both binary and source code. Note that the Java Card specifications are not included in this release. The specifications must be downloaded separately.

This release contains features required to support classic applets, web applications, and extended Java Card applet applications on the card. Specifically, this release includes the following:

- Java Card runtime environment (`cjcre.exe`)
- File system support
- Uninstaller tool
- Normalizer tool (normalizer.bat)
- OffCard Installer (`installer.bat`)
- Packager tool (`packager.bat`)
- APDU tool (`apdutool.bat`)
- Debugging tool (`debugproxy.bat`)
- Romizer tool (`romizer.bat`)
- Converter tool (`converter.bat`)
- Three Sample applications (The complete set of samples are available through the NetBeans IDE as Kenai Projects. You can also see them at http://kenai.com/projects/javacard/pages/JC3Samples.)
- User's guide for this release in Development Kit User's Guide for the Java Card Platform, Version 3.0.2, Connected Edition

### Application Support

This release supports web applications and classic and extended Java Card applet-based applications. The card manager application, which is built in, allows the user to do the following:

- Load - Loading classic, web-based, and extended Java Card applet applications onto the card
- Create - Creating instances of classic, web-based, and extended Java Card applet applications
- List - Obtaining the list of loaded applications and created instances
- Delete - Deleting instances of classic, web-based, and extended Java Card applet applications
- Unload - Unloading classic, web-based, and extended Java Card applet applications from the card

### Tools

- Normalizer (normalizer.bat) can be used for backward compatibility with classic applets
- OffCard Installer (`installer.bat`) is functional
- Packager (`packager.bat`) can be used to both validate and create classic, web and extended Java Card applets applications
- Debugging tool (`debugproxy.bat`) can be used to debug applications in an IDE (such as the NetBeans™ IDE)
- APDU tool (`apdutool.bat`) can be used to send APDU scripts to the extended Java Card applet applications
- Romizer (`romizer.bat`) can be used to create custom ROM image files to create customized Java Card runtime environment (`cjcre.exe`)
- Converter (`converter.bat`) can be used to create classic applet application bundles

### Java Card Runtime Environment (`cjcre.exe`) Features

- Support for traditional, classic Java Card applets
- Package sealing
- Secure hosting of web applications on static and dynamically assigned ports
- SSL, HTTP and HTTPS connection support. (The SSL implementation is provided for reference purposes and is not recommended for production use in devices.)
- On-card client application authentication
- Permission-based security
- Role-based security
- Code and context isolation between applications
- Transfer of object ownership support
- Transactions
- Extension library support
- SIO based services
- Events
- Restartable tasks
- Persistence
- Resource bundle support
- Evolutive Cryptography support
- Enhanced firewall support (including support for throwing exceptions across a firewall)
- Support for debugging using Java Card Debugger
- Preshared secret key support

### Web Application Features

- All basic support for a typical web application (servlets, filters, listeners, etc.)
- BASIC, FORM and DIGEST authentication

### Extended Java Card Applet Application Features

- All basic support for typical Extended Java Card Applet Application features (logical channels, etc.)
- T=0 and T=1 based APDU communication support
- APIs found in the Classic Edition

## Installation

For a more thorough description of the installation, contents and use of the development kit, see Development User's Guide, Java Card Platform, Version 3.0.2, Connected Edition included in the download bundle for this release.

An automatic installer tool can be used to unpack the download file containing this release. During download, you can choose to let the installer tool unpack the download file into a directory of your choice on your system or you can save the download file itself to your system.

Note — Do not install development kit software in any directory that has a space in its name. For example, on a Windows platform, do not install software in the `c:\program files` directory, or any subdirectory of `c:\program files`, because the `program files` element contains a space.

To install the Java Card development kit and associated software, follow these steps:

1. Install the JDK version 6, Update 10 or later. This JDK is available from: http://java.sun.com/javase/downloads/index.jsp.
2. Install Apache Ant version 1.6.5 or later. The latest version is available at: http://ant.apache.org/.
3. Install the GCC compiler. The compiler Minimal GNU for Windows (MinGW), version 5.1.4 is required. It is available at http://sourceforge.net/projects/mingw, while its installation information is at http://www.mingw.org.
4. Install NetBeans IDE. The NetBeans IDE version 6.8 is required to run the samples. It is available at http://www.netbeans.org.
5. Download the Java Card development kit. Download and store the development kit Java Archive (JAR) file in a directory of your choice.
6. Run the development kit installer or use the command line. Double click the JAR file on your system. If the JDK is installed correctly, the jar file is recognized as an executable jar and the automatic installer will launch to step you through the remainder of the installation process. `
   `

Alternatively, you can use the command line to unpack the JAR file using the following command:

> `java -jar` Bundle-Filename
> Where Bundle-Filename is the downloaded development kit JAR file.

By default, the development kit is installed in `c:\jcdk3.0.2_ConnectedEdition` and its associated sub-directories. You can specify a different directory if you wish.

The directory `c:\jcdk3.0.2_ConnectedEdition` (or the alternate directory you specify during installation) is referred to as `JC_CONNECTED_HOME` in these release notes. When the development kit installation is complete, `JC_CONNECTED_HOME` contains the following:

`JC_CONNECTED_HOME` | `RELEASENOTES-BIN.html` - These release notes. `` platform.properties - contains information about the Java Card Platform for use by developer tools such as the NetBeans IDE. Copyright files.
`docs` | `JCDevKitUG-Connected-3_0_2.pdf` - Development Kit User's Guide for the Java Card Platform, Version 3.0.2, Connected Edition. UserGuide_html\index.html - HTML version of the user's guide. ``
`docs\api` | The development kit's API files.
`docs\apduio` | JavadocTM tool files for use with APDU I/O described in the user's guide.
`api_export_files` | Contains java, javacard, and javacardx directories of API export files.
`bin` | Development kit executable files.
`samples\classic_applets` | HelloWorld sample using a classic applet. The complete set of samples is available through the NetBeans IDE, each as a Kenai Project. Running this sample requires the NetBeans IDE and its Java Card technology-specific plugin. ``
`samples\extended_applets` | HelloWorld sample using an extended applet.`` The complete set of samples is available through the NetBeans IDE, each as a Kenai Project. Running this sample requires the NetBeans IDE and its Java Card technology-specific plugin.
`samples\keystore` | Keystore and certificate files for use by the samples.
`samples\web` | HelloWorld sample using a servlet. The complete set of samples is available through the NetBeans IDE, each as a Kenai Project. Running this sample requires the NetBeans IDE and its Java Card technology-specific plugin.``
`lib` | Configuration and JAR files for the API, tools. Third-party libraries.
`Uninstaller\uninstaller.jar` | Deletes the development kit.
`legal` | License files.

## System Setup

Set System Variables and Paths
System variables and paths must be set before running the development kit. See the Development Kit User's Guide more details on how to set them. Note that if you choose to set the variables and paths each time you run the development kit rather than permanently in your system, you can place the appropriate commands in a batch file.

- `JAVA_HOME`. You must set the `JAVA_HOME` system variable to the JDK root directory before running the development kit.
  - To temporarily set `JAVA_HOME` from the command line, enter the command: `set JAVA_HOME=c:\path` before running the development kit. For example, if the Java platform software is stored in your `c:\jdk6` directory, enter `set` ```JAVA_HOM` `E``=c:\jdk6` before running the development kit.
  ``
- `JC_CONNECTED_HOME`. You must set the `JC_CONNECTED_HOME` system variable to the directory in which the development kit is installed before running the development kit.

- To temporarily set `JC_CONNECTED_HOME` from the command line, enter the command: `set JC_CONNECTED_HOME=c:\path` before running the development kit. For example, if the Java Card development kit is stored in your `c:\``jcdk3.0.2_ConnectedEdition``` directory, enter `set` ```JC_CONNECTED_HOM` `E``=c:\``jcdk3.0.2_ConnectedEdition``` before running the development kit.

- Apache Ant. You must set the ANT_HOME system variable to the Apache Ant directory before running the samples.

- To temporarily set `ANT_HOME` from the command line, enter the command: `set PATH=c:\path` before running the development kit. For example, if Apache Ant is stored in your `c:\``ant\apache-ant1.6.5``` directory, enter `set` ```ANT_HOM` `E``=``c:\``ant\apache-ant1.6.5``````` before running the development kit.

- MinGW. You must set the path to the location of `MinGW` before running the development kit. Note that the path has to point to the `\bin` subdirectory of the `MinGW` installation directory where the `gcc.exe` file is located.
  - To temporarily set the path to MinGW, enter the command `set PATH=c:\MinGW_path;%PATH%`. For example, if MinGW is installed in `c:\MinGW`, enter the command `set PATH=c:\MinGW\bin;%PATH%` before running the development kit.

Configure the Java Card Runtime Environment for the Samples

Note that the Java Card RE (cjcre) implementation is not optimized for memory or performance and, therefore, requires more memory than an actual optimized implementation on a card. To run the samples provided with the development kit, the Java Card RE must be configured with at least 1M of RAM, 4M of EEPROM, and 4K of COR (Clear-On_Reset). These parameters can be provided to the Java Card RE using the Java Card RE command line as follows:

`cjcre.exe -ramsize 1M -e2psize 4M -corsize 4K`
For details see the Java Card RE command reference in the Development Kit User's Guide for the Java Card Platform, Version 3.0.2, Connected Edition.

## Uninstalling the Development Kit

To remove this development kit, an automatic uninstaller tool is provided in the directory Uninstaller. You can also completely remove the development kit by deleting the `JC_CONNECTED_HOME` directory along with all of its contents.

## Known Bugs

This section describes known bugs and issues in the reference implementation.

BUG ID | DESCRIPTION
--- | ---
6906665 | Error msg is incorrect when instance with already existing name is being created.
6903372 | Package visible shareable interfaces should not be included into SIO Proxy classes
6902985 | In some cases incorrect 0x6700 (wrong length) status is returned for T1 case 4E

## Where to Find Product Information and News

The public Java Card technology web site is http://java.sun.com/javacard. The developer collaboration web site also contains information about Java Card technology at http://kenai.com/projects/javacard/pages/HOME.

If you are a Licensee, visit the product web site at https://java-partner.sun.com/portal/service/ent/platform/javacardgroup This site has the most up-to-date information on the following:

- Product news and reviews
- Release notes and product documentation
- Technical support contact information

## Sending Feedback

We greatly appreciate your feedback on the reference Implementation. Please send all feedback to jc3-ri-feedback@sun.com.

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

Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed at http://www.sun.com/patents and one or more additional patents or pending patent applications in the U.S. and in other countries.
U.S. Government Rights - Commercial Software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements.

Use is subject to license terms. Sun, Sun Microsystems, the Sun logo, Java, Solaris, Javadoc, Java Card and NetBeans are trademarks or registered trademarks of Sun Microsystems, Inc. or its subsidiaries, in the U.S. and other countries.
UNIX is a registered trademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd.