# TLS handshake policy

By default an HTTPS check only needs the TLS handshake to **complete**: an expired, self-signed or otherwise
invalid certificate does not by itself make the site "down", as long as the connection negotiates and the server
answers. That keeps "certificate problem" and "site unreachable" apart. When you want certificate and protocol
quality to count as a failure, switch on the **TLS Handshake** policy.

## Settings reference

| Setting (app label) | API field (`settings.*`) | Type | Default | Plan limits | What it does for you |
|---|---|---|---|---|---|
| **Require valid SSL certificate chain** | `requireValidChain` | Boolean | Off | SSL validation policies | Fails unless the server presents a complete, trusted chain: an expired, self-signed, name-mismatched or mis-chained certificate fails. |
| **Require strong TLS protocol (1.2 or higher)** | `requireStrongTls` | Boolean | Off | SSL validation policies | Fails when the connection negotiates TLS 1.0/1.1 or SSL. |
| **Block weak ciphers (128-bit or lower)** | `blockWeakCiphers` | Boolean | Off | SSL validation policies | Fails when the negotiated cipher suite uses 128-bit or weaker encryption. |
| **Check SSL certificate revocation** | `checkRevocation` | Boolean | Off | SSL validation policies **and** revocation checking | Verifies online (CRL/OCSP) during the handshake that the certificate has not been revoked; a revoked certificate fails. |

The switches exist on Website/HTTPS, API and Port monitors (for Port, only while TLS is switched on for the
connection).

## Set it up in the app

1. On **Sites**, open the monitor and expand **Response Validation** (for a Port monitor, its connection settings).
2. Under **TLS Handshake**, switch on the policies you want.
3. **Save**.

A switch your plan does not include is greyed out with "SSL validation policies are not available in your current
plan." (or "Revocation check is not supported in your package." for revocation) and an **Upgrade** link.

## Do it with the API or MCP

```bash
# Require a valid chain and TLS 1.2+ (scope monitor:write)
curl -X PATCH "https://api2.host-tracker.com/monitor/$MONITOR_ID" \
  -H "Authorization: Bearer $HT_TOKEN" -H "Content-Type: application/json" \
  -d '{ "settings": { "requireValidChain": true, "requireStrongTls": true } }'
```

MCP: **`update_monitor`** with `settingsJson` `{"requireValidChain":true,"requireStrongTls":true}`; many monitors
with **`bulk_update_monitors`** (`patchJson` `{"settings":{"requireValidChain":true}}`).

## What happens next

From the next check, a handshake that breaks a switched-on policy fails the check with a TLS error. Like any
failure, it is [re-checked](/monitors/down-detection/) from other locations before the monitor turns Down and
alerts go out.

## Limits and gotchas

- Turning on a switch your plan does not include is refused with `403 package_limit` ("SSL validation policies
  are not available on your package" / "Certificate revocation checking is not available on your package").
  Revocation needs both entitlements.
- A switch already on stays on if you later move to a plan without it; it just cannot be switched on again
  there. Turning a switch off is never refused.
- These switches judge the certificate at every check. To be **warned ahead** of expiry instead, use an
  [SSL/TLS certificate expiry](/monitors/types/ssl-expiry/) monitor or attach one to the website monitor - see
  [Attached sub-checks](/monitors/types/attached-sub-checks/).
- With **Require valid SSL certificate chain** on, an expired certificate turns the monitor Down. If you only want
  an expiry reminder, leave it off. See [Certificate expiry counted as downtime](/troubleshooting/cert-expiry-counted-down/).
- The old single field `tlsChainFlags` no longer exists; sending it is refused (`422`).

## Related

- [HTTP request configuration](/monitors/advanced/http-request-config/)
- [SSL/TLS certificate expiry](/monitors/types/ssl-expiry/)
- [Plan limits](/reference/plan-limits/)