Update documentation for cosign verify to account for using cosign 2.0
Could be relatively comprehensive, especially if we touch on public key vs cert
Could also include moving all of these to dccscr, making sure that it's linked or posted on the docs website. Move this document itself to the docs repository, and coordinate change with IBFE.
Currently, we have the cosign ca bundle, certificate, and the readme which discusses how to use cosign for our customers. It only discusses how to use the certificate to validate: https://repo1.dso.mil/ironbank-tools/ironbank-pipeline/-/tree/master/scripts/cosign
Internally, we have been using the public key instead of the certificate in order to verify. It is an alternative method that accomplishes the same task: https://repo1.dso.mil/ironbank-tools/ironbank-pipeline/-/tree/master/scripts/cosign
Since cosign 2.0 was released, we realized that we needed to update documentation because of the "tlog-insecure" change to the cosign verify command as discussed in the blog of the cosign 2.0 release: https://blog.sigstore.dev/cosign-2-0-released/
Please note that the documentation might be stored in 3 places (here in ironbank-pipeline code, in CHT's repo1.dso.mil/dccscr project, and also wherever their docs site points to: https://docs-ironbank.dso.mil/tutorials/cosign/). we need to consolidate/standardize so that the documentation is only kept in 1 place.
Acceptance criteria:
-
Notify our customers that cosign 2.x is breaking, link to the appropriate blog post that discusses the rekor changes and "tlog-insecure" requirement, and teach our customers how to verify whether they have the 1.x or 2.x version of cosign installed, since this will change the section of the document that they go to. -
Understand how the current documentation works for using cosign 1.x
and realize that it only discusses how to do so with a public key. We need to refactor the current commands into a subsection called "using version 1 of cosign to validate images" or something similar, and we need to add a paragraph in section in 1.x to let people know that they can use EITHER the certificate w/authority to use cosign to verify the image, or they can use the public key -
Create a cosign 2.x subsection that shows how to use cosign 2.x in order to verify images, again using both the public key and the certificate. You will want to call out that they will want to use the public key because of how simple it makes the command, but as an alternative for niche use cases, in case they need they can use the complicated certificate version of the cosign verify command using cosign 2.x. -
Make a single source of truth so that there is only one place that we need to look to update this document. -
Figure out how to make the certificate, ca bundle, and public key all available to the documentation site. This might be as simple as a link back to the repository or there might be a way to host files on the docs site. -
Remove the SBOM section from the bottom of this document. Please make a callout in the "cosign download" section of this document to let customers know that they will download the sbom included within the attestation. Please verify by downloading an attestation and ensuring that an sbom is inside of it -
How to generate a public key with link to cosign documentation