Skip to main content
Cloudstic uses AES-256-GCM encryption by default. This guide explains how to manage encryption credentials, add recovery keys, change passwords, and understand the key slot system.

​
Understanding Cloudstic Encryption

Cloudstic’s encryption model:
  • A random 32-byte master key is generated during cloudstic init
  • The master key encrypts all backup data
  • The master key itself is wrapped into one or more key slots
  • Each slot is unlocked with different credentials (password, platform key, KMS key, or recovery phrase)
  • All slots unlock the same master key
Think of key slots like multiple keys to the same safe. You can unlock your backups with any valid credential.

​
Key Slot Types

Slot TypeCredentialUse Case
passwordUser password (passphrase)Day-to-day access, interactive use
platform64-character hex keyAutomation, CI/CD, non-interactive scripts
kms-platformAWS KMS key ARNHSM-backed enterprise encryption
recovery24-word BIP39 mnemonicEmergency access when password is lost

​
Creating a Repository with Encryption

​
Password-Based Encryption

Most common for personal use: 
cloudstic init -encryption-password "your strong passphrase"
Use a strong, unique passphrase. Consider using a passphrase manager like 1Password, Bitwarden, or LastPass.
Add a recovery key during initialization: 
cloudstic init -encryption-password "your passphrase" -recovery
Output: 
╔══════════════════════════════════════════════════════════════╗
║                      RECOVERY KEY                           ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  abandon ability able about above absent absorb abstract ... ║
║                                                              ║
║  Write down these 24 words and store them in a safe place.   ║
║  This is the ONLY time the recovery key will be displayed.   ║
║  If you lose your password, this key is your only way to     ║
║  recover your encrypted backups.                             ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

Repository initialized (encrypted: true).
Write down your recovery key immediately! It will only be displayed once. Store it in a safe, offline location (physical safe, safety deposit box, etc.).

​
Platform Key for Automation

Use a raw encryption key for non-interactive systems: 
# Generate a random 32-byte key (64 hex characters)
export CLOUDSTIC_ENCRYPTION_KEY=$(openssl rand -hex 32)

# Initialize repository
cloudstic init -encryption-key $CLOUDSTIC_ENCRYPTION_KEY

# Store the key securely (e.g., in a secrets manager)
echo $CLOUDSTIC_ENCRYPTION_KEY | vault kv put secret/backups key=-
Platform keys are intended for automation where password prompts aren’t possible. Store them in a secrets manager (HashiCorp Vault, AWS Secrets Manager, etc.).

​
Dual Access (Password + Platform Key)

Create a repository with both types of access: 
cloudstic init \
  -encryption-password "your passphrase" \
  -encryption-key $(openssl rand -hex 32)
Now you can unlock the repository with either credential.

​
Listing Key Slots

View all key slots in a repository: 
cloudstic key list
Output: 
+──────────────+─────────+──────────+
| Type         | Label   | KDF      |
+──────────────+─────────+──────────+
| password     | default | argon2id |
| recovery     | default | —        |
+──────────────+─────────+──────────+

2 key slot(s) found.
key list does not require authentication — slot metadata is stored unencrypted.

​
Adding a Recovery Key

Add a recovery key to an existing repository: 
cloudstic key add-recovery -encryption-password "your passphrase"
Output: 
╔══════════════════════════════════════════════════════════════╗
║                      RECOVERY KEY                           ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  abandon ability able about above absent absorb abstract ... ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

Recovery key slot has been added to the repository.
This is the only time the recovery key is displayed. Write it down and store it securely.
If you’re using a platform key instead of a password: 
cloudstic key add-recovery -encryption-key <your-hex-key>
For KMS-managed repositories: 
cloudstic key add-recovery -kms-key-arn arn:aws:kms:us-east-1:123456:key/abc-123

​
Changing Your Password

Update the password slot: 
cloudstic key passwd
You’ll be prompted for:
  1. Current password (or provide via -encryption-password)
  2. New password (or provide via -new-password)
  3. Confirmation of new password
Non-interactive example: 
cloudstic key passwd \
  -encryption-password "old passphrase" \
  -new-password "new passphrase"
If you’re unlocking with a platform key or KMS key, you can use those to set a new password:
cloudstic key passwd -encryption-key <hex-key> -new-password "new passphrase"

​
Using Recovery Keys to Access Backups

If you’ve lost your password, use your recovery key: 
cloudstic list -recovery-key "word1 word2 word3 ... word24"
Or set it as an environment variable: 
export CLOUDSTIC_RECOVERY_KEY="word1 word2 word3 ... word24"
cloudstic list
cloudstic restore
Once you’ve regained access, set a new password: 
cloudstic key passwd -recovery-key "word1 word2 ... word24" -new-password "new passphrase"

