Establishing trust is important for IMlet suites that use security-sensitive APIs. Signing an IMlet suite's JAR file allows the suite to be trusted. A JAR file is signed with the jadtool
utility. A copy of the jadtool
utility is provided with the Oracle Java ME Embedded software bundle.
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 it is valid, and its Message Digest Algorithm 5 (MD5) and Secure Hash Algorithm (SHA) fingerprints.
This section explains how to use the JadTool
utility through an example that signs a hypothetical IMlet suite named ImaginaryIMlet.
Note:
ImaginaryIMlet is not an actual IMlet suite. No ImaginaryIMlet files are included with this release.
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
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.
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 [-useSha256]
[ -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.2. 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.