Chapter 2. Red Hat Enterprise Linux

Procedure

1. Open for editing the RHTAS Ansible Playbook.

2. Under the tas_single_node_backup_restore.backup section, set the enabled variable to true:

   tas_single_node_backup_restore:
     backup:
       enabled: true

   Copy to Clipboard Toggle word wrap

3. By default, a daily backup job runs at midnight every day. You can change this to better fit your schedule.

   tas_single_node_backup_restore:
     backup:
       enabled: true
       schedule: "*-*-* 00:00:00"

   Copy to Clipboard Toggle word wrap

4. Set a passphrase, and specify the local backup directory:

   tas_single_node_backup_restore:
     backup:
       enabled: true
       schedule: "*-*-* 00:00:00"
       force_run: false
       passphrase: "example123"
       directory: /root/tas_backups

   Copy to Clipboard Toggle word wrap
5. Optional. To start an immediate backup job, set the force_run variable to true.
6. Save the changes, and quit the editor.

7. Run the RHTAS Ansible Playbook to apply the changes:

   ansible-playbook -i inventory play.yml

   Copy to Clipboard Toggle word wrap

   After the backup finishes, the resulting encrypted, and compressed file name format is, BACKUP-<date-and-time>-UTC.tar.gz.enc.

Procedure

1. Copy the backup data file to a directory on the Ansible control node.
2. Open for editing the RHTAS Ansible Playbook.

3. Under the tas_single_node_backup_restore.restore section, set the enabled variable to true:

   tas_single_node_backup_restore:
     ...
     restore:
       enabled: true

   Copy to Clipboard Toggle word wrap

4. Specify the source location of the backup file, and give the correct passphrase:

   tas_single_node_backup_restore:
     ...
     restore:
       enabled: true
       source: "PATH_TO_BACKUP_FILE"
       passphrase: "example123"

   Copy to Clipboard Toggle word wrap
5. Under the tas_single_node_backup_restore.backup section, verify that the force_run variable to false. If the force_run variable to true, then set it to false.

6. . Run the RHTAS Ansible Playbook to apply the changes:

   $ ansible-playbook -i inventory play.yml

   Copy to Clipboard Toggle word wrap

   The restoration process starts, and does a re-execution of all tasks to validate the integrity of the RHTAS service.

Procedure

1. Download the tuftool 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.

   Important

   Currently, the tuftool binary is only available for Linux operating systems on the x86_64 architecture.

   1. From the download page, go to the tuftool 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 tuftool-amd64.gz
      $ chmod +x tuftool-amd64

      Copy to Clipboard Toggle word wrap

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

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

      Copy to Clipboard Toggle word wrap

2. Configure your shell environment:

   $ export WORK="${HOME}/trustroot-example"
   $ export ROOT="${WORK}/root/root.json"
   $ export KEYDIR="${WORK}/keys"
   $ export INPUT="${WORK}/input"
   $ export TUF_REPO="${WORK}/tuf-repo"
   $ export MANAGED_NODE_IP=IP_OF_ANSIBLE_MANAGED_NODE
   $ export MANAGED_NODE_SSH_USER=USER_TO_CONNECT_TO_MANAGED_NODE
   $ export REMOTE_KEYS_VOLUME=$(ssh ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP} -t "sudo podman volume mount tuf-signing-keys" | tr -d '[:space:]')
   $ export REMOTE_TUF_VOLUME=$(ssh ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP} -t "sudo podman volume mount tuf-repository" | tr -d '[:space:]')
   $ export TIMESTAMP_EXPIRATION="in 10 days"
   $ export SNAPSHOT_EXPIRATION="in 26 weeks"
   $ export TARGETS_EXPIRATION="in 26 weeks"
   $ export ROOT_EXPIRATION="in 26 weeks"

   Copy to Clipboard Toggle word wrap

   Replace IP_OF_ANSIBLE_MANAGED_NODE and USER_TO_CONNECT_TO_MANAGED_NODE with your relevant values.

   Set the expiration durations according to your requirements.

3. Create a temporary TUF directory structure:

   $ mkdir -p "${WORK}/root/" "${KEYDIR}" "${INPUT}" "${TUF_REPO}"

   Copy to Clipboard Toggle word wrap

4. Download the TUF contents to the temporary TUF directory structure:

   $ rsync -r --rsync-path="sudo rsync" ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP}:"${REMOTE_KEYS_VOLUME}/" "${KEYDIR}"
   $ rsync -r --rsync-path="sudo rsync" ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP}:"${REMOTE_TUF_VOLUME}/" "${TUF_REPO}"
   $ cp "${TUF_REPO}/root.json" "${ROOT}"

   Copy to Clipboard Toggle word wrap

