Java Glossary : keytool

Java definitions: 0-9 A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

You are here : home : Java Glossary : K words : keytool.

JDK 1.4 tool for creating phony self-signed certificates and managing imported certificates for Sun-style Applet signing and Java Web Start.

The code signing certificates Sun uses are usually X.509/DER binary format, with the extension .cer. Sometimes they are in X.509/DER BASE64 encoded printable ASCII format, also with the extension .cer. These certificates don't contain the private key. When certificates are stored in .keystore certificate collections, they do contain the private key.

Keytool Documentation : available:

on the web at java.Sun.com
on J: in the JDK 1.4.2_04: J:\j2sdk1.4.2_04\docs\tooldocs\windows\keytool.html
on J: in the JDK 1.5 beta: J:\Program Files\Java\j2sdk1.5.0\docs\tooldocs\windows\keytool.html

Files

\WINNT\Profiles\Administrator\.keystore contains your signing certificates. Each certificate contains both a private and public key. It may also contain authority certificates that contain only a public key. You may have multiple .keystore files. When you create a .keystore file, you assign it a password.

J:\j2sdk1.4.2_04\jre\lib\security\ cacerts contains your authority certificates. Each certificate contains only a public key. There is only one cacerts file. It comes preloaded with the JRE/JDK with root signing authority certificates from Verisign and Thawte. It comes by default with password changeit.

Generating a Real Certificate

If you want to buy a real certificate, you first use the -genkey option to generate a private/public key pair in your .keystore file. This can take a while. Don't panic. Then you export the public key as a PKCS#10 certificate request, and send it to the certificate authority. To be precise, if you want to buy a certificate from Thawte (who support only RSA certs) you would use:

view

Put these commands in a BAT file. It is almost impossible to type them correctly from the command line because they are so long. CN must be a valid domain name, not your first and last name! OU is usually your department, but you could use it for your personal name. O is your organisation. L is your location/city. See the list of C=country codes, S=state codes, and S=province codes. Whatever you put in here, you are asking the signing authority to attest to, so don't put in anything they can't easily verify.

Make a backup of your \WINNT\Profiles\Administrator.keystore file. These have a habit of mysteriously corrupting themselves. If you lose it, you lose your private key, and your certificate will become worthless.

For a $200.00 USD fee, Thawte will sign your certificate request with their private key and send it back to you in either X.509/DER or preferably the more advanced PKCS #7 format which includes certificate chains. You then import that certificate into your .keystore file and you can then use it for signing your code. To import it you would use:

REM import purchased cert
keytool -import -alias pluginsigner -trustcacerts -file cert.cer

You don't import it into your cacerts. This a code-signing certificate, not an authority certificate. The root Thawte certificate that comes preloaded in your cacerts file is your authority certificate.

Note, you never tell the certificate authority your private key. The certificate request and the certificate they send back do not contain the private key and hence are useless to anyone who does not have access to your private key.

Generating a Phony Certificate

If you want to create a phony self-signed certificate, the first steps are the similar except you must use the -selfcert option and export the finished PKCS#7 certificate. Basically, you set yourself up as a miniature certificate signing authority. To be precise:

view

phony is the alias for your cert. That is not a particularly auspicious name. See the jar essay where I talk about phony.dsa. You would be better to choose something dignified that hinted at your company name.

Since your clients have never heard of your miniature signing authority, you might try loading the phonycert.p7b into each browser who will use your code as if it were a signing authority. Even after you do that, your code still won't work because Sun Plug-in looks in the policy and .keystore files on each client machine to decide if it will let code run. You must update all those client .keystore files with your cert so they will treat you just like a legitimate signing authority.

REM import phony certificate into a client cacerts
keytool -import -keystore J:\j2sdk1.4.2_04\jre\lib\security\cacerts -alias phony -file phonycert.cer

or possibly into C:\Program Files\Java\j2re1.4.2_04\lib\security\cacerts.

Creating .keystore

