Chapter 2. Verify the Trusted Artifact Signer service installation

Procedure

1. Download the cosign binary from the OpenShift cluster to your workstation.

   1. Login to the OpenShift web console. From the home page, click the ? icon, click Command line tools, go to the cosign download section, and click the link for your platform.

   2. Open a terminal on your workstation, decompress the binary .gz file, and set the execute bit:

      Example

      $ gunzip cosign-amd64.gz
      $ chmod +x cosign-amd64

   3. Move and rename the binary to a location within your $PATH environment:

      Example

      $ sudo mv cosign-amd64 /usr/local/bin/cosign

2. Switch to the RHTAS project:

   Syntax

   oc project PROJECT_NAME

   Example

   $ oc project trusted-artifact-signer

   Note

   Use the project name for the RHTAS installation.

3. Configure your shell environment for doing container image signing and verifying.

   Example

   $ export TUF_URL=$(oc get tuf -o jsonpath='{.items[0].status.url}' -n trusted-artifact-signer)
   $ export OIDC_ISSUER_URL=https://$(oc get route keycloak -n keycloak-system | tail -n 1 | awk '{print $2}')/auth/realms/trusted-artifact-signer
   $ export COSIGN_FULCIO_URL=$(oc get fulcio -o jsonpath='{.items[0].status.url}' -n trusted-artifact-signer)
   $ export COSIGN_REKOR_URL=$(oc get rekor -o jsonpath='{.items[0].status.url}' -n trusted-artifact-signer)
   $ export COSIGN_MIRROR=$TUF_URL
   $ export COSIGN_ROOT=$TUF_URL/root.json
   $ export COSIGN_OIDC_CLIENT_ID="trusted-artifact-signer"
   $ export COSIGN_OIDC_ISSUER=$OIDC_ISSUER_URL
   $ export COSIGN_CERTIFICATE_OIDC_ISSUER=$OIDC_ISSUER_URL
   $ export COSIGN_YES="true"
   $ export SIGSTORE_FULCIO_URL=$COSIGN_FULCIO_URL
   $ export SIGSTORE_OIDC_ISSUER=$COSIGN_OIDC_ISSUER
   $ export SIGSTORE_REKOR_URL=$COSIGN_REKOR_URL
   $ export REKOR_REKOR_SERVER=$COSIGN_REKOR_URL

4. Initialize The Update Framework (TUF) system:

   Example

   $ cosign initialize

5. Sign a test container image.

   1. Create an empty container image:

      Example

      $ echo "FROM scratch" > ./tmp.Dockerfile
      $ podman build . -f ./tmp.Dockerfile -t ttl.sh/rhtas/test-image:1h

   2. Push the empty container image to the ttl.sh ephemeral registry:

      Example

      $ podman push ttl.sh/rhtas/test-image:1h

   3. Sign the container image:

      Syntax

      cosign sign -y IMAGE_NAME:TAG

      Example

      $ cosign sign -y ttl.sh/rhtas/test-image:1h

      A web browser opens allowing you to sign the container image with an email address.

   4. Remove the temporary Docker file:

      Example

      $ rm ./tmp.Dockerfile

6. Verify a signed container image by using a certificate identity and issuer:

   Syntax

   cosign verify --certificate-identity=SIGNING_EMAIL_ADDR IMAGE_NAME:TAG

   Example

   $ cosign verify --certificate-identity=jdoe@redhat.com ttl.sh/rhtas/test-image:1h

   Note

   You can also use regular expressions for the certificate identity and issuer by using the following options to the cosign command, --certificate-identity-regexp and --certificate-oidc-issuer-regexp.

Procedure

1. Download the gitsign binary from the OpenShift cluster to your workstation.

   1. Login to the OpenShift web console. From the home page, click the ? icon, click Command line tools, go to the gitsign download section, and click the link for your platform.

   2. Open a terminal on your workstation, decompress the .gz file, and set the execute bit:

      Example

      $ gunzip gitsign-amd64.gz
      $ chmod +x gitsign-amd64

   3. Move and rename the binary to a location within your $PATH environment:

      Example

      $ sudo mv gitsign-amd64 /usr/local/bin/gitsign

2. Switch to the RHTAS project:

   Syntax

   oc project PROJECT_NAME

   Example

   $ oc project trusted-artifact-signer

   Note

   Use the project name for the RHTAS installation.

