Enabling server identity verification

You can enable extra security to configure the agents to verify the identity of the server for communication that uses the HTTPS protocol.

Before you begin

Upgrade HCL DevOps Deploy (Deploy) to version 6.2.1.1 or later. If you use agent relays, update to version 6.2.3 or later. Upgrade the following plug-ins to the latest versions that are available:

All source configuration plug-ins
z/OS® Utility plug-in
MobileFirst Platform Foundation (formerly Worklight) plug-in
WebSphere® Application Server - Deployment plug-in

Versions of these plug-ins that were released before March 2016 do not support server identity verification.

Ensure that the keytool utility, which is provided with the Java™ developer kit and is not part of Deploy, is available in the system path.

About this task

When you install the Deploy server, a private key and self-signed certificate with the alias server are stored in the server_installation_directory/opt/tomcat/conf/tomcat.keystore file. This certificate is presented to agents, agent relays, and users that connect to the server via HTTPS. Because the certificate that is associated with the private key has a generic distinguished name (DN), you must replace the key so that the agent or agent relay can correctly verify the host name of the server. After you configure the server to present a certificate with a valid host name, you then configure the agents to accept that trusted certificate and to require verification of the host name of the server.

Procedure

Stop the Deploy server.
Open a command-line window, and go to the server_installation_directory/opt/tomcat/conf directory.
Generate a private key that is associated with the correct host name to use for HTTPS communication. Run a command similar to the following command:
```
keytool -genkeypair -alias serverNewCN -keysize 2048 -sigalg SHA256withRSA -keyalg RSA -keystore tomcat.keystore
```
The existing key is stored in the tomcat.keystore file with the server alias.
Edit the tomcat.key.alias property in the installed.properties file to specify the alias in the keystore that contains the certificate to use.
```
tomcat.key.alias="serverNewCN"
```
Edit the following properties in the secured-installed.properties file to specify the password for the certificate and keystore to use.
```
server.key.password=<new_certificate_password>
tomcat.keystore.password=changeit
```
Enter the passwords in plain text, so that it automatically encrypts once the server runs.
Optional: Create a certificate signing request that uses the new private key, and then use an internal or external certificate authority to sign it.
Export the server certificate. Run a command similar to the following command:
```
keytool -exportcert -alias server -keystore tomcat.keystore -file server.cert
```
Start the Deploy server.
If you used a certificate authority that is not already trusted by the agents, copy the server certificate to the agent computer, and then import the certificate into the keystore of the JRE that is used to run the agent process.
By default, the path to the keystore is $JAVA_HOME/lib/security/cacerts. If you use agent relays, repeat this step for all agent relays.
If you use agent relays, complete the following steps to configure the agents to verify the identity of the agent relays.

Note: Server identity verification uses the HTTPS, or codestation, keystores for the agent relays.
1. Open a command-line window on the agent relay computer, and go to the /agent_relay_install/conf/ directory.
  By default, the agent-relay-install location is /opt/devops-deploy/agentrelay on Linux™ and C:\Program Files\devops-deploy\agentrelay on Windows™.
2. Generate a private key that is associated with the HTTPS connection for the agent relay. Run a command similar to the following command:
```
keytool -genkeypair -alias agentrelay -keysize 2048 -sigalg  SHA256withRSA
    -storepass changeit -keypass changeit -keyalg RSA -keystore codestation.keystore
```
  For the -alias argument, specify the certificate alias of the codestation keystore for the agent relay. The certificate is in the agentrelay.properties file for the agent relay, in the property codestation.cert.alias. The default value is agentrelay.
3. Export the agent relay certificate. Run a command similar to the following command:
```
keytool -exportcert -alias agentrelay -keystore codestation.keystore -file agentrelay.cert
```
4. Copy the agent relay certificate to the agent computer, and then import the certificate into the keystore of the JRE that is used to run the agent process.
  By default, the path to the keystore is $JAVA_HOME/lib/security/cacerts.
Add verify.server.identity=true to the agent_installation_directory/conf/agent/installed.properties file on each agent.
If you use agent relays to cache artifacts, repeat this step for all agent relays.
Upgrade each agent or agent relay. If an agent is already upgraded, restart the agent.
Agents can communicate with the server during this process, so you can upgrade agents one at a time.