
# TLS (HTTPS)

Set `server.ssl.certificate` and `server.ssl.certificate-private-key` to two PEM files, and the server speaks HTTPS instead of HTTP.

## Why

Without TLS, everything between the client and the server can be read and changed on the way: passwords, session cookies, tokens. Use TLS when clients reach the server directly, without a proxy in front.

When a reverse proxy or a load balancer ends TLS for you (nginx, Traefik, a cloud load balancer), you usually leave `server.ssl.*` empty and set `server.forward-headers-strategy` instead. See [Behind a reverse proxy](reverse-proxy.md).

Client certificates (`server.ssl.client-auth`) let the server know which machine calls: mutual TLS between services.

## Example

```yaml
# lib/resources/application.yml
server:
  port: 8443
  ssl:
    certificate: /etc/shop/tls/fullchain.pem
    certificate-private-key: /etc/shop/tls/privkey.pem
```

```properties
server.port=8443
server.ssl.certificate=/etc/shop/tls/fullchain.pem
server.ssl.certificate-private-key=/etc/shop/tls/privkey.pem
```

The startup line then says `https`:

```text
Web server started on port 8443 (https)
```

A self-signed certificate for development:

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

```properties
server.ssl.certificate=cert.pem
server.ssl.certificate-private-key=key.pem
```

Relative paths are read from the working directory of the process.

### Mutual TLS

```yaml
server:
  ssl:
    certificate: /etc/billing/tls/server.pem
    certificate-private-key: /etc/billing/tls/server-key.pem
    key-password: ${TLS_KEY_PASSWORD}
    trust-certificate: /etc/billing/tls/clients-ca.pem
    client-auth: need
```

Only clients with a certificate signed by a certificate of `clients-ca.pem` get an answer. Others get a 403.

## Properties

| Key | Type | Default | Meaning |
|---|---|---|---|
| `server.ssl.enabled` | `bool` | `true` | `false` turns TLS off and ignores the other `server.ssl.*` keys. |
| `server.ssl.certificate` | `String` (file path) | none | The certificate chain, a PEM file. TLS is on when it is set. |
| `server.ssl.certificate-private-key` | `String` (file path) | none | The private key, a PEM file. Required with `certificate`. |
| `server.ssl.key-password` | `String` | none | The password of an encrypted private key. |
| `server.ssl.trust-certificate` | `String` (file path) | none | The certificates client certificates must be signed by, a PEM file. |
| `server.ssl.client-auth` | `none` / `want` / `need` | `none` | Whether clients are asked for a certificate. |

### `server.ssl.enabled`

- **Type:** `bool`. **Default:** `true`.
- **What it does:** with `false`, the server speaks plain HTTP, even when `certificate` is set. The other keys are ignored.
- **Why change it:** keep the certificate paths in a shared `application.yml` and turn TLS off in one profile, for example in `application-dev.yml`.
- **Example:** `server.ssl.enabled=false`.
- **Note:** `true` alone turns nothing on. TLS needs `certificate` too.

### `server.ssl.certificate`

- **Type:** a file path. **Default:** none (plain HTTP).
- **What it does:** the server's certificate chain in PEM format (`-----BEGIN CERTIFICATE-----`). Put the server's certificate first, then the intermediate certificates. A Let's Encrypt `fullchain.pem` is in this form.
- **TLS is on** when this key is set (not blank) and `server.ssl.enabled` is not `false`.
- **Why change it:** to serve HTTPS. Point it at the renewed file when the certificate is renewed, then restart the application: the file is read when the server starts.
- **Example:** `server.ssl.certificate=/etc/letsencrypt/live/shop.example/fullchain.pem`.
- **A path, not a location:** it is a path in the file system. `resources:` and `classpath:` locations are not supported, and certificates are not embedded in the executable.
- **Wrong value:** a file that does not exist or is not a valid PEM certificate fails the start (`Web server failed to start`, with the `dart:io` error).

### `server.ssl.certificate-private-key`

- **Type:** a file path. **Default:** none.
- **What it does:** the private key of the certificate, in PEM format.
- **Required with `certificate`.** Without it, the start fails with:

```text
server.ssl.certificate needs server.ssl.certificate-private-key
```

