From 11509d02ca76039915654e840ee3fa56bd51c735 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Sat, 10 Jun 2023 20:15:36 +0800 Subject: [PATCH 1/8] doc: update readme.md Signed-off-by: Yi Zha --- README.md | 236 +++++++++++------------------------------------------- 1 file changed, 45 insertions(+), 191 deletions(-) diff --git a/README.md b/README.md index 77403581..99b703b1 100644 --- a/README.md +++ b/README.md @@ -1,206 +1,60 @@ -# Notary Project Overview - -A current overview of Notary v2, including a collection of requirements & scenarios, framing the scope of the Notary v2 project. +# The Notary Project Overview + +The Notary Project aims to provide enterprise-grade solutions and cross-industry standards for securing software supply chain. The following are current repositories, aka sub-projects, under the Notary Project umbrella in Alphabetical order: + +| Repository | Description | +| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------| +| [.github](https://github.com/notaryproject/.github) | The repository that contains the Notary Project governance documents | +| [meeting-notes](https://github.com/notaryproject/meeting-notes) | The repository that contains archived meeting notes | +| [notary](https://github.com/notaryproject/notatry) | The repository that is an implementation of TUF that runs next to a container registry and adds the ability to sign and verify content in the registry | +| [notaryproject](https://github.com/notaryproject/notatryproject) | The repository that contains the Notary Project requirements and specifications | +| [notaryproject.dev](https://github.com/notaryproject/notatryproject.dev) | The repository that contains documents and styles for the Notary Project website | +| [notation](https://github.com/notaryproject/notation) | The repository that is an implementation of the Notary Project specification and provides a CLI tooling to sign and verify artifacts | +| [notation-go](https://github.com/notaryproject/notation-go) | The repository that is an implementation of the Notary Project specification and provides the library supports of signing and verifying artifacts | +| [notation-core-go](https://github.com/notaryproject/notation-core-go) | The repository that is an implementation of the Notary Project signature specification and provides the library supports | +| [roadmap](https://github.com/notaryproject/roadmap) | The repository that contains roadmap issues for the Notary Project | +| [tuf](https://github.com/notaryproject/tuf) | The repository that implements the full TUF specification in a registry native way | ## Project Status -The Notary v2 project is in early development and design documents should not be considered final. -Please refer to the [milestones](https://github.com/notaryproject/notaryproject/milestones) or [attend](#contributing--conversations) the weekly meetings for details on the roadmap. - -## TOC - -- [Overview](#notary-v2-overview) -- [Notary v2 Journey](#the-notary-v2-journey) -- [Top Areas of Focus](#top-areas-of-focus) -- [Stages of Development](#stages-of-development) -- [Notary v2 February 2021 Status](./status-updates/notary-status-2021-02.md) - -Additional details for Notary v2 efforts: - -- [Goals & Requirements][nv2-requirements] -- [Scenarios][nv2-scenarios] -- [Threat Model][nv2-threat-model] -- [Definitions & Terms][nv2-definitions] -- [Contributing](#contributing-&-conversations) - -## Notary v2 Overview - -![Notary v2 scenarios](./media/notary-e2e-scenarios.svg) - -Notary v2 provides for multiple signatures of an [OCI Artifact][oci-artifacts] (including container images) to be persisted in an [OCI conformant][oci-distribution-conformance] registry. -Artifacts are signed (`notation sign`) with private keys, and validated with public keys (`notation verify`). -To support user deployment flows, signing an OCI Artifact will not change the `@digest` or `artifact:tag` reference. -To support content movement across multiple certification boundaries, artifacts and their signatures will be easily copied within and across [OCI conformant][oci-distribution-conformance] registries. - -![Notary v2 dependent projects](./media/oss-project-sequence.svg) - -To deliver on the Notary v2 goals of cross registry movement of artifacts with their signatures, changes to several projects are anticipated, including [OCI distribution-spec][oci-distribution-spec], [CNCF Distribution][cncf-distribution], [OCI Artifacts][oci-artifacts], [ORAS][oras] with further consumption from projects including [containerd][containerd], [OPA][opa], [Gatekeeper][gatekeeper] and the [docker client][docker-client]. - -Notary v2 aims to solve the intra and cross registry signing & validating scenarios through the following prototypical experiences: - -**Docker build, sign, push, pull, verify**: - -```bash -docker build -t registry.wabbit-networks.io/net-monitor:v1 . - -notation sign \ - -k wabbit-networks.key \ - -r registry.wabbit-networks.io/net-monitor:v1 - -docker push registry.wabbit-networks.io/net-monitor:v1 -``` - -On another node, verify the signature before deployment. - -_**Note**: the `notation verify` command is shown external to the docker client to demonstrate validation, which may be added to any container runtime, including containerd._ - -```bash -notation verify \ - -k wabbit-networks.key \ - -r registry.wabbit-networks.io/net-monitor:v1 - -docker run registry.wabbit-networks.io/net-monitor:v1 -``` - -**Copy a container image, with it's signatures across two registries with the existing docker tool chain**: - -```bash -docker pull registry.wabbit-networks.io/net-monitor:v1 - -docker tag registry.wabbit-networks.io/net-monitor:v1 \ - registry.acme-rockets.io/net-monitor:v1 - -docker push registry.acme-rockets.io/net-monitor:v1 -``` - -**Copy a container image to a private registry, verifying the source then adding a verification signature**: - -```bash -notation verify \ - -k wabbit-networks.key \ - -r registry.wabbit-networks.io/net-monitor:v1 - -docker pull registry.wabbit-networks.io/net-monitor:v1 - -# run one or more verification processes, then sign with the ACME Rockets key - -docker tag registry.wabbit-networks.io/net-monitor:v1 \ - registry.acme-rockets.io/net-monitor:v1 - -notation sign \ - -k acme-rockets.key \ - -r registry.acme-rockets.io/net-monitor:v1 - -docker push registry.acme-rockets.io/net-monitor:v1 -``` - -## The Notary v2 Journey - -Notary v2 [kicked off in December of 2019][notaryv2-kickoff] with a [broad range of attendees][kickoff-attendees]. -The effort defined success goals, including adoption by all major vendors & projects, enabling content to be signed and flow within and across [OCI distribution-spec conformant][oci-distribution-conformance] registries. -Throughout 2020, the group agreed upon a set of [Notary v2 requirements][nv2-requirements] and [scenarios][nv2-scenarios] enabling spec and design conversations to be grounded in a set of [goals][nv2-requirements] and [non-goals][non-requirements]. -Prototypes, based on the requirements have started, focusing on the primary areas on innovations. - -## Top Areas of Focus - -To complete Notary v2, three key areas of focus were identified: - -1. [Definition of a Notary v2 Signature](#definition-of-a-notary-v2-signature) -1. [Registry Persistance, Discovery and Retrieval](#registry-persistance-discovery-and-retrieval) -1. [Key Management](#key-management) - -### Definition of a Notary v2 Signature - -A Notary v2 signature would attest to the digest of an artifact, associating it with a signing key. - -### Registry Persistance, Discovery and Retrieval - -An artifact must be capable of being pushed to a registry, with a signature being added independently from the artifact. -This enables the originating author of the content to sign the artifact, and subsequent entities to add additional signatures, attesting to its validity as they determine. - -The Notary v2 workflow ([outlined in Scenario #0](https://github.com/notaryproject/requirements/blob/main/scenarios.md#scenario-0-build-publish-consume-enforce-policy-deploy)) enables Wabbit Networks to sign their `net-monitor` software. -Docker Hub may endorse Wabbit Networks software, providing an aggregator certification by adding a Docker Hub signature. -This would allow customers like ACME Rockets to not necessarily know of small vendors like Wabbit Networks, but allow the ACME Rockets engineering team to pull Docker Certified content. -As ACME Rockets imports the content, scans and validates it meets their requirements, they add an additional ACME Rockets signature, which must exist for any production usage within the ACME Rockets environment. - -#### Registry Persistance and Retrieval - -Registry persistance and retrieval are defined through the [OCI distribution-spec][oci-distribution-spec], with [OCI Artifacts][oci-artifacts] capabilities to store non-container images. -No additional changes are known at this time. - -#### Registry Discovery - -Registry discovery of linked artifacts enables finding a signature, based on the target artifact. -In the Notary v2 example, the ACME Rockets production servers must be capable of efficiently finding the ACME Rockets signature for the `net-monitor:v1` image. -Once the signature is identified, through a content addressable digest, the Notary v2 client may validate the signature. - -### Key Management - -Key Management involves the following key scenarios: - -- Signing with private keys -- Publishing and discovery of public keys for consumers to validate signatures -- Key revocation, including support for air-gapped environments - -Private key management is beyond the scope of the Notary v2 effort, as companies have well defined practices that are internal to their software development. - -Publishing and discovery of public keys should be easy for consumers to acquire, however, Notary v2 will not implicitly support a **T**rust **o**n **F**irst **U**se (TOFU) model. - -Key revocation must support air-gap environments, enabling users to validate keys when resources inside a network isolated environment are unable to reach public endpoints. - -## Stages of Development +The Notary Project is now in active development. The latest release announcement will be published on [the Notary Project website](https://notaryproject.dev/blog/). The Notary community uses the [project board](https://github.com/orgs/notaryproject/projects/10) for project planning and status tracking. You can also use GitHub milestones to track the progress: -To deliver Notary v2, we recognized the need of experts from multiple backgrounds, experiences and skill sets. -The various perspectives were needed to assure we learned from past efforts and learned from subject matter experts. +- [Notation CLI](https://github.com/notaryproject/notation/milestones) +- [Notation library notation-go](https://github.com/notaryproject/notation-go/milestones) +- [Notation library notation-core-go](https://github.com/notaryproject/notation-core-go/milestones) +- [Notary](https://github.com/notaryproject/notary/milestones) -As subject matter experts converged, we found it difficult for the various SMEs to understand other components of the end to end workflow. -The typical Open Source model for authoring specs involves “writing it down”. -Contributors Create a pull request on some markdown so all can review. -However, we learned _The problem isn’t in the writing, it’s in the reading._ +> Note: The original intention of [roadmap repository](https://github.com/notaryproject/roadmap) is to maintain the roadmap issues for the Notary Project, but we are now moving these issues to correspondent repositories. We will finally archive roadmap repository. -To facilitate better communications across the skill sets, respecting everyone's time, we recognized the need to invest in models and prototypes. -We followed the design patterns of other large, complex projects like Antoni Gaudí's design of [The Sagrada Famila](https://simple.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia). -The [sketch, prototype, build approach](https://stevelasker.blog/2020/07/31/sketch-prototype-build/) would enable the various experts to focus on their component, while understanding where they plug-into other components of the design. +## Security -As a result, we identified the following stages of the Notary v2 effort: +The Notary Project has had several public security audits: -1. Define Requirements -1. Build Prototypes -1. Validate prototypes - learning, refining requirements, iterating prototypes -1. Author a Notary v2 Spec +- [August 7, 2018 by Cure53](https://github.com/notaryproject/notary/blob/master/docs/resources/cure53_tuf_notary_audit_2018_08_07.pdf)) covering `TUF` and `Notary` repositories +- [July 31, 2015 by NCC](https://github.com/notaryproject/notary/blob/master/docs/resources/ncc_docker_notary_audit_2015_07_31.pdf) covering `Notary` repository +- [Mar 21, 2023 by ADA Logics](https://github.com/notaryproject/notaryproject/blob/main/security/reports/fuzzing/ADA-fuzzing-audit-22-23.pdf) fuzzing audit covering `Notary`, `notation-go` and `notation-core-go` repositories -Throughout the Notary v2 effort, updates to the stages of development and areas of focus will be detailed. +There is ongoing security audit which will be published soon. -- [2021 - February Status Update](./status-updates/notary-status-2021-02.md) +## About this repository -## Contributing & Conversations +This repository contains requirements, scenarios, and specifications for the Notary Project: -Regular conversations for Notary v2 occur on the [Cloud Native Computing Slack](https://app.slack.com/client/T08PSQ7BQ/CQUH8U287?) channel. +- [Requirements](./requirements/): The Notary Project goals, scenarios, and requirements are stored in this folder. +- [Specification](./specs/): The Notary Project specifications are stored in this folder. You can develop your own implementation based on the specifications. The Notary Project specifications includes + - The Notary Project signature specification + - The Notary Project signature envelope specifications: JWS and COSE + - The signing and verifying specifications + - The trust store and trust policy specification + - The plugin specification +- [Threat Model](./threatmodel.md): General threat modeling for the Notary Project. We are now working on threat model for Notation CLI `notation`, Notation libraries `notation-go` and `notation-core-go`. -Weekly meetings occur each Monday. -Please see the [CNCF Calendar](https://www.cncf.io/community/calendar/) for details. +## Community -Meeting notes are captured on [hackmd.io](https://hackmd.io/_vrqBGAOSUC_VWvFzWruZw). +You can reach the Notary Project community and developers via the following channels: -[cncf-distribution]: https://github.com/distribution/distribution -[containerd]: https://github.com/containerd -[docker-client]: https://www.docker.com/products/docker-desktop -[gatekeeper]: https://github.com/open-policy-agent/gatekeeper -[kickoff-attendees]: https://github.com/notaryproject/meeting-notes/blob/main/meeting-notes-2019.md#attendees -[moby]: https://github.com/moby -[notaryv2-kickoff]: https://github.com/notaryproject/meeting-notes/blob/main/meeting-notes-2019.md#notary-v2-kickoff-meeting -[non-requirements]: ./requirements.md#non-goals -[nv2-notes]: https://hackmd.io/_vrqBGAOSUC_VWvFzWruZw -[nv2-requirements]: ./requirements.md -[nv2-scenarios]: ./scenarios.md -[nv2-signature-spec]: https://github.com/notaryproject/notation/tree/prototype-1/docs/signature -[nv2-threat-model]: ./threatmodel.md -[nv2-key-management]: https://github.com/notaryproject/requirements/pull/38/ -[nv2-distribution-spec]: https://github.com/opencontainers/artifacts/pull/29 -[nv2-definitions]: ./definitions-terms.md -[oci-artifacts]: https://github.com/opencontainers/artifacts -[oci-artifact-manifest]: https://github.com/opencontainers/artifacts/pull/29 -[oci-distribution-spec]: https://github.com/opencontainers/distribution-spec -[oci-distribution-conformance]: https://github.com/opencontainers/oci-conformance -[opa]: https://github.com/open-policy-agent -[oras]: https://github.com/deislabs/oras +- Slack: Join the [Notary Project community channel](https://app.slack.com/client/T08PSQ7BQ/CQUH8U287/) for discussion and ask questions +- Twitter: [@NotaryProject](https://mobile.twitter.com/NotaryProject) +- Meetings: Join the [Community meetings](https://notaryproject.dev/community/#community-meetings) + - Active meeting notes are captured at [the Notary Project meeting notes](https://hackmd.io/_vrqBGAOSUC_VWvFzWruZw?view) + - Archived meeting notes are stored at [meeting-notes repository](https://github.com/notaryproject/meeting-notes) \ No newline at end of file From f24862c7973a7c324b54f5e936de5abfd2f41f01 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Sat, 10 Jun 2023 20:25:01 +0800 Subject: [PATCH 2/8] doc: updates Signed-off-by: Yi Zha --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 99b703b1..30965d13 100644 --- a/README.md +++ b/README.md @@ -34,20 +34,20 @@ The Notary Project has had several public security audits: - [July 31, 2015 by NCC](https://github.com/notaryproject/notary/blob/master/docs/resources/ncc_docker_notary_audit_2015_07_31.pdf) covering `Notary` repository - [Mar 21, 2023 by ADA Logics](https://github.com/notaryproject/notaryproject/blob/main/security/reports/fuzzing/ADA-fuzzing-audit-22-23.pdf) fuzzing audit covering `Notary`, `notation-go` and `notation-core-go` repositories -There is ongoing security audit which will be published soon. +There is an ongoing security audit which will be published soon. ## About this repository This repository contains requirements, scenarios, and specifications for the Notary Project: - [Requirements](./requirements/): The Notary Project goals, scenarios, and requirements are stored in this folder. -- [Specification](./specs/): The Notary Project specifications are stored in this folder. You can develop your own implementation based on the specifications. The Notary Project specifications includes +- [Specification](./specs/): The Notary Project specifications are stored in this folder. You can develop your own implementation based on the specifications. The Notary Project specifications now includes: - The Notary Project signature specification - The Notary Project signature envelope specifications: JWS and COSE - The signing and verifying specifications - The trust store and trust policy specification - The plugin specification -- [Threat Model](./threatmodel.md): General threat modeling for the Notary Project. We are now working on threat model for Notation CLI `notation`, Notation libraries `notation-go` and `notation-core-go`. +- [Threat Model](./threatmodel.md): General threat modeling for the Notary Project. We are also working on specific threat model for repositories Notation CLI `notation`, Notation libraries `notation-go` and `notation-core-go`. ## Community @@ -56,5 +56,5 @@ You can reach the Notary Project community and developers via the following chan - Slack: Join the [Notary Project community channel](https://app.slack.com/client/T08PSQ7BQ/CQUH8U287/) for discussion and ask questions - Twitter: [@NotaryProject](https://mobile.twitter.com/NotaryProject) - Meetings: Join the [Community meetings](https://notaryproject.dev/community/#community-meetings) - - Active meeting notes are captured at [the Notary Project meeting notes](https://hackmd.io/_vrqBGAOSUC_VWvFzWruZw?view) - - Archived meeting notes are stored at [meeting-notes repository](https://github.com/notaryproject/meeting-notes) \ No newline at end of file + - Active meeting notes are captured at the [Notary Project meeting notes](https://hackmd.io/_vrqBGAOSUC_VWvFzWruZw?view) + - Archived meeting notes are stored at the [meeting-notes repository](https://github.com/notaryproject/meeting-notes) \ No newline at end of file From 7f6ba7d16b466f2a36f3f7bd729034a20bd1d7ca Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Sun, 11 Jun 2023 10:31:52 +0800 Subject: [PATCH 3/8] update typos Signed-off-by: Yi Zha --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 30965d13..9ca87658 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # The Notary Project Overview -The Notary Project aims to provide enterprise-grade solutions and cross-industry standards for securing software supply chain. The following are current repositories, aka sub-projects, under the Notary Project umbrella in Alphabetical order: +The Notary Project aims to provide enterprise-grade solutions and cross-industry standards for securing software supply chain. The following are current repositories, aka sub-projects, under the Notary Project umbrella in an alphabetical order: | Repository | Description | | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -19,10 +19,10 @@ The Notary Project aims to provide enterprise-grade solutions and cross-industry The Notary Project is now in active development. The latest release announcement will be published on [the Notary Project website](https://notaryproject.dev/blog/). The Notary community uses the [project board](https://github.com/orgs/notaryproject/projects/10) for project planning and status tracking. You can also use GitHub milestones to track the progress: +- [Notary](https://github.com/notaryproject/notary/milestones) - [Notation CLI](https://github.com/notaryproject/notation/milestones) - [Notation library notation-go](https://github.com/notaryproject/notation-go/milestones) - [Notation library notation-core-go](https://github.com/notaryproject/notation-core-go/milestones) -- [Notary](https://github.com/notaryproject/notary/milestones) > Note: The original intention of [roadmap repository](https://github.com/notaryproject/roadmap) is to maintain the roadmap issues for the Notary Project, but we are now moving these issues to correspondent repositories. We will finally archive roadmap repository. From 1c34771d0223e004c31c4616b22f3ce51fdc02cd Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 20 Jul 2023 18:10:25 +0800 Subject: [PATCH 4/8] update Signed-off-by: Yi Zha --- README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/README.md b/README.md index 89c33550..54bf1807 100644 --- a/README.md +++ b/README.md @@ -34,12 +34,8 @@ The Notary Project has had several public security audits: - [July 31, 2015 by NCC](https://github.com/notaryproject/notary/blob/master/docs/resources/ncc_docker_notary_audit_2015_07_31.pdf) covering `Notary` repository - [Mar 21, 2023 by ADA Logics](https://github.com/notaryproject/notaryproject/blob/main/security/reports/fuzzing/ADA-fuzzing-audit-22-23.pdf) fuzzing audit covering `Notary`, `notation-go` and `notation-core-go` repositories -![Notary v2 scenarios](./media/notary-e2e-scenarios.svg) - ## About this repository -![Notary v2 dependent projects](./media/oss-project-sequence.svg) - - [Requirements](./requirements/): The Notary Project goals, scenarios, and requirements are stored in this folder. - [Specification](./specs/): The Notary Project specifications are stored in this folder. You can develop your own implementation based on the specifications. The Notary Project specifications now includes: - The Notary Project signature specification From cf8be835c77bbb9923bdf4f04b6bc087cbb45bee Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Wed, 26 Jul 2023 17:31:31 +0800 Subject: [PATCH 5/8] update per aligned proposal Signed-off-by: Yi Zha --- README.md | 96 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 54 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 54bf1807..cd12717d 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,68 @@ -# The Notary Project Overview +# Notary Project Specifications -The Notary Project aims to provide enterprise-grade solutions and cross-industry standards for securing software supply chain. The following are current repositories, aka sub-projects, under the Notary Project umbrella in an alphabetical order: +This repositories is in active maintenance and contains specifications shared across repositories under Notary Project as well as used by other open source projects and/or vendor tools that want to interoperate with Notary Project tooling. -| Repository | Description | -| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------| -| [.github](https://github.com/notaryproject/.github) | The repository that contains the Notary Project governance documents | -| [meeting-notes](https://github.com/notaryproject/meeting-notes) | The repository that contains archived meeting notes | -| [notary](https://github.com/notaryproject/notatry) | The repository that is an implementation of TUF that runs next to a container registry and adds the ability to sign and verify content in the registry | -| [notaryproject](https://github.com/notaryproject/notatryproject) | The repository that contains the Notary Project requirements and specifications | -| [notaryproject.dev](https://github.com/notaryproject/notatryproject.dev) | The repository that contains documents and styles for the Notary Project website | -| [notation](https://github.com/notaryproject/notation) | The repository that is an implementation of the Notary Project specification and provides a CLI tooling to sign and verify artifacts | -| [notation-go](https://github.com/notaryproject/notation-go) | The repository that is an implementation of the Notary Project specification and provides the library supports of signing and verifying artifacts | -| [notation-core-go](https://github.com/notaryproject/notation-core-go) | The repository that is an implementation of the Notary Project signature specification and provides the library supports | -| [roadmap](https://github.com/notaryproject/roadmap) | The repository that contains roadmap issues for the Notary Project | -| [tuf](https://github.com/notaryproject/tuf) | The repository that implements the full TUF specification in a registry native way | +Please see the Notary Project [README](https://github.com/notaryproject/.github/blob/main/README.md) file to learn about overall Notary Project. -## Project Status +In this README -The Notary Project is now in active development. The latest release announcement will be published on [the Notary Project website](https://notaryproject.dev/blog/). The Notary community uses the [project board](https://github.com/orgs/notaryproject/projects/10) for project planning and status tracking. You can also use GitHub milestones to track the progress: +- [Folder Structure](#folder-structure) +- [Requirements](#requirements) +- [Security Documents](#security-documents) +- [Specifications](#specifications) +- [Threat Models](#threat-models) +- [Community](#community) -- [Notary](https://github.com/notaryproject/notary/milestones) -- [Notation CLI](https://github.com/notaryproject/notation/milestones) -- [Notation library notation-go](https://github.com/notaryproject/notation-go/milestones) -- [Notation library notation-core-go](https://github.com/notaryproject/notation-core-go/milestones) +## Folder Structure -> Note: The original intention of [roadmap repository](https://github.com/notaryproject/roadmap) is to maintain the roadmap issues for the Notary Project, but we are now moving these issues to correspondent repositories. We will finally archive roadmap repository. +| Folder Name | Description | +| --------------| -------------| +| [media](./media/) | Media files referenced by documents in this repository | +| [requirements](./requirements/) | Requirements for Notary Project | +| [security](./security/) | Notary Project security related documents and reports | +| [specs](./specs/) | Notary Project specifications | +| [status-updates](./status-updates/) | This folder is not in active maintenance and contains status updates report for Notary Project | +| [threatmodels](./threatmodels/) | Threat models for repositories under Notary Project | -## Security +## Requirements -The Notary Project has had several public security audits: +| Name | Description | +| -------- | ----------- | +| [definitions-terms.md](./requirements/definitions-terms.md) | A collection of definitions and terms used within this repository | +| [key-revocation.md](./requirements/key-revocation.md) | Requirements and proposals for key revocation | +| [keymanagementrequirements.md](./requirements/keymanagementrequirements.md) | Requirements for key management | +| [requirements.md](./requirements/requirements.md) | A collection of requirements and scenarios for Notary Project | +| [scenarios.md](./requirements/scenarios.md) | Notary Project signing scenarios | +| [verification-by-reference.md](./requirements/verification-by-reference.md) | Requirement of verification by reference | -- [August 7, 2018 by Cure53](https://github.com/notaryproject/notary/blob/master/docs/resources/cure53_tuf_notary_audit_2018_08_07.pdf)) covering `TUF` and `Notary` repositories -- [July 31, 2015 by NCC](https://github.com/notaryproject/notary/blob/master/docs/resources/ncc_docker_notary_audit_2015_07_31.pdf) covering `Notary` repository -- [Mar 21, 2023 by ADA Logics](https://github.com/notaryproject/notaryproject/blob/main/security/reports/fuzzing/ADA-fuzzing-audit-22-23.pdf) fuzzing audit covering `Notary`, `notation-go` and `notation-core-go` repositories +## Security Documents -## About this repository +| Name | Description | +| -------- | ----------- | +| [ADA-notation-security-audit-23.pdf](./security/reports/audit/ADA-notation-security-audit-23.pdf) | Security audit report in 2023 covering [notation](https://github.com/notaryproject/notation), [notation-go](https://github.com/notaryproject/notation-go), and [notation-core-go](https://github.com/notaryproject/notation-core-go) repositories | +| [ADA-fuzzing-audit-22-23.pdf](./security/reports/fuzzing/ADA-fuzzing-audit-22-23.pdf) | Fuzz testing audit in 2023 covering [notary](https://github.com/notaryproject/notaty), [notation-go](https://github.com/notaryproject/notation-go), and [notation-core-go](https://github.com/notaryproject/notation-core-go) repositories | -- [Requirements](./requirements/): The Notary Project goals, scenarios, and requirements are stored in this folder. -- [Specification](./specs/): The Notary Project specifications are stored in this folder. You can develop your own implementation based on the specifications. The Notary Project specifications now includes: - - The Notary Project signature specification - - The Notary Project signature envelope specifications: JWS and COSE - - The signing and verifying specifications - - The trust store and trust policy specification - - The plugin specification -- [Threat Model](./threatmodel.md): General threat modeling for the Notary Project. We are also working on specific threat model for repositories Notation CLI `notation`, Notation libraries `notation-go` and `notation-core-go`. +## Specifications -## Community +| Name | Description | +| -------- | ----------- | +| [plugin-extensibility.md](./specs/plugin-extensibility.md) | Notation Plugin specification | +| [signature-envelope-cose.md](./specs/signature-envelope-cose.md) | Notary Project OCI COSE signature envelope | +| [signature-envelope-jws.md](./specs/signature-envelope-jws.md) | Notary Project OCI JWS signature envelope | +| [signature-specification.md](./specs/signature-specification.md) | Notary Project OCI signature specification | +| [signing-and-verification-workflow.md](./specs/signing-and-verification-workflow.md) | Notary Project OCI signing and verification workflow | +| [signing-scheme.md](./specs/signing-scheme.md) | Notary Project signing scheme| +| [trust-store-trust-policy.md](./specs/trust-store-trust-policy.md) | Notation Trust Store and Trust Policy | + + +## Threat Models -You can reach the Notary Project community and developers via the following channels: +| Name | Description | +| -------- | ----------- | +| [notation-threatmodel.md](./threatmodels/notation-threatmodel.md) | Threat modes for [Notation CLI](https://github.com/notaryproject/notation) | + +## Community -- Slack: Join the [Notary Project community channel](https://app.slack.com/client/T08PSQ7BQ/CQUH8U287/) for discussion and ask questions -- Twitter: [@NotaryProject](https://mobile.twitter.com/NotaryProject) -- Meetings: Join the [Community meetings](https://notaryproject.dev/community/#community-meetings) - - Active meeting notes are captured at the [Notary Project meeting notes](https://hackmd.io/_vrqBGAOSUC_VWvFzWruZw?view) - - Archived meeting notes are stored at the [meeting-notes repository](https://github.com/notaryproject/meeting-notes) \ No newline at end of file +If you have any questions about Notary Project or contributing, do not hesitate to file an issue on relevant repository or contact the Notary Project maintainers and community members via the following channels: +- Join the [Notary Project community slack channel](https://app.slack.com/client/T08PSQ7BQ/CQUH8U287/) +- Join the [Community meetings](https://notaryproject.dev/community/#community-meetings) \ No newline at end of file From 1acfb952513fe9c433028bd28f7597024f047383 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Wed, 26 Jul 2023 17:42:47 +0800 Subject: [PATCH 6/8] update per aligned proposal Signed-off-by: Yi Zha --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index cd12717d..8b9ec450 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ In this README ## Requirements -| Name | Description | +| File Name | Description | | -------- | ----------- | | [definitions-terms.md](./requirements/definitions-terms.md) | A collection of definitions and terms used within this repository | | [key-revocation.md](./requirements/key-revocation.md) | Requirements and proposals for key revocation | @@ -37,14 +37,14 @@ In this README ## Security Documents -| Name | Description | +| File Name | Description | | -------- | ----------- | | [ADA-notation-security-audit-23.pdf](./security/reports/audit/ADA-notation-security-audit-23.pdf) | Security audit report in 2023 covering [notation](https://github.com/notaryproject/notation), [notation-go](https://github.com/notaryproject/notation-go), and [notation-core-go](https://github.com/notaryproject/notation-core-go) repositories | | [ADA-fuzzing-audit-22-23.pdf](./security/reports/fuzzing/ADA-fuzzing-audit-22-23.pdf) | Fuzz testing audit in 2023 covering [notary](https://github.com/notaryproject/notaty), [notation-go](https://github.com/notaryproject/notation-go), and [notation-core-go](https://github.com/notaryproject/notation-core-go) repositories | ## Specifications -| Name | Description | +| File Name | Description | | -------- | ----------- | | [plugin-extensibility.md](./specs/plugin-extensibility.md) | Notation Plugin specification | | [signature-envelope-cose.md](./specs/signature-envelope-cose.md) | Notary Project OCI COSE signature envelope | @@ -57,9 +57,9 @@ In this README ## Threat Models -| Name | Description | +| File Name | Description | | -------- | ----------- | -| [notation-threatmodel.md](./threatmodels/notation-threatmodel.md) | Threat modes for [Notation CLI](https://github.com/notaryproject/notation) | +| [notation-threatmodel.md](./threatmodels/notation-threatmodel.md) | Threat models for [Notation CLI](https://github.com/notaryproject/notation) | ## Community From 90cdf26e4781f98098fd331c53b1336fedda0122 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 31 Jul 2023 17:04:28 +0800 Subject: [PATCH 7/8] update per comments Signed-off-by: Yi Zha --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8b9ec450..c60c2cc5 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Notary Project Specifications -This repositories is in active maintenance and contains specifications shared across repositories under Notary Project as well as used by other open source projects and/or vendor tools that want to interoperate with Notary Project tooling. +This repository is in active maintenance and contains specifications shared across repositories under Notary Project as well as used by other open source projects and/or vendor tools that want to interoperate with Notary Project tooling. Please see the Notary Project [README](https://github.com/notaryproject/.github/blob/main/README.md) file to learn about overall Notary Project. From 6f8296d26a27c136b65a2667111eed2b09b7f75f Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 3 Aug 2023 14:46:10 +0800 Subject: [PATCH 8/8] update per comments Signed-off-by: Yi Zha --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c60c2cc5..313d7500 100644 --- a/README.md +++ b/README.md @@ -52,7 +52,7 @@ In this README | [signature-specification.md](./specs/signature-specification.md) | Notary Project OCI signature specification | | [signing-and-verification-workflow.md](./specs/signing-and-verification-workflow.md) | Notary Project OCI signing and verification workflow | | [signing-scheme.md](./specs/signing-scheme.md) | Notary Project signing scheme| -| [trust-store-trust-policy.md](./specs/trust-store-trust-policy.md) | Notation Trust Store and Trust Policy | +| [trust-store-trust-policy.md](./specs/trust-store-trust-policy.md) | Notary Project Trust Store and Trust Policy | ## Threat Models