3. Configure your shell environment for doing commit signing and verifying:

   Example

   $ export TUF_URL=$(oc get tuf -o jsonpath='{.items[0].status.url}' -n trusted-artifact-signer)
   $ export OIDC_ISSUER_URL=https://$(oc get route keycloak -n keycloak-system | tail -n 1 | awk '{print $2}')/auth/realms/trusted-artifact-signer
   $ export COSIGN_FULCIO_URL=$(oc get fulcio -o jsonpath='{.items[0].status.url}' -n trusted-artifact-signer)
   $ export COSIGN_REKOR_URL=$(oc get rekor -o jsonpath='{.items[0].status.url}' -n trusted-artifact-signer)
   $ export COSIGN_MIRROR=$TUF_URL
   $ export COSIGN_ROOT=$TUF_URL/root.json
   $ export COSIGN_OIDC_CLIENT_ID="trusted-artifact-signer"
   $ export COSIGN_OIDC_ISSUER=$OIDC_ISSUER_URL
   $ export COSIGN_CERTIFICATE_OIDC_ISSUER=$OIDC_ISSUER_URL
   $ export COSIGN_YES="true"
   $ export SIGSTORE_FULCIO_URL=$COSIGN_FULCIO_URL
   $ export SIGSTORE_OIDC_ISSUER=$COSIGN_OIDC_ISSUER
   $ export SIGSTORE_REKOR_URL=$COSIGN_REKOR_URL
   $ export REKOR_REKOR_SERVER=$COSIGN_REKOR_URL

4. Configure the local repository configuration to sign your commits by using the RHTAS service:

   Example

   $ git config --local commit.gpgsign true
   $ git config --local tag.gpgsign true
   $ git config --local gpg.x509.program gitsign
   $ git config --local gpg.format x509
   $ git config --local gitsign.fulcio $SIGSTORE_FULCIO_URL
   $ git config --local gitsign.rekor $SIGSTORE_REKOR_URL
   $ git config --local gitsign.issuer $SIGSTORE_OIDC_ISSUER
   $ git config --local gitsign.clientID trusted-artifact-signer

5. Make a commit to the local repository:

   Example

   $ git commit --allow-empty -S -m “Test of a signed commit”

   A web browser opens allowing you to sign the commit with an email address.

6. Initialize The Update Framework (TUF) system:

   Example

   $ cosign initialize

7. Verify the commit:

   Syntax

   gitsign verify --certificate-identity=SIGNING_EMAIL --certificate-oidc-issuer=$SIGSTORE_OIDC_ISSUER HEAD

   Example

   $ gitsign verify --certificate-identity=jdoe@redhat.com --certificate-oidc-issuer=$SIGSTORE_OIDC_ISSUER HEAD

Procedure

1. Download the ec binary from the OpenShift cluster.

   1. Log in to the OpenShift web console. From the home page, click the ? icon, click Command line tools, go to the ec download section, then click the link for your platform.

   2. Open a terminal on your workstation, decompress the binary .gz file, and set the execute bit:

      Example

      $ gunzip ec-amd64.gz
      $ chmod +x ec-amd64

   3. Move and rename the binary to a location within your $PATH environment:

      Example

      $ sudo mv ec-amd64 /usr/local/bin/ec

2. Switch to the RHTAS project:

   Syntax

   oc project PROJECT_NAME

   Example

   $ oc project trusted-artifact-signer

   Note

   Use the project name for the RHTAS installation.

3. Configure your shell environment for doing container image signing and verifying.

   Example

   $ export TUF_URL=$(oc get tuf -o jsonpath='{.items[0].status.url}' -n trusted-artifact-signer)
   $ export OIDC_ISSUER_URL=https://$(oc get route keycloak -n keycloak-system | tail -n 1 | awk '{print $2}')/auth/realms/trusted-artifact-signer
   $ export COSIGN_FULCIO_URL=$(oc get fulcio -o jsonpath='{.items[0].status.url}' -n trusted-artifact-signer)
   $ export COSIGN_REKOR_URL=$(oc get rekor -o jsonpath='{.items[0].status.url}' -n trusted-artifact-signer)
   $ export COSIGN_MIRROR=$TUF_URL
   $ export COSIGN_ROOT=$TUF_URL/root.json
   $ export COSIGN_OIDC_CLIENT_ID="trusted-artifact-signer"
   $ export COSIGN_OIDC_ISSUER=$OIDC_ISSUER_URL
   $ export COSIGN_CERTIFICATE_OIDC_ISSUER=$OIDC_ISSUER_URL
   $ export COSIGN_YES="true"
   $ export SIGSTORE_FULCIO_URL=$COSIGN_FULCIO_URL
   $ export SIGSTORE_OIDC_ISSUER=$COSIGN_OIDC_ISSUER
   $ export SIGSTORE_REKOR_URL=$COSIGN_REKOR_URL
   $ export REKOR_REKOR_SERVER=$COSIGN_REKOR_URL

