Preface

This document describes how to use the Java Card 3 Platform, Classic Edition, Development Kit version 3.0.2 to develop classic applets. The Java Card 3 Platform currently includes versions 3.0, 3.0.1, and 3.0.2 of various Java Card technology products. The latest platform specifications are version 3.0.1. The Classic Edition Platform is an update of the Java Card technology in the Platform 2.2.2 release. Classic applets are applet-based applications with the same capabilities as applets in previous versions of the Java Card platform.

In contrast, the Java Card 3 Platform, Connected Edition, contains a new architecture that enables developers to integrate smart cards within IP networks and web services architectures. In the Connected Edition development kit you can create extended applets and servlets to take advantage of those features. The Connected Edition also allows the creation of classic applets if you use the classic APIs. You can run both the Classic and Connected Edition development kits simultaneously.

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).

Note - The Java Card 3 platform development kit is released in both binary and source bundles. The bundles intended solely for U.S. distribution include cryptography extensions. Portions of this document are targeted toward specific release bundles and are identified as such throughout this book.

Who Should Use This Document

This Development Kit User’s Guide is written for developers who are creating classic applets using the Application Programming Interface, Java Card Platform, Version 3.0.1, Classic Edition, and also for developers who are considering creating a vendor-specific framework based on the Java Card specifications.

Before You Read This Document

Before reading this guide, become familiar with the Java programming language, object-oriented programming, the Java Card specifications, and smart card technology. A good resource for becoming familiar with Java and Java Card technology is the Sun Microsystems, Inc. web site located at http://java.sun.com.

You should also become familiar with the Java Card specifications. You can download the Java Card specifications bundle separately from the Sun Microsystems web site at http://java.sun.com/products/javacard.

How This Document Is Organized

The guide is divided into two parts. The Part I describes how to set up the development kit, how to use the samples, and how to use the development kit tools. Part II describes various programming issues for the Java Card 3 platform.

Note - Throughout this document the base installation directory is referred to by the JC_CLASSIC_HOME replacement variable. The default value for this is JCDK3.0.2_ClassicEdition but it can be changed during the installation process.

Part I: P A R T I - Setup, Samples and Tools

Chapter 1, Introduction, provides an overview of the development kit and tool use.

Chapter 3, Installation, describes the prerequisites to and procedures for installing the development kit.

Chapter 4, Running the Samples, describes sample applets that illustrate the use of the Java Card API. It also describes demonstration programs that illustrate very important scenarios of applet masking and post-manufacture installation.

Chapter 5, Converting and Exporting Java Class Files, provides an overview of the Converter and how to run it. It also describes how to use export files, including the exp2text tool to view an export file in ASCII format.

Chapter 6, Compatibility for Classic Applets, describes how to use the Normalizer tool to modify classic applets to run on both the Classic and Connected Editions.

Chapter 7, Working With CAP Files, describes how to use CAP files and their manifest files. It also describes how to use the capgen utility and the capdump utility.

Chapter 8, Packaging and Deploying Your Application, describes how to package and deploy applet applications to a smart card, including how to download and delete packages and create and delete applet instances using scriptgen, apdutool, and the on-card installer.

Chapter 9, Using the Reference Implementation, describes how to use the runtime environment simulator for the Java Card platform (Java Card runtime environment or Java Card RE).

Chapter 10, Producing a Mask File from Java Card Assembly Files, describes how to use the maskgen utility.

Chapter 11, Building a Custom RI From Sources, describes how to use the source release to build a custom runtime environment.

Chapter 12, Verifying CAP and Export Files, provides an overview of the off-card verifier tool and details of running it.

Part II: P A R T II - Programming With the Development Kit

Chapter 13, Using Cryptography Extensions, describes the cryptography APIs provided with this release.

Chapter 14, Localizing With The Development Kit, describes the localization support available for Java-based programs and tools, C-Based programs and Java Card platform RMI (Java Card RMI) sample applications and client framework.

Chapter 15, Programming to the Java Card RMI Client-Side API, describes the reference implementation of the client-side Java Card Remote Method Invocation API (client-side Java Card RMI API). See the Javadoc trademark tool generated API specification at JC_CLASSIC_HOME\docs\rmiclient.

Chapter 16, Working with APDU I/O, describes the APDU I/O library that is used by components of the Java Card development kit and can also be used to develop client applications and platform simulators. See the Javadoc trademark tool generated API specification at JC_CLASSIC_HOME\docs\apduio.

Chapter 17, Programming for the Large Address Space, describes how the large address space is implemented for the Java Card RE reference implementation of the Java Card 3 Platform, Classic Edition. It also describes how your applications can get the most out of a large address space implementation.

Appendix A, Java Card Assembly Syntax Example, describes the Java Card platform assembly output of the Converter using a commented example file.

Appendix B, Additional Optional Ant Tasks, describes how to use the optional, unsupported Apache Ant tasks included in the Java Card development kit to streamline using the tools. Several command line tools are grouped together into Ant tasks to allow for their combined use.

Glossary lists key terms used in the Classic and Connected Editions.

Typographic Conventions

Typeface	Meaning	Examples
`AaBbCc123`	The names of commands, files, and directories; on-screen computer output	Edit your`.login` file. Use `ls -a` to list all files. `% You have mail`.
`AaBbCc123`	What you type, when contrasted with on-screen computer output	`%` `su` `Password:`
AaBbCc123	Book titles, new words or terms, words to be emphasized. Replace command-line variables with real names or values.	Read Chapter 6 in the User’s Guide. These are called class options. You must be superuser to do this. To delete a file, type `rm` filename.

Typeface

Meaning

Examples

AaBbCc123

The names of commands, files, and directories; on-screen computer output

Edit your.login file.

Use ls -a to list all files.

% You have mail.

AaBbCc123

What you type, when contrasted with on-screen computer output

% su

Password:

AaBbCc123

Book titles, new words or terms, words to be emphasized. Replace command-line variables with real names or values.

Read Chapter 6 in the User’s Guide.

These are called class options.

You must be superuser to do this.

To delete a file, type rm filename.

Note - Characters display differently depending on browser settings. If characters do not display correctly, change the character encoding in your browser to Unicode UTF-8.

Accessing Sun Documentation Online

Access Java platform technical documentation on the web at the Java Developer Connection trademark program web site at

http://java.sun.com/reference/docs

Documentation, Support, and Training

Sun Function	URL
Documentation	`http://www.sun.com/documentation/`
Support	`http://www.sun.com/support/`
Training	`http://www.sun.com/training/`

Third-Party Web Sites

Sun is not responsible for the availability of third-party web sites mentioned in this document. Sun does not endorse and is not responsible or liable for any content, advertising, products, or other materials that are available on or through such sites or resources. Sun will not be responsible or liable for any actual or alleged damage or loss caused by or in connection with the use of or reliance on any such content, goods, or services that are available on or through such sites or resources.

Sun Welcomes Your Comments

Sun is interested in improving its documentation and welcomes your comments and suggestions. You can submit your comments to http://java.sun.com/docs/forms/sendusmail.html.

Please include the title of the document with your feedback:

Development Kit User’s Guide, Java Card 3 Platform, Classic Edition

You can also contact the project team by email at: jc3-ri-feedback@sun.com.