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. 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.

Advertisements

14 thoughts on “Keytool for Dummies

  1. Hi Arun,
    very good writeup.
    I have followed the steps you have mentioned to install certificates to my keystore(this has root CA cert and webserver cert and no intermediate).I used those certificate then to sign my applet using jarsigner.But when I load the applet, I am getting an alert message saying “Your security settings have blocked a self-signed application from running”.Any clue what had gone wrong?

    • Thanks for visiting my blog Divya.

      This looks like a browser configuration issue where by default a self signed certificate is blocked by the browser java. You will need to configure the browser to accept a self signed certificate.

      Below are the references.
      Please check the section “Java application with a certificate from an untrusted source” in the below given link.
      http://www.java.com/en/download/help/appsecuritydialogs.xml

      Also, if you are using IE browser, you may need to add this certificate as Trusted as noted in the below given URL.
      https://www.conetrix.com/Blog/post/How-to-Trust-a-Self-Signed-Certificate-in-IE-9.aspx

      Thanks!

      • Thanks Arun for the prompt reply.
        I am using latest java 7update 51 where the security is made strict and self signed applets and webstart applications are blocked.SO that arouse the need to sign my currently running applet with trusted CA.
        So for this I have used a certificate issued from a trusted CA (company internal CA) to sign the application.But when the application when run the alert says it’s still a self signed application.So here lies my problem.Why the application when shows as self signed while it is not.
        Please see if you can help me in this regard.

  2. Hi webmaster do you need unlimited articles
    for your site ? What if you could copy post from
    other blogs, make it pass copyscape test and publish on your website – i know the right tool for you, just search
    in google:
    Ziakdra’s article tool

  3. Arun good explanation Thank you ! One question, I saw someone do all their “keytool -import” commands without using the “-trustcacerts” option and things still worked. Why would that be ?
    Thanks again, Bill

  4. I see interesting content here. Your site can go viral easily, you need some initial traffic only.
    How to get it? Search for: ricusso’s methods massive
    traffic

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s