What's new in Java Card 3.1

Java Card 3.1 has a bunch of new features. Besides new algorithms and certificates, there's array views, monotonic counters, event handling, NIO byte buffers, and uptime.

Christian Hujer, Software Crafter and CEO / CTO of Nelkinda Software Craft Private Limited
First Published:
by NNelkinda Software Craft Private Limited
Last Modified:
by Christian Hujer
Approximate reading time:
Figure -1: Comparison screenshot

On 16th of January, Oracle released Java Card 3.1 [OracleJDK12Download]. Let's take a look at what's new.

1 Process

In order to see what's new, I've downloaded the Java Card Development Kit 3.0.5 and 3.1. The file relevant for comparison is lib/api_classic.jar

1.1 Comparison Command

For comparison, I've used the following command:

vi -d \
         <(javap -bootclasspath 'Java Card Development Kit 3.0.5u3/lib/api_classic.jar' -p $(jar tf 'Java Card Development Kit 3.0.5u3//lib/api_classic.jar' | grep '\.class$' | sed -e 's/\.class$//' -e 's/\//./g' | sort)) \
         <(javap -bootclasspath 'Java Card Development Kit Simulator 3.1.0/lib/api_classic.jar' -p $(jar tf 'Java Card Development Kit Simulator 3.1.0/lib/api_classic.jar' | grep '\.class$' | sed -e 's/\.class$//' -e 's/\//./g' | sort)) \
Listing 1-1: Shell script for comparing Java Card 3.0.5 and Java Card 3.1

2 The New Stuff

2.1 New Status Word in javacard.framework.ISO7816

In ISO7816, a new status word SW_AUTHENTICATION_METHOD_BLOCKED with value SW12 = 0x6983 is defined.

2.2 Array Views

This is a new feature of the Java Card Virtual Machine, Runtime Environment, and API. Array Views are views to existing arrays which show potentially read-only array slices.

With the help of array views, parts of an array can be shared with another applet without granting access to the entire array, and optionally making the access read-only. That way, it no longer is necessary to create partial array copies for sharing data. This can save substantial amounts of memory.

The API related to array views is in javacard.framework.JCSystem:

package javacard.framework;
public final class JCSystem {
    public static final short ATTR_READABLE_VIEW = 1;
    public static final short ATTR_WRITABLE_VIEW = 2;
    public static native Object makeArrayView(Object, short, short, short, Shareable);
    public static native boolean isArrayView(Object);
    public static native short getAttributes(Object) throws SystemException;
Listing 2-1: The new array view API in javacard.framework.JCSystem

2.3 Resources

Resources is a new feature which allows Java Card cap files to contain other files than classes, just like normal Jar files. These files are identified via a 16 Bit resourceId which is specified when the cap file is built.

package javacard.framework;


public class Resources {
    private Resources() {}
    public static Resources getResources() {}
    public short getSize(short resourceId) throws IOException;
    public byte[] getView(short resourceId) throws IOException;
    public byte[] getView(short resourceId, short ofs, short len) throws IOException;

2.4 javacard.framework.SerialCom

This interface does not appear in the API specification. Whether that was intentional or a mistake, I do not know. Either this interface is not supposed to be public. In that case, it should not have been included in lib/api_classic.jar in the first place. Or this interface is meant to be public, and the public modifier was forgotten in the source file.

2.5 Event Handling

Java Card 3.1 introduces event handling. Event handling is already in use in ETSI specifications for SIM/UICC. We'll have to wait and see whether this new event handling mechanism is going to bring any benefits in this context. The idea is to have a generic event handling mechanism independent from any spec that's built on top of Java Card. That's a good idea, it just comes a bit late.

2.6 New I/O arrives at Java Card

With Java Card 3.1, New I/O aka NIO arrives at Java Card. This should make reading/parsing and writing buffers easier. The implementation on Java Card only provides a ByteBuffer, but that should be sufficient for Java Card. The implementation also provides a ByteOrder enum to specify the byte order for operations dealing with short and int.

2.7 Uptime and TimeDuration

Java Card can now, to a limited extent, deal with time. The class javacardx.framework.time.TimeDuration deals with elapsed time of various precision. Instances of TimeDuration can be obtained via the factory method getInstance(byte memoryType) or getInstance(byte memoryType, short amount, short unit). The durations supported range from microseconds to days.

The class javaxardx.framework.time.SysTime provides a method uptime() which can store an estimated time elapsed since system boot in microseconds resolution in the supplied TimeDuration argument.

The assumption here is that smart cards do have system timers anyway, which they need for implementing the timings of the I/O protocols like ISO 7816. Effectively, that's what will be used for the implementation. This does not mean that Java Cards implementing this feature will have a battery backed clock. Also, beware of the precision. The frequency of the hardware clock may, depending on the hardware, vary up to 10%. Also, while in sleep mode between APDUs, a lot of cards stop their clock. Elapsed time measured from SysTime.uptime() should thus be treated as a ball-park figure only.

Still, this feature could be used for various things:


This addition was long overdue. Practically, cards had to deal with certificates ever since, but the certificate handling had to be done in the application. Support was only there for keys, encryption, decryption, key exchange, message digests, and digital signatures. Finally, direct support for certificates has been added to the Java Card API.

2.9 Key Derivation Functions

This is another addition that some people might have been waiting for. Finally, Key Derivation Functions have arrived in the Java Card API.

2.10 New Algorithms

As usual, every new version of Java Card gets an update regarding the list of supported algorithms.

2.10.1 KeyAgreement

Two new key agreements are supported:

2.10.2 KeyBuilder

Several new types have been added:

Two new algorithm types have been added:

2.10.3 MessageDigest

One new algorithm has been added:

2.10.4 Signature

Four new algorithms have been added:

2.10.5 Cipher

Six new cipher algorithms have been added:

Two new padding schemes have been added:

Two new algorithms have been added:


The new class provides, as the name suggests, a monotonic counter. One specialty about the MonotonicCounter is that, while all its operations are atomic, it does not participate in transactions. Any update to MonotonicCounter happens in a transaction of its own, which is committed immediately, regardless of whether or not a normal transaction is already going on. This is necessary for security reasons, and you may know this type of behavior for special classes already from class javacard.framework.OwnerPIN.

3 Conclusion

The update shows that Java Card Classic is alive and kicking. The new algorithms are the expected house keeping. ByteBuffer, Resources, and array views are welcome additions to the API. I'm skeptical about how popular the new event handling is going to be. I wish it all the best, but I also recognize how slow this market moves.