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 resourceconstrained 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 resourceconstrained 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
This specification
Environment
describes the runtime
Specification for environment (RE) for the
the Java Card
Classic Edition of the
Platform, Classic Java Card Platform. This
Edition
RE mirrors those REs

found in previous releases

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

Connected Edition
This specification
describes the runtime
environment required for
interoperable execution of
Runtime
Java Card technologyEnvironment
based servlets and applets
Specification for with extended/advanced
the Java Card
capabilities. It also
Platform,
includes some
Connected
information on Classic
Edition
applets, but see the
Classic runtime
environment specification
for the bulk of that
information.
Java Servlet
This specification
Specification for describes the
the Java Card
requirements for
Platform,
interoperable Java Card
Connected
technology-based servlet
Edition
execution.
Application
This API defines a set of
Programming
classes upon which Java
Interface for the 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 CSScompliant 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/rea
dstep.html.

Back to top

Installation Instructions
Download and unzip the specifications
bundle. The bundle unzips into the
subdirectory javacard_specifications3_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:

- 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 ( JCREspecCLASSIC3_0_1-RR.pdf) and an HTML
version at
classic/jcre_classic/html/index.html
api_classic

- contains the Java

Card virtual machine specification
for the Classic Edition in PDF
format ( JCVMspecCLASSIC-3_0_1RR.pdf) and an HTML version at
classic/jcvm_classic/html/index.htm
l
jcvm_classic

connected/

subdirectory

Within the connected/ subdirectory you

will find the specifications as listed:

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

JCREspecCONNECTED-3_0_1RR.pdf) and an HTML version

at
connected/jcre_connected/html/inde
x.html
- contains the Java
Card virtual machine specification
for the Connected Edition in PDF
format ( JCVMspecCONNECTED3_0_1-RR.pdf) and an HTML
version at
connected/jcvm_connected/html/ind
ex.html

jcvm_connected

servlet_connected

- contains the
servlet specification for the Java
Card Platform in PDF format (
ServletspecCONNECTED-3_0_1RR.pdf ) and an HTML version at

connected/servlet_connected/html/in
dex.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

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

setOutgoingNoChaini
ng method clarified
comment about 61xx
command chaining
restrictions - #6506163

Added case 4E mentions in

setOutgoing,
setOutgoingNoChaini
ng methods where T=0
extended length 4S called
out - #6621872

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

Added support for

transient RSA, EC and
DSA private keys #6270329

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

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

Added support for Suite B

KeyAgreement for longer
secret key generation using
RAW mode - #6270320

javacard.security.InitializedMessa
geDigest
o

javacard.security.HMACKey
o

Clarified the setKey/getKey

methods for key data and
length values

javacard.security.MessageDigest
o

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

Add a definition for SHA224 hash

javacard.security.Signature
o

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 SHA2(Hash)

Added support for SHA-2 in

all applicable Signature
algorithms

Added note for

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

Added support for Suite B

EC signatures with SHA256, SHA-384 - #6270320

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

Deprecated the
ALG_RSA_ISO14888
algorithm.

Added support for Suite B

AES ciphers with 192, 256
bit blocks - #6270320

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

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

method
has been clarified to return
MEMORY_TYPE_TRANSIE
NT_RESET for instances of
TransientReference.
.isTransient()

javacard.security

The
InitializedMessageD
igest.
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.
method
has been introduced to return
the name of the key interface
type.

Key.getTypeName

MessageDigest

The Signature class has

added new signature
algorithms for the
combination of
ECDSA(Cipher) and SHA2(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

class has
added the the SHA-224 hash
algorithm.

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.

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.

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.

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.

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.

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.

The
DeploymentUnitLoade
r 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

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.getBundl
e() 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 WEBINF/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.getRemot
eUser 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 facilitymanaged 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.