# Edge certificates

> How OpenWAF issues and renews a Let's Encrypt certificate for every proxied name, and what Valid, Pending and Failed mean.

The **edge certificate** is the certificate visitors see when they open `https://www.example.com`. OpenWAF obtains it from Let's Encrypt through ACME as soon as a name is proxied, installs it on every edge node that serves the zone and renews it before it expires. There is nothing to configure.

## How issuance works

OpenWAF proves control of each name to Let's Encrypt with a challenge that depends on where the zone's DNS lives:

| Zone | Challenge | When it can start |
|---|---|---|
| Delegated (OpenWAF serves the DNS) | **DNS-01**: OpenWAF publishes the challenge record in its own DNS. | As soon as the delegation to the OpenWAF name servers is detected. |
| External (DNS stays with your provider) | **HTTP-01**: the OpenWAF edge answers the challenge. | As soon as the name points at the edge (`CNAME` to `edge.openwaf.dev`). |

With a delegated zone, when many names one level below the zone need a certificate at the same time, OpenWAF may issue a single wildcard certificate (`*.example.com` plus `example.com`) instead of one per name. Only DNS-01 can validate wildcards, so external zones always get one certificate per name.

> **Note**
>
> If your zone has `CAA` records, one of them must allow `letsencrypt.org`; otherwise Let's Encrypt refuses to issue.


## Renewal

OpenWAF renews an automatic certificate about 30 days before it expires. If an attempt fails, it retries with a growing wait (from 30 minutes up to once a day) and shows the error and the next attempt in the dashboard. Renewed certificates reach the edge nodes with their next configuration, without interrupting traffic.

## Certificate states

**SSL/TLS › Certificates › Sites** shows one row per proxied name:

| State | Meaning |
|---|---|
| **Valid** | A certificate serves the name and nothing is due. |
| **Pending** | Issuance or renewal is due or in progress. Right after a delegation it usually takes a few minutes. |
| **Failed** | The last attempt failed. **Details** shows the error, the number of failed attempts and the next attempt. |

The **Source** column says where the serving certificate comes from: **Automatic (ACME)** or **Uploaded by an operator** (a *manual* certificate). OpenWAF never replaces a manual certificate with an automatic one; it only warns when it is about to expire. Uploading certificates isn't self-service: if you need a specific certificate on a name, contact support@openwaf.dev.

The **Certificate inventory** lists every certificate stored for the zone with its names, expiry, SHA-256 fingerprint and issuance state.

**Dashboard**

Open the zone and go to **SSL/TLS › Certificates**.

**CLI**

```sh
openwaf-cloud ctl certs list example.com
```

**API**

```sh
curl -s https://dash.openwaf.dev/v1/orgs/$ORG/zones/$ZONE/certs \
  -H "Authorization: Bearer $OPENWAF_TOKEN"
```

The answer has `items` (stored certificates, each with its `issuance` state) and `sites` (one entry per proxied name with `state`, `source`, `not_after`, `days_left`, `challenge`, `last_error`, `failures` and `next_attempt_at`).

**MCP**

Ask your assistant for the certificates of the zone; it calls `list_certificates` with `{"zone": "example.com"}`.


## TLS between visitors and the edge

- The edge accepts **TLS 1.2 and TLS 1.3** only. With TLS 1.2 it offers only ECDHE key exchange with AES-GCM or ChaCha20-Poly1305.
- Key exchange prefers the hybrid post-quantum group **X25519MLKEM768**, then X25519 and P-256, so browsers that support it get post-quantum protection automatically.
- Requests over plain HTTP are redirected to HTTPS with a `301`. To make browsers skip the HTTP request entirely, turn on [HSTS](https://developers.openwaf.dev/ssl/hsts/).

## Related

- [Troubleshooting: pending or failed certificates](https://developers.openwaf.dev/ssl/troubleshooting/#certificate-pending-or-failed)
- [Origin TLS modes](https://developers.openwaf.dev/ssl/origin-tls/): the other half of the connection.