The Security and Trust Services API for J2ME, Part 1

Overview and the Communication APIs

Introduced with the Java Specification Request 177, the Security and Trust Services API (SATSA) optional packages provides APIs for communication with security elements, as well as security APIs for the management of digital signatures, digital certificates, and cryptographic operations.

In this article I'll present an overview of SATSA, cover the communication APIs, and present some information about the reference implementation. Part 2 of this article will cover the SATSA security APIs.

Overview of SATSA APIs

SATSA brings the J2ME and smart card devices, including Java Card platforms, closer together. SATSA defines four optional packages as illustrated in Figure 1:

Two of SATSA packages, together with the Generic Connection Framework (GCF), provide an API that allows J2ME applications to communicate with security elements such as Java Cards, (Universal) Subscriber Identity Module (USIM) and security token smart cards. The other two optional packages provide the security APIs to manage digital signatures, user credentials (digital certificates), and perform cryptography operations. The following table summarizes the SATSA APIs:

Table 1: SATSA Packages

Package Name	Description
SATSA-APDU Communication API
javax.microedition.apdu	Defines the APDUConnection interface, for ISO7816-4 APDU-based communication.
SATSA-JCRMI Communication API
java.rmi	Subset of the J2SE java.rmi package, defines the Remote interface and the RemoteException.
javacard.framework	Subset of Java Card API, it includes a number of Java Card API framework exceptions.
javacard.framework.service	Subset of Java Card API, it includes a Java Card API service exception.
javacard.security	Subset of Java Card API, it includes a Java Card API crypto exception.
javax.microedition.jcrmi	Defines the JavaCardRMIConnection interface, for Java Card RMI-based communication, the RemoteRef interface, a handle for a remote object, and the class RemoteStub, a super-class for stubs.
SATSA-PKI Signature Service API
javax.microedition.pki	Defines class UserCredentialManager, the credential/certificate manager, and the UserCredentialManagerException.
javax.microedition.securityservice	Defines class CMSMessageSignatureService, which provides methods to create signatures and sign content, and the CMSMessageSignatureServiceException.
SATSA-CRYPTO Cryptographic API
java.security	A subset of J2SE java.security package it defines classes and interfaces for the security framework such as Key and PublicKey interfaces, and the classes KeyFactory, MessageDigest and Signature.
java.security.spec	A subset of J2SE java.security.spec package it defines classes and interfaces for key specifications and algorithm parameter specifications such as EncodedKeySpec, X509EncodedKeySpec, AlgorithmParameterSpec and KeySpec.
javax.crypto	A subset of J2SE javax.crypto package it defines the Cipher class for encryption/decryption, and various cryptographic exceptions.
javax.crypto.spec	A subset of J2SE javax.crypto.spec package it defines classes for key specifications.
Generic Connection Framework
javax.microedition.io	GCF Connector with SATSA-specific jcrmi: and apdu: connection support.

The next sections describe the communication and security APIs in more detail.

The SATSA Communication APIs

SATSA communication API supports communication with smart cards using the following methods:

• Application Protocol Data Unit (APDU) protocol.
• Java Card 2.2 JCRMI protocol.

In addition, SATSA supports communication with Universal Subscriber Identity Module (USIM) Application Toolkit or USAT, using the APDU protocol. (U)SIM cards are the small smart cards used in some handsets that contain details about the subscriber, security information and even storage memory. With the right permissions, a J2ME application can access the functionality residing on the SIM card such as the phone book or applets. There are a number of technical constraints that you must be aware of though when communicating with SIM cards; please refer to the SATSA specification for more information.

Communication between a J2ME application and a smart card application is based on a synchronous request/respond model where the J2ME application is a client, and the smart card application a server:

The communication stack on the handset and the card both support ISO 7816 (1-4). The SATSA API is based on ISO 7816-4 APDU, the logical data packets that are exchanged between the J2ME application and the smart card framework. The smart card framework receives and forwards to the appropriate smart card application any incoming command APDU sent by the J2ME application. The smart card application processes the command APDU, and returns a response APDU. This message-passing command/response model is the basis for all communications with smart cards.

SATSA uses the Generic Connection Framework (GCF) for I/O, which introduces two GCF connection interfaces, as illustrated here:

Experienced Java Card developers will find SATSA communications API a familiar territory. With its two GCF connection interfaces SATSA caters to both of the overall programming models for Java Card applications: the APDU-message model and the Java Card RMI object-oriented distributed model:

