How to configure SSL for CAS or ADS

Set up the report server to use secure connections with users' web browsers and to use automatically generated data or your own keys and certificates.

Before you begin

It is recommended that secure access be performed using TLSv1.1 or TLSv1.2, which are more secure than its predecessors.

If an older version of the protocol is required, configure it by setting the configuration property, connector.ssl.SSLProtocol to TLS1, SSLv3 or SSLv2 .

Note that the Apache Tomcat default is all and the acceptable values are SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2 and SSLv2+SSLv3 .

If the connector.ssl.SSLProtocol property is left blank, it causes the web browser to negotiate the version of a secure protocol when connecting to the web server. For more information about secure connection configuration in Apache Tomcat, refer to http://tomcat.apache.org/tomcat-6.0-doc/apr.html#HTTPS.

The report server implementation of SSL uses OpenSSL, so the encryption, certification, and other operations are handled as they are defined in OpenSSL.

The subdirectory server\openssl of the report server installation directory contains the OpenSSL tool, which can be used for the SSL key and certificate generation, conversions, and management. The report server installation process uses the tools in this directory to generate a self-signed SSL certificate and a key pair for the initial HTTPS server operation.

This certificate and the key pair are, by default, stored in the wwwroot/WEB-INF/ssl subdirectory of the report server installation directory. To change this path, modify the connector.ssl.SSLCertificateFile and connector.ssl.SSLCertificateKeyFile configuration properties in common.properties .

To configure your own encryption keys and register the server in the CA (certificate authority) infrastructure, the common.properties file has to be edited manually. Refer to the Apache Tomcat documentation at http://tomcat.apache.org/tomcat-5.5-doc/apr.html.

All certification procedures, such as certificate request or certificate signing, have to be handled manually by using the OpenSSL utility. For instructions on how to use the OpenSSL utility, refer to http://www.openssl.org.

The report server can connect to the network via standard HTTP or HTTPS (HTTP over SSL), both of which are supported by the report server installation process, or via other modes that can be configured manually.

The connectivity configuration settings are stored in the configuration file common.properties in the config subdirectory of the report server installation directory. The names of the configuration properties in common.properties follow the standard names used for Tomcat and OpenSSL. The format of the file is different, but the names of the configuration parameters are the same.

All of the connectivity configuration properties are set by the installation program during report server installation.

Note

Subsequent modifications to connectivity settings are possible but should be performed with great care. These settings require a thorough understanding of web server connector settings and OpenSSL.

The simplest procedure for joining the server to the certification infrastructure can be summarized as follows:

Generate a private RSA key as described in keys.txt.

It is suggested that the password should be encrypted. The report server can ask for the key password every time it starts, or the password can be configured using the report server installation program.

Create a certificate request as described in certificates.txt (section 3).

Pass the certificate to a certification authority for signing.

Set configuration properties.
Configure the following settings in the common.properties file:

  • Point connector.ssl.SSLCertificateFile to the received certificate file.

  • Point connector.ssl.SSLCertificateKeyFile to the generated key.

  • Point connector.ssl.SSLCertificateChainFile to the chain of certificates.

Set the key password.

If the key was encrypted, use the report server installation program to set the key password.

Stop the NAM Server service.

Open a command prompt on the server where the NAM Server is installed and navigate to the keytool.exe location.
Thekeytool.exe location depends on the operating system and Java version that you are using but, typically it is:

C:\Program Files (x86)\Java\jre7\bin  
Keytool utility

To ensure that the keytool utility is present and available on the system:

In the Command Prompt window, run the keytool utility without any command line arguments. If the utility is found, the result of running the command is the help output detailing keytool usage. If an error message is displayed instead, indicating that keytool is not recognized as an internal or external command or operable program or batch file, find keytool on the computer or install it. To do this:

Determine if keytool is present on the computer.
keytool is available free as part of the Java Runtime Environment (JRE). Verify if JRE is currently one of the installed programs and where it is installed. If it is installed, locate keytool in the JRE folder and make sure that this folder is in your system-wide PATH environment variable.

