Table of Contents

Introduction

What's New

System Requirements

Installation

Known Issues

Documentation

Product Information

Introduction

Java Card technology enables secure elements, such as smart cards and other tamper-resistant security chips to host applications called applets, which employ Java technology.

Java Card technology offers a secure and interoperable execution platform that can store and update multiple applications on a single resource constrained device, while retaining the highest certification levels and compatibility with standards. Java Card developers can build, test, and deploy applications and services rapidly and securely. This accelerated process reduces development costs, increases product differentiation, and enhances value to the customers.

The Java Card Development Kit is a suite of tools for designing implementations of Java Card technology and developing applets based on the Java Card Specifications. It is available as two independent downloads:

  • The Java Card Development Kit Tools are used to convert and verify Java Card applications.
  • The Java Card Development Kit Simulator offers a testing and debugging reference for Java Card applications. It includes a Java Card simulation environment and Eclipse plug-in.

Together, these two downloads provide a complete, stand-alone development environment in which applications written for the Java Card platform can be developed and tested.

These release notes describe the Java Card Development Kit Simulator, Version 26.0, which is based on version 3.2 with Preview Features of the Java Card Platform Specifications.

What's New

The complete set of Java Card Development Kit Simulator and Eclipse Plugin features is described in the Java Card Development Kit Simulator User Guide v26.0 in the Java Card Documentation web site.

New Features

JCDK 26.0 is primarily focused on adding support for Preview Features. This marks an important step in the process of releasing new capabilities for the Java Card platform. A Java Card Preview Feature is a new feature of the Java Card Platform whose design, specification, and implementation are complete, and yet impermanent, which means that the feature may exist in a different form or not at all in future releases of the Java Card Platform Specification. The main purpose of introducing a preview feature is to enable application developers to use this feature in real context and provide feedback. Details on the Java Card Preview Features are available in the Java Card API documentation.

  • Simulator – BDH Preview Feature – Add support for key agreement using the Blinded Diffie-Hellman (BDH) protocol (EMV® Contactless Book E Security and Key Management v1.1). A BDHKeyAgreement object instantiated with the KeyAgreement. ALG_EC_BDH_SECP256R1 constant enables to process and Elliptic Curve Blinded Diffie-Hellman Key Exchange (ECBDH-KE) using the secp256r1 curve defined in FIPS 186-4. The dedicated method BDHKeyAgreement.generateSecret() permits to generate the related blinding factor, blinded public key and shared secret.
  • Simulator – ECSDSA Preview Feature – Add support for generating and verifying digital signatures using the Elliptic Curve based Schnorr Digital Signature Algorithm (ECSDSA) with appendix, in accordance with ISO/IEC 14888-3 specifications. For that purpose, a Signature object can be instantiated based on the constants Signature.SIG_CIPHER_ECSDSA or Signature.SIG_CIPHER_ECSDSA_OPTIMIZED for the optimized variant where only the x-coordinate of the ephemeral public key is hashed rather than its (x, y) coordinates. The supported combinations (cipher algorithm, digest algorithm, padding algorithm) when instantiating a Signature object are the following:
    • (SIG_CIPHER_ECSDSA, ALG_SHA, PAD_NULL)
    • (SIG_CIPHER_ECSDSA, ALG_SHA_224, PAD_NULL)
    • (SIG_CIPHER_ECSDSA, ALG_SHA_256, PAD_NULL)
    • (SIG_CIPHER_ECSDSA, ALG_SHA_384, PAD_NULL)
    • (SIG_CIPHER_ECSDSA, ALG_SHA_512, PAD_NULL)
    • (SIG_CIPHER_ECSDSA_OPTIMIZED, ALG_SHA, PAD_NULL)
    • (SIG_CIPHER_ECSDSA_OPTIMIZED, ALG_SHA_224, PAD_NULL)
    • (SIG_CIPHER_ECSDSA_OPTIMIZED, ALG_SHA_256, PAD_NULL)
    • (SIG_CIPHER_ECSDSA_OPTIMIZED, ALG_SHA_384, PAD_NULL)
    • (SIG_CIPHER_ECSDSA_OPTIMIZED, ALG_SHA_512, PAD_NULL)
  • Simulator – Preview Features – Add the support to preview features for a given release by using the command line option “-enable-preview” to allow classes to depend on preview features of this release.
  • Eclipse Plugin – Preview Features – Add the ability to build Java Card applets including Preview Features in a Java Card project.
  • Simulator – ARM architecture – A new bundle of the JCDK Simulator is available to run on Linux Ubuntu 24.04 LTS for ARM 32-bit architecture. Its bundle name includes “linux-aarch32”.
  • Simulator - OpenSSL – The Java Card Development Kit Simulator is delivered with the OpenSSL shared library 3.5 updated to the version 3.5.5 for 32-bit machine architecture.

