Importing an SSL Certificate
By default, the Web Help Desk uses a self-signed certificate, causing web browsers to prompt the user whether to trust the certificate. This section explains how to configure the Web Help Desk to use a signed certificate that will be recognized by browsers automatically as a valid certificate.
Certificate configuration overview
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 by a Certification Authority (CA) that tells the browser who verified the authenticity of the server. Web browsers are pre configured to trust several CAs whose validity has been established by the browser manufacturer, such as VeriSign, Thawte, GeoTrust, and GoDaddy. If a browser does not recognize the certificate’s CA, it asks the user whether to trust the certificate. Once trust has been established, the browser uses the 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.
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.
The keystore holds one or more keypairs. A keypair consists of a private key and a certificate. Each keypair is given a unique name, or alias, and an optional password. The embedded Tomcat server used by Web Help Desk requires its keypair to be given the alias tomcat and, by default, the password changeit. If a different password is used, the new password must be given to Tomcat via the KEYSTORE_PASSWORD setting in whd.conf. The keystore itself also has a password, which Tomcat requires to be identical to the keypair password.
When a new keypair is created using Porteclé, it is given a self-signed certificate. To replace the self-signed certificate with a certificate signed by a CA, a Certificate Signing Request (CSR) must be generated for the keypair and submitted 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 replies with a certificate that can be used 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)
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 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.
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, and then to import the CA Reply certificate. If you do already have a certificate, you will need to import it and the primary key into the keystore. Since Porteclé does not allow you to import a primary key by itself, you will need to 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 later in this chapter.
Creating a new Keypair
After launching Porteclé, select File > Open KeyStore… and open <WebHelpDesk>/conf/keystore.jks. (This 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, simply uncomment the HTTPS_PORT setting and restart 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. First, delete the existing tomcat keypair by right-clicking on the alias and selecting Delete.
You will now be prompted to provide the x509 distinguished-name attributes for your certificate
The Validity attribute specifies the number of days you want your certificate to be valid. Typical validation periods are 6, 12, or 24 months. (See your CA for options and pricing.)
The most critical attribute is Common Name (CN). This must match exactly the full domain name for the site to be used with the certificate. For example, if your help desk will be hosted at support.mycompany.com, your CN must be support.mycompany.com, not merely mycompany.com. (However, some CAs support wildcard certificates, where *.company.com matches any subdomain of company.com.)
The Organization Unit (OU) may be anything that helps distinguish this certificate from others for your organization. Organization Name (O) should be the legal name for your organization. Locality Name (L) and State Name (ST) should be the unabbreviated city and state/province/region/territory of your organization. Country (C) should be the two letter ISO 3166 country code for your country. Email (E) is generally optional, but may be used by your CA as the address to which the certificate will be mailed. See your CA vendor for further information.
Provide a keypair password. Remember, this password, and the password used when creating the keystore, must match the KEYSTORE_PASSWORD parameter in <WebHelpDesk>/conf/whd.conf. By default, this password is changeit. If you use a different password, you must update the KEYSTORE_PASSWORD setting.
Give a name for the CSR that will help you remember the domain it will validate (i.e. support.mycompany.com.csr)
This will be 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 & 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, select Tools > Import Trusted Certificate
Locate each of the certificates (if any) provided by your CA and import them into the keystore.
Importing the CA Reply certificate
After installing any required root certificates, right-click the tomcat keypair and select Import CA Reply.
Locate the certificate returned by your CA and import it into the keystore.
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é should report 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 will 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. It will not work to 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é. (See Importing a PKCS#12 , below.)
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 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 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’ \
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> \
openssl pkcs12 -export \
-in cert-chain.txt \
-inkey <private_key_filename> \
-name ‘tomcat’ \
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 from Microsoft Management Console
If you wish to use an existing certificate located on a Windows server, you can export it to a PKCS#12 file using the Microsoft Management Console (MMC):
- Click Start > Run… and execute the command mmc. A Microsoft Management Console window will open.
- Select Console > Add/Remove Snap-In.
- Select Add > Certificates > Add > Computer Account > Local Computer > Finish.
- Expand Console Root > Certificates > Personal. You should see your certificate listed.
- Right-click your certificate and select All Tasks > Export.
- Follow the Certificate Export Wizard prompts to export a Personal Information Exchange – PKCS #12 (.PFX) file. 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. You will 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 (File > Open Keystore File…), convert it to a Java keystore (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…. You will be prompted 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 (Tools > Import Trusted Certificate…), and then import your keypair again. For some reason, 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).
- In Porteclé, Go to Tools > Options... and check Use CA Certs Keystore. This will make Porteclé check the built-in Java certificates when attempting to establish trust, which is fine because this same set of certificates will be available to the Web Help Desk at runtime.
- Portecle 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
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.
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.
Also be sure 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").
Finally, be sure that your keypair is aliased as tomcat.
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.
Running in debug mode
You may be able to get additional information about the error by running Web Help Desk in debug mode from the command line: