SSL Certificates with Situate CA

Situate provides two utility scripts to simplify SSL certificate management across multiple Situate instances. These scripts create a private Certificate Authority (CA) and generate certificates signed by that CA, eliminating browser warnings and enabling secure communication between Situate instances.

Overview

The certificate management process involves two steps:

• Initialize the Root CA - Create a private Certificate Authority once using situate-ca-init.sh
• Generate Server Certificates - Create signed certificates for each Situate instance using situate-cert-gen.sh

Both scripts are located in /opt/situate/bin (or ${INSTALLPATH}/bin if using a custom installation path).

Note

Company Name: The CA name and certificate details are derived from the company field in your Situate license file. This ensures consistency across your organization's Situate instances.

Step 1: Initialize the Root CA

The root CA must be created once and can then be used to sign certificates for all Situate instances in your organization. Run the following command on your primary Situate server:

> cd /opt/situate/bin
> sudo ./situate-ca-init.sh

This creates two files in /opt/situate/security:

• situate-ca-{company}.crt - Root CA certificate (public)
• situate-ca-{company}.key - Root CA private key (keep secure)

WARNING

Security: The CA private key (.key file) is used to sign all server certificates. Keep this file secure with restricted permissions (600). Anyone with access to this key can create valid certificates for your organization.

CA Certificate Details

The generated CA certificate has the following properties:

• Key Size: 4096-bit RSA
• Validity: 10 years (3650 days)
• Hash: SHA-256
• Subject: CN=Situate CA - {company}, O=

Step 2: Generate Server Certificates

After the root CA is created, generate a certificate for each Situate instance. Run this command on each server where Situate is installed:

> cd /opt/situate/bin
> sudo ./situate-cert-gen.sh

By default, the script uses the system's fully qualified hostname. To specify a different hostname:

> sudo ./situate-cert-gen.sh sit-production.example.com

Certificate Files Created

The script generates the following files:

• /opt/situate/security/web/server.crt - Server certificate
• /opt/situate/security/web/server.key - Server private key
• /opt/situate/security/web-container-keystore - Java keystore for Tomcat

Subject Alternative Names (SANs)

Each certificate includes multiple Subject Alternative Names for flexible access:

• Fully qualified hostname (e.g., sit-production.example.com)
• Short hostname (e.g., sit-production)
• Domain alias from dommgr.xml (e.g., sit-{domain})
• localhost
• 127.0.0.1

This allows connections using any of these names without certificate warnings.

Certificate Properties

• Key Size: 2048-bit RSA
• Validity: 1 year (365 days)
• Hash: SHA-256
• Signed By: Your Situate root CA

Step 3: Restart Situate

After generating the certificate, restart Situate to load the new keystore:

> sudo systemctl restart situate

The web interface will now use the new certificate signed by your CA.

Step 4: Distribute the CA Certificate

For servers and tools to trust certificates signed by your Situate CA, distribute the CA certificate to all systems that need to communicate with Situate instances.

For Situate Servers

Copy the CA certificate to each Situate server and configure Node.js to trust it:

> sudo cp /opt/situate/security/situate-ca-{company}.crt /opt/situate/security/
> export NODE_EXTRA_CA_CERTS=/opt/situate/security/situate-ca-{company}.crt

Add the export command to /etc/situate.conf to make it permanent:

NODE_EXTRA_CA_CERTS=/opt/situate/security/situate-ca-{company}.crt

For Web Browsers

To eliminate browser warnings, import the CA certificate into your browser or operating system trust store:

• Windows: Import into Trusted Root Certification Authorities via certmgr.msc
• macOS: Import into Keychain Access and set to "Always Trust"
• Linux: Copy to /usr/local/share/ca-certificates/ and run update-ca-certificates
• Firefox: Import via Preferences → Privacy & Security → Certificates → View Certificates → Authorities

Certificate Renewal

Server certificates are valid for one year. To renew a certificate before expiration:

• Remove the existing keystore: sudo rm /opt/situate/security/web-container-keystore
• Run situate-cert-gen.sh again to generate a new certificate
• Restart Situate: sudo systemctl restart situate

The root CA is valid for 10 years and rarely needs renewal.

Multi-Server Deployments

For organizations with multiple Situate instances:

Step 1. Create Root CA on Primary Server

Run situate-ca-init.sh once on your primary server.

Step 2. Copy CA Files to Other Servers

Copy both the CA certificate and private key to all other Situate servers:

> scp /opt/situate/security/situate-ca-{company}.crt root@server2:/opt/situate/security/
> scp /opt/situate/security/situate-ca-{company}.key root@server2:/opt/situate/security/

Ensure the private key has restrictive permissions on each server:

> sudo chmod 600 /opt/situate/security/situate-ca-{company}.key

Step 3. Generate Certificates on Each Server

Run situate-cert-gen.sh on each server to create host-specific certificates.

Step 4. Configure NODE_EXTRA_CA_CERTS

On each server, configure Node.js to trust the CA by adding to /etc/situate.conf:

NODE_EXTRA_CA_CERTS=/opt/situate/security/situate-ca-{company}.crt

Troubleshooting

Error: Root CA not found

If situate-cert-gen.sh reports that the root CA is not found, ensure you've run situate-ca-init.sh first and that the CA files exist in /opt/situate/security.

Error: License file not found

Both scripts require a valid license file at /opt/situate/license.dat. Verify the license file exists and contains a company: field.

Browser Still Shows Warnings

If browsers continue showing certificate warnings after installing the CA certificate:

• Verify the CA certificate is imported into the correct trust store
• Restart your browser after importing the certificate
• Check that the server certificate was generated after the CA was created
• Ensure you're accessing the server using a hostname that matches one of the SANs

Certificate Expired

Server certificates expire after one year. Follow the certificate renewal process to generate a new certificate.

Script Locations

The certificate management scripts are installed with Situate:

• /opt/situate/bin/situate-ca-init.sh - Initialize root CA
• /opt/situate/bin/situate-cert-gen.sh - Generate server certificate

Both scripts source /etc/situate.conf if present and respect the INSTALLPATH environment variable for non-standard installations.