implementing-aws-nitro-enclave-security

What this skill does

# Implementing AWS Nitro Enclave Security

## When to Use

- Processing sensitive data (PII, PHI, financial records, cryptographic secrets) that must be isolated from EC2 instance operators and administrators
- Building confidential computing pipelines where even root-level access on the parent instance cannot read enclave memory or state
- Implementing cryptographic attestation workflows that tie KMS decryption rights to a specific, verified enclave image hash
- Deploying multi-party computation environments where two or more enclaves authenticate each other via attestation before exchanging data
- Hardening existing workloads that currently decrypt secrets on the parent instance by migrating decryption into an enclave boundary

**Do not use** when the workload does not handle sensitive data that requires hardware-level isolation, when the instance type does not support Nitro Enclaves (requires Nitro-based instances with at least 4 vCPUs), or when latency constraints make the vsock communication overhead unacceptable.

## Prerequisites

- An AWS account with permissions to launch Nitro-capable EC2 instances (m5.xlarge or larger, C5, R5, M6i families)
- AWS CLI v2 and the `nitro-cli` toolset installed on the parent EC2 instance (Amazon Linux 2 or AL2023)
- Docker installed on the parent instance for building enclave image files (EIF)
- An AWS KMS symmetric key with key policy permissions for the enclave's IAM role
- The `aws-nitro-enclaves-sdk-c` or Python `aws-encryption-sdk` for enclave-side KMS operations
- The Nitro Enclaves allocator service configured with sufficient memory and vCPU allocation in `/etc/nitro_enclaves/allocator.yaml`

## Workflow

### Step 1: Configure the Nitro Enclaves Environment

Set up the parent EC2 instance to support enclave launches:

- **Install the Nitro Enclaves CLI**: On Amazon Linux 2, install the tools and allocator:
  ```bash
  sudo amazon-linux-extras install aws-nitro-enclaves-cli
  sudo yum install aws-nitro-enclaves-cli-devel -y
  sudo systemctl enable --now nitro-enclaves-allocator.service
  sudo systemctl enable --now docker
  sudo usermod -aG ne ec2-user
  sudo usermod -aG docker ec2-user
  ```
- **Configure memory and CPU allocation**: Edit `/etc/nitro_enclaves/allocator.yaml` to reserve resources for the enclave. The enclave requires dedicated memory that is carved from the parent instance:
  ```yaml
  ---
  memory_mib: 4096
  cpu_count: 2
  ```
  Restart the allocator: `sudo systemctl restart nitro-enclaves-allocator.service`
- **Verify setup**: Run `nitro-cli describe-enclaves` to confirm the CLI can communicate with the Nitro hypervisor. An empty JSON array `[]` indicates no enclaves are running and the setup is correct.

### Step 2: Build the Enclave Image File (EIF)

Package the sensitive workload into a signed enclave image:

- **Create the application Dockerfile**: The enclave runs a minimal Linux environment. The application communicates exclusively through vsock:
  ```dockerfile
  FROM amazonlinux:2

  RUN yum install -y python3 python3-pip && \
      pip3 install boto3 cbor2 cryptography requests

  COPY enclave_app.py /app/enclave_app.py

  WORKDIR /app
  CMD ["python3", "enclave_app.py"]
  ```
- **Build the EIF with nitro-cli**: Convert the Docker image into an enclave image file, capturing the PCR measurements:
  ```bash
  docker build -t enclave-app:latest .
  nitro-cli build-enclave \
    --docker-uri enclave-app:latest \
    --output-file enclave-app.eif
  ```
  The output contains three critical PCR values:
  - **PCR0**: SHA-384 hash of the enclave image file (the full image digest)
  - **PCR1**: SHA-384 hash of the Linux kernel and bootstrap process
  - **PCR2**: SHA-384 hash of the application code
  Record these values; they are used in KMS key policies for attestation-based access control.

