Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Welcome to SEV OS Certification


The purpose of this repository is to provide a unified framework for testing and certifying operating system support for [AMD Secure Encrypted Virtualization (SEV)](https://www.amd.com/en/developer/sev.html) features. These are hardware-enabled security features that provide confidentiality and integrity of VM memory through per-VM encryption keys. Self-service tools are provided to run a series of certification tests using an AMD EPYC server, allowing for any user/organization to verify SEV support on a particular OS.
The purpose of this repository is to provide a unified framework for testing and certifying operating system support for [AMD Secure Encrypted Virtualization (SEV)](https://www.amd.com/en/developer/sev.html) features. These are hardware-enabled security features that provide confidentiality and integrity of VM memory through per-VM encryption keys. Self-service tools are provided to run a series of certification tests using an AMD EPYC server, allowing for any user/organization to verify SEV support on a particular OS. Users who are new to AMD Secure Encrypted Virtualization (SEV) are encouraged to consult the introductory guide titled [Getting Started User Guide for SEV](./docs/getting-started-user-guide-for-sev.md) for foundational information and setup instructions..

**Note**: Currently only linux distributions supported by [`mkosi`](https://github.com/systemd/mkosi) are compatible with this framework.

Expand Down
93 changes: 93 additions & 0 deletions docs/getting-started-user-guide-for-sev.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# Getting Started Guide for AMD Security Feature(SEV) on AMD EPYC Processor
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
# Getting Started Guide for AMD Security Feature(SEV) on AMD EPYC Processor
# Enabling AMD Security Features in AMD EPYC Processors


## SEV Introduction
When a virtual machine is started, data is loaded into memory (RAM). This makes the data vulnerable to software or hardware probing by attackers on the host system, especially in shared environments like cloud computing, where resources are shared by many tenants. For this reason, users must ensure that the data in RAM is secure and protected from both attackers and hypervisors. This reduces the amount of trust virtual machines need to place in the hypervisor and the host system's administrators.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When a virtual machine is started, data is loaded into memory (RAM). This makes the data vulnerable to software or hardware probing by attackers on the host system, especially in shared environments like cloud computing, where resources are shared by many tenants. For this reason, users must ensure that the data in RAM is secure and protected from both attackers and hypervisors. This reduces the amount of trust virtual machines need to place in the hypervisor and the host system's administrators.
When a virtual machine (VM) starts, data is loaded into system memory (RAM). This data can be vulnerable to software or hardware probing by attackers on the host systemespecially in shared environments like cloud platforms, where multiple tenants share the same physical resources. To mitigate this risk, users must ensure that data in RAM is protected from both attackers and hypervisors. Doing so reduces the level of trust that virtual machines need to place in the hypervisor and host administrators.
AMD EPYC processors introduce confidential computing technologies that provide memory encryption for virtualized environments, protecting data not only from physical attacks but also from other virtual machines and even the hypervisor itself.
The following sections describe the different generations of Secure Encrypted Virtualization (SEV), each building on the previous generation and introducing new security capabilities and features:


**AMD's SEV (Secure Encrypted Virtualization)** is a technology used to protect KVM virtual machines (VMs) by transparently encrypting the memory of each VM with a unique key. SEV can also calculate a signature of the memory's content. This signature is provided to the VM's owner as an attestation to prove that the memory was correctly encrypted by the firmware.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**AMD's SEV (Secure Encrypted Virtualization)** is a technology used to protect KVM virtual machines (VMs) by transparently encrypting the memory of each VM with a unique key. SEV can also calculate a signature of the memory's content. This signature is provided to the VM's owner as an attestation to prove that the memory was correctly encrypted by the firmware.
**SEV (Secure Encrypted Virtualization)**: is the first generation of the security features. It protects KVM virtual machines (VMs) by transparently encrypting the memory of the VM using a unique key.


**AMD's SEV-ES (Secure Encrypted Virtualization - Encrypted State)** is a technology that encrypts all CPU register contents when a VM halts running, preventing the information leak from the CPU registers to components like hypervisor.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**AMD's SEV-ES (Secure Encrypted Virtualization - Encrypted State)** is a technology that encrypts all CPU register contents when a VM halts running, preventing the information leak from the CPU registers to components like hypervisor.
**ES (Encrypted State)**: is the second generation of SEV. It adds CPU register encryption when a VM stops running, preventing the information leak from the CPU registers to components like the hypervisor.


**AMD's SEV-SNP (AMD Secure Encrypted Virtualization-Secure Nested Paging)** is a technology which adds strong memory integrity protection on top of AMD's SEV and SEV-ES to aid in preventing malicious hypervisor-based attacks(data replay, memory mapping and so on) to create an isolated execution environment.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**AMD's SEV-SNP (AMD Secure Encrypted Virtualization-Secure Nested Paging)** is a technology which adds strong memory integrity protection on top of AMD's SEV and SEV-ES to aid in preventing malicious hypervisor-based attacks(data replay, memory mapping and so on) to create an isolated execution environment.
**SNP (Secure Nested Paging)**: is the third generation of SEV. It adds strong memory integrity protection on top of SEV and ES to aid in preventing malicious hypervisor-based attacks(data replay, memory mapping and more) to create an isolated execution environment. SNP also introduces several additional optional security enhancements designed to support additional VM use models, offer stronger protection around interrupt behavior, and offer increased protection against recently disclosed side channel attacks. It also introduces a new attestation model that allows run-time attestation in SNP protected VMs.


Resources
[AMD Secure Encrypted Virtualization Developer Central](https://www.amd.com/en/developer/sev.html)
[AMD-SEV Guide on SUSE Linux Enterprise Server 15 SP7 distribution](https://documentation.suse.com/sles/15-SP7/html/SLES-amd-sev/article-amd-sev.html#:~:text=AMD's%20Secure%20Encrypted%20Virtualization%20(SEV,virtual%20machine's%20CPU%20register%20content.))
Comment on lines +12 to +14
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Resources
[AMD Secure Encrypted Virtualization Developer Central](https://www.amd.com/en/developer/sev.html)
[AMD-SEV Guide on SUSE Linux Enterprise Server 15 SP7 distribution](https://documentation.suse.com/sles/15-SP7/html/SLES-amd-sev/article-amd-sev.html#:~:text=AMD's%20Secure%20Encrypted%20Virtualization%20(SEV,virtual%20machine's%20CPU%20register%20content.))
Additional Resources:
[AMD Secure Encrypted Virtualization Developer Central](https://www.amd.com/en/developer/sev.html)
[Using SEV with AMD EPYC Processors](https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/tuning-guides/58207-using-sev-with-amd-epyc-processors.pdf)

Also maybe put this at the bottom


## User-Specific SEV Implementation Guide
Stakeholders with varying objectives can utilize the following user guides to begin their implementation of AMD's SEV.
Comment on lines +16 to +17
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## User-Specific SEV Implementation Guide
Stakeholders with varying objectives can utilize the following user guides to begin their implementation of AMD's SEV.
## Configuring SNP
Users can utilize the following guides to set-up SNP in their system.


### 1. Host
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### 1. Host
### 1. Host configuration

Host system users can configure AMD's Secure Encrypted Virtualization (SEV) and subsequently verify its enablement within their specific Linux environment.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Host system users can configure AMD's Secure Encrypted Virtualization (SEV) and subsequently verify its enablement within their specific Linux environment.
Enable SNP in your host in order to launch SNP protected VMs.


#### Enable AMD's security feature(SEV) in the host BIOS
The host hardware should support AMD's SEV technology and should be enabled in the server BIOS.
Comment on lines +22 to +23
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Before this section I would add an SNP host requirements section:

#### SNP host requirements:
AMD EPYC Processor: 7003 or newer
kernel version: 6.11 or newer

Comment on lines +22 to +23
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
#### Enable AMD's security feature(SEV) in the host BIOS
The host hardware should support AMD's SEV technology and should be enabled in the server BIOS.
#### Enable AMD's security feature(SEV) in the host BIOS
To enable SNP in BIOS you need to enable the following settings:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then put the general settings you need enabled to enable everything from SEV to SNP. Also add a notice that the settings might be different depending on what system the user has.


Host users should enable AMD Secure Memory Encryption (SMEE) feature in BIOS on the host hardware containing AMD EPYC processors. Follow the instructions posted in [Using SEV with AMD EPYC Processors](https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/tuning-guides/58207-using-sev-with-amd-epyc-processors.pdf) to enable AMD SEV features from BIOS.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Host users should enable AMD Secure Memory Encryption (SMEE) feature in BIOS on the host hardware containing AMD EPYC processors. Follow the instructions posted in [Using SEV with AMD EPYC Processors](https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/tuning-guides/58207-using-sev-with-amd-epyc-processors.pdf) to enable AMD SEV features from BIOS.
For a more in depth enablement guide, please take a look at the "Using SEV with AMD EPYC Processors" guide in our additional resources.


#### Verify for AMD's security feature enablement on the host
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
#### Verify for AMD's security feature enablement on the host
#### Verify SNP enablement

Host users are advised to manually verify the enablement of AMD’s security features (SEV, SEV-ES, and SEV-SNP) within their Linux host environment. To facilitate this verification, users may utilize the snphost tool to assess SEV-SNP support on the system:
- Download the latest snphost release from [snphost GH Releases](https://github.com/virtee/snphost/releases) page.
- Execute the command `snphost ok` to confirm the presence and status of the supported security features.
Comment on lines +28 to +30
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Host users are advised to manually verify the enablement of AMD’s security features (SEV, SEV-ES, and SEV-SNP) within their Linux host environment. To facilitate this verification, users may utilize the snphost tool to assess SEV-SNP support on the system:
- Download the latest snphost release from [snphost GH Releases](https://github.com/virtee/snphost/releases) page.
- Execute the command `snphost ok` to confirm the presence and status of the supported security features.
To verify the complete enablement of AMD’s security features (SEV, ES, and SNP) within their Linux host, users may utilize the [Virtee snphost](https://github.com/virtee/snphost) tool to assess SNP support and enablement on the system:
To use this tool:
1. Download the latest snphost release from [snphost GH Releases](https://github.com/virtee/snphost/releases) page.
2. Execute the command `snphost ok` to confirm the presence and status of the supported security features.


### 2. Guest
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
### 2. Guest
### 2. Guest Launch and enablement

Guest users can launch SNP-enabled QEMU guest on the SNP host.
**Host Requirements:**
- Guest users should ensure that the below required packages are installed on the host:
- kernel package version: 6.11+
- QEMU version: 9.2+
- OVMF version: 2024.11+
Comment on lines +33 to +38
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Guest users can launch SNP-enabled QEMU guest on the SNP host.
**Host Requirements:**
- Guest users should ensure that the below required packages are installed on the host:
- kernel package version: 6.11+
- QEMU version: 9.2+
- OVMF version: 2024.11+
#### Guest Requirements
An SNP enabled guest can be launched after the host has properly set-up and enabled SNP.
The following are **guest** requirements to launch an SNP enabled VM:
- Guest kernel version: 5.19+
- QEMU version: 9.2+
- OVMF version: 2024.11+


**Procedure:**
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**Procedure:**
#### Guest Launch

Guest users may initiate SEV-SNP-enabled virtual machine boots using the QEMU hypervisor by either utilizing the guest UKI artifacts provided in the [sev-certify](https://github.com/AMDEPYC/sev-certify.git) project or deploying their own custom guest image.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Guest users may initiate SEV-SNP-enabled virtual machine boots using the QEMU hypervisor by either utilizing the guest UKI artifacts provided in the [sev-certify](https://github.com/AMDEPYC/sev-certify.git) project or deploying their own custom guest image.
Guest users may initiate SEV-SNP-enabled virtual machine boots using the QEMU hypervisor by utilizing the mainline release of one of the certified images in this repository. Please reference the table of certified images here: **link to table**

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Truthfully the images we produce on this project are not really meant for daily use. They're test reference images with a lot of functionality stripped or modified. So maybe the instruction here is for users to get a mainline image from the test images we have certified in the repo.


Guest users have two options for launching an SEV-SNP-enabled virtual machine using QEMU:
- **Option 1:** Download or build guest artifacts tailored to their specific operating system distribution from the [sev-certify](https://github.com/AMDEPYC/sev-certify.git) project. These artifacts can then be used to initiate an SEV-SNP-enabled guest following the procedures outlined in the [how-to-run-guest-manually](https://github.com/AMDEPYC/sev-certify/blob/main/docs/how-to-run-guest-manually.md) guide.

- **Option 2**: Directly boot an SEV-SNP-enabled guest using a custom guest image by specifying the appropriate QEMU command-line parameters.
Comment on lines +43 to +46
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Guest users have two options for launching an SEV-SNP-enabled virtual machine using QEMU:
- **Option 1:** Download or build guest artifacts tailored to their specific operating system distribution from the [sev-certify](https://github.com/AMDEPYC/sev-certify.git) project. These artifacts can then be used to initiate an SEV-SNP-enabled guest following the procedures outlined in the [how-to-run-guest-manually](https://github.com/AMDEPYC/sev-certify/blob/main/docs/how-to-run-guest-manually.md) guide.
- **Option 2**: Directly boot an SEV-SNP-enabled guest using a custom guest image by specifying the appropriate QEMU command-line parameters.
To boot one of the mainline qcow2 images from one of the certified OS, the user can use a command similar to the following:

Same idea. For daily/common use, we don't tell them to use our artifacts, we tell them to grab one of the certified images from the official repo.

```sh
$ qemu-system-x86_64 \
-enable-kvm \
-machine q35 \
-cpu EPYC-v4 \
-machine memory-encryption=sev0 \
-monitor none \
-display none \
-object memory-backend-memfd,id=ram1,size=<guest-ram-size> \
-machine memory-backend=ram1 \
-object sev-snp-guest,id=sev0,cbitpos=51,reduced-phys-bits=1 kernel-hashes=on" \
-bios <amdsev-ovmf-path> \
-kernel <guest-user-image-path>
Comment on lines +48 to +59
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
$ qemu-system-x86_64 \
-enable-kvm \
-machine q35 \
-cpu EPYC-v4 \
-machine memory-encryption=sev0 \
-monitor none \
-display none \
-object memory-backend-memfd,id=ram1,size=<guest-ram-size> \
-machine memory-backend=ram1 \
-object sev-snp-guest,id=sev0,cbitpos=51,reduced-phys-bits=1 kernel-hashes=on" \
-bios <amdsev-ovmf-path> \
-kernel <guest-user-image-path>
$ qemu-system-x86_64 \
-enable-kvm \
-machine q35 \
-cpu EPYC-v4 \
-machine memory-encryption=sev0 \
-monitor none \
-display none \
-object memory-backend-memfd,id=ram1,size=<guest-ram-size> \
-machine memory-backend=ram1 \
-object sev-snp-guest,id=sev0,cbitpos=51,reduced-phys-bits=1 kernel-hashes=on\
-bios <amdsev-ovmf-path> \
-hda path-to-image

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also you have an extra quotation mark (") that messes everything up.

```
Users may allocate the desired amount of memory for the guest virtual machine, with a minimum requirement of 2 GB (2048 MB).

`amdsev-ovmf-path` refers to the AMDSEV UEFI compatible guest firmware located at either `/usr/share/ovmf/OVMF.amdsev.fd` or `/usr/share/edk2/ovmf/OVMF.amdsev.fd` based on your host linux distribution.

`guest-user-image-path` refers to your custom guest image file path.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also in your command remember that UKIs can be booted using the -kernel parameter, but regular qcow2 images can't. So it would be important to note the difference.


Guest users can refer to [QEMU documentation](https://www.qemu.org/documentation/) for the additional guest capabilities.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe point them here https://www.qemu.org/docs/master/system/i386/amd-memory-encryption.html to see more sev settings they can set.


### 3. Verifier
Verifiers seek to perform AMD' SEV validation checks to confirm the presence and functionality of AMD’s Secure Encrypted Virtualization features. These verifiers may include operating system vendors, hardware manufacturers, or OEMs evaluating support within their platforms, firmware, or pre-release operating systems.
Comment on lines +69 to +70
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't really understand what a verifier is supposed to be. Someone that is verifying OS distros?


A comprehensive list of operating systems that support AMD SEV features is available in the [Certification Matrix](https://github.com/AMDEPYC/sev-certify#certification-matrix). Additionally, verifiers may review detailed host and guest SEV status reports within the GitHub Issues section of the sev-certify repository, which are automatically generated by the [dispatch](https://github.com/AMDEPYC/dispatch.git) tool.

**Procedure**
Verifiers may generate a new SEV certificate to evaluate the status of AMD SEV features on their specific hardware, firmware, or pre-release operating system. The process involves the following steps:
- **Fork the [sev-certify](https://github.com/AMDEPYC/sev-certify.git) repository** to create a personalized workspace for validation.
- **Operating system vendors** intending to test a new pre-release should incorporate support for their OS version within their fork of the [sev-certify](https://github.com/AMDEPYC/sev-certify.git) repository. This is achieved by creating a corresponding `mkosi.conf` configuration file using the mkosi tool, and placing it under the `images/` directory to define host and guest image parameters.

- **Verify the presence of the newly added host and guest artifacts** under the `Development Images` release tag in the forked sev-certify repository.

- **Set up and execute the [dispatch](https://github.com/AMDEPYC/dispatch.git) tool** against the development branch of the forked repository. Instructions for configuring and running the dispatch tool with the current host artifacts can be found [here](https://github.com/AMDEPYC/sev-certify/blob/main/docs/how-to-generate-certs.md).

To validate a new OS pre-release, verifiers can run the dispatch tool on your `sev-certify` fork using the following command::
```sh
./dispatch --owner <your GH username> --repo sev-certify <your-new-os-pre-release>
```

Alternatively, to download and utilize all existing host artifacts from your `sev-certify` fork, the following command may be used:
```sh
./dispatch --owner <your GH username> --repo sev-certify
```

- **Review the new sev-certificate** by examining the newly generated GitHub issues under the forked sev-certify repository, which detail the AMD's SEV feature status and validation outcomes.
Comment on lines +79 to +93
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of writing these instructions you could point them to the guide that was already written about how to run the project.