Every secret value in your Burrow is encrypted with a data key of its own, and every data key is encrypted with the Burrow's master key. The Encryption & keys section under Burrow Settings shows which master key is in use and lets you replace it. Viewing the section needs permission to view the Burrow's encryption settings, and rotating the key needs permission to change them.
Master key#
Fingerprint. A short fingerprint of the active master key, so you can tell one key from another. The key itself is never shown.
Key version. Starts at v1 and goes up by one with every rotation.
Source. App-managed key file, or Environment.
By default the Burrow manages its own master key, and that is the setup we recommend. The key is generated the first time the Burrow starts and kept in the file master.key in the Burrow's data directory, readable only by the account the Burrow runs as. There is nothing to set up, and the key can be rotated from this section.
The master key is kept outside the database, so a copy of the database can't be decrypted without it. Keep the key file wherever you keep the Burrow's data directory.
Key rotation#
Select Rotate key and confirm. The Burrow generates a new master key, encrypts every data key under it, and discards the old key. Secret values themselves are unchanged, so machines, SDKs and the CLI keep reading without any change on their side. When it finishes, the key version goes up by one and the fingerprint changes. Every rotation is recorded in the audit log.
Rotation happens in one step. If anything goes wrong partway, it is rolled back, your secrets stay under the old key, and you can try again.
Every backup carries the keys it was taken with, so a backup from before a rotation still restores.
Supplying your own key#
If your own infrastructure has to hold the master key, for example in a secrets store that injects it at start-up, you can supply it yourself in the BURROW_MASTER_KEY environment variable: 32 random bytes encoded as base64. This is optional and outside the recommended setup. Whenever the variable is set, the Burrow uses it in place of a key file, and Source shows Environment.
A key you supply is yours to look after. It can't be rotated from the Burrow, so the section shows it without Key rotation, and its value has to stay the same for as long as the Burrow's data exists.