C H A P T E R  14

Using SATSA

The Security and Trust Services APIs (SATSA) provide smart card access and cryptographic capabilities to applications running on small devices. JSR 177 (the SATSA specification) defines four distinct APIs as optional packages:

The Sun JavaTM Wireless Toolkit for CLDC emulator fully supports SATSA. This chapter describes how you can use the Sun JavaTM Wireless Toolkit for CLDC to work with SATSA in your own applications.

For a more general introduction to SATSA and using smart cards with small devices, see the SATSA Developer's Guide, which is available at
http://java.sun.com/j2me/docs/satsa-dg/.

The Sun JavaTM Wireless Toolkit for CLDC includes the Java Card Platform Simulator, which you can use to simulate smart cards in the Sun JavaTM Wireless Toolkit for CLDC emulator's slots. The Java Card Platform Simulator is found in.


Windows:

toolkit\bin\cref.exe

Linux:

toolkit/bin/cref


Hereafter we refer to it as simply cref.

If you need to develop your own Java Card applications, download the Java Card Development Kit, available at http://java.sun.com/products/javacard/.


14.1 Card Slots in the Emulator

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

The Sun JavaTM Wireless Toolkit for CLDC emulator is not a real device and, therefore, does not have physical slots for smart cards. Instead, it communicates with a smart card application using a socketprotocol. The other end of the socket might be a smart card simulator or it might be a proxy that talks with real smart card hardware.

The Sun JavaTM Wireless Toolkit for CLDC 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. You can set the socket port number for each slot. Choose Edit > Preferences, then click the SATSA tab. The default ports are 9025 for slot 0 and 9026 for slot 1.

FIGURE 14-1 Setting Port Numbers for Smart Card Slots


Preferences window with SATSA category shown sets Port # for slot 0 and slot 1, card emulator host name and simulator type.


14.2 Using the Java Card Platform Simulator

The basic procedure for testing SATSA applications with the Sun JavaTM Wireless Toolkit for CLDC is as follows:

1. Start cref with a Java Card platform application.

2. Start the Sun JavaTM Wireless Toolkit for CLDC emulator.

When a SATSA application attempts to communicate with a smart card, it uses a socket connection to communicate with cref.

It's important, therefore, to make sure that you start cref with the same port number as one of the slot port numbers you specified in the Sun JavaTM Wireless Toolkit for CLDC preferences.

For example, you could run cref on port 9025 with a prebuilt memory image using a command line like this:

cref -p 9025 -i memory_image.eeprom

The Sun JavaTM Wireless Toolkit for CLDC includes a demonstration application, Mohair, which illustrates how to use SATSA. For detailed instructions on running Mohair, see Appendix A.


14.3 Using the Network Monitor with SATSA

The Sun JavaTM Wireless Toolkit for CLDC can display data exchanged with simulated smart card applications in the network monitor. The network monitor displays Application Protocol Data Units (APDUs) that are exchanged between the emulator and the smart card simulator. It can also show data exchanged using the Java Card Remote Method Invocation (Java Card RMI) protocol. The APDU and JCRMI tabs in the network monitor show data exchanged with a smart card.

The network monitor parses each APDU and shows fields in the request and response as appropriate.

FIGURE 14-2 Viewing an APDU in the Network Monitor


Network Monitor with APDU tab selected


14.4 Adjusting Access Control

Access control permissions and PIN properties can be specified in text files. When the first APDU or Java Card RMI connection is established, the implementation reads the ACL and PIN data from the acl_slot-number in the workdir\appdb directory. For example, an access control file for slot 0 is workdir\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.

14.4.1 Specifying PIN Properties

PIN properties are represented by a pin_data record in the access control file.


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

14.4.2 Specifying Application Permissions

Application permissions are defined in access control file (acf) records.


acf AID fnumbers separated by blanks {
    ace {
         root CA name
         ...
         apdu {
                eight numbers separated by blanks
                ...
         }
         ...
         jcrmi {
                 classes {
                   classname
                   ...
                   }
                    hashModifier string
                    methods {
                   method name and signatiure
                   ...
                 }
         }
         ...
         pin_apdu {
                 id number
            verify | change | disable | enable | unblock
            four hexadecimal numbers
                 ...
         }
         ...
         pin_jcrmi {
                id number
            verify | change | disable | enable | unblock
            method name and signature
                ...
           }
        ...
        }
    ...
}

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, access to an application is restricted by this acf.

The ace record is an Access Control Entry. It can contain root, apdu, jcrmi, pin_apdu, and pin_jcrmi records.

The root record contains one CA name. If the MIDlet suite was authorized using a certificate issued by this CA, this ace grants access to this MIDlet. 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 or jcrmi record describes an APDU or Java Card RMI permission. A missing permission record indicates that all operations are allowed.

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

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

The Java Card RMI permission contains information about the hash modifier (optional), class list, and method list (optional). If the list of methods is empty, an application is allowed to invoke all the remote methods of interfaces in the list of classes, for example:


jcrmi {
    classes {
             com.sun.javacard.samples.RMIDemo.Purse
    }
    hashModifier zzz
    methods {
        debit(S)V
        setAccountNumber([B)V
        getAccountNumber()[B
    }
}

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

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

14.4.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 ff 1 {
  ace {
        root CN=thehost;OU=JCT;O=dummy CA;L=Santa Clara;ST=CA;C=US
  
        pin_jcrmi {
            id 55
            verify enterPIN([B)S
            change changePIN([B[B)S
            disable disablePIN([B)S
            enable enablePIN([B)S
            unblock unblockPIN([B[B)S
           }
  }
}
 
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 0 0 0 62 3 1 c 8 1 {
  ace {
        root CN=thehost;OU=JCT;O=dummy CA;L=Santa Clara;ST=CA;C=US
 
        jcrmi {
                 classes {
                     com.sun.javacard.samples.RMIDemo.Purse
              }
                 hashModifier xxx
                 methods {
                   setAccountNumber([B)V
                   getBalance()S
                   credit(S)V
                 }
  }
}
  ace {
        jcrmi {
                classes {
                     com.sun.javacard.samples.RMIDemo.Purse
                  }
 
                  debit(S)V
                  getAccountNumber()[B
              }
            }
       }
  }
  
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
    }
  }
}