Java Card v2.2.1 API

This document is the specification for the Java Card 2.2.1 Application Programming Interface.

See:
Description

Core Packages

java.io	A subset of the java.io package in the standard Java programming language.
java.lang	Provides classes that are fundamental to the design of the Java Card technology subset of the Java programming language.
java.rmi	The java.rmi package defines the Remote interface which identifies interfaces whose methods can be invoked from card acceptance device (CAD) client applications.
javacard.framework	Provides a framework of classes and interfaces for building, communicating with and working with Java Card technology-based applets.
javacard.framework.service	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.
javacard.security	Provides classes and interfaces that contain publicly-available functionality for implementing a security and cryptography framework on the Java Card platform.

Standard Extensions

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.

This document is the specification for the Java Card 2.2.1 Application Programming Interface.

Java Card 2.2.1 API Notes

Referenced Standards

ISO - International Standards Organization

• Information Technology - Identification cards - integrated circuit cards with contacts: ISO 7816
• Information Technology - Security Techniques - Digital Signature Scheme Giving Message Recovery: ISO 9796
• Information Technology - Data integrity mechanism using a cryptographic check function employing a block cipher algorithm: ISO 9797
• Information technology - Security techniques - Digital signatures with appendix: ISO 14888

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

IPSec

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

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

FIPS

• Advanced Encryption Standard (AES): FIPS-197

Standard Names for Security and Crypto Packages

• SHA (also SHA-1): Secure Hash Algorithm, as defined in Secure Hash Standard, NIST FIPS 180-1.
• 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.

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