20 JSR 177: Smart Card Security (SATSA)

This topic describes how you can use Oracle Java ME SDK 8 to work with SATSA in your applications. JSR 177: Security and Trust Services API (SATSA) for J2ME provides smart card access and cryptographic capabilities to applications running on small devices. The SATSA specification defines several APIs as optional packages. The Oracle Java ME SDK 8 emulator supports the following SATSA packages:

SATSA-APDU: Enables applications to communicate with smart card applications using a low-level protocol.
SATSA-CRYPTO: A general-purpose cryptographic API that supports message digests, digital signatures, and ciphers.

For a more general introduction to SATSA and using smart cards with small devices, see the SATSA Developer's Guide at http://www.oracle.com/technetwork/index.html.

To develop your own Java Card applications, download the Java Card Development Kit at http://www.oracle.com/technetwork/java/javame/index.html.

Card Slots in the Emulator

SATSA devices are likely to have one or more slots that hold smart cards. Applications that use SATSA to communicate with smart cards must specify a slot and a card application.

The Oracle Java ME SDK 8 emulator is not an external device and, therefore, does not have physical slots for smart cards. Instead, it communicates with a smart card application using a socket protocol. The other end of the socket might be a smart card simulator, or it might be a proxy that communicates with smart card hardware.

The Oracle Java ME SDK 8 emulator includes two simulated smart card slots. Each slot has an associated socket that represents one end of the protocol that is used to communicate with smart card applications.

The default card emulator host name is localhost, and the default ports are 9025 for slot 0 and 9026 for slot 1. These port defaults are a property of the device. To change the port numbers, right-click the device in the Device Selector, and select Properties.

Adjusting Access Control

Access control permissions and PIN properties can be specified in text files. When the first APDU connection is established, the implementation reads the ACL and PIN data from a file named acl_ followed by a slot number, located in the device's configuration directory. For example, the access control file for slot 0 on the EmbeddedDevice1 device is:

userdir\javame-sdk\8.0\work\EmbeddedDevice1\appdb\acl_0

If the file is absent or contains errors, the access control verification for this slot is disabled.

The file can contain information about PIN properties and application permissions.

Specifying PIN Properties

PIN properties are represented by a pin_data record in the access control file. The record has the following format:

Example 20-1 PIN Properties Example

pin_data {
    id number
    label string
    type       bcd | ascii | utf | half-nibble | iso
    min        minLength
    max        maxLength
    stored     storedLength
    reference  byte
    pad        byte - optional
    flag       case-sensitive | change-disabled | unblock-disabled
               needs-padding | disable-allowed | unblockingPIN
   }

Specifying Application Permissions

Application permissions are defined in access control file (acf) records. The record has the following format:

Example 20-2 Access Control File Record Format

acf AID fnumbers separated by blanks {
    ace {
         root CA name
         ...
         apdu {
                eight numbers separated by blanks
                ...
         }
         ...
         pin_apdu {
                 id number
            verify | change | disable | enable | unblock
            four hexadecimal numbers
                 ...
         }
         ...
    }
    ...
}

The acf record is an access control file. The AID after acf identifies the application. A missing AID indicates that the entry applies to all applications. The acf record can contain ace records. If there are no ace records, then access to an application is restricted by this acf.

The ace record is an access control entry. It can contain root, apdu, and pin_apdu records.

The root record contains one certification authority (CA) name. If the IMlet suite was authorized using a certificate issued by this CA, the ace grants access to this IMlet. A missing root field indicates that the ace applies to all identified parties. One principal is described by one line. This line must contain only the word root and the principal name, for example:

root CN=thehost;OU=JCT;O=dummy CA;L=Santa Clara;ST=CA;C=US

The apdu record describes an APDU permission. A missing permission record indicates that all operations are allowed.

An APDU permission contains one or more sequences of 8 hexadecimal values, separated by blanks. The first 4 bytes describe the APDU command, and the other 4 bytes are the mask, for example:

apdu {
     0 20  0 82  0 20  0 82
    80 20  0  0 ff ff  0  0
}

All the numbers are hexadecimal. Tabulation, blank, CR, and LF symbols are used as separators. Separators can be omitted before and after braces ({ }).

The pin_apdu records contain information necessary for PIN entry methods, which is the PIN identifier and APDU command headers, or remote method names.

Access Control File Example

A sample control file is provided in Example 20-3.

Example 20-3 Access Control File Example

pin_data {
  label   Unblock pin
  id        44
  type      utf
  min       4
  stored    8
  max       8
  reference 33
  pad       ff
  flag      needs-padding
  yflag     unblockingPIN
}
pin_data {
  label     Main pin
  id        55
  type      half-nibble
  min       4
  stored    8
  max       8
  reference 12
  pad       ff
  flag      disable-allowed
  flag      needs-padding
}
 
acf a0 0 0 0 62 ee 1 {
  ace {
    root CN=thehost;OU=JCT;O=dummy CA;L=Santa Clara;ST=CA;C=US
 
    pin_apdu {
            id 55
            verify 1 2 3 1
            change 4 3 2 2
            disable 1 1 1 3 
            enable 5 5 5 4
            unblock 7 7 7 5
        }
  }
}
 
acf a0 00 00 00 62 03 01 0c 02 01 {
  ace {
        root CN=thehost;OU=JCT;O=dummy CA;L=Santa Clara;ST=CA;C=US
        apdu {
               0 20  0 82  0 20  0 82
               80 20  0  0 ff ff  0  0
             }
        apdu {
               80 22  0  0 ff ff  0  0 
             }
        }
  }
acf a0 00 00 00 62 03 01 0c 02 01 {
 
  ace {
    apdu {
        0 20 0 82 ff ff ff ff
    }
  }
}
 
acf a0 00 00 00 62 03 01 0c 06 01 {
 
  ace {
    apdu {
        0 20 0 82 ff ff ff ff
    }
  }
}