Oracle® Java Micro Edition Software Development Kit Developer's Guide Release 3.4 for Eclipse on Windows E37550-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 Oracle Java ME SDK emulator fully supports SATSA. This topic describes how you can use the Oracle Java ME SDK to work with SATSA in your own applications.
If you must develop your own Java Card applications, download the Java Card Development Kit, available at:
http://www.oracle.com/technetwork/java/javacard/overview
Real SATSA devices are likely to have one or more slots that house smart cards. Applications that use SATSA to communicate with smart cards must specify a slot and a card application.
The Oracle Java ME SDK 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 talks with real smart card hardware.
The Oracle 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 Oracle Java ME SDK interface.
You can also change the port values in the device's property file found at:
username\javame-sdk\3.4\work\
devicename
Edit the device.properties
file and modify this line:
runtime.internal.com.sun.io.j2me.apdu.hostsandports = localhost:9025,localhost:9026
start cref -p 9025 -i memory_image.eeprom
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\
devicename\appdb
directory. For example, an access control file for slot 0 might be:
username\javame-sdk\3.4\work\
devicename\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.
Example 18-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 }
Application permissions are defined in access control file (acf
) records. The record format is as follows:
Example 18-2 Access Control File Record Format
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 signature ... } } ... 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.
Example 18-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 } } }
For the demo to work this project must reside in the Oracle Java ME SDK installation's \apps
subdirectory. You must create the apps
directory yourself
Click the File menu and select New Project and in the Categories window select Samples > Java ME SDK 3.4 and single-click SATSADemos. Click Next. Save the sample project in:
installdir\apps\SATSADemos
Click Finish.
Right-click on the project, click Run As > Run Configurations. The Run Configurations window opens. Select the project JAD file on the left. On the right, switch to the Emulation tab where you can set the SDK/Device/Security domain.
Start the instance(s) of cref
from the command line.
Run the project.
Right-click the project, click Properties and then click the Running category. Enable Regular execution and check Specify the Security Domain. Select 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 installdir\apps\SATSADemos\demo2.eeprom start installdir\bin\cref -p 9026 -i installdir\apps\SATSADemos\demo2.eeprom
When 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.
The emulator screen displays the process of exchanging APDUs between eeproms.
To set up the simulated smart card, use cref
, very much like you did for APDUMIDlet
. This time you do not have to specify a port number, and the memory image is different:
start
installdir\bin\cref -i
installdir\apps\SATSADemos\sat.eeprom
When you have the smart card simulator running, run SATSADemos. Select SATMIDlet, select the Menu soft key and select Launch (1). Press Go when prompted.
The emulator screen displays the process of sending envelopes over a SAT connection.
Start cref
from the SDK installation directory:
start
installdir\bin\cref -p 9025 -i
installdir\apps\SATSADemos\pki.eeprom
In the emulator, select Find Slots. After you see the slots found, select the Back soft key.
Select SATSA-PKI Sign test. The following confirmation message appears:
This certificate will be used: Certificate two
Select the OK soft key.
For PIN 1, type: 1234
Select the OK from the menu. 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: Certificate one
Select the OK soft key.
For non repudiation key 1 PIN, type: 2345
Select the soft menu and select OK (option 2). The sign test is complete.
Right-click the project, click Properties and then click the Running category. Enable Regular execution and check Specify the Security Domain. Select maximum from the list.
Start cref
from the SDK installation directory as follows:
start installdir\bin\cref -p 9025 -i
installdir\apps\SATSADemos\demo2.eeprom