Java Card API, Connected Edition

This is the Java CardTM application programming interface (API), Version 3.0.1, Connected Edition, which is a subset of the JavaTM programming language.

See:
          Description

Generic Connection Framework API Packages
javacardx.io Provides the classes and interfaces for the Generic Connection Framework extension.
javax.microedition.io Provides the classes and interfaces for the Generic Connection Framework.
javax.microedition.pki Certificates are used to authenticate information for secure Connections.

 

Servlet API Packages
javax.servlet The javax.servlet package contains a number of classes and interfaces that describe and define the contracts between a servlet class and the runtime environment provided for an instance of such a class by a conforming servlet container.
javax.servlet.http The javax.servlet.http package contains a number of classes and interfaces that describe and define the contracts between a servlet class running under the HTTP protocol and the runtime environment provided for an instance of such a class by a conforming servlet container.

 

Evolutive Cryptographic Framework API Packages (see also: javacardx.security)
javacard.security Provides classes and interfaces that contain publicly-available functionality for implementing a security and cryptography framework on the Java Card platform.
javacardx.crypto Extension package that contains functionality, which may be subject to export controls, for implementing a security and cryptography framework on the Java Card platform.

 

Other Packages
java.io Provides classes for input and output through data streams.
java.lang Provides classes that are fundamental to the Java programming language.
java.lang.annotation Provides library support for the Java programming language annotation facility.
java.rmi Defines the Remote interface which identifies interfaces whose methods can be invoked from card acceptance device (CAD) client applications.
java.security Provides the classes and interfaces for the security framework.
java.util Contains the collection classes, and the date and time facilities.
javacard.framework Provides a framework of classes and interfaces for building, communicating with and working with Java Card technology-based applets.
javacard.framework.service This extension package provides a service framework of classes and interfaces that allow a Java Card technology-based applet to be designed as an aggregation of service components.
javacardx.apdu Extension package that enables support for ISO7816 specification defined optional APDU related mechanisms.
javacardx.biometry Extension package that contains functionality for implementing a biometric framework on the Java Card platform.
javacardx.external Extension package that provides mechanisms to access memory subsystems which are not directly addressable by the Java Card runtime environment(Java Card RE) on the Java Card platform.
javacardx.facilities Provides the classes and interfaces for the SIO-based service, event and task facilities.
javacardx.framework Extension package that contains additional framework classes for web and extended applet applications.
javacardx.framework.math Extension package that contains common utility functions for BCD math and parity computations.
javacardx.framework.tlv Extension package that contains functionality, for managing storage for BER TLV formatted data, based on the ASN.1 BER encoding rules of ISO/IEC 8825-1:2002, as well as parsing and editing BER TLV formatted data in I/O buffers.
javacardx.framework.util Extension package that contains common utility functions for manipulating arrays of primitive components - byte, short or int.
javacardx.framework.util.intx Extension package that contains common utility functions for using int components.
javacardx.security Provides the classes and interfaces for security framework.
javacardx.servlet.http Provides the classes and interfaces to support the web application environment specific to the Java Card platform.

 

This is the Java CardTM application programming interface (API), Version 3.0.1, Connected Edition, which is a subset of the JavaTM programming language.

See Runtime Environment Specification for the Java Card Platform, Version 3.0.1, Connected Edition.

The following shorthand terms are used in these JavadocTM tool files:

Application Models

The Java Card platform, Connected Edition, supports three application models:
Classic applet application model
applet-based applications with the same capabilities as those in previous versions of the Java Card platform and in the Classic Edition. These applets use the APDU-based scheme of communication with the card.
See Runtime Environment Specification for the Java Card Platform, Version 3.0.1, Classic Edition and chapter 4 of Runtime Environment Specification for the Java Card Platform, Version 3.0.1, Connected Edition, for details.

Extended applet application model
applets with more advanced capabilities than classic applets. These applets use the APDU-based scheme of communication with the card.
See Runtime Environment Specification for the Java Card Platform, Version 3.0.1, Connected Edition, chapter 4 for details.

Web application model
applications based on servlets that use the HTTP protocol to support a web-based scheme of communication with the card.
See Runtime Environment Specification for the Java Card Platform, Version 3.0.1, Connected Edition, chapter 3 for details.

Application And Other Resource Identification With URI and AID

