This article describes how to configure, enable, and use SSL keys and certificates with the Jetty web server for xMatters customers using our on-premises product version 5.1.
NOTE: This article is not intended to be a comprehensive security document, and does not include information related to the strength of ciphers or security standards. You should always consider the key strength and size that is required by your organization. xMatters always follows industry best practices and standards published by security authorities. It is recommended that premise-based clients use an enterprise-grade proxy server to front and load-balance the xMatters user interface.
When following the information in this article, ensure that you back up relevant files before overwriting or deleting them. Work with your network staff to obtain the following information for production installations:
- DNS Domain for your URL
- Internet-facing IP Address
- Internet-facing DNS Entry for the latter IP address in the desired DNS Domain
You must also install the Java Development Kit (5.0 or later), which provides the keytool command referenced in this article. It is a best practice to place the JDK binaries on the classpath so that the keytool command is accessible from any directory. To learn more about keytool, click here.
NOTE: if you only want to renew a certificate, click here.
Generating a keystore
To generate a keystore, run the following command (the parameters are explained below):
keytool -genkey -keystore <your.keystore.file> -storepass <password> -keypass <password> -keyalg RSA -alias <your.alias> -dname
"CN=<your.internet.facing.url> , OU=<your.org.unit>, O=<your.company>, L=<your.city> , ST=<your.state>, C=<your.country>"
Replace the placeholder parameters in the command with the actual values, as explained in the following points:
- - This will be the file that will hold the certificate/key pair and any certificate chains. Do not lose this file. If you have a revision control or document management system you should add this file to it when the process is done.
- (-storepass)- Password to protect access to the keystore file.
- (-keypass) - Password to protect access to the private key of the generate key pair.
- - Alias you chose to store your key/cert pair.
- - Internet-facing URL to which the certificate will be bound. If the URL used to navigate your site and the URL in the certificate are not identical, you will receive certificate warnings.
- -dname values - Distinguished name values. For full details, see the following excerpt from the keytool URL referenced in the previous section.
X.500 Distinguished Names are used to identify entities, such as those which are named by the
issuer(signer) fields of X.509 certificates. keytool supports the following subparts
- commonName - common name of a person, e.g., "Susan Jones"
- organizationUnit - small organization (e.g, department or division) name, e.g., "Purchasing"
- organizationName - large organization name, e.g., "ABCSystems, Inc."
- localityName - locality (city) name, e.g., "Palo Alto"
- stateName - state or province name, e.g., "California"
- country - two-letter country code, e.g., "CH"
When supplying a distinguished name string as the value of a
-dnameoption, as for the
-selfcertcommands, the string must be in the following format:CN=cName, OU=orgUnit, O=org, L=city, S=state, C=countryCod
where all the italicized items represent actual values and the above keywords are abbreviations for the following:CN=commonName OU=organizationUnit O=organizationName L=localityName S=stateName C=country
A sample distinguished name string isCN=Mark Smith, OU=JavaSoft, O=Sun, L=Cupertino, S=California, C=USand a sample command using such a string iskeytool -genkey -dname "CN=Mark Smith, OU=JavaSoft, O=Sun, L=Cupertino, S=California, C=US" -alias mark
Case does not matter for the keyword abbreviations. For example, "CN", "cn", and "Cn" are all treated the same.
Order matters; each subcomponent must appear in the designated order. However, it is not necessary to have all the subcomponents. You may use a subset, for example:CN=Steve Meier, OU=SunSoft, O=Sun, C=US
If a distinguished name string value contains a comma, the comma must be escaped by a "\" character when you specify the string on a command line, as incn=peter schuster, o=Sun Microsystems\, Inc., o=sun, c=us
It is never necessary to specify a distinguished name string on a command line. If it is needed for a command, but not supplied on the command line, the user is prompted for each of the subcomponents. In this case, a comma does not need to be escaped by a "\".
- For -dname, do not leave any fields empty (empty fields the CA will consider the CSR as invalid).
- Provide the full name for ST field of -dname (e.g., use New York instead of NY).
- Use the two-letter country code in the C field of -dname.
The following command shows an example command with parameter placeholders replaced with sample parameters:
keytool -genkey -keystore keystore -storepass 123456ABC -keypass 123456ABC -keyalg RSA -alias jetty -dname
"CN=www.company.com , OU=information_services, O=ABC, L=New York , ST=New York, C=US"
Generate Certificate Signing Request (CSR)
This command generates a Certificate Signing Request (CSR) that is used to request a certificate from a certificate authority, based on your generated key:
- keytool -certreq -keyalg RSA -keystore <your.keystore.file> -storepass <password> -alias <your.alias> -file certreq.csr
Submit Certificate Signing Request to Certificate Authority (CA)
- Purchase a certificate from a trusted certificate authority such as VeriSign, Network Solutions, or Thawte.
- Ensure that the vendor's certificates are trusted by most modern web browsers. As part of this process, the certificate vendor will attempt to verify your identity, your company's identity, and that you are an authorized representative of the company. The vendor should also verify that the URL you are requesting for the certificate is valid and owned by your company. In your planning and scheduling, you should allow at least 3-10 business days for this process. For planning purposes, it is recommended that you discuss time lines directly with the certificate vendor.
- Make a note of the certificate's expiration date so that it can be renewed before expiry (tip: set a calendar reminder well before the certificate expiry date).
- When you are prompted for an email address for certificate management, it is recommended that you set this address to a group account (i.e., so that several people will be notified about any certificate issues such as expiration).
Add certificates to keystore
After you have received the certificate (and possibly the certificate chain files) you need to add them to the keystore you used to generate the CSR. After adding the certificate, the keystore will be ready for use by Jetty. Back up the keystore and record all related information (e.g., password).
To add the certificates, run the following commands:keytool -import -alias <your.root.alias> -keystore <your.keystore.filename> -trustcacerts -file <filename_of_the_chain_certificate>
keytool -import -alias <your.alias> -keystore <your.keystore.filename> -trustcacerts -file <your_certificate_filename>
Assume that you receive a trial SSL certificate from VeriSign using the generated .csr file; you will receive three certificates: your SSL certificate, a root CA certificate and an intermediate CA certificate. Save them to jetty.crt, rootCA.cer and intermediateCA.crt respectively and import these certificates into a keystore named "keystore".
keytool -import -alias jetty_int -keystore keystore -trustcacerts -file intermedicateCA.crt
keytool -import -alias jetty_root -keystore keystore -trustcacerts -file rootCA.cer
keytool -import -alias jetty -keystore keystore -trustcacerts -file jetty.crt
After you have imported these certificates, your keystore should look similar to the following:
Keystore type: jks
Keystore provider: SUN
Your keystore contains 3 entries
jetty, Apr 7, 2009, keyEntry,
Certificate fingerprint (MD5): D2:EB:4E:8F:C5:D9:9E:7E:63:68:21:64:47:19:43:E0
jetty_root, Apr 7, 2009, trustedCertEntry,
Certificate fingerprint (MD5): B6:9D:A4:40:52:02:50:0D:D5:9C:E1:B8:4B:66:C4:AC
jetty_int, Apr 7, 2009, trustedCertEntry,
Certificate fingerprint (MD5): 8D:E9:89:DB:7F:CC:5E:3B:FD:DE:2C:42:08:13:EF:43
After you have prepared your keystore file, you must configure Jetty to use it.
To configure Jetty:
- Back up the original keystore.
- Copy the keystore file to webserver/resources and remove the default keystore file that comes with xMatters.
- Navigate to the webserver/etc/jetty-ssl.xml file and open it in a text editor.
- Locate the following text and replace <your.keystore.filename> with the name of your keystore file (note that you must also replace <your.store.password>, <your.key.password>, and <your.trust.password> with the actual values from the initial keystore creation in the "Generating a Keystore" section):
<Call name="addConnector"> <Arg> <New class="org.mortbay.jetty.security.SslSocketConnector"> <Set name="Port">8443</Set> <Set name="maxIdleTime">30000</Set> <Set name="handshakeTimeout">2000</Set> <Set name="keystore"> <SystemProperty name="jetty.home" default="." />/resources/<your.keystore.filename> </Set> <Set name="password"> <your.store.password> </Set> <Set name="keyPassword"> <your.key.password> </Set> <Set name="truststore"> <SystemProperty name="jetty.home" default="." />/resources/<your.keystore.filename> </Set> <Set name="trustPassword"><your.trust.password></Set> </New> </Arg> </Call>
- Restart your web server after making these changes.
Add root CA certificate to your browser
The final step is to add the root CA certificate to all web browsers. The following sections describe this process for the two most popular browsers, Firefox and Internet Explorer.
- Start Firefox.
- Navigate to Tools > Options > Advanced > Encryption > View Certificates > Authorities.
- Click Import.
- Navigate to your Root Certificate, and then click Open.
- Select Trust this CA to identify web sites.
- Click OK.
- Start Internet Explorer.
- Navigate to Tools > Internet Options > Content > Certificates.
- Click Import.
- On the Certificate Import Wizard, click Next.
- Click Browse and navigate to your Root Certificate, and then click Open.
- Click Next.
- Select Automatically select the certificate store based on the type of the certificate.
- Click Next, and then click Finish.
- When you are prompted to add the certificate to the root store, click Yes.
When your certificate expires, use the following steps to renew it.
To renew your SSL certificate:
- Generate a Certificate Signing Request (CSR) from your current keystore.
- Send the CSR to your CA.
- You will receive a new SSL certificate, and a number of new chain certificates. For example, from VeriSign, you should receive a new SSL Certificate, a new intermediate certificate, and a new root certificate.
- Remove the old chain certificates from the current keystore.
- For example, for certificates from VeriSign, use the following commands:
keytool -delete -alias jetty_int -keystore keystore
keytool -delete -alias jetty_root -keystore keystore
- Import the new chain certificates.
- Import the new SSL certificates.
Additional Jetty configuration information
DTN-2283, SUP-3931, SUP-2603, JDN-1228
Originally created by Don Clark