The Oracle Java ME Embedded platform uses public keys from a Certificate Authority (CA) to validate Web sites and signed IMlet suites. The Oracle Java ME Embedded implementation also uses private keys from certificates to establish secure connections with client authentication. When the platform uses a secure protocol to access a Web site, the site provides a certificate which is typically signed by a CA. In the same manner, signed IMlet suites also contain a certificate that is signed by a CA. The Oracle Java ME Embedded platform checks the validity of a certificate by using the CA's public key. By signing a certificate, a CA certifies the identify of the owner of the Web site or IMlet suite.
You can manage the CA certificates, public keys, and private keys on the embedded board by using the MEKeyTool utility. The MEKeyTool utility is provided with the Java ME SDK distribution, and is similar to the keytool utility provided with the Java SE platform, except that MEKeyTool will also operate across a network on the keystores of an embedded device that is currently recognized by the Oracle Java ME Embedded Device Manager.
This chapter describes how to use MEKeyTool to manage keystores that are used by the Oracle Java ME Embedded Emulator or recognized by the Oracle Java ME SDK Device Manager.
MEKeyTool is an executable that can be found in the following location:
{ME-SDK_Home-Dir}\bin\MEKeyTool.exe
Where ME-SDK-Home-Dir is the base directory of the Oracle Java ME Embedded installation.
To connect to a keystore on an embedded board instead of the emulator, add the -Xdevice option to reference a device currently recognized by the Oracle Java ME Embedded Device Manager:
MEKeyTool.exe -Xdevice:EmbeddedExternalDevice1
WARNING:
Each embedded board may only accept a limited subset of commands, depending on the functionality offered. To list the functionality supported by the device EmbeddedExternalDevice1, for example, you can use the emulator's Xquery option:
emulator.exe -Xquery -Xdevice:EmbeddedExternalDevice1
The MEKeyTool utility keeps the CA certificates, public keys, and private keys in an ME keystore. Depending on the device, the keystore is at the following locations, where base-dir is the base directory of the Oracle Java ME Embedded or Oracle Java ME SDK installation.
Table D-1 Location of Keystores
| Device | Location |
|---|---|
|
Emulator |
{base_dir} |
|
Embedded Boards |
[base_dir} |
This keystore directory contains an index file named _main.ks and a set of certificate files. The platform includes the key of one CA.
WARNING:
Oracle does not recommend modifying the default keystore, but instead modifying a copy, either one that is user-generated or in the working directory for the appropriate device.
When the Oracle Java ME Embedded emulator is first started, it creates a working directory in {User_Home_Dir}/javame_sdk/{Version}/work/{device}/appdb/certs. (Note that this is only the case for emulated devices, such as EmbeddedDevice1, not devices that map to actual embedded boards such as EmbeddedExternalDevice1.) Next, it copies all certificates and several other important files there. Be aware that deleting the working directory removes all device settings and, of course, any additions to the local keystore.
Note:
The MEKeytool utility enables you to import keys from Java SE keystores. However, you cannot use the MEKeytool utility directly on a Java SE keystore. For example, if you try to use the MEKeytool utility to view public keys in a Java SE keystore, the utility displays an error message that the keystore is corrupted. An ME keystore has a different format Java SE platform keystores, which have a format in accordance with the Java Cryptography Architecture specification.
In addition to managing the public keys in the ME keystore, you can use the MEKeytool utility to manage additional ME keystores, both with the emulator and some embedded boards that contain an accessible filesystem. For example, during testing you might want to have multiple keystores to run against. One keystore could contain all the necessary testing keys, a second keystore could contain a subset of the testing keys, and a third keystore could contain an expired key.
The MEKeytool utility does not create a new ME keystore directory. The developer must create an empty keystore first, consisting of a directory and an empty _main.ks file, which can be copied from the keystore provided with the distribution bundle. See Importing a Key for instructions on how to import a key.
To manage a keystore other than the default, use the -import -MEkeystore option:
MEKeyTool.exe -import -MEkeystore keystoreName ...
For example, if you created an ME keystore, {User_Home_Dir}\myKeys\set2_test_keys.ks, that contains the keys that are needed to run a particular set of tests, use the MEKeyTool command to manage that keystore:
MEKeyTool.exe -import -MEkeystore {User_Home_Dir}/myKeys/set2_test_keys.ks ...
For all MEKeyTool commands, you receive an error message if the file that you provide as an argument to -MEkeystore does not exist.
You can add a key to an ME keystore by importing it from the Java Cryptography 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://download.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html.
The file name for the Java SE keystore is .keystore and the default location is in your home directory. This file is created if you use the Java SE platform's keytool utility to create keys and you do not specify a different location. The MEKeyTool utility references this keystore unless you use the -keystore argument to specify a different keystore.
Note:
If you use a Java SE keystore other than the default, the new keystore might require a password.
The -import option imports a key. For example, to add a key with an alias dummyca from the Java SE keystore j2se_test_keystore.bin that has a password, keystorepwd, to the ME keystore at {User_Home_Dir}/myKeys/set2_test_keys.ks:
C:\>MEKeyTool.exe -import -alias dummyca -keystore j2se_test_keystore.bin -storepass keystorepwd -MEkeystore myKeys/set2_test_keys.ks
If it is necessary to import a certificate with a private key from a file in PKCS12 format (for example, cert_with_key.p12) with the keystore password storepwd and the key password keypwd, use the command:
C:\>MEKeyTool.exe -import -keystore cert_with_key.p12 -storepass storepwd -keypass keypwd -MEkeystore myKeys\set2_test_keys.ks
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 {User_Home_Dir}/myKeys/set1_test_keys.ks:
C:\>MEKeyTool.exe -list -MEkeystore myKeys/set1_test_keys.ks Key 1 Owner: C=US;O=VeriSign, Inc.;OU=Class 3 Public Primary Certification Authority Valid from Mon Jan 29 03:00:00 MSK 1996 to Wed Aug 02 03:59:59 MSD 2028 Security Domain: identified_third_party Enabled: true Key 2 Owner: O=Oracle;C=myserver Valid from Sat Aug 03 00:43:51 PDT 2002 to Tue Jul 31 00:43:51 PDT 2012 Security Domain: operator Enabled: true
The following example lists of the contents of the ME keystore on a Raspberry Pi device currently listed as EmbeddedExternalDevice1. Again, note that the device must already be registered with the device manager.
C:>MEKeyTool.exe -list -Xdevice:EmbeddedExternalDevice1 [1] Owner CN=AddTrust External CA Root,OU=AddTrust External TTP Network,O=AddTrust AB,C=SE valid from Tue May 30 03:48:38 PDT 2000 till Sat May 30 03:48:38 PDT 2020 [2] Owner CN=GlobalSign Root CA,OU=Root CA,O=GlobalSign nv-sa,C=BE valid from Tue Sep 01 05:00:00 PDT 1998 till Fri Jan 28 04:00:00 PST 2028 [3] Owner CN=GTE CyberTrust Global Root,OU=GTE CyberTrust Solutions\, Inc.,O=GTE Corporation,C=US valid from Wed Aug 12 17:29:00 PDT 1998 till Mon Aug 13 16:59:00 PDT 2018 [4] Owner CN=Entrust.net Secure Server Certification Authority,OU=(c) 1999 Entrust.net Limited,OU=www.entrust.net/CPS incorp. by ref. (limits liab.),O=Entrust.net,C=US valid from Tue May 25 09:09:40 PDT 1999 till Sat May 25 09:39:40 PDT 2019 [5] Owner OU=Class 3 Public Primary Certification Authority,O=VeriSign\, Inc.,C=US valid from Sun Jan 28 16:00:00 PST 1996 till Tue Aug 01 16:59:59 PDT 2028 [6] Owner OU=VeriSign Trust Network,OU=(c) 1998 VeriSign\, Inc. - For authorized use only,OU=Class 3 Public Primary Certification Authority - G2,O=VeriSign\, Inc.,C=US valid from Sun May 17 17:00:00 PDT 1998 till Tue Aug 01 16:59:59 PDT 2028 [7] Owner CN=thehost,OU=Unknown,O=TEST,L=Unknown,ST=Unknown,C=US valid from Wed Nov 16 11:40:27 PST 2005 till Sat Nov 14 11:40:27 PST 2015 [8] Owner CN=GeoTrust CA for UTI,O=Unified Testing Initiative (UTI),C=US valid from Thu Jan 22 21:00:00 PST 2004 till Tue Jan 23 20:55:00 PST 2024 [9] Owner 1.2.840.113549.1.9.1=#16197072656d69756d2d736572766572407468617774652e636f6d, CN=Thawte Premium Server CA,OU=Certification Services Division,O=Thawte Consulting cc,L=Cape Town,ST=Western Cape,C=ZA valid from Wed Jul 31 17:00:00 PDT 1996 till Thu Dec 31 15:59:59 PST 2020 [10] Owner OU=Equifax Secure Certificate Authority,O=Equifax,C=US valid from Sat Aug 22 09:41:51 PDT 1998 till Wed Aug 22 09:41:51 PDT 2018
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:
-owner ownerName
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.
-number keyNumber
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 {User_Home_Dir}/myKeys/set1_test_keys.ks (the keystore used in Listing Available Keys):
Deleting a key by using its key number-
C:\>MEKeyTool.exe -delete -number 1 -MEkeystore myKeys\set1_test_keys.ks
Deleting a key by using its owner name-
C:\>MEKeyTool.exe -delete -owner "C=US;O=VeriSign,\ Inc.;OU=Class 3 Public Primary Certification Authority" -\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 has a key in the ME keystore.
The MEKeyTool utility supports the following options:
no option
Runs the tool without options and returns the same information as the -help option.
-help
Prints a usage summary.
-import [-alias keyAlias] [ -keystore JavaSEKeystore ] [ -keypass keyPassword ] [ -storepass storePassword ] [ -client clientName ]
Imports a key identified by security client clientName or keyAlias from JavaSEKeystore into the device keystore. If JavaSEKeystore is not provided, its default, {User_Home_Dir}/.keystore, is used (where {User_Home_Dir} is the user's home directory).
If JavaSEKeystore requires a password, you must provide storePassword. If the -keypass argument is provided, the private key will be imported to the ME keystore together with public certificate.
-list [ -client clientName ]
Lists the number, owner, and validity period, and domain of the key identified by security client clientName, or all keys if the option is omitted, in the device keystore.
-delete [ -client clientName ] ( -owner ownerName | -number keyNumber )
Deletes the key identified by security client clientName, ownerName or keyNumber from the device keystore.
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.
-export [ -client clientName ] ( -number keyNumber ) ( -out outputFile )
Exports a certificate, specified by security client clientName or keyNumber, from the device keystore to the output file outputFile. The format of the outputFile is:
PEM in the case of an extracted public key or certificate
PKCS#12 in the case of an extracted certificate with a private key. The keystore password of the PKCS#12 file is the same password that was used in the -keypass parameter of the import command
-clients
Presents a list of all the security clients defined in the system that can accept public keys.