Set up and use X509 TLS/SSL certificate

This guide describes how to configure the Validate server and Klocwork client tools to support TLS/SSL certificate verification.

Certificate verification in Klocwork client tools is controlled via the verifyCertificate setting in the client_config.xml file located in the config subdirectory of each client tool (for example, kwauthtools, kwbuildtools). If the file doesn't exist, you can create one manually.

Depending on your certificate type (self-signed or CA-signed), setup steps vary slightly.

In this guide:

• Certificate trust models

• Configure Validate with the certificate

• Enable certificate verification in the client

• Import certificates into the client JVM

• Logging and debugging

• Error handling

• Example scenarios

• Best practices

Certificate trust models

Support for certificates in Validate can be classified into two high-level types:

• Self-signed: The certificate is issued and signed by the same entity.

• CA-signed: The certificate is issued by a Certificate Authority (public, private, or intermediate).

For CA-signed certificates, the root or intermediate CA must be trusted by the client machine or explicitly imported.

Configure Validate with the certificate

To configure Validate with a certificate:

1. Create a self- or CA-signed certificate. When you generate a certificate, you will have a .crt file, which is the certificate itself, and a key file, which is the private key for the certificate.

2. Copy the .key and .crt files to the <projects_root>/tomcat/conf/ folder.

3. Edit server.template as shown next:

   1. Locate the <Connector…> element, which has as set of attributes beginning with port="$PORT".

   2. Append the following attribute/value pairs to the end of the list:

      SSLEnabled="true" scheme="https" secure="true"

   3. Within the same <Connector…> attribute, add the following sub-element. Change the value of the certificateFile and certificateKeyFile to match the name of your certificate and its key file.
      Copy

            <SSLHostConfig sslProtocol="TLS" ciphers="TLS_ECDHE_RSA_WITH_CAMELLIA_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_CAMELLIA_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_ARIA_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_ARIA_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256,TLS_AES_256_GCM_SHA384,TLS_CHACHA20_POLY1305_SHA256,TLS_AES_128_GCM_SHA256,TLS_AES_128_CCM_8_SHA256,TLS_AES_128_CCM_SHA256">
              <Certificate certificateFile="conf/selfsigned.crt" certificateKeyFile="conf/selfsigned.key" type="RSA"/>
            </SSLHostConfig>

4. Restart the Validate server to apply HTTPS. The portal will now be accessible at https://.

Enable certificate verification in the client

To enable certificate verification in a Klocwork client application, edit the client_config.xml file and add the verifyCertificate="true" attribute inside the <params> element.

If the file doesn't already exist, use the following:

<?xml version="1.0" encoding="UTF-8"?>
<params>
   <host verifyCertificate="true"/>
</params>

If the file already contains other attributes, append verifyCertificate="true" alongside the existing ones, separated by a space. For example:

<?xml version="1.0" encoding="UTF-8"?>
<params>
   <host resolveHost="false" verifyCertificate="true"/>
</params>

Import certificates into the client JVM

For self-signed certificates, each Klocwork client contains a a bundled Java runtime located in the _jvm subdirectory.

Use the following command to import the .crt file into the client’s truststore:

<full_path_to_client_application>/_jvm/bin/keytool -import -alias Validate <full_path_to_the_dot_crt_file> -keystore <full_path_to_client_application>/lib/security/cacerts -storepass changeit

For CA-signed certificates, the certificate of the signing certificate authority must be added to the client machine if not already present.

On Linux, perform the following:

1. Copy the .crt file to /usr/local/share/ca-certificates/

2. Run sudo update-ca-certificates

Logging and debugging

Run client tools with the --debug flag to display certificate details if verification fails. This is useful for identifying trust issues and understanding what the server is sending.

Error handling

If the client fails to validate the server certificate (for example, from missing or untrusted cert), authentication will fail with a peer not authenticated error. In debug mode, certificate metadata will also be printed to help with troubleshooting.

Example scenarios

This matrix summarizes how the client behaves during authentication depending on whether certificate verification is enabled, and whether the appropriate certificate is present in the client JVM truststore.

Best practices

The following are recommendations when setting up TSL/SSL certificates:

• Always enable verifyCertificate in production.

• Ensure all necessary certificates are available and trusted by the client JVM.

• Use --debug to troubleshoot validation errors and confirm certificate chains.