Certificate Import and Enabling TLS/SSL on Syndeia Cloud

Overview

The following OS-specific section will guide you through re-configuring Syndeia Cloud (SC) to:

a. begin using a certificate of your choosing (ie: commercial 3rd-party, internal CA, or self-generated)
b. listen for HTTPS traffic on TCP port 9443 ( not 443, but it can be configured to do so), and
c. stop listening for HTTP traffic on TCP port 9000.

Make sure to also configure your firewall to allow the new port, ex: 9443.

Note, this document is not an in-depth discussion on certificate generation + management. If you are unfamiliar with any of the terminology or need a review, you can refer to the section below but please refer to other primary sources for additional information.

Terminology

X.509: An ITU-T standard based on the ASN.1 standard
Public Key Cryptography Standard (PKCS): a set of standards published by RSA
Public Key Infrastructure (PKI): Overall infrastructure based on public & private key cryptography (large prime numbers), usually includes services for issuing, signing, renewing, and revoking certificates
Certificate Authority (CA): a central authority (server) used to sign and issue certificates, usually public, ex: Verisign, Thawte, etc.
Root CA: Top-level CA, usually the cert for this is self-signed and the public cert is distributed and installed to all clients, the private keys for this are usually locked away in a secure offline location to prevent compromise
Signing/Intermediate CA: CA that is actually used to sign certificates
Certificate Revocation List (CRL): list of revoked certificates
Online Certificate Status Protocol (OCSP): protocol to detect if a certificate has been revoked
.CSR (Certificate Signing Request): file extension defining a certification request, it is what is presented to the signing-CA for signing to become a certificate, consists of three main parts: the certification request information, a signature algorithm identifier, and a digital signature on the certification request information, usually encoded in PKCS#10- a Base64 (plain-text) format,
Certificate: the public key of a server/client/user with accompanying meta-data signed by a trusted authority, used for authentication, also called an X.509 certificate as it defines the format of certificates. Usually includes an expiration date.
Wildcard certificate: a certificate that allows any hostname under a specific domain name.
Subject Alternative Name (SAN): An X.509 v3 extension allowing for alternative Fully Qualified Domain Names (FQDN)s/domains to be defined, ex: DNS:wikiversity.org, DNS:wikivoyage.org, DNS:wiktionary.org
Full chain: used to indicate that all certificates up to a root authority are available, ie: root-CA, signing/intermediate-CA, issued server/client/user certificate
.DER (Distinguished Encoding Rules): is a subset of the X.690 ITU-T standard specifying several ASN.1 encoding formats; also a file extension for certificates (usually binary encoded).
.PEM (Privacy-enhanced Electronic Mail): certificate extension, Base64 (plain-text) encoded DER certificate, enclosed between "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----"
.CER, .CRT (Certificate): certificate extension, X.509 format usually or Base64 (plain-text).
.P7B, .P7C (PKCS#7): bundled certificate extension, SignedData structure without data, just certificate(s) or CRL(s)
.P12 (PKCS#12) / .PFX (Personal inFormation eXchange): bundle of (usually full-chain) certificate(s) (public) and private keys (password protected); PFX was a MS IIS standard that was the precursor to P12.
.JKS (Java Key Store): Java key store (repository) and extension used to store private keys, public keys, and certificates, created by Java’s keytool binary

Linux RHEL/Alma 8

1. Obtain full-chained cert, ie: root/signing CA + intermediate + issued cert (+ private key?) ( Note, you may need to create a CSR via openssl or Java keytool and submit it to your CA / IT security admin).

2. Concat root-CA + signing-CA certs:

cat signing-ca.crt root-ca.crt | sudo tee signing-ca_root-ca.crt

3. On a machine with openssl, convert (PEM bundle + priv-key PEM file) to PKCS12 (PFX) file, where host.domain.tld = your server's FQDN, ie: syndeia-cloud.company.com ( Note, you will need to create a password to protect exporting of the private key):

openssl pkcs12 -export -inkey host.domain.tld.key -in host.domain.tld.crt -certfile signing-ca_root-ca.crt -out host.domain.tld_CA-name_ca-chain_priv-key.pfx -name server -caname root

4. Copy .PFX over to Syndeia Cloud server which CSR was requested for

5. On the Syndeia Cloud server, copy the PFX (PKCS12) to the system's SSL cert directory & update ownership + permissions, where host.domain.tld = your server's FQDN, ie: syndeia-cloud.company.com:

sudo cp host.domain.tld_CA-name_ca-chain_priv-key.pfx /etc/ssl/certs/.
sudo chown root:syndeia-cloud /etc/ssl/certs/host.domain.tld_CA-name_ca-chain_priv-key.pfx
sudo chmod ug+rw /etc/ssl/certs/host.domain.tld_CA-name_ca-chain_priv-key.pfx

6. On the Syndeia Cloud server, update the web-gateway service's conf/application.conf file to now include an HTTPS.conf file:

sudo sed -i.bak 's#include "silhouette.conf"#include "HTTPS.conf"\ninclude "silhouette.conf"#' /opt/icx/syndeia-cloud-current/web-gateway-3.6/conf/application.conf

7. On the Syndeia Cloud server, create a new HTTPS.conf file in the web-gateway service's conf/ directory with the following settings to enable TLS/SSL, where <keystorePW> = the keystore password created in the previous step, ie:

# play.server.https.keyStore.path - The path to the keystore containing the private key and certificate, if not provided generates a keystore for you in the conf dir
play.server.https.keyStore.path = /etc/ssl/certs/host.domain.tld_CA-name.pfx

# play.server.https.keyStore.type - The key store type, defaults to JKS
play.server.https.keyStore.type = pkcs12

# play.server.https.keyStore.password - The password, defaults to a blank password if omitted
play.server.https.keyStore.password = "<keystorePW>"

# TLS/SSL port to run on
play.server.https.port = 9443
# HTTP port to run on, or set to "disabled" if you want to force TLS/SSL
play.server.http.port = disabled

# Set the following additional security settings if running on production
jdk.tls.ephemeralDHKeySize=2048
jdk.tls.rejectClientInitiatedRenegotiation=true

Note, you will probably also want to update your FW settings too, ex. for firewalld: change port to 9443 in L5 of /etc/firewalld/services/syndeia.xml.

8. If you are setting up a port below 1000 for your HTTPS connection (such as 443), then add the following line to /etc/systemd/system/sc-web-gateway.service within its [Service] section:

Ambient Capabilities

AmbientCapabilities=CAP_NET_BIND_SERVICE

9. On Syndeia Cloud server, restart the Syndeia Cloud web-gateway service, ie: sudo systemctl restart sc-web-gateway

If you've updated firewalld too, use: sudo firewall-cmd --reload && systemctl restart sc-web-gateway

10. Update the web-gateway entry in the lagom.services section of /opt/icx/syndeia-cloud-current/devops-.../conf/application.conf section to specify the external URL and HTTPS port (replace host.domain.tld with your FQDN):

application.conf

lagom.services {
  cas_native = "http://localhost:9042"

  [...]
  web-gateway = "https://host.domain.tld:9443"
  [...]
}

Windows 2012-R2+

1. Obtain full-chained cert, ie: root/signing CA + intermediate + issued cert (+ private key?) ( Note, you may need to create a CSR via openssl or Java keytool or IIS and submit it to your CA / IT security admin).

2. Concat root-CA + signing-CA certs:

copy signing-ca.crt+root-ca.crt signing-ca_root-ca.crt

3. On a machine with openssl, convert (PEM bundle + priv-key PEM file) to PKCS12 (PFX) file, where host.domain.tld = your server's FQDN, ie: syndeia-cloud.company.com ( Note, you will need to create a password to protect exporting of the private key):

openssl pkcs12 -export -inkey host.domain.tld.key -in host.domain.tld.crt -certfile signing-ca_root-ca.crt -out host.domain.tld_CA-name_ca-chain_priv-key.pfx -name server -caname root

4. Copy .PFX over to Syndeia Cloud server which CSR was requested for

5. On the Syndeia Cloud server, launch Cygwin Terminal and copy the PFX (PKCS12) to the system's SSL cert directory & update ownership + permissions, where host.domain.tld = your server's FQDN, ie: syndeia-cloud.company.com:

cp host.domain.tld_CA-name_ca-chain_priv-key.pfx /etc/ssl/certs/.
# may want to set ACLs as appropriate on /etc/ssl/certs/host.domain.tld_CA-name_ca-chain_priv-key.pfx
chmod ug+rw /etc/ssl/certs/host.domain.tld_CA-name_ca-chain_priv-key.pfx

6. On the Syndeia Cloud server, in the Cygwin Terminal, update the web-gateway service's conf/application.conf file to now include an HTTPS.conf file:

sed -i.bak 's#include "silhouette.conf"#include "HTTPS.conf"\ninclude "silhouette.conf"#' /opt/icx/syndeia-cloud-current/web-gateway-3.6/conf/application.conf

7. On the Syndeia Cloud server, create a new HTTPS.conf file in the web-gateway service's conf/ directory with the following settings to enable TLS/SSL, where <keystorePW> = the keystore password created in the previous step, ie:

# play.server.https.keyStore.path - The path to the keystore containing the private key and certificate, if not provided generates a keystore for you in the conf dir
play.server.https.keyStore.path = C:\\\cygwin64\\\etc\\\ssl\\\certs\\\host.domain.tld_CA-name.pfx

# play.server.https.keyStore.type - The key store type, defaults to JKS
play.server.https.keyStore.type = pkcs12

# play.server.https.keyStore.password - The password, defaults to a blank password if omitted
play.server.https.keyStore.password = "keystorePW"

# TLS/SSL port to run on
play.server.https.port = 9443
# HTTP port to run on, or set to "disabled" if you want to force TLS/SSL
play.server.http.port = disabled

# Set the following additional security settings if running on production
jdk.tls.ephemeralDHKeySize=2048
jdk.tls.rejectClientInitiatedRenegotiation=true

Note, you will probably also want to update your FW settings too, ex. for Windows Firewall, double-click the ruleset for the Syndeia Cloud ruleset to bring up the properties and navigate to the appropriate tab to update the port

8. On the Syndeia Cloud server, restart the Syndeia Cloud Web-Gateway service (sc-web-gateway).

9. Update the web-gateway entry in the lagom.services section of C:\cygwin64\opt\icx\syndeia-cloud-current\devops-...\conf\application.conf section to specify the external URL and HTTPS port (replace host.domain.tld with your FQDN):