AWS Nitro Enclaves Workflow

# Create the trust policy
cat > trust-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ec2.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
EOF

# Create the role
aws iam create-role \
  --role-name EnclaveInstanceRole \
  --assume-role-policy-document file://trust-policy.json

# Attach basic permissions (expand as needed for KMS)
aws iam attach-role-policy \
  --role-name EnclaveInstanceRole \
  --policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore

# Create instance profile
aws iam create-instance-profile \
  --instance-profile-name EnclaveInstanceProfile

aws iam add-role-to-instance-profile \
  --instance-profile-name EnclaveInstanceProfile \
  --role-name EnclaveInstanceRole

# Create security group (adjust VPC ID for your environment)
aws ec2 create-security-group \
  --group-name enclave-parent-sg \
  --description "Security group for Nitro Enclave parent instance" \
  --vpc-id vpc-xxxxxxxxx

# Allow SSH access (restrict source IP in production)
aws ec2 authorize-security-group-ingress \
  --group-name enclave-parent-sg \
  --protocol tcp \
  --port 22 \
  --cidr 0.0.0.0/0

# Find the latest Amazon Linux 2023 AMI
AMI_ID=$(aws ec2 describe-images \
  --owners amazon \
  --filters "Name=name,Values=al2023-ami-2023*-x86_64" \
            "Name=state,Values=available" \
  --query "Images | sort_by(@, &CreationDate) | [-1].ImageId" \
  --output text)

# Launch the instance
aws ec2 run-instances \
  --image-id $AMI_ID \
  --instance-type m5.xlarge \
  --key-name your-key-pair \
  --security-group-ids sg-xxxxxxxxx \
  --subnet-id subnet-xxxxxxxxx \
  --iam-instance-profile Name=EnclaveInstanceProfile \
  --enclave-options Enabled=true \
  --block-device-mappings '[{"DeviceName":"/dev/xvda","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=enclave-dev}]'

# SSH into the instance, then run:
aws ec2 describe-instances \
  --instance-ids i-xxxxxxxxx \
  --query "Reservations[].Instances[].EnclaveOptions"

# Expected output:
# [
#     {
#         "Enabled": true
#     }
# ]

# Install the Nitro Enclaves CLI and tools
sudo dnf install aws-nitro-enclaves-cli aws-nitro-enclaves-cli-devel -y

# Add your user to the ne group (required to run enclave commands)
sudo usermod -aG ne $USER

# Add your user to the docker group (required to build EIFs)
sudo usermod -aG docker $USER

# Log out and back in for group changes to take effect
exit
# SSH back in

# Install from amazon-linux-extras
sudo amazon-linux-extras install aws-nitro-enclaves-cli -y
sudo yum install aws-nitro-enclaves-cli-devel -y

# Add user to required groups
sudo usermod -aG ne $USER
sudo usermod -aG docker $USER

# Log out and back in
exit

# Edit the allocator configuration
sudo vi /etc/nitro_enclaves/allocator.yaml

---
# Memory in MiB to reserve for enclaves
memory_mib: 512

# Number of CPUs to reserve for enclaves
# Must be at least 2 (enclaves need full cores, not hyperthreads)
cpu_count: 2

# Enable and start the allocator service
sudo systemctl enable nitro-enclaves-allocator.service
sudo systemctl start nitro-enclaves-allocator.service

# Enable and start Docker (required for building EIFs)
sudo systemctl enable docker
sudo systemctl start docker

# Check CLI version
nitro-cli --version
# Expected: Nitro CLI <version>

# Check allocator service status
sudo systemctl status nitro-enclaves-allocator.service
# Should show "active (running)"

# Verify allocated resources
cat /etc/nitro_enclaves/allocator.yaml

# Check that the Nitro Enclaves device exists
ls -la /dev/nitro_enclaves
# Expected: crw------- 1 root ne ... /dev/nitro_enclaves

# Verify your user can access it
id | grep ne
# Should show the "ne" group in your groups

enclave-app/
├── Cargo.toml
├── src/
│   └── main.rs
└── Dockerfile

