@super-protocol/addons-tee 0.8.16 → 0.8.17-beta.2

package/bindings/sp-sev/Cargo.toml

@@ -0,0 +1,80 @@
+[package]
+name = "sev"
+version = "5.0.0"
+authors = [
+    "Nathaniel McCallum <npmccallum@redhat.com>",
+    "The VirTEE Project Developers",
+]
+license = "Apache-2.0"
+edition = "2018"
+homepage = "https://github.com/virtee/sev"
+repository = "https://github.com/virtee/sev"
+description = "Library for AMD SEV"
+readme = "README.md"
+keywords = ["amd", "sev"]
+categories = [
+    "os",
+    "os::linux-apis",
+    "parsing",
+    "network-programming",
+    "hardware-support",
+]
+exclude = [".gitignore", ".github/*"]
+rust-version = "1.80.0"
+
+[badges]
+# See https://doc.rust-lang.org/cargo/reference/manifest.html#the-badges-section
+github = { repository = "virtee/sev", workflow = "test" }
+#github = { repository = "virtee/sev", workflow = "lint" }
+maintenance = { status = "actively-developed" }
+is-it-maintained-issue-resolution = { repository = "virtee/sev" }
+is-it-maintained-open-issues = { repository = "virtee/sev" }
+
+[lib]
+name = 'sev'
+path = "src/lib.rs"
+doc = false
+
+[features]
+default = ["sev", "snp"]
+openssl = ["dep:openssl", "dep:rdrand"]
+hw_tests = []
+dangerous_hw_tests = ["hw_tests", "dep:reqwest", "dep:tokio"]
+sev = []
+snp = []
+crypto_nossl = ["dep:p384", "dep:rsa", "dep:sha2", "dep:x509-cert"]
+
+[target.'cfg(target_os = "linux")'.dependencies]
+iocuddle = "0.1"
+
+[dependencies]
+openssl = { version = "0.10", optional = true }
+serde = { version = "1.0", features = ["derive"] }
+serde_bytes = "0.11"
+bitflags = "1.2"
+codicon = "3.0"
+dirs = "5.0"
+serde-big-array = "0.5.1"
+static_assertions = "^1.1.0"
+bitfield = "^0.15"
+uuid = { version = "^1.11", features = ["serde"] }
+bincode = "^1.3"
+hex = "0.4.3"
+libc = "0.2.161"
+lazy_static = "1.4.0"
+p384 = { version = "0.13.0", optional = true }
+rsa = { version = "0.9.6", optional = true }
+sha2 = { version = "0.10.8", optional = true }
+x509-cert = { version = "0.2.5", optional = true }
+byteorder = "1.4.3"
+base64 = "0.22.1"
+rdrand = { version = "^0.8", optional = true }
+reqwest = { version="0.11.10", features = ["blocking"], optional = true }
+tokio = {version = "1.29.1", features =["rt-multi-thread"], optional = true }
+
+[target.'cfg(target_os = "linux")'.dev-dependencies]
+kvm-ioctls = ">=0.16"
+
+[dev-dependencies]
+kvm-bindings = ">=0.9.1"
+serial_test = "3.0"

package/bindings/sp-sev/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/bindings/sp-sev/README.md

