Nitro Enclaves application: AWS Certificate Manager for Nitro Enclaves - AWS Nitro Enclaves

Nitro Enclaves application: AWS Certificate Manager for Nitro Enclaves

AWS Certificate Manager (ACM) for Nitro Enclaves allows you to use public and private SSL/TLS certificates with your web applications and web servers running on Amazon EC2 instances with AWS Nitro Enclaves. SSL/TLS certificates are used to secure network communications and to establish the identity of websites over the internet, as well as resources on private networks.

Previously, when running a web server on an EC2 instance, you would have created SSL certificates and stored them as plaintext on your instance. With ACM for Nitro Enclaves, you can now bind AWS Certificate Manager certificates to an enclave and use those certificates directly with your web server, without exposing the certificates in plaintext form to the parent instance and its users.

ACM for Nitro Enclaves removes the time-consuming and error-prone manual process of purchasing, uploading, and renewing SSL/TLS certificates. ACM for Nitro Enclaves creates secure private keys, distributes the certificate and its private key to your enclave, and manages certificate renewals. With ACM for Nitro Enclaves, the certificate's private key remains isolated in the enclave, preventing the instance, and its users, from accessing it.

Currently, ACM for Nitro Enclaves works with NGINX servers running on Amazon EC2 instances to install the certificate and seamlessly replace expiring certificates. Support for additional web servers will be added over time.

Note

ACM for Nitro Enclaves uses the standardized PKCS11 cryptographic interface between the parent instance and the enclave. Any application that supports the PKCS11 protocol can be adapted to use ACM for Nitro Enclaves for protecting certificates and keys.

ACM for Nitro Enclaves also includes a “helper” p11-kit based module for using the PKCS11 protocol over the Nitro Enclaves vsock socket.

At this time, Apache HTTP server's built-in support for PKCS11 does not work with ACM for Nitro Enclaves.

Public SSL/TLS certificates that you provision through ACM for Nitro Enclaves are free. You pay only for the AWS resources that you create to run your application, such as Amazon EC2 instances.

Prerequisites

The IAM user performing this configuration must have permission to use the ec2:AssociateEnclaveCertificateIamRole, ec2:GetAssociatedEnclaveCertificateIamRoles, and ec2:DisassociateEnclaveCertificateIamRole actions. To grant the IAM 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 AWS Certificate Manager certificate

Create the AWS Certificate Manager (ACM) certificate that you want use with your NGINX 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.

After you have created the certificate, make a note of the certificate ARN; as you'll need it later.

Step 2: Launch the enclaves-enabled parent instance

Launch a new Amazon EC2 instance using one of the following ACM for Nitro Enclaves AMIs, depending on your Region, and enable the instance for Nitro Enclaves.

  • us-east-1—ami-09a1f053468bd3dcf

  • us-east-2—ami-0bc56d1a0e5584cb4

  • us-west-2—ami-0f0124ebc1f49daf5

  • ap-east-1—ami-09b985981f1c12e8f

  • ap-northeast-1—ami-0022e5e5ce88aa323

  • ap-south-1—ami-042fc7f2cda314ab4

  • ap-southeast-1—ami-0ed46cdbe7ca952fc

  • ap-southeast-2—ami-005448c3d2eab01b5

  • eu-central-1—ami-0acdbcca812cefd03

  • eu-north-1—ami-031805abef5291506

  • eu-west-1—ami-09be95e78685c4142

  • eu-west-2—ami-06ddc10f4b58d3f0b

  • eu-west-3—ami-00da9426142772b8a

  • sa-east-1—ami-0b2022ccbbf6bb599

$ aws ec2 run-instances --image-id ami_id --count 1 --instance-type supported_instance_type --key-name your_key_pair --enclave-options 'Enabled=true'

After you launch the instance, make a note of the instance ID, as you'll need it later.

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", "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:

  • Retrieve the ACM certificate from the Amazon S3 bucket returned in the previous step

  • Perform kms:Decrypt using the customer master key (CMK) returned in the previous step