​
Environment Variables for Credentials

Avoid typing credentials repeatedly: 
# For password-based access
export CLOUDSTIC_ENCRYPTION_PASSWORD="your passphrase"

# For platform key access
export CLOUDSTIC_ENCRYPTION_KEY="64-character-hex-key"

# For recovery key access
export CLOUDSTIC_RECOVERY_KEY="word1 word2 ... word24"

# For KMS access
export CLOUDSTIC_KMS_KEY_ARN="arn:aws:kms:us-east-1:123456:key/abc-123"
Add to your shell profile (~/.bashrc, ~/.zshrc) for persistence: 
echo 'export CLOUDSTIC_ENCRYPTION_PASSWORD="your passphrase"' >> ~/.bashrc
source ~/.bashrc
Security consideration: Only store credentials in environment variables on trusted, single-user systems. For shared systems, enter passwords interactively.

​
Interactive Password Prompts

If no credential is provided, Cloudstic will prompt interactively: 
$ cloudstic restore
Repository password: [hidden input]
This is the most secure option for personal use.

​
Advanced: AWS KMS Integration

For enterprise deployments, use AWS KMS to manage encryption keys:
1

Create a KMS key

aws kms create-key --description "Cloudstic backup encryption"
Note the KeyId from the output.
2

Initialize repository with KMS

cloudstic init -kms-key-arn arn:aws:kms:us-east-1:123456:key/abc-123
3

Use KMS for all operations

export CLOUDSTIC_KMS_KEY_ARN="arn:aws:kms:us-east-1:123456:key/abc-123"
cloudstic backup -source local -source-path ~/Documents
cloudstic restore
KMS integration requires AWS credentials with kms:Decrypt and kms:GenerateDataKey permissions.

​
Security Best Practices

1

Use strong, unique passphrases

  • At least 20 characters
  • Mix of words, numbers, and symbols
  • Not reused from other services
  • Consider using a passphrase generator
2

Always create a recovery key

cloudstic init -encryption-password "passphrase" -recovery
3

Store recovery keys offline

  • Write on paper, store in a safe
  • Use a safety deposit box
  • Split across multiple secure locations
  • Never store digitally alongside backups
4

Test recovery key access

Verify your recovery key works:
cloudstic list -recovery-key "word1 word2 ... word24"
5

Rotate passwords periodically

cloudstic key passwd
Recommended: every 6-12 months
6

Use KMS for production systems

Leverage hardware security modules for enterprise deployments:
cloudstic init -kms-key-arn arn:aws:kms:...

​
Troubleshooting

​
”Could not open key slots” Error

Your password or key is incorrect. Verify: 
# Check environment variable
echo $CLOUDSTIC_ENCRYPTION_PASSWORD

# Try recovery key
cloudstic list -recovery-key "word1 word2 ... word24"

​
“Repository not encrypted” Message

The repository was created with -no-encryption. Key management commands don’t apply to unencrypted repositories.

​
Lost Password and Recovery Key

There is no recovery option if both are lost. Your backups are permanently inaccessible. This is by design — encryption without a backdoor. Preventive measures:
  • Always create a recovery key (-recovery)
  • Store recovery key in multiple secure locations
  • Document your encryption setup

​
Changing Password Doesn’t Work

Ensure you’re providing the correct current credentials: 
# Unlock with current password
cloudstic key passwd -encryption-password "current passphrase"

# Or with platform key
cloudstic key passwd -encryption-key <current-hex-key>

# Or with recovery key
cloudstic key passwd -recovery-key "word1 word2 ... word24"

​
Recovery Key Format

Recovery keys use the BIP39 mnemonic standard:
  • 24 words from a standardized word list
  • Each word encodes ~11 bits of entropy
  • Total: 256 bits of entropy (same as the master key)
  • Words are lowercase, space-separated
  • Order matters
Example (do not use this): 
abandon ability able about above absent absorb abstract absurd abuse access accident
account accuse achieve acid acoustic acquire across act action actor actress actual

​
Unencrypted Repositories

You can create an unencrypted repository (not recommended): 
cloudstic init -no-encryption
Unencrypted repositories are not recommended. Your backup data is stored in plaintext and can be read by anyone with storage access.
Use cases for unencrypted repositories:
  • Testing and development
  • Backups of already-encrypted data
  • Air-gapped systems with physical security

​
Next Steps

First Backup

Create your first encrypted backup

Restoring Files

Use your encryption key to restore backups

Automation

Automate backups with platform keys

Check Command

Verify encrypted data integrity