Optional APIs Porting Guide

This appendix discusses the design and porting of the Security and Trust Services API (SATSA) optional package (JSR 177) for the Java ME platform. SATSA is a collection of APIs that provide security and trust services through integration of a security element (SE). For more information about JSR 177, see http://www.jcp.org/en/jsr/detail?id=177.

---

SATSA Code Structure

The SATSA file system is organized as shown in FIGURE 4-1 and FIGURE 4-2. Folders shown in bold in those figures represent the four main parts of the SATSA package and are described in TABLE 4-1:

FIGURE 4-1 SATSA File System Organization

FIGURE 4-2 SATSA File System Organization (Continued)

---

Security Elements

The SATSA specification introduces the SE as a "device" that holds the user's credentials and helps him to cipher and sign messages. This implementation assumes that the SE is compliant with the ISO 7816 standard which defines the SE to be a smart card. If your platform uses an SE that does not comply with ISO 7816, you must rewrite some of the classes in the APDU and PKI packages and the ACL file implementation.

You can access the SE by two means:

• File access - Available for smart cards that support an on-card file system.
• Application oriented access - Available for smart cards that are compatible with Java Card technology or with the (U)SIM Application Toolkit specifications.

This implementation (and the SATSA specification) assumes that only application oriented access is used. This means that to access the SE, the appropriate on-card application must be selected.

According to the PKCS-15 specification and appendix A of the SATSA specification, the implementation can read an access control file from an SE which can publish it. This is the only case where the implementation uses the file access option.

Both methods use APDU commands to communicate with the SE. The SATSA-APDU package is used to provide data exchange with the SE.

---

SATSA-APDU Package

Every SE is assumed to be inserted in a slot. Slots belong to devices (card readers). The platform can support many devices and a device can contain a number of slots. The Java platform layer sees only one device: the platform that operates with (logical) slots. Each slot has a number (index). The current slot must be selected before any data-oriented operation is performed.

The porting layer has to provide transactional access to a slot. None of the operations (except init and finalize) can be performed if the slot is not locked. When the slot is locked, it cannot be locked again. All error information is cleared after an unlock operation. Withdrawal does not perform an unlock operation. Switching the slot number between transactional operations is not allowed.

The SATSA-APDU package has two implementations:

• CardDevice - Can support any number of devices. It provides different interfaces for card device drivers developed in both the C and Java programming languages. You can use both types of drivers simultaneously. This implementation is comprehensive and contains a number of classes and methods.
• Simple - Can support only one device and only provides a C interface. It is simple because it contains only a few classes.

CardDevice Implementation

FIGURE 4-3 shows the SATSA-APDU package from the porting point of view.

FIGURE 4-3 SATSA-APDU Porting Interfaces

The CardDevice implementation has two potential porting layers. The APDUManager class holds the table of Cad objects - one for each card slot. The Cad class implements all functionality needed by the SATSA specification, including re-sending commands and getting the response in accordance with status words. The initialization procedure uses the SlotFactory class for creating CardSlot objects. These are responsible for low-level functionality, for example, locking, sending commands, and resetting.

Usually only one of the two layers is required. In most cases this is Porting Layer II, a native porting layer that must be supported by the target platform.

Porting Layer I is intended for Java platform implementations. For example, the Simulator class uses the CREF emulator as Security Element (the CREF emulator is a part of Java Card Development Kit 2.2)

Porting Layer I

This porting layer is implemented in the Java programming language. The abstract CardDevice class represents any device that can operate a smart card (card reader). If you use a real device, derive a class from CardDevice.

Any device has to know how many card slots it serves. During the initialization process, the device class must report this number to the SlotFactory.

The SlotFactory class uses the values assigned to the properties com.sun.cardreader.deviceClassN and com.sun.cardreader.deviceNumber to determine which classes must be used as CardDevice classes.

The card device class must support slot locking. It must prevent access from native applications and other tasks between the lock and unlock sequence. The APDUManager class is responsible for blocking access from Java programming language threads that are working in this task.

The following steps describe the process required to implement Porting Layer I.

1. Derive new classes from the CardDevice class.

Each card device might require its own derived class.

2. Implement all abstract methods from the CardDevice class.

