Tomcat currently operates only on JKS, PKCS11 or
PKCS12 format keystores. The JKS format
is Java's standard "Java KeyStore" format, and is the format created by the
keytool command-line utility. This tool is included in the JDK.
The PKCS12 format is an internet standard, and can be manipulated
via (among other things) OpenSSL and Microsoft's Key-Manager.
Each entry in a keystore is identified by an alias string. Whilst many
keystore implementations treat aliases in a case insensitive manner, case
sensitive implementations are available. The PKCS11 specification,
for example, requires that aliases are case sensitive. To avoid issues related
to the case sensitivity of aliases, it is not recommended to use aliases that
differ only in case.
To import an existing certificate into a JKS keystore, please read the
documentation (in your JDK documentation package) about keytool.
Note that OpenSSL often adds readable comments before the key,
keytooldoes not support that, so remove the OpenSSL comments if
they exist before importing the key using keytool.
To import an existing certificate signed by your own CA into a PKCS12
keystore using OpenSSL you would execute a command like:
 |
|
|
|
openssl pkcs12 -export -in mycert.crt -inkey mykey.key "
-out mycert.p12 -name tomcat -CAfile myCA.crt "
-caname root -chain
|
|
|
|
|
For more advanced cases, consult the OpenSSL
documentation.
To create a new keystore from scratch, containing a single self-signed
Certificate, execute the following from a terminal command line:
Windows:
|
|
|
|
%JAVA_HOME%"bin"keytool -genkey -alias tomcat -keyalg RSA
|
|
|
|
|
Unix:
|
|
|
|
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
|
|
|
|
|
(The RSA algorithm should be preferred as a secure algorithm, and this
also ensures general compatibility with other servers and components.)
This command will create a new file, in the home directory of the user
under which you run it, named ".keystore". To specify a
different location or filename, add the -keystore parameter,
followed by the complete pathname to your keystore file,
to the keytool command shown above. You will also need to
reflect this new location in the server.xml configuration file,
as described later. For example:
Windows:
|
|
|
|
%JAVA_HOME%"bin"keytool -genkey -alias tomcat -keyalg RSA "
-keystore "path"to"my"keystore
|
|
|
|
|
Unix:
|
|
|
|
$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA "
-keystore /path/to/my/keystore
|
|
|
|
|
After executing this command, you will first be prompted for the keystore
password. The default password used by Tomcat is "changeit"
(all lower case), although you can specify a custom password if you like.
You will also need to specify the custom password in the
server.xml configuration file, as described later.
Next, you will be prompted for general information about this Certificate,
such as company, contact name, and so on. This information will be displayed
to users who attempt to access a secure page in your application, so make
sure that the information provided here matches what they will expect.
Finally, you will be prompted for the key password, which is the
password specifically for this Certificate (as opposed to any other
Certificates stored in the same keystore file). You MUST
use the same password here as was used for the keystore password itself.
(Currently, the keytool prompt will tell you that pressing the
ENTER key does this for you automatically.)
If everything was successful, you now have a keystore file with a
Certificate that can be used by your server.
Note: your private key password and keystore password
should be the same. If they differ, you will get an error along the lines
of java.io.IOException: Cannot recover key, as documented in
Bugzilla issue 38217,
which contains further references for this issue.