Updating documentation to reflect the possibility of multiple platfor…

…m implementations

QUICKSTART.md

@@ -17,18 +17,19 @@ Whether new to the project or just wanting to quickly get an environment up and
 
 Unless otherwise stated, only x86 platforms are supported for building this project and running the tools provided. The only exception is the [TCPSigner bundle](./utils/tcpsigner-bundle/README.md), which can be built and ran in x86 and arm64 platforms.
 
-
 ## Common tasks
 
 - Run tests:
 ```
 ~/repo> middleware/test-all # Middleware unit tests
-~/repo> firmware/test/test-all # Ledger signer application tests
-~/repo/firmware/src/ledger/signer/test/*> make test # Run ledger signer application unit tests
-~/repo/firmware/src/common/test/*> make test # Run ledger common libraries unit tests
+~/repo> firmware/test/test-all # Firmware tests
+~/repo> firmware/src/ledger/ui/test/run-all.sh # Ledger UI 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
 ```
 
-- Build firmware binaries:
+- 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
@@ -43,3 +44,8 @@ Unless otherwise stated, only x86 platforms are supported for building this proj
 ```
 ~/repo> ./build-dist <destination path> <checkpoint> <minimum difficulty> <network> <ui_iteration> <ui_authorizers>
 ```
+
+- Build the TCPSigner:
+```
+~/repo> firmware/build/build-tcpsigner
+```

README.md

@@ -28,7 +28,7 @@ Unless otherwise stated, only x86 platforms are supported for building this proj
 
 ## 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 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 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.
 
 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.
 
@@ -48,7 +48,7 @@ Refer to the following documents for details on specifics:
 - [Blockchain bookkeeping documentation](./docs/blockchain-bookkeeping.md)
 - [Attestation documentation](./docs/attestation.md)
 - [Heartbeat documentation](./docs/heartbeat.md)
-- [Ledger apps](./firmware/README.md)
+- [Firmware](./firmware/README.md)
 - [Middleware](./middleware/README.md)
 - [Distribution](./dist/README.md)
 

dist/README.md

@@ -1,6 +1,6 @@
 # powHSM distribution
 
-This document describes the artifacts provided to build a distributable version of the powHSM software. This distributable version includes both ledger apps and middleware binaries, as well as scripts for both setting up and onboarding a brand new Ledger Nano S; and also for upgrading an existing Ledger Nano S with powHSM to a newer Signer version.
+This document describes the artifacts provided to build a distributable version of the powHSM software for Ledger Nano S. This distributable version includes both Ledger apps and middleware binaries, as well as scripts for both setting up and onboarding a brand new Ledger Nano S; and also for upgrading an existing Ledger Nano S with powHSM to a newer Signer version.
 
 ## Prerequisites
 
