## 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:

- Display usage help text
- Add a provider certificate from a keystore to a JAD
- Add the digital signature of a JAR to a JAD
- Decode and display a provider certificate from a JAD

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:

- "-alias" followed by the alias of the certificate, this is required to find the certificate in the keystore.
- "-keystore" followed by the filename of a J2SE keystore from which the get certificate. If not provided, the tool will assume the filename of the keystore is $HOME/.keystore. This is consistent with J2SE keytool.
- "-storepass" followed by a password to unlock the keystore if needed.
- "-certnum" followed by number of certificate in the signer certificate chain. This is only needed to replace a certificate, since if the number is not given it will be calculated automatically to be the next number in the chain. Numbers start at "1".
- "-chainnum" followed by number of a signer certificate chain. If not given, "1" is used.

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:

- "-alias" followed by the alias of the private key. This is required to find the key in the keystore.
- "-keystore" followed by the filename of a J2SE keystore from which the get private key. If not provided, the tool will assume the filename of the keystore is $HOME/.keystore. This is consistent with J2SE keytool.
- "-storepass" followed by a password to unlock the keystore, if needed
- "-keypass" followed by a password to unlock the private key used to sign the JAR
- "-jarfile" followed by the filename of the JAR. If not given and the MIDlet-Jar-URL attribute is present and has a valid HTTP URL, then the input JAR will downloaded using the URL over the network.

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:

- "-certnum" followed by number of certificate in the signer certificate chain. If not given "1" is used.
- "-chainnum" followed by number of a signer certificate chain. If not given, "1" is used.
- "-all". Only valid when -certnum and "-chainnum" are not used.

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>