Skip to main content

Deploying on AWS Nitro

This deployment uses m5.xlarge instances, and the enclave runs in debug mode so that the serial console is accessible. In debug mode the attestation document reports all-zero values for some measurements, so this is not a production configuration.

This assumes an AWS account is already set up, with billing enabled.

Install the AWS CLI

The deployment uses the AWS CLI. Install it from here.

Configure credentials

Use AWS IAM Identity Center (SSO) if your organization has it:

aws configure sso

It asks for your SSO start URL and region, then lets you pick the account and role. Name the profile after your project, <your-project> below. Log in and confirm which account you landed in:

aws sso login --profile <your-project>
aws sts get-caller-identity --query Account --output text

Export the profile in every shell you deploy from. OpenTofu reads it the same way the CLI does:

export AWS_PROFILE=<your-project>

Check the account before every tofu apply. The provider pins the region, not the account, so a leftover AWS_PROFILE silently targets the wrong one and fails late, typically as InvalidSubnetID.NotFound while creating instances.

Without SSO: IAM access keys

If the account has no Identity Center, use an IAM user's access keys instead (IAM → Users → your user → Security credentials → Create access key) and put them in ~/.aws/credentials:

[default]
aws_access_key_id = XXXXXXXXXXXXXXXXXXXX
aws_secret_access_key = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

If you put your credentials under a profile other than default, set AWS_PROFILE and verify which account you are in:

export AWS_PROFILE=<your-profile>
aws sts get-caller-identity --query Account --output text

Install OpenTofu

We will use OpenTofu, an infrastructure-as-code tool and open-source fork of Terraform.

Install it by following the official instructions

Note: We have tested this tutorial with OpenTofu v1.9.1 (linux_amd64).

Verify:

tofu -version

Clone trio-on-aws-nitro repo and go to the tf directory

git clone https://github.com/silence-laboratories/trio-on-aws-nitro.git
cd trio-on-aws-nitro/deploy/aws/tf

Configure the environment

Create your global.tfvars by copying the example config:

cp global-example.tfvars global.tfvars

Set the region

In global.tfvars, set region to the AWS region you want to deploy into. Choose one close to your users to keep latency low, or leave the default. See Available regions and zones.

Bootstrap KMS part 1

In a production environment, the KMS should be set up by separate AWS Account such that the Cloud Node admin would not be able to reach it and change its configuration.

Go to the bootstrap-kms-1 directory and apply the config by using tofu.

# In bootstrap-kms-1 directory
tofu init
tofu apply -var-file=../global.tfvars

The command will ask you to review the changes that are going to be applied. If everything is correct, type yes and hit enter. The script will create a key used as KEK by the Cloud Nodes.

Bootstrap Cloud Nodes

Generate SSH key

In secret place, generate secret SSH key used to connect to the VM instances:

aws ec2 create-key-pair \
  --key-name aws-key-pair \
  --key-type rsa \
  --key-format pem \
  --query "KeyMaterial" \
  --region <REGION AS IN global.tfvars> \
  --output text > aws_key_pair.pem

Write public key to trio-on-aws-nitro/deploy/aws/tf/bootstrap-cloud-node/aws_key_pair.pub:

# In bootstrap-cloud-node directory
openssl rsa -in /path/to/secret/aws_key_pair.pem -pubout | ssh-keygen -f /dev/stdin -i -m PKCS8 > aws_key_pair.pub

Provide Auth Service (Auth0) configuration

This deployment authenticates users with Auth0. The Auth Service configuration (AUTH0_DOMAIN, AUTH0_AUDIENCE, and the FaceTec / Helius keys used by the sample backend) is templated into the node config under deploy/aws/tf/bootstrap-cloud-node/templates/, and copied to the AWS Secrets Manager in the next step so the Auth Service can fetch it at startup.

The templates ship placeholders. Reach out to us for the Auth0, FaceTec and Helius values, since the sample mobile app is built to sign in against our Auth0 configuration. Using your own Auth0 account means rebuilding the app with matching settings.

Apply config

Go to the bootstrap-cloud-node directory and apply the config by using tofu.

# In bootstrap-cloud-node directory
tofu init
tofu apply -var-file=../global.tfvars

This step will read key from bootstrap-kms-1, bootstrap resources like iam_role, S3 Bucket, and resource policies, network configuration. Tofu will also read aws_key_pair.pub file, so make sure previous step was done correctly.

Bootstrap KMS part 2

Go to the bootstrap-kms-2 directory and apply the config by using tofu.

# In bootstrap-kms-2 directory
tofu init
tofu apply -var-file=../global.tfvars

The crucial part of KMS bootstrap is the Key Policy configuration. Our script puts this simple assertion:

Condition = {
    StringEqualsIgnoreCase = {
      "kms:RecipientAttestation:ImageSha384" =  "...",
      ...
    }

}
Effect = "Allow"

It can be read as: Grant access to KMS only if the running VM's software provides Attestation Document with specified measurements. The measurements relates to enclave image hash, the key used during image signing, etc.

Share the AWS Account details with us

Our team will grant that Account access to the Amazon Machine Image (AMI). This will allow you to launch VMs with our software configured.

Start Cloud Nodes

Once the AMI access is granted (previous step). Go to the cloud-node directory and apply the config by using tofu.

# In cloud-node directory
tofu init
tofu apply -var-file=../global.tfvars

Similarly to the previous run, review the changes that are going to be applied. If everything is right, type yes and hit enter.

It reads state from bootstrap-cloud-node and launches the two EC2 instances and their Nitro enclaves. This is a debug launch that allows you to connect to the serial console and see the output of the operating system and the container.

We provide production-ready AMIs. In such case, there is no serial console access to the Nitro enclave, and the attestation document contains non-zero values.

Congrats! The backend is ready!

Monitor Cloud Node

SSH to the VM instance using the SSH key generated previously.

# In deploy/aws/tf/bootstrap-cloud-node, where the SSH key was generated
ssh -i aws_key_pair ec2-user@<CLOUD_NODE_IP>

Verify the services are running:

sudo systemctl status

The state should be running. If it is not, reach out to us for assistance.

When enclave runs in debug mode, it is possible to connect to the console:

nitro-cli console --enclave-name trio_node_nitro