Many of the new functionalities of the Java Card platform, Connected Edition, use URIs [RFC 3986]. Applet-based applications are classically identified with AIDs. AIDs are encapsulated in javacard.framework.AID objects. AIDs can be transformed into equivalent hierarchical URIs such as //aid/<RID>/<PIX> and conversely using getURI(AID) and getAID(String) methods of javacardx.framework.JCSystem.

Web application URIs (i.e.: <web-app-context-path> or //<web-app-context-path>, e.g.: /transit) use a default authority while APDU-based application URIs (i.e.: //aid/<RID>/<PIX>, e.g.: //aid/a000000062/03010c0D01) use the aid registry-based authority. If the authority is null then the URI must be resolved against/by the default authority; if the authority is aid then the URI must be resolved against/by the aid registry-based authority.

By using a unique identification scheme based on hierarchical namespace, servlet-based applications and applet-based applications can seamlessly inter-operate using SIO and events.

Table 1: Unified Identification Formats

Application or Resource

URI Format

Example

Web application

//<application-path> or <application-path>

where

application-path corresponds to the web application's context path

///transit

Applet-based application

//aid<application-path>

with

application-path = /<RID>/<PIX>

//aid/a000000062/03010c0D01

SIO

sio://<application-path>/<sio-path>

sio://aid<application-path>/<sio-path>

sio://<reserved-path>/<sio-path>

sio:///transit/pos/ticketbook

sio://aid/a000000062/03010c0D01/purse

sio:///standard/auth/holder/global/owner/biometric

Event

event://<application-path>/<event-path>

event://aid<application-path>/<event-path>

event://<reserved-path>/<event-path>

event:///transit/pos/credited

event://aid/a000000062/03010c0D01/debited

event:///platform/reset

Resources

<scheme>://<application-path>/<resource-path>

<scheme>://aid<application-path>/<resource-path>

<scheme>://<reserved-path>/<resource-path>

file:///transit/pos/transactionlog

file://aid/a000000062/03010c0D01/log

Handling of URIs

URIs used for designating on-card resources such as applications, SIO-based services, SIO-based events and files, as well as off-card (network) resources such as those accessed using the Generic Connection Framework conform to the URI syntax as defined by RFC 3986: Uniform Resource Identifiers (URI): Generic Syntax with the additional following amendments:
Default Normalization of URIs
By default, only enhanced syntax-based normalization is performed in order to test URI strings for equivalence. As a result, the followings apply:
No default port assumption
A URI with an explicit port, where the port is the default for the scheme, is not equivalent to one where the port is omitted.
No host resolution
A URI with a host, where the host is a a domain name of a network host, is not equivalent to one where the host has been resolved to its IP address.
No interpretation and no default value assumption for path segment parameters
Path segments are considered opaque and are compared byte-for-byte.
Scheme-based and Protocol-based Normalization of Network URIs
Scheme-dependent and protocol-dependent handling of a network URI is not performed until the designated resource is being accessed or located. Scheme-based and protocol-based normalizations are only performed when actually locating and controlling access to the resource designated by the network URI. As a result, applications and permission-based security policies should use URIs in a scheme-based and protocol-based normalized form to reduce false negatives during security checks.
URI Patterns
The Java Card Platform-specific URI syntax extension is supported for patterns that designate one or more resources.

Canonicalization of URIs

URIs can be absolute or relative. A URI which starts with a scheme (preceding a ‘:’) such as sio, event or file, is an absolute URI. Otherwise it is a relative URI reference.

In order to properly interpret or compare URIs, all URI matching operations performed by the Java Card RE or API apply on canonicalized forms of the URIs. Therefore, URIs are first resolved, then normalized.

API and SPI methods accept well-formed URIs (including those identifying applications or the platform) passed by applications but only return or pass to applications such URIs in their canonical forms.

Resolution of Relative URI References

Relative URI references are resolved as per RFC 3986 against a base URI:

Default Normalization of URIs

Syntax-based normalization of URIs is the default URI normalization procedure on a Java Card Platform implementation. URIs are normalized as per RFC 3986’s Syntax-Based Normalization which includes:
Case Normalization
Any hexadecimal digits within a percent-encoding triplet (e.g., "%3a" versus "%3A") are case-insensitive and therefore is normalized to lower case. The scheme and host components of a URI are considered case-insensitive, and therefore is normalized to lower case.
Percent-Encoding Normalization
Any percent-encode octets in a URI is normalized by decoding any percent-encoded octet that corresponds to an unreserved character.
Path Segment Normalization
The complete path segments ”.” and ”..” are intended only for use within relative URI references and are removed as part of the resolution process described above. Path segments are otherwise considered opaque.
In addition, URIs are further normalized as follows:
IP Address Normalization
In addition to the case normalization of the host, an IPv6 address is normalized by converting the address to the “preferred form” x:x:x:x:x:x:x:x and removing leading zeros from each individual field (see RFC 2373, IP Version 6 Addressing Architecture).
Port Specification Normalization
Any port number stated in the port specification of a URI is normalized by removing any leading zeros.
Registry-based Authority Normalization
Platform and standard URIs (URIs with root path component /platform and /standard respectively) that use the default registry-based URI authority, and those that use the aid registry-based URI authority are considered equivalent. Platform and standard URIs is normalized to use the default registry-based URI authority.
Application and Platform-identifying URI Normalization

Scheme-based and Protocol-based Normalization of Network URIs

Scheme-based and protocol-based normalizations is only be performed when actually locating and controlling access to the resource designated by the network URI. In addition to syntax-based normalization, network URIs are normalized as per RFC 3986’s Scheme-based Normalization and Protocol-based Normalization which include depending on the schemes:
Port Specification Normalization
A URI with a port specification that corresponds to the default port for the scheme is normalized with the default port omitted.
Host Normalization
A URI with a host (a host name or an IP address) is normalized with the complete domain name for the host and only defaults to use its IP address when it can’t be resolved. Reverse name resolution is on a best effort basis. To preserve GCF semantics on server connections (e.g. ssl://:369 or ssl://), no default is defined for the host subcomponent of a URI. An empty host subcomponent is not normalized with the "localhost" name, even if a port is specified. And conversely, a host subcomponent with the "localhost" name is not normalized to an empty host subcomponent, even if no port is specified.
Empty Path Normalization
A URI with an empty path MUST be normalized with a path of "/". This normalization MUST not be applied to GCF connection schemes for which the path is irrelevant such as for the schemes ssl, socket and datagram.
Scheme-based and Protocol-based Normalization of network URIs is only performed by the methods of the Connector class.

URI Patterns

Some of the new functionalities of the Java Card platform, Connected Edition, use URI patterns. URI patterns are used to designate sets of resources.

Table 2: URI Pattern Types

Pattern Type

Description

Example(s)

Exact

Designates a single resource

/transit/pos

sio:///transit/pos/ticketbook

event://aid/A000000062/03010C0D01/debited

file:///transit/pos/ticketbook/log/transactions.txt

http://java.sun.com:80/products/javacard

Path-prefix

Designates a set of resources: all the resources with the same scheme and authority, and with a URI path component starting with the same path prefix.

/*

/transit/*

sio:///transit/pos/*

event://aid/A000000062/03010C0D01/*

file:///transit/pos/ticketbook/log/*

http://java.sun.com:80/products/*

Application-generic

Designates a set of resources: all the resources with the same scheme and authority, and with a path relative to their owning application’s root URI matching exactly the path suffix (the path after the ‘~’).

sio:///~/ticketbook

event://aid/~/debited

file:///~/ticketbook/log/transactions.txt

Registry-based authority

Designates a set of resources in a web application or applet application: all the resources with the same scheme and URI path component.

sio://*/~/ticketbook

event://*/~/debited

file://*/~/ticketbook/log/transactions.txt

Server-based authority

Designates a set of resources: all the resources with the same scheme and URI path component, and with a hostname and port number matching the hostname pattern and port number pattern.

http://java.sun.com:80/products/javacard

http://*.sun.com:80/products/javacard

https://java.sun.com:*/products/javacard

https://*:*/products/javacard

ssl://java.sun.com:*

socket://*:5555

Note On Transactions

An implementation of an interface or class specified in this API that is annotated SUPPORTS for TransactionType MAY rely on the transaction state of the caller for maintaining consistent internal state only on methods that update state visible at the level of the interface they expose. For example, the get method of the Hashtable class and getter methods in general need not be called with a transaction in progress.

Generic Connection Framework (GCF) Protocol Support

See: javax.microedition.io package overview: Generic Connection Framework (GCF) Protocol Support section.

Generic Connection Framework (GCF) Security Checks

See: javax.microedition.io package overview: Generic Connection Framework (GCF) Security Checks section.

Public Key Certificate Support

Certificates are used to authenticate information for secure Connections. The Certificate interface provides to the application information about the origin and type of the certificate. Concrete implementations of this interface are platform implementation-specific. The Java Card Platform specification does not provide an API for generating Certificates from an encoded form nor does it provide means for provisionning Certificates. Provisionning of certificates may be supported by card management frameworks.

The Java Card platform, Connected Edition, supports X.509 Certificates. Other certificate formats may be supported.

See: javax.microedition.pki package overview: X.509 Certificate Profile section.

Package Optionality

The following packages are optional under certain conditions.

Optional Package or Package Set

Description and Optionality Conditions

javacard.framework.service

Extension package that provides a service framework of classes and interfaces that allow a Java Card technology-based applet to be designed as an aggregation of service components.The platform must support this optional package only if the features enabled are included in the implementation.

javacardx.crypto

Extension package that contains functionality, which may be subject to export controls, for implementing a security and cryptography framework on the Java Card platform. The platform must support this optional package only if cryptographic encryption and decryption functionality is included in the implementation. Classes that contain security and cryptography functionality that are not subject to export control restrictions are contained in the package javacard.security.

javacardx.apdu

Extension package that enables support for ISO7816 specification defined optional APDU related mechanisms. The platform must support this optional package only if the features enabled are included in the implementation.

javacardx.biometry

Extension package that contains functionality for implementing a biometric framework on the Java Card platform. The platform must support this optional package only if biometry support is included in the implementation.

javacardx.external

Extension package that provides mechanisms to access memory subsystems which are not directly addressable by the Java Card runtime environment(Java Card RE) on the Java Card platform. The platform must support this optional package if an external memory access feature is included in the implementation.

javacardx.framework.math

javacardx.framework.tlv

javacardx.framework.util

javacardx.framework.util.intx

All these packages are inter-dependent. All of them must be implemented or none.

javacardx.framework.math: Extension package that contains common utility functions for BCD math and parity computations..

javacardx.framework.tlv: Extension package that contains functionality, for managing storage for BER TLV formatted data, based on the ASN.1 BER encoding rules of ISO/IEC 8825-1:2002, as well as parsing and editing BER TLV formatted data in I/O buffers.

javacardx.framework.util: Extension package that contains common utility functions for manipulating arrays of primitive components - byte, short or int.

javacardx.framework.util.intx: Extension package that contains common utility functions for using int components.

API Notes

Referenced Standards

ETSI - European Telecommunications Standards Institute (ETSI)

ISO - International Standards Organization

RSA Data Security, Inc.

EMV

ANSI

IEEE

IETF (Internet Engineering Task Force) - IPSec Working Group

IETF (Internet Engineering Task Force) - Network Working Group

FIPS

KISA - Korea Information Security Agency

Standard Names for Security and Crypto Packages

Parameter Checking

Policy

All Java Card API implementations must conform to the Java model of parameter checking. That is, the API code should not check for those parameter errors which the Java Card Virtual Machine(VM) is expected to detect. These include all parameter errors, such as null pointers, index out of bounds, and so forth, that result in standard runtime exceptions. The runtime exceptions that are thrown by the Java Card VM are:

Exceptions to the Policy

In some cases, it may be necessary to explicitly check parameters. These exceptions to the policy are documented in the Java Card API specification. A Java Card API implementation must not perform parameter checking with the intent to avoid runtime exceptions, unless this is clearly specified by the Java Card API specification.

Note—If multiple erroneous input parameters exist, any one of several runtime exceptions will be thrown by the VM. The terms "Java Virtual Machine" and "JVM" mean a Virtual Machine for the Java platform. Java programmers rely on this behavior, but they do not rely on getting a specific exception. It is not necessary (nor is it reasonable or practical) to document the precise error handling for all possible combinations of equivalence classes of erroneous inputs. The value of this behavior is that the logic error in the calling program is detected and exposed via the runtime exception mechanism, rather than being masked by a normal return.



Copyright (c) 2009 Sun Microsystems, Inc. All rights reserved.