Include troubleshooting comments under some code snippets

[DMills27]

Description

The current documentation for Sigstore lacks comments related to troubleshooting under the various code snippets. Many of the code snippets make the assumption that the commands will work as planned and offer no useful advice for any common problems that may occur. This can lead to frustration and confusion for users who encounter issues while attempting to use the code snippets. It would be helpful to include troubleshooting comments and advice to help users overcome any potential obstacles. Ideally, the potential issues could be identified via some short user studies to see what meaningful, common issues may prop up when running various commands.

Here's an example of troubleshooting a potential issue with the cosign verify command in the context of an unexpected error message:

Let's say you are running the following command:

cosign verify <image uri>

And you receive the following error message:

Error: x509: certificate signed by unknown authority

This error message indicates that the certificate of the container image's registry is not trusted by your local machine. In order to troubleshoot this issue, you can try the following steps:

1. Check the registry's certificate: You can use the openssl command to retrieve the registry's certificate and check if it's valid. For example, if your image is hosted on Docker Hub, you can use the following command:

openssl s_client -showcerts -connect index.docker.io:443 </dev/null

This will display the registry's certificate chain, and you can check if it's valid and issued by a trusted certificate authority.

2. Add the certificate to your local trust store: If the certificate is valid but not trusted by your local machine, you can add it to your local trust store. For example, on Linux systems, you can copy the certificate to /usr/local/share/ca-certificates/ and run the update-ca-certificates command to update the trust store.

3. Check your network settings: If the certificate is valid and trusted but you still can't verify the image, you may need to check your network settings. Make sure your machine is able to connect to the registry and that there are no firewall rules blocking the connection.

Using these troubleshooting steps, we were able to diagnose and fix the issue with the cosign verify command.

[Neilblaze]

@ltagliaferri can we add a separate section (say named FAQ or troubleshooting) in the docs to add this? I'd love to take this up! 😃