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