Update documentation

docs/admin_guide.md

@@ -5,6 +5,11 @@
 -   [Verify that your hardware and software can run SGX](prerequisites.md)
 -   [Enable SGX](enabling-sgx.md)
 -   [Start, stop and upgrade sgxwallet](run_in_hardware_mode.md)
+    -   [Docker Compose configuration](run_in_hardware_mode.md#docker-compose-configuration)
+    -   [Run sgxwallet in secure mode](run_in_hardware_mode.md#run-sgxwallet-in-secure-mode)
+    -   [Start, stop and upgrade sgxwallet containers](run_in_hardware_mode.md#start-stop-and-upgrade-sgxwallet-containers)
+    -   [Logging](run_in_hardware_mode.md#logging)
+-   [Backup and recover sgxwallet](backup-procedure.md)
 
 ## Community
 

docs/backup-procedure.md

+<!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->
+
+# SGXWallet Backup Procedure
+
+When SGXWallet is initialized, the server will print the backup key. 
+**This key must be securely recorded and stored.**
+
+## Backup SGXWallet
+
+1.  Stop the container:
+
+```bash
+docker-compose down
+```
+
+2.  Copy the entire `sgx_data` directory.
+
+## Recover from backup
+
+1.  Edit the `docker-compose.yml` and add the `-b` flag to recover from backup.
+
+```yaml
+command: -s -y -d -b
+```
+
+2.  Copy the backed up `sgx_data` directory to the recovery `sgx_data` directory.
+
+3.  Execute:
+
+```bash
+docker-compose up
+```
+
+4.  Enter the backup key when prompted.
+
+5.  Edit the `docker-compose.yml` file and remove the `-b` flag.

docs/building.md

-# Building SGX wallet from source
-
 <!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->
 
+# Building SGX wallet from source
+
 ## Clone this repository and its submodules
 
 `git clone --recurse-submodules  https://github.com/skalenetwork/sgxwallet.git`

docs/enabling-sgx.md

-# Enabling SGX
-
 <!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->
 
-### Verify Intel SGX is enabled in BIOS
+# Enabling SGX
+
+## Verify Intel SGX is enabled in BIOS
 
 Enter BIOS by pressing the BIOS key during boot.
 The BIOS key varies by manufacturer and could be F10, F2, F12, F1, DEL, or ESC.
@@ -26,7 +26,7 @@ This repo includes the **_sgx_enable_** utility. To enable SGX run:
 sudo ./sgx_enable
 ```
 
-Note: if you are not using Ubuntu 18.04 (something that we do not recommend), you may need
+Note: if you are not using Ubuntu 18.04 (Not recommended!), you may need
 to rebuild the sgx-software-enable utility before use by typing:
 
 ```bash
@@ -36,7 +36,7 @@ make
 
 ## Install SGX driver
 
-Install make and gcc if you do not have it
+Install make and gcc if you do not have it:
 
 ```bash
 apt-get install  build-essential
@@ -48,8 +48,8 @@ Run the following command:
 cd scripts; sudo ./sgx_linux_x64_driver_2.5.0_2605efa.bin; cd ..
 ```
 
-You can also try other driver versions from Intel website, but version 2.5.0_2605efa is what
-that we use in testing.
+Alternatively, other driver versions may be downloaded from Intel.
+Please note that version `2.5.0_2605efa` is what is currently supported.
 
 Reboot you machine after driver install.  Do `ls /dev/isgx` to check that `isgx` device is properly installed.
 If you do not see the `isgx` device, you need to troubleshoot your driver installation.
@@ -63,16 +63,16 @@ git clone https://github.com/intel/linux-sgx-driver
 
 And then follow instructions in README.md
 
-# Troubleshooting Installation
+## Troubleshooting Installation
 
 -   If the message  `intel_sgx: SGX is not enabled` appears in `/var/log/syslog`
-    Intel SGX needs to be enabled in BIOS
+    Intel SGX needs to be enabled in BIOS.
 
 -   If you are running in Intel SGX hardware mode, make sure you have device
     `/dev/isgx` (and not `/dev/sgx`). Review the Intel SGX device driver
     installation instructions above. If you have `/dev/sgx` the
-    device driver must be removed first
+    device driver must be removed first.
 
 -   If you are running in Intel SGX hardware mode, you need to modify
     the `ias_api_key` in `config/tcs_config.toml` with your
-    IAS Subscription key obtained in the instructions above
+    IAS Subscription key obtained in the instructions above.

docs/examples.md

-# Example usage
-
 <!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->
 
+# Example usage
+
 ## Run sgxwallet from build
 
 Type:
@@ -59,7 +59,7 @@ curl -X POST --data '{ "jsonrpc": "2.0", "id": 2, "method": "signCertificate", "
 
 The above example produces on success:
 
-```
+```json
 {"id":2,"jsonrpc":"2.0","result":{"errorMessage":"","result":true,"status":0}}
 
 ```
@@ -91,7 +91,7 @@ curl \
 
 The above example produces on success:
 
-```
+```json
 {"id":1,"jsonrpc":"2.0","result":{"encryptedKeyShare":"0400020000000000040effffff02000000000000000000000b000000000000ff0000000000000000cecb5d7bd507cb936464fdb6b88cfe80e38eae963af6a39b6b05cdfba5521c60000000f0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000080000000000000000000000000000000875c0520e8d6739c440e0e5073633861769fc1d31d627e9a72c66d43871c62bce2cc48e821341e10784242c4c8aad6ca73a491cbf7453c2ff012b6b3d9d96823c0256992d9792ea60269789b2d51ae87c75fe522dbcb8053458c1bca421cbc57f4a58e4e5689d534ca0303db83c7a9e88cd23afe3a39e1a3801371c95e7ffa54e834c6be8853983dcaa1fa9f5e6959a5","errorMessage":"","status":0}}
 
 ```

docs/prerequisites.md

-# SKALE sgxwallet Prerequisites
-
 <!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->
 
+# SKALE sgxwallet Prerequisites
+
 sgxwallet depends on several freely available
 software components. These must be installed and configured before
 running sgxwallet.
@@ -9,7 +9,7 @@ This document describes how to install and configure these required components.
 
 ## Recommended host system
 
-sgxwallet should be ran on Ubuntu 18.04. Sgxwallet has been tested on Ubuntu 18.04.
+sgxwallet has been tested and should be run on Ubuntu 18.04.
 
 Sgxwallet may run on other Linux distributions, 
 but the installation process is likely to be more complicated, 
@@ -50,4 +50,4 @@ Verify processor support of Intel SGX:
 cpuid | grep SGX:
 ```
 
-The printout should read  `SGX: Software Guard Extensions supported = true`
+The printout should read: `SGX: Software Guard Extensions supported = true`

docs/run_in_hardware_mode.md

-# Configuring sgxwallet server in hardware secure mode
-
 <!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->
 
+# Run in hardware secure mode
+
+-   [Docker Compose configuration](#docker-compose-configuration)
+-   [Run sgxwallet in secure mode](#run-sgxwallet-in-secure-mode)
+-   [Start, stop and upgrade sgxwallet containers](#start-stop-and-upgrade-sgxwallet-containers)
+-   [Logging](#logging)
+
 ## Docker Compose configuration
 
-Install docker-compose if you do not have it.
+Install docker-compose:
 
 ```bash
 sudo apt-get install docker.io docker-compose
 ```
 
+Edit `docker-compose.yml` as needed with the appropriate devices, ports, command flags, and healthcheck.
+
+### Devices
+
+Note: on some machines, the SGX device is not `/dev/mei0` but a different device, such 
+as `/dev/bs0`. In this case please edit  `docker-compose.yml` to specify the correct 
+device to use. 
+
+### Ports
+
+sgxwallet operates on the following network ports:
+
+-   1026 (https)
+-   1027 (http for initial SSL certification signing)
+-   1028 (localhost for admin )
+-   1029 (http only operation)
+
+If operating with a firewall, please make sure these ports are open so clients are able to connect to the server. 
+
+### Command Flags
+
+-   \-c   Do not verify client certificate
+-   \-s   Sign client certificate without human confirmation
+-   \-d   Turn on debug output
+-   \-v   Verbose mode: turn on debug output
+-   \-vv  Detailed verbose mode: turn on debug and trace outputs
+-   \-n   Launch SGXWalletServer using http (not https)
+-   \-b   Restore from back up (you will need to enter backup key) 
+-   \-y   Do not ask user to acknowledge receipt of backup key 
+
+### Healthcheck
+
+Healthcheck devices should match the same devices specified under `devices`.
+
+Note: All docker-compose commands herein need to be issued from `run_sgx` directory. If running in simulation mode, use `run_sgx_sim`.
+
+Note: sgxwallet places all its data into the `sgx_data` directory, which is created when sgxwallet is initialized.
+**This directory must be backed up. Do not remove this directory!**
+
 ## Run sgxwallet in secure mode
 
 ```bash
 cd run_sgx; sudo docker-compose up -d
 ```
 
-You should see "SGX Server started" message.
+The server should display: "SGX Server started".
 
-Note: on some machines, the SGX device is not `/dev/mei0` but a different device, such 
-as "/dev/bs0". In this case please edit  `docker-compose.yml` on your machine to specify the correct 
-device to use. 
+If not, confirm that the SGX device drivers are correctly configured to the machine.
 
 ## Start, stop and upgrade sgxwallet containers
 
-As any docker-compose application sgxwallet is super easy to use. 
-
 To run the server as a daemon, do
 
     sudo docker-compose up -d
@@ -39,20 +79,22 @@ To view server logs do
 
     sudo docker-compose logs
 
-To upgrade sgxwallet to the latest version do 
+To upgrade sgxwallet to a different version:
+
+1.  First stop the container:
 
     sudo docker-compose stop
-    sudo docker-compose pull
-    sudo docker-compose up
 
-Note: all docker-compose commands need to be issued from run_sgx_sim directory.
+2.  Edit `docker-compose.yml` with the appropriate container tag:
 
-Note: sgxwallet places all its data into the sgx_data directory, which is created the first time you run sgxwallet.
-Do not remove this directory!
+```yaml
+image: skalenetwork/sgxwallet:<TAG>
+```
 
-Note: sgxwallet operates on network ports 1026 (https) and 1027 (http for initial registration). 
-If you have a firewall on your network, please make sure these ports are open so clients are able to
-connect to the server. 
+3.  Pull and start the container:
+
+    sudo docker-compose pull
+    sudo docker-compose up
 
 ## Logging