Security and key custody
Your host encrypts every backup before it uploads it. The bucket keeps it under S3 Object Lock until a date set by your plan or your retention settings. Unless you choose a customer-managed key, SafeGrd keeps the key that decrypts your backups sealed and releases it only to your enrolled hosts.
The cryptography
| Layer | What is used |
|---|---|
| Encryption | Age, which uses ChaCha20-Poly1305 for authenticated encryption and X25519 for key agreement. It is a standard scheme you can audit, with nothing bespoke. |
| Compression | zstandard, applied before encryption on the streaming path. |
| Attestation | Ed25519 signatures over a SHA-256 hash chain. |
| Implementation | Written in Go, with no wrapped proprietary blobs. Database surfaces use the engine's own client tools: pg_dump for a PostgreSQL schema, mysqldump and mysql for MySQL and MariaDB, mongodump and mongorestore for MongoDB. SQLite, files and mail need no other tool. |
Encryption is asymmetric, so a host needs only the public key to back up. You need the private key only to restore or to run a Fire Drill.
The CLI sets no server-side encryption header when it uploads, because the object is already Age ciphertext. Your bucket's own encryption at rest (SSE-S3, which AWS applies to every new bucket) is up to you. It adds nothing to a backup's confidentiality.
Data keys and key-encryption keys
In envelope-encryption terms, every backup has its own data encryption key (DEK), and your age key pair is the key-encryption key (KEK) that wraps it.
| Key | What it does | Where it lives |
|---|---|---|
| DEK | Age makes a random 16-byte file key for each backup, and encrypts the backup with ChaCha20-Poly1305 under a key derived from it. | In the backup's header, wrapped by the KEK. Each backup gets a new one, so there is nothing to store or rotate. |
| KEK | Your age key pair (X25519). The public half wraps each backup's DEK. The private half unwraps it for a restore or a drill. | The public half is on your hosts and in SafeGrd. Where the private half lives depends on your key custody choice: a SafeGrd-managed key or a customer-managed key. |
With a SafeGrd-managed key, SafeGrd keeps your key sealed and releases it only to your enrolled hosts, so you can restore even after losing a host. With a customer-managed key, the private half of the KEK stays on your hosts. The KEK is the only key you make a choice about.
A SafeGrd-managed key works like a key your cloud provider manages for you. SafeGrd keeps it per organization, releases it only to your enrolled hosts and audits every release. A customer-managed key never reaches SafeGrd. In cloud terms, that is client-side encryption rather than a key in a provider's KMS.
What SafeGrd's server never receives
- Your data. Your host sends the backup to the bucket already encrypted. It never passes through SafeGrd's server, even when the bucket is hosted storage. A drill you set to run on SafeGrd decrypts the snapshot on a machine SafeGrd starts for that drill alone. The machine gets the key and never a database credential. The release shows in your key access record, and the machine is destroyed when the drill ends. When SafeGrd backs up a database for you, a machine started for that backup alone runs the dump. It gets the connection string and never the key.
- Filenames, table contents and email subjects. The manifest is sealed inside the encrypted archive, not written beside it.
- Your age private key, if it is a customer-managed key. The CLI never writes it into the config file and never sends it anywhere.
- Database and mailbox passwords, unless you choose to have SafeGrd hold them (below).
Two secrets, each chosen separately
SafeGrd needs two secrets to protect a surface. You choose for each one whether SafeGrd keeps it, and choosing SafeGrd for one does not choose it for the other.
| Secret | What it does | Default |
|---|---|---|
| The encryption key | The age private key that decrypts a host's backups (the private half of the KEK). Restores and drills need it. Backing up needs only its public half. | A SafeGrd-managed key, kept sealed by SafeGrd. You choose per host when it enrolls. --key-custody local keeps it on the host as a customer-managed key. |
| A surface's credential | The database URL or mailbox password the host uses to read the surface, or the S3 key of a bucket SafeGrd backs up. Only backups need it. | The host keeps it. You choose per surface: the setup wizard asks, or use Credential in the surface's panel to hand it to SafeGrd. |
A bucket's access key belongs to the project rather than to a host. If you set the bucket up in the console, SafeGrd keeps the access key sealed. If you set it up with the CLI, the hosts keep it. Hosted storage needs no key of yours.
The encryption key
You choose each host's key mode when the host enrolls, with --key-custody. In both
modes the host encrypts every backup the same way before it leaves. The difference is where the
private key lives, and so how a new host gets it.
SafeGrd-managed key --key-custody safegrd, the default
- This host makes the key when it enrolls
- SafeGrd keeps it sealed
- Your enrolled hosts get it to restore or drill
- What it gives you
- SafeGrd keeps your key sealed and releases it only to your enrolled hosts, so you can restore even after losing a host.
- Every release
- is written to the key access record before it happens.
- A copy
safegrd keygen --heldwrites one on an enrolled host, if you want your own.
Customer-managed key --key-custody local
- This host makes the key and keeps it
- Your copy somewhere safe, such as a password manager
- A new host you copy the key file to it
- What it gives you
- Only you can decrypt these backups. SafeGrd has the public key and nothing else.
- Keep
- a copy of the key file somewhere safe, before the first backup.
You lose no backups when you lose a host, in either mode. With a SafeGrd-managed key, enroll a new host and restore (the runbook). With a customer-managed key, put your copy of the key file on the new host first.
$ safegrd keygen --held --out /tmp/prod-app-01.key Private key: /tmp/prod-app-01.key (mode 0600), a copy of the SafeGrd-managed key. Public key: age1lq70sjlq9u8ymuxvmxqwf20trfjn5qx44578xy3gvu2fqyzsaa9scp2uzm Fingerprint: SG:e53b6c6a:cc58f416 SafeGrd still holds this key and releases it only to your enrolled hosts. Keep this copy somewhere safe: it opens every backup sealed to this key.
$ safegrd keygen --out /tmp/offline.key Private key: /tmp/offline.key (mode 0600). Keep a copy somewhere safe. Public key: age1k0j89dn7xm007xyd2ct7z4jxfyw7scph5tt5my6f83rmcza6tp9s3ppdmu Fingerprint: SG:b26ce676:74b55239
encryption.public_key on those hosts. They can then encrypt but cannot decrypt.The console shows how each surface's key is managed. The CLI never sends a key you supply yourself. When SafeGrd backs up a database or bucket for you, there is no host to make a key. Those backups are sealed to a key SafeGrd makes and keeps for your organization.
Credentials
When SafeGrd holds a credential, it keeps it sealed and releases it only to the surface's host when it backs up, or to the machine SafeGrd starts for that backup. Nobody can read it back through the console or the API. A credential you keep on the host stays in its config, which points to it with an environment variable, a command or a file.
To restore from the console you need an account that can write, and the backup's own account cannot. Type that account's URL when you ask for the restore. SafeGrd seals it and gives it once to the host or the machine SafeGrd starts that runs the restore. The release is recorded in the key access log. SafeGrd deletes the URL when the restore ends, or after a day if nothing picked it up. A machine SafeGrd starts for a restore gets the snapshot's key and that one URL, for that restore only. It never receives the surface's own credential.
Whichever you pick, the archive is sealed the same way. Install and enroll shows how to choose the key when a host enrolls.
SafeGrd's own database
SafeGrd's database holds your account, your hosts' enrollment, the record of every backup and drill, and the sealed secrets above.
If a host, a token or a key file is compromised
Work through the steps in order. The first one cuts off access, and the later ones show what was reached. Each step names the console action or the command to run.
| What happened | What to do |
|---|---|
| A host is lost or compromised |
|
| A personal access token leaked |
|
| An agent's sign-in token leaked |
|
| A customer-managed key file was copied |
|
The activity log
Activity in the console is the audit log for owners and admins. Each row names who did what, and when. It records:
- sign-ins, and sign-ins refused for a wrong password or two-factor code
- members invited, joined and removed, and their roles changed
- access tokens created and revoked
- hosts enrolled and decommissioned, and their tokens rotated
- surfaces added and retired, and their connections changed
- changes to projects and storage
- sign-in rules and two-factor turned on or off
- alert and compliance settings
Every release of a held key or credential appears here too, as well as in the
Key access record. A host reading its own hosted storage appears only in the key
access record. Owners and admins can read both and export them as CSV or JSON
(GET /api/v1/orgs/{id}/events/export?category=action|access&format=csv|json).
SafeGrd keeps them for 90 days, so export the log to keep it longer.
Check these claims in the CLI's source
You can check everything this page says about what leaves your host in the CLI's source, at github.com/safegrd/cli. It is licensed under the Business Source License 1.1, so you can read, modify, build and evaluate it. Any SafeGrd account comes with production use, the free plan included. Without an account you can still list, verify, restore and export your backups. If SafeGrd stops running its service, all production use is allowed. Each version becomes GPLv3 four years after its release (license).
Hardening the host
- Keep
config.yamland the key file at 0600. On POSIX systemssafegrd doctorfails when they are not. - Give the backup credential read-only database access. A backup never writes to the database.
- Deny
s3:DeleteObjectto the backup credential. Object Lock already stops a locked backup from being destroyed, and denying deletes keeps the credential from writing delete markers at all. - Use a
credentialblock (from: env,commandorfile) instead of an inlinedatabase_urlwith a password in it. That keeps the password out of the config, shell history and the process table. - Before you need it, run a real restore at least once on a host that is not production.