• APDUConnection allows a J2ME application to exchange APDUs with a smart-card application using the ISO 7816-4 APDUs.
• JavaCardRMIConnection allows a J2ME application to use Java Card RMI client API to invoke remote methods on a Java Card-enabled smart card.

Specifying SATSA Connection Types

GCF connections are created by calling the Connector.open() factory method. One of the arguments to Connector.open() is the connection URL string that indicates the type of connection to create. The SATSA URL connection string has the following format:

protocol:[slotID]; target

Where:

• protocol is either apdu for an APDU-based connection, or jcrmi for a JCRMI-based connection.
• slotID is the number that indicates the slot into which the card is inserted. The slotID field is optional; it defaults to slot number 0, and it can be discovered as described below.
• target is either an Application Identifier (AID) for a smart card application, or is the word "SAT". An AID is a string of five to 16 hexadecimal byte values separated by periods; for example, "A0.0.0.67.4.7.1F.3.2C.3". The AID must be known ahead of time. SAT indicates a connection to a SIM Application Toolkit (SAT).

Because a handset may support more that one smart card, SATSA defines a special property to discover the available smart card slots. This property, called microedition.smartcardslots, can be queried by calling the method System.getProperty() which returns a comma-delimited list of available slots, for example:

microedition.smartcardslots: 0C,1H

The returned slot information consists of two characters per available slot. The first character is the slot number that is used in the connection URL string. The second character indicates if the smart card slot is swappable and if so, if it is hot (H) or cold (C) swappable; hot swappable means the card can be changed while the handset is running, cold swappable means the device must first be turned off. In the above example, 0C,1H indicates the existence of two slots, the cold-swappable slot 0 and hot-swappable slot 1.

Using the SATSA APDU Communications API

The SATSA communications API really simplifies how to perform I/O with smart cards; it is based on the easy to use GCF, and it handles things such as channel and application selection command exchanges between the J2ME application and the smart card device.

The SATSA ISO 7816 APDU communications API consists of a single GCF interface, the javax.microedition.apdu.APDUConnection. This interface defines methods to enter, change, disable, and block Personal Identification Numbers (PIN), to exchange APDUs with a smart card application, and to read the Answer To Reset (ATR) message sent by the smart card when the card is powered up or when it is reset.

GCF connections are created by calling the Connector.open() factory method; for SATSA connections the AID and optionally the slot number are passed in the connection URL string. During the Connector.open() method call, the SATSA implementation handles for the J2ME application activities such as channel and application selection, by sending the appropriate APDU commands to the smart card. Please refer to the SATSA specification for more information.

To exchange APDU commands with a smart card application, the method exchangeAPDU() is used. This method automatically sets the channel number of the associated channel in the CLA byte of the command APDU, sends the command APDU, and blocks until a response has been received from the smart card, or if processing is interrupted (InterruptedIOException). Note that there are restrictions on the APDU commands that can be exchanged: card application selection and MANAGE CHANNEL command APDUs are not allowed to be sent (these are handled by the SATSA implementation), and attempting to do so will result on an IllegalArgumentException being thrown.

When communication with the smart-card is no longer required, the connection must be closed by calling the method Connector.close(); this releases the logical channel that was acquired when the connection was opened to communicate with the smart card. During the Connector.close() method call, the SATSA implementation handles activities on behalf of the J2ME application, such as channel management, by sending the appropriate APDU commands. Please refer to the SATSA specification for more information.

The following code snippet shows how to use an APDUConnection to communicate with the smart application with an AID equal to A1.0.0.67.4.7.1F.3.2C.5 that resides on the smart card in slot 0:

// Setup the command APDU
byte[] commandAPDU = ...;

try {
    // Create an APDUConnection
    String url = "apdu:0;AID=A1.0.0.67.4.7.1F.3.2C.5";
    APDUConnection ac = (APDUConnection) Connector.open(url);

    // Send a command APDU and receive a response APDU
    byte[] responseAPDU = ac.exchangeAPDU(commandAPDU);

    // Process the response
    ...

} catch(Exception e){
    // Handle Exception
    ...
} finally {
   ...
   if (ac != null) {
      // Close connection.
      ac.close();
   }
}

