Keytool for Dummies

Intention: This article intends to be simple, clear, concise and accurate. I encourage you to read further after this. Google is your friend. This is targeted at an audience with little or no knowledge whatsoever about internet security infrastructure but is stuck in a sorry state of dealing with keytool and digital certificates. Hope this article useful. Thank you for your time.

Some basics

Even before I dive into Java keytool utility, you need have a high level understanding of the following:

SSL – A way to secure internet communication from your browser to a secure website. The websites using SSL will have https:// to their name as shown below.

PKI or Public Key Infrastructure – SSL uses PKI to implement security. PKI uses two keys (keys are some kind of math functions) to secure communication between a browser and a secure website.

• Public key – A key which is made made public (published online and given away) to anyone and everyone who wishes to communicate with the secure website. It is used by the receiver of the key to convert normal messages into cryptic messages. These cryptic messages are useless until it is converted back to normal messages.
• Private Key – This is a secret (hence private) key which is possessed and maintained only by the secure website. This key is used to convert the cryptic messages into normal messages.

When a message (say a text message) is passed between the browser and a secure website, public key is used to convert the text message into a cryptic form(processed is called encryption). This cryptic message can only be transformed to the normal text message by using the private key that the website owns. So other than the secure website, no one else can use this message as they don’t have the private key to convert the cryptic message to normal message.

Digital certificate – Consider this to be like a Driving License. Driving License is issued by the Government Authority certifying that you know how to drive. People trust this license as they trust the Government Authority. Similarly, for secure web transactions, Certificate Authority (Verisign or Thawte or Digicert etc…) is trusted by all computers and browsers, people can get an elo duo boosting with no problem. If a website presents a certificate issued by a Trusted CA, your browser trusts that the website is secure. The digital certificate contains a public key (with some information) of the secure website. This public key is used to encrypt (make the messages cryptic) the communication. The cryptic messages then need to be transformed into normal using the private key maintained only by the secure website.

Your browser has a list of Certification Authorities that it trusts like below.

Chrome Browser Trusted Certificates

Java Keytool utility

Keytool is a program to manage private key, public key and the digital certificates (provided to by the Certificate Authority like Verisign or Thawte) of the secure website. Keytool stores all the certificates and the digital certificates it manages in a container (which also a file) called a keystore. Using keytool, you can add, delete, and view different keys and certificates stored in a container.

The following are the different phases of implementing SSL security through keytool.

• Creating a keystore and a private key
• Creating Certificate Signing Request(CSR)
• Retrieving certificates from CA
• Importing Root certificates to your keystore
• Importing intermediate certificates to your keystore
• Importing the server certificates to keystore

Step 1 – Creating a keystore and a private key

Before generating keys and installing certificates, you ll need a container to store them. So the first step is to create that store called keystore.

The command to create a keystore with a Private Key is:

keytool –genkey –alias webserver.arunpc.com –keyalg RSA –keysize 2048 –keystore webserver.keystore

You ll be prompted to fill in details after which a keystore with a private key is created. It is important to provide the ‘hostname or FQDN’ of your webserver as the alias.

Below is what the command means:

-genkey is the command to generate a Private Key and create a keystore if there is none,

-alias is the tag which is used to identify the entry in the keystore. Consider this to be names that identify keystore entries. You can provide any name but we recommend using hostname or FQDN while generating the private key.

-keyalg is the algorithm used to encrypt keys. Usually RSA is what is used.

-keysize is the size in bits. Nowadays 2 bytes or 2048 bits is the standard

-keystore is the name of the keystore which in this case is webserver.keystore. If a keystore with this name does not exist in the system, keytool program will create one.

Important Notes

• If you don’t specify –keystore option, the system will take the default keystore. So make sure that you are not making modifications to the default keystore but instead to the newly created keystore. It may be a good practice to find out all the keystore files in the already in the system and move them to a different folder. You may find the location of the keystore file from the operating system documentation or searching the entire filesystem by “sudo find / -name “*keystore”“
• It is a good practice to provide the hostname of the server as the alias. Highly recommended. In the above case, the hostname is webserver.arunpc.com.

To view the Private Key stored in the keystore you may execute the following command:

keytool -list -v -keystore webserver.keystore

Step 2 – Creating Certificate Signing request

Using the above step you have created a keystore and a private key. Now you will need to apply to a Certificate Authority (like Verisign or Thawte) to issue your server a Digital Certificate. This request is called CSR or Certificate Signing Request.

The command to create a CSR is:

keytool -certreq -v -alias webserver.arunpc.com -file aruntest.pem -keystore webserver.keystore

Once this command is executed successfully, you ll get the message

Below is what the command means:

-certreq specifies that this is a certification request to be send to CA

-alias should be the same as the alias that you used in Step -1 for generating the Private Key.

-file is the certification request file that we want to create to be sent to CA.

-keystore is the keystore for which the certificate is being created.

You will need to ensure that above values are accurate and exactly matches the values of Step-1.

In the above example, aruntest.pem is the request that we created. The file when opened looks like this.

—–BEGIN NEW CERTIFICATE REQUEST—–

MIIC4DCCAcgCAQAwgZoxCzAJBgNVBAYTAkNBMRAwDgYDVQQIEwdPbnRhcmlvMRAwDgYDVQQHEwdU

b3JvbnRvMTwwOgYDVQQKEzNDQU5BRElBTiBNVVNJQ0FMIFJFUFJPRFVDVElPTiBSSUdIVFMgQUdF

