RELEASE NOTES - JAVA CARD 3.0.1 PLATFORM SPECIFICATION

      Contents  - Introduction- Supported Platforms- Installation Instructions

- Changes in the Classic Edition Specifications since the Java Card Platform, v2.2.2

 

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

This API defines a set of classes upon which Java Card technology-based

Java Card Platform, Connected Edition

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.

 

Back to 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.

Back to 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 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.

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

Back to top

Changes in the Classic Edition Specifications since the Java Card Platform, v2.2.2

The following sections describe the changes to the Classic Edition specifications for the Java Card platform since the Version 2.2.2 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 2.2.2 release.

This section describes the changes to the Application Programming Interface Specification for the Java Card Platform, Version 3.0.1, Classic Edition since the previous release. The package version numbers (export file versions) of the updated packages in the Application Programming Interface, Version 3.0.1, Classic Edition are shown below. All other package version numbers are unchanged from version 2.2.2:

package javacard.framework o version number = 1.4

package javacard.security

o version number = 1.4

package javacardx.crypto

o version number = 1.4

The export files associated with the API packages will be available with the final release of the reference implementation bundles.

Summary

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

javacard.framework.APDU o Added new method -

isValidCLA, which returns true if the CLA encoding is not reserved or invalid per the ISO7816 specification

o The term "chaining mode" is used consistently instead of the misleading "block chaining" in all the method

descriptions

o Clarified methods getCLAChannel, isSecureMessaging, isCommandChaining with respect to RFU and 0xFF encodings of CLA, added new isValidCLA method - #6503484

o setOutgoingNoChaining method clarified comment about 61xx command chaining restrictions - #6506163

o Added case 4E mentions in setOutgoing, setOutgoingNoChaining methods where T=0 extended length 4S called out - #6621872

o Added ISOException with SW_WRONG_LENGTH in setOutgoing and setOutgoingNochaing methods if in T=1, Le>32767 - #6543550

javacard.security.KeyBuilder

o Added 4096 bit RSA key - #6593240

o Added support for transient RSA, EC and DSA private keys - #6270329

o Added support for Suite B keys – longer EC_FP keys - #6270320

javacard.security.KeyAgreement

o Clarified ALG_EC_SVDP_DH and ALG_EC_SVDP_DHC on requirement of output to be the computed SHA-1 on

key derivation primitive. -#6557775

o Duplicated ALG_EC_SVDP_DH and ALG_EC_SVDP_DHC with _KDF names with identical descriptions to make key derivation step (SHA) more intuitive - #6557775

o Added support for Suite B KeyAgreement for longer secret key generation using RAW mode - #6270320

javacard.security.InitializedMessageDigest

o Clarified the setInitialDigest() to require a  512 byte input param for SHA-384

javacard.security.HMACKey

o Clarified the setKey/getKey methods for key data and length values

javacard.security.MessageDigest

o Add a definition for SHA-224 hash

javacard.security.Signature

o The init method now allows the salt length parameter to be configured in the RSA with PSS algorithm

o Clarified the sign and verify methods to throw an ILLEGAL_USE CryptoException if the message data is not consistent with the algorithm

o Added new signature algorithms with the combination of

ECDSA(Cipher) and SHA-2(Hash)

o Added support for SHA-2 in all applicable Signature algorithms

o Added note for ALG_ECDSA_SHA algorithm on truncating SHA digest to EC key length if required per SEC 1 - #6575843

o Added support for Suite B EC signatures with SHA-256, SHA-384 - #6270320

o Added support for Suite B AES signatures with 192, 256 bit blocks - #6270320

javacardx.external.Memory

o Added support for external 4K MIFARE memory #6639482

javacardx.crypto.Cipher

o 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

o Deprecated the ALG_RSA_ISO14888 algorithm.

o Added support for Suite B AES ciphers with 192, 256 bit blocks - #6270320

o Added AES algorithms with ISO9797 and PKCS#5 padding options

