Enable FIPS in a new deployment

This section describes how to enable FIPS in a new Web Help Desk 12.8.3 Hotfix 3 deployment. In this deployment, Web Help Desk is installed on a host server for the first time.

Before you begin

Back up your Web Help Desk deployment to a safe place.

Task 1: Review the requirements

Verify that your Web Help Desk deployment meets all component requirements for enabling FIPS 140-2 compliant cryptography.

Task 2: Install Web Help Desk 12.8.3 Hotfix 3 in your deployment

See the Web Help Desk Installation and Upgrade Guide for details on how to install Web Help Desk on your Microsoft Windows server.

After you complete the installation steps, a window opens in your default browser, prompting you to select a database.

Do not select a database type or click Next. You will continue the Getting Started Wizard in a later step. Leave this window open and go to the next section.

Task 3: Enable FIPS on the Web Help Desk server

In the following procedures, <WebHelpDesk> represents the Web Help Desk home folder on your system.

For example:

c:\Program Files\WebHelpDesk

Stop Web Help Desk

1. Navigate to the <WebHelpDesk> directory.

2. Right-click whd_stop.bat and select Run as administrator.

   Web Help Desk is stopped.

Update the java.security file

Register the new FIPS cryptography provider in the java.security file and update the preference order. When you are finished, add a new keystore type (BCFKS) that identifies the new provider keystore. You will create the keystore in a future step.

1. Navigate to the following directory:

   <WebHelpDesk>\bin\jre\conf\security

2. Open the java.security file using a text editor (such as Notepad).

3. Scroll down to the following comment: 

   *List of providers and their preference orders

4. In the list of providers, add the following security providers to the top of the list:

   security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider 
   security.provider.2=org.bouncycastle.jsse.provider.BouncyCastleJsseProvider fips:BCFIPS
   

5. Renumber the preference order so all security providers are listed in descending order.

   For example:

   security.provider.1=org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider
   security.provider.2=org.bouncycastle.jsse.provider.BouncyCastleJsseProvider fips:BCFIPS
   security.provider.3=SUN
   security.provider.4=SunRsaSign
   security.provider.5=SunEC
   security.provider.6=SunJSSE
   security.provider.7=SunJCE
   security.provider.8=SunJGSS
   security.provider.9=SunSASL
   security.provider.10=XMLDSig
   security.provider.11=SunPCSC
   security.provider.12=JdkLDAp
   security.provider.13=JdkSASL
   security.provider.14=SunMSCAPI
   security.provider.15=SunPKCS11
   

6. Scroll down to the following comment: 

   #Default keystore type
    keystore.type=pkcs12

7. Comment out the pkcs12 keystore type and add the following type:

   keystore.type=bcfks

   For example:

   #Default keystore type
   #keystore.type=pkcs12
    keystore.type=bcfks

8. Scroll down to the following entry:

   ssl.KeyManagerFactory.algorithm=SunX509

9. Change the entry to the following:

   ssl.KeyManagerFactory.algorithm=PKIX

10. Save and close the file.

Create a new keystore for the FIPS cryptography provider

Java uses the cacerts keystore to store the public certificates of all root Certificates of Authority (CAs). To support the new FIPS cryptography provider, perform the following steps to convert the cacerts keystore to a BCFKS keystore.

1. Update the environment variable path settings on the Web Help Desk host server.
   1. Press <Windows> + <Pause>.
   2. Click Advanced System Settings.
   3. Click the Advanced tab.
   4. Click Environmental Variables.
   5. Under System Variables, select the PATH variable.

   6. Update the PATH string with the following path:

      <WebHelpDesk>\bin\jre\bin

      where <WebHelpDesk> is the path to where the application is installed.

      For example:

      C:\Program Files\WebHelpDesk\bin\jre\bin

   7. Save your changes.
2. Open a command prompt.

3. Change the directory to:

   <WebHelpDesk>\bin\jre\lib\security

   For example:

   C:\Program Files\WebHelpDesk\bin\jre\lib\security

4. At the prompt, execute the following command:

   keytool -importkeystore -srckeystore cacerts -srcstoretype JKS -srcstorepass changeit -destkeystore "C:\Program Files\WebHelpDesk\conf\cacerts.bcfks" -deststoretype BCFKS -deststorepass changeit -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider -providerpath "C:\Program Files\WebHelpDesk\bin\webapps\helpdesk\WEB-INF\lib\bc-fips.jar"

   If Web Help Desk is not installed in the C:\Program Files\WebHelpDesk directory, replace this path in the command with the path to your Web Help Desk installation directory.

   The cacerts keystore is converted to a BCFKS keystore.

