# Configure backup and recovery

This guide covers everything you do **before** a disaster: understanding how Wallet-as-a-Service backups work, making the key decisions, setting up the infrastructure, preparing for disaster recovery, and maintaining your backups over time. As an owner or administrator, you are responsible for this setup and its upkeep.

When something goes wrong and you need to restore a corrupted node or recover wallets without the platform, use the [Disaster recovery](/pt-br/products/wallet/admin-guide/disaster-recovery) guide instead. For AWS specifics (policy JSON, ARNs, troubleshooting), see the [AWS backup infrastructure reference](/pt-br/products/wallet/user-interface/security-controls/wallet-backup-configuration).

## How backups work

You and your team don't perform backups yourselves. After you configure them, the platform runs them automatically:

1. For **every key created** under a quorum that has a backup kit assigned, Wallet-as-a-Service generates recovery data encrypted to **your RSA public key**. Each wallet key gets one backup, so an organization with a million wallets has a million backups.
2. Wallet-as-a-Service always writes the encrypted recovery data to a **Wallet-as-a-Service-managed S3 bucket**. If you configure your own AWS infrastructure, it writes an **additional copy to your S3 bucket** through an IAM role that Wallet-as-a-Service assumes. If you configure AWS KMS, Wallet-as-a-Service uses KMS for S3 server-side encryption of the object in your bucket.
3. Only you hold the RSA private key needed to decrypt the recovery data after you retrieve it from S3.


This design ensures that Wallet-as-a-Service never has unilateral access to your backup data: Wallet-as-a-Service encrypts every copy to your public key before it writes the copy. Recovery requires the RSA private key that you control. If the S3 object uses SSE-KMS, you also need AWS access to read and decrypt the object from the bucket before you run recovery.

Backups fail closed: if Wallet-as-a-Service can't write the recovery data to S3, wallet creation fails rather than producing an unbacked-up wallet. Wallet-as-a-Service doesn't retry, so re-request the wallet after you fix the storage issue. The upside is a guarantee: every active wallet under a backup-enabled quorum has a backup. A failed write can still leave some `recovery_shard` files behind in either bucket, so you might find backup folders for key IDs that never became wallets. Check folders against your wallet inventory rather than treating every folder as a wallet.