[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 2.2.2 release.

Summary

Updates to the Runtime Environment specification since the Java Card Platform, v2.2.2 version include:

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"

Clarified selection requirements of default applications in contactless interface

Added support for ETSI defined SWP protocol defined in ETSI TS 102 613 for contactless communication, and for independent contacted and contactless interfaces

Added support for USB connected interface communication

Clarified the behavior of outbound I/O when the applet aborts wihout sending the number of bytes specified via

setOutgoingLength method

Clarified the behavior of applets not implementing the ExtendedLength interface with respect to application level T=0 ENVELOPE commands

Added constant values corresponding to the new security algorithms and key sizes

[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 2.2.2 release.

Summary

This version incorporates minor typographical fixes since the Java Card Platform, v2.2.2 version.

Back to 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.getClientCert

ificate() method.

Back to 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

o The Throwable class and its subclasses are now implicitly transferable classes.

java.util

o The Calendar.hashcode() method has been added.

o The thread-safety requirements of the collection classes - Hashtable, Vector and Stack - has been clarified.

javacard.framework

o The JCSystem .isTransient()

method has been clarified to

return MEMORY_TYPE_TRANSIENT_RESET for instances of TransientReference.

javacard.security

o The InitializedMessageDigest. setInitialDigest() method has been clarified to require a 512 byte input param for SHA-384.

o The HMACKey.setKey/getKey methods have been clarified for invalid key data and length values.

o Key.getTypeName method has been introduced to return the name of the key interface type.

o MessageDigest class has added the the SHA-224 hash algorithm.

o The Signature class has added new signature algorithms for the combination of ECDSA(Cipher) and SHA-2(Hash) algorithms.

o The Signature class has added support for SHA-2 in all applicable Signature algorithms.

o 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

o The Cipher instance creation factory method with default provider has been clarified to describe the procedure used to select the most preferred provide.

o Deprecated the Cipher.ALG_RSA_ISO14888

algorithm.

javacardx.framework

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

o Authenticator. reset method has been added. The Authenticator interface now extends the Shareable interface.

o The ContextPermission class no longer supports the standard event URI aliasing pattern.

o The Password class does not require a minimum password length.

o The JCSystem.getPreviousURI

method with the same semantics as the former JCSystem.getClientURI method has been introduced.

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

o 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

o The EventRegistry.n otifyListenersInRole 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.

o 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

o The CredentialManager class has been refactored to support the TLS-PSK algorithm.

o The CredentialManager class has been refactored to be align with the javacard.security

package and the javax.microedition.pki.

Certificate package.

o The chooseCipherSuites method has been added to

the SecurityRequirements class to allow applications to choose the cipher suites for TLS connections.

o SensitiveType, SensitiveMethod security annotation classes have been added.

javacardx.spi.*

o The ClassicSIOProxy class has been moved to the javacardx.framework package to account for the restrictions on package access control.

o The CryptoProvider class has been refactored to better account for how cryptographic services must be instantiated.

com.sun.javacard.spi.*

o The ProtectionDomain. initializePlatformPolic

y method has been added.

o The DeploymentUnitLoader class default constructor has been made private to ensure singleton pattern.

Back to top

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

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

Security Annotations

o Optional support for security annotations has been added in an appendix.

Code Isolation

o The classloader to be requested to dynamically load a class using Class.forName() or ResourceBundle.getBundl

e() has been redefined. It must be the defining classloader of the calling class.

o The lookup order of classpath resources has been clarified.

o The visibility of Connected API classes to Classic Applet applications has been clarified.

Transactions

o Section 2.9.3 Overlapping Transaction Updates has been clarified with respect to concurrent updates in transactions.

o Section 2.9.2 Transaction Demarcation provides generic guidelines for programmer when using API classes such as collection classes.

Applet Application Environment

o This ClassicSIOProxy mechanism now ensures the thread safety of classic applications. Classic SIO proxies classes are supported only inside a classic applet application.

o The ClassicSIOProxy mechanism now supports he SIO instance echo pattern between a classic application and extended applet application.

Web Application Environment

o 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

o The behavior of the web container when login configuration is not defined has been clarified.

o Authenticator URIs are required to have a “realm” path component that must be matched by the realm name of web applications.

o The matching of the “scheme” path component of authenticator URIs with the authentication method of web apps has been relaxed.

o Interface between Authenticators and the

container for HTTP Digest authentication has been specified.

o Generic authentication procedure returns 401 when authentication fails.

o The result of a call to ServletRequest.getRemot

eUser after authentication has been clarified.

o The name of the credential parameter for the Java Card platform-specific authentication scheme has been explicitly defined.

o Mapping roles of a remotely accessible application to global card holder authenticators has been allowed, with some restrictions.

Inter-application Communication Facilities

o Ownership of standard application events created and fired by the Java Card RE on behalf of applications has been clarified.

o The restrictions on the use of the standard and platform subnamespaces for new event and service URIs has been clarified.

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

o The restrictions on unregistration of service, event and task has been

clarified (only the application that previously registered the object can unregister it).

o The restrictions on the ownership of the parameter to ownership transfer operations have been clarified.

o The handling of the extra byte lookup parameter by the classic SIO lookup fallback mechanism of the ServiceRegistry has been clarified.

o The applicability of the classic lookup fallback mechanism of the ServiceRegistry to web applications and extended applet applications has been clarified.

Firewall

o Section 6.9 Context Isolation Basics has been moved to section 2.4 to improve the readability and flow.

o The object access bytecode behavior for implicitly transferable objects has been added.

Exception Objects

o Throwable and subclasses thereof have been added to the list of implicitly transferable classes to simplify throwing exceptions across the firewall.

Credential Manager

o 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

o The subset of the URI specification (RFC 3986) has been clarified.

Classic Applet Applications

o The synchronization proxy code example in Figure 4-1 has been corrected to show proper casting and error checks.

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

o 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

o Recommended file name extensions for each distribution unit format has been introduced.

o Classic applet application and classic library distribution unit format has been clarified to show the proper path for the *.CAP components.

o Clarified to allow card manager to reject class files with unused constant pool entries containing linking error or malformed references.

o The requirements for static secure port allocation have been clarified.

o Clarified to require Classic SIO proxy classes to be added to the list of dynamically loaded classes.

o The dependency checks requirements when unloading a deployment unit have been corrected.

o The requirements for application deletion have been clarified.

o The limitation introduced by the case-insensitive handling of role names in the role mapping attributes of the runtime descriptor has been described.

o The URL for the Java Card schema documents has been corrected.

o Class loading requirements for arrays of Shareable

interfaces has been clarified.

o Classic applet application and classic library distribution unit format has been clarified to require the package to be sealed.

Miscellaneous

o The restrictions on linking with platform and SPI implementation classes has been clarified (code isolation).

o The Classic platform protection domain has been corrected to not preclude context switching from the classic application environment to the web application environment.

o The transaction facility-managed transitions upon entry into and exit from a method annotated NOT_CONNECTED has been clarified.

Back to 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

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

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.