Install ACM for Nitro Enclaves

Use the following procedure to install and configure ACM for Nitro Enclaves.

Prerequisites

The user performing this configuration must have permission to use the ec2:AssociateEnclaveCertificateIamRole, ec2:GetAssociatedEnclaveCertificateIamRoles, and ec2:DisassociateEnclaveCertificateIamRole actions. To grant the user the required permissions, use the following IAM policy.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "ec2:AssociateEnclaveCertificateIamRole",
                "ec2:GetAssociatedEnclaveCertificateIamRoles",
                "ec2:DisassociateEnclaveCertificateIamRole"
            ],
            "Resource": [
                "arn:aws:acm:region:account_id:certificate/*",
                "arn:aws:iam::account_id:role/*"
            ],
            "Effect": "Allow"
        }
    ]
}

Step 1: Create the ACM certificate

Create the AWS Certificate Manager (ACM) certificate that you want use with your NGINX or Apache HTTP server. ACM for Nitro Enclaves supports both private and public certificates. For more information about creating a certificate, see the following resources in the AWS Certificate Manager User Guide.

When you use DNS validation to request an ACM certificate, ACM provides a CNAME record that you must then add to your DNS configuration. ACM uses the CNAME record to validate ownership of domains.

Step 2: Prepare the enclaves-enabled parent instance

Launch the enclave enabled instance that you will use as the parent instance. You can use either the ACM for Nitro Enclaves AMI from AWS Marketplace, or you can install ACM for Nitro Enclaves and the web server using RPM packages.

Step 3: Prepare the IAM role

To grant the instance permission to use the ACM certificate, you must create an IAM role with the required permissions. The IAM role is later attached to the instance and the ACM certificate.

Create a JSON file named acm-role and add the following policy statement.

{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Principal":{
            "Service":"ec2.amazonaws.com"
         },
         "Action":"sts:AssumeRole"
      }
   ]
}

Use the create-role command to create a role named acm-role, and specify the path to the JSON policy file.

$ aws iam create-role --role-name acm-role --assume-role-policy-document file://acm-role.json

After you have created the role, make a note of the role ARN, as you'll need it in the next step.

Step 4: Associate the role with the ACM certificate

Attach the IAM role that you created in the previous step to the ACM certificate. To do this, use the associate-enclave-certificate-iam-role command, and specify the ARN of the role to attach, and the ARN of the certificate to attach it to.

$ aws ec2 --region region associate-enclave-certificate-iam-role --certificate-arn certificate_ARN --role-arn role_ARN

For example

$ aws ec2 --region us-east-1 associate-enclave-certificate-iam-role --certificate-arn arn:aws:acm:us-east-1:123456789012:certificate/d4c3b2a1-e5d0-4d51-95d9-1927fEXAMPLE --role-arn arn:aws:iam::123456789012:role/acm-role

Example output

{

"CertificateS3BucketName": "aws-ec2-enclave-certificate-us-east-1-prod",
"CertificateS3ObjectKey": "arn:aws:iam::123456789012:role/acm-role/arn:aws:acm:us-east-1:123456789012:certificate/d4c3b2a1-e5d0-4d51-95d9-1927fEXAMPLE",
"EncryptionKmsKeyId": "a1b2c3d4-354d-4e51-9190-b12ebEXAMPLE"
}

After running the command, make a note of CertificateS3BucketName and EncryptionKmsKeyId, as you'll need them for the next step.

Step 5: Grant the role permission to access the certificate and encryption key

You must now grant the IAM role (acm-role) permission to do the following:

Create a JSON file named acm-role-policies.json, add the following policy statement, and specify the values of CertificateS3BucketName and EncryptionKmsKeyId from the previous step.

{
  "Version": "2012-10-17",
  "Statement": [
    {
        "Effect": "Allow",
        "Action": [
        "s3:GetObject"
        ],
        "Resource": ["arn:aws:s3:::CertificateS3BucketName/*"]
    },
    {
        "Sid": "VisualEditor0",
        "Effect": "Allow",
        "Action": [
            "kms:Decrypt"
        ],
        "Resource": "arn:aws:kms:region:*:key/EncryptionKmsKeyId"
    },
    {
            "Effect": "Allow",
            "Action": "iam:GetRole",
            "Resource": "arn:aws:iam::123456789012:role/acm-role"
    }
  ]
}

