Managing a Central System Keystore
A description of some of the tasks one might need to perform when SSL-ifying Tomcat.
Generate a Self-signed Certificate
[root@stubing bin]# keytool -genkey -alias tomcat -keyalg RSA -keystore /etc/.keystore -storepass "my password"
Note: if desired, add option "-validity valDays" to specify the number of days the certificate will be valid. The default is 3 months.
What is your first and last name?
[Unknown]: sakai2.ucdavis.edu
What is the name of your organizational unit?
[IET]: IET
What is the name of your organization?
[University of California Davis]:
What is the name of your City or Locality?
[Davis]:
What is the name of your State or Province?
[California]:
What is the two-letter country code for this unit?
[US]:
Is CN=sakai2.ucdavis.edu, OU=IET, O=University of California Davis, L=Davis, ST=California, C=US correct?
[no]: yes
Enter key password for <tomcat>
(RETURN if same as keystore password):
[root@stubing bin]# chmod 640 /etc/.keystore
[root@stubing bin]# chgrp sakai /etc/.keystore
[root@stubing bin]# ls -l /etc/.keystore
-rw-r----- 1 root sakai 1414 Jan 19 11:41 /etc/.keystore
[root@stubing bin]# keytool -list -keystore /etc/.keystore
Enter keystore password: my password
Keystore type: jks
Keystore provider: SUN
Your keystore contains 4 entries
...
sakai-dev, Mar 7, 2006, keyEntry,
Certificate fingerprint (MD5): F0:7E:4F:D4:82:FD:E4:4A:64:2A:84:7C:31:61:A9:EC
...
[root@stubing bin]#
Then enable the SSL connector in the server.xml file.
Acquire and install a certificate from an "offical" CA
Generate a new keypair, specifying an alias for the collection of records in the keystore related to this CN
[root@isaac bin]# keytool -genkey -alias sakai-dev -keyalg RSA -keystore /etc/.keystore -storepass "my password"
What is your first and last name?
[sakai-dev]: sakai-dev.ucdavis.edu
What is the name of your organizational unit?
[IET-IR]:
What is the name of your organization?
[University of California Davis]:
What is the name of your City or Locality?
[Davis]:
What is the name of your State or Province?
[CA]:
What is the two-letter country code for this unit?
[US]:
Is CN=sakai-dev.ucdavis.edu, OU=IET-IR, O=University of California Davis, L=Davis, ST=CA, C=US correct?
[no]: yes
Enter key password for <sakai-dev>
(RETURN if same as keystore password):
[root@isaac bin]#
Use the new keypair to generate the CSR, which can be verified using openssl if desired
[root@isaac bin]# keytool -certreq -alias sakai-dev -keyalg RSA -file /root/sakai-dev.csr -keystore /etc/.keystore
Enter keystore password: my password
[root@isaac bin]# openssl req -noout -text -in /root/sakai-dev.csr|grep CN
Subject: C=US, ST=CA, L=Davis, O=University of California Davis, OU=IET-IR, CN=sakai-dev.ucdavis.edu
[root@isaac bin]#
Note that you can't use the certificate as-is, like with Apache/OpenSSL:
[root@isaac java5]# keytool -import -alias sakai-dev -file /root/sakai-dev.cert -keystore /etc/.keystore Enter keystore password: my password keytool error: java.lang.Exception: Failed to establish chain from reply [root@isaac java5]#
You must first convert the certificate to PKCS#7 format. Grab the cert from GeoTrust (a.k.a. Equifax) using the tool of your choice, e.g.
Note: As of 8/2007, the correct cert. is: Equifax_Secure_Certificate_Authority.cer
hotep> curl https://www.geotrust.com/resources/root_certificates/certificates/Equifax_Secure_Certificate_Authority.cer
cletus> curl https://www.geotrust.com/resources/root_certificates/certificates/Equifax_Secure_Global_eBusiness_CA-1.cer -----BEGIN CERTIFICATE----- MIICkDCCAfmgAwIBAgIBATANBgkqhkiG9w0BAQQFADBaMQswCQYDVQQGEwJVUzEc MBoGA1UEChMTRXF1aWZheCBTZWN1cmUgSW5jLjEtMCsGA1UEAxMkRXF1aWZheCBT ZWN1cmUgR2xvYmFsIGVCdXNpbmVzcyBDQS0xMB4XDTk5MDYyMTA0MDAwMFoXDTIw MDYyMTA0MDAwMFowWjELMAkGA1UEBhMCVVMxHDAaBgNVBAoTE0VxdWlmYXggU2Vj dXJlIEluYy4xLTArBgNVBAMTJEVxdWlmYXggU2VjdXJlIEdsb2JhbCBlQnVzaW5l c3MgQ0EtMTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAuucXkAJlsTRVPEnC UdXfp9E3j9HngXNBUmCbnaEXJnitx7HoJpQytd4zjTov2/KaelpzmKNc6fuKcxtc 58O/gGzNqfTWK8D3+ZmqY6KxRwIP1ORROhI8bIpaVIRw28HFkM9yRcuoWcDNM50/ o5brhTMhHD4ePmBudpxnhcXIw2ECAwEAAaNmMGQwEQYJYIZIAYb4QgEBBAQDAgAH MA8GA1UdEwEB/wQFMAMBAf8wHwYDVR0jBBgwFoAUvqigdHJQa0S3ySPY+6j/s1dr aGwwHQYDVR0OBBYEFL6ooHRyUGtEt8kj2Puo/7NXa2hsMA0GCSqGSIb3DQEBBAUA A4GBADDiAVGqx+pf2rnQZQ8w1j7aDRRJbpGTJxQx78T3LUX47Me/okENI7SS+RkA Z70Br83gcfxaz2TE4JaY0KNA4gGK7ycH8WUBikQtBmV1UsCGECAhX2xrD2yuCRyv 8qIYNMR1pHMc8Y3c7635s3a0kr/clRAevsvIO1qEYBlWlKlV -----END CERTIFICATE----- cletus>
Note that trying to grab the certificate using a web browser will likely result in the certificate simply being imported into the browser's cache, rather than being downloaded. Once you have it, concatenate your certificate with it, then import:
[root@isaac ~]# cat equifax_ca-1.cert sakai-dev.cert > dev.pkcs
[root@isaac java5]# keytool -import -alias sakai-dev -file /root/dev.pkcs -keystore /etc/.keystore
Enter keystore password: my password
Top-level certificate in reply:
Owner: CN=Equifax Secure Global eBusiness CA-1, O=Equifax Secure Inc., C=US
Issuer: CN=Equifax Secure Global eBusiness CA-1, O=Equifax Secure Inc., C=US
Serial number: 1
Valid from: Sun Jun 20 21:00:00 PDT 1999 until: Sat Jun 20 21:00:00 PDT 2020
Certificate fingerprints:
MD5: 8F:5D:77:06:27:C4:98:3C:5B:93:78:E7:D7:7D:9B:CC
SHA1: 7E:78:4A:10:1C:82:65:CC:2D:E1:F1:6D:47:B4:40:CA:D9:0A:19:45
... is not trusted. Install reply anyway? [no]: yes
Certificate reply was installed in keystore
[root@isaac java5]# keytool -list -keystore /etc/.keystore
Enter keystore password: my password
Keystore type: jks
Keystore provider: SUN
Your keystore contains 4 entries
...
sakai-dev, Mar 9, 2006, keyEntry,
Certificate fingerprint (MD5): 7D:C5:7D:A7:43:3B:F6:AD:26:E7:7F:30:05:3B:D5:54
...
[root@isaac java5]#
Repeat with a different keystore alias for each CN
Specify a particular certificate for Tomcat to present
This part of the procedure is completely undocumented, save for an obscure mailing list posting and, of course, this page. This part is actually trivial; simply specify the keyAlias in the appropriate connector in Tomcat instance's server.xml file, like so:
<Connector port="8543" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS" keystoreType="JKS"
keystoreFile="/etc/.keystore" keyAlias="sakai-dev" keystorePass="my password" />
then restart Tomcat.
Note: If following the example above for generating a Self-signed Cert., the "keyAlias" here would be "tomcat".
Verifying Client Certificates
Tomcat references a different keystore when asked to verify certificates presented by clients. To import a CA certificate into that keystore, simply point keytool to the appropriate location.
[root@casweb4 security]# $JAVA_HOME/bin/keytool -v -import -alias iet-ca -file /root/ucd_iet_ca.pem -trustcacerts -keystore /ucd/opt/java5/jre/lib/security/cacerts
Enter keystore password:
Owner: EMAILADDRESS=iet-ca@ucdavis.edu, CN=UC Davis IET CA, OU=IET, O=University of California Davis, L=Davis, ST=California, C=US
Issuer: EMAILADDRESS=iet-ca@ucdavis.edu, CN=UC Davis IET CA, OU=IET, O=University of California Davis, L=Davis, ST=California, C=US
Serial number: 0
Valid from: Mon Apr 28 10:54:40 PDT 2003 until: Thu Apr 25 10:54:40 PDT 2013
Certificate fingerprints:
MD5: B1:63:EA:67:25:4E:95:41:A6:48:4D:55:EC:59:50:91
SHA1: C1:93:56:E5:36:3F:F7:5C:5D:C1:D1:6D:AE:EB:A7:8E:AD:85:21:84
Trust this certificate? [no]: yes
Certificate was added to keystore
[Storing /ucd/opt/java5/jre/lib/security/cacerts]
[root@casweb4 security]#