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 © 2014 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.
09/19/2014
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
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 self- signed 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
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. Enter changeit in the Enter Password field.
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.
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.
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.
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.
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 re- import 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>]
... \
> 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.
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 built- in 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.
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.
