implementing-aws-nitro-enclave-security

Files (4)

• LICENSE
• SKILL.md
• api-reference.md · references/
• agent.py · scripts/

SKILL.md (first lines)

# 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:

From pinkpixel-dev/skills-collection-2, Apache-2.0.

More from pinkpixel-dev/skills-collection-2