feature: the router has a two-level CA with an optional offline root, issuing CAs for P2S, site-to-site and general use, templates, published certificates and CRLs and an ACME server, site-to-site connections authenticate with certificates, and setup installs Caddy from Ubuntu or Caddy's repository.
Release / release (push) Successful in 13s

This commit is contained in:
slawek committed 2026-10-25 22:05:39 +01:00
1 parent fe45272f7c
commit 8d3469d10a
37 files changed
+2499 -921

No files matched your search

+163 -29
View File
@@ -121,25 +121,30 @@ and it is backed up with `slapcat`, not by copying files.
Status: Accepted
Context: The router CA issues client certificates for IKEv2. OpenVPN can check a certificate, a
password, or both. With both, a certificate alone and a password alone are not enough, but
`openvpn-auth-ldap` checks only the password of the user name given at login, which need not be
the user of the certificate.
Context: The P2S issuing CA (ADR-27) issues the users' client certificates, for IKEv2 and
OpenVPN. OpenVPN can check a certificate, a password, or both. With both, a certificate alone and
a password alone are not enough, but `openvpn-auth-ldap` checks only the password of the user name
given at login, which need not be the user of the certificate. OpenVPN trusts every chain to a
CA of its `ca` file and has no option that accepts one intermediate CA only, while the root also
signs the site-to-site and the general-purpose CAs.
Decision: OpenVPN checks the certificate against the CA and the CRL, the password with
`openvpn-auth-ldap`, and runs `openvpn-same-user` as `auth-user-pass-verify` with `via-env`,
which accepts the login only when the user name equals the certificate's common name. OpenVPN
calls both and needs both to pass. A user's certificate has the user name as its common name, is
issued when the user is added and revoked when the user is removed. The CRL is created with the
CA, so that `crl-verify` has a file from the start, and is valid for ten years, because the router
renews it only when it revokes a certificate. The server uses the router's own certificate, whose
common name is `wan.local_fqdn`; the client profile checks that name (`verify-x509-name`), since
the CA's certificates carry both the server and the client purpose.
Decision: OpenVPN checks the certificate against the root and the P2S CA and their CRLs, which
it needs for every CA of the chain, the password with `openvpn-auth-ldap`, and runs
`openvpn-same-user` as `auth-user-pass-verify` with `via-env`, which accepts the login only when
the user name equals the certificate's common name. `openvpn-issuer`, as `tls-verify`, accepts
the certificate at depth 1 only when its SHA-256 fingerprint, which OpenVPN gives the script,
is the P2S CA's. OpenVPN calls all of them and needs all to pass. A user's certificate has the
user name as its common name, is issued with the template `vpn-user`, client authentication
only, when the user is added, and revoked when the user is removed. The server uses the router's
VPN server certificate, whose common name is `wan.local_fqdn`; the client profile checks that
name (`verify-x509-name`).
Consequences: Disabling a user locks the password, which stops OpenVPN but not IKEv2, which
checks certificates only; removing a user revokes the certificate for both. A user's
certificate expires after the CA's default of a year and is renewed by removing and adding the
user again.
checks certificates only; removing a user revokes the certificate for both. A certificate of
another issuing CA with a user's name does not reach the password check. A user's certificate
expires after the days of `vpn-user` and is renewed by removing and adding the user again. An
expired root CRL stops every OpenVPN client, so an offline root needs its CRL renewed in time
(ADR-28).
## ADR-6: The web service and vpn-router-user share one module for users
@@ -147,9 +152,9 @@ Status: Accepted
Context: Users are managed from the command line, by an operator at a terminal, and through
`/users` of the web service, by the Router Manager. Both must apply the same rules to names,
passwords and person attributes, and both change the directory and the CA. `simple-ca` keeps
the CA's state in one file, so two changes must not run at the same time. The web unit is
sandboxed with `ProtectSystem=strict`.
passwords and person attributes, and both change the directory and the PKI, whose state is one
file, so two changes must not run at the same time. The web unit is sandboxed with
`ProtectSystem=strict`.
Decision: `vpnrouter_users.py` holds the user operations, the checks and a session that takes a
lock and the connection of the user manager account. The web service imports it and maps a
@@ -157,11 +162,14 @@ lock and the connection of the user manager account. The web service imports it
the output, text for people and JSON with `--json`. The web unit allows writing the paths the
operations need: `/run/vpn-router` for the lock, its `RuntimeDirectory`, which systemd creates
before the service starts, also before setup has run, and keeps when it stops, as setup's state
files are there too; `/etc/vpn-router/pki` for the certificates and the CA's state, and
`/etc/swanctl/x509crl` for the published CRL.
files are there too; `/etc/vpn-router/pki` for the certificates and the PKI's state, and
`/etc/swanctl/x509crl`, `/etc/openvpn/server` and `/var/lib/vpn-router/pki-publish` for the
CRLs a revocation signs. The PKI module, `vpnrouter_pki.py`, works the same way for `/ca`,
`vpn-router-ca` and `vpn-router-setup`, and its lock is the users' lock, as adding and removing
a user issue and revoke a certificate.
Consequences: The rules exist once. A request starts no process, and a password never leaves
the process that received it. The web service imports `python3-ldap` and the package's
Consequences: The rules exist once. A request starts no process but `swanctl --load-creds` after
a revocation, and a password never leaves the process that received it. The web service imports `python3-ldap` and the package's
configuration module. The API is protected by the tokens of ADR-3, so only members of `admins`
and the holders of an admin token manage users.
@@ -245,12 +253,13 @@ Context: Users are prepared before a P2S system is switched on, and the Router M
them on any configured router, with or without one.
Decision: Once a platform is chosen, `vpn-router-setup` always provisions the user directory in
slapd and the CA with its CRL; the server certificate follows once `wan.local_fqdn` is set.
`/users` and `vpn-router-user` rely only on the directory and the CA. Only the OpenVPN client
profile needs OpenVPN to be enabled.
slapd and the PKI (ADR-27) with its CRLs; the router's certificates follow once `wan.local_fqdn`
is set. `/users` and `vpn-router-user` rely only on the directory and the P2S CA. Only the
OpenVPN client profile needs OpenVPN to be enabled.
Consequences: slapd always holds the directory and the CA always exists on a configured router,
even when no P2S system uses them. An operator who wants a CA of their own must place it before
Consequences: slapd always holds the directory and the CAs exist on a configured router, even
when no P2S system uses them; with an offline root the P2S CA, and so the users' certificates,
wait for its certificate. An operator who wants a root CA of their own must place it before
choosing the platform.
## ADR-11: Groups are groupOfNames entries that never become empty
@@ -721,9 +730,134 @@ state in one directory and then archives or sends it.
it stops their services, keeps what it replaces and lets `vpn-router-setup` rebuild the rest.
The API offers no restore, so a stolen admin session cannot replace the router's keys.
Consequences: A backup holds every secret of the router, including the CA key, in plain form
Consequences: A backup holds every secret of the router, including the keys of the issuing CAs
and the root key while it is on the router, in plain form
unless a PBS key file encrypts it, so where it is kept must be as safe as the router. A restore
onto another VM brings back the old interface names and addresses, which may need changing. The
timer's schedules are systemd's shorthands, so all backups of one schedule start at the same
moment. A change of the users between the end of the copy and the next backup is in no backup
until then.
## ADR-27: A two-level CA with dedicated issuing CAs, whose root may be offline
Status: Accepted
Context: One self-signed CA signed every certificate of the router with the same server and
client purposes, so a certificate for any use was also a VPN client certificate, and the key
that signed everything had to stay on the router. The router needs CAs for the VPN clients, for
site-to-site certificates and for the administrator's own uses, and a root whose key can be kept
elsewhere. The `simple-ca` script handled one level and ran as a separate process with its own
state file.
Decision: The root signs only issuing CAs, path length 1; the issuing CAs, path length 0, sign
the certificates. `p2s` signs the router's VPN server certificate and the users' certificates,
`s2s` the site-to-site certificates, and the CAs of `pki.issuing_cas` what their templates
allow. A template fixes the key, the lifetime, the key usages, the extended key usages, the kind
of common name and the subject alternative names a certificate may have; `vpn-server` and
`vpn-user` are issued by the router only, so no certificate for another use comes from the P2S
CA. The module `vpnrouter_pki.py`, with `python3-cryptography` from the Ubuntu archive, builds
the keys, certificates, CSRs and CRLs in the processes that need them, as the user module does
(ADR-6); the settings are the `pki` section of `vpn-router.json` and the state is
`pki/state.json`. Keeping the root key off the router is recommended, not required: while it is
on the router a new issuing CA is signed at once, and while it is not the CA gets its key and a
CSR, signed offline and imported with `vpn-router-ca` or `/ca`. The root key itself crosses
neither the API nor the Manager. For a certificate of something other than the router, the router
signs the requester's CSR, or makes the key and returns it once in a PKCS#12 file, keeping only
the certificate, so a key it gave away cannot leak from it later. The PKCS#12 file uses 3DES and
SHA-1 MACs, the encryption the key stores of Windows and macOS import. strongSwan reads only the
first certificate of a PEM file, so each CA has a file of its own in `/etc/swanctl/x509ca`;
road-warrior and site-to-site name their CA in `cacerts`, which restricts the trust chain to it.
Consequences: The P2S CA's certificates are accepted by road-warrior and OpenVPN only, the site-to-site CA's by
site-to-site only. With an offline root, new issuing CAs and the root CRL need the offline step,
and a router whose P2S CA waits has no VPN server certificate and so no P2S access. The router
keeps the users' keys, as the OpenVPN profile embeds them.
## ADR-28: CA certificates and CRLs are published at configurable endpoints, and CRLs are short-lived
Status: Accepted
Context: Clients outside the router, such as Windows and servers using the general-purpose CAs,
find the issuer's certificate and the CRL through the AIA and CRL distribution point extensions,
and cache a CRL until its next update. The router's CRLs were valid for ten years and published
nowhere. Caddy serves files itself, and the web service already answers on the status port.
Decision: `pki.publish` lists the endpoints, in the order the URLs appear in the certificates:
plain HTTP on the status port, served by the web service; plain HTTP on port 80, HTTPS on the
status HTTPS port and HTTPS on port 443, served by Caddy's `file_server`. The files are DER, as
RFC 5280 asks of these URLs, copied to `/var/lib/vpn-router/pki-publish`, outside the 0700 PKI
directory, so that Caddy's user reads them. Ports 80 and 443 serve only the CA files and are opened
on both interfaces when chosen. The CRLs of the issuing CAs are valid for `pki.crl_days`, a week
by default, signed again at every revocation and by a daily timer once half their validity has
passed; the root CRL has its own `pki.root_crl_days`, half a year by default, so an offline root
needs its CRL signed twice a year, not weekly.
Consequences: A client that caches a CRL sees a revocation within a week. The URLs are fixed in a
certificate when it is signed, so a change of the endpoints or of `wan.local_fqdn` applies to
certificates signed afterwards. HTTPS URLs are offered for clients that cannot use plain HTTP,
although a client checking the revocation of the HTTPS server's own certificate cannot use them;
Caddy's certificate is Let's Encrypt's, so the router's endpoints do not depend on themselves.
## ADR-29: Site-to-site connections authenticate with a pre-shared key or certificates
Status: Accepted
Context: Site-to-site connections used pre-shared keys only. Peers that are routers of this
package, or have a PKI of their own, can authenticate with certificates, which leaves no shared
secret to distribute. Azure's VPN gateway authenticates site-to-site connections with pre-shared
keys only.
Decision: A connection's `auth` is `psk`, the default, or `certificate`. With `certificate` the
router presents one site-to-site certificate of its `s2s` CA, whose names are `wan.local_fqdn`,
the public address and the internal address, so it fits every `local_id_mode`; the peer's
certificate must name the connection's `id` and be issued by the router's `s2s` CA or, when the
connection has `remote_ca`, by that CA, its PEM certificate kept in the connection and copied to
`/etc/swanctl/x509ca/s2s-<name>.pem`. A peer without a PKI gets its certificate from the router.
Consequences: The connection Azure's gateway needs stays `psk`, so the platform writes nothing
new. The router's site-to-site certificate is issued again when an address it names changes. The
router does not check a remote CA's revocations unless strongSwan can fetch the CRL its
certificates name.
## ADR-30: A general-purpose issuing CA can back an ACME server of Caddy
Status: Accepted
Context: Servers that use a general-purpose CA need their certificates renewed, which ACME clients
automate. Caddy, which the router runs for HTTPS, has an ACME server built on a CA of its `pki`
app. Caddy 2.6.2 of the Ubuntu archive needs the key file of that CA's root, never renews an
intermediate given to it, keeps no CRL and takes only the CA in the `acme_server` directive,
issuing certificates valid for 12 hours. Its ACME handler answers every path under `/acme/`.
Decision: An issuing CA of `pki.issuing_cas` with `acme` makes Caddy serve an ACME server for it
at `/acme/<name>/` of the HTTPS status port, each in a `handle` block of its own. The issuing CA's
certificate and key are given to Caddy as both the root and the intermediate of a `pki` CA, copied
to `/etc/caddy/vpn-router-pki/<name>/` for Caddy's group, so that the router's root key never
reaches Caddy and may be offline.
Consequences: The certificates Caddy issues chain to the router's root through the issuing CA, are
not in the router's inventory, follow no template and are not revoked; their short lifetime takes
the place of revocation. An issuing CA waiting for the offline root has no ACME server.
## ADR-31: vpn-router-setup installs Caddy from the Ubuntu archive or from Caddy's repository
Status: Accepted
Context: Caddy 2.6.2 of the Ubuntu archive lacks later features, such as a pki root without its key
and the settings of the ACME server. Caddy's own repository has current versions of the package of
the same name. A dependency on `caddy` installs the archive's package with `vpn-router`. apt cannot
run inside `vpn-router-setup` when the package's installation runs setup, as dpkg holds its lock.
Decision: `vpn-router` only suggests `caddy`. While HTTPS is on, setup has
`vpn-router-caddy.service` install it from `https.caddy_source`: `ubuntu`, or `upstream`, for
which the unit writes the deb822 source and the key it downloads over HTTPS from Caddy's
repository. The unit waits for dpkg's lock and runs setup again when Caddy is in place.
`vpn-router-caddy use-upstream` switches an installed router. Upstream's versions sort above the
archive's, so once the repository is configured apt keeps upstream's Caddy without a pin, and
`ubuntu` has no effect; nothing downgrades Caddy on its own, as a downgrade may break the
configuration and is the administrator's decision. Only the CLI switches the source; the Router
Manager shows which one is in effect.
Consequences: The first setup run with HTTPS starts the installation and serves HTTPS on the run
that follows it. The key of Caddy's repository is trusted as downloaded over HTTPS, the way Caddy's
installation instructions do it. Going back to the archive's Caddy is a manual downgrade.