Chapter 2. Red Hat Enterprise Linux

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 execution bit:

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

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

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

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

   $ 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:

   $ cosign initialize

4. Sign a test container image.

   1. Create an empty container image:

      $ 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:

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

   3. Sign the container image:

      cosign sign -y IMAGE_NAME:TAG

      $ 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:

      $ rm ./tmp.Dockerfile

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

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

   $ 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 execution bit:

      $ gunzip rekor-cli-amd64.gz
      $ chmod +x rekor-cli-amd64

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

      $ 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:

      $ 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):

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

      $ 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:

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

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

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 execution bit:

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

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

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

2. Configure your shell environment for doing commit signing and verifying.

   $ 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. Change directory (cd) to the local Git repository directory.

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

   $ 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:

   $ 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:

   $ cosign initialize

7. Verify the commit:

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

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

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 execution bit:

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

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

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

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

   $ 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:

   $ cosign initialize

4. Sign a test container image.

   1. Create an empty container image:

      $ 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:

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

   3. Sign the container image:

      cosign sign -y IMAGE_NAME:TAG

      $ 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:

      $ rm ./tmp.Dockerfile

5. Create a predicate.json file:

   {
     "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:

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

   $ 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:

   cosign tree IMAGE_NAME:TAG

   $ 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 Conforma:

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

   $ ec validate image --image ttl.sh/rhtas/test-image:1h --certificate-identity-regexp 'jdoe@example.com' --certificate-oidc-issuer-regexp '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.