@@ -14,7 +14,7 @@ To generate a full distribution into a fresh directory, issue:
 ~/repo> ./build-dist <destination path> <checkpoint> <minimum difficulty> <network> <ui_iteration> <ui_authorizers>
 ```
 
-where `<destination path>` is the target directory (which must not exist); `<checkpoint>`, `<minimum difficulty>` and `<network>` are the build parameters for the signer app; `<ui_iteration>` is the signer version iteration with which the UI must be built; and `<ui_authorizers>` is the basename of the authorizers header file. The script will build the ledger apps (signer and UI) as well as the required middleware. Then it will output all of the necessary distribution artifacts, including the aforementioned builds, to the destination path given.
+where `<destination path>` is the target directory (which must not exist); `<checkpoint>`, `<minimum difficulty>` and `<network>` are the build parameters for the signer app; `<ui_iteration>` is the signer version iteration with which the UI must be built; and `<ui_authorizers>` is the basename of the authorizers header file. The script will build the Ledger apps (signer and UI) as well as the required middleware. Then it will output all of the necessary distribution artifacts, including the aforementioned builds, to the destination path given.
 
 For example, to build a distribution with checkpoint `0x00f06dcff26ec8b4d373fbd53ee770e9348d9bd6a247ad4c86e82ceb3c2130ac`, minimum cumulative difficulty of `0x7c50933098`, `testnet` network, signer iteration `43` and authorizers header file `testing`, issue:
 

docs/blockchain-bookkeeping.md

@@ -63,7 +63,7 @@ In order to update the `blockchain_state` of an *initialized* powHSM device, we
 
 #### Context and preliminaries
 
-The following constants are assumed to be predefined (and hardcoded into the physical device's firmware):
+The following constants are assumed to be predefined (and hardcoded into the device's firmware):
 
 - `MINIMUM_CUMULATIVE_DIFFICULTY`: The minimum cumulative block difficulty to consider a block sufficiently confirmed.
 - `MAXIMUM_BLOCK_DIFFICULTY`: The maximum allowed difficulty for any given block.

docs/heartbeat.md

@@ -7,11 +7,11 @@ acknowledge the state of a running powHSM installation.
 
 ## Heartbeat and attestation
 
-Just like the attestation process, the heartbeat feature makes use of the Ledger Nano S
-endorsement mechanism to prove to the end user a given state of the device and its running
-applications. Nevertheless, and as opposed to the attestation process, the heartbeat
-feature itself does not include the chain of certification all the way up to the
-manufacturer (Ledger itself), but rather leverages the previously generated attestation
+Just like the attestation process, the heartbeat feature makes use of the Hardware
+Abstraction Layer's endorsement mechanism to prove to the end user a given state of the
+device and its running applications. Nevertheless, and as opposed to the attestation
+process, the heartbeat feature itself does not include the chain of certification all the
+way up to the manufacturer, but rather leverages the previously generated attestation
 process artifacts for this purpose. For more details about this and the attestation
 process, see [the attestation documentation](./attestation.md).
 

docs/signer-authorization.md

@@ -2,23 +2,23 @@
 
 ## Abstract
 
-This document describes the mechanisms by which the UI component authorizes versions of
-the Signer component to run on a device. It is an improvement to the authorization scheme
-present up to version 2.3 in that it introduces an "N of M" signatures requirement for the
-authorization of any given Signer version, enhancing security and decentralization of the
-powHSM solution as a whole. It is also an improvement over the "downgrade prevention"
-mechanism (also present up to version 2.3), in that it removes the limit present in the
-feature up to then.
+This document describes the mechanisms by which the Ledger Nano S UI application
+authorizes versions of the Signer application to run on an onboarded device. It is an
+improvement to the authorization scheme present up to version 2.3 in that it introduces an
+"N of M" signatures requirement for the authorization of any given Signer version,
+enhancing security and decentralization of the powHSM solution as a whole. It is also an
+improvement over the "downgrade prevention" mechanism (also present up to version 2.3), in
+that it removes the limit present in the feature up to then.
 
 ## Motivation
 
 Up to version 2.3 of the UI, each new version of the Signer component is authorized using
 the Ledger Nano S's custom certificate authority (CCA for short), represented by a unique
 ECDSA pair. If lost or stolen, there would be a need to generate a new pair, reset the
-existing devices and update the RSK federation in order to issue new Signer versions.
+existing devices and update the RSK PowPeg in order to issue new Signer versions.
 Moreover, the downgrade prevention mechanism, which is based on a finite blacklist of
 previous signer versions, rolls over after 100 versions, which also implies the need to
-reset existing devices, the CCA and update the RSK federation in order to clear said list
+reset existing devices, the CCA and update the RSK PowPeg in order to clear said list
 and move past the 100 signer version mark. Even though at the time of writing the 100
 signer version mark is very far away, it would eventually become an issue.
 
@@ -36,7 +36,7 @@ has no real use beyond the device setup, a scenario where the user tampers with
 process and uses a CCA of his choosing would have no real impact on the device's security.
 The UI and Signer are still protected from counterfeiting by the [attestation
 process](./attestation.md), which is the ultimate source of truth when it comes to
-determining RSK's federation members.
+determining RSK's PowPeg members.
 
 ## Implementation
 
@@ -92,7 +92,7 @@ of:
 
 ### Considerations
 
-It is important to mention that, when distributing UI and Signer for a new federation
+It is important to mention that, when distributing UI and Signer for a new PowPeg
 member, the UI should be built with the `authorized_signer_iteration` corresponding to the
 current Signer version, preventing the installation of older Signers using old
 authorization witnesses.

firmware/README.md

@@ -1,15 +1,26 @@
-# powHSM Ledger Nano S apps
+# powHSM Firmware
+
+## 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:
+
+- `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.
+- `powhsm`: contains the powHSM logic.
+- `ledger`: contains the Ledger Nano S apps.
+- `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).
+
+## powHSM for Ledger Nano S
+
+### Apps
 
 There are two ledger apps, both of them targeted for running on a Ledger Nano S with a 1.3.1 firmware.
 
 - UI: this is the modified 1.3.1 UI with a nonblocking behavior to allow the device to run uninterruptedly without human interaction. It is essentially the RSK version of the Ledger Nano S User Interface which can be loaded as a specific application - it can be used to personalize most generic parts of the user experience. This version also modifies the onboarding process to reflect RSK needs. Modified UIs display a warning at boot time to let you know whether you're running a certified version. This application shall be installed in Recovery mode. Find the source code under `firmware/src/ledger/ui`.
 
 - Signer: this is the main app that implements the signing and authorization logic for powHSM. It is intended to be used alongside the UI. Find the source code under `firmware/src/powhsm`.
 
-
-There exists also an x86 implementation of the _Signer_ component, which we call TCPSigner, that we use 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 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.
-
-## Prerequisites
+### Prerequisites
 
 Before starting, you must have the following installed on your system:
 
@@ -29,12 +40,17 @@ and
 
 that should build (or rebuild in case any of the `Dockerfile`s have changed) the corresponding docker images.
 
-## Common tasks and documentation
+### Common tasks and documentation
 
 Refer to [firmware/build/README.md](./build/README.md) for instructions on building and to [firmware/deploy/README.md](./deploy/README.md) for instructions on deploying.
 
 See [Ledger's documentation](http://ledger.readthedocs.io) to get a reference on developing for the 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
 
 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:

firmware/build/README.md

@@ -1,8 +1,11 @@
-# Ledger app building
+# powHSM building
 
-The Docker image for ledger builds (see [the ledger readme](../README.md)) provides a environment suitable to build Ledger Nano S applications on 1.3.1 firmware. This way new developers don't have to struggle setting up the build toolchain, and all of them will have exactly the same toolchain (no different compiler versions and related nuisances). Overall, we have an infrastructure enabling repeatable and bytewise reproducible builds.
+## Building the Ledger Nano S apps
 
-### Building signer and UI
+The following instructions indicate how to build both the Signer and UI applications for
+Ledger Nano S. The Docker image for ledger builds (see [the ledger readme](../README.md)) provides an environment suitable to build Ledger Nano S applications on 1.3.1 firmware. This way new developers don't have to struggle setting up the build toolchain, and all of them will have exactly the same toolchain (no different compiler versions and related nuisances). Overall, we have an infrastructure enabling repeatable and bytewise reproducible builds. This image must be built beforehand.
+
+### Building the UI
 
 To build the UI, just issue:
 
@@ -18,6 +21,8 @@ There is also a *debug* version of the UI, which disables disallowing PINs with
 ~/repo> firmware/build/build-ledger-ui-debug <signer_hash> <signer_iteration> <signers_file>
 ```
 
