Release Notes

[Skip TOC]

Table of Contents

Introduction

Supported Platforms

Installation Instructions

Changes in the Classic Edition Specifications since the Java Card Platform, v3.0

Application Programming Interface, Version 3.0.1, Classic Edition

Runtime Environment Specification, Version 3.0.1, Classic Edition

Virtual Machine Specification, Version 3.0.1, Classic Edition

New Features in the Java Card 3 Connected Edition Specifications

Java Servlet Specification, Java Card 3 Platform, Connected Edition

Application Programming Interface, Java Card 3 Platform, Connected Edition

Runtime Environment Specification, Java Card 3 Platform, Connected Edition

Virtual Machine Specification, Java Card 3 Platform, Connected Edition

Changes in the Connected Edition Specifications since the Java Card Platform, v3.0

Java Servlet Specification, Version 3.0.1, Connected Edition

Application Programming Interface, Version 3.0.1, Connected Edition

Runtime Environment Specification, Version 3.0.1, Connected Edition

Virtual Machine Specification, Version 3.0.1, Connected Edition

Sending Feedback

Introduction

These release notes introduce the Java Card^TM specifications for the Java Card Platform, Version 3.0.1. Versions 3.0 and 3.0.1 are, together, referred to as the Java Card 3 Platform.

The Java Card 3 Platform consists of two editions, both of which are backward compatible with previous versions, including support for classic applet applications, and share key security features:

• The Classic Edition is based on an evolution of the Java Card Platform, Version 2.2.2 and targets resource-constrained devices that support applet-based applications. Bug fixes and clarifications against the Java Card v2.2.2 specifications and new security algorithms have been included. You may disregard the specifications for the Connected Edition if you are interested in the functionality found only in the Classic Edition.

• The Connected Edition features a significantly enhanced runtime environment and a new virtual machine. It targets less resource-constrained devices and includes new network-oriented features, such as support for web applications, including the Java^TM Servlet APIs, and also support for applets with extended and advanced capabilities. An application written for or an implementation of the Connected Edition may use features found in the Classic Edition. Therefore, you will need to use the specifications for both the Classic Edition and the Connected Edition.
  

CLASSIC EDITION
Runtime Environment Specification for the Java Card Platform, Classic Edition	This specification describes the runtime environment (RE) for the Classic Edition of the Java Card Platform. This RE mirrors those REs found in previous releases of the Java Card platform, including v2.2.2.
Application Programming Interface for the Java Card Platform, Classic Edition	This API defines a set of classes upon which Java Card technology-based applets can be constructed. This API mirrors those APIs found in previous releases of the Java Card platform, including v2.2.2.
Virtual Machine Specification for the Java Card Platform, Classic Edition	This specification describes the virtual machine for the Classic Edition of the Java Card Platform. This VM mirrors those VMs found in previous releases of the Java Card platform, including v2.2.2.

CONNECTED EDITION
Runtime Environment Specification for the Java Card Platform, Connected Edition	This specification describes the runtime environment required for interoperable execution of Java Card technology-based servlets  and applets with extended/advanced capabilities. It also includes some information on Classic applets, but see the Classic runtime environment specification for the bulk of that information.
Java Servlet Specification for the Java Card Platform, Connected Edition	This specification describes the requirements for interoperable Java Card technology-based servlet execution.
Application Programming Interface for the Java Card Platform, Connected Edition	This API defines a set of classes upon which Java Card technology-based servlets and applets with extended/advanced capabilities can be constructed. It also includes some information on Classic applets, but see the Classic API specification for the bulk of that information. For more information on servlet execution, see the servlet specification for the Java Card platform.
Virtual Machine Specification for the Java Card Platform, Connected Edition	This specification describes the new virtual machine for the Connected Edition of the Java Card Platform.

[Top]

Supported Platforms

The documents are accessible on any computer system with an unzip utility, Adobe Acrobat Reader (version 4.0 or later), and a CSS-compliant web browser.

HTML can be viewed with any CSS-compliant browser software, such as:

• Netscape Communicator, version 5.0 or later
• Mozilla, version 1.1 or later

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.

[Top]

Installation Instructions

Download and unzip the specifications bundle. The bundle unzips into the subdirectory javacard_specifications-3_0_1-RR, within which you will find the subdirectories classic/ and connected/.

