sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget'/translations/zh_CN/virt/coco/sev-guestmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/zh_TW/virt/coco/sev-guestmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/it_IT/virt/coco/sev-guestmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/ja_JP/virt/coco/sev-guestmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/ko_KR/virt/coco/sev-guestmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/pt_BR/virt/coco/sev-guestmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/sp_SP/virt/coco/sev-guestmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhcomment)}(h SPDX-License-Identifier: GPL-2.0h]h SPDX-License-Identifier: GPL-2.0}hhsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1hhhhhhA/var/lib/git/docbuild/linux/Documentation/virt/coco/sev-guest.rsthKubhsection)}(hhh](htitle)}(h*The Definitive SEV Guest API Documentationh]h*The Definitive SEV Guest API Documentation}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h1. General descriptionh]h1. General description}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hThe 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:h]hThe 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:}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh block_quote)}(h- 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. h]h bullet_list)}(hhh](h list_item)}(hHypervisor ioctls: These query and set global attributes which affect the whole SEV firmware. These ioctl are used by platform provisioning tools. h]h)}(hHypervisor ioctls: These query and set global attributes which affect the whole SEV firmware. These ioctl are used by platform provisioning tools.h]hHypervisor ioctls: These query and set global attributes which affect the whole SEV firmware. These ioctl are used by platform provisioning tools.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1j hjubj )}(hIGuest ioctls: These query and set attributes of the SEV virtual machine. h]h)}(hHGuest ioctls: These query and set attributes of the SEV virtual machine.h]hHGuest ioctls: These query and set attributes of the SEV virtual machine.}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj#ubah}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]bullet-uh1jhhhKhjubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubeh}(h]general-descriptionah ]h"]1. general descriptionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h2. API descriptionh]h2. API description}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhjQhhhhhKubh)}(hThis 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:h]hThis 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:}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjQhhubh)}(hXxTechnology: 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. h]hdefinition_list)}(hhh](hdefinition_list_item)}(hSTechnology: which SEV technology provides this ioctl. SEV, SEV-ES, SEV-SNP or all. h](hterm)}(h Technology:h]h Technology:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhj{ubh definition)}(hhh]h)}(hFwhich SEV technology provides this ioctl. SEV, SEV-ES, SEV-SNP or all.h]hFwhich SEV technology provides this ioctl. SEV, SEV-ES, SEV-SNP or all.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhj{ubeh}(h]h ]h"]h$]h&]uh1jyhhhKhjvubjz)}(hUType: hypervisor or guest. The ioctl can be used inside the guest or the hypervisor. h](j)}(hType:h]hType:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhKhjubj)}(hhh]h)}(hNhypervisor or guest. The ioctl can be used inside the guest or the hypervisor.h]hNhypervisor or guest. The ioctl can be used inside the guest or the hypervisor.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jyhhhKhjvubjz)}(h7Parameters: what parameters are accepted by the ioctl. h](j)}(h Parameters:h]h Parameters:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK"hjubj)}(hhh]h)}(h*what parameters are accepted by the ioctl.h]h*what parameters are accepted by the ioctl.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK"hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jyhhhK"hjvubjz)}(h~Returns: the return value. General error numbers (-ENOMEM, -EINVAL) are not detailed, but errors with specific meanings are. h](j)}(hReturns:h]hReturns:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhhhK&hj ubj)}(hhh]h)}(htthe return value. General error numbers (-ENOMEM, -EINVAL) are not detailed, but errors with specific meanings are.h]htthe return value. General error numbers (-ENOMEM, -EINVAL) are not detailed, but errors with specific meanings are.}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK%hjubah}(h]h ]h"]h$]h&]uh1jhj ubeh}(h]h ]h"]h$]h&]uh1jyhhhK&hjvubeh}(h]h ]h"]h$]h&]uh1jthjpubah}(h]h ]h"]h$]h&]uh1hhhhKhjQhhubh)}(hXiThe 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.h]hXiThe 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.}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK(hjQhhubh)}(hThe 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.h]hThe 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.}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK.hjQhhubh literal_block)}(hXstruct 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; }; }; };h]hXstruct 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; }; }; };}hjesbah}(h]h ]h"]h$]h&]hhuh1jchhhK4hjQhhubh)}(hThe host ioctls are issued to a file descriptor of the /dev/sev device. The ioctl accepts the command ID/input structure documented below.h]hThe host ioctls are issued to a file descriptor of the /dev/sev device. The ioctl accepts the command ID/input structure documented below.}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKFhjQhhubjd)}(hstruct sev_issue_cmd { /* Command ID */ __u32 cmd; /* Command request structure */ __u64 data; /* Firmware error code on failure (see psp-sev.h) */ __u32 error; };h]hstruct sev_issue_cmd { /* Command ID */ __u32 cmd; /* Command request structure */ __u64 data; /* Firmware error code on failure (see psp-sev.h) */ __u32 error; };}hjsbah}(h]h ]h"]h$]h&]hhuh1jchhhKKhjQhhubh)}(hhh](h)}(h2.1 SNP_GET_REPORTh]h2.1 SNP_GET_REPORT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKXubh field_list)}(hhh](hfield)}(hhh](h field_name)}(h Technologyh]h Technology}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubh field_body)}(hsev-snph]h)}(hjh]hsev-snp}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKZhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKZhjhhubj)}(hhh](j)}(hTypeh]hType}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(h guest ioctlh]h)}(hjh]h guest ioctl}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK[hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhK[hjhhubj)}(hhh](j)}(hParameters (in)h]hParameters (in)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(hstruct snp_report_reqh]h)}(hjh]hstruct snp_report_req}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK\hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhK\hjhhubj)}(hhh](j)}(h Returns (out)h]h Returns (out)}(hj8hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj5hhhKubj)}(h6struct snp_report_resp on success, -negative on error h]h)}(h5struct snp_report_resp on success, -negative on errorh]h5struct snp_report_resp on success, -negative on error}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK]hjFubah}(h]h ]h"]h$]h&]uh1jhj5ubeh}(h]h ]h"]h$]h&]uh1jhhhK]hjhhubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhKZubh)}(hThe 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.h]hThe 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.}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK_hjhhubh)}(hOn 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.h]hOn 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.}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKchjhhubeh}(h]snp-get-reportah ]h"]2.1 snp_get_reportah$]h&]uh1hhjQhhhhhKXubh)}(hhh](h)}(h2.2 SNP_GET_DERIVED_KEYh]h2.2 SNP_GET_DERIVED_KEY}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKhubj)}(hhh](j)}(hhh](j)}(h Technologyh]h Technology}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(hsev-snph]h)}(hjh]hsev-snp}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKihjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKihjhhubj)}(hhh](j)}(hTypeh]hType}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(h guest ioctlh]h)}(hjh]h guest ioctl}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKjhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKjhjhhubj)}(hhh](j)}(hParameters (in)h]hParameters (in)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(hstruct snp_derived_key_reqh]h)}(hjh]hstruct snp_derived_key_req}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKkhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKkhjhhubj)}(hhh](j)}(h Returns (out)h]h Returns (out)}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj,hhhKubj)}(h;struct snp_derived_key_resp on success, -negative on error h]h)}(h:struct snp_derived_key_resp on success, -negative on errorh]h:struct snp_derived_key_resp on success, -negative on error}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKlhj=ubah}(h]h ]h"]h$]h&]uh1jhj,ubeh}(h]h ]h"]h$]h&]uh1jhhhKlhjhhubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhKiubh)}(hThe 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.h]hThe 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.}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKnhjhhubh)}(hThe 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.h]hThe 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.}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKrhjhhubh)}(h|On success, the snp_derived_key_resp.data contains the derived key value. See the SEV-SNP specification for further details.h]h|On success, the snp_derived_key_resp.data contains the derived key value. See the SEV-SNP specification for further details.}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKvhjhhubeh}(h]snp-get-derived-keyah ]h"]2.2 snp_get_derived_keyah$]h&]uh1hhjQhhhhhKhubh)}(hhh](h)}(h2.3 SNP_GET_EXT_REPORTh]h2.3 SNP_GET_EXT_REPORT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK{ubj)}(hhh](j)}(hhh](j)}(h Technologyh]h Technology}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(hsev-snph]h)}(hjh]hsev-snp}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK|hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhK|hjhhubj)}(hhh](j)}(hTypeh]hType}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(h guest ioctlh]h)}(hjh]h guest ioctl}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK}hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhK}hjhhubj)}(hhh](j)}(hParameters (in/out)h]hParameters (in/out)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(hstruct snp_ext_report_reqh]h)}(hjh]hstruct snp_ext_report_req}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK~hjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhK~hjhhubj)}(hhh](j)}(h Returns (out)h]h Returns (out)}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj1hhhKubj)}(h6struct snp_report_resp on success, -negative on error h]h)}(h5struct snp_report_resp on success, -negative on errorh]h5struct snp_report_resp on success, -negative on error}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjBubah}(h]h ]h"]h$]h&]uh1jhj1ubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhK|ubh)}(hThe 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.h]hThe 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.}(hjfhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h}The ioctl uses the SNP_GUEST_REQUEST (MSG_REPORT_REQ) command provided by the SEV-SNP firmware to get the attestation report.h]h}The ioctl uses the SNP_GUEST_REQUEST (MSG_REPORT_REQ) command provided by the SEV-SNP firmware to get the attestation report.}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXOn 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.h]hXOn 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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hOSee GHCB specification for further detail on how to parse the certificate blob.h]hOSee GHCB specification for further detail on how to parse the certificate blob.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]snp-get-ext-reportah ]h"]2.3 snp_get_ext_reportah$]h&]uh1hhjQhhhhhK{ubh)}(hhh](h)}(h2.4 SNP_PLATFORM_STATUSh]h2.4 SNP_PLATFORM_STATUS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubj)}(hhh](j)}(hhh](j)}(h Technologyh]h Technology}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(hsev-snph]h)}(hjh]hsev-snp}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubj)}(hhh](j)}(hTypeh]hType}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(hhypervisor ioctl cmdh]h)}(hjh]hhypervisor ioctl cmd}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubj)}(hhh](j)}(hParameters (out)h]hParameters (out)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(hstruct sev_user_data_snp_statush]h)}(hj)h]hstruct sev_user_data_snp_status}(hj+hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj'ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubj)}(hhh](j)}(h Returns (out)h]h Returns (out)}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjDhhhKubj)}(h!0 on success, -negative on error h]h)}(h 0 on success, -negative on errorh]h 0 on success, -negative on error}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjUubah}(h]h ]h"]h$]h&]uh1jhjDubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhKubh)}(hThe 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.h]hThe 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.}(hjyhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]snp-platform-statusah ]h"]2.4 snp_platform_statusah$]h&]uh1hhjQhhhhhKubh)}(hhh](h)}(h2.5 SNP_COMMITh]h2.5 SNP_COMMIT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubj)}(hhh](j)}(hhh](j)}(h Technologyh]h Technology}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(hsev-snph]h)}(hjh]hsev-snp}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubj)}(hhh](j)}(hTypeh]hType}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(hhypervisor ioctl cmdh]h)}(hjh]hhypervisor ioctl cmd}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubj)}(hhh](j)}(h Returns (out)h]h Returns (out)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(h!0 on success, -negative on error h]h)}(h 0 on success, -negative on errorh]h 0 on success, -negative on error}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKhjhhubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhKubh)}(hX 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.h]hX 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.}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h] snp-commitah ]h"]2.5 snp_commitah$]h&]uh1hhjQhhhhhKubh)}(hhh](h)}(h2.6 SNP_SET_CONFIGh]h2.6 SNP_SET_CONFIG}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjJhhhhhKubj)}(hhh](j)}(hhh](j)}(h Technologyh]h Technology}(hjahhhNhNubah}(h]h ]h"]h$]h&]uh1jhj^hhhKubj)}(hsev-snph]h)}(hjqh]hsev-snp}(hjshhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjoubah}(h]h ]h"]h$]h&]uh1jhj^ubeh}(h]h ]h"]h$]h&]uh1jhhhKhj[hhubj)}(hhh](j)}(hTypeh]hType}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(hhypervisor ioctl cmdh]h)}(hjh]hhypervisor ioctl cmd}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKhj[hhubj)}(hhh](j)}(hParameters (in)h]hParameters (in)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(hstruct sev_user_data_snp_configh]h)}(hjh]hstruct sev_user_data_snp_config}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKhj[hhubj)}(hhh](j)}(h Returns (out)h]h Returns (out)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(h!0 on success, -negative on error h]h)}(h 0 on success, -negative on errorh]h 0 on success, -negative on error}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKhj[hhubeh}(h]h ]h"]h$]h&]uh1jhjJhhhhhKubh)}(hX,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.h]hX,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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjJhhubeh}(h]snp-set-configah ]h"]2.6 snp_set_configah$]h&]uh1hhjQhhhhhKubh)}(hhh](h)}(h2.7 SNP_VLEK_LOADh]h2.7 SNP_VLEK_LOAD}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj3hhhhhKubj)}(hhh](j)}(hhh](j)}(h Technologyh]h Technology}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjGhhhKubj)}(hsev-snph]h)}(hjZh]hsev-snp}(hj\hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjXubah}(h]h ]h"]h$]h&]uh1jhjGubeh}(h]h ]h"]h$]h&]uh1jhhhKhjDhhubj)}(hhh](j)}(hTypeh]hType}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjuhhhKubj)}(hhypervisor ioctl cmdh]h)}(hjh]hhypervisor ioctl cmd}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjuubeh}(h]h ]h"]h$]h&]uh1jhhhKhjDhhubj)}(hhh](j)}(hParameters (in)h]hParameters (in)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(h"struct sev_user_data_snp_vlek_loadh]h)}(hjh]h"struct sev_user_data_snp_vlek_load}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKhjDhhubj)}(hhh](j)}(h Returns (out)h]h Returns (out)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(h!0 on success, -negative on error h]h)}(h 0 on success, -negative on errorh]h 0 on success, -negative on error}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKhjDhhubeh}(h]h ]h"]h$]h&]uh1jhj3hhhhhKubh)}(hXWhen 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.h]hXWhen 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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj3hhubh)}(hIn 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.h]hIn 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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj3hhubeh}(h] snp-vlek-loadah ]h"]2.7 snp_vlek_loadah$]h&]uh1hhjQhhhhhKubeh}(h]api-descriptionah ]h"]2. api descriptionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h3. SEV-SNP CPUID Enforcementh]h3. SEV-SNP CPUID Enforcement}(hj5 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj2 hhhhhKubh)}(hSEV-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:h]hSEV-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:}(hjC hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj2 hhubh)}(hX- 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. h]j)}(hhh](j )}(hIts address is obtained via bootloader/firmware (via CC blob), and those binaries will be measured as part of the SEV-SNP attestation report.h]h)}(hIts address is obtained via bootloader/firmware (via CC blob), and those binaries will be measured as part of the SEV-SNP attestation report.h]hIts address is obtained via bootloader/firmware (via CC blob), and those binaries will be measured as part of the SEV-SNP attestation report.}(hj\ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjX ubah}(h]h ]h"]h$]h&]uh1j hjU ubj )}(hIts 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.h]h)}(hIts 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.h]hIts 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.}(hjt hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjp ubah}(h]h ]h"]h$]h&]uh1j hjU ubj )}(hAttempts 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.h]h)}(hAttempts 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.h]hAttempts 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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1j hjU ubj )}(hXKThe 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. h]h)}(hXJThe 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.h](hThe CPUID page contents are }(hj hhhNhNubhemphasis)}(h*not*h]hnot}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1j hj ubhX) 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.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1j hjU ubeh}(h]h ]h"]h$]h&]jAjBuh1jhhhKhjQ ubah}(h]h ]h"]h$]h&]uh1hhhhKhj2 hhubh)}(hXIt 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.h]hXIt 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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj2 hhubeh}(h]sev-snp-cpuid-enforcementah ]h"]3. sev-snp cpuid enforcementah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h%4. SEV Guest Driver Communication Keyh]h%4. SEV Guest Driver Communication Key}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hXCommunication 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.h]hXCommunication 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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hhh](h)}(h Referenceh]h Reference}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(h5SEV-SNP and GHCB specification: developer.amd.com/sevh]h5SEV-SNP and GHCB specification: developer.amd.com/sev}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hKThe driver is based on SEV-SNP firmware spec 0.9 and GHCB spec version 2.0.h]hKThe driver is based on SEV-SNP firmware spec 0.9 and GHCB spec version 2.0.}(hj, hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubeh}(h] referenceah ]h"] referenceah$]h&]uh1hhj hhhhhKubeh}(h]"sev-guest-driver-communication-keyah ]h"]%4. sev guest driver communication keyah$]h&]uh1hhhhhhhhKubeh}(h]*the-definitive-sev-guest-api-documentationah ]h"]*the definitive sev guest api documentationah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerju error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehnj _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(jO jL jNjKj/ j, jjjjjjjjjGjDj0j-j' j$ j j jG jD j? j< u nametypes}(jO jNj/ jjjjjGj0j' j jG j? uh}(jL hjKhj, jQjjjjjjjjjDjj-jJj$ j3j j2 jD j j< j u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.