# Choose an encryption mode

> Choose how Coritan's network encrypts each hostname's traffic to your origin, and turn on Always use HTTPS and HSTS on the SSL/TLS tab.

Source: https://www.coritan.com/docs/websites/ssl/encryption-mode/

In the dashboard:

- /dashboard/websites/…/ssl: https://www.coritan.com/dashboard/websites

The encryption mode decides how Coritan's network connects to your origin for one hostname: over plain HTTP, over HTTPS without checking your origin's certificate, or over HTTPS with that check. Visitors who open an `https://` address reach Coritan's network over an encrypted connection in every mode. Choose the mode that matches what your origin serves, then decide whether to send every visitor to HTTPS and whether browsers should remember to use it. Each hostname on Coritan's network has settings of its own.

## Before you begin

- The hostname must be on Coritan's network, through a [proxied DNS record](/docs/websites/dns/#proxied-records) or a [web proxy](/docs/proxies/web-proxies/create-a-web-proxy/). A domain with neither shows `example.com is not on our network yet` on the **SSL/TLS** tab, with **Proxy a DNS record** and **Set up a web proxy**.
- Find out what your origin answers with: plain HTTP, HTTPS with a self-signed certificate, or HTTPS with a certificate from a public certificate authority.
- Before you turn on **Always use HTTPS** or **HSTS**, the hostname needs an `active` certificate. The **Certificate** card lower on the tab shows it ([Issue an SSL/TLS certificate](/docs/websites/ssl/issue-a-certificate/)).

## The three modes {#modes}

**Flexible**
: Coritan's network connects to your origin over plain HTTP, so requests cross the internet to your origin unencrypted. Choose it only when your origin has no certificate.

**Full**
: Coritan's network connects to your origin over HTTPS and does not check its certificate, so a self-signed certificate works. Choose it when your origin has a certificate of any kind.

**Full (strict)**
: Coritan's network connects to your origin over HTTPS and checks its certificate: it must come from a public certificate authority, be valid now and cover the name. The name is the origin's hostname, or the hostname visitors open when the origin is an IP address. Choose it when your origin has a certificate from a certificate authority.

A web proxy that you create starts on **Full (strict)** when it connects to its origin over TLS, and on **Flexible** when it does not. A proxied DNS record starts on **Flexible** to port 80. Coritan's network then tries HTTPS on port 443 at every address in the hostname's records, and moves it to **Full** when every address answers. It tries again each time the records change while the hostname is on plain HTTP to port 80.

## Choose the mode

