Run CloudSign in AWS Nitro Enclaves

You can run CloudSign inside an AWS Nitro Enclave — an isolated compute environment with no persistent storage, no interactive access, and no direct network connectivity. The enclave isolates the CloudSign node and its key material from the host EC2 instance.

This guide assumes you have already created CloudSign devices and recorded their pairing keys. See Set up and run CloudSign.

A Nitro deployment has three components:

• CloudSign enclave image — The CloudSign node, packaged as an Enclave Image File (EIF) that runs inside the enclave.
• Networking proxy (tacos) — A systemd service on the host that tunnels the enclave's traffic between a virtual network interface and the enclave's vsock channel, because the enclave has no network interface of its own.
• Configuration server (servitor) — A small service on the host that serves the node's configuration to the enclave over HTTP on port 3000. The enclave fetches its configuration once at startup.

In Nitro mode, CloudSign requires a PostgreSQL database — the local storage option isn't available inside an enclave.

The EC2 instance requires no inbound network connectivity — the enclave only makes outbound connections through the host. You can apply firewall rules that block all inbound traffic to the instance.

• An EC2 instance with Nitro Enclaves enabled — for example, m5.xlarge — running Amazon Linux 2023.
• Docker, and the AWS Nitro Enclaves CLI (aws-nitro-enclaves-cli and aws-nitro-enclaves-cli-devel). Add your user to the docker and ne groups.
• The Nitro allocator (/etc/nitro_enclaves/allocator.yaml) configured with at least 1 GB of memory and 2 CPU cores. Restart the nitro-enclaves-allocator service after you change this file.
• Access credentials for the Wallet-as-a-Service container registry (provided by Ripple).
• A PostgreSQL database reachable from the host.
• An AWS KMS key ARN for database encryption (DB_ENCRYPTION_KEY_REF).
• A CloudSign pairing key from the console.

Sign in to the Wallet-as-a-Service container registry, then pull the Nitro image:

aws ecr get-login-password --region eu-west-2 | docker login --username AWS --password-stdin 335650072995.dkr.ecr.eu-west-2.amazonaws.com

docker pull 335650072995.dkr.ecr.eu-west-2.amazonaws.com/external/custody/cloudsign-nitro/app:<version>

Install socat, then install and start the tacos service. The proxy runs on the host and forwards the enclave's traffic on ports 8080 and 9080:

sudo yum install -y socat
sudo systemctl enable tacos.service --now

Wallet-as-a-Service distributes the tacos binary and its systemd unit file as release artifacts — your Ripple representative can point you to the download for your version.

Build the EIF from the Docker image:

nitro-cli build-enclave \
  --docker-uri 335650072995.dkr.ecr.eu-west-2.amazonaws.com/external/custody/cloudsign-nitro/app:<version> \
  --output-file ~/cloudsign-<version>.eif

Install the servitor binary (also distributed as a release artifact) to /usr/local/bin/servitor, then run it with the node's configuration:

PAIRING_KEY=<pairing-key> \
DB_ENCRYPTION_KEY_REF=<kms-key-arn> \
DB_DATA_SOURCE='postgres://user:password@host:5432/cloudsign?sslmode=require' \
TSM_DB_DATA_SOURCE='postgres://user:password@host:5432/cloudsign?sslmode=require' \
servitor

The server listens on port 3000 and serves the configuration to the enclave. SIGN_MODE_ACTIVE (default true) and LOG_LEVEL are optional.

Restart the proxy, then launch the enclave with the resources you allocated:

sudo systemctl restart tacos.service

nitro-cli run-enclave \
  --eif-path ~/cloudsign-<version>.eif \
  --cpu-count 2 \
  --memory 1024 \
  --enclave-cid 5

At startup, the enclave fetches its configuration from the host's configuration server and pairs with the platform. The device in the console moves to Waiting for approval, and setup continues as in the standard flow: approve the device, create a quorum, and create wallets.

To see the enclave's console output while debugging, add --attach-console to the run-enclave command.