Using a secure Klocwork Server connection

You can set up Klocwork tools to use a secure HTTP connection (https). This means all Klocwork client tools that connect to the Klocwork Server will connect using SSL.

Perform the following steps to set up SSL:

  • Set up the Klocwork Server.
  • Set up all Klocwork client tools that connect to the Klocwork Server.

You can use kwauthconfig to generate an unsigned certificate, or you can generate your own signed certificate. Both scenarios are explained below.

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 23.3 > Klocwork Security Configuration.
    • 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.

 

Important:

The following procedure provides basic instructions for creating a self-signed keystore using the Java Development Kit tool "keytool", which you can find at <Server_install>/_jvm/bin. However, Klocwork strongly recommends that you read the following for more information:

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.htm,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. 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

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 2023.3 > 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.

Configure redirection from HTTP to HTTPS

Once you have migrated your servers from HTTP to HTTPS, you can use Tomcat to configure all your bookmarks and links in various portals, emails, and document systems to be redirected to the new HTTPS scheme and a new secure port.

The original bookmarked URLs will have the form of http://<hostname>:<port>, for instance, http://localhost:8080. Since we have configured HTTPS to port 8080, the redirects will not work. The steps to fix the redirects are:

  • change the Klocwork server port for HTTPS to something other than 8080, for instance, 8443

  • add an insecure connector to redirect from

  • add a redirect from HTTP/8080 to HTTPS/8443

Change the HTTPS server port

  1. Stop the project and set a different HTTPS port:

    kwservice -r projects_root stop
kwservice -r projects_root set-service-property klocwork port 8443
  2. Edit <projects_root>/tomcat/conf/server.template and remove the redirectPort attribute from the Connector definition.

  3. Restart the project:

    kwservice -r projects_root start

  4. Open https://localhost:8443 and log into the portal to verify that the secure site is working. Optionally, check that http://localhost:8080 is no longer accessible.

Add an insecure connector to redirect from

Configure Tomcat to respond to requests on HTTP/8080 by adding a connector for it. We'll use the new HTTPS connector as a template and modify it to be non-SSL.

  1. Stop the project:

    kwservice -r projects_root stop

  2. Edit <projects_root>/tomcat/conf/server.template:

    • Copy the secure Connector definition and paste it above the secure Connector definition. Do not modify the original secure definition.

    • In the copy of the Connector definition:

      • Change the port setting to the old port number you wrote down above (8080)

      • Add or set the following attributes:
        SSLEnabled="false", scheme="http" and secure="false"

      • Delete these attributes:
        clientAuth="false", sslProtocol="TLS", keystoreFile="conf/mycertificate.cert", keystorePass="password"

      • Add the redirectPort attribute configured as your new HTTPS port:

        redirectPort="8443"

At this point no redirect will happen. You will be able to access both HTTP (on http://localhost:8080) and HTTPS (on https://localhost:8443) and each will function properly.

Add the redirect

The final step is to tell Tomcat to redirect insecure connections using the above connectors.

  1. Stop the project:

    kwservice -r projects_root stop

  2. Edit <Klocwork install>/3rdparty/tomcat/conf/web.xml:

    Important: Do not edit projects_root/tomcat/conf/web.xml as it will be overwritten when the Klocwork server is started. No redirects will happen and you will still be able to access HTTP and HTTPS sites independently.

    Add the following XML just before the closing web-app tag:

    Copy 
    <!-- Enable redirect from HTTP to HTTPS -->
    <security-constraint>
        <web-resource-collection>
            <web-resource-name>Entire Application</web-resource-name>
            <url-pattern>/*</url-pattern>
        </web-resource-collection>
        <user-data-constraint>
            <transport-guarantee>CONFIDENTIAL</transport-guarantee>
        </user-data-constraint>
    </security-constraint>

When you open your old HTTP URLs in your browser, they will redirect to the new HTTPS ones. For example, entering http://localhost:8080/review/insight-review.html will redirect to https://localhost:8443/review/insight-review.html.

The following is a sample server.template file configured for redirect:

Copy 
<?xml version="1.0" encoding="UTF-8"?>
<Server port="$SHUTDOWNPORT" shutdown="SHUTDOWN">
  <Listener className="org.apache.catalina.startup.VersionLoggerListener" />
  <Listener className="org.apache.catalina.core.AprLifecycleListener" SSLEngine="on" />
  <Listener className="org.apache.catalina.core.JreMemoryLeakPreventionListener" />
  <Listener className="org.apache.catalina.core.ThreadLocalLeakPreventionListener" />
  <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" />
  <!-- Global JNDI resources Documentation at /docs/jndi-resources-howto.html -->
  <GlobalNamingResources />
  <Service name="Catalina">
      <!-- Insecure connector for redirect -->
      <!-- use your old HTTP port number -->
      <Connector port="8080" redirectPort="8443"
        protocol="org.apache.coyote.http11.Http11NioProtocol" 
        maxThreads="64" minSpareThreads="20" 
        acceptCount="200" connectionTimeout="20000" 
        URIEncoding="UTF-8" compression="on" compressionMinSize="2048" 
        noCompressionUserAgents="gozilla,traviata" 
        compressableMimeType="text/html,text/xml,text/javascript" 
        maxPostSize="-1" 
        SSLEnabled="false" 
        scheme="http" 
        secure="false" 
        clientAuth="false" 
        />
    
    <!-- Secure connector -->
    <!-- $PORT will be configured by Klocwork using the configured Klocwork port (see kwservice set-service-property) -->
    <Connector port="$PORT"
        protocol="org.apache.coyote.http11.Http11NioProtocol" 
        maxThreads="64" minSpareThreads="20" 
        acceptCount="200" connectionTimeout="20000" 
        URIEncoding="UTF-8" compression="on" compressionMinSize="2048" 
        noCompressionUserAgents="gozilla,traviata" 
        compressableMimeType="text/html,text/xml,text/javascript" 
        maxPostSize="-1" 
        SSLEnabled="true" 
        scheme="https" 
        secure="true" 
        clientAuth="false" 
        sslProtocol="TLS" 
        keystoreFile="conf/mycertificate.cert"
        keystorePass="password"/>
    <Engine name="Catalina" defaultHost="localhost">
      <Host name="localhost" unpackWARs="false" autoDeploy="false" errorReportValveClass="com.klocwork.valves.KlocworkErrorReportValve" appBase="webapps">
        <Valve className="org.apache.catalina.valves.AccessLogValve" directory="logs" prefix="localhost_access_log" suffix=".txt" pattern="common" />
      </Host>
    </Engine>
  </Service>
</Server>

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.