Version Fulcio Certificates

[feelepxyz]

Could we version Fulcio certificates to make it easier to deal with old certificates that contain different cert extensions?

Context

Fulcio Certificates went through a significant change recently with the deprecation and addition of the following cert extensions: https://github.com/sigstore/fulcio/blob/main/docs/oid-info.md#136141572641--fulcio

When implementing support for these new cert extensions in a service that backs the npmjs.com provenance UI, we ended up with a check like so:

if ext.Id.Equal(certificate.OIDIssuerV2) {
  fcs.IsPostFulcioV1_2 = true
}

This is ok but feels a bit clunky and will only get more complicated as we add new extensions and want to deprecate extension in future. For example deprecating all GitHub Workflow * extensions, it seems gross to just check if one is missing and assume all the others are gone too once they are removed.

Proposal

I'm proposing we add a new certificate extension that encodes the version of the Fulcio certificate, that could then be used to easily handle certificates with different sets of extensions. It's not entirely clear to me yet what the best approach would be so I'll try to list out some options here.

To clarify: this would only be a version that Fulcio controls, and not tied to the backing ID token, that might change over time.

Ways we could encode a version in the Fulcio Certificate

• Add a string extension that contains the deployed Fulcio version at the time of signing: e.g. Fulcio Version: "1.2.0"
  • Pros
    • Probably the most straight forward option, we have a version already and it's incremented on each release
  • Cons
    • Slightly annoying to work with the version in code, you can't just do cert.fulcioVersion >= "1.2.0", you would need a semver lib to do range comparisons. which is probably what you want for forward compatibility
    • The Fulcio version does not always contain any cert changes. e.g. Fulcio 2.0 might only contain breaking API changes and no cert changes.
  • Cons
• Use a separate version just for the certificate that's disconnected from deployed Fulcio version and use something that's sortable/greppable in docs: e.g. a date like the GitHub API Fulcio Version: 2023-08-30
  • Pros
    • Easy to sort version so no need for special libraries to do version range comparisons
    • Seems good to have a separate changelog/version that is just for the certificate to clearly show when there are changes to the cert?
  • Cons
    • Additional version to keep track of and remember to increment when there are certificate changes
    • Maybe confusing to have a separate version?
• Do nothing: rely on the presence/omission of extensions to identify the version of the cert
  • Pros
    • No extra work in Fulcio
  • Cons
    • Seems like this will only cause more pain in the future when we want to remove deprecated cert extensions for example

[haydentherapper]

I wrote like 5 versions of this comment going back and forth on what to do, so everything I'm going to say is a brain dump and I don't have a stance on this yet.

I don't want to include every version of Fulcio in a certificate, because that adds too much work for the client to understand what is expected in the certificate, and like you said, most changes aren't going to have a change to the certificate.

+1 to clients being able to say "I support Fulcio certs of version X" so as we add more fields, we can tell when clients lag behind. For example, Cosign has not been updated for any of the new CI fields.

Just thinking about how to implement this as a client - You'd need a list of claims, and a mapping from fulcio cert version to OID (and an understanding of how to parse that OID). Maybe the version should be bounded, for example [1.0, 1.2) = , [1.2, 1.4) = , 1.4+ =

We could say that adding and deprecating fields must require a minor bump. Removing those fields will always be a major revision, so we'll probably stick to deprecating for awhile. This would at least minimize the number of versions clients have to track. Not sure how to inform clients when a minor version contains no updates to the extensions however.

[haydentherapper]

One other idea is publishing the mapping via the /configuration endpoint so it's discoverable via clients. As part of cutting a new release, we would also update some yaml/json configuration that would specify ranges of versions and what extensions are available for each range. Not sure the best standard for specifying ranges - I thought pURL had a spec but didn't see this.