diff --git a/media/notary-e2e-scenarios.svg b/media/notary-e2e-scenarios.svg deleted file mode 100644 index 7542bce8..00000000 --- a/media/notary-e2e-scenarios.svg +++ /dev/null @@ -1 +0,0 @@ -ScopeWabbitNetworks2Public RegistryNotary v2 ScopeInteroperability with other projectsSBoMsrcImageArtifact Build Environment14PolicyManagement5ContainerHost3Private RegistrySBoMsrcImageDocker HubACME RocketsSBoMsrcImagedeployArtifact PushArtifact ImportArtifact DeploymentImageAir-gapped network \ No newline at end of file diff --git a/media/notary-project-e2e-scenarios.svg b/media/notary-project-e2e-scenarios.svg new file mode 100644 index 00000000..9e0bd10b --- /dev/null +++ b/media/notary-project-e2e-scenarios.svg @@ -0,0 +1 @@ +ScopeWabbitNetworks2Public RegistryNotary Project ScopeInteroperability with other projectsSBoMsrcImageArtifact Build Environment14PolicyManagement5ContainerHost3Private RegistrySBoMsrcImageDocker HubACME RocketsSBoMsrcImagedeployArtifact PushArtifact ImportArtifact DeploymentImageAir-gapped network \ No newline at end of file diff --git a/requirements/key-revocation.md b/requirements/key-revocation.md index 9a8a31d0..ce8cf29f 100644 --- a/requirements/key-revocation.md +++ b/requirements/key-revocation.md @@ -1,6 +1,6 @@ # Key Revocation -One of the goals of Notary v2 is to build in solutions for key revocation that are easy to use and ensure that users will always use non-compromised keys. +One of the goals of Notary Project is to build in solutions for key revocation that are easy to use. This document discusses some potential mechanisms for key revocation. In existing systems, there are three main approaches to key revocation: automatic revocation through key expiration, key revocation lists, and providing a list of trusted keys. diff --git a/requirements/requirements.md b/requirements/requirements.md index 138c8b1a..66c31f4a 100644 --- a/requirements/requirements.md +++ b/requirements/requirements.md @@ -1,9 +1,10 @@ # Requirements -A collection of requirements and scenarios, framing the scope of the Notary v2 project. +A collection of requirements and scenarios, framing the scope of Notary Project. ## TOC + - [Goals](#goals) - [Non Goals](#non-goals) - [Scenarios](./scenarios.md) @@ -14,27 +15,27 @@ A collection of requirements and scenarios, framing the scope of the Notary v2 p ## Goals -Notary v2 aims to address the learnings and gaps of v1, while prioritizing a set of goals and [scenarios](./scenarios.md). +Notary Project aims to address the learnings and limitations of [TUF-based implementation](https://github.com/notaryproject/notary), while establishing and prioritizing a set of goals and [scenarios](./scenarios.md) for new implementation (this repository). 1. Offline signature creation 1. Signatures attesting to authenticity and/or certification 1. Maintain the original artifact digest and collection of associated tags, supporting existing dev through deployment workflows 1. Multiple signatures per artifact, enabling the originating vendor signature, public registry certification and user/environment signatures -1. Native persistance within an [OCI Artifact][oci-artifacts] enabled, [distribution-spec][distribution-spec] based registry -1. Artifact and signature copying within and across [OCI Artifact][oci-artifacts] enabled, [distribution-spec][distribution-spec] based registries +1. Native persistance within an [OCI image specification v1.1][oci-image-spec] enabled, [OCI distribution specification v1.1][oci-distribution] compliant registry +1. Artifact and signature copying within and across an [OCI image specification v1.1][oci-image-spec] enabled, [OCI distribution specification v1.1][oci-distribution] compliant registries 1. Support multi-tenant registries enabling cloud providers and enterprises to support managed services at scale 1. Support private registries, where public content may be copied to, and new content originated within 1. Air-gapped environments, where the originating registry of content is not accessible 1. Key hierarchies and delegation 1. Key revocation, including private and air-gapped registries 1. Key acquisition must support users from hobbyists, open source projects to large software vendors -1. Usable workflows, enabled for the masses to easily create and consume Notary v2 signatures +1. Usable workflows, enabled for adopters to easily create and consume Notary Project signatures ## Non Goals 1. Trust on first use 1. Implicit permissions on rotated keys -1. Compatibility with Notary v1 +1. Compatibility with [TUF-based implementation](https://github.com/notaryproject/notary) ## Key Stake Holders & Contributors @@ -58,22 +59,20 @@ As we identify the requirements and constraints, a number of key contributors wi - [Mirantis Container Runtime (formerly Docker Engine – Enterprise)][mirantis-runtime] - [Mirantis Kubernetes Engine (mke, formerly Docker Enterprise/UCP)][mke] - Artifact Types - - [OCI & Docker Container Images][image-spec] + - [OCI & Docker Container Images][oci-image-spec] - [Helm Charts][helm-registry] - [Singularity][singularity] - Operator Bundles ## Contributing & Conversations -Regular conversations for Notary v2 occur on the [Cloud Native Computing Slack](https://app.slack.com/client/T08PSQ7BQ/CQUH8U287?) channel. +Regular conversations for Notary Project occur on the [Cloud Native Computing Slack](https://app.slack.com/client/T08PSQ7BQ/CQUH8U287?) channel. Weekly meetings occur each Monday. Please see the [CNCF Calendar](https://www.cncf.io/community/calendar/) for details. Meeting notes are captured on [hackmd.io](https://hackmd.io/_vrqBGAOSUC_VWvFzWruZw). -[distribution-spec]: https://github.com/opencontainers/distribution-spec -[oci-artifacts]: https://github.com/opencontainers/artifacts [acr]: https://aka.ms/acr/artifacts [artifacts-repo]: https://github.com/opencontainers/artifacts [docker-hub]: https://hub.docker.com/ @@ -86,12 +85,10 @@ Meeting notes are captured on [hackmd.io](https://hackmd.io/_vrqBGAOSUC_VWvFzWru [harbor]: https://goharbor.io/ [icr]: https://icr.io/ [helm-registry]: https://v3.helm.sh/docs/topics/registries/ -[image-spec]: https://github.com/opencontainers/image-spec [jfrog]: https://jfrog.com/integration/docker-registry/ [oci-distribution]: https://github.com/opencontainers/distribution-spec -[oci-image]: https://github.com/opencontainers/image-spec +[oci-image-spec]: https://github.com/opencontainers/image-spec [oci-index]: https://github.com/opencontainers/image-spec/blob/master/image-index.md -[oci-manifest]: https://github.com/opencontainers/image-spec/blob/master/manifest.md [oci-tob]: https://github.com/opencontainers/tob [singularity]: https://github.com/sylabs/singularity [quay]: https://quay.io/ diff --git a/requirements/scenarios.md b/requirements/scenarios.md index f11a1fb7..f5c1e576 100644 --- a/requirements/scenarios.md +++ b/requirements/scenarios.md @@ -1,23 +1,23 @@ -# Notary v2 Signing Scenarios +# Notary Project Signing Scenarios As containers and cloud native artifacts become the common unit of deployment, users want to know the artifacts in their environments are authentic and unmodified. -These Notary v2 scenarios define end-to-end scenarios for signing artifacts in a generalized way, storing and moving them between OCI compliant registries, validating them with various artifact hosts and tooling. -Notary v2 focuses on the signing of content, enabling e2e workflows, without specifying what those workflows must be. +Notary Project signing scenarios define end-to-end scenarios for signing artifacts in a generalized way, storing and moving them between OCI compliant registries, validating them with various artifact hosts and tooling. +Notary Project focuses on the signing of content, enabling end-to-end (e2e) workflows, without specifying what those workflows must be. -By developing a generalized solution, artifact authors may develop their unique artifact types, allowing them to leverage Notary for signing and OCI Compliant registries for distribution. +By developing a generalized solution, artifact authors may develop their unique artifact types, allowing them to leverage [Notary Project signature specification](../specs/signature-specification.md) for signing and OCI Compliant registries for distribution. ## Scenarios -Notary v2 aims to solve the core issue of trusting content within, and across registries. -There are many elements of an end to end scenario that are not implemented by Notary v2, rather enabled because the content is verifiable. +Notary Project aims to solve the core issue of trusting content within, and across registries. +There are many elements of an e2e scenario that are not in the scope of Notary Project, rather enabled because the content is verifiable. ### Scenario #0: Build, Publish, Consume, Enforce Policy, Deploy -To put Notary v2 in context, the following end-to-end scenario is outlined. -The blue elements are the scope of Notary v2, with the other elements providing generic references to other projects or products that demonstrate how Notary v2 may be utilized. +To put Notary Project in context, the following end-to-end scenario is outlined. +The blue elements are the scope of Notary Project, with the other elements providing generic references to other projects or products that demonstrate how Notary Project may be utilized. -![Notary e2e Scenarios](/media/notary-e2e-scenarios.svg) +![Notary Project e2e Scenarios](/media/notary-project-e2e-scenarios.svg) In a world of consuming public software, we must account for content that's acquired from a public source, copied into a trusted environment, then deployed. In this scenario, the consumer is not re-building or adding additional content. @@ -26,7 +26,7 @@ However, they do wish to add attestations to the validity of the content. 1. The Wabbit Networks company builds their `net-monitor` software. - As a result of the build, they produce an [OCI Image][oci-image], a Software Bill of Materials (`SBoM`) and to comply with gpl licensing, produce another artifact which contains the source (`src`) to all the gpl licensed projects. - The `SBoM` and `src` artifacts are created as reference types to the image, creating a graph of artifacts. - - Each of the artifacts are signed with the Notary v2 wabbit-networks key. + - Each of the artifacts are signed with the wabbit-networks key. 1. The Wabbit Networks signed contents are pushed to a public OCI compliant registry. - Docker can provide an additional Docker hub signature providing an extra level of certification confidence. 1. ACME Rockets consumes the `net-monitor` software, importing the referenced artifacts into their private registry. @@ -45,7 +45,7 @@ However, they do wish to add attestations to the validity of the content. - Signatures can be placed on any type of [artifact](artifacts-repo) stored in an OCI compliant registry using an [OCI Manifest][oci-manifest] - Signatures can be persisted as references to the [OCI Manifest][oci-manifest], allowing a entity to define a collection of artifacts. -- Signatures and their public keys can be moved within, and across OCI compliant registries which support Notary v2. +- Signatures and their public keys can be moved within, and across OCI compliant registries which support Notary Project signatures. - Because content is trusted, an ecosystem of other projects and products can leverage information in various formats. ### Scenario #1: Local Build, Sign, Validate @@ -89,8 +89,8 @@ Once the developer has locally validated the build, sign, validate scenario, the - The artifact can be renamed from the unique build id `net-monitor:abc123` to a product versioned tag `wabbitnetworks.example.com/networking/net-monitor:1.0` without invalidating the signature. - Users may reference the `sha256` digest directly, or the `artifact:tag`. While tag locking is not part of the [OCI Distribution Spec][oci-distribution], various registries support this capability, allowing users to reference human readable tags, as opposed to long digests. - Either reference is supported with Notary v2, however it's the unique manifest that is signed. -- Notary v2 supports a pattern for signing any type of artifact, from OCI Images, Helm Charts, Singularity to yet unknown types. + Either reference is supported with Notary Project, however it's the unique manifest that is signed. +- Notary Project supports a pattern for signing any type of artifact, from OCI Images, Helm Charts, Singularity to yet unknown types. - Orchestrators may require signatures, but not enforce specific specific signatures. This enables a host to understand what content is deployed, without having to manage specific keys. @@ -213,8 +213,7 @@ They pushed unsigned content to existing tags. 1. How a registry implements the rollback to the previously secured state is a differentiating capability. The scenario simply calls out a compromise that must be discoverable through forensic logging of who, when and what was pushed. The logged updates must include previous digests that represented updated tags allowing a registry, or external tools, to reset its original state. -1. A registry may choose to make repos, or the entire registry, restricted to pushing only signed content, and potentially only signed content with one or more keys. - Notary v2 doesn't require this capability, rather highlights the scenario for registry operators to innovate means to secure from this scenario. +1. A registry may choose to restrict repositories or the entire registry to pushing only signed content, and potentially only signed content with one or more keys. With this, attackers cannot push unsigned content to the registry, mitigating the threat described by scenario #7. #### Scenario #7.1: Repository Compromise - Mutable Tags Modified @@ -253,9 +252,9 @@ A developer accidentally discloses the private key they use to certify their sof **Implications of this requirement:** -1. All Notary v2 implementations support key revocation as part of their implementation to assure signed content is still valid content. +1. All implementations of the [Notary Project signature specification](../specs/signature-specification.md) support key revocation as part of their implementation to assure signed content is still valid content. 1. Registry operators routinely check for revoked keys and remediate the exploited content. -1. Notary v2 clients routinely check for revoked keys and block the content. +1. Implementations of the [Notary Project verification specification](../specs/signing-and-verification-workflow.md) routinely check for revoked keys and block the content. ### Scenario #9: A Crypto Algorithm Is Deprecated @@ -282,7 +281,7 @@ Maybe this is an internally created artifact with a known signing key. This key may be distributed using a trusted third party mechanism. 1. The user obtains a trusted key for a particular artifact. -1. The user downloads and verifies the artifact using Notary v2 and their known key. +1. The user downloads and verifies the artifact using implementations of the [Notary Project verification specification](../specs/signing-and-verification-workflow.md) and their public key. **Implications of this requirement:** @@ -310,7 +309,7 @@ It should be possible for the signer to revoke the trust in that vulnerable arti If a user does not have a specific key for a given artifact, verified using a third party system, they will need to determine the trusted signing key(s) for an artifact by chaining from a trusted key. 1. The user determines the trusted key(s) for a specific artifact using delegations from a trusted root. -1. The user downloads and verifies an artifact using Notary v2 and the trusted key(s) discovered in the previous step. +1. The user downloads and verifies an artifact using implementations of the [Notary Project verification specification](../specs/signing-and-verification-workflow.md) and the trusted key(s) discovered in the previous step. **Implications of this requirement:** diff --git a/requirements/verification-by-reference.md b/requirements/verification-by-reference.md index 401320dc..7719a747 100644 --- a/requirements/verification-by-reference.md +++ b/requirements/verification-by-reference.md @@ -1,11 +1,11 @@ -# Notary v2 - Verification by Reference +# Notary Project - Verification by Reference 5/1/2020 [Steve Lasker](https://github.com/SteveLasker) ## Overview -One of the many questions of Notary v2 is how will verification (signatures) be persisted within a registry. +One of the many questions of Notary Project is how verification (signatures) will be persisted within a registry. This paper outlines an option for persisting verification content as additional artifacts in the registry, with a reverse lookup. This would enable multiple verifications to exist without changing the original artifact, or the digest of the original content. @@ -24,23 +24,23 @@ This doc experiments with the avoidance of signatures as the reference. 1. A collection of verification objects may be associated with an artifact. 1. Leverage the garbage collection infrastructure registry operators have implemented. Garbage collection represents significant investments for registry services which are based on OCI Manifest and OCI Index. - We should aim to utilize these existing schemas, or only slight verifications from them to maximize the opportunity for registry implementations to adopt Notary v2. + We should aim to utilize these existing schemas, or only slight verifications from them to maximize the opportunity for registry implementations to adopt [Notary Project signature specification](../specs/signature-specification.md). 1. Minimize requirements to change persistence and object stores used by registry operators. Similar to garbage collection, we should work within the constraints of manifest, index and layers to represent verification objects. ## Non-goals 1. Work within the constraints of the existing OCI-distribution spec api set. - Supporting Notary v1, or Docker Content Trust, requires new APIs. + Supporting [TUF-based implementation](https://github.com/notaryproject/notary), or Docker Content Trust, requires new APIs. APIs are comparatively cheap to implement atop the persistence stores of registries. - New APIs should be part of the Notary v2 spec, which may represent changes to the OCI-distribution spec or implementations of a new extension model over the Distribution spec. -1. Compatibility with Notary v1. - Registries that have implemented Notary v1 are looking for a better solution. - We cumulatively have little existing usage, and if successful, we expect all customers would rapidly move to Notary v2 eliminating the need to maintain two sets of APIs for an extended period of time. + New APIs should be part of the [Notary Project signature specification](../specs/signature-specification.md), which may represent changes to the OCI-distribution spec or implementations of a new extension model over the Distribution spec. +1. Compatibility with [TUF-based implementation](https://github.com/notaryproject/notary). + Registries that have implemented [TUF-based implementation](https://github.com/notaryproject/notary) are looking for a better solution. + We cumulatively have little existing usage, and if successful, we expect all adopters would rapidly move to implement [Notary Project signature specification](../specs/signature-specification.md) eliminating the need to maintain two sets of APIs for an extended period of time. ## Adding verifications along a workflow -To address [Notary v2 Scenario #6: Multiple Signatures](https://github.com/notaryproject/requirements/blob/master/scenarios.md#scenario-6-multiple-signatures), an artifact must be capable of having additional signatures (verifications) be added. +To address [scenario #6: Multiple Signatures](./scenarios.md#scenario-6-multiple-signatures), an artifact must be capable of having additional signatures (verifications) added. However, a deployment document (Helm chart, Kube deploy yaml) must not be required to change. 1. A dev team builds a container image, `(web:a2b2)`. @@ -189,12 +189,12 @@ Updating the existing tag could cause inconsistencies as some verification syste **What if** we supported a reverse lookup, where a client can ask for all the verification objects for a given artifact? Reverse lookup refers to the ability to find which manifests are referenced by index objects. -![Two notary artifacts refering a single image](/media/oci-manifest-index-reverse-lookup.png) +![Reverse lookup](/media/oci-manifest-index-reverse-lookup.png) We could still use the oci index schema with two changes: 1. Index is versioned to include `index.config` (artifactType in red) -1. Add a new notary API that finds all indexes, with `"index.config.mediaType": "application/vnd.cncf.notary.verification.v1.config.json"` +1. Add a new API that finds all indexes, with `"index.config.mediaType": "application/vnd.cncf.notary.verification.v1.config.json"` ### web:a2b2 image as an OCI Manifest @@ -225,7 +225,7 @@ Same as above. ### web:a2b2 staging verification w/ index -An index is pushed that supports `index.config`, which tells the registry this index is a type of Notary Verification. +An index is pushed that supports `index.config`, which tells the registry this index is a type of Notary Project Verification. This follows the same pattern we use with [OCI Artifacts to identify oci manifest as specific type](https://github.com/opencontainers/artifacts/blob/master/artifact-authors.md#defining-oci-artifact-types). This index would NOT be pushed with a tag. It would be a digest only reference. @@ -304,7 +304,7 @@ Another index of type `notary.verification`, which adds the scanning verificatio } ``` -The notation client could retrieve all signatures with the following command +Users could retrieve all signatures with the following command ```shell notation verify registry.contoso.com/marketing/web:a2b2 @@ -324,7 +324,7 @@ The pros of this approach are: The cons of this approach: - A new API must be added. - We’ve said this was within scope and ok as registries must add Notary v1, Content Trust to support existing scenarios. + We’ve said this was within scope and ok as registries must add [TUF-based implementation](https://github.com/notaryproject/notary), Content Trust to support existing scenarios. Since most registries need to do some work, adding a new API is not a stretch - Reverse lookup, and its impact on garbage collection. Registries tend to traverse down. @@ -343,9 +343,9 @@ The reverse lookup index could be expanded as follows: ![Multi-platform manifest with SBoM, TUF, and Scan artifacts](/media/oci-manifest-index-reverse-lookup-sbom.png) -The user still references `registry.contoso.com/web:a2b2`, while other parts of the system that adhere to notary v2 would know to query the registry for the additional verification information. +The user still references `registry.contoso.com/web:a2b2`, while other parts of the system that adhere to [Notary Project signature specification](../specs/signature-specification.md) would know to query the registry for the additional verification information. -An notation client queries for all indexes with a `"config.mediaType"` of `"application/vnd.cncf.notary.verification.config.v1+json"` It would read all the verification objects and decide how to proceed. +Notation CLI verify command queries for all indexes with a `"config.mediaType"` of `"application/vnd.cncf.notary.verification.config.v1+json"`. It would read all the verification objects and decide how to proceed. For customers that aren’t comfortable with tags, you could query for the digest of `web:a2b2`. It would return the same list of verification objects. diff --git a/specs/plugin-extensibility.md b/specs/plugin-extensibility.md index 74858e8a..9981d14f 100644 --- a/specs/plugin-extensibility.md +++ b/specs/plugin-extensibility.md @@ -1,11 +1,11 @@ # Notation Extensibility for Signing and Verification -Keys and associated certificates used for signing artifacts using Notary could be available to users through varied solutions that provide secure key generation, storage and cryptographic operations. Some are well established with standards like [PIV](https://csrc.nist.gov/projects/piv/piv-standards-and-supporting-documentation) and [PKCS #11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) implemented by hardware tokens, smart cards. More recent options which use varied authentication and API protocols are remote key management services and signing services by third party vendors and cloud service providers. Notation will support a few built-in integrations with standard providers, and will provide plugin interfaces for users, and vendors to implement their own integrations with the solutions they use. This allows a plugin publisher to implement, test, release and patch their solutions independent of Notation’s development and release cycle. This document provides specification for the plugin model, and interfaces to implement. This specification aims to work both for [existing](./signature-specification.md) and future signature formats adopted by Notary. +Keys and associated certificates used for signing artifacts using Notation could be available to users through varied solutions that provide secure key generation, storage and cryptographic operations. Some are well established with standards like [PIV](https://csrc.nist.gov/projects/piv/piv-standards-and-supporting-documentation) and [PKCS #11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) implemented by hardware tokens, smart cards. More recent options which use varied authentication and API protocols are remote key management services and signing services by third party vendors and cloud service providers. Notation will support a few built-in integrations with standard providers, and will provide plugin interfaces for users, and vendors to implement their own integrations with the solutions they use. This allows a plugin publisher to implement, test, release and patch their solutions independent of Notation’s development and release cycle. This document provides specification for the plugin model, and interfaces to implement. This specification aims to work both for [existing](./signature-specification.md) and future signature formats adopted by Notary Project. ## Terminology * **Plugin Publisher** - A user, organization, open source project or 3rd party vendor that creates a Notation plugin for internal or public distribution. -* **Plugin** - A component external to Notation that can integrate as one of the steps in Notation’s workflow for signature generation or verification. +* **Plugin** - A component external to Notation that can integrate as one of the steps in Notation’s workflow for signature generation or verification. * **Default provider** - Signing and verification mechanisms built into Notation itself to provide default experience without requiring to install/configure additional plugins. ***[We are yet to define what is included in the default experience]***. ## Plugin mechanism @@ -20,7 +20,7 @@ Keys and associated certificates used for signing artifacts using Notary could b * Notation MUST work with a plugin that implements a matching or lower minor version of the plugin contract. Notation SHALL NOT support using a plugin with higher version of plugin contract. * A plugin MUST support a single plugin contract version, per major version. -Notation will invoke plugins as executable, pass parameters using command line arguments, and use standard IO streams to pass request/response payloads. This mechanism is used as Go language (used to develop [Notation library](https://github.com/notaryproject/notation-go)) does not have a [in built support](https://github.com/golang/go/issues/19282) to load and execute plugins that works across OS platforms. Other mechanisms like gRPC require every plugin to be implemented as a service/daemon. +Notation will invoke plugins as executable, pass parameters using command line arguments, and use standard IO streams to pass request/response payloads. This mechanism is used as Go language (used to develop [Notation Go library](https://github.com/notaryproject/notation-go)) does not have a [in built support](https://github.com/golang/go/issues/19282) to load and execute plugins that works across OS platforms. Other mechanisms like gRPC require every plugin to be implemented as a service/daemon. ### Plugin lifecycle management @@ -101,7 +101,7 @@ Plugin config can be also set/overriden during signing with the `notation sign` ### Plugin contract * Notation will invoke the plugin executable for each command (e.g. sign, verify), pass inputs through `stdin` and get output through `stdout` and `stderr`. -* The command will be passed as the first argument to the plugin e.g. `notary-{plugin-name} `. A JSON request is passed using `stdin`. The plugin is expected to return a JSON response through `stdout` with a `0` exit code for successful response, and a non-zero exit code with a JSON error response in `stderr` for error response. Each command defines its request, response and error contract. To avoid any additional content like debug or info level logging from dependencies and inbuilt libraries, the plugin implementation should redirect any output to `stdout` on initialization, and only send the JSON response away from `stdout` when the command execution completes. E.g. For golang, set [`os.Stdout`](https://pkg.go.dev/os#pkg-variables) to point to a log file. +* The command will be passed as the first argument to the plugin e.g. `notation-{plugin-name} `. A JSON request is passed using `stdin`. The plugin is expected to return a JSON response through `stdout` with a `0` exit code for successful response, and a non-zero exit code with a JSON error response in `stderr` for error response. Each command defines its request, response and error contract. To avoid any additional content like debug or info level logging from dependencies and inbuilt libraries, the plugin implementation should redirect any output to `stdout` on initialization, and only send the JSON response away from `stdout` when the command execution completes. E.g. For golang, set [`os.Stdout`](https://pkg.go.dev/os#pkg-variables) to point to a log file. * Every request JSON will contain a `contractVersion` top level attribute whose value will indicate the plugin contract version. Contract version is revised when there are changes to command request/response, new plugin commands are introduced, and supported through Notation. * To maintain forward compatibility plugin implementors MUST ignore unrecognized attributes in command request which are introduced in minor version updates of the plugin contract. * For an error response, every command returns a non-zero exit code 1, with an OPTIONAL JSON error response in `stderr`. It is recommended to return an error response to help user troubleshoot the error. There is no need to send different exit codes for different error conditions, as Notation (which will call the plugin and parse the response) will use `error-code` in the error response to interpret different error conditions if needed. Notation will attempt to parse the error response in `stderr` when exit code is 1, else treat it as a general error for any other non-zero exit codes. @@ -189,20 +189,20 @@ Notation will support plugins to be developed against the following interfaces - ### Signature Generator -This interface targets plugins that integrate with providers of basic cryptographic operations. E.g. Local PIV/PKCS#11 hardware tokens, remote KMS, or key vault services. Plugins that target this interface will only generate a raw signature given a payload to sign. Notation will package this signature into a signature envelope, and generate the signature manifest. Notation will also generate the TSA signature if indicated by the user. The plugin does not need to be signature envelope format aware, and will continue to work if Notary adopts additional signature formats. +This interface targets plugins that integrate with providers of basic cryptographic operations. E.g. Local PIV/PKCS#11 hardware tokens, remote KMS, or key vault services. Plugins that target this interface will only generate a raw signature given a payload to sign. Notation will package this signature into a signature envelope, and generate the signature manifest. Notation will also generate the TSA signature if indicated by the user. The plugin does not need to be signature envelope format aware, and will continue to work if Notary Project adopts additional signature formats. #### Signing workflow using plugin 1. Given a user request to sign `oci-artifact`, with signing key `keyName` (the friendly key name) 2. Pull the image manifest using `oci-artifact` url, and construct a descriptor -3. Append any user provided metadata and Notary metadata as descriptor annotations. +3. Append any user provided metadata and metadata defined in [Notary Project signature specification](signature-specification.md) as descriptor annotations. 4. Determine if the registered key uses a plugin 5. Execute the plugin with `get-plugin-metadata` command 1. If plugin supports capability `SIGNATURE_GENERATOR.RAW` 1. Execute the plugin with `describe-key` command, set `request.keyId` and the optional `request.pluginConfig` to corresponding values associated with signing key `keyName` in `config.json`. 2. Generate the payload to be signed for [JWS](./signature-specification.md#supported-signature-envelopes) envelope format. 1. Create the JWS protected headers collection and set `alg` to value corresponding to `describe-key.response.keySpec` as per [signature algorithm selection](./signature-specification.md#algorithm-selection). - 2. Create the Notary v2 Payload (JWS Payload) as defined [here](./signature-specification.md#payload). + 2. Create the Notary Project signature Payload (JWS Payload) as defined [here](./signature-specification.md#payload). 3. The *payload to sign* is then created as - `ASCII(BASE64URL(UTF8(ProtectedHeaders)) ‘.’ BASE64URL(JWSPayload))` 3. Execute the plugin with `generate-signature` command. 1. Set `request.keyId` and the optional `request.pluginConfig` to corresponding values associated with signing key `keyName` in `config.json`. @@ -335,17 +335,17 @@ All response attributes are required. ### Signature Envelope Generator -This interface targets plugins that in addition to signature generation want to generate the complete signature envelope. This interface allows plugins to have full control over the generated signature envelope, and can append additional signed and unsigned metadata, including timestamp signatures. The plugin must be signature envelope format aware, and implement new formats when Notary adopts new formats. +This interface targets plugins that in addition to signature generation want to generate the complete signature envelope. This interface allows plugins to have full control over the generated signature envelope, and can append additional signed and unsigned metadata, including timestamp signatures. The plugin must be signature envelope format aware, and implement new formats when Notary Project adopts new formats. #### Signing workflow using plugin 1. Given a user request to sign `image`, with `keyName` (friendly key name) 1. Pull the image manifest using `image` url, and construct a descriptor -1. Append any user provided metadata and Notary metadata as descriptor annotations. +1. Append any user provided metadata and metadata defined in [Notary Project signature specification](signature-specification.md) as descriptor annotations. 1. Determine if the registered key uses a plugin 1. Execute the plugin with `get-plugin-metadata` command 1. If plugin supports capability `SIGNATURE_GENERATOR.ENVELOPE` - 1. Execute the plugin with `generate-envelope` command. Set `request.keyId` and the optional `request.pluginConfig` to corresponding values associated with signing key `keyName` in `config.json`. Set `request.payload` to base64 encoded [Notary v2 Payload](./signature-specification.md#payload), `request.payloadType` to `application/vnd.cncf.notary.payload.v1+json` and `request.signatureEnvelopeType` to a pre-defined type (`application/jose+json` for JWS). + 1. Execute the plugin with `generate-envelope` command. Set `request.keyId` and the optional `request.pluginConfig` to corresponding values associated with signing key `keyName` in `config.json`. Set `request.payload` to base64 encoded the [Notary Project signature Payload](./signature-specification.md#payload), `request.payloadType` to `application/vnd.cncf.notary.payload.v1+json` and `request.signatureEnvelopeType` to a pre-defined type (`application/jose+json` for JWS). 2. `response.signatureEnvelope` contains the base64 encoded signature envelope, value of `response.signatureEnvelopeType` MUST match `request.signatureEnvelopeType`. 3. Validate the generated signature, return an error if of the checks fails. 1. Check if `response.signatureEnvelopeType` is a supported envelope type and `response.signatureEnvelope`'s format matches `response.signatureEnvelopeType`. @@ -433,7 +433,7 @@ All response attributes are required. * Revocation check validation * The interface MAY be extended in future to support additional steps which can be customized through a plugin. * The interface MUST be agnostic of sequencing of steps in signature verification workflow as implemented in Notation or other implementations. -* The interface MUST allow processing of [extended attributes](./signature-specification.md#extended-attributes) that are not part of Notary v2 [standard attributes](./signature-specification.md#standard-attributes). +* The interface MUST allow processing of [extended attributes](./signature-specification.md#extended-attributes) that are not part of the Notary Project signature [standard attributes](./signature-specification.md#standard-attributes). ### Guidelines for Verification plugin publishers @@ -443,7 +443,7 @@ Therefore, signatures intended for public distribution which require broad signa * Signatures which require a plugin for verification may be distributed privately (e.g. within an organization) or publicly (e.g. via a public registry). If the plugin publisher wants their plugin used publicly they SHOULD publish specifications for the verification logic the plugin performs and test vectors. -This allows Notary v2 implementations to perform the same logic themselves, if they choose to. +This allows implementations of the [Notary Project signature specification](./signature-specification.md) to perform the same logic themselves, if they choose to. ### Signature Verifier @@ -461,7 +461,7 @@ This allows Notary v2 implementations to perform the same logic themselves, if t 3. Complete steps *Validate Integrity, Validate Expiry* and *Validate Trust Store* from [signature verification workflow](./trust-store-trust-policy.md#steps). 4. Based on the signature verification level, each validation may be enforced, logged or skipped. 5. Populate `verify-signature` request. NOTE: The processing order of remaining known attributes does not matter as long as they are processed before the end of signature verification workflow. - 1. Set `request.signature.criticalAttributes` to the set of [standard Notary v2 attributes](./signature-specification.md#standard-attributes) that are marked critical, from the signature envelope. + 1. Set `request.signature.criticalAttributes` to the set of [standard Notary Project signature attributes](./signature-specification.md#standard-attributes) that are marked critical, from the signature envelope. 2. Set `request.signature.criticalAttributes.extendedAttributes` to extended attributes that Notation does not recognize. Notation only supports JSON primitive types for critical extended attributes. If a signature producer required complex types, it MUST set the value to a primitive type by encoding it (e.g. Base64), and MUST be decoded by the plugin which processed the attribute. 3. Set `request.signature.unprocessedAttributes` to set of critical attribute names that are marked critical, but unknown to Notation, and therefore cannot be processed by Notation. 4. Set `request.signature.certificateChain` to ordered array of certificates from signing envelope. @@ -484,7 +484,7 @@ This allows Notary v2 implementations to perform the same logic themselves, if t "contractVersion" : "", "signature" : { - // Array of all Notary V2 defined critical attributes and their values + // Array of all the Notary Project defined critical attributes and their values // in the signature envelope. Agnostic of header names and value serialization // in specific envelope formats like JWS or COSE. "criticalAttributes" : diff --git a/specs/signature-envelope-cose.md b/specs/signature-envelope-cose.md index bf9def3c..b23ed9fb 100644 --- a/specs/signature-envelope-cose.md +++ b/specs/signature-envelope-cose.md @@ -1,20 +1,24 @@ # COSE Sign1 Signature Envelope -This specification implements the [Notary v2 Signature specification](signature-specification.md) using +This specification implements the [Notary Project signature specification](signature-specification.md) using CBOR Object Signing and Encryption (COSE). COSE ([RFC8152](https://datatracker.ietf.org/doc/html/rfc8152)) is a CBOR based envelope format for digital signatures over any type of payload (e.g. CBOR, JSON, binary). -Notary v2 specifically supports [COSE_Sign1_Tagged](https://datatracker.ietf.org/doc/html/rfc8152#section-4.2) as a signature envelope. +Notary Project specifically supports [COSE_Sign1_Tagged](https://datatracker.ietf.org/doc/html/rfc8152#section-4.2) as a signature envelope. ## Storage -A COSE signature envelope will be stored in an OCI registry as a blob, and referenced in the signature manifest as a blob with `mediaType` of `"application/cose"`. +A COSE signature envelope will be stored in an OCI registry as a blob, and referenced in the signature manifest as a layer blob with `mediaType` of `"application/cose"`. Signature Manifest Example ```jsonc { "mediaType": "application/vnd.oci.artifact.manifest.v1+json", - "artifactType": "application/vnd.cncf.notary.signature", - "blobs": [ + "config": { + "mediaType": "application/vnd.cncf.notary.signature", + "size": 2, + "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a" + }, + "layers": [ { "mediaType": "application/cose", "digest": "sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0", @@ -35,9 +39,9 @@ Signature Manifest Example ## COSE Payload -The COSE envelope contains a [Notary v2 Payload](./signature-specification.md#payload). +The COSE envelope contains the [Notary Project signature Payload](./signature-specification.md#payload). -Example of Notary v2 payload: +Example of the Notary Project signature payload: ```jsonc { @@ -54,7 +58,7 @@ Example of Notary v2 payload: ## Protected Header -The COSE envelope for Notary v2 uses the following header parameters: +The COSE envelope for the Notary Project signature uses the following header parameters: - [Common parameters](https://www.iana.org/assignments/cose/cose.xhtml#header-parameters) - Label `1`: `alg` @@ -101,17 +105,17 @@ Example with Signing Scheme `notary.x509.signingAuthority` Note: The above examples are represented using the [extended CBOR diagnostic notation](https://datatracker.ietf.org/doc/html/rfc8152#appendix-C). -- **[`alg`](https://datatracker.ietf.org/doc/html/rfc8152#section-3.1)** (*int*): This REQUIRED parameter (label `1`) defines which signing algorithm was used to generate the signature. The signature algorithm of the signing key (first certificate in `x5chain`) is the source of truth, and during signing the value of `alg` MUST be set corresponding to signature algorithm of the signing key using [this mapping](#supported-alg-header-values) that lists the Notary v2 allowed subset of `alg` values supported by COSE. Similarly verifier of the signature MUST match `alg` with signature algorithm of the signing key to mitigate algorithm substitution attacks. +- **[`alg`](https://datatracker.ietf.org/doc/html/rfc8152#section-3.1)** (*int*): This REQUIRED parameter (label `1`) defines which signing algorithm was used to generate the signature. The signature algorithm of the signing key (first certificate in `x5chain`) is the source of truth, and during signing the value of `alg` MUST be set corresponding to signature algorithm of the signing key using [this mapping](#supported-alg-header-values) that lists the Notary Project signature allowed subset of `alg` values supported by COSE. Similarly verifier of the signature MUST match `alg` with signature algorithm of the signing key to mitigate algorithm substitution attacks. - **[`crit`](https://datatracker.ietf.org/doc/html/rfc8152#section-3.1)** (*array of int/tstr*): This REQUIRED parameter (label `2`) lists the header parameters that implementations MUST understand and process. It MUST only contain parameters apart from integer labels in the range of 0 to 8. This header MUST contain `io.cncf.notary.signingScheme` which is a required critical header, and optionally contain `io.cncf.notary.authenticSigningTime` and `io.cncf.notary.expiry` if these critical headers are present in the signature. - **[`content type`](https://datatracker.ietf.org/doc/html/rfc8152#section-3.1)** (*tstr*): The REQUIRED parameter content type (label `3`) is used to declare the media type of the secured content (the payload). The supported value is `application/vnd.cncf.notary.payload.v1+json`. -- **`io.cncf.notary.signingScheme`** (*tstr*, critical): This REQUIRED header specifies the [Notary v2 Signing Scheme](./signing-scheme.md) used by the signature. Supported values are `notary.x509` and `notary.x509.signingAuthority`. +- **`io.cncf.notary.signingScheme`** (*tstr*, critical): This REQUIRED header specifies the [Notary Project signing scheme](./signing-scheme.md) used by the signature. Supported values are `notary.x509` and `notary.x509.signingAuthority`. - **`io.cncf.notary.signingTime`** (*date/time*): This header specifies the time at which the signature was generated. This is an untrusted date/time, and therefore not used in trust decisions. Its value is an Epoch-Based Date/Time defined in [RFC 8949](https://datatracker.ietf.org/doc/html/rfc8949#section-3.4.2). The optional fractional seconds SHOULD NOT be used. This claim is REQUIRED and only valid when signing scheme is `notary.x509`. - **`io.cncf.notary.authenticSigningTime`** (*date/time*, critical): This header specifies the authenticated time at which the signature was generated. Its value is an Epoch-Based Date/Time defined in [RFC 8949](https://datatracker.ietf.org/doc/html/rfc8949#section-3.4.2). The optional fractional seconds SHOULD NOT be used. This claim is REQUIRED and only valid when signing scheme is `notary.x509.signingAuthority` . - **`io.cncf.notary.expiry`** (*date/time*, critical): This OPTIONAL header provides a "best by use" time for the artifact, as defined by the signer. Its value is an Epoch-Based Date/Time defined in [RFC 8949](https://datatracker.ietf.org/doc/html/rfc8949#section-3.4.2). The optional fractional seconds SHOULD NOT be used. ## Unprotected Headers -Notary v2 supports the following unprotected header parameters: +The Notary Project signature supports the following unprotected header parameters: - `io.cncf.notary.timestampSignature` - Label `33`: `x5chain` @@ -193,13 +197,13 @@ The final signature envelope is a `COSE_Sign1_Tagged` object, consisting of Payl ### Supported `alg` header values -Notary v2 implementation MUST enforce the following constraints on signature generation and verification: +Implementations of the [Notary Project signature specification](./signature-specification.md) MUST enforce the following constraints on signature generation and verification: 1. `alg` parameter value MUST NOT be a symmetric-key algorithm such as `HMAC`. 1. `alg` parameter value MUST be same as that of signature algorithm identified using signing certificate's public key algorithm and size. 1. `alg` parameter values for various signature algorithms is a subset of values supported by [COSE](https://www.iana.org/assignments/cose/cose.xhtml#algorithms). -**Mapping of Notary v2 approved algorithms to COSE `alg` header parameter values** +**Mapping of the Notary Project signature approved algorithms to COSE `alg` header parameter values** | Signature Algorithm | `alg` Label | | ------------------------------- | ----------------- | diff --git a/specs/signature-envelope-jws.md b/specs/signature-envelope-jws.md index 183ed4b2..19659308 100644 --- a/specs/signature-envelope-jws.md +++ b/specs/signature-envelope-jws.md @@ -1,18 +1,22 @@ # JWS Signature Envelope -This specification implements the [Notary v2 Signature specification](signature-specification.md) using JSON Web Signature (JWS). JWS ([RFC7515](https://datatracker.ietf.org/doc/html/rfc7515)) is a JSON based envelope format for digital signatures over any type of payload (e.g. JSON, binary). JWS is a Notary v2 supported signature format and specifically uses the *JWS JSON Serialization* representation. +This specification implements the [Notary Project signature specification](./signature-specification.md) using JSON Web Signature (JWS). JWS ([RFC7515](https://datatracker.ietf.org/doc/html/rfc7515)) is a JSON based envelope format for digital signatures over any type of payload (e.g. JSON, binary). JWS is the Notary Project supported signature format and specifically uses the *JWS JSON Serialization* representation. ## Storage -A JWS signature envelope will be stored in an OCI registry as a blob, and referenced in the signature manifest as a blob with `mediaType` of `"application/jose+json"`. +A JWS signature envelope will be stored in an OCI registry as a layer, and referenced in the signature manifest as a layer blob with `mediaType` of `"application/jose+json"`. Signature Manifest Example ```jsonc { "mediaType": "application/vnd.oci.artifact.manifest.v1+json", - "artifactType": "application/vnd.cncf.notary.signature", - "blobs": [ + "config": { + "mediaType": "application/vnd.cncf.notary.signature", + "size": 2, + "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a" + }, + "layers": [ { "mediaType": "application/jose+json", "digest": "sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0", @@ -33,9 +37,9 @@ Signature Manifest Example ## JWS Payload -The JWS envelope contains a [Notary v2 Payload](./signature-specification.md#payload). +The JWS envelope contains the [Notary Project signature payload](./signature-specification.md#payload). -Example of Notary v2 payload +Example of the Notary Project signature payload ```jsonc { @@ -52,7 +56,7 @@ Example of Notary v2 payload ## Protected Headers -The JWS envelope for Notary v2 uses following headers +The JWS envelope for the Notary Project signature uses following headers - Registered headers - `alg`, `cty`, and `crit` - [Public headers](https://datatracker.ietf.org/doc/html/rfc7515#section-4.2) with collision resistant names. @@ -93,13 +97,13 @@ Example with Signing Scheme `notary.x509.signingAuthority` } ``` -- **[`alg`](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.1)**(*string*): This REQUIRED header defines which signing algorithm was used to generate the signature. JWS specification defines `alg` as a required header, that MUST be present and MUST be understood and processed by verifier. The signature algorithm of the signing key (first certificate in `x5c`) is the source of truth, and during signing the value of `alg` MUST be set corresponding to signature algorithm of the signing key using [this mapping](#supported-alg-header-values) that lists the Notary v2 allowed subset of `alg` values supported by JWS. Similarly verifier of the signature MUST match `alg` with signature algorithm of the signing key to mitigate algorithm substitution attacks. +- **[`alg`](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.1)**(*string*): This REQUIRED header defines which signing algorithm was used to generate the signature. JWS specification defines `alg` as a required header, that MUST be present and MUST be understood and processed by verifier. The signature algorithm of the signing key (first certificate in `x5c`) is the source of truth, and during signing the value of `alg` MUST be set corresponding to signature algorithm of the signing key using [this mapping](#supported-alg-header-values) that lists the Notary Project signature allowed subset of `alg` values supported by JWS. Similarly verifier of the signature MUST match `alg` with signature algorithm of the signing key to mitigate algorithm substitution attacks. - **[`cty`](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.10)**(*string*): The REQUIRED header content-type is used to declare the media type of the secured content (the payload). The supported value is `application/vnd.cncf.notary.payload.v1+json`. -- **`io.cncf.notary.signingScheme`**(*string*)(critical): This REQUIRED header specifies the [Notary v2 Signing Scheme](./signing-scheme.md) used by the signature. Supported values are `notary.x509` and `notary.x509.signingAuthority`. +- **`io.cncf.notary.signingScheme`**(*string*)(critical): This REQUIRED header specifies the [Notary Project signing scheme](./signing-scheme.md) used by the signature. Supported values are `notary.x509` and `notary.x509.signingAuthority`. - **`io.cncf.notary.signingTime`**(*string*): This header specifies the time at which the signature was generated. This is an untrusted timestamp, and therefore not used in trust decisions. Its value is a [RFC 3339][rfc3339] formatted date time, the optional fractional second ([time-secfrac][rfc3339][[1](https://datatracker.ietf.org/doc/html/rfc3339#section-5.3)]) SHOULD NOT be used. This claim is REQUIRED and only valid when signing scheme is `notary.x509`. - **`io.cncf.notary.authenticSigningTime`**(*string*)(critical): This header specifies the authenticated time at which the signature was generated. Its value is a [RFC 3339][rfc3339] formatted date time, the optional fractional second ([time-secfrac][rfc3339][[1](https://datatracker.ietf.org/doc/html/rfc3339#section-5.3)]) SHOULD NOT be used. This claim is REQUIRED and only valid when signing scheme is `notary.x509.signingAuthority` . - **`io.cncf.notary.expiry`**(*string*)(critical): This OPTIONAL header provides a “best by use” time for the artifact, as defined by the signer. Its value is a [RFC 3339][rfc3339] formatted date time, the optional fractional second ([time-secfrac][rfc3339][[1](https://datatracker.ietf.org/doc/html/rfc3339#section-5.3)]) SHOULD NOT be used. -- **[`crit`](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.11)**(*array of strings*): This REQUIRED (optional as per JWS spec, but required in Notary v2 JWS signature) header lists the headers that implementation MUST understand and process. It MUST only contain headers apart from registered headers (e.g. `alg`, `cty`) in JWS specification. This header MUST contain `io.cncf.notary.signingScheme` which is a required critical header, and optionally contain `io.cncf.notary.authenticSigningTime` and `io.cncf.notary.expiry` if these critical headers are present in the signature. +- **[`crit`](https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.11)**(*array of strings*): This REQUIRED (optional as per JWS spec, but required in Notary Project JWS signature) header lists the headers that implementation MUST understand and process. It MUST only contain headers apart from registered headers (e.g. `alg`, `cty`) in JWS specification. This header MUST contain `io.cncf.notary.signingScheme` which is a required critical header, and optionally contain `io.cncf.notary.authenticSigningTime` and `io.cncf.notary.expiry` if these critical headers are present in the signature. ## Extended Protected Headers for *Notation* Plugins @@ -110,7 +114,7 @@ See [Extended attributes for *Notation* Plugins](./signature-specification.md#ex ## Unprotected Headers -Notary v2 supports following unprotected headers: `timestamp`, `x5c` and `io.cncf.notary.signingAgent` +The Notary Project signature supports following unprotected headers: `timestamp`, `x5c` and `io.cncf.notary.signingAgent` ```jsonc { @@ -149,7 +153,7 @@ Base64Url encoding used by JWS (*Base64url Encoding* in [RFC 7515 section 2][jws The final signature envelope comprises of Payload, ProtectedHeaders, UnprotectedHeaders, and Signature, no additional top level fields are supported. -Since Notary v2 restricts one signature per signature envelope, the compliant signature envelope MUST be in flattened JWS JSON format. +Since the Notary Project restricts one signature per signature envelope, the compliant signature envelope MUST be in flattened JWS JSON format. ```jsonc { @@ -167,13 +171,13 @@ Since Notary v2 restricts one signature per signature envelope, the compliant si ### Supported `alg` header values -Notary v2 implementation MUST enforce the following constraints on signature generation and verification: +Implementations of the [Notary Project signature specification](./signature-specification.md) MUST enforce the following constraints on signature generation and verification: 1. `alg` header value MUST NOT be `none` or any symmetric-key algorithm such as `HMAC`. 1. `alg` header value MUST be same as that of signature algorithm identified using signing certificate's public key algorithm and size. 1. `alg` header values for various signature algorithms is a subset of values supported by [JWS][jws-alg-values]. -**Mapping of Notary v2 approved algorithms to JWS `alg` header values** +**Mapping of the Notary Project signature approved algorithms to JWS `alg` header values** | Signature Algorithm | `alg` Header Value| | ------------------------------- | ----------------- | @@ -191,11 +195,11 @@ Notary v2 implementation MUST enforce the following constraints on signature gen **Q:** Why JWT is not used as the signature envelope format? -**A:** JWT uses JWS compact serialization which do not support unsigned attributes. Notary v2 signature requires support for unsigned attributes. Instead we use the *JWS JSON Serialization* representation, which supports unsigned attributes. +**A:** JWT uses JWS compact serialization which do not support unsigned attributes. The Notary Project signature requires support for unsigned attributes. Instead we use the *JWS JSON Serialization* representation, which supports unsigned attributes. **Q:** Why JWT `exp` and `iat` claims are not used? -**A:** Unlike JWT which always contains a JSON payload, Notary v2 envelope can support payloads other than JSON, like binary. Reusing the JWT payload structure and claims, limits the Notary v2 JWS envelope to only support JSON payload, which is undesirable. Also, reusing JWT claims requires following same claim semantics as defined in JWT specifications. The [`exp`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) claim requires that verifier MUST reject the signature if current time equals or is greater than `exp`, where as Notary v2 allows verification policy to define how expiry is handled. +**A:** Unlike JWT which always contains a JSON payload, The Notary Project signature envelope can support payloads other than JSON, like binary. Reusing the JWT payload structure and claims, limits the Notary Project signature JWS envelope to only support JSON payload, which is undesirable. Also, reusing JWT claims requires following same claim semantics as defined in JWT specifications. The [`exp`](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4) claim requires that verifier MUST reject the signature if current time equals or is greater than `exp`, where as the [Notary Project signature specification](./signature-specification.md) allows verification policy to define how expiry is handled. [jws-alg-values]: https://datatracker.ietf.org/doc/html/rfc7518#section-3.1 [rfc3339]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6 diff --git a/specs/signing-and-verification-workflow.md b/specs/signing-and-verification-workflow.md index 0ac1bbb4..1c3b18b6 100644 --- a/specs/signing-and-verification-workflow.md +++ b/specs/signing-and-verification-workflow.md @@ -1,6 +1,6 @@ # Signing and Verification Workflow -This document describes how Notary v2 signs and verifies OCI artifacts. +This document describes the workflow of signing and verifying OCI artifacts. ## Signing workflow @@ -22,8 +22,8 @@ The user wants to sign an OCI artifact and push the signature to a repository. 1. Verify that the timestamp signing algorithm satisfies [algorithm requirements](./signature-specification.md#signature-algorithm-requirements). 1. Embed timestamp to the signature envelope. 1. **Push the signature envelope:** Push the signature envelope generated in the previous step to the repository. -1. **Generate signature artifact manifest:** As decribed in [signature specification](./signature-specification.md#storage) create the Notary v2 signature artifact manifest for the signature envelope generated in step 1. -1. **Push signature artifact manifest:** Push Notary v2 signature artifact manifest to the repository. +1. **Generate signature artifact manifest:** As described in [signature specification](./signature-specification.md#storage) create the Notary Project signature manifest for the signature envelope generated in step 1. +1. **Push signature artifact manifest:** Push the Notary Project signature manifest to the repository. The user pushes the OCI artifact to the repository before the signature generation process as the signature reference must exist for the signature push to succeed. @@ -41,12 +41,12 @@ The user wants to pull an OCI artifact only if they are signed by a trusted publ ### Verification Steps -1. **Should Notary v2 verify the signature? :** Depending upon [trust-policy](./trust-store-trust-policy.md#trust-policy) configuration, determine whether Notary v2 needs to verify the signature or not. +1. **Should implementations of this specification verify the signature? :** Depending upon [trust-policy](./trust-store-trust-policy.md#trust-policy) configuration, determine whether implementations of this specification need to verify the signature or not. If signature verification should be skipped for the given artifact, skip the below steps and directly jump to step 4. -1. **Get signature artifact descriptors:** Using the [OCI Distribution Referrers API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers) download the Notary v2 signature artifact descriptors. - The `artifactType` parameter is set to Notary v2 signature's artifact type `application/vnd.cncf.notary.signature`. +1. **Get signature artifact descriptors:** Using the [OCI Distribution Referrers API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers) download the Notary Project signature manifest descriptors. + The `artifactType` parameter is set to the Notary Project signature's artifact type `application/vnd.cncf.notary.signature`. 1. For each signature artifact descriptor, perform the following steps: - 1. **Get signature artifact manifest:** Download the Notary v2 signature's artifact manifest for the given artifact descriptor. + 1. **Get signature artifact manifest:** Download the Notary Project signature's manifest for the given artifact descriptor. 1. **Filter signature artifact manifest:** 1. Filter out the unsupported signature formats by comparing the signature envelope format type (`[descriptors].descriptor.mediaType`) in the signature manifest, with the supported formats defined in [signature specification](./signature-specification.md#storage). 1. Depending upon the trust-store and trust-policy configuration, further filter out signature manifests. @@ -59,7 +59,7 @@ The user wants to pull an OCI artifact only if they are signed by a trusted publ If all signature artifact descriptors have already been processed, fail the signature verification and exit. 1. If the artifact manifest is filtered out, skip the below steps and move to the next signature artifact descriptor(step 3.1). If all signature artifact descriptors have already been processed, fail the signature verification and exit. - 1. **Get and verify signatures:** On the filtered Notary v2 signature artifact manifest, perform the following steps: + 1. **Get and verify signatures:** On the filtered manifest of the Notary Project signature, perform the following steps: 1. Download the signature envelope. 1. Verify the signature envelope using trust-store and trust-policy as mentioned in [signature evaluation](./trust-store-trust-policy.md#signature-evaluation) section. 1. If the signature verification fails, skip the below steps and move to the next signature artifact descriptor(step 3.1). @@ -69,4 +69,4 @@ The user wants to pull an OCI artifact only if they are signed by a trusted publ Otherwise, move to the next signature artifact descriptor(step 3.1). If all signature artifact descriptors have already been processed, fail the signature verification and exit. 1. **Get OCI artifact:** Using the verified digest, download the OCI artifact. - This step is not in the purview of Notary v2. + This step is not in the purview of Notary Project. diff --git a/specs/signing-scheme.md b/specs/signing-scheme.md index 1d7e14ca..2fd49c73 100644 --- a/specs/signing-scheme.md +++ b/specs/signing-scheme.md @@ -1,13 +1,13 @@ # Signing Scheme -Signatures are primarily used to provide a consumer of an artifact the following guarantees - integrity (the signed artifact was not tampered after signing it), and authenticity (the artifact was indeed signed by the entity who claims to have signed it). +Signatures are primarily used to provide a consumer of an artifact the following guarantees - integrity (the signed artifact was not tampered with after signing it), and authenticity (the artifact was indeed signed by the entity who claims to have signed it). X.509 PKI based identities are commonly used to for signing artifacts. It has well established standards for issuing and representing identities (CAs and certificates) which sign artifacts, mechanism to establish authenticity using trust stores, and support for managing key lifetimes and rotation, and revocation of identities. -There is interest in the community to support other ways to establish integrity and authenticity, based on other systems and techniques (Notary TUF, ledger based). +There is interest in the community to support other ways to establish integrity and authenticity, based on other systems and techniques ([TUF-based implementation](https://github.com/notaryproject/notary), ledger based). These approaches also can provide different feature sets than ones traditionally provided by standard X.509 PKI based signing. E.g. TUF is geared for software update systems and provides a freshness guarantee. -Notary v2 will initially support X.509 PKI identity based signing, but provide the flexibility for additional systems through an abstraction called Signing Scheme. +Notary Project will initially support X.509 PKI identity based signing, but provide the flexibility for additional systems through an abstraction called Signing Scheme. The Signing Scheme covers aspects of signature generation and verification, and formalizes the feature set (guarantees) provided by the signature produced using a signing scheme. Generally it covers the following aspects, but can be extended to other aspects as required by newer systems. @@ -24,7 +24,7 @@ Generally it covers the following aspects, but can be extended to other aspects ## Signing Scheme -Notary v2 currently defines the following Signing Schemes. +Notary Project currently defines the following Signing Schemes. `notary.x509` - Defines a signing scheme that uses the traditional signing workflow in which an end user generates signatures using X.509 certificates. @@ -35,10 +35,10 @@ A certificate authority (CA) will need to demonstrate only validated entities we Similarly, a signing authority (SA) will need to demonstrate signing keys were only used within their service and only validated entities were allowed to generate signatures using the service. * A signature envelope can only specify one Signing Scheme -* When Notary supports an additional Signing Scheme +* When Notary Project supports an additional Signing Scheme * Existing signed artifacts MUST be resigned if they need to be verified using the new signing scheme defined verification process. * Existing clients used by verifying entity MUST be updated to newer versions that support verifying signatures that use the new signing scheme, otherwise the signatures with newer signing schemes which are unknown to existing clients will fail signature verification. Signatures that use older signing schemes which are known to existing clients will continue to verify correctly. - * The Notary verification policy language in *trustpolicy.json* MAY have breaking changes to support newer concepts/configuration elements introduced by the new signing scheme. + * The language of the [Notary Project verification policy](./trust-store-trust-policy.md) in *trustpolicy.json* MAY have breaking changes to support newer concepts/configuration elements introduced by the new signing scheme. The breaking changes are addressed by introducing new major version in the versioned *trustpolicy.json* . ## Signature Creation @@ -49,7 +49,7 @@ This attribute dictates the rest of signature schema - the set of signed and uns Both `notary.x509` and `notary.x509.signingAuthority` signing schemes use the similar signature schema (set of signed and unsigned attributes) with the following differences. * `notary.x509` MUST use a countersignature from trusted source to determine authentic signing time (timestamp). -This is supported through the the Timestamp signature unsigned attribute in the signature envelope. Currently Notary V2 uses a [RFC3161](ietf-rfc3161) compliant TSA signature for this purpose. +This is supported through the Timestamp signature unsigned attribute in the signature envelope. Currently Notary Project uses a [RFC3161](ietf-rfc3161) compliant TSA signature for this purpose. * `notary.x509.signingAuthority` MUST use a timestamp attribute that is generated by a signing service as part of the original signature itself to determine authenticated signing time (timestamp). This is supported through the *Authentic Signing time* attribute in the signature envelope. @@ -57,8 +57,8 @@ This is supported through the *Authentic Signing time* attribute in the signatur ## Signature Verification Signature verification requires that a `Signing Scheme` attribute is present in the signature and it’s treated as critical i.e. the attribute MUST be understood and processed by the verifier. -For the JWS signature format, the attribute name is `io.cncf.notary.signingScheme` , with supported values `notary.x509` and `notary.x509.signingAuthority`. -Any other value will fail signature verification i.e when Notary supports an additional Signing Scheme, clients (like *notation*) MUST be updated to a version that supports the new signing scheme. +For the JWS signature format, the attribute name is `io.cncf.notary.signingScheme`, with supported values `notary.x509` and `notary.x509.signingAuthority`. +Any other value will fail signature verification i.e when Notary Project supports an additional Signing Scheme, clients (like *Notation CLI*) MUST be updated to a version that supports the new signing scheme. ### Trust Stores @@ -76,9 +76,9 @@ The signature is verified against the trust store of type CA, and the *Timestamp * Uses trusts store type Signing Authority during signature verification. The signature is verified against the trust store of type Signing Authority. -The signing time is determined using the *Authentic Signing time* attribute in the signature envelope, and does not rely on a seperate TSA generated Timestamp signature. +The signing time is determined using the *Authentic Signing time* attribute in the signature envelope, and does not rely on a separate TSA generated Timestamp signature. * For signature verification to be successful - * The verifying entity’s trust store MUST contain the trusted root certificates under named trust stores of type CA (`{CONFIG}/notation/truststore/x509/signingAuthority`). + * The verifying entity’s trust store MUST contain the trusted root certificates under named trust stores of type signingAuthority (`{CONFIG}/notation/truststore/x509/signingAuthority`). * The named trust stores MUST be specified in *trustpolicy.json*. E.g. *trustPolicy.trustStores* with value of `signingAuthority:foobar` . ## FAQ diff --git a/specs/trust-store-trust-policy.md b/specs/trust-store-trust-policy.md index 4edb77f2..9d2789b8 100644 --- a/specs/trust-store-trust-policy.md +++ b/specs/trust-store-trust-policy.md @@ -1,18 +1,18 @@ # Trust Store and Trust Policy Specification -Notary v2 currently supports X.509 based PKI and identities, and uses a trust store and trust policy to determine if a signed artifact is considered authentic. +Notary Project currently supports X.509 based PKI and identities, and uses a trust store and trust policy to determine if a signed artifact is considered authentic. The document consists of the following sections: - **[Trust Store](#trust-store)**: Contains a set of trusted identities through which trust is derived for the rest of the system. For X.509 PKI, the trust store typically contains a set of root certificates. - **[Trust Policy](#trust-policy)**: A policy language which indicates which identities are trusted to produce artifacts. Both trust store and trust policy need to be configured by users/administrators before artifact signature can be evaluated. -- **[Signature Verification](#signature-verification)**: Describes how signatures are evaluated using the policy, to determine if a signed artifact is authentic. This section is meant for implementors of Notary v2 standards. +- **[Signature Verification](#signature-verification)**: Describes how signatures are evaluated using the policy, to determine if a signed artifact is authentic. This section is meant for implementations of the [Notary Project verification specification](./signing-and-verification-workflow.md). Other types of identities and trust models may be supported in future, which may introduce other constructs/policy elements to support signature evaluation. ## Scenario -All examples use the actors defined in Notary v2 [scenario](https://github.com/notaryproject/notaryproject/blob/main/scenarios.md#scenario-0-build-publish-consume-enforce-policy-deploy) +All examples use the actors defined in the Notary Project [scenarios](../requirements/scenarios.md#scenario-0-build-publish-consume-enforce-policy-deploy) - Wabbit Networks company builds, signs and distributes their `net-monitor` software though public registries. - ACME Rockets consumes the `net-monitor` software from a public registry importing the artifacts and reference artifacts (signatures, SBoMs) into their private registry. The private registry also contains additional artifacts that ACME Rockets themselves sign. @@ -21,13 +21,13 @@ All examples use the actors defined in Notary v2 [scenario](https://github.com/n Contains a set of trusted identities through which trust is derived for the rest of the system. For X.509 PKI, the trust store typically contains root certificates. -- The Notary v2 trust store consists of multiple named collections of certificates, called named stores. +- The Notary Project trust store consists of multiple named collections of certificates, called named stores. - Following certificate formats are supported - Files with extension .pem, .crt and .cer, the files are expected to contain certificate(s) in DER (binary) format or PEM format (base-64 encoded DER). - The trust store is a directory location, under which each sub directory is considered a named store, that contains zero or more certificates. The name of this sub directory is used to reference the specific store in trust policy. - Symlinks are not supported for the named store directories or certificate files. Implementation MUST validate that the named store directory or certificate files are not symlinks, and fail if it does not meet this condition. - Certificates in a trust store are root certificates. Placing intermediate certificates in the trust store is not recommended this is a form of certificate pinning that can break signature verification unexpectedly anytime the intermediate certificate is rotated. -Notary v2 uses following directory structure to represent the trust store. The example shows named stores `acme-rockets` and `wabbit-networks`, which are subseqently references in the trust policy. Without this reference, presence of a named store and certificates in it does not confer trust automatically to the named store. The trust store is configured ahead of verification time, by an out of band mechanism that is beyond the scope of this document. Different entities and organizations have their own processes and policies to configure and distribute trust stores. +The Notary Project uses following directory structure to represent the trust store. The example shows named stores `acme-rockets` and `wabbit-networks`, which are subsequently references in the trust policy. Without this reference, presence of a named store and certificates in it does not confer trust automatically to the named store. The trust store is configured ahead of verification time, by an out of band mechanism that is beyond the scope of this document. Different entities and organizations have their own processes and policies to configure and distribute trust stores. ```text $XDG_CONFIG_HOME/notation/trust-store @@ -161,10 +161,10 @@ Trust policy for the scenario where ACME Rockets uses some artifacts signed by W The scope field supports filtering based on fully qualified repository URI `${registry-name}/${namespace}/${repository-name}`. For more information, see [registry scopes constraints](#registry-scopes-constraints) section. - **`signatureVerification`**(*object*): This REQUIRED property dictates how signature verification is performed. - An *object* that specifies a predefined verification level, with an option to override Notary v2 defined verification level if user wants to specify a [custom verification level](#custom-verification-level). - - **`level`**(*string*): A REQUIRED property that specifies the verification level, supported values are `strict`, `permissive`, `audit` and `skip`. Detailed explaination of each level is present [here](#signatureverification-details). + An *object* that specifies a predefined verification level, with an option to override the Notary Project trust policy defined verification level if user wants to specify a [custom verification level](#custom-verification-level). + - **`level`**(*string*): A REQUIRED property that specifies the verification level, supported values are `strict`, `permissive`, `audit` and `skip`. Detailed explanation of each level is present [here](#signatureverification-details). - **`override`**(*map of string-string*): This OPTIONAL map is used to specify a [custom verification level](#custom-verification-level). - - **`trustStores`**(*array of string*): This REQUIRED property specifies a set of one or more named trust stores, each of which contain the trusted roots against which signatures are verified. Each named trust store uses the format `{trust-store-type}:{named-store}`. Currently supported values for `trust-store-type` are `ca`, `signingAuthority` and `tsa`. For publicly trusted TSA, `tsa:publicly-trusted-tsa` is the default value, and implied without explictly specifying it. If a custom TSA is used the format `ca:acme-rockets,tsa:acme-tsa` is supported to specify it. + - **`trustStores`**(*array of string*): This REQUIRED property specifies a set of one or more named trust stores, each of which contain the trusted roots against which signatures are verified. Each named trust store uses the format `{trust-store-type}:{named-store}`. Currently supported values for `trust-store-type` are `ca`, `signingAuthority` and `tsa`. For publicly trusted TSA, `tsa:publicly-trusted-tsa` is the default value, and implied without explicitly specifying it. If a custom TSA is used the format `ca:acme-rockets,tsa:acme-tsa` is supported to specify it. - **`trustedIdentities`**(*array of strings*): This REQUIRED property specifies a set of identities that the user trusts. For X.509 PKI, it supports list of elements/attributes of the signing certificate's subject. For more information, see [identities constraints](#trusted-identities-constraints) section. A value `*` is supported if user trusts any identity (signing certificate) issued by the CA(s) in `trustStore`. #### Signature Verification details @@ -180,9 +180,9 @@ Trust policy for the scenario where ACME Rockets uses some artifacts signed by W - If a validation is *logged*, a failure causes details to be logged, and the next validation is evaluated till all validations succeed or a critical failure is encountered. - Implementations may change the ordering of these validations based on efficiency, but all validation MUST be performed till the first critical failure is encountered, or all validation succeed, for the overall signature verification process to be considered complete. - Notary v2 defines the following signature verification levels to provide different levels of enforcement for different scenarios. + Notary Project defines the following signature verification levels to provide different levels of enforcement for different scenarios. -- `strict` : Signature verification is performed at `strict` level, which enforces all validations. If any of these validations fail, the signature verification fails. This is the recommended level in environments where a signature verification failure does not have high impact to other concerns (like application availability). It is recommended that build and development environments where images are initially injested, or for high assurance at deploy time use `strict` level. +- `strict` : Signature verification is performed at `strict` level, which enforces all validations. If any of these validations fail, the signature verification fails. This is the recommended level in environments where a signature verification failure does not have high impact to other concerns (like application availability). It is recommended that build and development environments where images are initially created, or for high assurance at deploy time use `strict` level. - `permissive` : The `permissive` level enforces most validations, but will only logs failures for revocation and expiry. The `permissive` level is recommended to be used if signature verification is done at deploy time or runtime, and the user only needs integrity and authenticity guarantees. - `audit` : The `audit` level only enforces signature integrity if a signature is present. Failure of all other validations are only logged. - `skip` : The `skip` level does not fetch signatures for artifacts and does not perform any signature verification. This is useful when an application uses multiple artifacts, and has a mix of signed and unsigned artifacts. Note that `skip` cannot be used with a global scope (`*`), the value of `registryScopes` MUST contain fully qualified registry URL(s). @@ -205,13 +205,13 @@ The following table shows the resultant validation action, either *enforced* (ve - **NOTE**: `notation` RC1 will generate trusted timestamp using a TSA when the signature is generated, but will not support verification of TSA countersignatures. Related issue - [#59](https://github.com/notaryproject/roadmap/issues/59). -**Expiry** : This is an optional feature that guarantees that artifact is within “best by use” date indicated in the signature. Notary v2 allows users to include an optional expiry time when they generate a signature. The expiry time is not set by default and requires explicit configuration by users at the time of signature generation. The artifact is considered expired when the current time is greater than or equal to expiry time, users performing verification can either configure their trust policies to fail the verification or even accept the artifact with expiry date in the past using policy. This is an advanced feature that allows implementing controls for user defined semantics like deprecation for older artifacts, or block older artifacts in a production environment. Users should only include an expiry time in the signed artifact after considering the behavior they expect for consumers of the artifact after it expires. Users can choose to consume an artifact even after the expiry time based on their specific needs. +**Expiry** : This is an optional feature that guarantees that artifact is within “best by use” date indicated in the signature. Notary Project allows users to include an optional expiry time when they generate a signature. The expiry time is not set by default and requires explicit configuration by users at the time of signature generation. The artifact is considered expired when the current time is greater than or equal to expiry time, users performing verification can either configure their trust policies to fail the verification or even accept the artifact with expiry date in the past using policy. This is an advanced feature that allows implementing controls for user defined semantics like deprecation for older artifacts, or block older artifacts in a production environment. Users should only include an expiry time in the signed artifact after considering the behavior they expect for consumers of the artifact after it expires. Users can choose to consume an artifact even after the expiry time based on their specific needs. **Revocation check** : Guarantees that the signing identity is still trusted at signature verification time. Events such as key or system compromise can make a signing identity that was previously trusted, to be subsequently untrusted. This guarantee typically requires a verification-time call to an external system, which may not be consistently reliable. The `permissive` verification level only logs failures of revocation check and does not enforce it. If a particular revocation mechanism is reliable, use `strict` verification level instead. #### Custom Verification Level -Signature verification levels provide Notary v2 defined behavior for each validation e.g. `strict` will always *enforce* authenticity validation. For fine grained control over validations that occur during signature verification, users can define a custom level which overrides the behavior of an existing verification level. +Signature verification levels provide defined behavior for each validation e.g. `strict` will always *enforce* authenticity validation. For fine grained control over validations that occur during signature verification, users can define a custom level which overrides the behavior of an existing verification level. - To use this feature, the `level` property MUST be specified along with an OPTIONAL `override` map. - Supported values for `level` are - `strict`, `permissive` and `audit`. A `skip` level cannot be customized. @@ -245,7 +245,7 @@ Signature verification levels provide Notary v2 defined behavior for each valida #### Selecting a trust policy based on artifact URI - For a given artifact there MUST be only one applicable trust policy, except for trust policy with global scope. -- For a given artifact, if there is no applicable trust policy then Notary v2 MUST consider the artifact as untrusted and fail signature verification. +- For a given artifact, if there is no applicable trust policy then implementations of the [Notary Project verification specification](./signing-and-verification-workflow.md) MUST consider the artifact as untrusted and fail signature verification. - The scope MUST NOT support reference expansion i.e. URIs must be fully qualified. E.g. the scope should be `docker.io/library/registry` rather than `registry`. - Evaluation order of trust policies: @@ -266,7 +266,7 @@ The RDN consists of an attribute type name followed by an equal sign and the str - The value of each `trustedIdentities` list item, if it begins with `x509.subject:`, MUST be followed by comma-separated one or more RDNs. Other types of trusted identities may be supported, by using an alternate prefix, or a different format. For example, `x509.subject: C=${country}, ST=${state}, L=${locallity}, O={organization}, OU=${organization-unit}, CN=${common-name}`. - - Each identity in `identities` list MUST contain country (CN), state Or province (ST), and organization (O) RDNs. + - Each identity in `identities` list MUST contain country (C), state or province (ST), and organization (O) RDNs. All other RDNs are optional. The minimal possible value is `x509.subject: C=${country}, ST=${state}, O={organization}`, - `trustedIdentities` list items MUST NOT have overlapping values, @@ -283,7 +283,7 @@ The RDN consists of an attribute type name followed by an equal sign and the str ### Extended Validation -Notary v2 allows user to execute custom validations during verificaton using plugins. Please refer [plugin-extensibility.md](plugin-extensibility.md#verification-extensibility) for more information. +Notary Project allows user to execute custom validations during verification using plugins. Please refer [plugin-extensibility.md](plugin-extensibility.md#verification-extensibility) for more information. ## Signature Verification @@ -365,9 +365,9 @@ There are two types of CRLs (per RFC 3280), Base CRLs and Delta CRls. Delta CRLs are signed by the certificate issuing CAs. - **Indirect CRLs:** Special Case in which BaseCRLs and Delta CRLs are not signed by the certificate issuing CAs, instead they are signed with a completely different certificate. -Notary v2 MUST support BaseCRLs and Delta CRLs. -Notary v2 MAY support Indirect CRLs. -Notary v2 supports only HTTP CRL URLs. +Implementations of the [Notary Project verification specification](./signing-and-verification-workflow.md) MUST support BaseCRLs and Delta CRLs. +Implementations of the [Notary Project verification specification](./signing-and-verification-workflow.md) MAY support Indirect CRLs. +Implementations of the [Notary Project verification specification](./signing-and-verification-workflow.md) support only HTTP CRL URLs. Implementations MAY add support for caching CRLs and OCSP response to improve availability, latency and avoid network overhead. @@ -375,7 +375,7 @@ Implementations MAY add support for caching CRLs and OCSP response to improve av CRL download location (URL) can be obtained from the certificate's CRL Distribution Point (CDP) extension. If the certificate contains multiple CDP locations then each location download is attempted in sequential order, until a 2xx response is received for any of the location. -For each CDP location, Notary V2 will try to download the CRL for the default threshold of 5 seconds. +For each CDP location, [Notary Project verification workflow](./signing-and-verification-workflow.md) will try to download the CRL for the default threshold of 5 seconds. The user may be able to configure this threshold. If the CRL cannot be downloaded within the timeout threshold the revocation result will be "revocation unavailable". @@ -413,7 +413,7 @@ When delta CRLs are implemented, the following results can occur during revocati OCSP URLs can be obtained from the certificate's authority information access (AIA) extension as defined in [RFC 6960](https://www.rfc-editor.org/rfc/rfc6960). If the certificate contains multiple OCSP URLs, then each URL is invoked in sequential order, until a 2xx response is received for any of the URL. -For each OCSP URL, Notary V2 will wait for a default threshold of 2 seconds to receive an OCSP response. +For each OCSP URL, wait for a default threshold of 2 seconds to receive an OCSP response. The user may be able to configure this threshold. If OCSP response is not available within the timeout threshold the revocation result will be "revocation unavailable". @@ -435,12 +435,12 @@ To check the revocation status of a certificate using OCSP, the following steps ## FAQ -**Q: Does Notary v2 supports `n` out of `m` signatures verification requirement?** +**Q: Does the Notary Project trust policy supports `n` out of `m` signatures verification requirement?** -**A:** Notary v2 doesn't support n out m signature requirement verification scheme. +**A:** The Notary Project trust policy doesn't support n out m signature requirement verification scheme. Signature verification workflow succeeds if verification succeeds for at least one signature. -**Q: Does Notary v2 support overriding of revocation endpoints to support signature verification in disconnected environments?** +**Q: Does the Notary Project trust policy support overriding of revocation endpoints to support signature verification in disconnected environments?** **A:** TODO: Update after verification extensibility spec is ready. Not natively supported but a user can configure `revocationValidations` to `skip` and then use extended validations to check for revocation.