# RSA Lockbox: Setup and Usage

RSA Lockbox is a customer-managed encryption key (CMEK) mode in Cloudback. You supply an RSA public key, and Cloudback encrypts each backup's password with it. Only you can decrypt those passwords using your private key.

## Prerequisites

* An RSA key pair (minimum 2048 bits) in PEM format.
* If you don't have one, see [Generating an RSA key pair](#generating-an-rsa-key-pair) below.

## How it works

1. **You provide your RSA public key.** The private key never leaves your infrastructure.
2. **For each backup,** Cloudback generates a unique random ZIP password and encrypts it with your public key using RSA-OAEP with SHA-256. Only the ciphertext is stored.
3. **To restore or download,** you paste your private key into a dialog. Cloudback decrypts the password in memory and never persists the private key.

This gives you full control over backup encryption: even if Cloudback were compromised, your archives stay protected without your private key.

## Setting up RSA Lockbox

### Step 1: Create an encryption key

1. Go to **Account Settings**.
2. Open the **Encryption Keys** section and click **Add Encryption Key**.
3. Select **RSA Lockbox** as the type.
4. Enter a name for the key (e.g., "Production RSA Key").
5. Paste your RSA **public key** in PEM format into the text area. It should look like:

   ```
   -----BEGIN PUBLIC KEY-----
   MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...
   -----END PUBLIC KEY-----
   ```
6. Click **Save**.

Cloudback validates that the key is a valid RSA key of at least 2048 bits before accepting it.

![New Encryption Key form](https://2781059148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQEI7SjBF2CddqNXZpCoE%2Fuploads%2Fgit-blob-81e1c3019cadcdbcb5e03eee9f63c91eee2c7a1e%2Fencryption-provider-new.png?alt=media)

### Step 2: Assign the key to your account

1. In the encryption key's settings, open the **Access** panel.
2. Check the accounts that should use this key.
3. Click **Save**.

A single key can be shared across multiple accounts.

![Encryption Key Access Editor](https://2781059148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQEI7SjBF2CddqNXZpCoE%2Fuploads%2Fgit-blob-912d302cd20c36238270cdf89aad807758b20f14%2Fencryption-provider-access.png?alt=media)

### Step 3: Activate the key

1. Go to **Account Settings** for the target account.
2. Under **Backup Encryption**, select your new RSA Lockbox key from the dropdown.
3. Click **Save**.

All future backups for this account will now be encrypted with your key. Existing backups are not affected.

![Account Settings - Backup Encryption dropdown](https://2781059148-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FQEI7SjBF2CddqNXZpCoE%2Fuploads%2Fgit-blob-a8f27b1c0077aa26a11ef511a13c3784a825c747%2Faccount-settings-encryption-dropdown.png?alt=media)

## Restoring or downloading a backup

When you restore or download a backup that was encrypted with RSA Lockbox, Cloudback will prompt you for your private key:

1. Click **Restore** or **Download** on the backup.
2. A dialog appears asking for your RSA private key.
3. Paste the private key in PEM format:

   ```
   -----BEGIN RSA PRIVATE KEY-----
   MIIEowIBAAKCAQEA...
   -----END RSA PRIVATE KEY-----
   ```

   Both PKCS#1 (`BEGIN RSA PRIVATE KEY`) and PKCS#8 (`BEGIN PRIVATE KEY`) formats are accepted.
4. Click **Submit**. Cloudback decrypts the backup password in memory and proceeds with the operation.

The private key is used only for the duration of the request and is never stored.

## Rotating your RSA key

If you need to replace your RSA key pair (e.g., for periodic rotation or after a suspected compromise), Cloudback supports re-encrypting all existing backup passwords with a new public key.

### Steps

1. Open the encryption key you want to rotate.
2. Replace the public key with your new public key.
3. Click **Save**.
4. If there are existing backups encrypted with the old key, Cloudback will open a **Re-encryption** dialog:
   * **Phase 1:** Choose whether to re-encrypt existing passwords, skip re-encryption, or cancel.
   * **Phase 2:** If you chose to re-encrypt, paste the **old private key** so Cloudback can decrypt the existing passwords.
   * **Phase 3:** Cloudback re-encrypts all passwords with the new public key. Progress is shown during the operation.
5. Once complete, all existing and future backups use the new key.

### What happens if you skip re-encryption?

* The public key on the provider is updated. Future backups use the new key.
* Existing backups remain encrypted with the old key. You will need the **old private key** to restore or download them.
* This means you must retain both the old and new private keys.

### Re-encryption details

* Passwords are re-encrypted in batches, within a single database transaction.
* If any row fails to decrypt (e.g., wrong private key), the entire operation rolls back and no changes are made.
* The old private key is held in server memory only for the duration of the re-encryption request.

## Deleting an encryption key

You can delete a custom encryption key only if there are **no active backups** encrypted with it. If backups still reference the key, the delete button is disabled.

To delete a key that has active backups:

1. Delete or let the retention policy expire the backups encrypted with that key.
2. Once no backups reference the key, it can be deleted.

## Generating an RSA key pair

If you don't already have an RSA key pair, you can generate one with OpenSSL:

```bash
# Generate a 4096-bit RSA private key
openssl genpkey -algorithm RSA -out private-key.pem -pkeyopt rsa_keygen_bits:4096

# Extract the public key
openssl rsa -pubout -in private-key.pem -out public-key.pem
```

Upload the contents of `public-key.pem` to Cloudback. Store `private-key.pem` securely - you will need it every time you restore or download a backup.

**Important:** If you lose your private key, any backups encrypted with the corresponding public key **cannot be recovered**. Store your private key in a secure location such as a hardware security module (HSM), a secrets manager, or an encrypted vault.

## Security considerations

* **RSA-OAEP with SHA-256** is used for all encryption operations. This is the recommended padding scheme for RSA encryption.
* **Minimum key size is 2048 bits.** We recommend 4096 bits for long-term protection.
* **Cloudback never stores your private key.** It exists in server memory only during restore, download, or re-encryption requests, and is discarded immediately after.
* **Key fingerprints** (first 16 hex characters of the SHA-256 hash of the public key) are recorded in the audit log for traceability, allowing you to verify which key was used without exposing the full key.

## Learn More

* [Encryption Overview](https://docs.cloudback.it/encryption-management/encryption-overview) - overview of all encryption modes
* [Password-Protected Archives](https://docs.cloudback.it/security-and-compliance/password-protected-archives) - AES-256 ZIP encryption details
* [Account Settings](https://docs.cloudback.it/managing-backups/account-settings) - configuring default settings per account
* [Audit Log](https://docs.cloudback.it/security-and-compliance/audit-log) - tracking all account activities