+### Building the Signer
+
 To build the signer, just issue:
 
 ```bash
@@ -34,11 +39,13 @@ For example, to build the signer with checkpoint `0x00f06dcff26ec8b4d373fbd53ee7
 
 Once the build is complete, you will get the hash of the build as output, and the actual build output will be in `<HSM_PROJECT_ROOT>/firmware/src/ledger/signer/bin/app.hex` (for the signer) and `<HSM_PROJECT_ROOT>/firmware/src/ledger/ui/bin/token.hex` (for the UI).
 
-#### Reproducible builds
+### Reproducible builds
 
 It is *very important* to mention that both the Signer and the UI builds are bitwise reproducible. That is, two independent builds of the same code will yield the exact same hex files (and thus, the same app hashes). This is of remarkable importance for the [attestation process](../../docs/attestation.md).
 
-### Building the TCPSigner
+## Building the TCPSigner
+
+The Docker image for the middleware (see [the middleware readme](../../middleware/README.md)) provides a suitable environment to build, run and test the TCPSigner. This image must be built beforehand. To then build the TCPSigner, just issue:
 
 ```bash
 ~/repo> firmware/build/build-tcpsigner

firmware/deploy/README.md

@@ -1,4 +1,4 @@
-# Ledger app deployment
+# powHSM Ledger Nano S app deployment
 
 The Docker image for middleware (see [the middleware readme](../../middleware/README.md)) provides an environment suitable to deploy Ledger Nano S applications on a Ledger Nano S device. This way new developers don't have to struggle setting up the deployment toolchain.
 

firmware/fuzz/README.md

@@ -6,7 +6,7 @@ is geared towards (AFL++)[https://github.com/aflplusplus].
 Most of the scripts here require a working `hsm:afl` Docker image which you
 can build using the `~/repo/docker/afl/build` script.
 
-# Building a fuzzable TCPSinger 
+## Building a fuzzable TCPSigner
 
 You can build the TCPSigner with the AFL++ compilers with the 
 `~/repo/firmware/build/build-tcpsigner-afl` script, which uses the 
@@ -22,16 +22,17 @@ The `fuzz` script takes three optional parameters:
 
 And runs a primary fuzzer, coverage and `cores - 1` secondary fuzzers.
 
-The script uses the `env` file to read some `tcpsinger` arguments. See the 
+The script uses the `env` file to read some `tcpsigner` arguments. See the
 `Modifying run parameters` title on this doc.
 
-# Coverage build
+## Coverage build
+
 The `coverage-build` parameter is an unfortunate technicality. Coverage needs
 a copy of the source files, and we must put it somewhere. The default is `./.coverage-build`.
 You can mostly ignore this folder. But whatever you specify as the coverage build folder
 **will get deleted** by the script, so be careful.
 
-# Generating testcases
+## Generating testcases
 
 You can run `./generate-testcases` to generate the testcases,
 make them unique and minimize them. This is recommended but takes
@@ -45,7 +46,7 @@ If you want to run only some steps of the process, you can run the
 helper scripts `extract-inputs-from-tests`, `unique-testcases` and 
 `min-testcases` one by one.
 
-# Creating new entries in the dictionary
+## Creating new entries in the dictionary
 
 The `./fuzz` script will read from the dictionary at `./dict/`. To easily add 
 entries to the dictionary, you can use the helper python script `hex_to_dict.py` like this:
@@ -54,6 +55,7 @@ entries to the dictionary, you can use the helper python script `hex_to_dict.py`
 python3 hex_to_dict.py <hex data, no 0x prefix> <name>
 ```
 
-# Modifying run parameters
+## Modifying run parameters
+
 The `~/repo/firmware/fuzz/env` file specifies the difficulty, network and checkpoint to be
 used both by the fuzzer and the coverage script.

firmware/test/README.md

@@ -1,6 +1,6 @@
-# Ledger signer firmware test suite
+# powHSM firmware test suite
 
-## Build parameters for a physical dongle
+## Build parameters for a physical Ledger Nano S
 
 *Checkpoint:* 0xbdcb3c17c7aee714cec8ad900341bfd987b452280220dcbd6e7191f67ea4209b
 *Difficulty:* 0x32 (50)