1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
|
# Optional Features
These features are **disabled by default** and must be explicitly enabled as
described below.
* [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 HTTP
health check responder on the configured port.
```yaml
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:
```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
[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)
for details.
#### `roughenough-kms` Command line
```bash
# 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:
```yaml
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:
```bash
$ 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
```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
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:
```yaml
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:
```bash
$ 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
```
|
