"Chain" for verification is confusingly named

[znewman01]

See helpful context: https://github.com/sigstore/cosign/pull/2461#discussion_r1024644134_

The verify-* commands have this argument:

--certificate-chain string: path to a list of CA certificates in PEM format which will be needed when building the certificate chain for the signing certificate. Must start with the parent intermediate CA certificate of the signing certificate and end with the root certificate

We automatically trust any provided chain here. That's a reasonable behavior, if you're trying to specify a trust root.

However, when I see a flag named --certificate-chain I assume that it's just something I provide to link the cert back up to a default trust root! It feels eminently reasonable to me to download a certificate and a chain alongside a signature, and want to pass that in.

Can we rename this to something like --ca-trust-root or --root-ca and then just specify in the help text that accepts a certificate or a chain of certs?

[znewman01]

There are two possible changes here:

1. Just rename the current --certificate-chain flag to something more descriptive (possibly keeping an alias from the old name for backwards compatibility)
2. Shuffle around how users provide certs. So you'd pass something like --cert-and-intermediates and --root-pool (names very much TBD). This would probably require a transition period.

This means that it's no longer a 2.0 blocker.

Our APIs should also reflect this.

[haydentherapper]

Something to learn from is how openssl implements this - You pass a set of trusted certificates (typically root certs) and "untrusted" certs used for chain building (typically intermediates). I'd avoid using "untrusted", but splitting up a chain makes sense. It also lets us easily pass sets of roots rather than a single root in a chain.

We also chatted about how Sigstore's TUF targets don't differentiate between trusted roots and chain building intermediates. This is something we should address.

[dmitris]

It also lets us easily pass sets of roots rather than a single root in a chain.

being able to pass a set of roots (a bundle) would be very convenient! If there are no big "conceptual" hurdles / objections etc, I'd volunteer to help this happen.

[dmitris]

Something to learn from is how openssl implements this - You pass a set of trusted certificates (typically root certs) and "untrusted" certs used for chain building (typically intermediates). I'd avoid using "untrusted", but splitting up a chain makes sense. It also lets us easily pass sets of roots rather than a single root in a chain.

could we split the --certificate-chain into 1. --certificate-roots - which could contain either the single CA root file, like the last part of the current certificate chain and 2. --certificate-intermediates - optional parameter that would include the intermediate CA(s)? We can treat the current --certificate-chain as if the last certificate where in the file passed to --certificate-root, and the rest of the file - as content of the --certificate-intermediates file.