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.

cat new.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 your Polarity server in the following locations. The SSL certificate should be in PEM format.

Filename	Install Location	Polarity Container Specification
server.crt	/app/caddy/config	polarity_web
server.key	/app/caddy/config	polarity_web
polarity.pem	/app/certs	polarity_platform
polarity_key.pem	/app/certs	polarity_platform
<any_ca_chain_filename>.crt	/app/certs/ca	N/A

server.crt and polarity.pem are the same file and differ only in their filename and install location.

server.key and polarity_key.pem are the same file and differ only in their filename and install location.

The filenames for your certificates must match the filenames provided above with the exception of CA certificates placed in /app/certs/ca.

After the certificate and private key are installed in the correct locations listed above, restart the server's containers.

cd /app && ./down.sh && ./up.sh

CA Certificate Chains

If there is a CA certificate chain that your company uses, such as: GoDaddy or Zscaler. The full CA cert will need to be added to Polarity in order for the integration store to work correctly.

Check the Certificate Issuer:

openssl x509 -in /app/certs/polarity.pem -issuer -noout

Download the full CA certificate. Add the CA certificate to the following location.

/app/certs/ca

The CA cert can have any filename but needs to be in PEM format and end with a .pem or .crt extension

Once you've added your CA certificate to /app/certs/ca restart the server's Docker containers:

cd /app && ./down.sh && ./up.sh

If you do not have the CA certificate, it can typically be found by navigating to the browser and clicking on the left of the url. This will pull up a dialog box that will allow you to navigate to the certificates the site is using

GoDaddy Certificate Example

The following is an example of downloading the GoDaddy CA certificate and installing it on the server.

mkdir /app/certs/ca
cd /app/certs/ca
wget https://certs.godaddy.com/repository/gd_bundle-g2.crt
cd /app && ./down.sh && ./up.sh

Self-Signed SSL Certificate Generation

If you elect to generate a self-signed SSL certificate, we recommend using the below script to generate the self-signed cert.

wget https://dl.polarity.io/beta/generate_certs.sh 
chmod a+x generate_certs.sh 
./generate_certs.sh

The script will generate the cert and put the certs into the correct locations needed for the V5 server.

Once the script is complete and the certs have been generated, we recommend restarting the docker containers:

cd /app && ./down.sh && ./up.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.

Converting PFX to PEM

Converting a PFX to a PEM file that contains both the certificate and private key:

openssl pkcs12 -in filename.pfx -out cert.pem -nodes

From there different portions of the new cert.pem file will need to be copied to the correct location:

Portion of Cert	File Name to Copy
Key Portion	/app/certs/polarity_key.pem
First Cert Portion	/app/certs/polarity.pem
Remaining Certs Listed in the chain	/app/certs/ca.crt

Other conversion options:

Extract Private key from a PFX to a PEM file:

openssl pkcs12 -in filename.pfx -nocerts -out key.pem

Exports certificate (includes public key only)

openssl pkcs12 -in filename.pfx -clcerts -nokeys -out cert.pem

Removes passphrase from the Extracted Key

openssl rsa -in key.pem -out server.key

Convert PKCS to PKCS8

openssl pkcs8 -topk8 -inform PEM -outform PEM -in 
/etc/pki/tls/private/server.key.orig -out 
/etc/pki/tls/private/server.key -nocrypt

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

Private Key and Public Cert Mismatch

If you are seeing an error Private key does not match Public key, this will typically mean that there is an error in the certs matching. To test this, please run the following commands and compare the MD5 hashes to each other.

Verify key

openssl rsa -modulus -noout -in /app/certs/polarity_key.pem | openssl md5

Verify Certificate

openssl x509 -modulus -noout -in /app/certs/polarity.pem | openssl md5

Verify if the key is valid

openssl rsa -check -noout -in /app/certs/polarity_key.pem

After running the command you should see RSA Key is ok. If you see that output then the key is valid.

If you are still seeing errors and the key and certs match, please check if there is a passphrase on the key and remove the passphrase.

If there is no pass phrase, please follow the general steps below to check if the docker containers can connect to the certs

General OpenSSL Troubleshooting

These commands will confirm if HTTPS is working and allow you to view the certs the HTTPs server is responding with

Connect to Docker Shell

docker exec -it polarity_platform bash
docker exec -it polarity_web sh

Verify Polarity_Platform can connect to Polarity_Web

docker exec -it polarity_platform bash
openssl s_client -connect polarity_web:443 -showcerts

Verify Polarity_Web can connect to Polarity_Platform

docker exec -it polarity_web sh
openssl s_client -connect polarity_platform:4001 -showcerts

Verify Polarity_Web can connect to Polarity Integration Store

docker exec -it polarity_web sh
openssl s_client -connect integration-store.polarity.io:443 -showcerts

Integration Store Failures

Integration Store fails to load

If the integration store is failing to load completly, there might be a few issues causing the problem.

Check and ensure the global proxy is setup.

See Configuring a Proxy for more details:

Configuring a Proxy

Check to ensure polarity_web can access integration store

docker exec -it polarity_web sh
curl -v https://integration-store.polarity.io/api/repos

If there is a successful connection, please check the certificates to ensure they are valid and that the full CA cert chain is added to the server.

Integration store loads but fails to install integrations

If you are able to access the integration store, however are not able install integrations and are getting an error. Then there is most likely a missing cert in the CA cert chain path.

Recommend re-checking your CA certificates to ensure the full paths are contained.

See CA section above