5. Close the command prompt window.

Update the whd.conf file

Update the whd.conf file in the <WebHelpDesk> directory so it includes the WHD_HOST parameter with your company name and domain.

1. Open the following file in a text editor:

   <WebHelpDesk>\conf\whd.conf

2. In the Ports section, ensure that the following parameter is uncommented and includes a port number that is not occupied by another process:

   HTTPS_PORT=443

   The default port is 8443.

3. In the Ports section, locate the following:

   #WHD_HOST

4. Uncomment the parameter and add a value that identifies your company name and domain. Record this value for a later step.

   For example:

   WHD_HOST=mycompany.mydomain

5. Save and close the file.

Configure the BCFKS keystore

1. Open a command prompt window.

2. Change the directory to:

   <WebHelpDesk>\conf

   For example:

   C:\Program Files\WebHelpDesk\conf

3. At the prompt, execute the following command:

   keytool -genkey -alias tomcat -keyalg RSA -keypass changeit -storepass changeit -keystore keystore.bcfks -storetype BCFKS -providerpath "C:\Program Files\WebHelpDesk\bin\webapps\helpdesk\WEB-INF\lib\bc-fips.jar" -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider

   You can update the changeit password in the command if required by your corporate policy. Be sure to record the new password, as you will need it in a future step.

4. When prompted for your first and last name, enter the values you created for the WHD_HOST parameter.

   For example:

   What is the name of your organizational unit?
     [Unknown]: mycompany.mydomain
   What is the name of your organizational unit?
     [Unknown]: my_company_name
   What is the name of your organization?
     [Unknown]: Technical_Support
   What is the name of your City or Locality?
     [Unknown]: Austin
   What is the name of your State or Province?
     [Unknown]: Texas
   What is the two-letter country code for this unit?
     [Unknown]: US
   Is CN=mycompany.mydomain, OU=my_company_name, O=Technical_Support, L=Austin, ST=Texas, C=US correct?
     [no]:
   

5. At the no prompt, enter yes and press Return.

   The application generates the RSA keypair and self-signed certificate, and then displays the following message:

   Generating 2,048 bit RSA key pair and self-signed certificate (SHA256withRSA) with a validity of 90 days for CN=mycompany.mydomain, OU=my_company_name, O=Technical_Support, L=Austin, ST=Texas, C=US

6. Leave the command prompt window open.

Create a signed Web Help Desk certificate

Generate a certificate signing request and send the generated file to a trusted Certificate of Authority (CA)---such as Verisign or GlobalSign---to validate the certificate identity. The certificate is signed by the CA and may require several weeks to certify and receive. After you receive the signed certificate, import the certificate to your BCFKS keystore.

1. Stop Web Help Desk.

   1. Navigate to your <WebHelpDesk> directory.
   2. Right-click whd_stop.bat and select Run as administrator.
2. Create the certificate signing request.
   1. Open a command prompt window.

   2. At the prompt, change the directory to:

      <WebHelpDesk>\conf

      For example:

      C:\Program Files\WebHelpDesk\conf\

   3. At the prompt, execute: 

      keytool –keystore "C:\Program Files\WebHelpDesk\conf\keystore.bcfks" –certreq –alias tomcat –keyalg rsa –file server.csr -storepass changeit -storetype BCFKS -providerpath "C:\Program Files\WebHelpDesk\bin\webapps\helpdesk\WEB-INF\lib\bc-fips.jar" -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider

      where changeit is the BCFKS keystore password.

      C:\Program Files\WebHelpDesk\conf\

      Web Help Desk generates the server.csr certificate and copies the certificate to the following directory:

      C:\Program Files\WebHelpDesk\conf\

3. Back up the server.csr certificate to a safe location.

4. Send the server.csr certificate to a trusted CA to validate the certificate identity.

   The CA validates the certificate and sends the validated certificate back to you.

5. When you receive the certificate from the CA, import the certificate into your BCFKS database.
   1. Open a command prompt window.

   2. At the prompt, change the directory to:

      c:\Program Files\WebHelpDesk\conf\

   3. At the prompt, execute:

      keytool -import -v - trustcacerts -alias tomcat -file server.cer -keystore "C:\Program Files\WebHelpDesk\conf\cacerts.bcfks" -keypass changeit - storepass changeit -storetype BCFKS -providerpath "C:\Program Files\WebHelpDesk\bin\webapps\helpdesk\WEB-INF\lib\bc-fips.jar" -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider

      where changeit is the default password of your BCFKS keystore.

