From a50d9b21cd4b63c8aa162d88de88bbec0fd70497 Mon Sep 17 00:00:00 2001 From: Carteepaul Date: Fri, 31 Mar 2023 15:26:49 -0600 Subject: [PATCH] [Doc] Updates suggest by Dmitrii. --- CONTRIBUTING.rst | 37 -------------- Documentation/Installation-index.rst | 2 - Documentation/_static/css/gramine.css | 8 --- Documentation/attestation.rst | 1 - Documentation/cloud-deployment.rst | 10 ++-- Documentation/concepts-index.rst | 3 +- Documentation/contributor-index.rst | 24 ++++++--- Documentation/curated-installation.rst | 2 +- Documentation/custom-installation.rst | 12 ++--- Documentation/devel/building.rst | 16 +++--- Documentation/developer-index.rst | 2 +- Documentation/docker-image-installation.rst | 21 +++++--- Documentation/environment-setup.rst | 11 ++--- Documentation/gramine-users.rst | 49 +++++++++---------- .../manpages/gramine-sgx-get-token.rst | 1 - Documentation/pal/host-abi.rst | 2 +- Documentation/prepare-a-signing-key.rst | 9 ---- Documentation/prerequisites.rst | 13 +++-- Documentation/quickstart.rst | 27 +--------- Documentation/sgx-intro.rst | 3 +- 20 files changed, 93 insertions(+), 160 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 2b8a1cd681..323d76061f 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -252,40 +252,3 @@ To run these tests:: For more information on how to run the ltp tests, please refer to :file:`libos/test/ltp/README.rst`. - - -Management Team (Maintainers) -============================= - -The currently active members of the management team are: - -* Michał Kowalczyk (Invisible Things Lab/Intel) -* Dmitrii Kuvaiskii (Intel) -* Borys Popławski (Invisible Things Lab/Intel) -* Wojtek Porczyk (Invisible Things Lab/Intel) -* Don Porter (UNC) -* Chia-Che Tsai (Texas A&M University) -* Mona Vij (Intel) - -The past (inactive) members of the management team are: - -* Paweł Marczewski -* Rafał Wojdyła -* Isaku Yamahata - -The active members have the review and voting rights. The past (inactive) -members have only the review rights. - -The active members are also the TSC voting members as described in the Technical -Charter for Gramine project. - -The Procedure for Adding and Removing Maintainers -------------------------------------------------- - -+ Joining: # of PRs submitted & merged + # of PRs reviewed + # of issues closed - >= 20 (this means that a PR which fixes 3 issues counts as 4). Only complete - and thorough reviews count. -+ Leaving: a member may be removed if not active or notoriously breaking rules - from this document. -+ Additionally, at least 60% (rounded up) of currently active members have to - agree to make any change to the team membership. diff --git a/Documentation/Installation-index.rst b/Documentation/Installation-index.rst index a1cf14982b..112ed393cd 100644 --- a/Documentation/Installation-index.rst +++ b/Documentation/Installation-index.rst @@ -4,5 +4,3 @@ Gramine Deployment Options ========================== Choose one of the deployment options based on your business need or preference. - - diff --git a/Documentation/_static/css/gramine.css b/Documentation/_static/css/gramine.css index c01cacccfa..c6f85cdcc1 100644 --- a/Documentation/_static/css/gramine.css +++ b/Documentation/_static/css/gramine.css @@ -6,11 +6,3 @@ width: auto; overflow-y: auto; } - - h1 - h1.{ - color: black; - text-align: left; - font-size:large; - } - \ No newline at end of file diff --git a/Documentation/attestation.rst b/Documentation/attestation.rst index 432d1bc066..8b5441bbf5 100644 --- a/Documentation/attestation.rst +++ b/Documentation/attestation.rst @@ -482,7 +482,6 @@ The secret may be retrieved by the application in two ways: ``mbedtls_base64_decode()``) instead of non-crypto-secure functions (e.g., self-written decoding logic or a standard library function). - ``secret_prov_verify_epid.so`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/cloud-deployment.rst b/Documentation/cloud-deployment.rst index ed259eefcb..304bb290d8 100644 --- a/Documentation/cloud-deployment.rst +++ b/Documentation/cloud-deployment.rst @@ -29,7 +29,7 @@ On Ubuntu 20.04 LTS and 18.04 LTS:: sudo curl -fsSLo /usr/share/keyrings/gramine-keyring.gpg https://packages.gramineproject.io/gramine-keyring.gpg echo "deb [arch=amd64 signed-by=/usr/share/keyrings/gramine-keyring.gpg] https://packages.gramineproject.io/ $(lsb_release -sc) main" \ | sudo tee /etc/apt/sources.list.d/gramine.list - + sudo curl -fsSLo /usr/share/keyrings/intel-sgx-deb.asc https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key echo "deb [arch=amd64 signed-by=/usr/share/keyrings/intel-sgx-deb.asc] https://download.01.org/intel-sgx/sgx_repo/ubuntu $(lsb_release -sc) main" \ | sudo tee /etc/apt/sources.list.d/intel-sgx.list @@ -40,7 +40,9 @@ On Ubuntu 20.04 LTS and 18.04 LTS:: Prepare a signing key ^^^^^^^^^^^^^^^^^^^^^ -Only if you haven't already:: +Only prepare a signing key if you haven't already done so.:: + +The following command generates an |~| RSA 3072 key suitable for signing SGX enclaves and stores it in :file:`{HOME}/.config/gramine/enclave-key.pem`. Protect this key and do not disclose it to anyone:: gramine-sgx-gen-private-key @@ -64,6 +66,4 @@ Run the HelloWorld example with SGX:: cd gramine/CI-Examples/helloworld make SGX=1 - gramine-sgx helloworld - - \ No newline at end of file + gramine-sgx helloworld \ No newline at end of file diff --git a/Documentation/concepts-index.rst b/Documentation/concepts-index.rst index 25cd6ed4e2..f25970e181 100644 --- a/Documentation/concepts-index.rst +++ b/Documentation/concepts-index.rst @@ -4,4 +4,5 @@ Concepts .. toctree:: :maxdepth: 1 - sgx-intro \ No newline at end of file + sgx-intro + \ No newline at end of file diff --git a/Documentation/contributor-index.rst b/Documentation/contributor-index.rst index 003955f022..838a77733f 100644 --- a/Documentation/contributor-index.rst +++ b/Documentation/contributor-index.rst @@ -3,16 +3,26 @@ Contribution Guidelines ======================= -These articles contain helpful material for users who want to contribute to Gramine development. +These articles contain helpful material for users who want to contribute to Gramine development. -:doc:`devel/contributing` - Learn about how to report bugs, security vulnerabilities and perform pull requests. This section contains information for working with the Gramine project. +:doc:`devel/contributing` - Learn about how to report bugs, security +vulnerabilities and perform pull requests. This section contains information +for working with the Gramine project. -:doc:`devel/onboarding` - This page describes the knowledge needed to efficiently contribute high-quality PRs to the Gramine project. This page also describes typical flows that Gramine developers should follow to make the process of PR review consistent for everyone involved. +:doc:`devel/onboarding` - This page describes the knowledge needed to +efficiently contribute high-quality PRs to the Gramine project. This page also +describes typical flows that Gramine developers should follow to make the +process of PR review consistent for everyone involved. -:doc:`devel/DCO/index` - Affirm that the source code you will submit was originated by you and/or that you have permission to submit it to the Gramine project. +:doc:`devel/DCO/index` - Affirm that the source code you will submit was +originated by you and/or that you have permission to submit it to the Gramine +project. -:doc:`devel/setup` - Learn the Emacs and Vim configurations used for Gramine. +:doc:`devel/setup` - Learn the Emacs and Vim configurations used for Gramine. -:doc:`devel/howto-doc` - This section describes how the Gramine documentation is constructed and provides directions on how to contribute to it. +:doc:`devel/howto-doc` - This section describes how the Gramine documentation +is constructed and provides directions on how to contribute to it. -:doc:`devel/coding-style` - This document describes coding conventions and formatting styles we use in Gramine. All newly committed code must conform to them to pass a review. \ No newline at end of file +:doc:`devel/coding-style` - This document describes coding conventions and +formatting styles we use in Gramine. All newly committed code must conform to +them to pass a review. \ No newline at end of file diff --git a/Documentation/curated-installation.rst b/Documentation/curated-installation.rst index 62b0e58834..3444a53ccb 100644 --- a/Documentation/curated-installation.rst +++ b/Documentation/curated-installation.rst @@ -1,7 +1,7 @@ .. _curated_index Ready-made confidential protected images -====================================== +======================================== Confidential Compute images with Gramine are ready-made solutions for popular open-source projects such as PyTorch and Redis. Customize your environment through Interactive scripts. The result is a curated, confidentially protected Gramine image that includes your specific machine-learning application, common dependencies, and a manifest file that specifies security policies to enforce for your workload. diff --git a/Documentation/custom-installation.rst b/Documentation/custom-installation.rst index 1666c46695..c7c08310b0 100644 --- a/Documentation/custom-installation.rst +++ b/Documentation/custom-installation.rst @@ -1,20 +1,20 @@ .. _custom_installation -Install Gramine on your server -===================================== +Install Gramine on your system +============================== -Install Gramine and all components on your server. Select this option if you have an existing application and you want to take advantage of SGX without making modifications. This option requires you to create your own manifest. +Install Gramine and all components on your system. Select this option if you have an existing application and you want to take advantage of SGX without making modifications. This option requires you to create your own manifest. **Select** :doc:`quickstart` instructions to quickly install and run Gramine. For full build instructions, see :doc:`devel/building`. Gramine Docker image --------------------------------------- +-------------------- If you opt to build Gramine, you can install Gramine from a Docker container that you build which includes an OS packaged with Gramine binaries. The container includes everything that's included in the installation. This option requires you to create your own manifest. Cloud cloud-deployment ------------------------- +---------------------- **Select** :doc:`docker-image-installation` @@ -23,7 +23,7 @@ Gramine can be installed in the cloud on VMs that support Intel SGX. **Select** :doc:`cloud-deployment` Refer to the following as you configure and develop Gramine. - + - :doc:`configuration-index` - :doc:`developer-index` - :doc:`tutorials-index` diff --git a/Documentation/devel/building.rst b/Documentation/devel/building.rst index c9bf5ee30a..5017d78595 100644 --- a/Documentation/devel/building.rst +++ b/Documentation/devel/building.rst @@ -1,5 +1,5 @@ Build and install Gramine from source -==================== +===================================== .. highlight:: sh @@ -273,13 +273,17 @@ Additional build options Prepare a signing key --------------------- -Only for SGX enclave development, and if you haven't already, run the following -command:: +These instructions are only required for systems using Intel® SGX that have not already created a signing key. - gramine-sgx-gen-private-key + - If your system is not using Intel® SGX, skip this step. + + - If your system is using Intel® SGX and you already created a signing key, skip this step. + + - If your system is using Intel® SGX and have not created a signing key, follow the instructions below. -This command generates an |~| RSA 3072 key suitable for signing SGX enclaves and -stores it in :file:`{HOME}/.config/gramine/enclave-key.pem`. Protect this key and do not disclose it to anyone. +The following command generates an |~| RSA 3072 key suitable for signing SGX enclaves and stores it in :file:`{HOME}/.config/gramine/enclave-key.pem`. Protect this key and do not disclose it to anyone:: + + gramine-sgx-gen-private-key After signing the application's manifest, users may ship the application and Gramine binaries, along with an SGX-specific manifest (``.manifest.sgx`` diff --git a/Documentation/developer-index.rst b/Documentation/developer-index.rst index 2938796de1..8731ee4f21 100644 --- a/Documentation/developer-index.rst +++ b/Documentation/developer-index.rst @@ -8,7 +8,7 @@ Helpful material for users who develop Gramine or who are installing Gramine the .. toctree:: :maxdepth: 1 + python/api devel/debugging devel/new-syscall pal/host-abi - python/api diff --git a/Documentation/docker-image-installation.rst b/Documentation/docker-image-installation.rst index 07e71eb87e..bf15bc651f 100644 --- a/Documentation/docker-image-installation.rst +++ b/Documentation/docker-image-installation.rst @@ -1,9 +1,6 @@ Gramine docker image ==================== -The Gramine team publishes a base Gramine Docker image at DockerHub: -https://hub.docker.com/r/gramineproject/gramine. - This Gramine image is a minimal distribution of Gramine: it contains only Gramine binaries and tools, as well as the pre-requisite packages to run applications under Gramine. The only currently available Gramine image is based @@ -15,14 +12,22 @@ quickly test Gramine with your applications and workloads. This image can also be used as a base for your workflows to produce production-ready Docker images for your SGX applications. +The Gramine team publishes a base Gramine Docker image at: `DockerHub `_. + To run the Gramine image via Docker, the recommended command is:: - docker run --device /dev/sgx_enclave -it gramineproject/gramine +``docker run --device /dev/sgx_enclave -it gramineproject/gramine`` If you want to run :program:`gramine-direct` in addition to command:`gramine-sgx`, then you should run Docker with our custom seccomp -profile using ``--security-opt seccomp=``. You can download the -profile file from +profile using: + + ``--security-opt seccomp=`` + +You can download the profile file from: + https://github.com/gramineproject/gramine/blob/master/scripts/docker_seccomp.json. -Alternatively you can disable seccomp completely (``--security-opt -seccomp=unconfined``). \ No newline at end of file + +Alternatively you can disable seccomp completely + +``--security-optseccomp=unconfined`` \ No newline at end of file diff --git a/Documentation/environment-setup.rst b/Documentation/environment-setup.rst index cc9b494f89..74b0767f5d 100644 --- a/Documentation/environment-setup.rst +++ b/Documentation/environment-setup.rst @@ -1,7 +1,8 @@ .. _environment_setup Set up the Gramine environment -------------------------------- +------------------------------ + Gramine without SGX has no special requirements. Gramine with SGX support requires several features from your system: @@ -15,13 +16,12 @@ Gramine with SGX support requires several features from your system: If your system doesn’t meet these requirements, please refer to more detailed descriptions in :doc:`devel/building`. Check for SGX compatibility -============================== +=========================== We supply a tool, `is-sgx-available `_ that checks the environment for SGX compatibility. Use this tool to check your hardware and system. It’s installed together with the respective gramine package you previously installed. - Prepare a signing key -========================== +===================== Only for SGX, and if you haven’t already, enter the following: @@ -29,5 +29,4 @@ Only for SGX, and if you haven’t already, enter the following: gramine-sgx-gen-private-key - -This command generates an RSA 3072 key suitable for signing SGX enclaves and stores it in HOME/.config/gramine/enclave-key.pem. Protect this key and do not disclose it to anyone. \ No newline at end of file +This command generates an RSA 3072 key suitable for signing SGX enclaves and stores it in :file: `{HOME}/.config/gramine/enclave-key.pem`. Protect this key and do not disclose it to anyone. \ No newline at end of file diff --git a/Documentation/gramine-users.rst b/Documentation/gramine-users.rst index a4b0b7ecd5..2731d696a3 100644 --- a/Documentation/gramine-users.rst +++ b/Documentation/gramine-users.rst @@ -5,32 +5,31 @@ We are excited to share that several companies are experimenting with Gramine fo - `Eder Labs `__ started its journey with the belief that businesses worldwide should easily be able to adopt ML/AI, without the concerns around compromising sensitive enterprise or consumer data. Towards this future, Eder Labs has begun facilitating exploratory data science between data users and data providers, for structured text data, and will be using the Gramine LibOS to facilitate training and deployment of models in a secure and federated manner, as the data science journey matures for these businesses. The Gramine ecosystem is laying the path to a more secure future, for all kinds of ML/AI applications, and Eder Labs is a firm supporter and beneficiary of this future-defining paradigm. -- `enclaive.io `__ uses among other technologies Gramine to - generically enclavize applications. Enclaive builds and deploys confidential - containers for the zero-trust Web. Use cases are in the area of GDPR-compliant - Web analytics and AI. Specifically, Gramine Shielded Containers (GSC) ease the - design of confidential containers. +- `enclaive.io `__ uses among other technologies Gramine to generically enclavize applications. Enclaive builds and deploys confidential +containers for the zero-trust Web. Use cases are in the area of GDPR-compliant +Web analytics and AI. Specifically, Gramine Shielded Containers (GSC) ease the +design of confidential containers. -- `JD Cloud `__ is experimenting with Gramine for - several solutions. +- `JD Cloud `__ is experimenting with Gramine for +several solutions. - - `Super Protocol `__ combines the benefits of - both Trusted Execution Environment (TEE) technology and blockchain to offer a - universal, decentralized, confidential cloud computing platform. It enables - easy deployment of a wide range of workloads - a rich ecosystem of - interoperable solutions and services, including databases, web services, - confidential data sources, and much more. Super Protocol takes advantage of - the open-source Gramine library OS, which works in conjunction with Intel SGX - to provide additional security benefits in Linux environments. +- `Super Protocol `__ combines the benefits of +both Trusted Execution Environment (TEE) technology and blockchain to offer a +universal, decentralized, confidential cloud computing platform. It enables +easy deployment of a wide range of workloads - a rich ecosystem of +interoperable solutions and services, including databases, web services, +confidential data sources, and much more. Super Protocol takes advantage of +the open-source Gramine library OS, which works in conjunction with Intel SGX +to provide additional security benefits in Linux environments. -- `Tencent Cloud `__ relies on Gramine to - implement several SGX-based solutions by running unmodified Linux - applications. One example is the recent launch of the Tencent Cloud - Shuliantong product, announced at the Tencent Digital Ecosystem Summit. +- `Tencent Cloud `__ relies on Gramine to +implement several SGX-based solutions by running unmodified Linux +applications. One example is the recent launch of the Tencent Cloud +Shuliantong product, announced at the Tencent Digital Ecosystem Summit. -- The national digital health agency `gematik `__ is - responsible for the *ePrescription* project in Germany. `IBM - `__ uses Gramine to implement the "VAU"-concept on SGX - to ensure a maximum of privacy and request-context isolation. The VAU-concept - is used for confidential computing in different implementations as well, such - as the electronic health record. +- The national digital health agency `gematik `__ is +responsible for the *ePrescription* project in Germany. `IBM +`__ uses Gramine to implement the "VAU"-concept on SGX +to ensure a maximum of privacy and request-context isolation. The VAU-concept +is used for confidential computing in different implementations as well, such +as the electronic health record. diff --git a/Documentation/manpages/gramine-sgx-get-token.rst b/Documentation/manpages/gramine-sgx-get-token.rst index 85802e28e2..584c4dca52 100644 --- a/Documentation/manpages/gramine-sgx-get-token.rst +++ b/Documentation/manpages/gramine-sgx-get-token.rst @@ -23,7 +23,6 @@ fetched automatically if needed during the first enclave start. On upstream/DCAP driver this command does nothing and is deprecated. In the future, it will be removed altogether. - Command line arguments ====================== diff --git a/Documentation/pal/host-abi.rst b/Documentation/pal/host-abi.rst index ae8cc2fe0f..9157df3816 100644 --- a/Documentation/pal/host-abi.rst +++ b/Documentation/pal/host-abi.rst @@ -114,7 +114,7 @@ memory. .. doxygentypedef:: pal_prot_flags_t :project: pal - .. doxygenstruct:: pal_initial_mem_range +.. doxygenstruct:: pal_initial_mem_range :project: pal :members: diff --git a/Documentation/prepare-a-signing-key.rst b/Documentation/prepare-a-signing-key.rst index 11d1174e4c..d34f257498 100644 --- a/Documentation/prepare-a-signing-key.rst +++ b/Documentation/prepare-a-signing-key.rst @@ -16,12 +16,3 @@ and stores it in :file:`{HOME}/.config/gramine/enclave-key.pem`. Protect this key and do not disclose it to anyone:: gramine-sgx-gen-private-key - - -glibc vs musl -------------- - -Most of the examples we provide use GNU C Library (glibc). If your application -is built against musl libc, you can pass ``'musl'`` to -:py:func:`gramine.runtimedir()` when generating the manifest from a template; -this will mount musl libc (instead of the default glibc). \ No newline at end of file diff --git a/Documentation/prerequisites.rst b/Documentation/prerequisites.rst index ccf2ceff54..13c280c56b 100644 --- a/Documentation/prerequisites.rst +++ b/Documentation/prerequisites.rst @@ -3,17 +3,16 @@ Prerequisites ------------- -Gramine without SGX support has no special requirements. +Gramine without Intel® SGX support has no special requirements. -Gramine with SGX support has the following requirements: +Gramine with Intel® SGX support has the following requirements: -- Linux kernel version at least 5.11 (with SGX driver enabled); -- Intel SGX PSW and (optionally) Intel DCAP must be installed and configured. +- Linux kernel version at least 5.11 (with Intel® SGX driver enabled); +- Intel SGX PSW and (optionally) Intel® DCAP must be installed and configured. If your system doesn't meet these requirements, please refer to the :doc:`devel/building` section for instructions on how to install these requirements. -Check for SGX compatibility +Check for Intel® SGX compatibility --------------- -To check your hardware and system for SGX compatibility, use the supplied tool, :doc:`manpages/is-sgx-available`. It's installed together with the respective gramine -package you install from the options below. \ No newline at end of file +To check your hardware and system for Intel® SGX compatibility, use the supplied tool, :doc:`manpages/is-sgx-available`. It's installed together with the respective Gramine package you install from the options below. \ No newline at end of file diff --git a/Documentation/quickstart.rst b/Documentation/quickstart.rst index 93e5979acf..84e9014b88 100644 --- a/Documentation/quickstart.rst +++ b/Documentation/quickstart.rst @@ -7,7 +7,7 @@ There are three options to choose from when using Gramine to protect your applic :ref:`Install Gramine` - This option provides instructions for installing Gramine on various versions of Ubuntu or Red Hat Enterprise Linux 8. -:ref:`Gramine Docker Image` - This option provides instructions for installing a prepared Docker image with Gramine and running the container. This option enables you to protect an application running in the cloud. +:doc:`docker-image-installation` - This option provides instructions for installing a prepared Docker image with Gramine and running the container. This option enables you to protect an application running in the cloud. :doc:`devel/building` - This option is mainly used for assisting in helping the development of Gramine. This option is much more involved. The instructions for this option are listed on another page. @@ -61,28 +61,3 @@ RHEL-like distributions version 8 (and experimentally also version 9) sudo curl -fsSLo /etc/yum.repos.d/gramine.repo https://packages.gramineproject.io/rpm/gramine.repo sudo dnf install gramine - -Gramine Docker image -======================== - -This Gramine image is a minimal distribution of Gramine. It contains only Gramine binaries and tools, as well as the pre-requisite packages to run applications under Gramine. The only currently available Gramine image is based on Ubuntu 20.04. The only requirement on the host system is a Linux kernel with in-kernel SGX driver (available from version 5.11 onward). This Gramine image can be used as a disposable playground environment, to quickly test Gramine with your applications and workloads. This image can also be used as a base for your workflows to produce production-ready Docker images for your SGX applications. - -The Gramine team publishes a base Gramine Docker image at: `DockerHub `_. - -The recommended command to run the Gramine image via Docker is:: - -``docker run --device /dev/sgx_enclave -it gramineproject/gramine`` - -If you want to run :program:`gramine-direct` in addition to -command:`gramine-sgx`, then you should run Docker with our custom seccomp -profile using: - - ``--security-opt seccomp=`` - -You can download the profile file from: - -https://github.com/gramineproject/gramine/blob/master/scripts/docker_seccomp.json. - -Alternatively you can disable seccomp completely using this command: - -``--security-optseccomp=unconfined`` \ No newline at end of file diff --git a/Documentation/sgx-intro.rst b/Documentation/sgx-intro.rst index cd2afe58e6..a9a17a1cb8 100644 --- a/Documentation/sgx-intro.rst +++ b/Documentation/sgx-intro.rst @@ -360,7 +360,7 @@ SGX terminology :term:`DCAP` -Key Separation and Sharing + Key Separation and Sharing KSS A feature that lets developer define additional enclave identity attributes and configuration identifier. Extended enclave identity @@ -391,7 +391,6 @@ Key Separation and Sharing This feature was not part of original SGX and therefore not supported by all SGX-enabled hardware. - Launch Enclave LE