Add tutorial for generating signed provenance

This should help people set up signing OCI images and generating signed provenance for them.

Author: Priya Wadhwa

README.md

@@ -47,8 +47,10 @@ To finish setting up Chains, please complete the following steps:
 * [Set up any additional configuration](docs/config.md)
 
 
-## Tutorial
-To get started with Chains, try out our getting started [tutorial](docs/tutorial.md)!
+## Tutorials
+To get started with Chains, try out our [getting started tutorial](docs/tutorials/getting-started-tutorial.md).
+
+To start signing OCI images and generating signed provenance for them, try our [signed provenance tutorial](docs/tutorials/signed-provenance-tutorial.md).
 
 ## Experimental Features
 To learn more about experimental features, check out [experimental.md](docs/experimental.md)

docs/authentication.md

@@ -11,28 +11,32 @@ The Chains controller will use the same service account your Task runs under as
 First, you will need access to credentials for your registry (they are in a file called `credentials.json` in this example).
 Next, create a [Docker config type Kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/#docker-config-secrets), which will contain the credentials required to push signatures:
 
+
+Set the namespace and name of the Kubernetes service account:
+
+```
+export NAMESPACE=<your namespace>
+export SERVICE_ACCOUNT_NAME=<service account name>
+```
+
+Then, create a `.dockerconfig` type secret:
+
 ```
 kubectl create secret docker-registry registry-credentials \
   --docker-server=gcr.io \
   --docker-username=_json_key \
   --docker-email=someemail@something.com \
   --docker-password="$(cat credentials.json)" \
-  -n tekton-chains
+  -n $NAMESPACE
 ```
 More details around creating this secret can be found [here](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#registry-secret-existing-credentials).
 
-Set the namespace and name of the service account:
-
-```
-export NAMESPACE=<your namespace>
-export SERVICE_ACCOUNT_NAME=<service account name>
-```
 
-and give the service account access to the secret above:
+Finally, give the service account access to the secret above:
 
 ```
 kubectl patch serviceaccount $SERVICE_ACCOUNT_NAME \
   -p "{\"imagePullSecrets\": [{\"name\": \"registry-credentials\"}]}" -n $NAMESPACE
 ```
 
-Now, anything running under `$SERVICE_ACCOUNT_NAME` should be able to push to your OCI registry.
+Now, Chains has push permissions for any TaskRuns running under the service account `$SERVICE_ACCOUNT_NAME`.

docs/tutorial.md …cs/tutorials/getting-started-tutorial.mddocs/tutorial.md renamed to docs/tutorials/getting-started-tutorial.md docs/tutorial.md renamed to docs/tutorials/getting-started-tutorial.md

@@ -1,4 +1,4 @@
-# Chains Tutorial
+# Chains Getting Started Tutorial
 This tutorial will guide you through:
 * Generating your own keypair and storing it as a Kubernetes Secret
 * Creating a sample TaskRun

docs/tutorials/signed-provenance-tutorial.md

@@ -0,0 +1,130 @@
+# Chains Signed Provenance Tutorial
+
+This tutorial will cover how to set up Chains to sign OCI images built in Tekton, and how to automatically generate and sign in-toto attestations for each image.
+This tutorial will also cover how to store these attestations in a transparency log and query the log for the attestation.
+
+This tutorial will guide you through:
+* Generating your own keypair and storing it as a Kubernetes Secret
+* Setting up authentication for your OCI registry to store images, image signatures and signed image attestations
+* Configuring Tekton Chains to generate and sign provenance
+* Building an image with kaniko in a Tekton TaskRun
+* Verifying the signed image and the signed provenance
+
+## Prerequisites
+A Kubernetes cluster with the following installed:
+* Tekton Chains
+* Tekton Pipelines
+
+
+## Generate a Key Pair
+First, we'll generate an encrypted x509 keypair and save it as a Kubernetes secret.
+Install [cosign](https://github.com/sigstore/cosign) and run the following:
+
+```shell
+cosign generate-key-pair k8s://tekton-chains/signing-secrets
+```
+
+cosign will prompt you for a password, which will be stored in a Kubernetes secret named `signing-secrets` in the `tekton-chains` namespace.
+
+The public key will be written to a local file called `cosign.pub`.
+
+
+## Set up Authentication
+There are two forms of authentication that need to be set up:
+1. The default service account in the default namespace needs permission to push to your registry, since this is what Chains will be using for pushing signatures. See our [authentication doc](../authentication.md)
+1. The Kaniko Task that will build and push the image needs push permissions for your registry
+
+To set up auth for the Kaniko Task, you'll need a Kubernetes secret of a docker `config.json` file which contains the required auth.
+You can create the secret by running:
+
+```
+kubectl create secret generic [DOCKERCONFIG_SECRET_NAME] --from-file [PATH TO CONFIG.JSON]
+```
+
+## Configuring Tekton Chains
+You'll need to make these changes to the Tekton Chains Config:
+* `artifacts.taskrun.format=tekton-provenance`
+* `artifacts.taskrun.storage=oci`
+* `transparency.enabled=true`
+
+You can set these fields by running
+
+```
+kubectl patch configmap chains-config -n tekton-chains -p='{"data":{"artifacts.taskrun.format": "tekton-provenance"}}'
+kubectl patch configmap chains-config -n tekton-chains -p='{"data":{"artifacts.taskrun.storage": "oci"}}'
+kubectl patch configmap chains-config -n tekton-chains -p='{"data":{"transparency.enabled": "true"}}'
+```
+
+This tells Chains to generate an in-toto attestation and store it in the specified OCI registry.
+Attestations will also be stored in [rekor](https://github.com/sigstore/rekor) since transparency is enabled.
+
+## Start the Kaniko Task
+Great, now that the setup is done we're finally ready to build an image with kaniko!
+
+First, apply the [Kaniko Task](../../examples/kaniko/kaniko.yaml) to your cluster:
+
+```
+kubectl apply -f examples/kaniko/kaniko.yaml
+```
+
+and set the following environment variables:
+
+```
+REGISTRY=[The registry you'll be pushing to]
+DOCKERCONFIG_SECRET_NAME=[The name of the secret with the docker config.json]
+```
+
+Then, you can start the Kaniko Task with the Tekton CLI tool, [tkn](https://github.com/tektoncd/cli):
+
+```
+tkn task start --param IMAGE=$REGISTRY/kaniko-chains --use-param-defaults --workspace name=source,emptyDir="" --workspace name=dockerconfig,secret=$DOCKERCONFIG_SECRET_NAME kaniko-chains
+```
+
+You can watch the logs of this Task until they complete; if authentication is set up correctly than the final image should be pushed to `$REGISTRY/kaniko-chains`.
+
+
+## Verifying the Image and Attestation
+Once the TaskRun has successfully completed, you'll need to wait a few seconds for Chains to generate provenance and sign it.
+
+Once you see the `chains.tekton.dev/signed=true` annotation on your TaskRun you know that Chains has completed the signing process and you're ready to move on to verification:
+
+```
+kubectl get tr [TASKRUN_NAME] -o json | jq -r .metadata.annotations
+
+{
+  "chains.tekton.dev/signed": "true",
+  ...
+}
+```
+
+To verify the image and the attestation, we'll use `cosign` again:
+
+```
+cosign verify -key cosign.pub $REGISTRY/kaniko-chains
+cosign verify-attestation -key cosign.pub $REGISTRY/kaniko-chains
+```
+
+You should see verification output for both!
+
+## Finding Provenance in Rekor
+To find provenance for the image in Rekor, first get the digest of the `$REGISTRY/kaniko-chains` image you just built.
+You can look this up in the TaskRun, or pull the image to get the digest. 
+
+You can then search rekor to find all entries that match the sha256 digest of the image you just built with the [rekor-cli](https://github.com/sigstore/rekor/releases/) tool:
+
+```
+rekor-cli search --sha [IMAGE_DIGEST]
+
+[UUID1]
+[UUID2]
+```
+
+The search will print out the UUIDs of matching entries.
+It may take a little guessing, but one of those UUIDs holds the attestation.
+You can see the attestation by using [jq](https://github.com/stedolan/jq):
+
+```
+rekor-cli get --uuid [UUID] --format json | jq -r .Attestation | base64 --decode | jq
+```
+
+Congratulations! You have officially built an image, signed it, and generated signed provenance for it with Tekton Chains 🎉