Rotating the Timestamp Authority signer key and certificate chain

You can proactively rotate the Timestamp Authority (TSA) signer key and certificate chain.

Before you begin

For OpenShift:

  • Installation of the RHTAS operator running on Red Hat OpenShift Container Platform.
  • A running Securesign instance.
  • A workstation with the oc and openssl binaries installed.

For Red Hat Enterprise Linux:

  • Installation of RHTAS running on Red Hat Enterprise Linux managed by Ansible.
  • A workstation with the rsync, openssl, and cosign binaries installed.
  • A SSH connection to the managed node, with root-level privileges on the managed node.

About this task

This procedure walks you through expiring your old TSA signer key and certificate chain, and replacing them with a new ones for Red Hat Trusted Artifact Signer (RHTAS) to use. Expiring your old TSA signer key and certificate chain still allows you to verify artifacts signed by the old key and certificate chain.

Procedure

  1. For OpenShift: Download the tufcli binary from the OpenShift cluster to your workstation.
    1. From the home page, click the ? icon, click Command line tools, go to the tufcli download section, and click the link for your platform.
  2. For Red Hat Enterprise Linux: Download the tufcli binary from the Red Hat developers portal.
    Note
    The binaries are available at Red Hat Trusted Artifact Signer download page.
    1. From the download page, go to the tufcli download section, and click the link for your platform.
  3. Open a terminal on your workstation, extract the .tar.gz archive, and set the execution bit: 
    $ tar -xzf tufcli_linux_amd64.tar.gz
$ chmod +x tufcli
  4. Move the binary to a location within your $PATH environment: 
    $ sudo mv tufcli /usr/local/bin/tufcli
  5. For OpenShift: Log in to OpenShift from the command line: 
    oc login --token=TOKEN --server=SERVER_URL_AND_PORT
     
    $ oc login --token=sha256~ZvFDBvoIYAbVECixS4-WmkN4RfnNd8Neh3y1WuiFPXC --server=https://example.com:6443
    Note
    You can find your login token and URL for 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.
  6. For OpenShift: Switch to the RHTAS project: 
    $ oc project trusted-artifact-signer
  7. Generate a new TSA certificate and signer key: 
    $ openssl ecparam -genkey -name prime256v1 -noout -out new-tsa-signer.pem
$ openssl req -new -x509 -key new-tsa-signer.pem -out new-tsa-cert-chain.pem -days 365
    Important
    The certificate and new keys must have unique file names.
  8. Configure The Update Framework (TUF) service to use the new TSA certificate chain.
    1. For OpenShift: 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 TSA_URL="$(oc get timestampauthority -o jsonpath='{.items[0].status.url}')"
$ export TUF_REPO="${WORK}/tuf-repo"
$ export TUF_SERVER_POD="$(oc get pods -l app.kubernetes.io/component=tuf,\!job-name -o jsonpath='{.items[0].metadata.name}')"
$ export TUF_URL="$(oc get tuf -o jsonpath='{.items[0].status.url}')"
    2. For Red Hat Enterprise Linux: Set up your shell environment: 
      $ export BASE_HOSTNAME=BASE_HOSTNAME_OF_RHTAS_SERVICE
$ export WORK="${HOME}/trustroot-example"
$ export ROOT="${WORK}/root/root.json"
$ export KEYDIR="${WORK}/keys"
$ export INPUT="${WORK}/input"
$ export TSA_URL="https://timestamp.${BASE_HOSTNAME}"
$ 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:]')
    3. Create a temporary TUF directory structure: 
      $ mkdir -p "${WORK}/root/" "${KEYDIR}" "${INPUT}" "${TUF_REPO}"
    4. For OpenShift: Download the TUF contents to the temporary TUF directory structure: 
      $ oc extract --confirm --to "${KEYDIR}/" secret/tuf-root-keys
