Oracle® Java Micro Edition Software Development Kit Developer's Guide Release 3.0.5 for Windows E24265-04 |
|
Previous |
Next |
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:
SATSA-APDU - Enables applications to communicate with smart card applications using a low-level protocol.
SATSA-JCRMI - Provides an alternate method for communicating with smart card applications using a remote object protocol.
SATSA-PKI -Enables applications to use a smart card to digitally sign data and manage user certificates.
SATSA-CRYPTO - A general-purpose cryptographic API that supports message digests, digital signatures, and ciphers.
The Java ME SDK emulator fully supports SATSA. This topic describes how you can use the Java ME SDK 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://download.oracle.com/javame/config/cldc/opt-pkgs/api/security/satsa-dg
.
If you need to develop your own Java Card applications, download the Java Card Development Kit, available at http://www.oracle.com/technetwork/java/javacard/overview/index.html
. This kit is for Windows.
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 Java ME SDK 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 socket protocol. 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 Java ME SDK 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 defaults in the user interface, right click on the device in the Device Selector, and select Properties. By default the Properties window is docked on the upper right of the Java ME SDK interface. You can also change them in the device's property file:
userhome\Application Data\javame-sdk\3.0.5\
directory-number
Edit the device.properties
file and modify this line:
runtime.internal.com.sun.io.j2me.apdu.hostsandports = localhost:9025,localhost:9026
The Java ME SDK includes the Java Card Platform Simulator, which you can use to simulate smart cards in the Java ME SDK emulator's slots. The Java Card Platform Simulator is found in the following location:
installdir\bin\cref.exe
Hereafter we refer to it as simply cref. The basic procedure for testing SATSA applications with the Java ME SDK is as follows:
Start cref
with a Java Card platform application.
Start the 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 Java ME SDK preferences.
For example, to run cref
on port 9025 with a prebuilt memory image, use a command line similar to this:
start cref -p 9025 -i memory_image.eeprom
The Java ME SDK includes a demonstration application, Mohair
, which illustrates how to use SATSA. For detailed instructions on running Mohair
, see Section 20.4.4, "MohairMIDlet".
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\emulator-instance\appdb
directory. For example, an access control file for slot 0 might be:
Documents and Settings\
user\javame-sdk\3.0.5\work\
emulator-instance\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.
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 }
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.
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 } } }
SATSADemos
includes demonstrations of SATSA, the Security and Trust Services APIs. Most of the demonstrations show how to communicate with a smart card. The emulator can communicate with a simulated smart card using a socket protocol. The smart card simulator, cref
, is included with the SDK, as discussed in Section 20.2, "Java Card Platform Simulator (cref)".
For each SATSA demo, start with this sequence:
Start the instance(s) of cref
from the command line.
Be sure to set the project security domain to maximum.
Right-click on the project, select Properties and choose Running. Enable Regular execution and check Specify the Security Domain. Choose maximum from the list.
Run the project.
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.
Right-click on the project, select Properties, and choose Running. Enable Regular execution and check Specify the Security Domain. Choose maximum from the list.
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
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.
SATMIDlet
demonstrates smart card communication with a slight variation on APDU communication.
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:
Right-click on the project, select Properties, and choose Running. Enable Regular execution and check Specify the Security Domain. Choose maximum from the list.
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
.
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.
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.
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
.
Right-click on the project, select Properties, and choose Running. Enable Regular execution and check Specify the Security Domain. Choose maximum from the list.
Type the following from the SDK installation directory:
start installdir\bin\cref -i apps\SATSADemos\sat.eeprom
In the emulator, select SATSA-PKI Sign test. The following confirmation message appears:
This certificate will be used: MohairAuth
Select the OK soft key.
For PIN 1, type: 1234
Select the OK soft key. The following confirmation message appears:
This string will be signed: JSR 177 Approved
Select the OK soft key. The following confirmation message appears:
This certificate will be used: MohairAuth
Select the OK soft key.
For non repudiation key 1 PIN, type: 2345
Select the soft menu and choose OK (option 2).
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.
Right-click on the project, select Properties, and choose Running. Enable Regular execution and check Specify the Security Domain. Choose maximum from the list.
Start cref
from the SDK installation directory as follows:
start installdir\bin\cref -p 9025 -i apps\SATSADemos\demo2.eeprom
Now run JCRMIMIDlet
to see how your application can communicate with a distributed object on the card.