If JRE is not installed on the computer, install the latest version.
Perform the installation by following the steps described at [www.java.com](http://www.java.com) . When installing the JRE, you may be prompted to un-install older versions of Java. Do this only if you are sure that there is no software on your computer that relies on the particular version or language of the currently installed Java.

Verify that keytool is now available.
After the JRE has been installed, open the Command Prompt window and verify that keytool is now available. If it is still not available, amend the PATH environment variable accordingly and re-try.

Create a private key within an existing or new keystore. Execute the following:

keytool -genkeypair -keyalg rsa -keystore keystorename -storepass [keystorepassword] -alias [my_new_key]
  • To protect the new private key by its own keypassword within the keystore, you have to add the keypass option. If you don't use the keypass option, the keystore password is used to protect the private key.

  • To delete a key password (which is not possible with keytool), copy the keystore password to the key password.

  • To use the key as a client certificate, use RSA as a key algorithm, instead of default DSA, because many servers only accept RSA client certificates.

Generate a CSR.

keytool -certreq -alias my_new_key (from step 4) -keystore keystorename(from step 4) -storepass keystorepassword(from step 4) -file my_new.csr -validity[number of days]

Send you CSR to a certificate authority.

When you receive your files back from the CA, export files to Base64 X509 format, if your CA didn't provide it in that format.

Right-click on the certificate chain file (for example, newcert.p7b) and select Open. The certificate should open in Window's Certificates tool.

In the left pane, expand Certificates - Current User  > Certificates. You will see two certificates in the right pane, one above the other, first the root certificate and then the web server.

Export each certificate into Base64 X509 by right-clicking on each certificate and selecting All Tasks  > Export.

Click Next.

Enter the name of the exported file, for example, root.cer for the root certificate. Click Finish.

Repeat for the web server certificate (webserver.cer).

Open root.cer and webserver.cer in Notepad. Append all contents from each file (Control-A) and merge both into a new text file. Make sure to merge them in the same order they were opened: root followed by webserver.

Save the merged file as chain.txt .

Import keystore files

Import chain.txt into your keystore file.

 keytool -import -alias root -keystore keystorename(from step 4) -storepass keystorepassword (from step 4) -trustcacerts -file chain.txt

Import webserver.cer .

 keytool -import -alias tomcat -keystore keystorename (from step 4) -storepass keystorepassword (from step 4) -trustcacerts -file webserver.cer

Configure SSL Server Settings

Configure the following settings in the common.properties  file:

  • Point connector.ssl.SSLCertificateFile  to the received certificate file.

  • Point connector.ssl.SSLCertificateKeyFile  to the generated key.

  • Point connector.ssl.SSLCertificateChainFile  to the chain of certificates.

Set the key password.

In Windows, go to Program and Features > Uninstall a program, select Dynatrace Central Analysis Server and click Uninstall/Change.

In NAM Server installation dialog, select Change HTTP and SSL Server settings and click Next.

Select Use HTTPS (HTTP over SSL) and Use custom key and certificate, and click Next.

Read the on-screen information, type and confirm the password and click Next. The key password is updated.

Restart the NAM Server service.

To browse to the NAM Server site, use the fully qualified name (FQN) of the web server in the URL. When you created the keystore, you specified the FQN of the web server, so the SSL certificate is tied to that exact name.

field input

Procedure to create CSR and install certificate on VAS and ADS Server (for internal CA)

Logon to server NAM Probe server to use the openssl commands to create the private KEY and the CSR.

openssl req -new -newkey rsa:2048 -nodes -out
{servername}_ent_rt_csaa_com.csr -keyout
{servername}_ent_rt_csaa_com.key -subj
"/C=US/ST={state}/L={city}/O={organization}/OU={department}/CN={servername}"

The results from this should be 2 files:
{servername}.csr
{servername}.key

Send the {servername}.csr file to CA team to get the certificate (use Service Catalog request).

When you receive your files back from the CA team, export files to Base64 X509 format, if your CA didn't provide it in that format.

Right-click on the certificate chain file (for example, {servername}.p7b) and select Open. The certificate should open in Window's Certificates tool.

In the left pane, expand Certificates - Current User > Certificates . You will see two certificates in the right pane, one above the other, first the root certificate and then the web server.

Export each certificate into Base64 X509 by right-clicking on each certificate and selecting All Tasks > Export.

Click Next.

Enter the name of the exported file, for example, issuing.cer for the root certificate. Click Finish.

Enter the name of the exported file, for example, root.cer for the root certificate. Click Finish.

Repeat for the web server certificate ({servername}.cer).

Make a copy of the issuing.cer file and rename to “chain.txt”

Copy chain.txt, {servername}.key, and certnew.cer to the NAM Server or ADS server in a storage folder.

  • For VAS/NAM Server copy the above files to: D:\Program Files\Compuware\CAS\wwwroot\WEB-INF\ssl

  • For ADS copy the above files to: D:\Program Files\Compuware\ADS\wwwroot\WEB-INF\ssl

Configure the following settings in the common.properties file:

  • Point connector.ssl.SSLCertificateFile = certnew.cer (provided within zip from Cert Team).

  • Point connector.ssl.SSLCertificateKeyFile = {servername}.key (generated with CER on NAM Probe).

  • Point connector.ssl.SSLCertificateChainFile = chain.txt (created above).

Restart the service, and verify everything is working.