6. Back up your CA certificate to a safe location.

Update the wrapper_template.conf file

Update the file with additional Java class path elements and Java additional parameters.

1. Navigate to:

   C:\Program Files\WebHelpDesk\bin\wrapper\conf

2. Open the wrapper_template.conf file in a text editor (such as Notepad).
3. Scroll down to Java Classpath.

4. Enter the following elements after the last element in the list:

   wrapper.java.classpath.4=../../webapps/helpdesk/WEB-INF/lib/bc-fips.jar
   wrapper.java.classpath.5=../../webapps/helpdesk/WEB-INF/lib/bcpkix-fips.jar
   wrapper.java.classpath.6=../../webapps/helpdesk/WEB-INF/lib/bctls-fips.jar
   

5. Verify that all elements in are descending order.

   For example:

   wrapper.java.classpath.1=../../wrapper/lib/wrapper.jar
   wrapper.java.classpath.2=../../tomcat/bin/bootstrap.jar
   wrapper.java.classpath.3=../../tomcat/bin/tomcat.juli.jar
   wrapper.java.classpath.4=../../webapps/helpdesk/WEB-INF/lib/bc-fips.jar
   wrapper.java.classpath.5=../../webapps/helpdesk/WEB-INF/lib/bcpkix-fips.jar
   wrapper.java.classpath.6=../../webapps/helpdesk/WEB-INF/lib/bctls-fips.jar
   

6. Scroll down to Java Additional Parameters.

7. Add the following elements to the end of the list:

   wrapper.java.additional.19=-DWHDfips
   wrapper.java.additional.20=-Djavax.net.ssl.keyStore="C:\Program Files\WebHelpDesk\conf\cacerts.bcfks"
   wrapper.java.additional.21=-Djavax.net.ssl.keyStorePassword=changeit
   wrapper.java.additional.22=-Djavax.net.ssl.keyStoreType=BCFKS
   wrapper.java.additional.23=-Djavax.net.ssl.trustStore="C:\Program Files\WebHelpDesk\conf\cacerts.bcfks"
   wrapper.java.additional.24=-Djavax.net.ssl.trustStorePassword=changeit
   wrapper.java.additional.25=-Djavax.net.ssl.trustStoreType=BCFKS

8. (Optional) Update the changeit password in the following elements based on your corporate requirements. The password must be identical to the password used when you created the bcfks keystore.

   wrapper.java.additional.21=-Djavax.net.ssl.keyStorePassword=changeit
   wrapper.java.additional.24=-Djavax.net.ssl.trustStorePassword=changeit

9. Verify that all elements are listed in descending order.
10. Save and close the file.

Update the tomcat_server_template file

1. Navigate to:

   C:\Program Files\WebHelpDesk\conf

2. Open the tomcat_server_template.xml file in a text editor (such as Notepad).

3. Locate the following header:

   @@@WEBHELPDESK_SSL_START@@@

4. Below this header are two headers with the following name:

   <Connector port="@@@WEBHELPDESK_SSL_PORT@@@" protocol="HTTP/1.1 SSLEnabled="true"

5. Under the first Connector port header, locate the following elements:

   keystoreFile="@@@WEBHELPDESK_KEYSTORE@@@"
   keystorePass="@@@WEBHELPDESK_KEYSTORE_PASS@@@"
   keystoreType="@@@WEBHELPDESK_KEYSTORE_TYPE@@@"
   

6. Update the element values as shown below:

   keystoreFile="C:\Program Files\WebHelpDesk\conf\keystore.bcfks"
   keystorePass="changeit"
   keystoreType="BCFKS"
   

7. In the same section, delete the following cipher entries:

   ciphers="TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA256_TLS_RSA_WITH_A
   ES_256_CBC_SHA_TLS_RSA_WITH_AES_128_CBC_SHA_SSL_RSA_WITH_3DES_EDE_CBC_SHA_SSL_RSA_WITH_
   RC4_128_SHA1_SSL_RSA_WITH_RC4_128_MDS_TLS_EMPTY_RENEGOTIATION_INFO_SCSV"

