JAD Tool

Summary

The JAD Tool provides a command line interface to sign MIDlet suites using public key cryptography according to the MIDP specification. Signing a MIDlet suite is the process of adding the signer certificate(s) and the digital signature of the JAR to a JAD.

The JAD Tool only uses certificates and keys from Javatm Standard Edition (J2SE) keystores. J2SE provides the command line tool to manage J2SE keystores.

The general usage for the JAD Tool is (from the MIDP home directory):
java -jar bin/JadTool.jar (command followed by arguments for the command)
The JAD Tool provides the following commands to: For shell script use, when a command is successful, the status code upon completion will be "0" and if there is an error it will be "-1".

General Argument Parsing Considerations

Properly producing user friendly command line argument errors requires a great deal of code, and since this tool is not intended for the general public, this tool with have very simple option parsing that will lead to to some less then user friendly error conditions. Like the J2SE "java" command, any potentially valid value for an option will be accepted for that option even if it looks like a option flag. No positive case will be disallowed to make the errors more user friendly. Basically the tool will make only ensure that option values are formated according to the specification of the underlying Java APIs.

JAD File Arguments

The argument for the input JAD filename is "-inputjad" followed by a filename. The argument for the output JAD filename is "-outputjad" followed by a filename. The filenames can any valid name the file system allows. If a command only reads a JAD, it is an error to give an output JAD. If the input and output JAD filenames are the same the output JAD will replace the input JAD.

The default character encoding for a JAD is UTF-8, to the override this, use the argument "-encoding" followed by an alternate encoding.

Display Usage Help Text

The command to display help text is "-help". There are no arguments for the command. The usage text is also displayed when JAD Tool arguments are not in the correct format or missing. The usage text is:
JadTool arguments:
-help
-addcert
        -alias <key alias> [-storepass <password>] [-keystore <keystore>]
        [-certnum <number>] [-chainnum <number>]
        [-encoding <encoding>] -inputjad <filename> -outputjad <filename>
-addjarsig
        [-jarfile <filename>] -keypass <password> -alias <key alias>
        [-storepass <password>] [-keystore <keystore>] [-encoding <encoding>]
         -inputjad <filename> -outputjad <filename>
-showcert
        [([-certnum <number>] [-chainnum <number>]) | -all]
        [-encoding <encoding>]  -inputjad <filename>

        The default for -encoding is UTF-8.
        The default for -jarfile is the MIDlet-Jar-URL property in the JAD.
        The default for -keystore is "$HOME/.keystore".
        The default for -certnum is 1.
        The default for -chainnum is 1.

Adding a Certificate to a JAD

The command for adding a certificate to a JAD is "-addcert". In addition to the JAD file arguments above, the command has the following arguments: Example of certificate attribute (line breaks added for readability):
MIDlet-Certificate-1-1: MIIC0zCCAbsCBDy0+uQwDQYJKoZIhvcNAQEEBQAwLjEZMBcGA1UEChM
QU3VuIE1pY3Jvc3lzdGVtczERMA8GA1UEBhMIbXlzZXJ2ZXIwHhcNMDIwNDExMDI1NDI4WhcNMTIwND
A4MDI1NDI4WjAuMRkwFwYDVQQKExBTdW4gTWljcm9zeXN0ZW1zMREwDwYDVQQGEwhteXNlcnZlcjCCA
SIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAPGun98yp7isd+Si7YwplA0lBoTlBi8IhalPTwZ5
k9UsDGpWPrGeI7+PFPm5c37T7NNJPx68MtxOQViq+oRqX4TbpMSQ6yXNl8EhfgIa9HGsmIv59bUiP7S
EZKsFFTLaN01DlWqbO3GW01irzvSV8PgoKO8UI8ymfqV77C2W71ICFJsThAJg54gOmli4Ycc52+IBtK
yQWrNJqP849XQphnVfv1jw/qdk20rch+SyAiVWtG7f/v3CKytWWcr99+jLt1oCN+jNJZl7CKQjM1MGa
NE+5pOhk/H3VkXsMqlmEc+vB4vxlxoVoEnbbjM4u0w7aAIySZt+FoMXOgMhkbh19msCAwEAATANBgkq
hkiG9w0BAQQFAAOCAQEArC0Cj9kK3SQzOJQgZYXwcpJWxfnw6p4ynMNaDz2EC2D7/SdcFkL7ZDbhZ9u
6kcxUtGRpx727iEsNPDLq7M2L2dIqvPa3s4Qqp83iVKRvEA6/xcwdOWHB9tU5jXUdzrljfj99vTGysx
EkpAxz6+HAxFK8rvv1sgfJGMQbXVOUQMkRJzS/7+8h8DWno6Kv5XKWUI/4hBzjlBP+Gh9mbYgF7lJ2f
w+yTwmDFOK2X2vpnBZx6+dFFkGtCZQAnp1bZBYe67kKwxHzSA5iXKThANFyjQQr0pedwEVU0LVVH0V9
PovndKRgFCLRTwkV7yChI+1P2YXDv1dp5UszG/o11BtPhg==
The following steps are performed when adding a certificate to a JAD.
  1. Read the input JAD into memory.
  2. Get the certificate from the keystore.
  3. Encode the certificate as base64.
  4. Add the base64 encode certificate as the value of a MIDlet-Certificate-m-<n> attribute to the JAD in memory, where m is the given chain number and where n is the given certificate number. If the certificate is already in the JAD is replaced.
  5. Write the JAD in memory to the output JAD file.

Adding a JAR Signature to a JAD

Adding a JAR signature to a JAD, also creates a the JAR signature using a private key from a J2SE keystore.

The command for adding the signature of a JAR to a JAD is "-addjarsig". In addition to the JAD file arguments above, the command has the following arguments:

Example of JAR signature attribute (line breaks added for readability):
MIDlet-Jar-RSA-SHA1: WhYZlroRQ4qdoHV9OuCBhwq2ICLix2IcebGOjrq8xNvYxH6233ZK13CyKJ
iXnX/YjZ9e00vh3PCKz6UvRptB1HzUqL5tBGROIXO5YQK1fonDSzz2mz+bpoo36zzXEVZD1WXJtskxR
LkUBxGLhOfISfvqDZs1hX22gYjQbEYFaTHofEBi00LfVIESrEpvHvsbB0rJqNQtm9M9m8igP6kDSuMn
dF22JP/trh/1aH9Cf3g8Fj9fop72VKt/5dHn6ya/IVkXKDV5LRhNZMMU9hJgan/txIFuHrAkGVfU8tx
mOc6TTxB6ucE3s9YBZ2YTC1Pm0pqCk+RouRdIhZD5Vvy2Aw==
The following steps are performed when adding the signature of JAR to a JAD.
  1. Read the input JAD into memory.
  2. Get the private key from the keystore.
  3. Open an input stream of the JAR for the signing step.
  4. Sign the JAR using the EMSA-PKCS1-v1_5 encoding method of PKCS #1 version 2.0 standard[RFC2437] with the private key.
  5. Encode the signature in base64.
  6. Add the base64 encoded signature as the value a MIDlet-Jar-RSA-SHA1 attribute to the JAD in memory. If a signature attribute is already in the JAD, it is replaced.
  7. Write the JAD in memory to the output JAD file.

Displaying a Certificate from a JAD

The command for displaying a certificate from a JAD is "-showcert". The command can also display all of the certificates in the JAD. In addition to the JAD input file and encoding arguments above, the command has the following arguments: Example of certificate display:
Subject: C=myserver, O=Sun Microsystems
Issuer : C=myserver, O=Sun Microsystems
Serial number: 3cb4fae4
Valid from Wed Apr 10 22:54:28 EDT 2002 to Sat Apr 07 22:54:28 EDT 2012
Certificate fingerprints:
  MD5: 29:bc:e2:28:b9:7f:76:4a:b2:c5:b4:9c:aa:80:4e:be
  SHA: b2:1c:4e:ec:47:7c:13:a4:62:46:f9:d7:cc:3a:e2:f4:f3:3a:6f:6f
It should be noted, that the attributes in the subject and issuer names in the example above are in reverse order from what is in the certificate. This is a side effect of using the J2SE certificate API to get the subject and issuer fields from the certificate, so display the name may not match other tools that display a certificate's subject.

The following steps are performed when displaying a certificate from a JAD.

  1. Read the input JAD into memory.
  2. If "-all" was given as argument get all of the certificates from the JAD. If there are not certificate found display "No certificates found in JAD." and exit. Otherwise skip the next step, and for each certificate found perform the all the steps after the next.
  3. Get the base64 encode certificate attribute MIDlet-Certificate-m-<n> attribute from the JAD, where m is the given chain number and where n is the given certificate number.
  4. Decode the certificate into a byte array.
  5. Create a J2SE certificate object.
  6. Print out to standard output, the subject, issuer, serial number, and validity fields of the certificate object along with MD5 and SHA-1 fingerprints of the raw bytes of the certificate.

Error Conditions

Not all error messages are created by the JAD Tool code, the tool relies on the java.security and java.io classes to generate messages. So only when an error condition has a message created by the MIDP implementation code, will the full message be specified. This is because the message not under control of the MIDP implementation can change at anytime and this cannot be considered a bug.
Error Condition Message to User
There is no command or arguments. No command given
The first argument after the jar name is not a command. Illegal command: <invalid argument>
An argument for a command is not valid for that command. Illegal option for <command>: <invalid argument>
The arguments end after an option flag (command arguments that start with "-") that should be followed by a value. Missing value for <last argument>
An input JAD was not given. <command> requires an input JAD
The input JAD does not exist. Input JAD does not exist: <filename>
The given encoding is not supported. Encoding type <encoding> not supported
The input JAD cannot be parsed. Error parsing input JAD: <filename>
The given keystore does not exist. Keystore does not exist: <filename>
The keystore is empty. Keystore exists, but is empty: <filename>
The output JAD is read-only. Error opening output JAD: <filename>
An output JAD was not given and the command requires one. <command> requires an output JAD
The alias was not given to the -addcert command. -addcert requires -alias
Certificate not found in keystore. -addcert failed: java.security.cert.CertificateException: Certificate not found
General error adding the certificate to a JAD. -addcert failed: <exception message>
A non-digit character in the certificate number argument or the number is zero. -certnum must be a positive number
A non-digit character in the certificate chain number argument or the number is zero. -chainnum must be a positive number
-showcert command could find the certificate to display in the JAD. Certificate <chain number>-<certificate number> not in JAD
-all and -certnum or -chainnum were given to the -showcert command. -all cannot be used with -certnum or -chainnum
General error showing a certificate from a JAD. -showcert failed: <exception message>
The alias was not given to the -addjarsig command. -addjarsig requires -alias
The key password was not given to the -addjarsig command. -addjarsig requires -keypass
-addjarsig could not load the keystore. Keystore could not be loaded: <exception message>
The JAR file does not exist. JAR does not exist: <filename>
General error adding a JAR signature to a JAD. -addjarsig failed: <exception message>