Merge pull request #18 from keystone-enclave/docswork

Documentation Update

.readthedocs.yml

@@ -1,3 +1,2 @@
-submodules:
-  include: []
-  recursive: false
+version: 2
+

docs/.gitignore

@@ -1,2 +1,3 @@
+.*.swp
 build/
 !.PLACEHOLDER

docs/source/Contributing-to-Keystone/How-to-Contribute.rst

@@ -1,24 +1,31 @@
 How to Contribute
-=================
+================================
 
 Keystone is, and will be, fully open source. We hope to see many
-projects both under the Keystone name, and built on-top of it.
+projects both under the Keystone unbrella, and built on-top of it.
 
 We welcome contributions at all levels, from platform specific
-bootloader modifications, to improved compilers and toolchains, to
+bootloader modifications, to make compilers and toolchains for programming enclaves, to
 support for novel use-cases for end users.
 
+
+Knwon Issues and Ongoing Projects
+--------------------------------
+
+Known issues are updated in `github issues <https://github.com/keystone-enclave/keystone/issues>`_.
+We also post ongoing projects on `github projects <https://github.com/keystone-enclave/keystone/projects>`_.
+If you have any issues or project ideas, please post it to the github issue page.
+
 Platform Specific Builds/Changes
 --------------------------------
 
 Many SoCs and boards will require some amount of custom support for
-Keystone to function fully. If you are interested in ensuring Keystone
+Keystone to fully function. If you are interested in ensuring Keystone
 operates correctly on your target there are several requirements:
 
- - PMP support
- - RISCV priv-1.10 ISA support
+ - RISC-V priv-1.10 ISA support (including PMP)
  - Entropy sources
- - >=3-run level support (U/S/M)
+ - 3 privilege level support (U/S/M)
 
 Where possible, changes that allow Keystone to operate on another
 platform should be cross-platform themselves, to avoid fragmentation.
@@ -27,7 +34,7 @@ See also the list of known areas to work on, we need better platform
 specific builds!
 
 General Contributions
----------------------
+--------------------------------
 
-Submit pull-requests, with a good explanation, and following the
-coding guidelines.
+Fork ``keystone`` repo to your own account, mess around, and submit a pull request (PR) to the remote ``develop`` branch.
+A PR must be separated if it contains multiple patches for different parts.

docs/source/Getting-Started/How-Keystone-Works/Keystone-Security-Monitor.rst

