Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit256bb9b

Browse files
committed
add docs for encryption
1 parent2e2ed4a commit256bb9b

File tree

3 files changed

+161
-0
lines changed

3 files changed

+161
-0
lines changed

‎docs/admin/encryption.md

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
#Database Encryption
2+
3+
By default, Coder stores external user tokens in plaintext in the database. This
4+
is undesirable in high-security environments, as an attacker with access to the
5+
database can use these tokens to impersonate users. Database Encryption allows
6+
Coder administrators to encrypt these tokens at-rest, preventing attackers from
7+
using them.
8+
9+
##How it works
10+
11+
Coder allows administrators to specify up to two
12+
[external token encryption keys](../cli/server.md#external-token-encryption-keys).
13+
If configured, Coder will use these keys to encrypt external user tokens before
14+
storing them in the database. The encryption algorithm used is AES-256-GCM with
15+
a 32-byte key length.
16+
17+
Coder will use the first key provided for both encryption and decryption. If a
18+
second key is provided, Coder will use it for decryption only. This allows
19+
administrators to rotate encryption keys without invalidating existing tokens.
20+
21+
The following database fields are currently encrypted:
22+
23+
-`user_links.oauth_access_token`
24+
-`user_links.oauth_refresh_token`
25+
-`git_auth_links.oauth_access_token`
26+
-`git_auth_links.oauth_refresh_token`
27+
28+
Additional database fields may be encrypted in the future.
29+
30+
>Implementation note: there is an additional encrypted database field
31+
>`dbcrypt_sentinel.value`. This field is used to verify that the encryption
32+
>keys are valid for the configured database. It is not used to encrypt any user
33+
>data.
34+
35+
Encrypted data is stored in the following format:
36+
37+
-`encrypted_data = dbcrypt-<b64data>`
38+
-`b64data = <cipher checksum>-<ciphertext>`
39+
40+
All encrypted data is prefixed with the string`dbcrypt-`. The cipher checksum
41+
is the first 7 bytes of the SHA256 hex digest of the encryption key used to
42+
encrypt the data.
43+
44+
##Enabling encryption
45+
46+
1. Ensure you have a valid backup of your database.**Do not skip this step.**
47+
If you are using the built-in PostgreSQL database, you can run
48+
[`coder server postgres-builtin-url`](../cli/server_postgres-builtin-url.md)
49+
to get the connection URL.
50+
51+
1. Generate a 32-byte random key and base64-encode it. For example:
52+
53+
```shell
54+
dd if=/dev/urandom bs=32 count=1| base64
55+
```
56+
57+
1. Store this key in a secure location (for example, a Kubernetes secret):
58+
59+
```shell
60+
kubectl create secret generate coder-external-token-encryption-keys --from-literal=keys=<key>
61+
```
62+
63+
1. In your Coder configuration set the`external_token_encryption_keys` field to
64+
a comma-separated list of base64-encoded keys. For example, in your Helm
65+
`values.yaml`:
66+
67+
```yaml
68+
coder:
69+
env:
70+
[...]
71+
-name:CODER_EXTERNAL_TOKEN_ENCRYPTION_KEYS
72+
valueFrom:
73+
secretKeyRef:
74+
name:coder-external-token-encryption-keys
75+
key:keys
76+
```
77+
78+
## Rotating keys
79+
80+
We recommend only having one active encryption key at a time normally. However,
81+
if you need to rotate keys, you can perform the following procedure:
82+
83+
1. Ensure you have a valid backup of your database. **Do not skip this step.**
84+
85+
1. Generate a new encryption key following the same procedure as above.
86+
87+
1. Add the above key to the list of
88+
[external token encryption keys](../cli/server.md#external-token-encryption-keys).
89+
**The new key must appear first in the list**. For example, in the Kubernetes
90+
secret created above:
91+
92+
```yaml
93+
apiVersion:v1
94+
kind:Secret
95+
type:Opaque
96+
metadata:
97+
name:coder-external-token-encryption-keys
98+
namespace:coder-namespace
99+
data:
100+
keys:<new-key>,<old-key>
101+
```
102+
103+
1. After updating the configuration, restart the Coder server. The server will
104+
now encrypt all new data with the new key, but will be able to decrypt tokens
105+
encrypted with the old key.
106+
107+
1. To re-encrypt all encrypted database fields with the new key, run
108+
[`coder dbcrypt-rotate`](../cli/dbcrypt-rotate.md). This command will
109+
re-encrypt all tokens with the first key in the list of external token
110+
encryption keys. We recommend performing this action during a maintenance
111+
window.
112+
113+
> Note: this command requires direct access to the database. If you are using
114+
> the built-in PostgreSQL database, you can run
115+
> [`coder server postgres-builtin-url`](../cli/server_postgres-builtin-url.md)
116+
> to get the connection URL.
117+
118+
1. Once the above command completes successfully, remove the old encryption key
119+
from Coder's configuration and restart Coder once more. You can now safely
120+
delete the old key from your secret store.
121+
122+
## Disabling encryption
123+
124+
Automatically disabling encryption is currently not supported. Encryption can be
125+
disabled by removing the encrypted data manually from the database:
126+
127+
```sql
128+
DELETE FROM user_links WHERE oauth_access_token LIKE 'dbcrypt-%';
129+
DELETE FROM user_links WHERE oauth_refresh_token LIKE 'dbcrypt-%';
130+
DELETE FROM git_auth_links WHERE oauth_access_token LIKE 'dbcrypt-%';
131+
DELETE FROM git_auth_links WHERE oauth_refresh_token LIKE 'dbcrypt-%';
132+
DELETE FROM dbcrypt_sentinel WHERE value LIKE 'dbcrypt-%';
133+
```
134+
135+
Users will then need to re-authenticate with external authentication providers.
136+
137+
## Troubleshooting
138+
139+
-If Coder detects that the data stored in the database under
140+
`dbcrypt_sentinel.value`was not encrypted with a known key, it will refuse to
141+
start. If you are seeing this behaviour, ensure that the encryption keys
142+
provided are correct.
143+
-If Coder is unable to decrypt a token, it will be treated as if the data were
144+
not present. This means that the user will be prompted to re-authenticate with
145+
the external provider. If you are seeing this behaviour consistently, ensure
146+
that the encryption keys are correct.

‎docs/images/icons/lock.svg

Lines changed: 3 additions & 0 deletions
Loading

‎docs/manifest.json

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -385,6 +385,13 @@
385385
"description":"Learn what usage telemetry Coder collects",
386386
"path":"./admin/telemetry.md",
387387
"icon_path":"./images/icons/science.svg"
388+
},
389+
{
390+
"title":"Database Encryption",
391+
"description":"Learn how to encrypt sensitive data at rest in Coder",
392+
"path":"./admin/database-encryption.md",
393+
"icon_path":"./images/icons/lock.svg",
394+
"state":"enterprise"
388395
}
389396
]
390397
},
@@ -535,6 +542,11 @@
535542
"description":"Create a workspace",
536543
"path":"cli/create.md"
537544
},
545+
{
546+
"title":"dbcrypt-rotate",
547+
"description":"Rotate database encryption keys",
548+
"path":"cli/dbcrypt-rotate.md"
549+
},
538550
{
539551
"title":"delete",
540552
"description":"Delete a workspace",

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp