Attestation Proxy

This repository contains a very simple reverse proxy which helps to expose cryptographic attestation documents generated by the Nitro Hypervisor for AWS Nitro Enclaves.

This proxy serves two primary purposes:

• Exposing the attestation API of Enclaver
• Implementing an external authorization server for Envoy proxy which can be used to provide in-band attestation for incoming HTTPS requests

Exposing the attestation API

Enclaver provides an (unfortunately poorly documented) internal API endpoint which can be enabled by specifying api.listen_port in its configuration manifest. This API endpoint provides a POST /v1/attestation handler which forwards the request to the internal attestation facility provided by the AWS Nitro Hypervisor system via the AWS NSM API library and returns the resulting attestation document in the binary (CBOR-encoded) form. This endpoint allows passing the following information which will be included in the signed attestation result:

• a nonce to ensure the uniqueness of the request and prevent replay attacks, in the form of a hex-encoded number;
• a public key which can be used to encrypt data communicated to the enclave, PEM-encoded to a string;
• arbitrary user data, encoded to a base64 string.

The public key option is especially useful, as it allows to provide the public key of the private key used for TLS termination inside the enclave inside the attestation document, proving that the data is end-to-end encrypted between the client and the enclave.

The purpose of this attestation proxy is to reuse the TLS keypair used by the ingress proxy terminating TLS traffic inside the enclave, and to pass it to the Enclaver attestation API endpoint for every external attestation request, providing the proof of the secure communication channel.

The proxy also supplies user data comprising a JSON object in the following format:

{
  "enclave": {
    "build_id": "ENCLAVE_BUILD_ID",
    "build_version": "ENCLAVE_BUILD_VERSION",
    "provenance_path": "ENCLAVE_PROVENANCE_PATH"
  },
  "tls": {
    "certificate": "TLS_CERTIFICATE_SHA256_FINGERPRINT",
    "public_key": "TLS_PUBLIC_KEY_SHA256_FINGERPRINT"
  }
}

The proxy expects the environment variables ENCLAVE_BUILD_ID ENCLAVE_BUILD_VERSION and ENCLAVE_PROVENANCE_PATH to be set inside the enclave environment. Their values should help fetch public provenance information necessary to verify the PCR values provided in the attestation documents as belonging to the unaltered, genuine build of the software running inside the Nitro enclave.

The TLS section contains SHA-256 fingerprints of the DER-encoded TLS certificate and public key used by the attestation proxy (and by TLS termination inside the enclave). This serves as a second layer of protection besides the entire public certificate being separately included in the attestation document. These fingerprint hashed can be verified, for example, by checking the certificate information in the browser after navigating to the attestation API endpoint or any other relevant endpoint of the service provided by the enclave.

The proxy implements an attestation API handler, GET /-/attestation

This handler accepts a user nonce as a query parameter (?nonce=...) or in a request header x-attestation-nonce and returns the attestation document obtained from the Enclaver attestation API with the user nonce passed as specified and the rest of fields set as described above.

The resulting document is returned as plain text after being encoded to base64. You can obtain the original CBOR binary by decoding the output or by requesting the original binary document directly by specifying a query parameter cbor=true or a request header accept: application/octet-stream

The obtained binary attestation document can be verified, for example, at this web page provided by the company that developed Enclaver.

Please note that the AWS Nitro Hypervisor returns the provided public key in the attestation document in a base64-encoded DER form with bare key data, when the attestation proxy and browsers usually use a DER form with an RSA encryption data container, so the fingerprint of a directly decoded private key field from the attestation document will differ from the value in the tls.public_key field in user data and in the browser certificate information. To verify the correct fingeprint using the public key data from the attestation document, you can use the following command:

echo 'PUBLIC_KEY_BASE64_DATA_FROM_ATTESTATION_DOCUMENT' \
| base64 -d | openssl rsa -pubin -outform DER | sha256sum

External Authorization Server

Besides the /-/attestation endpoint described in the previous section, the proxy implements a catch-all HTTP handler which does the following:

• If the original HTTP request contains an x-attestation-nonce header, it retrieves the attestation document with the nonce specified in the header the same way as if the /-/attestation endpoint were called directly, and returns an empty 200 OK response with an x-attestation-payload header set to the base64-encoded value of the attestation document.
• Otherwise, an empty 200 OK response is immediately returned.

This handler can be used as an external authorization server for Envoy proxy to provide inline, or "in-band", attestation of all requests coming through the proxy with the specified nonce header.

An instance of Envoy proxy can be running inside the Nitro enclave as an ingress proxy providing TLS traffic termination for all services inside the enclave, including the attestation proxy and using the same TLS key pair as the attestation proxy. This way it is very easy to implement both the externally exposed dedicated attestation endpoint, proxied to the attestation proxy directly, and the side-channel attestation requests for any other service served through the ingress proxy.