Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 2. Red Hat Enterprise Linux

2.1. Installing Trusted Artifact Signer using Ansible

You can install the Red Hat Trusted Artifact Signer (RHTAS) on Red Hat Enterprise Linux by using a Red Hat provided Ansible Playbook. This deployment gives you a basic signing framework with Keycloak as the OpenID Connect (OIDC) provider.

Warning

Red Hat recommends not to use Ansible logging in verbose or debugging mode for production environments.

For more information, see the Ansible documentation.

Prerequisites

  • Red Hat Enterprise Linux version 9.4 or later.
  • A Red Hat user account to access the Red Hat Hybrid Cloud Console.

Procedure

  1. Log in to the Red Hat Hybrid Cloud Console with your Red Hat credentials.
  2. From the home page, click the Services drop-down menu, and click Red Hat Ansible Automation Platform.
  3. From the navigational menu, expand Automation Hub, and click Collections.
  4. In the search field type rhtas and press enter.
  5. Click the artifact_signer link on the Red Hat Trusted Artifact Signer tile.

  6. Click the Documentation tab, and follow the steps there to complete the installation of RHTAS on Red Hat Enterprise Linux.

    Note

    For a detailed overview of all the configuration parameters, click the tas_single_node link under the Roles section.

Additional resources

  • See the Appendix in the RHTAS Deployment Guide for more information about RHTAS components and version numbers.

2.2. Verify the Trusted Artifact Signer installation

As as systems administrator, you can verify if the deployment of Red Hat Trusted Artifact Signer (RHTAS) running on Red Hat Enterprise Linux.

You can sign a test container image, and verify the authenticity of that signature to validate the deployment of RHTAS in your environment.

There are two ways to sign and three ways to verify build artifacts from your code pipeline. You can sign and verify with cosign and gitsign, but can only verify with Enterprise Contract.

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

  • Installation of RHTAS running on Red Hat Enterprise Linux 9.4 or later managed by Ansible.
  • A workstation with the podman binary installed.

Procedure

  1. Download the cosign binary from the local command-line interface (CLI) tool download page to your workstation.

    Note

    The URL address is the configured node as defined by the tas_single_node_base_hostname variable. An example URL address would be, https://cli-server.example.com, given the tas_single_node_base_hostname value as example.com.

    1. From the download page, 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. Configure your shell environment for doing container image signing and verifying.

    Example

    export BASE_HOSTNAME=BASE_HOSTNAME_OF_RHTAS_SERVICE
export TUF_URL="https://tuf.${BASE_HOSTNAME}"
export OIDC_ISSUER_URL=OIDC_ISSUER_URL
export COSIGN_FULCIO_URL="https://fulcio.${BASE_HOSTNAME}"
export COSIGN_REKOR_URL="https://rekor.${BASE_HOSTNAME}"
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

    Replace BASE_HOSTNAME_OF_RHTAS_SERVICE with the value of the tas_single_node_base_hostname` variable, and replace OIDC_ISSUER_URL with your OpenID Connect (OIDC) provider’s URL string.

  3. Initialize The Update Framework (TUF) system:

    Example

    cosign initialize

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

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

  6. Download the rekor-cli binary from the local command-line interface (CLI) tool download page to your workstation.

    1. Open a web browser, and go to the CLI server web page.

      Note

      The URL address is the configured node as defined by the tas_single_node_base_hostname variable. An example URL address would be, https://cli-server.example.com, given that the value of tas_single_node_base_hostname is example.com.

    2. From the download page, go to the rekor-cli download section, and click the link for your platform.

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

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

      Example

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

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

  • Installation of RHTAS running on Red Hat Enterprise Linux 9.4 or later managed by Ansible.

  • A workstation with the git, and cosign binaries installed.

    • You must use cosign version 2.2 or later.

Procedure

  1. Download the gitsign binary from the local command-line interface (CLI) tool download page to your workstation.

    Note

    The URL address is the configured node as defined by the tas_single_node_base_hostname variable. An example URL address would be, https://cli-server.example.com, given the tas_single_node_base_hostname value as example.com.

    1. From the download page, 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. Configure your shell environment for doing commit signing and verifying.

    Example

    export BASE_HOSTNAME=BASE_HOSTNAME_OF_RHTAS_SERVICE
export TUF_URL="https://tuf.${BASE_HOSTNAME}"
export OIDC_ISSUER_URL=OIDC_ISSUER_URL
export COSIGN_FULCIO_URL="https://fulcio.${BASE_HOSTNAME}"
export COSIGN_REKOR_URL="https://rekor.${BASE_HOSTNAME}"
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

    Replace BASE_HOSTNAME_OF_RHTAS_SERVICE with the value of the tas_single_node_base_hostname` variable, and replace OIDC_ISSUER_URL with your OpenID Connect (OIDC) provider’s URL string.

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

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

  5. Initialize The Update Framework (TUF) system:

    Example

    cosign initialize

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

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

  • Installation of RHTAS running on Red Hat Enterprise Linux 9.4 or later managed by Ansible.

  • A workstation with the cosign, and podman binaries installed.

    • You must use cosign version 2.2 or later.

Procedure

  1. Download the ec binary from the local command-line interface (CLI) tool download page to your workstation.

    Note

    The URL address is the configured node as defined by the tas_single_node_base_hostname variable. An example URL address would be, https://cli-server.example.com, given the tas_single_node_base_hostname value as example.com.

    1. From the download page, go to the ec 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 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. Configure your shell environment for doing container image signing and verifying.

    Example

    export BASE_HOSTNAME=BASE_HOSTNAME_OF_RHTAS_SERVICE
export TUF_URL="https://tuf.${BASE_HOSTNAME}"
export OIDC_ISSUER_URL=OIDC_ISSUER_URL
export COSIGN_FULCIO_URL="https://fulcio.${BASE_HOSTNAME}"
export COSIGN_REKOR_URL="https://rekor.${BASE_HOSTNAME}"
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

    Replace BASE_HOSTNAME_OF_RHTAS_SERVICE with the value of the tas_single_node_base_hostname` variable, and replace OIDC_ISSUER_URL with your OpenID Connect (OIDC) provider’s URL string.

  3. Initialize The Update Framework (TUF) system:

    Example

    cosign initialize

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

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

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

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

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

Additional Resources

  • See the Enterprise Contract website for more information.
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. Explore our recent updates.

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.