While the format of command and response APDUs is standard and described in the ISO/IEC 7816 specification, the contents of APDUs is application specific. See the article An Introduction to Java Card Technology - Part 2, The Java Card Applet, for an introduction to Java Card Applets, and APDU commands.

The following exceptions may be thrown during APDUConnection connection establishment:

• ConnectionNotFoundException if there is no card or is not powered on.
• SecurityException if the J2ME application is not allowed to access the application with the specified AID.
IOException if no logical channel is available. InterruptedIOException if card was removed/re-inserted.

The following exceptions may be thrown when exchanging APDUs:

• IllegalArgumentException if command APU is null or malformed, or contains a card application selection and MANAGE CHANNEL command; for other reasons please see the SATSA specification.
• SecurityException if the J2ME application does not have the rights to use the API.
• IOException if connection is closed or errors encountered.
• InterruptedIOException if card was removed/re-inserted.

Using the SATSA Java Card RMI Client API

The SATSA Java Card RMI (JCRMI) Client API is based on the Java Card 2.2 specification, which is a subset of the J2SE RMI API. JCRMI provides an object-centric distributed model, in which the APDU communication is abstracted; instead of dealing with APDUs, you deal with objects. This simplifies the programming and integration of Java Card technology-based devices.

As with typical remote invocation systems, the JCRMI Client API is based on a proxy pattern where remote objects are represented by a local stub (and a remote skeleton):

In this model, the J2ME application invokes remote methods via a local stub and a remote skeleton. The local stub is responsible for the following:

• Initializing the remote method call.
• Marshalling the method parameters.
• Transferring the invocation request and waiting for the result of the method.
• Unmarshalling the return value or exception returned.
• Returning the value to the caller. If the returned value is a remote object, a reference to its local stub is returned.

The remote object skeleton is responsible for the following:

• Unmarshalling the method parameters.
• Invoking the method appropriately.
• Marshalling the return value or exception.
• Transferring the result of the method or the appropriate exception.

In the RMI model a server application creates and makes accessible remote objects, and the client application obtains remote references to the server's remote objects, and then invokes remote methods on them. In SATSA JCRMI, the Java Card applet is the server, and the J2ME application is the client. Figure 5 describes in more detail the elements and flow of JCRMI:

Figure 5 shows a J2ME environment with a J2ME client application, remote object stubs, and a JCRMI runtime that together with the stub translates a remote invocation to APDUs. On the security element, in our example a smart card running Java Card, the APDUs are received and dispatched to the JCRMI RMI Service, which translates APDUs to methods calls on objects owned by the smart card application.

A stub generator tool is typically used to generate the JCRMI stub. Stub generators are not discussed in this article, but it suffices to say that creating remote classes and their related stubs is similar to the method in J2SE RMI: an application-specific interface that implements the java.rmi.Remote interface is written, a concrete class that implements the exposed behavior is written, and the JCRMI stub generator is invoked to generate the stub and skeleton.

From the API perspective, SATSA JCRMI Client API consists of stub and application interfaces:

• The stub interfaces, mainly used by local stubs and rarely used by the J2ME applications directly, define the remote reference (RemoteRef) interface and remote stub (RemoteStub) super-class, both defined in package javax.microedition.jcrmi.
• The application interfaces include the GCF javax.microedition.jcrmi.JavaCardRMIConnection interface for JCRMI remote method invocation, a subset of the J2SE java.rmi package.
• Other classes or interfaces include the Remote interface and the RemoteException class, as well as some Java Card-specific exception classes that may be thrown when invoking a Java Card remote object method.

The JavaCardRMIConnection class defines, as the names implies, a GCF Java Card RMI (JCRMI) connection type. JavaCardRMIConnection defines methods to enter, change, disable and block Personal Identification Numbers (PIN). It also defines the method getInitialReference(), which returns the selected Java Card applet's stub object for an initial remote reference.

The following code snippet shows how to create a JavaCardRMIConnection to communicate with the smart application with an AID equal to A1.0.0.67.4.7.1F.3.2C.5 that resides on slot 0. Once a JavaCardRMIConnection has been instantiated, and the reference to the remote object is obtained, the appropriate remote methods can be invoked:

import com.j2medeveloper.MyRemoteObject;
...