NOTE: The HTML versions of the specifications can be viewed in most browsers but do not render well in Mozilla Firefox 3.0.10.

classic/ Subdirectory

Within the classic/ subdirectory you will find the specifications as listed:

• api_classic - contains the Java Card API specification for the Classic Edition in Javadoc^TM tool HTML format. This subdirectory also contains a PDF version (APIspecCLASSIC-3_0_1-RR.pdf) of those files.
  
• jcre_classic - contains the Java Card runtime environment specification for the Classic Edition in PDF format (JCREspecCLASSIC-3_0_1-RR.pdf) and an HTML version at classic/jcre_classic/html/index.html
• jcvm_classic - contains the Java Card virtual machine specification for the Classic Edition in PDF format (JCVMspecCLASSIC-3_0_1-RR.pdf) and an HTML version at classic/jcvm_classic/html/index.html

connected/ Subdirectory

Within the connected/ subdirectory you will find the specifications as listed:

• api_connected - contains the Java Card API specification for the Connected Edition in Javadoc tool HTML format. The subdirectory api_connected/spi/ contains the System Programming Interface (SPI) specification in Javadoc tool HTML format. The Descriptor XML schemas are available at http://java.sun.com/xml/ns/javacard/
  
• jcre_connected - contains the Java Card runtime environment specification for the Connected Edition in PDF format (JCREspecCONNECTED-3_0_1-RR.pdf) and an HTML version at connected/jcre_connected/html/index.html
• jcvm_connected - contains the Java Card virtual machine specification for the Connected Edition in PDF format (JCVMspecCONNECTED-3_0_1-RR.pdf) and an HTML version at connected/jcvm_connected/html/index.html
• servlet_connected - contains the servlet specification for the Java Card Platform in PDF format (ServletspecCONNECTED-3_0_1-RR.pdf) and an HTML version at connected/servlet_connected/html/index.html

[Top]

Changes in the Classic Edition Specifications since the Java Card Platform, v3.0

The following sections describe the changes to the Classic Edition specifications for the Java Card platform since the Version 3.0 release.

Application Programming Interface, Version 3.0.1, Classic Edition

This section describes the changes to the Application Programming Interface Specification for the Java Card Platform, Version 3.0.1, Classic Edition since the Version 3.0 release.

Summary

• javacard.framework.APDU
• The term "chaining mode" is used consistently instead of the misleading "block chaining" in all the method descriptions
• javacard.security.InitializedMessageDigest
• Clarified the setInitialDigest() to require a  512 byte input param for SHA-384
  
• javacard.security.HMACKey
• Clarified the setKey/getKey methods for key data and length values
  
• javacard.security.MessageDigest
• Add a definition for SHA-224 hash
• javacard.security.Signature
• The init method now allows the salt length parameter to be configured in the RSA with PSS algorithm
  
• Clarified the sign and verify methods to throw an ILLEGAL_USE CryptoException if the message data is not consistent with the algorithm
• Added new signature algorithms with the combination of ECDSA(Cipher) and SHA-2(Hash)
• Added support for SHA-2 in all applicable Signature algorithms
• javacardx.crypto.Cipher
• Clarified the ALG_RSA_NOPAD algorithm to  throw an ILLEGAL_USE CryptoException in the update and doFinal methods if the  input data value is equal to or greater than the key modulus
• Deprecated the ALG_RSA_ISO14888 algorithm.
  

[Top]

Runtime Environment Specification, Version 3.0.1, Classic Edition

This section describes the changes to the Runtime Environment Specification for the Java Card Platform, Version 3.0.1, Classic Edition since the Version 3.0 release.

Summary

• Clarified the JCRE behavior in  section 9.4 when an applet aborts and sends less than Le bytes in CASE2 in No Chaining mode in T=0
• Fixed the typos in section 12.26 to define the constants BER_TAG_MASK_... with correct name
• The term "transient memory segment" has been clarified in a footnote of the logical channels chapter 4
• Rephrased the term "valid remote object" as "remote object referenced from a valid remote reference"
  

[Top]

Virtual Machine Specification, Version 3.0.1, Classic Edition

This section describes the changes to the Virtual Machine Specification for the Java Card Platform, Version 3.0.1, Classic Edition since the Version 3.0 release.

Summary

• This version incorporates minor typographical fixes since the Java Card Platform, v3.0 version.