8. Repeat step 5 through step 7 in the second Connector port section.
9. Save and close the file.
10. Start Web Help Desk.
    1. Open a command prompt window.

    2. At the prompt, execute:

       whd_start

       During the restart, the following message displays in the window:

       Web Help Desk is configured to work in FIPS compliant security mode.

11. Open a web browser and navigate to:

    https://mywebhelpdesk.mydomain:443/helpdesk/

    where mywebhelpdesk.mydomain is your Web Help Desk domain name.

    If you configured HTTPS_PORT differently in an earlier step, choose a port other than port 443.

Task 4: Complete the installation

After Web Help Desk restarts, the Web Help Desk Getting Started Wizard displays. Complete the following steps.

1. In the Getting Started Wizard, select a database option, and click Next.

   

2. Complete the fields as required to configure the incoming email account and SMTP server, and then click Next.

   

   Each incoming mail account is associated with a specific request type, an optional tech group, and an outgoing mail account (SMTP server) used to deliver outgoing mail. For example, you could have an incoming mail account for all IT tickets, another account for HR tickets, and another for Facilities tickets.

   Web Help Desk checks the Incoming mail accounts each minute for new messages, processes the messages into tickets, and deletes the processed messages from the incoming mail server.

   If you are not ready to set up the email accounts, you can skip this step and set up the email accounts later from the Web Help Desk Administrator Console. To continue without configuring email, click Skip this step.

3. Complete the fields to create the default administrator account, and then click Next.

   

   The default admin account is a local super user account used to:

   • Log in to Web Help Desk for the first time and configure the application.
   • Access all Web Help Desk settings and accounts.

   Administrators with a default administrator account can create all user accounts, including additional admin accounts. The default admin account includes tech account privileges so you can create and process tickets with tech privileges. Techs can have Tech or Tech Admin account privileges.

4. (Optional) Create one or more custom request types.

   

   When you install Web Help Desk, the last step of the Getting Started wizard prompts you to add request types or edit the preconfigured request types. This step is optional.

   You may find it easier to add request types in the Tickets panel after WHD is configured.

   SolarWinds recommends that you click Finish to bypass this step in the wizard and take time to plan the request types you need. See Create tech groups and request types in the Web Help Desk Getting Started Guide for information about creating request types.

5. Click Finish.

   The Configuration Wizard applies your settings and configures the application.

   

6. Click Login as admin to continue setup.

   

7. Log in to Web Help Desk using admin as your user name and password.

8. Review the SolarWinds End User License Agreement. If you accept the terms, select the appropriate checkboxes and then click Continue.

   The Web Help Desk Administrator Console displays.

9. In the toolbar, click Setup > General > Options.
10. In the Server DNS Name field, enter your Web Help Desk fully qualified domain name.
11. Set Force HTTPS to Always.
12. Click Save.
13. Click Setup > General > Authentication.

14. In the FIPS Compliant Cryptography field, verify that Enabled displays in the field with a green icon. This indicates that WHD is using cryptographic algorithms that are compliant with the FIPS 140-2 standard.

    

    If Disabled displays in the field with a red icon, contact Technical Support for assistance.

15. Update your Web Help Desk password to a secure password.
16. Activate your Web Help Desk license.

Task 5: Set up the SolarWinds Integration and email

If you are using self-signed certificates in your SolarWinds Integration servers, email servers, or primary tools, add these certificates in the Web Help Desk database.

Below is an example for an Orion connection.

1. Open a Web browser window and navigate to:

   https://ORION_IP_Address:17778/SolarWinds/InformationService/v3/OrionBasic/

2. Export the certificate into a file in CER format.

   1. Click the lock icon next to the URL address and select Certificate Information > Details > Copy to File.
   2. Follow the prompts in the export wizard, selecting the .der format of the exported certificate.
3. Open a command prompt window.

4. Change the directory to:

   <WebHelpDesk>\conf

   For example:

   C:\Program Files\WebHelpDesk\conf

5. Import the certificate.

   At the prompt, execute:

   keytool -import -trustcacerts -keystore "C:\Program Files\WebHelpDesk\conf\cacerts.bcfks" -storepass changeit -alias orion_cert -file c:\<path_to_exported_ cert>\previously_exported_cert.cer -storetype BCFKS -providerpath "C:\Program Files\WebHelpDesk\bin\webapps\helpdesk\WEB-INF\lib\bc- fips.jar" -provider org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider

   where changeit is the BCFKS keystore password.