Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,8 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version
and renews on its own from Let's Encrypt or ZeroSSL (or any ACME authority), proving the domain over HTTP, TLS-ALPN
or DNS, with Cloudflare, Route 53 and the other caddy-dns providers, so wildcards and machines the internet can't
reach work too. Set it up in **Settings › HTTPS**, whose **Open the HTTPS ports** has the machine open 443 and 80
and restart Lens (or run the install line with `LENS_HTTPS=1`). Off by default ([HTTPS](docs/https.md)).
and restart Lens (or run the install line with `LENS_HTTPS=1`). It can answer only for its own domains (strict SNI)
and require client certificates (mutual TLS). Off by default ([HTTPS](docs/https.md)).

- **Budget meter and Costs page.** The top bar shows what the namespace picked spent against its budget, used and
left, highlighted when near or over, and follows the namespace switcher; it opens the details for a day, week or
Expand Down
15 changes: 15 additions & 0 deletions docs/https.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,20 @@ it (on the LAN, say). Pick the provider and give what it asks for:
Any other [caddy-dns](https://github.com/caddy-dns) plugin works too: its name as the provider (like `hetzner`), and
its fields as JSON. `dns_package` names a plugin outside caddy-dns (`github.com/<owner>/<repo>`).

## Who gets in

Off by default, in Settings › HTTPS › Who gets in:

- **Answer only for these domains** (`strict_sni`): a TLS handshake happens only for the domains listed. A
connection to the machine's IP address, to another name pointed at it, or with no name at all (SNI) is refused,
and a request must name in `Host` the domain its connection was made for (else 421 Misdirected Request), so a
scanner learns nothing and one domain can't be reached through another's connection.
- **Client certificates** (`client_auth`, `client_ca`): `optional` checks a certificate when the browser offers one;
`required` is mutual TLS, where only browsers and devices holding a certificate signed by the CA you paste (PEM,
one or more) get a connection at all, before any page or sign-in. Keep the web app's own port to this machine
(`LENS_PUBLIC=0`) so HTTPS is the only way in from elsewhere.
- **Oldest TLS version** (`min_tls`): 1.2 (default) or 1.3.

## Certificate authorities

| `ca` | |
Expand All @@ -79,6 +93,7 @@ All in Settings › HTTPS (`PUT /api/v1/settings/https`; `POST /api/v1/settings/
| `redirect_http` | `true` | send http:// to https:// |
| `hsts` | `false` | tell browsers to use https:// only, for a year. Turn it on once HTTPS works: turning HTTPS off later leaves browsers unable to reach the http:// address |
| `origin` | | the web app, as the worker reaches it (`LENS_HTTPS_ORIGIN`, else `LENS_TUNNEL_ORIGIN`: `http://frontend:3000` in Docker) |
| `strict_sni`, `client_auth`, `client_ca`, `min_tls` | off, `off`, `""`, `1.2` | see Who gets in |
| `https_port`, `http_port` | `8443`, `8080` | where Caddy listens in the container (install.sh publishes 443 and 80 to them) |

## How it runs
Expand Down
53 changes: 46 additions & 7 deletions fastapi_backend/app/domain/https.py
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
import urllib.parse

import httpx
from cryptography.hazmat.primitives import serialization

from . import store

Expand Down Expand Up @@ -256,13 +257,36 @@ def check(cfg):
raise ValueError(f"https.{k} is a port number")
if t.get("https_port") and t.get("https_port") == t.get("http_port"):
raise ValueError("the HTTPS and HTTP ports are different ports")
if (t.get("client_auth") or "off") != "off":
client_cas(t.get("client_ca") or "")
elif t.get("client_ca"):
client_cas(t["client_ca"])
o = urllib.parse.urlsplit(origin(cfg))
if o.scheme != "http" or not o.hostname:
raise ValueError("the web app's address for HTTPS is an http:// address, like http://frontend:3000")
if t.get("enabled") and not names:
raise ValueError("enter the domain name Lens is reached at, like lens.example.com")


def client_cas(pem):
"""The CA certificates in PEM text, as base64 DER for Caddy. ValueError when there's none or one doesn't parse."""
import base64

from cryptography import x509

blocks = re.findall(r"-----BEGIN CERTIFICATE-----[^-]+-----END CERTIFICATE-----", pem or "")
if not blocks:
raise ValueError("paste the PEM of the CA that signs client certificates (-----BEGIN CERTIFICATE-----)")
out = []
for b in blocks:
try:
c = x509.load_pem_x509_certificate(b.encode())
except ValueError:
raise ValueError("a client CA certificate doesn't parse; paste it as PEM") from None
out.append(base64.b64encode(c.public_bytes(serialization.Encoding.DER)).decode())
return out


# ---------- Caddy's configuration ----------
def _issuers(cfg):
t = conf(cfg)
Expand Down Expand Up @@ -312,14 +336,29 @@ def caddy_config(cfg, storage):
if t.get("hsts"):
handle.append({"handler": "headers", "response": {"set": {"Strict-Transport-Security": ["max-age=31536000"]}}})
handle.append({"handler": "reverse_proxy", "upstreams": [{"dial": upstream}]})
servers: dict = {
"lens": {
"listen": [f":{https_port}"],
"routes": [{"match": [{"host": names}], "handle": handle, "terminal": True}],
# its own redirect below: Caddy's would send people to the port inside the container
"automatic_https": {"disable_redirects": True},
}
routes: list[dict] = [{"match": [{"host": names}], "handle": handle, "terminal": True}]
lens: dict = {
"listen": [f":{https_port}"],
"routes": routes,
# its own redirect below: Caddy's would send people to the port inside the container
"automatic_https": {"disable_redirects": True},
}
policy: dict = {}
if t.get("strict_sni"):
policy["match"] = {"sni": names} # no other name, and no SNI at all, gets a handshake
lens["strict_sni_host"] = True # the Host a request names is the name its connection was made for
routes.append({"handle": [{"handler": "static_response", "status_code": 421}]})
mode = {"optional": "verify_if_given", "required": "require_and_verify"}.get(t.get("client_auth") or "off")
if mode:
policy["client_authentication"] = {
"ca": {"provider": "inline", "trusted_ca_certs": client_cas(t.get("client_ca") or "")},
"mode": mode,
}
if t.get("min_tls") == "1.3":
policy["protocol_min"] = "tls1.3"
if policy:
lens["tls_connection_policies"] = [policy]
servers: dict = {"lens": lens}
if t.get("redirect_http", True):
port = public_port()
target = "https://{http.request.host}" + ("" if port == 443 else f":{port}") + "{http.request.uri}"
Expand Down
2 changes: 2 additions & 0 deletions fastapi_backend/app/domain/settings.py
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,8 @@
("tunnel", "mode"): {"off", "quick", "token", "managed"},
("https", "ca"): {"letsencrypt", "zerossl", "both", "custom"},
("https", "challenge"): {"http", "tls-alpn", "dns"},
("https", "client_auth"): {"off", "optional", "required"},
("https", "min_tls"): {"1.2", "1.3"},
("files", "store"): {"local", "connection"},
("documents", "converter"): {"auto", "anytopdf", "lens"},
("logs", "level"): set(logs.LEVELS),
Expand Down
7 changes: 7 additions & 0 deletions fastapi_backend/app/domain/store.py
Original file line number Diff line number Diff line change
Expand Up @@ -600,6 +600,13 @@ def labels():
"origin": "",
"https_port": 8443,
"http_port": 8080,
# strict_sni: only the domains get a TLS handshake (no SNI, an IP or another name is refused), and a request's
# Host must match its SNI (else 421). client_auth: off, optional (a certificate, when given, must be from
# client_ca) or required (mutual TLS); client_ca: PEM of the CAs that sign client certificates. min_tls: 1.2 or 1.3
"strict_sni": False,
"client_auth": "off",
"client_ca": "",
"min_tls": "1.2",
},
"notifications": {"enabled": True, "networks": [], "poll_seconds": 5, "max_attempts": 6, "app_url": None},
# OpenTelemetry traces and metrics (docs/telemetry.md): off unless an admin turns it on, and sent only to the OTLP/HTTP
Expand Down
48 changes: 48 additions & 0 deletions fastapi_backend/tests/api/test_https.py
Original file line number Diff line number Diff line change
Expand Up @@ -350,3 +350,51 @@ def run(request):
assert ran == "ref=main https=0"
ran, _ = run("id=a3\nref=\nhttps=yes; rm -rf /\n") # nothing but 0 or 1
assert ran == "ref=main https=0"


def _ca_pem():
from cryptography import x509
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import ec

key = ec.generate_private_key(ec.SECP256R1())
name = x509.Name([x509.NameAttribute(x509.NameOID.COMMON_NAME, "Family CA")])
now = dt.datetime.now(dt.UTC)
cert = (
x509.CertificateBuilder()
.subject_name(name)
.issuer_name(name)
.public_key(key.public_key())
.serial_number(1)
.not_valid_before(now)
.not_valid_after(now + dt.timedelta(days=30))
.sign(key, hashes.SHA256())
)
return cert.public_bytes(serialization.Encoding.PEM).decode()


def test_strict_sni_client_certificates_and_tls_13(client, db, cfg):
cfg["https"] = {**cfg["https"], "enabled": True, "domains": ["lens.example.com"], "origin": "http://frontend:3000"}
lens = https.caddy_config(cfg, "/s")["apps"]["http"]["servers"]["lens"]
assert "tls_connection_policies" not in lens and "strict_sni_host" not in lens # off by default: Caddy's own
pem = _ca_pem()
cfg["https"].update(strict_sni=True, client_auth="required", client_ca=pem, min_tls="1.3")
https.check(cfg)
lens = https.caddy_config(cfg, "/s")["apps"]["http"]["servers"]["lens"]
[policy] = lens["tls_connection_policies"]
assert policy["match"] == {"sni": ["lens.example.com"]} and policy["protocol_min"] == "tls1.3"
assert policy["client_authentication"]["mode"] == "require_and_verify"
assert policy["client_authentication"]["ca"]["trusted_ca_certs"] == https.client_cas(pem)
assert lens["strict_sni_host"] is True and lens["routes"][-1]["handle"][0]["status_code"] == 421
cfg["https"]["client_auth"] = "optional"
assert https.caddy_config(cfg, "/s")["apps"]["http"]["servers"]["lens"]["tls_connection_policies"][0]["client_authentication"][
"mode"
] == ("verify_if_given")
# set up in the app: a client CA that isn't one is refused
cfg["https"] = {**cfg["https"], "enabled": False, "client_auth": "off", "client_ca": "", "strict_sni": False}
make_user(db, "root@x.io", "root password 1", admin=True)
a = login(client, "root@x.io", "root password 1")
for bad in ({"client_auth": "required"}, {"client_ca": "not a certificate"}, {"min_tls": "1.0"}, {"client_auth": "always"}):
assert client.put("/api/v1/settings/https", headers=a, json=bad).status_code == 400, bad
r = client.put("/api/v1/settings/https", headers=a, json={"strict_sni": True, "client_auth": "required", "client_ca": pem})
assert r.status_code == 200, r.text
20 changes: 20 additions & 0 deletions nextjs-frontend/__tests__/httpsSettings.test.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,10 @@ const OFF = {
origin: "",
https_port: 8443,
http_port: 8080,
strict_sni: false,
client_auth: "off",
client_ca: "",
min_tls: "1.2",
};

function show(values: Record<string, unknown>) {
Expand Down Expand Up @@ -139,6 +143,22 @@ describe("Settings › HTTPS", () => {
});
});

it("requires client certificates signed by a CA you paste", async () => {
(Admin.httpsStatus as jest.Mock).mockImplementation(() => ok({ ...STATUS, enabled: false }));
show(OFF);
expect(await screen.findByText("Off.")).toBeInTheDocument();
expect(screen.queryByLabelText("CA that signs client certificates")).not.toBeInTheDocument();
fireEvent.change(screen.getByLabelText("Client certificates"), { target: { value: "required" } });
const pem = "-----BEGIN CERTIFICATE-----\nMIIB\n-----END CERTIFICATE-----";
fireEvent.change(screen.getByLabelText("CA that signs client certificates"), { target: { value: pem } });
fireEvent.click(screen.getByRole("button", { name: "Save" }));
await waitFor(() => expect(Admin.updateSettings).toHaveBeenCalledTimes(1));
expect((Admin.updateSettings as jest.Mock).mock.calls[0][0]).toMatchObject({
body: { client_auth: "required", client_ca: pem },
});
expect(crossErrors({ "https.client_auth": "required", "https.client_ca": "" })["https.client_ca"]).toMatch(/PEM/);
});

it("checks the domains, the email and the authority's address", () => {
expect(crossErrors({ "https.domains": ["not a domain"] })["https.domains"]).toMatch(/domain/);
expect(crossErrors({ "https.domains": ["*.example.com"], "https.challenge": "http" })["https.domains"]).toMatch(
Expand Down
34 changes: 33 additions & 1 deletion nextjs-frontend/components/settings/bodies.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ import {
} from "@/components/settings/model";
import { Banner } from "@/components/ui/banner";
import { Button } from "@/components/ui/button";
import { Field, Input, Select, Switch } from "@/components/ui/field";
import { Field, Input, Select, Switch, Textarea } from "@/components/ui/field";
import { Skeleton } from "@/components/ui/states";
import { data, useApiClient } from "@/lib/api/browser";
import { useArchive } from "@/lib/hooks/session";
Expand Down Expand Up @@ -1443,6 +1443,8 @@ function HttpsBody({ ctx }: { ctx: BodyCtx }) {
const provider = ctx.state("https.dns_provider");
const creds = ctx.state("https.dns_credentials");
const eab = ctx.state("https.eab_hmac_key");
const clientCa = ctx.state("https.client_ca");
const clientAuth = (ctx.state("https.client_auth").value as string | undefined) ?? "off";
const [fields, setFields] = useState<Record<string, string>>({});
const [other, setOther] = useState(false);
const status = useQuery({
Expand Down Expand Up @@ -1581,6 +1583,36 @@ function HttpsBody({ ctx }: { ctx: BodyCtx }) {
</p>
</>
)}
<Sub>Who gets in</Sub>
<F ctx={ctx} id="https.strict_sni" />
<F ctx={ctx} id="https.client_auth" />
{clientAuth !== "off" && (
<Field
label="CA that signs client certificates"
error={ctx.state("https.client_ca").error}
hint="PEM, one certificate or more. Only browsers and devices with a certificate it signed get in."
>
{({ id, describedBy, invalid }) => (
<Textarea
id={id}
aria-describedby={describedBy}
invalid={invalid}
rows={5}
className="font-mono text-[12px]"
placeholder="-----BEGIN CERTIFICATE-----"
value={(clientCa.value as string | undefined) ?? ""}
onChange={(e) => clientCa.onChange(e.target.value)}
/>
)}
</Field>
)}
{clientAuth === "required" && (
<p className="text-[12.5px] leading-[1.45] text-fg-muted">
The web app’s own port (3000) doesn’t ask for a certificate: keep it to this machine (install with
LENS_PUBLIC=0) so the only way in from elsewhere is HTTPS.
</p>
)}
<F ctx={ctx} id="https.min_tls" />
<details className="text-[13px]">
<summary className="cursor-pointer font-semibold text-fg-secondary">More options</summary>
<div className="mt-3 flex flex-col gap-4">
Expand Down
37 changes: 37 additions & 0 deletions nextjs-frontend/components/settings/model.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1135,6 +1135,35 @@ export const FIELDS: FieldSpec[] = [
placeholder: "as installed",
hint: "Where Caddy reaches the web app from the server. Leave empty unless you moved it.",
},
{
section: "https",
key: "strict_sni",
label: "Answer only for these domains",
kind: "switch",
hint: "Connections to another name, an IP address or no name at all are refused, and a request must name the domain its connection was made for.",
},
{
section: "https",
key: "client_auth",
label: "Client certificates",
kind: "select",
options: [
{ value: "off", label: "Not asked for" },
{ value: "optional", label: "Checked when a browser offers one" },
{ value: "required", label: "Required (mutual TLS)" },
],
},
{ section: "https", key: "client_ca", label: "CA that signs client certificates", kind: "text" },
{
section: "https",
key: "min_tls",
label: "Oldest TLS version",
kind: "select",
options: [
{ value: "1.2", label: "TLS 1.2" },
{ value: "1.3", label: "TLS 1.3" },
],
},
{ section: "https", key: "https_port", label: "HTTPS port in the container", kind: "int", min: 1, max: 65535 },
{ section: "https", key: "http_port", label: "HTTP port in the container", kind: "int", min: 1, max: 65535 },
// Chat rooms (Matterbridge)
Expand Down Expand Up @@ -3374,6 +3403,14 @@ export function crossErrors(values: Record<string, unknown>): Record<string, str
e["https.dns_provider"] = "Choose the DNS provider that holds the domain";
const prop = values["https.propagation"] as string | undefined;
if (prop && !/^\d+(ms|s|m|h)$/.test(prop)) e["https.propagation"] = "A duration, like 2m";
const clientCa = values["https.client_ca"] as string | undefined;
if (
values["https.client_auth"] &&
values["https.client_auth"] !== "off" &&
"https.client_ca" in values &&
!/-----BEGIN CERTIFICATE-----/.test(clientCa ?? "")
)
e["https.client_ca"] = "Paste the PEM of the CA that signs client certificates";
const hOrigin = values["https.origin"] as string | undefined;
if (hOrigin && !/^http:\/\/[^/\s]+/.test(hOrigin))
e["https.origin"] = "Use an http:// address, such as http://frontend:3000";
Expand Down
Loading