diff options
Diffstat (limited to 'doc/OPTIONAL-FEATURES.md')
| -rw-r--r-- | doc/OPTIONAL-FEATURES.md | 60 |
1 files changed, 30 insertions, 30 deletions
diff --git a/doc/OPTIONAL-FEATURES.md b/doc/OPTIONAL-FEATURES.md index 80310fd..963409e 100644 --- a/doc/OPTIONAL-FEATURES.md +++ b/doc/OPTIONAL-FEATURES.md @@ -1,6 +1,6 @@ # Optional Features -These features are **disabled by default** and must be explicitly enabled as +These features are **disabled by default** and must be explicitly enabled as described below. * [HTTP Health Check responder](#http-health-check) @@ -8,10 +8,10 @@ described below. # HTTP Health Check -## Description +## Description -Intended for use by load balancers or other control plane facilities to monitor -the state of Roughenough servers and remove unhealthy instances automatically. +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: @@ -23,12 +23,12 @@ Connection: Close ``` -No attempt is made to parse the request, the server *always* emits this response. +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 HTTP -health check responder on the configured port. +Provide a value for the `health_check_port` setting. This enables the HTTP +health check responder on the configured port. ```yaml interface: 127.0.0.1 @@ -39,11 +39,11 @@ health_check_port: 8000 ## DoS Warning -**An unprotected health-check port can be used to DoS the server. Do NOT expose -the health check port to the internet!** +**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 +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) @@ -52,14 +52,14 @@ and/or control plane components*. # Key Management System (KMS) Support -## Description +## 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. +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 +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 @@ -76,16 +76,16 @@ $ 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** +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: +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 + 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 @@ -103,13 +103,13 @@ projects/PROJECT_NAME/locations/GCP_LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KE ### AWS Example -#### Credentials +#### Credentials [Rusoto](https://rusoto.org/) is used by Roughenough to access AWS. If your system has AWS credentials in the typical `~/.aws/credentials` then everything should "just work". -Otherwise Rusoto supports alternative ways to provide AWS credentials. See -[Rusoto's documentation](https://github.com/rusoto/rusoto/blob/master/AWS-CREDENTIALS.md) +Otherwise Rusoto supports alternative ways to provide AWS credentials. See +[Rusoto's documentation](https://github.com/rusoto/rusoto/blob/master/AWS-CREDENTIALS.md) for details. #### `roughenough-kms` Command line @@ -124,7 +124,7 @@ $ cargo build --release --features "awskms" $ 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 kms_protection: "arn:aws:kms:SOME_AWS_REGION:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" seed: b8000c000102020078d39e85c7386e9e2bed1f30fac6dd322db96b8aaac8974fc6c0e0f566f8f6c971012fca1e69fffffd947fe82a9e505baf580000007e307c06092a864886f70d010706a06f306d020100306806092a864886f70d010701301e060960864801650304012e3011040c55d16d891b3b2a1ae2587a9c020110803bcc74dd96336009087772b28ec908c40e4113b1ab9b98934bd3b4f3dd3c1e8cdc6da82a4321fd8378ad0e2e0507bf0c5ea0e28d447e5f8482533baa423b7af8459ae87736f381d87fe38c21a805fae1c25c43d59200f42cae0d07f741e787a04c0ad72774942dddf818be0767e4963fe5a810f734a0125c @@ -156,20 +156,20 @@ $ export ROUGHENOUGH_SEED=b8000c000102020078d39e85c7386e9e2bed1f30fac6dd322db96b #### Credentials -Only **Service Account credentials** (in `.json` format) are currently supported. OAuth, bearer tokens, +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 obtain Service Account credentials if you don't already have them: * Creating a new service account? - 1. Create the account + 1. Create the account 2. Download the credentials when prompted - + * 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) + 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 @@ -179,7 +179,7 @@ Make note of the full path where the credentials are saved, it's needed in the n ```bash # Set environment variable pointing to downloaded Service Account credentials -$ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/creds.json +$ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/creds.json # Build roughenough with Google KMS support $ cargo build --release --features "gcpkms" @@ -188,7 +188,7 @@ $ cargo build --release --features "gcpkms" $ 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 kms_protection: "projects/PROJECT_NAME/locations/GCP_LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME" seed: 71000c000a2400c7f2553954873ef29aeb37384c25d7a937d389221207c3368657870129d601d084c8da1249008d6fd4640f815596788e97bb3ce02fd007bc25a1019ca51945c3b99283d3945baacd77b1b991f5f6f8848c549a5767f57c9c999e97fe6d28fdb17db1d63c2ea966d8236d20c71e8e9c757c5bab62472c65b48376bc8951700aceb22545fce58d77e7cc147f7134da7a2cca790b54f29e4798442cee6e0d34e57f80ce983f7e5928cceff2 |