5. You can update the timestamp, snapshot, and targets metadata all in one command:

   $ tuftool update \
     --root "${ROOT}" \
     --key "${KEYDIR}/timestamp.pem" \
     --key "${KEYDIR}/snapshot.pem" \
     --key "${KEYDIR}/targets.pem" \
     --timestamp-expires "${TIMESTAMP_EXPIRATION}" \
     --snapshot-expires "${SNAPSHOT_EXPIRATION}" \
     --targets-expires "${TARGETS_EXPIRATION}" \
     --outdir "${TUF_REPO}" \
     --metadata-url "file://${TUF_REPO}"

   Copy to Clipboard Toggle word wrap
   Note

   You can also run the TUF metadata update on a subset of TUF metadata files. For example, the timestamp.json metadata file expires more often than the other metadata files. Therefore, you can just update the timestamp metadata file by running the following command:

   $ tuftool update \
     --root "${ROOT}" \
     --key "${KEYDIR}/timestamp.pem" \
     --timestamp-expires "${TIMESTAMP_EXPIRATION}" \
     --outdir "${TUF_REPO}" \
     --metadata-url "file://${TUF_REPO}"

   Copy to Clipboard Toggle word wrap

6. Only update the root expiration date if it is about to expire:

   $ tuftool root expire "${ROOT}" "${ROOT_EXPIRATION}"

   Copy to Clipboard Toggle word wrap
   Note

   You can skip this step if the root file is not close to expiring.

7. Update the root version:

   $ tuftool root bump-version "${ROOT}"

   Copy to Clipboard Toggle word wrap

8. Sign the root metadata file again:

   $ tuftool root sign "${ROOT}" -k "${KEYDIR}/root.pem"

   Copy to Clipboard Toggle word wrap

9. Set the new root version, and copy the root metadata file in place:

   $ export NEW_ROOT_VERSION=$(cat "${ROOT}" | jq -r ".signed.version")
   $ cp "${ROOT}" "${TUF_REPO}/root.json"
   $ cp "${ROOT}" "${TUF_REPO}/${NEW_ROOT_VERSION}.root.json"

   Copy to Clipboard Toggle word wrap

10. Upload these changes to the TUF server.

    1. Create a compressed archive of the TUF repository:

       $ tar -C "${WORK}" -czvf repository.tar.gz tuf-repo

       Copy to Clipboard Toggle word wrap

    2. Update the RHTAS Ansible Playbook with these two lines:

       tas_single_node_trust_root:
         full_archive: "{{ lookup('file', 'repository.tar.gz') | b64encode }}"

       Copy to Clipboard Toggle word wrap

    3. Run the RHTAS Anisble Playbook to apply the changes:

       $ ansible-playbook -i inventory play.yml

       Copy to Clipboard Toggle word wrap

Procedure

1. 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. From a terminal on your workstation, decompress the binary .gz file, and set the execute bit:

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

      Copy to Clipboard Toggle word wrap

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

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

      Copy to Clipboard Toggle word wrap

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

   Important

   Currently, the tuftool binary is only available for Linux operating systems on the x86_64 architecture.

   1. From the download page, go to the tuftool download section, and click the link for your platform.

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

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

      Copy to Clipboard Toggle word wrap

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

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

      Copy to Clipboard Toggle word wrap

3. Assign shell variables to the base hostname, and the Rekor URL:

   $ export BASE_HOSTNAME=BASE_HOSTNAME_OF_RHTAS_SERVICE
   $ export REKOR_URL=https://rekor.${BASE_HOSTNAME}

   Copy to Clipboard Toggle word wrap

   Replace BASE_HOSTNAME_OF_RHTAS_SERVICE with the value of the tas_single_node_base_hostname variable.

4. Get the log tree identifier for the active shard:

   $ export OLD_TREE_ID=$(rekor-cli loginfo --rekor_server $REKOR_URL --format json | jq -r .TreeID)

   Copy to Clipboard Toggle word wrap

5. Configure your shell environment:

   $ export MANAGED_NODE_IP=IP_OF_ANSIBLE_MANAGED_NODE
   $ export MANAGED_NODE_SSH_USER=USER_TO_CONNECT_TO_MANAGED_NODE
   $ export REMOTE_KEYS_VOLUME=$(ssh ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP} -t "sudo podman volume mount tuf-signing-keys" | tr -d '[:space:]')
   $ export REMOTE_TUF_VOLUME=$(ssh ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP} -t "sudo podman volume mount tuf-repository" | tr -d '[:space:]')

   Copy to Clipboard Toggle word wrap

   Replace IP_OF_ANSIBLE_MANAGED_NODE and USER_TO_CONNECT_TO_MANAGED_NODE with values for your environment.

6. Set the log tree to the DRAINING state:

   $ ssh ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP} -t "sudo podman run --network=rhtas --rm registry.redhat.io/rhtas/updatetree-rhel9:1.1.0 --admin_server=trillian-logserver-pod:8091 --tree_id=${OLD_TREE_ID} --tree_state=DRAINING"

   Copy to Clipboard Toggle word wrap

   While draining, the tree log will not accept any new entries. Watch and wait for the queue to empty.

   Important

   You must wait for the queues to be empty before proceeding to the next step. If leaves are still integrating while draining, then freezing the log tree during this process can cause the log path to exceed the maximum merge delay (MMD) threshold.

7. Freeze the log tree:

   $ ssh ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP} -t "sudo podman run --network=rhtas --rm registry.redhat.io/rhtas/updatetree-rhel9:1.1.0 --tree_id=${OLD_TREE_ID} --admin_server=trillian-logserver-pod:8091 --tree_state=FROZEN"

   Copy to Clipboard Toggle word wrap

8. Get the length of the frozen log tree:

   $ export OLD_SHARD_LENGTH=$(rekor-cli loginfo --rekor_server $REKOR_URL --format json | jq -r .ActiveTreeSize)

   Copy to Clipboard Toggle word wrap

9. Get Rekor’s public key for the old shard:

   $ export OLD_PUBLIC_KEY=$(curl -s $REKOR_URL/api/v1/log/publicKey | base64 | tr -d '\n')

   Copy to Clipboard Toggle word wrap

10. Create a new log tree:

    $ export NEW_TREE_ID=$(ssh ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP} -t "sudo podman run -q --network=rhtas --rm registry.redhat.io/rhtas/createtree-rhel9:1.1.0 --logtostderr=false --admin_server=trillian-logserver-pod:8091 --display_name=rekor-tree | tr -d '[:punct:][:blank:][:cntrl:]'")

    Copy to Clipboard Toggle word wrap

    Now you have two log trees, one frozen tree, and a new tree that will become the active shard.

11. Create a new private key and an associated public key:

    $ openssl ecparam -genkey -name secp384r1 -noout -out new-rekor.pem
    $ openssl ec -in new-rekor.pem -pubout -out new-rekor.pub
    $ export NEW_KEY_NAME=new-rekor.pub

    Copy to Clipboard Toggle word wrap
    Important

    The new key must have a unique file name.

12. Get the active Rekor signing key, and save the key to a file:

    $ rsync --rsync-path="sudo rsync" ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP}:/etc/rhtas/certs/rekor-signer0.key ./rekor-signer0.key
    echo "$OLD_PUBLIC_KEY" | base64 -d > rekor.pub

    Copy to Clipboard Toggle word wrap

13. Update the Rekor configuration in the RHTAS Ansible playbook:

    tas_single_node_rekor:
      active_signer_id: "new-rekor-key"
      active_tree_id: NEW_TREE_ID
      private_keys:
        - id: "new-rekor-key"
          key: |
            {{ lookup('file', 'new-rekor.pem') }}
        - id: "private-0"
          key: |
            {{ lookup('file', 'rekor-signer0.key') }}
      public_keys:
        - id: "new-rekor-pubkey"
          key: |
            {{ lookup('file', 'new-rekor.pub') }}
        - id: "public-0"
          key: |
            {{ lookup('file', 'rekor.pub') }}
      sharding_config:
        - tree_id: OLD_TREE_ID
          tree_length: OLD_SHARD_LENGTH
          pem_pub_key: "public-0"

    Copy to Clipboard Toggle word wrap

14. Configure The Update Framework (TUF) service to use the new Rekor public key.

    1. Configure your shell environment:

       $ export WORK="${HOME}/trustroot-example"
       $ export ROOT="${WORK}/root/root.json"
       $ export KEYDIR="${WORK}/keys"
       $ export INPUT="${WORK}/input"
       $ export TUF_REPO="${WORK}/tuf-repo"
       $ export TUF_URL="https://tuf.${BASE_HOSTNAME}"

       Copy to Clipboard Toggle word wrap

    2. Create a temporary TUF directory structure:

       $ mkdir -p "${WORK}/root/" "${KEYDIR}" "${INPUT}" "${TUF_REPO}"

       Copy to Clipboard Toggle word wrap

    3. Download the TUF contents to the temporary TUF directory structure:

       $ rsync -r --rsync-path="sudo rsync" ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP}:"${REMOTE_KEYS_VOLUME}/" "${KEYDIR}"
       $ rsync -r --rsync-path="sudo rsync" ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP}:"${REMOTE_TUF_VOLUME}/" "${TUF_REPO}"
       $ cp "${TUF_REPO}/root.json" "${ROOT}"

       Copy to Clipboard Toggle word wrap

    4. Assign an environment variable to the active Rekor signer key file name:

       $ export ACTIVE_KEY_NAME=rekor.pub

       Copy to Clipboard Toggle word wrap

    5. Expire the old Rekor signer key:

       $ tuftool rhtas \
         --root "${ROOT}" \
         --key "${KEYDIR}/snapshot.pem" \
         --key "${KEYDIR}/targets.pem" \
         --key "${KEYDIR}/timestamp.pem" \
         --set-rekor-target "${ACTIVE_KEY_NAME}" \
         --rekor-uri "${REKOR_URL}" \
         --rekor-status "Expired" \
         --outdir "${TUF_REPO}" \
         --metadata-url "file://${TUF_REPO}"

       Copy to Clipboard Toggle word wrap

    6. Add the new Rekor signer key:

       $ tuftool rhtas \
         --root "${ROOT}" \
         --key "${KEYDIR}/snapshot.pem" \
         --key "${KEYDIR}/targets.pem" \
         --key "${KEYDIR}/timestamp.pem" \
         --set-rekor-target "${NEW_KEY_NAME}" \
         --rekor-uri "${REKOR_URL}" \
         --outdir "${TUF_REPO}" \
         --metadata-url "file://${TUF_REPO}"

       Copy to Clipboard Toggle word wrap

    7. Create a compressed archive file of the updated TUF repository:

       $ tar -C "${WORK}" -czvf repository.tar.gz tuf-repo

       Copy to Clipboard Toggle word wrap

    8. Update the RHTAS Ansible playbook by adding the new compressed archive file name to the tas_single_node_trust_root variable:

       tas_single_node_trust_root:
         full_archive: "{{ lookup('file', 'repository.tar.gz') | b64encode }}"

       Copy to Clipboard Toggle word wrap

    9. Delete the working directory:

       $ rm -r $WORK

       Copy to Clipboard Toggle word wrap

