| Tools Guide |    
|
| Tools Guide |
|
| C H A P T E R 2 |
|
Signing a MIDlet Suite's JAR File |
Trusted MIDlets can typically access more protected functionality than untrusted ones. As a result, establishing trust is important for MIDlet suites that use security-sensitive APIs. Signing a MIDlet suite's JAR file allows the suite to be trusted. A JAR file is signed with the JadTool utility provided with Java Wireless Client software.
The JadTool utility signs a JAR file by adding a certificate and the JAR file's digital signature to a Java Application Descriptor (JAD) file. Adding a certificate and a JAR file's digital signature to a JAD file are separate steps. You must complete both steps to sign a JAR file. The steps are in Instructions for Using JadTool.
You can also use the JadTool utility to obtain information about a certificate in a JAD file. The information can include the name of the entity that issued the certificate, the certificate's serial number, the dates between which is it valid, and its MD5 and SHA fingerprints.
This chapter describes the use of the JadTool utility, including an example. It has the sections:
This section explains how to use the JadTool utility through an example that signs a hypothetical MIDlet suite, ImaginaryMIDlet.
|
Note - ImaginaryMIDlet is not an actual MIDlet suite. No ImaginaryMIDlet files are included with this release. |
The example uses the key pair provided with Java Wireless Client software. The key pair is in the j2se_test_keystore.bin file, which is a keystore managed with the Java SE platform's keytool utility. For information on the keytool utility, see
http://java.sun.com/j2se/1.4/docs/tooldocs/win32/keytool.html.
After you build an implementation of the Java Wireless Client software, j2se_test_keystore.bin is located in the installDir/midp/bin directory. The password for the file is keystorepwd. The alias of the key pair is dummyca. The private key password is keypwd. The file is provided for testing purposes.
For MIDlet suites on end-user devices, use an RSA key pair backed by a certificate or certificate chain from a certificate authority. You must import the certificate or certificate chain into a Java SE platform's keystore with the Java SE platform's keytool utility.
The JadTool utility is packaged in a JAR file, JadTool.jar, in the
installDir/midp/bin directory.
|
1. Open a command prompt or terminal window.
2. Change your current directory to the directory that holds your MIDlet's JAR and JAD files.
For example, if the JAR and JAD files are in the directory $HOME/myMIDlets/, issue the following command:
$ cd $HOME/myMIDlets/
3. Add the certificate for your public key pair to the JAD file using the JadTool utility.
The JadTool utility adds the certificate as the value of an attribute named MIDlet-Certificate-m-n, where m is the number of the certificate chain (it defaults to one but you can provide a different number with the -chainnum switch), and n is an integer that, for new certificates, begins at one and increments by one each time you add a new certificate to the JAD file.
For example, if installDir is $HOME/jwc2.0, the following command adds the certificate as the value of the attribute MIDlet-Certificate-1-1 to the example JAD file:
$ java -jar $HOME/jwc2.0/midp/bin/JadTool.jar -addcert -alias dummyca -storepass keystorepwd -keystore $HOME/jwc2.0/midp/bin/j2se_test_keystore.bin -inputjad ImaginaryMIDlet.jad -outputjad ImaginaryMIDlet.jad
4. (Optional) Verify that the certificate is added to the JAD file by using the JadTool utility to list the certificate in the JAD file.
$ java -jar $HOME/jwc2.0/midp/bin/JadTool.jar -showcert -certnum 1 -inputjad ImaginaryMIDlet.jad
Subject: C=US, ST=CA, L=Santa Clara, O=dummy CA, OU=JCT, CN=thehost
Issuer : C=US, ST=CA, L=Santa Clara, O=dummy CA, OU=JCT, CN=thehost
Serial number: 3d3ece8a
Valid from Wed Jul 24 08:58:02 PDT 2002 to Sat Jul 21 08:58:02 PDT 2012
Certificate fingerprints:
MD5: 87:7f:5e:64:c8:dd:b4:bf:35:39:76:87:99:9b:68:82
SHA: 9d:c0:88:ce:08:83:cd:e6:fe:13:8b:26:f6:b4:df:e2:da:3c:25:98
5. If you have a key pair backed by a certificate chain, import the intermediate certificates.
Import the intermediate certificates using the JadTool utility with the -addcert switch shown in Step 3, taking care to use the correct chain order.
The XXXX company provides a certificate that vouches for your key pair, the WidgetCertificates company vouches for the XXXX certificate, and VeriSign vouches for the WidgetCertificates certificate.
Import the XXXX certificate followed by the WidgetCertificate. The XXXX certificate is MIDlet-Certificate-1-2 and the WidgetCertificate certificate is MIDlet-Certificate-1-3.
|
Note - You do not import the certificate of the root CA. In this example, the certificate is from VeriSign. The root certificate is on the device. |
6. Sign the JAR file using the JadTool utility.
The JadTool utility signs the JAR file, base64 encodes the signature, and stores it as the value of the MIDlet-Jar-RSA-SHA1 attribute of the output JAD file.
|
Note - The key used to sign the JAR file must be from the same Connector Architecture keystore entry as key pair specified in Step 3. The JadTool utility does not check that the JAR file is signed with a keystore entry that has a certificate in the JAD file. |
$ java -jar $HOME/jwc2.0/midp/bin/JadTool.jar -addjarsig -keystore $HOME/jwc2.0/midp/bin/j2se_test_keystore.bin -alias dummyca -storepass keystorepwd -keypass keypwd -jarfile ImaginaryMIDlet.jar -inputjad ImaginaryMIDlet.jad -outputjad ImaginaryMIDlet.jad
A JAD file can have more than one certificate, but it can hold the signature for only one JAR file. When a certificate in the JAD file expires, you must add a new certificate and re-sign the JAR file. When re-signing the JAR file, the JadTool utility overwrites the current digital signature with the new one.
The following summarizes the JadTool utility command and options:
java -jar JadTool.jar
[ -addcert -alias keyAlias [ -keystore keystore ] [ -storepass password ] [ -certnum certNumber ] [-chainnum chainNumber ] [-encoding encoding ] -inputjad inputJadFile -outputjad outputJadFile ]
[ -addjarsig [ -jarfile jarFile ] -alias keyAlias [ -keystore keystore ] -storepass password -keypass keyPassword [ -encoding encoding ] -inputjad inputJadFile -outputjad outputJadFile ]
[ -help ]
[ -showcert [ ( [ -certnum certNumber ] [ -chainnum chainNumber ] ) | -all ] [ -encoding encoding ] -inputjad inputJadFile ]
The JadTool utility supports the following options:
Running the tool without options returns the same information as the
-help option.
Adds a certificate to a JAD file. To do this, this utility first creates the certificate from the entry identified by keyAlias in keystore. The keystore, if provided, must be a Connector Architecture keystore (a file containing data such as key entries in a format that the Java SE platform can use). If keystore is not provided, its default, $HOME/.keystore, is used. If keystore requires a password to access its contents, password must be provided.
After creating the certificate and attribute name, this utility concatenates the contents of inputJadFile with the new certificate and writes it as outputJadFile.
|
Note - You can use the same file for the inputJadFile and outputJadFile. |
The certificate is in the JAD file as the value of an attribute named
MIDlet-Certificate-m-n, where:
If inputJadFile uses an encoding other than UTF-8 (ASCII with unicode escapes), encoding must be specified. This utility uses the same encoding for reading inputJadFile and writing outputJadFile.
Creates a digital signature for jarFile. If jarFile is not specified, the value of the MIDlet-Jar-URL attribute from inputJadFile is used. The attribute's value must be a valid HTTP URL.
This utility creates a digital signature for the JAR file using the private key identified by keyAlias in keystore. If keystore is not provided, its default is
$HOME/.keystore. This utility gets the key from keystore using storePassword and keyPassword, and creates the signature with it using the EMSA-PKCS1-v1_5 encoding method of PKCS #1, version 2.0. See RFC 2437 at
http://www.ietf.org/rfc/rfc2437.txt.
After creating the signature, this utility concatenates the contents of inputJadFile with the signature, and writes it as outputJadFile. The signature is base64 encoded, and is in the output JAD file as the value of the
MIDlet-Jar-RSA-SHA1 attribute.
If inputJadFile uses an encoding other than UTF-8 (ASCII with unicode escapes), encoding must be specified. This utility uses the same encoding for reading inputJadFile and writing outputJadFile.
Prints information about either all certificates, or the certificate that corresponds to the given certNumber and chainNumber in the inputJadFile. The option -all cannot be combined with the -certnum and -chainnum options.
The chainNumber of a certificate is the m in the JAD file's MIDlet-Certificate-m-n attribute, while the certNumber is the n. For example, to show the certificate that is the value of attribute
MIDlet-Certificate-2-3, the chainNumber must be 2 and certNumber must be 3. If certNumber or chainNumber are not provided (and the -all option is not used), the utility uses a 1.
The information printed includes the certificate's subject, issuer, serial number, dates between which it is valid, and fingerprints (md5 and SHA). The attributes in the subject and issuer names are shown in reverse order from what is in the certificate (a side effect of using the Java SE platform certificate API). As a result, the names might not match what is returned from other tools that display a certificate's subject and issuer names.
If inputJadFile uses an encoding other than UTF-8 (ASCII with unicode escapes), encoding must be specified. The tool uses the same encoding for reading inputJadFile and writing outputJadFile.
| Tools Guide | 05-2007 |
|
Copyright © 2007, Sun Microsystems, Inc. All rights reserved. SUN PROPRIETARY/CONFIDENTIAL.
Using the JadTool Utility