> ## Documentation Index
> Fetch the complete documentation index at: https://buildbuddy-io-buildbuddy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer-managed Encryption Keys

> Use your own KMS keys from GCP or AWS to encrypt BuildBuddy cache artifacts at rest

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.

> [!NOTE]
>
> 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

**Google Cloud Platform (GCP)**

BuildBuddy infrastructure will access the supplied key using the `kms-prod@flame-build.iam.gserviceaccount.com`
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
```

> [!TIP]
>
> These permissions are available as part of the `Cloud KMS CryptoKey Encrypter/Decrypter` predefined IAM role.

**Amazon Web Services (AWS)**

BuildBuddy infrastructure will access the supplied key using a BuildBuddy owned user in account `561871016185`. You must
grant this AWS account access to the supplied key.

Add a key policy statement similar to:

```json theme={null}
{
  "Sid": "Allow BuildBuddy to use the key",
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::561871016185:root"
  },
  "Action": [
    "kms:Decrypt",
    "kms:Encrypt",
    "kms:GenerateDataKey"
  ],
  "Resource": "*"
}
```

## Considerations

> [!WARNING]
>
> **Important considerations before enabling this feature:**

> **Propagation delay**
>
> 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.

> **Existing artifacts**
>
> 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.

> **Key caching**
>
> The key used for encryption and decryption may be cached in memory by the BuildBuddy infrastructure for up to 10
> minutes for performance reasons.

> **Key rotation**
>
> 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

> [!NOTE]
>
> During operation, the Derived Key may be cached in memory by BuildBuddy systems for up to 10 minutes for performance
> reasons.

> [!WARNING]
>
> 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-Poly1305
>
> Industry-standard authenticated encryption with associated data (AEAD)

> **Key Size**
>
> 256-bit
>
> Provides strong cryptographic security

> **Performance**
>
> High throughput
>
> Optimized for encrypting large cache artifacts

> **Authentication**
>
> Built-in verification
>
> Poly1305 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](#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.

> [!TIP]
>
> Consider setting up monitoring and alerts for your KMS key usage to detect any issues with key access or rotation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.