Java Card™ Platform: Runtime Environment Specification, Classic Edition
Java Card™ Platform: Runtime Environment Specification, Classic Edition
Java Card™ Platform: Runtime Environment Specification, Classic Edition
February 2021
Java Card Platform Runtime Environment Specification, Classic Edition Version 3.1
Copyright © 1998, 2021, Oracle and/or its affiliates. All rights reserved.
The Specification provided herein is provided to you only under the Oracle Technology Network Developer License
included herein as Annex A - Oracle Technology Network Developer License Terms.
This software and related documentation are provided under a license agreement containing restrictions on use
and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license
agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit,
distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering,
disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.
Warranty Disclaimer
The information contained herein is subject to change without notice and is not warranted to be error-free. If you
find any errors, please report them to us in writing.
If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on
behalf of the U.S. Government, then the following notice is applicable:
U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any
programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are
"commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific
supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs,
including any operating system, integrated software, any programs installed on the hardware, and/or
documentation, shall be subject to license terms and license restrictions applicable to the programs. No other
rights are granted to the U.S. Government.
This software or hardware is developed for general use in a variety of information management applications. It is
not developed or intended for use in any inherently dangerous applications, including applications that may create
a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be
responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle
Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in
dangerous applications.
Trademark Notice
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their
respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used
under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD
logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a
registered trademark of The Open Group.
This software or hardware and documentation may provide access to or information about content, products, and
services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all
warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an
applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any
loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except
as set forth in an applicable agreement between you and Oracle.
Documentation Accessibility
For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
Oracle customers that have purchased support have access to electronic support through My Oracle Support. For
information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.
Preface .......................................................................................................................................... 14
Who Should Use This Specification......................................................................................................... 14
Before You Read This Specification......................................................................................................... 14
Shell Prompts .......................................................................................................................................... 14
Typographic Conventions ....................................................................................................................... 15
Related Documentation .......................................................................................................................... 15
Third-Party Web Sites ............................................................................................................................. 15
Documentation Accessibility................................................................................................................... 16
Access to Oracle Support ........................................................................................................................ 16
Oracle Welcomes Your Comments ......................................................................................................... 16
1 Introduction .............................................................................................................................. 17
2 Lifetime of the Java Card Virtual Machine ................................................................................ 19
2.1 Initialization....................................................................................................................................... 19
The Classic Edition of the Java Card Platform is defined by three specifications:
• Virtual Machine Specification, Java Card Platform, Version 3.1, Classic Edition,
• Runtime Environment Specification, Java Card Platform, Version 3.1, Classic Edition,
• Application Programming Interface, Java Card Platform, Version 3.1, Classic Edition.
This document is a specification of the Classic Edition of the Java Card Platform, Version 3.1,
Runtime Environment (Java Card RE).
In this book, Java Card Platform refers to version 3.1 to distinguish it from all earlier versions. A vendor
of a Java Card technology-enabled device provides an implementation of the Java Card RE. A Java Card
RE implementation within the context of this specification refers to a vendor's implementation of the
Java Card Virtual Machine (or Java Card VM), the Java Card Application Programming Interface (API), or
other component, based on the Java Card technology specifications. A "reference implementation" is an
implementation produced by Oracle. Application software written for the Java Card platform is referred
to as a Java Card technology-based applet (Java Card applet or card applet).
Shell Prompts
Shell Prompt
C shell machine-name%
C shell superuser machine-name#
Bourne shell and Korn shell $
Bourne shell and Korn shell superuser #
Related Documentation
References to various documents or products are made in this guide, so you might want to have them
available:
• Application Programming Interface, Java Card Platform, Version 3.1, Classic Edition
• Virtual Machine Specification, Java Card Platform, Version 3.1, Classic Edition
• The Java Language Specification (https://docs.oracle.com/javase/specs/)
• ISO 7816 Specification Parts 1-6. (https://www.iso.org)
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info
http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs
The runtime environment (RE) for the Java Card Platform, Version 3.1, comprises the Java Card Virtual
Machine (VM), the Java Card Application Programming Interface (API) classes (and industry-specific
extensions), and support services.
This document specifies the Java Card RE functionality required by the Classic Edition of the Java Card
technology:
Any implementation of Java Card technology shall provide this necessary behavior and environment.
In a PC or workstation, the Java virtual machine1 runs as an operating system process. When the OS
process is terminated, the Java programming language applications and their objects are automatically
destroyed.
In Java Card technology, the execution lifetime of the virtual machine (VM) is the lifetime of the secure
element. Most of the information stored on a secure element shall be preserved even when power is
turned off. Persistent memory technology (such as EEPROM) enables a secure element or smart card to
store information when power is removed. Because the VM and the objects created on the card are
used to represent application information that is persistent, the Java Card VM appears to run forever.
When power is removed, the VM only stops temporarily. When the secure element is next reset, the VM
starts again and recovers its previous object heap from persistent storage.
Aside from its persistent nature, the Java Card virtual machine is just like the Java virtual machine.
2.1 Initialization
The secure element initialization time is the time after masking, and prior to the time of secure element
personalization and issuance. At the time of secure element initialization, the Java Card RE is initialized.
The framework objects created by the Java Card RE exist for the lifetime of the virtual machine. Because
the execution lifetime of the virtual machine and the Java Card RE framework span power sessions of
the secure elements, the lifetimes of objects created by applets also span power sessions. Objects that
have this property are called persistent objects. Power sessions are those periods when the secure
element is powered-up, is exchanging streams of commands and ends when powered-down.
• The Applet.register method is called. The Java Card RE stores a reference to the instance
of the applet object. The Java Card RE implementer shall ensure that instances of class applet
are persistent.
• A reference to an object is stored in a field of any other persistent object or in a class's static
field. This requirement stems from the need to preserve the integrity of the Java Card RE's
internal data structures.
1
The terms "Java Virtual Machine" and "JVM" mean a Virtual Machine for the Java platform.
For the purposes of this specification, applet refers to an applet written for the Java Card platform. An
applet instance's lifetime begins when it is successfully registered with the Java Card RE via the
Applet.register method. Applets registered with the Applet.register method exist until
deleted by the Applet Deletion Manager (Section 11.3 The Applet Deletion Manager). The Java Card RE
initiates interactions with the applet via the applet's public methods install, select, deselect,
and process. An applet shall implement the static install(byte[], short, byte) method. If the
install(byte[], short, byte) method is not implemented, the applet's objects cannot be
created or initialized. A Java Card RE implementation shall call an applet's install, select,
deselect, and process methods as described below.
When the applet is installed on the smart card, the static install(byte[],short,
byte)method is called once by the Java Card RE for each applet instance created. The Java Card RE
shall not call the applet's constructor directly.
Typically, an applet creates various objects, initializes them with predefined values, sets some internal
state variables, and calls either the Applet.register() method or the
Applet.register(byte[], short, byte) method to specify the AID (applet IDentifier as
defined in ISO 7816-5) to be used to select it. This installation is considered successful when the call to
the Applet.register method completes without an exception. The installation is deemed
unsuccessful if the install method does not call the Applet.register method, or if an exception
is thrown from within the install method prior to the Applet.register method being called, or
if the Applet.register method throws an exception. If the installation is unsuccessful, the Java
Card RE shall perform all cleanup when it regains control. That is, all conditional updates to persistent
storage shall be returned to the state they had prior to calling the install method. If the installation
is successful, the Java Card RE can mark the applet as available for selection.
Prior to calling select, the Java Card RE shall deselect the previously selected applet. The Java Card RE
indicates this to the applet by invoking the applet's deselect method or, if concurrently selected on
more than one logical channel, its MultiSelectable.deselect method (for more details, see
Section 4.3 Multiselectable Applets).
The Java Card RE informs the applet of selection by invoking its select method or, if being
concurrently selected on more than one logical channel, its MultiSelectable.select method
(for more details, see Section 4.3 Multiselectable Applets).
The applet may decline to be selected by returning false from the call to the select method or by
throwing an exception. If the applet returns true, the actual SELECT FILE APDU command is supplied to
the applet in the subsequent call to its process method, so that the applet can examine the APDU
contents. The applet can process the SELECT FILE APDU command exactly like it processes any other
APDU command. It can respond to the SELECT FILE APDU with data (see Section 3.3 process Method
for details), or it can flag errors by throwing an ISOException with the appropriate returned status
word. The status word and optional response data are returned to the CAD.
The Applet.selectingApplet method shall return true when called during the select
method. The Applet.selectingApplet method continues to return true during the
subsequent process method, which is called to process the SELECT FILE APDU command.
If the applet declines to be selected, the Java Card RE returns an APDU response status word of
ISO7816.SW_APPLET_SELECT_FAILED to the CAD. Upon selection failure, the Java Card RE state
is set to indicate that no applet is selected. See Section 4.6 Applet Selection for more details.
After successful selection, all subsequent APDUs directed to the assigned logical channel are delivered
to the currently selected applet via the process method.
On normal return, the Java Card RE automatically appends 0x9000 as the completion response status
word to any data already sent by the applet.
On normal return, when an applet initiated transaction is in progress, the Java Card RE aborts the
transactions and returns the status word ISO7816.SW_UNKNOWN to the CAD. See Section 7.6.2
Abortion by the Java Card RE.
At any time during process, the applet may throw an ISOException with an appropriate status word,
in which case the Java Card RE catches the exception and returns the status word to the CAD.
If any other exception is thrown during process, the Java Card RE catches the exception and returns the
status word ISO7816.SW_UNKNOWN to the CAD.
The deselect method allows the applet to perform any cleanup operations that may be required to
allow some other applet to execute.
The Applet.selectingApplet method shall return false when called during the deselect
method. Exceptions thrown by the deselect method are caught by the Java Card RE, but the applet is
deselected.
This method may be called multiple times, once for each applet deletion attempt.
When power is reapplied to the card and on card reset (warm or cold) the Java Card RE shall ensure
that:
Note: On cards on which contacted and contactless interfaces are not independent, the ISO7816-2
defined reset signal input (RST) contact resets the card and the Java Card RE must handle this event
as defined in Section 3.6 Power Loss and Reset.
A Java Card technology compliant proximity contactless card operates in the ACTIVE state and processes
commands defined in the ISO 14443 Specification Parts 1-4 or using the commands defined by the SWP
interface standard (ETSI TS 102 613).
The following conditions are deemed as a reset of the contactless I/O interface:
• The ISO 14443 Supervisory block (S-block) DESELECT command results in the proximity card
entering the HALT state.
• A loss of RF field results in the proximity card entering the POWER OFF state.
• A contactless interface which is accessed using the SWP interface is logically reset.
• The transaction in progress in the currently selected applet instance executing on a logical
channel on the contactless I/O interface, if any, must be aborted.
• Each applet instance that was active on a logical channel over the contactless I/O interface,
must be deselected.
If the contactless interface, using the SWP interface standard, is being logically reset, the applet
instances are explicitly deselected by calling the applicable deselect method. Otherwise, the
instances are implicitly deselected and the deselect method is not called.
• All the logical channels open on the contactless I/O interface are implicitly closed.
• Transient data of CLEAR_ON_DESELECT objects associated with each applet instance that was
active on a logical channel over the contactless I/O interface and that does not have an applet
instance from the same context active on any logical channel over the contacted I/O interface, is
reset to the default value.
Note: To establish a card session over both contacted and contactless interfaces concurrently, on
cards on which the ISO7816-2 defined reset signal input (RST) contact resets the card, the CAD must
initiate the contacted session first. A power loss or card reset on the contacted interface results in a
card tear and card reset event even if a contactless session is in progress. An RF signal loss, or logical
reset, on the contactless interface must not affect an ongoing contacted session.
On some cards, the ISO7816-2 defined reset signal input (RST) is used to reset only the contacted I/O
interface. On some other cards, the contacted I/O interface may be a universal serial bus interface (USB)
or some other physical interconnect which logically transports ISO 7816-4 APDU commands and
responses. When the contacted I/O interface of such a card concurrently operating over both the
contacted as well as the contactless I/O interfaces, with full operational power, is reset, the Java Card RE
must ensure the following:
• A single contacted I/O interface conforming to ISO 7816 parts 1-4 specifications
• A single contacted I/O interface based on ISO 7816-4 standards over the USB interface specified
in the ISO 7816-12 specification and/or the European Telecommunications Standards Institute
(ETSI) TS 102 600 specification
• A single contactless I/O interface based on the ISO 14443 specifications or the ETSI defined
single wire protocol (SWP) TS 102 613 specification
• Dual I/O interfaces - one contacted and one contactless interface based on the standards
described above
Logical channel sessions as described in this chapter may be supported over any of these interfaces. In
addition, a dual interface card may be able to sustain logical channel sessions over both the contacted
and the contactless interface simultaneously.
An implementation may support between 1 and 20 logical channels over the contacted I/O interface.
Similarly, an implementation may support between 1 and 20 logical channels over the contactless I/O
interface. When both I/O interfaces are concurrently active, the number of logical channels supported
on each of the two interfaces is also implementation specific.
Note: To establish a card session over both contacted and contactless interfaces concurrently,
on cards on which the ISO7816-2 defined reset signal input (RST) contact resets the card, the
CAD must initiate the contacted session first. A power loss or card reset on the contacted
interface results in a card tear and card reset event even if a contactless session is in progress.
An RF signal loss, or logical reset, on the contactless interface must not affect an ongoing
contacted session.
An applet written for the Java Card Platform, Classic Edition, can be designed to take advantage of
logical channel support. Such an applet can take advantage of multi-session functionality, can be
concurrently selected alongside another applet on a different logical channel, and even be selected
multiple times simultaneously on different logical channels. As shown in Figure 4-1: Logical Channels for
Distinct Applets, an implementation may support from one to twenty logical channels on each I/O
interface, each with its own distinct CLEAR_ON_DESELECT transient memory segment2.
Only one logical channel, logical channel number 0 (the basic logical channel) becomes active on the
contacted I/O interface following a card reset. Similarly, only one logical channel, logical 0 (the basic
logical channel) becomes active on the contactless I/O interface following a PICC activation sequence. A
MANAGE CHANNEL APDU command may be issued on this logical channel to instruct the card to open a
new logical channel. Applet instances can be selected on different logical channels using the SELECT FILE
APDU command, just as they would in a single logical channel environment. The MANAGE CHANNEL
APDU command is also used for closing a logical channel. Note that the basic logical channel is
permanent and can never be closed as long as the I/O interface remains activated.
On a card that is able to sustain logical channel sessions over both interfaces simultaneously, there are
two sets of twenty logical channels possible. A logical channel number 0 on the contacted I/O interface
is not the same as the logical channel number 0 on the contactless I/O interface. An applet instance
selected on a logical channel on the contacted I/O interface would normally receive APDUs only from
the contacted I/O interface. However, it can receive APDUs from the contactless I/O interface also, only
if the applet instance is concurrently selected on a logical channel on the contactless I/O interface. Rules
of multiselection apply as described in Section 4.3 Multiselectable Applets.
Legacy applets written for version 2.1 of the Java Card Platform running on the Java Card Platform,
Classic Edition, need not be aware of logical channel support to work correctly. The Java Card RE must
2
The term "CLEAR_ON_DESELECT transient memory segment" is used to denote a logical partition of volatile
memory which contains the data associated with CLEAR_ON_DESELECT transient arrays of an active application.
The word "segment" is intended to suggest that the implementation may overlay the same physical area of volatile
memory being used for the transient memory segment of an active application with that of another application
when its context is no longer active. For example, if only one logical channel is supported, only one such physical
memory area in volatile memory is sufficient.
Support for multiple logical channels (with multiple selected applet instances) requires a change to the
Java Card platform version 2.1.* concept of selected applet. Because more than one applet instance can
be selected at the same time, and one applet instance can be selected on different logical channels
simultaneously, it is necessary to differentiate the state of the applet instances in more detail.
An applet instance is considered an active applet instance if it is currently selected in at least one logical
channel, up to a maximum of forty. Each active applet instance from a distinct context executes with a
distinct CLEAR_ON_DESELECT transient memory segment (see Figure 4-1: Logical Channels for
Distinct Applets). An applet instance is the currently selected applet instance only if it is processing the
current command. There can only be one currently selected applet instance at a given time.
Applets with the capability of being selected on multiple logical channels at the same time, or accepting
other applets belonging to the same context being selected simultaneously, are referred to as
multiselectable applets. (Refer to Figure 4-2: Different Applet Instances in Same Context.)
No applet is active on the new (or only) logical channel when one of the following occurs:
• The card is reset and no applet is designated as the default applet instance for the basic channel
on the contacted I/O interface, or the default applet instance for the basic channel on the
contacted I/O interface rejects selection.
• The card successfully completes its PICC activation sequence and no applet is designated as the
default applet instance for the basic channel on the contactless I/O interface, or the default
applet instance for the basic channel on the contactless I/O interface rejects selection.
In a similar manner, some smart card proximity coupling device (PCD) applications require a default card
applet instance to become implicitly selected after the proximity card (PICC) activation sequence
successfully completes. In addition, default applet selection may also be required on each new logical
channel opened during the contactless session.
The Java Card platform allows the card implementer to designate a default applet instance for each of
the logical channels supported by the card. For any logical channel, the card implementation may
designate an applet instance as the default applet instance for that logical channel. Alternatively, for any
logical channel, the implementation may choose to designate no default applet instance at all. Logical
channels may share the same applet instance as the default applet instance for more than one channel.
Upon card reset on the contacted interface and upon the completion of the PICC activation sequence on
the contactless interface, only the basic logical channel (channel 0) is automatically opened. The default
card applet instance for the contacted interface, if any, is therefore the default applet instance for
logical channel 0 on the contacted interface. Similarly, the default card applet instance for the
contactless interface, if any, is therefore the default applet instance for logical channel 0 on the
contactless interface. A card that supports both I/O interfaces could designate the same applet instance
or a different applet instance as the default card applet instance for each interface.
1. After card reset (or power on, which is a form of reset) on the contacted I/O interface, the Java
Card RE performs its initialization and checks to see if its internal state indicates that a particular
applet instance is the default applet instance for the basic logical channel. If so, the Java Card RE
makes this applet instance the currently selected applet instance on the basic logical channel,
and the applet's select method is called. If this method throws an exception or returns
false, or returns true when an applet-initiated transaction is in progress, the Java Card RE
sets its state to indicate that no applet is active on the basic logical channel.
2. The Java Card RE ensures that the Answer to Reset (ATR) was sent and the card is now ready to
accept APDU commands.
1. After the successful completion of the PICC activation sequence on the contactless interface, the
Java Card RE performs its initialization, if the contacted interface is not already active, and then
checks to see if its internal state indicates that a particular applet instance is the default applet
instance for the basic logical channel on the contactless I/O interface. If the default applet is not
a multiselectable applet (see Section 4.3 Multiselectable Applets) and either an instance of the
default applet is already active on the contacted interface, or another applet instance from the
same context is active on the contacted interface, the Java Card RE sets its state to indicate that
no applet is active on the basic logical channel. Otherwise, the Java Card RE makes this applet
instance the currently selected applet instance on the basic logical channel on the contactless
I/O interface, and informs the applet instance of its selection - if the applet's context is active on
the contacted interface, calls the MultiSelectable.select method with the
appInstAlreadyActive set to indicate if the same applet instance is already active, and
otherwise, if the applet's context is not active on the contacted interface, calls the
Applet.select method. If multiselection is required for selecting the default applet but the
default applet does not implement the MultiSelectable interface, or if the select
method throws an exception or returns false, or returns true when an applet-initiated
transaction is in progress, the Java Card RE sets its state to indicate that no applet is active on
the basic logical channel on the contactless I/O interface.
When a default card applet instance becomes active after the successful completion of the PICC
activation sequence on the contactless interface, it shall not require its process method to be
called. The applet instance's process method is not called during default applet selection
because there is no SELECT FILE APDU.
2. The Java Card RE ensures that the Answer to Select (ATS), if applicable, was sent and the card is
now ready to accept APDU commands.
When a MANAGE CHANNEL command is issued on the basic logical channel and a new logical channel is
opened, the Java Card RE checks if there is a designated default applet instance for the newly opened
logical channel. If so, the Java Card RE makes this applet instance the currently selected applet instance
If a default applet instance is successfully selected, then APDU commands can be sent directly to the
applet instance on that logical channel. If no applet is active, then only SELECT FILE commands for applet
selection or MANAGE CHANNEL commands can be processed on that logical channel.
A MANAGE CHANNEL command issued over an I/O interface shall open a new logical channel only on
the same I/O interface. Similarly a SELECT FILE command issued over an I/O interface to open a new
logical channel shall open a new logical channel only on the same I/O interface.
The mechanism for specifying the default applet instance for a logical channel is not defined in the Java
Card API. It is a Java Card RE implementation detail and is left to the individual implementers.
Note: All applets within a CAP file shall be multiselectable or none shall be.
An applet's context is active when either an instance of the applet is already active, or when another
applet instance from the same context is active. For more information about contexts see Section 6.1.2
Contexts and Context Switching. An attempt to select an applet instance when the applet's context is
active, is referred to as a multiselection attempt. If successful, multiselection occurs, and the applet
instance becomes multiselected.
When an applet instance not currently active is the first one selected in its context, its
Applet.select method is called. Subsequent multiselections to this applet instance or selection of
other applet instances in the same context shall result in a call to MultiSelectable.select
method. This method is defined in the MultiSelectable interface. Its only purpose is to inform the
applet instance that it will be multiselected. The applet instance may accept or reject a multiselection
attempt.
If a multiselection attempt is made on an applet which does not implement the MultiSelectable
interface, the selection shall be rejected by the Java Card RE.
1. When two distinct applet instances from within the same context are multiselected, each applet
instance shares the same CLEAR_ON_DESELECT memory transient segment. The applet
instances share objects within the context firewall as well as their transient data. The Java Card
RE shall not reset this CLEAR_ON_DESELECT transient objects until all applet instances within
the context are deselected, see Figure 4-2: Different Applet Instances in Same Context.
2. When the same applet instance is multiselected on two different logical channels
simultaneously, it shares the CLEAR_ON_DESELECT memory segment space across logical
channels. The Java Card RE shall not reset the CLEAR_ON_ DESELECT transient objects until all
applet instances within the context are deselected, see Figure 4-3: Same Applet Instance
Selected on Multiple Logical Channels.
In addition, cards compliant with the Java Card Platform specification must also support proprietary
class values of the CLA byte equal to 0x8X, 0x9X, 0xAx and 0xBX for channel numbers in the range 0-3
and proprietary class values of the CLA byte equal to 0xCY, 0xDY, 0xEY and 0xFY for channel numbers 4-
19 (using 0 origin notation). The bit encoding of the proprietary class values of the CLA byte mirror that
of the ISO 7816-4:2013 Specification defined interindustry values with the most significant bit b8 set to
1. Table 4-2 and Table 4-3 show the supported encodings of the CLA byte.
The two least significant bits (b2,b1*) of the X nibble encodes the logical channels numbers 0-3, whereas
the Y nibble (b4-b1*) encodes logical channel numbers in the range 4-19 (using 0 origin notation). When
an APDU command is received, the Java Card RE shall process it and determine whether or not the
command has logical channel information. If logical channel information is encoded, the card dispatches
the APDU command to the appropriate logical channel on that I/O interface. All other APDU commands
are forwarded to the basic logical channel (logical channel 0) on that I/O interface.
Notation Description
u undefined
y Secure Messaging (SM) indicator See ISO 7816-4:2013
Specification Section 6 for further information.
z Logical channel indicator Type 4 supports logical channels
[0..3] Type 16 supports logical channels [4..19]
Note: CLA byte 0xFX cannot encode logical channel 19 because CLA = 0xFF is a reserved
value for Protocol Type Selection. In compliance with ISO 7816-4:2013 Specification, logical
channel number 19 is not available when using this CLA byte.
The Java Card RE always forwards the command "as is" to the appropriate applet instance. In particular,
the Java Card RE does not clear the logical channel encoding bits of the CLA byte.
To avoid the complexity of the transport information encoded in the CLA byte of the APDU command
header, the application programmer is advised not to parse the CLA byte directly. The following
methods in the javacard.framework.APDU class may be used to extract application specific
information:
• APDU.isISOInterindustryCLA
• APDU.isSecureMessagingCLA
• APDU.isCommandChainingCLA
• APDU.getCLAChannel
• APDU.isValidCLA
With the addition of logical channels in Java Card platform, the Java Card RE includes a multichannel
dispatching mechanism, as well as checks to ensure applet integrity during multi-channel operations.
The Java Card RE must ensure that applets written to operate in a single logical channel environment
operate consistently on a multiple logical channel smart card.
Java Card platform defines a class of APDU commands, called MANAGE CHANNEL commands. The
functions the Java Card RE must perform by using MANAGE CHANNEL command processing are:
MANAGE CHANNEL OPEN: Open a new logical channel from an already-open logical channel. Two
variations of this command are supported:
• The Java Card RE selects the new logical channel specified in the command
• The Java Card RE automatically assigns a new logical channel.
MANAGE CHANNEL CLOSE: Close a specified logical channel from another open logical channel.
In addition, the SELECT FILE APDU command to select an applet instance is extended to specify a
new or already opened logical channel on which the specified applet instance is to be selected.
The term origin logical channel refers to the logical channel on which the command is received based
on the logical channel number encoding within the CLA byte, as described in Section 4.4 Forwarding
APDU Commands To a Logical Channel.
The Java Card RE shall guarantee that an applet that is designed to run on any logical channel can be
selected on any of the available logical channels on the card. The resources accessed by the applet
instance must be the same, irrespective of the logical channel on which it is selected.
1. The MANAGE CHANNEL OPEN command uses: CLA=%b000000cc* (where cc in the bits
(b2,b1) denotes the origin logical channel: 0-3), or CLA=%0100dddd* (where dddd in the bits
(b4-b1) denote the origin logical channel: 4-19), INS=0x70and P1=0. Two variants of this
command are supported:
• P2=0 when the Java Card RE shall assign a new logical channel number.
• P2=the logical channel number specified.
o If the MANAGE CHANNEL OPEN command has non-zero secure messaging bits
(b4,b3*) in the CLA byte when the origin logical channel is 0-3 or non-zero bit (b6*)
when the origin logical channel is 4-19, the Java Card RE responds with status code
0x6882 (SW_SECURE_MESSAGING_NOT_SUPPORTED).
o If the MANAGE CHANNEL OPEN command is issued with a specified logical channel
number greater than 19, the Java Card RE responds with status code 0x6A81
(SW_FUNC_NOT_SUPPORTED).
2. If the origin logical channel on that I/O interface is not open, the Java Card RE responds with status
code 0x6881 (SW_LOGICAL_CHANNEL_NOT_SUPPORTED)
3. If the Java Card RE supports only the basic logical channel on that I/O interface, the Java Card RE
responds with status code 0x6881 (SW_LOGICAL_CHANNEL_NOT_SUPPORTED).
4. If the P2=0 variant is used:
• If the expected length value (Le) is not equal to 1, the Java Card RE responds with status
code 0x6C01 (SW_CORRECT_LENGTH_00+0x01).
• If resources for the new logical channel are not available, the Java Card RE responds with
status code 0x6A81 (SW_FUNC_NOT_SUPPORTED).
5. If the P2!=0 variant is used:
If the specified logical channel number is not supported or resources for the specified logical
channel are not available or the logical channel is already open, the Java Card RE responds with
status code 0x6A86 (SW_INCORRECT_P1P2).
Note: Unlike the SELECT FILE commands to select an applet instance, the MANAGE CHANNEL
command is never forwarded to the applet instance.
1. The Applet SELECT FILE command uses: CLA=%b000000cc* (where cc in the bits (b2,b1*)
specifies the logical channel to be selected: 0-3), or CLA=%0100dddd* (where dddd in the
bits (b4-b1) denote the origin logical channel: 4-19) and INS=0xA4.
If the SELECT FILE command has non-zero secure messaging bits (b4,b3*) in the CLA byte when
the origin logical channel is 0-3 or non-zero bit (b6*) when the origin logical channel is 4-19, it is
deemed not to be an Applet SELECT FILE command. The Java Card RE simply forwards the
command to the active applet on the specified logical channel.
• The Applet SELECT FILE command uses "Selection by DF name" with P1=0x04.
• The Java Card RE shall support both of the following:
o Selection by "exact DF name(AID)"3 with P2=%b0000xx00 (b4,b3* are ignored) and
o The RFU variant described in ISO 7816-4 Specification with P2=%b0001xx00 (b4,b3*
are ignored).
• All other partial DF name SELECT FILE options (b2,b1* variants) are Java Card RE
implementation dependent. Errors which occur during the processing of these commands
may result in implementation-defined, error response status codes.
• All file control information options codes (b4,b3*) of the P2 parameter shall be supported by
the Java Card RE and interpreted and processed by the applet instance itself.
2. If resources for the specified logical channel are not available, the Java Card RE responds with
status code 0x6881 (SW_LOGICAL_CHANNEL_NOT_SUPPORTED).
3. If the specified logical channel is not open on the I/O interface that received the SELECT FILE
command, it is now opened and the Java Card RE state is set so that no applet is active on this
new logical channel. The specified logical channel will be the assigned channel for the applet
instance that will be active on it.
4. The Java Card RE searches the internal applet table which lists all successfully installed applet
instances on the card for an applet instance with a matching AID. If a matching applet instance is
found, it is picked as the candidate applet instance. Otherwise, if no AID match is found:
3 If the implementation supports partial DF name selection, and the AID of an applet instance is a truncation of
the AID of another applet instance on the card, implementation defined rules of "first DF name" selection may
be applicable.
Note: If the SELECT FILE command does not conform to the exact format of an Applet
SELECT FILE command described in item 1 above or if there is no matching AID, the
SELECT FILE command is forwarded to the active applet instance (if any) on that logical
channel for processing as a normal applet APDU command.
Note: If there is a matching AID and the SELECT FILE command fails, the Java Card RE
always sets the state in which no applet is active on that logical channel.
Note: If the matching AID is the same as the active applet instance on the specified
logical channel, the Java Card RE still goes through the process of deselecting the applet
instance and then selecting it. Reselection could fail, leaving the card in a state in which
no applet is active on that logical channel.
In either case, when an applet instance is deselected the following procedure shall be followed by the
Java Card RE:
• If the applet instance to be deselected is active on more than one logical channel, or another
applet instance from the same context is also active, the Java Card RE sets the currently selected
applet instance to be the applet instance being deselected, and calls its
MultiSelectable.deselect(appInstStillActive) method, where the
appInstStillActive parameter is set to true if the same applet instance is still active on
another logical channel. A context switch occurs into the applet instance's context at this point,
see Section 6.1.2 Contexts and Context Switching.
• Otherwise, the Java Card RE sets the currently selected applet instance to be the applet instance
being deselected, and calls its Applet.deselect method. Upon return or uncaught
exception, the Java Card RE clears the fields of all CLEAR_ON_DESELECT transient objects in
the context of deselected applet instance.
Note: Note that the deselection is always successful even if the applet instance throws
an exception from within the deselect method.
1. The MANAGE CHANNEL CLOSE command uses: CLA=%b000000cc* (where cc in the bits (b2,b1)
denotes the origin logical channel: 0-3) or CLA=%0100dddd* (where dddd in the bits (b4-b1) denote
the origin logical channel: 4-19), INS=0x70, P1=0x80 and P2 specifies the logical channel to be
closed.
If the MANAGE CHANNEL CLOSE command has non-zero secure messaging bits (b4,b3) in the CLA
byte when the origin logical channel is 0-3 or non-zero bit (b6*) when the origin logical channel is 4-
19, the Java Card RE responds with status code
0x6882(SW_SECURE_MESSAGING_NOT_SUPPORTED).
2. If the origin logical channel on the I/O interface that received the MANAGE CHANNEL CLOSE
command is not open, the Java Card RE responds with status code 0x6881
(SW_LOGICAL_CHANNEL_NOT_SUPPORTED).
3. If the Java Card RE supports only the basic logical channel on the I/O interface that received the
MANAGE CHANNEL CLOSE command, the Java Card RE responds with status code 0x6881
(SW_LOGICAL_CHANNEL_NOT_SUPPORTED).
4. If the specified logical channel to close is the basic logical channel (logical channel 0) or the specified
logical channel number is greater than 19, the Java Card RE responds with status code 0x6A81
(SW_FUNC_NOT_SUPPORTED).
5. If the specified logical channel to close is currently open on the I/O interface that received the
MANAGE CHANNEL CLOSE command, deselect the active applet instance (if any) on the specified
logical channel as described above in Section 4.7 Applet Deselection. The specified logical channel is
now closed. The Java Card RE responds with status code 0x9000.
6. Otherwise, if the specified logical channel is closed or not available on that I/O interface, the Java
Card RE responds with warning status code 0x6200 (SW_WARNING_STATE_UNCHANGED).
When the Java Card RE receives an APDU other than a SELECT FILE or MANAGE CHANNEL command with
either of the following:
When an APDU other than a Applet SELECT FILE or a MANAGE CHANNEL command is received, and
there is an active applet instance on the logical channel to be used for dispatching the command, the
Java Card RE sets the active applet instance on the origin channel as the currently selected applet
instance and invokes the process method passing the APDU as a parameter. This causes a context
switch from the Java Card RE context into the currently selected applet instance's context (For more
information on contexts see Section 6.1.2 Contexts and Context Switching.) When the process
method exits, the VM switches back to the Java Card RE context. The Java Card RE sends the response
APDU and waits for the next command APDU.
Note that the Java Card RE dispatches the APDU command "as is" to the applet instance for processing
via the process method. Therefore, the CLA byte in the command header contains in its least
significant bits the origin channel number. An applet designed to run on any logical channel needs to
mask out these two bits before checking for specific values.
The Java Card Virtual Machine conforms to the relevant subset of the Java Language Specification
memory model. In particular, it provides a strong guarantee about the visibility and ordering of all
individual actions (such as read and write) in an execution of a program that must be sequentially
consistent with the order of the program.
Besides these rules, the Java Card Virtual Machine lifetime (see section 2) implies that the Java Card
Virtual Machine uses non-volatile memory to persistently store object heap. Multiple memory layout
and strategies are possible and depend on the capability and characteristics of the underlying hardware
platform. Note that objects referenced from another persistent object must be persistent and a Java
Card Virtual Machine implementation may use volatile memory for short-lived objects only referenced
from the stack or volatile memory. In any case, specific implementation strategies using cache or storing
such temporary objects in volatile memory must not affect their behavior. These objects shall behave
like other objects and therefore conform to the rules defined in section 7 Transactions and Atomicity.
This has implications on the application programming model. An application must expect that
operations performed on a persistent object will imply non-volatile memory updates (see also section 7
Transactions and Atomicity). Applications sometimes require objects that contain temporary (transient)
data that need not be persistent or data that, for security reasons or because it is frequently updated,
must not be stored in non-volatile memory. In this case, it must use transient objects.
This chapter describes special kinds of objects and how they are treated within a Java Card runtime
environment.
Note: In this section, the term field is used to refer to the component of an array object also.
The term "transient object" is a misnomer. It can be incorrectly interpreted to mean that the object
itself is transient. However, only the contents of the fields of the object (except for the length field) have
a transient nature. As with any other object in the Java programming language, transient objects within
the Java Card platform exist as long as they are referenced from:
• The stack
• Local variables
• A class static field
• A field in another existing object
• The fields of a transient object shall be cleared to the field's default value (zero, false, or
null) at the occurrence of certain events (see Section 5.1.2 Events That Clear Transient
Objects).
• For security reasons, the fields of a transient object shall never be stored in a "persistent
memory technology." Using current smart card technology as an example, the contents of
transient objects can be stored in RAM, but never in EEPROM. The purpose of this requirement
is to allow transient objects to be used to store session keys.
• Writes to the fields of a transient object shall not have a performance penalty. Using current
smart card technology as an example, the contents of transient objects can be stored in RAM,
while the contents of persistent objects can be stored in EEPROM. Typically, RAM technology
has a much faster write cycle time than EEPROM.
• Writes to the fields of a transient object shall not be affected by "transactions." That is, an
abortTransaction never causes a field in a transient object to be restored to a previous
value.
This behavior makes transient objects ideal for small amounts of temporary applet data that is
frequently modified, but that need not be preserved across CAD or select sessions.
• CLEAR_ON_RESET - The object's fields (except for the length field) are cleared when the card is
reset. When a card is powered on, this also causes a card reset.
Note: It is not necessary to clear the fields of transient objects before power is removed from a
card. However, it is necessary to guarantee that the previous contents of such fields cannot be
recovered once power is lost.
• CLEAR_ON_DESELECT - The object's fields (except for the length field) are cleared whenever the
applet is deselected and no other applets from the same context are active on the card. Because
a card reset implicitly deselects the currently selected applet, the fields of CLEAR_ON_DESELECT
objects are also cleared by the same events specified for CLEAR_ON_RESET.
The currently selected applet is explicitly deselected (its deselect method is called) only when a SELECT
FILE command or MANAGE CHANNEL CLOSE command is processed. The currently selected applet is
deselected and then the fields of all CLEAR_ON_DESELECT transient objects owned by the applet are
cleared if no other applets from the same context are active on the card, regardless of whether the
SELECT FILE command:
An application has no direct control on designating temporary objects and the temporary attribute is
assigned by the Java Card Runtime Environment in a limited number of cases:
• Some JCRE Entry Point Objects are temporary objects: the APDU object and all Java Card RE
owned exception objects are examples of temporary objects.
• All global arrays are temporary objects: the APDU buffer is an example of global array
• All array views are temporary objects.
• From Java language perspective, an array view is an array and is accessed via the same set of
array-access byte-codes. In particular, an array view can be used as parameter of any method
that accept an array with same type.
• The elements of a view are mapped to the selected subset of the actual parent array and any
modification in the parent array is visible in the view and vice versa. Also note that a view can
map all the elements of its parent array. By construction, a view is a different object from its
parent, with its own attributes (type, firewall context, length) but with same memory location
for its elements.
• The elements of a view have the exact same type as the elements of the parent array.
• A view has configurable read/write access rights that can be specified at its creation time. These
access rights apply only to accessing the elements of the array (bytecodes <T>aload,
<T>astore), not to invoking methods, reading the length or checking the type.
• A view is a temporary object. Consequently, it is not possible to store a reference to a view in
class variables, instance variables or array components.
• A parent array cannot be deleted (garbage collected) if an array view mapping its elements still
exist.
• The specified source must be an array accessible from the context creating the view.
Particularly, when the source is a CLEAR_ON_DESELECT transient array, the currently active
context must be the context of the currently selected applet.
• The range of elements specified must not go beyond the boundaries of the specified source
array. If the source array is a view, the array view being created shall map the actual array
elements and the elements mapped shall remain in the range of elements accessible to the
source view.
• The created array view shall not be granted access rights that are not allowed on the source
array. For example, it is not possible to create a writable view mapping the elements from a
read-only view.
A view can be created in the context of the application creating the view, or in the context of a provided
Sharable Interface Object of a server application. In the latter case, the main purpose is to share a
subset of the elements of an array as parameter with a server application and the array view will only be
accessible in the context of the server application and not in the context of the application creating it.
For more details, see section 6.2.2.2 Sharing using Array Views and see the
JCSystem.makeArrayView() method definition in the Application Programming Interface, Java Card
Platform, Version 3.1.
A view can be used as parameter of any method of the Java Card API that accept an array with same
type. The parameters used as input buffer(s) must be readable and API implementation must support
read-only views for these parameters. The parameters used as output buffer(s) must be writable and
API implementation must support write-only views for these parameters.
An application can use the following methods to get details about a view
• JCSystem.isArrayView(Object) to check if an object is an array view
• JCSystem.getAttributes(Object) to get the access attributes of a view
(ATTR_READABLE_VIEW, ATTR_WRITABLE_VIEW)
• JCSystem.isTransient(Object) to get the memory type where the elements mapped
by the view are located.
• SensitiveArrays.isIntegritySensitive(Object) to check whether the view is
mapping elements that belong to a sensitive array.
For that purpose, a call to JCSystem.isTransient(Object) or
SensitiveArrays.isIntegritySensitive(Object)on a view returns the same value as if called
on the parent array.
Any implementation of the Java Card RE shall support isolation of contexts and applets. Isolation means
that one applet cannot access the fields or objects of an applet in another context unless the other
applet explicitly provides an interface for access. The Java Card RE mechanisms for applet isolation and
object sharing are detailed in the following sections.
Applet firewalls are always enforced in the Java Card VM. They allow the VM to automatically perform
additional security checks at runtime.
The firewall also provides protection against incorrect code. If incorrect code is loaded onto a card, the
firewall still protects objects from being accessed by this code.
This specification, Runtime Environment Specification, Java Card Platform, Version 3.1, Classic Edition,
specifies the basic minimum protection requirements of contexts and firewalls because the features
described in this document are not transparent to the applet developer. Developers shall be aware of
the behavior of objects, APIs, and exceptions related to the firewall.
Java Card RE implementers are free to implement additional security mechanisms beyond those of the
applet firewall, as long as these mechanisms are transparent to applets and do not change the externally
visible operation of the VM.
Figure 6-1: Contexts Within the Java Card Platform's Object System
In addition, the Java Card RE maintains its own Java Card RE context. This context is much like the
context of an applet, but it has special system privileges so that it can perform operations that are
denied to contexts of applets. For example, access from the Java Card RE context to any applet
instance's context is allowed, but the converse, access from an applet instance's context to the Java
Card RE context, is prohibited by the firewall.
4
Note that a library CAP File is not assigned a separate context. Objects from a library belong to the context of the
creating applet instance.
During a context switch, the previous context and object owner information is pushed on an internal VM
stack, a new context becomes the currently active context, and the invoked method executes in this
new context. Upon exit from that method the VM performs a restoring context switch. The original
context (of the caller of the method) is popped from the stack and is restored as the currently active
context. Context switches can be nested. The maximum depth depends on the amount of VM stack
space available.
Most method invocations in Java Card technology do not cause a context switch. For example, a context
switch is unnecessary when an attempt is made to access an object that belongs to an applet instance
that resides in the same context. Context switches only occur during invocation of and return from
certain methods, as well as during exception exits from those methods (see Section 6.2.8 Class and
Object Access Behavior).
Further details of contexts and context switching are provided in later sections of this chapter.
Following are the combined rules of context and object ownership within the firewall:
• Every applet instance belongs to a context. All applet instances from the same CAP File belong
to the same context.
• Every object is owned by an applet instance (or the Java Card RE). An applet instance is
identified by its AID. When executing in an instance method of an object (or a static class
method called from within), the object's owner must be in the currently active context.
For example, assume that applets A and B are in the same CAP File, and applet C is in another CAP File. A
and B therefore belong to the same context: 1. C belongs to a different context: 2. For an illustration of
this situation, see Figure 6-2: Context Switching and Object Access.
If context 1 is the currently active context, and a method m1 in an object owned by applet A is invoked,
no context switch occurs. If method m1 invokes a method m2 in an object owned by applet B, again no
context switch occurs (in spite of the object "owner" change), and no firewall restrictions apply.
• When the m1 method in the object owned by applet A calls the method m2 in the object owned
by applet B, the context does not change but the owner of the object does change. If the
JCSystem.getAID method is called from method m2 within context 1, the AID of applet B is
returned.
• When method m2 calls method m0 in an object owned by applet C, applet B is the owner of the
object when the context switches from 1 to 2. Therefore, if the JCSystem.getAID method is
called from method m0 within context 2, the AID of applet C shall be returned. If the
JCSystem.getPreviousContextAID method is called, the AID of applet B shall be
returned.
• When the JCSystem.getAID method is called from method m2 after the return from
method m0 in context 2, the AID of applet B is returned. However, if the
JCSystem.getPreviousContextAID method is called, the AID of the applet which called
into context 1 (or null if Java Card RE) is returned and not the AID of applet C.
• An object is accessed when one of the following bytecodes is executed using the object's
reference:
<T> refers to the various types of array bytecodes, such as baload and sastore.
• This list includes any special or optimized forms of these bytecodes implemented in the Java
Card VM, such as getfield_b and getfield_s_this.
Transient objects of CLEAR_ON_DESELECT type can only be created or accessed when the currently
active context is the context of the currently selected applet. If any of the makeTransient factory
methods of JCSystem class are called to create a CLEAR_ON_DESELECT type transient object when
the currently active context is not the context of the currently selected applet (even if the attempting
context is that of an active applet instance on another logical channel, see Section 4.1 Logical Channels
Overview), the method shall throw a java.lang.SystemException with reason code of
ILLEGAL_TRANSIENT. If an attempt is made to access a transient object of CLEAR_ON_DESELECT
type when the currently active context is not the context of the currently selected applet (even if the
attempting context is that of an active applet instance on another logical channel), the Java Card RE shall
throw a java.lang.SecurityException because the corresponding memory segment may not
be mapped (see 4.1 Logical Channels Overview, footnote 2). However, accessing the elements of a view
on a transient array of CLEAR_ON_DESELECT type is allowed because the access to the elements is
verified at the creation of the view and the elements remain accessible for the lifetime of the view.
Applets that are part of the same CAP file share the same context. Every applet instance from a CAP file
shares all its object instances with all other instances from the same CAP file. This includes transient
objects of both CLEAR_ON_RESET type and CLEAR_ON_DESELECT type owned by these applet
instances.
The transient objects of CLEAR_ON_DESELECT type owned by any applet instance in the same
context shall be accessible when any of the applet instances is the currently selected applet.
Public static fields and public static methods are accessible from any context: Static methods execute in
the same context as their caller.
Objects referenced in static fields are just regular objects. They are owned by whoever created them
and standard firewall access rules apply. If it is necessary to share them across multiple contexts, these
objects need to be Shareable Interface Objects (SIOs), see Section 6.2.4 Shareable Interfaces.
Of course, the conventional Java technology protections are still enforced for static fields and methods.
In addition, when applets are installed, the Installer verifies that each attempt to link to an external
static field or method is permitted. Installation and specifics about linkage are beyond the scope of this
specification.
These mechanisms are provided in the Java Card API and are discussed in the following sections:
In the Java Card API, this is accomplished using Java Card RE Entry Point Objects. These are objects
owned by the Java Card RE context, but they are flagged as containing entry point methods.
The firewall protects these objects from access by applets. The entry point designation allows the
methods of these objects to be invoked from any context. When that occurs, a context switch to the
Java Card RE context is performed. These methods are the gateways through which applets request
Following are the two categories of Java Card RE Entry Point Objects:
Like all Java Card RE Entry Point Objects, methods of temporary Java Card RE Entry Point Objects
can be invoked from any context. Since they are temporary (see 5.2 Temporary Objects),
references to these objects cannot be stored in class variables, instance variables or array
components. The Java Card RE detects and restricts attempts to store references to these
objects as part of the firewall functionality to prevent unauthorized reuse.
The APDU object and all Java Card RE owned exception objects are examples of temporary Java
Card RE Entry Point Objects.
Like all Java Card RE Entry Point Objects, methods of permanent Java Card RE Entry Point
Objects can be invoked from any context. Additionally, references to these objects can be stored
and freely re-used.
Java Card RE owned AID instances are examples of permanent Java Card RE Entry Point Objects.
Note: Only the methods of these objects are accessible through the firewall. The fields of these
objects are still protected by the firewall and can only be accessed by the Java Card RE context.
Only the Java Card RE itself can designate Entry Point Objects and whether they are temporary
or permanent. Java Card RE implementers are responsible for implementing the mechanism by
which Java Card RE Entry Point Objects are designated and how they become temporary or
permanent.
All global arrays are temporary global array objects. These objects are owned by the Java Card RE
context, but can be accessed from any context. Since they are temporary (see 5.2 Temporary Objects),
references to these objects cannot be stored in class variables, instance variables or array components.
The Java Card RE detects and restricts attempts to store references to these objects as part of the
firewall functionality to prevent unauthorized reuse. An attempt to store a reference to a Global Array
object results in a SecurityException exception.
For added security, only arrays can be designated as global. The Java Card specification introduced the
JCSystem.makeGlobalArray() API method (since 3.0.4), which an applet may use to create a
global array. These arrays are intended for use during inter-process communication.
Apart from the user created arrays, the only global arrays required in the Java Card API are the APDU
buffer and the byte array input parameter (bArray) to the applet's install method.
Note: Because of the global status of the APDU buffer, the previous content of this array must
be made unavailable before another applet becomes the currently selected applet. This is to
prevent an applet's potentially sensitive data from being "leaked" to another applet via the
global APDU buffer. The APDU buffer can be accessed from a shared interface object context
and is suitable for passing data across different contexts. The applet is responsible for protecting
secret data that may be accessed from the APDU buffer.
• An array view gives control over the exact subset of elements that are shared, without the need
to perform a defensive copy of the data and to resynchronize result when required
• It allows to precisely specify the context that will own the view by providing the Shareable
Interface Object that will receive the view.
• It also gives control on the access rights granted to the other application and specify if the
elements can be read or updated.
• It finally prevents the application receiving the reference to the array view from storing it for
further reuse.
Again, because it is the "system" context, the Java Card RE context can access fields and components of
any object on the card including CLEAR_ON_DESELECT transient objects owned by the currently
selected applet.
Note: The Java Card RE can access both methods and fields of X. Method access is the
mechanism by which the Java Card RE enters the context of an applet. Although the Java Card
RE could invoke any method through the firewall, it shall only invoke the select, process,
deselect, and getShareableInterfaceObject (see Section 6.2.7.1
Applet.getShareableInterfaceObject(AID, byte) Method) methods defined in
the Applet class, and methods on the objects passed to the API as parameters.
The Java Card RE context is the currently active context when the VM begins running after a card reset.
The Java Card RE context is the "root" context and is always either the currently active context or the
bottom context saved on the stack.
To the owning context, the SIO is a normal object whose fields and methods can be accessed. To any
other context, the SIO is an instance of the shareable interface, and only the methods defined in the
shareable interface are accessible. All other fields and methods of the SIO are protected by the firewall.
Shareable interfaces provide a secure mechanism for inter-applet communication, as described in the
following sections.
In this sequence, applet B initiates communication with applet A using the special system method in the
JCSystem class to request a Shareable Interface Object from applet A. Once this communication is
established, applet B can obtain other Shareable Interface Objects from applet A using normal
parameter passing and return mechanisms. It can also continue to use the special JCSystem method
described above to obtain other Shareable Interface Objects.
If the applet calls getPreviousContextAID from a method that may be accessed either from
within the applet itself or when accessed via a shareable interface from an external applet, it shall check
for null return before performing caller AID authentication.
The Shareable interface serves to identify all shared objects. Any object that needs to be shared
through the applet firewall shall directly or indirectly implement this interface. Only those methods
specified in a shareable interface are available through the firewall.
Implementation classes can implement any number of shareable interfaces and can extend other
shareable implementation classes.
Like any Java platform interface, a shareable interface simply defines a set of service methods. A service
provider class declares that it "implements" the shareable interface and provides implementations for
each of the service methods of the interface. A service client class accesses the services by obtaining an
object reference, casting it to the shareable interface type, and invoking the service methods of the
interface.
The shareable interfaces within the Java Card technology shall have the following properties:
• When a method in a shareable interface is invoked, a context switch occurs to the context of the
object's owner.
• When the method exits, the context of the caller is restored.
• Exception handling is enhanced so that the currently active context is correctly restored during
the stack frame unwinding that occurs as an exception is thrown.
The default behavior shall return null, which indicates that an applet does not participate in inter-
applet communication.
A server applet that is intended to be invoked from another applet needs to override this method. This
method should examine the clientAID and the parameter. If the clientAID is not one of the
expected AIDs, the method should return null. Similarly, if the parameter is not recognized or if it is
not allowed for the clientAID, the method also should return null. Otherwise, the applet should
return an SIO of the shareable interface type that the client has requested.
The server applet need not respond with the same SIO to all clients. The server can support multiple
types of shared interfaces for different purposes and use clientAID and parameter to determine
which kind of SIO to return to the client.
1. The Java Card RE searches its internal applet table which lists all successfully installed applets on
the card for one with serverAID. If not found, null is returned.
2. If the server applet instance is not a multiselectable applet instance and is currently active on
another logical channel, a SecurityException is thrown. See Section 4.3 Multiselectable
Applets.
3. The Java Card RE invokes this applet's getShareableInterfaceObject method, passing
the clientAID of the caller and the parameter.
4. A context switch occurs to the server applet, and its implementation of
getShareableInterfaceObject proceeds as described in the previous section. The
server applet returns a SIO (or null).
5. getAppletShareableInterfaceObject returns the same SIO (or null) to its caller.
getstatic, putstatic
An object is accessed when one of the following Java programming language bytecodes is executed
using the object's reference:
<T> refers to the various types of array bytecodes, such as baload, sastore, etc.
This list also includes any special or optimized forms of these bytecodes that can be implemented in the
Java Card VM, such as getfield_b and getfield_s_this.
Prior to performing the work of the bytecode as specified by the Java VM, the Java Card VM will perform
an access check on the referenced object. If access is denied, a java.lang.SecurityException
is thrown.
The access checks performed by the Java Card VM depend on the type and owner of the referenced
object, the bytecode, and the currently active context. They are described in the following sections.
getstatic, putstatic
getfield, putfield
invokevirtual
• If the object is owned by an applet in the currently active context, access is allowed.
• Otherwise, if the object is designated a Java Card RE Entry Point Object, access is allowed.
Context is switched to the object owner's context (shall be Java Card RE).
• Otherwise, if Java Card RE is the currently active context, access is allowed. Context is switched
to the object owner's context.
• Otherwise, access is denied.
5
This does not apply to the views on a transient array of CLEAR_ON_DESELECT type. See 6.1.5 Transient Objects
and Contexts for more details.
invokeinterface
• If the object is owned by an applet in the currently active context, access is allowed.
• Otherwise, if the object is designated a Java Card RE Entry Point Object, access is allowed.
Context is switched to the object owner's context (shall be Java Card RE).
• Otherwise, if the Java Card RE is the currently active context, access is allowed. Context is
switched to the object owner's context.
• Otherwise, access is denied.
invokeinterface
• If the object is owned by an applet in the currently active context, access is allowed.
• Otherwise, if the object is owned by a non-multiselectable applet instance that is not in the
context of the currently selected applet instance, and that is active on another logical channel,
access is denied. See Section 4.3 Multiselectable Applets.
• Otherwise, if the object's class implements a Shareable interface, and if the interface being
invoked extends the Shareable interface, access is allowed. Context is switched to the object
owner's context.
• Otherwise, if the Java Card RE is the currently active context, access is allowed. Context is
switched to the object owner's context.
• Otherwise, access is denied.
athrow
• If the object is owned by an applet in the currently active context, access is allowed.
• Otherwise, if the object is designated a Java Card RE Entry Point Object, access is allowed.
• Otherwise, if the Java Card RE is the currently active context, access is allowed.
• Otherwise, access is denied.
checkcast, instanceof
• If the object is owned by an applet in the currently active context, access is allowed.
• Otherwise, if the object is designated a Java Card RE Entry Point Object, access is allowed.
checkcast, instanceof
• If the object is owned by an applet in the currently active context, access is allowed.
• Otherwise, if the object is designated a Java Card RE Entry Point Object, access is allowed.
• Otherwise, if the Java Card RE is the currently active context, access is allowed.
• Otherwise, access is denied.
checkcast, instanceof
• If the object is owned by an applet in the currently active context, access is allowed.
• Otherwise, if the object's class implements a Shareable interface, and if the object is being
cast into (checkcast) or is being verified as being an instance of (instanceof) an interface
that extends the Shareable interface, access is allowed.
• Otherwise, if the Java Card RE is the currently active context, access is allowed.
• Otherwise, access is denied.
Bytecodes:
invokevirtual
• If the array is a transient array6 of CLEAR_ON_DESELECT type owned by an applet which is not in
the context of the currently selected applet, access is denied.
• If the array is owned by an applet in the currently active context, access is allowed.
• Otherwise, if the array is designated a global array, access is allowed. Context is switched to the
array owner's context (Java Card RE context).
• Otherwise, if Java Card RE is the currently active context, access is allowed. Context is switched
to the array owner's context.
• Otherwise, access is denied.
6
This does not apply to the views on a transient array of CLEAR_ON_DESELECT type. See 6.1.5 Transient Objects
and Contexts for more details.
A transaction is a logical set of updates of persistent data. For example, transferring some amount of
money from one account to another is a banking transaction. It is important for transactions to be
atomic: Either all of the data fields are updated, or none are. The Java Card RE provides robust support
for atomic transactions, so that card data is restored to its original pre-transaction state if the
transaction does not complete normally. This mechanism protects against events such as power loss in
the middle of a transaction, and against program errors that might cause data corruption should all
steps of a transaction not complete normally.
7.1 Atomicity
Atomicity defines how the card handles the contents of persistent storage after a stop, failure, or fatal
exception during an update of a single object field or single class field or single array component. If
power is lost during the update, the applet developer shall be able to rely on what the field or array
component contains when power is restored.
The Java Card platform guarantees that any update to a single persistent object field or single class field
will be atomic. In addition, the Java Card platform provides single component level atomicity for
persistent arrays. That is, if the smart card loses power during the update of a data element (field in an
object, class or component of an array) that shall be preserved across CAD sessions, that data element
shall be restored to its previous value. Some methods also guarantee atomicity for block updates of
multiple data elements. For example, the atomicity of the Util.arrayCopy method guarantees that
either all bytes are correctly copied or else the destination array is restored to its previous byte values.
An applet might not require atomicity for array updates. The Util.arrayCopyNonAtomic method
is provided for this purpose. It does not use the transaction commit buffer even when called with a
transaction in progress.
7.2 Transactions
An applet might need to atomically update several different fields or array components in several
different objects. Either all updates take place correctly and consistently, or else all fields or components
are restored to their previous values. The Java Card platform supports a transactional model in which an
applet can designate the beginning of an atomic set of updates with a call to the
JCSystem.beginTransaction method. Each object update after this point is conditionally
updated. The field or array component appears to be updated (reading the field or array component
back yields its latest conditional value) but the update is not yet committed. When the applet calls
This action is performed automatically by the Java Card RE when it reinitializes the card after recovering
from the power loss, reset, or failure. The Java Card RE determines which of those objects (if any) were
conditionally updated, and restores them.
Note: Object space used by instances created during the transaction that failed due to power
loss or card reset can be recovered by the Java Card RE.
If the Java Card RE catches an uncaught exception from the select, deselect, process,
install, or uninstall methods when an applet initiated transaction is in progress, the Java Card
RE automatically aborts the transaction.
Note: The abortion of a transaction by the Java Card RE during the process method results in
uncaught exception processing. The response status is determined as described in Section 3.3
process Method.
Alternatively, programmatic abortion after creating objects within the transaction can be deemed to be
a programming error. When this occurs, the Java Card RE may, to ensure the security of the card and to
avoid heap space loss, lock up the card session to force tear or reset processing.
The Remote Method Invocation Service is an optional component of the Java Card Platform. The service
is available when the javacard.framework.service package is present on the card.
Java Card platform Remote Method Invocation (Java Card RMI) is a subset of the Java platform Remote
Method Invocation (RMI) system. It provides a mechanism for a client application running on the CAD
platform to invoke a method on a remote object on the card. The on-card transport layer for Java Card
RMI is provided in the package javacard.framework.service by the class RMIService. It is
designed as a service requested by the Java Card RMI-based applet when it is the currently selected
applet.
The Java Card RMI message is encapsulated within the APDU object passed into the RMIService
methods.
Java Card RMI imposes additional constraints on the definition of remote methods. These constraints
are a result of the Java Card platform language subset and other feature limitations.
The return value of a remote method must only be one of the following types:
All parameters, including array parameters, are always transmitted by value during the remote method
invocation. The return values from a remote method are transmitted by value for primitive types and
arrays. Return values that are remote object references are transmitted by reference using a remote
object reference descriptor.
8.1.1.2 Exceptions
Java Card RMI uses the following simplified model for returning exceptions thrown by remote methods:
• When an exception defined in the Java Card API is thrown by a remote method, the exact
exception type and the embedded reason code is transmitted to the client application. In
essence, the exception object is transmitted by value.
• When an exception not defined in the Java Card API is thrown by a remote method, the
"closest" superclass exception type from the API and the embedded reason code is transmitted
to the client application. In this case, the "closest" API defined superclass exception object is
transmitted by value. The client application can distinguish an inexact exception from an exact
one.
• CAD client application remote objects cannot be passed as arguments to remote methods.
• Card remote objects cannot be passed as arguments to remote methods.
• Applets on the card cannot invoke remote methods on the CAD client.
• Method argument data and return values, along with the Java Card RMI protocol overhead,
must fit within the size constraints of an APDU command and APDU response, respectively.
• Get the initial remote object reference for the Java Card RMI based applet. The initial remote
object reference is the seed remote object that the CAD client application needs to begin
remote method invocations.
• Send a remote method invocation request to the card.
To ensure that the protocol is compatible with all applications, the SELECT FILE command is used for
getting the initial reference. The response to the SELECT FILE command allows the remote method
invocation command itself to be customized by the applet.
• Direct selection by DF Name, that is, selection by AID. This is the normal option used to select
all applet instances in the Java Card platform.
• Return FCI (File Control Information - ISO7816-4), optional template. This is an additional
option that indicates that the applet is expected to return FCI information.
In addition, an alternate RFU variant of the Return FCI option is required to configure the
RMIService for an alternate Java Card RMI protocol format. For more details see Section
8.4.1 SELECT FILE Command.
The answer to this command is a constructed TLV (tag-length-value) data structure (ISO 7816-6) that
includes the following information:
• The byte to be used as instruction byte (INS) for subsequent invocation commands.
• The initial remote object reference descriptor. The descriptor includes the remote object
identifier and information to identify the associated class.
• The remote object identifier. This identifier is used to uniquely identify the object on the card.
• The invoked method identifier. This designator uniquely identifies the remote method within
the remote object class or superclass.
• The values of the arguments. These values are raw values for primitive data types, and for
arrays, a length followed by the values.
The response to the invocation request may include one of the following items:
• A remote object identifier that identifies the remote object on the card.
• A remote object reference descriptor that describes the remote object on the card for the CAD
client.
• A method identifier that identifies the remote method on the card.
This section uses a C-like structure notation similar to that used in the Virtual Machine Specification,
Java Card Platform, Version 3.1, Classic Edition.
remote_ref_descriptor {
union {
ref_null remote_ref_null
remote_ref_with_class remote_ref_c
remote_ref_with_interfaces remote_ref_i
}
}
Note: Even though this structure uses the C-like "union" notation, the lengths of the alternate
representations within the union do not use any padding to normalize their lengths.
ref_null {
u2 remote_ref_id = 0xFFFF
}
The remote_ref_id item must be the reserved value 0xFFFF.
remote_ref_with_class is the definition of a remote object reference using the class name and
uses the following format:
remote_ref_with_class {
u2 remote_ref_id != 0xFFFF
u1 hash_modifier_length
u1 hash_modifier[ hash_modifier_length ]
u1 pkg_name_length
u1 package_name[ pkg_name_length ]
The pkg_name_length item is the number of bytes in the package_name item to represent the
name of the package in UTF-8 string notation. The value of this item must be non-zero.
The package_name item is the variable length representation of the fully qualified name of the
package which contains the remote class in UTF-8 string notation. The fully qualified name of the
package represented here uses the internal form wherein the ASCII periods (.) that normally separate
the identifiers that make up the fully qualified name are replaced by ASCII forward slashes (/). For
example, the internal form of the normally fully qualified package name of the package java.rmi is
java/rmi.
The class_name_length item is the number of bytes in the class_name item to represent the
name of the remote class in UTF-8 string notation. The value of this item must be non-zero.
The class_name item is the variable length representation of the name of the implementation class
(or superclass) of the remote object in UTF-8 string notation. The class referenced in the remote object
reference descriptor must directly implement a remote interface. If the implementation class of the
remote object does not directly implement a remote interface, the class name of the "closest"
superclass of the implementation class which directly implements a remote interface must be used.
remote_ref_with_interfaces {
u2 remote_ref_id != 0xFFFF
u1 hash_modifier_length
u1 hash_modifier[ hash_modifier_length ]
u1 remote_interface_count
rem_interface_def remote_interfaces[remote_interface_count]
}
The definition of the remote_ref_id, the hash_modifier_length and the hash_modifier
item are the same as that described earlier in the remote_ref_with_class structure.
rem_interface_def {
u1 pkg_name_length
u1 package_name[ pkg_name_length ]
u1 interface_name_length
u1 interface_name[ interface_name_length ]
}
The items in the rem_interface_def structure are as follows:
The pkg_name_length item is the number of bytes used in the package_name item to represent
the name of the package in UTF-8 string notation. If the value of this item is 0, it indicates that the
package name of the previous remote_interfaces item must be used instead. The value of this
item in remote_interfaces[0] must not be 0.
The package_name item is the pkg_name_length byte length representation of the fully qualified
name of the package which contains the remote interface in UTF-8 string notation. The fully qualified
name of the package represented here uses the internal form wherein the ASCII periods (.) that
normally separate the identifiers that make up the fully qualified name are replaced by ASCII forward
slashes (/). For example, the internal form of the normally fully qualified package name of the package
java.rmi is java/rmi.
The interface_name item is the variable length representation of the name of the remote interface
implemented by the remote object in UTF-8 string notation.
u2 method_id
The method_id is a unique 16-bit hashcode identifier of the remote method within the remote class.
This 16-bit hashcode consists of the first two bytes of the SHA-1 message digest function performed on a
class specific hash modifier string, followed by the name of the method, followed by the method
descriptor representation in UTF-8 format. Representation of a method descriptor is the same as that
described in The Java Virtual Machine Specification (Section 4.3.3).
void_param {
}
boolean_param {
u1 boolean_value
}
byte_param {
s1 byte_value
}
short_param {
s2 short_value
}
int_param {
s4 int_value
}
The boolean_value field may only take the values 0 (for false) and 1 (for true). All the other
fields can take any value in their range.
null_array_param {
u1 length = 0xFF
}
boolean_array_param {
u1 length != 0xFF
u1 boolean_value[length]
}
byte_array_param {
u1 length != 0xFF
s1 byte_value[length]
}
short_array_param {
u1 length != 0xFF
s2 short_value[length]
}
int_array_param {
u1 length != 0xFF
s4 int_value[length]
return_response {
u1 tag
u1[] value
}
The return value using the return_response encoding is always followed by a good completion
status code of 0x9000 in the response APDU.
normal_param_response {
u1 normal_tag = 0x81
param normal_value
}
The null_array_param format described in Section 8.3.4 Parameter Encoding is not used to
represent a null array reference. Instead, a null object reference, as well as a null array reference,
shares the following common format:
normal_null_response {
u1 normal_tag = 0x81
ref_null null_array_or_ref
}
In addition, a remote object reference descriptor type is also encapsulated using the normal response
format as follows:
normal_ref_response {
u1 normal_tag = 0x81
remote_ref_descriptor remote_ref
}
exception_response {
u1 exception_tag = 0x82
u1 exception_type
s2 reason
}
Following are the values for the exception_type item:
java.lang.Throwable = 0x00
java.lang.ArithmeticException = 0x01
java.lang.ArrayIndexOutOfBoundsException = 0x02
java.lang.ArrayStoreException = 0x03
java.lang.ClassCastException = 0x04
java.lang.Exception = 0x05
java.lang.IndexOutOfBoundsException = 0x06
java.lang.NegativeArraySizeException = 0x07
java.lang.NullPointerException = 0x08
java.lang.RuntimeException = 0x09
java.lang.SecurityException = 0x0A
java.io.IOException = 0x0B
java.rmi.RemoteException = 0x0C
javacard.framework.APDUException = 0x20
javacard.framework.CardException = 0x21
javacard.framework.CardRuntimeException = 0x22
javacard.framework.ISOException = 0x23
javacard.framework.PINException = 0x24
javacard.framework.SystemException = 0x25
javacard.framework.TransactionException = 0x26
javacard.framework.UserException = 0x27
javacard.security.CryptoException = 0x30
javacard.framework.service.ServiceException = 0x40
javacardx.biometry.BioException = 0x50
javacardx.external.ExternalException = 0x60
javacardx.framework.tlv.TLVException = 0x70
javacardx.framework.util.UtilException = 0x80
Any API defined exception not listed here is encoded using 0x82 for the exception_tag and by
looking up in its class hierarchy until reaching one the type listed above and using the corresponding
exception_type.
exception_subclass_response {
u1 exception_subclass_tag = 0x83
u1 exception_type
s2 reason
}
error_response {
u1 error_tag = 0x99
s2 error_detail
}
Following are the values of the error_detail item:
• The Remote Object Identifier is invalid or ineligible for Java Card RMI = 0x0001
• The Remote Method could not be identified = 0x0002
• The Remote Method signature did not match the parameter format = 0x0003
• Insufficient resources available to unmarshall parameters = 0x0004
• Insufficient resources available to marshall response = 0x0005
• Java Card Remote Method Invocation protocol error = 0x0006
• Internal Error occurred = 0xFFFF
Note: Java Card RMI message protocol supports only the 1 byte encodings of the Lc and Le
values of the APDU data length.
Note: (%b) indicates binary notation using bit numbering as in the ISO 7816 specification. The
most significant bit is b8. The least significant bit is b1. An "x" notation represents a "don't care".
CLA %b000000cc The cc in bits (b2,b1) denote the origin logical channels number in the
range 0-3.
or
The dddd in bits (b4-b1) denote the origin logical channel number 4-19
%b0100dddd
using 0 origin notation.
See Figure 4-1: Logical Channels for Distinct Applets for CLA field
encoding format.
INS 0xA4 SELECT FILE
P1 0x04 Select by AID
P2 %b000x00xx Return FCI information. The bits (b2,b1) are used for partial selection, if
supported. If bit b5 is 1, the remote reference descriptor uses the
remote_ref_with_interfaces format, otherwise it uses the alternate
remote_ref_with_class format.
Lc Lc Length of the AID
Data AID AID of the applet to be selected (between 5 and 16 bytes)
Following is the format of the response. Note that the applet may extend the format to include
additional information, if necessary before sending the response back to the CAD. The additional
information must retain the TLV format and must not introduce any additional information under the
jc_rmi_data_tag.
select_response {
u1 fci_tag = 0x6F
u1 fci_length
u1 application_data_tag = 0x6E
u1 application_data_length
u1 jc_rmi_data_tag = 0x5E
u1 jc_rmi_data_length
u2 version = 0x0202
u1 invoke_ins
union {
normal_ref_response normal_initial_ref
normal_null_response null_initial_ref
error_response initial_ref_error
} initial_ref
}
The response data includes invoke_ins, the instruction byte to use in the method invocation
command. It also includes initial_ref, the initial remote object reference descriptor. The
initial_ref item corresponds to the remote object designated as the initial reference to the
RMIService instance during construction. The initial_ref item can be a
normal_ref_response item described in Section 8.3.5.1 Normal Response Encoding or a null
representation using a normal_null_response item described in that same section, if the initial
remote reference object is not enabled for remote access. Also, note that if an error occurs during the
marshalling of the initial remote reference descriptor, an error response is returned in initial_ref
instead of using the error_response item format described in Section 8.3.5.3 Error Response
Encoding.
Note: Even though the select_response structure uses the C-like "union" notation, the
lengths of the alternate representations within the union do not use any padding to normalize
their lengths.
The format of the remote_ref_descriptor to be used in this response as well as all subsequent
responses (remote_ref_with_classor remote_ref_with_interfaces) is determined by
the value of the P2 byte of the SELECT FILE command.
Note: Only the RMIService instance that processes the SELECT FILE command sets (or
changes) the format of the remote object reference descriptor based on the value of the P2
byte. Once set or changed, the RMIService instance uses only that format in all Java Card
RMI responses it generates.
See Figure 4-1: Logical Channels for Distinct Applets, for CLA field
encoding formats.
invoke_data {
u2 object_id
u2 method_id
param parameters[]
}
The object_id is the remote object identifier of the object whose remote method is to be invoked.
The method to be invoked is specified by the method_id item, and each parameter is specified by a
param structure.
The response format uses the return_response structure as described in Section 8.3.5 Return Value
Encoding.
8.5 RMIServiceClass
The RMIService class implements the Java Card RMI protocol and processes the RMI access
commands described earlier: SELECT FILE and INVOKE. It performs the function of the transport layer for
Java Card RMI commands on the card.
The RMIService object maintains a list of remote objects that have been returned during the current
applet selection session. It enforces the following rules for the lifetime of the remote object references:
• A remote reference is valid only when the INVOKE command is processed by the RMIService
instance that returned the reference.
• A remote reference is valid with any applet instance in the package of the applet instance that
returned it.
• A remote reference is valid as long as at least one applet instance within the same package has
been active at all times since the point in time when the remote reference was returned.
• A remote object cannot be garbage collected if referenced by a valid remote reference.
In addition, a remote object reference descriptor of an object must only be returned from the card if it is
exported. See the class javacard.framework.service.CardRemoteObject. Otherwise, an
exception is thrown. See the class javacard.framework.service.RMIService.
When called with a SELECT FILE command with format described in Section 8.4.1 SELECT FILE Command,
this method builds a response APDU as described in that section.
When called with an INVOKE command with the format described in Section 8.4.2 INVOKE Command,
this method must call the specified remote method of the identified remote object with the specified
parameters. It must catch all exceptions thrown by the remote method. When an exception is caught or
the remote method returns, this method must build a response APDU in the format described in Section
8.4.2 INVOKE Command.
Prior to invoking the remote method, the following errors must be detected and must result in an error
response in the format described in Section 8.3.5.3 Error Response Encoding:
In addition, upon return from the remote method, the following errors must be detected and must
result in an error response in the format described in Section 8.3.5.3 Error Response Encoding:
• There is insufficient space to allocate the array response from the remote method. The
implementation must support an APDU buffer of at least 133 bytes.
• A remote object is being returned, and its associated remote object identifier was not previously
returned during the current selection session, and there is insufficient space to add the remote
object identifier to the session remote object identifier list. The implementation must support at
least eight remote object identifiers during a selection session.
In addition, the object access firewall rules must be enforced in a manner similar to that of the
invokevirtual instruction (Section 6.2.8.4 Accessing Class Instance Object Methods) by this method
when a remote method is invoked. Only methods of a remote object owned by the context of the
currently selected applet may be invoked.
• They are owned by the Java Card RE, but they can be freely accessed from all contexts.
• They are temporary objects and cannot be stored in any object.
• They are not subject to transactions.
The implementation may choose to maintain the data portion of these global array objects used for
remote method parameters in the APDU buffer itself.
The topics in this chapter complement the requirements specified in the Application Programming
Interface, Java Card Platform, Version 3.1, Classic Edition.
Unless explicitly called out in the API descriptions, updates to internal implementation state within the
API objects must be conditional. Internal state updates must participate in any ongoing transaction.
The Java Card RE may support T=0 or T=1 transport protocols or both.
When the no chaining mode is used (that is, after the invocation of the setOutgoingNoChaining
method), calls to the waitExtension method shall throw an APDUException with reason code
ILLEGAL_USE.
9.4.1.1.1 Notation
This notation scheme is used in Section 9.4.1.1.2 ISO 7816-4 CASE 2 and Section 9.4.1.1.3 ISO 7816-4
CASE 4.
<INS> = the protocol byte equal to the incoming header INS byte, which indicates that all data bytes will
be transferred next.
<~INS> = the protocol byte that is the complement of the incoming header INS byte, which indicates
that 1 data byte will be transferred next.
Ne == Nr
1. The card sends Nr bytes of output data using the standard T=0 <INS> or <~INS> procedure byte
mechanism.
2. The card sends <SW1,SW2> completion status on completion of the Applet.process
method.
Nr < Ne
Nr > Ne
1. The card sends Ne bytes of output data using the standard T=0 <INS> or <~INS> procedure byte
mechanism.
2. The card sends <0x61,(Nr-Ne)> completion status bytes.
3. The CAD sends GET RESPONSE command with new Ne <= Nr.
4. The card sends (new) Ne bytes of output data using the standard T=0 <INS> or <~INS> procedure
byte mechanism.
5. Repeat steps 2-4 as necessary to send the remaining output data bytes (Nr) as required.
6. The card sends <SW1,SW2> completion status on completion of the Applet.process
method.
In all cases of constrained outbound transfers with no chaining, if the applet aborts early, and sends less
than Nr bytes, zeros shall be sent instead to fill out the length of the transfer expected by the CAD.
If the applet aborts early and sends less than the applet response length (Nr) set via
setOutgoingLength method, only the data bytes written via the send methods of the APDU class
are sent to the CAD.
Note: The waitExtension method may be invoked by the applet at any time. The
waitExtension method shall request an additional work waiting time (ISO/IEC 7816-3:2004)
using the 0x60 procedure byte.
At any time, when the T=0 output transfer protocol is in use, and the APDU class is awaiting a command
reissue from the CAD in reaction to a response status of <0x6C, xx> from the card, if the CAD sends in a
different command on the same origin logical channel, or a command on a different origin logical
channel, the sendBytes or the sendBytesLong methods shall throw an APDUException with
reason code NO_T0_REISSUE.
9.4.2.1.1 Notation
Ne = CAD expected length.
The transport protocol sequence shall not use block chaining. Specifically, the M-bit (more data bit) shall
not be set in the PCB of the I-blocks during the transfers (ISO/IEC 7816-3:2004). The entire outgoing data
(Nr bytes) shall be transferred in one I-block.
If the applet aborts early and sends less than Nr bytes, zeros shall be sent instead to complete the
remaining length of the block.
If the applet aborts early and sends less than the applet response length (Nr) set via
setOutgoingLength method, only the data bytes written via the send methods of the APDU class
are sent to the CAD.
Note: The waitExtension method may be invoked by the applet at any time. The
waitExtension method shall send an S-block command with WTX request of INF units,
which is equivalent to a request of 1 additional work waiting time in T=0 mode. See ISO/IEC
7816-3:2004.
Calls to receiveBytes, sendBytes or sendBytesLong methods from this point on shall result in
an APDUException with reason code ILLEGAL_USE. If an ISOException is thrown by the applet
after the T1_IFD_ABORT exception is thrown, the Java Card RE shall discard the response status in its
If the implementation supports extended length APDU formats, extended length semantics shall be
enabled at the APDU class methods only if the currently selected applet implements the
javacardx.apdu.ExtendedLength interface. If the implementation supports extended length
APDU formats, when the T=0 APDU transfer protocol is in use, and receives an ENVELOPE command, but
the currently selected applet on the origin logical channel does not implement the ExtendedLength
interface, the ENVELOPE command must be forwarded to the currently selected applet on the origin
logical channel. If the implementation supports extended length APDU formats, when the T=1 APDU
transfer protocol is in use, and receives an APDU command that requires extended length semantics at
the APDU class methods, but the currently selected applet does not implement the ExtendedLength
tagging interface, the Java Card RE shall respond to the CAD with the error response status
SW_WRONG_LENGTH.
An implementation which supports the optional javacardx.apdu package shall support APDUs with
extended length up to 32767.
When the T=0 transfer protocol is in use, a Case 3E and 4E APDU is enclosed within an ENVELOPE (ISO
Inter-industry CLA, INS=0xC2) command as described in ISO 7816-4:2013 Specification. The ENVELOPE
As shown in the table, the header data at offset 4, 5 and 6 of the APDU buffer contains a 3-byte Lc value
as defined in ISO 7816-4. The 3-byte length may encode a number from 1 to 32767.
When the T=0 transfer protocol is in use for a Case 2E (P3=0) or Case 4 command, this method returns
32767.
When the T=1 transfer protocol is in use for a Case 2E or Case 4E command and Le is set to 0x0000 or is
greater than 32767 , this method returns 32767.
The platform behavior for an ill-formed or inconsistent message might differ depending if the error
happened at the physical layer, the data link layer, or the transport layer of the communication stack.
Some of these issues might even be caught before reaching the device and goes beyond the scope of
this specification. Also, depending on the transport protocol used (T=0 or block-oriented protocol like
T=1) and the configuration of the communication stack (e.g. support for extended APDU, reception
buffer size, block size), it is neither always possible nor efficient for the APDU class to receive data at
once and perform consistency checks.
Consequently, it is the responsibility of the application to check the consistency of commands received,
verify the conditions of execution and react with the appropriate actions to ensure its security and state
consistency before sending its response. This includes (but not limited to):
• check the APDU class, instruction code, parameters
• check the consistency of the data length received with the length in the APDU header
• check the format and payload content
• check the response data length expected
The Java Card API is specifically designed for an Applet to perform these checks and react accordingly.
The code snippet below shows an example of interoperable code which makes no assumption on the
protocol used or data size received and checks the consistency of total length received compared to the
length initially indicated in APDU header.
if (remaining > 0) {
// length of data read is inconsistent with lc specified in header:
// do cleanup and return error
...
}
javacard.security.MessageDigest
javacard.security.InitializedMessageDigest
javacard.security.Signature
javacard.security.RandomData
javacard.security.KeyAgreement
javacard.security.Checksum
javacardx.crypto.Cipher
An implementation of the Java Card RE may implement zero or more of the algorithms listed in the
Application Programming Interface, Java Card Platform, Version 3.1, Classic Edition. When an algorithm
that is not implemented is requested, this method shall throw a CryptoException with reason code
NO_SUCH_ALGORITHM.
Implementations of the above classes shall extend the corresponding base class and implement all the
abstract methods. All data allocation associated with the implementation instance shall be performed at
the time of instance construction to ensure that any lack of required resources can be flagged early
during the installation of the applet.
In the same fashion, the constructor for the javacard.security.KeyPair class creates a
KeyPair instance for the specified key type. The Java Card RE may implement zero or more types of
keys. When a key type that is not implemented is requested, the method shall throw a
CryptoException with reason code NO_SUCH_ALGORITHM.
Implementations of key types shall implement the associated interface. All data allocation associated
with the key implementation instance shall be performed at the time of instance construction to ensure
that any lack of required resources can be flagged early during the installation of the applet.
The MessageDigest object uses temporary storage for intermediate results when the update()
method is invoked. This intermediate state need not be preserved across power up and reset. The
object is reset to the state it was in when previously initialized via a call to reset().
The Signature and Cipher objects use temporary storage for intermediate results when the
update() method is invoked. This intermediate state need not be preserved across power up and
reset. The object is reset to the state it was in when previously initialized via a call to init().
• java.rmi - This package contains the base interface and exception class for the Remote
Method Invocation Service.
• javacard.framework.service - This package enables an applet to be designed as an
aggregation of service components. The Remote Method Invocation Service component is
included in this package. If this package in included, the package java.rmi must also be
included.
• javacardx.annotations - This package contains annotations for defining character string
constants.
• javacardx.apdu - This package enables support for advanced APDU mechanisms. This
package must be implemented if and only if the platform supports the extended length APDU
format on at least one APDU transfer protocol. The extended length APDU format is defined in
the ISO 7816-4:2013 Specification.
• javacardx.biometry - This package contains classes and interfaces which can be used to
build a biometric server application.
• javacardx.biometry1toN - This package contains functionality for implementing a 1:N
biometric framework on the Java Card platform. When N=1, this package provides the same
functionality as that of the javacardx.biometry package. The platform must support this
optional package or the optional javacardx.biometry package - or both of them - only if
biometry support is included in the implementation.
This chapter details virtual machine resource failures and security violations.
All other (non-recoverable) virtual machine errors, such as stack overflow, shall result in a virtual
machine error. These conditions shall cause the virtual machine to halt. When such a non-recoverable
virtual machine error occurs, an implementation can optionally require the card to be muted or blocked
from further use.
For security reasons, the Java Card RE implementation may mute the card instead of throwing the
exception object.
Applet installation and deletion on smart cards using Java Card technology is a complex topic. The design
of the Application Programming Interface for the Java Card Platform, Classic Edition is intended to give
Java Card RE implementers as much freedom as possible in their implementations. However, some basic
common specifications are required to allow Java Card applets to be installed and deleted without
knowing the implementation details of a particular installer or deletion manager.
This specification defines the concepts of an Installer and an Applet Deletion Manager and specifies
minimal requirements to achieve interoperability across a wide range of possible Installer
implementations.
The Applet Installer is an optional part of the Runtime Environment Specification, Java Card Platform,
Version 3.1, Classic Edition. An implementation of the Java Card RE does not necessarily need to include
a post-issuance Installer. However, if implemented, the installer is required to support the behavior
specified in this chapter.
If the implementation of the Java Card RE includes a post-issuance Installer, an Applet Deletion Manager
that supports the behavior specified in this chapter is also required.
Section 11.1 The Installer describes CAP file loading and linking. For more information on CAP files, see
the Virtual Machine Specification, Java Card Platform, Version 3.1, Classic Edition. Section 11.2 The
Newly Installed Applet describes applet installation. Even though the loading and linking operations are
described together with the installation operations, there is no requirement that they be performed
together during the same card session for the following reasons:
• Applet CAP files in ROM are preloaded and prelinked at card issuance, but instances of applets
from these CAP files may be installed by the Installer during a card session.
• Applet CAP files may be downloaded and linked by the Installer during one card session, but
applet instances from these CAP files may be installed by the Installer during a different card
session.
• Library CAP files may be preloaded in ROM or downloaded and linked by the Installer during a
card session. There are no applets to install within a library CAP file.
• It receives all APDUs dispatched to this logical channel just like any other active applet.
• Its design specification prescribes the various kinds and formats of APDUs that it expects to
receive along with the semantics of those commands under various preconditions.
• It processes and responds to all APDUs that it receives. Response to incorrect APDUs include an
error condition of some kind.
• When another applet is selected on this logical channel (or when the card is reset or when
power is removed from the card), the Installer becomes deselected and remains suspended until
the next time that it is selected.
Obviously, a Java Card RE implementer could choose to implement the Installer as an applet. If so, then
the Installer might be coded to extend the Applet class and respond to invocations of the select,
process, and deselect methods; and, if necessary, the methods of the
javacard.framework.MultiSelectable interface.
But a Java Card RE implementer could also implement the Installer in other ways, as long as it provides
the SELECTable behavior to the outside world. In this case, the Java Card RE implementer has the
freedom to provide some other mechanism by which APDUs are delivered to the Installer code module.
The model is that the Installer on the card is initiated by an installation program running on the CAD. For
installation to succeed, this CAD installation program shall be able to do the following:
The Application Programming Interface, Java Card Platform, Version 3.1, Classic Edition does not specify
the details of the CAD installation program nor the APDUs passed between it and the Installer.
The Java Card RE shall guarantee that an applet will not be deemed successfully installed in the following
cases:
• The applet CAP file as identified by the CAP AID is already resident on the card.
• The applet CAP file contains an applet with the same Java Card platform name as that of
another applet already resident on the card. The Java Card platform name of an applet
identified by the AID item is described in Chapter 6 of the Virtual Machine Specification, Java
Card Platform, Version 3.1, Classic Edition.
• The applet CAP file requires more memory than is available on the card.
• The applet CAP file references a package that is not resident on the card.
• The applet CAP file references another package already resident on the card, but the version of
the resident package is not binary compatible with the applet CAP file. For more information on
binary compatibility in the Java programming language, see Java Language Specification. Binary
compatibility in Java Card technology is discussed in Chapter 2 of the Virtual Machine
Specification, Java Card Platform, Version 3.1, Classic Edition.
• A class in the applet CAP file is found to contain more package visible virtual methods or
instance fields than the limitations enumerated in Chapter 2 of the Virtual Machine
Specification, Java Card Platform, Version 3.1, Classic Edition.
• A reset or power fail occurs while executing the applet's install method and before
successful return from the Applet.register method (see Section 3.1 install Method).
• The applet's install method throws an exception before successful return from the
Applet.register method (see Section 3.1 install Method).
• Read and write directly to memory, bypassing the object system and/or standard security.
• Access objects owned by other applets or by the Java Card RE.
• Invoke non-entry point methods of the Java Card RE.
• Be able to invoke the install method of a newly installed applet.
Again, it is up to each Java Card RE implementer to determine the Installer implementation and supply
such features in their Java Card RE implementations as necessary to support their Installer. Java Card RE
implementers are also responsible for the security of such features, so that they are not available to
normal applets.
The Installer shall not invoke the install(byte[], short, byte) method of a non-
multiselectable applet if another applet from the same CAP file is active on the card. The applet
instantiation shall be deemed unsuccessful.
The Installer shall ensure that during the execution of the install() method, the new applet (not the
Installer) is the currently selected applet. In addition, any CLEAR_ON_DESELECT objects created
during the install() method shall be associated with the selection context of the new applet.
The maximum size of the parameter data is 127 bytes. The bArray parameter is a global array
(install(byte[] bArray, short bOffset, byte bLength)), and for security reasons
is zeroed after the return from the install method, just as the APDU buffer is zeroed on return from
an applet's process method.
Any of the length items: Li, Lc, La may be zero. If length Li is non-zero, the instance AID
bytes item is the proposed AID of the applet instance.
The control info item of the parameter data is implementation dependent and is specified by the
Installer.
Other than the need for the entire parameter data to not be greater than 127 bytes, the Java Card API
does not specify anything about the contents of the applet data item of the global byte array
installation parameter. This is fully defined by the applet designer and can be in any format desired. In
addition, the applet data portion is intended to be opaque to the Installer.
Java Card RE implementers should design their Installers so that it is possible for an installation program
running in a CAD to specify the applet data delivered to the Installer. The Installer simply forwards
this along with the other items in the format defined above to the target applet's install method in
the bArray parameter. A typical implementation might define a Java Card RE implementer-proprietary
APDU command that has the semantics "call the applet's install method passing the contents of the
accompanying applet data."
To the CAD, the Applet Deletion Manager appears to be an applet, and may be one and the same as the
Applet Installer. It has an AID, and it becomes the currently selected applet instance when this AID is
• It receives all APDUs dispatched to this logical channel, just like any other active applet.
• Its design specification prescribes the various kinds and formats of APDUs that it expects to
receive, along with the semantics of those commands under various preconditions.
• It processes and responds to all APDUs that it receives. Response to incorrect APDUs include an
error condition of some kind.
• When another applet is selected on this logical channel (or when the card is reset or when
power is removed from the card), the Applet Deletion Manager becomes deselected and
remains suspended until the next time it is selected.
A Java Card RE implementer could choose to implement the Applet Deletion Manager as an applet. If so,
the Applet Deletion Manager might be coded to extend the Applet class and to respond to invocations
of the select, process, and deselect methods, and, if necessary, the methods of the
javacard.framework.MultiSelectable interface.
However, a Java Card RE implementer could also implement the Applet Deletion Manager in other ways,
as long as it provides the SELECTable behavior to the outside world. In this case, the Java Card RE
implementer has the freedom to provide some other mechanism by which APDUs are delivered to the
Applet Deletion Manager code module.
The model is that the Applet Deletion Manager on the card is initiated by an applet deletion program
running on the CAD. In order for applet deletion to succeed, this CAD applet deletion program shall be
able to do the following:
The Application Programming Interface, Java Card Platform, Version 3.1, Classic Edition does not specify
the details of the CAD applet deletion program nor the APDUs passed between it and the Applet
Deletion Manager.
• Whether or not applet deletion can be aborted and how this is done
• What happens if an exception, reset, or power fail occurs during applet deletion
• What happens if another applet is selected before the Applet Deletion Manager is finished with
its work
The following three categories of applet deletion are required on the card:
• Applet instance deletion involves the removal of the applet object instance and the objects
owned by the applet instance and associated Java Card RE structures.
• Applet/library CAP file deletion involves the removal of all the card resident components of the
CAP file, including code and any associated Java Card RE management structures.
• Deletion of the applet CAP file and the contained applet instances involves the removal of the
card-resident code and Java Card RE structures associated with the applet CAP file, and all the
applet instances and objects in the context of the CAP file and associated Java Card RE
structures.
• Perform any security and authorization checks required for the deletion of each of the applet
instances to be deleted. If the checks fail, an error is returned and the applet deletion fails.
• Otherwise, check if the applet instance being deleted is active on the card. If so, an error is
returned and the applet instance deletion fails.
• Otherwise, perform the following steps for each of the applet instances to be deleted:
• A context switch into the context of the applet instance occurs upon invocation.
• If an uncaught exception is thrown during the execution of the uninstall method, it is
caught and ignored.
• An object owned by the applet instance is referenced from an object owned by another applet
instance on the card.
• An object owned by the applet instance is referenced from a static field of a class from any CAP
file on the card.
• The applet instance being deleted is active on the card.
Note: The applet deletion attempt may fail due to security considerations or resource
limitations.
The applet instance deletion operation must be atomic. If a reset or power fail occurs during the
deletion process, it must result in either an unsuccessful applet instance deletion or a successfully
completed applet instance deletion before any applet is selected on the card.
Following an unsuccessful applet instance deletion, the applet instance shall be selectable, and all
objects owned by the applet shall remain unchanged. The functionality of all applet instances on the
card remains the same as prior to the unsuccessful attempt.
Following a successful applet instance deletion, it shall not be possible to select that applet, and no
object owned by the applet can be accessed by any applet currently on the card or by a new applet
created in the future.
The resources used by the applet instance may be recovered for reuse.
The AID of the deleted applet instance may be reassigned to a new applet instance.
• An object owned by any of the applet instances being deleted is referenced from an object
owned by an applet instance on the card which is not being deleted.
Note: The applet deletion attempt may fail due to security considerations or resource
limitations.
The multiple applet instance deletion operation must be atomic. If a reset or power fail occurs during
the deletion process, it must result in either an unsuccessful multiple applet instance deletion or a
successfully completed multiple applet instance deletion before any applet is selected on the card.
Following an unsuccessful multiple applet instance deletion, all applet instances shall be selectable, and
all objects owned by the applets shall remain unchanged. The functionality of all applet instances on the
card remains the same as prior to the unsuccessful attempt.
Following a successful multiple applet instance deletion, it shall not be possible to select any of the
deleted applets, and no object owned by the deleted applets can be accessed by any applet currently on
the card or by a new applet created in the future.
The resources used by the applet instances may be recovered for reuse.
The AID of the deleted applet instances may be reassigned to new applet instances.
• A reachable (non-garbage) instance of a class belonging to the CAP file being deleted exists on
the card.
• Another CAP file on the card depends on this CAP file (as expressed in the CAP file's import
component).
Otherwise, if the applet/library CAP file is resident in mutable memory, the Java Card RE shall delete it.
Note: The CAP file deletion attempt may fail due to security considerations or resource
limitations.
The applet/library CAP file deletion operation must be atomic. If a reset or power fail occurs during the
deletion process, it must result in either an unsuccessful applet/library CAP file deletion or a successfully
completed applet/library CAP file deletion before any applet is selected on the card.
Following an unsuccessful applet/library CAP file deletion, any object or CAP file that depends on it
continues to function unaffected. The functionality of all applets on the card remains the same as prior
to the unsuccessful attempt.
The resources used by the applet/library CAP file may be recovered for reuse.
• Another CAP file on the card depends on this CAP file (as expressed in the CAP file's import
component).
• An object owned by any of the applet instances being deleted is referenced from an object
owned by an applet instance on the card that is not being deleted.
• An object owned by any of the applet instances being deleted is referenced from a static field of
a CAP file that is not being deleted.
• Any of the applet instances being deleted is active on the card.
Otherwise, if the applet CAP file is resident in mutable memory, the Java Card RE shall delete the applet
CAP file and contained instances.
Note: The applet and CAP file deletion attempt may fail due to security considerations or
resource limitations.
The deletion of applet CAP file and contained instances operation must be atomic. If a reset or power
fail occurs during the deletion process, it must result in either an unsuccessful deletion of the applet CAP
file and contained instances or a successfully completed deletion of the applet CAP file and contained
instances before any applet is selected on the card.
Following an unsuccessful deletion of the applet CAP file and contained instances, any object or CAP file
that depends on it continues to function unaffected. The functionality of all applets on the card remains
the same as prior to the unsuccessful attempt.
Following a successful deletion of the applet CAP file and contained instances, it shall not be possible to
install another CAP file that depends on the deleted one. Additionally, it shall be possible to reinstall the
same CAP file (with exactly the same CAP AID) or an upgraded version of the deleted CAP file onto the
card.
The resources used by the applet CAP file may be recovered for reuse.
Following a successful deletion of the applet CAP file and contained instances, it shall not be possible to
select any of the deleted applets, and no object owned by the deleted applets can be accessed by any
applet currently on the card or by a new applet created in the future.
The resources used by the applet instances may be recovered for reuse.
• Read and write directly to memory, bypassing the object system and/or standard security.
• Access objects owned by other applets or by the Java Card RE.
• Invoke non-entry point methods of the Java Card RE.
Again, it is up to each Java Card RE implementer to determine the Applet Deletion Manager
implementation and supply such features in their Java Card RE implementations as necessary to support
their Applet Deletion Manager. Java Card RE implementers are also responsible for the security of such
features, so that they are not available to normal applets.
A
active applet instance
an applet instance that is selected on at least one of the logical channels.
A unique AID is assigned to each CAP file and public packages in a CAP file. In addition, a unique AID is
assigned to each applet in the CAP file. The AID for the CAP file, the package AID of every public package
in a CAP file and the default AID for each applet defined in the CAP file are specified in the CAP file. They
are supplied to the converter when the CAP file is generated.
APDU
an acronym for Application Protocol Data Unit as defined in ISO 7816-4.
API
an acronym for Application Programming Interface. The API defines calling conventions by which an
application program accesses the operating system and other services.
applet
within the context of this document, a Java Card applet, which is the basic unit of selection, context,
functionality, and security in Java Card technology.
applet application
an application that consists of one or more applets.
applet framework
an API that enables applet applications to be built.
applet developer
a person creating an applet using Java Card technology.
applet firewall
the mechanism that prevents unauthorized accesses to objects in contexts other than currently active
context.
applet package
a Java programming language package that contains one or more non-abstract classes that extend the
javacard.framework.Applet class. See also library package.
atomic operation
an operation that either completes in its entirety or no part of the operation completes at all.
atomicity
state in which a particular operation is atomic. Atomicity of data updates guarantee that data are not
corrupted in case of power loss or card removal.
ATR
an acronym for Answer to Reset. An ATR is a string of bytes sent by the Java Card platform after a reset
condition.
authentication
the process of establishing or confirming an application or a user as authentic using some sort of
credentials
big-endian
a technique of storing multibyte data where the high-order bytes come first. For example, given an 8-bit
data item stored in big-endian order, the first bit read is considered the high bit.
binary compatibility
in a Java Card system, a change in a Java programming language package in a Java Card CAP file results
in a new CAP file. A new CAP file is binary compatible with (equivalently, does not break compatibility
with) a preexisting CAP file if another CAP file converted using the export files of packages included in
the preexisting CAP file can link with the new CAP file without errors.
bytecode
machine-independent code generated by the compiler and executed by the Java virtual machine.
C
CAD
an acronym for Card Acceptance Device. The CAD is the device in which the card is inserted.
CAP file
Standard file format containing a binary representation of a shared library (library CAP file) or an
application with its libraries that might be exported or not (applet CAP file).
A CAP file represents a module, which is a unit of code, made of one or more Java packages, with
dependencies and list of exported packages and an assigned name (AID) for lifecycle management. Its
structure is made of multiple CAP components deployed within a JAR file
When a CAP file containing application(s) is deployed on a Java Card platform, it is assigned a new
unique group context that must be associated with any application instance created from code within
this application module.
The following components are conditionally included or optional: the Applet, Export, Static Resources
and Debug. The Applet component is included only if one or more Applets are defined in one or more
packages in the CAP file. The Export component is included only if one or more packages are public and
exported allowing classes in other packages to import elements from them. The Static Resources
component is included only if static resources are embedded in the CAP file. The Debug component is
optional. It contains all of the data necessary for debugging.
card session
a card session begins with the insertion of the card into the CAD. The card is then able to exchange
streams of APDUs with the CAD. The card session ends when the card is removed from the CAD.
cast
the explicit conversion from one data type to another.
card session
a card session begins when it is powered up or reset. The card is then able to exchange messages with
external clients. The card session ends when the card loses power or is reset.
client application
an on-card application that uses services provided by other applications (server applications).
constant pool
the constant pool contains variable-length structures representing various string constants, class names,
field names, and other constants referred to within the CAP file and the Export File structure. Each of
the constant pool entries, including entry zero, is a variable-length structure whose format is indicated
by its first tag byte. There are no ordering constraints on entries in the constant pool entries. One
constant pool is associated with each CAP file.
There are differences between the Java platform constant pool and the Java Card technology-based
constant pool. For example, in the Java platform constant pool there is one constant type for method
references, while in the Java Card constant pool, there are three constant types for method references.
The additional information provided by a constant type in Java Card technologies simplifies resolution of
references.
context
protected object space associated with each applet CAP file and Java Card RE. All objects owned by an
applet belong to the context associated with the applet's CAP file.
converter
a piece of software that preprocesses all of the Java programming language class files contained in a set
of packages and converts them into a CAP file. The Converter also produces export files for exported
packages.
D
default applet
an applet that is selected by default on a logical channel in the APDU application environment when it is
opened. If an applet is designated the default applet on a particular logical channel in the APDU
application environment on the Java Card platform, it becomes the active applet by default when that
logical channel is opened using the basic channel.
E
EEPROM
an acronym for Electrically Erasable, Programmable Read Only Memory.
export file
a file produced by the Converter tool that represents the fields and methods of a package that can be
imported by classes in other classic applet applications and classic libraries.
externally visible
in the Java Card platform, any classes, interfaces, their constructors, methods and fields that can be
accessed from package according to the Java programming language semantics, as defined by the Java
Language Specification.
Externally visible items are represented in an export file. For a library package, externally visible items
are represented in an export file. For an applet package, only those externally visible items that are part
of a shareable interface are represented in an export file.
A Java Card CAP file may restrict the visibility of a package it contains. In this case, these packages are
only visible to the other packages inside the CAP file and are not be accessible by packages in other CAP
files. No export file is generated for the packages that have their visibility restricted to packages inside
the same CAP file.
F
finalization
the process by which a Java virtual machine (VM) allows an unreferenced object instance to release non-
memory resources (for example, close and open files) prior to reclaiming the object's memory.
Finalization is only performed on an object when that object is ready to be garbage collected (meaning,
there are no references to the object).
Finalization is not supported by the Java Card virtual machine. The method finalize() is not called
automatically by the Java Card virtual machine.
firewall
the mechanism that prevents unauthorized accesses to objects in one application group context from
another application group context.
framework
the set of classes that implement the API. This includes core and extension packages. Responsibilities
include applet selection, sending APDU bytes, and managing atomicity.
G
garbage collection
the process by which dynamically allocated storage is automatically reclaimed during the execution of a
program.
global array
an array objects accessible from any context.
group context
protected object space associated with each CAP file and Java Card RE defining the boundaries of the
firewall.
H
heap
a common pool of free memory in volatile and persistent spaces usable by a program for dynamic
memory allocation, in which blocks of memory are used in an arbitrary order. The Java Card virtual
machine's heap is not required to be garbage collected and objects allocated from the heap are not
necessarily reclaimed.
I
installer
the on-card mechanism to download and install CAP files. The installer receives executable binary from
the off-card installation program, writes the binary into the smart card memory, links it with the other
classes on the card, and creates and initializes any data structures used internally by the Java Card
Runtime Environment.
instance variables
also known as non-static fields.
instantiation
in object-oriented programming, to produce a particular object from its class template. This involves
allocation of a data structure with the types specified by the template, and initialization of instance
variables with either default values or those provided by the class's constructor function.
instruction
a statement that indicates an operation for the computer to perform and any data to be used in
performing the operation. An instruction can be in machine language or a programming language.
internally visible
code items that are not externally visible. These items are not described in a package's export file and
use private tokens to represent internal references. See externally visible.
J
JAR file
an acronym for Java Archive file, which is a file format used for aggregating and compressing many files
into one.
• temporary - references to temporary Java Card RE entry point objects cannot be stored in class
variables, instance variables or array components. The Java Card RE detects and restricts
attempts to store references to these objects as part of the firewall functionality to prevent
unauthorized reuse. Examples of these objects are APDU objects and the APDU byte array.
• permanent - references to permanent Java Card RE entry point objects can be stored and freely
reused. Examples of these objects are Java Card RE-owned AID instances.
JDK software
an acronym for Java Development Kit. The JDK software provides the environment required for software
development in the Java programming language. The JDK software is available for a variety of operating
systems.
L
library CAP file
a CAP file that contains only library packages. See library package.
library package
a Java programming language package that does not contain any non-abstract classes that extend the
class javacard.framework.Applet. See also applet package.
local variable
a data item known within a block, but inaccessible to code outside the block. For example, any variable
defined within a method is a local variable and cannot be used outside the method.
logical channel
as seen at the card edge, works as a logical link to an applet application on the card. A logical channel
establishes a communications session between a card applet and the terminal. Commands issued on a
specific logical channel are forwarded to the active applet on that logical channel. For more information,
see the ISO/IEC 7816 Specification, Part 4. (http://www.iso.org).
method
a procedure or routine associated with one or more classes in object-oriented languages.
multiselectable applets
implements the javacard.framework.MultiSelectable interface. Multiselectable applets can
be selected on multiple logical channels in the APDU application environment at the same time. They
can also accept other applets belonging to the same applet application being selected simultaneously.
multiselected applet
an applet instance that is selected and, therefore, active on more than one logical channel in the APDU
application environment simultaneously.
N
namespace
a set of names in which all names are unique.
native method
a method that is not implemented in the Java programming language, but in another language. The CAP
file format does not support native methods to prevent from loading untrusted code.
nibble
four bits.
non-volatile memory
memory that is expected to retain its contents between card tear and power up events or across a reset
event on the smart card device.
object
in object-oriented programming, unique instance of a data structure defined according to the template
provided by its class. Each object has its own values for the variables belonging to its class and can
respond to the messages (methods) defined by its class.
owning context
the application or Java Card RE context in which an object is instantiated or created.
owner context
see owning context.
P
package
a namespace within the Java programming language that can have classes and interfaces.
PCD
an acronym for Proximity Coupling Device. The PCD is a contactless card reader device.
persistent object
persistent objects and their values persist from one card session to the next, indefinitely. Objects are
persistent when referred from another persistent object. Persistent object values are typically updated
atomically using transactions. The term persistent does not mean there is an object-oriented database
on the card or that objects are serialized and deserialized, just that the objects are not lost when the
card loses power.
R
RAM (random access memory)
temporary working space for storing and modifying data. RAM is non-persistent memory; that is, the
information content is not preserved when power is removed from the memory cell. RAM can be
accessed an unlimited number of times and none of the restrictions of EEPROM apply.
remote interface
an interface of an applet application, which extends, directly or indirectly, the
java.rmi.Remote interface.
Each method declaration in the remote interface or its super-interfaces includes the exception
java.rmi.RemoteException (or one of its super classes) in its throws clause.
In a remote method declaration, if a remote object is declared as a return type, it is declared as the
remote interface, not the implementation class of that interface.
In addition, Java Card RMI imposes additional constraints on the definition of remote methods of an
applet application. See Runtime Environment Specification, Java Card Platform, v3.0.5, Classic Edition.
remote methods
the methods of a remote interface of an applet application.
remote object
an object of an applet application whose remote methods can be invoked remotely from the off-card
client. A remote object is described by one or more remote interfaces of an applet application.
RFU
acronym for Reserved for Future Use.
RID
see AID (application identifier).
runtime environment
see Java Card Runtime Environment (Java Card RE).
S
service
a shareable interface object that a server application uses to provide a set of well-defined functionalities
to its clients.
shareable interface
an interface that defines a set of shared methods. These interface methods can be invoked from an
application in one context when the object implementing them is owned by an applet in another
context.
smart card
a card that stores and processes information through the electronic circuits embedded in silicon in the
substrate of its body. Unlike magnetic stripe cards, smart cards carry both processing power and
information. They do not require access to remote databases at the time of a transaction.
SPI
an acronym for Service Provider Interface or sometimes for System Programming Interface. The SPI
defines calling conventions by which a platform implementer may implement system services.
thread
the basic unit of program execution. A process can have several threads running concurrently each
performing a different job, such as waiting for events or performing a time-consuming job that the
program doesn't need to complete before going on. When a thread has finished its job, it is suspended
or destroyed.
The Java Card virtual machine can support only a single thread of execution. Java Card technology
programs cannot use class Thread or any of the thread-related keywords in the Java programming
language.
transaction
an atomic operation in which the developer defines the extent of the operation by indicating in the
program code the beginning and end of the transaction.
transient object
the state of transient objects does not persist from one card session to the next and is reset to a default
state at specified intervals. Updates to the values of transient objects are not atomic and are not
affected by transactions.
U
uniform resource identifier (URI)
a compact string of characters used to identify or name an abstract or physical resource. A URI can be
further classified as a uniform resource locator (URL), a uniform resource name (URN), or both. See RFC
3986 for more information.
volatile memory
memory that is not expected to retain its contents between card tear and power up events or across a
reset event on the smart card device.
volatile object
an object that is ideally suited to be stored in volatile memory. This type of object is intended for a
short-lived object or an object, which requires frequent updates. A volatile object is garbage collected
on card tear (or reset).
W
word
an abstract storage unit. A word is large enough to hold a value of type byte, short, reference or
returnAddress. Two words are large enough to hold a value of integer type.
Specifications
Export Controls
Export laws and regulations of the United States and any other relevant local export laws and
regulations apply to the specifications. You agree that such export control laws govern your use
of the specifications (including technical data), and you agree to comply with all such export
laws and regulations (including "deemed export" and "deemed re- export" regulations). You
agree that no data, information, program and/or materials resulting from services (or direct
product thereof) will be exported, directly or indirectly, in violation of these laws, or will be
used for any purpose prohibited by these laws including, without limitation, nuclear, chemical,
or biological weapons proliferation, or development of missile technology.
- You will not download, provide, make available or otherwise export or re-export the
specifications, directly or indirectly, to countries prohibited by applicable laws and regulations
nor to citizens, nationals or residents of those countries.
- You are not listed on the United States Department of Treasury lists of Specially Designated
Nationals and Blocked Persons, Specially Designated Terrorists, and Specially Designated
Narcotic Traffickers, nor are you listed on the United States Department of Commerce Table of
Denial Orders.
- You will not download or otherwise export or re-export the specifications, directly or
indirectly, to persons on the above mentioned lists.
- You will not use the specifications for, and will not allow the specifications to be used for, any
purposes prohibited by applicable law, including, without limitation, for the development,
design, manufacture or production of nuclear, chemical or biological weapons of mass
destruction.
Oracle Employees: Under no circumstances are Oracle Employees authorized to download the
specifications for the purpose of distributing it to customers. Oracle products are available to
employees for internal use or demonstration purposes only. In keeping with Oracle's trade
PLEASE READ THE FOLLOWING LICENSE AGREEMENT TERMS AND CONDITIONS CAREFULLY
BEFORE INSTALLING OR USING THE SPECIFICATIONS. THESE TERMS AND CONDITIONS
CONSTITUTE A LEGAL AGREEMENT BETWEEN YOU AND ORACLE.
"We," "us," and "our" refers to Oracle America, Inc., for and on behalf of itself and its
subsidiaries and affiliates under common control. "You" and "your" refers to the individual or
entity that wishes to use the specification from Oracle. "Specifications" refers to the Java Card
Classic Edition specification document and/or Java Card Connected Edition specification
document that you selected for download or use from Oracle and any other Oracle product or
technology documentation provided to you by Oracle under this agreement. "License" refers to
your right to use the specifications under the terms of this agreement. “Applications” means
Java technology applications intended to run on the Java Card Classic and/or Java Card
Connected platforms. This agreement is governed by the substantive and procedural laws of
California. You and Oracle agree to submit to the exclusive jurisdiction of, and venue in, the
courts of San Francisco or Santa Clara counties in California in any dispute arising out of or
relating to this agreement.
We are willing to license the specifications to you only upon the condition that you accept all of
the terms contained in this agreement. Read the terms carefully and select the "Accept License
Agreement" button to confirm your acceptance. If you are not willing to be bound by these
terms, select the "Decline License Agreement" button and the registration process will not
continue.
LICENSE RIGHTS
Except for any included software package or file that is licensed to you by Oracle under
different license terms, we grant you a perpetual (unless terminated as provided in this
agreement), nonexclusive, nontransferable, limited License to use (without the right to
sublicense) the specifications internally solely for the purposes of designing and developing
your implementation of the specifications and designing and developing your applets and
applications intended to run on the Java Card platform. Other than this limited license, you
acquire no right, title or interest in or to the specifications or any other Oracle intellectual
property. You acknowledge that any commercial or productive use of an implementation of the
Page 130 Java Card Platform Runtime Environment Specification, v3.1
specifications requires separate and appropriate licensing agreements.
All rights not expressly granted above are hereby reserved. If you want to use the specifications
for any purpose other than as permitted under this agreement, including but not limited to
distribution of the specifications or any use of the specifications for your internal business
purposes (other than developing, testing, prototyping and demonstrating your applications) or
for any commercial production purposes, you must obtain a valid license permitting such use.
We may audit your use of the specifications.
Third-Party Technology
The specifications may contain or be distributed with certain third-party technology. Oracle
may provide certain notices related to such third-party technology in the specifications.
Third party technology will be licensed to you either under the terms of this agreement, or, if
specified in the specifications, under separate license terms ("Separate Terms") and not under
the terms of this agreement ("Separately Licensed Third Party Technology"). Licensee's rights to
use such Separately Licensed Third Party Technology under the Separate Terms are not
restricted or modified in any way by this Agreement.
We retain all ownership and intellectual property rights in the specifications. Unless
enforcement is prohibited by applicable law, you may not modify the specifications. You may
make a sufficient number of copies of the specifications for the licensed use and one copy of
the specifications for backup purposes.
- remove or modify any program markings or any notice of our proprietary rights;
- assign this agreement or give or transfer the specifications or an interest in them to another
- disclose results of any benchmark test results related to the specifications without our prior
consent.
- create, modify, or change the behavior of classes, interfaces, or subpackages that are in any
way identified as "java", "javax", "javafx", “javaee”,"sun", “oracle” or similar convention as
specified by Oracle in any naming convention designation;
Export
You agree that U.S. export control laws and other applicable export and import laws govern
your use of the specifications, including technical data; additional information can be found on
Oracle's Global Trade Compliance web site located at
https://www.oracle.com/products/export-regulations.html. You agree that neither the
specifications nor any direct product thereof will be exported, directly, or indirectly, in violation
of these laws, or will be used for any purpose prohibited by these laws including, without
limitation, nuclear, chemical, or biological weapons proliferation.
THE SPECIFICATIONS IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. WE FURTHER
DISCLAIM ALL WARRANTIES, EXPRESS AND IMPLIED, INCLUDING WITHOUT LIMITATION, ANY
IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR
NONINFRINGEMENT.
Our technical support organization will not provide technical support, phone support, or
updates to you for the specifications licensed under this agreement.
End of Agreement
You may terminate this agreement by destroying all copies of the specifications. We have the
right to terminate your right to use the specifications if you fail to comply with any of the terms
of this agreement, in which case you shall destroy all copies of the specifications.
The relationship between you and us is that of licensee/licensor. Neither party will represent
that it has any authority to assume or create any obligation, express or implied, on behalf of the
other party, nor to represent the other party as agent, employee, franchisee, or in any other
capacity. Nothing in this agreement shall be construed to limit either party's right to
independently develop or distribute software that is functionally similar to the other party's
products, so long as proprietary information of the other party is not included in such software.
"Open Source" software - software available without charge for use, modification and
distribution - is often licensed under terms that require the user to make the user's
modifications to the Open Source software or any software that the user 'combines' with the
Open Source software freely available in source code form. If you use Open Source software in
conjunction with the specifications, you must ensure that your use does not: (i) create, or
purport to create, obligations of us with respect to the Oracle specifications; or (ii) grant, or
purport to grant, to any third party any rights to or immunities under our intellectual property
or proprietary rights in the Oracle specifications. For example, you may not develop a software
program using an Oracle program/specification and an Open Source program where such use
results in a program file(s) that contains code from both the Oracle program/specification and
the Open Source program (including without limitation libraries) if the Open Source program is
licensed under a license that requires any "modifications" be made freely available. You also
may not combine the Oracle specifications with a program licensed under the GNU General
Public License ("GPL") in any manner that could cause, or could be interpreted or asserted to
cause, the Oracle specifications or any modifications thereto to become subject to the terms of
the GPL.
You agree that this agreement is the complete agreement for the specifications and licenses,
and this agreement supersedes all prior or contemporaneous agreements or representations. If
any term of this agreement is found to be invalid or unenforceable, the remaining provisions
will remain effective.
Should you have any questions concerning this License Agreement, or if you desire to contact
Oracle for any reason, please write: