> For the complete documentation index, see [llms.txt](https://docs.cloudback.it/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cloudback.it/encryption-management/customer-held-rsa-lockbox.md). # Customer-Held RSA Lockbox: Setup and Usage Customer-Held 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. The encrypted password is stored as a `.lockbox` file beside the backup archive in your own backup storage. Only you can decrypt the archive password using your private key. Cloudback never stores your private key. ## Prerequisites * An RSA key pair (minimum 2048 bits) in PEM format. * Backup storage connected to the Cloudback account where you will select this provider. * If you don't have an RSA key pair, 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. 3. **Cloudback stores the encrypted password in your backup storage** as a `.lockbox` sidecar file beside the archive. For example, `repo-2026-05-19.zip` has a sidecar file named `repo-2026-05-19.zip.lockbox`. 4. **To restore or download,** you paste the private key that matches the backup. Cloudback downloads the `.lockbox` file, decrypts the password in memory, and never persists the private key. This gives you control over both the private key and the encrypted password location. If Cloudback were compromised, your archives stay protected without your private key and the matching `.lockbox` sidecar file. ## Setting up Customer-Held RSA Lockbox ### Step 1: Create an encryption provider 1. Go to **Encryption** in the left navigation. 2. Click **Add Encryption Provider**. 3. Enter a name for the provider (e.g., "Production Customer-Held RSA Key"). 4. Under **Provider Type**, select **Customer-Held RSA Lockbox**. 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. ### Step 2: Set provider access 1. Return to **Encryption**. 2. In the provider row, click **Edit Access**. 3. Check the accounts that should be allowed to use this provider. 4. Click **Save**. A single provider can be made available to multiple accounts. ### Step 3: Select the provider for backups 1. Go to **Account Settings** for the target account. 2. Under **Backup Encryption**, select your new Customer-Held RSA Lockbox provider from the dropdown. 3. Click **Save**. All future backups for this account will now use the selected provider. Existing backups are not affected. ## Restoring or downloading a backup When you restore or download a backup that was encrypted with Customer-Held RSA Lockbox, Cloudback will prompt you for the private key that matches that backup: 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 downloads the backup's `.lockbox` sidecar file, decrypts the archive password in memory, and proceeds with the operation. The private key is used only for the duration of the request and is never stored. The `.lockbox` sidecar file must still exist in backup storage for restore or download to work. ## Decrypting a lockbox file manually If you have downloaded a backup archive and its `.lockbox` sidecar file, you can decrypt the archive password outside Cloudback with OpenSSL. You need the private key that matches the public key used when the backup was created. ```bash base64 -D -i "$lockbox_file" \ | openssl pkeyutl -decrypt \ -inkey "$private_key" \ -pkeyopt rsa_padding_mode:oaep \ -pkeyopt rsa_oaep_md:sha256 ``` The decrypted output is the ZIP archive password. Treat it as a secret, and avoid saving it in shell history, logs, or shared terminal output. ## Rotating your RSA key If you need to replace your RSA key pair (e.g., for periodic rotation or after a suspected compromise), update the public key on the Customer-Held RSA Lockbox provider. Customer-Held RSA Lockbox does **not** re-encrypt existing `.lockbox` files. Changing the public key affects future backups only. ### Steps 1. Generate a new RSA key pair. 2. Open the encryption provider you want to update. 3. Replace the public key with your new public key. 4. Click **Save**. Future backups use the new public key. Existing backups remain encrypted with the old public key and still require the old private key. ### What happens to existing backups? * Existing `.lockbox` files are not changed. * Existing backups require the private key that matched the public key active when those backups were created. * You must retain old private keys until all backups encrypted with those keys have been deleted or expired by retention. ## Deleting an encryption provider You can delete a custom encryption provider only if there are **no active backups** protected by it. If backups still reference the provider, the delete button is disabled. To delete a provider that has active backups: 1. Delete or let the retention policy expire the backups protected by that provider. 2. Once no backups reference the provider, it can be deleted. Deleting a backup also deletes its `.lockbox` sidecar file from backup storage. ## 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 encrypted with this key. **Important:** If you lose your private key, any backups encrypted with the corresponding public key **cannot be recovered**. If the matching `.lockbox` file is deleted or moved from backup storage, that backup also cannot be restored or downloaded. ## Security considerations * **RSA-OAEP with SHA-256** is used for all encryption operations. * **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 or download requests, and is discarded immediately after. * **Encrypted passwords are stored in your backup storage.** Each backup has a `.lockbox` sidecar file beside the archive it unlocks. * **Existing `.lockbox` files are not re-encrypted during key rotation.** Keep old private keys for old backups. * **Cloudback does not log plain archive passwords, private keys, or decrypted secrets.** * **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](/encryption-management/encryption-overview.md) - overview of all encryption modes * [RSA Lockbox: Setup and Usage](/encryption-management/rsa-lockbox.md) - database-stored RSA Lockbox variant * [Password-Protected Archives](/security-and-compliance/password-protected-archives.md) - AES-256 ZIP encryption details * [Account Settings](/managing-backups/account-settings.md) - configuring default settings per account * [Audit Log](/security-and-compliance/audit-log.md) - tracking all account activities --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cloudback.it/encryption-management/customer-held-rsa-lockbox.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.