Configure the Klocwork Server to use SSL - Unsigned certificate

This section shows you how to generate an unsigned SSL certificate by using kwauthconfig. See the next section if you want to generate your own signed certificate.

You can configure SSL as part of setting up access control. You can also configure SSL later.

If you haven't already set up access control:

• Go to Setting up access control and be sure to select the Use secure Klocwork Server connection check box when you select the access control method. The text fields are explained below.

If you've already set up access control:

1. The way to launch the Klocwork security utility, kwauthconfig, is different depending on your platform:
   • Windows: Click Start > All Programs > Klocwork 18.1 > Klocwork Security Configuration.
   • Mac OS/X: Launch kwauthconfig from the Applications folder.
   • Other: From <server_install>/bin, run kwauthconfig.
2. Click Configure.
3. Select the Use secure Klocwork Server connection check box.
4. Fill in the text fields as described below.
5. Click Finish.
6. Restart the Klocwork Server by using the command kwservice restart, or by using Windows Services Administration.

Text fields for setting up SSL with kwauthconfig

• Host name is the fully qualified host name of the Klocwork Server, for example, testserver.mydomain.com.
• Organizational unit is the organizational unit this certificate will apply to, for example, development.
• Organization is the name of your organization, for example, Klocwork.

Configure the Klocwork Server to use SSL - Signed certificate

When you set up the Klocwork Server to use a secure connection by using kwauthconfig as shown above, the generated certificate is unsigned. If you want to use your own signed certificate, create a self-signed keystore file, then run the kwauthconfig utility to detect the settings.

• Generic Apache Tomcat instructions on setting up secure HTTP: http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html
• Complete instructions on using keytool: http://docs.oracle.com/javase/8/docs/technotes/tools/windows/keytool.html

For example, you may want to use the -validity flag to change the default certificate validity period.

Create a self-signed keystore file

From <Server_install>, run the following command:

_jvm/bin/keytool -genkeypair -alias tomcat -keyalg RSA -keystore <projects_root>/tomcat/conf/.keystore 
-dname "cn=<KlocworkServer_hostname>, ou=<your_organizational_unit>,o=<your_organization>" 
-keypass changeit -storepass changeit

where

• cn is the fully qualified Klocwork Server hostname.
• ou and o should be substituted with an appropriate organizational unit and organization name.
• The values for keypass and storepass are the Tomcat default values.

The keystore is saved into the Tomcat config directory at <projects_root>/tomcat/conf.

Example command line:

_jvm/bin/keytool -genkeypair -alias tomcat -keyalg RSA -keystore <projects_root>/tomcat/conf/.keystore 
-dname "cn=testserver.klocwork.com, ou=Development, o=Klocwork" -keypass changeit -storepass changeit

This command generates a keystore file named .keystore.

Configure the Klocwork Server to use SSL (using kwauthconfig)

1. Launch the Klocwork security utility, kwauthconfig.
2. Specify the location of your projects_root directory.
3. Click Configure....
4. Select the Use secure Klocwork Server connection check box. Verify that the settings are correct and click Finish. (These settings are entered during keystore creation above.)
5. Restart the Klocwork Server by using the command kwservice --projects-root <projects_root> restart klocwork or by using Windows Services Administration.

After completing these steps, continue to the section Configure Klocwork client tools to use SSL.

Configure the Klocwork Server to use SSL (manually)

If you need to manually configure/enable SSL on the Klocwork Server (for example, if you are running Klocwork on servers and only have shell access), the steps are as follows:

Prerequisite: Your .keystore file must have been previously created and saved at <projects_root>/tomcat/conf

1. Open the following file in a text editor:

   <projects_root>/config/admin.conf

2. Find the setting klocwork.protocol=http and change the value to https.
3. Open the following file in a text editor:

   <projects_root>/tomcat/conf/server.template

4. Find the XML element <Connector>. Below is an example of what it may look like:

        <Connector port="$PORT"
        maxthreads="4-" minSpareThreads="20" maxSpareThreads="40"
        enableLooksups="false" redirectPort="8443" acceptCount="50"
        debug="0" connectionTimeout="20000"
        compression="on"
        compressionMinSize="2048"
        noCompressionUserAgents=".*MSIE.*,gozilla,traviata"
        compressableMimeType="text/html,text/xml"
        maxPostSize="0"
        />
   