15. Run the RHTAS Ansible Playbook to apply the changes:

    $ ansible-playbook -i inventory play.yml

    Copy to Clipboard Toggle word wrap

16. Update the cosign configuration with the updated TUF configuration:

    $ cosign initialize --mirror=$TUF_URL --root=$TUF_URL/root.json

    Copy to Clipboard Toggle word wrap

    Now, you are ready to sign and verify your artifacts with the new Rekor signer key.

Procedure

1. Download the tuftool 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.

   Important

   Currently, the tuftool binary is only available for Linux operating systems on the x86_64 architecture.

   1. From the download page, go to the tuftool 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:

      $ unzip tuftool-amd64.gz
      $ chmod +x tuftool-amd64

      Copy to Clipboard Toggle word wrap

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

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

      Copy to Clipboard Toggle word wrap

2. Configure your shell environment:

   $ export MANAGED_NODE_IP=IP_OF_ANSIBLE_MANAGED_NODE
   $ export MANAGED_NODE_SSH_USER=USER_TO_CONNECT_TO_MANAGED_NODE
   $ export REMOTE_KEYS_VOLUME=$(ssh ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP} -t "sudo podman volume mount tuf-signing-keys" | tr -d '[:space:]')
   $ export REMOTE_TUF_VOLUME=$(ssh ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP} -t "sudo podman volume mount tuf-repository" | tr -d '[:space:]')
   $ export BASE_HOSTNAME=BASE_HOSTNAME_OF_RHTAS_SERVICE

   Copy to Clipboard Toggle word wrap

   Replace BASE_HOSTNAME_OF_RHTAS_SERVICE with the value of the tas_single_node_base_hostname variable.

3. Download the CTlog configuration map, the CTlog keys, and the Fulcio root certificate to your workstation:

   $ rsync --rsync-path="sudo rsync" ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP}:/etc/rhtas/configs/ctlog-config.yaml ./ctlog-config.yaml
   $ rsync --rsync-path="sudo rsync" ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP}:/etc/rhtas/certs/ctlog0.key ./ctfe.key
   $ rsync --rsync-path="sudo rsync" ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP}:/etc/rhtas/certs/ctlog0.pub ./ctfe.pub
   $ rsync --rsync-path="sudo rsync" ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP}:/etc/rhtas/certs/fulcio.pem ./fulcio-0.pem

   Copy to Clipboard Toggle word wrap

4. Capture the current tree identifier:

   $ export OLD_TREE_ID=$(ssh ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP} -t "sudo cat /etc/rhtas/configs/ctlog-treeid-config.yaml | grep 'tree_id:' | awk '{print \$2}'" | tr -d '[:punct:][:blank:][:cntrl:]')

   Copy to Clipboard Toggle word wrap

5. Set the log tree to the DRAINING state:

   $ ssh ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP} -t "sudo podman run --network=rhtas --rm registry.redhat.io/rhtas/updatetree-rhel9:1.1.0 --tree_id=${OLD_TREE_ID} --admin_server=trillian-logserver-pod:8091 --tree_state=DRAINING"

   Copy to Clipboard Toggle word wrap

   While draining, the tree log will not accept any new entries. Watch and wait for the queue to empty.

   Important

   You must wait for the queues to be empty before proceeding to the next step. If leaves are still integrating while draining, then freezing the log tree during this process can cause the log path to exceed the maximum merge delay (MMD) threshold.

6. Once the queue has been fully drained, freeze the log:

   $ ssh ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP} -t "sudo podman run --network=rhtas --rm registry.redhat.io/rhtas/updatetree-rhel9:1.1.0 --tree_id=${OLD_TREE_ID} --admin_server=trillian-logserver-pod:8091 --tree_state=FROZEN"

   Copy to Clipboard Toggle word wrap

7. Create a new Merkle tree, and capture the new tree identifier:

   $ export NEW_TREE_ID=$(ssh ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP} -t "sudo podman run -q --network=rhtas --rm registry.redhat.io/rhtas/createtree-rhel9:1.1.0 --logtostderr=false --admin_server=trillian-logserver-pod:8091 --display_name=ctlog-tree" | tr -d '[:punct:][:blank:][:cntrl:]')

   Copy to Clipboard Toggle word wrap

8. Generate a new certificate, along with new public and private keys:

   $ openssl ecparam -genkey -name prime256v1 -noout -out new-ctlog.pem
   $ openssl ec -in new-ctlog.pem -pubout -out new-ctlog-public.pem
   $ openssl ec -in new-ctlog.pem -out new-ctlog.pass.pem -des3 -passout pass:"CHANGE_ME"

   Copy to Clipboard Toggle word wrap

   Replace CHANGE_ME with a new password.

   Important

   The certificate and new keys must have unique file names.

