C Signing an IMlet Suite's JAR File

C.1 Instructions for Using JadTool

This section explains how to use the JadTool utility through an example that signs a hypothetical IMlet suite named ImaginaryIMlet.

The example uses the key pair provided with the 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://download.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html.

After you build an implementation of the software, j2se_test_keystore.bin is located in this directory:

{OUTPUT-Dir}/meep/bin/i386

Where {OUTPUT-Dir} is the directory that contains the output of your builds of the Oracle Java ME Embedded software.

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 IMlet 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 named JadTool.jar in this directory where {OJMEE-Dir} is the base directory of the Oracle Java ME Embedded installation:

{OJMEE-Dir}\toolkit-lib\process\jadtool\code

C.2 Using the JadTool Utility

1. Open a Windows command prompt.

2. Change your current directory to the directory that holds your IMlet's JAR and JAD files.

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 {OUTPUT-Dir}/binaries is C:\jme\src\output\binaries, the following command adds the certificate as the value of the attribute MIDlet-Certificate-1-1 to the example JAD file:

   C:\myIMlets>java -jar %OJMEE_HOME%\toolkit-lib\process\jadtool\code\JadTool.jar -addcert -alias dummyca -storepass keystorepwd -keystore C:\jme\src\output\midp\bin\i386\j2se_test_keystore.bin -inputjad ImaginaryIMlet.jad -outputjad ImaginaryIMlet.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.

   C:\myIMlets>java -jar %OJMEE_HOME%\toolkit-lib\process\jadtool\code\JadTool.jar -showcert -certnum 1 -inputjad ImaginaryIMlet.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.

   For example:

   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 Java SE 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.

   For example:

   C:\myIMlets>java -jar %OJMEE_HOME%\toolkit-lib\process\jadtool\code\JadTool.jar -addjarsig -keystore C:\jme\src\output\midp\bin\i386\j2se_test_keystore.bin -alias dummyca -storepass keystorepwd -keypass keypwd -jarfile ImaginaryIMlet.jar -chainnum 2 -inputjad ImaginaryIMlet.jad -outputjad ImaginaryIMlet.jad

C.3 Handling Expired Certificates

A JAD file can have multiple 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.

C.4 Options Summary

The JadTool utility supports the following options:

• none

  Running the tool without options returns the same information as the -help option.

• -addcert -alias keyAlias [ -keystore keystore ] [ -storepass password ] [ -chainnum chainNumber ] [ -certnum certNumber ] [ -encoding encoding ] -inputjad inputJadFile   -outputjad outputJadFile

Adds a certificate to a JAD file. To add a certificate, this utility first creates the certificate from the entry identified by keyAlias in keystore. The keystore, if provided, must be a Java Cryptography 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, {User_Home_Dir}/.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.

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:

• m is chainNumber, or 1 if it is not provided. A JAD file can contain multiple certificate chain.

• n is certNumber. The value certNumber depends on whether the new certificate replaces an existing certificate. If the certificate is a replacement, then certNumber must be the number of the certificate to replace. For example, if the new certificate would replace the one stored as the value of attribute MIDlet-Certificate-1-3, then certNumber must be 3. If the certificate is new, certNumber is ignored.

  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.

• -addjarsig [ -jarfile jarFile ] -alias keyAlias [ -keystore keystore ] -storepass storePassword -keypass keyPassword [ -encoding encoding ] [-chainnum chainNumber ] -inputjad inputJadFile -outputjad 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 {User_Home_Dir}/.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-m attribute where m is chainNumber, or 1 if it is not provided. This number corresponds to the value for m in the MIDlet-Certificate-m-n 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.

• -help

  Prints a usage summary.

• -showcert [ ( [ -certnum certNumber ] [ -chainnum chainNumber ] ) | -all ]  [ -encoding encoding ] -inputjad inputJadFile

  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.