# TLS / HTTPS

These settings are for configuring the TLS / HTTPS support for datarhei Core.

## Configuration

{% tabs %}
{% tab title="JSON" %}

```
{
   "tls": {
      "address": ":8181",
      "enable": false,
      "auto": false,
      "mail": "cert@datarhei.com",
      "cert_file": "",
      "key_file": "",
   }
}
```

{% endtab %}

{% tab title="ENV" %}

```
CORE_TLS_ADDRESS=":8181"
CORE_TLS_ENABLE=false
CORE_TLS_AUTO=false
CORE_TLS_MAIL=cert@datarhei.com
CORE_TLS_CERT_FILE=
CORE_TLS_KEY_FILE=
```

{% endtab %}
{% endtabs %}

### address (string)

If TLS is enabled, the HTTPS server will listen on this address. The default address is `:8181`.

{% hint style="info" %}
The default `:8181` will listen on all interfaces on port 8181. To use a specific interface, write additionally it's IP, e.g. `127.0.0.1:8181` to only listen on the loopback interface.
{% endhint %}

### enable (bool)

Set this value to `true` in order to enable TLS / HTTPS support. If enabled you have to either provide your own certificate (see [cert\_file](#cert_file) and [key\_file](#key_file)) or enable automatic certificate from Let's Encrypt (see [auto](#auto)).

If TLS is enabled, a HTTP server listening on [address](https://docs.datarhei.com/core/configuration/..#address) will be additionally started. This server provides access to everything as the HTTPS server, additionally it will allow ACME http-1 challenges in case Let's Encrypt (auto) certificates are enabled.

By default this is set to `false`.

### **auto (bool)**

Enable automatic certificate generation from Let's Encrypt. This only works if `enable` is set to `true` and at least one public hostname is defined in [host.name](https://docs.datarhei.com/core/hostname#name-array). All listed hostnames will be included in the certificate. All listed public hostnames is required to point to the host where datarhei Core is running on.

{% hint style="warning" %}
In order for Let's Encrypt to resolve the http-1 challenge, the HTTP server of the datarhei Core must be reachable on port 80. Either by setting [address](https://docs.datarhei.com/core/configuration/..#address) to `:80` or by forwarding/mapping port 80 to the actual port the HTTP server is listening on.
{% endhint %}

The obtained certificates will be stored in the `/cert` subdirectory of [db.dir](https://docs.datarhei.com/core/database#dir-string) to be available after a restart.

Any provided paths in `cert_file` and `key_file` will be ignored.

By default this is set to `false`.

### **mail (string)**

An email address that is required for Let's Encrypt in order to receive a certificate.

By default the email address `cert@datarhei.com` is used.

### **cert\_file (string)**

If you bring your own certificate, provide the path to the certificate file in PEM format.

By default this is not set.

### **key\_file (string)**

If you bring your own certificate, provide the path to the key file in PEM format

By default this is not set.

## Examples

### Let's Encrypt

If you want to use automatic certificates from Let's Encrypt, set [tls.enable](#enable-bool) and [tls.auto](#auto-bool) to `true`. and [host.name](https://docs.datarhei.com/core/hostname#name-array) has to be set to the domain name this host will be reachable. Otherwise the ACME http-1 challenge will not work. 

{% tabs %}
{% tab title="JSON" %}

```
{
   "address": ":80",
   "host": {
      "name": ["domain.com"],
      "auto": false
   },
   "tls": {
      "address": ":8181",
      "enable": true,
      "auto": true,
      "mail": "cert@domain.com"
   }
}
```

{% endtab %}

{% tab title="ENV" %}

```
CORE_ADDRESS=:80
CORE_HOST_NAME=domain.com
CORE_HOST_AUTO=false
CORE_TLS_ADDRESS=:8181
CORE_TLS_ENABLE=true
CORE_TLS_AUTO=true
CORE_TLS_EMAIL=cert@domain.com
```

{% endtab %}
{% endtabs %}

### Self-Signed certificates

To create a self-signed certificate and key file pair, run this command and provide a reasonable value for the Common Name (CN). The CN is the fully qualified name of the host the instance is running on (e.g., `localhost`). You can also use an IP address or a wildcard name, e.g., `*.example.com`.

RSA SSL certificate

```
openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out cert.pem -subj '/CN=localhost'
```

ECDSA SSL certificate

```
openssl ecparam -name secp521r1 -genkey -out key.pem
openssl req -new -x509 -key key.pem -out cert.pem -days 365 -subj '/CN=localhost'
```

Call `openssl ecparam -list_curves` to see all available supported curves listed.

{% tabs %}
{% tab title="JSON" %}

```
{
   "host": {
      "name": ["domain.com"],
      "auto": false
   },
   "tls": {
      "address": ":8181",
      "enable": true,
      "auto": false,
      "cert_file": "/core/config/example.cert",
      "key_file": "/core/config/example.key"
   }
}
```

{% endtab %}

{% tab title="ENV" %}

```
CORE_HOST_NAME=domain.com
CORE_HOST_AUTO=false
CORE_TLS_ADDRESS=:8181
CORE_TLS_ENABLE=true
CORE_TLS_AUTO=false
CORE_TLS_CERT_FILE=/core/config/example.cert
CORE_TLS_KEY_FILE=/core/config/example.key
```

{% endtab %}
{% endtabs %}