[package]
name = "enclave-app"
version = "0.1.0"
edition = "2021"

[dependencies]
vsock = "0.4"

use std::io::{Read, Write};
use vsock::{VsockListener, VMADDR_CID_ANY};

const VSOCK_PORT: u32 = 5000;

fn main() {
    println!("Enclave application starting...");

    // Bind to vsock - VMADDR_CID_ANY accepts connections from any CID
    let listener = VsockListener::bind_with_cid_port(VMADDR_CID_ANY, VSOCK_PORT)
        .expect("Failed to bind vsock listener");

    println!("Listening on vsock port {}", VSOCK_PORT);

    for stream in listener.incoming() {
        match stream {
            Ok(mut conn) => {
                let mut buf = [0u8; 1024];
                match conn.read(&mut buf) {
                    Ok(n) if n > 0 => {
                        println!("Received {} bytes", n);
                        // Echo back the received data
                        let _ = conn.write_all(&buf[..n]);
                    }
                    _ => {}
                }
            }
            Err(e) => eprintln!("Connection error: {}", e),
        }
    }
}

# Build stage
FROM rust:1.75-slim as builder

WORKDIR /app
COPY Cargo.toml ./
COPY src ./src

RUN cargo build --release

# Runtime stage - minimal image
FROM amazonlinux:2023-minimal

COPY --from=builder /app/target/release/enclave-app /usr/local/bin/

# Enclaves run the CMD as PID 1
CMD ["/usr/local/bin/enclave-app"]

# Build the Docker image
docker build -t enclave-app:latest .

# Verify the image exists
docker images | grep enclave-app

nitro-cli build-enclave \
  --docker-uri enclave-app:latest \
  --output-file enclave-app.eif

Start building the Enclave Image...
Enclave Image successfully created.
{
  "Measurements": {
    "HashAlgorithm": "Sha384 { ... }",
    "PCR0": "abc123...",
    "PCR1": "def456...",
    "PCR2": "789ghi..."
  }
}

# Save PCR values for later use
nitro-cli build-enclave \
  --docker-uri enclave-app:latest \
  --output-file enclave-app.eif 2>&1 | tee build-output.json

nitro-cli describe-eif --eif-path enclave-app.eif

nitro-cli run-enclave \
  --eif-path enclave-app.eif \
  --cpu-count 2 \
  --memory 2048

{
  "EnclaveName": "enclave-app",
  "EnclaveID": "i-xxxxxxxxx-enc0123456789abcdef0",
  "ProcessID": 12345,
  "EnclaveCID": 16,
  "NumberOfCPUs": 2,
  "CPUIDs": [1, 3],
  "MemoryMiB": 2048
}

nitro-cli describe-enclaves

[
  {
    "EnclaveName": "enclave-app",
    "EnclaveID": "i-xxxxxxxxx-enc0123456789abcdef0",
    "ProcessID": 12345,
    "EnclaveCID": 16,
    "NumberOfCPUs": 2,
    "CPUIDs": [1, 3],
    "MemoryMiB": 2048,
    "State": "RUNNING",
    "Flags": "NONE",
    "Measurements": {
      "HashAlgorithm": "Sha384 { ... }",
      "PCR0": "abc123...",
      "PCR1": "def456...",
      "PCR2": "789ghi..."
    }
  }
]

# Terminate by enclave ID
nitro-cli terminate-enclave --enclave-id i-xxxxxxxxx-enc0123456789abcdef0

# Or terminate all running enclaves
nitro-cli terminate-enclave --all

# First enclave
nitro-cli run-enclave --eif-path app-a.eif --cpu-count 2 --memory 1024

# Second enclave (if resources allow)
nitro-cli run-enclave --eif-path app-b.eif --cpu-count 2 --memory 1024

# Launch with debug mode enabled
nitro-cli run-enclave \
  --eif-path enclave-app.eif \
  --cpu-count 2 \
  --memory 2048 \
  --debug-mode

# Attach to the enclave console in a separate terminal
nitro-cli console --enclave-id i-xxxxxxxxx-enc0123456789abcdef0

# 1. Make code changes locally
# 2. Rebuild Docker image
docker build -t enclave-app:latest .

