Wallet backup configuration

This guide provides instructions for configuring AWS S3 buckets to securely store encrypted Palisade wallet backup files. The setup ensures your encrypted recovery shards are stored with enterprise-grade security while maintaining controlled access for the Palisade MPC (Multi-Party Computation) service to write backups when needed.

This backup process works with MPC quorums to ensure key recovery.

Architecture overview

Your S3 bucket stores encrypted wallet backups in a specific folder structure, with AWS IAM roles controlling access. The Palisade MPC service assumes a role in your AWS account to write encrypted backup files, ensuring you maintain full ownership and control of your data.

Data structure

your-backup-bucket/
├── <key_id_1>/
│   ├── recovery_shard-0.txt
│   ├── recovery_shard-1.txt
│   └── recovery_shard-2.txt
└── <key_id_2>/
    ├── recovery_shard-0.txt
    └── recovery_shard-1.txt

Prerequisites: Generate recovery key pairs

Before setting up your backup strategy, generate RSA-4096 recovery key pairs using either the Palisade Wallet Recovery CLI (recommended) or OpenSSL.

Key format requirements

Public key files you upload to Palisade must be:

• RSA-4096 public keys
• DER encoded (PKIX/SubjectPublicKeyInfo format)
• Either binary DER format OR hex-encoded text (auto-detected)

Option 1: Using the Palisade Wallet Recovery CLI (recommended)

For key generation, validation, and wallet recovery, use the Palisade Wallet Recovery CLI:

Repository: https://github.com/palisadeinc/wallet-recovery-cli

The CLI provides commands for:

• generate-recovery-keypair - Generate RSA-4096 recovery key pairs
• validate-private-key - Validate private key files
• recover - Recover wallets from encrypted backups

See the wallet-recovery-cli README for complete documentation.

Option 2: Using OpenSSL (manual generation)

If you cannot use the Palisade CLI, generate keys using OpenSSL:

# Step 1: Generate an RSA-4096 private key
openssl genrsa -out recovery-private.pem 4096

# Step 2: Extract the public key in binary DER format
openssl rsa -in recovery-private.pem -pubout -outform DER -out recovery-public.der

# Step 3: Securely store the private key (convert to DER and optionally encrypt)
openssl rsa -in recovery-private.pem -outform DER -out recovery-private.der

Upload recovery-public.der (the binary DER file) to the Palisade UI. The UI auto-detects the format.

xxd -p recovery-public.der | tr -d '\n' > recovery-public.hex

Verify your key files

Before uploading, verify your public key file is in the correct format:

# Check file size
wc -c recovery-public.der
# Expected output for binary DER: 550 recovery-public.der
# Expected output for hex-encoded: 1100 recovery-public.der

# Check file type
file recovery-public.der
# Binary DER output: recovery-public.der: data
# Hex-encoded output: recovery-public.der: ASCII text, with very long lines, with no line terminators

# For binary DER, check it starts with ASN.1 SEQUENCE tag (0x30)
xxd recovery-public.der | head -1
# Expected: 00000000: 3082 0222 300d 0609 2a86 4886 f70d 0101  0.."0...*.H.....

# For hex-encoded, check content starts correctly
head -c 50 recovery-public.der
# Expected: 30820222300d06092a864886f70d01010105000382020f00

Step 1: Create the S3 bucket

1. Create a new S3 bucket with a descriptive name (e.g., company-palisade-wallet-backups).
2. Enable versioning to protect against accidental overwrites.
3. Create a KMS Customer Managed Key (CMK) for encryption, or use an existing one.
4. Enable default encryption with AWS KMS (SSE-KMS):

{
  "BucketEncryption": {
    "ServerSideEncryptionConfiguration": [
      {
        "ServerSideEncryptionByDefault": {
          "SSEAlgorithm": "aws:kms",
          "KMSMasterKeyID": "arn:aws:kms:REGION:ACCOUNT:key/KEY-ID"
        },
        "BucketKeyEnabled": true
      }
    ]
  }
}

5. Set bucket ownership and block public access:

   • Enable "Block Public Access" for this bucket
   • Set Object ownership to "Bucket owner enforced" to disable ACLs

6. Add a bucket policy to enforce TLS, KMS encryption, and block public access:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DenyInsecureTransport",
      "Effect": "Deny",
      "Principal": "*",
      "Action": "s3:*",
      "Resource": [
        "arn:aws:s3:::your-backup-bucket",
        "arn:aws:s3:::your-backup-bucket/*"
      ],
      "Condition": { "Bool": { "aws:SecureTransport": "false" } }
    },
    {
      "Sid": "DenyUnencryptedObjectUploads",
      "Effect": "Deny",
      "Principal": "*",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::your-backup-bucket/*",
      "Condition": {
        "StringNotEquals": { "s3:x-amz-server-side-encryption": "aws:kms" }
      }
    },
    {
      "Sid": "DenyWrongKmsKey",
      "Effect": "Deny",
      "Principal": "*",
      "Action": "s3:PutObject",
      "Resource": "arn:aws:s3:::your-backup-bucket/*",
      "Condition": {
        "StringNotEquals": {
          "s3:x-amz-server-side-encryption-aws-kms-key-id": "arn:aws:kms:REGION:ACCOUNT:key/KEY-ID"
        }
      }
    }
  ]
}

7. Configure lifecycle policies for backup retention:

{
  "Rules": [
    {
      "Id": "RetainBackupsAndVersions",
      "Status": "Enabled",
      "NoncurrentVersionExpiration": {
        "NoncurrentDays": 90
      },
      "AbortIncompleteMultipartUpload": {
        "DaysAfterInitiation": 7
      }
    }
  ]
}

Step 2: Create the IAM role for S3 access

Create an IAM role named PalisadeS3BackupRole (or similar) with the following configuration:

Permission policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowS3BackupWrites",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:AbortMultipartUpload"
      ],
      "Resource": "arn:aws:s3:::your-backup-bucket/*",
      "Condition": {
        "StringEquals": {
          "s3:x-amz-server-side-encryption": "aws:kms",
          "s3:x-amz-server-side-encryption-aws-kms-key-id": "arn:aws:kms:REGION:ACCOUNT:key/KEY-ID"
        }
      }
    },
    {
      "Sid": "AllowS3BucketList",
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket"
      ],
      "Resource": "arn:aws:s3:::your-backup-bucket"
    },
    {
      "Sid": "AllowKMSEncryption",
      "Effect": "Allow",
      "Action": [
        "kms:GenerateDataKey",
        "kms:Encrypt",
        "kms:DescribeKey"
      ],
      "Resource": "arn:aws:kms:REGION:ACCOUNT:key/KEY-ID"
    },
    {
      "Sid": "AllowStsGetCallerIdentity",
      "Effect": "Allow",
      "Action": "sts:GetCallerIdentity",
      "Resource": "*"
    }
  ]
}

Trust relationship policy

For sandbox environment (app.sandbox.palisade.co)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::187316130931:user/mpc-service"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

For production environment (app.palisade.co)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::663932549156:user/mpc-service"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

Enhanced security with External ID (optional)

For additional security, require an External ID in your trust policy. This prevents the "confused deputy" problem where other AWS accounts might try to assume your role.

When you configure an External ID in the Palisade UI, the MPC service includes it when assuming your role. Your trust policy can then require this specific External ID:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::663932549156:user/mpc-service"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "sts:ExternalId": "your-unique-external-id"
        }
      }
    }
  ]
}

Step 3: Configure in Palisade UI

After creating your S3 bucket and IAM role, configure the backup strategy in the Palisade dashboard.

Navigate to Settings → Backup & Recovery and enter the following:

Pre-flight validation

When you save your backup configuration, Palisade automatically validates that:

1. The MPC service can assume the specified IAM role
2. The role has permission to write to the S3 bucket
3. If an External ID is configured, it's accepted by the trust policy
4. If a KMS Key ARN is configured, the role can use it for encryption

This validation happens before Palisade provisions any wallets, ensuring you discover configuration issues immediately rather than during wallet creation.

ARN format reference

Step 4: Advanced security configuration (optional)

Enable CloudTrail logging

{
  "EventSelectors": [
    {
      "ReadWriteType": "All",
      "IncludeManagementEvents": false,
      "DataResources": [
        {
          "Type": "AWS::S3::Object",
          "Values": ["arn:aws:s3:::your-backup-bucket/*"]
        }
      ]
    }
  ]
}

Configure S3 Object Lock (for immutable backups)

{
  "ObjectLockEnabled": "Enabled",
  "Rule": {
    "DefaultRetention": {
      "Mode": "COMPLIANCE",
      "Days": 30
    }
  }
}

Security best practices checklist

• Encryption at rest: Default SSE-KMS with your CMK enforced at bucket and IAM policy
• Encryption in transit: Bucket policy enforces SSL/TLS connections
• Access control: IAM role with minimal required permissions
• KMS permissions: Role has kms:GenerateDataKey and kms:Encrypt on your CMK
• External ID: Configure an External ID for enhanced role assumption security
• Versioning: Enabled to protect against accidental overwrites
• Logging: CloudTrail and S3 access logging enabled
• Monitoring: CloudWatch alarms configured
• Backup retention: Lifecycle policies configured
• MFA Delete: Consider enabling for production buckets

Troubleshooting

Access denied errors

Encryption errors

Role assumption failures

Invalid ARN format in Palisade UI

Pre-flight validation failures

When saving a backup configuration, you may see validation errors:

Public key validation errors

Invalid format or file rejected on upload

The UI validates public key files on upload. Common causes of rejection:

Key too small or key rejected after upload

This error means your public key is smaller than RSA-4096. Common causes:

Quick diagnostic

Run this command to check your key file:

file your-public-key.der && wc -c your-public-key.der

Expected output for valid RSA-4096 keys:

# Binary DER format (550 bytes):
your-public-key.der: data
550 your-public-key.der

# Hex-encoded format (1100 characters):
your-public-key.der: ASCII text, with very long lines, with no line terminators
1100 your-public-key.der

Wallet recovery process

For complete wallet recovery instructions, see the Palisade Wallet Recovery CLI documentation:

Repository: https://github.com/palisadeinc/wallet-recovery-cli

The recovery process involves:

1. Downloading the encrypted backup from your S3 bucket
2. Using the recover command with your recovery private key
3. Securely handling the recovered wallet private key

Appendix: Quick reference

Palisade AWS account IDs