Managing Encryption Keys

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 Type	Credential	Use Case
`password`	User password (passphrase)	Day-to-day access, interactive use
`platform`	64-character hex key	Automation, CI/CD, non-interactive scripts
`kms-platform`	AWS KMS key ARN	HSM-backed enterprise encryption
`recovery`	24-word BIP39 mnemonic	Emergency 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.

Password + Recovery Key (Recommended)

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:

Current password (or provide via -password)
New password (or provide via -new-password)
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 Field	What it stores
`password_secret`	Secret reference for the repository password
`encryption_key_secret`	Secret reference for the platform key (hex)
`recovery_key_secret`	Secret reference for the recovery mnemonic
`kms_key_arn`	KMS ARN (stored directly)
`kms_region`	KMS region (stored directly)
`kms_endpoint`	Custom 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:

Create a KMS key

aws kms create-key --description "Cloudstic backup encryption"

Note the KeyId from the output.

Initialize repository with KMS

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

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

Use strong, unique passphrases

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

Always create a recovery key

cloudstic init -password "passphrase" -add-recovery-key

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

Test recovery key access

Verify your recovery key works:

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

Rotate passwords periodically

cloudstic key passwd

Recommended: every 6-12 months

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

Get Started

Core Concepts

Sources

Storage Backends

Guides

Managing Encryption Keys

Understanding Cloudstic Encryption

Key Slot Types

Creating a Repository with Encryption

Password-Based Encryption

Password + Recovery Key (Recommended)

Platform Key for Automation

Dual Access (Password + Platform Key)

Listing Key Slots

Adding a Recovery Key

Changing Your Password

Using Recovery Keys to Access Backups

Environment Variables for Credentials

Store-Level Encryption Configuration

Interactive Password Prompts

Advanced: AWS KMS Integration

Security Best Practices

Troubleshooting

”Could not open key slots” Error

“Repository not encrypted” Message

Lost Password and Recovery Key

Changing Password Doesn’t Work

Recovery Key Format

Unencrypted Repositories

Next Steps

First Backup

Restoring Files

Automation

Check Command

​Understanding Cloudstic Encryption

​Key Slot Types

​Creating a Repository with Encryption

​Password-Based Encryption

​Password + Recovery Key (Recommended)

​Platform Key for Automation

​Dual Access (Password + Platform Key)

​Listing Key Slots

​Adding a Recovery Key

​Changing Your Password

​Using Recovery Keys to Access Backups

​Environment Variables for Credentials

​Store-Level Encryption Configuration

​Interactive Password Prompts

​Advanced: AWS KMS Integration

​Security Best Practices

​Troubleshooting

​”Could not open key slots” Error

​“Repository not encrypted” Message

​Lost Password and Recovery Key

​Changing Password Doesn’t Work

​Recovery Key Format

​Unencrypted Repositories

​Next Steps

First Backup

Restoring Files

Automation

Check Command

Understanding Cloudstic Encryption

Key Slot Types

Creating a Repository with Encryption

Password-Based Encryption

Password + Recovery Key (Recommended)

Platform Key for Automation

Dual Access (Password + Platform Key)

Listing Key Slots

Adding a Recovery Key

Changing Your Password

Using Recovery Keys to Access Backups

Environment Variables for Credentials

Store-Level Encryption Configuration

Interactive Password Prompts

Advanced: AWS KMS Integration

Security Best Practices

Troubleshooting

”Could not open key slots” Error

“Repository not encrypted” Message

Lost Password and Recovery Key

Changing Password Doesn’t Work

Recovery Key Format

Unencrypted Repositories

Next Steps