Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 2. Verify the Trusted Artifact Signer service installation

2.1. Signing and verifying containers by using Cosign from the command-line interface

The cosign tool gives you the capability to sign and verify Open Container Initiative (OCI) container images, along with other build artifacts by using Red Hat’s Trusted Artifact Signer (RHTAS) service.

Important

For RHTAS, you must use cosign version 2.2 or later.

Prerequisites

  • A RHTAS installation on Red Hat OpenShift Container Platform version 4.13 or later.
  • Access to the OpenShift web console.
  • A workstation with the podman, and oc binaries installed.

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

Additional resources

2.2. Signing and verifying commits by using Gitsign from the command-line interface

The gitsign tool gives you the ability to sign and verify Git repository commits by using Red Hat’s Trusted Artifact Signer (RHTAS) service.

Prerequisites

  • A RHTAS installation on Red Hat OpenShift Container Platform version 4.13 or later.
  • Access to the OpenShift web console.
  • A workstation with the oc, and git binaries installed.

  • Downloaded the cosign binary from the OpenShift cluster.

    • You must use cosign version 2.2 or later.

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

Additional resources

2.3. Verifying signatures on container images with Enterprise Contract

Enterprise Contract (EC) is a tool for maintaining the security of software supply chains, and you can use it to define and enforce policies for container images. You can use the ec binary to verify the attestation and signature of container images that use Red Hat’s Trusted Artifact Signer (RHTAS) signing framework.

Prerequisites

  • A RHTAS installation on Red Hat OpenShift Container Platform version 4.13 or later.
  • A workstation with the oc, cosign, and podman binaries installed.
  • Access to the OpenShift web console.

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.

Additional resources

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.