Overview (Java Card API, Connected Edition)
Date: 2009-12-11

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV NEXT | FRAMES NO FRAMES

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

- Java Card platform framework extension ("Java Card framework") or ("Java Card framework extension").
- Java Card runtime environment ("Java Card runtime").
- Java Card runtime environment permissions ("Java Card runtime permissions").
- Java Card platform framework ("Java Card framework").
- Java programming language modified UTF-8 format ("Java modified UTF-8 format") or ("Java modified UTF representation").
- Java programming language primitive types ("Java primitive types").
- Java programming language data types ("Java data types").
- Java programming language model ("Java model").
- Java programming language ("Java language").

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

- The default base URI is the current application’s root URI, for the scheme appropriate for the use. The current application’s root URI for a specific scheme is constructed as follows:

  > <scheme>`:`<application URI>`/`

  where <scheme> is the scheme, <application URI> is the canonical URI of the current application. Note that a ‘`/`’ is appended to construct the default base URI.
- If the API or SPI explicitly states a base URI, the relative URI reference is resolved against that 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
  - A URI identifying the platform is normalized to `///platform`.
  - A URI identifying a web application is normalized to `//`<context path>.
  - An AID URI identifying an applet application is normalized to the `//aid/`<RID>`/`<PIX> or `//aid/`<RID>`/-` (if <PIX> is 0 of length), where <RID> and <PIX> are upper-case hexadecimal digit strings, <RID> is 10 digits of length and <PIX> has an even length of at the most 22 digits, including any necessary leading zero.

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

- Smart Cards; UICC - Contactless Front-end (CLF) Interface; Part 1: Physical and data link layer characteristics (ETSI TS 102 613)
- Smart Cards; UICC - Terminal interface; Characteristics of the USB interface ((ETSI TS 102 600)

#### ISO - International Standards Organization

- Information Technology - Identification cards - integrated circuit cards with contacts: ISO/IEC 7816
- Identification cards -- Contactless integrated circuit(s) cards -- Proximity cards: ISO/IEC 14443
- Information Technology - Security Techniques - Digital Signature Scheme Giving Message Recovery: ISO/IEC 9796-2
- Information Technology - Data integrity mechanism using a cryptographic check function employing a block cipher algorithm: ISO/IEC 9797
- Information technology - Security techniques - Digital signatures with appendix: ISO/IEC 14888
- Information technology -- ASN.1 encoding rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules (CER) and Distinguished Encoding Rules (DER): ISO 8825-1:2002

#### RSA Data Security, Inc.

- RSA Encryption Standard: PKCS #1 Version 2.1
- Password-Based Encryption Standard: PKCS #5 Version 1.5

#### EMV

- The EMV 2000 ICC Specifications for Payments systems Version 4.0
- The EMV '96 ICC Specifications for Payments systems Version 3.0

#### ANSI

- Public Key Cryptography for the Financial Industry: The Elliptic Curve Digital Signature Algorithm (ECDSA): X9.62-1998

#### IEEE

- Standard Specifications for Public Key Cryptography, Institute of Electrical and Electronic Engineers, 2000 : IEEE 1363

#### IETF (Internet Engineering Task Force) - IPSec Working Group

- The Internet Key Exchange ( IKE ) document RFC 2409 (STD 1)

#### IETF (Internet Engineering Task Force) - Network Working Group

- RFC 1321: The MD5 Message-Digest Algorithm)
- RFC 1630: Uniform Resource Identifiers (URI)
- RFC 1738: Uniform Resource Locators (URL)
- RFC 1900: Renumbering Needs Work
- RFC 1945: Hypertext Transfer Protocol (HTTP/1.0)
- RFC 2019: A Method for the Transmission of IPv6 Packets over FDDI Networks
- RFC 2045: MIME Part One: Format of Internet Message Bodies
- RFC 2046: MIME Part Two: Media Types
- RFC 2047: MIME Part Three: Message Header Extensions for non-ASCII text
- RFC 2048: MIME Part Four: Registration Procedures
- RFC 2049: MIME Part Five: Conformance Criteria and Examples
- RFC 2104: Keyed-Hashing for Message Authentication)
- RFC 2109: HTTP State Management Mechanism
- RFC 2145: Use and Interpretation of HTTP Version Numbers
- RFC 2373: IP Version 6 Addressing Architecture
- RFC 2437: PKCS #1: RSA Cryptography Specifications Version 2.0
- RFC 2616: Hypertext Transfer Protocol (HTTP/1.1)
- RFC 2617: HTTP Authentication: Basic and Digest Authentication
- RFC 2818: HTTP Over TLS
- RFC 3280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile
- RFC 3986: Uniform Resource Identifier (URI): Generic Syntax
- RFC 4279: Pre-Shared Key Ciphersuites for Transport Layer Security (TLS)
- RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2

#### FIPS

- Advanced Encryption Standard (AES): FIPS-197

#### KISA - Korea Information Security Agency

- SEED Algorithm Specification

#### Standard Names for Security and Crypto Packages

- SHA (also SHA-1): Secure Hash Algorithm, as defined in Secure Hash Standard, NIST FIPS 180-1
- SHA-256, SHA-384, SHA-512: Secure Hash Algorithm, as defined in Secure Hash Standard, NIST FIPS 180-2
- MD5: The Message Digest algorithm RSA-MD5, as defined by RSA DSI in RFC 1321
- RIPEMD-160: as defined in ISO/IEC 10118-3:1998 Information technology - Security techniques - Hash-functions - Part 3: Dedicated hash-functions
- DSA: Digital Signature Algorithm, as defined in Digital Signature Standard, NIST FIPS 186
- DES: The Data Encryption Standard, as defined by NIST in FIPS 46-1 and 46-2
- RSA: The Rivest, Shamir and Adleman Asymmetric Cipher algorithm
- ECDSA: Elliptic Curve Digital Signature Algorithm
- ECDH: Elliptic Curve Diffie-Hellman algorithm
- AES: Advanced Encryption Standard (AES), as defined by NIST in FIPS 197
- HMAC: Keyed-Hashing for Message Authentication, as defined in RFC-2104

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

- `ArithmeticException`
- `ArrayStoreException`
- `ClassCastException`
- `IndexOutOfBoundsException`
- `ArrayIndexOutOfBoundsException`
- `NegativeArraySizeException`
- `NullPointerException`
- `SecurityException`

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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV NEXT | FRAMES NO FRAMES

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