Change artifactType for Notary signatures to use application/cose when COSE is chosen

[SteveLasker]

Backgrond

Early in notation development we chose JWS as a placeholder until we could unify on an existing signature standard. We were discussing PKCS7 but there weren't enough supporting libraries. We ultimately chose COSE, although it was felt too late to switch entirely. Thus the current specs support both JWS and COSE.

Now that notation has COSE support, I'd like to resurface the discussion related to the artifactType used for the detached notary signature.

Proposal

The purpose of choosing COSE was to align around existing standards, and only create new standards when necessary. The standards approach says there may be many tools & services that sign & verify signatures. Notary (notation cli and notation-go) are just examples of the tools and libraries we're developing here.

What I'm suggesting is we change the detached signature artifactType from application/vnd.cncf.notary.signature to application/cose I realize the blob is also application/cose, but I don't see a problem as the APIs are differentiated between a manifest type and a blob type.

Modified version of Signature Manifest Example

{
    "mediaType": "application/vnd.cncf.oras.artifact.manifest.v1+json",
    "artifactType": "application/cose",
    "blobs": [
        {
            "mediaType": "application/cose",
            "digest": "sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0",
            "size": 32654
        }
    ],
    "subject": {
        "mediaType": "application/vnd.oci.image.manifest.v1+json",
        "digest": "sha256:73c803930ea3ba1e54bc25c2bdc53edd0284c62ed651fe7b00369da519a3c333",
        "size": 16724
    },
    "annotations": {
        "io.cncf.notary.x509chain.thumbprint#S256": 
        "[\"B7A69A70992AE4F9FF103EBE04A2C3BA6C777E439253CE36562E6E98375068C3\",\"932EB6F5598435D4EF23F97B0B5ACB515FAE2B8D8FAC046AB813DDC419DD5E89\"]"
    }
}

Part of this discussion should be whether to use application/cose or be more specific and use application/cose-x509

In either case, I would like to raise the issue of moving from notary/notation being the type to notation/notation-go being tools that work over the COSE standard.

SCOPE: This would only apply when the COSE envelope is chosen.

[gokarnm]

The underlying signature format can be JWS or COSE, both of which are it's based on a Notary v2 specification, which dictates the payload to be signed and the headers to be used. It's unclear how changing artifactType to generic application/cose media type which implies any COSE signature, not the specific Notaty v2 defined COSE signature helps. Also, what would the value of artifactType be for JWS signatures?

[SteveLasker]

Thanks @gokarnm, The JWS format was a unique to notary implementation, as a placeholder, while we built on an existing standard. So, I'm not suggesting we change the artifactType when using JWS, as that is notary specific. What I'm suggesting is we change to application/cose when we're using the COSE format.

SCOPE: This would only apply when the COSE envelope is chosen.

[gokarnm]

JWS is not a placeholder, it's an approved Notary v2 signature format based on an existing standard. Both JWS and COSE are supported in an interchangeable way. For verification, notation will query all signatures of type application/vnd.cncf.notary.signature and process them irrespective of them being JWS or COSE. Could you detail the rationale for this change? How do you propose notation verify should work if we have different artifact types for JWS and COSE, and the reason for inconsistent artifactType values between them?

So, I'm not suggesting we change the artifactType when using JWS, as that is notary specific.

Also, the content inside both JWS and COSE envelopes are notary specific.

[SteveLasker]

JWS was a placeholder, that we decided we needed to include, because we needed time to get security reviews of go-cose. I'm not suggesting we pull it out, rather just pointing out this is a path forward to avoid notary specific formats.

For verification, notary can query signatures that support application/vnd.cncf.notary.signature or application/cose and process them.

Could you detail the rationale for this change?

From above:

The purpose of choosing COSE was to align around existing standards, and only create new standards when necessary. The standards approach says there may be many tools & services that sign & verify signatures. Notary (notation cli and notation-go) are just examples of the tools and libraries we're developing here.

[toddysm]

The meaning of application/cose will be that every other client (different from Notary and not implemented according to the Notary specification) will be able to pull the signature and validate it. Is this the expectation @SteveLasker?

@gokarnm are you saying that this is not the case and clients need to be aware of Notary specific to understand the signature, hence we should not use it?

[SteveLasker]

The meaning of application/cose will be that every other client (different from Notary and not implemented according to the Notary specification) will be able to pull the signature and validate it. Is this the expectation @SteveLasker?

Yes, the power of interoperability, leaning into COSE as the signature format. Notation is one of many clients that can generate a COSE signature.

[michaelb990]

Also, the content inside both JWS and COSE envelopes are notary specific.

This feels like the most important part. JWS & COSE are implementation options for Notary V2 signatures and we can differentiate between them in the blob descriptor. Presumably, a COSE signature generated by something other than notation would be somewhat useless to a notation client. Maybe it would help if you explained more about what use case you have in mind. If you want to build a client that uses notary-like signatures but isn't notation, why not just teach that client how to search for artifactType=application/vnd.cncf.notary.signature?

[rchincha]

In the order of peeling the onion ... Also, imho, why a "best practices" guide lacking for various specs (artifacts, dist-spec, etc)

[sudo-bmitch]

The meaning of application/cose will be that every other client (different from Notary and not implemented according to the Notary specification) will be able to pull the signature and validate it. Is this the expectation @SteveLasker?

@gokarnm are you saying that this is not the case and clients need to be aware of Notary specific to understand the signature, hence we should not use it?

This assumes the payload of a COSE signature is the same regardless of the tool used to create it. To give a more obviously bad example, shipping an SBOM with an artifactType application/json doesn't tell me if it's a SPDX, cycloneDX, or maybe something that isn't even an SBOM. We should avoid referring to the payload by the packaging format, since other tools may ship completely different payloads with the same packaging.