New Features in the Java Card 3 Connected Edition Specifications

The following sections describe the contents of the Connected Edition specifications for the Java Card platform.

Java Servlet Specification, Java Card 3 Platform, Connected Edition

This section describes the new Java Servlet Specification for the Java Card 3 Platform, Connected Edition.

Summary

• The Java Servlet API for the Java Card Platform is a subset of the Java Servlet API v.2.4. The subset is described in this draft.
• For information on other features in web applications, see the Connected Edition's API and runtime environment specifications.
  

[Top]

Application Programming Interface, Java Card 3 Platform, Connected Edition

This section describes the Application Programming Interface Specification for the Java Card 3 Platform, Connected Edition.

Summary

• This API contains specifications for extended and enhanced applets and for web applications, including servlets. Some APIs pertain to classic applets, but the bulk of that information is in the Classic Edition's API.
  
• The following packages are new in the Java Card Platform, v3.0.1:
• java.security
• java.util
• javacardx.facilities
• javacardx.framework
• javacardx.io
• javacardx.security
• javax.microedition.io
• javax.microedition.pki
• javax.servlet 
• javax.servlet.http
• javacardx.spi.framework
• javacardx.spi.cardmgmt
• javacardx.spi.security
  
• com.sun.javacard.spi.cardmgmt [INFORMATIVE ONLY]
• com.sun.javacard.spi.security [ INFORMATIVE ONLY]

[Top]

Runtime Environment Specification, Java Card 3 Platform, Connected Edition

This section describes the features of the Runtime Environment Specification for the Java Card 3 Platform, Connected Edition.

Summary

• The information in this book covers web applications and applets with extended/advanced capabilities. It also includes some information on classic applets, but see the Classic runtime environment specification for the bulk of that information. For more information on servlet execution, see the servlet specification for the Java Card platform.

[Top]

Virtual Machine Specification, Java Card 3 Platform, Connected Edition

This section describes the features of the Virtual Machine Specification for the Java Card 3 Platform, Connected Edition.

Summary

• The virtual machine specification describes the core platform features of the Java Card platform, Connected Edition
• The supported subset of the Java Language Specification
• The supported subset of the Java Virtual Machine Specification
• Core platform classes – subset of Java^TM Platform, Standard Edition class libraries and Java^TM Platform, Micro Edition class libraries

[Top]

Changes in the Connected Edition Specifications since the Java Card Platform, v3.0

The following sections describe the changes to the Connected Edition specifications for the Java Card platform since the Version 3.0 release.

Java Servlet Specification, Version 3.0.1, Connected Edition

This section describes the changes to the Java Servlet Specification for the Java Card Platform, Version 3.0.1, Connected Edition.

Summary

Updates to the Java Servlet specification since the Java Card Platform, Version 3.0 include:

• A realm name can be defined for any authentication method (alignment with the Java Servlet Specification version 2.5).
• The web container is required to filter out Authorization headers during BASIC and DIGEST authentication.
• The ServletRequest certificate request attribute has been simplified and aligned with TLSSecurityInfo.getClientCertificate() method.
  

[Top]

Application Programming Interface, Version 3.0.1, Connected Edition

This section describes the changes to the Application Programming Interface Specification for the Java Card Platform, Version 3.0.1, Connected Edition since the Version 3.0 release.

Summary

Updates to the API specification since the Java Card Platform, Version 3.0 include:

• Inaccessibility of SPI classes to applications have been added in their respective package overview.
• Documentation of public (i.e. non-proprietary) SPI classes (javacardx.spi.* packages) have been moved to the API documentation.
• The status of not yet public (i.e. proprietary) SPI classes (com.sun.javacard(x).spi.* packages) has been clarified in the respective package overview.
• All the classic features (classes and methods) that are not applicable to the connected environment have been tagged deprecated.
• References to obsolete RFCs have been updated and an RFC reference summary table has been added to the main API overview.
• Requirements and limitations of certificate support have been described in the overview.
• Optionality of certain packages has been clarified in their respective package overview as well as in the main API overview.
• A requirement for protection against the mutability of Java Card RE objects has been added.
• java.lang
  • The Throwable class and its subclasses are now implicitly transferable classes.
• java.util
• The Calendar.hashcode() method has been added.
• The thread-safety requirements of the collection classes - Hashtable, Vector and Stack - has been clarified.
• javacard.framework
  
