# SSL/TLS settings reference

> Every SSL/TLS edge setting with its values and default, the origin certificate limits and the API routes, CLI commands and MCP tools.

## Edge settings

These keys live in the zone's edge settings (`GET`/`PATCH /v1/orgs/{org}/zones/{zone}/edge`). Each can be overridden for one name under `hosts.<name>`; for example `hosts.www.example.com.origin.tls_verify`. See [Per-name settings](https://developers.openwaf.dev/rules/per-name-settings/).

| Key | Values | Default | Effect |
|---|---|---|---|
| `origin.scheme` | `https`, `http` | `https` | Scheme of the connection to the origin. |
| `origin.port` | `0`–`65535` | `0` | Origin port; `0` = the scheme's (443 or 80). |
| `origin.tls_verify` | `full`, `full_strict` | `full_strict` for new zones | `full` encrypts without verifying; `full_strict` verifies chain, dates, name and revocation (failure = `526`). See [Origin TLS modes](https://developers.openwaf.dev/ssl/origin-tls/). |
| `origin.server_name` | Lower-case host name, or `""` | `""` | Name sent in SNI and verified. `""` = the origin's host name, or the site's name for an IP origin. |
| `origin.client_cert` | `true`, `false` | `false` | The edge presents its client certificate when the origin asks for one. See [Authenticated origin pulls](https://developers.openwaf.dev/ssl/authenticated-origin-pulls/). |
| `hsts.max_age` | `0`–`63072000` seconds | `0` | `Strict-Transport-Security` max-age; `0` = no header. See [HSTS](https://developers.openwaf.dev/ssl/hsts/). |
| `hsts.include_subdomains` | `true`, `false` | `false` | Adds `includeSubDomains`. |
| `hsts.preload` | `true`, `false` | `false` | Adds `preload`. |

`origin.*` TLS settings only apply when `origin.scheme` is `https`.

A `PATCH` is a JSON merge patch: only the fields you send change. It needs the `tech` or `admin` role and an `X-Change-Reason` header (1–500 characters); `If-Match: "<version>"` refuses the change if the zone changed since, and `?dry_run=1` validates and returns the diff without applying it. Invalid values are rejected with `422`.

## Origin certificate limits

| Item | Limit |
|---|---|
| Names per certificate | 1–100: the zone, names below it or `*.<name>` wildcards |
| Generated key types | `ecdsa_p256` (default), `rsa2048` |
| CSR keys | ECDSA P-256 or P-384; RSA 2048–8192 bits |
| Validity | 7, 30, 90, 365, 730, 1095 or 5475 days (default 5475) |
| Private key | Returned once, never stored |

## API routes

Paths are relative to `https://dash.openwaf.dev`.

| Route | Role | Purpose |
|---|---|---|
| `GET /v1/orgs/{org}/zones/{zone}/certs` | any | Edge certificates (`items`) and the certificate state of each proxied name (`sites`). |
| `GET /v1/orgs/{org}/zones/{zone}/origin-tls/status` | any | Origin status of each proxied name (cached 60 s). |
| `GET /v1/orgs/{org}/zones/{zone}/origin-certs` | any | Origin certificates, without keys. |
| `POST /v1/orgs/{org}/zones/{zone}/origin-certs` | `tech` | Issue an origin certificate (`?dry_run=1` validates). |
| `DELETE /v1/orgs/{org}/zones/{zone}/origin-certs/{id}` | `tech` | Revoke an origin certificate (idempotent). |
| `GET /v1/origin-tls/origin-ca.pem` | public | OpenWAF Origin CA certificates (PEM). |
| `GET /v1/origin-tls/edge-client-ca.pem` | public | OpenWAF Edge Client CA certificates (PEM), for mTLS. |
| `PATCH /v1/orgs/{org}/zones/{zone}/edge` | `tech` | Change `origin.*` and `hsts.*`. |

## CLI

| Command | Purpose |
|---|---|
| `openwaf-cloud ctl certs list <zone>` | Edge certificates and the state of each site. |
| `openwaf-cloud ctl origin-tls status <zone>` | Origin status of each name: mode, verified name, mTLS, certificate and 525/526 errors in 24 h. |
| `openwaf-cloud ctl origin-tls ca [--client]` | Origin CA (or, with `--client`, Edge Client CA) PEM. No token needed. |
| `openwaf-cloud ctl origin-certs list <zone>` | Origin certificates. |
| `openwaf-cloud ctl origin-certs create <zone> <name>… --cert-out F [--key-out F] [--key-type ecdsa\|rsa] [--days N] [--csr F]` | Issue an origin certificate. |
| `openwaf-cloud ctl origin-certs revoke <zone> <id>` | Revoke an origin certificate. |
| `openwaf-cloud ctl zones set <zone> [--host <name>] origin.tls_verify=… origin.server_name=… origin.client_cert:=true hsts.max_age=…` | Change the settings. |

Every change needs `--reason "…"`; see the [CLI](https://developers.openwaf.dev/cli/) for the shared options.

## MCP tools

| Tool | Purpose |
|---|---|
| `list_certificates` | Edge certificates and the status of each proxied site. |
| `origin_tls_status` | Origin status of each proxied name. |
| `list_origin_certs` | Origin certificates. |
| `create_origin_cert` | Issue an origin certificate (two steps). |
| `revoke_origin_cert` | Revoke an origin certificate (two steps). |
| `update_settings` | Change `origin` and `hsts` settings (two steps). |

See [MCP server](https://developers.openwaf.dev/mcp/).