|
|
This chapter describes how to manage the certificate authority (CA) keys that your MIDP implementation uses to ensure that you access secure, valid web sites and to ensure that it properly accepts and classifies signed MIDlet suites.
This chapter contains the sections:
See Appendix B, "The MEKeyTool Utility” for information in a manpage format on managing certificate authority keys.
The MIDP Reference Implementation uses the public keys of CAs for two reasons. One is to check the validity of web sites, and the other is to check the validity of a signed MIDlet suite. (See Chapter 3, "Using MIDP Security Features” for more information on checking the validity of signed MIDlet suites.)
When you use a secure protocol to access a web site, the site provides a certificate. The certificate is typically signed by a CA. By signing the certificate, the CA is saying that the web site is being run by the owners of the certificate. (It is not, for example, a look-alike web site set up by hackers to collect information.)
MIDP Reference Implementation checks the web site’s certificate using the public key of the CA that signed it. If the certificate is valid, you are permitted to visit the site. If there is a problem with the web site’s certificate, or you do not have the public key of the CA that signed the certificate, you will not be permitted to access the site. For example, if you try to connect to a test site with a self-signed certificate, and you do not have access to that site’s public key, you will receive a certificate error.
To manage public keys for the MIDP Reference Implementation, you use the MEKeyTool utility. The utility is functionally similar to the keytool utility that comes with the Java™ 2 Platform, Standard Edition (J2SE™). The MEKeyTool utility enables you to:
The MEKeyTool utility keeps the CA public keys in an ME keystore, a file that holds the keys in a format that Java 2 Platform, Micro Edition (J2ME™) can use. By contrast, a file that holds the keys in a format that the J2SE platform can use is a JCA keystore.
Note that JCA and ME keystores have different formats. You cannot use the MEKeytool utility on a JCA keystore. If you do (for example, to try to see its public keys), you will receive an error message that the keystore is corrupted. The message means that the JCA keystore is not in a format that the MEKeyTool utility can read. The JCA keystore is in the correct format for the J2SE platform tools.
The MEKeyTool utility is packaged in a JAR file, MEKeyTool.jar, in the midpInstallDir\bin directory. To use the utility:
For example, if MIDP Reference Implementation was installed in the directory c:\midp2.0fcs:
MEKeyTool with the java command, the -jar option, and any commands or options to MEKeyTool.
The commands and options to the MEKeyTool utility are described below. Using no options provides help on MEKeyTool. For example, if the java command were on your PATH, you could get help with the command:
When you use a secure protocol, the MIDP Reference Implementation expects its ME keystore to be the file midpInstallDir\appdb\_main.ks. The file is included with MIDP Reference Implementation, and contains the key of one popular CA. By default the MEKeyTool utility uses this file when you add, delete, or list keys.
You can also use the MEKeyTool utility to manage other ME keystores. For example, during testing you might want to have multiple keystores to run against: one might have all the keys that you need, another might be missing one or more keys, another might have an expired key. You would use the MEKeyTool utility to manage all of them.
This section has the following topics:
Importing a key is a 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. Another way to create an ME keystore is to copy the keystore provided with MIDP Reference Implementation.
To manage a keystore other than the default, use the -MEkeystore option to MEKeyTool. That is, the command will begin like this:
For example, assume you have created an ME keystore that contains the keys that you need for a particular set of tests, c:\myKeys\set2_test_keys.ks. The command to run the MEKeyTool utility to manage that keystore would begin like this:
For most MEKeyTool commands, if the file that you provide as an argument to
-MEkeystore does not exist you will receive an error message. The one exception is importing a key. In this case MEKeyTool creates a new ME keystore with the name that you supply.
\appdb\_main.ks.
Because the MIDP executable uses only the ME keystore midpInstallDir\appdb\_main.ks, you need to do the following steps before running MIDP if you want to use an alternate keystore:
\appdb\_main.ks, if necessary.If you already have a copy of this file, go to the next step.
For example, assuming that midpInstallDir is c:\midp2.0fcs, you would run a command such as this:
\appdb\_main.ks.
For example, if you want to use the keys in the file c:\myKeys\set2_test_keys.ks for this run of the MIDP Reference Implementation executable you would execute a command like the following one:
Because the ME keystore comes with few keys, you might find that you cannot visit some web sites or install some MIDlets until you add more keys to the keystore. You will also have to add keys to the keystore as time passes and keys expire. (You would first delete the expired key, then add the new one.)
You add a key to an ME keystore by importing it from a JCA keystore. You can import keys from the JCA keystore that comes with the J2SE platform or from a JCA keystore that you create. For more information on the keystore that comes with the J2SE platform, see:
http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html
The default JCA keystore for the MEKeyTool utility is userHome\.keystore. Whatever keystore you use, if it requires a passwords, you must provide it.
When you add a key to an ME keystore, you can also associate a security domain with it. The MIDP Reference Implementation can assign that domain to any MIDlet suite for which the owner of the public key was a signer. (See "Protection Domains" for more information.) If you don’t provide a domain, the public key is associated with the untrusted domain.
The option that imports a key is -import. For example, assume that you want to add a key with an alias dummyca from the JCA keystore ../bin/j2se_test_keystore.bin to the ME keystore c:\myKeys\set2_test_keys.ks. Further assume that the JCA keystore has a password, keystorepwd, and that you want to assign the public key to the trusted domain. You would do this with the command:
c:\midp2.0fcs> java -jar bin/MEKeyTool.jar -import-alias dummyca -keystore ../bin/j2se_test_keystore.bin -storepass keystorepwd -MEkeystore c:/myKeys/set2_test_keys.ks -domain trusted
An ME keystore organizes the keys that it contains by giving each one a number. The keystore also holds, for each key, 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 -list command to the MEKeyTool utility shows you all this information for each key in a particular keystore.
The following example lists the contents of the ME keystore c:\myKeys\set1_test_keys.ks:
c:\midp2.0fcs> java -jar bin/MEKeyTool.jar -list -MEkeystore c:/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: untrusted 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: trusted
As keys expire, you will have to delete them from the keystore so that you can add their replacements. You might also want to delete keys that you will no longer be using. (For example, if you add the public key of a test site with a self-signed certificate, you might want to remove that key when testing is over.)
The -delete command to the MEKeyTool utility removes a key from an ME keystore. The command requires one of the following options:
-owner ownerName
String that describes the owner of the public key. The string must match the one that is printed when you use the -list command to the MEKeyTool utility. (See the previous section, "Listing Available Keys” for more information.)
-number keyNumber
Number greater than or equal to one. The -list command prints the number that a given keystore has assigned to each of its keys. (See the previous section, "Listing Available Keys” for more information.)
The following examples show the two ways to delete a key from the ME keystore c:\myKeys\set1_test_keys.ks used in the previous section, "Listing Available Keys.” The first example deletes the key using its key number:
c:\midp2.0fcs> java -jar bin/MEKeyTool.jar -delete -number 1 -MEkeystore c:/myKeys/set1_test_keys.ks
The second example deletes the key using its owner name:
c:\midp2.0fcs> java -jar bin/MEKeyTool.jar -delete -owner “OU=Secure Server Certification Authority;O=RSA Data Security, Inc.;C=US“ -MEkeystore c:/myKeys/set1_test_keys.ks
Replacing keys is necessary in some situations, such as when a key expires. (See "Handling Certificate Exceptions When Running MIDP,” next, for other situations where key replacement is in order.)
To replace a key you must first delete the old key, then import the new key. (If you try to import the new key before deleting the old one, you will receive an error message telling you 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, and "Importing a Key" for instructions on how to import the new one.
When you run MIDP, you could encounter errors with certificates. When methods that authenticate a certificate encounter such a problem, they throw a CertificateException. Each CertificateException contains a reason code that indicates the nature of the problem. If you receive a CertificateException, you can get its reason code by calling it’s getReason method.
The following list contains the reason codes followed by their corrective actions and descriptions.
BAD_EXTENSIONS — Replace the end entity’s certificate. The certificate has a field that specifies additional critical information that the system does not recognize. (The system must reject certificates that contain unrecognized critical extensions.)BROKEN_CHAIN — Replace the end entity’s certificate chain. The chain has a certificate that was not issued by the next authority in the chain.CERTIFICATE_CHAIN_TOO_LONG — Replace the end entity’s certificate chain with a shorter one. (The CA specifies the maximum length of the end entity’s certificate chain.)EXPIRED — Replace the certificate because the current date is past the last date on which the certificate is valid.INAPPROPRIATE_KEY_USAGE — Replace the end entity’s certificate. The certificate has an invalid value in a field that indicates the purposes for which the certificate can be used. (The field names are keyUsage or extendedKeyUsage. They are typically critical extensions.)MISSING_SIGNATURE — Replace the end entity’s certificate with one that has a signature; the current certificate is unsigned.NOT_YET_VALID — Replace the certificate because the current date is before the date that the certificate can be used.ROOT_CA_EXPIRED — Replace the CA’s public key on the device using the MEKeyTool utility. The current date is past the last date on which the CA’s public key is valid.SITENAME_MISMATCH — Replace the end entity’s certificate with one that has the same site name as the common name attribute of subject name.UNAUTHORIZED_INTERMEDIATE_CA — Replace certificate chain because an intermediate certificate in the chain does not have the authority to be a intermediate CA.UNRECOGNIZED_ISSUER — Import the public key of the end entity’s CA into the device using the MEKeyTool utility. The system can’t recognize the end entity without that key.UNSUPPORTED_PUBLIC_KEY_TYPE — Replace the end entity’s certificate because its public key is not supported by the device.UNSUPPORTED_SIGALG — Replace the end entity’s certificate with one that was signed using RSA. The signature of the current certificate uses another algorithm that this system does not support.VERIFICATION_FAILED — Replace the certificate because the system cannot confirm that the certificate is valid.
The exception’s detail message, returned by the getMessage method, provides additional information.
|
|
Using MIDP MIDP Reference Implementation, Version 2.0 FCS |
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.