• The JCSystem.isTransient() method has been clarified to return MEMORY_TYPE_TRANSIENT_RESET for instances of TransientReference.
• javacard.security
  
• The InitializedMessageDigest.setInitialDigest() method has been clarified to require a  512 byte input param for SHA-384.
• The HMACKey.setKey/getKey methods have been clarified for invalid key data and length values.
• Key.getTypeName method has been introduced to return the name of the key interface type.
• MessageDigest class has added the the SHA-224 hash algorithm.
• The Signature class has added new signature algorithms for  the combination of ECDSA(Cipher) and SHA-2(Hash) algorithms.
• The Signature class has added support for SHA-2 in all applicable Signature algorithms.
• The instance creation factory methods - buildkey and getInstance methods with default provider of all the classes have been clarified to describe the procedure used to select the most preferred provider.
• javacardx.crypto
  
  • The  Cipher instance creation factory method with default provider has been clarified to describe the procedure used to select the most preferred provide.
  • Deprecated the Cipher.ALG_RSA_ISO14888 algorithm.
• javacardx.framework 
  • The ClassicSIOProxy class  has been refactored to ensure the thread safety of classic applications and  to support SIO instance echo pattern between a classic application and extended applet application.
  • Authenticator.reset method has been added. The Authenticator interface now extends the Shareable interface.
  • The ContextPermission class no longer supports the standard event URI aliasing pattern.
  • The Password class does not require a minimum password length.
  • The JCSystem.getPreviousURI method with the same semantics as the former JCSystem.getClientURI method has been introduced.
  • The JCSystem.getClientURI and JCSystem.isClientInRole methods have been changed to account for callers from the same group context has that of the server application.
  • The JCSystem.getAppProperty and JCSystem.isUserInRole methods have been enhanced to allow for an extra URI parameter that designates the applicable runtime configuration.
• javacardx.facilities
  • The EventRegistry.notifyListenersInRole method has been corrected to describe the notification of the notifying application's own listeners. It has also been changed to account for listeners from the same group context as that of the notifying application.
  • The StandardEvent and the PlatformEvent classes have been removed to simplify the Event class hierarchy. The Event class now supports platform and standard event URIs.
• javacardx.security
  • The CredentialManager class has been refactored to support the TLS-PSK algorithm.
  • The CredentialManager class has been refactored to  be align with the javacard.security package and the javax.microedition.pki.Certificate package.
  • The chooseCipherSuites method has been added to the SecurityRequirements class to allow applications to choose the cipher suites for TLS connections.
  • SensitiveType, SensitiveMethod security annotation classes have been added.
• javacardx.spi.*
  • The ClassicSIOProxy class has been moved to the javacardx.framework package to account for the restrictions on package access control.
  • The CryptoProvider class has been refactored to better account for how cryptographic services must be instantiated.
• com.sun.javacard.spi.*
  • The ProtectionDomain.initializePlatformPolicy method has been added.
• The DeploymentUnitLoader class default constructor has been made private to ensure singleton pattern.

Runtime Environment Specification, Version 3.0.1, Connected Edition

This section describes the changes to the Runtime Environment Specification for the Java Card Platform, Version 3.0.1, Connected Edition since the Version 3.0 release.

Summary

• Security Annotations
  
• Optional support for security annotations has been added in an appendix.
• Code Isolation
  
• The classloader to be requested to dynamically load a class using Class.forName() or ResourceBundle.getBundle() has been redefined. It must be the defining classloader of the calling class.
• The lookup order of classpath resources has been clarified.
• The visibility of Connected API classes to Classic Applet applications has been clarified.
• Transactions
  
• Section 2.9.3 Overlapping Transaction Updates has been clarified with respect to concurrent updates in transactions.
• Section 2.9.2 Transaction Demarcation provides generic guidelines for programmer when using API classes such as collection classes.
• Applet Application Environment
• This ClassicSIOProxy mechanism now ensures the thread safety of classic applications. Classic SIO proxies classes are supported only inside a classic applet application.
• The ClassicSIOProxy mechanism now supports he SIO instance echo pattern between a classic application and extended applet application.
• Web Application Environment
  
• The availability to web application code of WEB-INF/classes and META-INF directories as well as of the WEB-INF/web.xml file has been clarified.
• User Authentication
  
