Handshakes
How enclaves establish trust with the client.
A handshake must be performed to establish the secure transmission of information from a client to an enclave. The purpose of this handshake is to authenticate both the enclave and client and to share a symmetric key that is used for payload encryption thereafter.
note
This section is purely for your understanding. The handshakes between a client machine and the enclave are performed for you by the client side proxy cli. Find out more about how to use the CLI proxy here
Creating a Secure Connection
To establish a secure connection between the client and enclave, the client must first send a request to the enclave API. This initial message authenticates the client and encapsulates a public key (provided by the client).
The enclave service can now retrieve an attestation document from the underlying nitro service manager. This internal API call allows the enclave to provide a public key, user data, and nonce.
The enclave service first generates a symmetric key per connection. It then encrypts the symmetric key with a public key provided by the client, and this encrypted symmetric key is used as user data for an attestation document. The attestation document is then returned to the client.
The client can now do the following in sequence:
- Verify that the attestation document is signed by AWS certificate authority and validates the certificate of attestation.
- Verify all intermediate signatures and that of the attestation document.
- Verify that the PCRs of the attestation document match those expected by the client.
- Verify nonce if needed.
- Extract the symmetric key from the user data of the attestation document and use it for payload encryption going forward.
Special Case: AWS KMS
AWS has a similar handshake native in their key management system (KMS). As such, there is a special case scenario whereby a user can upload encrypted data to an enclave, or an enclave can call an external resource such as AWS Aurora to retrieve encrypted data, when the encryption key is created within the AWS KMS. For the enclave to retrieve the key to decrypt the data, it must request it from the KMS directly, and the KMS must have a correctly configured policy to release the key to the specific enclave based on its attestation documents PCR codes. For more information on retrieving keys from the AWS KMS, please refer to the Internal Service API page.