From 7e5d708216ffe5bf2e8678da94fb31f5842fc99f Mon Sep 17 00:00:00 2001 From: Roseline Bassey Date: Thu, 10 Aug 2023 19:09:56 +0100 Subject: [PATCH] Create a FAQ to describe difference among notary, TUF, Notary Project specification, and notation (#328) This PR adds a new section in faq.md to clarify the difference between Notary, Notary v2, Notation, TUF, and Notary Project. It fixes #323 I haven't included a link to the `glossary page` in the last line because PR #326 is still under review and has not been merged yet. I will update this PR with the link once #326 is merged. --------- Signed-off-by: Roseline Co-authored-by: Yi Zha --- content/en/docs/faq.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/content/en/docs/faq.md b/content/en/docs/faq.md index d0b40dd8..8e4daa0a 100644 --- a/content/en/docs/faq.md +++ b/content/en/docs/faq.md @@ -75,3 +75,34 @@ Not natively supported but a user can configure `revocationValidations` to `skip **A:** Ideally, we should validate the signing identity first and then use the public key in the signing identity to validate the artifact signature. However, this will lead to poor performance in the case where the signature is not valid as there are lots of validations against the signing identity including network calls for revocations, and possibly we won't even need to read the trust store/trust policy if the signature validation fails. Also, by validating artifact signature first we will still fail the validation if the signing identity is not trusted. + +## Notary Project Terms +Below are the frequently asked questions about Notary Project terms. For detailed definitions of each Notary Project term, please refer to the [glossary]({{< ref "/docs/glossary" >}}) page. + +**Q: What is Notary Project?** + +**A:** The Notary Project is a set of specifications and tools intended to provide a cross-industry standard for securing software supply chains by using authentic container images and other OCI artifacts. Notary Project is also the name of the GitHub organization that has multiple prominent subprojects like Notation, Notary Project specifications, and Notary. Very often we use the name Notary Project to refer to all the above as well as the community that drives the specifications and the implementations. + +**Q: How are Notary and Notary Project related?** + +**A:** Notary is one of the subprojects under the Notary Project organization. Notary uses The Update Framework (TUF) to implement client and server components that run and interact with trusted collections that describe the content in a container registry. The name Notary comes from the `notary` CLI that is used to manage the trusted collections. The code that has the implementation of the client and the server components is available in the [notaryproject/notary](https://github.com/notaryproject/notary) repository. + +**Q: What is the difference between Notary Project and TUF?** + +**A:** [The Update Framework (aka TUF)](https://github.com/theupdateframework) is a CNCF graduated project that helps developers maintain the security of software update systems. TUF is a separate community and separate GitHub organization. One of the subprojects under Notary Project, [`notary`](https://github.com/notaryproject/notary), uses TUF for the implementation. + +**Q: What is Notary Project specification?** + +**A:** Due to some portability challenges with the TUF-based implementation in Notary, circa 2019, the Notary Project community decided to work on a portable signature specification. This resulted in the creation of the [specifications](https://github.com/notaryproject/specifications) subproject. The Notary Project specifications are shared across repositories under Notary Project as well as used by other open-source projects and/or vendor tools that want to interoperate with the Notary Project tooling. The Notary Project community plans to add other specifications in the future as our work on software supply chain evolves. + +**Q: Does Notary Project signature specification leverage TUF?** + +**A:** No, the Notary Project [signature specification](https://github.com/notaryproject/specifications/blob/v1.0.0/specs/signature-specification.md) does not leverage TUF. + +**Q: What is the difference between Notation and Notary?** + +**A:** [Notation](https://github.com/notaryproject/notation) and [Notary](https://github.com/notaryproject/notary) are both subprojects of Notary Project and offer capabilities for signing container images. Notation implements the new [Notary Project signing specification and workflows](https://github.com/notaryproject/specifications/) while Notary is based on [The Update Framework](https://theupdateframework.com) (TUF) and does not implement any of the Notary Project specifications. While Notation has a CLI and libraries and leverages existing key management infrastructure and [OCI-compliant](https://opencontainers.org/) registries, Notary has a server and client components. An example of a `notary` implementation is Docker Content Trust (DCT). In addition to signing artifacts, Notation handles artifact verification, signature portability, and integration with third-party key/certificate management solutions via a plugin model. + +**Q: I've heard the term "Notary v2". What does this mean?** + +**A:** The term "Notary v2" or "notary v2" was previously used by members of the Notary Project community and others. However, various meanings were ascribed to it, leading to its ambiguous usage with some people referring to it as the entire Notary Project and others as the [Notation CLI](https://github.com/notaryproject/notation). Because of this ambiguity, the term "Notary v2" or "notary v2" is no longer used by the Notary Project community. While the term may still be visible in some articles on the internet, the name "Notary v2" or "notary v2" is only preserved for historical reasons and will not be used by the Notary Project community going forward. \ No newline at end of file