Create a JSON file named acm-role-policies, 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" } ] }

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 NGINX to use ACM for Nitro Enclaves

Configure the NGINX web server to use the ACM certificate.

To configure NGINX

  1. SSH into the instance that you launched previously.

  2. Rename the sample ACM for Nitro Enclaves configuration file from /etc/nitro_enclaves/acm.example.yaml to /etc/nitro_enclaves/acm.yaml.

    $ sudo mv /etc/nitro_enclaves/acm.example.yaml /etc/nitro_enclaves/acm.yaml
  3. Using your preferred text editor, open /etc/nitro_enclaves/acm.yaml. In the Acm section, for certificate_arn, specify the ARN of the certificate. Save and close the file.

  4. Configure NGINX to use the pkcs11 SSL engine by setting the top-level ssl_engine directive.

    Using your preferred text editor, open /etc/nginx/nginx.conf. Add the following line below pid /run/nginx.pid;.

    ssl_engine pkcs11;

    Example

    # For more information on configuration, see: # * Official English Documentation: http://nginx.org/en/docs/ user nginx; worker_processes auto; error_log /var/log/nginx/error.log; pid /run/nginx.pid; ssl_engine pkcs11;
  5. Enable the TLS server and configure the server to use your certificate.

    In /etc/nginx/nginx.conf, scroll to the bottom of the file and do the following:

    • Uncomment all of the lines below Settings for a TLS enabled server.

    • In the first block, for server_name, specify the host name, or the common name (CN), that you specified when you created the certificate.

    • In the second block, remove the following lines.

      ssl_certificate "/etc/pki/nginx/server.crt"; ssl_certificate_key "/etc/pki/nginx/private/server.key"; ssl_ciphers PROFILE=SYSTEM;

      And add the following line.

      ssl_protocols TLSv1.2;
    • Add the following as a new block below the second block.

      # Set this to the stanza path configured in /etc/nitro_enclaves/acm.yaml include "/etc/pki/nginx/nginx-acm.conf";

    The completed section should appear as follows.

    # Settings for a TLS enabled server. # server { listen 443 ssl http2; listen [::]:443 ssl http2; server_name example.com; root /usr/share/nginx/html; ssl_protocols TLSv1.2; ssl_session_cache shared:SSL:1m; ssl_session_timeout 10m; ssl_prefer_server_ciphers on; # Set this to the stanza path configured in /etc/nitro_enclaves/acm.yaml include "/etc/pki/nginx/nginx-acm.conf"; # Load configuration files for the default server block. include /etc/nginx/default.d/*.conf; error_page 404 /404.html; location = /40x.html { } error_page 500 502 503 504 /50x.html; location = /50x.html { } }
  6. Start the ACM for Nitro Enclaves service and ensure that it starts automatically at instance boot.

    $ sudo systemctl start nitro-enclaves-acm.service
    $ sudo systemctl enable nitro-enclaves-acm
  7. Test that the ACM for Nitro Enclaves is working as expected.

    If you used a public certificate, use the following command.

    $ curl https://host_name_or_IP

    If you used a private certificate, you must add the host name to /etc/hosts in the following format: 127.0.0.1 host_name, for example 127.0.0.1 example.com. And you must specify the certificate chain to use to validate the certificate. For more information about generating the certificate chain for your certificate, see Exporting a Private Certificate in the AWS Certificate Manager User Guide.

    $ curl --cacert path_to_pem_file https://host_name_or_IP

    A successful test displays the NGINX index.htm.

The ACM for Nitro Enclaves service continuously polls and fetches the ACM certificate data and updates NGINX accordingly. It does this by generating an NGINX config snippet and including it in the main nginx.conf.

If you renew the ACM certificate by running acm renew-certificate, the ACM for Nitro Enclaves automatically reconfigures the enclave and the NGINX web server. You can use the following command to check the log for update announcements and to diagnose possible issues.

$ journalctl -u nitro-enclaves-acm.service

If you encounter any unexpected errors, you can also check the NGINX service log for more details.

$ journalctl -u nginx.service