Transport Layer Security

Transport Layer Security (TLS) is used to provide network security and privacy. In addition to providing encryption services, TLS uses trusted certificates to perform client and server authentication, and it uses message authentication codes to ensure data integrity.

Assumptions in this guide

Assumption 1 - SAS Enterprise Session Monitor (Server and Agent(s)) are installed on a Linux system. The commands for Windows are the same but the commands will need to be updated to reflect the different path structures.
Assumption 2 - All of the machines in your environment can talk to each other on the short hostname. If you are unable to ping the SAS Enterprise Session Monitor server from the agents without using the FQDN then you will either need to modify the hostname in the instructions or modify the /etc/hosts file on all of the machines in your environment.
Assumption 3 - openssl is installed and available in the Server's $PATH variable.

Shutdown your environment before starting this guide

Before implementing the steps in this configuration guide it is important to stop the SAS Enterprise Session Monitor Agent(s) and the SAS Enterprise Session Monitor Server in your environment.

Configure TLS using openssl and trusted authority certificates¶

Note

This guide assumes that you received files fullchain.pem and privkey.pem from your certification provider. Common Name (CN) from your certificate must match the url that you will be using in your browser to access the ESM and match the hostname that ESM agents will use to connect to the ESM server.

Configure the Server¶

Combine the fullchain.pem and privkey.pem files into a single file called fullcert.pem:
```
cat *.pem > /tmp/fullcert.pem
```
Use OpenSSL to convert the file created in step 1 into PKCS12 format. You MUST set a password for the key store specified in the -out option below.
```
openssl pkcs12 -export -out /tmp/fullcert.pkcs12 -in /tmp/fullcert.pem
```
Navigate to the esm-server directory of your SAS Enterprise Session Monitor server installation

Remove the default certificate:

jre/bin/keytool -delete -alias esm -storepass changeit -keystore conf/keystore.jks

Import the fullcert.pkcs12 keystore into the Server's keystore.jks file using the below command.
```
jre/bin/keytool -v -importkeystore -srckeystore /tmp/fullcert.pkcs12 -srcstorepass <PWFROMSTEP2> -destkeystore conf/keystore.jks -deststoretype JKS
```
You will be prompted for the destination keystore password, enter: changeit.

The above step import the certificate with an alias of "1". We can update this to something more meaningful:

jre/bin/keytool -keystore conf/keystore.jks -storepass changeit -changealias -alias 1 -destalias mycert

Copy files fullchain.pem and privkey.pem into conf/ directory of the Server installation

Add the following properties to the end of conf/config.properties:

useSSL=true
sslCertChainFile=fullchain.pem
sslPrivateKeyFile=privkey.pem

Restart the esm-server
Open Chrome and try with this url: https://yourdomain.com:18181/esm/. To verify the configuration, open the logs/server_0.log file. You should see a line similar to:
```
SSL configured using cert chain file '/opt/esm-server/conf/fullchain.pem' and private key file '/opt/esm-server/conf/privkey.pem' . SSL provider is 'JDK']]
```

Configure the Agent¶

Update the value of the ESMUSESSL option in esm-agent/conf/esmconfig.sh to true and make sure ESMSECUREPORT points to the same port as ESMPORT variable, default is 18082.
```
ESMUSESSL=true
ESMSECUREPORT=18082
```
Restart the SAS Enterprise Session Monitor Agent. To verify the configuration, open the esm-agent/logs/esm-agent-<yourhostname>.log file. You should see a line similar to:
```
INFO ... SSL configured without trust cert file, using defaults.
INFO ... SSL provider is 'JDK'
```
(Optional) The Agent will by default look into its own certification authorities file (jre/lib/security/cacerts) to verify if certificates have been signed with trusted certification authority. If the Agent can't connect to the server, download the root certificate from your certification authority and put it into the esm-agent/bin folder and rename it to ca.crt. If you want to use another file name, add the following parameter to esm-agent/bin/config.properties:
```
tlsTrustCertFile=my_CA_ROOT.crt
```

Configure TLS using openssl to create self-signed certificates¶

Configure the Server¶

Navigate to the esm-server/conf directory of your SAS Enterprise Session Monitor server installation
Edit line 5 of opensslSelfSignedCerts.sh file and specify your server's short hostname instead of localhost SERVER_CN=localhost
Execute opensslSelfSignedCerts.sh to generate the server certificate chain file (server.crt), server private key file(server.pem), and agent trust certificate file (ca.crt).
Add the following property to the end of conf/config.properties:
```
useSSL=true
```
Restart the SAS Enterprise Session Monitor server
Copy file ca.crt to the esm-agent/bin folder for all agents.

To verify the configuration, open the esm-server/logs/server_0.log file. You should see a line similar to:

INFO SSL configured using cert chain file '/home/esmuser/esm-server/conf/server.crt' and private key file '/home/esmuser/esm-server/conf/server.pem' . SSL provider is 'JDK'

Configure the Agent¶

Ensure that the ca.crt from step 6 of the server configuration guide exists in the bin folder of the Agent installation.
Update the value of the ESMUSESSL option in esm-agent/conf/esmconfig.sh to true
```
ESMUSESSL=true
```
Restart the SAS Enterprise Session Monitor agent

To verify the configuration, open the esm-agent/logs/esm-agent-<yourhostname>.log file. You should see a line similar to:

INFO ... SSL configured using trust cert file 'ca.crt'
INFO ... SSL provider is 'JDK'

Configure TLS using java keytool to create self-signed certificates¶

Warning

This method should only be used when openssl is not available.

Configure the Server¶

Navigate to the root directory of your SAS Enterprise Session Monitor server installation

Generate a private key, a certificate signing request, and a certificate, and add the certificate to the key chain:

./jre/bin/keytool -genkey -keysize 2048 -alias mymachine -validity 3650 -keyalg RSA -dname "CN=localhost,O=MyOrg,L=London,S=UK,C=UK" -keypass changeit -storepass changeit -keystore conf/identity.jks

Export the generated certificate for deployment to the SAS Enterprise Session Monitor agents:

./jre/bin/keytool -export -alias mymachine -file mymachine.cer -keypass changeit -storepass changeit -keystore conf/identity.jks

Add the following properties to the end of conf/config.properties:
```
useSSL=true
sslUseKeystore=true
```
Restart the SAS Enterprise Session Monitor server
To verify the configuration, open the esm-server/logs/server_0.log file, you should see the message like this: INFO SSL configured using keystore '/home/esmuser/esm-server/conf/identity.jks'. SSL provider is not specified, using default.

Configure the Agent¶

Navigate to the root of your SAS Enterprise Session Monitor agent installation directory
In the root of your SAS Enterprise Session Monitor agent installation, create a certs folder.
Copy the mymachine.cer file created in step 3 above into the certs folder created in the step above

Import the certificate into the agent's trusted certificate keystore

./jre/bin/keytool -import -trustcacerts -noprompt -file certs/mymachine.cer -alias mymachine -storepass changeit -keystore jre/lib/security/cacerts

Verify that the certificate was successfully added to the keystore

./jre/bin/keytool -list -v -storepass changeit -keystore jre/lib/security/cacerts

Update the following configuration option in conf/esmconfig.sh
```
ESMUSESSL=true
```
Update the following configuration option in bin/config.properties
```
tlsUseCacertsTrustStore=true
```
Restart the SAS Enterprise Session Monitor agent
To verify the configuration, open the esm-agent/logs/esm-agent-<yourhostname>.log file, you should see the message like this: INFO ... SSL configured using cacerts trust store (jre/lib/security/cacerts)

Last update: April 24, 2023
Created: April 24, 2023