4. Initialize The Update Framework (TUF) system:

   Example

   $ cosign initialize

5. Sign a test container image.

   1. Create an empty container image:

      Example

      $ echo "FROM scratch" > ./tmp.Dockerfile
      $ podman build . -f ./tmp.Dockerfile -t ttl.sh/rhtas/test-image:1h

   2. Push the empty container image to the ttl.sh ephemeral registry:

      Example

      $ podman push ttl.sh/rhtas/test-image:1h

   3. Sign the container image:

      Syntax

      cosign sign -y IMAGE_NAME:TAG

      Example

      $ cosign sign -y ttl.sh/rhtas/test-image:1h

      A web browser opens allowing you to sign the container image with an email address.

   4. Remove the temporary Docker file:

      Example

      $ rm ./tmp.Dockerfile

6. Create a predicate.json file:

   Example

   {
     "builder": {
       "id": "https://localhost/dummy-id"
     },
     "buildType": "https://example.com/tekton-pipeline",
     "invocation": {},
     "buildConfig": {},
     "metadata": {
       "completeness": {
         "parameters": false,
         "environment": false,
         "materials": false
       },
       "reproducible": false
     },
     "materials": []
   }

   Refer to the SLSA provenance predicate specifications for more information on the purpose, and schema layout.

7. Associate the predicate.json file with the container image:

   Syntax

   cosign attest -y --predicate ./predicate.json --type slsaprovenance IMAGE_NAME:TAG

   Example

   $ cosign attest -y --predicate ./predicate.json --type slsaprovenance ttl.sh/rhtas/test-image:1h

8. Verify that the container image has at least one attestation and signature:

   Syntax

   cosign tree IMAGE_NAME:TAG

   Example

   $ cosign tree ttl.sh/rhtas/test-image:1h
   
   📦 Supply Chain Security Related artifacts for an image: ttl.sh/rhtas/test-image@sha256:7de5fa822a9d1e507c36565ee0cf50c08faa64505461c844a3ce3944d23efa35
   └── 💾 Attestations for an image tag: ttl.sh/rhtas/test-image:sha256-7de5fa822a9d1e507c36565ee0cf50c08faa64505461c844a3ce3944d23efa35.att
      └── 🍒 sha256:40d94d96a6d3ab3d94b429881e1b470ae9a3cac55a3ec874051bdecd9da06c2e
   └── 🔐 Signatures for an image tag: ttl.sh/rhtas/test-image:sha256-7de5fa822a9d1e507c36565ee0cf50c08faa64505461c844a3ce3944d23efa35.sig
      └── 🍒 sha256:f32171250715d4538aec33adc40fac2343f5092631d4fc2457e2116a489387b7

9. Verify the container image by using Enterprise Contact:

   Syntax

   ec validate image --image IMAGE_NAME:TAG --certificate-identity-regexp 'SIGNER_EMAIL_ADDR' --certificate-oidc-issuer-regexp 'keycloak-keycloak-system' --output yaml --show-successes

   Example

   $ ec validate image --image ttl.sh/rhtas/test-image:1h --certificate-identity-regexp 'jdoe@example.com' --certificate-oidc-issuer-regexp 'keycloak-keycloak-system' --output yaml --show-successes
   
   success: true
   successes:
     - metadata:
         code: builtin.attestation.signature_check
       msg: Pass
     - metadata:
         code: builtin.attestation.syntax_check
       msg: Pass
     - metadata:
         code: builtin.image.signature_check
       msg: Pass
   ec-version: v0.1.2427-499ef12
   effective-time: "2024-01-21T19:57:51.338191Z"
   key: ""
   policy: {}
   success: true

   Enterprise Contract generates a pass-fail report with details on any security violations. When you add the --info flag, the report includes more details and possible solutions for any violations found.