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 -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 -password "your passphrase" -add-recovery-key
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 \
  -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 | N/A      |
+──────────────+─────────+──────────+

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 -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 -password)
  2. New password (or provide via -new-password)
  3. Confirmation of new password
Non-interactive example: 
cloudstic key passwd \
  -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_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_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.

​
Store-Level Encryption Configuration

When using profiles, encryption settings can be stored on the store entry using secret references. Only the reference is saved, never the secret value itself: 
cloudstic store new \
  -name prod-s3 \
  -uri s3:my-bucket/backups \
  -password-secret keychain://cloudstic/prod/repo-password \
  -kms-key-arn arn:aws:kms:us-east-1:123456:key/abcd
In interactive mode, store new guides you through encryption setup if no encryption flags are provided: 
Select encryption method
  1) Password (recommended for interactive use)
  2) Platform key (recommended for automation/CI)
  3) AWS KMS key (enterprise)
  4) No encryption (not recommended)
Select option number [1]:
The chosen settings are saved to profiles.yaml as secret references. You can then initialize the store immediately or later with cloudstic init -profile <name>. This saves to profiles.yaml: 
stores:
  prod-s3:
    uri: s3:my-bucket/backups
    password_secret: keychain://cloudstic/prod/repo-password
    kms_key_arn: arn:aws:kms:us-east-1:123456:key/abcd
Supported secret reference schemes:
  • env://VAR_NAME
  • keychain://service/account
  • wincred://target
  • secret-service://collection/item
At backup time, Cloudstic resolves the secret reference and uses the returned value. The KMS ARN is stored directly since it’s not a secret.
Store FieldWhat it stores
password_secretSecret reference for the repository password
encryption_key_secretSecret reference for the platform key (hex)
recovery_key_secretSecret reference for the recovery mnemonic
kms_key_arnKMS ARN (stored directly)
kms_regionKMS region (stored directly)
kms_endpointCustom KMS endpoint (stored directly)
Store-level encryption settings are applied automatically when you use -profile. CLI flags always take precedence if you need to override them.

​
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:~/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 -password "passphrase" -add-recovery-key
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_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 (-add-recovery-key)
  • 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 -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