diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml index 4440d87d..8b5b0a4f 100644 --- a/.github/workflows/vale.yml +++ b/.github/workflows/vale.yml @@ -1,4 +1,4 @@ -name: Linting +name: Vale on: push: branches: @@ -10,17 +10,12 @@ on: - "docs/**" jobs: - prose: + vale: runs-on: ubuntu-latest steps: - - name: Checkout - uses: actions/checkout@v3 + - uses: actions/checkout@v3 - - name: Vale - uses: errata-ai/vale-action@v2 + - uses: errata-ai/vale-action@reviewdog with: files: docs/docs - env: - # Required, set by GitHub actions automatically: - # https://docs.github.com/en/actions/security-guides/automatic-token-authentication#about-the-github_token-secret - GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} + fail_on_error: true diff --git a/.vale.ini b/.vale.ini index edb772d0..4b481e12 100644 --- a/.vale.ini +++ b/.vale.ini @@ -3,6 +3,7 @@ Vocab = edgeless [*.md] BasedOnStyles = Vale, Microsoft, Google +Vale.Terms = NO # decrease to suggestion Microsoft.Foreign = suggestion # conflicts with Microsoft.Contractions diff --git a/docs/docs/knowledge/limitations.md b/docs/docs/knowledge/limitations.md index fd3af813..e3ce8566 100644 --- a/docs/docs/knowledge/limitations.md +++ b/docs/docs/knowledge/limitations.md @@ -17,7 +17,7 @@ These usually compile, but return an error at runtime. * `os/exec`: spawning processes is unsupported * `os/signal`: signals aren't passed to the enclave -## cgo: Unsupported libc functions +## cgo: Unsupported `libc` functions Using these functions causes a build, sign, or runtime error. diff --git a/docs/docs/knowledge/model.md b/docs/docs/knowledge/model.md index 97bd57da..9e0d0917 100644 --- a/docs/docs/knowledge/model.md +++ b/docs/docs/knowledge/model.md @@ -1,9 +1,11 @@ # Programming model + Enclaves are execution environments isolated from the rest of the system. In the original SGX programming model, the application code is partitioned into trusted and untrusted code. The untrusted code runs in a conventional process. Within this process, one or more enclaves are created that execute the trusted code. The enclave is entered with an *ECALL*. The enclave can transfer execution to untrusted code by performing an *OCALL*. -EGo has a different programming model: The entire application runs inside the enclave. Transitions between trusted and untrusted code are hidden inside the EGo runtime and are transparent to the developer. Internally, an ECALL is performed when the enclave creates a new thread. The enclave uses OCALLs to implement some classes of syscalls, e.g., file and network I/O. (Some syscalls can be fully emulated within the enclave.) Manual ECALLs/OCALLs by application code are neither required nor possible. +EGo has a different programming model: The entire application runs inside the enclave. Transitions between trusted and untrusted code are hidden inside the EGo runtime and are transparent to the developer. Internally, an ECALL is performed when the enclave creates a new thread. The enclave uses OCALLs to implement some classes of system calls, e.g., file and network I/O. (Some system calls can be fully emulated within the enclave.) Manual ECALLs/OCALLs by application code are neither required nor possible. Advantages of this approach are: + * Developing a confidential app is almost like developing a conventional app. Developers don't need to learn a new programming model. * No need to partition an app, which can be effortful and error-prone * Porting an existing app is simple diff --git a/docs/docs/reference/cli.md b/docs/docs/reference/cli.md index 9ce9368c..6303eb33 100644 --- a/docs/docs/reference/cli.md +++ b/docs/docs/reference/cli.md @@ -76,7 +76,7 @@ Run a signed executable as a MarbleRun Marble Run a signed executable as a MarbleRun Marble. Requires a running MarbleRun Coordinator instance. -Environment variables are only readable from within the enclave if they start with "EDG_" and +Environment variables are only readable from within the enclave if they start with `EDG_` and will be extended/overwritten with the ones specified in the manifest. Requires the following configuration environment variables: diff --git a/docs/docs/reference/config.md b/docs/docs/reference/config.md index cf5651e0..b70495f7 100644 --- a/docs/docs/reference/config.md +++ b/docs/docs/reference/config.md @@ -1,7 +1,9 @@ # Configuration file + Your enclave's configuration is defined in JSON and applied when signing an executable via `ego sign`. Here's an example configuration: + ```json { "exe": "helloworld", @@ -47,6 +49,7 @@ Here's an example configuration: ``` ## Basic settings + `exe` is the (relative or absolute) path to the executable that should be signed. `key` is the path to the private RSA key of the signer. When invoking `ego sign` and the key file doesn't exist, a key with the required parameters is automatically generated. You can also generate it yourself with: @@ -55,7 +58,7 @@ Here's an example configuration: openssl genrsa -out private.pem -3 3072 ``` -If `debug` is true, the enclave will be debuggable. +If `debug` is true, the enclave can be inspected with a debugger. `heapSize` specifies the heap size available to the enclave in MB. It should be at least 512 MB. @@ -66,12 +69,13 @@ If `executableHeap` is true, the enclave heap will be executable. This is requir `securityVersion` should be incremented by the developer whenever a security fix is made to the enclave code. ## Mounts + `mounts` define custom mount points that apply to the file system presented to the enclave. This can be omitted if no mounts other than the default mounts should be performed, or you can define multiple entries with the following parameters: - * `source` (required for `hostfs`): The directory from the host file system that should be mounted in the enclave when using `hostfs`. If this is a relative path, it will be relative to the working directory of the ego host process. For `memfs`, this value will be ignored and can be omitted. - * `target` (required): Defines the mount path in the enclave. - * `type` (required): Either `hostfs` if you want to mount a path from the host's file system in the enclave, or `memfs` if you want to use a temporary file system similar to *tmpfs* on UNIX systems, with your data stored in the secure memory environment of the enclave. - * `readOnly`: Can be `true` or `false` depending on if you want to mount the path as read-only or read-write. When omitted, will default to read-write. +* `source` (required for `hostfs`): The directory from the host file system that should be mounted in the enclave when using `hostfs`. If this is a relative path, it will be relative to the working directory of the ego host process. For `memfs`, this value will be ignored and can be omitted. +* `target` (required): Defines the mount path in the enclave. +* `type` (required): Either `hostfs` if you want to mount a path from the host's file system in the enclave, or `memfs` if you want to use a temporary file system similar to *tmpfs* on UNIX systems, with your data stored in the secure memory environment of the enclave. +* `readOnly`: Can be `true` or `false` depending on if you want to mount the path as read-only or read-write. When omitted, will default to read-write. By default, `/` is initialized as an empty `memfs` file system. To expose certain directories to the enclave, you can use the `hostfs` mounts with the options mentioned above. You can also choose to define additional `memfs` mount points, but note that there is no explicit isolation between them. They can be accessed either via the path specified in `target` or also via `/edg/mnt/`, which is where the files of the additional `memfs` mount are stored internally. @@ -82,15 +86,17 @@ It's not recommended to use the mount options to remount `/` as `hostfs` other t ::: ## Environment variables + `env` holds environment variables to set or take over from the host inside the enclave. By default, all environment variables not starting with `EDG_` are dropped when entering the enclave. - * `name` (required): The name of the environment variable - * `value` (required if not `fromHost`): The value of the environment variable - * `fromHost`: When set to `true`, the current value of the requested environment variable will be copied over if it exists on the host. If the host doesn't hold this variable, it will either fall back to the value set in `value` (if it exists), or won't be created at all. +* `name` (required): The name of the environment variable +* `value` (required if not `fromHost`): The value of the environment variable +* `fromHost`: When set to `true`, the current value of the requested environment variable will be copied over if it exists on the host. If the host doesn't hold this variable, it will either fall back to the value set in `value` (if it exists), or won't be created at all. A special environment variable is `PWD`. Depending on the mount options you have set in your configuration, you can set the initial working directory of your enclave by specifying your desired path as a value for `PWD`. Note that this directory needs to exist in the context of the enclave, not your host file system. ## Embedded files + `files` specifies files that should be embedded into the enclave. Embedded files are included in the enclave measurement and thus can't be manipulated. At runtime they're accessible via the in-enclave-memory filesystem. `source` is the path to the file that should be embedded. `target` Is the path within the in-enclave-memory filesystem where the file will reside at runtime. diff --git a/docs/docs/workflows/debug.md b/docs/docs/workflows/debug.md index edb040eb..9c62f8e0 100644 --- a/docs/docs/workflows/debug.md +++ b/docs/docs/workflows/debug.md @@ -16,7 +16,7 @@ ego-gdb --args ./helloworld The enclave may raise SIGILL signals during startup. These are expected and will be handled by EGo, so you can just `continue`. Use `handle SIGILL nostop` to do this automatically. -Setting up the `mi` interface for VSCode is a bit trickier. First, install the [C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools). +Setting up the `mi` interface for Visual Studio Code is a bit trickier. First, install the [C/C++ extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools). Use one of the following templates for your `.vscode/launch.json` file. Just replace `samples/helloworld/helloworld` with the path to your EGo executable. diff --git a/docs/styles/Google/OptionalPlurals.yml b/docs/styles/Google/OptionalPlurals.yml deleted file mode 100644 index f858ea6f..00000000 --- a/docs/styles/Google/OptionalPlurals.yml +++ /dev/null @@ -1,12 +0,0 @@ -extends: existence -message: "Don't use plurals in parentheses such as in '%s'." -link: 'https://developers.google.com/style/plurals-parentheses' -level: error -nonword: true -action: - name: edit - params: - - remove - - '(s)' -tokens: - - '\b\w+\(s\)' diff --git a/docs/styles/Google/Spelling.yml b/docs/styles/Google/Spelling.yml index 57acb884..527ac07d 100644 --- a/docs/styles/Google/Spelling.yml +++ b/docs/styles/Google/Spelling.yml @@ -5,4 +5,6 @@ ignorecase: true level: warning tokens: - '(?:\w+)nised?' - - '(?:\w+)logue' + - 'colour' + - 'labour' + - 'centre' diff --git a/docs/styles/Google/Units.yml b/docs/styles/Google/Units.yml index 379fad6b..53522ab2 100644 --- a/docs/styles/Google/Units.yml +++ b/docs/styles/Google/Units.yml @@ -1,8 +1,8 @@ extends: existence message: "Put a nonbreaking space between the number and the unit in '%s'." -link: 'https://developers.google.com/style/units-of-measure' +link: "https://developers.google.com/style/units-of-measure" nonword: true level: error tokens: - - \d+(?:B|kB|MB|GB|TB) - - \d+(?:ns|ms|s|min|h|d) + - \b\d+(?:B|kB|MB|GB|TB) + - \b\d+(?:ns|ms|s|min|h|d) diff --git a/docs/styles/Microsoft/Contractions.yml b/docs/styles/Microsoft/Contractions.yml index ded330f7..8c81dcbc 100644 --- a/docs/styles/Microsoft/Contractions.yml +++ b/docs/styles/Microsoft/Contractions.yml @@ -22,7 +22,7 @@ swap: should not: shouldn't - 'that is(?!\.)': that's + "that is(?![.,])": that's 'that''s(?=\.)': that is 'they are(?!\.)': they're diff --git a/docs/styles/Microsoft/Foreign.yml b/docs/styles/Microsoft/Foreign.yml index d37835a5..0d3d6002 100644 --- a/docs/styles/Microsoft/Foreign.yml +++ b/docs/styles/Microsoft/Foreign.yml @@ -9,4 +9,5 @@ action: swap: '\b(?:eg|e\.g\.)[\s,]': for example '\b(?:ie|i\.e\.)[\s,]': that is - + '\b(?:viz\.)[\s,]': namely + '\b(?:ergo)[\s,]': therefore diff --git a/docs/styles/Microsoft/Plurals.yml b/docs/styles/Microsoft/Plurals.yml new file mode 100644 index 00000000..1bb6660a --- /dev/null +++ b/docs/styles/Microsoft/Plurals.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Don't add '%s' to a singular noun. Use plural instead." +ignorecase: true +level: error +link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/s/s-es +raw: + - '\(s\)|\(es\)' diff --git a/docs/styles/Microsoft/Terms.yml b/docs/styles/Microsoft/Terms.yml index e41ff74b..7708900e 100644 --- a/docs/styles/Microsoft/Terms.yml +++ b/docs/styles/Microsoft/Terms.yml @@ -1,5 +1,7 @@ extends: substitution message: "Prefer '%s' over '%s'." +# term preference should be based on microsoft style guide, such as +link: https://learn.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/a/adapter level: warning ignorecase: true action: @@ -24,10 +26,8 @@ swap: anti-spyware: antispyware anti-virus: antivirus appendixes: appendices - artificial intelligence: artificial intelligence - assembler: assembly language - bpp: bpp - bps: bps + artificial intelligence: AI + '(?:assembler|machine language)': assembly language caap: CaaP conversation-as-a-platform: conversation as a platform eb: EB @@ -39,5 +39,3 @@ swap: pb: PB tb: TB zb: ZB - viz: namely - ergo: therefore diff --git a/docs/styles/Vocab/edgeless/accept.txt b/docs/styles/config/vocabularies/edgeless/accept.txt similarity index 61% rename from docs/styles/Vocab/edgeless/accept.txt rename to docs/styles/config/vocabularies/edgeless/accept.txt index 7b24cf00..6d9e4322 100644 --- a/docs/styles/Vocab/edgeless/accept.txt +++ b/docs/styles/config/vocabularies/edgeless/accept.txt @@ -1,20 +1,14 @@ Alibaba attestable cgo -[Cc]loud +cloud collateral -debuggable dereference env -libc MarbleRun -marblerun +OCALL SignerID -signerid -syscall -tmpfs uncomment UniqueID -uniqueid untrusted Wasmer diff --git a/ego/ego/cmd/marblerun.go b/ego/ego/cmd/marblerun.go index fb2622f2..1f7920cf 100644 --- a/ego/ego/cmd/marblerun.go +++ b/ego/ego/cmd/marblerun.go @@ -18,7 +18,7 @@ func newMarblerunCmd() *cobra.Command { Short: "Run a signed executable as a MarbleRun Marble", Long: `Run a signed executable as a MarbleRun Marble. Requires a running MarbleRun Coordinator instance. -Environment variables are only readable from within the enclave if they start with "EDG_" and +Environment variables are only readable from within the enclave if they start with ` + "`EDG_`" + ` and will be extended/overwritten with the ones specified in the manifest. Requires the following configuration environment variables: