Skip to main content
BuildBuddy allows you to provide a managed key to be used to encrypt cache artifacts at rest. BuildBuddy currently supports encryption keys stored in Google Cloud Platform (GCP) KMS or Amazon Web Services (AWS) KMS.
To get started, open the organization settings page and navigate to the “Encryption keys” tab.Only organization administrators may change the encryption settings.

​
Key permissions

BuildBuddy infrastructure will access the supplied key using the [email protected] service account. You must grant this service account permissions to use the supplied key. At a minimum, the service account must be granted both of the following IAM permissions:
cloudkms.cryptoKeyVersions.useToEncrypt
cloudkms.cryptoKeyVersions.useToDecrypt
These permissions are available as part of the Cloud KMS CryptoKey Encrypter/Decrypter predefined IAM role.

​
Considerations

Important considerations before enabling this feature:
When enabling or disabling customer-managed encryption keys, it may take up to 10 minutes for the change to propagate through the system. If there are active builds during this window, they may experience “not found” errors while the change propagates.
Artifacts written prior to enabling this feature will not be retroactively encrypted using the new key, but will become effectively inaccessible and will be evicted from the cache as part of the regular cache lifecycle.
The key used for encryption and decryption may be cached in memory by the BuildBuddy infrastructure for up to 10 minutes for performance reasons.
The customer-managed key may be rotated. During rotation, the old key material must remain accessible for at least 24 hours to ensure existing cached artifacts remain accessible.

​
Implementation details

​
Key management

When the feature is enabled, two internal 256-bit keys are generated by BuildBuddy:
1

Customer Key generation

The first key (“Customer Key”) is generated and encrypted using the customer-supplied KMS key before being stored within BuildBuddy systems.
2

BuildBuddy Key generation

The second key (“BuildBuddy Key”) is generated and encrypted using a BuildBuddy-managed key before storage.
3

Derived Key creation

To perform encryption or decryption, a third 256-bit key (“Derived Key”) is obtained by:
  1. Decrypting the Customer Key using your KMS key
  2. Decrypting the BuildBuddy Key using BuildBuddy’s managed key
  3. Concatenating both keys and feeding them into HKDF-Expand using a SHA256 hash
During operation, the Derived Key may be cached in memory by BuildBuddy systems for up to 10 minutes for performance reasons.
If the feature is disabled, the Customer Key and BuildBuddy Key material are immediately deleted. Previously encrypted data will no longer be decryptable after 10 minutes at most, due to temporary in-memory key caching.

​
Content encryption and decryption

The Derived Key is used to encrypt and decrypt content using the XChaCha20-Poly1305 algorithm.

Algorithm

XChaCha20-Poly1305Industry-standard authenticated encryption with associated data (AEAD)

Key Size

256-bitProvides strong cryptographic security

Performance

High throughputOptimized for encrypting large cache artifacts

Authentication

Built-in verificationPoly1305 MAC ensures data integrity

​
Setup guide

1

Create or select a KMS key

Create a new key or use an existing symmetric encryption key in your cloud provider’s KMS service (GCP Cloud KMS or AWS KMS).
2

Grant permissions

Follow the instructions in the Key permissions section above to grant BuildBuddy access to your key.
3

Configure in BuildBuddy

Navigate to your organization settings → Encryption keys tab, and enter your KMS key identifier:
  • GCP: projects/PROJECT_ID/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME
  • AWS: arn:aws:kms:REGION:ACCOUNT:key/KEY_ID
4

Test the configuration

Run a test build to verify that artifacts are being encrypted with your key. Monitor for any “not found” errors during the propagation period.
Consider setting up monitoring and alerts for your KMS key usage to detect any issues with key access or rotation.

Build docs developers (and LLMs) love

Get started for freeTalk to us