SEV 게스트 API 완전 문서

1. 일반 설명

SEV API는 게스트 또는 하이퍼바이저가 SEV 가상 머신의 특정 속성을 조회하거나 설정하는 ioctl 집합입니다.

ioctl은 두 종류로 나뉩니다. hypervisor ioctl은 SEV firmware 전체에 영향을 주는 전역 속성을 조회·설정하며 platform provisioning 도구가 사용합니다. guest ioctl은 개별 SEV 가상 머신의 속성을 조회·설정합니다.

.. SPDX-License-Identifier: GPL-2.0

===================================================================
The Definitive SEV Guest API Documentation
===================================================================

1. General description
======================

The SEV API is a set of ioctls that are used by the guest or hypervisor
to get or set a certain aspect of the SEV virtual machine. The ioctls belong
to the following classes:

 - Hypervisor ioctls: These query and set global attributes which affect the
   whole SEV firmware.  These ioctl are used by platform provisioning tools.

 - Guest ioctls: These query and set attributes of the SEV virtual machine.

2. API 설명과 공통 계약

각 ioctl 항목은 어떤 SEV 기술이 제공하는지(`SEV`, `SEV-ES`, `SEV-SNP` 또는 전체), guest와 hypervisor 중 어디에서 쓰는지, 입력 매개변수와 반환값을 함께 설명합니다. `-ENOMEM`, `-EINVAL` 같은 일반 오류는 반복하지 않고 명령별 의미가 있는 오류만 자세히 다룹니다.

Guest ioctl은 `/dev/sev-guest`의 파일 디스크립터에 발행합니다. ioctl 인자는 `struct snp_guest_request_ioctl`이며 `req_data`와 `resp_data`가 각각 입력 구조체와 출력 구조체 주소를 지정합니다.

Firmware 오류로 ioctl 실행이 실패하면 `fw_error`에 firmware 오류 코드가 설정되고, 그렇지 않으면 `fw_error`는 `-1`입니다. `exitinfo2`의 상위 32비트는 VMM 오류, 하위 32비트는 firmware 오류를 담습니다.

Firmware는 메시지 sequence counter가 게스트의 이전 counter보다 정확히 1 큰지 검사합니다. 게스트 드라이버가 counter overflow 등으로 값을 증가시키지 못하면 `-EIO`가 반환됩니다.

2. API description
==================

This section describes ioctls that is used for querying the SEV guest report
from the SEV firmware. For each ioctl, the following information is provided
along with a description:

  Technology:
      which SEV technology provides this ioctl. SEV, SEV-ES, SEV-SNP or all.

  Type:
      hypervisor or guest. The ioctl can be used inside the guest or the
      hypervisor.

  Parameters:
      what parameters are accepted by the ioctl.

  Returns:
      the return value.  General error numbers (-ENOMEM, -EINVAL)
      are not detailed, but errors with specific meanings are.

The guest ioctl should be issued on a file descriptor of the /dev/sev-guest
device.  The ioctl accepts struct snp_user_guest_request. The input and
output structure is specified through the req_data and resp_data field
respectively. If the ioctl fails to execute due to a firmware error, then
the fw_error code will be set, otherwise fw_error will be set to -1.

The firmware checks that the message sequence counter is one greater than
the guests message sequence counter. If guest driver fails to increment message
counter (e.g. counter overflow), then -EIO will be returned.

Guest 요청 ioctl 구조체

`struct snp_guest_request_ioctl`은 메시지 버전, 요청·응답 버퍼의 사용자 주소, firmware와 VMM 오류를 전달하는 공용체로 구성됩니다.

`exitinfo2`로 전체 64비트 오류 값을 읽거나 `fw_error`와 `vmm_error` 두 32비트 필드로 나누어 읽을 수 있습니다. 구체적인 firmware 오류 정의는 `psp-sev.h`를 따릅니다.

::

        struct snp_guest_request_ioctl {
                /* Message version number */
                __u32 msg_version;

                /* Request and response structure address */
                __u64 req_data;
                __u64 resp_data;

                /* bits[63:32]: VMM error code, bits[31:0] firmware error code (see psp-sev.h) */
                union {
                        __u64 exitinfo2;
                        struct {
                                __u32 fw_error;
                                __u32 vmm_error;
                        };
                };
        };

Host 명령 ioctl 구조체

Host ioctl은 `/dev/sev`의 파일 디스크립터에 발행하며 아래에서 설명하는 command ID와 입력 구조체를 `struct sev_issue_cmd`로 전달합니다.

`cmd`는 명령 ID, `data`는 명령 요청 구조체 주소, `error`는 실패 시의 firmware 오류 코드입니다. 오류 코드 정의는 guest 구조체와 마찬가지로 `psp-sev.h`를 참조합니다.

The host ioctls are issued to a file descriptor of the /dev/sev device.
The ioctl accepts the command ID/input structure documented below.

::

        struct sev_issue_cmd {
                /* Command ID */
                __u32 cmd;

                /* Command request structure */
                __u64 data;

                /* Firmware error code on failure (see psp-sev.h) */
                __u32 error;
        };

2.1 SNP_GET_REPORT

`SNP_GET_REPORT`는 SEV-SNP guest ioctl입니다. 입력은 `struct snp_report_req`, 성공 출력은 `struct snp_report_resp`이고 오류 시 음수 값을 반환합니다.

이 ioctl은 SEV-SNP firmware의 `SNP_GUEST_REQUEST`(`MSG_REPORT_REQ`) 명령으로 attestation report를 조회합니다. 성공하면 `snp_report_resp.data`에 SEV-SNP 명세 형식의 report가 들어갑니다.

2.1 SNP_GET_REPORT
------------------

:Technology: sev-snp
:Type: guest ioctl
:Parameters (in): struct snp_report_req
:Returns (out): struct snp_report_resp on success, -negative on error

The SNP_GET_REPORT ioctl can be used to query the attestation report from the
SEV-SNP firmware. The ioctl uses the SNP_GUEST_REQUEST (MSG_REPORT_REQ) command
provided by the SEV-SNP firmware to query the attestation report.

On success, the snp_report_resp.data will contains the report. The report
contain the format described in the SEV-SNP specification. See the SEV-SNP
specification for further details.

2.2 SNP_GET_DERIVED_KEY

`SNP_GET_DERIVED_KEY`는 SEV-SNP guest ioctl입니다. 입력은 `struct snp_derived_key_req`, 성공 출력은 `struct snp_derived_key_resp`이며 오류 시 음수 값을 반환합니다.

Root key에서 파생한 키를 얻으며, 게스트는 sealing key를 만들거나 외부 entity와 통신하는 등 임의의 용도로 이 키를 사용할 수 있습니다.

ioctl은 firmware의 `SNP_GUEST_REQUEST`(`MSG_KEY_REQ`) 명령을 사용합니다. 요청 필드의 세부 의미는 SEV-SNP 명세를 따르고, 성공하면 `snp_derived_key_resp.data`에 derived key 값이 들어갑니다.

2.2 SNP_GET_DERIVED_KEY
-----------------------
:Technology: sev-snp
:Type: guest ioctl
:Parameters (in): struct snp_derived_key_req
:Returns (out): struct snp_derived_key_resp on success, -negative on error

The SNP_GET_DERIVED_KEY ioctl can be used to get a key derive from a root key.
The derived key can be used by the guest for any purpose, such as sealing keys
or communicating with external entities.

The ioctl uses the SNP_GUEST_REQUEST (MSG_KEY_REQ) command provided by the
SEV-SNP firmware to derive the key. See SEV-SNP specification for further details
on the various fields passed in the key derivation request.

On success, the snp_derived_key_resp.data contains the derived key value. See
the SEV-SNP specification for further details.

2.3 SNP_GET_EXT_REPORT

`SNP_GET_EXT_REPORT`는 `SNP_GET_REPORT`와 비슷한 SEV-SNP guest ioctl이지만 report와 함께 추가 certificate data를 반환합니다. 입력·출력 요청은 `struct snp_ext_report_req`, report 출력은 `struct snp_report_resp`입니다.

Certificate data는 hypervisor가 `SNP_SET_EXT_CONFIG`로 제공합니다. ioctl은 firmware의 `SNP_GUEST_REQUEST`(`MSG_REPORT_REQ`)로 attestation report를 얻습니다.

성공하면 report는 `snp_ext_report_resp.data`, certificate blob은 `snp_ext_report_req.certs_address`가 가리키는 버퍼에 저장됩니다. 제공한 blob 길이가 필요한 크기보다 작으면 `certs_len`이 예상 크기로 갱신됩니다. Certificate blob 파싱 방법은 GHCB 명세를 따릅니다.

2.3 SNP_GET_EXT_REPORT
----------------------
:Technology: sev-snp
:Type: guest ioctl
:Parameters (in/out): struct snp_ext_report_req
:Returns (out): struct snp_report_resp on success, -negative on error

The SNP_GET_EXT_REPORT ioctl is similar to the SNP_GET_REPORT. The difference is
related to the additional certificate data that is returned with the report.
The certificate data returned is being provided by the hypervisor through the
SNP_SET_EXT_CONFIG.

