--- title: "Configure SSL Certificates for Polarity Server v5" slug: "polarity-configure-server-ssl-certificates" description: "Learn how to set up and configure SSL/TLS certificates for Polarity Server v5 to enable HTTPS encryption. Step-by-step guide for administrators deploying secure server instances with proper certificate management and deployment options." updated: 2026-01-26T22:51:13Z published: 2026-01-26T22:51:13Z --- > ## Documentation Index > Fetch the complete documentation index at: https://knowledge.threatconnect.com/llms.txt > Use this file to discover all available pages before exploring further. # Configure the Server SSL Certificates ## Polarity Server Certificates 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 commercial SSL certificate 2. Generate a server certificate from an internal Certificate Authority (CA) 3. Use a self-signed certificate and add it to the trusted store on all Polarity Client workstations > [!NOTE] > Not sure? > > 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 [Self-Signed SSL Certificate Generation](/v1/docs/configure-the-server-ssl-certificates#selfsigned-ssl-certificate-generation) section --- ## Certificate Format Requirements Before installing your certificates, please ensure they are in the correct 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). > [!NOTE] > *The*`.crt`*file may also be generated as a*`.pem`*file.* - Private keys **must not** include a passphrase - Private and public keys should **not** include content outside of `-----BEGIN-----` and `-----END-----` blocks - Filenames should be limited to upper- or lower case letters, digits (0-9), underscores, and dashes (**no spaces or special characters**) ### Private Key Requirements **The private key must not have a passphrase on it.** If your private key has a passphrase, you can generate a copy of the key without a passphrase by running the following command on the Polarity Server: ```shell openssl rsa -in [original.key] -out [new.key] ``` *Replace*`[original.key]`*with the name of your current key file and*`[new.key]`*with a new name, omitting the brackets (*`[]`*) in the command.* 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. ```shell cat new.key ``` The file content should look similar to this: ```shell -----BEGIN PRIVATE KEY----- MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC1NALrZ6xcgCLO // Additional Base64 encoded text -----END PRIVATE KEY----- ``` ### Public Key Requirements The public key certificate file for your server must match the private key. This can be checked with the commands in the [Troubleshooting section](/v1/docs/configure-the-server-ssl-certificates#public-and-private-key-mismatch), below. This key must be signed by *some* certificate authority (CA), even if that CA is the server itself (ie. a “self-signed” certificate). If there is more than one CA in the CA chain (ie. one or more intermediate CAs in addition to the root CA), the public key certificate file installed in the web container’s `/app/caddy/config` directory **must**include all the certificates in the chain, **starting with the most specific**. Multiple files will need to be combined into a single file. To combine multiple certificate files, use this command: ```shell cat cert1.crt cert2.crt cert3.crt > /app/caddy/config/server.crt ``` The above command will add the contents of three certificates (`cert1.crt`, `cert2.crt`, and `cert3.crt`) into the file `/app/caddy/config/server.crt`. In this example, `cert1` is the server’s certificate. If there are additional certificates, simply add the file names to the `cat `command before the carat. Check the format of the public key by viewing the content of the file with the "`cat`" command (`cat /app/caddy/config/server.crt`). The output should look similar to this: ```shell -----BEGIN CERTIFICATE----- MIIEADCCAuigAwIBAgIBADANBgkqhkiG9w0BAQUFADBjMQswCQYDVQQGEwJVUzEh // Additional base64 encoded text for most specific public key (the server's public key) -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- MIID7TCCAtWgAwIBAgIJAJlLcgDO1uJuMA0GCSqGSIb3DQEBCwUAMIGMMQswCQYD // Additional base64 encoded text for next most specific public key (an intermediate CA) -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- MIIFCDCCAvCgAwIBAgIIcL7NAf8zejcwDQYJKoZIhvcNAQELBQAwIzEUMBIGA1UE // Additional base64 encoded text for least specific public key (the root CA) -----END CERTIFICATE----- ``` ## CA Certificate Chains If there is a CA certificate chain that your organization uses, such as GoDaddy or Zscaler, the full CA cert chain will need to be added to Polarity in order for the Integration Store to work correctly. You can see the referenced chain with the following command to check the certificate issuer: ```shell openssl x509 -in /app/certs/polarity.pem -issuer -noout ``` Obtain the full CA certificate chain (you can do this through your browser). Add all CA certificates to the `/app/certs/ca` directory. > [!NOTE] > Note > > CA certs can have any filename (no spaces or special characters) but need to be in PEM format and end with a `.pem` or `.crt` extension. Once you've added your CA certificates to `/app/certs/ca`, restart the Server's Docker containers: ```shell cd /app && ./down.sh && ./up.sh ``` > [!WARNING] > If you do not have CA chain certificates … > > They can typically be found by navigating to the Polarity Server via the browser and clicking on the “lock” or “shield” icon to 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 and download them. ### GoDaddy Certificate Example The following is an example of downloading the GoDaddy CA certificate and installing it on the server. ```shell mkdir /app/certs/ca cd /app/certs/ca wget https://certs.godaddy.com/repository/gd_bundle-g2.crt cd /app && ./down.sh && ./up.sh ``` --- ## SSL Certificate Installation The SSL certificate and key should be copied to your Polarity Server in the following locations. The SSL certificates should be in PEM format in a PKCS8 container and match the below provided filenames. | **Filename** | **Install Location** | **Polarity Container Specification** | | --- | --- | --- | | `server.crt` | `/app/caddy/config` | `polarity_web` | | `server.key` | | `polarity.pem` | `/app/certs` | `polarity_platform` | | `polarity_key.pem` | | `<any_ca_chain_filename>.crt` or `<any_ca_chain_filename>.pem` | `/app/certs/ca` | *all* | > [!NOTE] > Notes > > `server.crt` and `polarity.pem` contain the same public key (and may be the same exact file unless there is more than one CA in the CA chain) and differ only in their **filename**and**install location**. > > `server.key` and `polarity_key.pem` are the same file (i.e., contain the same certificate information) and differ only in their **filename**and**install location**. > [!CAUTION] > Warning > > The filenames for the certificates **must match**the filenames provided above. > > CA certificates placed in `/app/certs/ca` may be named arbitrarily, but they **must not** have filenames with **spaces**or **special characters**, and must have a `.crt` or `.pem` **file extension**. After the certificate and private key are installed in the correct locations listed above, restart the Server's containers. ```shell 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 `/app/utils/generate_certs.sh` script to generate the self-signed cert. The script will ask for the FQDN and IP address of the Server, then generate the key pair and put them into the correct locations needed for the v5 server. Once the script is complete and the certs have been generated and placed, restart the Docker containers to assimilate the changes: ```shell cd /app && ./down.sh && ./up.sh ``` --- ## Converting Between Formats ### Converting PKCS1 to PKCS8 If you "`cat`" the private key file, you will see the following on the first line if it is in PKCS1 format: ```shell -----BEGIN RSA PRIVATE KEY----- ``` *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: ```shell openssl pkcs8 -topk8 -inform pem -in -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. Similarly, If you "`cat`" the public key, you will see the following if it is in PKCS1 format: ```shell -----BEGIN RSA PUBLIC KEY----- ``` To convert the public key from PKCS1 to PKCS8 you can use the following command: ```shell openssl rsa -RSAPublicKey_in -in -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 To convert a PFX to a PEM file that will contain the private, public, and certificate authority public keys: ```shell openssl pkcs12 -in filename.pfx -out cert.pem -nodes ``` This will output a consolidated certificate file in PEM format, `cert.pem`. This file will include the private key, the public key, and any CA public keys (in that order, from top to bottom). [*See below to extract the public and private keys individually.*](/v1/docs/configure-the-server-ssl-certificates#export-public-certificate-only) Different portions of the new `cert.pem` file will need to be copied to the correct locations: | **Portion of Cert** | **Destination File Name(s)** | | --- | --- | | Key Portion (top) | `/app/certs/polarity_key.pem` `/app/caddy/config/server.key` | | First Cert Portion (second) | `/app/certs/polarity.pem` `/app/caddy/config/server.crt` | | Remaining Certs Listed in the chain | `/app/certs/ca/ca.crt` *If there is more than one CA Public Key, these must be concatenated onto the bottom of the*`/app/caddy/config/server.crt` *file.* | ### Extract Private key from a PFX to a PEM file ```shell openssl pkcs12 -in filename.pfx -nocerts -out key.pem ``` ### Export public certificate only ```shell openssl pkcs12 -in filename.pfx -clcerts -nokeys -out cert.pem ``` ### Remove passphrase from the extracted key ```shell openssl rsa -in key.pem -out server.key ``` ### Convert PKCS to PKCS8**** ```shell openssl pkcs8 -topk8 -inform PEM -outform PEM -in /etc/pki/tls/private/server.key.orig -out /etc/pki/tls/private/server.key -nocrypt ``` ### Convert from 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: ```shell openssl x509 -in -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: ```shell openssl rsa -inform DER -outform PEM -in -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 ### Public and Private Key Mismatch If you are seeing the error "`Private key does not match Public key`", this typically means that there is an error in the certs matching. Run the following commands and compare the MD5 hashes to each other to test this. ##### **Verify key** ```shell openssl rsa -modulus -noout -in /app/certs/polarity_key.pem | openssl md5 ``` ##### **Verify Certificate** ```shell openssl x509 -modulus -noout -in /app/certs/polarity.pem | openssl md5 ``` ##### **Verify if the key is valid** ```shell openssl rsa -check -noout -in /app/certs/polarity_key.pem ``` After running the command, you should see "`RSA Key is ok`", indicating 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](/v1/docs/configure-the-server-ssl-certificates#private-key-requirements). If there is no passphrase, follow the [general steps below](/v1/docs/configure-the-server-ssl-certificates#general-openssl-troubleshooting) 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 the Shell Inside the Docker Containers** ```shell docker exec -it polarity_platform bash docker exec -it polarity_web bash ``` #### **Verify polarity_platform can connect to polarity_web** ```shell docker exec -it polarity_platform bash openssl s_client -connect polarity_web:8443 -showcerts ``` #### **Verify polarity_web can connect to polarity_platform** ```shell docker exec -it polarity_web bash openssl s_client -connect polarity_platform:4001 -showcerts ``` #### **Verify polarity_web can connect to the Polarity Integration Store** ```shell docker exec -it polarity_web bash 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 completely, there could be a few issues causing the problem. **Check and validate the global proxy is set up.** See the [Configuring Proxies](/v1/docs/configuring-proxies) section of the Polarity Documentation for more details. **Check to ensure the polarity_web container can access the Polarity Integration Store** ```shell 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 has been added to the server. #### Integration Store Loads but Fails to Install Integrations If you are able to access the Integration Store but are not able install integrations and are getting an error, the most likely cause is a missing cert in the CA certificate chain path. We recommend re-checking your CA certificates to ensure the full chain is added to the appropriate locations. [See CA section above](/v1/docs/configure-the-server-ssl-certificates#ca-certificate-chains)