9. Update the CT log configuration.

   1. Open the RHTAS Ansible playbook for editing.

   2. Configuring the CTlog signer key rotation for the first time, you need to add the following to the tas_single_node_ctlog.sharding_config section:

      tas_single_node_ctlog:
        sharding_config:
          - treeid: OLD_TREE_ID # frozen log
            prefix: "rhtasansible"
            private_key: "private-0"
            password: "rhtas"
            root_pem_file: "/ctfe-keys/fulcio-0"
            not_after_limit:
              seconds: 1728056285
              nanos: 012111000

      Copy to Clipboard Toggle word wrap

      Replace OLD_TREE_ID with the contents contained in the $OLD_TREE_ID environment variable.

      Note

      You can get the current time value for seconds and nanoseconds, by running the following commands: date +%s, and date +%N.

      Important

      The not_after_limit field defines the end of the timestamp range for the frozen log only. Certificates beyond this point in time are no longer accepted for inclusion in this log.

   3. Copy and paste the frozen log block, appending it to the tas_single_node_ctlog.sharding_config section, creating a new entry.

   4. Change the following lines in the new log block. Set the treeid to the new tree identifier, change the prefix to trusted-artifact-signer, change the private_key path to private-1, change not_after_limit to not_after_start, set the timestamp range, and update tas_single_node_fulcio.ct_log_prefix for Fulcio to make use of the new log:

      tas_single_node_ctlog:
        sharding_config:
           ... # frozen log
           - treeid: NEW_TREE_ID # new active log
             prefix: "trusted-artifact-signer"
             private_key: "private-1"
             password: "CHANGE_ME"
             root_pem_file: "/ctfe-keys/fulcio-0"
             not_after_start:
               seconds: 1713201754
               nanos: 155663000
      tas_single_node_fulcio:
        ct_log_prefix: "trusted-artifact-signer"

      Copy to Clipboard Toggle word wrap

      Replace CHANGE_ME with the new private key password. The password here must match the password used for generating the new private and public keys.

      Important

      The not_after_start field defines the beginning of the timestamp range inclusively. This means the log will start accepting certificates at this point in time.

10. Update the tas_single_node_ctlog section for CTlog to distribute the new keys to the managed node:

    tas_single_node_ctlog:
      ...
      private_keys:
        - id: private-0
          key: |
            {{ lookup('file', 'ctfe.key') }}
        - id: private-1
          key: |
            {{ lookup('file', 'new-ctlog.pass.pem') }}
      public_keys:
        - id: public-0
          key: |
            {{ lookup('file', 'ctfe.pub') }}
        - id: public-1
          key: |
            {{ lookup('file', 'new-ctlog-public.pem') }}

    Copy to Clipboard Toggle word wrap

11. Configure The Update Framework (TUF) service to use the new CT log public key.

    1. Configure your shell environment:

       $ export WORK="${HOME}/trustroot-example"
       $ export ROOT="${WORK}/root/root.json"
       $ export KEYDIR="${WORK}/keys"
       $ export INPUT="${WORK}/input"
       $ export TUF_REPO="${WORK}/tuf-repo"
       $ export TUF_URL="https://tuf.${BASE_HOSTNAME}"

       Copy to Clipboard Toggle word wrap

    2. Create a temporary TUF directory structure:

       $ mkdir -p "${WORK}/root/" "${KEYDIR}" "${INPUT}" "${TUF_REPO}"

       Copy to Clipboard Toggle word wrap

    3. Download the TUF contents to the temporary TUF directory structure:

       $ rsync -r --rsync-path="sudo rsync" ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP}:"${REMOTE_KEYS_VOLUME}/" "${KEYDIR}"
       $ rsync -r --rsync-path="sudo rsync" ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP}:"${REMOTE_TUF_VOLUME}/" "${TUF_REPO}"
       $ cp "${TUF_REPO}/root.json" "${ROOT}"

       Copy to Clipboard Toggle word wrap

    4. Assign an environment variable to the active CT log signer key file name:

       $ export ACTIVE_CTFE_NAME=ctfe.pub

       Copy to Clipboard Toggle word wrap

    5. Expire the old CT log signer key:

       $ tuftool rhtas \
         --root "${ROOT}" \
         --key "${KEYDIR}/snapshot.pem" \
         --key "${KEYDIR}/targets.pem" \
         --key "${KEYDIR}/timestamp.pem" \
         --set-ctlog-target "$ACTIVE_CTFE_NAME" \
         --ctlog-uri "https://ctlog.rhtas" \
         --ctlog-status "Expired" \
         --outdir "${TUF_REPO}" \
         --metadata-url "file://${TUF_REPO}"

       Copy to Clipboard Toggle word wrap

    6. Add the new CT log signer key:

       $ tuftool rhtas \
         --root "${ROOT}" \
         --key "${KEYDIR}/snapshot.pem" \
         --key "${KEYDIR}/targets.pem" \
         --key "${KEYDIR}/timestamp.pem" \
         --set-ctlog-target "new-ctlog-public.pem" \
         --ctlog-uri "https://ctlog.rhtas" \
         --outdir "${TUF_REPO}" \
         --metadata-url "file://${TUF_REPO}"

       Copy to Clipboard Toggle word wrap

    7. Create a compressed archive file of the updated TUF repository:

       $ tar -C "${WORK}" -czvf repository.tar.gz tuf-repo

       Copy to Clipboard Toggle word wrap

    8. Update the RHTAS Ansible playbook by adding the new compressed archive file name to the tas_single_node_trust_root variable:

       tas_single_node_trust_root:
         full_archive: "{{ lookup('file', 'repository.tar.gz') | b64encode }}"

       Copy to Clipboard Toggle word wrap
    9. Save the changes to the playbook, and close your text editor.

