## ME Key Tool

### Summary

Provides a command line interface to manage mobile equipment (ME) keystore for the MIDP implementation.

The ME Key Tool uses the Javatm Standard Edition (J2SE) keystore API to access J2SE keystores. J2SE provides the command line tool to manage J2SE keystores.

The general usage for the ME Key Tool is (from the MIDP home directory):

> `java -jar bin/MEKeyTool.jar` (command followed by arguments for the command)

The ME Key Tool provides the following commands.

- Display usage help text
- Import a public key into an ME keystore from a J2SE keystore
- Delete a key from an ME keystore
- List the keys in an ME keystore

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.

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

>     MEKeyTool argument combinations:

>       -help
>       -import [-MEkeystore <filename>] [-keystore <filename>]
>               [-storepass <password>] -alias <key alias> [-domain <domain>]
>       -list [-MEkeystore <filename>]
>       -delete [-MEkeystore <filename>]
>               (-owner <owner name> | -number <key number>)

>     The default for -MEkeystore is "appdb/_main.ks".
>     The default for -keystore is $HOME/.keystore.

### Importing a Public Key

The ME Key Tool only imports keys contained in X.509 certificates.

The command for importing a public key into an ME keystore from a J2SE keystore is "-import". The command has the following arguments:

- "-alias" followed by the alias of the certificate of the public key in the J2SE keystore, 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.
- "-MEkeystore" followed by the filename of a ME keystore to import the public key into. If not provided, the tool will assume "appdb/_main.ks".
- "domain" the security domain to associate with the public key. If not given "untrusted" will be used.

The following steps are performed when importing a public key into an ME keystore.

1. Load the ME keystore.
2. Get the certificate from the J2SE keystore.
3. Check to see if there are any keys owned by subject of the certificate in the ME keystore. If there are any keys found, exit if any of the keys found are a duplicate of the key in the certificate.
4. Create an ME key object with the subject name, validity, and key from the certificate, plus the given security domain.
5. Add the ME key object to the loaded keystore.
6. Save the loaded keystore.

### Listing Public Keys

The command for listing the keys in an ME keystore "-list". The command has the following arguments:

- "-MEkeystore" followed by the filename of the ME keystore containing the keys to list. If not provided, the tool will assume "appdb/_main.ks".

Example of key listing:

>     Key 1
>       Owner: C=US;O=RSA Data Security, Inc.;OU=Secure Server Certification Authority
>       Valid from Tue Nov 08 19:00:00 EST 1994 to Thu Jan 07 18:59:59 EST 2010
>       Security Domain: untrusted
>     Key 2
>       Owner: CN=Sun Microsystems Inc TEST CA;O=Sun Microsystems Inc
>       Valid from Mon Nov 20 16:20:50 EST 2000 to Fri Nov 20 16:20:50 EST 2009
>       Security Domain: trusted

The following steps are performed when listing the key in an ME keystore.

1. Load the ME keystore.
2. For each key, print:
   - Number of the key (1 for the first)
   - Name of the owner
   - Validity
   - Security domain

### Deleting a Public Key

The command for deleting a key from an ME keystore "-delete". The command has the following arguments:

- "-MEkeystore" followed by the filename of the ME keystore to delete a public key from. If not provided, the tool will assume "appdb/_main.ks".
- "-owner" followed by the common name of the key's owner as presented by the "-list" command. If not given the -number argument must be given. If "-owner" is given "-number" must not be given.
- "-number" followed by the number the key as presented by the "-list" command. If not given the -owner argument must be given. If "-number" is given "-owner" must not be given.

The following steps are performed when deleting a key from an ME keystore.

1. Load the ME keystore.
2. If the key selected by owner, delete the first key of the owner from the loaded keystore.
3. If the key selected by number (1 for the first), delete selected key from the loaded keystore.
4. Save the loaded keystore.

### Error Conditions

Not all error messages are created by the ME keytool 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. | Error: No command given
The first argument after the ME Key Tool JAR name is not a command. | Error: Invalid command: <invalid argument>
An argument for a command is not valid for that command. | Error: Invalid argument for <command> command: <invalid argument>
The arguments end after an option flag (command arguments that start with "-") that should be followed by a value. | Error: Missing value for <last argument>
-alias was not given to the import command. | Error: J2SE key alias was not given
A non-digit character in the -number argument. | Error: Invalid number for the -number argument: <invalid number>
Neither -owner of -number given for the delete command. | Error: Neither key -owner or -number was not given
Both -owner of -number given for the delete command. | Error: -owner and -number cannot be used together
The key for a given owner cannot be found in the ME keystore. | Error: Key not found for: <owner argument>
The key number given was out of range. | Error: Invalid number for the -number delete option: <key number argument>
No certificate was found in the J2SE keystore with the given alias | Error: Certificate not found
The certificate found in the J2SE keystore does not have an RSA public key. | Error: Key in certificate is not an RSA key
The public key to be imported is matches a key already in the ME keystore belonging to the same owner. | Error: Owner already has this key in the ME keystore
Corrupted (or not a keystore file) ME keystore given | Error: input storage corrupted
Corrupted (or not a keystore file) J2SE keystore given, J2SE keystore password incorrect, or any other error condition not listed above | Error: <exception message>