Now you can finally sign your code with jarsigner and have your clients run it. A .keystore file is automatically created whenever you use a -genkey, -import, or -identitydb command to add data to a .keystore that doesn't yet exist. If you want to create one programmatically here is how to do it:

KeyStore ks = KeyStore.getInstance( "JCEKS" , "SunJCE" );

Updating Root Certificates

If your cacerts file is missing the root signing authority certificate, your purchased cert will behave like a phony-self-signed cert. See certificate for how to get the missing root certificates. Import them into all your cacerts files with keytool:

view

Other Useful keytool Commands

REM delete a cert from the default .keystore
keytool -delete -alias phony

REM delete a cert from the cacerts file, password ( changeit )
keytool -delete -alias phony -keystore J:\j2sdk1.4.2_04\jre\lib\security\cacerts

REM list all .keystore certs
keytool -list -v | more

REM list all .keystore certs to a text file
keytool -list -v > allmycerts.txt

REM list just one .keystore cert
keytool -list -v -alias mycert | more

REM list all cacerts certificates ( password changeit )
keytool -list -keystore J:\j2sdk1.4.2_04\jre\lib\security\cacerts | more

REM list just one cacerts certificate ( password changeit )
keytool -list -keystore J:\j2sdk1.4.2_04\jre\lib\security\cacerts -alias thatcert | more

REM list display a standalone exported cert not inside .keystore or cacerts
keytool -printcert -v -file anycert.cer | more

If you screw up, you can start over by deleting your .keystore file, or by deleting the offending entries. Make sure you never delete the private key for one of your paid certificates though!

You can tell if a certificate includes a private key by the way keytool lists it. Signing certificates with private keys will be marked keyEntry. Authority certificates without private keys will be marked trustedCertEntry.

Exporting Private Keys

Keytool will generate a private key, but won't import or export one. This is why you can't easily convert a Sun code signing certificate to a Netscape code signing certificate or vice versa. Mitch Gallant has found a a way around this that uses the BouncyCastle classes.

You must plan ahead and generate your private key in the .keystore where you want to it to finally reside. People not understanding the process so often lose the original private key, or find they can't move it to where it is needed. This applies even more so to SSL certificates.

Understand the process!

You generate a private key.
You back it up inside the .keystore file.
You export the corresponding public key to the certificate authority.
They sign it with their private key and return it to you. (They never see your private key.)
You import your signed public key back into your .keystore.
Now the pair is ready for use, "forever" trapped in that .keystore file.

Passwords

Both the .keystore and cacerts file are password protected. The cacerts password by default is changeit, which, surprise, you are supposed to change. .keystore by default has no password.

There are also optional additional password protections on each individual item in the store. Passwords are case sensitive and must be at least 6 letters long. Best to include some digits to make them harder to guess. Putting punctuation in them will make it difficult to use them on the command line.

Here is how to change the password:

REM change cacerts password from changeit to sesame6
keytool -storepasswd -new sesame6 -storepass changeit -keystore J:\j2sdk1.4.2_04\jre\lib\security\cacerts

REM change .keystore password, it will prompt for the old one.
keytool -storepasswd -new sesame7

Backups

You need to keep backups of all your key files since the signing authorities won't replace your certs if you lose your private key. Use a tool like 4NT DESCRIBE to label all your files. There are many formats and keytool can only read some of them. Many are binary formats so peeking with a text editor won't help either. You will soon become hopelessly confused about what is what if you don't meticulously label them all.

.keystore Finder/Viewer ¤ cacerts ¤ certificate ¤ jarsigner ¤ keyman: IBM's more user-friendly keystore manipulator ¤ keystore ¤ signed Applets

home	Canadian Mind Products
	mindprod.com IP:[24.87.56.253]
	Your IP:[80.134.30.163]
	You are visitor number 17754.
	Please send errors, omissions and suggestions
	to improve this page to Roedy Green.
	You can get a fresh copy of this page from:	or possibly from your local J: drive mirror:
	http://mindprod.com/jgloss/keytool.html	J:\mindprod\jgloss\keytool.html