Bug Fixes

  • Simulator – JCAPI – Fix KeyBuilder.buildXECKey() to reject invalid attributes passed as parameter.
  • Simulator – JCAPI – Fix KeyBuilder.buildXECKey() to allocate the correct amount of transient memory for public keys.
  • Simulator – GlobalPlatform – Fix GET DATA (Card Capability Information) with the correct TLV length and add support for the ISO-format command.
  • Simulator – JCAPI – Fix ConstructedBERTag.init(byte tagClass, short tagNumber) and PrimitiveBERTag.init(byte tagClass, short tagNumber) to throw TLVException.INVALID_PARAM when the tag number parameter is negative.
  • Simulator – JCAPI – Fix ConstructedBERTag.init(byte tagClass, short tagNumber) and PrimitiveBERTag.init(byte tagClass, short tagNumber) to throw TLVException.INVALID_PARAM when the tag number parameter is negative.
  • Fix: Corrected ConstructedBERTLV.append() and ConstructedBERTLV.toBytes() behavior when a BER TLV entry had previously been removed using ConstructedBERTLV.delete().
  • Simulator - GlobalPlatform - Fix SecureChannel.unwrap() so its return value also includes the command header length.
  • Simulator - GlobalPlatform - Allow storing Application Provider Identifier tag 5F20 with lengths up to 16 bytes.

System Requirements

This product is targeted for use on PCs with the following operating systems and architectures:

  • Microsoft Windows 11 for x86 architecture
  • Linux for Oracle Linux 9 and Ubuntu 24.04 LTS for x86 architecture
  • Linux Ubuntu 24.04 LTS for ARM 32-bit architecture

The following software must be installed for the Java Card Development Kit Simulator to work:

  • Java Development Kit (JDK): This release has been verified and tested with Oracle JDK 25 (64 bit version) and OpenJDK 25 (64 bit version). Download the JDK software from:

    http://www.oracle.com/technetwork/java/javase/downloads

    Install it according to the instructions on the website.

  • PCSC-Lite: PCSC-Lite for Linux is optional and is required only to communicate with the Java Card Development Kit Simulator on Linux when using the PC/SC interface. This release has been verified and tested with PCSC-Lite 2.3.3, which can be installed following the instructions on the website https://pcsclite.apdu.fr/

  • Eclipse IDE: Eclipse IDE is optional and is required only for using Eclipse plug-in. The Java Card Eclipse Plug-in requires Eclipse 2024-06 (4.32) and JDK 25. Download the Windows Eclipse IDE from the following URL, and install it according to instructions on the website:

    https://www.eclipse.org/

  • Visual Studio Code IDE: Visual Studio Code IDE and the Oracle Java is optional and is required only for integrating a Java Card project within this IDE. The version against which the Java Card Development Kit Simulator has been validated is v1.108. Download the Visual Studio Code IDE from the following URL, and install it according to instructions on the website:

    https://code.visualstudio.com/download

  • Java Extension for Visual Studio Code: Java Extension for Visual Studio Code is optional and is required only for integrating a Java Card project within this IDE. The version against which the Java Card Development Kit Simulator has been validated is v25. Install Java Extension for Visual Studio Code from the following URL, and install it according to instructions on the website: https://marketplace.visualstudio.com/items?itemName=Oracle.oracle-java

Installation

The Java Card Specifications, Development Kit Simulator, and Development Kit Tools must be downloaded and installed individually.

  • See the Downloading the Specification Documents topic of the Java Card Platform Specification Release Notes, Version 3.2 for more details on how to download the Java Card Specification bundle.

  • See the Installation topic of the Java Card Development Kit User Guide for more details on how to install the Java Card Development Kit Simulator and Java Card Development Kit Tools.

