Notary v2: Prototype 2 Scope

[SteveLasker]

To support Notary v2 requirements for multiple signatures that don't change the artifact digest or tag, we must support new artifacts that link to existing artifacts.

Goals & Intent

With Prototype-1 complete, we must now harden the linked artifacts implementation with a spec and design that could be deployed for production validation. While the design will be prototyped in CNCF Distribution, the full implementation will not be completed in CNCF Distribution. Cloud providers have cloud-optimized implementations, and implementers of CNCF Distribution have their unique product implementations. The purpose of the prototype is to prove the APIs are capable of being implemented.

The prototype should:

• 1. Implement the oci.artifact.manifest spec, supporting linked manifests in CNCF distribution.
• 2. Implement the oci.artifact.manifest links API, supporting retrieving linked manifests in CNCF distribution.
• 3. Implement ORAS client libraries, enabling the pushing of the oci.artifact.manifest with the link, discovering and pulling of artifacts, using the OCI.artifact.manifest
• 4. ORAS cli to support pushing by digest, enabling the ability to update an existing tag, after the updated image and signatures have been posted. (needs further refactoring not related to notary efforts)
• 5. Converge docker-generate and docker-nv2 into the nv2 repo. Update the nv2 cli to create a docker plug-in to provide docker sign, verify push, pull capabilities, supporting the oci.artifact.manifest and linked manifest discovery.
• 6. Incorporate any nv2 client feedback items related to signing and verifying. (TBD)
• 7. With ORAS support, users should be able to link Notary v2 signatures or other files, including SBoM simulated files. ORAS push, would push the single file reference as a tar file, eliminating the org.opencontainers.image.title annotation. See oras issue # 114 (needs further refactoring not related to notary efforts)
• 8. Update the docker-generate plug-in to support pushing the image by digest, the linked signature, then pushing the tag update. (needs further refactoring not related to notary efforts)
• 9. Implement an OPA/Gatekeeper policy that confirms signature validation, before deploying an image to k8s.

The prototype should not:

1. Attempt to complete the CNCF distribution implementation with de-duping or garbage collection. Linked storage layout will be completed, enabling CNCF distribution implementors to complete their specific implementations.
2. Focus on private or public key acquisition. Key management is not part of this prototype.

Target Experience

The experience should focus on the e2e tooling, including the use of the docker cli.

Demo Script

Deliverables

• Instance of cncf distribution to locally run. The prototype would be checked into: notaryproject/distribution/prototype-2.

2. A built image, users can run locally pushed to: docker.io/notaryv2/registry:nv2-prototype-2
3. A docker plug-in to simulate the docker build, sign, push experience
4. An OPA/Gatekeeper policy for validating signatures, prior to image deployment

[dlorenc]

The purpose of the prototype is to prove the APIs are capable of being implemented.

What would the plan be for getting this upstreamed/accepted into the OCI distribution spec? This seems to jump ahead a bit from prototypes here to implementation by cloud providers.

7. Notary v2 signatures

Which signature format is this intended to use. I have some serious concerns with the existing one. I can't really find any of the discussion around its design, and it hasn't been touched in ~6 months. Could we include at least iterating on that format a bit here too?

Same goes for payloads - the existing one looks like a mashup of a parts of a Descriptor and parts of a JWT token. We should pick one or the other here. Settling on the formats early will unblock other tools from integrating here.

• Implement the oci.artifact.manifest spec, supporting linked manifests in CNCF distribution.

Also, just a nit but an important one - I believe this isn't a spec yet - it's a spec draft. There are alternate proposals here too, including this one: opencontainers/image-spec#828. It's important that whatever tooling notary eventually works with whichever linking proposals are eventually accepted and implemented - not only this specific draft.

[dlorenc]

The experience should focus on the e2e tooling, including the use of the docker cli.

Demo Script

I just read through the demo script - I'm having trouble seeing how the commands and examples support the requirements and threat models... Is there a better place to provide feedback or ask questions? I'm having a hard time understanding a lot of this.

Apologies again if I missed something, I can't find any of the conversation that might have taken place on the PR itself before it was merged: notaryproject/notation#42 Was it discussed on a mailing list or something?

The self-signed cert contains a CN entry of the registry the image is pushed to - doesn't this make the scenarios around moving content between registries difficult? The cert itself is kind of confusing, since it's self signed I can't follow what it adds on top of just a normal private key. Is the intention that these would be issued by some CA eventually? The CN/Subject stuff isn't clear to me.

The SBOM example just contains a tag reference - should it instead reference the image by digest? I'm not following how the signature protects the mapping of this SBOM to the image. If we don't trust the registry operator, the scenarios from #48 might apply. The SBOM could be moved from one image to another by the registry and we have no way to be sure it's "attached" to the right one.

[sajayantony]

@SteveLasker - I agree with @dlorenc - The prototype should call out that the this doesn't address the threat model issue like rollback and is aimed only at supporting storing artifacts and not its security aspects with the general direction or unifying with the prototype-3 which should address this problem.

[dlorenc]

@sajayantony thanks, I agree. Clarifying exactly what threat model this prototype is intended to address would be useful. I'm still lost on the purpose of the self-signed certificate.

[SteveLasker]

The prototype should not:

• Focus on private or public key acquisition. Key management is not part of this prototype.

[SteveLasker]

Mostly finished wtih prototype-2

• nv2 updates pending PR review
• CNCF Distribution support for reference types
• CNCF Distribution persistence docs pending PR review
• ORAS Experimental Validation
• OPA/Gatekeeper validation

[SteveLasker]

House cleaning as prototype-2 has been complete for a while, and we're working on the alpha1 release