$ oc cp "${TUF_SERVER_POD}:/var/www/html" "${TUF_REPO}"
$ cp "${TUF_REPO}/root.json" "${ROOT}"
    5. For Red Hat Enterprise Linux: 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}"
    6. Find the active TSA 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 TSA certificate file name, for example, timestamp_chain.pem. Set an environment variable with this active TSA certificate file name: 
      $ export ACTIVE_CERT_NAME=timestamp_chain.pem
    7. For OpenShift: Extract the active TSA certificate from OpenShift: 
      $ oc get secret $(oc get timestampauthority securesign-sample -o jsonpath='{.status.certificate.certificateChainRef.name}') -o jsonpath='{.data.cert}' | base64 -d > $ACTIVE_CERT_NAME
    8. For Red Hat Enterprise Linux: Get the active TSA certificate from the managed node: 
      $ rsync -r --rsync-path="sudo rsync" ${MANAGED_NODE_SSH_USER}@${MANAGED_NODE_IP}:/etc/rhtas/certs/timestamp.pem "${ACTIVE_CERT_NAME}"
    9. Expire the old TSA certificate: 
      $ tufcli rhtas \
  --root "${ROOT}" \
  --key "${KEYDIR}/snapshot.pem" \
  --key "${KEYDIR}/targets.pem" \
  --key "${KEYDIR}/timestamp.pem" \
  --set-timestamp-target "$ACTIVE_CERT_NAME" \
  --timestamp-uri "${TSA_URL}" \
  --timestamp-status "Expired" \
  --outdir "${TUF_REPO}" \
  --metadata-url "file://${TUF_REPO}"
    10. Add the new TSA certificate: 
      $ tufcli rhtas \
  --root "${ROOT}" \
  --key "${KEYDIR}/snapshot.pem" \
  --key "${KEYDIR}/targets.pem" \
  --key "${KEYDIR}/timestamp.pem" \
  --set-timestamp-target "new-tsa-cert-chain.pem" \
  --timestamp-uri "${TSA_URL}" \
  --outdir "${TUF_REPO}" \
  --metadata-url "file://${TUF_REPO}"
    11. For OpenShift: Upload these changes to the TUF server: 
      $ oc rsync --no-perms "${TUF_REPO}/" "${TUF_SERVER_POD}:/var/www/html"
    12. For Red Hat Enterprise Linux: Create a compressed archive file of the updated TUF repository: 
      $ tar -C "${WORK}" -czvf repository.tar.gz tuf-repo
    13. For Red Hat Enterprise Linux: 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 }}"
    14. Delete the working directory: 
      $ rm -r $WORK
  9. For OpenShift: Create a new Secret for the new TSA signer key and certificate chain: 
    $ oc create secret generic tsa-cert-chain --from-file=cert=new-tsa-cert-chain.pem --from-file=key=new-tsa-signer.pem
  10. For OpenShift: Update the Securesign TSA configuration: 
    $ read -r -d '' SECURESIGN_PATCH <<EOF
[
{
    "op": "replace",
    "path": "/spec/timestampAuthority/signer/certificateChain/certificateChainRef",
    "value": {"name": "tsa-cert-chain", "key": "cert"}
},
{
    "op": "replace",
    "path": "/spec/timestampAuthority/signer/file/privateKeyRef",
    "value": {"name": "tsa-cert-chain", "key": "key"}
}
]
EOF
  11. For OpenShift: Patch the Securesign instance: 
    $ oc patch Securesign securesign-sample --type='json' -p="$SECURESIGN_PATCH"
  12. For OpenShift: Wait for the TSA server to redeploy: 
    $ oc wait pod -l app.kubernetes.io/name=timestamp-authority,\!job-name --for=condition=Ready
  13. For OpenShift: Accept the updated TSA trust material: 
    $ oc annotate timestampauthority securesign-sample rhtas.redhat.com/refresh-trust-material=true --overwrite
    Note
    After you rotate the certificate, the TSA instance stays unready until you annotate the resource to accept the new trust material.
  14. For OpenShift: Wait until the TSA instance is ready: 
    $ oc wait timestampauthority securesign-sample --for=condition=Ready
  15. For Red Hat Enterprise Linux: Run the RHTAS Ansible Playbook to apply the changes: 
    $ ansible-playbook -i inventory play.yml
  16. Update the cosign configuration with the updated TUF configuration: 
    $ : "${TAS_TUF_ROOT_CHECKSUM:?Set the pinned TAS_TUF_ROOT_CHECKSUM}"
$ cosign initialize --mirror=$TUF_URL --root=$TUF_URL/1.root.json --root-checksum=$TAS_TUF_ROOT_CHECKSUM

    The --root-checksum option ensures that the TUF root metadata is valid and has not been tampered with.

Results

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

What to do next

For Red Hat Enterprise Linux: Additional resources

  • Running your playbook with Ansible Automation Platform