12. Run the RHTAS Ansible playbook to apply the changes:

    $ ansible-playbook -i inventory play.yml

    Copy to Clipboard Toggle word wrap

13. Delete the working directory:

    $ rm -r $WORK

    Copy to Clipboard Toggle word wrap

14. Update the cosign configuration with the updated TUF configuration:

    $ cosign initialize --mirror=$TUF_URL --root=$TUF_URL/root.json

    Copy to Clipboard Toggle word wrap

    Now, you are ready to sign and verify your artifacts with the new CT log signer key.

Procedure

1. Download the tuftool 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.

   Important

   Currently, the tuftool binary is only available for Linux operating systems on the x86_64 architecture.

   1. From the download page, go to the tuftool 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 tuftool-amd64.gz
      $ chmod +x tuftool-amd64

      Copy to Clipboard Toggle word wrap

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

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

      Copy to Clipboard Toggle word wrap

2. Generate a new certificate, along with new public and private keys:

   $ openssl ecparam -genkey -name prime256v1 -noout -out new-fulcio.pem
   $ openssl ec -in new-fulcio.pem -pubout -out new-fulcio-public.pem
   $ openssl ec -in new-fulcio.pem -out new-fulcio.pass.pem -des3 -passout pass:"CHANGE_ME"
   $ openssl req -new -x509 -key new-fulcio.pass.pem -out new-fulcio.cert.pem

   Copy to Clipboard Toggle word wrap

   Replace CHANGE_ME with a new password.

   Important

   The certificate and new keys must have unique file names.

3. Update the RHTAS Ansible playbook by adding the new private key file name, the new certificate content, and the password to the tas_single_node_fulcio variable:

   tas_single_node_fulcio:
     root_ca: "{{ lookup('file', 'new-fulcio.cert.pem') }}"
     private_key: "{{ lookup('file', 'new-fulcio.pass.pem') }}"
     ca_passphrase: CHANGE_ME

   Copy to Clipboard Toggle word wrap

   Replace CHANGE_ME with a new password.

   Note

   The password here must match the password used for generating the new private and public keys.

   Note

   We recommend sourcing the passphrase either from a file or encrypted by using Ansible Vault.

4. Configure The Update Framework (TUF) service to use the new Fulcio certificate.

   1. Set up your shell environment:

      $ export WORK="${HOME}/trustroot-example"
      $ export ROOT="${WORK}/root/root.json"
      $ export KEYDIR="${WORK}/keys"
      $ export INPUT="${WORK}/input"
      $ export TUF_REPO="${WORK}/tuf-repo"
      $ export TUF_URL="https://tuf.${BASE_HOSTNAME}"
      $ export MANAGED_NODE_IP=IP_OF_ANSIBLE_MANAGED_NODE
      $ export MANAGED_NODE_SSH_USER=USER_TO_CONNECT_TO_MANAGED_NODE
      $ export REMOTE_KEYS_VOLUME=$(ssh ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP} -t "sudo podman volume mount tuf-signing-keys" | tr -d '[:space:]')
      $ export REMOTE_TUF_VOLUME=$(ssh ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP} -t "sudo podman volume mount tuf-repository" | tr -d '[:space:]')

      Copy to Clipboard Toggle word wrap

   2. Create a temporary TUF directory structure:

      $ mkdir -p "${WORK}/root/" "${KEYDIR}" "${INPUT}" "${TUF_REPO}"

      Copy to Clipboard Toggle word wrap

   3. Download the TUF contents to the temporary TUF directory structure:

      $ rsync -r --rsync-path="sudo rsync" ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP}:"${REMOTE_KEYS_VOLUME}/" "${KEYDIR}"
      $ rsync -r --rsync-path="sudo rsync" ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP}:"${REMOTE_TUF_VOLUME}/" "${TUF_REPO}"
      $ cp "${TUF_REPO}/root.json" "${ROOT}"

      Copy to Clipboard Toggle word wrap

   4. Find the active Fulcio certificate file name. Open the latest target file, for example, 1.targets.json, within the local TUF repository. In this file you will find the active Fulcio certificate file name, for example, fulcio_v1.crt.pem. Set an environment variable with this active Fulcio certificate file name:

      $ export ACTIVE_CERT_NAME=fulcio_v1.crt.pem

      Copy to Clipboard Toggle word wrap

   5. Get the active Fulico certificate from the managed node:

      $ rsync -r --rsync-path="sudo rsync" ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP}:/etc/rhtas/certs/fulcio.pem "${ACTIVE_CERT_NAME}"

      Copy to Clipboard Toggle word wrap

   6. Expire the old certificate:

      $ tuftool rhtas \
        --root "${ROOT}" \
        --key "${KEYDIR}/snapshot.pem" \
        --key "${KEYDIR}/targets.pem" \
        --key "${KEYDIR}/timestamp.pem" \
        --set-fulcio-target "$ACTIVE_CERT_NAME" \
        --fulcio-uri "https://fulcio.rhtas" \
        --fulcio-status "Expired" \
        --outdir "${TUF_REPO}" \
        --metadata-url "file://${TUF_REPO}"

      Copy to Clipboard Toggle word wrap

   7. Add the new Fulcio certificate:

      $ tuftool rhtas \
        --root "${ROOT}" \
        --key "${KEYDIR}/snapshot.pem" \
        --key "${KEYDIR}/targets.pem" \
        --key "${KEYDIR}/timestamp.pem" \
        --set-fulcio-target "new-fulcio.cert.pem" \
        --fulcio-uri "https://fulcio.rhtas" \
        --outdir "${TUF_REPO}" \
        --metadata-url "file://${TUF_REPO}"

      Copy to Clipboard Toggle word wrap

   8. Create a compressed archive file of the updated TUF repository:

      $ tar -C "${WORK}" -czvf repository.tar.gz tuf-repo

      Copy to Clipboard Toggle word wrap

   9. Update the RHTAS Ansible playbook by adding the new compressed archive file content to the tas_single_node_trust_root variable:

      tas_single_node_trust_root:
        full_archive: "{{ lookup('file', 'repository.tar.gz') | b64encode }}"

      Copy to Clipboard Toggle word wrap

   10. Delete the working directory:

       $ rm -r $WORK

       Copy to Clipboard Toggle word wrap

