Change doc reference in the Ratify error log

[FeynmanZhou]

What happened in your environment?

When Ratify fails to verify a Notary Project signature, the Ratify always points users to the same URL https://github.com/notaryproject/notaryproject/tree/main/specs whatever the verification failure cause is. This URL is not helpful for troubleshooting since it doesn't point to a file path instead of a specific doc. Users might be confused if Ratify points to a file path.

"verifierReports": [
    {
      "subject": "ghcr.io/deislabs/ratify/notary-image@sha256:8e3d01113285a0e4aa574da8eb9c0f112a1eb979d72f73399d7175ba3cdb1c1b",
      "referenceDigest": "sha256:57be2c1c3d9c23ef7c964bba05c7aa23b525732e9c9af9652654ccc3f4babb0e",
      "artifactType": "application/vnd.cncf.notary.signature",
      "verifierReports": [
        {
          "isSuccess": false,
          "message": "Original Error: (Original Error: (error while loading the trust store, valid certificates must be provided, only CA certificates or self-signed signing certificates are supported), Error: verify signature failure, Code: VERIFY_SIGNATURE_FAILURE, Plugin Name: notation, Component Type: verifier, Documentation: https://github.com/notaryproject/notaryproject/tree/main/specs, Detail: failed to verify signature of digest), Error: verify reference failure, Code: VERIFY_REFERENCE_FAILURE, Plugin Name: notation, Component Type: verifier",
          "name": "notation",
          "extensions": null
        }
      ],
      "nestedReports": []
    }
  ]

There are other failure cases and logs referencing this URL, see Ratify negative test.

What did you expect to happen?

I think Ratify logs should point users to a Ratify troubleshooting doc that explains the detailed root cause and potential solution according to the error code, or at least point to a specific versioned Notary Project spec.

What version of Kubernetes are you running?

v1.26

What version of Ratify are you running?

v1.0.0-rc.8

Anything else you would like to add?

N/A

Are you willing to submit PRs to contribute to this bug fix?

• Yes, I am willing to implement it.

[binbin-li]

Hi @FeynmanZhou, thanks for the feedback on it! Even though notation could fail a signature in different ways, Ratify cannot distinguish between them as Ratify catches the error from the offline verify method provided by notation-go.
https://github.com/deislabs/ratify/blob/main/pkg/verifier/notation/notation.go#L133
That's why Ratify just provides the same page to different notation failures. Which doc or page do you think would make more sense for this verification error?

[FeynmanZhou]

Had a discussion with @binbin-li , we will change the doc reference link to the Ratify troubleshooting doc and maintain common cases/solutions in that chapter. See an example: https://ratify.dev/docs/1.0/troubleshoot/certstore/cert-invalid-tsg