# Roll the DNSSEC keys

Replace a signed zone's zone-signing key or key-signing key, and finish a key-signing key rollover.

Replace _zone-id_ with the id of your signed hosted zone.

## How the keys roll

| Key                    | When it rolls                            | What happens                                                                                                                                                                                                                                                     |
| ---------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Zone-signing key (ZSK) | Every 90 days by itself, or when you ask | A new key is published and starts signing about two hours later. The old key stays published as `retiring` for 8 days, until every signature it made has expired, and is then removed. Nothing changes at the registrar.                                         |
| Key-signing key (KSK)  | Only when you ask                        | A second key signs at once, next to the old one, so either DS at the registrar validates. You replace the DS at the registrar. The old key is removed once two public resolvers have returned only the new DS for at least an hour (or the DS's TTL, if longer). |

The **Keys** table on the **DNSSEC** tab lists every key with its role, **Tag**, **State**
(`published`, `active` or `retiring`) and **When** it signs from, has signed since, or is removed.

## Prerequisites

- Permission for `dns:RotateDnssecKey` on the zone; to finish a key-signing key rollover early,
  `dns:CompleteDnssecKeyRollover`. Without them the console's buttons are unavailable.
- In the console, also `dns:ListZones` to open **Hosted zones** (without it the page shows an
  access-denied notice), `dns:GetZone` to open the zone (without it the zone's page is not found)
  and `dns:GetDnssec` to see its keys (without it the **DNSSEC** tab says "Seeing this zone’s
  DNSSEC keys needs dns:GetDnssec on it. Ask an administrator.").
- The zone is signed (DNSSEC status `signing`).

## Roll the zone-signing key

**Console**
1. Open the zone, then choose the **DNSSEC** tab.
2. Under **Signing**, choose **Roll the zone-signing key**.

The console says "A new zone-signing key is published; it signs in two hours." The button is
unavailable while a new zone-signing key waits to sign.

**CLI**
```sh
dcloud dns dnssec rotate zone-id --key zsk
```

**API**
```http
POST /dns/api/zones/zone-id/dnssec/rotate
{ "key": "zsk" }
```

## Roll the key-signing key

**Console**
1. Open the zone, then choose the **DNSSEC** tab.
2. Under **Signing**, choose **Roll the key-signing key**.
3. Under **DS record for the registrar**, the new key's DS now appears next to the old one. At the
   registrar, replace the DS with the newest one.
4. (Optional) Once the registrar has the new DS, choose **Finish the rollover now** to remove the
   old key without waiting for the resolvers.

The console says "A second key-signing key signs the zone. Replace the DS at the registrar with the
new one." **Roll the key-signing key** is unavailable until the rollover is finished. **Finish the
rollover now** appears only while a rollover is under way; it says "The old key-signing key is
removed."

**CLI**
```sh
dcloud dns dnssec rotate zone-id --key ksk
dcloud dns dnssec complete-rollover zone-id
```

**API**
```http
POST /dns/api/zones/zone-id/dnssec/rotate
{ "key": "ksk" }
```

To finish early:

```http
POST /dns/api/zones/zone-id/dnssec/complete-rollover
```

**Warning:**
Finish a rollover early only once the registrar serves the new DS. While the parent still points at
the old key, removing it makes validating resolvers reject every answer for the zone.

## When the request is refused

All with `409`:

- "The zone is not signed" when DNSSEC is off or being turned off.
- "A ZSK rollover is already under way" or "A KSK rollover is already under way".
- "No key-signing key rollover is under way" when you finish a rollover that has not started.

## Related

- [Sign a zone with DNSSEC](sign-a-zone-with-dnssec.md)
- [Troubleshooting](troubleshooting.md)
- `dns.dnssec.rotate` · `dns.dnssec.complete-rollover` · `dcloud dns dnssec rotate`