- **Build a signed EIF** (recommended for production): Generate a signing certificate and use it to produce PCR8:
  ```bash
  openssl ecparam -name secp384r1 -genkey -noout -out enclave_key.pem
  openssl req -new -key enclave_key.pem -sha384 \
    -nodes -subj "/CN=Enclave Signer" -out enclave_csr.pem
  openssl x509 -req -days 365 -in enclave_csr.pem \
    -signkey enclave_key.pem -sha384 -out enclave_cert.pem

  nitro-cli build-enclave \
    --docker-uri enclave-app:latest \
    --output-file enclave-app.eif \
    --private-key enclave_key.pem \
    --signing-certificate enclave_cert.pem
  ```
  PCR8 (the signing certificate hash) enables KMS policies that trust any image signed by a specific certificate, allowing image updates without changing the policy.

### Step 3: Configure KMS Attestation-Based Key Policies

Create a KMS key policy that restricts decryption to a verified enclave:

- **Policy using PCR0 (image hash)**: This locks the key to a specific enclave build. Any code change produces a new PCR0, requiring a policy update:
  ```json
  {
    "Version": "2012-10-17",
    "Statement": [
      {
        "Sid": "AllowEnclaveDecrypt",
        "Effect": "Allow",
        "Principal": {
          "AWS": "arn:aws:iam::111122223333:role/EnclaveParentRole"
        },
        "Action": [
          "kms:Decrypt",
          "kms:GenerateDataKey"
        ],
        "Resource": "*",
        "Condition": {
          "StringEqualsIgnoreCase": {
            "kms:RecipientAttestation:ImageSha384": "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210"
          }
        }
      }
    ]
  }
  ```
- **Policy using PCR8 (signing certificate)**: Trusts any enclave signed with a specific certificate, enabling image rotation without policy changes:
  ```json
  {
    "Condition": {
      "StringEqualsIgnoreCase": {
        "kms:RecipientAttestation:PCR8": "ab3456789012345678901234567890123456789012345678901234567890123456789012345678901234567890abcdef"
      }
    }
  }
  ```
- **Multi-PCR policy for defense in depth**: Combine PCR0 (image) and PCR1 (kernel) to ensure both the application and the boot environment match expected values:
  ```json
  {
    "Condition": {
      "StringEqualsIgnoreCase": {
        "kms:RecipientAttestation:PCR0": "<pcr0-hex>",
        "kms:RecipientAttestation:PCR1": "<pcr1-hex>"
      }
    }
  }
  ```
- **IAM role policy**: The parent instance's IAM role must have `kms:Decrypt` permission, but the KMS key policy condition ensures the actual decryption only succeeds when the request originates from a valid enclave with the correct attestation document attached.

### Step 4: Implement Secure Vsock Communication

Establish the parent-to-enclave communication channel:

- **Vsock architecture**: The only way an enclave communicates with the outside world is through a vsock (virtual socket). Vsock uses a CID (Context Identifier) and port number. The parent instance CID is always `3`, and the enclave CID is assigned at launch.
- **Parent-side proxy server**: The parent runs a proxy that forwards KMS API calls from the enclave through the vsock to the AWS KMS endpoint:
  ```python
  import socket
  import json
  import boto3

  VSOCK_CID = 3  # Parent CID
  VSOCK_PORT = 5000

  def start_proxy():
      sock = socket.socket(socket.AF_VSOCK, socket.SOCK_STREAM)
      sock.bind((VSOCK_CID, VSOCK_PORT))
      sock.listen(5)

      kms_client = boto3.client('kms', region_name='us-east-1')

      while True:
          conn, addr = sock.accept()
          data = conn.recv(65536)
          request = json.loads(data.decode())

          if request['action'] == 'decrypt':
              response = kms_client.decrypt(
                  CiphertextBlob=bytes.fromhex(request['ciphertext']),
                  Recipient={
                      'KeyEncryptionAlgorithm': 'RSAES_OAEP_SHA_256',
                      'AttestationDocument': bytes.fromhex(request['attestation_doc'])
                  }
              )
              conn.sendall(json.dumps({
                  'ciphertext_for_recipient': response['CiphertextForRecipient'].hex()
              }).encode()