1. In the dashboard, go to [Websites](https://www.coritan.com/dashboard/websites), open the domain and select the **SSL/TLS** tab.
2. When the domain has more than one hostname on Coritan's network, choose one in **Settings for**, such as `www.example.com`.
3. On the **Encryption mode** card, select **Flexible**, **Full** or **Full (strict)**.
4. Read what the change does, then confirm with the dialog's button, such as `Use Full (strict)`.

**Full** and **Full (strict)** move a hostname on port 80 to port 443, and **Flexible** moves a hostname on port 443 to port 80. A hostname on any other port keeps it, so choose the mode that matches what answers there: **Flexible** for HTTP, **Full** or **Full (strict)** for HTTPS.

When the hostname follows its proxied DNS records, the mode applies to every address in them. A web proxy with additional origins applies the port and the choice of HTTP or HTTPS to its origin host only, and each additional origin keeps what it has on the **Origin** tab. **Full** or **Full (strict)** decides for every origin on HTTPS whether Coritan's network checks its certificate.

## Always use HTTPS {#always-use-https}

**Always use HTTPS** sends every visitor who opens an `http://` address of the hostname to the same address over `https://`, with a `301` redirect. Coritan's network still answers certificate validation requests under `/.well-known/acme-challenge/` over plain HTTP, so HTTP validation keeps working.

1. On the **SSL/TLS** tab, choose the hostname in **Settings for**.
2. On the **Always use HTTPS** card, turn the switch on.

While the hostname has no `active` certificate, the card warns that browsers warn every visitor it sends to `https://`. A redirect set on the **Rules** tab with **Redirect the whole hostname** sends visitors on before **Always use HTTPS** does.

## HSTS {#hsts}

HSTS (HTTP Strict Transport Security) is a header that tells browsers to open the hostname only over HTTPS, for a time you choose. A browser that has received it turns every `http://` address of the hostname into `https://` before it sends anything, even when a visitor types `http://`.

> [!WARNING]
> Browsers keep HSTS for the time you chose, counted from their last visit, and turning it off does not reach them until that time has passed. If the hostname stops working over HTTPS in that time, those browsers cannot open it. Check that every page works over HTTPS first, and every subdomain too before you include them.

1. Turn on **Always use HTTPS** first. Coritan's network sends HSTS only with answers over HTTPS, so a visitor who stays on `http://` never receives it.
2. On the **HSTS** card, turn the switch on, then select **Turn on HSTS**. HSTS starts at **6 months**.
3. In **Remember for**, choose **1 month**, **6 months**, **1 year** or **2 years**.
4. To cover every name under the hostname as well, select **Include subdomains**, then **Include subdomains** in the dialog.
5. To ask for a place on the preload list that browsers ship with, choose **1 year** or more, select **Include subdomains**, then select **Preload** and **Turn on preload**. Then submit the domain at [hstspreload.org](https://hstspreload.org/) yourself. A preloaded domain opens only over HTTPS even on a first visit, and leaving the list takes months.

The header Coritan's network sends reads `Strict-Transport-Security: max-age=31536000; includeSubDomains; preload` for 1 year with both boxes selected. When your origin sends a `Strict-Transport-Security` header of its own, Coritan's network passes that one on and adds none.

While **Preload** is on, **Remember for** offers only **1 year** and **2 years**, and **Include subdomains** stays selected. Turn off **Preload** to change either. Turning the **HSTS** switch off sends no header from then on, and turns off **Preload** too.

## TLS versions {#tls-versions}

Coritan's network uses the same TLS settings for every hostname, and the **TLS versions** card lists them:

| Protocol | State |
| --- | --- |
| TLS 1.3 and TLS 1.2 | On |
| TLS 1.0 and 1.1 | Refused |
| HTTP/2 | On |
| HTTP/3 | On |

A browser or app that supports only TLS 1.0 or 1.1 cannot connect. Answers over HTTPS carry an `Alt-Svc` header, which tells a browser that supports HTTP/3 to use it for later requests. A browser that supports neither HTTP/2 nor HTTP/3 uses HTTP/1.1.

## Result

The dashboard confirms each change for the hostname, such as `Encryption mode set to Full (strict) for www.example.com.`, `Always use HTTPS turned on for www.example.com.` or `HSTS time for www.example.com set to 1 year.` The path on the **Encryption mode** card shows a closed lock on each encrypted part of a visit, and the sentence under **Settings for** says whether Coritan's network reaches your origin over plain HTTP or over HTTPS.

## Troubleshooting

Visitors get too many redirects on **Flexible**
: Your origin redirects `http://` requests to `https://`. On **Flexible**, every request reaches it over plain HTTP, so it answers each one with another redirect. Choose **Full** or **Full (strict)** when your origin serves HTTPS. Otherwise, set your origin to trust the `X-Forwarded-Proto` header, which Coritan's network sets to `https` for visitors on HTTPS ([What your origin receives](/docs/proxies/web-proxies/#what-your-origin-receives)).

Visitors get an error page that names `Origin TLS failed`
: On **Full (strict)**, your origin's certificate is self-signed, expired or not valid for the name it is checked against. On either **Full** mode, the origin may not serve HTTPS on its port at all. Give the origin a certificate from a public certificate authority for that name, or choose **Full** for a self-signed one.

Visitors get an error page that names `Connection refused` or `Connect timed out` after a change to **Full**
: Nothing answers on port 443 at your origin, or a firewall drops the connections. **Full** and **Full (strict)** move a hostname on port 80 to port 443. Open port 443 on the origin, or choose **Flexible** to go back to port 80. [A web proxy shows a 502 or 504 error page](/docs/proxies/troubleshooting/#a-web-proxy-shows-a-502-or-504-error-page) explains every failure the page can name.

The mode changed from **Flexible** to **Full** on its own
: The hostname follows its proxied DNS records, its records changed, and every address in them answered HTTPS on port 443 ([The three modes](#modes)). **Full** works with such an origin. If its HTTPS answers with another site, choose **Flexible** again.

Browsers warn visitors after you turn on **Always use HTTPS**
: The hostname has no `active` certificate yet, so Coritan's network answers HTTPS for it with a certificate for another name. Issue one ([Issue an SSL/TLS certificate](/docs/websites/ssl/issue-a-certificate/)), or turn **Always use HTTPS** off until the **Certificate** card shows it as `active`.

**Preload** cannot be selected
: Preload needs **Remember for** at **1 year** or more and **Include subdomains** selected, and the card says `Preload needs 1 year or more and Include subdomains.`

A browser still opens the hostname only over HTTPS after you turned HSTS off
: The browser keeps the last policy it received for its whole time, counted from its last visit. It ends on its own when that time has passed.

## Related

- [How SSL/TLS certificates work](/docs/websites/ssl/)
- [Issue an SSL/TLS certificate](/docs/websites/ssl/issue-a-certificate/)
- [Change a web proxy's origin](/docs/proxies/web-proxies/change-the-origin/)
- [Troubleshoot proxies and join addresses](/docs/proxies/troubleshooting/)

## With the API

Each hostname on Coritan's network is a web proxy, and the tab's settings are fields of it. Change them with `PATCH /api/v1/proxy/routes/{route_id}`, sending only what changes. The mode is two fields:

| Mode | `upstream_ssl` | `upstream_tls_verify` |
| --- | --- | --- |
| Flexible | `false` | not used |
| Full | `true` | `false` |
| Full (strict) | `true` | `true` |

The dashboard also sends `upstream_port`: `443` when it moves a hostname on port 80 to **Full** or **Full (strict)**, and `80` when it moves a hostname on port 443 to **Flexible**. Put web proxy `31` on **Full (strict)** and port 443:

```bash
curl -X PATCH https://api.coritan.com/api/v1/proxy/routes/31 \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"upstream_ssl": true, "upstream_tls_verify": true, "upstream_port": 443}'
```

The answer is `200` with `{"message": "Route updated"}`. On a web proxy whose origins follow its proxied DNS records (`origin_follows_dns` is `true`), a new `upstream_port` or `upstream_ssl` applies to every address in the records.

`force_https` is **Always use HTTPS**. `hsts_max_age` is the HSTS time in seconds, from `0` to `63072000` (two years), and `0` sends no header. The dashboard's times are `2592000`, `15552000`, `31536000` and `63072000`. Turn on both, with the subdomains and preload:

```bash
curl -X PATCH https://api.coritan.com/api/v1/proxy/routes/31 \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"force_https": true, "hsts_max_age": 31536000, "hsts_include_subdomains": true, "hsts_preload": true}'
```

The API judges `hsts_preload` on the values after the change. Preload with less than `31536000` seconds or without `hsts_include_subdomains` answers `422`, and `detail` names what is missing, such as `Preload needs a max age of at least one year (31536000 seconds) and include subdomains turned on.` So turning HSTS off on a preloaded hostname takes both fields: `{"hsts_max_age": 0, "hsts_preload": false}`. A time outside `0` to `63072000` answers `422` as a validation error, and a web proxy that is not yours answers `404` with `Route not found`.

`GET /api/v1/proxy/routes/{route_id}` returns the same fields, with `origin_follows_dns` ([How web proxies work](/docs/proxies/web-proxies/)).

## API

- `PATCH /api/v1/proxy/routes/{route_id}`: Update a proxy route you own (https://www.coritan.com/docs/api/reference/client/reverse-proxy/#op-patch-api-v1-proxy-routes-route-id)