1. technology and computing
2. programming languages
3. java

SolarWinds Technical Reference
Using SSL Certificates in
Web Help Desk
Introduction.............................................................. 1
How WHD Uses SSL .............................................. 1
Setting WHD to use HTTPS .................................... 1
Enabling HTTPS and Initializing the Java
Keystore ............................................................. 1
Keys and Certificates ......................................... 1
Generating a New Certificate ............................. 3
Generating a Certificate Signing Request
(CSR) ................................................................. 6
Importing an Existing Certificate ........................ 8
Troubleshooting ............................................... 10
This paper covers how to use SSL Certificates
with the Web Help Desk Product.
network management simplified - solarwinds.com
Copyright © 1995-2013 SolarWinds Worldwide, LLC. All rights reserved worldwide.
No part of this document may be reproduced by any means nor modified, decompiled, disassembled, published or distributed, in
whole or in part, or translated to any electronic medium or other means without the written consent of SolarWinds. All right, title, and
interest in and to the software and documentation are and shall remain the exclusive property of SolarWinds and its respective
licensors.
SOLARWINDS DISCLAIMS ALL WARRANTIES, CONDITIONS OR OTHER TERMS, EXPRESS OR IMPLIED, STATUTORY OR
OTHERWISE, ON SOFTWARE AND DOCUMENTATION FURNISHED HEREUNDER INCLUDING WITHOUT LIMITATION THE
WARRANTIES OF DESIGN, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN
NO EVENT SHALL SOLARWINDS, ITS SUPPLIERS, NOR ITS LICENSORS BE LIABLE FOR ANY DAMAGES, WHETHER
ARISING IN TORT, CONTRACT OR ANY OTHER LEGAL THEORY EVEN IF SOLARWINDS HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
The SOLARWINDS, the SOLARWINDS & Design, DAMEWARE, ORION, and other SolarWinds marks, identified on the SolarWinds
website, as updated from SolarWinds from time to time and incorporated herein, are registered with the U.S. Patent and Trademark
Office and may be registered or pending registration in other countries. All other SolarWinds trademarks may be common law
marks or registered or pending registration in the United States or in other countries. All other trademarks or registered trademarks
contained and/or mentioned herein are used for identification purposes only and may be trademarks or registered trademarks of
their respective companies. Microsoft®, Windows®, and SQL Server® are registered trademarks of Microsoft Corporation in the
United States and/or other countries.
10/03/2013
Using SSL Certificates in Web Help Desk 1
Introduction
HTTPS is widely used for communications across the Internet. HTTPS is also called secure HTTP. It
provides a secure and encrypted communication channel between browsers and servers. HTTPS is not a
actual protocol. It is the result of layering SSL security on top of HTTP. If you use SolarWinds Web Help
Desk (WHD).across wireless or Internet connections, you should consider using HTTPS. This paper limits
the discussion of HTTPS and SSL to their use in WHD.
How WHD Uses SSL
When a browser submits an HTTPS request to Web Help Desk, the SSL protocol requires Web Help
Desk to respond with a certificate to prove the authenticity of the server. The certificate contains a public
key used for encryption and a digital signature from a Certification Authority (CA) that indicates which CA
verified the authenticity of the server.
Certificate's that have been signed by one of the large CAs such as Verisign are already trusted by most
web browsers. But that does not mean you cannot use certificates signed by a smaller CA. If a browser
does not recognize the certificate’s CA, the browser asks you to confirm trust in the certificate.
After trust has been established, the browser uses the certificate's public key to encrypt information it
sends to Web Help Desk, and Web Help Desk decrypts it using its private key. Similarly, Web Help Desk
uses its private key to encrypt information sent to the browser, and the browser uses the public key
received in the certificate to decrypt it.
Setting WHD to use HTTPS
To enable HTTPS with Web Help Desk, you must first configure the port it will listen to for HTTPS
requests and the port it will use in URLs it generates that point back to itself.
Enabling HTTPS and Initializing the Java Keystore
To enable Web Help Desk to listen to HTTPS requests, you must un-comment the HTTPS_PORT setting
in <WebHelpDesk>/conf/whd.conf by removing the pound character (#) at the beginning of the line. By
default, browsers use port 443 for SSL connections. If you use a different port, you will need to include it
in URLs to Web Help Desk. For example, if your whd.conf file contains the line
HTTPS_PORT=8443
then you would connect to Web Help Desk with the following URL:
https://localhost:8443
After setting HTTPS_PORT, restarting Web Help Desk will create a new Java keystore at
<WebHelpDesk>/conf/keystore.jks containing a self-signed certificate.
Keys and Certificates
Web Help Desk keeps its keys and certificates in a Java keystore at <WebHelpDesk>/conf/keystore.jks.
The open-source utility Porteclé (“POR-tuh-CLAY,” French for keychain), which comes bundled with Web
Help Desk, provides a graphical user interface for administering the keystore.
Default Keypair Alias and Passwords
2 Using SSL Certificates in Web Help Desk
Web Help Desk uses the Tomcat web server. The Tomcat web server requires its keypair to have the
alias tomcat. The default password to both the keypair and keystore is changeit—Tomcat requires the
keystore and keypair password be identical. To use your own password, change the
KEYSTORE_PASSWORD setting in whd.conf located at \Program Files\WebHelpDesk\whd.conf.
Replacing Self-signed Certificates with CA Certificates
Keypairs created using Porteclé are given a self-signed certificate. To replace the self-signed certificate
with a certificate signed by a CA, you must generate a Certificate Signing Request (CSR) for the keypair
and submit it to the CA. The CSR contains the public key and the name of the server, in a format defined
by the PKCS#10 standard (typically given the filename extension .p10 or .csr).
After verifying the applicant’s identity, the CA sends you a certificate you can use to replace the selfsigned certificate in the keypair. This CA Reply (or CSR Reply) is typically given as an X.509 Certificate
file (.cer, .crt, .pem, or .der) or as a PKCS#7 file (.p7b).
Adding Certificate Chains
Using SSL Certificates in Web Help Desk 3
It is possible for a trusted CA to delegate to another CA. In this case, the certificate returned by the
delegated CA will itself be signed by the trusted CA, resulting in a certificate chain. Certificate chains may
be of any length. The highest certificate in the chain, the root certificate, should be a self-signed
certificate, signed by the trusted CA.
Each certificate in the chain must be imported into the keystore so that the complete chain can be sent to
the browser. If the CA Reply does not include the chain certificates, they must be added to the keystore
manually before the CA reply. The certificates must be imported in order of dependency—i.e., the root
certificate must be added first, then the next chained certificate that was signed by the root certificate, and
so on, down to the CA reply.
Summary
If you have not yet obtained a certificate for your server, you should use Porteclé to generate both a
keypair and a CSR to send to the CA. You should then to import the CA Reply certificate.
If you already have a certificate, you must import both the certificate and the primary key into the
keystore. Porteclé does not allow you to import a primary key by itself, so you must combine it with its
certificate in a PKCS#12 file (*.p12 or *.pfx). In each case, the keypair must be aliased as “tomcat,” and
both it and the keystore must be protected by the password specified with the KEYSTORE_PASSWORD
setting in whd.conf.
Generating a New Certificate
This section explains how to create a new certificate, generate a certificate signing request (CSR), and
import the CA reply. If you already have a certificate, skip to Importing an Existing Certificate.
Creating a New Keypair
To create a new keypair:
1. Launch the Porteclé batch file from the \Program Files\WebHelpDesk folder.
2. Select the JKS file type
3. Click Protocols for SQLXXX, where XXX is your version of SQL Server.
Note: The whd.conf file is created automatically when Web Help Desk is started with the HTTPS_PORT
setting uncommented in <WebHelpDesk>/conf/whd.conf. If it does not yet exist, uncomment the
HTTPS_PORT setting and restart Web Help Desk.
4. Enter changeit in the Enter Password field.
4 Using SSL Certificates in Web Help Desk
After opening the keystore, you should see a keypair entry with the alias tomcat. This keypair was created
automatically by Web Help Desk. You will need to replace it with a new keypair that is configured for your
domain.
5. Delete the existing tomcat keypair: right-click the alias and then click Delete
6. Click Tools > Generate Key Pair
7. You will be prompted to choose an algorithm and key size. Enter either 1024 or 2048, and select
RSA.
8. Click OK. Porteclé prompts you to provide the x509 attributes for your certificate.
9. Select a Validity that matches the number of days you CA certificate will be valid. Typical validation
periods are 6, 12, or 24 months.
Note: The Validity period is the period you specified when you purchased you certificate from the CA.
10. Enter a CN that matches the site used in the certificate For example, if Web Help Desk is hosted at
support.example.com, your CN must be support.examole.com.
11. Enter an Organization Unit (OU) that helps distinguish this certificate from others for your
organization.
12. Enter an Organization Name (O), typically name for your organization.
13. Locality Name (L). This is typically a city name.
Using SSL Certificates in Web Help Desk 5
14 Enter a State Name (ST). This should be the unabbreviated city and state/province/region/territory of
your organization.
14. Enter a Country (C) This should be the two letter ISO 3166 country code for your country.
15. Email (E) is generally optional, but may be used by your CA as the address to which the certificate
will be mailed.
16. Click OK.
After clicking OK on the Generate Certificate panel, Porteclé asks you to provide an alias for the new
keypair.
17. Enter the alias tomcat, and then click OK.
You will not be asked to enter passwords for the keystore.
18.
Enter changeit in both fields, and then click Enter.
After successfully providing the keypair password, you should see the new keypair aliased by tomcat.
6 Using SSL Certificates in Web Help Desk
Generating a Certificate Signing Request (CSR)
1. Right-click the tomcat keypair and then click Generate CSR
2. Enter a name for the CSR to help you remember the domain it will validate. For example, you might
use support.example.com.csr.
Using SSL Certificates in Web Help Desk 7
This is the file you will send to your CA to request your certificate. The CA should return an x.509
certificate in DER (*.cer, *.crt), PEM (*.pem, *.cer, *.crt) or PKCS#7 (*.p7b, *.p7c) encoding.
Importing CA Chain and Root Certificates
Before importing your certificate into the keystore, you should check whether the certificate vendor
requires you to include any other certificates to complete the certificate chain.
To import a certificate, complete the following steps.
1.
Click Tools > Import Trusted Certificate.
2. Locate each of the certificates provided by your CA and import them into the keystore.
Importing the CA Reply Certificate
After installing any required root certificates, you need to import the response from the CA.
To import the CA reply, Right-click the tomcat keypair and then click Import CA Reply.
8 Using SSL Certificates in Web Help Desk
Note: If your certificate is in Base64-encoded format (*.pem and sometimes *.cer), you may get an
error when importing the certificate if it contains anything besides the certificate itself. If this is the
case, make a copy of the certificate that includes only the lines starting with -----BEGIN
CERTIFICATE----- and ending with -----END CERTIFICATE-----.
After importing your certificate reply, Porteclé reports that the certificate was imported successfully.
If when attempting to import the CA Reply, Porteclé gives you an error that the certificate cannot be
trusted, you are likely missing a root certificate. To determine which certificate you need, temporarily
import your CA Reply as a Trusted Certificate, rather than a CA Reply certificate, and examine the
Certificate Details.
Locate the Issuer property. You need to obtain a certificate from your CA that matches this property and
then import it into Porteclé as a Trusted Certificate. Once you have imported this certificate into Porteclé,
as well as any other certificates needed by its issuer, you can delete your own trusted certificate and reimport it as a CA Reply to your keypair.
Importing an Existing Certificate
If you have an existing certificate that you would like to use with Web Help Desk, you will need to import
your private key as well as your certificate chain.
Do not import the certificate using Porteclé’s Tools > Import Trusted Certificate… option, as it will not
include the private key.
The PKCS#12 standard specifies a keystore format that is used for transferring private keys and
certificates. PKCS#12 files typically use the extension .p12 or .pfx. If you already have your private key
and certificate bundled in this format, you can import it directly into Porteclé. If you do not have a
PKCS#12 (.p12 or .pfx) file, you can use the OpenSSL pkcs12 command to generate one from a private
key and a certificate; or, if your certificate is on a Windows server, you can export a PKCS#12 file from
the Microsoft Management Console.
Creating a PKCS#12 Keystore File from a Private Key and a Certificate
OpenSSL provides the pkcs12 command for generating PKCS#12 files from a private key and a
certificate. OpenSSL is open source and can be downloaded from http://openssl.org. The private key and
certificate must be in PEM format (i.e., base64-encoded, with ----BEGIN CERTIFICATE---- and ----END
CERTIFICATE---- headers and footers).
Use this command in OpenSSL to create a PKCS#12 file from your private key and certificate:
openssl pkcs12 -export \
-in <signed_cert_filename> \
-inkey <private_key_filename> \
-name ‘tomcat’ \
-out keystore.p12
If you have a chain of certificates, you should first combine the certificates into a single file and use it for
the input file, as shown below. The order of certificates must be from server certificate to the CA root
certificate (see RFC2246 section 7.4.2).
cat <signed_cert_filename> \
<intermediate.cert> [<intermediate2.cert>]
... \
Using SSL Certificates in Web Help Desk 9
> cert-chain.txt
openssl pkcs12 -export \
-in cert-chain.txt \
-inkey <private_key_filename> \
-name ‘tomcat’ \
-out keystore.p12
You will be prompted to provide a password for the new keystore, which you will need to provide when
importing the keystore into the Web Help Desk Java keystore.
Exporting a PKCS#12 Keystore File from Microsoft Management Console
To use an existing certificate located on a Windows server, complete the following steps:
1.
Click Start > Run… and execute the command mmc. A Microsoft Management Console
window will open.
2.
Select Console > Add/Remove Snap-In.
3.
Select Add > Certificates > Add > Computer Account > Local Computer > Finish.
4.
Expand Console Root > Certificates > Personal. You should see your certificate listed.
5.
Right-click your certificate and select All Tasks > Export.
6.
Follow the Certificate Export Wizard prompts to export a Personal Information Exchange –
PKCS #12 (.PFX) file.
7.
Check the option to Include all certificates in the certification path if possible, and do not
check the options to Enable strong protection and to Delete the private key if the export is
successful. Take note of the location in which you save the .pfx file.
8.
Import it into Porteclé using the instructions below.
Importing a PKCS#12 File into the Web Help Desk Keystore
Porteclé provides two ways to import contents of a PKCS#12 file into the Web Help Desk Java keystore.
The first method is to open the PKCS#12 keystore in File > Open Keystore File…, convert it to a Java
keystore in Tools > Change Keystore Type > JKS, and overwrite the existing keystore by saving it as
<WebHelpDesk>/conf/keystore.jks.
The second method is to open the Web Help Desk keystore file and then import the keypair containing
your certificate, using Tools > Import Keypair….. Porteclé prompts you to select which keypair in your
PKCS#12 keystore to import.
If your keystore already contains a default, unsigned ‘tomcat’ certificate, delete it before importing your
PKCS#12 file.
Be sure that your certificate chain is intact in the Web Help Desk keystore. You can inspect the certificate
chain by double-clicking the certificate to view the certificate details. Use the left and right arrows at the
top of the details panel to navigate through each certificate in the chain.
If you do not see the full certificate chain, try importing the CA certificates first in Tools > Import Trusted
Certificate…, and then import your keypair again. Porteclé does not establish trust when a certificate is
imported before the certificate that was used to sign it.
10 Using SSL Certificates in Web Help Desk
Sequence is important. Import the root certificate first, then the next certificate in the chain, and so on,
until you get to your own certificate.
Your certificate must be aliased as tomcat. The password for your certificate and for the keystore itself
must be the same, and must match the KEYSTORE_PASSWORD setting in
<WebHelpDesk>/conf/whd.conf ("changeit" by default).
Troubleshooting
If you are having difficulties completing any of the above tasks, review the items below to check for
improper settings or mistakes in your procedures.
•
In Porteclé, Go to Tools > Options... and check Use CA Certs Keystore. Porteclé checks the builtin Java certificates when attempting to establish trust. This action is fine, because this same set of
certificates is available to the Web Help Desk at runtime.
•
Porteclé requires that certificates be imported in order of most-trusted certificate first (i.e., root
certificate, then the intermediate certificate that is issued by the root, then the certificate issued by
that certificate, etc.). If you attempt to import a certificate out of order, Porteclé will allow it, but will
complain that it cannot establish trust. You should never have to confirm trust for any certificate other
than the root certificate.
•
Do NOT import your own certificate using the Tools > Import Trusted Certificates... menu option.
This option is only for importing root and chain certificates. Instead, right-click your tomcat keypair
and select Import CA Reply.
•
Make sure that the password set for the keypair and the keystore are the same, and match the
KEYSTORE_PASSWORD setting in <WebHelpDesk>/conf/whd.conf. (The default password is
changeit.) To set the keypair password, right-click the tomcat keypair and select Set password. To set
the keystore password, select Tools > Set Keystore Password....
•
Make sure that your keystore is saved to <WebHelpDesk>/conf/keystore.jks.
•
You must restart the Web Help Desk for any changes in Porteclé or whd.conf to take effect. On
Windows, be sure to use the Web Help Desk Start/Stop utilities in the Start menu, not the Windows
Services panel (right-click Run As Administrator on Server 2008+).
•
You will get a certificate warning if the hostname in the address you are using to browse to the Web
Help Desk is different from the Common Name (CN) field in your certificate. This will happen, for
instance, if your certificate is for "help.my company.com" and you use "localhost" as the hostname in
your URL.
•
It is no longer necessary to edit web.xml to cause the Web Help Desk to switch automatically from an
HTTP request to HTTPS. This will be done automatically when DEFAULT_PORT and HTTPS_PORT
are both enabled in <WebHelpDesk>/conf/whd.conf.
•
When using HTTPS, set Setup > Options > Force HTTPS to Always. This will ensure that links
pointing to the Web Help Desk use HTTPS.
Additional Troubleshooting Scenarios
Issue: Porteclé Says My CA Reply Certificate Cannot Be Trusted.
Your certificate has been signed by an Issuer that Porteclé does not trust. You must obtain a root
certificate (or chain of certificates) from your CA that match the Issuer identity of your certificate, and
import them into Porteclé before importing your own certificate as a CA Reply.
You can determine the Issuer of your CA Reply by temporarily importing your certificate into Porteclé as a
Trusted Certificate rather than a CA Reply, and then examining its Certificate Details. Look at the
Certificate Details of other certificates in your keystore to see if any of them match your certificate’s Issuer
attribute. If not, you will need to obtain from your CA a certificate that does match.
Using SSL Certificates in Web Help Desk 11
Once you have imported a certificate that matches your own certificate’s issuer, as well as any other
certificates needed to trust those certificates, delete your temporarily trusted certificate and re-import it as
a CA Reply to your keypair.
Issue: After importing My Certificate, Web Help Desk Won’t Start.
Check your <WebHelpDesk>/conf/whd.conf file to be sure you have uncommented the SSL_PORT
setting, and that your DEFAULT_PORT and HTTPS_PORT settings are not conflicting with any other
processes on the server.
Ensure that your KEYSTORE_PASSWORD setting in whd.conf matches BOTH the password of your
keystore AND the password of your keypair (by default, this password is changeit).
Issue: After Importing My Certificate, Web Help Desk Starts Okay But My Browser Shows a Self-Signed
Certificate.
Check whether your private key was generated using the DSA algorithm. DSA keys are known to fail with
many browsers, including Internet Explorer. Try using RSA instead.