Docs, polish, clean-ups for KMS and health-check features

1 files changed, 168 insertions, 0 deletions

diff --git a/doc/OPTIONAL-FEATURES.md b/doc/OPTIONAL-FEATURES.md
new file mode 100644
index 0000000..babf1f0
--- /dev/null
+++ b/doc/OPTIONAL-FEATURES.md
@@ -0,0 +1,168 @@
+# Optional Features
+
+These are opt-in features enabled either A) via a config setting, or B) at compile-time.
+
+* [An HTTP Health Check responder](#http-health-check)
+* [Key Management System (KMS) support](#key-management-system-kms-support)
+
+
+# HTTP Health Check
+
+## Description 
+
+Intended for use by load balancers or other control plane facilities to monitor 
+the state of Roughenough servers and remove unhealthy instances automatically. 
+
+The server unconditionally emits a response to any TCP connection to the health
+check port then closes the connection:
+
+```http
+HTTP/1.1 200 OK
+Content-Length: 0
+Connection: Close
+
+```
+
+No attempt is made to parse the request, the server *always* emits this response. 
+
+# How to enable
+
+Provide a value for the `health_check_port` setting. This enables the simplistic 
+HTTP health check responder on the configured port. 
+
+## Warning
+
+**An unprotected health-check port can be used to DoS the server. Do NOT expose 
+the health check port to the internet!** 
+
+To accurately reflect the ability of a Roughenough server to respond to requests, 
+the health check socket is serviced in the same event loop executing the primary Roughtime 
+protocol. Abuse of the health-check port can denial-of-service the whole server.
+
+If enabled, ensure the health check port is accessible only to the *intended load-balancer(s)
+and/or control plane components*.
+
+
+# Key Management System (KMS) Support
+
+## Description 
+
+The server's long-term identity can be protected by encrypting it, storing the encrypted value
+in the configuration, and invoking a cloud key management system to temporarily decrypt 
+(in memory) the long-term identity at server start-up. 
+
+This way the server's long-term identity is never stored in plaintext. Instead the encrypted 
+long-term identity "blob" is safe to store on disk, on Github, in a container, etc. Ability 
+to access the unencrypted identity is controlled "out of band" by the KMS system.
+
+## How to enable KMS support
+
+KMS support must be compiled-in. To enable:
+
+```bash
+# Build with Google Cloud KMS support
+$ cargo build --release --features "gcpkms"
+
+# Build with AWS KMS support
+$ cargo build --release --features "awskms"
+```
+
+## Google or Amazon: choose one and one only
+
+Sadly, due to incompatibilities with dependencies of the KMS libraries, only **one** 
+KMS system can be enabled at a time. Attempting `--features "awskms,gcpkms"` will result
+in a build failure.
+
+## Using `roughtime-kms` to encrypt the long-term seed
+
+Use the command line tool `roughtime-kms` to encrypt the seed value for the 
+server's long-term identity. To do this you will need: 
+
+ 1. The long-term key seed value 
+ 2. Access credentials for your cloud of choice
+ 3. An identifier for the KMS key to be used
+ 4. Necessary permissions to perform symmetric encrypt/decrypt operations
+    using the selected key
+
+For Amazon the key identifier is an ARN in the form:
+```
+arn:aws:kms:SOME_AWS_REGION:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
+```
+
+For Google the key identifier is a resource ID in the form:
+```
+projects/PROJECT_NAME/locations/GCP_LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME
+```
+
+### AWS Example
+
+#### Credentials 
+
+Mercifully, the Rusoto library handles AWS credentials pretty smoothly as described in 
+[Rusoto's documentation](https://github.com/rusoto/rusoto/blob/master/AWS-CREDENTIALS.md). 
+
+#### Command line
+
+```bash
+# Build roughenough with AWS KMS support
+$ cargo build --release --features "awskms"
+
+# Encrypt the seed value
+$ target/release/roughenough-kms \
+  -k arn:aws:kms:SOME_AWS_REGION:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab \
+  -s a0a31d76900080c3cdc42fe69de8dd0086d6b54de7814004befd0b9c4447757e
+  
+# Output of above will be something like this
+key_protection: "arn:aws:kms:SOME_AWS_REGION:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
+seed: b8000c000102020078d39e85c7386e9e2bed1f30fac6dd322db96b8aaac8974fc6c0e0f566f8f6c971012fca1e69fffffd947fe82a9e505baf580000007e307c06092a864886f70d010706a06f306d020100306806092a864886f70d010701301e060960864801650304012e3011040c55d16d891b3b2a1ae2587a9c020110803bcc74dd96336009087772b28ec908c40e4113b1ab9b98934bd3b4f3dd3c1e8cdc6da82a4321fd8378ad0e2e0507bf0c5ea0e28d447e5f8482533baa423b7af8459ae87736f381d87fe38c21a805fae1c25c43d59200f42cae0d07f741e787a04c0ad72774942dddf818be0767e4963fe5a810f734a0125c
+```
+
+Copy and paste the output `key_protection` and `seed` values into a config or
+set the corresponding environment variables. `roughenough-server` will detect that
+AWS KMS is being used and decrypt the seed automatically.
+
+### GCP Example
+
+#### Credentials
+
+Only **Service Account credentials** (in `.json` format) are currently supported. OAuth, bearer tokens, 
+GAE default credentials, and GCE default credentials are **not** supported (contributions to
+add support are particularly welcome!).
+
+To get Service Account credentials:
+
+1. Creating a new service account?
+    1. Create the account 
+    2. Download the credentials when prompted
+2. Existing service account?
+    1. Open the Cloud Console https://console.cloud.google.com
+    2. Navigate to `IAM -> Service accounts`
+    3. Locate the service account row, click on its "Actions" menu (the three dots on the right) 
+    4. Choose `Create key` and `JSON` format
+    5. Download the credentials when prompted
+
+Make note of the full path where the credentials are saved, it's needed in the next step.
+
+#### Command line
+
+```bash
+# Set environment variable pointing to downloaded Service Account credentials
+$ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/creds.json 
+
+# Build roughenough with Google KMS support
+$ cargo build --release --features "gcpkms"
+
+# Encrypt the seed value
+$ target/release/roughenough-kms \
+  -k projects/PROJECT_NAME/locations/GCP_LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME \
+  -s a0a31d76900080c3cdc42fe69de8dd0086d6b54de7814004befd0b9c4447757e
+  
+# Output of above will be something like this
+key_protection: "projects/PROJECT_NAME/locations/GCP_LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME"
+seed: 71000c000a2400c7f2553954873ef29aeb37384c25d7a937d389221207c3368657870129d601d084c8da1249008d6fd4640f815596788e97bb3ce02fd007bc25a1019ca51945c3b99283d3945baacd77b1b991f5f6f8848c549a5767f57c9c999e97fe6d28fdb17db1d63c2ea966d8236d20c71e8e9c757c5bab62472c65b48376bc8951700aceb22545fce58d77e7cc147f7134da7a2cca790b54f29e4798442cee6e0d34e57f80ce983f7e5928cceff2
+```
+
+Copy and paste the output `key_protection` and `seed` values into a config or
+set the corresponding environment variables. `roughenough-server` will detect that
+Google KMS is being used and decrypt the seed automatically.
+