Installing SSL Certificate

SSL Certificate Requirements

Polarity-Clients require the Polarity-Server to use a valid SSL certificate. This certificate must be trusted by the workstation running Polarity Client or Polarity Web. There are several options to meet this requirement including:

1. Buy a SSL certificate.

2. Generate a server certificate from an internal Certificate Authority trusted by Polarity Client workstations.

3. Use a self-signed certificate and add it to the trusted store on all Polarity Client workstations

Options 1 and 2 are the preferred methods for all Polarity deployments in enterprise environments. If you elect to generate a self-signed SSL certificate, please refer to the SSL Certificate Generation section.

Certificate Format Requirements

Before installing your certificates please ensure the certificates are in the right format. The SSL certificate and private key should be encoded in the PEM format using the PKCS8 container. The public and private keys should be two separate files (typically a public .crt and a private .key file). The .crt file might also be generated as a .pem file.

Private Key Format

The private key should not have a passphrase on it. If your private key has a passphrase on it you can generate a copy of the key without a passphrase by running the following command on the Polarity Server:

openssl rsa -in [original.key] -out [new.key]

The original.key should be the key with the passphrase and new.key will be same key with the passphrase removed. When running the above command you will be prompted for the passphrase.

You can check to see if you private key is in the right format by viewing the content of the key. The file content should look like this:

-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC1NALrZ6xcgCLO
// Additional Base64 encoded text
-----END PRIVATE KEY-----

Public Certificate

The certificate file (.crt) should include all the certificates in your chain starting with the most specific. If you have multiple .crt files they will need to be combined into a single certificate. You can easily do this with the cat command like this:

cat cert1.crt cert2.crt cert3.crt > server.crt

The above command will add the contents of three certificates cert1.crt, cert2.crt, cert3.crt into the file server.crt. In this example, cert1 should be the most specific certificate. If you have more certificates simply add the additional file names to the cat command.

You can check the format of your public key by viewing the content of the file which should look like this:

-----BEGIN CERTIFICATE-----
MIIEADCCAuigAwIBAgIBADANBgkqhkiG9w0BAQUFADBjMQswCQYDVQQGEwJVUzEh
// Additional base64 encoded text
-----END CERTIFICATE-----

SSL Certificate Installation

The SSL certificate and key should be copied to Polarity Server and placed in the following locations:

Filename	Location
server.crt	/etc/pki/tls/certs/server.crt
server.key	/etc/pki/tls/private/server.key

The names of the certificate and key file should be server.crt and server.key as these are the filenames the server are expecting.

The SSL certificate should be in PEM format.

Permissions, including SELinux type context, should be applied to the SSL certificate and key as the root user using the following commands:

sudo chmod 600 /etc/pki/tls/certs/server.crt
sudo chmod 600 /etc/pki/tls/private/server.key
sudo chown polarityd.polarityd /etc/pki/tls/certs/server.crt
sudo chown polarityd.polarityd /etc/pki/tls/private/server.key
sudo chcon -t cert_t /etc/pki/tls/certs/server.crt
sudo chcon -t cert_t /etc/pki/tls/private/server.key

If you see the following errors when trying to apply the contexts to the server.crt file and server.key file:

chcon: can't apply partial context to unlabeled file ‘/etc/pki/tls/certs/server.crt’ 2chcon: can't apply partial context to unlabeled file ‘/etc/pki/tls/private/server.key’

Then you should use the following commands instead:

sudo chcon -h unconfined_u:object_r:cert_t:s0 /etc/pki/tls/certs/server.crt
sudo chcon -h unconfined_u:object_r:cert_t:s0 /etc/pki/tls/private/server.key

After the certificate and private key are installed, restart NGINX to ensure the certificate is accepted:

sudo systemctl restart nginx

If NGINX fails to restart, please verify the permissions and SELinux context for the SSL certificate and key. SELinux errors usually manifest themselves as permission denied errors when NGINX attempts to access the SSL certificate or key files and can be discovered by reviewing the nginx error log or audit log:

sudo cat /var/log/nginx/error.log 
sudo cat /var/log/audit/audit.log | audit2why

Once NGINX is successfully restarted, restart the Polarity Server service to ensure the certificate is accepted:

sudo systemctl restart polarityd
sudo systemctl status polarityd

Self-Signed SSL Certificate Generation

