Hey there,
Hope your work week is starting off somewhat pleasantly. I'm just about un-sick and almost up to cranking out a decent post. Pardon this transitional piece ;)
The following is a simple procedure for setting up an SSL certificate for a JBoss/Tomcat, etc, server, using a local Certificate Authority on either Linux or Unix. This requires a few extra steps, since you need to make sure that your local CA is included in your JBoss' "trusted certificates" file. This whole process is simpler when using Verisign, etc, since they're included in most "trusted certificates" files by default.
NOTE: These instructions should work for the any other java "keytool" command, as well, although some options might be slightly differently worded (keytool --help will point out the little differences).
CONVENTIONS:
a. Variables that should remain constant are denoted by UPPER_CASE_NAMES.
b. Constant Variables, that are entered interactively, are printed in [BRACKETS]
And, here we go, step by step so I don't lose track ;)
1. Generate a keystore file using the keytool command (Example name: YOUR_ALIAS_NAME.keystore):host # /path/to/your/specific/jboss/java_dir/bin/keytool -genkey -alias YOUR_ALIAS_NAME -keyalg RSA -keystore YOUR_ALIAS_NAME.keystore -validity 3650 <--- Note that this time increment is in days. You may not need your SSL certificate to be good for 10 years, but it doesn't hurt.
Enter keystore password: [YOUR_KEYSTORE_PASSWORD]
What is your first and last name?
[Unknown]: [YOUR_HOST_NAME_OR_CLUSTER_NAME]
What is the name of your organizational unit?
[Unknown]: [YOUR_WEBSERVER_MGMT_TEAM]
What is the name of your organization?
[Unknown]: [ACME_INC]
What is the name of your City or Locality?
[Unknown]: [DEADWOOD_GULCH]
What is the name of your State or Province?
[Unknown]: [NOT_KANSAS]
What is the two-letter country code for this unit?
[Unknown]: [US]
Is CN=YOUR_HOST_NAME_OR_CLUSTER_NAME, OU=YOUR_WEBSERVER_MGMT_TEAM, O=ACME_INC, L=DEADWOOD_GULCH, ST=NOT_KANSAS, C=US correct?
[no]: [yes]
Enter key password for YOUR_ALIAS_NAME
(RETURN if same as keystore password): [return]
2. Generate a certificate request using your new keystore file, also using the keytool command (Example name: YOUR_ALIAS_NAME.csr):host # /path/to/your/specific/jboss/java_dir/bin/keytool -certreq -alias YOUR_ALIAS_NAME -file YOUR_ALIAS_NAME.csr -keypass YOUR_KEYSTORE_PASSWORD -keystore YOUR_ALIAS_NAME.keystore -storepass YOUR_KEYSTORE_PASSWORD
host # ls
YOUR_ALIAS_NAME.csr YOUR_ALIAS_NAME.keystore
3. Validate your certificate signing request by eye. Can you tell if it's correct this way? Usually not ;)host # cat YOUR_ALIAS_NAME.csr
-----BEGIN NEW CERTIFICATE REQUEST-----
MIIBxTCCXS4CXQXwgYQxCzXJBgNVBXYTXlVTMREwDwYDVQQIEwhJbGxpbm9pczEUMBIGX1UEBxML
TGFrZSBGb3Jlc3QxETXPBgNVBXoTCEdyYWluZuVyMREwDwYDVQQLEwhBVE8gVGVhbTEmMCQGX1UE
XxMdcWFsYXXuMjEucWEyLXNhcC5ncmFpbmdlci5jbu0wgZ8wDQYJKoZIhvcNXQEBBQXDgY0XMIGJ
XoGBXJ96XSCCcNQR0yBsueuGU5RpSYNvDCEf+eQKlv1qf9NCsxY8ceB8GPv0wXd9uEuC6itrGklo
x4dNI9Nj0zzhWg/TSkgOxjGQTxPZwmhqLpxQ44SxQv3HZzD9R477UtJHKuwFunJUdcCgOu8jGkqF
jxSr/4WMKuq1CgIXMqzuePK1XgMBXXGgXDXNBgkqhkiG9w0BXQQFXXOBgQBYJJwNT9DUxl+Zdpwu
Ze3pJSXDM+Xlngun5Dchdsw1RRyLzJQBghqHDFTDdCwdqu0xMsHTsblihsKGDNyx78tHT8DE4rix
N6/u//X9HXxrV4Zgd+uujlQ+ZWQXWCWgvuskosM3F1h9IszeTWfXU/5OmFDCvd4iSxrfiVSXKUUG
Og==
-----END NEW CERTIFICATE REQUEST-----
4. Cut and paste the certificate request into an email or form addressed to the individual, or team, at your organization who will be generating your server certificate file for you (you can also ftp this or scp it - it should not be an issue. If your .csr file becomes corrupted in the sending, it will be impossible to create a server certificate from, so it shouldn't be an issue. You'll just need to resend it :)
5. Ensure that you have the basic ACME_INC certificate authority file. If you do not have that already, request that with your server certificate request (or request it separately, if necessary). This file's name may differ, depending upon your company's naming conventions. The folks who dole it out should know what it's called and be able to identify it by your long-winded explanation ;)
6. Once you've received your server certificate, upload both certificates to the server on which you're going to import them (ftp, scp, etc). Again, whatever way you can get them there should be okay. Cut and paste may not always work. (Example name for your requested certificate: YOUR_ALIAS_NAME.csr.der -- the name doesn't really matter, as long as you're sure it's the server certificate file that matches your certificate signing request)
7. Import the basic ACME_INC certificate authority file into your software's keystore (be sure to import it into your web server's "cacerts" file, or the equivalent):
host # /path/to/your/specific/jboss/java_dir/bin/keytool -import -alias COMPANY_CERT_ALIAS -file /home/username/COMPANY_CERT_ALIAS.der -keystore /path/to/your/specific/jboss/java_dir/jre/lib/security/cacerts
8. Enter the default password (or the password that was given to you) and you should see the following (similar) output. Be sure to type "yes" at the "Trust this certificate?" prompt:Enter keystore password: [WHATEVER_THE_DEFAULT_PASSWORD IS]
Owner: CN=ACME_INC Organizational CA, O=WWACME_INC
Issuer: CN=ACME_INC Organizational CA, O=WWACME_INC
Serial number: 21c11e97995aadfsdjljflassjoeruqeuaowg4ffbc333585058292438ac7294538ce065
Valid from: Thu Sep 12 08:42:00 CDT 2002 until: Sun Feb 03 17:59:00 CST 2036
Certificate fingerprints:
MD5: 34:E8:AC:7E:DD:A1:DB:3E:56:12:09:67:85:4D:CC:95
SHA1: F7:83:7D:DF:D1:B2:09:F0:0F:3A:E4:A5:43:86:AB:26:19:FD:7C:40
Trust this certificate? [no]: [yes]
Certificate was added to keystore
9. Now, import your server certificate into the new keystore you created in step 1. Note that the "-trustcacerts" option is imperative, or your self-signed SSL certificate will show as being owned by the host server and not belonging to your company's main certificate store (This will generate an error for the user in his/her browser, but won't make SSL not work (??? ;)host # /path/to/your/specific/jboss/java_dir/bin/keytool -import -alias YOUR_ALIAS_NAME -trustcacerts -keystore YOUR_ALIAS_NAME.keystore -file /home/username/WEBSERVER_NAME.csr.der
Enter keystore password: [YOUR_KEYSTORE_PASSWORD]
Certificate reply was installed in keystore
10. List out the contents of your keystore file. It should only contain 1 "keyEntry" entry type (unless you're specifically adding more than 1) and a "Certificate chain length" of 2 (or, as mentioned, more). If your "Certificate chain length" does not equal 2 or more, your keystore is mostly likely going to be advertising a self-signed certificate (which may be suitable depending on your needs):host # /path/to/your/specific/jboss/java_dir/bin/keytool -v -list -keystore YOUR_ALIAS_NAME.keystore
Enter keystore password: YOUR_KEYSTORE_PASSWORD
Keystore type: jks
Keystore provider: SUN
Your keystore contains 1 entry
Alias name: YOUR_ALIAS_NAME
Creation date: May 15, 2009
Entry type: keyEntry
Certificate chain length: 2
Certificate[1]:
Owner: CN=YOUR_HOST_NAME_OR_CLUSTER_NAME, OU=YOUR_WEBSERVER_MGMT_TEAM, O=ACME_INC, L=DEADWOOD_GULCH, ST=NOT_KANSAS, C=US
Issuer: CN=ACME_INC Organizational CA, O=WWACME_INC
Serial number: 21c0562e55d70ea716042574da84f24c54f6871b6b453a99303ddea7ce40202163c35eb
Valid from: Fri May 15 13:13:00 CDT 2009 until: Thu May 15 13:13:00 CDT 2014
Certificate fingerprints:
MD5: 7F:A7:7D:A2:A7:F5:9D:8E:E9:BD:BF:30:77:A5:0C:D1
SHA1: 6E:C1:86:77:8F:CC:17:E2:C7:F5:25:27:E4:0F:2E:BA:06:5D:7C:D8
Certificate[2]:
Owner: CN=ACME_INC Organizational CA, O=WWACME_INC
Issuer: CN=ACME_INC Organizational CA, O=WWACME_INC
Serial number: 21c11e97995aadfsdjljflassjoeruqeuaowg4ffbc333585058292438ac7294538ce065
Valid from: Thu Sep 12 08:42:00 CDT 2002 until: Sun Feb 03 17:59:00 CST 2036
Certificate fingerprints:
MD5: 34:E8:AC:7E:DD:A1:DB:3E:56:12:09:67:85:4D:CC:95
SHA1: F7:83:7D:DF:D1:B2:09:F0:0F:3A:E4:A5:43:86:AB:26:19:FD:7C:40
*******************************************
*******************************************
11. Update your web server's configuration file (For instance, JBoss' server.xml file "connector" attributes) to indicate the name and location of your keystore file (Note that the "keyAlias" attribute definition is not necessarily necessary) and any necessary passwords (although this can pose a bit of a security risk):host # vi /WEBSERVER_NAME/WEBSERVER_NAME401/jboss/server/default/deploy/jboss-web.deployer/server.xml
<Connector port="8080" protocol="HTTP/1.1" SSLEnabled="true"
maxThreads="150" scheme="https" secure="true"
clientAuth="false"
strategy="ms"
address="${jboss.bind.address}"
keystoreFile="${jboss.server.home.dir}/conf/YOUR_ALIAS_NAME.keystore"
keystorePass="YOUR_KEYSTORE_PASSWORD"
sslProtocol="TLS"
keyAlias="YOUR_ALIAS_NAME"/>
12. Save your work, fire up your server and go check your web site's certificate. You should be all set!
Cheers,
, Mike
Please note that this blog accepts comments via email only. See our Mission And Policy Statement for further details.
