20 JSR 177: Smart Card Security (SATSA)

20.3.1 Specifying PIN Properties

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

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
   }

20.3.2 Specifying Application Permissions

Application permissions are defined in access control file (acf) records. The record format is as follows:

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.

20.3.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
    }
  }
}

20.4.1 APDUMIDlet

This MIDlet demonstrates communication with a smart card using Application Protocol Data Units (APDUs), small packets of data. APDUMIDlet expects to find two simulated smart cards. You can run the smart card simulator using cref, which is part of the Java Card Development Kit. See Section 20.2, "Java Card Platform Simulator (cref)".

The Mohair application includes pre-built memory images that you can use with cref. The memory images contain Java Card applications with which Mohair interacts. The memory images are in the root directory of the Mohair project.

1. Right-click on the project, select Properties, and choose Running. Enable Regular execution and check Specify the Security Domain. Choose maximum from the list.

2. Start up two instances of cref, one for each simulated card slot (assuming the current directory is the SDK installation directory):

   start installdir\bin\cref -p 9025 -i apps\SATSADemos\demo2.eeprom

   start installdir\bin\cref -p 9026 -i apps\SATSADemos\demo2.eeprom

3. Once you have the two smart card simulators running, run SATSADemos. Select APDUMIDlet, select the Menu soft key and select Launch (1). Press Go when prompted.

20.4.2 SATMIDlet

SATMIDlet demonstrates smart card communication with a slight variation on APDU communication.

1. To set up the simulated smart card, use cref, very much like you did for APDUMIDlet. This time you don't have to specify a port number, and the memory image is different:

2. Right-click on the project, select Properties, and choose Running. Enable Regular execution and check Specify the Security Domain. Choose maximum from the list.

3. Start cref:

   start installdir\bin\cref -i apps\SATSADemos\sat.eeprom

   Note that the port number arguments (9025 and 9026 in this example) must match the SATSA port numbers. Also, make sure you use the correct path to sat.eeprom.

4. Once you have the smart card simulator running, run SATSADemos. Select SATMIDlet, select the Menu soft key and select Launch (1). Press Go when prompted.

20.4.3 CryptoMIDlet

CryptoMIDlet demonstrates the general cryptographic features of SATSA. It does not interact with a smart card in any way. Choose the MIDLet and launch it to see the cryptography results. Use the up and down navigation keys to scroll the display.

20.4.4 MohairMIDlet

MohairMIDlet has two functions. The first, "Find slots", displays all the available card slots. Each slot has a number followed by 'C' or 'H' indicating whether the slot is cold-swappable or hot-swappable. After viewing the slots select Back to return to the first screen.

The second part of MohairMIDlet, SATSA-PKI Sign test, uses a smart card to generate a digital signature. As with the earlier demonstrations, you need to run cref with the right memory image to prepare for the connection from MohairMIDlet.

1. Right-click on the project, select Properties, and choose Running. Enable Regular execution and check Specify the Security Domain. Choose maximum from the list.

2. Type the following from the SDK installation directory:

   start installdir\bin\cref -i apps\SATSADemos\sat.eeprom

3. In the emulator, select SATSA-PKI Sign test. The following confirmation message appears:

   This certificate will be used: MohairAuth

   Select the OK soft key.

4. For PIN 1, type: 1234

   Select the OK soft key. The following confirmation message appears:

   This string will be signed: JSR 177 Approved

5. Select the OK soft key. The following confirmation message appears:

   This certificate will be used: MohairAuth

   Select the OK soft key.

6. For non repudiation key 1 PIN, type: 2345

   Select the soft menu and choose OK (option 2).

20.4.5 Running SATSAJCRMIDemo

This application contains a single MIDlet, JCRMIMIDlet, which shows how to communicate with a card application using Java Card RMI, a card-friendly remote object protocol. As with some of the MIDlets in SATSADemos, you need to start up cref with an appropriate memory image.

1. Right-click on the project, select Properties, and choose Running. Enable Regular execution and check Specify the Security Domain. Choose maximum from the list.

2. Start cref from the SDK installation directory as follows:

   start installdir\bin\cref -p 9025 -i apps\SATSADemos\demo2.eeprom

3. Now run JCRMIMIDlet to see how your application can communicate with a distributed object on the card.