> For the complete documentation index, see [llms.txt](https://docs.enginsight.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enginsight.com/docs/knowledge-base/english/configuration/how-do-i-store-and-configure-a-self-signed-ssl-tls-certificate-in-enginsight.md).

# How do I store and configure a self-signed SSL/TLS certificate in Enginsight?

If you use a self-signed SSL/TLS certificate or a Windows PKI (Public Key Infrastructure) for the secure connection to the Enginsight user interface and/or Enginsight SIEM, you must store and configure it manually.

In the following article, we will show you which steps you need to take to do so.

***

## Storing the Certificate Files

{% stepper %}
{% step %}

### Upload the certificate files to the Application Server

{% hint style="warning" %}
**Please note**: These steps only apply to Linux and macOS systems. On Windows, you can use WinSCP (Windows Secure Copy), for example, to upload the certificate files to the Application Server.
{% endhint %}

1. On the **system on which your new certificate is stored**, navigate to the folder that contains all new certificate files using the following command:

```
cd /<CustomDirectoryPath>/<CertificateFilesFolder>
```

{% hint style="info" %}
Remember to replace `<CustomDirectoryPath>` and `<CertificateFilesFolder>` accordingly.
{% endhint %}

2. Upload the new certificate files to a target directory of your choice on the Enginsight Application Server using the following command:

```
<CertificateFilesFolder> % scp * <ApplicationServerUsername>@<ApplicationServerIPAddress>:<ApplicationServerTargetDirectory>
```

{% hint style="info" %}
Remember to replace the placeholders in `<>` accordingly:

* `<CertificateFilesFolder>`
* `<ApplicationServerUsername>`
* `<ApplicationServerIPAddress>`
* `<ApplicationServerTargetDirectory>`
  {% endhint %}
  {% endstep %}

{% step %}

### Optional: Convert certificate files to the PEM format

If your self-signed certificate files are available in the PFX format, you must convert them to the PEM format *after uploading them to the Application Server*.

You can use the following commands for this:

* Convert the certificate to PEM format without the private key:

```
openssl pkcs12 -in <CertificateFileName>.pfx -clcerts -nokeys -out <NewCertificateFileName>.pem
```

* Extract the private key and convert it to the PEM format:

```
openssl pkcs12 -in <CertificateFileName>.pfx -nocerts -out <PrivateKeyFileName>.pem
```

* Remove the password from the extracted key:

```
openssl rsa -in <PrivateKeyFileName>.pem -out server.key
```

{% hint style="info" %}
Remember to replace the placeholders in `<>` accordingly:

* `<CertificateFileName>`
* `<NewCertificateFileName>`
* `<PrivateKeyFileName>`
  {% endhint %}
  {% endstep %}

{% step %}

### Adjust access rights for the certificate files

Because the uploaded certificate files can only be read by the user who is currently logged in to the Application Server, but not by the web server, the access rights must be adjusted accordingly.

Run the following command to adjust the access rights:

```
sudo chown root: *.pem
```

{% endstep %}

{% step %}

### Adjust the nginx configuration

You can now adjust the nginx configuration.

1. Open the **nginx configuration file** using the following command:

```
sudo nano /etc/nginx/sites-available/ngs.conf
```

2. Compare the following template with the configuration file and edit the highlighted lines as follows:
   * For `<CustomDirectoryPath>`, enter the path that leads to the new certificate files.
   * For `<CertificateFileName>`, enter the name of the new certificate file.
   * For `<KeyFileName>`, enter the name of the new certificate key file.

{% hint style="danger" %}
**Please note**: The **complete certificate chain** consisting of the root certificate, intermediate certificate (if available), and server certificate must be stored in a corresponding file.
{% endhint %}

{% hint style="warning" %}
**Please note**: The Diffie-Hellman parameter (`dhparam`) is not available by default and must be created first; otherwise, nginx will return an error.

In our example, we also specify a key length of **2048** bits. While this is secure, we nonetheless recommend a key length of **3072** bits or **4096** bits. Adjust the key length accordingly if needed. Please note, however, that creating the key will take significantly longer in this case.
{% endhint %}

<pre><code>map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    server_name &#x3C;AppDomain>;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers "ECDHE+AESGCM+AES256";
    ssl_ecdh_curve secp384r1;
    ssl_session_cache shared:SSL:10m;
    ssl_session_tickets off;
    ssl_stapling on;
    ssl_stapling_verify on;
    resolver 8.8.8.8 8.8.4.4 valid=300s;
    resolver_timeout 5s;

    # Creating dhparam.pem:
    #$ sudo mkdir /etc/nginx/ssl -p
    #$ sudo openssl dhparam -out /etc/nginx/ssl/dhparam.pem 2048
    
    ssl_dhparam /etc/nginx/dhparam.pem;
    
<strong>    ssl_certificate /&#x3C;CustomDirectoryPath>/&#x3C;CertificateFileName>.pem;
</strong><strong>    ssl_certificate_key /&#x3C;CustomDirectoryPath>/&#x3C;KeyFileName>.pem;
</strong>
    client_max_body_size 200m;

    location / {
        proxy_pass http://127.0.0.1:81;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-Proto "https";
        proxy_set_header X-Forwarded-Ssl   "on";
        proxy_set_header Upgrade           $http_upgrade;
        proxy_set_header Connection        $connection_upgrade;
    }
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    server_name &#x3C;DomainAPI>;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers "ECDHE+AESGCM+AES256";
    ssl_ecdh_curve secp384r1;
    ssl_session_cache shared:SSL:10m;
    ssl_session_tickets off;
    ssl_stapling on;
    ssl_stapling_verify on;
    resolver 8.8.8.8 8.8.4.4 valid=300s;
    resolver_timeout 5s;

    # Creating dhparam.pem:
    #$ sudo mkdir /etc/nginx/ssl -p
    #$ sudo openssl dhparam -out /etc/nginx/ssl/dhparam.pem 2048

    ssl_dhparam /etc/nginx/dhparam.pem;
    
<strong>    ssl_certificate /&#x3C;CustomDirectoryPath>/&#x3C;CertificateFileName>.pem;
</strong><strong>    ssl_certificate_key /&#x3C;CustomDirectoryPath>/&#x3C;KeyFileName>.pem;
</strong>
    client_max_body_size 200m;

    location / {
        proxy_pass http://127.0.0.1:82;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-Proto "https";
        proxy_set_header X-Forwarded-Ssl   "on";
        proxy_set_header Upgrade           $http_upgrade;
        proxy_set_header Connection        $connection_upgrade;
    }
}
</code></pre>