# 3. Rebuild EIF
nitro-cli build-enclave \
  --docker-uri enclave-app:latest \
  --output-file enclave-app.eif

# 4. Terminate existing enclave
nitro-cli terminate-enclave --all

# 5. Run new enclave in debug mode
nitro-cli run-enclave \
  --eif-path enclave-app.eif \
  --cpu-count 2 \
  --memory 2048 \
  --debug-mode

# 6. Attach console to see output
nitro-cli console --enclave-id $(nitro-cli describe-enclaves | jq -r '.[0].EnclaveID')

use std::io::{Read, Write};
use std::net::Shutdown;
use vsock::{VsockListener, VMADDR_CID_ANY};

const LISTEN_PORT: u32 = 5000;
const MAX_MSG_SIZE: usize = 1024 * 1024; // 1 MiB

fn main() -> std::io::Result<()> {
    let listener = VsockListener::bind_with_cid_port(VMADDR_CID_ANY, LISTEN_PORT)?;
    println!("Enclave listening on vsock port {}", LISTEN_PORT);

    for stream in listener.incoming() {
        match stream {
            Ok(mut conn) => {
                // Read length-prefixed message
                let mut len_buf = [0u8; 4];
                if conn.read_exact(&mut len_buf).is_err() {
                    continue;
                }
                let msg_len = u32::from_be_bytes(len_buf) as usize;

                if msg_len > MAX_MSG_SIZE {
                    eprintln!("Message too large: {} bytes", msg_len);
                    let _ = conn.shutdown(Shutdown::Both);
                    continue;
                }

                let mut msg_buf = vec![0u8; msg_len];
                if conn.read_exact(&mut msg_buf).is_err() {
                    continue;
                }

                // Process and respond
                let response = process_request(&msg_buf);

                let resp_len = (response.len() as u32).to_be_bytes();
                let _ = conn.write_all(&resp_len);
                let _ = conn.write_all(&response);
            }
            Err(e) => eprintln!("Accept error: {}", e),
        }
    }
    Ok(())
}

fn process_request(data: &[u8]) -> Vec<u8> {
    // Your application logic here
    data.to_vec() // Echo for demonstration
}

use std::io::{Read, Write};
use vsock::VsockStream;

const ENCLAVE_CID: u32 = 16; // From run-enclave output
const ENCLAVE_PORT: u32 = 5000;

fn send_to_enclave(data: &[u8]) -> std::io::Result<Vec<u8>> {
    let mut stream = VsockStream::connect_with_cid_port(ENCLAVE_CID, ENCLAVE_PORT)?;

    // Send length-prefixed message
    let len_bytes = (data.len() as u32).to_be_bytes();
    stream.write_all(&len_bytes)?;
    stream.write_all(data)?;

    // Read length-prefixed response
    let mut len_buf = [0u8; 4];
    stream.read_exact(&mut len_buf)?;
    let resp_len = u32::from_be_bytes(len_buf) as usize;

    let mut resp_buf = vec![0u8; resp_len];
    stream.read_exact(&mut resp_buf)?;

    Ok(resp_buf)
}

fn main() {
    let request = b"Hello from parent";
    match send_to_enclave(request) {
        Ok(response) => println!("Response: {:?}", String::from_utf8_lossy(&response)),
        Err(e) => eprintln!("Error: {}", e),
    }
}

External Service <--HTTPS--> Parent Proxy <--vsock--> Enclave

# Using the AWS-provided vsock proxy for KMS
# (installed with aws-nitro-enclaves-cli)
vsock-proxy 8000 kms.us-east-1.amazonaws.com 443 &

use aws_nitro_enclaves_nsm_api::api::Request;
use aws_nitro_enclaves_nsm_api::driver;
use serde_bytes::ByteBuf;