Use the Simulator class as an example.

3. Define the com.sun.cardreader.deviceClassN and com.sun.cardreader.deviceNumber properties.

The file properties_jsr177_simulator_class.xml (one of the italic entries in FIGURE 4-1) contains the properties that describe card devices. These properties are listed in TABLE 4-2.

You can create a new properties file with your class using properties_jsr177_simulator_class.xml as an example. If you do, remember to update the makefile (subsystem.gmk) accordingly.

Porting Layer II

This porting layer supports the platform's native API and the PlatformCardDevice class is used in place of Porting Layer I. The KNI layer converts native method invocations to native API calls. For a detailed description of porting API data types and functions see the Native API Reference (html/group_satsa.html).

The correct sequence (lock ➝ select slot ➝ operations ➝ unlock) is supported by the Java platform and the KNI layer and is not managed by the porting layer. Access to the locked slot by native applications must be blocked by the porting layer.

1. Define the com.sun.cardreader.deviceClass1 and com.sun.cardreader.deviceNumber properties in properties_jsr177_platform.xml.

On the target device platform, define the property com.sun.cardreader.deviceClass1 to be com.sun.cardreader.PlatformCardDevice and the property com.sun.cardreader.deviceNumber to be 1.

2. Build a card device driver.

Place the porting layer code (the device driver) in a library. Use an ordinary C-compatible static-linking library with a name like libXXXX.a, where XXXX is the name of the device (for example, gemplus)

3. Place the card device driver into the workspace.

Create a directory with an appropriate name. The path to the driver's library must be:

SATSA-root/src/protocol/apdu/platform_api/driver_lib/

SATSA-root is the root of the SATSA workspace.

4. Define card device driver.

Define the environment variable JSR_177_APDU_PLATFORM_API to be the name of device (for example, gemplus) before building the SATSA workspace.

Porting with the JavaCall API

If you are using the JavaCall API, set the build options as follows:

JSR_177_APDU_MANAGER=carddevice

JSR_177_APDU_CARDDEVICE=platformcarddevice

JSR_177_APDU_PLATFORM_API=javacall

or

JSR_177_APDU_MANAGER=simple

