Security Best Practices

How to protect backup encryption keys, object storage credentials, database passwords, and app tokens when using peppykeep.

Separate recovery keys from runtime credentials

Treat recovery keys and runtime credentials as two separate material classes:

恢复密钥：ppk.pub、ppk.key、PPKPKPSW（私钥口令）
运行时凭证：S3 兼容对象存储凭证、数据库密码、应用令牌

Recovery keys protect encrypted backups. Runtime credentials let peppykeep reach object storage, databases, or app APIs. Store, authorize, and rotate them separately.

Recovery key management

ppk.pub is the backup-source public key. You may deploy it to backup hosts or config management, but do not publish it on the public internet.

ppk.key is the restore private key—store it only on restore hosts or trusted ops environments, not on every backup source.

PPKPKPSW holds the private-key passphrase. Provide it via secure env vars or interactive input—never commit it to config. If both private key and passphrase are lost, backups are unrecoverable.

Recommended Linux permissions:

chmod 600 /etc/peppykeep/keys/<key-purpose>/ppk.key

Recommended macOS permissions:

chmod 600 ~/.peppykeep/keys/<key-purpose>/ppk.key

Small-team practices

Individuals or teams of 1–3:

• Keep ppk.key separate from the private-key passphrase.
• Keep at least one offline copy (paper record or encrypted USB).
• Do not store passphrases on a single personal machine only.
• Prefer env vars or key files for object storage and DB passwords.
• Verify an encrypted test backup at least every 6–12 months.

Teams of 3–20:

• Assign different owners for ppk.key and the private-key passphrase.
• Record each key’s purpose, owner, creation date, and affected systems.
• Use accounts scoped to a single bucket or prefix.
• Use dedicated accounts for database backup and restore.
• Rotate runtime credentials on a schedule.
• Run recovery drills after onboarding and after credential changes.

Larger teams:

• Manage runtime credentials with a secrets manager, Vault, Kubernetes Secrets, cloud KMS, or vendor key services.
• Prefer IAM/RAM roles and temporary credentials over long-lived access keys.
• Use dual control or approval for recovery private keys.
• Audit access, copy, rotation, and destruction of ppk.key and passphrases.
• Split object storage permissions by env, system, bucket, and prefix.
• Run at least one recovery drill per quarter on mission-critical systems.

Object storage credentials

Use scoped sub-accounts or roles for S3-compatible storage; never use the cloud root access key.

Recommended setup:

[object_storage]
provider = "s3"
access_key_id_env = "PPK_S3_ACCESS_KEY_ID"
access_key_secret_env = "PPK_S3_ACCESS_KEY_SECRET"

Environment variable example:

export PPK_S3_ACCESS_KEY_ID="<access-key-id>"
export PPK_S3_ACCESS_KEY_SECRET="<access-key-secret>"

Grant least privilege by workflow:

Permission names depend on your cloud provider.

Database password

Use dedicated DB accounts for backup and restore; do not run daily backups as root or admin.

Use a dedicated MySQL backup user; pass passwords via env vars or key files:

[mysql]
user = "ppk_backup"
password_env = "PPK_MYSQL_PASSWORD"

Or:

[mysql]
user = "ppk_backup"
password_file = "/etc/peppykeep/secrets/mysql.pwd"

Environment variable example:

export PPK_MYSQL_PASSWORD="<mysql-password>"

Apply the same pattern to PostgreSQL, Redis, MongoDB, and app APIs: dedicated accounts/tokens with least privilege for backup/restore only.

Key files

If you are not using a secrets manager, store key files in a dedicated directory with tight permissions.

Linux example:

/etc/peppykeep/secrets

macOS example:

~/.peppykeep/secrets

Recommended permissions:

chmod 700 /etc/peppykeep/secrets
chmod 600 /etc/peppykeep/secrets/*.toml
chmod 600 /etc/peppykeep/secrets/*.pwd

Never commit key files to git, shared drives, screenshots, tickets, or backup artifacts.

Redact logs and screenshots

Redact secrets before sharing logs, screenshots, commands, or config snippets with support.

May include:

• Configuration key names.
• Environment variable names.
• Key file paths.
• Host, port, database name, and username—only if these are not sensitive in your environment.
• Error summary.
• peppykeep version, OS, and install method.

Must redact:

• Plaintext passwords.
• Access key secret。
• API token。
• Full connection strings with passwords.
• Contents of ppk.key.
• The actual PPKPKPSW value or private-key passphrase.

Redaction example:

MySQL connection failed.
Mode: container_exec
Host: 192.0.2.10
Port: 3306
User: ppk_restore
Password: <hidden>

Rotation and recovery drills

Rotate runtime credentials after personnel changes, suspected leaks, or environment changes; set a cadence based on your risk tier.

Validate before you need a real restore:

• Confirm ppk.key and passphrase decrypt a test backup.
• Confirm object storage credentials can upload and download.
• Confirm the DB account still has required backup/restore privileges.
• Restore to a staging location first, then verify content and permissions.

Suggested minimum frequency:

Quick checklist

• ppk.pub is deployed on the backup source.
• Store ppk.key only on restore hosts or trusted environments.
• Manage private-key passphrases separately from ppk.key.
• Offline recovery key copies exist and were tested.
• Use scoped sub-accounts, roles, or least-privilege access keys for object storage.
• Use dedicated accounts for database backup and restore.
• Passwords and tokens are not stored in plaintext in main config files.
• Key file permissions are locked down.
• Logs, screenshots, tickets, and chat must not contain real keys.