• The behavior of the web container when login configuration is not defined has been clarified.
• Authenticator URIs are required to have a “realm” path component that must be matched by the realm name of web applications.
• The matching of the “scheme” path component of authenticator URIs with the authentication method of web apps has been relaxed.
• Interface between Authenticators and the container for HTTP Digest authentication has been specified.
• Generic authentication procedure returns 401 when authentication fails.
• The result of a call to ServletRequest.getRemoteUser after authentication has been clarified.
• The name of the credential parameter for the Java Card platform-specific authentication scheme has been explicitly defined.
• Mapping roles of a remotely accessible application to global card holder authenticators has been allowed, with some restrictions.
• Inter-application Communication Facilities
  
• Ownership of standard application events created and fired by the Java Card RE on behalf of applications has been clarified.
• The restrictions on the use of the standard and platform subnamespaces for new event and service URIs has been clarified.
• The concept of "application clients" has been extended to also include applications (SIO callers) from the same group context has that of the server application.
• The restrictions on unregistration of service, event and task has been clarified (only the application that previously registered the object can unregister it).
• The restrictions on the ownership of the parameter to ownership transfer operations have been clarified.
• The handling of the extra byte lookup parameter by the classic SIO lookup fallback mechanism of the ServiceRegistry has been clarified.
• The applicability of the classic lookup fallback mechanism of the ServiceRegistry to web applications and extended applet applications has been clarified.
• Firewall
  
• Section 6.9 Context Isolation Basics  has been moved  to section 2.4 to improve the readability and flow.
• The object access bytecode behavior for implicitly transferable objects has been added.
• Exception Objects
  
• Throwable and subclasses thereof have been added to the list of implicitly transferable classes to simplify throwing exceptions across the firewall.
• Credential Manager
  
• Diagrams describing the sequence of invocation of the CredentialManager class's methods both for TLS-PKI and TLS-PSK have been added.
• URI Syntax and Semantics
  
• The subset of the URI specification (RFC 3986) has been clarified.
• Classic Applet Applications
  
• The synchronization proxy code example in Figure 4-1 has been corrected to show proper casting and error checks.
• The SIO Proxy generation rules for offcard tools has been improved. Proxy classes which implement exactly the same interfaces as the corresponding SIO class are now generated when possible.
  
• The requirements for wrapping an SIO object into its proxy and unwrapping the SIO object from its proxy is described in detail. These requirements ensure the single threaded guarantees for classic applet applications. The SIO object echo pattern between a classic applet application and an extended applet application is now supported.
• Card Management
  
• Recommended file name extensions for each distribution unit format has been introduced.
• Classic applet application and classic library distribution unit format has been clarified to show the proper path for the *.CAP components.
• Clarified to allow card manager to reject class files with unused constant pool entries containing linking error or malformed references.
• The requirements for static secure port allocation have been clarified.
• Clarified to require Classic SIO proxy classes to be added to the list of dynamically loaded classes.
• The dependency checks requirements when unloading a deployment unit have been corrected.
• The requirements for application deletion have been clarified.
• The limitation introduced by the case-insensitive handling of role names in the role mapping attributes of the runtime descriptor has been described.
• The URL for the Java Card schema documents has been corrected.
• Class loading requirements for arrays of Shareable interfaces has been clarified.
• Classic applet application and classic library distribution unit format has been clarified to  require the package to be sealed.
• Miscellaneous
  
• The restrictions on linking with platform and SPI implementation classes has been clarified (code isolation).
• The Classic platform protection domain has been corrected to not preclude context switching from the classic application environment to the web application environment.
• The transaction facility-managed transitions upon entry into and exit from a method annotated NOT_CONNECTED has been clarified.

[Top]

Virtual Machine Specification, Version 3.0.1, Connected Edition

This section describes the changes to the Virtual Machine Specification for the Java Card Platform, Version 3.0.1, Connected Edition since the previous release.

Summary

The firewall access control checking of method parameters requirement in native methods has been added.

The required character encodings and the default character encoding have been clarified and made consistent with that of the Servlet Specification.

The line.separator system property has been added.

Sending Feedback

We greatly appreciate your feedback on the specifications. Please send all feedback to jc-bandol-spec-feedback@sun.com.

[Top]

---

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