-
Notifications
You must be signed in to change notification settings - Fork 19
/
Copy pathencryption.html.md.erb
112 lines (88 loc) · 5.55 KB
/
encryption.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
---
title: Encrypting the Concourse Database
owner: Concourse
---
<strong><%= modified_date %></strong>
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.
Pivotal recommends that Concourse admins enable encryption.
In addition to encrypting the Concourse database, you might want to configure <a href="./credential-management.html">credential management</a> for your pipelines.
## <a id="values-affected"></a> 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](https://concourse-ci.org/resources.html#resource-source)** and **resource type [sources](https://concourse-ci.org/resource-types.html#resource-type-source)**. These sources often contain private keys and other credentials for writing to or accessing the resource.
* **Task step [parameters](https://concourse-ci.org/tasks.html#task-params)**, **put step [parameters](https://concourse-ci.org/put-step.html#put-step-put)**, and **get step [parameters](https://concourse-ci.org/get-step.html#get-step-get)**. 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:
<ul>
<li><strong>Build logs</strong></li>
<li><strong>Resource versions</strong></li>
<li><strong>Resource metadata</strong><br/>
<p class="note"><strong>Note</strong>: If your pipeline is <a href="https://concourse-ci.org/managing-pipelines.html#fly-expose-pipeline">exposed</a>, resource metadata is publicly visible. It should never contain credentials.
</p>
</li>
<li><strong>Component names</strong>, 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.
</li>
</ul>
## <a id="enable-encryption"></a> Enabling Encryption
<p class="note"><strong>Note</strong>: 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.</p>
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.
<ol>
<li>Navigate to your Concourse manifest.</li>
<li>Add the <code>encryption\_key</code> property to the manifest under <code>instance\_groups/web/jobs/atc/properties</code>.
<br>Use a random 16- or 32-byte character sequence as the encryption key. </li>
<pre>
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
<strong>encryption_key: ENCRYPTION-KEY</strong>
</pre>
<li>Redeploy.</li>
</ol>
## <a id="rotate-key"></a> 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.
<ol>
<li>Navigate to your Concourse manifest.</li>
<li>Rename the <code>encryption_key</code> property to <code>old_encryption_key</code>.</li>
<li>Add the <code>encryption_key</code> property to the manifest with a random 16- or 32-byte character sequence.</li>
<pre>
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
<strong>old_encryption_key: OLD-ENCRYPTION-KEY</strong>
<strong>encryption_key: NEW-ENCRYPTION-KEY</strong>
</pre>
<li>Redeploy.</li>
<li>Delete the <code>old_encryption_key</code> property.</li>
</ol>
## <a id="disable-encryption"></a> Disabling Encryption
Disable encryption by passing the <code>old\_encryption\_key</code> property with no new key. Without a new encryption key, the ATC decrypts all existing data on start.
<ol>
<li>Navigate to your Concourse manifest.</li>
<li>Rename the <code>encryption\_key</code> property to <code>old\_encryption\_key</code>.</li>
<li>Redeploy.</li>
<li>Delete the <code>old\_encryption\_key</code> property.</li>
</ol>