TkNZIExJTUlURUQxCzAJBgNVBAsTAklUMRwwGgYDVQQDExNjbXJyYS12ZGkxLmNtcnJhLmNhMIIB

IjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAk1gEjbg/goUjbbjHNrvr0jvCOwbsQjyAzKdL

vb/S5XwfhjEwyP1f6KNrdj/TKAqZdg9tA4coI/1J4++/XeIQI72imq08FJaixpjsUHk48nYTYWcp

a/DTWdk3gHWo45iKGCeU+2bmTE938na8rk9d67GBDwXCmbPHBWMUiKogUHAQN7OjVfNR7b6biT3s

CGB/sCTtEh6H5RwmvFeU+OKh9Bk4PLjUCcRemxMp97/5XiPZyFTBFZN5EsbY5FDe88SoZ4Ce+lkb

OcaKRuEjLN92khjdwonxJdEOFglSj1zRF5OyI4wgT8u/2HGLF52zWvX6tkWEFSf8aYf00f9KRMUP

BwIDAQABoAAwDQYJKoZIhvcNAQEFBQADggEBAInPQzEB/xpWebIhWAny7Xw5/sF6+LAzerxskBCT

zUzDaO5OKu7GULM8aMjNHgQliIJiKwYNnt53rcYk1N6iK1JWGW8TzEFZYAz/Uyg/b7em7T9OBKBN

5hm8I2fDxA1Szh9ysuxyaXMj3LCO/DhPrEJFQLdl0kxPMYjquA/1FLgD6Jsmr2knC2ytFLfx7j5H

cELH0Bqzoiu8qtoXg6XLzI1NOYk0+QH1CCnKJ/0z01rnTr27FNY4JPTk+MlGlUkD87sIJgx4UUoz

oAAavYZtLz0Y5PmWQWckwxBCbllcvftH9IvrHadK3VwO/RXqecUIFqkmC7CtOZWvgLvaJKFYDvQ=

—–END NEW CERTIFICATE REQUEST—–

Step 3- Retrieving certificates from CA

Now that you have created the certificate request for your webserver, it is time to go to the website of a CA for signing and endorsement. You can download the ROOTCA and the Intermediate certificates from the issuer’s website or by contacting their Tech Support. The CA usually gives 3 types of certificates:

• Server certificate for webserver,
• RootCA certificate,
• Intermediate certificate.

Server certificate is the one which contains your public key and which certifies your server. The below says that Issuer is Thawte which is reputed CA and is issued to mail.google.com

Then you have the RootCA certificate. This is the CA’s certificate and it has all the details of the CA like below. Notice the issued to and issue by.

Now you may also have another certificate called the Intermediate certificate. This is nothing but a certificate which comes between the server certificate and the RootCA certificate. This is like a bridge between RootCA certificate and the server certificate.

Step 4 – Importing Root certificates to your keystore

In Step 1, you have already created a keystore and it is populated with a Private Key. In Step 3, you have generated certificates for RootCA, your webserver and Intermediate CA. You now need to install these certficates.

The order in which the certificates are installed is important. First you ll need to install RootCA certificate and then you need to install the intermediate certificate and last the webserver certificate.

So as the first step, let us install the RootCA certificate. You may use the following command and may use any alias.

keytool -import -trustcacerts -alias root -file RootCertFileName.crt -keystore webserver.keystore.

where RootCertFileName.crt is the RootCA certificate and the keystore name is webserver.keystore

Step 5 – Importing Intermediate certificates to your keystore

After installing RootCA certificate, you need to then install intermediate certificate.

keytool -import -trustcacerts -alias intermediate -file Intermediate-Digicert.crt -keystore webserver.keystore

It is to be noted there may not be an intermediate certificate in some cases. In such cases, just a RootCA certificate will suffice.

Step 6 – Importing Server certificate to your keystore

After installing RootCA and Intermediate certificates, you need to then import server certificates.

keytool -import -trustcacerts -alias webserver.arunpc.com -file arunpccert.crt -keystore webserver.keystore

Imp Note: Make sure that you provide the same alias as your Private Key which in this example is the hostname

To view the keys in keystore, you may do it like this:

keytool -list -keystore webserver.keystore

Verifying the certificates are correctly installed

Once the keystore is populated with keys and certificates, you may verify that the certificate chain is established from the server certificate to intermediate certificate to the RootCA certificate.

If you run the command:

keytool -v -list -keystore webserver.keystore

It will list information of all the certificates. Look for the PrivateKey entry and see whether the Certificate Chain length is 2 or above. This will tell you that server certificate is able to establish a chain till the RootCA.

*******************************************

*******************************************

Alias name: webserver.arunpc.com

Creation date: May 9, 2012

Entry type: PrivateKeyEntry

Certificate chain length: 3

Configuring your SSL Connector

Tomcat will need an SSL Connector configured before it can accept secure connections.

Open the Tomcat server.xml file in a text editor (this is usually located in the conf folder of your Tomcat’s home directory). Find the connector that will be secured with the new keystore and uncomment it if necessary (it is usually a connector with port 443 or 8443 like the example below).

Specify the correct keystore filename and password in your connector configuration. When you are done your connector should look something like this:

<Connector port="443" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" scheme="https" secure="true" SSLEnabled="true" clientAuth="false" sslProtocol="TLS" keyAlias="server" keystoreFile="/home/user_name/webserver.keystore” keypass=”your_keystore_password” />

Note: If you are using version 7 of Tomcat you will need to change “keypass” to “keystorePass”.

Save your changes to the server.xml file.

Restart Tomcat Server.