The ioctl uses the SNP_GUEST_REQUEST (MSG_REPORT_REQ) command provided by the SEV-SNP
firmware to get the attestation report.

On success, the snp_ext_report_resp.data will contain the attestation report
and snp_ext_report_req.certs_address will contain the certificate blob. If the
length of the blob is smaller than expected then snp_ext_report_req.certs_len will
be updated with the expected value.

See GHCB specification for further detail on how to parse the certificate blob.

2.4 SNP_PLATFORM_STATUS

`SNP_PLATFORM_STATUS`는 SEV-SNP hypervisor ioctl command입니다. 출력 매개변수는 `struct sev_user_data_snp_status`이며 성공 시 0, 오류 시 음수를 반환합니다. API major·minor version 등을 포함한 SNP platform status를 조회하며 필드 세부 사항은 SEV-SNP 명세를 따릅니다.

2.4 SNP_PLATFORM_STATUS
-----------------------
:Technology: sev-snp
:Type: hypervisor ioctl cmd
:Parameters (out): struct sev_user_data_snp_status
:Returns (out): 0 on success, -negative on error

The SNP_PLATFORM_STATUS command is used to query the SNP platform status. The
status includes API major, minor version and more. See the SEV-SNP
specification for further details.

2.5 SNP_COMMIT

`SNP_COMMIT`은 SEV-SNP hypervisor ioctl command이며 성공 시 0, 오류 시 음수를 반환합니다. SEV-SNP firmware의 동명 명령으로 현재 설치된 firmware를 commit합니다.

Commit하면 이전에 commit한 firmware version으로 rollback할 수 없게 되며, 보고되는 TCB도 현재 설치된 firmware의 TCB와 일치하도록 갱신됩니다.

2.5 SNP_COMMIT
--------------
:Technology: sev-snp
:Type: hypervisor ioctl cmd
:Returns (out): 0 on success, -negative on error

SNP_COMMIT is used to commit the currently installed firmware using the
SEV-SNP firmware SNP_COMMIT command. This prevents roll-back to a previously
committed firmware version. This will also update the reported TCB to match
that of the currently installed firmware.

2.6 SNP_SET_CONFIG

`SNP_SET_CONFIG`는 SEV-SNP hypervisor ioctl command입니다. 입력은 `struct sev_user_data_snp_config`이며 성공 시 0, 오류 시 음수를 반환합니다.

Attestation report에 표시할 TCB version 같은 system-wide 구성을 설정합니다. SEV-SNP 명세의 `SNP_CONFIG`와 유사하며, 이 명령이 바꾸는 현재 firmware parameter 값은 `SNP_PLATFORM_STATUS`로 조회할 수 있습니다.

2.6 SNP_SET_CONFIG
------------------
:Technology: sev-snp
:Type: hypervisor ioctl cmd
:Parameters (in): struct sev_user_data_snp_config
:Returns (out): 0 on success, -negative on error

SNP_SET_CONFIG is used to set the system-wide configuration such as
reported TCB version in the attestation report. The command is similar
to SNP_CONFIG command defined in the SEV-SNP spec. The current values of
the firmware parameters affected by this command can be queried via
SNP_PLATFORM_STATUS.

2.7 SNP_VLEK_LOAD

`SNP_VLEK_LOAD`는 SEV-SNP hypervisor ioctl command입니다. 입력은 `struct sev_user_data_snp_vlek_load`이며 성공 시 0, 오류 시 음수를 반환합니다.

게스트는 attestation report 서명 키로 chip 고유 secret에서 파생한 Versioned Chip Endorsement Key(VCEK) 또는 AMD Key Derivation Service(KDS)에서 받아 등록된 cloud service provider용 seed로 파생한 Versioned Loaded Endorsement Key(VLEK)를 선택할 수 있습니다.

VLEK를 사용할 때는 KDS에서 키를 받은 뒤 `SNP_VLEK_LOAD` 명령으로 system에 적재합니다. 이 ioctl은 SEV-SNP 명세의 firmware `SNP_VLEK_LOAD` 명령과 밀접하게 대응합니다.

2.7 SNP_VLEK_LOAD
-----------------
:Technology: sev-snp
:Type: hypervisor ioctl cmd
:Parameters (in): struct sev_user_data_snp_vlek_load
:Returns (out): 0 on success, -negative on error

When requesting an attestation report a guest is able to specify whether
it wants SNP firmware to sign the report using either a Versioned Chip
Endorsement Key (VCEK), which is derived from chip-unique secrets, or a
Versioned Loaded Endorsement Key (VLEK) which is obtained from an AMD
Key Derivation Service (KDS) and derived from seeds allocated to
enrolled cloud service providers.

