-
-
Notifications
You must be signed in to change notification settings - Fork 373
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
AES secrets encryption #2300
Closed
Closed
AES secrets encryption #2300
Changes from all commits
Commits
Show all changes
14 commits
Select commit
Hold shift + click to select a range
a6f397a
cleanup encryption code
anbraten 57586e4
simplify EncryptedStore
6543 32d7786
next ...
6543 24e37f5
Added encrypted secret service
zc-devs 72341b6
Changed AES service
zc-devs 02c04ca
Moved encryption to plugins
zc-devs ee068e9
Cleaning up
zc-devs 325850b
Changed base64 and added logs
zc-devs 9a444a3
Fixed token creation (using name instead of id)
zc-devs ae2ccd3
Fixed documentation
zc-devs f4ef1e8
Update docs/docs/30-administration/40-encryption.md
anbraten 09002eb
Made encryption service system-wide
zc-devs 7b853e5
Fixed NPE
zc-devs 111e99c
Fixed docs
zc-devs File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,64 +1,55 @@ | ||
# Secrets encryption | ||
|
||
By default, Woodpecker does not encrypt secrets in its database. You can enable encryption | ||
using simple AES key or more advanced [Google TINK](https://developers.google.com/tink) encryption. | ||
By default, Woodpecker does not encrypt secrets in its database. You can enable encryption using a simple AES key. | ||
|
||
:::caution | ||
Secrets encryption is experimental. | ||
Check the [current state](https://github.com/woodpecker-ci/woodpecker/issues/1541) | ||
::: | ||
|
||
## Common | ||
|
||
### Enabling secrets encryption | ||
|
||
To enable secrets encryption and encrypt all existing secrets in database set | ||
`WOODPECKER_ENCRYPTION_KEY`, `WOODPECKER_ENCRYPTION_KEY_FILE` or `WOODPECKER_ENCRYPTION_TINK_KEYSET_PATH` environment | ||
variable depending on encryption method of your choice. | ||
To enable secrets encryption set `WOODPECKER_SECRETS_ENCRYPTION_MODE` environment variable to the one of: | ||
- `Disabled` (default) - use plain text secrets; | ||
- `Enabled` - use encryption without migration (encryption) of already existing secrets; | ||
- `EnabledAndEncrypt` - use encryption and encrypt already existing secrets; | ||
- `DisabledAndDecrypt` - use plain text secrets and run decryption of existing secrets. | ||
|
||
:::caution | ||
After migration, don't forget to switch the mode: `EnabledAndEncrypt` -> `Enabled`, `DisabledAndDecrypt` -> `Disabled`. | ||
After encryption is enabled you will be unable to start Woodpecker server without providing valid encryption key! | ||
|
||
### Disabling encryption and decrypting all secrets | ||
|
||
To disable secrets encryption and decrypt database you need to start server with valid | ||
`WOODPECKER_ENCRYPTION_KEY` or `WOODPECKER_ENCRYPTION_TINK_KEYSET_FILE` environment variable set depending on | ||
enabled encryption method, and `WOODPECKER_ENCRYPTION_DISABLE` set to true. | ||
|
||
After secrets was decrypted server will proceed working in unencrypted mode. You will not need to use "disable encryption" | ||
variable or encryption keys to start server anymore. | ||
|
||
::: | ||
|
||
## AES | ||
Simple AES encryption. | ||
|
||
### Configuration | ||
You can manage encryption on server using these environment variables: | ||
- `WOODPECKER_ENCRYPTION_KEY` - encryption key | ||
- `WOODPECKER_ENCRYPTION_KEY_FILE` - file to read encryption key from | ||
- `WOODPECKER_ENCRYPTION_DISABLE` - disable encryption flag used to decrypt all data on server | ||
|
||
## TINK | ||
TINK uses AEAD encryption instead of simple AES and supports key rotation. | ||
- `WOODPECKER_ENCRYPTION_AES_KEY` - encryption key | ||
- `WOODPECKER_ENCRYPTION_AES_KEY_FILE` - file to read encryption key from | ||
|
||
### Configuration | ||
You can manage encryption on server using these two environment variables: | ||
- `WOODPECKER_ENCRYPTION_TINK_KEYSET_FILE` - keyset filepath | ||
- `WOODPECKER_ENCRYPTION_DISABLE` - disable encryption flag used to decrypt all data on server | ||
|
||
### Encryption keys | ||
You will need plaintext AEAD-compatible Google TINK keyset to encrypt your data. | ||
|
||
To generate it and then rotate keys if needed, install `tinkey`([installation guide](https://developers.google.com/tink/install-tinkey)) | ||
|
||
Keyset contains one or more keys, used to encrypt or decrypt your data, and primary key ID, used to determine which key | ||
to use while encrypting new data. | ||
|
||
Keyset generation example: | ||
One option to generate encryption key is to use OpenSSL, but any password generator can also be used. Recommended key length is at least 32 bytes: | ||
```shell | ||
tinkey create-keyset --key-template AES256_GCM --out-format json --out keyset.json | ||
$ openssl rand -base64 32 | ||
GjVHT007c4x3N+YPbsZld+hifba1enXkOzIb/0h6oW8= | ||
``` | ||
|
||
### Key rotation | ||
Use `tinkey` to rotate encryption keys in your existing keyset: | ||
```shell | ||
tinkey rotate-keyset --in keyset_v1.json --out keyset_v2.json --key-template AES256_GCM | ||
If we run the server with `WOODPECKER_ENCRYPTION_AES_KEY='GjVHT007c4x3N+YPbsZld+hifba1enXkOzIb/0h6oW8='`, and try to create a secret like `some_secret:super-secret-value` | ||
then we'll get messages in the log similar to: | ||
```log | ||
{"level":"debug","id":1,"name":"s-name","time":"2023-09-24T10:49:21Z","caller":"/woodpecker/server/plugins/secrets/encrypted.go:48","message":"encryption"} | ||
``` | ||
and a row in the database similar to: | ||
```psql | ||
woodpecker=# select secret_id, secret_name, secret_value from secrets; | ||
secret_id | secret_name | secret_value | ||
-----------+-------------+---------------------------------------------------------------- | ||
1 | some_secret | _aes_PUattjAz6EOP28sbJOEaDSZyXRDrPxGQv9EyQHQPimrWLQELr59WYp83DUNQ6w | ||
(1 row) | ||
``` | ||
|
||
Then you just need to replace server keyset file with the new one. At the moment server detects new encryption | ||
keyset it will re-encrypt all existing secrets with the new key, so you will be unable to start server with previous | ||
keyset anymore. | ||
:::note | ||
You won't get exactly the same secret's encrypted value, because a random nonce is used. | ||
::: |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
there should be an option to revert encryption back to unencrypted ... we could add a warning if that's really the intended case ... but we should have it
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done
This can be achieved via disabling encryption. For example, Plain -> AES -> Plain -> Tink. I would leave it like that, for this PR at least.