From nobody Tue Feb 10 00:23:08 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 163248370086635.88541454205472; Fri, 24 Sep 2021 04:41:40 -0700 (PDT) Received: from localhost ([::1]:36916 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mTjaE-0007vR-B3 for importer@patchew.org; Fri, 24 Sep 2021 07:41:38 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:34634) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mTjKg-00087A-9Q for qemu-devel@nongnu.org; Fri, 24 Sep 2021 07:25:35 -0400 Received: from mail-ed1-x52c.google.com ([2a00:1450:4864:20::52c]:36847) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mTjKe-0000di-8G for qemu-devel@nongnu.org; Fri, 24 Sep 2021 07:25:34 -0400 Received: by mail-ed1-x52c.google.com with SMTP id v24so34822764eda.3 for ; Fri, 24 Sep 2021 04:25:31 -0700 (PDT) Received: from avogadro.lan ([2001:b07:6468:f312:c8dd:75d4:99ab:290a]) by smtp.gmail.com with ESMTPSA id t14sm4886961ejf.24.2021.09.24.04.25.30 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 24 Sep 2021 04:25:30 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=n2e71CYdYrgeKoDZGg5aC8FSc4Xw4PN68IZuK98DOS4=; b=CAoayVRUtmiFyjRiLFssZ5V3ESILCarUJMabkkkO9ZuO1ra9DX0xqGnCkhsNryhxZj JgsDhq0SDhgv/BzdQipOCtLmbc6EQ9lGu6W7EXes2XKp+lrDrtR7SiUuW+DamFOMid+K qPInCoM6hWIyhnMsNXv9YwykZ0CJOsc3mTZf7dz35W3zvytMel9RMNhtmN7ZHotYeqtG VZ4jEkFr5sb3vugfD5ukcWrNbJOLIT4ouWJP6opKK9fbwVB0x6wCjazlOWgzmKxpEJdz trc+RsFskTYfJl4aPiHdR8k3IrLl2eNhY3qL2/SlnaQc48WtS4hJReP5ENxAoxnbpgbg LodQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=n2e71CYdYrgeKoDZGg5aC8FSc4Xw4PN68IZuK98DOS4=; b=mZW1g0m9ODWCe8vwg+w7F33O6nMMqGWHVTGtflFOfRXP8FQs60KAzaemTmMJ6/4DSK Q1DmX97YGF89eelAHmmRIz4CBOssY2D+q1CIlAAy3aXA+OYVqEa4XYEE11p5yZWfAgMg +kxy/WEbDrP0g0W6eDWVS2pCz5q563LBWoch7Hh5y4VLDxsQdzvohTBXQ6gsDquvOEq7 j+S+qa0Fdpxp2/UtgEWJQaeECt1psbBE2nPMbA2diEQXqVnINxn48Q1gthCHtLwV4ZpC 1zO290qiDq7YPljMbvINuv6r1kSJk7N6zgfWGIzObFwvpGFaWV4NihOVU7Jl8IZ77Q4l zMkA== X-Gm-Message-State: AOAM5335L/BCPj/yT/8OhEqesuQwkrK6NTfXqdDJZCqL6cZ0qt3O+Stu AnQptPk1ZwKOIqyaYJxBmhlZh8kEju8= X-Google-Smtp-Source: ABdhPJyoqB0/wCCuPN9C3PQhSpRipyS3lCQH/zrMtR9JmJ1OUgn6mxm9t49BKjU9qdHvc9K4l9bRwg== X-Received: by 2002:a17:906:1d07:: with SMTP id n7mr10380734ejh.53.1632482730711; Fri, 24 Sep 2021 04:25:30 -0700 (PDT) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH v5 24/26] docs/system: Add SGX documentation to the system manual Date: Fri, 24 Sep 2021 13:25:07 +0200 Message-Id: <20210924112509.25061-25-pbonzini@redhat.com> X-Mailer: git-send-email 2.31.1 In-Reply-To: <20210924112509.25061-1-pbonzini@redhat.com> References: <20210924112509.25061-1-pbonzini@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=2a00:1450:4864:20::52c; envelope-from=paolo.bonzini@gmail.com; helo=mail-ed1-x52c.google.com X-Spam_score_int: -14 X-Spam_score: -1.5 X-Spam_bar: - X-Spam_report: (-1.5 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FORGED_FROMDOMAIN=0.249, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.248, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: yang.zhong@intel.com, philmd@redhat.com, eblake@redhat.com, Sean Christopherson Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1632483703295100001 Content-Type: text/plain; charset="utf-8" From: Sean Christopherson Signed-off-by: Sean Christopherson Signed-off-by: Yang Zhong Message-Id: <20210719112136.57018-34-yang.zhong@intel.com> [Convert to reStructuredText, and adopt the standard =3D=3D=3D --- ~~~ head= ings suggested for example by Linux. - Paolo] Signed-off-by: Paolo Bonzini --- docs/system/i386/sgx.rst | 165 ++++++++++++++++++++++++++++++++++++ docs/system/target-i386.rst | 1 + 2 files changed, 166 insertions(+) create mode 100644 docs/system/i386/sgx.rst diff --git a/docs/system/i386/sgx.rst b/docs/system/i386/sgx.rst new file mode 100644 index 0000000000..f103ae2a2f --- /dev/null +++ b/docs/system/i386/sgx.rst @@ -0,0 +1,165 @@ +Software Guard eXtensions (SGX) +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D + +Overview +-------- + +Intel Software Guard eXtensions (SGX) is a set of instructions and mechani= sms +for memory accesses in order to provide security accesses for sensitive +applications and data. SGX allows an application to use it's pariticular +address space as an *enclave*, which is a protected area provides confiden= tiality +and integrity even in the presence of privileged malware. Accesses to the +enclave memory area from any software not resident in the enclave are prev= ented, +including those from privileged software. + +Virtual SGX +----------- + +SGX feature is exposed to guest via SGX CPUID. Looking at SGX CPUID, we can +report the same CPUID info to guest as on host for most of SGX CPUID. With +reporting the same CPUID guest is able to use full capacity of SGX, and KVM +doesn't need to emulate those info. + +The guest's EPC base and size are determined by Qemu, and KVM needs Qemu to +notify such info to it before it can initialize SGX for guest. + +Virtual EPC +~~~~~~~~~~~ + +By default, Qemu does not assign EPC to a VM, i.e. fully enabling SGX in a= VM +requires explicit allocation of EPC to the VM. Similar to other specialized +memory types, e.g. hugetlbfs, EPC is exposed as a memory backend. + +SGX EPC is enumerated through CPUID, i.e. EPC "devices" need to be realized +prior to realizing the vCPUs themselves, which occurs long before generic +devices are parsed and realized. This limitation means that EPC does not +require -maxmem as EPC is not treated as {cold,hot}plugged memory. + +Qemu does not artificially restrict the number of EPC sections exposed to a +guest, e.g. Qemu will happily allow you to create 64 1M EPC sections. Be a= ware +that some kernels may not recognize all EPC sections, e.g. the Linux SGX d= river +is hardwired to support only 8 EPC sections. + +The following Qemu snippet creates two EPC sections, with 64M pre-allocated +to the VM and an additional 28M mapped but not allocated:: + + -object memory-backend-epc,id=3Dmem1,size=3D64M,prealloc=3Don \ + -object memory-backend-epc,id=3Dmem2,size=3D28M \ + -M sgx-epc.0.memdev=3Dmem1,sgx-epc.1.memdev=3Dmem2 + +Note: + +The size and location of the virtual EPC are far less restricted compared +to physical EPC. Because physical EPC is protected via range registers, +the size of the physical EPC must be a power of two (though software sees +a subset of the full EPC, e.g. 92M or 128M) and the EPC must be naturally +aligned. KVM SGX's virtual EPC is purely a software construct and only +requires the size and location to be page aligned. Qemu enforces the EPC +size is a multiple of 4k and will ensure the base of the EPC is 4k aligned. +To simplify the implementation, EPC is always located above 4g in the guest +physical address space. + +Migration +~~~~~~~~~ + +Qemu/KVM doesn't prevent live migrating SGX VMs, although from hardware's +perspective, SGX doesn't support live migration, since both EPC and the SGX +key hierarchy are bound to the physical platform. However live migration +can be supported in the sense if guest software stack can support recreati= ng +enclaves when it suffers sudden lose of EPC; and if guest enclaves can det= ect +SGX keys being changed, and handle gracefully. For instance, when ERESUME = fails +with #PF.SGX, guest software can gracefully detect it and recreate enclave= s; +and when enclave fails to unseal sensitive information from outside, it can +detect such error and sensitive information can be provisioned to it again. + +CPUID +~~~~~ + +Due to its myriad dependencies, SGX is currently not listed as supported +in any of Qemu's built-in CPU configuration. To expose SGX (and SGX Launch +Control) to a guest, you must either use `-cpu host` to pass-through the +host CPU model, or explicitly enable SGX when using a built-in CPU model, +e.g. via `-cpu ,+sgx` or `-cpu ,+sgx,+sgxlc`. + +All SGX sub-features enumerated through CPUID, e.g. SGX2, MISCSELECT, +ATTRIBUTES, etc... can be restricted via CPUID flags. Be aware that enforc= ing +restriction of MISCSELECT, ATTRIBUTES and XFRM requires intercepting ECREA= TE, +i.e. may marginally reduce SGX performance in the guest. All SGX sub-featu= res +controlled via -cpu are prefixed with "sgx", e.g.:: + + $ qemu-system-x86_64 -cpu help | xargs printf "%s\n" | grep sgx + sgx + sgx-debug + sgx-encls-c + sgx-enclv + sgx-exinfo + sgx-kss + sgx-mode64 + sgx-provisionkey + sgx-tokenkey + sgx1 + sgx2 + sgxlc + +The following Qemu snippet passes through the host CPU but restricts acces= s to +the provision and EINIT token keys:: + + -cpu host,-sgx-provisionkey,-sgx-tokenkey + +SGX sub-features cannot be emulated, i.e. sub-features that are not present +in hardware cannot be forced on via '-cpu'. + +Virtualize SGX Launch Control +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Qemu SGX support for Launch Control (LC) is passive, in the sense that it +does not actively change the LC configuration. Qemu SGX provides the user +the ability to set/clear the CPUID flag (and by extension the associated +IA32_FEATURE_CONTROL MSR bit in fw_cfg) and saves/restores the LE Hash MSRs +when getting/putting guest state, but Qemu does not add new controls to +directly modify the LC configuration. Similar to hardware behavior, locki= ng +the LC configuration to a non-Intel value is left to guest firmware. Unli= ke +host bios setting for SGX launch control(LC), there is no special bios set= ting +for SGX guest by our design. If host is in locked mode, we can still allow +creating VM with SGX. + +Feature Control +~~~~~~~~~~~~~~~ + +Qemu SGX updates the `etc/msr_feature_control` fw_cfg entry to set the SGX +(bit 18) and SGX LC (bit 17) flags based on their respective CPUID support, +i.e. existing guest firmware will automatically set SGX and SGX LC accordi= ngly, +assuming said firmware supports fw_cfg.msr_feature_control. + +Launching a guest +----------------- + +To launch a SGX guest: + +.. parsed-literal:: + + |qemu_system_x86| \\ + -cpu host,+sgx-provisionkey \\ + -object memory-backend-epc,id=3Dmem1,size=3D64M,prealloc=3Don \\ + -object memory-backend-epc,id=3Dmem2,size=3D28M \\ + -M sgx-epc.0.memdev=3Dmem1,sgx-epc.1.memdev=3Dmem2 + +Utilizing SGX in the guest requires a kernel/OS with SGX support. +The support can be determined in guest by:: + + $ grep sgx /proc/cpuinfo + +and SGX epc info by:: + + $ dmesg | grep sgx + [ 1.242142] sgx: EPC section 0x180000000-0x181bfffff + [ 1.242319] sgx: EPC section 0x181c00000-0x1837fffff + +References +---------- + +- `SGX Homepage `__ + +- `SGX SDK `__ + +- SGX specification: Intel SDM Volume 3 diff --git a/docs/system/target-i386.rst b/docs/system/target-i386.rst index c9720a8cd1..6a86d63863 100644 --- a/docs/system/target-i386.rst +++ b/docs/system/target-i386.rst @@ -26,6 +26,7 @@ Architectural features :maxdepth: 1 =20 i386/cpu + i386/sgx =20 .. _pcsys_005freq: =20 --=20 2.31.1