Using the Keytool

The keytool supplied with Wadjet was originally developed to fix the annoying fault in the Java keytool program. keytool opens the key store file before asking for a password which means that using it with encrypted key stores you have to type the password on the command line and then anyone running ps can see your password. I also found that getting the password as clear text on the terminal should be improved and hoped that Java 1.4 might at last solve this. As it didn’t I kept the StrUtils.readPassword() method that more or less clears the line while you type.

The kstool utility can be used to replace the Java keytool and supports all the same functionality and then some more:

• Generate a fully conformant V3 X.509 Certificate Authority key pair,
• Generate secret keys into a key store (not all key stores support this, Bouncy Castle does),
• Sign a certificate with another key pair in the same or a different key store,
• Export a certificate chain to a PEM file,
• Import OpenSSL files to the Java key store,
• Copy a key store from one type to another,
• Print out full certificate information including key usage.

I also changed the way the tool interprets the –provider parameter, you give it the provider name (SUN, BC, etc.) rather than having to remember the full class name.

The tool uses the BouncyCastle JCE provider to generate V3 X.509 certificates with key usage, path length for CA certificates and the possibility of inputting X.520 distinguished names.

Unlike the Sun keytool, it defaults to creating RSA/MD5 key-pairs and Blowfish 256-bit secret keys.

Like the Sun keytool, you will get a list of possible commands and parameters if you run the tool with no parameters. Like the Sun version, this help is not very easy to decipher so I will try to explain some of the new commands and parameters better here. All the other parameters and commands are described in the keytool documentation on the Java site. You should also see the API documentation for com.addc.tools.keytool.KsTool.

Back to top

-gencakey

Generates a 2048-bit RSA with MD5 certificate and private key marked as a Certificate Authority certificate that has key usage keyCertSign + cRLSign with an infinite path length and 10 year validity. The key algorithm and size can be changed with the keyalg and keysize parameters. The path length and the validity can be modified with the parameters:

• -pathlen length
• -validity days

Example:

  $ kstool –gencakey –keystore store –storetype BouncyCastle –alias caentry –v

Generates a 2048-bit RSA CA certificate and private key under the alias caentry in the key store store which is a BouncyCastle key store.

Back to top

-sign

Signs a certificate with another and introduces a completely new set of parameters:

• -skeystore keystore with signing alias
• -sstoretype the signer keystore type
• -sprovider the signer provider name
• -salias the alias of the signing key pair

Example:

  $ kstool –sign –keystore store –alias test –skeystore castore –salias cacert

Signs the certificate under the alias test in the key store store with the certificate and private key under the alias cacert in the key store castore. Both key stores are of the default type.

Back to top

-genskey

Generates a secret key in the key store for a given alias. The –keyalg and –keysize parameters should be set accordingly.

Example:

  $ kstool –genskey –alias secret –keystore store –storetype BouncyCastle –provider BC

Generates a 256-bit Blowfish secret key under the alias secret in the keystore store.

Some key stores like JKS and PKCS12 don’t store secret keys correctly, use the BouncyCastle key store to save secret keys.

Back to top

–gensigned

Generates a new key pair and signs it. This takes the same extra parameters as the –sign command.

Example

  $ kstool –gensigned –keystore store –alias test –skeystore castore –salias cacert

Generates a new 1024-bit RSA certificate under the alias test in the key store store and signs it with the certificate and private key under the alias cacert in the key store castore. Both key stores are of the default type.

Back to top

–openssl

Imports an OpenSSL private key file and certificate file to a Java keystore. This introduces the following new parameters:

• -pkfile the private key file
• -cfile the certificate file

Example

  $ kstool –openssl –keystore test –alias openssl –cfile cert.pem –pkfile key.pem

imports the private key in key.pem and the corresponding certificate in cert.pem to the alias openssl in the key store test.

Back to top

–clonestore

Clones a key store allowing you to copy the contents of one key store to another of a different type, this introduces a new set of parameters:

• -dkeystore the destination key store
• -dstoretype the destination store type
• -dprovider the destination store provider

If the source store contains secret keys and the destination does not support them, the copy will fail.

Example

  $ kstool –clonestore –keystore cacerts –dkeystore .cacerts –storetype BouncyCastle

Copies the entries in the JKS key store cacerts to the BouncyCastle key store .cacerts.

Back to top

Ant Keytool Tasks

There are two ant tasks supplied with the Keytool, the GenCAKeyPairTask and the GenSignedSSLCertsTask. These classes allow you to generate a CA certificate and a set of SSL certificates using an ant build.

The GenCA Task

This task should be declared in a taskdef element before being used

<taskdef name="genca"
         classname="com.addc.keytool.GenCAKeyPairTask"
         classpath="${lib}/wj-security-110.jar"/>

It can them be used in the build task:

<genca
    ksname="${ssl.cert.repository}/.castore"
    kspass="${ca.pass}"
    keypass="${ca.key.pass}"
    alias="${ca.alias}"
    validity="${ca.validity}"
    dname="C=${CA_C},L=${CA_L},O=${CA_O},OU=${CA_OU},CN=${CA_CN}"
    certfile="${ssl.cert.repository}/pfca.pem"
    rfc="true"/>

The parameters that are accepted by the task are shown in the table

Back to top

The GenSSL Certificates Task

This task allows you to generate a set of SSL certificates for a set of hostnames. The hostnames and optional key store definitions are read from a file. The task is defined in the build.xml file:

<taskdef name="gencerts"
    classname="com.addc.keytool.GenSignedSSLCertsTask"
    classpath="${lib}/wj-security-110.jar"/>

The task can then be invoked:

<gencerts
    hostsfilename="${hosts.file}"
    rfc="on"
    pem="on"
    verbose="on"
    dirperhost="on"
    kspass="${machine.pass}"
    sksname="${ssl.cert.repository}/.castore"
    skspass="${ca.pass}"
    skeypass="${ca.key.pass}"
    salias="${ca.alias}"
    filename="${ssl.cert.repository}"
    dname="OU=${CA_OU},O=${CA_O},L=${CA_L},C=${CA_C}"/>

The task accepts the parameters shown in the table.

The hosts file contains a list of definitions for each host on one line, the format is

<hostname> [-kstore <store>] [-kspass <password>] [-keypass <password>] [-uid <uid>]

where each line must start with the host name and the other parameters are optional:

• -kstore The keystore file name for the host.
• -kspass The password for host’s key store.
• -keypass The alias entry password.
• -uid The LDAP UID which is added to the distinguished name.

Back to top

Secure Delete

The secure delete utility will first write random data into the file to overwrite any data and then delete the file, to run this use the rmsec script:

  $ rmsec path/to/file

Generating swing.properties

This utility will search the extension directories for jar fiels containing LookAndFeel implementations and add them to the swing.properties file.

  $ genswingprops

Generate The Httpd Password File

This utility is a another command line tool that allows you to generate the password files for the Wadjet-HTTP http daemon. It is interactivr and generates both the digest and basic entries for the authenticators.

   $ httppassword