@@ -0,0 +1,82 @@
+<!-- cargo-rdme start -->
+
+The `sev` crate provides an implementation of the [AMD Secure Encrypted
+Virtualization (SEV)][SEV] APIs and the [SEV Secure Nested Paging
+Firmware (SNP)][SNP] ABIs.
+
+[SEV]: https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/programmer-references/55766_SEV-KM_API_Specification.pdf
+[SNP]: https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/specifications/56860.pdf
+
+## SEV APIs
+
+The linux kernel exposes two technically distinct AMD SEV APIs:
+
+1. An API for managing the SEV platform itself
+2. An API for managing SEV-enabled KVM virtual machines
+
+This crate implements both of those APIs and offers them to client.
+code through a flexible and type-safe high-level interface.
+
+## SNP ABIs
+
+Like SEV, the linux kernel exposes another two different AMD SEV-SNP ABIs:
+
+1. An ABI for managing the SEV-SNP platform itself
+2. An ABI for managing SEV-SNP enabled KVM virtual machines
+
+These new ABIs work only for **SEV-SNP** enabled hosts and guests.
+
+This crate implements APIs for both SEV and SEV-SNP management.
+
+## SEV and SEV-SNP enablement
+
+By default, both the SEV and SEV-SNP libraries are compiled.
+Because many modules provide support to both legacy SEV and SEV-SNP, they have been split into individual sub-modules `sev.rs` and `snp.rs`, isolating generation specific behavior.
+If desired, you may opt to exclude either of the sub-modules by disabling its feature in your project's `Cargo.toml`  
+
+For example, to include the SEV APIs only:  
+`sev = { version = "1.2.1", default-features = false, features = ["sev"] }`  
+ 
+To include the SEV-SNP APIs only:  
+`sev = { version = "1.2.1", default-features = false, features = ["snp"] }`  
+
+## Platform Management
+
+Refer to the [firmware](https://docs.rs/sev/latest/sev/firmware/) module for more information.
+
+## Guest Management
+
+Refer to the [launch](https://docs.rs/sev/latest/sev/launch/) module for more information.
+
+## Cryptographic Verification
+
+To enable the cryptographic verification of certificate chains and
+attestation reports, either the `openssl` or `crypto_nossl` feature
+has to be enabled manually. With `openssl`, OpenSSL is used for the
+verification. With `crypto_nossl`, OpenSSL is _not_ used for the
+verification and instead pure-Rust libraries (e.g., `p384`, `rsa`,
+etc.) are used. `openssl` and `crypto_nossl` are mutually exclusive,
+and enabling both at the same time leads to a compiler error.
+
+## Remarks
+
+Note that the linux kernel provides access to these APIs through a set
+of `ioctl`s that are meant to be called on device nodes (`/dev/kvm` and
+`/dev/sev`, to be specific). As a result, these `ioctl`s form the substrate
+of the `sev` crate. Binaries that result from consumers of this crate are
+expected to run as a process with the necessary privileges to interact
+with the device nodes.
+
+## Using the C API
+
+Projects in C can take advantage of the C API for the SEV [launch] ioctls.
+To install the C API, users can use `cargo-c` with the features they would
+like to produce and install a `pkg-config` file, a static library, a dynamic
+library, and a C header:
+
+`cargo cinstall --prefix=/usr --libdir=/usr/lib64`
+
+[firmware]: ./src/firmware/
+[launch]: ./src/launch/
+
+<!-- cargo-rdme end -->

package/bindings/sp-sev/build.rs

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: Apache-2.0
+
+fn main() {
+    use std::path::Path;
+
+    // Add in configurations to be checked within the code.
+    println!("cargo::rustc-check-cfg=cfg(host)");
+    println!("cargo::rustc-check-cfg=cfg(guest)");
+
+    if Path::new("/dev/sev").exists() {
+        println!("cargo:rustc-cfg=host");
+    }
+
+    if Path::new("/dev/sev-guest").exists() {
+        println!("cargo:rustc-cfg=guest");
+    }
+}

package/bindings/sp-sev/docs/attestation/README.md

@@ -0,0 +1,239 @@
+# Attestation
+
+Please note that attestation is a deeply technical process and readers
+should be familiar with some [prerequisite concepts](./prerequisites.md)
+before reading this document.
+
+### Colors
+
+In process diagrams, colors mean the following:
+
+* Green: Implicitly Trusted
+* Red: Untrusted
+* Yellow: Trusted via a Cryptographic Root of Trust
+* Orange: Trusted via Cryptographic Measurement
+
+In certificate chain diagrams, colors mean the following:
+
+* Blue: The private key is accessable only by hardware.
+
+The AMD SEV attestation process is a series of cryptographic transactions between a tenant (entity that wants a
+secure virtual machine) and a host (the entity that provides the virtual machine on their infrastructure).
+This attestation process establishes the following:
+
+* A guarantee that the tenant's secure virtual machine (the guest) is running on an authentic AMD processor which
+  correctly implements AMD's Secure Encrypted Virtualization (SEV) technology in microcode. This demonstrates
+  that the host's processor is capable of supporting an SEV-enabled guest and the guest can be assured it is
+  receiving the protections advertised by the SEV featureset once attestation is complete.
+* A guarantee that the platform that tenant's virtual machine will be running on is actually owned by the host.
+* The host-provided virtual machine image matches exactly what the tenant is expecting. That is, both the tenant
+  and the host calculate the same measurement of the image.
+* A secure channel to inject a secret (or secrets) into the encrypted guest so that its workload is entirely
+  private and known only to the guest itself.
+
+AMD SEV seeks to provide these guarantees even with the presence of a potentially hostile or compromised host.
+
+#### Establishing Trust
+
+The public-key cryptography employed in the attestation for AMD SEV forms a tree-like structure that can be traced
+all the way back to two roots of trust (an authoritative, completely trusted entity):
+
+![amd sev cert chain](./certchain.dot.png)
+
+The above diagram illustrates the two roots of trust from which two chains of trust are established, each terminating
+at the Platform Diffie-Hellman (PDH) node at the bottom. This relationship is important because it shows how trust
+is traced back to what is known as a "root of trust", or in other words: a completely trusted, authoritative entity.
+For AMD SEV, the roots of trust are Advanced Micro Devices (AMD) and the owner of the platform (the entity providing
+the host or a group of hosts). A chain of trust is formed when a trusted entity uses its key to sign another entity's
+key.  When an entity's key is signed by a trusted entity, then the newly-signed key is also trusted.
+
+Let's step through the two chains of trust shown in the above diagram:
+
+The first root of trust is the **Owner Certificate Authority (OCA) signing key**. The OCA is exclusively owned
+by the owner of the platform (the entity that provides the host). It is used to sign the Platform Endorsement Key
+(PEK) to indicate that the owner controls the platform. The only exception to this is if the platform is considered
+"self-owned". In this case, the SEV firmware will generate both the public and private OCA keys and store them. The
+"self-owned" state is the default state.
+
+The second root of trust is the **AMD Root Key (ARK)**. The ARK is used to sign the AMD SEV Signing Key (ASK) to mark
+it as an authentic AMD key in the chain of trust. The ARK is an offline key, carefully protected and controlled by
+AMD. This key is used to sign the AMD Signing Key (ASK), which is online.
+
+The **AMD SEV Signing Key (ASK)** is signed by the ARK and is therefore branded as an authentic and trusted AMD key.
+This key is used to sign the Chip Endorsement Key (CEK).
+
+The **Chip Endorsement Key (CEK)** is a unique key stored within the fuses of the chip itself. This key is signed by
+the ASK to officially associate the processor with the AMD chain of trust. The ASK's signature indicates that the chip
+is an authentic AMD processor. This key is signed during provisioning, a process by which a platform owner takes
+control over the platform. The platform owner exports this key, submits a POST request to an online service, and
+AMD returns the key with an ASK signature on it.
+
+The two chains of trust intersect at the **Platform Endorsement Key (PEK)** which is signed by both the OCA and the
+CEK. This means that the PEK derives trust from both roots of trust: AMD and the platform owner. Any key signed by
+the PEK is considered to be trusted by both the platform owner and AMD. This key is generated by the SEV firmware
+(the software that controls the Platform Secure Processor).
+
+Finally, the chain of trust terminates at the aforementioned **Platform Diffie-Hellman (PDH)** key. This key is used
+to enable a key exchange between the PSP firmware and the tenant to create a master key.
+
+#### Attestation Overview
+
+1. **Validation:** Tenant will validate the certificate chain (described above) provided by the host.
+
+1. **Secure Channel Establishment:** Tenant and Platform Secure Processor (PSP) will negotiate an encrypted channel.
+
+1. **Measurement:** Tenant will validate the measurement of the VM provided by the PSP.
+
+1. **Launch:** Attestation is successful. The tenant will inject secrets into the guest and the guest is launched.
+
+#### Performing Attestation
+
+Now let's examine how the keys are used in practice to perform attestation and safely establish the guarantees that
+were described earlier in the document with a tenant.
+
+First, have a quick look at the following diagram, then we'll unpack it:
+
+![amd sev process](./process.msc.png)
+
+##### Validation
+
+1. To begin, the tenant will ask the host for the certificate chain. The host will route this request to the PSP which
+   will export the certificate chain. The certificate chain is the chain of trust that can be traced all the way to
+   the two roots of trust described above. The PSP's response contains the certificate chain and the firmware version
+   that drives the PSP. The host will relay this response to the tenant.
+
+1. The tenant will verify the certificate chain. The components of the AMD signing keys can be obtained individually
+   to confirm the authenticity of the signatures on the certificate. Similarly, the owner's signature on the PEK
+   derived from the OCA can be used to verify that the expected owner is in control of the platform.
+
+1. The tenant will verify the firmware version advertised by the PSP. Some SEV features are only available in certain
+   firmware revisions.
+
+1. The tenant will build an execution policy. The execution policy contains configuration information. For example:
+   requiring SEV-ES support, disabling the ability to transmit the guest to another platform, or a minimum firmware
+   version. This policy will be delivered to the PSP in a secure channel, which will be established next.
+
+##### Secure Channel Establishment
+
+1. The tenant will create a trusted channel between itself and the PSP to facilitate attestation:
+
+   1. The tenant generates a random Transport Integrity Key ("tik") and random Transport Encryption Key ("tek").
+
+   1. The tenant already has the host's Platform Diffie-Hellman (PDH) key from the certificate chain it requested.
+
+   1. The tenant generates its own random Elliptic Curve Diffie-Hellman (ECDH) key pair.
+
+   1. The tenant derives a shared secret ("Z") from its own PDH and the host's PDH.
+
+   1. The tenant generates a random nonce ("N").
+
+   1. The tenant generates a random initialization vector ("IV").
+
+   1. The tenant derives the master key ("M") from the shared secret ("Z") and the nonce ("N") and from the string
+      "sev-master-secret".
+
+   1. The tenant derives a Key Encryption Key ("kek") from the master key and the string "sev-kek".
+   
+   1. The tenant derives a Key Integrity Key ("kik") from the master key and the string "sev-kik".
+
+   1. The tenant concatenates the Transport Encryption Key ("tek") and the Transport Integrity Key ("tik") and wraps
+      the result with the Key Encryption Key ("kek"), which is then wrapped by the Key Integrity Key ("kik").
+
+   1. The Key Integrity Key ("kik") is used to hash and sign the wrapped data with HMAC-SHA256, seeded from the
+      initialization vector ("IV").
+
+   1. The Transport Integrity Key ("tik") is used to hash and sign (HMAC-SHA256) the guest's execution policy that
+      was crafted above.
+
+1. Finally, the tenant has prepared everything that is required to establish a secure channel between itself
+   and the PSP. The tenant will transmit the following to the host (which will relay it to the PSP): the
+   tenant's PDH public key, the TIK-protected policy, KIK-protected KEK (TEK, TIK), the nonce ("N"), the
+   initialization vector ("IV").  This is everything the PSP needs to securely derive its own understanding
+   of the shared secret and decrypt the buffers. This initiates attestation and foreshadows a virtual machine
+   launch.
+
+   | transmitted as | component |
+   | --------------: | - |
+   | plaintext | N, IV, tenant's PDH (public key) |
+   | ciphertext | (KEK: TEK\|TIK) |
+   | integrity-protected | (TIK: guest policy), (KIK: KEK) |
+
+1. The PSP will receive the tenant's request for a secure channel and decrypt it.
+
+   1. The PSP will use the nonce ("N"), its PDH and the tenant's PDH to derive the shared secret ("Z") that the
+      tenant had derived.
+
+   1. The PSP will derive the master secret ("M") using the shared secret it had just derived.
+
+   1. The PSP will derive the Key Encryption Key ("kek") and the Key Integrity Key ("kik") from the master
+      key ("M").
+
+   1. The PSP will decrypt the KIK-protected buffer sent by the tenant which contains the KEK (which itself wraps
+      around the concatenated TEK and TIK data).
+
+   1. The PSP will decrypt the KEK-wrapped buffer to reveal the TEK/TIK concatenated buffer.
+
+##### Measurement
+
+1. The PSP will create an SEV context for the tenant's virtual machine (guest) and begin bootstrapping an encrypted
+   environment for the it.
+
+   1. The PSP will use the TIK to decrypt the policy and associate the policy with the guest for the entirety
+      of its lifetime.
+
+   1. The PSP will create a cryptographic measurement of the pages provided by the host.
+
+   1. The PSP will encrypt the guest's pages.
+
+   1. The PSP will use the TIK to hash and sign the measurement it took of the pages prior to encryption and
+      send this reply to the host which then routes it to the tenant.
+
+   | transmitted as | component |
+   | --------------: | - |
+   | integrity-protected | (TIK: measurement) |
+
+1. The tenant will digest the response from the PSP containing the measurement of the virtual machine image.
+
+1. The tenant will perform its own measurement of the pages. If it calculates the same measurement, then the image is
+   exactly what the tenant was expecting. If not, attestation has failed, and the tenant should assume the image has
+   been tampered with.
+
+##### Launch
+
+1. If the tenant agrees with the PSP's measurement of the pages, the guest is now ready to securely receive any
+   secret metadata.
+
+   1. The tenant will generate a new initialization vector ("IV") to seed AES-128 encryption used to protect
+      the transmission of the secret.
+
+   1. The secret will be encrypted with AES 128 using the TEK to calculate the ciphertext.
+
+   1. The secret ciphertext will be hashed and signed by the TIK with HMAC-SHA256.
+
+1. The tenant will send the encrypted metadata (secret) to the host which will then relay it to the PSP.
+
+   | transmitted as | component |
+   | --------------: | - |
+   | ciphertext | (TEK: secret metadata)  |
+   | integrity-protected | (TIK: TEK) |
+
+1. The PSP will decrypt the ciphertext containing the secret and place it into the guest's memory.
+
+1. Finally, attestation has successfully concluded and the virtual machine's launch is complete. The virtual
+   machine is now ready to run under the protection of AMD SEV.
+
+Please note that attestation for SEV-ES and SEV-SNP will be documented at a later date.
+
+#### Protections
+
+After attestation completes successfully, a guest is assured to receive [a number of protections](
+./protections.md).
+
+#### References
+
+This document relies on a number of resources to accurately summarize the deeply technical process of attestation.
+Please note that **this document will defer to AMD's official documentation if any component here is found to be in
+disagreement with the AMD SEV's documentation.** If a discrepency is found, please reach out to file an issue and/or
+open a pull request to notify the Enarx team. Your assistance is sincerely appreciated.
+
+* [AMD Secure Encrypted Virtualization (SEV) API, revision 0.22](https://developer.amd.com/wp-content/resources/55766.PDF)

package/bindings/sp-sev/docs/attestation/certchain.dot

@@ -0,0 +1,14 @@
+# Commits which modify this file MUST generate the new .png!
+digraph G {
+    node [style=filled];
+
+    node [fillcolor=blue, fontcolor=white];
+    CEK;
+
+    node [fillcolor=none, fontcolor=black];
+    ARK -> ASK;
+    ASK -> CEK;
+    CEK -> PEK;
+    PEK -> PDH;
+    OCA -> PEK;
+}

package/bindings/sp-sev/docs/attestation/prerequisites.md

@@ -0,0 +1,6 @@
+# Prerequisites
+
+Attestation is built on a number of technical concepts. Readers should familiarize
+themselves with the following topics:
+
+* [Public-key Cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography)