Skip to content
Open
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
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,11 @@ just check
Then send a test mail to [mail-tester.com](https://www.mail-tester.com) and
run [internet.nl](https://internet.nl/test-mail/) against your domain.

Then go through [docs/operator-security.md](docs/operator-security.md):
two-factor authentication on the provider, registrar, DNS and GitHub
accounts, and protecting the keys on your own machine. Those accounts are
the real perimeter.

**Back up your age key** (`~/.config/sops/age/keys.txt`, or
`~/Library/Application Support/sops/age/keys.txt` on macOS). Without it you
can't change secrets or reinstall the server from this repository.
Expand Down
73 changes: 73 additions & 0 deletions docs/operator-security.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# Operator security checklist

The server is hardened, but whoever controls one of the accounts or machines
*around* it controls the mail. Each item below is a full compromise if lost.
Go through this list once, and again whenever something changes.

## Accounts

Turn on two-factor authentication, preferably a hardware key (FIDO2/WebAuthn,
e.g. a YubiKey) and otherwise TOTP. Never SMS. Store the recovery codes
offline.

- [ ] **Hosting provider** (OVHcloud, netcup CCP *and* SCP, UpCloud,
Serverspace). Its web console, rescue mode, snapshots and "reinstall"
button each give full access to the server and the disk.
- [ ] **Domain registrar.** Whoever can change the nameservers can redirect
your mail and get valid certificates for your domains. Also turn on
the registrar lock / transfer lock.
- [ ] **Cloudflare** (or wherever DNS is hosted). Same as the registrar.
- [ ] **GitHub** (or wherever this repository lives). With `autoUpgrade` on,
push access is root on the server; protect the branch (required
reviews, no force pushes).
- [ ] **The backup bucket provider** (see docs/backups.md).
- [ ] **The admin mailbox's own provider**, if `adminEmail` or your
healthcheck alerts go to an external address.

## Your machine

Everything needed to take over the server lives on the machine you run
`just` from:

- **The age key** (`~/.config/sops/age/keys.txt`, or
`~/Library/Application Support/sops/age/keys.txt` on macOS). It decrypts
every secret, including the server's SSH host key. It is stored
unencrypted by default. Better options:
- Keep it on a hardware key with
[age-plugin-yubikey](https://github.com/str4d/age-plugin-yubikey); sops
supports age plugins, so `keys.txt` then only holds a stub and every
decryption needs the key plugged in (and touched).
- Or keep it in your password manager and hand it to sops on demand with
`SOPS_AGE_KEY_CMD`, e.g.
`export SOPS_AGE_KEY_CMD="op read op://Private/mailserver-age/key"`.
- Either way, keep an offline backup of the key; without it you cannot
change secrets or reinstall the server.
- **The root SSH key** (`settings.sshKeys`). Prefer a key that lives on a
hardware token (`ssh-keygen -t ed25519-sk`), so that a stolen laptop or
malware can't use it without the token.
- **Provider API credentials.** They are long-lived and powerful (the OVH
key can order and terminate services). Keep them in your password manager
and load them per shell (`op run`, `pass`, direnv with a password
manager); don't put them in `~/.bashrc`. Give each key only what it needs
(docs/providers.md lists the rights) and revoke keys you no longer use.
The netcup token is stored encrypted in `secrets/secrets.yaml` by
`just netcup-login` and never printed.
- **Full-disk encryption and a screen lock** on the machine itself.

## If something leaks

- **Age key or the repository with it:** generate a new age key, replace it in
`.sops.yaml`, run `sops updatekeys secrets/*`, and then rotate the secrets
themselves, because old ciphertexts stay in git history: every mailbox
password (`just passwd`), the DKIM keys (`just add-domain` with a new
selector, then remove the old one), the relay and backup credentials, and
the Terraform state passphrase.
- **Server SSH host key / root on the server:** the attacker could decrypt all
secrets. Generate a new host key (as `scripts/init.sh` does), replace the
server's recipient in `.sops.yaml` with its `ssh-to-age` value, run
`sops updatekeys secrets/*`, reinstall with `just install`, and rotate all
secrets as above.
- **A provider API key:** revoke it in the provider's panel and create a new
one.
- **A mailbox password:** `just passwd <address>` and `just deploy`; check
`just logs` for what was sent from the account.
5 changes: 3 additions & 2 deletions docs/providers.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,8 +68,9 @@ netcup has no API for creating servers.
SSH key for root when it is set up (SCP > Media > Images > reinstall
"Debian" with your key, or copy it in with the emailed password).
2. Put the server ID (SCP > server > General) into `server.netcup.serverId`.
3. `just netcup-login`, then export the printed `NETCUP_SCP_REFRESH_TOKEN`.
It stays valid if used at least once every 30 days.
3. `just netcup-login`. The resulting API token is stored encrypted in
`secrets/secrets.yaml` (never printed) and used by `just apply`. It stays
valid if used at least once every 30 days.

`just apply` then sets the host name and the reverse DNS for IPv4 and the
first address of your IPv6 /64, and **turns off netcup's network firewall**,
Expand Down
5 changes: 5 additions & 0 deletions docs/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,11 @@ misdirected message.

## 6. Secrets

The accounts and machines around the server (provider, registrar, DNS,
GitHub, your laptop with the age key) are outside what this configuration
can protect; see [operator-security.md](operator-security.md).


- Secrets are encrypted with [sops](https://github.com/getsops/sops) to two
age keys: yours, and one derived from the server's SSH host key. The server
decrypts them at boot into `/run/secrets` (tmpfs), readable only by the
Expand Down
9 changes: 9 additions & 0 deletions scripts/apply.sh
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,15 @@ cd "$ROOT"

mode="${1:-apply}"
vars="$(tfvars)"

# Provider credentials kept in the encrypted secrets instead of the shell
# environment (currently: the netcup token from `just netcup-login`).
if [[ "$(provider)" == netcup && -z "${NETCUP_SCP_REFRESH_TOKEN:-}" ]]; then
require_secrets
NETCUP_SCP_REFRESH_TOKEN="$(sops decrypt --extract '["netcup"]["scp_refresh_token"]' "$SECRETS" 2> /dev/null)" \
|| die "no netcup token: run 'just netcup-login' first"
export NETCUP_SCP_REFRESH_TOKEN
fi
info "Provider: $(provider), DNS: $(jq -r .dns <<< "$vars")"

server="$(server_dir)"
Expand Down
15 changes: 9 additions & 6 deletions scripts/netcup-login.sh
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,12 @@
# Obtain an offline refresh token for the netcup Server Control Panel API via
# the OAuth device flow, for the netcup Terraform step.
#
# The token is printed, not stored: put it in your password manager and
# export it as NETCUP_SCP_REFRESH_TOKEN before `just apply`. It stays valid as
# long as it is used at least once every 30 days; revoke it in the SCP under
# "Sessions" if it leaks.
# The token can reinstall the server and read rescue-system passwords, so it
# is never printed: it goes straight into secrets/secrets.yaml (encrypted),
# from where `just apply` loads it. It stays valid as long as it is used at
# least once every 30 days; revoke it in the SCP under "Sessions" if it leaks.
source "$(dirname "$0")/lib.sh"
require_secrets

realm="https://www.servercontrolpanel.de/realms/scp/protocol/openid-connect"

Expand All @@ -31,5 +32,7 @@ while true; do
esac
done

echo
echo "export NETCUP_SCP_REFRESH_TOKEN='$(jq -r .refresh_token <<< "$response")'"
token="$(jq -r .refresh_token <<< "$response")"
[[ -n "$token" && "$token" != null ]] || die "no refresh token in the response"
sops_set '["netcup"]["scp_refresh_token"]' "$token"
info "Stored the refresh token (encrypted) in secrets/secrets.yaml; 'just apply' uses it."
Loading