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]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.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhubah}(h]h ]h"]h$]h&]uh1hhhubh)}(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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhhubeh}(h]h ]h"]h$]h&]bullet-uh1hhhhKhhubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubeh}(h]general-descriptionah ]h"]1. general descriptionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h2. API descriptionh]h2. API description}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj=hhhhhKubh)}(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:}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj=hhubh)}(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:}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1jkhhhKhjgubh 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&]uh1hhhhKhj}ubah}(h]h ]h"]h$]h&]uh1j{hjgubeh}(h]h ]h"]h$]h&]uh1jehhhKhjbubjf)}(hUType: hypervisor or guest. The ioctl can be used inside the guest or the hypervisor. h](jl)}(hType:h]hType:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jkhhhKhjubj|)}(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&]uh1j{hjubeh}(h]h ]h"]h$]h&]uh1jehhhKhjbubjf)}(h7Parameters: what parameters are accepted by the ioctl. h](jl)}(h Parameters:h]h Parameters:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jkhhhK"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&]uh1j{hjubeh}(h]h ]h"]h$]h&]uh1jehhhK"hjbubjf)}(h~Returns: the return value. General error numbers (-ENOMEM, -EINVAL) are not detailed, but errors with specific meanings are. h](jl)}(hReturns:h]hReturns:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jkhhhK&hjubj|)}(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%hj ubah}(h]h ]h"]h$]h&]uh1j{hjubeh}(h]h ]h"]h$]h&]uh1jehhhK&hjbubeh}(h]h ]h"]h$]h&]uh1j`hj\ubah}(h]h ]h"]h$]h&]uh1hhhhKhj=hhubh)}(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.}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK(hj=hhubh)}(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.}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK.hj=hhubh 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; }; }; };}hjQsbah}(h]h ]h"]h$]h&]hhuh1jOhhhK4hj=hhubh)}(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.}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKFhj=hhubjP)}(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; };}hjmsbah}(h]h ]h"]h$]h&]hhuh1jOhhhKKhj=hhubh)}(hhh](h)}(h2.1 SNP_GET_REPORTh]h2.1 SNP_GET_REPORT}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj{hhhhhKXubh 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)}(hjhhhNhNubah}(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)}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj!hhhKubj)}(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}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK]hj2ubah}(h]h ]h"]h$]h&]uh1jhj!ubeh}(h]h ]h"]h$]h&]uh1jhhhK]hjhhubeh}(h]h ]h"]h$]h&]uh1jhj{hhhhhKZubh)}(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.}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK_hj{hhubh)}(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.}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKchj{hhubeh}(h]snp-get-reportah ]h"]2.1 snp_get_reportah$]h&]uh1hhj=hhhhhKXubh)}(hhh](h)}(h2.2 SNP_GET_DERIVED_KEYh]h2.2 SNP_GET_DERIVED_KEY}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjzhhhhhKhubj)}(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)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(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}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKlhj)ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(h]h ]h"]h$]h&]uh1jhhhKlhjhhubeh}(h]h ]h"]h$]h&]uh1jhjzhhhhhKiubh)}(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.}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKnhjzhhubh)}(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.}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKrhjzhhubh)}(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.}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKvhjzhhubeh}(h]snp-get-derived-keyah ]h"]2.2 snp_get_derived_keyah$]h&]uh1hhj=hhhhhKhubh)}(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)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjhhhKubj)}(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}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj.ubah}(h]h ]h"]h$]h&]uh1jhjubeh}(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.}(hjRhhhNhNubah}(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.}(hj`hhhNhNubah}(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.}(hjnhhhNhNubah}(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.}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]snp-get-ext-reportah ]h"]2.3 snp_get_ext_reportah$]h&]uh1hhj=hhhhhK{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)}(hjh]hstruct sev_user_data_snp_status}(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)}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj0hhhKubj)}(h!0 on success, -negative on error h]h)}(h 0 on success, -negative on errorh]h 0 on success, -negative on error}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjAubah}(h]h ]h"]h$]h&]uh1jhj0ubeh}(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.}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]snp-platform-statusah ]h"]2.4 snp_platform_statusah$]h&]uh1hhj=hhhhhKubh)}(hhh](h)}(h2.5 SNP_COMMITh]h2.5 SNP_COMMIT}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj{hhhhhKubj)}(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&]uh1jhj{hhhhhKubh)}(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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj{hhubeh}(h] snp-commitah ]h"]2.5 snp_commitah$]h&]uh1hhj=hhhhhKubh)}(hhh](h)}(h2.6 SNP_SET_CONFIGh]h2.6 SNP_SET_CONFIG}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj6hhhhhKubj)}(hhh](j)}(hhh](j)}(h Technologyh]h Technology}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjJhhhKubj)}(hsev-snph]h)}(hj]h]hsev-snp}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj[ubah}(h]h ]h"]h$]h&]uh1jhjJubeh}(h]h ]h"]h$]h&]uh1jhhhKhjGhhubj)}(hhh](j)}(hTypeh]hType}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjxhhhKubj)}(hhypervisor ioctl cmdh]h)}(hjh]hhypervisor ioctl cmd}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjxubeh}(h]h ]h"]h$]h&]uh1jhhhKhjGhhubj)}(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&]uh1jhhhKhjGhhubj)}(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&]uh1jhhhKhjGhhubeh}(h]h ]h"]h$]h&]uh1jhj6hhhhhKubh)}(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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj6hhubeh}(h]snp-set-configah ]h"]2.6 snp_set_configah$]h&]uh1hhj=hhhhhKubh)}(hhh](h)}(h2.7 SNP_VLEK_LOADh]h2.7 SNP_VLEK_LOAD}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubj)}(hhh](j)}(hhh](j)}(h Technologyh]h Technology}(hj6hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj3hhhKubj)}(hsev-snph]h)}(hjFh]hsev-snp}(hjHhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjDubah}(h]h ]h"]h$]h&]uh1jhj3ubeh}(h]h ]h"]h$]h&]uh1jhhhKhj0hhubj)}(hhh](j)}(hTypeh]hType}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjahhhKubj)}(hhypervisor ioctl cmdh]h)}(hjth]hhypervisor ioctl cmd}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjrubah}(h]h ]h"]h$]h&]uh1jhjaubeh}(h]h ]h"]h$]h&]uh1jhhhKhj0hhubj)}(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&]uh1jhhhKhj0hhubj)}(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&]uh1jhhhKhj0hhubeh}(h]h ]h"]h$]h&]uh1jhjhhhhhKubh)}(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.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(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&]uh1hhhhKhjhhubeh}(h] snp-vlek-loadah ]h"]2.7 snp_vlek_loadah$]h&]uh1hhj=hhhhhKubeh}(h]api-descriptionah ]h"]2. api descriptionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h3. SEV-SNP CPUID Enforcementh]h3. SEV-SNP CPUID Enforcement}(hj! hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj 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:}(hj/ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj 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]h)}(hhh](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]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.}(hjH hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjD ubah}(h]h ]h"]h$]h&]uh1hhjA ubh)}(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.}(hj` hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj\ ubah}(h]h ]h"]h$]h&]uh1hhjA ubh)}(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.}(hjx hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjt ubah}(h]h ]h"]h$]h&]uh1hhjA ubh)}(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&]uh1hhjA ubeh}(h]h ]h"]h$]h&]j-j.uh1hhhhKhj= ubah}(h]h ]h"]h$]h&]uh1hhhhKhj 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&]uh1hhhhKhj 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_handlerja error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _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}(j; j8 j:j7j j jwjtj|jyjjjxjuj3j0jjj j j j j3 j0 j+ j( u nametypes}(j; j:j jwj|jjxj3jj j j3 j+ uh}(j8 hj7hj j=jtj{jyjzjjjujj0j{jj6j jj j j0 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.