Guides

Set up and run CloudSign

Suggest Edits

1. Network architecture requirements

Set up your AWS environment with the following essential resources:

  • AWS SDK
  • Docker
  • EC2 machine

We also recommend setting up an IAM Role and Amazon KMS Key to enable the database to be encrypted securely using DB_ENCRYPTION_KEY_REF - see section 5 below.

2. Authenticate your AWS account

Palisade uses AWS IAM authentication for external facing cloud access. Export the following variables to authenticate your account:

export AWS_ACCESS_KEY_ID=
export AWS_SECRET_ACCESS_KEY=
export AWS_DEFAULT_REGION=eu-west-2

Please keep these variables confidential as they contain credentials that grant access to Palisade’s docker repository.

3. Login to Palisade’s docker repository

Once the environment variables for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are set, execute the following to login to the Palisade’s docker repository:

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

4. Pull the CloudSign docker image

docker pull 335650072995.dkr.ecr.eu-west-2.amazonaws.com/external/custody/cloudsign/app:1.5.1

5. Quick Start CloudSign (testing only)

Run the following command to start a CloudSign node in the foreground:

docker run -v /path/to/volume:/var/cloudsign -e DB_ENCRYPTION_KEY_HEX=YOUR_ENCRYPTION_KEY -e PAIRING_KEY=YOUR_PAIRING_KEY -e LOG_LEVEL=debug --rm --name cloudsign-node -it 335650072995.dkr.ecr.eu-west-2.amazonaws.com/external/custody/cloudsign/app:1.5.1

Replace /path/to/volume with your desired shard storage location.

Data is encrypted by default using the encryption key provided in DB_ENCRYPTION_KEY_HEX. This directory must be backed up and protected and the encryption key changed before first use.

Navigate to your Palisade dashboard and add a new CloudSign device, then use the generated PAIRING_KEY from the Palisade dashboard.

Note that this will run a CloudSign node in a container called cloudsign-node.

📘

We recommend using the DB_ENCRYPTION_KEY_REF in production with the ARN of the Amazon KMS key instead of the DB_ENCRYPTION_KEY_HEX as it provides a more secure way of handling the encryption secret. This approach ensures that all node data is encrypted using a physical HSM. Note that if you use this approach, your CloudSign node must have “encrypt” and “decrypt” permissions on Amazon KMS.

6. Run the CloudSign node

Run the CloudSign node using docker-compose script. The following example script runs 3 CloudSign nodes, on the basis that 3 CloudSign devices have been added in Palisade:

services: cloudsign1: image: 335650072995.dkr.ecr.eu-west-2.amazonaws.com/external/custody/cloudsign/app:1.5.1 container_name: cloudsign1 environment: DB_ENCRYPTION_KEY_HEX: ${ENCRYPTION_KEY_1} PAIRING_KEY: ${PAIRING_KEY_1} volumes: - ${VOLUME_1}:/var/cloudsign cloudsign2: image: 335650072995.dkr.ecr.eu-west-2.amazonaws.com/external/custody/cloudsign/app:1.5.1 container_name: cloudsign2 environment: DB_ENCRYPTION_KEY_HEX: ${ENCRYPTION_KEY_2} PAIRING_KEY: ${PAIRING_KEY_2} volumes: - ${VOLUME_2}:/var/cloudsign cloudsign3: image: 335650072995.dkr.ecr.eu-west-2.amazonaws.com/external/custody/cloudsign/app:1.5.1 container_name: cloudsign3 environment: DB_ENCRYPTION_KEY_HEX: ${ENCRYPTION_KEY_3} PAIRING_KEY: ${PAIRING_KEY_3} volumes: - ${VOLUME_3}:/var/cloudsign

It requires the ENCRYPTION_KEY, PAIRING_KEY and VOLUME suffixed by a number identifying the CloudSign node.

Example .env file configuration:

# cloudsign1

ENCRYPTION_KEY_1=c6516198ba86603e2fda776706b44373d5630cd2e89352772a9b75cda2df67ed PAIRING_KEY_1=eyJkZXZpY2VJZCI6ImQz...8ifQ== VOLUME_1=/tmp/cloudsign1

# cloudsign2

ENCRYPTION_KEY_2=0c92f60527b778f2f0036067429b3982d2c7f79ef657943f0e18c1e918362aa6 PAIRING_KEY_2=eyJkZXZpY2VJZCI6IjJm...8ifQ== VOLUME_2=/tmp/cloudsign2

# cloudsign3

ENCRYPTION_KEY_3=bf7e463d11347c486f4b8e79284a02e0543369009ff0d1efc1d2644fe63b21a7 PAIRING_KEY_3=eyJkZXZpY2VJZCI6Ijg5...8ifQ== VOLUME_3=/tmp/cloudsign3

Please note that directories defined in VOLUME_x environment variable need to exist before running the docker-compose script.

Network setup options

1. Single node setup

A single node setup is suitable in cases where you are one of the shard holders among other shard holders. It assumes that you are not holding the entire quorum yourself, i.e. hosting all of the CloudSign devices.

Here, we have one CloudSign instance running on an EC2 machine. The state is stored on a mounted EBS volume, on an encrypted disk. It has outbound connectivity through a NAT in a public subnet to the Palisade Platform as well as the MPC Messaging Layer. Please note that the NAT gateway here does not allow any inbound traffic.

2. Quorum setup

A quorum setup is suitable when you are holding all the shards of the quorum. The reference below lowers network risk and provides redundancy in case of loss or unavailability of some shards.

Here, we have a 2/3 quorum setup (two of the three CloudSign devices in the quorum are required to sign transactions). The setup of each individual CloudSign instance is no different than the single node setup described above.

Best practices

We strongly suggest adhering to the below best practices when setting up both single node and quorum networks:

  • Use separate AWS Accounts or Organizations to further segregate access and privileges for CloudSign
  • Use separate single purpose multi region replicated KMS keys for encrypting disks and EBS volumes
  • EC2 must not allow any inbound access (including SSH)
  • Ensure EC2 instances are using trusted AMIs
  • Ensure the EBS volumes are backed up securely using snapshots

Updated 6 days ago