Java Card™ Platform, Application Programming Interface, Classic Edition
Version 3.2 with Preview Features

This version of the Java Card API Specification is amended with Preview Features.
Preview features may exist in a different form or be removed in a future release, or upgraded to permanent features of the Java Card platform.
This is the Application Programming Interface (API) for the Java Card™ Platform, Classic Edition, Version 3.2.

The list of packages is divided into two groups:

  • Core packages - mandatory packages providing the core features of the Java Card platform
  • Extension packages - optional packages providing specific features. These may not necessarily be available on all implementations of the Java Card Platform.

Package
Description
java.io
Defines 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
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
This optional 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.
javacard.security
Provides classes and interfaces that contain publicly-available functionality for implementing a security and cryptography framework on the Java Card platform.
javacardx.annotations
Extension package that contains annotations for defining character string constants.
javacardx.apdu
Extension package that enables support for ISO7816 specification defined optional APDU related mechanisms.
javacardx.apdu.util
Extension package that contains the APDUUtil class which contains utility functions to parse CLA byte from a command APDU.
javacardx.biometry
Extension package that contains functionality for implementing a biometric framework on the Java Card platform.
javacardx.biometry1toN
Extension package that contains functionality for implementing a 1:N biometric 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.
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.framework.event
Extension package that defines a framework to handle different source of events.
javacardx.framework.math
Extension package to perform operations on Big Numbers in either binary form or Binary Coded Decimal (BCD) form, and perform parity computations.
javacardx.framework.nio
Extension package that defines buffers, which are containers for data.
javacardx.framework.string
Extension package that contains common utility functions for manipulating UTF-8 encoded character strings.
javacardx.framework.time
Extension package that defines classes to handle system time and time
javacardx.framework.tlv
Extension package for managing the storage of 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
Extension package that contains functionality, for implementing security countermeasures to protect security relevant applet assets on the Java Card platform.
javacardx.security.bdh
Extension package that provides support for Elliptic Curve Blinded Diffie-Hellman Key Exchange protocol as defined in EMV Contactless Specifications for Payment Systems - Book E Security and Key Management - Version 1.1 Feb 2025.
javacardx.security.cert
Extension package that provides classes to handle certificates
javacardx.security.derivation
Extension package that provides classes implementing cryptographic derivation functions
javacardx.security.util
Extension package defining utility classes for security framework

See also

  • Runtime Environment Specification for the Java Card Platform, Classic Edition, Version 3.2.
  • Virtual Machine Specification for the Java Card Platform, Clasic Edition, Version 3.2.

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

Acknowledgement 

Dedicated to Tanjore (Ravi) Ravishankar, 1958 - 2015. His leadership, passion and devotion inspired us all.

API Notes 

Referenced Standards

ANSSI - Agence nationale de la securite des systemes d'information

  • FRP256V1 Elliptic Curve

ETSI - European Telecommunications Standards Institute

  • 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 - American National Standards Institute

  • Public Key Cryptography for the Financial Industry: The Elliptic Curve Digital Signature Algorithm (ECDSA): X9.62-1998
  • Public Key Cryptography for the Financial ServicesIndustry - Key Agreement and Key Transport Using EllipticCurve Cryptography: X9.63

IEEE - Institute of Electrical and Electronic Engineers

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

ICAO - International Civil Aviation Organization

  • ICAO Machine Readable Travel Documents (MRTD) Doc 9303

IETF (Internet Engineering Task Force)

  • RFC 2104: Keyed-Hashing for Message Authentication
  • RFC 1321: The MD5 Message-Digest Algorithm
  • RFC 2409: The Internet Key Exchange (IKE)
  • RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile
  • RFC 4346: The Transport Layer Security (TLS) Protocol Version 1.1
  • RFC 5246: The Transport Layer Security (TLS) Protocol Version 1.2
  • RFC 7748: Elliptic Curves for Security (curve25519 and curve448 and Key Agreement)
  • RFC 8032: Edwards-Curve Digital Signature Algorithm (EdDSA)
  • RFC 5869: HMAC-based Extract-and-Expand Key Derivation Function (HKDF)

FIPS - Federal Information Processing Standards

  • Advanced Encryption Standard (AES): FIPS-197
  • Digital Signature Standard (DSS): FIPS 186-4

NIST - National Institute of Standards and Technology

  • Recommendation for Key Derivation Using Pseudorandom Functions: SP800-108

KISA - Korea Information Security Agency

  • SEED Algorithm Specification

OSCCA - Office of the State Commercial Cryptography Administration

  • GM/T 0003.1-2012: Public Key Cryptographic Algorithm SM2 Based on Elliptic Curves Part 1: General
  • GM/T 0003.2-2012: Public Key Cryptographic Algorithm SM2 Based on Elliptic Curves Part 2: Digital Signature Algorithm
  • GM/T 0003.3-2012: Public Key Cryptographic Algorithm SM2 Based on Elliptic Curves Part 3: Key Exchange Protocol
  • GM/T 0003.4-2012: Public Key Cryptographic Algorithm SM2 Based on Elliptic Curves Part 4:Public key encryption algorithm
  • GM/T 0003.5-2012: Public Key Cryptographic Algorithm SM2 Based on Elliptic Curves Part 5: Parameter definition
  • GM/T 0004-2012: SM3 Cryptographic Hash Algorithm
  • GM/T 0002-2012: SM4 Block Cipher Algorithm

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"TM 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 © 1998, 2026, Oracle and/or its affiliates.