When connecting from the Virtru SaaS to the Virtru Private Keystore (for Google Workspace CSE), the session must be secured with a CA-signed Transport Layer Security(TLS) certificate. TLS ensures that the information cannot be accessed while in transit and is a method to validate the authenticity of the target server further and verify the domain's ownership.
Step 1: Backup your CSE
Before doing any work on your CSE installation it is recommended to perform a full backup of all directories and files.
Commands:
cd /var/virtru
mkdir backup
cd backup
cp -r /var/virtru/cse
Step 2: Stop your running CSE
You will need to stop the running Docker containers before updating anything. If running multiple CSE servers, take one out of the load balancer before stopping.
Commands:
cd /var/virtru/cse
docker ps -a
docker stop <container-ID>
docker rm <container-ID>
Step 3: Update the SSL certificate
If you already have a renewed certificate, skip to Step 4. If you need to generate a certificate request (CSR), you can run the following commands and then send the .csr to your certificate authority. They should return a new certificate bundle which you will turn into a .crt and .key file in the next step.
Certificate Generation
If your organization does not already have an SSL cert for your server's fully qualified domain name (or a wildcard cert), you must first generate a Certificate Signing Request(CSR).
Shell
openssl req -new -newkey rsa:2048 -nodes -keyout myserver.key -out server.csr
Once you execute this command, OpenSSL will ask you for important certificate information. Answer each question based on your organization, contact info, and server FQDN. Once complete, you will now have your private key(server.key) and the CSR(server.csr). Use this CSR to request a CA-signed certificate from the CA your organization has approved for use.
Step 4: Convert your certificate bundle to separate file format
The CSE requires an SSL certificate to be inside the /var/virtru/cse/ssl directory and be in a .crt and .key format, for the public certificate and private keys respectively. Most certificate authorities will send you a bundle containing the certificate and one or more intermediate certificates.
Note:
To prevent decryption errors, the order of cert chain in the .crt file must be formatted correctly. The certificate for your CSE FQDN must come before the intermediate and/or root certificates within the .crt file.
Once the CA has returned a certificate, one must create a .crt and .key file for use by the CSE.
Shell
On your CSE server
cd /var/virtru/cse
openssl x509 -modulus -in server.cert -noout -text
openssl rsa -modulus -in server.key -noout -text
cp server.cert expired_server.cert
cp server.key expired_server.key
Replace your current certificate and key files with the new server.cert
and server.key
files.
- Open the certificate file:
vim server.cert
- Press
esc
on your keyboard, then type:%d
to delete the existing certificate value. - Paste the new certificate value into the
server.cert
file. - Press
esc
again, then type:wq
to save and close the file. - Repeat these steps for the key file:
vim server.key
- Press
esc
, then type:%d
to delete the existing key value. - Paste the new key value into the
server.key
file. - Press
esc
again, then type:wq
to save and close the file.
Step 5: Start the CSE Containers
Now that the new certificate files are inside the ssl folder you can turn the CSE back on.
Commands:
cd /var/virtru/cse
sh run.sh
Step 6: Check the Logs
Checking the logs for the absence of any errors is important. Also make sure that the docker containers start up and run and do not continue to restart. Continuing to restart is an indication of a problem.
Commands:
cd /var/virtru/cse
docker logs <container-ID> -f
Step 7: Additional Testing Steps
Once the container is up, validate the response.
Commands:
curl https://csesrv.example.com/status
Using a browser, navigate to the /status endpoint and observe the updated date on the certificate.
Commands:
https://csesrv.example.com/status
Validate TLS
Once you have generated your SSL certificates and followed the steps in the Installation section, you will have a Virtru Private Keystore instance running with TLS support. Once it is up and running, you can use the following openssl syntax to confirm it is utilizing the correct certificates:
Shell
openssl s_client -starttls smtp -crlf -connect <server FQDN or IP>:<port>
Example output from this command sequence can be found below for reference:
Text
--- SSL handshake has read 1528 bytes and written 360 bytes --- New, TLSv1/SSLv3, Cipher is DHE-RSA-AES256-SHA Server public key is 1024 bit Secure Renegotiation IS supported Compression: NONE Expansion: NONE SSL-Session: Protocol : TLSv1 Cipher : DHE-RSA-AES256-SHA Session-ID: 06F03A7C2AB0EA3E97cut7CD4A4A6166D551B Session-ID-ctx: Master-Key: 1A2FF452C3E09F9D7B2DECEcutFB67158960BA6 Key-Arg : None Start Time: 1370375286 Timeout : 300 (sec) Verify return code: 21 (unable to verify the first certificate) ...
Ensure your server is up and running by checking the FQDN (https://csesrv.yourdomain.com/status)