Use the put-role-policy command to add the additional policies to the acm-role role, and specify the path to the JSON policy file.

$ aws iam put-role-policy --role-name acm-role --policy-name acm-role-policy --policy-document file://acm-role-policies.json

Step 6: Attach the role to the instance

You must attach the IAM role to the instance to give it permission to use the certificate.

Create a new instance profile named acm-instance-profile using the create-instance-profile command.

$ aws iam create-instance-profile --instance-profile-name acm-instance-profile

Example output

{
    "InstanceProfile": {
    "Path": "/",
     "InstanceProfileName": "acm-instance-profile",
    "InstanceProfileId": "ABCDUS6G56GWDIEXAMPLE",
    "Arn": "arn:aws:iam::123456789012:instance-profile/acm-instance-profile",
    "CreateDate": "2020-10-14T03:38:08+00:00",
"Roles": []
}
}

Add the acm-role that you created earlier to the acm-instance-profile that you just created. Use the add-role-to-instance-profile command.

$ aws iam add-role-to-instance-profile --instance-profile-name acm-instance-profile --role-name acm-role

Associate the instance profile with the instance that you launched previously. Use the associate-iam-instance-profile command and specify the instance profile to attach and the instance to attach it to.

$ aws ec2 --region region associate-iam-instance-profile --instance-id instance_id --iam-instance-profile Name=acm-instance-profile

Example output

{
    "IamInstanceProfileAssociation": 
    {
        "AssociationId": "iip-assoc-0a411083b4EXAMPLE",
        "InstanceId": "i-1234567890abcdef0",
        "IamInstanceProfile": 
        {
            "Arn": "arn:aws:iam::123456789012:instance-profile/acm-instance-profile",
            "Id": "ABCDUS6G56GWDIEXAMPLE"
        },
        "State": "associating"
    }
}

Step 7: Configure the web server to use ACM for Nitro Enclaves

Configure the NGINX or Apache HTTP web server to use the ACM certificate. Choose the correct procedure depending on the web server you're using.

Using multiple certificates

You can also add multiple ACM certificates; one for each PKCS#11 token. For each additional certificate that you need to add, repeat Step 4: Associate the role with the ACM certificate in order to associate your IAM role with the additional ACM certificates.

Then to add more PKCS#11 tokens, open /etc/nitro_enclaves/acm.yaml with your preferred text editor, and under the token section, add another label block and specify a label name, the ARN of the additional certificate, and a path for the NGINX stanza or Apache HTTP configuration file respectively. For example, the following snippet shows the format to be used for two ACM certificates (the initial certificate and two additional certificates):

tokens:
    # A label for this PKCS#11 token
  - label: nginx-acm-token
    # Configure a managed token, sourced from an ACM certificate.
    source:
      Acm:
        # The certificate ARN
        # Note: this certificate must have been associated with the IAM role assigned to the instance on 
        # which ACM for Nitro Enclaves is run.
        certificate_arn: "arn:aws:acm:us-east-1:123456789012:certificate/d4c3b2a1-e5d0-4d51-95d9-1927fEXAMPLE"
    target:
      NginxStanza:
        # Path to the nginx stanza to be written by the ACM service whenever # the certificate configuration 
        # changes (e.g. after a certificate renewal). # This file must be included from the main nginx config 
        # `server` section, as it will contain the TLS nginx configuration directives.
        path: /etc/pki/nginx/nginx-acm.conf
        # Stanza file owner (i.e. the user nginx is configured to run as).
        user: nginx
    # PKCS#11 token 2  
  - label: token_2_name
    source:
      Acm:
        certificate_arn: "certificate_2_ARN"
    target:
      NginxStanza:
        path: /etc/pki/nginx/nginx-acm-2.conf
        user: nginx

After you have completed the necessary configuration, run the following command to restart the Start the ACM for Nitro Enclaves service.

$ sudo systemctl restart nitro-enclaves-acm.service