5. Run the RHTAS Ansible Playbook to apply the changes:

   $ ansible-playbook -i inventory play.yml

   Copy to Clipboard Toggle word wrap

6. Update the cosign configuration with the updated TUF configuration:

   $ cosign initialize --mirror=$TUF_URL --root=$TUF_URL/root.json

   Copy to Clipboard Toggle word wrap

   Now, you are ready to sign and verify your artifacts with the new Fulcio certificate.

Procedure

1. Download the tuftool 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 that the value of tas_single_node_base_hostname is example.com.

   Important

   Currently, the tuftool binary is only available for Linux operating systems on the x86_64 architecture.

   1. From the download page, go to the tuftool 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 tuftool-amd64.gz
      $ chmod +x tuftool-amd64

      Copy to Clipboard Toggle word wrap

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

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

      Copy to Clipboard Toggle word wrap

2. Generate a new certificate chain, and a new signer key.

   Important

   The new certificate and keys must have unique file names.

   1. Create a temporary working directory:

      $ mkdir certs && cd certs

      Copy to Clipboard Toggle word wrap

   2. Create the root certificate authority (CA) private key, and set a password:

      $ openssl req -x509 -newkey rsa:2048 -days 365 -sha256 -nodes \
      -keyout rootCA.key.pem -out rootCA.crt.pem \
      -passout pass:"CHANGE_ME" \
      -subj "/C=CC/ST=state/L=Locality/O=RH/OU=RootCA/CN=RootCA" \
      -addext "basicConstraints=CA:true" -addext "keyUsage=cRLSign, keyCertSign"

      Copy to Clipboard Toggle word wrap

      Replace CHANGE_ME with a new password.

   3. Create the intermediate CA private key and certificate signing request (CSR), and set a password:

      $ openssl req -newkey rsa:2048 -sha256 \
      -keyout intermediateCA.key.pem -out intermediateCA.csr.pem \
      -passout pass:"CHANGE_ME" \
      -subj "/C=CC/ST=state/L=Locality/O=RH/OU=IntermediateCA/CN=IntermediateCA"

      Copy to Clipboard Toggle word wrap

      Replace CHANGE_ME with a new password.

   4. Sign the intermediate CA certificate with the root CA:

      $ openssl x509 -req -in intermediateCA.csr.pem -CA rootCA.crt.pem -CAkey rootCA.key.pem \
      -CAcreateserial -out intermediateCA.crt.pem -days 365 -sha256 \
      -extfile <(echo -e "basicConstraints=CA:true\nkeyUsage=cRLSign, keyCertSign\nextendedKeyUsage=critical,timeStamping") \
      -passin pass:"CHANGE_ME"

      Copy to Clipboard Toggle word wrap

      Replace CHANGE_ME with the root CA private key password to sign the intermediate CA certificate.

   5. Create the leaf CA private key and CSR, and set a password:

      $ openssl req -newkey rsa:2048 -sha256 \
      -keyout leafCA.key.pem -out leafCA.csr.pem \
      -passout pass:"CHANGE_ME" \
      -subj "/C=CC/ST=state/L=Locality/O=RH/OU=LeafCA/CN=LeafCA"

      Copy to Clipboard Toggle word wrap

   6. Sign the leaf CA certificate with the intermediate CA:

      $ openssl x509 -req -in leafCA.csr.pem -CA intermediateCA.crt.pem -CAkey intermediateCA.key.pem \
        -CAcreateserial -out leafCA.crt.pem -days 365 -sha256 \
        -extfile <(echo -e "basicConstraints=CA:false\nkeyUsage=cRLSign, keyCertSign\nextendedKeyUsage=critical,timeStamping") \
        -passin pass:"CHANGE_ME"

      Copy to Clipboard Toggle word wrap

      Replace CHANGE_ME with the intermediate CA private key password to sign the leaf CA certificate.

   7. Create the certificate chain by combining the newly created certificates together:

      $ cat leafCA.crt.pem intermediateCA.crt.pem rootCA.crt.pem > new-tsa.certchain.pem

      Copy to Clipboard Toggle word wrap