try {
    // Create a JavaCardRMIConnection
    String url = "jcrmi:0;AID=A0.0.0.67.4.7.1F.3.2C.3";
    JavaCardRMIConnection jc = (JavaCardRMIConnection)    Connector.open(url);
    MyRemoteObject robj = (MyRemoteObject)   jc.getInitialReference();
    :

    short result = robj.myRemoteMethod();
    :

} catch(Exception e){
    // Handle Exception
    ...
} finally {
   ...
   if (jc != null) {
       // Close connection
       jc.close();
   }
}

The above code snippet, shows how to get a reference to MyRemoteObject by calling the method getInitialReference(), then properly casting the returned reference. Method myRemoteMethod() is then invoked, which returns a short. All the details related to data marshalling and underlying APDU exchanges are taken care of by the SATSA Java Card RMI implementation. Finally the connection is closed, releasing the logical channel that was acquired to communicate with the smart card when the connection is opened; as previously mentioned, when closing the connection SATSA automatically handles the command APDUs for channel management.

Because of the restricted nature of the Java Card environment, there are some constraints to be aware of; these same constraints apply when writing Java Card applets:

• Up to 15 interfaces that can be implemented by a remote class, either directly or indirectly.
• Only the following data types can be used as parameters or returned data during remote method invocation: boolean, byte, short, int, and single-dimension arrays of the same integral data types. In addition, for return values, void and Remote interfaces are valid. Note that support for int is optional, as defined by the Java Card specification. All parameters and return values are exchanged by value, except for remote object references, which is by reference (to the local stub).

The following exceptions may be thrown during JCRMI connection establishment:

• ConnectionNotFoundException if there is no card or is not powered on.
• SecurityException if the J2ME application is not allowed to access the application with the specified AID.
• IOException if no logical channel is available.
• RemoteException if initial remote reference object cannot be created.

To learn more about Java Card applets and the typical steps when developing a Java Card application, see the article, An Introduction to Java Card Technology - Part 2, The Java Card Applet.

MIDP 2.0 Permissions

For SATSA communication, SATSA defines the following MIDP 2.0 permissions:

• To open an APDU connection: javax.microedition.apdu.aid. This permission is only granted to applications in the operator, manufacturer, and third-party trusted domain.
• To open a JCRMI connection: javax.microedition.jcrmi. This permission is only granted to applications in the operator, manufacturer, and third-party trusted domain.
• To open an APDU connection to a SIM Application toolkit: javax.microedition.apdu.sat. This permission is only granted to applications in the operator domain.

Applications request the appropriate permissions by making an entry in the JAD or MANIFEST file, for example:

MIDlet-Permissions: javax.microedition.apdu.aid, javax.microedition.apdu.sat, javax.microedition.jcrmi 

A SecurityException will be thrown when attempting to use a connection without the appropriate permissions being granted.

The Reference Implementation

A reference implementation (RI) for SATSA is available for download from the SATSA product page. This is a complete working binary implementation that is based on CLDC 1.0.4 and MIDP 2.0 reference implementations. For the smart card security element, it uses the Java Card Platform Development Kit 2.2.1 Reference Implementation.

Because the SATSA reference implementation has not yet been integrated with the Wireless Toolkit, there are some manual steps that must be done. Please refer to the SATSA RI Installation Guide for more information.

Summary

The SATSA API provides tighter integration between J2ME applications and smart cards. In this Part 1 of the SATSA article I have introduced the SATSA APIs, covered the SATSA communication APIs that allows J2ME applications to communicate with security elements such as (U)SIM and smart-cards using standard APDU or JCRMI protocols, and pointed you to the reference implementation.

On Part 2 of this article I will cover the SATSA security APIs, which provides developers the APIs to create digital signatures and sign content, manage digital certificates, and encrypt/decrypt information providing secure access to resources over the Internet.

Resources

• Sun's Security and Trust Services API for J2ME (SATSA) Web Site
• SATSA (JSR 177) Specification
• SATSA Developer's Guide
• SATSA Reference Implementation and Release Notes
• Java Card Web Site

Acknowledgements

Many thanks to Zhiqun Chen and Saqib Ahmad of Sun Microsystems for their feedback to this article.

About the Author

C. Enrique Ortiz is a software architect and developer, and a wireless technologist and writer. He has been author or co-author of many publications, a co-designer of Sun Microsystems' the Mobile Java Developer Certification Exam, and an active participant in the wireless Java community and in various J2ME expert groups. Enrique holds a B.S. in Computer Science from the University of Puerto Rico and has more than 15 years of software engineering, product development, and management experience.