3. Save the changes to the configuration file (**Ctrl** + **o**) and confirm the save process. Close the file (**Ctrl** + **x**).
   {% endstep %}

{% step %}

### Check the changes to the nginx configuration

Validate the changes to the nginx configuration using the following command:

```
sudo nginx -t
```

If the configuration changes are successful, you will get the following answer:

```
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
```

{% endstep %}

{% step %}

### Restart nginx

Restart nginx using the following command:

```
sudo systemctl restart nginx
```

{% endstep %}
{% endstepper %}

***

## Trusting the Root Certificate

You must now mark your root certificate as trusted on the Enginsight Application Server and also, if you use the Enginsight SIEM, on the SIEM Management Server.

{% hint style="danger" %}
**Please note**: ***Only certificates in*** **`.crt`** ***format*** are accepted. Files with other extensions such as `.pem` or `.cer` are ignored by the `update-ca-certificates` process. In most cases, it is possible to simply rename files with the `.pem` extension accordingly. What is important is that the certificate is ***Base64-encoded***.
{% endhint %}

Follow these steps:

{% stepper %}
{% step %}

### Copy the root certificate to the CA store of the Application Server

1. Log in to the **Enginsight Application Server**.
2. Copy the root certificate to the CA store using one of the following commands.

{% hint style="danger" %}
**Please note**: The certificate must be **Base64-encoded**.
{% endhint %}

**Command for files in `.pem` format:**

```
sudo cp <RootCertificateFileName>.pem /usr/local/share/ca-certificates/<RootCertificateFileName>.crt
```

**Command for files in `.crt` format:**

```
sudo cp <RootCertificateFileName>.crt /usr/local/share/ca-certificates/<RootCertificateFileName>.crt
```

{% hint style="info" %}
Remember to replace `<RootCertificateFileName>` accordingly.
{% endhint %}
{% endstep %}

{% step %}

### Update the CA store of the Application Server

Update the CA store of the Application Server using the following command:

```
sudo update-ca-certificates
```

{% endstep %}

{% step %}

### Copy the root certificate to the CA store of the SIEM Management Server

If you use the Enginsight SIEM, you must also store the root certificate on the SIEM Management Server.

{% hint style="danger" %}
**Please note**: The certificate must be **Base64-encoded**.
{% endhint %}

1. Log in to the **SIEM Management Server**.
2. Copy the root certificate to the CA store using one of the following commands:

**Command for files in `.pem` format:**

```
sudo cp <RootCertificateFileName>.pem /usr/local/share/ca-certificates/<RootCertificateFileName>.crt
```

**Command for files in `.crt` format:**

```
sudo cp <RootCertificateFileName>.crt /usr/local/share/ca-certificates/<RootCertificateFileName>.crt
```

{% hint style="info" %}
Remember to replace `<RootCertificateFileName>` accordingly.
{% endhint %}
{% endstep %}