fn get_attestation_document(
    nonce: Option<&[u8]>,
    user_data: Option<&[u8]>,
    public_key: Option<&[u8]>,
) -> Result<Vec<u8>, String> {
    // Open connection to NSM device
    let nsm_fd = driver::nsm_init();
    if nsm_fd < 0 {
        return Err("Failed to open NSM device".into());
    }

    // Build the attestation request
    let request = Request::Attestation {
        nonce: nonce.map(|n| ByteBuf::from(n.to_vec())),
        user_data: user_data.map(|d| ByteBuf::from(d.to_vec())),
        public_key: public_key.map(|k| ByteBuf::from(k.to_vec())),
    };

    // Send request to NSM
    let response = driver::nsm_process_request(nsm_fd, request);
    driver::nsm_exit(nsm_fd);

    match response {
        aws_nitro_enclaves_nsm_api::api::Response::Attestation { document } => {
            Ok(document)
        }
        _ => Err("Unexpected NSM response".into()),
    }
}

COSE_Sign1 {
    protected: { algorithm: ES384 },
    payload: {
        module_id:   "i-xxxxxxxxx-encXXXXXX",
        timestamp:   1234567890123,       // Unix ms
        digest:      "SHA384",
        pcrs: {
            0: <48 bytes>,                // EIF image hash
            1: <48 bytes>,                // Kernel + boot
            2: <48 bytes>,                // Application
            ...
        },
        certificate: <DER bytes>,         // Signing cert
        cabundle:    [<DER bytes>, ...],   // Chain to root
        nonce:       <bytes>,             // Echoed nonce
        user_data:   <bytes>,             // Echoed user_data
        public_key:  <bytes>,             // Echoed public_key
    },
    signature: <bytes>                    // ES384 signature
}

// Pseudocode — use a COSE/CBOR library for actual implementation

fn verify_attestation(
    raw_document: &[u8],
    expected_pcrs: &HashMap<usize, Vec<u8>>,
    expected_nonce: &[u8],
    max_age_ms: u64,
) -> Result<AttestationDoc, VerifyError> {
    // 1. Parse COSE_Sign1 envelope
    let cose = parse_cose_sign1(raw_document)?;
    let doc = parse_cbor_payload(&cose.payload)?;

    // 2. Verify certificate chain back to AWS Nitro root CA
    let root_cert = load_aws_nitro_root_cert();
    verify_certificate_chain(&doc.cabundle, &doc.certificate, &root_cert)?;

    // 3. Verify COSE signature using the signing certificate's public key
    let signing_key = extract_public_key(&doc.certificate)?;
    verify_cose_signature(&cose, &signing_key)?;

    // 4. Check PCR values match expected measurements
    for (index, expected) in expected_pcrs {
        let actual = doc.pcrs.get(index)
            .ok_or(VerifyError::MissingPcr(*index))?;
        if actual != expected {
            return Err(VerifyError::PcrMismatch(*index));
        }
    }

    // 5. Verify nonce matches (prevents replay)
    if doc.nonce.as_deref() != Some(expected_nonce) {
        return Err(VerifyError::NonceMismatch);
    }

    // 6. Check timestamp freshness
    let now_ms = current_time_ms();
    if now_ms - doc.timestamp > max_age_ms {
        return Err(VerifyError::AttestationExpired);
    }

    Ok(doc)
}

# Create a KMS key
KEY_ID=$(aws kms create-key \
  --description "Enclave-protected key" \
  --query 'KeyMetadata.KeyId' \
  --output text)

echo "Key ID: $KEY_ID"

cat > key-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowAdminAccess",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::ACCOUNT_ID:root"
      },
      "Action": "kms:*",
      "Resource": "*"
    },
    {
      "Sid": "AllowEnclaveDecrypt",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::ACCOUNT_ID:role/EnclaveInstanceRole"
      },
      "Action": "kms:Decrypt",
      "Resource": "*",
      "Condition": {
        "StringEqualsIgnoreCase": {
          "kms:RecipientAttestation:PCR0": "EXPECTED_PCR0_VALUE",
          "kms:RecipientAttestation:PCR1": "EXPECTED_PCR1_VALUE",
          "kms:RecipientAttestation:PCR2": "EXPECTED_PCR2_VALUE"
        }
      }
    }
  ]
}
EOF

aws kms put-key-policy \
  --key-id $KEY_ID \
  --policy-name default \
  --policy "$(cat key-policy.json)"

