Encrypting the Concourse Database

Continuous integration and deployment systems are high-value targets for malicious third parties who want to gain access to your data. Because CI/CD tools have comprehensive access to many components, gaining access to a CI/CD tool often equates to gaining access to all the components that tool touches.

Concourse lets you encrypt the database information at rest. By using encryption, you ensure that plaintext credentials do not exist in the database in the event of a security incident.

VMware recommends that Concourse admins enable encryption. In addition to encrypting the Concourse database, you might want to configure credential management for your pipelines.

Values Affected by Encryption

When you encrypt Concourse, it secures the following values. These values are likely to contain credentials, which is why they get encrypted by default.

• Resources sources and resource type sources. These sources often contain private keys and other credentials for writing to or accessing the resource.
• Task step parameters, put step parameters, and get step parameters. Parameters are often used to configure access to an external deployment with which a task is integrating.
• Team authentication configurations. These often contain OAuth client secrets.

The following things are not encrypted:

• Build logs

• Resource versions

• Resource metadata

  Important Resource metadata should never contain credentials. If your pipeline is exposed, resource metadata is publicly visible.

• Component names, like pipeline names or job names. Resources and jobs specifically exist in their own tables, with their names in plaintext, and only their config encrypted.

Enabling Encryption

Important Depending on the size of your deployment, enabling encryption might cause some downtime. If your deployment uses multiple ATCs, they might not be able to communicate with each other after encryption until the encryption keys are shared among them.

On startup, the ATC encrypts all existing plaintext data. After this point, any new data is encrypted before it is sent over the network to the database.

1. Navigate to your Concourse manifest.

2. Add the encryption_key property to the manifest under instance_groups/web/jobs/atc/properties.

   Use a random 16- or 32-byte character sequence as the encryption key.

   jobs:
   - name: atc
   release: concourse
   properties:
   # replace with your CI's externally reachable URL, e.g. https://ci.concourse.com
   external_url: ((EXTERNAL-URL))
   
   # Basic Auth is not recommended; please replace with the admin team authentication method of your choice
   basic_auth_username:
   basic_auth_password:
   
   # replace with your SSL cert and key
   #tls_cert: TLS-CERT
   #tls_key: TLS-CERT-KEY
   
   postgresql_database: &atc_db atc
   # replace with an encryption key in the form of a random 16- or 32-byte character sequence
   encryption_key: ENCRYPTION-KEY
   

3. Redeploy.

Rotating the Encryption Key

Key rotation is a method of exchanging an outdated encryption key for a new one. Using a supported key rotation process helps preserve access to your data while maintaining consistent security.

On startup, the ATC decrypts all existing data and re-encrypts it with the new key.

1. Navigate to your Concourse manifest.

2. Rename the encryption_key property to old_encryption_key.

3. Add the encryption_key property to the manifest with a random 16- or 32-byte character sequence.

   jobs:
   - name: atc
   release: concourse
   properties:
   # replace with your CI's externally reachable URL, e.g. https://ci.concourse.com
   external_url: ((EXTERNAL-URL))
   
   # Basic Auth is not recommended; please replace with the admin team authentication method of your choice
   basic_auth_username:
   basic_auth_password:
   
   # replace with your SSL cert and key
   #tls_cert: TLS-CERT
   #tls_key: TLS-CERT-KEY
   
   postgresql_database: &atc_db atc
   # replace with an encryption key in the form of a random 16- or 32-byte character sequence
   old_encryption_key: OLD-ENCRYPTION-KEY
   encryption_key: NEW-ENCRYPTION-KEY
   

4. Redeploy.

5. Delete the old_encryption_key property.

Disabling Encryption

Disable encryption by passing the old_encryption_key property with no new key. Without a new encryption key, the ATC decrypts all existing data on start.

1. Navigate to your Concourse manifest.
2. Rename the encryption_key property to old_encryption_key.
3. Redeploy.
4. Delete the old_encryption_key property.