Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve high level documentation for AWS Nitro specific processes #121

Open
emostov opened this issue Sep 20, 2022 · 2 comments
Open

Improve high level documentation for AWS Nitro specific processes #121

emostov opened this issue Sep 20, 2022 · 2 comments
Assignees
Labels
documentation Improvements or additions to documentation

Comments

@emostov
Copy link
Contributor

emostov commented Sep 20, 2022

Generally, we want to avoid documentation rot and duplicate documentation. However this should be balanced with the need have an easy to understand, centralized entry point to understanding QOS's use of the AWS Nitro specific infrastructure. With this in mind I proposed adding either a section to the readme or a new conceptual doc to cover the below:

  • Include Basic overview of enclaves
    • For in depth context: https://docs.aws.amazon.com/enclaves/latest/user/nitro-enclave.html
    • virtualized resource isolation within an AWS EC2 instance (not physically seperate)
      • own kernal, vCPU, partitioned memory
      • no persistent storage, no network connectivity
      • can only communicate over a virtual socket
      • has access to a nitro secure module which can cryptographically attest (sign) to the booted image, arbitrary data fed to it, and some other measurements (see PCRs)
      • Measurements that can be attested to (Platform Configuration Registers): https://docs.aws.amazon.com/enclaves/latest/user/set-up-attestation.html
    • verify the amazon CA with nitro secure module signatures over the attestation document https://docs.aws.amazon.com/enclaves/latest/user/verify-root.html
    • Attestation process overview
      • During the boot flow we want to verify the enclave has the intended OS image. In short if we trust our code and we can independently attest that the encalve booted with that code, then we can trust the enclave enough to post quorum key shares
  • Diagrams for how a encalve app communication
    • Flow diagram for booting
      • QOS instance goes up
      • Load manifest (with signatures from quorum members specified in manifest) and the pivot application (which is refferenced by hash in the manifest)
        • QOS generates epehemeral key
      • QOS requests attestation doc with refferences to the ephemeral public key and manifest
      • A threshold of quorum members each indepently request the attestation document and
        • verify that it is correctly authenticated by AWS CA, has the correct PCRs, and refferences the corect manifest
        • additionally the should do another check of the manifest
        • they then pull the ephemeral key out of the attestation document and use it to encrypt their quorum key share
        • finally they post theier quorum key share
        • once a threshold of quorum key shares are posted, QOS will reconstruct the Quorum Key and pivot to running the enclave application
    • Diagram for communication with App Host <-> QOS <-> App Enclave Server
@emostov emostov self-assigned this Sep 20, 2022
@emostov emostov added the documentation Improvements or additions to documentation label Sep 20, 2022
@emostov
Copy link
Contributor Author

emostov commented Sep 20, 2022

cc @r-n-o @cr-tk

@cr-tk
Copy link
Collaborator

cr-tk commented Sep 20, 2022

I think this is a good idea and describes some of the documentation that I've been missing so far 👍

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

2 participants