@@ -0,0 +1,161 @@
+Keystone Security Monitor
+====================================
+
+The security monitor (SM) is trusted software that runs in M-mode, and forms the trusted computing
+base (TCB) in Keystone system.
+The SM is the most important software in Keystone as it provides most of the security guarantees.
+The SM provides the following functionality:
+
+1. Memory Isolation using RISC-V PMP
+2. Remote Attestation (Signatures and measurement)
+3. Enclave Thread Management
+4. System PMP Synchronization
+5. Side-Channel Defenses
+
+.. attention::
+
+  Version 0.1 only implements 1, 2, and 3, supporting single-threaded enclave.
+
+The security monitor must be verified by the *root of trust* in hardware before being trusted.
+After the root of trust measures the SM it generates a keypair for remote attestation, signs the public key, and then continues booting.
+See `Chain of Trust <#>`_ for details.
+
+The OS and enclaves may call SM functions using the supervisor binary interface (SBI),
+which is implemented in RISC-V environment calls (i.e., ``ecall`` instruction).
+See `SBI Documentation <#>`_ for details.
+
+PMP Internals
+-------------
+
+PMP allows for N (platform defined) entries, which are configured
+using a config (cfg) and address (addr) register each. There are
+further details available in the RISC-V `specification
+<https://content.riscv.org/wp-content/uploads/2017/05/riscv-privileged-v1.10.pdf>`_
+section 3.6.
+
+In Keystone we refer to the section of memory that an enclave uses as
+a *region* and each region is defined by a PMP entry.
+
+Memory Isolation using RISC-V PMP
+-------------------------------------
+
+The SM currently consumes *two* PMP entries for its own uses (i.e., security monitor memory and untrusted memory).
+Each of the remaining PMP entries may be consumed by one active enclave each.
+
+To understand how the SM utilizes PMP, we need to know several properties of RISC-V PMP:
+
+1. **Prioritized by Index**
+
+	PMP entries are statically priortized by their index, with a check stopping at the highest priority matching.
+        Indices run from 0..N (where N is platform defined), with 0 having the highest priority, and N having the lowest.
+	Thus, the access permissions to a physical address should be of the lowest-index PMP entry among the matched ones.
+
+2. **Default Deny**
+
+	If no PMP entry matches with an address, the memory access will be rejected by default.
+
+3. **Dynamically Configurable by M-mode**
+
+	M-mode can write to PMP CSRs during runtime to define PMP entries dynamically.
+	A TLB flush is required after reconfiguration.
+
+4. **Addressing Modes**
+
+	PMP supports two addressing modes: naturally-aligned power of two (NAPOT), or top-of-range (TOR).
+	TOR consumes adjacent PMP entry's address register for the bound address to allow shared boundaries efficiently.
+        Ex: Two ranges of 0-2048 and 2048-4096 uses 3 entries, 0, 2048, 4096.
+
+.. note::
+
+  The current Keystone SM uses NAPOT (> 4KB), because it relies on Linux memory allocation for contiguous physical memory regions, and these regions are not guaranteed to be contiguous with each other.
+
+At the very beginning of the boot process, physical memory is not accessible by U- or S-modes
+because of property 2 as shown in the diagram below.
+
+.. code-block:: text
+
+  For ease of understanding, we denote PMP entries as pmp[i] where i is an index.
+  There are N PMP entries.
+
+  -: inaccessible (NO_PERM), =: accessible (ALL_PERM)
+
+  pmp[1:N]     |                                        | : undefined
+  net result   |----------------------------------------|
+
+The SM sets the first PMP entry to cover the address range containing itself (``0x80000000``-``0x80200000``), and sets all permission bits to 0.
+The SM then sets the last PMP entry to cover the entire DRAM and sets all permission bits to 1, allowing the OS to access the rest of the memory and start booting.
+Because of the property 1, the net result will be as follows:
+
+.. code-block:: text
+
+  -: inaccessible (NO_PERM), =: accessible (ALL_PERM)
+
+  pmp[0]       |-------|                                | : SM memory
+  pmp[others]  |                                        | : undefined
+  pmp[N]       |========================================| : OS memory
+  net result   |-------|================================|
+
+When the SM creates an enclave, it will assign a PMP entry to the enclave to protect its memory from other U-/S-mode software.
+
+.. code-block:: text
+
+  -: inaccessible (NO_PERM), =: accessible (ALL_PERM)
+
+  pmp[0]       |-------|                                | : SM memory
+  pmp[1]       |              |---------|               | : enclave memory
+  pmp[others]  |                                        | : undefined
+  pmp[N]       |========================================| : OS memory
+  net result   |-------|======|---------|===============|
+
+When the SM enters the enclave (executes the enclave), it flips the permission bits of the enclave's PMP entry and the last PMP entry.
+In addition, Keystone allows the OS to allocate an additional contiguous memory region in the OS memory space so that the enclave can use it as a communication buffer.
+The buffer is called untrusted shared buffer.
+
+.. code-block:: text
+
+  -: inaccessible (NO_PERM), =: accessible (ALL_PERM)
+
+  pmp[0]       |-------|                                | : SM memory
+  pmp[1]       |              |=========|               | : enclave memory
+  pmp[others]  |                                        | : undefined
+  pmp[N]       |                                |==|    | : untrusted shared buffer
+  net result   |-------|------|=========|-------|==|----|
+
+When the SM exits the enclave, it simply flips the permission bits back.
+When the SM destroys an enclave, it clears the PMP entry so that other enclaves can use it.
+
+
+Remote Attestation
+-------------------------------------
+
+The goal of remote attestation is to prove to a remote client that the enclave contains the program expected, and is running on hardware that is trusted.
+In Keystone this involves a few cryptographic operations including ECDSA signature and SHA-3 hash.
+
+For more detail about the remote attestation process, see :doc:`Remote Attestation </Keystone-Applications/Attestation>`.
+
+Enclave Context Management
+-------------------------------------
+
+The Keystone SM manages enclave context (e.g., general purpose registers, trap vector, etc) and the status of each hardware thread.
+When an enclave enters and exits, the SM performs the following steps to switch between trusted and untrusted contexts:
+
+#. Update thread status
+#. Save the previous context
+#. Restore the next context
+#. Flip PMP permissions
+#. Flush TLB
+
+System PMP Synchronization
+-------------------------------------
+
+.. note::
+
+  System PMP is not supported yet.
+
+Side-Channel Defense
+-------------------------------------
+
+.. note::
+
+  Side-channel defenses are not implemented yet.
+  Note that there are many different side-channels, and each platform will have its own threat model for side-channels.

