Placing Signed SSL Certificates on the Appliances

Overview

Note: This document applies to Stratusphere version 6.7.1-1 and higher. For instructions on how to place signed SSL certificates on appliances using Stratusphere 6.7.0-5 and earlier versions, refer to the 6.7.0-5 or earlier versions of this document.

This document provides instructions on how to place signed SSL certificates on the Stratusphere Hub, Database, and Collector appliances. Apart from getting rid of the alarming warning each time the Stratusphere Hub Web UI is accessed, placing a signed SSL certificate provides verifiable identification and security compliance to administrator & users accessing the Web UI of Stratusphere.

Preparation

  1. Procure any change controls needed to make changes to the production Stratusphere Hub, Database, and Collector appliances.
  2. Get login credentials of the Linux users as per the platform i.e., <username> as friend on VMware, Citrix, and Nutanix, ec2-user on AWS, or azureuser on Azure to SSH into the Stratusphere Hub, Database, and Collector appliances.
  3. Procure SSH access to the Stratusphere Hub, Database, and Collector Appliances. An SSH client such as Windows Command Prompt and PuTTY can be used to log into the Hub, Database, and Collector provided TCP/22 is allowed to the appliances.
  4. Download and install your preferred SCP client (e.g., WinSCP, FileZilla, or similar) to download certificate requests and upload the SSL Certificate files.
  5. Be aware that you will need to first start the steps to prepare the SSL certificate request, pause in the middle of the instructions as you send the request to the Certifying Authority (CA), and then receive your certificate. This may take minutes, hours, or even days depending on your CA. You will then use the new certificate to complete the process.

Scenarios

  1. Import and Install an SSL Certificate and Key.
  2. Traditional: Generate a Request, Import & Install an SSL certificate.

Scenario 1: Import and Install an SSL Certificate and Key

This scenario applies when the IT or Security department created a certificate without using a request generated by a Stratusphere appliance. It walks the user through the steps to import the certificate, set the right permissions, and then install it in the right locations.

Instructions for Stratusphere Hub, Database or Collector Appliances

Note: Stratusphere will function normally with the default, self-signed certificates; replacing them with CA-signed certificates is optional. Deciding which appliance's certificate to update depends on your security needs. Only the hub certificate is presented to browsers that visit the Stratusphere web UI, so replacing the hub certificate is the only requirement for the browser to show “Connection is secure”. If your organization requires secure connections for Stratusphere inter-appliance communications, Postgres database service, Connector ID agent reporting, etc., you may want to replace the Database and Collector certificates as well. The procedure is identical on all appliances, and the Postgres service certificate is linked to, and automatically updated along with the Apache httpd web service certificate for Hub and Database appliances.

  1. Obtain the new signed certificate and key files for your appliance hostname. The final certificate needs to be in base64 / PEM / CER format. You may upload a PFX file containing the certificate and key, then extract the PEM certificate and key if needed. If the PFX file is password protected, that password will be required to do the extraction and remove the password protection.
  2. Use your favorite SCP client, such as WinSCP, to upload the certificate and key files to /home/<username>/(replace <username> with friend/ec2-user/azureuser) on the Hub or Collector using credentials for the <username> on your platform i.e., <username> as friend on VMware, Citrix, and Nutanix, ec2-user on AWS, or azureuser on Azure.
  3. Use your favorite SSH client, such as Windows Command Prompt or PuTTY, to connect and log in using the credentials for <username> and run:
  4. Copy 
    sudo bash

  5. to obtain root access. When prompted, enter the password for your <username>.

  6. Copy the new certificate to ssl.cert.new (replace YOURCERTNAME with name of uploaded file):
  7. Copy 
    cp /home/$(logname)/YOURCERTNAME /home/$(logname)/ssl.crt.new

  8. If you have uploaded a PEM format certificate along with a separate key file, copy the key to ssl.key.new (replace YOURKEYNAME with name of uploaded key).

  9. Note: PFX files should contain the key, so for PFX skip this step and go to the next step for extracting the cert and key from the PFX.

  10. Copy 
    cp /home/$(logname)/YOURKEYNAME /home/$(logname)/ssl.key.new

  11. For a PFX file, complete the following sub-steps. If the certificate is already in PEM format, skip to the next numbered step.

    1. Export the certificate from the PFX file by running the following command:

    2. Note: You’ll be prompted for the password if the file is protected.

    3. Copy
      openssl pkcs12 -in /home/$(logname)/ssl.crt.new -clcerts -nokeys -out /home/$(logname)/ssl.crt.extract

    4. Export the private key file from the PFX file:
    5. Copy
      openssl pkcs12 -in /home/$(logname)/ssl.crt.new -nocerts -nodes -out /home/$(logname)/ssl.key.new

    6. Remove the passphrase from the private key (if needed):
    7. Copy
      openssl rsa -in /home/$(logname)/ssl.key.new -out /home/$(logname)/ssl.key.new

    8. If there are no errors, move ssl.crt.extract back into ssl.crt.new.
    9. Copy
      mv /home/$(logname)/ssl.crt.extract /home/$(logname)/ssl.crt.new

  12. Back up the working or existing certificate and key:
  13. Copy 
    /bin/cp /etc/lwl/ssl/ssl.crt /etc/lwl/ssl/ssl.crt.backup
    /bin/cp /etc/lwl/ssl/ssl.key /etc/lwl/ssl/ssl.key.backup

  14. Copy the new certificate and key into the same location:
  15. Copy 
    /bin/cp /home/$(logname)/ssl.crt.new /etc/lwl/ssl/ssl.crt
    /bin/cp /home/$(logname)/ssl.key.new /etc/lwl/ssl/ssl.key

  16. Update ownership, permissions, and the security context of the certificate and key:
  17. Copy 
    chown root:root /etc/lwl/ssl/ssl.crt
    chmod 644 /etc/lwl/ssl/ssl.crt
    chmod 640 /etc/lwl/ssl/ssl.key
    restorecon -RF /etc/lwl/ssl

  18. Restart the Web Server to load the newly added SSL Certificate.
  19. Copy 
    systemctl restart httpd

  20. Verify httpd is running:
  21. Copy 
    systemctl is-active httpd

  22. If httpd restarted successfully after the hub cert was replaced, the Stratusphere Web UI should be accessible. Check that your browser shows the correct certificate.
  23. For Hub and Database appliances, if you’d like to immediately load the newly added SSL Certificate to database communications, restart the Postgres Database service.
  24. Copy 
    systemctl restart postgresql-*

  25. Check whether the Postgres Database service is running:
  26. Copy 
    systemctl is-active postgresql-*

  27. If the postgresql service restarted successfully the new certificate was accepted.

Scenario 2: Traditional: Generate a Request, Import, and Install an SSL Certificate

In this scenario, Stratusphere administrators will execute a script which prompts the end user for relevant inputs to create a certificate request. After entering information for the generation of the certificate request, the end user must download the certificate request file, send it to the Certifying Authority (CA) to receive the certificate back, and then place it back on the appliance to install it.

Note: Stratusphere will function normally with the default, self-signed certificates; replacing them with CA-signed certificates is optional. Deciding which appliance's certificate to update depends on your security needs. Only the hub certificate is presented to browsers that visit the Stratusphere web UI, so replacing the hub certificate is the only requirement for the browser to show “Connection is secure”. If your organization requires secure connections for Stratusphere inter-appliance communications, Postgres database service, Connector ID agent reporting, etc., you may want to replace the Database and Collector certificates as well. The procedure is identical on all appliances, and the Postgres service certificate is linked to, and automatically updated along with the Apache httpd web service certificate for Hub and Database appliances.

Instructions for Stratusphere Hub, Database or Collector Appliances

  1. Use your favorite SSH client, such as Windows Command Prompt or PuTTY, to connect and log in to the Stratusphere Hub appliance or Collector using the credentials for <username> on your platform i.e., <username> as friend on VMware, Citrix, and Nutanix, ec2-user on AWS, and azureuser on Azure. The default password is sspassword.
  2. Obtain root access by executing:
  3. Copy 
    sudo bash

  4. When prompted, enter the password for your <username>.

  5. Execute the following command to begin the process of collecting details for the certificate request:
  6. Copy 
    /opt/lwl/bin/createcsr.sh

  7. The script will prompt for the following items (press Enter to accept defaults within […]):
    1. Country Name (2 letter code) [US]:
    2. State of Province Name (full name) [Georgia]:
    3. Locality Name (e.g., city) [Alpharetta]:
    4. Organization Name (e.g., company) [Liquidware, Inc.]:
    5. Common Name (e.g., server FQDN or YOUR name) [lwl]: hub.domain.com
    6. Alternative DNS names (comma separated list) [lwl]: hub1.domain.com, hub2.domain.com
    7. The script will then generate the request and display the location where it is stored:
    8. Copy
      Generating request...
      Request can be found here: /var/tmp/lwlreq.VhyY.csr.  Contents are:
      -----BEGIN CERTIFICATE REQUEST-----
      MIIC1DCCAbwCAQAwXTELMAkGA1UEBhMCVVMxEDAOBgNVBAgMB0dlb3JnaWExEzAR
      BgNVBAcMCkFscGhhcmV0dGExGTAXBgNVBAoMEExpcXVpZHdhcmUsIEluYy4xDDAK
      BgNVBAMMA2x3bDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBANnK3M6H
      PBcTfyvMJKVy+T0bNC28c6iKESTAeiWiYUK73MFld9UKX1XIELesxJapFZfpbVaG
      qt0uXnK4cgyGdsLuWjsDTP66BHRsclBnWwNt93RJAttqblML7ug7xQPdoHTE7TH7
      J3YrCkGcJsHT1laxgZlHaJzIt7QMmE81W3c0AFyLu82OOsIXrkGvoefi1G4HWxl9
      F6qUQ61YhMppJvv+LWI76bc05+DB/cpR7KqvX+r6fmwoEp0vlAD63xBgoTP/kZ1z
      e1v44hDZ8f2uIAAqURt6ZsYv64yq9Us6ev7JfJSGdU2NkfoNpeIPF09kq3wzgNHH
      y00LK08Bpdjnm8ECAwEAAaAyMDAGCSqGSIb3DQEJDjEjMCEwHwYDVR0RBBgwFoIJ
      aG9zdG5hbWUxgglob3N0bmFtZTIwDQYJKoZIhvcNAQELBQADggEBAIt+0MN0h6/w
      rKfvy3PH3XtkJpgHjiK3HsjAFCjtn+RBGSFo/oSFXjPk77ECk5cZo7RRk1I+aGbO
      gCV9A8TmPcVV9JwBSpAY6+pu9Ss/HYd+MkfdBZ3rZWicL1D0LZzGuDiuLek4iHEu
      rqtmqfoz9oXD3wa//AY0DzYFa/h9Xo3m79St1owCOKowYL8W/KQMYKHJnV4YxlBO
      whseGnqR4GcnpyGbl7nJt1wVmXKgCABYYN5KvJbZ58UjJtCIYyn1mZxHbMvCzguU
      hkLU8FvF3ZB4+JSfWDJuHBySnLh5WLr9CBjXRgxG/MRj58oGv2G0PZz+pfPLCj2A
      buySxtt9h1A=
      -----END CERTIFICATE REQUEST-----
      This file can be copied off or the contents pasted to obtain a certificate

  8. The certificate request is generated in the following location with a .csr extension:
  9. Copy 
    /var/tmp/<certrequest>.csr

  10. Enter the following to change ownership of the file so that it is accessible using the <username> on the platform (e.g., friend or ec2-user or azureuser user).
  11. Copy 
    chown $(logname):$(logname) /var/tmp/<certrequest>.csr

  12. Use your favorite SCP client, such as WinSCP or similar software, to connect to the appliance using its IP or DNS address, with SCP protocol and connecting to Port 22 using the credentials of the platform <username> (e.g., friend or ec2-user or azureuser user) to download this certificate request from /var/tmp/<certrequest>.csr file to your local desktop.
  13. Provide this certificate request file to your security provider or Certifying Authority and request that they provide the SSL Certificate specifically in base64 / PEM / CER format. For these instructions, we will call the SSL Certificate file YOURCERTNAME. When you see references to YOURCERTNAME in this document, you should substitute the actual name of the SSL Certificate file you received from your security provider or Certifying Authority.

  14. Important: Pause here until you receive your SSL certificate from your provider, then complete the process using the following instructions.

  15. Use your favorite SCP client, such as WinSCP or similar software, to connect to the appliance using its IP or DNS address, with SCP protocol and connecting to Port 22 using the credentials of the platform <username> (e.g., friend or ec2-user or azureuser user) to upload the sslcert.crt SSL Certificate file to your Stratusphere Hub or Collector in the /home/<username>/sslcert.crt location.
  16. Now back within your SSH client window on the Stratusphere Hub console, while still logged in as the root user, make a copy the original SSL certificate as a backup:
  17. Copy 
    cp /etc/lwl/ssl/ssl.crt /etc/lwl/ssl/ssl.crt.backup

  18. Copy the new certificate into /etc/lwl/ssl/ (update YOURCERTNAME with the name of your certificate)
  19. Copy 
    cp /home/$(logname)/YOURCERTNAME /etc/lwl/ssl/ssl.crt

  20. Update ownership and permissions of the certificate and key:
  21. Copy 
    chown root:root /etc/lwl/ssl/ssl.crt
    chmod 644 /etc/lwl/ssl/ssl.crt
    restorecon -RF /etc/lwl/ssl

  22. Restart the Web Server to load the newly added SSL Certificate.
  23. Copy 
    systemctl restart httpd

  24. Check that httpd is running:
  25. Copy 
    systemctl is-active httpd

  26. For Hub and Database appliances, if you’d like to immediately load the newly added SSL Certificate to database communications, restart the Postgres Database service.

  27. Copy 
    systemctl restart postgresql-*

  28. Check whether the Postgres Database service is running:

  29. Copy 
    systemctl is-active postgresql-*

  30. If the above command restarts with no errors, the new certificate has been accepted. After replacing a hub certificate, log in to the Stratusphere Hub Web UI using your browser of choice. Ensure that the UI Login page shows no certificate related warning. Also verify the information within the certificate provided by the browser address bar.