# Encrypt a secret
aws kms encrypt \
  --key-id $KEY_ID \
  --plaintext fileb://secret.txt \
  --output text \
  --query CiphertextBlob > encrypted-secret.b64

# Start the KMS vsock proxy on the parent instance
# This listens on vsock port 8000 and forwards to KMS
vsock-proxy 8000 kms.us-east-1.amazonaws.com 443 &

# Verify the proxy is running
ps aux | grep vsock-proxy

use aws_nitro_enclaves_nsm_api::api::Request;
use aws_nitro_enclaves_nsm_api::driver;
use serde_bytes::ByteBuf;

fn decrypt_with_kms(ciphertext: &[u8]) -> Result<Vec<u8>, Box<dyn std::error::Error>> {
    // 1. Generate an ephemeral RSA key pair inside the enclave
    let (public_key_der, private_key) = generate_rsa_keypair()?;

    // 2. Get attestation document with the public key embedded
    let nsm_fd = driver::nsm_init();
    let request = Request::Attestation {
        nonce: None,
        user_data: None,
        public_key: Some(ByteBuf::from(public_key_der.clone())),
    };
    let response = driver::nsm_process_request(nsm_fd, request);
    driver::nsm_exit(nsm_fd);

    let attestation_doc = match response {
        aws_nitro_enclaves_nsm_api::api::Response::Attestation { document } => document,
        _ => return Err("Failed to get attestation".into()),
    };

    // 3. Call KMS Decrypt via vsock proxy
    //    The request includes the attestation document as the "Recipient" field
    //    KMS will re-encrypt the plaintext to the enclave's public key
    let kms_response = call_kms_decrypt_via_vsock(
        ciphertext,
        &attestation_doc,
    )?;

    // 4. Decrypt the KMS response with the enclave's private key
    //    KMS encrypted the data key to our RSA public key
    let plaintext = rsa_decrypt(&private_key, &kms_response.ciphertext_for_recipient)?;

    Ok(plaintext)
}

nitro-cli describe-enclaves | jq '.[0].Flags'
# Expected: "NONE"
# If debug: "DEBUG_MODE"

# Get running enclave PCRs
nitro-cli describe-enclaves | jq '.[0].Measurements'

# Compare against build-time values
# These MUST match exactly

fn verify_entropy_source() {
    let rng_source = std::fs::read_to_string(
        "/sys/devices/virtual/misc/hw_random/rng_current"
    ).expect("Failed to read RNG source");

    if rng_source.trim() != "nsm-hwrng" {
        panic!("Invalid RNG source: expected 'nsm-hwrng', got '{}'", rng_source.trim());
    }
}

fn verify_clock_source() {
    let clock_source = std::fs::read_to_string(
        "/sys/devices/system/clocksource/clocksource0/current_clocksource"
    ).expect("Failed to read clock source");

    if clock_source.trim() != "kvm-clock" {
        panic!("Invalid clock source: expected 'kvm-clock', got '{}'", clock_source.trim());
    }
}

# Check group membership
id | grep ne

# If missing, add and re-login
sudo usermod -aG ne $USER
exit
# SSH back in

# Check allocator service
sudo systemctl status nitro-enclaves-allocator.service

# If not running
sudo systemctl start nitro-enclaves-allocator.service

# Check what's allocated
cat /etc/nitro_enclaves/allocator.yaml

# Check what's currently in use
nitro-cli describe-enclaves

# Update allocator config, then restart
sudo vi /etc/nitro_enclaves/allocator.yaml
sudo systemctl restart nitro-enclaves-allocator.service

# Verify enclave is running and note the CID
nitro-cli describe-enclaves | jq '.[0] | {State, EnclaveCID}'

# Verify the PCRs in your KMS policy match the running enclave
nitro-cli describe-enclaves | jq '.[0].Measurements'

# Common issues:
# - PCR values changed after rebuilding the EIF
# - Key policy uses PCR0 only, but should include PCR1/PCR2
# - IAM role ARN in the policy doesn't match the instance's role
# - Region mismatch between KMS key and vsock proxy endpoint