Skip to content

Latest commit

 

History

History
217 lines (154 loc) · 9.5 KB

OPTIONAL-FEATURES.md

File metadata and controls

217 lines (154 loc) · 9.5 KB
Raw

Optional Features

These features are disabled by default and must be explicitly enabled as described below.

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/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 HTTP health check responder on the configured port.

interface: 127.0.0.1
port: 8686
seed: f61075c988feb9cb700a4a6a3291bfbc9cab11b9c9eca8c802468eb38a43d7d3
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!

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:

# 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

Rusoto 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 for details.

roughenough-kms Command line

# Provide AWS credentials as described in the Rusoto docs

# 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
kms_protection: "arn:aws:kms:SOME_AWS_REGION:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
seed: b8000c000102020078d39e85c7386e9e2bed1f30fac6dd322db96b8aaac8974fc6c0e0f566f8f6c971012fca1e69fffffd947fe82a9e505baf580000007e307c06092a864886f70d010706a06f306d020100306806092a864886f70d010701301e060960864801650304012e3011040c55d16d891b3b2a1ae2587a9c020110803bcc74dd96336009087772b28ec908c40e4113b1ab9b98934bd3b4f3dd3c1e8cdc6da82a4321fd8378ad0e2e0507bf0c5ea0e28d447e5f8482533baa423b7af8459ae87736f381d87fe38c21a805fae1c25c43d59200f42cae0d07f741e787a04c0ad72774942dddf818be0767e4963fe5a810f734a0125c

Configuration

Copy and paste the output kms_protection and seed values into a config or set the corresponding environment variables. The roughenough-server will detect that AWS KMS is being used and decrypt the seed automatically. For example:

interface: 127.0.0.1
port: 8686
kms_protection: "arn:aws:kms:SOME_AWS_REGION:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
seed: b8000c000102020078d39e85c7386e9e2bed1f30fac6dd322db96b8aaac8974fc6c0e0f566f8f6c971012fca1e69fffffd947fe82a9e505baf580000007e307c06092a864886f70d010706a06f306d020100306806092a864886f70d010701301e060960864801650304012e3011040c55d16d891b3b2a1ae2587a9c020110803bcc74dd96336009087772b28ec908c40e4113b1ab9b98934bd3b4f3dd3c1e8cdc6da82a4321fd8378ad0e2e0507bf0c5ea0e28d447e5f8482533baa423b7af8459ae87736f381d87fe38c21a805fae1c25c43d59200f42cae0d07f741e787a04c0ad72774942dddf818be0767e4963fe5a810f734a0125c

or using environment based configuration:

$ export ROUGHENOUGH_INTERFACE=127.0.0.1
$ export ROUGHENOUGH_PORT=8686
$ export ROUGHENOUGH_KMS_PROTECTION="arn:aws:kms:SOME_AWS_REGION:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
$ export ROUGHENOUGH_SEED=b8000c000102020078d39e85c7386e9e2bed1f30fac6dd322db96b8aaac8974fc6c0e0f566f8f6c971012fca1e69fffffd947fe82a9e505baf580000007e307c06092a864886f70d010706a06f306d020100306806092a864886f70d010701301e060960864801650304012e3011040c55d16d891b3b2a1ae2587a9c020110803bcc74dd96336009087772b28ec908c40e4113b1ab9b98934bd3b4f3dd3c1e8cdc6da82a4321fd8378ad0e2e0507bf0c5ea0e28d447e5f8482533baa423b7af8459ae87736f381d87fe38c21a805fae1c25c43d59200f42cae0d07f741e787a04c0ad72774942dddf818be0767e4963fe5a810f734a0125c

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 obtain Service Account credentials if you don't already have them:

  • Creating a new service 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)
    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.

roughenough-kms Command line

# 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
kms_protection: "projects/PROJECT_NAME/locations/GCP_LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME"
seed: 71000c000a2400c7f2553954873ef29aeb37384c25d7a937d389221207c3368657870129d601d084c8da1249008d6fd4640f815596788e97bb3ce02fd007bc25a1019ca51945c3b99283d3945baacd77b1b991f5f6f8848c549a5767f57c9c999e97fe6d28fdb17db1d63c2ea966d8236d20c71e8e9c757c5bab62472c65b48376bc8951700aceb22545fce58d77e7cc147f7134da7a2cca790b54f29e4798442cee6e0d34e57f80ce983f7e5928cceff2

Configuration

Copy and paste the output kms_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. For example:

interface: 127.0.0.1
port: 8686
kms_protection: "projects/PROJECT_NAME/locations/GCP_LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME"
seed: 71000c000a2400c7f2553954873ef29aeb37384c25d7a937d389221207c3368657870129d601d084c8da1249008d6fd4640f815596788e97bb3ce02fd007bc25a1019ca51945c3b99283d3945baacd77b1b991f5f6f8848c549a5767f57c9c999e97fe6d28fdb17db1d63c2ea966d8236d20c71e8e9c757c5bab62472c65b48376bc8951700aceb22545fce58d77e7cc147f7134da7a2cca790b54f29e4798442cee6e0d34e57f80ce983f7e5928cceff2

or using environment based configuration:

$ export ROUGHENOUGH_INTERFACE=127.0.0.1
$ export ROUGHENOUGH_PORT=8686
$ export ROUGHENOUGH_KMS_PROTECTION="projects/PROJECT_NAME/locations/GCP_LOCATION/keyRings/KEYRING_NAME/cryptoKeys/KEY_NAME"
$ export ROUGHENOUGH_SEED=71000c000a2400c7f2553954873ef29aeb37384c25d7a937d389221207c3368657870129d601d084c8da1249008d6fd4640f815596788e97bb3ce02fd007bc25a1019ca51945c3b99283d3945baacd77b1b991f5f6f8848c549a5767f57c9c999e97fe6d28fdb17db1d63c2ea966d8236d20c71e8e9c757c5bab62472c65b48376bc8951700aceb22545fce58d77e7cc147f7134da7a2cca790b54f29e4798442cee6e0d34e57f80ce983f7e5928cceff2