Contents of the Development Kit Simulator

This release of the Java Card Development Kit Simulator contains Java Card simulation environment and Eclipse plug-in.

The following table describes the files and directories that are installed in the root installation directory (JC_HOME_SIMULATOR).

Directory/File Description
client Contains client components: an application management service API (AMService.jar file and javadoc documentation), a communication smartcardio API (socketprovider.jar file) and a debugger proxy (jc-debug-proxy.jar file) to manage, communicate, and debug Java Card applications.
drivers For Linux, it contains the IFD Handler (libjcsdkifdh.so) for PCSCLite. For Windows, it contains the driver and its controller (jcsdkPCSC.cat, jcdkPCSC.sys, jcdkPCSCBus.inf, jcdkPCSCCtrl.exe, jcdkPCSCReader.inf). It enables an application to communicate with the Java Card Development Kit Simulator based on PC/SC.
runtime Contains the Java Card Development Kit Simulator binary executable, as well as the OpenSSL shared library 3.5 (32-bit).
samples Contains sample applets and the corresponding client applications.
tools Contains a tool to configure the Java Card Development Kit Simulator (Configurator.jar) with a secure channel protocol key set and a Global PIN.

Known Issues

Windows PC/SC driver

Single Reader Only

You can only add one smart card reader.

Simulated Reader State Not Updated When Simulator Stops

Problem

When the simulator is stopped, the PC/SC stack fails to update the simulated reader state to SCARD_ABSENT. As a result, applications relying on card removal detection may not respond as expected.

Impact

For applications using winscard.h:

  • SCardStatus() may still report SCARD_PRESENT even though the Simulator is no longer running
  • SCardGetStatusChange() can remain blocked despite the Simulator having been stopped
  • SCardConnect() can connect and return successfully even though the Simulator is no longer running

For applications using javax.smartcardio:

  • CardTerminal.waitForCardAbsent() may remain blocked despite the Simulator having been stopped
  • CardTerminal.connect() can connect and return successfully even though the Simulator is no longer running

Workaround

After stopping the Simulator, issue a connection attempt to force a state refresh:

  • Using winscard.h: call SCardConnect() and then call SCardDisConnect() if connect was successful
  • Using javax.smartcardio: call CardTerminal.connect(“*”) and then call Card.disconnect(true) if connect was successful

This probe will detect that the Simulator is stopped and will unblock logic waiting for SCARD_ABSENT.

Recommendation

Always use SCardDisconnect(), when using winscard.h, or Card.disconnect(true), when using javax.smartcardio, before the Simulator is stopped and include timeouts or cancellation where possible to avoid indefinite blocking.

Documentation

The Java Card Documentation web site provides online product documentation for the Java Card Platform.

Document Description
Java Card Platform Specifications. The following specification documents are available for the Java Card Platform, Version 3.2 with Preview Features:

  • Java Card Platform Runtime Environment Specification, Classic Edition, Version 3.2 (PDF format)

  • Java Card Platform Virtual Machine Specification, Classic Edition, Version 3.2 (PDF format)

  • Java Card Platform Application Programming Interface, Classic Edition, Version 3.2 with Preview Features (HTML format)

  • Java Card Platform Specification Release Notes, Version 3.2 with Preview Features (HTML and PDF formats)

Java Card Options List This document describes the list of options available to implement a Java Card platform, based on the Java Card Specifications.
Java Card Development Kit Simulator - User Guide This document describes how to use the Java Card Development Kit Simulator and Eclipse plugin to develop, test and debug applications for Java Card Platform. It is available in HTML and PDF formats.
Java Card Development Kit Tools - User Guide This document describes how to use the Java Card Development Kit Tools to convert and verify applications for Java Card Platform. It is available in HTML and PDF formats.

Product Information

The Java Card Technology website provides useful information about the Java Card product.

Visit the Java Card Technology website to access the most up-to-date information on the following:

  • Product news and reviews
  • Release notes and product documentation

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at https://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit https://www.oracle.com/pls/ topic/lookup?ctx=acc&id=info or visit https://www.oracle.com/pls/topic/lookup?ctx=acc&id=trsif you are hearing impaired.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customer access to and use of Oracle support services will be pursuant to the terms and conditions specified in their Oracle order for the applicable services.