In the case of VLEK keys, the SNP_VLEK_LOAD SNP command is used to load
them into the system after obtaining them from the KDS, and corresponds
closely to the SNP_VLEK_LOAD firmware command specified in the SEV-SNP
spec.

3. SEV-SNP CPUID 강제

SEV-SNP 게스트는 `SNP_LAUNCH_UPDATE` firmware 명령의 일부로 PSP가 검증한 CPUID 값 표를 담은 특별한 페이지에 접근할 수 있습니다.

페이지 주소는 bootloader 또는 firmware가 CC blob을 통해 제공하며, 이 binary들은 SEV-SNP attestation report의 measurement 대상입니다. 초기 페이지는 encrypted·pvalidated 상태이므로 runtime 변조는 의미 없는 값 쓰기나 backing page validation 상태 변경에 따른 `#VC` exception으로 이어집니다.

Hypervisor가 정상 페이지나 CPUID용이 아닌 encrypted page로 PSP 검사를 우회하려 하면 attestation report의 measurement가 달라집니다.

CPUID 페이지 내용 자체는 측정하지 않지만, 게스트 초기화 때 예상 내용을 바꾸려는 시도는 `SNP_LAUNCH_UPDATE` 중 PSP CPUID enforcement policy 검사를 받습니다. 게스트 소유자가 CPUID 값을 별도로 검사하면 이후에도 차이를 발견할 수 있습니다.

마지막 보장은 커널이 boot 전 단계에서 SEV-SNP CPUID를 일관되게 사용했을 때만 유효합니다. 그렇지 않으면 guest-owner attestation만으로는 boot 중 커널이 잘못된 값을 받지 않았다고 보장할 수 없습니다.

3. SEV-SNP CPUID Enforcement
============================

SEV-SNP guests can access a special page that contains a table of CPUID values
that have been validated by the PSP as part of the SNP_LAUNCH_UPDATE firmware
command. It provides the following assurances regarding the validity of CPUID
values:

 - Its address is obtained via bootloader/firmware (via CC blob), and those
   binaries will be measured as part of the SEV-SNP attestation report.
 - Its initial state will be encrypted/pvalidated, so attempts to modify
   it during run-time will result in garbage being written, or #VC exceptions
   being generated due to changes in validation state if the hypervisor tries
   to swap the backing page.
 - Attempts to bypass PSP checks by the hypervisor by using a normal page, or
   a non-CPUID encrypted page will change the measurement provided by the
   SEV-SNP attestation report.
 - The CPUID page contents are *not* measured, but attempts to modify the
   expected contents of a CPUID page as part of guest initialization will be
   gated by the PSP CPUID enforcement policy checks performed on the page
   during SNP_LAUNCH_UPDATE, and noticeable later if the guest owner
   implements their own checks of the CPUID values.

It is important to note that this last assurance is only useful if the kernel
has taken care to make use of the SEV-SNP CPUID throughout all stages of boot.
Otherwise, guest owner attestation provides no assurance that the kernel wasn't
fed incorrect values at some point during boot.

4. SEV 게스트 드라이버 통신 키

SEV 게스트와 AMD Secure Processor(ASP, PSP라고도 함)의 SEV firmware 사이 통신은 VM Platform Communication Key(VMPCK)로 보호됩니다.

기본적으로 `sev-guest` 드라이버는 게스트가 실행되는 VM Privilege Level(VMPL)에 연결된 VMPCK를 사용합니다.

드라이버가 이 키를 지운 경우에는 `sev-guest` 드라이버를 다시 적재하면서 `vmpck_id` module parameter로 원하는 다른 키를 지정할 수 있습니다. 키를 지우는 이유는 드라이버 구현을 참조해야 합니다.

4. SEV Guest Driver Communication Key
=====================================

Communication between an SEV guest and the SEV firmware in the AMD Secure
Processor (ASP, aka PSP) is protected by a VM Platform Communication Key
(VMPCK). By default, the sev-guest driver uses the VMPCK associated with the
VM Privilege Level (VMPL) at which the guest is running. Should this key be
wiped by the sev-guest driver (see the driver for reasons why a VMPCK can be
wiped), a different key can be used by reloading the sev-guest driver and
specifying the desired key using the vmpck_id module parameter.

참고 문헌과 구현 기준

SEV-SNP와 GHCB 명세는 원문이 가리키는 `developer.amd.com/sev`에서 확인할 수 있습니다.

이 드라이버 문서는 SEV-SNP firmware specification 0.9와 GHCB specification 2.0을 기준으로 합니다.

Reference
---------

SEV-SNP and GHCB specification: developer.amd.com/sev

The driver is based on SEV-SNP firmware spec 0.9 and GHCB spec version 2.0.