Java Card^TM 2.1 Platform API Specification
Final Revision 1.0

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

See:
Description

Packages

java.lang	Provides classes that are fundamental to the design of the Java Card technology subset of the Java programming language.
javacard.framework	Provides framework of classes and interfaces for the core functionality of a Java Card applet.
javacard.security	Provides the classes and interfaces for the Java Card security framework.
javacardx.crypto	Extension package containing security classes and interfaces for export-controlled functionality.

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

Java Card 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.0
• Password-Based Encryption Standard: PKCS #5 Version 1.5

EMV

• The EMV '96 ICC Specifications for Payments systems Version 3.0

IPSec

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

Standard Names for Security and Crypto

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

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
• IllegalArgumentException
• IllegalStateException
• 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.