Skip to content
This repository has been archived by the owner on Jan 20, 2022. It is now read-only.

[Docs] Ensure that insecure options are clearly marked as such #2454

Merged
merged 2 commits into from
Jun 28, 2021
Merged

[Docs] Ensure that insecure options are clearly marked as such #2454

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6376605
[Docs] Update SGX availability checking instruction
mkow Jun 16, 2021
8f77a8e
[Docs] Ensure that insecure options are clearly marked as such
mkow Jun 16, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 3 additions & 4 deletions Documentation/cloud-deployment.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,10 +102,9 @@ cluster.

.. warning::

This example relies on insecure arguments provided at runtime and should
not be used production. To use trusted arguments, please see the `manpage
of GSC
<https://graphene.readthedocs.io/en/latest/manpages/gsc.html#using-graphene-s-trusted-command-line-arguments>`__.
This example relies on insecure arguments provided at runtime and should not
be used production. To use trusted arguments, please see the `manpage of GSC
<https://graphene.readthedocs.io/en/latest/manpages/gsc.html#using-graphene-s-trusted-command-line-arguments>`__.

#. Pull Python image::

Expand Down
55 changes: 33 additions & 22 deletions Documentation/manifest-syntax.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,10 @@ Graphene outputs log messages of the following types:
* ``trace``: More detailed information, such as all system calls requested by
the application. Might contain a lot of noise.

.. warning::
Only ``error`` log level is suitable for production. Other levels may leak
sensitive data.

Preloaded libraries
^^^^^^^^^^^^^^^^^^^

Expand Down Expand Up @@ -83,6 +87,7 @@ The recommended usage is to provide an absolute path, and mount the executable
at that path. For example:

::

libos.entrypoint = "/usr/bin/python3.8"

fs.mount.python.type = "chroot"
Expand Down Expand Up @@ -430,8 +435,8 @@ Optional CPU features (AVX, AVX512, MPX, PKRU)

This syntax ensures that the CPU features are available and enabled for the
enclave. If the options are set in the manifest but the features are unavailable
on the platform, enclave initialization should fail. If the options are unset,
enclave initialization should succeed even if these features are unavailable on
on the platform, enclave initialization will fail. If the options are unset,
enclave initialization will succeed even if these features are unavailable on
the platform.

ISV Product ID and SVN
Expand All @@ -456,9 +461,12 @@ Allowed files
This syntax specifies the files that are allowed to be created or loaded into
the enclave unconditionally. In other words, allowed files can be opened for
reading/writing and can be created if they do not exist already. Allowed files
are not cryptographically hashed and are thus not protected. It is insecure to
mark files as allowed if they contain code or critical information; developers
must not allow files blindly! Instead, use trusted or protected files.
are not cryptographically hashed and are thus not protected.

.. warning::
It is insecure to allow files containing code or critical information;
developers must not allow files blindly! Instead, use trusted or protected
files.

Trusted files
^^^^^^^^^^^^^
Expand All @@ -467,14 +475,14 @@ Trusted files

sgx.trusted_files.[identifier] = "[URI]"

This syntax specifies the files to be cryptographically hashed and thus allowed
to be loaded into the enclave. This implies that trusted files can be only
opened for reading (not for writing) and cannot be created if they do not exist
already. The signer tool will automatically generate hashes of these files and
add them into the SGX-specific manifest (``.manifest.sgx``). Marking files as
trusted is especially useful for shared libraries: a |~| trusted library cannot
be silently replaced by a malicious host because the hash verification will
fail.
This syntax specifies the files to be cryptographically hashed at build time,
and allowed to be accessed by the app in runtime only if their hashes match.
This implies that trusted files can be only opened for reading (not for writing)
and cannot be created if they do not exist already. The signer tool will
automatically generate hashes of these files and add them to the SGX-specific
manifest (``.manifest.sgx``). Marking files as trusted is especially useful for
shared libraries: a |~| trusted library cannot be silently replaced by a
malicious host because the hash verification will fail.

Protected files
^^^^^^^^^^^^^^^
Expand All @@ -490,7 +498,7 @@ Protected files guarantee data confidentiality and integrity (tamper
resistance), as well as file swap protection (a protected file can only be
accessed when in a specific path).

URIs can be files or directories. If a directory is specified, all existing
URI can be a file or a directory. If a directory is specified, all existing
files/directories within it are registered as protected recursively (and are
expected to be encrypted in the PF format). New files created in a protected
directory are automatically treated as protected.
Expand Down Expand Up @@ -586,9 +594,10 @@ This syntax specifies whether to enable SGX enclave-specific statistics:
includes creating the enclave, adding enclave pages, measuring them and
initializing the enclave.

*Note:* this option is insecure and cannot be used with production enclaves
(``sgx.debug = false``). If the production enclave is started with this option
set, Graphene will fail initialization of the enclave.
.. warning::
This option is insecure and cannot be used with production enclaves
(``sgx.debug = false``). If a production enclave is started with this option
set, Graphene will fail initialization of the enclave.

SGX profiling
^^^^^^^^^^^^^
Expand All @@ -611,9 +620,10 @@ sgx-perf.data``.

See :ref:`sgx-profile` for more information.

*Note:* this option is insecure and cannot be used with production enclaves
(``sgx.debug = false``). If the production enclave is started with this option
set, Graphene will fail initialization of the enclave.
.. warning::
This option is insecure and cannot be used with production enclaves
(``sgx.debug = false``). If a production enclave is started with this option
set, Graphene will fail initialization of the enclave.

::

Expand Down Expand Up @@ -655,5 +665,6 @@ lower overhead.
Note that the accuracy is limited by how often the process is interrupted by
Linux scheduler: the effective maximum is 250 samples per second.

**Note**: This option applies only to ``aex`` mode. In the ``ocall_*`` modes,
currently all samples are taken.
.. note::
This option applies only to ``aex`` mode. In the ``ocall_*`` modes, currently
all samples are taken.
9 changes: 2 additions & 7 deletions Documentation/quickstart.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,13 +39,8 @@ Graphene requires several features from your system:
If your system doesn't meet these requirements, please refer to more detailed
descriptions in :doc:`building`.

#. Ensure that Intel SGX is enabled on your platform::

lsmod | grep sgx
ps ax | grep [a]esm_service

The first command should list :command:`isgx` (or :command:`sgx`) and the
second command should list the process status of :command:`aesm_service`.
#. Ensure that Intel SGX is enabled on your platform using
:program:`is_sgx_available`.

#. Clone the Graphene repository::

Expand Down