# Your data leaves. Your key stays.

> Understand AES-256-GCM backup encryption, local key generation, archive authentication, temporary files and the metadata CalmBackup can see.

Canonical page: https://www.calmbackup.com/security

Encryption happens on your machine, before upload. Understand the key, the encrypted file, and the boundary between your server and the service.

[Start free trial](https://app.calmbackup.com/register)

## Two credentials. Two different jobs.

Your API key authorizes requests for a backup source. Your encryption key makes the contents of your backups readable. They are separate values and are not interchangeable.

During CLI setup, CalmBackup generates 32 random bytes and stores their 64-character hexadecimal representation as the encryption\_key in your local configuration. The client derives the 32-byte AES key by hashing that configuration string with SHA-256.

### API key

Sent to the API to authenticate source requests, including uploads and downloads. Treat it as a secret account credential.

### Encryption key

Used locally to encrypt and decrypt archives. It is not included in the upload or confirmation API requests.

**Keep the generated key**

The derivation uses SHA-256, not a password-stretching function. Keep a randomly generated, high-entropy encryption key; do not replace it with a memorable word or a short password.

## What happens before a byte is uploaded.

The database dump and selected directories are first packaged into a compressed archive on the source machine. AES-256-GCM then transforms that archive into ciphertext.

AES-256 provides the encryption. GCM adds an authentication tag used to detect an invalid key or modified encrypted contents when the archive is decrypted. The client creates a fresh random 12-byte nonce for each encryption operation.

1.  ### Prepare the plaintext locally
    
    The client needs access to the readable database and files. Temporary dump and archive files are created locally during the backup process.
    
2.  ### Encrypt with AES-256-GCM
    
    The locally derived 256-bit key, a fresh random nonce, and the compressed archive are supplied to the encryption operation.
    
3.  ### Write a self-contained encrypted file
    
    A version header, nonce and authentication tag are stored alongside the ciphertext. The secret encryption key is not part of the file.
    
4.  ### Upload ciphertext
    
    The client uploads the .tar.gz.enc file. Transport security and archive encryption serve different purposes: the file remains encrypted after the transfer finishes.
    

## Inside an encrypted archive.

The CLI uses this ordered binary format. The nonce and authentication tag can travel with the archive; neither is a substitute for the encryption key.

| Field | Size | Purpose |
| --- | --- | --- |
| Version | 2 bytes | Identifies the archive encryption format (01 00). |
| Nonce / IV | 12 bytes | Fresh random input used for this encryption operation. |
| Authentication tag | 16 bytes | Checked during GCM decryption to authenticate the encrypted contents. |
| Ciphertext | Remaining bytes | The encrypted compressed database-and-files archive. |

**A checksum is a separate mechanism**

The client also calculates a SHA-256 checksum of the encrypted file and sends it as backup metadata. This checksum identifies file bytes; it is not the encryption key, a decryption capability, or proof that the application can be restored.

## What stays private. What the service can see.

The encryption boundary is the archive’s contents. Operating a backup service also requires metadata about the source and upload. Encryption does not make the existence or size of a backup invisible.

| Stays on the client / inside the encrypted archive | Visible to the service |
| --- | --- |
| Encryption key and derived AES key | Source identity and account association |
| Database contents and included file contents | Archive filename and byte size |
| Readable archive contents | Client-reported SHA-256 checksum |
| Local database credentials | Database driver, backup status and timestamps |

**Your source machine remains part of the trust boundary**

Encryption does not protect data from an attacker who already controls the running source machine or can read its configuration. Protect the host, local temporary storage and configuration permissions. Temporary-file cleanup is not a secure-erasure guarantee.

## Recovery starts with key custody.

Keep a secure copy of the encryption key in a separate password manager or another protected location outside the source machine. Check that the people responsible for recovery can access it when needed.

Changing the configured key affects future backups. It does not re-encrypt previous archives. Retain the matching old key for as long as you retain backups encrypted with it.

A login password reset or replacement API key cannot recreate a lost encryption key. If every copy of the encryption key is lost, the encrypted archives cannot be recovered through an account reset.

[Read the configuration and key guide](https://www.calmbackup.com/docs/configuration)

## Good questions.  
Clear answers.

Does CalmBackup decrypt my backups on the server?

The reviewed upload flow stores encrypted archives and metadata. Decryption is performed by the client using the key in its local configuration. The API does not receive that encryption key.

Is a successful decrypt the same as a tested restore?

No. Authenticated decryption establishes that the ciphertext can be opened with the key and passes the authentication check. You still need to import the database, restore files and test application behavior.

Can I rotate the key?

You can use a new key for subsequent backups, but old archives still require their original key. Keep a record that maps retained archives or date ranges to the appropriate recovery key.