When you combine a backup with the [Wallet-as-a-Service Wallet Recovery CLI](https://github.com/palisadeinc/wallet-recovery-cli), you can **eject the raw private key** for a wallet and sign transactions with it directly, without any Wallet-as-a-Service infrastructure. This capability is what makes [recovery independent of Ripple](/pt-br/products/wallet/admin-guide/disaster-recovery) possible.

## Key decisions

### Own S3 bucket or managed storage only

When you create a backup kit, you choose between two storage configurations. **Ripple recommends Use own AWS configuration** because it's the only option that lets you recover without Ripple.

| Option | Where backups live | Recovery independent of Ripple? |
|  --- | --- | --- |
| **Use own AWS configuration** (**Recommended**) | The managed bucket **plus** your own S3 bucket | **Yes**. You can retrieve and recover backups without any involvement from Ripple. |
| **Wallet-as-a-Service AWS configuration** (default) | Only the Wallet-as-a-Service-managed bucket | No. You currently have no self-service way to retrieve backup files from the managed bucket. |


You need your own bucket for Ripple-independent recovery
If your disaster recovery plan requires recovering assets without Ripple's involvement, select **Use own AWS configuration** so that Wallet-as-a-Service writes a copy of every backup to a bucket you control. Make this choice before you create quorums. You can't add or change a kit's S3 configuration after you create the kit, and you can't change a quorum's kit after you create the quorum.

### Recovery key custody

Decide who holds the recovery private key and where to store it. Common approaches:

| Approach | Pros | Cons |
|  --- | --- | --- |
| HSM-protected storage | Tamper-resistant custody of a wrapping key, auditable access | The recovery CLI reads the private key from a file and has no HSM integration, so you can't use a non-exportable HSM key directly. Instead, keep the recovery private key encrypted under a non-exportable wrapping key in the HSM and unwrap it to a file at recovery time. You build and maintain that tooling. |
| Encrypted offline storage (USB, air-gapped machine) | Low cost, simple | Relies on physical security |
| Split across multiple custodians | No single point of failure | Coordination required for recovery |


A backup kit can hold multiple recovery public keys, and each wallet gets a separate recovery file for each one. Any single key is sufficient for recovery. For resilience, consider generating several key pairs on geographically separate, isolated machines and adding all their public keys to the kit.

Store the private key securely
If you lose the recovery private key, you can't decrypt backups. Never store it on the same systems or accounts that hold the backups.

### Environment separation

Use separate AWS infrastructure for sandbox and production backups:

- Different S3 buckets
- Different IAM roles
- Different KMS keys
- Different recovery key pairs (recommended)


This prevents a sandbox misconfiguration from affecting production backups.

## Set up backups

The setup has four steps across three surfaces. The [AWS backup infrastructure reference](/pt-br/products/wallet/user-interface/security-controls/wallet-backup-configuration) provides the commands, policy JSON, and troubleshooting for each step. This table tells you what each step is for.

| Step | What you do | Where | Details |
|  --- | --- | --- | --- |
| 1. Generate a recovery key pair | Create an RSA-4096 key pair with the recovery CLI's `generate-recovery-keypair` command (optionally password-protecting the private key with `--encrypt-private-key`) or with OpenSSL. Upload the public key to Wallet-as-a-Service; store the private key offline. Use `validate-private-key` to confirm the password works. | Your workstation | [Key generation](/pt-br/products/wallet/user-interface/security-controls/wallet-backup-configuration#prerequisites-generate-recovery-key-pairs) |
| 2. Create an S3 bucket | Create a bucket with versioning, KMS encryption, and a bucket policy that enforces TLS and encryption. | Your AWS account | [Bucket setup](/pt-br/products/wallet/user-interface/security-controls/wallet-backup-configuration#step-1-create-the-s3-bucket) |
| 3. Create an IAM role | Create a role that Wallet-as-a-Service's MPC service can assume, with permissions to write to your bucket and use your KMS key. | Your AWS account | [IAM role setup](/pt-br/products/wallet/user-interface/security-controls/wallet-backup-configuration#step-2-create-the-iam-role-for-s3-access) |
| 4. Create the backup kit | Enter a name, upload your public keys (up to five per kit), then select **Use own AWS configuration** and enter your bucket name, role ARN, region, external ID, and KMS key ARN. Wallet-as-a-Service validates the AWS configuration before it saves the kit (pre-flight validation). | **Settings** > **Backup & Recovery** > **Manage backups** > **Create backup** | [Console fields and pre-flight](/pt-br/products/wallet/user-interface/security-controls/wallet-backup-configuration#step-3-configure-in-wallet-as-a-service-ui) |


After setup, apply the [security hardening checklist](/pt-br/products/wallet/user-interface/security-controls/wallet-backup-configuration#security-best-practices-checklist) in the reference: CloudTrail data events, S3 Object Lock, minimal IAM permissions, MFA Delete, and CloudWatch alarms.

## Assign the kit and verify

Assign the backup kit to an MPC quorum **during quorum creation**. Wallet-as-a-Service backs up only quorums created with an assigned backup kit, and you can't add, remove, or change the kit later through quorum restructuring. See [Manage MPC quorums](/pt-br/products/wallet/admin-guide/manage-mpc-quorums).

Mixed quorums have no key shard backups
Wallet-as-a-Service doesn't back up wallets in a **Mixed** quorum. The console doesn't offer a backup kit when you create a Mixed quorum, and CloudSign devices generate recovery data only in Cloud quorums. Without a backup, you can't use the recovery CLI to recover a Mixed quorum wallet. If you need key shard backups, create a Cloud or Mobile quorum and assign a backup kit to it.

Then verify the pipeline end to end:

1. Create a wallet using the quorum.
2. Check your S3 bucket for backup files in the expected folder structure (`<key_id>/recovery_shard-*.txt`, where the key ID is the wallet ID). See the [data structure reference](/pt-br/products/wallet/user-interface/security-controls/wallet-backup-configuration#data-structure) for what the files contain.
3. Confirm CloudTrail logged the write operation.


## Prepare for disaster recovery

Backups alone don't make you recoverable. You must complete everything in this checklist **while the platform is available**. If you skip these steps, your backups might be unrecoverable when you need them.

- [ ] **Configure your own S3 bucket** (above). Without the platform, you can't retrieve backups that exist only in the managed bucket.
- [ ] **Download the recovery CLI now.** Download the [Wallet-as-a-Service Wallet Recovery CLI](https://github.com/palisadeinc/wallet-recovery-cli/releases) binary for your platform (or build it from source with Go) and store it offline alongside your recovery materials. Don't assume you can download it during a disaster.
- [ ] **Secure the recovery private key** according to your [custody decision](#recovery-key-custody), and record its password in a secure location such as a password manager or vault. Periodically [verify the key](/pt-br/products/wallet/admin-guide/disaster-recovery#verify-your-recovery-private-key) with `wallet-recovery-cli validate-private-key`. The command tests decryption without modifying the file.
- [ ] **Maintain an offline wallet inventory.** The `recover` command requires the quorum ID, key ID, and key type for each wallet, and the **backup files don't store the quorum ID anywhere**, so without your inventory, you can't recover wallets from the backups alone. Keep a CSV file or secure database with these columns, and store it somewhere you can access without the platform (an encrypted file on your own infrastructure, a hardware-encrypted drive, or a secrets manager):
| Column | Description | Example |
|  --- | --- | --- |
| `key_id` | Wallet key UUID (same as the wallet ID) | `a1b2c3d4-...` |
| `quorum_id` | Quorum UUID the wallet belongs to | `e5f6a7b8-...` |
| `key_type` | Key algorithm | `SECP256K1` or `ED25519` |
| `blockchain` | Blockchain name | `ethereum`, `solana`, `bitcoin` |
| `address` | Wallet address on chain | `0x1234...` |
The wallets list API (`POST /v2/wallets:list`) returns the wallet ID, quorum ID, and key algorithm for every wallet. The API paginates the response: follow `filter.nextPageToken` until it's empty, or your inventory silently omits wallets. Refresh the inventory whenever you create wallets. In the console, the quorum's detail page shows the quorum ID.
- [ ] **Record where Wallet-as-a-Service stores your backups.** Note the S3 bucket name, region, and, if you use SSE-KMS, which AWS credentials can read and decrypt the objects.
- [ ] **Prepare an air-gapped machine.** Recovery ejects a raw private key; plan to run it on a machine with no network connection, with the CLI binary already installed.
- [ ] **Rehearse in sandbox.** Run the full [recovery procedure](/pt-br/products/wallet/admin-guide/disaster-recovery#recover-wallets-independently-of-ripple) against a sandbox wallet at least annually, and make sure the team members responsible know where you store the recovery keys and inventory. There's no dry-run mode. A test recovery produces a live private key, so securely destroy it afterward, just as you would in a real recovery.


## Maintain your backups

Backups aren't one-time configurations. Maintain them throughout the life of your organization:

| Event | Required action |
|  --- | --- |
| **Key reshare or quorum restructure** | You don't need to take any action on key shard backups, and you can't. Resharing and restructuring replace the key shards without changing the wallet's underlying key, and Wallet-as-a-Service binds each backup file to the wallet's key ID and quorum ID, neither of which changes. The backup file doesn't store the quorum ID, so keep it in your [offline wallet inventory](/pt-br/products/wallet/admin-guide/configure-backup-and-recovery#prepare-for-disaster-recovery). Wallet-as-a-Service can't regenerate a key shard backup for an existing key. Take fresh CloudSign node backups after every reshare or restructure, and never restore a node snapshot taken before one. See [Disaster recovery](/pt-br/products/wallet/admin-guide/disaster-recovery#restore-a-cloudsign-node-database). |
| **Personnel change** | If the person who held the recovery key leaves, create a new backup kit with the new recovery public key for future quorums. You can't update existing quorums to use a different backup kit, so plan migration or replacement with Ripple support if you must retire that key. |
| **Shard-holding device permanently lost** | You don't need to take any backup action. Replace the device by restructuring the quorum. See [Replace a lost shard-holding device](/pt-br/products/wallet/admin-guide/disaster-recovery#replace-a-lost-shard-holding-device). Key shard backups stay valid, because the wallet key doesn't change. |
| **Annual review** | [Verify your recovery private key](/pt-br/products/wallet/admin-guide/disaster-recovery#verify-your-recovery-private-key) still decrypts with the password you hold. Rehearse a recovery in sandbox. Confirm your offline wallet inventory is up to date. Without it, you can't recover wallets if the platform is unavailable. |


Ongoing best practices:

- **Monitor backup creation**: Use CloudTrail logs to confirm Wallet-as-a-Service writes backups to S3 as expected.
- **Set retention policies:** configure S3 lifecycle rules to manage backup retention, but always keep the most recent backup, and never add rules that could transition or expire recovery data you still need.
- **Document your backup architecture**: Record which S3 buckets, IAM roles, and KMS keys each environment uses, and who has access to the recovery private key.


## Back up CloudSign node databases

Key shard backups are one of two backup layers. The other is operational: each CloudSign node stores its encrypted key shards in a local embedded database (under `/var/cloudsign`) or in PostgreSQL. Back up this data regularly (for example, with encrypted EBS snapshots or standard PostgreSQL backups), and always take a backup before you upgrade a node. These backups protect against failed upgrades and database corruption without requiring key recovery.

See [Set up and run CloudSign](/pt-br/products/wallet/user-interface/devices/set-up-and-run-cloudsign#storage-options) for storage options, and [Disaster recovery](/pt-br/products/wallet/admin-guide/disaster-recovery#restore-a-cloudsign-node-database) for the restore procedure and its constraints.

## Related guides

- [Disaster recovery](/pt-br/products/wallet/admin-guide/disaster-recovery): Restore a node database or recover wallets when something has gone wrong
- [AWS backup infrastructure reference](/pt-br/products/wallet/user-interface/security-controls/wallet-backup-configuration): Policy JSON, ARNs, key generation commands, pre-flight details, and troubleshooting
- [Manage MPC quorums](/pt-br/products/wallet/admin-guide/manage-mpc-quorums): Assign backup kits to quorums