The JadTool Utility

JadTool — add certificates to and see certificates in a Java™ application descriptor (JAD) file; create a digital signature of a JAR file, and add that signature to a JAD file.

Synopsis

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 ]

Description

The JadTool utility signs a JAR file, which means that it adds a certificate and the JAR file’s digital signature to a JAD file. Signing a JAR file is one way that a MIDP environment that includes security might trust a MIDlet suite. Trusted MIDlet suites typically have more permissions to use protected, security-sensitive APIs and functionality than untrusted MIDlet suites.

Adding a certificate and a JAR file’s digital signature to a JAD file are separate steps, both of which must be completed to sign a JAR file. A JAD file can have more than one certificate, but can hold the signature for only one JAR file. When a certificate in the JAD file expires, a new certificate must be added to the it, and the JAR file re-signed. (The JadTool utility will overwrite the digital signature it currently holds with the new signature.)

Note – It is up to the user of the JadTool utility to ensure that the certificate in the JAD file is from the same JCA keystore entry as the one used to sign the JAR file.

The JadTool utility can also provide information about a certificate in a JAD file, including 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.

Options

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 do this, this utility first creates the certificate from the entry identified by keyAlias in keystore. The keystore, if provided, must be a JCA keystore (a file containing data such as key entries in a format that the Java 2 Platform, Standard Edition (J2SE™) 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. 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.

-addjarsig [ -jarfile jarFile ] -alias keyAlias [ -keystore keystore ]
-storepass storePassword -keypass keyPassword
[ -encoding encoding ] -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
$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.

-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, then chainNumber should be 2 and certNumber should be 3. If certNumber or chainNumber are not provided, this 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 J2SE platform certificate API). As a result, the names may 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.

Examples

In the following examples the JCA keystore is midpInstallDir\bin\j2se_test_keystore.bin. The password for the keystore is keystorepwd. The keystore has RSA key pair with an alias of dummyca; it has a password of keypwd.

Adding a Certificate to a JAD file

The following command creates a new JAD file that contains the contents of the input JAD file and a certificate created from the specified key:

c:\midp2.0fcs> java -jar bin/JadTool.jar -addcert -alias dummyca -keystore bin/j2se_test_keystore.bin -storepass keystorepwd -inputjad example/pushdemo.jad -outputjad example/pushdemo-w-mykey.jad

Viewing a Certificate

The following command shows the certificate associated with certificate number two (and, by default, chain number one) in the named JAD file:

c:\midp2.0fcs> java -jar bin/JadTool.jar -showcert -certnum 2 -inputjad example/pushdemo-w-mykey.jad 
Subject: C=myserver, O=Sun Microsystems 
Issuer : C=myserver, O=Sun Microsystems 
Serial number: 3cf7e309 
Valid from Sun Jul 28 15:06:50 PDT 2002 to Wed Jul 25 15:06:50 PDT 2012 
Certificate fingerprints: 
  MD5: df:b1:40:a7:3c:4d:5b:f5:91:27:68:86:9c:a6:68:9e 
  SHA: 20:c4:1e:53:cc:cd:d0:7e:eb:a3:64:57:c2:1f:eb:88:23:cc:aa:25

Signing a JAR File

c:\midp2.0fcs> java -jar bin/JadTool.jar -addjarsig -alias dummyca -keystore bin/j2se_test_keystore.bin -storepass keystorepwd -keypass keypwd -jarfile example/pushdemo.jar -inputjad example/pushdemo-w-mykey.jad -outputjad example/pushdemo-w-certsig.jad

Appendix A