Added SGX documentation (#205)

QUICKSTART.md

@@ -10,6 +10,7 @@ Whether new to the project or just wanting to quickly get an environment up and
 ```
 ~/repo> docker/mware/build # Middleware image
 ~/repo> docker/ledger/build # Ledger image
+~/repo> docker/sgx/build # SGX image
 ~/repo> docker/packer/build # Middleware binary packer image
 ```
 
@@ -27,26 +28,42 @@ Unless otherwise stated, only x86 platforms are supported for building this proj
 ~/repo> firmware/src/ledger/signer/test/run-all.sh # Ledger Signer application unit tests
 ~/repo> firmware/src/common/test/run-all.sh # Common code unit tests
 ~/repo> firmware/src/powhsm/test/run-all.sh # powHSM logic unit tests
-~/repo> firmware/src/hal/test/run-all.sh # HAL unit tests
+~/repo> firmware/src/hal/common/test/run-all.sh # HAL common code unit tests
+~/repo> firmware/src/hal/x86/test/run-all.sh # HAL x86 implementation unit tests
 ```
 
 - Build Ledger Nano S application binaries:
 ```
-~/repo> firmware/build/build-signer <checkpoint> <difficulty> <network> # Build signer
-~/repo> firmware/build/build-ui <signer_hash> <signer_iteration> <signers_file> # Build UI
+~/repo> firmware/build/build-ledger-signer <checkpoint> <difficulty> <network> # Build signer
+~/repo> firmware/build/build-ledger-ui <signer_hash> <signer_iteration> <signers_file> # Build UI
+```
+
+- Build SGX binaries (both host and enclave):
+```
+~/repo> firmware/build/build-sgx <checkpoint> <difficulty> <network>
 ```
 
 - Build middleware binaries:
 ```
 ~/repo> middleware/build/all
 ```
 
-- Build a complete powHSM distribution:
+- Build a complete Ledger powHSM distribution:
 ```
-~/repo> ./build-dist <destination path> <checkpoint> <minimum difficulty> <network> <ui_iteration> <ui_authorizers>
+~/repo> ./build-dist-ledger <destination path> <checkpoint> <minimum difficulty> <network> <ui_iteration> <ui_authorizers>
+```
+
+- Build a complete SGX powHSM distribution:
+```
+~/repo> ./build-dist-sgx <destination path> <checkpoint> <minimum difficulty> <network>
 ```
 
 - Build the TCPSigner:
 ```
 ~/repo> firmware/build/build-tcpsigner
 ```
+
+- Build the SGX simulator:
+```
+~/repo> firmware/build/build-sgx-sim <checkpoint> <minimum difficulty> <network>
+```

README.md

@@ -12,7 +12,7 @@
 
 The RSK Powpeg protects private keys stored in special purpose PowHSMs based on tamper-proof secure elements (SE). The PowHSM runs an RSK node in SPV mode, and signatures can only be commanded by chain cumulative proof of work.
 
-This repository hosts the powHSM firmware. The stable versions are the tags published in the [releases tab](https://github.com/rsksmart/rsk-powhsm/releases).
+This repository hosts the powHSM firmware and middleware.  The stable versions are the tags published in the [releases tab](https://github.com/rsksmart/rsk-powhsm/releases).
 
 ## Notation
 
@@ -22,23 +22,30 @@ Throughout the repository READMEs, the prompt `~/repo>` is used to denote a `bas
 
 Refer to our [quickstart guide](./QUICKSTART.md) to learn about environment setup and common tasks without further ado.
 
+## Firmware platforms
+
+PowHSM can run both on Ledger Nano S devices and Intel SGX servers. At any given time, a PowPeg can be composed of a mix of members running PowHSM on either platform. The decision of which platform to run on each member is ultimately up to the member itself and the Rootstock network maintainers.
+
 ## Supported platforms
 
 Unless otherwise stated, only x86 platforms are supported for building this project and running the tools provided. It is possible, however, to build and run the [TCPSigner bundle](./utils/tcpsigner-bundle/README.md) on arm64 platforms. This is provided for development and testing purposes.
 
 ## Concepts overview
 
-powHSM is a solution designed specifically for the [RSK network](https://www.rsk.co/) powPeg. Its main role is to safekeep and prevent the unauthorized usage of each of the powPeg's members' private keys. powHSM is currently implemented as a pair of applications for the [Ledger Nano S](https://shop.ledger.com/products/ledger-nano-s), namely a UI and a Signer, and it strongly depends on the device's security features to implement the aforementioned safekeeping.
+powHSM is a solution designed specifically for the [RSK network](https://www.rsk.co/) powPeg. Its main role is to safekeep and prevent the unauthorized usage of each of the powPeg's members' private keys. powHSM has currenty got two implementations that target two different platforms.
+
+1. The first implementation consists of a pair of applications for the [Ledger Nano S](https://shop.ledger.com/products/ledger-nano-s), namely a UI and a Signer, and it strongly depends on the device's security features to implement the aforementioned safekeeping. This implementation requires a physical Ledger Nano S device and a self-managed physical standalone server.
+2. The second implementation consists of both a host and an enclave binary targetting the Intel SGX architecture. Just as the Ledger Nano S implementation, it strongly depends on the Intel SGX security features in order to keep the private keys safe. This implementation can run both on standalone SGX-enabled servers as well as on SGX-enabled cloud computing providers (e.g., Microsoft Azure).
 
-Each powPeg member runs an individual physical device on which a transparent installation and onboarding process is carried. Amongst other things, this process safely generates the root key, that never leaves the device. There is an [attestation process](./docs/attestation.md) that serves the purpose of testifying and guaranteeing this key generation process, and ultimately the fact that the key is only ever known to the device.
+Each powPeg member runs an individual physical device or SGX enclave on which a transparent installation and onboarding process is carried. Amongst other things, this process safely generates the root key, that either never leaves the device (Ledger) or can only ever be decrypted by the enclave (SGX). There is an [attestation process](./docs/attestation.md) that serves the purpose of testifying and guaranteeing this key generation process, and ultimately the fact that the key is only ever known to the device (attestation is currently only supported on the Ledger implementation).
 
-After onboarding, each device is physically connected to and interacts with its corresponding powPeg node by means of a middleware layer that exposes a [high-level protocol](./docs/protocol.md) for its operation.
+After onboarding, each powHSM runs either on its host (SGX) or is physically connected to it (Ledger), and interacts with its corresponding powPeg node by means of a middleware layer that exposes a [high-level protocol](./docs/protocol.md) for its operation.
 
-The signer application running within each device enables the usage of two sets of keypairs by its owner powPeg node: an _unauthorized_ and an _authorized_ set. These keys are generated from the root key using a standard [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) derivation path (following [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)).
+The signer application running within each powHSM enables the usage of two sets of keypairs by its owner powPeg node: an _unauthorized_ and an _authorized_ set. These keys are generated from the root key using a standard [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) derivation path (following [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki)).
 
-The _unauthorized_ keyset can be used to sign arbitrary hashes, and its security scheme relies solely on the knowledge of the device's pin (akin to owning a Ledger Nano S for personal usage). This keyset is used by the powPeg members for non critical operations (e.g., signing powPeg-only transactions within the RSK network).
+The _unauthorized_ keyset can be used to sign arbitrary hashes, and its security scheme relies solely on the knowledge of the powHSM's pin (in the Ledger Nano S case, akin to owning a device for personal usage). This keyset is used by the powPeg members for non critical operations (e.g., signing powPeg-only transactions within the RSK network).
 
-The _authorized_ keyset is the main security focus of the solution. It can _only_ ever be used to sign BTC transactions that correspond to pegOuts within the RSK network, i.e., the release of Bitcoin funds held within RSK's bridge mechanism. This authorization is enforced by means of events that the [Bridge contract](https://explorer.rsk.co/address/0x0000000000000000000000000000000001000006) emits whenever a pegOut request is generated, and that are included in RSK's blocks by means of transaction receipts, and ultimately mined and secured by actual Bitcoin miners. This implies that without a mined pegOut request with a minimum amount of hashing power on top, the device emits no signature. This powerful feature gives the project its name: _powHSM_ - Proof of Work Hardware Security Module.
+The _authorized_ keyset is the main security focus of the solution. It can _only_ ever be used to sign BTC transactions that correspond to pegOuts within the RSK network, i.e., the release of Bitcoin funds held within RSK's bridge mechanism. This authorization is enforced by means of events that the [Bridge contract](https://explorer.rsk.co/address/0x0000000000000000000000000000000001000006) emits whenever a pegOut request is generated, and that are included in RSK's blocks by means of transaction receipts, and ultimately mined and secured by actual Bitcoin miners. This implies that, without a mined pegOut request with a minimum amount of hashing power on top, the powHSM emits no signature. This powerful feature gives the project its name: _powHSM_ - Proof of Work Hardware Security Module.
 
 ## Digging deeper
 

docs/attestation.md

@@ -1,12 +1,16 @@
 # powHSM attestation
 
+## Foreword
+
+Currently, attestation is a feature supported only in the Ledger version of powHSM. An attestation implementation for the SGX version of powHSM is currently under development. Therefore, all the information contained herein must be interpreted as applying exclusively to the Ledger version of powHSM.
+
 ## Abstract
 
-This document describes the mechanisms through which a powHSM installation can prove to an end user that it is actually installed on an authentic physical Ledger device with a specific UI and Signer versions, along with its currently authorized signer version and generated public keys.
+This document describes the mechanisms through which a powHSM installation can prove to an end user that it is actually installed on an authentic physical Ledger device with specific UI and Signer versions, along with its currently authorized signer version and generated public keys.
 
 ## Preliminaries, native support and assumptions
 
-Each device currently used to run powHSM on, namely Ledger Nano S, ships with a mechanism to prove its authenticity and that also enables and leverages some basic additional support for user application attestation. For powHSM attestation we make extensive use of these mechanisms, assuming it is robust enough for our purpose.
+Each Ledger device currently used to run powHSM on, namely Ledger Nano S, ships with a mechanism to prove its authenticity and that also enables and leverages some basic additional support for user application attestation. For powHSM attestation we make extensive use of these mechanisms, assuming it is robust enough for our purpose.
 
 ## Device key and authenticity
 
@@ -174,4 +178,4 @@ Installed Signer hash: e1baa18564fc0c2c70ac4019609c6db643adbf12711c8b319f838e6a7
 ---------------------------------------------------------------------------------------
 ```
 
-and verify that the reported custom CA and UI and Signer hashes match the expected values.
+and verify that the reported UI and Signer application hashes match the expected value. Additionally, the user should check that each additional reported value corresponds with an expected or reasonable value (e.g., verify that the UD value corresponds to an RSK block header hash that was mined on or after the time of setup/update; or that in the case of an update, the public keys correspond to those of the powPeg member and have not been altered from the values obtained at setup).

docs/blockchain-bookkeeping.md

@@ -243,7 +243,7 @@ At any point in time, the only block that is considered to be included in the bl
 
 ## Implementation considerations
 
-The implementation must take into account the limited resources available on the actual hardware, and thus implement the described algorithms as a set of request-response incremental operations without compromising the integrity of the update processes. For example, to process just a single block, many request-response operations might be needed, and that would correspond to a single iteration in either of the above algorithms.
+The implementation must take into account any potential limited resources available on the actual hardware, and thus implement the described algorithms as a set of request-response incremental operations without compromising the integrity of the update processes. For example, to process just a single block, many request-response operations might be needed, and that would correspond to a single iteration in either of the above algorithms.
 
 ## Miscellaneous
 

docs/heartbeat.md

@@ -1,5 +1,9 @@
 # powHSM heartbeat
 
+## Foreword
+
+Currently, just like what happens in the case of [attestation](./attestation.md), heartbeat is a feature supported only in the Ledger version of powHSM. A heartbeat implementation for the SGX version of powHSM is currently under development. Therefore, all the information contained herein must be interpreted as applying exclusively to the Ledger version of powHSM.
+
 ## Abstract
 
 This document describes the feature known as "heartbeat", which allows an end user to

docs/protocol-v1.md

@@ -2,7 +2,7 @@
 
 ## About
 
-This document describes the legacy protocol used in version 1 of the HSM. The purpose is to provide a reference for the usage of the legacy mode in the Ledger manager and TCP manager (with modifier `--version-one`).
+This document describes the legacy protocol used in version 1 of the HSM. The purpose is to provide a reference for the usage of the legacy mode in the Ledger, SGX and TCP managers (with modifier `--version-one`).
 
 ## Definitions
 

docs/signer-authorization.md

@@ -1,5 +1,15 @@
 # powHSM signer authorization and upgrade
 
+## Foreword
+
+Signer authorization and upgrading is a feature designed exclusively for the Ledger
+version of powHSM. Therefore, all the information contained herein must be interpreted as
+applying exclusively to this implementation.
+
+The only other implementation of powHSM, written for the Intel SGX platform, has currently
+got no support for upgrading, and thus an equivalent document to describe such a process
+does not exist.
+
 ## Abstract
 
 This document describes the mechanisms by which the Ledger Nano S UI application

firmware/README.md

@@ -2,13 +2,14 @@
 
 ## Overview and source code
 
-By firmware, we collectively refer to the group of applications that comprise the main powHSM logic and its different implementations (currently and namely, powHSM for Ledger Nano S and powHSM for x86 -- codenamed TCPSigner). The source code under this document's directory is located within the `src` directory, and is organised as follows:
+By firmware, we collectively refer to the group of applications that comprise the main powHSM logic and its different implementations (currently and namely, powHSM for Ledger Nano S, powHSM for Intel SGX and powHSM for x86 -- codenamed TCPSigner). The source code under this document's directory is located within the `src` directory, and is organised as follows:
 
-- `hal`: contains header and source files for the Hardware Abstraction Layer, on top of which the powHSM logic is built. Currently implemented for Ledger Nano S and x86.
+- `hal`: contains header and source files for the Hardware Abstraction Layer, on top of which the powHSM logic is built. Currently implemented for Ledger Nano S, Intel SGX and x86.
 - `powhsm`: contains the powHSM logic.
 - `ledger`: contains the Ledger Nano S apps.
+- `sgx`: contains the Intel SGX implementation of powHSM (host and enclave).
 - `tcpsigner`: contains the x86 implementation of powHSM.
-- `common`: contains some common headers used both in powHSM and the Ledger Nano S apps (note that the Ledger UI app does not use the HAL layer).
+- `common`: contains some common headers used both in powHSM, the Ledger Nano S apps and the Intel SGX host and enclave.
 
 ## powHSM for Ledger Nano S
 
@@ -46,26 +47,39 @@ Refer to [firmware/build/README.md](./build/README.md) for instructions on build
 
 See [Ledger's documentation](http://ledger.readthedocs.io) to get a reference on developing for the platform.
 
+## powHSM for Intel SGX
 
-## powHSM for x86
+### Host and Enclave
 
-Besides the Ledger implementation, there is also an x86 based implementation of the powHSM, which we call _TCPSigner_. This is used to smoke test, fuzz (see [the fuzzing documentation](./fuzz/README.md) for details) and debug & test new features on before we jump onto testing on a physical Ledger Nano S device. With the exception of fuzzing, this component creates a TCP/IP server that serves the purpose of enabling the otherwise USB-based interactions with a given client.
+There are two parts to the Intel SGX powHSM implementation: a host and an enclave. The enclave is responsible for hosting the core powHSM business logic, as well as for managing all secrets (e.g., private keys). This enclave runs in a reserved memory area and cannot be tampered with or accessed by any other entities than itself. Its only link with the outside world is the host, with which it shares a limited, well defined, communication protocol. The host, then, is responsible for managing the enclave creation, destruction, and all its interactions with the outside world -- including, but not limited to, disk and network access. Once built, both host and enclave take the form of binaries that must be deployed together to the Intel SGX server on which they are set to run.
 
-## Tests
+### Prerequisites
+
+Before starting, you must have the following installed on your system:
+
+- Docker
 
-There are some tests written in Python that serve the purpose of smoke testing the powHSM signer when either installed and running on a Ledger Nano S or via a fresh TCPSigner build. To run them against a TCPSigner, issue:
+The first time, you must build the docker image that will serve as the SGX build environment. Issue:
 
 ```
-~/repo/firmware/test> ./test-all
+~/repo> docker/sgx/build
 ```
 
-To run them against a Ledger Nano S, issue:
+that should build (or rebuild in case any of the `Dockerfile`s have changed) the corresponding docker image.
 
-```
-~/repo/firmware/test> ./test-all dongle
-```
+### Common tasks and documentation
+
+Refer to [firmware/build/README.md](./build/README.md) for instructions on building.
+
+See [Open Enclave](https://openenclave.io/sdk/) for development documentation and reference, and [Intel SGX](https://www.intel.com/content/www/us/en/products/docs/accelerator-engines/software-guard-extensions.html) for information about the underlying platform.
+
+## powHSM for x86
+
+Besides the Ledger implementation, there is also an x86 based implementation of the powHSM, which we call _TCPSigner_. This is used to smoke test, fuzz (see [the fuzzing documentation](./fuzz/README.md) for details) and debug & test new features on before we jump onto testing on a physical Ledger Nano S device. With the exception of fuzzing, this component creates a TCP/IP server that serves the purpose of enabling the otherwise USB-based interactions with a given client.
+
+## Tests
 
-Make sure that the Ledger is unlocked and with the signer app running for the tests to run correctly.
+There is a test framework written in Python with a rather large set of tests that serve the purpose of smoke testing the main powHSM signing business logic when either installed and running on a Ledger Nano S, an Intel SGX server or via a fresh TCPSigner build. Refer to [the firmware testing documentation](./test/README.md) for details on how to run these tests on each supported platform.
 
 ## Troubleshooting