| Tools Guide |    
|
| Tools Guide |
|
| C H A P T E R 1 |
|
Managing Public Keys of Certificate Authorities |
Java Wireless Client uses public keys from a Certificate Authority (CA) to check the validity of web sites and signed MIDlet suites. When Java Wireless Client uses a secure protocol to access a web site, the site provides a certificate typically signed by a CA. Similarly, signed MIDlet suites contain a certificate that is typically signed by a CA. By signing a certificate, a CA vouches for the web site or MIDlet suite.
Java Wireless Client checks the validity of a certificate by using the CA's public key. You manage the CA public keys for your Java Wireless Client port with the MEKeyTool utility. The utility is functionally similar to the keytool utility provided with the Java SE platform.
This chapter describes how to use MEKeyTool. This chapter contains the following sections:
In the following sections, installDir represents the Java Wireless Client installation directory.
MEKeyTool is packaged in a JAR file, MEKeyTool.jar, in the installDir/midp/bin directory.
|
1. Open a command prompt or terminal window.
2. Change your current directory to installDir/midp.
For example, if Java Wireless Client software is installed in the directory
$HOME/jwc2.0:
$ cd $HOME/jwc2.0/midp
3. Run MEKeyTool with the java command, the -jar option, and any options to MEKeyTool.
The commands and options to the MEKeyTool utility are described in MEKeyTool Summary. Using no options provides help. For example, if the java command is on your PATH, use the following command to display help:
$ java -jar bin/MEKeyTool.jar
The MEKeyTool utility keeps the CA public keys in an ME keystore, a file that holds the keys in a format that the Java ME platform can use. When using a secure protocol, the Java Wireless Client software implementation expects the ME keystore to be the file installDir/midp/appdb/_main.ks. Java Wireless Client software includes the file and the key of one CA. By default the MEKeytool utility uses this file when you add, delete, or list keys.
An ME keystore has a different format from the Java SE platform's J2EE Connector Architecture (Connector Architecture) keystore file. You cannot use the MEKeytool utility on a Connector Architecture keystore. For example, if you try to use the MEKeytool utility to view public keys in a Connector Architecture keystore, the utility displays an error message that the keystore is corrupted. The message indicates that the keystore is not in a format that the MEKeyTool utility can read. However, the keystore is in the correct format for the Java SE platform tools.
In addition to managing the CA public keys in the default ME keystore, you can use the MEKeytool utility to manage additional ME keystores. For example, during testing you might want to have multiple keystores to run against: One keystore could contain all the keys, a second keystore could contain a subset of keys, and a third keystore could contain an expired key.
Importing a key is one way to create a new ME keystore. If you import a key into a keystore that does not exist, the MEKeyTool utility creates it. See Importing a Key for instructions on how to import a key. A second way to create an ME keystore is to copy the keystore provided with Java Wireless Client software.
To manage a keystore other than the default, use the -MEkeystore option:
java -jar bin/MEKeyTool.jar -MEkeystore keystoreName ...
For example, if you created an ME keystore containing the keys needed to run a particular set of tests, $HOME/myKeys/set2_test_keys.ks, use the MEKeyTool command to manage that keystore:
java -jar bin/MEKeyTool.jar-MEkeystore $HOME/myKeys/set2_test_keys.ks ...
For most MEKeyTool commands, you receive an error message if the file that you provide as an argument to -MEkeystore does not exist. The only exception is importing a key, when MEKeyTool creates a new ME keystore with the name that you supply.
|
The Java Wireless Client software executables only use the ME keystore:
installDir/midp/appdb/_main.ks
To use an alternate keystore, you must perform the following steps before running an executable:
1. Create a backup copy of the existing installDir/midp/appdb/_main.ks. If you already have a copy of this file, go to the next step.
For example, if your current directory is installDir, run the following command:
$ cp midp/appdb/_main.ks myKeys/orig_main.ks
2. Copy your alternate keystore to installDir/midp/appdb/_main.ks.
For example, to use the keys in the file $HOME/myKeys/set2_test_keys.ks, for this run of the Java Wireless Client software executable, run the following command:
$ cp myKeys/set2_test_keys.ks midp/appdb/_main.ks
The ME keystore comes with few keys. If you cannot visit some web sites or install some MIDlets, you can add the required keys to the keystore. You must also add new keys to the keystore when existing keys expire. First delete the expired key, then add the new one.
Add a key to an ME keystore by importing it from the Connector Architecture keystore that comes with the Java SE platform or from a keystore that you create. For more information on the keystore that comes with the Java SE platform, see
http://java.sun.com/j2se/1.4/docs/tooldocs/win32/keytool.html.
The default Connector Architecture keystore for the MEKeyTool utility is $HOME/.keystore.
|
Note - If you use a Connector Architecture keystore other than the default, the new keystore might require a password. |
When you add a key to an ME keystore, you can associate a security domain with it. The Java Wireless Client software can assign that domain to any MIDlet suite for which the owner of the public key was a signer. If you do not provide a domain, the public key is associated with the domain called identified.
The option that imports a key is -import. For example, to add a key with an alias dummyca from the Connector Architecture keystore ../bin/j2se_test_keystore.bin to the ME keystore $HOME/myKeys/set2_test_keys.ks:
$ java -jar bin/MEKeyTool.jar -import -alias dummyca-keystore ../bin/j2se_test_keystore.bin-MEkeystore myKeys/set2_test_keys.ks
If the Connector Architecture keystore has a password, keystorepwd, and you want to assign the public key to the operator domain, use the command:
$ java -jar bin/MEKeyTool.jar -import -alias dummyca-keystore ../bin/j2se_test_keystore.bin -storepass keystorepwd -MEkeystore myKeys/set2_test_keys.ks -domain operator
An ME keystore organizes the keys that it contains by giving each one a number. For each key, the keystore also holds the name of the entity to whom the public key belongs, the time over which the key is valid, and the domain associated with the key. The MEKeyTool -list command displays information for each key in a particular keystore.
The following example lists the contents of the ME keystore
$HOME/myKeys/set1_test_keys.ks:
$ java -jar bin/MEKeyTool.jar -list -MEkeystore myKeys/set1_test_keys.ks
Key 1
Owner: C=US;O=RSA Data Security, Inc.;OU=Secure Server Certification Authority
Valid from Tue Nov 08 16:00:00 PST 1994 to Thu Jan 07 15:59:59 PST 2010
Security Domain: identified
Key 2
Owner: O=Sun Microsystems;C=myserver
Valid from Sat Aug 03 00:43:51 PDT 2002 to Tue Jul 31 00:43:51 PDT 2012
Security Domain: operator
When keys expire, you must delete them from the keystore and add their replacements. You can also delete unused keys. For example, if you added the public key of a test site with a self-signed certificate during testing, you can delete that key when testing is completed.
The -delete command to the MEKeyTool utility removes a key from an ME keystore. The -delete command requires one of the following options:
Sets the string that describes the owner of the public key in a given keystore. Use the -list command to print information about each key in the keystore. The string in the command must match the one printed when you use the
-list command to the MEKeyTool utility. See Listing Available Keys for more information.
Sets the number that a given keystore has assigned to each of its keys. The number is greater than or equal to one. Use the -list command to print the number that the keystore has assigned to each of its keys. See Listing Available Keys for more information.
The following examples show two ways to delete a key from the ME keystore $HOME/myKeys/set1_test_keys.ks (the keystore used in Listing Available Keys):
$ java -jar bin/MEKeyTool.jar -delete -number 1 -MEkeystore myKeys/set1_test_keys.ks
$ java -jar bin/MEKeyTool.jar -delete -owner "OU=Secure Server Certification Authority;O=RSA Data Security, Inc.;C=US" -MEkeystore myKeys/set1_test_keys.ks
Some situations require that you replace a key (such as when a key expires). To replace a key, first delete the old key, then import the new key.
|
Note - If you import the new key before deleting the old one, the MEKeyTool utility displays an error message that the owner of the key already has a key in the ME keystore. |
See Deleting a Key for instructions on how to delete a key.
See Importing a Key for instructions on how to import the new key.
The following summarizes the MEKeyTool utility command and options:
java -jar MEKeyTool.jar
-delete [ -MEkeystore MEKeystore ] ( -owner ownerName | -number keyNumber )
[-help]
-import [ -MEkeystore MEKeystore ] -alias keyAlias [ -keystore CAKeystore ] [ -storepass storePassword ] [ -domain domain ]
-list [ -MEkeystore MEKeystore ]
|
Note - In the command line above, the variable CAKeystore stands for "Connector Architecture keystore" and not "Certificate Authority keystore." |
The MEKeyTool utility supports the following options:
Runs the tool without options returns the same information as the -help option.
Deletes the key with ownerName or keyNumber from MEKeystore. If MEKeystore is not provided, its default, installDir/midp/appdb/_main.ks, is used.
You can provide either ownerName or keyNumber, but not both. You can find the valid values for them by running the MEKeyTool utility with the -list command.
Imports a public key from CAKeystore into MEKeystore, and associates the public key with domain. If CAKeystore is not provided, its default, $HOME/.keystore, is used (where $HOME is the user's home directory). If MEKeystore is not provided, its default, installDir/midp/appdb/_main.ks, is used. If domain is not provided, its default domain, called identified, is used.
If CAKeystore requires a password, you must provide storePassword.
|
Note - In the command line above, the variable CAKeystore stands for "Connector Architecture keystore" and not "Certificate Authority keystore." |
Lists the number, owner, and validity period, and domain of each key in MEKeystore. If MEKeystore is not provided, the default, installDir/midp/appdb/_main.ks, is used.
| Tools Guide | 05-2007 |
|
Copyright © 2007, Sun Microsystems, Inc. All rights reserved. SUN PROPRIETARY/CONFIDENTIAL.
Using the MEKeyTool Utility