Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create a FAQ to describe difference among notary, TUF, Notary Project specification, and notation #328

Merged
merged 16 commits into from
Aug 10, 2023
Merged
Changes from 15 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions content/en/docs/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -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?**

Roseline-Bassey marked this conversation as resolved.
Show resolved Hide resolved
**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. Notary is based on [The Update Framework](https://theupdateframework.com) (TUF) and does not implement any of the Notary Project specifications while Notation implements the new [Notary Project signing specification and workflows](https://github.com/notaryproject/specifications/). While Notary has a server and client components, Notation has a CLI and libraries and leverages existing key management infrastructure and [OCI-compliant](https://opencontainers.org/) registries. 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.
yizha1 marked this conversation as resolved.
Show resolved Hide resolved

**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.