3. Update the RHTAS playbook with the new certificate chain, private key, and password:

   tas_single_node_tsa:
     certificate_chain: "{{ lookup('file', 'new-tsa.certchain.pem') }}"
     signer_private_key: "{{ lookup('file', 'leafCA.key.pem') }}"
     ca_passphrase: CHANGE_ME

   Copy to Clipboard Toggle word wrap

   Replace CHANGE_ME with the leaf CA private key password.

   Note

   Red Hat recommends sourcing the passphrase either from a file or encrypted by using Ansible Vault.

4. Find your active TSA certificate file name, the TSA URL string, and configure your shell environment with these values:

   $ export BASE_HOSTNAME=BASE_HOSTNAME_OF_RHTAS_SERVICE
   $ export ACTIVE_CERT_CHAIN_NAME=tsa.certchain.pem
   $ export TSA_URL=https://tsa.${BASE_HOSTNAME}/api/v1/timestamp
   $ curl $TSA_URL/certchain -o $ACTIVE_CERT_CHAIN_NAME

   Copy to Clipboard Toggle word wrap

5. Configure The Update Framework (TUF) service to use the new TSA certificate chain.

   1. Set up your shell environment:

      $ export WORK="${HOME}/trustroot-example"
      $ export ROOT="${WORK}/root/root.json"
      $ export KEYDIR="${WORK}/keys"
      $ export INPUT="${WORK}/input"
      $ export TUF_REPO="${WORK}/tuf-repo"
      $ export TUF_URL="https://tuf.${BASE_HOSTNAME}"
      $ export MANAGED_NODE_IP=IP_OF_ANSIBLE_MANAGED_NODE
      $ export MANAGED_NODE_SSH_USER=USER_TO_CONNECT_TO_MANAGED_NODE
      $ export NEW_CERT_CHAIN_NAME=new-tsa.certchain.pem

      Copy to Clipboard Toggle word wrap

   2. Create a temporary TUF directory structure:

      $ mkdir -p "${WORK}/root/" "${KEYDIR}" "${INPUT}" "${TUF_REPO}"

      Copy to Clipboard Toggle word wrap

   3. Download the TUF contents to the temporary TUF directory structure:

      $ export REMOTE_KEYS_VOLUME=$(ssh ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP} -t "sudo podman volume mount tuf-signing-keys" | tr -d '[:space:]')
      $ export REMOTE_TUF_VOLUME=$(ssh ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP} -t "sudo podman volume mount tuf-repository" | tr -d '[:space:]')
      $ rsync -r --rsync-path="sudo rsync" ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP}:"${REMOTE_KEYS_VOLUME}/" "${KEYDIR}"
      $ rsync -r --rsync-path="sudo rsync" ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP}:"${REMOTE_TUF_VOLUME}/" "${TUF_REPO}"
      $ cp "${TUF_REPO}/root.json" "${ROOT}"

      Copy to Clipboard Toggle word wrap

   4. Expire the old TSA certificate:

      $ tuftool rhtas \
        --root "${ROOT}" \
        --key "${KEYDIR}/snapshot.pem" \
        --key "${KEYDIR}/targets.pem" \
        --key "${KEYDIR}/timestamp.pem" \
        --set-tsa-target "$ACTIVE_CERT_CHAIN_NAME" \
        --tsa-uri "$TSA_URL" \
        --tsa-status "Expired" \
        --outdir "${TUF_REPO}" \
        --metadata-url "file://${TUF_REPO}"

      Copy to Clipboard Toggle word wrap

   5. Add the new TSA certificate:

      $ tuftool rhtas \
        --root "${ROOT}" \
        --key "${KEYDIR}/snapshot.pem" \
        --key "${KEYDIR}/targets.pem" \
        --key "${KEYDIR}/timestamp.pem" \
        --set-tsa-target "$NEW_CERT_CHAIN_NAME" \
        --tsa-uri "$TSA_URL" \
        --outdir "${TUF_REPO}" \
        --metadata-url "file://${TUF_REPO}"

      Copy to Clipboard Toggle word wrap

   6. Create a compressed archive file of the updated TUF repository:

      $ tar -C "${WORK}" -czvf repository.tar.gz tuf-repo

      Copy to Clipboard Toggle word wrap

   7. Update the RHTAS Ansible playbook by adding the new compressed archive file name to the tas_single_node_trust_root variable:

      tas_single_node_trust_root:
        full_archive: "{{ lookup('file', 'repository.tar.gz') | b64encode }}"

      Copy to Clipboard Toggle word wrap

   8. Delete the working directory:

      $ rm -r $WORK

      Copy to Clipboard Toggle word wrap

6. Run the RHTAS Ansible Playbook to apply the changes:

   $ ansible-playbook -i inventory play.yml

   Copy to Clipboard Toggle word wrap

7. Update the cosign configuration with the updated TUF configuration:

   $ cosign initialize --mirror=$TUF_URL --root=$TUF_URL/root.json

   Copy to Clipboard Toggle word wrap

   Now, you are ready to sign and verify your artifacts that uses the new TSA signer key, and certificate.