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. Log in to the OpenShift cluster:

   Syntax

   oc login --token=TOKEN --server=SERVER_URL_AND_PORT

   Example

   $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443

   Note

   You can find your login token and URL to use on the command line from the OpenShift web console. Log in to the OpenShift web console. Click your user name, and click Copy login command. Offer your user name and password again, if asked, and click Display Token to view the command.

3. 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.

4. 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

5. Initialize The Update Framework (TUF) system:

   Example

   $ cosign initialize

6. 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

7. 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.

8. Download the rekor-cli 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 rekor-cli 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 rekor-cli-amd64.gz
      $ chmod +x rekor-cli-amd64

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

      Example

      $ sudo mv rekor-cli-amd64 /usr/local/bin/rekor-cli

9. Query the transparency log by using the Rekor command-line interface.

   1. Search based on the log index:

      Example

      $ rekor-cli get --log-index 0 --rekor_server $COSIGN_REKOR_URL --format json | jq

   2. Search for an email address to get the universal unique identifier (UUID):

      Syntax

      rekor-cli search --email SIGNING_EMAIL_ADDR --rekor_server $COSIGN_REKOR_URL --format json | jq

      Example

      $ rekor-cli search --email jdoe@redhat.com --rekor_server $COSIGN_REKOR_URL --format json | jq

      This command returns the UUID for use with the next step.

   3. Use the UUID to get the transaction details:

      Syntax

      rekor-cli get --uuid UUID --rekor_server $COSIGN_REKOR_URL --format json | jq

      Example

      $ rekor-cli get --uuid 24296fb24b8ad77a71b9c1374e207537bafdd75b4f591dcee10f3f697f150d7cc5d0b725eea641e7 --rekor_server $COSIGN_REKOR_URL --format json | jq

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. Log in to the OpenShift cluster:

   Syntax

   oc login --token=TOKEN --server=SERVER_URL_AND_PORT

   Example

   $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443

   Note

   You can find your login token and URL to use on the command line from the OpenShift web console. Log in to the OpenShift web console. Click your user name, and click Copy login command. Offer your user name and password again, if asked, and click Display Token to view the command.

3. 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.

4. 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

5. 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

6. 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.

7. Initialize The Update Framework (TUF) system:

   Example

   $ cosign initialize

8. 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. Log in to the OpenShift cluster:

   Syntax

   oc login --token=TOKEN --server=SERVER_URL_AND_PORT

   Example

   $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443

   Note

   You can find your login token and URL to use on the command line from the OpenShift web console. Log in to the OpenShift web console. Click your user name, and click Copy login command. Offer your user name and password again, if asked, and click Display Token to view the command.

3. 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.

4. 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

5. Initialize The Update Framework (TUF) system:

   Example

   $ cosign initialize

6. 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

7. 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 about the schema layout.

8. 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

9. 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

10. 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.