Encryption & Security

Zero-knowledge architecture — your keys, your data, your control

AES-256-GCM End-to-End Encryption

All backup data is encrypted with AES-256-GCM before it leaves your device. GCM provides built-in authentication — no separate HMAC needed. Ginkgo uses only this one algorithm — a single audited path, no risk of choosing the wrong one.

项目	值
Algorithm	`AES-256-GCM`
Key Size	`256 bits`
Password Derivation	`Argon2id (time=3, memory=64MB, threads=4)`
Derivation Usage	`Argon2id derives a KEK to wrap the master key; HKDF-SHA256 derives per-blob keys in the cloud GC read path`
Nonce Size	`12 bytes`

Key Hierarchy

A multi-layer key design: the user password derives a Key Encryption Key (KEK) that wraps the master key. The master key encrypts every blob and manifest. Cloud repositories use their own independent master keys, isolated from the local repo.

层级	说明
`User Password`	User password (optional input; required once encryption is enabled)
`KEK (Argon2id)`	Key Encryption Key derived from the password via Argon2id; used only to wrap the master key inside repo.key
`Master Key`	Random 32-byte key; encrypts all blobs (GB1/GB2) and manifests (GKM1)
`Cloud Repo Master Key`	Per-cloud-backend master key, generated independently and isolated from the local master key
`repo.key file`	Stores the KEK-wrapped master key (GEK1 binary or JSON format)

Zero-Knowledge Design

Encryption keys are generated and stored only on your device. Ginkgo servers cannot read your data. Even if cloud storage is breached, without the keys, attackers get only unreadable ciphertext.

Recovery Codes — Your Lifeline If You Forget the Password

Zero-knowledge encryption means: forget your password = data is unrecoverable. Always export a recovery code after enabling encryption and store it safely (e.g. print it out or save to a password manager).

⚠️ Without the password and without the recovery code, no one can help you recover your data — that's the price of zero-knowledge encryption, and also why it's secure.

Credential Encryption

Cloud credentials (S3 keys, WebDAV passwords, OAuth tokens) are encrypted with the repository key and stored in the local database. API responses never return decrypted credentials.

Ransomware Protection

Ginkgo's cross-repo protection detects abnormal mass file changes. Backups synced to the cloud via WebDAV are fully isolated from your machine — ransomware cannot reach them. Even if your machine is infected, cloud backups remain safe and can be rolled back to a pre-infection version.

Configuration Vault

Securely back up and restore app configuration — settings, schedules, repository layouts. After a system reinstall, restore all settings in one click without reconfiguring.

Key Export & Import

Export encryption keys via API for disaster recovery, or import them to a new machine to regain access to old backups.

TLS & Local CA

When the API server listens on 0.0.0.0 or runs in headless mode, Ginkgo Backup automatically enables TLS using an ECDSA P-256 generated local CA and server certificate. The CA certificate includes NameConstraints and user-configured public IP SANs (written as /32 or /128 ranges into PermittedIPRanges) to avoid conflicts with other instances' CAs.

Enabling TLS for the First Time

Run ginkgo-server --tls-auto to auto-generate the local CA and server certificate

Run ginkgo-server --tls-trust (requires admin) to install the CA into the system trust store; stale CAs with the same name are cleaned up before install

On the CLI side, use --tls or export GINKGO_TLS=1 to connect over HTTPS

💡 Self-signed certificates are only for localhost and LAN. For public internet access, terminate TLS on a reverse proxy (e.g. Caddy/Nginx) with a public CA-issued certificate.

TOTP Two-Factor Authentication

Enable TOTP (time-based one-time password) two-factor authentication for WebUI login to prevent account takeover if the password leaks. TOTP endpoints live under /api/v1/auth/totp/*.

POST /api/v1/auth/totp/setup to begin setup; returns a QR code and secret

Scan the QR code in an Authenticator app (Google Authenticator, 1Password, etc.)

POST /api/v1/auth/totp/confirm with a verification code to confirm binding

POST /api/v1/auth/totp/disable disables 2FA (requires the current TOTP code)

💡 Once 2FA is enabled, every login requires a dynamic verification code in addition to the password. Save backup recovery codes — losing your phone should not lock you out.

WebUI Access Password

When the API server listens on 0.0.0.0, set a WebUI access password to prevent unauthorized LAN access. Token and password work side by side: the Token is for API clients, the password protects browser sessions.

Run ginkgo-server --set-password <password> to set a password and exit

Or call POST /api/v1/auth/password to change it later

The browser prompts for the password on first WebUI visit, then establishes a session

💡 Setting a password does not affect the existing Token authentication. CLI/API calls still use Bearer Token; the password only protects browser sessions.