If you elect to generate a self-signed SSL certificate, please generate an SSL certificate that supports SHA256 with a minimum RSA size of 2048.

openssl req -x509 -nodes -sha256 -days 365 -newkey rsa:2048 -keyout server.key -out server.crt

To make it easier to generate a self-signed certificate Polarity provides a utility script called create-self-signed-cert.sh. Simply run the script as root and follow the instructions. The script will generate a valid self-signed certificate and install the certificate onto your server.

sudo /app/polarity-server/scripts/create-self-signed-cert.sh

Converting Between Formats

Converting PKCS1 to PKCS8

If your private key is in PKCS1 format, when you output the file you will see the following:

-----BEGIN RSA PRIVATE KEY-----
// this is PKCS1 

The header will say BEGIN RSA PRIVATE KEY instead of just BEGIN PRIVATE KEY. If this is the case, you can convert your private key from PKCS1 format to PKCS8 format using the following openssl command.

openssl pkcs8 -topk8 -inform pem -in <private_pkcs1.pem> -outform pem -nocrypt -out server.key

Replace <private_pkcs1.pem> with the name of your PKCS1 private key. The command will output the equivalent PKCS8 private key and name it server.key which is the naming format expected by Polarity Server.

If your public key is in PKCS1 format, when you output the file you will see the following:

-----BEGIN RSA PUBLIC KEY-----
// this is PKCS1

To convert the public key from PKCS1 to PKCS8 you can use the following command:

openssl rsa -RSAPublicKey_in -in <public_pkcs1.pem> -pubout -out server.crt

Replace <public_pkcs1.pem> with the name of your PKCS1 public key. The command will output the equivalent PKCS8 public key and name it server.crt which is the naming format expected by Polarity Server.

DER encoding

DER is a binary encoding. If you open your certificate and are unable to read the content of the certificate it could be DER encoded. To confirm that the certificate is DER encoded run the command:

openssl x509 -in <cert.cer> -inform DER -text

Replace <cert.cer> with the certificate you want to test. If the certificate is in DER format you will see the certificate content output. If the certificate is not in DER format you will get the error message unable to load certificate.

If the certificate is DER encoded you can convert it to PEM encoding using the command:

openssl rsa -inform DER -outform PEM -in <mykey.cer>-out server.crt

Replace <cert.cer> with the name of your certificate. The command will output the equivalent PEM encoded public key and name it server.crt which is the naming format expected by Polarity Server.

Troubleshooting

Checking Certificate Subject

It is important that your certificate subject matches the FQDN of your Polarity Server. To check that these match you can use the following command:

openssl x509 -in server.crt -noout -subject

To decode and view the entire certificate:

openssl x509 -in server.crt -noout -text

Private key has a passphrase

If your private key has a passphrase (i.e., is encrypted), you will need to remove the passphrase before the key can be used by the server. To do this you can run the following command.

openssl rsa -in [original-password-protected.key] -out server.key

The comman will prompt you for the passphrase and will then output a copy of the key called server.key without the passphrase.

Private Key and Public Cert Mismatch

If you see the following error when attempting to start nginx after replacing your public and private key it means the private key and certificate do not match.

nginx: [emerg] SSL_CTX_use_PrivateKey_file(“/etc/ssl/private/cert1.key”) failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch)

You can check to make sure your private key and certificate match by ensuring the MD5s from the following commands match:

openssl x509 –noout –modulus –in server.crt | openssl md5
openssl rsa –noout –modulus –in server.key | openssl md5

File Permission Error on Certificate

If the certificate has incorrect permissions and is not readable by the Polarity user, you may see the following errors in the Polarity Server logs.

at Object.start (/app/polarity-server/lib/websocket-server.js:25:22)
at /app/polarity-server/polarity-runner.js:114:31
at /app/polarity-server/lib/utils/integration-cache.js:155:9
at /app/polarity-server/node_modules/async/dist/async.js:473:16
at next (/app/polarity-server/node_modules/async/dist/async.js:5329:29)
at /app/polarity-server/node_modules/async/dist/async.js:969:16
at /app/polarity-server/lib/utils/integration-cache.js:143:13
at Object.callbackOrEmit [as callback_or_emit] (/app/polarity-server/node_modules/redis/lib/utils.js:89:9)

In this scenario, ensure the server.crt file is owned by the polarityd user.