github.com/appscode/helm@v3.0.0-alpha.1+incompatible/docs/provenance.md (about) 1 # Helm Provenance and Integrity 2 3 Helm has provenance tools which help chart users verify the integrity and origin 4 of a package. Using industry-standard tools based on PKI, GnuPG, and well-respected 5 package managers, Helm can generate and verify signature files. 6 7 ## Overview 8 9 Integrity is established by comparing a chart to a provenance record. Provenance 10 records are stored in _provenance files_, which are stored alongside a packaged 11 chart. For example, if a chart is named `myapp-1.2.3.tgz`, its provenance file 12 will be `myapp-1.2.3.tgz.prov`. 13 14 Provenance files are generated at packaging time (`helm package --sign ...`), and 15 can be checked by multiple commands, notable `helm install --verify`. 16 17 ## The Workflow 18 19 This section describes a potential workflow for using provenance data effectively. 20 21 Prerequisites: 22 23 - A valid PGP keypair in a binary (not ASCII-armored) format 24 - The `helm` command line tool 25 - GnuPG command line tools (optional) 26 - Keybase command line tools (optional) 27 28 **NOTE:** If your PGP private key has a passphrase, you will be prompted to enter 29 that passphrase for any commands that support the `--sign` option. 30 31 Creating a new chart is the same as before: 32 33 ``` 34 $ helm create mychart 35 Creating mychart 36 ``` 37 38 Once ready to package, add the `--sign` flag to `helm package`. Also, specify 39 the name under which the signing key is known and the keyring containing the corresponding private key: 40 41 ``` 42 $ helm package --sign --key 'helm signing key' --keyring path/to/keyring.secret mychart 43 ``` 44 45 **TIP:** for GnuPG users, your secret keyring is in `~/.gnupg/secring.gpg`. You can 46 use `gpg --list-secret-keys` to list the keys you have. 47 48 **Warning:** the GnuPG v2 store your secret keyring using a new format 'kbx' on the default location '~/.gnupg/pubring.kbx'. Please use the following command to convert your keyring to the legacy gpg format: 49 50 ``` 51 $ gpg --export-secret-keys >~/.gnupg/secring.gpg 52 ``` 53 54 At this point, you should see both `mychart-0.1.0.tgz` and `mychart-0.1.0.tgz.prov`. 55 Both files should eventually be uploaded to your desired chart repository. 56 57 You can verify a chart using `helm verify`: 58 59 ``` 60 $ helm verify mychart-0.1.0.tgz 61 ``` 62 63 A failed verification looks like this: 64 65 ``` 66 $ helm verify topchart-0.1.0.tgz 67 Error: sha256 sum does not match for topchart-0.1.0.tgz: "sha256:1939fbf7c1023d2f6b865d137bbb600e0c42061c3235528b1e8c82f4450c12a7" != "sha256:5a391a90de56778dd3274e47d789a2c84e0e106e1a37ef8cfa51fd60ac9e623a" 68 ``` 69 70 To verify during an install, use the `--verify` flag. 71 72 ``` 73 $ helm install --verify mychart-0.1.0.tgz 74 ``` 75 76 If the keyring (containing the public key associated with the signed chart) is not in the default location, you may need to point to the 77 keyring with `--keyring PATH` as in the `helm package` example. 78 79 If verification fails, the install will be aborted before the chart is even rendered. 80 81 82 ### Using Keybase.io credentials 83 84 The [Keybase.io](https://keybase.io) service makes it easy to establish a chain of 85 trust for a cryptographic identity. Keybase credentials can be used to sign charts. 86 87 Prerequisites: 88 89 - A configured Keybase.io account 90 - GnuPG installed locally 91 - The `keybase` CLI installed locally 92 93 #### Signing packages 94 95 The first step is to import your keybase keys into your local GnuPG keyring: 96 97 ``` 98 $ keybase pgp export -s | gpg --import 99 ``` 100 101 This will convert your Keybase key into the OpenPGP format, and then import it 102 locally into your `~/.gnupg/secring.gpg` file. 103 104 You can double check by running `gpg --list-secret-keys`. 105 106 ``` 107 $ gpg --list-secret-keys 1 ↵ 108 /Users/mattbutcher/.gnupg/secring.gpg 109 ------------------------------------- 110 sec 2048R/1FC18762 2016-07-25 111 uid technosophos (keybase.io/technosophos) <technosophos@keybase.io> 112 ssb 2048R/D125E546 2016-07-25 113 ``` 114 115 Note that your secret key will have an identifier string: 116 117 ``` 118 technosophos (keybase.io/technosophos) <technosophos@keybase.io> 119 ``` 120 121 That is the full name of your key. 122 123 Next, you can package and sign a chart with `helm package`. Make sure you use at 124 least part of that name string in `--key`. 125 126 ``` 127 $ helm package --sign --key technosophos --keyring ~/.gnupg/secring.gpg mychart 128 ``` 129 130 As a result, the `package` command should produce both a `.tgz` file and a `.tgz.prov` 131 file. 132 133 #### Verifying packages 134 135 You can also use a similar technique to verify a chart signed by someone else's 136 Keybase key. Say you want to verify a package signed by `keybase.io/technosophos`. 137 To do this, use the `keybase` tool: 138 139 ``` 140 $ keybase follow technosophos 141 $ keybase pgp pull 142 ``` 143 144 The first command above tracks the user `technosophos`. Next `keybase pgp pull` 145 downloads the OpenPGP keys of all of the accounts you follow, placing them in 146 your GnuPG keyring (`~/.gnupg/pubring.gpg`). 147 148 At this point, you can now use `helm verify` or any of the commands with a `--verify` 149 flag: 150 151 ``` 152 $ helm verify somechart-1.2.3.tgz 153 ``` 154 155 ### Reasons a chart may not verify 156 157 These are common reasons for failure. 158 159 - The prov file is missing or corrupt. This indicates that something is misconfigured 160 or that the original maintainer did not create a provenance file. 161 - The key used to sign the file is not in your keyring. This indicate that the 162 entity who signed the chart is not someone you've already signaled that you trust. 163 - The verification of the prov file failed. This indicates that something is wrong 164 with either the chart or the provenance data. 165 - The file hashes in the provenance file do not match the hash of the archive file. This 166 indicates that the archive has been tampered with. 167 168 If a verification fails, there is reason to distrust the package. 169 170 ## The Provenance File 171 The provenance file contains a chart’s YAML file plus several pieces of 172 verification information. Provenance files are designed to be automatically 173 generated. 174 175 176 The following pieces of provenance data are added: 177 178 179 * The chart file (Chart.yaml) is included to give both humans and tools an easy 180 view into the contents of the chart. 181 * The signature (SHA256, just like Docker) of the chart package (the .tgz file) 182 is included, and may be used to verify the integrity of the chart package. 183 * The entire body is signed using the algorithm used by PGP (see 184 [http://keybase.io] for an emerging way of making crypto signing and 185 verification easy). 186 187 The combination of this gives users the following assurances: 188 189 * The package itself has not been tampered with (checksum package tgz). 190 * The entity who released this package is known (via the GnuPG/PGP signature). 191 192 The format of the file looks something like this: 193 194 ``` 195 -----BEGIN PGP SIGNED MESSAGE----- 196 name: nginx 197 description: The nginx web server as a replication controller and service pair. 198 version: 0.5.1 199 keywords: 200 - https 201 - http 202 - web server 203 - proxy 204 source: 205 - https://github.com/foo/bar 206 home: http://nginx.com 207 208 ... 209 files: 210 nginx-0.5.1.tgz: “sha256:9f5270f50fc842cfcb717f817e95178f” 211 -----BEGIN PGP SIGNATURE----- 212 Version: GnuPG v1.4.9 (GNU/Linux) 213 214 iEYEARECAAYFAkjilUEACgQkB01zfu119ZnHuQCdGCcg2YxF3XFscJLS4lzHlvte 215 WkQAmQGHuuoLEJuKhRNo+Wy7mhE7u1YG 216 =eifq 217 -----END PGP SIGNATURE----- 218 ``` 219 220 Note that the YAML section contains two documents (separated by `...\n`). The 221 first is the Chart.yaml. The second is the checksums, a map of filenames to 222 SHA-256 digests (value shown is fake/truncated) 223 224 The signature block is a standard PGP signature, which provides [tamper 225 resistance](http://www.rossde.com/PGP/pgp_signatures.html). 226 227 ## Chart Repositories 228 229 Chart repositories serve as a centralized collection of Helm charts. 230 231 Chart repositories must make it possible to serve provenance files over HTTP via 232 a specific request, and must make them available at the same URI path as the chart. 233 234 For example, if the base URL for a package is `https://example.com/charts/mychart-1.2.3.tgz`, 235 the provenance file, if it exists, MUST be accessible at `https://example.com/charts/mychart-1.2.3.tgz.prov`. 236 237 From the end user's perspective, `helm install --verify myrepo/mychart-1.2.3` 238 should result in the download of both the chart and the provenance file with no 239 additional user configuration or action. 240 241 ## Establishing Authority and Authenticity 242 243 When dealing with chain-of-trust systems, it is important to be able to 244 establish the authority of a signer. Or, to put this plainly, the system 245 above hinges on the fact that you trust the person who signed the chart. 246 That, in turn, means you need to trust the public key of the signer. 247 248 One of the design decisions with Kubernetes Helm has been that the Helm 249 project would not insert itself into the chain of trust as a necessary 250 party. We don't want to be "the certificate authority" for all chart 251 signers. Instead, we strongly favor a decentralized model, which is part 252 of the reason we chose OpenPGP as our foundational technology. 253 So when it comes to establishing authority, we have left this 254 step more-or-less undefined in Helm 2.0.0. 255 256 However, we have some pointers and recommendations for those interested 257 in using the provenance system: 258 259 - The [Keybase](https://keybase.io) platform provides a public 260 centralized repository for trust information. 261 - You can use Keybase to store your keys or to get the public keys of others. 262 - Keybase also has fabulous documentation available 263 - While we haven't tested it, Keybase's "secure website" feature could 264 be used to serve Helm charts. 265 - The [official Kubernetes Charts project](https://github.com/helm/charts) 266 is trying to solve this problem for the official chart repository. 267 - There is a long issue there [detailing the current thoughts](https://github.com/helm/charts/issues/23). 268 - The basic idea is that an official "chart reviewer" signs charts with 269 her or his key, and the resulting provenance file is then uploaded 270 to the chart repository. 271 - There has been some work on the idea that a list of valid signing 272 keys may be included in the `index.yaml` file of a repository. 273 274 Finally, chain-of-trust is an evolving feature of Helm, and some 275 community members have proposed adapting part of the OSI model for 276 signatures. This is an open line of inquiry in the Helm team. If you're 277 interested, jump on in.