From 9bae2b0f42f1ca5204bcd0a0010b142d298d9567 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Pawe=C5=82=20Marczewski?= Date: Mon, 9 May 2022 13:28:32 +0200 Subject: [PATCH] fixup! [LibOS,Pal/Linux-SGX] Replace old protected files subsystem MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Paweł Marczewski --- common/src/protected_files/README.rst | 63 +++++++++++++++++---------- 1 file changed, 40 insertions(+), 23 deletions(-) diff --git a/common/src/protected_files/README.rst b/common/src/protected_files/README.rst index 0e19722624..ea0ff49254 100644 --- a/common/src/protected_files/README.rst +++ b/common/src/protected_files/README.rst @@ -1,44 +1,58 @@ -=============== -Protected Files -=============== +=========================== +Protected (Encrypted) Files +=========================== -Protected files (PF) are a type of files that can be specified in the manifest (SGX only). They are -encrypted on disk and transparently decrypted when accessed by Gramine or by application running -inside Gramine. +This directory contains the implementation of Protected Files (PF), a library +used for implementing *encrypted files* in Gramine. These files are encrypted on +disk and transparently decrypted when accessed by Gramine or by application +running inside Gramine. + +Originally, the whole feature was called *protected files*, and was implemented +for SGX only. After moving it to LibOS, we updated the name: + +* *encrypted files* is the name of the feature in Gramine, +* ``protected_files`` is the name of the platform-independent library used by + that feature (i.e. this directory). Features ======== -- Data is encrypted (confidentiality) and integrity protected (tamper resistance). -- File swap protection (a PF can only be accessed when in a specific path). -- Transparency (Gramine application sees PFs as regular files, no need to modify the application). +- Data is encrypted (confidentiality) and integrity protected (tamper + resistance). +- File swap protection (an encrypted file can only be accessed when in a + specific path). +- Transparency (the application sees encrypted files as regular files, no need + to modify the application). Example ------- :: - sgx.protected_files = [ - "file:tmp/some_file", - "file:tmp/some_dir", - "file:tmp/another_dir/some_file", + fs.mounts = [ + ... + { type = "encrypted", path = "/some_file", uri = "file:tmp/some_file" }, + { type = "encrypted", path = "/some_dir", uri = "file:tmp/some_dir" }, + { type = "encrypted", path = "/another_file", uri = "file:another_dir/some_file" }, ] -Paths specifying PF entries can be files or directories. If a directory is specified, -all existing files/directories within 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. +Gramine allows mounting files and directories as encrypted. If a directory is +mounted as encrypted, all existing files/directories within it are recursively +treated as encrypted. + +See ``Documentation/manifest-syntax.rst`` for details. Limitations ----------- -Metadata currently limits PF path size to 512 bytes and filename size to 260 bytes. +Metadata currently limits PF path size to 512 bytes and filename size to 260 +bytes. NOTE ---- -The ``tools`` directory contains the ``pf_crypt`` utility that converts files to/from the protected -format. +The ``tools`` directory in Linux-SGX PAL contains the ``pf_crypt`` utility that +converts files to/from the protected format. Internal protected file format in this version was ported from the `SGX SDK `_. @@ -46,11 +60,14 @@ Internal protected file format in this version was ported from the `SGX SDK Tests ===== -Tests in ``LibOS/shim/test/fs`` contain PF tests (target is ``pf-test``). +Tests in ``LibOS/shim/test/fs`` contain encrypted file tests (``test_enc.py``). +Some tests in ``LibOS/shim/test/regression`` also work with encrypted files. TODO ==== - Truncating protected files is not yet implemented. -- The recovery file feature is disabled, this needs to be discussed if it's needed in Gramine. -- Tests for invalid/malformed/corrupted files need to be ported to the new format. +- The recovery file feature is disabled, this needs to be discussed if it's + needed in Gramine. +- Tests for invalid/malformed/corrupted files need to be ported to the new + format.