linux-kernel - [PATCH v20 28/28] docs: x86/sgx: Document the enclave API

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <20190417103938.7762-29-jarkko.sakkinen@linux.intel.com>
Date:   Wed, 17 Apr 2019 13:39:38 +0300
From:   Jarkko Sakkinen <jarkko.sakkinen@...ux.intel.com>
To:     linux-kernel@...r.kernel.org, x86@...nel.org,
        linux-sgx@...r.kernel.org
Cc:     akpm@...ux-foundation.org, dave.hansen@...el.com,
        sean.j.christopherson@...el.com, nhorman@...hat.com,
        npmccallum@...hat.com, serge.ayoun@...el.com,
        shay.katz-zamir@...el.com, haitao.huang@...el.com,
        andriy.shevchenko@...ux.intel.com, tglx@...utronix.de,
        kai.svahn@...el.com, bp@...en8.de, josh@...htriplett.org,
        luto@...nel.org, kai.huang@...el.com, rientjes@...gle.com,
        Jarkko Sakkinen <jarkko.sakkinen@...ux.intel.com>
Subject: [PATCH v20 28/28] docs: x86/sgx: Document the enclave API

Document the enclave driver API i.e. the set of ioctl's used to create
and manage enclaves and set their privileges

Signed-off-by: Jarkko Sakkinen <jarkko.sakkinen@...ux.intel.com>
---
 Documentation/x86/sgx/3.API.rst | 27 +++++++++++++++++++++++++++
 Documentation/x86/sgx/index.rst |  1 +
 2 files changed, 28 insertions(+)
 create mode 100644 Documentation/x86/sgx/3.API.rst

diff --git a/Documentation/x86/sgx/3.API.rst b/Documentation/x86/sgx/3.API.rst
new file mode 100644
index 000000000000..b113aeb05f54
--- /dev/null
+++ b/Documentation/x86/sgx/3.API.rst
@@ -0,0 +1,27 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===
+API
+===
+
+The enclave life-cycle starts by opening `/dev/sgx/enclave`. After this there is
+already a data structure inside kernel tracking the enclave that is initially
+uncreated. After this a set of ioctl's can be used to create, populate and
+initialize the enclave.
+
+You can close (if you want) the fd after you've mmap()'d. As long as the file is
+open the enclave stays alive so you might want to do that after you don't need
+it anymore. Even munmap() won't destruct the enclave if the file is open.
+Neither will closing the fd as long as you have mmap() done over the fd (even
+if it does not across the range defined in SECS).
+
+Finally, there is ioctl to authorize priviliged attributes:
+`SGX_IOC_ENCLAVE_SET_ATTRIBUTE`. Each of them is presented by a file inside
+`/dev/sgx/`. Right now there is only one such file `/dev/sgx/provision`, which
+controls the `PROVISON_KEY` attribute.
+
+.. kernel-doc:: arch/x86/kernel/cpu/sgx/driver/ioctl.c
+   :functions: sgx_ioc_enclave_create
+               sgx_ioc_enclave_add_page
+               sgx_ioc_enclave_init
+               sgx_ioc_enclave_set_attribute
diff --git a/Documentation/x86/sgx/index.rst b/Documentation/x86/sgx/index.rst
index 5d660e83d984..de0b78328611 100644
--- a/Documentation/x86/sgx/index.rst
+++ b/Documentation/x86/sgx/index.rst
@@ -15,3 +15,4 @@ potentially malicious.
 
    1.Architecture
    2.Kernel-internals
+   3.API
-- 
2.19.1