From patchwork Sat Oct 23 01:21:14 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Jarkko Sakkinen X-Patchwork-Id: 12579253 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 856C2C433FE for ; Sat, 23 Oct 2021 01:21:23 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 669376109E for ; Sat, 23 Oct 2021 01:21:23 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S230086AbhJWBXk (ORCPT ); Fri, 22 Oct 2021 21:23:40 -0400 Received: from mail.kernel.org ([198.145.29.99]:58170 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229507AbhJWBXk (ORCPT ); Fri, 22 Oct 2021 21:23:40 -0400 Received: by mail.kernel.org (Postfix) with ESMTPSA id 8890361059; Sat, 23 Oct 2021 01:21:21 +0000 (UTC) From: Jarkko Sakkinen To: Michael Kerrisk Cc: linux-man@vger.kernel.org, linux-sgx@vger.kernel.org, Dave Hansen , Reinette Chatre , Jarkko Sakkinen Subject: [PATCH v8] sgx.7: New page with overview of Software Guard eXtensions (SGX) Date: Sat, 23 Oct 2021 04:21:14 +0300 Message-Id: <20211023012114.16122-2-jarkko.sakkinen@iki.fi> X-Mailer: git-send-email 2.32.0 In-Reply-To: <20211023012114.16122-1-jarkko.sakkinen@iki.fi> References: <20211023012114.16122-1-jarkko.sakkinen@iki.fi> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-sgx@vger.kernel.org From: Jarkko Sakkinen Signed-off-by: Jarkko Sakkinen --- v8: * Fix errors reported for the previous version. v7: * Added more meat about the address space and API. * Reorganized the text to have focus more on developer to have a big picture of kernel provided interfaces. v6: * Small fixes based on Dave's and Reinette's feedback. * Extended the "Permissions" section to cover mmap() v5: * Taking away hardware concepts and focusing more on the interface. v4: * Did a heavy edit trying to streamline the story a bit and focus on stuff important to the user (e.g. lighten up x86 details). v3: * Overhaul based on Michael's comments. Most likely needs to be refined in various places but this is at least a small step forward for sure. v2: * Fixed the semantic newlines convention and various style errors etc. that were reported by Alenjandro and Michael. * SGX was merged to v5. --- man7/sgx.7 | 170 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 man7/sgx.7 diff --git a/man7/sgx.7 b/man7/sgx.7 new file mode 100644 index 000000000..85afea912 --- /dev/null +++ b/man7/sgx.7 @@ -0,0 +1,170 @@ +.\" Copyright (C) 2021 Intel Corporation +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.\" +.TH SGX 7 2021\-02\-02 "Linux" "Linux Programmer's Manual" +.PP +sgx - overview of Software Guard eXtensions +.SH SYNOPSIS +.EX +.B #include +.PP +.IB enclave " = open(""/dev/sgx_enclave", " O_RDWR);" +.EE +.SH DESCRIPTION +Intel Software Guard eXtensions (SGX) allow applications to host +enclaves, +protected executable objects in memory. +.PP +Enclaves are blobs of executable code, +running inside a CPU enforced container, +which is mapped to the process address space. +They have a fixed set of entry points, +defined when the enclave is built with the ioctls, +provided by +.I /dev/sgx_enclave. +.PP +SGX is available only if the kernel was configured and built with the +.B CONFIG_X86_SGX +option. +You can verify that both the kernel and hardware have SGX enabled by +checking that "sgx" appears in the +.I flags +field in +.IR /proc/cpuinfo . +.PP +SGX must be enabled in BIOS. +If SGX appears to be unsupported, +ensure that SGX is enabled in the BIOS. +If a BIOS presents a choice between +.I Enabled +and +.I Software Enabled +modes for SGX, +choose +.I Enabled. +.PP +Enclaves are shared objects, meaning that +they can be shared with a +.BR cmsg (3), +and inherited in a fork. +.SS Address space +The address range for an enclave must be reserved with +.BR mmap (2). +This must happen before the enclave construction can begin, +because the enclave page addresses are fixed during its build time. +.PP +The CPU requires the size of the enclave to be power of two, +at least size of a one page, +and the base address to be naturally aligned with the size. +An appropriate address range can be found by an anonymous mapping: +.PP +.EX +void *area = mmap(NULL, size * 2, PROT_NONE, MAP_PRIVATE | MAP_ANONYMOUS, + -1, 0); + +/* Find the first address aligned to the size within the range. */ +void *base = ((uint64_t)area + size - 1) & ~(size - 1); +.EE +.PP +.SS Ioctls +An enclave life-cycle is started by opening +.I /dev/sgx_enclave. +They are managed with an +.BR ioctl (2) +interface, +.IR : +.TP +.IB SGX_IOC_ENCLAVE_CREATE +Create SGX Enclave Control Structure (SECS) for an enclave. +SECS is a hardware defined structure, +which contains the properties of an enclave, +such as its base address and size. +The ioctl argument has the type +.IR "struct\ *sgx_enclave_create" . +.TP +.IB SGX_IOC_ENCLAVE_ADD_PAGES +Populate a range of enclave pages with the page data provided by the caller. +The ioctl argument has the type +.IR "struct\ *sgx_enclave_add_pages" . +.TP +.IB SGX_IOC_ENCLAVE_INIT +Tell the CPU to prepare the enclave for use. +After a successful initialization, +no new pages can be added to the enclave. +The ioctl argument has the type +.IR "struct\ *sgx_enclave_init" . +.PP +The details of what these operations actually mean in the hardware level can be +found at the Intel Software Developers Manual. +.SS vDSO +A process can access an enclave by entering into its address space through +a set of entry points, +which must be defined during the construction process. +This requires a complex sequence of CPU instructions, +and kernel assisted exception handling. +For these reasons, +it is encapsulated into +a vDSO interface, +provided by +.BR vdso_sgx_enter_enclave_t , +which is declared in +.IR . +.SS Permissions +In order to build an enclave, a process must be able to call +.IR mmap (2) +with +.IR PROT_EXEC +set, +because, as with any other type of executable, +the page table protections must be set appropriately. +Therefore, +.I /dev/sgx_enclave +must reside in a partition, +which is not mounted with +.B noexec +set in the mount options. +.PP +During the build process each enclave page is assigned protection bits, +as part of +.BR ioctl(SGX_IOC_ENCLAVE_ADD_PAGES). +These protections are also the maximum protections to which the page can be be mapped. +If +.BR mmap (2) +is called with higher protections than those defined during the build, +it will return +.B -EACCES. +If +.BR ioctl(SGX_IOC_ENCLAVE_ADD_PAGES) +is called after +.BR mmap (2) +with lower protections, +the caller receives +.BR SIGBUS, +once it accesses the page for the first time. +.SH VERSIONS +The SGX feature was added in Linux 5.11. +.SH SEE ALSO +.BR ioctl (2), +.BR mmap (2), +.BR mprotect (2)