5. Add the following attributes to that element (paste these lines after maxPostSize but before the />):

        SSLEnabled="true" scheme="https" secure="true"
        clientAuth="false" sslProtocol="TLS"
        keystoreFile="conf/.keystore"
   

6. If the Klocwork Server is running on the AIX platform, you must also add the following line (after the lines you pasted in Step 5, before the />):

        algorithm="IbmX509"
   

7. Restart the Klocwork Server with the command kwservice --projects-root <projects_root> restart klocwork (or with Windows Services Administration).

After completing these steps, continue to the section Configure Klocwork client tools to use SSL.

Configure Klocwork client tools to use SSL

Note: This section provides information on setting up a secure Klocwork Server connection after installation. You can set up SSL during installation as well, with:

• the Use secure server connection (HTTPS) check box in the Windows User installer
• the "USE_SSL" property for unattended Windows installation
• the --use-ssl option for the UnixServer installer and User installer

Client certificates support

You can configure the Klocwork tools to work with client certificates to support Public-key infrastructure (PKI) and smart cards. Client certificates are also supported for use with the Klocwork Web API.

Prerequisites:

• You must be running your client installation on Windows.

To enable this:

1. In Windows, click Start > All Programs > Klocwork 2018.1 > Klocwork Security Configuration, or from the command line on any platform, run the following command:

   kwauthconfig [<projects_root>]

2. Click Configure...
3. Select the Use secure Klocwork Server connection check box and fill in the fields if you have not already done so.
4. Select the Enable smart card client authentication check box.
5. Click Browse... and point to the location of your trusted client certificates keystore.
6. Enter your keystore password.
7. Click Finish and then OK to finalize your changes.

Your trusted client certificates keystore should be created by your administrator and contain the certificates for all users with access to the Klocwork tools.

When accessing the Klocwork portal login page in your browser, Chrome and Internet Explorer will ask you to select your client certificate the first time the page is accessed. After the initial time, your browser will remember your choice automatically.

Firefox uses a separate keystore, so it requires some manual configuration:

1. Go to Options > Advanced > Encryption.
2. Click View Certificates.
3. Click the Your Certificates tab and click Import....
4. Locate your client certificate and click Open.

When you open Firefox for the first time after completing these steps, it may ask you to verify the certificate. After this, you will be able to access the Klocwork portal login page without any prompts.

Command-line tools that connect to Klocwork Server

Specify the --url option, which also allows you to specify the host and port of the Klocwork Server plus the name of the integration project for some commands. Specify https in the URL instead of http.

kwadmin --url https://myserver:8080/

Tip: If you still use the older --host and --port options, you can use the --ssl option instead of the --url option.

kwadmin --ssl --host myserver --port 8080

GUI-based client tools

For the IDE plug-ins and Klocwork Desktop enable the "Use secure connection" option when connecting to the Klocwork Server.

Browser-based client tools

For Klocwork Static Code Analysis, Klocwork Code Review and Klocwork Documentation, specify https instead of http in the URL. Note that users may be prompted to download a file if they use http.

Example for Klocwork Static Code Analysis:

https://myserver.mydomain.com:8080/

Certificate warning issued by browser-based client tools

When connecting to the Klocwork browser-based tools after SSL has been configured on the Klocwork Server, users will see a warning, such as:

• "Secure Connection Failed" in Firefox
• "Certificate Error: Navigation Blocked" in Internet Explorer

Users can add an exception for the Klocwork Server, so that they do not see this message in future. Consult your browser help for more information.

Disabling the SSL connection

1. Launch kwauthconfig from <server_install>/bin.
2. Click Configure.
3. Clear the Use secure Klocwork Server connection check box.
4. Click Finish.
5. Restart the Klocwork Server by using the command kwservice restart, or by using Windows Services Administration.
6. Inform all users that they now need to run Klocwork tools without the special SSL options.