docs/source/Getting-Started/How-Keystone-Works/Platform-Integration.rst

@@ -0,0 +1,2 @@
+Hardware Requirement and Platform Integration
+==============================================

docs/source/Getting-Started/How-Keystone-Works/RISC-V-Background.rst

@@ -0,0 +1,124 @@
+RISC-V Background
+===================================
+
+Keystone Enclave is an enclave for RISC-V processors.
+`RISC-V <https://riscv.org>`_ is an open and free instruction set architecture (ISA), which allows anyone to use, modify, and extend.
+
+RISC-V presents us with a number of benefits besides just being open-source:
+
+* RISC-V has added security-oriented primitives (notably Physical Memory Protection) that enable efficient isolation.
+
+* RISC-V is an evolving and community driven ISA. Keystone can explore the design space of useful 
+  security features, and feed good ideas back into the standards themselves.
+
+* RISC-V has a constantly expanding world of open-source cores and products. This gives Keystone a
+  wide variety of potential platforms and uses it can adapt to.
+
+In addition, RISC-V software privilege specification fits well for Keystone, which requires transparent and agile patch on the trusted computing base (TCB).
+To understand why this is true, see the next section explaining why using M-mode as a TCB is a great idea.
+
+.. note::
+
+  Keystone is based on the lastest stable ISA specification at the time of writing (User 2.2 and Priv. 1.10).
+  This document only contains high-level ideas of several components in the privileged ISA.
+  For more details, please refer to `RISC-V Spec Documentations <https://riscv.org/specifications/>`_.
+
+RISC-V Privilieged ISA
+-----------------------------------
+
+RISC-V has three software privilege levels (in increasing order of capability): user-mode (U-mode), supervisor mode (S-mode), and machine mode (M-mode).
+The processor can run in only one of the privilege modes at a time.
+
+.. note::
+
+  RISC-V also defines hypervisor priviliege mode (H-mode), but the spec of H-mode is not included in the stable revision (RISC-V Priv. v1.10).
+
+Privilege level defines what the running software can do during its execution.
+Common usage of each privilege level is as follows:
+
+* U-mode: user processes
+* S-mode: kernel (including kernel modules and device drivers), hypervisor
+* M-mode: bootloader, firmware
+
+
+Only M-mode is required, and some embedded devices may have only M-mode or only M/U modes.
+
+M-mode is the highest privilege mode and controls all physical resources and events.
+M-mode is somewhat similar to microcode in complex instruction set computer (CISC) ISAs such as x86,
+in that it is not interruptible and free from interference of lower modes.
+
+Keystone uses M-mode for running the *security monitor (SM)*, the trusted computing base (TCB) of the system.
+
+There are several benefits for using an M-mode software as the TCB:
+
+**Programmability**:
+Unlike microcode, we can build M-mode software in existing programming languages (i.e., C) and toolchains (i.e., gcc).
+
+**Agile Patching**:
+Since the SM is entirely software, it is possible to patch bugs or vulnerabilities without involving hardware-specific updates.
+
+**Verifiability**:
+In general, software is easier to formally verify then hardware.
+
+Physical Memory Protection (PMP)
+-----------------------------------
+
+The RISC-V Priv 1.10 standard introduced Physical memory protection
+(PMP): a strong standard primitive that allows M-mode to control
+physical memory access from lower privileges (U-/S-modes). Keystone
+requires PMP to implement memory isolation of enclaves.
+
+PMP is controlled by a set of control and status registers (CSR) to
+restrict physical memory access to the U-mode and S-mode, and can only
+be configured by M-mode. The number of PMP entries varies depending on
+the platform design. For example, RocketChip has 8 PMP entries per
+core by default, where QEMU virt machine has 16 entries. Each PMP
+entry is defined by 1 or more PMP CSRs depending on the configuration
+mode.
+
+As PMP operates on physical addresses, the configuration of virtual
+addresses can remain a capability of S-mode without compromising
+security. While the actual hardware implementation of PMP may vary
+among processors, the basic guarantees are part of the standard.
+
+
+:doc:`Keystone-Security-Monitor` relies on PMP for implementing memory isolation.
+
+Interrupts and Exceptions
+----------------------------------
+
+
+By default, M-mode is the first receiver of any interrupts or
+exceptions (i.e., traps) in the system.  Thus, M-mode has complete
+authority over CPU scheduling and configuration, but may delegate this
+control as needed to S-mode.
+
+Optionally, M-mode can disable or enable each of the interrupts by using ``mie`` CSR.
+M-mode can also delegate traps to S-mode by setting bits of the trap delegation registers (i.e., ``mideleg``
+and ``medeleg``).
+Trap delegation enables skipping M-mode handler so that S-mode can quickly handle frequent traps
+such as page faults, system calls (environment call), and so on.
+
+Virtual Address Translation
+----------------------------------
+
+U- and S-modes accesses memory via virtual addresses, while M-mode operates exclusively on physical addresses.
+
+Virtual address translation in RISC-V is performed by a memory
+management unit (MMU) consisting of two hardware components: a page
+table walker (PTW) and a translation look-aside buffer (TLB).
+RISC-V uses multi-level page table, where number of pages and the size of a page depends on the
+addressing mode.
+The ``satp`` CSR determines which addressing mode MMU should use and which physical page contains the
+root page table for beginning page table walks.
+
+.. attention::
+
+  Keystone currently only supports RV64 with Sv39 addressing mode, which translates 39-bit virtual addresses into
+  50-bit physical addresses based on a 3-level page table.
+
+Although S-mode (the OS) may change ``satp`` arbitrarily, Keystone
+enclaves are not susceptible to any attacks based on altering the page
+table.  Enclaves are protected from external access by the OS with
+physical address restrictions via PMP, and have their own protected
+page tables that cannot be modified by the OS.

docs/source/Getting-Started/How-Keystone-Works/Runtime-And-SDK.rst

@@ -0,0 +1,4 @@
+Keystone Runtime
+===================================
+
+`Keystone Runtime <https://github.com/keystone-enclave/keystone-runtime>`_ is a part of enclave that runs in S-mode.

docs/source/Getting-Started/How-Keystone-Works/index.rst

@@ -0,0 +1,10 @@
+How Keystone Works
+=========================================
+
+.. toctree::
+   :maxdepth: 2
+
+   RISC-V-Background
+   Keystone-Security-Monitor
+   Platform-Integration
+   Runtime-And-SDK