A Java keytool certificate example: Using ‘keytool’ with certificate files

Java keytool FAQ: Can you share an example of how to use the Java keytool command to create and share a Java/keytool certificate?

Here's a quick look at how two people, John and Paul, might use the Java keytool command to create and share a certificate file. In this example, John will create the certificate with the "keytool genkey" and "keytool export" commands, and Paul will import John's public key from the certificate file with the "keytool import" command.

Java keytool - create a certificate file from a private key (keystore)

To begin with, John wants to share a document with Paul, and both John and Paul want to make sure the document Paul receives is indeed the document that John sent. To do this, John will provide a copy of his public key to Paul, and will then sign the document with his private key. As mentioned, all of this is done with the Java keytool command.

For John to share his public key with Paul, he'll follow these steps. First, if he hasn't already done so, he'll create a private and public key pair in his keystore file, using an "alias" for the keys so he can refer to it in future Java keytool commands:

$ keytool -genkey -alias KeyForPaul -keystore JohnsPrivateKey.store

Enter keystore password:  ABC123
What is your first and last name?
  [Unknown]:  John Doe
What is the name of your organizational unit?
  [Unknown]:  Software Development
What is the name of your organization?
  [Unknown]:  example.com
What is the name of your City or Locality?
  [Unknown]:  Talkeetna
What is the name of your State or Province?
  [Unknown]:  AK
What is the two-letter country code for this unit?
  [Unknown]:  US
Is CN=John Doe, OU=Software Development, O=example.com, L=Talkeetna, ST=AK, C=US correct?
  [no]:  yes

Enter key password for <KeyForPaul>
      (RETURN if same as keystore password):  123XYZ

Now that the file JohnsPrivateKey.store is created, and the alias "KeyForPaul" has been created, John will export a certificate file from this private keystore, like this:

$ keytool -export -alias KeyForPaul -file certfile.cer -keystore JohnsPrivateKey.store

Enter keystore password:  ABC123
Certificate stored in file <certfile.cer>

This step created the certfile file named "certfile.cer".

Note that the keystore password provided here matches the keystore password used when creating this private keystore file (JohnsPrivateKey.store).

In the final step for John, he manages to send this certificate file to Paul securely. At this point I'm going to wave my hands a lot about how this happens, otherwise this discussion can get very lengthy. For the purposes of this tutorial, let's just assume that John gets this certificate file to Paul in a secure manner. (On a related note, this happens a zillion times successfully every day in the real world, so my hand-waving isn't that far fetched.)

Java keytool - import a public key certificate into your keystore

Next, let's look at this from Paul's perspective. Paul has just securely received John's certificate file, and he wants to be able to use John's public key. To do so, he simply imports the public key from John's certificate file into his own keystore. Assuming Paul names his keystore file "MyPublicKey.store", the command he uses to do this looks like this:

$ keytool -import -alias PublicKeyFromJohn -file certfile.cer -keystore MyPublicKey.store

Enter keystore password:  BARBAZ
Owner: CN=John Doe, OU=Software Development, O=example.com, L=Talkeetna, ST=AK, C=US
Issuer: CN=John Doe, OU=Software Development, O=example.com, L=Talkeetna, ST=AK, C=US
Serial number: 4bd4e793
Valid from: Sun Apr 25 17:08:35 AKDT 2010 until: Sat Jul 24 17:08:35 AKDT 2010
Certificate fingerprints:
       MD5:  55:20:B2:68:FD:0F:4E:BF:D5:E5:D5:04:47:6C:E3:10
       SHA1: 25:17:A0:CA:86:CC:3E:6C:2D:C0:4E:8D:E8:33:05:F7:4B:50:FE:E5
Trust this certificate? [no]:  yes
Certificate was added to keystore

Note that the alias Paul gave to this public key did not have to match the alias John used when creating the certificate. Also, John's keystore file (MyPublicKey.store) may have existed previously (in which case this key was added to that keystore file), or it may have been created as a new file when this keytool command was run; the keytool command doesn't care about this difference.

Also, the password used in this command is Paul's password for his keystore file.

Coming soon: Signing with a private key, verifying with a public key

Now that Paul has John's public key stored in his keystore file, he can be sure that documents that John signs and sends to him have really been signed with John's private key. I'll cover this process of signing a document, and then verifying its authenticity in a future keytool tutorial.

In the meantime, if you can't wait for that tutorial, my Java keytool command, keystore files, and certificates tutorial may provide enough information to get you rolling.