JSR_177_APDU_CARDDEVICE (doesn't matter)

JSR_177_APDU_PLATFORM_API=javacall

The JavaCall API for CardDevice consists of five functional groups:

1. Initialization and finalization

2. Data exchange

3. Locking

4. Retrieving information

5. Error handling

All five functional groups are mandatory.

Initialization and Finalization

• javacall_carddevice_init() must initialize the card device
• javacall_carddevice_finalize() must finalize the card device. If no special finalization actions are required, it may do nothing.
• javacall_carddevice_set_property() is used for setting properties. If a JavaCall API implementation doesn't support given property it must return JAVACALL_NOT_IMPLEMENTED.
• javacall_carddevice_select_slot() must select "current" slot for use. If a card device has only one slot this method may do nothing. This method will be called only when the card device is locked (see the locking group).

Data Exchange

There are two operations with a smart card that require data exchange: "reset" and "transfer data". The former means "do power up and receive the answer-to-reset (ATR)". The latter is used for sending and receiving data (APDU) to/from a card.

Data exchange operations may take some time. In this case a data exchange method must return JAVACALL_WOULD_BLOCK. When the operation is completed a JavaCall API implementation must call the javanotify_carddevice_event() callback method. Then, the corresponding ..._finish() method will be called. It must either return JAVACALL_WOULD_BLOCK or fill given buffer with received data.

• javacall_carddevice_reset_start() and javacall_carddevice_reset_finish() must do reset and return an ATR.
• javacall_carddevice_xfer_data_start() and javacall_carddevice_xfer_data_finish() must exchange an APDU.

Locking

Before any data exchange operation is performed a card device must be locked.

The SATSA implementation uses following scenario:

javacall_carddevice_lock

        |

        V

javacall_carddevice_select_slot

        |

        V

any card operation

        |

        V

javacall_carddevice_unlock

The javacall_carddevice_lock method may return JAVACALL_WOULD_BLOCK. In this case, a JavaCall API implementation must call javanotify_carddevice_event() when the device can be locked.

A JavaCall API implementation must guarantee that native applications will not access the card device when it has been locked.

• javacall_carddevice_lock() must lock the card device
• javacall_carddevice_unlock() must unlock the card device

Retrieving Information

• javacall_carddevice_get_slot_count() must return number of device slots. This method will be called once at initialization time.
• javacall_carddevice_is_sat() must return a boolean value: is this slot a SAT slot? This method will be called after any card insertion.
• javacall_carddevice_card_movement_events() must report which insertion/withdrawals were performed with a card. This method will be called before and after any card operation.

Error Handling

The SATSA implementation will send a text message into the error handling system if it supposes that a trouble occurred. In that case an error state must be set. After that the SATSA implementation must be able retrieve all (if allowed by memory limitations) messages concatenated to one string, separated by the new line character. The error state must be clear after that.

• javacall_carddevice_clear_error() must clear the error state.
• javacall_carddevice_set_error() must receive a message and set the error state.
• javacall_carddevice_get_error() must return the concatenated messages and clear the error state.

Simple Implementation of the APDU Package

Java Wireless Client software includes an sample implementation of the APDU package called Simple. The Simple implementation uses Porting Layer II and contains the following four classes.

• Protocol
• APDUManager
• Handle
• Slot

All the classes are located in the following directory:

SATSA_root/src/protocol/apdu/simple/classes/com/sun/	midp/io/j2me/apdu

The Simple implementation uses the same Protocol class as does the CardDevice implementation. APDUManager is a static class with native methods. The Handle and Slot classes only contain data that corresponds to a connection handle and to a device slot.

All the native methods of the APDUManager class are located in SATSA_root/src/protocol/apdu/simple/native.

In comparison to the CardDevice implementation, the Simple implementation has the following features:

• It is faster because it does not call virtual methods.
• It is smaller by about eight kilobytes.
• It supports the asynchronous mode and includes an example that uses native pthreads.
• It supports only one device.
• Its device driver cannot be written in the Java programming language.
• It has a limited buffer for incoming data. The buffer is defined in the Slot class, and you can enlarge it.
• It requires different implementations for different platforms.

Platform API

The Platform API directory (SATSA_root/src/protocol/apdu/platform_api) contains the following different implementations of Porting Layer II.

• stubs - Stub files that allow the system to build correctly but do not do anything.
• simulator - A complete port of the Simulator class. This implementation uses the CREF utility as a Security Element.
• javacall - A JavaCall API port. This contains wrappers for JavaCall API functions. See details in the the JavaCall API documentation.
• driver_lib - A location in which to put the library that contains the card device driver.

See Porting Layer II for details about Porting Layer II.

Build Options

Specify your implementation by setting build options. These options are set using environment variables prior to building the product. These options are used in subsystem.gmk.

The build options are listed and described in TABLE 4-3.

SAT Connection

SAT is the (U)SIM Application Toolkit, an environment for applications that comply with the SAT specification. This environment is different from the Java Card technology runtime environment. When a Java ME technology application wants to communicate with the SAT, it must not select an on-card application. The application invokes events (by sending the ENVELOPE command) that are handled by the on-card SAT environment and then may be sent to registered on-card applications.

The implementation has not been tested against actual SAT applications. For testing purposes an emulator can be found in the SATSA workspace at the following locations:

• SATSA_root/src/tool/javacard/com/sun/satsa/satapplet
• SATSA_root/src/tool/javacard/com/sun/satsa/gsmapplet
• SATSA_root/src/tool/javacard/sim

The SIM emulator is an ordinary Java Card technology applet. Before using it select an on-card application. The property com.sun.midp.io.j2me.apdu.satselectapdu contains the APDU command to select the proper application. If the property is not defined, then no selection is made. This property is defined in the file properties_jsr177.xml.

---

SATSA-CRYPTO Package

The SATSA-CRYPTO optional package defines a subset of the Java SE platform cryptography API. It provides basic cryptographic operations to support the following functionality:

• Message digest creation
• Signature verification
• Encryption using an asymmetric or symmetric cipher
• Decryption using a symmetric cipher

According to the specification, the package does not include an API to create a private key object. Because you cannot create an asymmetric cipher using a private key, an asymmetric cipher can only be used for signature verification and encryption.

Implementation

SATSA-CRYPTO is an optional package. It is implemented independently from other SATSA packages and does not use other SATSA packages APIs.

Implementation of CRYPTO algorithms is based on the functionality provided by the Java Wireless Client software security subsystem's crypto library.

TABLE 4-4 summarizes the algorithms recommended by the JSR 177 specification and the algorithms that are implemented in this release.

Porting Notes

The SATSA-CRYPTO package is implemented entirely in the Java programming language. It has no native code. No external or platform-specific resources are utilized. The only external dependency is on the SSL package that is created using the Java programming language and platform-independent native code. For that reason, the SATSA-CRYPTO package implementation does not have a porting layer or API.

If the cryptographic algorithms are implemented in hardware on your platform, you must create a porting layer and a native API.

---

SATSA-PKI package

This package provides functionality for user credential management that includes creating certificate signing requests, adding user credentials, and removing credentials. The package also provides an API for digital signature generation based on stored credentials.

Implementation

This implementation of the PKI package is based on Appendix D, "WIM Recommended Practice," of the SATSA specification. WIM (Wireless Identity Module) is a PKI-based identity module. It is used for storing keys and certificates and for performing cryptographic operations with these keys. The WIM can be implemented in smart cards, such as (U)SIM cards, or other tamper-resistant hardware. The current version of credential management supports X.509 version 3 certificates. This implementation does not support URIs. The implementation based on the WIM specification is: WAP-260-WIM-20010712-a, Version 12-July-2001.

This implementation assumes the use of an on-card applet that provides WIM functionality. That applet (WIM emulator) is contained in the SATSA workspace. The path to the emulator is SATSA-root/src/tool/javacard/com/sun/satsa/pkiapplet.

The implementation introduces a WIM-compatible command named Generate Public Key Pair. This command is not specified in the WIM specification because the specification anticipates that key pairs are generated as a part of the personalization process. Detailed information about this command can be found in TABLE 4-5 and TABLE 4-6. The property com.sun.satsa.keygen can disable this key generation feature. The value true enables key generation, and false disables it. This property is defined in the file properties_jsr177.xml.

The implementation saves the public key ID (10-byte hash) in the local file storage as _csr.id when the key has already been used for certificate enrollment request (CER) generation. The key IDs must be stored until a new certificate is received. Saving is required to conform to the SATSA specification requirement that an implementation must prioritize keys during CER generation according to the following parameters:

• Unused keys
• Keys used in CERs
• Keys used in certificates

The property com.sun.satsa.store_csr_list is used to manage the save process. The value true enables saving, false (or no value) disables it. This property is placed in the file properties_jsr177.xml. When key IDs are not saved in storage, they are placed in a memory array.

The PKI part of the implementation is placed in the directory SATSA_root/src/classes/com/sun/satsa/pki.

Porting Notes

The PKIManager class provides a basic interface to the off-card WIM application. The PKIManager class uses the WIMApplication class, which provides an interface to the on-card WIM application. If the target device already has mechanisms in place to talk to an on-card WIM application, this class must be replaced with those mechanisms and the PKIManager class must be updated accordingly. Only two classes (PKIManager and Certificate) do not depend on an on-card WIM application. The others are helpers for the WIMApplication class.

If the target device does not have a mechanism in place to talk to the WIM, the implementation can be ported without modification. Note that this implementation has not been tested with an actual WIM, therefore it requires some modification to talk to an actual WIM.

The Dialog class is used to create dialog boxes that do the following:

• Display messages
• Prompt the user for confirmation
• Prompt the user to sign
• Prompt the user to choose a certificate
• Prompt the user to enter new PIN parameters

According to the SATSA specification, this dialog box must be secure and must include security features that cannot be duplicated by any regular Java ME platform application. Therefore, this security requirement cannot be satisfied by the Dialog class in the implementation. On the target platform, this class can be rewritten so that it provides the same basic functionality of the Dialog class. To ensure security, the class must also have one or more unique features that are distinguishable from a user interface generated by external sources such as Java ME platform applications.

---

Static Access Control Mechanism

The SE is able to publish its access control requirements in an access control file (ACF). The ACF is created by the issuer of the application or the SE. The ACF contains an access control list (ACL).

The implementation of the static access control mechanism complies with Appendix A, "Recommended Security Element Access Control," of the SATSA specification.

The path to an implementation of the ACL is SATSA_root/src/protocol/acl/. Two different versions of the implementation are possible. One is based on text files (from the RI) and the other is mandated by the SATSA specification and is based on octet files.

The implementation can retrieve an ACF from security element that satisfies the ISO7816-4 standard. The SATSA and the PKCS-15 specifications partially explain how to find an ACF stored on a card. The implementation performs the following sequence of steps to do that.

1. Look for the DIR file.

The implementation selects MF and then tries to select EF with file ID=2F00.

2. If the DIR file is not found (Step 1 fails) try to select the PKCS-15 application using its AID.

3. If neither the DIR file or the PKCS-15 application are found (Step 1 and Step 2 fail) decide that all permissions must be granted.

The sequence is complete.

4. If the application was successfully selected in Step 2, go to Step 9.

5. Read the DIR file and try to find the PKCS-15 application's AID in it.

6. If the required AID is not found, then decide that all permissions must be granted.

The sequence is complete.

7. Select the DF that corresponds with first DIR entry where the PKCS-15 application's AID is found.

8. If Step 7 fails, then decide that all permissions must be revoked.

The sequence is complete.

9. Look for the ODF.

The implementation tries to select EF with the file ID retrieved from the DIR file or, if it is not specified, with the default file ID=5031.

10. If Step 9 fails, decide that all permissions must be revoked.

The sequence is complete.

11. Read the ODF.

12. Repeat Step 13 through Step 16 for each DODF entry found in the ODF, then go to Step 17.

13. Select the DODF and then read it.

14. If Step 13 fails, go to the next iteration of the loop defined in Step 12.

15. Search through the DODF for an entry with the OID as defined in subsection A.4.2.1 of the SATSA specification.

16. If the required entry is found, parse the access control index file and load permissions as specified in the Appendix A of the SATSA specification.

The sequence is complete.

17. Decide that all permissions must be revoked.

The sequence is complete.

All errors that occur during a given sequence of operations (for example, I/O errors, invalid file structures, broken card problems, and missing card features) lead to the revocation of all permissions. In general, the implementation allows access if it reads a correct PKCS-15 structure (with or without an ACF) and denies access when it cannot verify the existence of an ACF.

Definitions

TABLE 4-7 defines the terms shown in italics in the previous sequence of steps.

TABLE 4-8 defines the acronyms used in the previous steps and shows the specification in which it is specified.

Reference Implementation Version of ACF

In the SATSA RI, implementation of the access control mechanism is based on an access control file (ACF), which is a plain-text file located in permanent storage. The ACF is named acl_N, where N is a slot number. The structure of that ACF is fully described in the RI's porting appendix.

Although Appendix A of the SATSA specification is now mandatory, the RI's version is still supported. To switch between versions, set the variable USE_JSR_177_ACL_TEXT in subsystem.gmk.

The error handling behavior of the RI version differs from Appendix A of the SATSA specification in the following way: if any error occurs when loading the ACF, all permissions must be granted.

Porting Notes

If the security element is compatible with ISO7816, then the access control mechanism can be ported without modification.

If the SE does not support ISO7816-4 commands, then a new file system class must be derived from the FileSystemAbstract class. This new class replaces the AclFileSystem class with new methods for accessing files. The ACSlot class must be updated accordingly.

The PINEntryDialog class is used to create a dialog that is shown to users when they are required to enter PIN values. The implementation of this class was moved from the RI without modification. According to the SATSA specification, this dialog must be secure and must include security features that cannot be duplicated by any regular Java ME platform application. Therefore, this security requirement cannot be satisfied by the PINEntryDialog class in the implementation. On the target platform, this class can be rewritten so that it provides the same basic functionality of the PINEntryDialog class. The class must provide one or more unique features that are distinguishable from a user interface generated by external sources such as Java ME platform applications.

Optional APIs Porting Guide

05-2007

Copyright © 2007, Sun Microsystems, Inc. All rights reserved. SUN PROPRIETARY/CONFIDENTIAL.