{"canonical_url":"https://engineer.company/glossary/hsts/","content_markdown":"# HSTS\n\n## What it is\n\nHTTP Strict Transport Security, nearly always shortened to HSTS, is a response\nheader that tells a browser to reach a site only over HTTPS for a stated number\nof seconds, and to refuse the connection outright when the certificate is wrong.\nThe header is named `Strict-Transport-Security`, and RFC 6797 has defined it\nsince November 2012. It encrypts nothing itself; it changes what a browser is\nwilling to do over HTTPS.\n\nA typical value carries two directives:\n\n```text\nStrict-Transport-Security: max-age=31536000; includeSubDomains\n```\n\n`max-age` is how long the browser keeps the rule, here one year. With\n`includeSubDomains` the rule reaches every name below the host, so\n`api.example.com` and `old.example.com` inherit what `example.com` asked for. A\nthird token, `preload`, appears in many configurations. It comes from the\npreload list run at hstspreload.org rather than from the RFC, and it is the\nsite's consent to have its name built into browsers.\n\nOnce a browser has seen the header on a secure response, it does three things\nfor that host until the time runs out. It rewrites every `http://` address to\n`https://` before a request leaves the machine. It treats any certificate error\nas fatal, with no button to carry on regardless. And it restarts the clock each\ntime the header arrives again. A response carrying `max-age=0` makes it forget\nthe host.\n\nThe usual comparison is a redirect from port 80 to port 443. A redirect works,\nbut only after the browser has sent its first request in the clear, and anyone\non the same network can answer that request themselves and keep the visitor on\nan unencrypted copy of the site. HSTS removes that plain request from every\nvisit after the first. Upgrade Insecure Requests, a Content Security Policy\ndirective, is the other neighbour: it upgrades the requests a page makes for its\nown scripts and images, and leaves a visitor who arrives from someone else's\n`http://` link to the redirect.\n\n## Why it matters\n\nTurning HSTS on costs one line of configuration. The real decision is how far to\ntake it, because each step protects more visitors and is harder to take back.\n\nThe header alone leaves a gap that RFC 6797 names itself. A browser that has\nnever seen the site, or whose remembered policy has expired, still starts with a\nplain request. A long `max-age` shrinks the second half of that gap, which is\nwhy a year is the common setting. The first half closes only through the preload\nlist: host names compiled into Chrome, with Firefox, Safari and Edge keeping\nlists based on it, so that a browser fresh from the installer already knows to\nuse HTTPS.\n\nThe list asks a great deal. The base domain needs a valid certificate, a\nredirect from HTTP to HTTPS that stays on the same host, every subdomain served\nover HTTPS, and a header with a `max-age` of at least 31536000 seconds,\n`includeSubDomains` and `preload`. Its maintainers say plainly that this covers\ninternal subdomains the public never sees. Leaving is the part that settles the\nquestion: a removal takes months to reach users through Chrome updates, the\nother browsers come with no guarantee, and the site describes removal as “slow\nand painful”.\n\nSo the choice runs up a ladder, one rung at a time:\n\n- **The header without `includeSubDomains`** suits almost any site that already\n  serves HTTPS. RFC 9325, the current best practice for TLS, says web servers\n  should send it.\n- **Adding `includeSubDomains`** is safe once someone has listed every name\n  under the domain and confirmed that each one answers on HTTPS, including the\n  ones a vendor or another department runs.\n- **Preloading** fits a domain whose owners are certain no name under it will\n  need plain HTTP again: a login domain, a payments domain, a company that\n  controls all of its own DNS. A marketing domain where a campaign tool may soon\n  ask for a CNAME is a poor candidate, and so is any domain shared with office\n  equipment.\n\nThe list's maintainers also give the pace for the climb: `max-age` at 300\nseconds, then a week, then a month, each with `includeSubDomains`, waiting out\nthe full age of one stage before starting the next. A browser keeps whichever\nvalue it saw last, so a mistake made at the five-minute rung costs five minutes.\n\n## What it looks like in practice\n\nOn one platform holding professional and organizational data, the company\nworked as Security Engineer and hardened every layer, and HSTS was one of them.\n[In the Next.js proxy middleware, `proxy.ts`, the response carries HSTS](/portfolio/hardened-the-application-with-nonce-based-csp/)\nalongside a Content Security Policy with a fresh nonce on every request and\n`strict-dynamic`, and SameSite cookies. A proxy middleware runs in front of the\nroutes it matches, which keeps the browser-facing rules in one file rather than\nspread across pages.\n\nThe same piece of work shows where HSTS stops. Its working assumption was that\nthe client is hostile: anything the browser enforces can be switched off by\nwhoever is holding the browser. HSTS protects an honest visitor from a hostile\nnetwork. It does nothing about a hostile client, which is why the work went on\nbelow it. The API added rate limiting, CORS, request-size limits, input\nvalidation before anything reached the database, and logging of\nsecurity-relevant events. The API connected to the database as a role that\ncould only execute the application's functions, and entitlements were checked\nagain on the server on every request, with the frontend's gates treated as user\nexperience only. In that stack HSTS keeps the traffic itself out of reach, and\nit is the cheapest layer to add.\n\n## Where it goes wrong\n\n**The header is in the configuration and browsers behave as though it were\nabsent.** It is being sent on the plain HTTP response, usually the redirect, or\non an HTTPS response whose certificate the browser rejected. RFC 6797 tells\nbrowsers to ignore it in both cases and tells servers to leave it off plain\nresponses altogether. A related slip sends `example.com` straight to\n`https://www.example.com` with the header only on `www`, which leaves the base\ndomain and its other names uncovered. Put the header on every HTTPS response,\nredirects included, and check both doors:\n\n```sh\ncurl -sI https://example.com/ | grep -i strict-transport-security\ncurl -sI http://example.com/ | grep -i strict-transport-security\n```\n\nThe first line should print the header. The second belongs to the redirect and\nshould print nothing at all.\n\n**An old service under the domain stops loading for everyone who has visited the\nmain site.** `includeSubDomains` on the base domain covers every name beneath it:\na status page hosted by a vendor, a printer's admin page, an intranet tool that\nnever had a certificate. Those visitors get a connection error with no way past\nit, while colleagues who never opened the main site reach the service without\ntrouble, so the reports are hard to reproduce. The directive went out before\nanyone made the list. Make it first, from the DNS zone and from certificate\ntransparency logs, which record every name a public certificate was issued for.\nMove each name to HTTPS or to a different domain, then add the directive at a\nshort `max-age`.\n\n**A warning that staff used to click through becomes a wall.** Staging on a\nself-signed certificate, an internal certificate authority that visitors'\nlaptops do not trust, a certificate that lapsed over a weekend: before HSTS each\nof these was a warning page with a way past it, and afterwards the browser\noffers none. RFC 9325 names self-signed certificates as a case where HSTS can\nleave security worse off. Give staging a publicly trusted certificate or a\ndomain the policy does not reach, and treat certificate renewal as something\nthat now takes the site down when it fails, with no choice left to the visitor.\n\n**A preloaded domain needs plain HTTP back.** A device that speaks only HTTP, a\nvendor whose custom-domain feature serves no certificate, an acquisition that\nbrings its own hosts under the name. The entry already sits inside browsers that\nhave shipped, and the server can do little about it: a removal request reaches\nusers only as their browsers update. Put the new name under a different domain,\nand preload only after a long run at a one-year `max-age` with\n`includeSubDomains` has raised no tickets.\n\n## Further reading\n\n- [RFC 6797: HTTP Strict Transport Security (HSTS)](https://www.rfc-editor.org/rfc/rfc6797)\n  — the header, its two directives, and exactly when a browser must honour it\n  or ignore it.\n- [HSTS Preload List Submission](https://hstspreload.org/) — the conditions for\n  being listed, the staged rollout the maintainers advise, and what leaving\n  costs.\n- [RFC 9325, section 3.2](https://www.rfc-editor.org/rfc/rfc9325#section-3.2) —\n  the current best practice for TLS on HSTS: clients and servers must support\n  it, and servers should send it.\n- [Upgrade Insecure Requests](https://www.w3.org/TR/upgrade-insecure-requests/)\n  — the W3C directive that upgrades a page's own requests, and how it divides\n  the work with HSTS.\n\n\u003chttps://engineer.company/glossary/hsts/\u003e\n","date_modified":"2026-10-20T21:59:50Z","description":"How HSTS closes the plain-HTTP gap a redirect leaves open, when includeSubDomains is safe, and why joining the preload list is a decision measured in months.","formats":{"gemtext":"https://engineer.company/glossary/hsts/index.gmi","gopher":"https://engineer.company/glossary/hsts/gophermap","html":"https://engineer.company/glossary/hsts/","json":"https://engineer.company/glossary/hsts/index.json","markdown":"https://engineer.company/glossary/hsts/index.md","pdf":"https://engineer.company/glossary/hsts/index.pdf"},"kind":"page","language":"en","title":"What is HSTS?","url":"https://engineer.company/glossary/hsts/","version":1}