{% step %}

### Update the CA store of the SIEM Management Server

Update the CA store of the SIEM Management Server using the following command:

```
sudo update-ca-certificates
```

{% endstep %}

{% step %}

### Adjust the Docker configuration file on the Application Server

1. Go back to the **Enginsight Application Server**.
2. Navigate to the Enginsight installation directory using the following command:

```
cd /opt/enginsight/enterprise
```

2. Open the **Docker configuration file** using the following command:

```
sudo nano docker-compose.yml
```

3. To make the root certificate available in the required Docker container, it must be mounted there manually.\
   \
   To do this, navigate to the `volumes` section in the Docker container `server-m2` and add the following:

<pre><code>volumes:
<strong>    - "/usr/local/share/ca-certificates/&#x3C;RootCertificateFileName>:/etc/ssl/cert.crt"
</strong></code></pre>

{% hint style="info" %}
Remember to replace `<RootCertificateFileName>` accordingly.
{% endhint %}

4. Because Node.js does not access the system trust store, the environment variable `NODE_EXTRA_CA_CERTS` must be set in the affected Docker container to point to the root certificate.\
   \
   To do this, navigate to the `environment` section in the same Docker container as before and add the following:

<pre><code>environment:
<strong>    - NODE_EXTRA_CA_CERTS=/etc/ssl/cert.crt
</strong></code></pre>

5. Save the changes to the configuration file (**Ctrl** + **o**) and confirm the save process. Close the file (**Ctrl** + **x**).
   {% endstep %}

{% step %}

### Adjust the Docker configuration file on the SIEM Management Server

1. Go back to the **SIEM Management Server**.
2. Navigate to the Enginsight installation directory using the following command:

```
cd /opt/enginsight/enterprise
```

2. Open the **Docker configuration file** using the following command:

```
sudo nano docker-compose.yml
```

3. To make the root certificate available in the required Docker containers, it must be mounted there manually.\
   \
   To do this, navigate to the `volumes` section in the Docker containers `solr`, `zookeeper`, and `traicer`, and add the following:

<pre><code>volumes:
<strong>    - "/usr/local/share/ca-certificates/&#x3C;RootCertificateFileName>:/etc/ssl/cert.crt"
</strong></code></pre>

{% hint style="info" %}
Remember to replace `<RootCertificateFileName>` accordingly.
{% endhint %}

4. Because Node.js does not access the system trust store, the environment variable `NODE_EXTRA_CA_CERTS` must be set in the affected Docker containers to reference the root certificate.\
   \
   To do this, navigate to the `environment` section in the same Docker containers as before and add the following:

<pre><code>environment:
<strong>    - NODE_EXTRA_CA_CERTS=/etc/ssl/cert.crt
</strong></code></pre>

5. Save the changes to the configuration file (**Ctrl** + **o**) and confirm the save process. Close the file (**Ctrl** + **x**).
   {% endstep %}

{% step %}

### Apply the changes on the Application Server

You must now run the setup script for the Application Server again to apply your changes.

1. Navigate back to the Enginsight installation directory on the Application Server.
2. Run the setup script anew using the following command and confirm all prompts with the **Enter** key:

```
sudo ./setup.sh
```

{% endstep %}
{% endstepper %}

***

## Checking Domain Functionality

Now check whether your domains for the user interface (app) and API are working as expected.

Run the following commands:

* **User interface (app)**:

```
curl -IsS https://<DomainApp> |& head -n1
```

* **API**:

```
curl -IsS https://<DomainAPI> |& head -n1
```

{% hint style="info" %}
Remember to replace `<DomainApp>` and `<DomainAPI>` accordingly.
{% endhint %}

If everything works as expected, you should get one the following answers:

```
HTTP/1.1 200 OK
```

or

```
 HTTP/2 200
```

If the self-signed certificate is considered untrusted, the following answer will be returned:

```
curl: (60) SSL certificate problem: self signed certificate
```

In this case, check whether the entire certificate chain is actually included in the certificate file and whether the root certificate was trusted correctly.

***

## Further Resources

* [How do I replace a self-signed SSL/TLS certificate in Enginsight?](/docs/knowledge-base/english/configuration/how-do-i-replace-a-self-signed-ssl-tls-certificate-in-enginsight.md)
* [How do I update a SSL/TLS certificate by Let's Encrypt in Enginsight?](/docs/knowledge-base/english/configuration/how-do-i-update-a-ssl-tls-certificate-by-lets-encrypt-in-enginsight.md)
* [What adjustments do I need to make if my Enginsight domain changes?](/docs/knowledge-base/english/configuration/what-adjustments-do-i-need-to-make-if-my-enginsight-domain-changes.md)

***