- **Only the key, without `certificate`:** TLS stays off. No error.
- **Why change it:** together with `certificate`.
- **Example:** `server.ssl.certificate-private-key=/etc/letsencrypt/live/shop.example/privkey.pem`.
- **Wrong value:** a missing file, a key that does not match the certificate, or an encrypted key without the right password fails the start with the `dart:io` error.

### `server.ssl.key-password`

- **Type:** `String`. **Default:** none (the key is not encrypted).
- **What it does:** the password `dart:io` uses to decrypt an encrypted private key file.
- **Why change it:** your key file is encrypted (`-----BEGIN ENCRYPTED PRIVATE KEY-----`).
- **Example:** `server.ssl.key-password=${TLS_KEY_PASSWORD}`. Do not write the password in a file you commit: take it from an environment variable or a secret store through a placeholder.
- **Note:** a blank value counts as no password.

### `server.ssl.trust-certificate`

- **Type:** a file path. **Default:** none.
- **What it does:** a PEM file with the certificates (usually one certificate authority of your own) that client certificates must be signed by. It is used with `client-auth`.
- **Why change it:** you use `client-auth: want` or `need`. Always set it in that case, so that the server trusts exactly the issuer you chose.
- **Example:** `server.ssl.trust-certificate=/etc/billing/tls/clients-ca.pem`.
- **With `client-auth: none`** it has no effect: no client certificate is asked for.

### `server.ssl.client-auth`

- **Type:** enum. **Default:** `none`.

| Value | What happens |
|---|---|
| `none` | No client certificate is asked for. |
| `want` | The server asks for a certificate during the TLS handshake. A client without one is served anyway. |
| `need` | The server asks for a certificate. A request without one is answered with `403 Forbidden`, a `ProblemDetail` with the detail `A client certificate is required`. |

- **Why change it:** service-to-service calls where the caller proves who it is with a certificate (mutual TLS).
- **How `need` works:** the TLS handshake completes without a certificate, then the server answers every request on that connection with the 403, before any filter or controller runs. WebSocket handshakes get the same 403.
- **Example:** `server.ssl.client-auth=need`.
- **Wrong value:** `server.ssl.client-auth=sometimes` stops the start with a binding failure that names `server.ssl.client-auth`.
- **Note:** the client certificate itself is not passed to filters or controllers. The starter checks that one was presented; it does not map it to a user.

## What changes with TLS on

- `request.isSecure` is `true`, and `request.uri` has the scheme `https`.
- The session cookie gets `Secure` (unless `server.session.cookie.secure` says otherwise). See [Sessions](../sessions.md).
- A WebSocket session's URI has the scheme `wss`.
- One port serves HTTPS only. There is no second HTTP port and no redirect from HTTP to HTTPS: let a proxy do that, or start a second application.

## Rules

- The files are read once, when the server starts. A renewed certificate takes effect after a restart (in a Flutter app, also after the app comes back from the background, as the server starts again).
- Only PEM files. There are no Java key stores (`server.ssl.key-store`, `key-store-type`, `key-alias`, `trust-store`) and no SSL bundles (`server.ssl.bundle`).
- No `server.ssl.protocol`, `enabled-protocols` or `ciphers`: `dart:io` (BoringSSL) chooses them.
- HTTP/1.1 only, also over TLS: there is no HTTP/2 (`server.http2.enabled` is not read).

## In Spring (Java)

```properties
server.port=8443
server.ssl.certificate=classpath:tls/fullchain.pem
server.ssl.certificate-private-key=classpath:tls/privkey.pem
server.ssl.trust-certificate=classpath:tls/clients-ca.pem
server.ssl.client-auth=need
```

Differences that matter:

- The keys are Spring Boot's PEM keys, but the values are file paths only: no `classpath:` or `resources:` locations.
- No key stores, no SSL bundles, no protocol or cipher settings.
- With `need`, Tomcat refuses the TLS handshake without a client certificate. Here the handshake completes and each request gets a 403 `ProblemDetail`.
- The client certificate is not available to the application (Spring puts it in the request attribute `jakarta.servlet.request.X509Certificate`).

## See also

- [The embedded server](index.md)
- [Behind a reverse proxy](reverse-proxy.md)
- [Sessions](../sessions.md)
- [All properties](../properties.md)
- [Placeholders](../../spring-core-dart/config/placeholders.md)
- [Profiles](../../spring-core-dart/config/profiles.md)
