From 4cffce76eb0c4c5a2f1b3c8379c027fbe44d6ca6 Mon Sep 17 00:00:00 2001 From: Benny Fuhry Date: Tue, 18 Apr 2023 23:05:35 +0200 Subject: [PATCH] fixup! Updating the documentation so it is consistent with my changes and the updates from the team. Changes corresponding to comments from Dmitrii. Signed-off-by: Benny Fuhry --- Documentation/cloud-deployment.rst | 6 +- Documentation/conf.py | 1 - Documentation/curated-installation.rst | 12 ++- Documentation/custom-installation.rst | 14 ++- Documentation/devel/.vscode/settings.json | 3 - Documentation/devel/building.rst | 27 +++-- Documentation/environment-setup.rst | 14 ++- Documentation/gramine-users.rst | 68 +++++++----- Documentation/gsc-installation.rst | 16 ++- Documentation/img/indx-background.png | Bin 2095 -> 0 bytes Documentation/index.rst | 102 +++++++++++++----- Documentation/manifest-syntax.rst | 14 +-- .../manpages/gramine-sgx-sigstruct.rst | 3 +- Documentation/manpages/index.rst | 3 +- Documentation/performance.rst | 10 +- Documentation/prepare-a-signing-key.rst | 18 ---- Documentation/prerequisites.rst | 8 +- Documentation/quickstart.rst | 24 +++-- Documentation/requirements.txt | 14 ++- Documentation/run-sample-application.rst | 11 +- Documentation/sgx-intro.rst | 3 +- 21 files changed, 234 insertions(+), 137 deletions(-) delete mode 100644 Documentation/devel/.vscode/settings.json delete mode 100644 Documentation/img/indx-background.png delete mode 100644 Documentation/prepare-a-signing-key.rst diff --git a/Documentation/cloud-deployment.rst b/Documentation/cloud-deployment.rst index 304bb290d8..15b47b6db3 100644 --- a/Documentation/cloud-deployment.rst +++ b/Documentation/cloud-deployment.rst @@ -42,7 +42,9 @@ Prepare a signing key 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:: +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 @@ -66,4 +68,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 diff --git a/Documentation/conf.py b/Documentation/conf.py index bd5d99c900..2ccd5179e4 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -50,7 +50,6 @@ 'sphinx.ext.napoleon', 'sphinx.ext.todo', 'sphinx_rtd_theme', - 'sphinx.ext.autosectionlabel', ] # Add any paths that contain templates here, relative to this directory. diff --git a/Documentation/curated-installation.rst b/Documentation/curated-installation.rst index 3444a53ccb..436cbbb458 100644 --- a/Documentation/curated-installation.rst +++ b/Documentation/curated-installation.rst @@ -3,12 +3,18 @@ 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. +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. .. note:: - These confidential compute images only run on machines that support Intel SGX. + These confidential compute images only run on machines that support Intel + SGX. Current list of solutions and installation instructions: - `Redis `_ -- `PyTorch `_ \ No newline at end of file +- `PyTorch `_ diff --git a/Documentation/custom-installation.rst b/Documentation/custom-installation.rst index c7c08310b0..131369eeac 100644 --- a/Documentation/custom-installation.rst +++ b/Documentation/custom-installation.rst @@ -3,15 +3,21 @@ Install Gramine on your system ============================== -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. +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`. +**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. +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 ---------------------- @@ -27,4 +33,4 @@ Refer to the following as you configure and develop Gramine. - :doc:`configuration-index` - :doc:`developer-index` - :doc:`tutorials-index` -- :doc:`concepts-index` \ No newline at end of file +- :doc:`concepts-index` diff --git a/Documentation/devel/.vscode/settings.json b/Documentation/devel/.vscode/settings.json deleted file mode 100644 index a7d0fc7b77..0000000000 --- a/Documentation/devel/.vscode/settings.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "esbonio.sphinx.confDir": "" -} \ No newline at end of file diff --git a/Documentation/devel/building.rst b/Documentation/devel/building.rst index f28a68d8ce..f779d963aa 100644 --- a/Documentation/devel/building.rst +++ b/Documentation/devel/building.rst @@ -17,13 +17,16 @@ performance reasons. Both patched glibc and patched musl are built by default. Gramine currently only works on the x86_64 architecture. Gramine is currently tested on Ubuntu 18.04/20.04, along with Linux kernel version 5.x. We recommend building and installing Gramine on Ubuntu with Linux kernel version 5.11 or -higher. If you find problems with Gramine on other Linux distributions, +higher. If you find problems with Gramine on other Linux distributions, contact us with a |~| detailed `bug report `__. **Install from a Docker container** -If you opt to build Gramine, you can install Gramine from a Docker container you build that includes an OS packaged with Gramine binaries. The container includes everything that's included in the custom installation. You must create your own manifest. Go to :doc:`docker-image-installation`. +If you opt to build Gramine, you can install Gramine from a Docker container +you build that includes an OS packaged with Gramine binaries. +The container includes everything that's included in the custom installation. +You must create your own manifest. Go to :doc:`docker-image-installation`. Install dependencies -------------------- @@ -269,20 +272,23 @@ Additional build options take a long time: unfortunately, the only supported way of building ``libgomp`` is as part of a complete GCC build. -.. _FSGSBASE: - Prepare a signing key --------------------- -These instructions are only required for systems using Intel® SGX that have not already created a signing key. +These instructions are only required for systems using Intel® SGX that have not +already created a signing 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 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. + - If your system is using Intel® SGX and have not created a signing key, + follow the instructions below. -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:: +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 @@ -420,8 +426,7 @@ instructions ensure that the resulting kernel has FSGSBASE support. After the patched Linux kernel is installed, you may proceed with installations of other SGX software infrastructure: the Intel SGX Linux driver, the Intel SGX -SDK/PSW, and Gramine itself. - +SDK/PSW, and Gramine itself. 2. Install the Intel SGX driver ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -446,4 +451,4 @@ Note that this is an inadvisable configuration for production systems. Alternatively, if your CPU supports :term:`FLC`, you can choose to install the DCAP version of the Intel SGX driver from: -- https://github.com/intel/SGXDataCenterAttestationPrimitives \ No newline at end of file +- https://github.com/intel/SGXDataCenterAttestationPrimitives diff --git a/Documentation/environment-setup.rst b/Documentation/environment-setup.rst index 74b0767f5d..7fad6a0e5b 100644 --- a/Documentation/environment-setup.rst +++ b/Documentation/environment-setup.rst @@ -13,14 +13,18 @@ Gramine with SGX support requires several features from your system: - Intel SGX SDK/PSW and (optionally) Intel DCAP must be installed. -If your system doesn’t meet these requirements, please refer to more detailed descriptions in :doc:`devel/building`. +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. +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 +Prepare a signing key ===================== Only for SGX, and if you haven’t already, enter the following: @@ -29,4 +33,6 @@ 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 :file: `{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. diff --git a/Documentation/gramine-users.rst b/Documentation/gramine-users.rst index 2731d696a3..a1e8cdc39f 100644 --- a/Documentation/gramine-users.rst +++ b/Documentation/gramine-users.rst @@ -1,35 +1,51 @@ Users of Gramine ================ -We are excited to share that several companies are experimenting with Gramine for their confidential computing solutions. Please reach out to us at maintainers@gramineproject.io if you are using Gramine and would like to be highlighted on our page. We are looking forward to collaborating with you and continue to enhance Gramine to meet the needs of your confidential computing use cases. We will be updating this list regularly (the list is sorted alphabetically). +We are excited to share that several companies are experimenting with Gramine +for their confidential computing solutions. Please reach out to us at +maintainers@gramineproject.io if you are using Gramine and would like to be +highlighted on our page. We are looking forward to collaborating with you and +continue to enhance Gramine to meet the needs of your confidential computing use +cases. We will be updating this list regularly (the list is sorted +alphabetically). -- `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. +- `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/gsc-installation.rst b/Documentation/gsc-installation.rst index 62ad4ebdb5..ff1fd24c93 100644 --- a/Documentation/gsc-installation.rst +++ b/Documentation/gsc-installation.rst @@ -1,14 +1,20 @@ Gramine Shielded Containers =========================== -The Gramine Shielded Container (GSC) tool transforms an original Docker image into a new, "graminized" image -which includes the Gramine Library OS, manifest files, and Intel SGX related information. It uses Gramine to execute the application inside an Intel SGX enclave. It follows the common Docker approach to first build an image and subsequently run this image inside a container. +The Gramine Shielded Container (GSC) tool transforms an original Docker image +into a new, "graminized" image which includes the Gramine Library OS, manifest +files, and Intel SGX related information. +It uses Gramine to execute the application inside an Intel SGX enclave. +It follows the common Docker approach to first build an image and subsequently +run this image inside a container. -At first a Docker image has to be graminized via the ``gsc build`` command. When the graminized image is -run within an Intel SGX enclave, the image must be signed via a ``gsc sign-image`` command. Subsequently, the image can be run using ``docker run``. +At first a Docker image has to be graminized via the ``gsc build`` command. +When the graminized image is run within an Intel SGX enclave, the image must be +signed via a ``gsc sign-image`` command. +Subsequently, the image can be run using ``docker run``. Note the GSC documentation is split from the core Gramine documentation and is hosted here: https://gramine.readthedocs.io/projects/gsc. Similarly, the GSC tool is split from the core Gramine repository and can be -found here: https://github.com/gramineproject/gsc. \ No newline at end of file +found here: https://github.com/gramineproject/gsc. diff --git a/Documentation/img/indx-background.png b/Documentation/img/indx-background.png deleted file mode 100644 index 5dce3e7199df7e25c2096d46ca832c1e7b3d5df7..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 2095 zcmeAS@N?(olHy`uVBq!ia0y~yU~B;5uN-VZk^dT+XMq%Ffk$L91A|Zr2s7SGldk{@ zvX^-Jy0SmxkQ5Z=NfA9N3KnvWC~+(;$;dBaSh?;LB0FlEm9xw)x%B@ExrOxq6>V*@D*$t=l9Wmxgt@ zV0co->>`U%g-PIr_~WlmK=SAzmZs Z{o2bm=UrkzHn3h~@O1TaS?83{1OOg|{MrBj diff --git a/Documentation/index.rst b/Documentation/index.rst index 90bdd82f03..34cc5329d5 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -2,27 +2,47 @@ Gramine Documentation ********************* -Gramine is a lightweight guest OS that's designed to run a single Linux application with minimal host requirements. Gramine can run applications in an isolated environment with benefits comparable to running a complete OS in a virtual machine, including guest customization, ease of porting to different host OSs, and process migration. +Gramine is a lightweight guest OS that's designed to run a single Linux +application with minimal host requirements. +Gramine can run applications in an isolated environment with benefits comparable +to running a complete OS in a virtual machine, including guest customization, , +ease of porting to different host OSs, and process migration. -Gramine supports running Linux applications using the Intel Software Guard Extensions, or Intel SGX. For mor information, refer to the :doc:`sgx-intro` article. +Gramine supports running Linux applications using the Intel Software Guard +Extensions, or Intel SGX. For mor information, refer to the :doc:`sgx-intro` +article. -This page provides an overview of this site. Each section is outlined below with a brief explanation and links to specific sections. This page mimics the table of contents in the left column. +This page provides an overview of this site. +Each section is outlined below with a brief explanation and links to specific +sections. +This page mimics the table of contents in the left column. Gramine deployment options ------------------------------------ -There are three deployment options for Gramine—each option is described below. There is also one option to help develop Gramine. +There are three deployment options for Gramine—each option is described below. +There is also one option to help develop Gramine. Ready-made protected applications ===================================== -Confidential compute images are ready-made solutions for popular open source projects such as `PyTorch `_ and `Redis `_. These images enable you to customize your environment through interactive scripts. The result is an image that includes your specific machine-learning application, common dependencies, and a manifest file. +Confidential compute images are ready-made solutions for popular open source +projects such as `PyTorch `_ +and `Redis `_. +These images enable you to customize your environment through interactive +scripts. The result is an image that includes your specific machine-learning +application, common dependencies, and a manifest file. -.. note:: These confidential compute images only run on machines that support Intel SGX. +.. note:: These confidential compute images only run on machines that support + Intel SGX. See the :doc:`curated-installation` article for more information. Protect your container ============================ -Docker images are used to run applications in the cloud. The Gramine Shielded Container tool transforms a Docker image into a graminized image that includes the Gramine Library OS and Intel SGX related information. It enables you to run an application on a Docker image and keep it protected. +Docker images are used to run applications in the cloud. +The Gramine Shielded +Container tool transforms a Docker image into a graminized image that includes +the Gramine Library OS and Intel SGX related information. +It enables you to run an application on a Docker image and keep it protected. - :doc:`gsc-installation` - Get an overview of the installation process of a Gramine Shielded Container. - `Build a Gramine Docker image `_ - Build a Docker image that contains the Gramine functionality. @@ -32,52 +52,78 @@ Docker images are used to run applications in the cloud. The Gramine Shielded Co Protect your application ========================== -Use this option to protect an exiting application with Gramine. Little to no addition modification of your application is needed. +Use this option to protect an exiting application with Gramine. +Little to no addition modification of your application is needed. These are the processes to follow protect your application with Gramine: -- :doc:`Install Gramine` - Install Gramine from binaries on to the various supported versions of Ubuntu or RHEL 8. -- :doc:`Set up the environment` - Set up the Gramine environment to work with or without SGX and prepare a signing key. -- :doc:`Run a sample application` - Run a sample application to ensure your environment is running correctly. +- :doc:`Install Gramine` - Install Gramine from binaries on to the + various supported versions of Ubuntu or RHEL 8. +- :doc:`Set up the environment` - Set up the Gramine + environment to work with or without SGX and prepare a signing key. +- :doc:`Run a sample application` - Run a sample + application to ensure your environment is running correctly. Develop Gramine ------------------------------------ -This section describes how to develop Gramine. It contains instructions on how to install Gramine from binaries, install dependencies, set up debugging and other processes necessary for Gramine development. +This section describes how to develop Gramine. +It contains instructions on how to install Gramine from binaries, install +dependencies, set up debugging and other processes necessary for Gramine +development. -- :doc:`Build Gramine from source files` - Build Gramine and ensure all the dependencies installed with proper drivers. This option requires a more work but allows you to choose build options. -- :doc:`Set up Debugging` - Configure Gramine with Gnu Debugger (GDB) and setup compiling optimizations. -- :doc:`Implement a new system call` - Define the interface of the system call, add, import, and Implement new PAL calls if needed. +- :doc:`Build Gramine from source files` - Build Gramine and + ensure all the dependencies installed with proper drivers. + This option requires a more work but allows you to choose build options. +- :doc:`Set up Debugging` - Configure Gramine with Gnu Debugger + (GDB) and setup compiling optimizations. +- :doc:`Implement a new system call` - Define the interface + of the system call, add, import, and Implement new PAL calls if needed. Contribute to Gramine ------------------------------------ -We encourage anyone who is interested to contribute to Gramine. We offer procedures and user groups that to help you get started. +We encourage anyone who is interested to contribute to Gramine. +We offer procedures and user groups that to help you get started. -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` - The Contributing to Gramine page outlines the procedures for performing pull requests, reviews, and regression tests. +- :doc:`devel/contributing` - The Contributing to Gramine page outlines the + procedures for performing pull requests, reviews, and regression tests. -- :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/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. +- :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. -- :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. - -- `Gramine User Groups `_ - The Gramine user-groups page lists the user groups you can join to help you get up to speed with developing Gramine. +- `Gramine User Groups `_ - The + Gramine user-groups page lists the user groups you can join to help you get up + to speed with developing Gramine. Resources ------------------------------------ -The Gramine project provides resources to help you understand and develop it. The resources page contains a list of maintainers, users, and a glossary to help you with any questions you may have. - -- :doc:`management-team` - This page list the people managing the maintenance of Gramine -- :doc:`gramine-users` - See what companies are using Gramine for their confidential computing needs +The Gramine project provides resources to help you understand and develop it. +The resources page contains a list of maintainers, users, and a glossary to help + you with any questions you may have. + +- :doc:`management-team` - This page list the people managing the maintenance of + Gramine +- :doc:`gramine-users` - See what companies are using Gramine for their + confidential computing needs - :doc:`glossary` - Become familiar with the terms used for Gramine Getting help diff --git a/Documentation/manifest-syntax.rst b/Documentation/manifest-syntax.rst index 65c7733723..2fd17de304 100644 --- a/Documentation/manifest-syntax.rst +++ b/Documentation/manifest-syntax.rst @@ -124,10 +124,13 @@ or loader.argv_src_file = "file:file_with_serialized_argv" -If you want your application to use commandline arguments, you must choose one of the three mutually exclusive options: +If you want your application to use commandline arguments, you must choose one +of the three mutually exclusive options: + - set ``loader.insecure__use_cmdline_argv`` (insecure in almost all cases), - put commandline arguments into ``loader.argv`` array, -- point ``loader.argv_src_file`` to a file containing output of :ref:`gramine-argv-serializer`. +- point ``loader.argv_src_file`` to a file + containing output of :ref:`gramine-argv-serializer`. If none of the above arguments-handling manifest options are specified in the manifest, the application will get ``argv = [ ]``. @@ -354,7 +357,6 @@ Python). Could be useful in SGX environments: child processes consume to achieve this, you need to run the whole Gramine inside a proper security sandbox. - Root FS mount point ^^^^^^^^^^^^^^^^^^^ @@ -485,7 +487,6 @@ explicit value will take precedence. .. note:: Support for EDMM first appeared in Linux 6.0. - Enclave size ^^^^^^^^^^^^ @@ -533,13 +534,12 @@ your system, such ``bash -c ls`` SGX workload will fail. Note this does not apply to the enclaves with :term:`EDMM` enabled, where memory is not reserved upfront and is allocated on demand. - Number of threads ^^^^^^^^^^^^^^^^^ :: - sgx.insecure__rpc_thread_num = [NUM] + sgx.max_threads = [NUM] (Default: 4) This syntax specifies the maximum number of threads that can be created inside @@ -571,7 +571,7 @@ Number of RPC threads (Exitless feature) :: - sgx.rpc_thread_num = [NUM] + sgx.insecure__rpc_thread_num = [NUM] (Default: 0) This syntax specifies the number of RPC threads that are created outside of diff --git a/Documentation/manpages/gramine-sgx-sigstruct.rst b/Documentation/manpages/gramine-sgx-sigstruct.rst index 58d8c4a2e1..79c160eb2d 100644 --- a/Documentation/manpages/gramine-sgx-sigstruct.rst +++ b/Documentation/manpages/gramine-sgx-sigstruct.rst @@ -35,6 +35,7 @@ Example ======= .. code-block:: sh + $ gramine-sgx-sigstruct-view --verbose --output-format=toml helloworld.sig mr_signer = "0dedbe47afb6955e5f6109637c1fbd9cc4b4e073e1396da8ce2091075e5b0a3b" mr_enclave = "81a675e9a408818b430be4b259f3e11e6f8cacdb4c971c3114ee79fe53076893" @@ -47,4 +48,4 @@ Example attribute_xfrm_mask = "0xfffffffffff9ff1b" misc_mask = "0xffffffff" date = "2023-02-20" - debug_enclave = true \ No newline at end of file + debug_enclave = true diff --git a/Documentation/manpages/index.rst b/Documentation/manpages/index.rst index 9c6f710367..d01de21390 100644 --- a/Documentation/manpages/index.rst +++ b/Documentation/manpages/index.rst @@ -13,7 +13,8 @@ The following man pages are available: gramine-sgx-get-token gramine-sgx-ias-request gramine-sgx-ias-verify-report - gramine-sgx-quote-dump + gramine-sgx-quote-view + gramine-sgx-sigstruct-view gramine-sgx-sign is-sgx-available diff --git a/Documentation/performance.rst b/Documentation/performance.rst index f59734fe48..93f587a51a 100644 --- a/Documentation/performance.rst +++ b/Documentation/performance.rst @@ -182,9 +182,9 @@ for each system call and exit the enclave. The feature can be disabled by specifying ``sgx.insecure__rpc_thread_num = 0``. You must decide how many untrusted helper RPC threads your application needs. A -rule of thumb: specify ``sgx.insecure__rpc_thread_num == sgx.thread_num``, i.e., -the number of untrusted RPC threads should be the same as the number of enclave -threads. For example, native Redis 6.0 uses 3-4 enclave threads during +rule of thumb: specify ``sgx.insecure__rpc_thread_num == sgx.max_threads``, +i.e., the number of untrusted RPC threads should be the same as the number of +enclave threads. For example, native Redis 6.0 uses 3-4 enclave threads during its execution, plus Gramine uses another 1-2 helper enclave threads. So Redis manifest has an over-approximation of this number: ``sgx.max_threads = 8``. Thus, to correctly enable the Exitless feature, specify @@ -192,12 +192,12 @@ to correctly enable the Exitless feature, specify :: - # exitless disabled: `sgx.thread_num = 8` and `sgx.insecure__rpc_thread_num = 0` + # exitless disabled: `sgx.max_threads = 8` and `sgx.insecure__rpc_thread_num = 0` CI-Examples/redis$ gramine-sgx redis-server --save '' --protected-mode no & CI-Examples/redis$ src/src/redis-benchmark -t set 43010.75 requests per second - # exitless enabled: `sgx.thread_num = 8` and `sgx.insecure__rpc_thread_num = 8` + # exitless enabled: `sgx.max_threads = 8` and `sgx.insecure__rpc_thread_num = 8` CI-Examples/redis$ gramine-sgx redis-server --save '' --protected-mode no & CI-Examples/redis$ src/src/redis-benchmark -t set 68119.89 requests per second diff --git a/Documentation/prepare-a-signing-key.rst b/Documentation/prepare-a-signing-key.rst deleted file mode 100644 index d34f257498..0000000000 --- a/Documentation/prepare-a-signing-key.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. _prepare_a_signing_key - -Prepare a signing key ---------------------- - -These instructions are only required for systems using SGX and have not already created a signing key. - - - If your system is not using SGX, skip to Run the sample application. - - - If your system is using SGX and you already created a signing key, skip to Run the sample application. - - - If your system is using SGX and have not created a signing key, follow the instructions below. - -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 diff --git a/Documentation/prerequisites.rst b/Documentation/prerequisites.rst index 13c280c56b..799d36c66f 100644 --- a/Documentation/prerequisites.rst +++ b/Documentation/prerequisites.rst @@ -10,9 +10,13 @@ Gramine with Intel® SGX support has the following requirements: - 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. +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 Intel® SGX compatibility --------------- -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 +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. diff --git a/Documentation/quickstart.rst b/Documentation/quickstart.rst index 84e9014b88..5b2e8fe585 100644 --- a/Documentation/quickstart.rst +++ b/Documentation/quickstart.rst @@ -3,16 +3,21 @@ Gramine installation options ---------------------------- -There are three options to choose from when using Gramine to protect your application. The option you choose depends on how you are running your application. +There are three options to choose from when using Gramine to protect your +application. +The option you choose depends on how you are running your application. -:ref:`Install Gramine` - This option provides instructions for installing Gramine on various versions of Ubuntu or Red Hat Enterprise Linux 8. +:ref:`Install Gramine` - This option provides instructions for installing +Gramine on various versions of Ubuntu or Red Hat Enterprise Linux 8. -: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:`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. - -..role:: h1Install Gramine - +: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. Debian 11 ^^^^^^^^^ @@ -23,7 +28,6 @@ Debian 11 echo "deb http://deb.debian.org/debian $(lsb_release -sc)-backports main" \ | sudo tee /etc/apt/sources.list.d/backports.list - 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 @@ -32,10 +36,12 @@ Debian 11 echo "deb [arch=amd64 signed-by=/usr/share/keyrings/intel-sgx-deb.asc] https://download.01.org/intel-sgx/sgx_repo/ubuntu focal main" \ | sudo tee /etc/apt/sources.list.d/intel-sgx.list + sudo apt-get update sudo apt-get install gramine Ubuntu 22.04 LTS, 20.04 LTS or 18.04 LTS ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + :: sudo curl -fsSLo /usr/share/keyrings/gramine-keyring.gpg https://packages.gramineproject.io/gramine-keyring.gpg @@ -46,6 +52,7 @@ Ubuntu 22.04 LTS, 20.04 LTS or 18.04 LTS 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 + sudo apt-get update sudo apt-get install gramine RHEL-like distributions version 8 (and experimentally also version 9) @@ -56,7 +63,6 @@ RHEL-like distributions version 8 (and experimentally also version 9) 1. Install EPEL repository as described here: https://docs.fedoraproject.org/en-US/epel/ - 2. Install Gramine:: sudo curl -fsSLo /etc/yum.repos.d/gramine.repo https://packages.gramineproject.io/rpm/gramine.repo diff --git a/Documentation/requirements.txt b/Documentation/requirements.txt index 294dcccfb6..7f39416795 100644 --- a/Documentation/requirements.txt +++ b/Documentation/requirements.txt @@ -1,7 +1,15 @@ -sphinx==4.2.0 -breathe==4.29.2 -sphinx_rtd_theme +sphinx==1.8.0 +breathe<4.13.0 +recommonmark==0.7.1 +sphinx_rtd_theme<1 tomli>=1.1.0 # Work around Sphinx/docutils incompatibility, see https://github.com/sphinx-doc/sphinx/issues/9727. # TODO: This shouldn't be necessary once we upgrade to newer Sphinx (Sphinx 4.2.0 is not yet +# compatible with new docutils, but pins the docutils version by itself). +docutils<0.18 + +# jinja 3.1.0 removed quite a few functions used by sphinx +# https://jinja.palletsprojects.com/en/3.1.x/changes/#version-3-1-0 +# https://github.com/pallets/jinja/pull/1544 +jinja2<3.1 diff --git a/Documentation/run-sample-application.rst b/Documentation/run-sample-application.rst index 5d0068d9a8..9db848848f 100644 --- a/Documentation/run-sample-application.rst +++ b/Documentation/run-sample-application.rst @@ -4,7 +4,8 @@ Run a sample application ======================= -The core Gramine repository contains sample applications to test the Gramine installation. To clone the Gramine repo, use the following command: +The core Gramine repository contains sample applications to test the Gramine +installation. To clone the Gramine repo, use the following command: .. parsed-literal:: @@ -37,7 +38,8 @@ Build and run with SGX:: Other sample applications ------------------------- -Several applications that demonstrate Gramine usability are available in the :file:`CI-Examples` directory in the repository. Each application contains a +Several applications that demonstrate Gramine usability are available in the +:file:`CI-Examples` directory in the repository. Each application contains a short README file with instructions how to test it. We recommend starting with a simpler, thoroughly documented example of Redis to understand manifest options and Gramine features. @@ -54,4 +56,7 @@ only on Ubuntu). 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 ''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 +Most of the examples we provide use GNU C Library (glibc). +If your application is built against musl libc, you can pass ''musl'' to +''gramine.runtimedir()'' when generating the manifest from a template; +this will mount musl libc (instead of the default glibc). diff --git a/Documentation/sgx-intro.rst b/Documentation/sgx-intro.rst index 355c63b3da..2f0a68c2e2 100644 --- a/Documentation/sgx-intro.rst +++ b/Documentation/sgx-intro.rst @@ -3,7 +3,8 @@ Introduction to SGX .. highlight:: sh -Gramine project uses :term:`SGX` to securely run software. Gramine supports running Linux applications using the :term:`Intel SGX ` +Gramine project uses :term:`SGX` to securely run software. +Gramine supports running Linux applications using the :term:`Intel SGX ` (Software Guard Extensions) technology (we sometimes call this version **Gramine-SGX**). With Intel SGX, applications are secured in hardware-encrypted memory regions (called SGX enclaves). SGX protects code and