From d9ee4ad4d5458ae3ce591cdbc1f0797d478cbe36 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Sat, 6 May 2023 14:15:12 +0800 Subject: [PATCH 01/18] doc: update signature specification for v1 release Signed-off-by: Yi Zha --- media/signature-specification.svg | 4 +- specs/signature-specification.md | 121 ++++++++++-------------------- 2 files changed, 42 insertions(+), 83 deletions(-) diff --git a/media/signature-specification.svg b/media/signature-specification.svg index e009f6c6..6b2bc5be 100644 --- a/media/signature-specification.svg +++ b/media/signature-specification.svg @@ -1,2 +1,4 @@ + + -
Registry
[Not supported by viewer]
Manifest
[Not supported by viewer]
Blobs
[Not supported by viewer]
Artifact Type
[Not supported by viewer]
Annotations
[Not supported by viewer]
Notary Signature Manifest
[Not supported by viewer]
Subject
(Manifest Descriptor)
[Not supported by viewer]
Payload
(Manifest Descriptor)
[Not supported by viewer]
Signed Attributes
[Not supported by viewer]
Unsigned Attributes
[Not supported by viewer]
Signature
<div>Signature</div>
Signature Envelope

[Not supported by viewer] \ No newline at end of file +
Registry
Regist...
Manifest
Manifest
Layers
Layers
Media Type
Media Type
Annotations
Annotations
Notary Signature Manifest
Notary Signature Mani...
Subject
(Manifest Descriptor)
Subject...
Payload
(Manifest Descriptor)
Payload(Manifest Des...
Signed Attributes
Signed Attributes
Unsigned Attributes
Unsigned Attributes
Signature
Signature
Signature Envelope

Signature Envelope...Text is not SVG - cannot display \ No newline at end of file diff --git a/specs/signature-specification.md b/specs/signature-specification.md index 0651e63a..a28fc15a 100644 --- a/specs/signature-specification.md +++ b/specs/signature-specification.md @@ -1,60 +1,18 @@ # Signature Specification -This document provides the following details for Notary v2 signatures: +This document provides the following details for Notary signatures: - **[Storage](#storage)**: Describes how signatures are stored and retrieved from an OCI registry. -- **[Signature Envelope](#signature-envelope)**: Describes the structure of a Notary v2 signature. +- **[Signature Envelope](#signature-envelope)**: Describes the structure of a Notary signature. ## Storage -This section describes how Notary v2 signatures are stored in the OCI Distribution conformant registry. -Notary v2 uses [OCI artifact manifest][oci-artifact-manifest] to store signatures in the registry. -The media type of the signature manifest is `application/vnd.oci.artifact.manifest.v1+json`. -The signature manifest has an artifact type that specifies it's a Notary V2 signature, a reference to the manifest of the artifact being signed, a blob referencing the signature, and a collection of annotations. +This section describes how Notary signatures are stored in the OCI Distribution conformant registry. +OCI image manifest is used to store signatures in the registry, see [OCI image spec v1.1.0-rc.2][oci-image-manifest] for details. +The signature manifest has an media type of config that specifies it's a Notary signature, a subject referencing the manifest of the artifact being signed, a layer referencing the signature, and a collection of annotations. ![Signature storage inside registry](../media/signature-specification.svg) -Signature manifest example per OCI artifact manifest - -```jsonc -{ - "mediaType": "application/vnd.oci.artifact.manifest.v1+json", - "artifactType": "application/vnd.cncf.notary.signature", - "blobs": [ - { - "mediaType": "application/jose+json", - "digest": "sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0", - "size": 32654 - } - ], - "subject": { - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "digest": "sha256:73c803930ea3ba1e54bc25c2bdc53edd0284c62ed651fe7b00369da519a3c333", - "size": 16724 - }, - "annotations": { - "io.cncf.notary.x509chain.thumbprint#S256": - "[\"B7A69A70992AE4F9FF103EBE04A2C3BA6C777E439253CE36562E6E98375068C3\",\"932EB6F5598435D4EF23F97B0B5ACB515FAE2B8D8FAC046AB813DDC419DD5E89\"]" - } -} -``` - -- **`artifactType`** (*string*): This REQUIRED property references the Notary version of the signature: `application/vnd.cncf.notary.signature`. -- **`blobs`** (*array of objects*): This REQUIRED property contains collection of only one [OCI descriptor][oci-descriptor] referencing signature envelope. - - **`mediaType`** (*string*): This REQUIRED property contains media type of signature envelope blob. Following values are supported - - `application/jose+json` - - `application/cose` -- **`subject`** (*descriptor*): A REQUIRED artifact descriptor referencing the signed manifest, including, but not limited to image manifest, image index, OCI artifact manifest. -- **`annotations`** (*string-string map*): This REQUIRED property contains metadata for the artifact manifest. - It is being used to store information about the signature. - Keys using the `io.cncf.notary` namespace are reserved for use in Notary and MUST NOT be used by other specifications. - - **`io.cncf.notary.x509chain.thumbprint#S256`**: A REQUIRED annotation whose value contains the list of SHA-256 fingerprint of signing certificate and certificate chain (including root) used for signature generation. The annotation name contains the hash algorithm as a suffix (`#S256`) and can be extended to support other hashing algorithms in future. - The list of fingerprints is present as a JSON array string, corresponding to ordered certificates in [*Certificate Chain* unsigned attribute](#unsigned-attributes) in the signature envelope. - -### Backward Compatibility - -Notary v2 MAY support using `OCI image manifest` to store signatures in the registries that implement partial of the [OCI image specification v1.1][oci-image-manifest]. - Signature manifest example per OCI image manifest: ```jsonc @@ -88,7 +46,7 @@ Signature manifest example per OCI image manifest: Besides the [image manifest property requirements][image-manifest-property-descriptions], the properties have the following additional restrictions: - **`mediaType`** (*string*): This REQUIRED property MUST be `application/vnd.oci.image.manifest.v1+json`. -- **`config`** (*descriptor*): This property is REQUIRED to be compatible with [OCI image specification][oci-image-manifest]. Notary v2 doesn't require any configuration for a signature, and the configuration content is not consumed by Notary v2. +- **`config`** (*descriptor*): This property is REQUIRED to be compatible with [OCI image specification][oci-image-manifest]. Notary doesn't require any configuration for a signature, and the configuration content is not consumed by Notary. - **`mediaType`** (*string*): This REQUIRED property MUST be `application/vnd.cncf.notary.signature`. - **`digest`** (*string*): This REQUIRED property is the digest of the config content. - **`size`** (*int64*): This REQUIRED property specifies the size, in bytes, of the raw config content. @@ -112,8 +70,8 @@ Each Notary signature artifact refers to a signature envelope blob. ### Signature Filtering -An OCI artifact can have multiple signatures, Notary v2 uses annotations of the signature artifact to filter relevant signatures based on the applicable trust policy. -The Notary v2 signature artifact's `io.cncf.notary.x509chain.thumbprint#S256` annotations key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. +An OCI artifact can have multiple signatures, Notary uses annotations of the signature artifact to filter relevant signatures based on the applicable trust policy. +The Notary signature artifact's `io.cncf.notary.x509chain.thumbprint#S256` annotations key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. ## Signature Envelope @@ -127,20 +85,20 @@ A signature envelope consists of the following components: A signature envelope is `e = {m, v, u, s}` where `s` is signature. -This specification defines the set of signed and unsigned attributes that make up a valid The Notary v2 signature. This specification aims to be be agnostic of signature envelope format (e.g. COSE, JWS), details of encoding the envelope in a specific signature envelope format are covered in in separate specs. +This specification defines the set of signed and unsigned attributes that make up a valid Notary signature. This specification aims to be be agnostic of signature envelope format (e.g. COSE, JWS), details of encoding the envelope in a specific signature envelope format are covered in in separate specs. -Notary v2 supports the following envelope formats: +Notary signature supports the following envelope formats: - [JWS](./signature-envelope-jws.md) - [COSE Sign1](./signature-envelope-cose.md) ### Payload -Notary v2 payload is a JSON document with media type `application/vnd.cncf.notary.payload.v1+json` and has following properties. +Notary signature payload is a JSON document with media type `application/vnd.cncf.notary.payload.v1+json` and has following properties. - `targetArtifact` : Required property whose value is the descriptor of the target artifact manifest that is being signed. Only [OCI descriptor][oci-descriptor] is supported. - Descriptor MUST contain `mediaType`, `digest`, `size` fields. - - Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules][annotation-rules]. Notary v2 uses annotations for storing both Notary specific and user defined metadata. The prefix `io.cncf.notary` in annotation keys is reserved for use in Notary v2 and MUST NOT be used outside this specification. + - Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules][annotation-rules]. Notary signature uses annotations for storing both Notary specific and user defined metadata. The prefix `io.cncf.notary` in annotation keys is reserved for use in Notary and MUST NOT be used outside this specification. - Descriptor MAY contain `artifactType` field for artifact manifests, or the `config.mediaType` for `oci.image` based manifests. #### Examples @@ -177,11 +135,11 @@ Signed attributes/claims are additional metadata apart from the payload, which a - Claims that MUST be processed by a verifier MUST be marked as critical. Some claims may be optional and critical, i.e. they MUST be processed by a verifier only if they are present. - Claims which are informational and do not influence signature verification MUST NOT be marked critical. -Notary v2 requires the signature envelope to support the following signed attributes/claims. +Notary requires the signature envelope to support the following signed attributes/claims. #### Standard attributes -- **Signing Scheme** (critical): A REQUIRED claim that defines the [Notary v2 Signing Scheme](./signing-scheme.md) used by the signature. This attribute dictates the rest of signature schema - the set of signed and unsigned attributes to be included in the signature. Supported values are `notary.x509` and `notary.x509.signingAuthority`. +- **Signing Scheme** (critical): A REQUIRED claim that defines the [Notary Signing Scheme](./signing-scheme.md) used by the signature. This attribute dictates the rest of signature schema - the set of signed and unsigned attributes to be included in the signature. Supported values are `notary.x509` and `notary.x509.signingAuthority`. - **Signing Time**: A claim that indicates the time at which the signature was generated. Though this claim is signed by the signing key, it’s considered unauthenticated as a signer can modify local time and manipulate this claim. More details [here](#signing-time). This claim is REQUIRED and only valid when signing scheme is `notary.x509` . - **Authentic Signing Time** (critical): The authenticated time at which the signature was generated. This claim is REQUIRED and only valid when signing scheme is `notary.x509.signingAuthority` . More details [here](#signing-time). - **Expiry** (critical): An OPTIONAL claim that provides a “best by use” time for the artifact, as defined by the signer. More details [here](#expiry). @@ -189,17 +147,17 @@ Notary v2 requires the signature envelope to support the following signed attrib #### Extended attributes -Implementations of Notary v2 signature spec MAY include additional signed attributes in the signature envelope. +Implementations of Notary signature spec MAY include additional signed attributes in the signature envelope. These attributes MAY be marked critical, i.e. the attribute MUST be understood and processed by a verifier, unknown critical attributes MUST cause signature verification to fail. Usage of extended signed attributes which are marked critical in signature will have implications on portability of the signature, these are discussed in [Signature Portability](#signature-portability) section. #### Extended attributes for *Notation* Plugins -This section documents extended attributes used by Notary v2 reference implementation *Notation* to support plugins. +This section documents extended attributes used by Notary reference implementation *Notation* to support plugins. Plugins is a *Notation* concept that allows parts of signing and verification logic to be performed by an external provider. *Signing plugins* allow *Notation* to be extended for integration with remote keys remote key management services and signing services, where as *verification plugins* allow for customization of verification logic. Detailed specification for plugins can be found [here](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#notation-extensibility-for-signing-and-verification). -These extended attributes are documented in this spec, as other Notary V2 implementations may encounter these attributes if they verify a signature that indicated it required a verification plugin for complete signature verification. +These extended attributes are documented in this spec, as other Notary implementations may encounter these attributes if they verify a signature that indicated it required a verification plugin for complete signature verification. - **Verification Plugin** (critical): An OPTIONAL attribute that specifies the name of the verification plugin that MAY be used to verify the signature e.g. “com.example.nv2plugin”. [Notation plugin](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#plugin-contract) aware implementations use this attribute to load and execute a *Notation* compliant plugin. @@ -209,14 +167,14 @@ A Notation plugin aware implementations MUST use this attribute to verify the si The plugin MUST use [Semantic Versioning](https://semver.org/) (SemVer) to use this feature i.e the `get-plugin-metadata` plugin command MUST return a SemVer compliant version in the response. A use case for this feature is for a plugin publisher to address security bug in older plugin version, by setting the minimum version to the plugin version with fixes. -See [Guidelines for Notary v2 Implementors](#guidelines-for-notary-v2-implementors) for options to handle these attributes during signature verification. +See [Guidelines for Notary Implementors](#guidelines-for-notary-implementors) for options to handle these attributes during signature verification. ### Unsigned Attributes These attributes are considered unsigned with respect to the signing key that generates the signature. These attributes are typically signed by a third party (e.g. CA, TSA). - **Certificate Chain**: This is a REQUIRED attribute that contains the ordered list of X.509 public certificates associated with the signing key used to generate the signature. The ordered list starts with the signing certificates, any intermediate certificates and ends with the root certificate. The certificate chain MUST be authenticated against a trust store as part of signature validation. Specific requirements for the certificates in the chain are provided [here](#certificate-requirements). -- **Timestamp signature** : An OPTIONAL counter signature which provides [authentic timestamp](#signing-time)e.g. Time Stamp Authority (TSA) generated timestamp signature. Only [RFC3161](ietf-rfc3161) compliant TimeStampToken are currently supported. +- **Timestamp signature** : An OPTIONAL counter signature which provides [authentic timestamp](#signing-time)e.g. Time Stamp Authority (TSA) generated timestamp signature. Only [RFC3161][ietf-rfc3161] compliant TimeStampToken are currently supported. - **Signing Agent**: An OPTIONAL claim that provides the identifier of the software (e.g. Notation) that produced the signature on behalf of the user. It is an opaque string set by the software that produces the signature. It's intended primarily for diagnostic and troubleshooting purposes, this attribute is unsigned, the verifier MUST NOT validate formatting, or fail validation based on the content of this claim. The suggested format is one or more tokens of the form `{id}/{version}` containing identifier and version of the software, seperated by spaces. E.g. “notation/1.0.0”, “notation/1.0.0 com.example.nv2plugin/0.8”. ## Signature Algorithm Requirements @@ -287,12 +245,12 @@ The `keyUsage` extension MUST be present and MUST be marked critical. Bit positi ## FAQ -**Q: How will Notary v2 support multiple signature envelope formats?** +**Q: How will Notary support multiple signature envelope formats?** **A:** The `mediaType` of artifact manifest's blob identifies the signature envelope type. The client implementation can use the aforementioned `mediaType` to parse the signature envelope. -**Q: How will Notary v2 support multiple payload formats?** +**Q: How will Notary support multiple payload formats?** **A:** The Signature envelope MUST have a versioning mechanism to support multiple payload formats. @@ -307,7 +265,7 @@ The signing time denotes the time at which the signature was generated. A X509 c ### Expiry -This is an optional feature that provides a “best by use” time for the artifact, as defined by the signer. 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. +This is an optional feature that provides a “best by use” time for the artifact, as defined by the signer. Notary 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. ### Signature Portability @@ -323,44 +281,43 @@ Signatures associated with these artifacts require broad portability. E.g. Images for containerized applications and services used within an organization, or shared with limited authorized parties. Based on user requirements a private artifact can have different levels of portability, the signature’s portability should at least match the the artifact’s portability. -*Notary v2 signature portability* is based on the following +*Notary signature portability* is based on the following -**Signature discovery** +#### Signature discovery -Notary v2 addressed signature discovery by storing signatures in the same registry (location) where an artifact is present. +Notary addressed signature discovery by storing signatures in the same registry (location) where an artifact is present. This is supported through [OCI Distribution Referrers API][oci-distribution-referrers] which allows reference artifacts such as signatures, SBOMs to be associated with existing artifacts like Images. -Notary v2 allows multiple signatures to be associated with an artifact, and clients may automatically push signatures for an artifact to a destination registry when a signed artifact moves from one registry to other. +Notary allows multiple signatures to be associated with an artifact, and clients may automatically push signatures for an artifact to a destination registry when a signed artifact moves from one registry to other. -**Verification requirements** +#### Verification requirements -Notary v2 supports a range of signed artifacts intended for public and private distribution. -Signatures generated by Notary v2 without extended signature attributes marked critical can be verified in any environment where Notation client or another Notary v2 standards compliant verification tool is available, without any additional dependencies. +Notary supports a range of signed artifacts intended for public and private distribution. +Signatures generated by Notary without extended signature attributes marked critical can be verified in any environment where Notation client or another Notary standards compliant verification tool is available, without any additional dependencies. It should be noted that revocations checks, which usually relies on an external mechanism such as CRL/OCSP may require the verification environment to have access to local network or public internet, to have access to the CRL/OCSP endpoint. -Notary v2 also supports signatures generated using compliant signing plugins, which allow vendors to optionally provide additional features on top of Notary v2 standard features. -Verification of these signatures may require additional dependencies like Notary v2 compliant verification plugin, making these signatures more appropriate to use where broad portability may not be required for the associated signed artifact. +Notary also supports signatures generated using compliant signing plugins, which allow vendors to optionally provide additional features on top of Notary standard features. +Verification of these signatures may require additional dependencies like Notary compliant verification plugin, making these signatures more appropriate to use where broad portability may not be required for the associated signed artifact. This allows users to implement security controls required for their organizations, that are not broadly applicable and may take time to standardize. E.g. Integration with a signature transparency log as part of signature verification. Based on user’s requirements, a user can select appropriate signing mechanism that produces signatures with desired portability. -Notation signatures without any critical extended attributes do not impose any additional dependency requirements for verifiers as these can be validated with just the Notation client. -Whereas, Notation signatures that contain critical extended attributes will require additional dependencies for signature validation, either on Notary v2 compliant plugins or equivalent tooling which may not be available in all environments. -Similarly, Notary v2 compliant plugin vendors should be aware that usage of extended signed attributes which are marked critical in signature will have implications on portability of the signature. +Notary signatures without any critical extended attributes do not impose any additional dependency requirements for verifiers as these can be validated with just the Notation client. +Whereas, Notary signatures that contain critical extended attributes will require additional dependencies for signature validation, either on Notary compliant plugins or equivalent tooling which may not be available in all environments. +Similarly, Notary compliant plugin vendors should be aware that usage of extended signed attributes which are marked critical in signature will have implications on portability of the signature. -### Guidelines for Notary v2 Implementors +### Guidelines for Notary Implementors -Implementations of Notary v2, can choose to be [Notation plugin protocol](./plugin-extensibility.md#plugin-contract) aware or not. If an implementation chooses to be plugin protocol aware, and it encounters the Verification Plugin and Verification Plugin minimum version attributes during signature verification, it MUST process these attributes. This involves finding the appropriate plugin and the version to use, and executing `verify-signature` plugin command with correct inputs and processing the plugin response, as per the [Verification Plugin interface](./plugin-extensibility.md#verification-extensibility). +Implementations of Notary, can choose to be [Notation plugin protocol](./plugin-extensibility.md#plugin-contract) aware or not. If an implementation chooses to be plugin protocol aware, and it encounters the Verification Plugin and Verification Plugin minimum version attributes during signature verification, it MUST process these attributes. This involves finding the appropriate plugin and the version to use, and executing `verify-signature` plugin command with correct inputs and processing the plugin response, as per the [Verification Plugin interface](./plugin-extensibility.md#verification-extensibility). -Alternatively, an implementation of Notary v2 can choose not to implement plugin protocol. +Alternatively, an implementation of Notary can choose not to implement plugin protocol. - The implementation MUST itself perform equivalent verification logic that is usually performed by plugin specified in the signature. - An implementation MUST fail signature verification if it cannot perform the equivalent verification logic, as skipping the plugin equivalent verification logic will cause incorrect and inconsistent signature verification behavior. - An implementation MAY choose to support a set of known plugin’s verification logic and fail others. -[annotation-rules]: https://github.com/opencontainers/image-spec/blob/main/annotations.md#rules -[oci-descriptor]: https://github.com/opencontainers/image-spec/blob/main/descriptor.md +[annotation-rules]: https://github.com/opencontainers/image-spec/blob/v1.0.0/annotations.md#rules +[oci-descriptor]: https://github.com/opencontainers/image-spec/blob/v1.0.0/descriptor.md [ietf-rfc3161]: https://datatracker.ietf.org/doc/html/rfc3161#section-2.4.2 -[oci-artifact-manifest]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/artifact.md [oci-distribution-referrers]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers [oci-image-manifest]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/manifest.md [image-manifest-property-descriptions]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/manifest.md#image-manifest-property-descriptions From 530024724802c5185074370a08f50f853b55d0e7 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Wed, 10 May 2023 19:10:47 +0800 Subject: [PATCH 02/18] doc: update per comments Signed-off-by: Yi Zha --- media/signature-specification.svg | 2 +- specs/signature-specification.md | 78 ++++++++++++++++--------------- 2 files changed, 41 insertions(+), 39 deletions(-) diff --git a/media/signature-specification.svg b/media/signature-specification.svg index 6b2bc5be..5a826189 100644 --- a/media/signature-specification.svg +++ b/media/signature-specification.svg @@ -1,4 +1,4 @@ -
Registry
Regist...
Manifest
Manifest
Layers
Layers
Media Type
Media Type
Annotations
Annotations
Notary Signature Manifest
Notary Signature Mani...
Subject
(Manifest Descriptor)
Subject...
Payload
(Manifest Descriptor)
Payload(Manifest Des...
Signed Attributes
Signed Attributes
Unsigned Attributes
Unsigned Attributes
Signature
Signature
Signature Envelope

Signature Envelope...Text is not SVG - cannot display \ No newline at end of file +
Registry
Regist...
Manifest
Manifest
Layers
Layers
Media Type
Media Type
Annotations
Annotations
Notary Project Signature Manifest
Notary Project Signature Mani...
Subject
(Manifest Descriptor)
Subject...
Payload
(Manifest Descriptor)
Payload(Manifest Des...
Signed Attributes
Signed Attributes
Unsigned Attributes
Unsigned Attributes
Signature
Signature
Signature Envelope

Signature Envelope...Text is not SVG - cannot display \ No newline at end of file diff --git a/specs/signature-specification.md b/specs/signature-specification.md index a28fc15a..f42b5dad 100644 --- a/specs/signature-specification.md +++ b/specs/signature-specification.md @@ -1,15 +1,15 @@ # Signature Specification -This document provides the following details for Notary signatures: +This document provides the following details for Notary Project signatures: - **[Storage](#storage)**: Describes how signatures are stored and retrieved from an OCI registry. -- **[Signature Envelope](#signature-envelope)**: Describes the structure of a Notary signature. +- **[Signature Envelope](#signature-envelope)**: Describes the structure of a Notary Project signature. ## Storage -This section describes how Notary signatures are stored in the OCI Distribution conformant registry. +This section describes how Notary Project signatures are stored in the OCI Distribution conformant registry. OCI image manifest is used to store signatures in the registry, see [OCI image spec v1.1.0-rc.2][oci-image-manifest] for details. -The signature manifest has an media type of config that specifies it's a Notary signature, a subject referencing the manifest of the artifact being signed, a layer referencing the signature, and a collection of annotations. +The signature manifest has an media type of config that specifies it's a Notary Project signature, a subject referencing the manifest of the artifact being signed, a layer referencing the signature, and a collection of annotations. ![Signature storage inside registry](../media/signature-specification.svg) @@ -46,7 +46,7 @@ Signature manifest example per OCI image manifest: Besides the [image manifest property requirements][image-manifest-property-descriptions], the properties have the following additional restrictions: - **`mediaType`** (*string*): This REQUIRED property MUST be `application/vnd.oci.image.manifest.v1+json`. -- **`config`** (*descriptor*): This property is REQUIRED to be compatible with [OCI image specification][oci-image-manifest]. Notary doesn't require any configuration for a signature, and the configuration content is not consumed by Notary. +- **`config`** (*descriptor*): This property is REQUIRED to be compatible with [OCI image specification][oci-image-manifest]. Notary Project signature specification doesn't require any configuration for a signature, and the configuration content is not consumed by Notary Project tooling. - **`mediaType`** (*string*): This REQUIRED property MUST be `application/vnd.cncf.notary.signature`. - **`digest`** (*string*): This REQUIRED property is the digest of the config content. - **`size`** (*int64*): This REQUIRED property specifies the size, in bytes, of the raw config content. @@ -57,7 +57,7 @@ Besides the [image manifest property requirements][image-manifest-property-descr - **`subject`** (*descriptor*): A REQUIRED artifact descriptor referencing the signed manifest, including, but not limited to image manifest, image index, OCI artifact manifest. - **`annotations`** (*string-string map*): This REQUIRED property contains metadata for the artifact manifest. It is being used to store information about the signature. - Keys using the `io.cncf.notary` namespace are reserved for use in Notary and MUST NOT be used by other specifications. + Keys using the `io.cncf.notary` namespace are reserved for use in Notary Project and MUST NOT be used by other specifications. - **`io.cncf.notary.x509chain.thumbprint#S256`**: A REQUIRED annotation whose value contains the list of SHA-256 fingerprint of signing certificate and certificate chain (including root) used for signature generation. The annotation name contains the hash algorithm as a suffix (`#S256`) and can be extended to support other hashing algorithms in future. The list of fingerprints is present as a JSON array string, corresponding to ordered certificates in [*Certificate Chain* unsigned attribute](#unsigned-attributes) in the signature envelope. @@ -65,13 +65,13 @@ Besides the [image manifest property requirements][image-manifest-property-descr The client should be able to discover all the signatures belonging to an artifact (such as image manifest) by using [OCI Distribution Referrers API][oci-distribution-referrers]. OCI Distribution Referrers API returns a paginated list of all artifacts belonging to a target artifact (such as container images, SBoMs). -The implementation can filter Notary signature artifacts by either using OCI Distribution Referrers API or using custom logic on the client. -Each Notary signature artifact refers to a signature envelope blob. +The implementation can filter Notary Project signature artifacts by either using OCI Distribution Referrers API or using custom logic on the client. +Each Notary Project signature artifact refers to a signature envelope blob. ### Signature Filtering -An OCI artifact can have multiple signatures, Notary uses annotations of the signature artifact to filter relevant signatures based on the applicable trust policy. -The Notary signature artifact's `io.cncf.notary.x509chain.thumbprint#S256` annotations key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. +An OCI artifact can have multiple signatures, Notary Project tooling uses annotations of the signature artifact to filter relevant signatures based on the applicable trust policy. +The Notary Project signature artifact's `io.cncf.notary.x509chain.thumbprint#S256` annotations key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. ## Signature Envelope @@ -85,20 +85,20 @@ A signature envelope consists of the following components: A signature envelope is `e = {m, v, u, s}` where `s` is signature. -This specification defines the set of signed and unsigned attributes that make up a valid Notary signature. This specification aims to be be agnostic of signature envelope format (e.g. COSE, JWS), details of encoding the envelope in a specific signature envelope format are covered in in separate specs. +This specification defines the set of signed and unsigned attributes that make up a valid Notary Project signature. This specification aims to be be agnostic of signature envelope format (e.g. COSE, JWS), details of encoding the envelope in a specific signature envelope format are covered in in separate specs. -Notary signature supports the following envelope formats: +Notary Project signature supports the following envelope formats: - [JWS](./signature-envelope-jws.md) - [COSE Sign1](./signature-envelope-cose.md) ### Payload -Notary signature payload is a JSON document with media type `application/vnd.cncf.notary.payload.v1+json` and has following properties. +Notary Project signature payload is a JSON document with media type `application/vnd.cncf.notary.payload.v1+json` and has following properties. - `targetArtifact` : Required property whose value is the descriptor of the target artifact manifest that is being signed. Only [OCI descriptor][oci-descriptor] is supported. - Descriptor MUST contain `mediaType`, `digest`, `size` fields. - - Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules][annotation-rules]. Notary signature uses annotations for storing both Notary specific and user defined metadata. The prefix `io.cncf.notary` in annotation keys is reserved for use in Notary and MUST NOT be used outside this specification. + - Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules][annotation-rules]. Notary Project signature uses annotations for storing both Notary specific and user defined metadata. The prefix `io.cncf.notary` in annotation keys is reserved for use in Notary Project and MUST NOT be used outside this specification. - Descriptor MAY contain `artifactType` field for artifact manifests, or the `config.mediaType` for `oci.image` based manifests. #### Examples @@ -135,11 +135,11 @@ Signed attributes/claims are additional metadata apart from the payload, which a - Claims that MUST be processed by a verifier MUST be marked as critical. Some claims may be optional and critical, i.e. they MUST be processed by a verifier only if they are present. - Claims which are informational and do not influence signature verification MUST NOT be marked critical. -Notary requires the signature envelope to support the following signed attributes/claims. +Notary Project requires the signature envelope to support the following signed attributes/claims. #### Standard attributes -- **Signing Scheme** (critical): A REQUIRED claim that defines the [Notary Signing Scheme](./signing-scheme.md) used by the signature. This attribute dictates the rest of signature schema - the set of signed and unsigned attributes to be included in the signature. Supported values are `notary.x509` and `notary.x509.signingAuthority`. +- **Signing Scheme** (critical): A REQUIRED claim that defines the [Notary Project Signing Scheme](./signing-scheme.md) used by the signature. This attribute dictates the rest of signature schema - the set of signed and unsigned attributes to be included in the signature. Supported values are `notary.x509` and `notary.x509.signingAuthority`. - **Signing Time**: A claim that indicates the time at which the signature was generated. Though this claim is signed by the signing key, it’s considered unauthenticated as a signer can modify local time and manipulate this claim. More details [here](#signing-time). This claim is REQUIRED and only valid when signing scheme is `notary.x509` . - **Authentic Signing Time** (critical): The authenticated time at which the signature was generated. This claim is REQUIRED and only valid when signing scheme is `notary.x509.signingAuthority` . More details [here](#signing-time). - **Expiry** (critical): An OPTIONAL claim that provides a “best by use” time for the artifact, as defined by the signer. More details [here](#expiry). @@ -147,17 +147,19 @@ Notary requires the signature envelope to support the following signed attribute #### Extended attributes -Implementations of Notary signature spec MAY include additional signed attributes in the signature envelope. +Implementations of Notary Project signature spec MAY include additional signed attributes in the signature envelope. These attributes MAY be marked critical, i.e. the attribute MUST be understood and processed by a verifier, unknown critical attributes MUST cause signature verification to fail. Usage of extended signed attributes which are marked critical in signature will have implications on portability of the signature, these are discussed in [Signature Portability](#signature-portability) section. #### Extended attributes for *Notation* Plugins -This section documents extended attributes used by Notary reference implementation *Notation* to support plugins. +Notation is a CLI and set of libraries that offer an implementation of the Notary Project signature specification. Notation allows you to sign artifacts and attaching Notary Project signatures as well as verifying Notary Project signatures. + +This section documents extended attributes used by Notation to support plugins. Plugins is a *Notation* concept that allows parts of signing and verification logic to be performed by an external provider. *Signing plugins* allow *Notation* to be extended for integration with remote keys remote key management services and signing services, where as *verification plugins* allow for customization of verification logic. Detailed specification for plugins can be found [here](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#notation-extensibility-for-signing-and-verification). -These extended attributes are documented in this spec, as other Notary implementations may encounter these attributes if they verify a signature that indicated it required a verification plugin for complete signature verification. +These extended attributes are documented in this spec, as other Notary Project signature implementations may encounter these attributes if they verify a signature that indicated it required a verification plugin for complete signature verification. - **Verification Plugin** (critical): An OPTIONAL attribute that specifies the name of the verification plugin that MAY be used to verify the signature e.g. “com.example.nv2plugin”. [Notation plugin](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#plugin-contract) aware implementations use this attribute to load and execute a *Notation* compliant plugin. @@ -167,7 +169,7 @@ A Notation plugin aware implementations MUST use this attribute to verify the si The plugin MUST use [Semantic Versioning](https://semver.org/) (SemVer) to use this feature i.e the `get-plugin-metadata` plugin command MUST return a SemVer compliant version in the response. A use case for this feature is for a plugin publisher to address security bug in older plugin version, by setting the minimum version to the plugin version with fixes. -See [Guidelines for Notary Implementors](#guidelines-for-notary-implementors) for options to handle these attributes during signature verification. +See [Guidelines for Notary Project Signature Implementors](#guidelines-for-notary-project-signature-implementors) for options to handle these attributes during signature verification. ### Unsigned Attributes @@ -239,18 +241,18 @@ The `keyUsage` extension MUST be present and MUST be marked critical. Bit positi - The certificate MUST NOT chain to multiple parents/roots. - The certificate chain MUST NOT contain a certificate that is unrelated to the certificate chain. 1. Any certificate in the certificate chain MUST NOT use SHA1WithRSA and ECDSAWithSHA1 signatures. -1. Only Basic Constraints, Key Usage, and Extended Key Usage extensions of X.509 certificates are honored. For rest of the extensions, Notary MUST fail open i.e. they MUST NOT be evaluated or honored. -1. The certificates in the certificate chain MUST be valid at signing time. Notary MUST NOT enforce validity period nesting, i.e the validity period for a given certificate may not fall entirely within the validity period of that certificate's issuer certificate. +1. Only Basic Constraints, Key Usage, and Extended Key Usage extensions of X.509 certificates are honored. For rest of the extensions, Notary Project signature implementors MUST fail open i.e. they MUST NOT be evaluated or honored. +1. The certificates in the certificate chain MUST be valid at signing time. Notary Project signature implementors MUST NOT enforce validity period nesting, i.e the validity period for a given certificate may not fall entirely within the validity period of that certificate's issuer certificate. 1. In the absence of an Authentic Timestamp, each and every certificate in the certificate chain i.e. signing certificate, intermediate certificates, and the root certificate must be valid i.e. not expired at the time of signature verification. ## FAQ -**Q: How will Notary support multiple signature envelope formats?** +**Q: How will Notary Project support multiple signature envelope formats?** **A:** The `mediaType` of artifact manifest's blob identifies the signature envelope type. The client implementation can use the aforementioned `mediaType` to parse the signature envelope. -**Q: How will Notary support multiple payload formats?** +**Q: How will Notary Project support multiple payload formats?** **A:** The Signature envelope MUST have a versioning mechanism to support multiple payload formats. @@ -265,7 +267,7 @@ The signing time denotes the time at which the signature was generated. A X509 c ### Expiry -This is an optional feature that provides a “best by use” time for the artifact, as defined by the signer. Notary 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. +This is an optional feature that provides a “best by use” time for the artifact, as defined by the signer. Notary Project signature specification 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. ### Signature Portability @@ -281,35 +283,35 @@ Signatures associated with these artifacts require broad portability. E.g. Images for containerized applications and services used within an organization, or shared with limited authorized parties. Based on user requirements a private artifact can have different levels of portability, the signature’s portability should at least match the the artifact’s portability. -*Notary signature portability* is based on the following +*Notary Project signature portability* is based on the following #### Signature discovery -Notary addressed signature discovery by storing signatures in the same registry (location) where an artifact is present. +Notary Project signature specification addressed signature discovery by storing signatures in the same registry (location) where an artifact is present. This is supported through [OCI Distribution Referrers API][oci-distribution-referrers] which allows reference artifacts such as signatures, SBOMs to be associated with existing artifacts like Images. -Notary allows multiple signatures to be associated with an artifact, and clients may automatically push signatures for an artifact to a destination registry when a signed artifact moves from one registry to other. +Notary Project signature specification allows multiple signatures to be associated with an artifact, and clients may automatically push signatures for an artifact to a destination registry when a signed artifact moves from one registry to other. #### Verification requirements -Notary supports a range of signed artifacts intended for public and private distribution. -Signatures generated by Notary without extended signature attributes marked critical can be verified in any environment where Notation client or another Notary standards compliant verification tool is available, without any additional dependencies. +Notary Project signature specification supports a range of signed artifacts intended for public and private distribution. +Signatures generated without extended signature attributes marked critical can be verified in any environment where Notation client or another Notary Project standards compliant verification tool is available, without any additional dependencies. It should be noted that revocations checks, which usually relies on an external mechanism such as CRL/OCSP may require the verification environment to have access to local network or public internet, to have access to the CRL/OCSP endpoint. -Notary also supports signatures generated using compliant signing plugins, which allow vendors to optionally provide additional features on top of Notary standard features. -Verification of these signatures may require additional dependencies like Notary compliant verification plugin, making these signatures more appropriate to use where broad portability may not be required for the associated signed artifact. +Notary Project signature specification also supports signatures generated using compliant signing plugins, which allow vendors to optionally provide additional features on top of Notation standard features. +Verification of these signatures may require additional dependencies like Notation compliant verification plugin, making these signatures more appropriate to use where broad portability may not be required for the associated signed artifact. This allows users to implement security controls required for their organizations, that are not broadly applicable and may take time to standardize. E.g. Integration with a signature transparency log as part of signature verification. Based on user’s requirements, a user can select appropriate signing mechanism that produces signatures with desired portability. -Notary signatures without any critical extended attributes do not impose any additional dependency requirements for verifiers as these can be validated with just the Notation client. -Whereas, Notary signatures that contain critical extended attributes will require additional dependencies for signature validation, either on Notary compliant plugins or equivalent tooling which may not be available in all environments. -Similarly, Notary compliant plugin vendors should be aware that usage of extended signed attributes which are marked critical in signature will have implications on portability of the signature. +Notary Project signatures without any critical extended attributes do not impose any additional dependency requirements for verifiers as these can be validated with just the Notation client. +Whereas, Notary Project signatures that contain critical extended attributes will require additional dependencies for signature validation, either on Notation compliant plugins or equivalent tooling which may not be available in all environments. +Similarly, Notation compliant plugin vendors should be aware that usage of extended signed attributes which are marked critical in signature will have implications on portability of the signature. -### Guidelines for Notary Implementors +### Guidelines for Notary Project signature Implementors -Implementations of Notary, can choose to be [Notation plugin protocol](./plugin-extensibility.md#plugin-contract) aware or not. If an implementation chooses to be plugin protocol aware, and it encounters the Verification Plugin and Verification Plugin minimum version attributes during signature verification, it MUST process these attributes. This involves finding the appropriate plugin and the version to use, and executing `verify-signature` plugin command with correct inputs and processing the plugin response, as per the [Verification Plugin interface](./plugin-extensibility.md#verification-extensibility). +Implementations of Notary Project signature specification, can choose to be [Notation plugin protocol](./plugin-extensibility.md#plugin-contract) aware or not. If an implementation chooses to be plugin protocol aware, and it encounters the Verification Plugin and Verification Plugin minimum version attributes during signature verification, it MUST process these attributes. This involves finding the appropriate plugin and the version to use, and executing `verify-signature` plugin command with correct inputs and processing the plugin response, as per the [Verification Plugin interface](./plugin-extensibility.md#verification-extensibility). -Alternatively, an implementation of Notary can choose not to implement plugin protocol. +Alternatively, an implementation of Notary Project signature specification can choose not to implement plugin protocol. - The implementation MUST itself perform equivalent verification logic that is usually performed by plugin specified in the signature. - An implementation MUST fail signature verification if it cannot perform the equivalent verification logic, as skipping the plugin equivalent verification logic will cause incorrect and inconsistent signature verification behavior. From a48eda2462d3f16bdeb990e568e9cf5b28180119 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 11 May 2023 13:10:52 +0800 Subject: [PATCH 03/18] doc: update per comments Signed-off-by: Yi Zha --- specs/signature-specification.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/specs/signature-specification.md b/specs/signature-specification.md index f42b5dad..70963023 100644 --- a/specs/signature-specification.md +++ b/specs/signature-specification.md @@ -8,7 +8,7 @@ This document provides the following details for Notary Project signatures: ## Storage This section describes how Notary Project signatures are stored in the OCI Distribution conformant registry. -OCI image manifest is used to store signatures in the registry, see [OCI image spec v1.1.0-rc.2][oci-image-manifest] for details. +OCI image manifest is used to store signatures in the registry, see [OCI image spec v1.0.0][oci-image-manifest] for details. The signature manifest has an media type of config that specifies it's a Notary Project signature, a subject referencing the manifest of the artifact being signed, a layer referencing the signature, and a collection of annotations. ![Signature storage inside registry](../media/signature-specification.svg) @@ -54,8 +54,8 @@ Besides the [image manifest property requirements][image-manifest-property-descr - **`mediaType`** (*string*): This REQUIRED property contains media type of signature envelope blob. Following values are supported - `application/jose+json` - `application/cose` -- **`subject`** (*descriptor*): A REQUIRED artifact descriptor referencing the signed manifest, including, but not limited to image manifest, image index, OCI artifact manifest. -- **`annotations`** (*string-string map*): This REQUIRED property contains metadata for the artifact manifest. +- **`subject`** (*descriptor*): A REQUIRED artifact descriptor referencing the signed manifest, including, but not limited to image manifest, image index. +- **`annotations`** (*string-string map*): This REQUIRED property contains metadata for the image manifest. It is being used to store information about the signature. Keys using the `io.cncf.notary` namespace are reserved for use in Notary Project and MUST NOT be used by other specifications. - **`io.cncf.notary.x509chain.thumbprint#S256`**: A REQUIRED annotation whose value contains the list of SHA-256 fingerprint of signing certificate and certificate chain (including root) used for signature generation. The annotation name contains the hash algorithm as a suffix (`#S256`) and can be extended to support other hashing algorithms in future. @@ -99,7 +99,7 @@ Notary Project signature payload is a JSON document with media type `application - `targetArtifact` : Required property whose value is the descriptor of the target artifact manifest that is being signed. Only [OCI descriptor][oci-descriptor] is supported. - Descriptor MUST contain `mediaType`, `digest`, `size` fields. - Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules][annotation-rules]. Notary Project signature uses annotations for storing both Notary specific and user defined metadata. The prefix `io.cncf.notary` in annotation keys is reserved for use in Notary Project and MUST NOT be used outside this specification. - - Descriptor MAY contain `artifactType` field for artifact manifests, or the `config.mediaType` for `oci.image` based manifests. + - Descriptor MAY contain `artifactType` field for the `config.mediaType` for `oci.image` based manifests. #### Examples @@ -153,7 +153,7 @@ Usage of extended signed attributes which are marked critical in signature will #### Extended attributes for *Notation* Plugins -Notation is a CLI and set of libraries that offer an implementation of the Notary Project signature specification. Notation allows you to sign artifacts and attaching Notary Project signatures as well as verifying Notary Project signatures. +Notation is a CLI and set of libraries that offer an implementation of the Notary Project signature specification. Notation allows you to sign artifacts as well as verify artifacts using Notary Project signatures. This section documents extended attributes used by Notation to support plugins. Plugins is a *Notation* concept that allows parts of signing and verification logic to be performed by an external provider. @@ -249,7 +249,7 @@ The `keyUsage` extension MUST be present and MUST be marked critical. Bit positi **Q: How will Notary Project support multiple signature envelope formats?** -**A:** The `mediaType` of artifact manifest's blob identifies the signature envelope type. +**A:** The `mediaType` of image manifest's layer identifies the signature envelope type. The client implementation can use the aforementioned `mediaType` to parse the signature envelope. **Q: How will Notary Project support multiple payload formats?** @@ -320,6 +320,6 @@ Alternatively, an implementation of Notary Project signature specification can c [annotation-rules]: https://github.com/opencontainers/image-spec/blob/v1.0.0/annotations.md#rules [oci-descriptor]: https://github.com/opencontainers/image-spec/blob/v1.0.0/descriptor.md [ietf-rfc3161]: https://datatracker.ietf.org/doc/html/rfc3161#section-2.4.2 -[oci-distribution-referrers]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0-rc1/spec.md#listing-referrers -[oci-image-manifest]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/manifest.md -[image-manifest-property-descriptions]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/manifest.md#image-manifest-property-descriptions +[oci-distribution-referrers]: https://github.com/opencontainers/distribution-spec/blob/v1.0.0/spec.md#listing-referrers +[oci-image-manifest]: https://github.com/opencontainers/image-spec/blob/v1.0.0/manifest.md +[image-manifest-property-descriptions]: https://github.com/opencontainers/image-spec/blob/v1.0.0/manifest.md#image-manifest-property-descriptions From eb84a55c790cb70659b439da934ed9ee00ac6d67 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Sat, 20 May 2023 21:00:12 +0800 Subject: [PATCH 04/18] doc: update per comments Signed-off-by: Yi Zha --- media/signature-specification.svg | 2 +- specs/signature-specification.md | 21 ++++++++++----------- 2 files changed, 11 insertions(+), 12 deletions(-) diff --git a/media/signature-specification.svg b/media/signature-specification.svg index 5a826189..1708a5f1 100644 --- a/media/signature-specification.svg +++ b/media/signature-specification.svg @@ -1,4 +1,4 @@ -
Registry
Regist...
Manifest
Manifest
Layers
Layers
Media Type
Media Type
Annotations
Annotations
Notary Project Signature Manifest
Notary Project Signature Mani...
Subject
(Manifest Descriptor)
Subject...
Payload
(Manifest Descriptor)
Payload(Manifest Des...
Signed Attributes
Signed Attributes
Unsigned Attributes
Unsigned Attributes
Signature
Signature
Signature Envelope

Signature Envelope...Text is not SVG - cannot display \ No newline at end of file +
Registry
Regist...
Manifest
Manifest
Layers
Layers
config.mediaType
config.mediaType
Annotations
Annotations
Notary Project Signature Manifest
Notary Project Signature Mani...
Subject
(Manifest Descriptor)
Subject...
Payload
(Manifest Descriptor)
Payload(Manifest Des...
Signed Attributes
Signed Attributes
Unsigned Attributes
Unsigned Attributes
Signature
Signature
Signature Envelope

Signature Envelope...Text is not SVG - cannot display \ No newline at end of file diff --git a/specs/signature-specification.md b/specs/signature-specification.md index 70963023..7c60639d 100644 --- a/specs/signature-specification.md +++ b/specs/signature-specification.md @@ -8,8 +8,8 @@ This document provides the following details for Notary Project signatures: ## Storage This section describes how Notary Project signatures are stored in the OCI Distribution conformant registry. -OCI image manifest is used to store signatures in the registry, see [OCI image spec v1.0.0][oci-image-manifest] for details. -The signature manifest has an media type of config that specifies it's a Notary Project signature, a subject referencing the manifest of the artifact being signed, a layer referencing the signature, and a collection of annotations. +OCI image manifest is used to store signatures in the registry, see [OCI image spec v1.1.0-rc3][oci-image-manifest] for details. +The signature manifest has a configuration media type that specifies it's a Notary Project signature, a subject referencing the manifest of the artifact being signed, a layer referencing the signature, and a collection of annotations. ![Signature storage inside registry](../media/signature-specification.svg) @@ -54,12 +54,11 @@ Besides the [image manifest property requirements][image-manifest-property-descr - **`mediaType`** (*string*): This REQUIRED property contains media type of signature envelope blob. Following values are supported - `application/jose+json` - `application/cose` -- **`subject`** (*descriptor*): A REQUIRED artifact descriptor referencing the signed manifest, including, but not limited to image manifest, image index. +- **`subject`** (*descriptor*): A REQUIRED artifact descriptor referencing the signed manifest. - **`annotations`** (*string-string map*): This REQUIRED property contains metadata for the image manifest. It is being used to store information about the signature. Keys using the `io.cncf.notary` namespace are reserved for use in Notary Project and MUST NOT be used by other specifications. - - **`io.cncf.notary.x509chain.thumbprint#S256`**: A REQUIRED annotation whose value contains the list of SHA-256 fingerprint of signing certificate and certificate chain (including root) used for signature generation. The annotation name contains the hash algorithm as a suffix (`#S256`) and can be extended to support other hashing algorithms in future. - The list of fingerprints is present as a JSON array string, corresponding to ordered certificates in [*Certificate Chain* unsigned attribute](#unsigned-attributes) in the signature envelope. + - **`io.cncf.notary.x509chain.thumbprint#S256`**: A REQUIRED annotation whose value contains the list of SHA-256 fingerprints of signing certificate and certificate chain (including root) used for signature generation. The list of fingerprints is present as a JSON array string, corresponding to ordered certificates in [*Certificate Chain* unsigned attribute](#unsigned-attributes) in the signature envelope. The annotation name contains the hash algorithm as a suffix (`#S256`) and can be extended to support other hashing algorithms in future. ### Signature Discovery @@ -71,7 +70,7 @@ Each Notary Project signature artifact refers to a signature envelope blob. ### Signature Filtering An OCI artifact can have multiple signatures, Notary Project tooling uses annotations of the signature artifact to filter relevant signatures based on the applicable trust policy. -The Notary Project signature artifact's `io.cncf.notary.x509chain.thumbprint#S256` annotations key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. +The Notary Project signature manifest's `io.cncf.notary.x509chain.thumbprint#S256` annotation key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. ## Signature Envelope @@ -90,7 +89,7 @@ This specification defines the set of signed and unsigned attributes that make u Notary Project signature supports the following envelope formats: - [JWS](./signature-envelope-jws.md) -- [COSE Sign1](./signature-envelope-cose.md) +- [COSE](./signature-envelope-cose.md) ### Payload @@ -153,7 +152,7 @@ Usage of extended signed attributes which are marked critical in signature will #### Extended attributes for *Notation* Plugins -Notation is a CLI and set of libraries that offer an implementation of the Notary Project signature specification. Notation allows you to sign artifacts as well as verify artifacts using Notary Project signatures. +Notation is a CLI and has set of libraries that offer an implementation of the Notary Project signature specification. Notation allows you to sign artifacts as well as verify artifacts against Notary Project signatures. This section documents extended attributes used by Notation to support plugins. Plugins is a *Notation* concept that allows parts of signing and verification logic to be performed by an external provider. @@ -267,7 +266,7 @@ The signing time denotes the time at which the signature was generated. A X509 c ### Expiry -This is an optional feature that provides a “best by use” time for the artifact, as defined by the signer. Notary Project signature specification 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. +This is an optional feature that provides a "best by use" time for the artifact, as defined by the signer. Notary Project signature specification 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. ### Signature Portability @@ -321,5 +320,5 @@ Alternatively, an implementation of Notary Project signature specification can c [oci-descriptor]: https://github.com/opencontainers/image-spec/blob/v1.0.0/descriptor.md [ietf-rfc3161]: https://datatracker.ietf.org/doc/html/rfc3161#section-2.4.2 [oci-distribution-referrers]: https://github.com/opencontainers/distribution-spec/blob/v1.0.0/spec.md#listing-referrers -[oci-image-manifest]: https://github.com/opencontainers/image-spec/blob/v1.0.0/manifest.md -[image-manifest-property-descriptions]: https://github.com/opencontainers/image-spec/blob/v1.0.0/manifest.md#image-manifest-property-descriptions +[oci-image-manifest]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc3/manifest.md +[image-manifest-property-descriptions]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc3/manifest.md#image-manifest-property-descriptions From fd090fece6f80f76afe3244df3d7bdea94120db3 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Wed, 31 May 2023 16:14:55 +0800 Subject: [PATCH 05/18] update per comments Signed-off-by: Yi Zha --- specs/signature-specification.md | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/specs/signature-specification.md b/specs/signature-specification.md index 7c60639d..009b6594 100644 --- a/specs/signature-specification.md +++ b/specs/signature-specification.md @@ -98,19 +98,16 @@ Notary Project signature payload is a JSON document with media type `application - `targetArtifact` : Required property whose value is the descriptor of the target artifact manifest that is being signed. Only [OCI descriptor][oci-descriptor] is supported. - Descriptor MUST contain `mediaType`, `digest`, `size` fields. - Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules][annotation-rules]. Notary Project signature uses annotations for storing both Notary specific and user defined metadata. The prefix `io.cncf.notary` in annotation keys is reserved for use in Notary Project and MUST NOT be used outside this specification. - - Descriptor MAY contain `artifactType` field for the `config.mediaType` for `oci.image` based manifests. + - Descriptor MAY contain `artifactType` field for the `config.mediaType` of OCI image based manifests. #### Examples ```jsonc { "targetArtifact": { - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "digest": "sha256:73c803930ea3ba1e54bc25c2bdc53edd0284c62ed651fe7b00369da519a3c333", - "size": 16724, - "annotations": { - "io.wabbit-networks.buildId": "123" // user defined metadata - } + "mediaType": "sbom/example", + "digest": "sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0", + "size": 32654 } } ``` @@ -118,9 +115,13 @@ Notary Project signature payload is a JSON document with media type `application ```jsonc { "targetArtifact": { - "mediaType": "sbom/example", - "digest": "sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0", - "size": 32654 + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "digest": "sha256:73c803930ea3ba1e54bc25c2bdc53edd0284c62ed651fe7b00369da519a3c333", + "size": 16724, + "artifactType": "application/vnd.cncf.notary.signature", + "annotations": { + "io.wabbit-networks.buildId": "123" // user defined metadata + } } } ``` @@ -172,11 +173,11 @@ See [Guidelines for Notary Project Signature Implementors](#guidelines-for-notar ### Unsigned Attributes -These attributes are considered unsigned with respect to the signing key that generates the signature. These attributes are typically signed by a third party (e.g. CA, TSA). +These attributes are considered unsigned with respect to the signing key that generates the signature. -- **Certificate Chain**: This is a REQUIRED attribute that contains the ordered list of X.509 public certificates associated with the signing key used to generate the signature. The ordered list starts with the signing certificates, any intermediate certificates and ends with the root certificate. The certificate chain MUST be authenticated against a trust store as part of signature validation. Specific requirements for the certificates in the chain are provided [here](#certificate-requirements). +- **Certificate Chain**: This is a REQUIRED attribute that contains the ordered list of X.509 public certificates associated with the signing key used to generate the signature. The ordered list starts with the signing certificate, any intermediate certificates and ends with the root certificate. The certificate chain MUST be authenticated against a trust store as part of signature validation. Specific requirements for the certificates in the chain are provided [here](#certificate-requirements). - **Timestamp signature** : An OPTIONAL counter signature which provides [authentic timestamp](#signing-time)e.g. Time Stamp Authority (TSA) generated timestamp signature. Only [RFC3161][ietf-rfc3161] compliant TimeStampToken are currently supported. -- **Signing Agent**: An OPTIONAL claim that provides the identifier of the software (e.g. Notation) that produced the signature on behalf of the user. It is an opaque string set by the software that produces the signature. It's intended primarily for diagnostic and troubleshooting purposes, this attribute is unsigned, the verifier MUST NOT validate formatting, or fail validation based on the content of this claim. The suggested format is one or more tokens of the form `{id}/{version}` containing identifier and version of the software, seperated by spaces. E.g. “notation/1.0.0”, “notation/1.0.0 com.example.nv2plugin/0.8”. +- **Signing Agent**: An OPTIONAL claim that provides the identifier of the software (e.g. Notation) that produced the signature on behalf of the user. It is an opaque string set by the software that produces the signature. It's intended primarily for diagnostic and troubleshooting purposes, this attribute is unsigned, the verifier MUST NOT validate formatting, or fail validation based on the content of this claim. The suggested format is one or more tokens of the form `{id}/{version}` containing identifier and version of the software, separated by spaces. E.g. “notation/1.0.0”, “notation/1.0.0 myplugin/0.8”. ## Signature Algorithm Requirements @@ -240,7 +241,7 @@ The `keyUsage` extension MUST be present and MUST be marked critical. Bit positi - The certificate MUST NOT chain to multiple parents/roots. - The certificate chain MUST NOT contain a certificate that is unrelated to the certificate chain. 1. Any certificate in the certificate chain MUST NOT use SHA1WithRSA and ECDSAWithSHA1 signatures. -1. Only Basic Constraints, Key Usage, and Extended Key Usage extensions of X.509 certificates are honored. For rest of the extensions, Notary Project signature implementors MUST fail open i.e. they MUST NOT be evaluated or honored. +1. Only Basic Constraints, Key Usage, and Extended Key Usage extensions of X.509 certificates are honored. For rest of the extensions, Notary Project signature implementors MUST fail to open i.e. they MUST NOT be evaluated or honored. 1. The certificates in the certificate chain MUST be valid at signing time. Notary Project signature implementors MUST NOT enforce validity period nesting, i.e the validity period for a given certificate may not fall entirely within the validity period of that certificate's issuer certificate. 1. In the absence of an Authentic Timestamp, each and every certificate in the certificate chain i.e. signing certificate, intermediate certificates, and the root certificate must be valid i.e. not expired at the time of signature verification. From 9b342311381a8158a0cf9a261c4cc979f5265bd7 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 5 Jun 2023 19:38:54 +0800 Subject: [PATCH 06/18] doc: update per comments Signed-off-by: Yi Zha --- specs/signature-specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/signature-specification.md b/specs/signature-specification.md index 009b6594..88b00be0 100644 --- a/specs/signature-specification.md +++ b/specs/signature-specification.md @@ -241,7 +241,7 @@ The `keyUsage` extension MUST be present and MUST be marked critical. Bit positi - The certificate MUST NOT chain to multiple parents/roots. - The certificate chain MUST NOT contain a certificate that is unrelated to the certificate chain. 1. Any certificate in the certificate chain MUST NOT use SHA1WithRSA and ECDSAWithSHA1 signatures. -1. Only Basic Constraints, Key Usage, and Extended Key Usage extensions of X.509 certificates are honored. For rest of the extensions, Notary Project signature implementors MUST fail to open i.e. they MUST NOT be evaluated or honored. +1. Only Basic Constraints, Key Usage, and Extended Key Usage extensions of X.509 certificates are honored. For rest of the extensions, Notary Project signature implementors MUST fail open i.e. rest of the extensions MUST NOT be evaluated or honored. 1. The certificates in the certificate chain MUST be valid at signing time. Notary Project signature implementors MUST NOT enforce validity period nesting, i.e the validity period for a given certificate may not fall entirely within the validity period of that certificate's issuer certificate. 1. In the absence of an Authentic Timestamp, each and every certificate in the certificate chain i.e. signing certificate, intermediate certificates, and the root certificate must be valid i.e. not expired at the time of signature verification. From 6d5f1122e44e0622296aa300f07292a5eda1ff19 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Sat, 10 Jun 2023 15:21:23 +0800 Subject: [PATCH 07/18] doc: update per comments Signed-off-by: Yi Zha --- specs/signature-specification.md | 66 ++++++++++++++++---------------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/specs/signature-specification.md b/specs/signature-specification.md index 88b00be0..f00116d3 100644 --- a/specs/signature-specification.md +++ b/specs/signature-specification.md @@ -1,15 +1,15 @@ # Signature Specification -This document provides the following details for Notary Project signatures: +This document provides the following details for the Notary Project signature: - **[Storage](#storage)**: Describes how signatures are stored and retrieved from an OCI registry. -- **[Signature Envelope](#signature-envelope)**: Describes the structure of a Notary Project signature. +- **[Signature Envelope](#signature-envelope)**: Describes the structure of the Notary Project signature. ## Storage -This section describes how Notary Project signatures are stored in the OCI Distribution conformant registry. +This section describes how the Notary Project signature are stored in the OCI Distribution conformant registry. OCI image manifest is used to store signatures in the registry, see [OCI image spec v1.1.0-rc3][oci-image-manifest] for details. -The signature manifest has a configuration media type that specifies it's a Notary Project signature, a subject referencing the manifest of the artifact being signed, a layer referencing the signature, and a collection of annotations. +The signature manifest has a configuration media type that specifies it's the Notary Project signature, a subject referencing the manifest of the artifact being signed, a layer referencing the signature, and a collection of annotations. ![Signature storage inside registry](../media/signature-specification.svg) @@ -46,7 +46,7 @@ Signature manifest example per OCI image manifest: Besides the [image manifest property requirements][image-manifest-property-descriptions], the properties have the following additional restrictions: - **`mediaType`** (*string*): This REQUIRED property MUST be `application/vnd.oci.image.manifest.v1+json`. -- **`config`** (*descriptor*): This property is REQUIRED to be compatible with [OCI image specification][oci-image-manifest]. Notary Project signature specification doesn't require any configuration for a signature, and the configuration content is not consumed by Notary Project tooling. +- **`config`** (*descriptor*): This property is REQUIRED to be compatible with [OCI image specification][oci-image-manifest]. The Notary Project signature specification doesn't require any configuration for a signature, and the configuration content is not consumed by the Notary Project tooling. - **`mediaType`** (*string*): This REQUIRED property MUST be `application/vnd.cncf.notary.signature`. - **`digest`** (*string*): This REQUIRED property is the digest of the config content. - **`size`** (*int64*): This REQUIRED property specifies the size, in bytes, of the raw config content. @@ -57,19 +57,19 @@ Besides the [image manifest property requirements][image-manifest-property-descr - **`subject`** (*descriptor*): A REQUIRED artifact descriptor referencing the signed manifest. - **`annotations`** (*string-string map*): This REQUIRED property contains metadata for the image manifest. It is being used to store information about the signature. - Keys using the `io.cncf.notary` namespace are reserved for use in Notary Project and MUST NOT be used by other specifications. + Keys using the `io.cncf.notary` namespace are reserved for use in the Notary Project and MUST NOT be used by other specifications. - **`io.cncf.notary.x509chain.thumbprint#S256`**: A REQUIRED annotation whose value contains the list of SHA-256 fingerprints of signing certificate and certificate chain (including root) used for signature generation. The list of fingerprints is present as a JSON array string, corresponding to ordered certificates in [*Certificate Chain* unsigned attribute](#unsigned-attributes) in the signature envelope. The annotation name contains the hash algorithm as a suffix (`#S256`) and can be extended to support other hashing algorithms in future. ### Signature Discovery The client should be able to discover all the signatures belonging to an artifact (such as image manifest) by using [OCI Distribution Referrers API][oci-distribution-referrers]. OCI Distribution Referrers API returns a paginated list of all artifacts belonging to a target artifact (such as container images, SBoMs). -The implementation can filter Notary Project signature artifacts by either using OCI Distribution Referrers API or using custom logic on the client. -Each Notary Project signature artifact refers to a signature envelope blob. +The implementation can filter the Notary Project signatures by either using OCI Distribution Referrers API or using custom logic on the client. +Each the Notary Project signature refers to a signature envelope blob. ### Signature Filtering -An OCI artifact can have multiple signatures, Notary Project tooling uses annotations of the signature artifact to filter relevant signatures based on the applicable trust policy. +An OCI artifact can have multiple signatures, The Notary Project tooling uses annotations of the signature artifact to filter relevant signatures based on the applicable trust policy. The Notary Project signature manifest's `io.cncf.notary.x509chain.thumbprint#S256` annotation key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. ## Signature Envelope @@ -86,18 +86,18 @@ A signature envelope is `e = {m, v, u, s}` where `s` is signature. This specification defines the set of signed and unsigned attributes that make up a valid Notary Project signature. This specification aims to be be agnostic of signature envelope format (e.g. COSE, JWS), details of encoding the envelope in a specific signature envelope format are covered in in separate specs. -Notary Project signature supports the following envelope formats: +The Notary Project signature supports the following envelope formats: - [JWS](./signature-envelope-jws.md) - [COSE](./signature-envelope-cose.md) ### Payload -Notary Project signature payload is a JSON document with media type `application/vnd.cncf.notary.payload.v1+json` and has following properties. +The Notary Project signature payload is a JSON document with media type `application/vnd.cncf.notary.payload.v1+json` and has following properties. - `targetArtifact` : Required property whose value is the descriptor of the target artifact manifest that is being signed. Only [OCI descriptor][oci-descriptor] is supported. - Descriptor MUST contain `mediaType`, `digest`, `size` fields. - - Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules][annotation-rules]. Notary Project signature uses annotations for storing both Notary specific and user defined metadata. The prefix `io.cncf.notary` in annotation keys is reserved for use in Notary Project and MUST NOT be used outside this specification. + - Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules][annotation-rules]. The Notary Project signature uses annotations for storing both Notary specific and user defined metadata. The prefix `io.cncf.notary` in annotation keys is reserved for use in the Notary Project signature and MUST NOT be used outside this specification. - Descriptor MAY contain `artifactType` field for the `config.mediaType` of OCI image based manifests. #### Examples @@ -135,7 +135,7 @@ Signed attributes/claims are additional metadata apart from the payload, which a - Claims that MUST be processed by a verifier MUST be marked as critical. Some claims may be optional and critical, i.e. they MUST be processed by a verifier only if they are present. - Claims which are informational and do not influence signature verification MUST NOT be marked critical. -Notary Project requires the signature envelope to support the following signed attributes/claims. +The Notary Project requires the signature envelope to support the following signed attributes/claims. #### Standard attributes @@ -147,19 +147,19 @@ Notary Project requires the signature envelope to support the following signed a #### Extended attributes -Implementations of Notary Project signature spec MAY include additional signed attributes in the signature envelope. +Implementations of the Notary Project signature spec MAY include additional signed attributes in the signature envelope. These attributes MAY be marked critical, i.e. the attribute MUST be understood and processed by a verifier, unknown critical attributes MUST cause signature verification to fail. Usage of extended signed attributes which are marked critical in signature will have implications on portability of the signature, these are discussed in [Signature Portability](#signature-portability) section. #### Extended attributes for *Notation* Plugins -Notation is a CLI and has set of libraries that offer an implementation of the Notary Project signature specification. Notation allows you to sign artifacts as well as verify artifacts against Notary Project signatures. +Notation is a CLI and has set of libraries that offer an implementation of the Notary Project signature specification. Notation allows you to sign artifacts as well as verify artifacts against the Notary Project signatures. This section documents extended attributes used by Notation to support plugins. Plugins is a *Notation* concept that allows parts of signing and verification logic to be performed by an external provider. *Signing plugins* allow *Notation* to be extended for integration with remote keys remote key management services and signing services, where as *verification plugins* allow for customization of verification logic. Detailed specification for plugins can be found [here](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#notation-extensibility-for-signing-and-verification). -These extended attributes are documented in this spec, as other Notary Project signature implementations may encounter these attributes if they verify a signature that indicated it required a verification plugin for complete signature verification. +These extended attributes are documented in this spec, as other implementations of the Notary Project signature specification may encounter these attributes if they verify a signature that indicated it required a verification plugin for complete signature verification. - **Verification Plugin** (critical): An OPTIONAL attribute that specifies the name of the verification plugin that MAY be used to verify the signature e.g. “com.example.nv2plugin”. [Notation plugin](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#plugin-contract) aware implementations use this attribute to load and execute a *Notation* compliant plugin. @@ -169,7 +169,7 @@ A Notation plugin aware implementations MUST use this attribute to verify the si The plugin MUST use [Semantic Versioning](https://semver.org/) (SemVer) to use this feature i.e the `get-plugin-metadata` plugin command MUST return a SemVer compliant version in the response. A use case for this feature is for a plugin publisher to address security bug in older plugin version, by setting the minimum version to the plugin version with fixes. -See [Guidelines for Notary Project Signature Implementors](#guidelines-for-notary-project-signature-implementors) for options to handle these attributes during signature verification. +See [Guidelines for implementations of the Notary Project signature specification](#guidelines-for-notary-project-signature-implementors) for options to handle these attributes during signature verification. ### Unsigned Attributes @@ -241,18 +241,18 @@ The `keyUsage` extension MUST be present and MUST be marked critical. Bit positi - The certificate MUST NOT chain to multiple parents/roots. - The certificate chain MUST NOT contain a certificate that is unrelated to the certificate chain. 1. Any certificate in the certificate chain MUST NOT use SHA1WithRSA and ECDSAWithSHA1 signatures. -1. Only Basic Constraints, Key Usage, and Extended Key Usage extensions of X.509 certificates are honored. For rest of the extensions, Notary Project signature implementors MUST fail open i.e. rest of the extensions MUST NOT be evaluated or honored. -1. The certificates in the certificate chain MUST be valid at signing time. Notary Project signature implementors MUST NOT enforce validity period nesting, i.e the validity period for a given certificate may not fall entirely within the validity period of that certificate's issuer certificate. +1. Only Basic Constraints, Key Usage, and Extended Key Usage extensions of X.509 certificates are honored. For rest of the extensions, implementations of the Notary Project signature specification MUST fail open i.e. rest of the extensions MUST NOT be evaluated or honored. +1. The certificates in the certificate chain MUST be valid at signing time. Implementations of the Notary Project signature specification MUST NOT enforce validity period nesting, i.e the validity period for a given certificate may not fall entirely within the validity period of that certificate's issuer certificate. 1. In the absence of an Authentic Timestamp, each and every certificate in the certificate chain i.e. signing certificate, intermediate certificates, and the root certificate must be valid i.e. not expired at the time of signature verification. ## FAQ -**Q: How will Notary Project support multiple signature envelope formats?** +**Q: How will the Notary Project specification support multiple signature envelope formats?** **A:** The `mediaType` of image manifest's layer identifies the signature envelope type. The client implementation can use the aforementioned `mediaType` to parse the signature envelope. -**Q: How will Notary Project support multiple payload formats?** +**Q: How will the Notary Project specification support multiple payload formats?** **A:** The Signature envelope MUST have a versioning mechanism to support multiple payload formats. @@ -267,7 +267,7 @@ The signing time denotes the time at which the signature was generated. A X509 c ### Expiry -This is an optional feature that provides a "best by use" time for the artifact, as defined by the signer. Notary Project signature specification 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. +This is an optional feature that provides a "best by use" time for the artifact, as defined by the signer. The Notary Project signature specification 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. ### Signature Portability @@ -283,35 +283,35 @@ Signatures associated with these artifacts require broad portability. E.g. Images for containerized applications and services used within an organization, or shared with limited authorized parties. Based on user requirements a private artifact can have different levels of portability, the signature’s portability should at least match the the artifact’s portability. -*Notary Project signature portability* is based on the following +*The Notary Project signature portability* is based on the following #### Signature discovery -Notary Project signature specification addressed signature discovery by storing signatures in the same registry (location) where an artifact is present. +The Notary Project signature specification addressed signature discovery by storing signatures in the same registry (location) where an artifact is present. This is supported through [OCI Distribution Referrers API][oci-distribution-referrers] which allows reference artifacts such as signatures, SBOMs to be associated with existing artifacts like Images. -Notary Project signature specification allows multiple signatures to be associated with an artifact, and clients may automatically push signatures for an artifact to a destination registry when a signed artifact moves from one registry to other. +The Notary Project signature specification allows multiple signatures to be associated with an artifact, and clients may automatically push signatures for an artifact to a destination registry when a signed artifact moves from one registry to other. #### Verification requirements -Notary Project signature specification supports a range of signed artifacts intended for public and private distribution. -Signatures generated without extended signature attributes marked critical can be verified in any environment where Notation client or another Notary Project standards compliant verification tool is available, without any additional dependencies. +The Notary Project signature specification supports a range of signed artifacts intended for public and private distribution. +Signatures generated without extended signature attributes marked critical can be verified in any environment where Notation client or another Notary Project specification compliant verification tool is available, without any additional dependencies. It should be noted that revocations checks, which usually relies on an external mechanism such as CRL/OCSP may require the verification environment to have access to local network or public internet, to have access to the CRL/OCSP endpoint. -Notary Project signature specification also supports signatures generated using compliant signing plugins, which allow vendors to optionally provide additional features on top of Notation standard features. +The Notary Project signature specification also supports signatures generated using compliant signing plugins, which allow vendors to optionally provide additional features on top of Notation standard features. Verification of these signatures may require additional dependencies like Notation compliant verification plugin, making these signatures more appropriate to use where broad portability may not be required for the associated signed artifact. This allows users to implement security controls required for their organizations, that are not broadly applicable and may take time to standardize. E.g. Integration with a signature transparency log as part of signature verification. Based on user’s requirements, a user can select appropriate signing mechanism that produces signatures with desired portability. -Notary Project signatures without any critical extended attributes do not impose any additional dependency requirements for verifiers as these can be validated with just the Notation client. -Whereas, Notary Project signatures that contain critical extended attributes will require additional dependencies for signature validation, either on Notation compliant plugins or equivalent tooling which may not be available in all environments. +The Notary Project signatures without any critical extended attributes do not impose any additional dependency requirements for verifiers as these can be validated with just the Notation client. +Whereas, the Notary Project signatures that contain critical extended attributes will require additional dependencies for signature validation, either on Notation compliant plugins or equivalent tooling which may not be available in all environments. Similarly, Notation compliant plugin vendors should be aware that usage of extended signed attributes which are marked critical in signature will have implications on portability of the signature. -### Guidelines for Notary Project signature Implementors +### Guidelines for implementations of the Notary Project signature specification -Implementations of Notary Project signature specification, can choose to be [Notation plugin protocol](./plugin-extensibility.md#plugin-contract) aware or not. If an implementation chooses to be plugin protocol aware, and it encounters the Verification Plugin and Verification Plugin minimum version attributes during signature verification, it MUST process these attributes. This involves finding the appropriate plugin and the version to use, and executing `verify-signature` plugin command with correct inputs and processing the plugin response, as per the [Verification Plugin interface](./plugin-extensibility.md#verification-extensibility). +Implementations of the Notary Project signature specification, can choose to be [Notation plugin protocol](./plugin-extensibility.md#plugin-contract) aware or not. If an implementation chooses to be plugin protocol aware, and it encounters the Verification Plugin and Verification Plugin minimum version attributes during signature verification, it MUST process these attributes. This involves finding the appropriate plugin and the version to use, and executing `verify-signature` plugin command with correct inputs and processing the plugin response, as per the [Verification Plugin interface](./plugin-extensibility.md#verification-extensibility). -Alternatively, an implementation of Notary Project signature specification can choose not to implement plugin protocol. +Alternatively, an implementation of the Notary Project signature specification can choose not to implement plugin protocol. - The implementation MUST itself perform equivalent verification logic that is usually performed by plugin specified in the signature. - An implementation MUST fail signature verification if it cannot perform the equivalent verification logic, as skipping the plugin equivalent verification logic will cause incorrect and inconsistent signature verification behavior. From d5975ef491dbf232ac234283262e8abd13d8afd0 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Sat, 10 Jun 2023 15:29:17 +0800 Subject: [PATCH 08/18] doc: update per comments Signed-off-by: Yi Zha --- media/signature-specification.svg | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/media/signature-specification.svg b/media/signature-specification.svg index 1708a5f1..dc124bc4 100644 --- a/media/signature-specification.svg +++ b/media/signature-specification.svg @@ -1,4 +1,4 @@ -
Registry
Regist...
Manifest
Manifest
Layers
Layers
config.mediaType
config.mediaType
Annotations
Annotations
Notary Project Signature Manifest
Notary Project Signature Mani...
Subject
(Manifest Descriptor)
Subject...
Payload
(Manifest Descriptor)
Payload(Manifest Des...
Signed Attributes
Signed Attributes
Unsigned Attributes
Unsigned Attributes
Signature
Signature
Signature Envelope

Signature Envelope...Text is not SVG - cannot display \ No newline at end of file +
Registry
Regist...
Manifest
Manifest
Layers
Layers
config.mediaType
config.mediaType
Annotations
Annotations
The Notary Project Signature Manifest
The Notary Project Signature Mani...
Subject
(Manifest Descriptor)
Subject...
Payload
(Manifest Descriptor)
Payload(Manifest Des...
Signed Attributes
Signed Attributes
Unsigned Attributes
Unsigned Attributes
Signature
Signature
Signature Envelope

Signature Envelope...Text is not SVG - cannot display \ No newline at end of file From 3a5c26e02f1ab196d48dc4aa92c377d82ee11aa3 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 12 Jun 2023 14:12:07 +0800 Subject: [PATCH 09/18] update to Notary signature Signed-off-by: Yi Zha --- specs/signature-specification.md | 58 ++++++++++++++++---------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/specs/signature-specification.md b/specs/signature-specification.md index f00116d3..54e82157 100644 --- a/specs/signature-specification.md +++ b/specs/signature-specification.md @@ -1,15 +1,15 @@ # Signature Specification -This document provides the following details for the Notary Project signature: +This document provides the following details for the Notary signature: - **[Storage](#storage)**: Describes how signatures are stored and retrieved from an OCI registry. -- **[Signature Envelope](#signature-envelope)**: Describes the structure of the Notary Project signature. +- **[Signature Envelope](#signature-envelope)**: Describes the structure of the Notary signature. ## Storage -This section describes how the Notary Project signature are stored in the OCI Distribution conformant registry. +This section describes how the Notary signature are stored in the OCI Distribution conformant registry. OCI image manifest is used to store signatures in the registry, see [OCI image spec v1.1.0-rc3][oci-image-manifest] for details. -The signature manifest has a configuration media type that specifies it's the Notary Project signature, a subject referencing the manifest of the artifact being signed, a layer referencing the signature, and a collection of annotations. +The signature manifest has a configuration media type that specifies it's the Notary signature, a subject referencing the manifest of the artifact being signed, a layer referencing the signature, and a collection of annotations. ![Signature storage inside registry](../media/signature-specification.svg) @@ -46,7 +46,7 @@ Signature manifest example per OCI image manifest: Besides the [image manifest property requirements][image-manifest-property-descriptions], the properties have the following additional restrictions: - **`mediaType`** (*string*): This REQUIRED property MUST be `application/vnd.oci.image.manifest.v1+json`. -- **`config`** (*descriptor*): This property is REQUIRED to be compatible with [OCI image specification][oci-image-manifest]. The Notary Project signature specification doesn't require any configuration for a signature, and the configuration content is not consumed by the Notary Project tooling. +- **`config`** (*descriptor*): This property is REQUIRED to be compatible with [OCI image specification][oci-image-manifest]. The Notary signature specification doesn't require any configuration for a signature, and the configuration content is not consumed by the Notary Project tooling. - **`mediaType`** (*string*): This REQUIRED property MUST be `application/vnd.cncf.notary.signature`. - **`digest`** (*string*): This REQUIRED property is the digest of the config content. - **`size`** (*int64*): This REQUIRED property specifies the size, in bytes, of the raw config content. @@ -64,13 +64,13 @@ Besides the [image manifest property requirements][image-manifest-property-descr The client should be able to discover all the signatures belonging to an artifact (such as image manifest) by using [OCI Distribution Referrers API][oci-distribution-referrers]. OCI Distribution Referrers API returns a paginated list of all artifacts belonging to a target artifact (such as container images, SBoMs). -The implementation can filter the Notary Project signatures by either using OCI Distribution Referrers API or using custom logic on the client. -Each the Notary Project signature refers to a signature envelope blob. +The implementation can filter the Notary signatures by either using OCI Distribution Referrers API or using custom logic on the client. +Each the Notary signature refers to a signature envelope blob. ### Signature Filtering An OCI artifact can have multiple signatures, The Notary Project tooling uses annotations of the signature artifact to filter relevant signatures based on the applicable trust policy. -The Notary Project signature manifest's `io.cncf.notary.x509chain.thumbprint#S256` annotation key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. +The Notary signature manifest's `io.cncf.notary.x509chain.thumbprint#S256` annotation key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. ## Signature Envelope @@ -84,20 +84,20 @@ A signature envelope consists of the following components: A signature envelope is `e = {m, v, u, s}` where `s` is signature. -This specification defines the set of signed and unsigned attributes that make up a valid Notary Project signature. This specification aims to be be agnostic of signature envelope format (e.g. COSE, JWS), details of encoding the envelope in a specific signature envelope format are covered in in separate specs. +This specification defines the set of signed and unsigned attributes that make up a valid Notary signature. This specification aims to be be agnostic of signature envelope format (e.g. COSE, JWS), details of encoding the envelope in a specific signature envelope format are covered in in separate specs. -The Notary Project signature supports the following envelope formats: +The Notary signature supports the following envelope formats: - [JWS](./signature-envelope-jws.md) - [COSE](./signature-envelope-cose.md) ### Payload -The Notary Project signature payload is a JSON document with media type `application/vnd.cncf.notary.payload.v1+json` and has following properties. +The Notary signature payload is a JSON document with media type `application/vnd.cncf.notary.payload.v1+json` and has following properties. - `targetArtifact` : Required property whose value is the descriptor of the target artifact manifest that is being signed. Only [OCI descriptor][oci-descriptor] is supported. - Descriptor MUST contain `mediaType`, `digest`, `size` fields. - - Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules][annotation-rules]. The Notary Project signature uses annotations for storing both Notary specific and user defined metadata. The prefix `io.cncf.notary` in annotation keys is reserved for use in the Notary Project signature and MUST NOT be used outside this specification. + - Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules][annotation-rules]. The Notary signature uses annotations for storing both Notary specific and user defined metadata. The prefix `io.cncf.notary` in annotation keys is reserved for use in the Notary signature and MUST NOT be used outside this specification. - Descriptor MAY contain `artifactType` field for the `config.mediaType` of OCI image based manifests. #### Examples @@ -147,19 +147,19 @@ The Notary Project requires the signature envelope to support the following sign #### Extended attributes -Implementations of the Notary Project signature spec MAY include additional signed attributes in the signature envelope. +Implementations of the Notary signature spec MAY include additional signed attributes in the signature envelope. These attributes MAY be marked critical, i.e. the attribute MUST be understood and processed by a verifier, unknown critical attributes MUST cause signature verification to fail. Usage of extended signed attributes which are marked critical in signature will have implications on portability of the signature, these are discussed in [Signature Portability](#signature-portability) section. #### Extended attributes for *Notation* Plugins -Notation is a CLI and has set of libraries that offer an implementation of the Notary Project signature specification. Notation allows you to sign artifacts as well as verify artifacts against the Notary Project signatures. +Notation is a CLI and has set of libraries that offer an implementation of the Notary signature specification. Notation allows you to sign artifacts as well as verify artifacts against the Notary signatures. This section documents extended attributes used by Notation to support plugins. Plugins is a *Notation* concept that allows parts of signing and verification logic to be performed by an external provider. *Signing plugins* allow *Notation* to be extended for integration with remote keys remote key management services and signing services, where as *verification plugins* allow for customization of verification logic. Detailed specification for plugins can be found [here](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#notation-extensibility-for-signing-and-verification). -These extended attributes are documented in this spec, as other implementations of the Notary Project signature specification may encounter these attributes if they verify a signature that indicated it required a verification plugin for complete signature verification. +These extended attributes are documented in this spec, as other implementations of the Notary signature specification may encounter these attributes if they verify a signature that indicated it required a verification plugin for complete signature verification. - **Verification Plugin** (critical): An OPTIONAL attribute that specifies the name of the verification plugin that MAY be used to verify the signature e.g. “com.example.nv2plugin”. [Notation plugin](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#plugin-contract) aware implementations use this attribute to load and execute a *Notation* compliant plugin. @@ -169,7 +169,7 @@ A Notation plugin aware implementations MUST use this attribute to verify the si The plugin MUST use [Semantic Versioning](https://semver.org/) (SemVer) to use this feature i.e the `get-plugin-metadata` plugin command MUST return a SemVer compliant version in the response. A use case for this feature is for a plugin publisher to address security bug in older plugin version, by setting the minimum version to the plugin version with fixes. -See [Guidelines for implementations of the Notary Project signature specification](#guidelines-for-notary-project-signature-implementors) for options to handle these attributes during signature verification. +See [Guidelines for implementations of the Notary signature specification](#guidelines-for-notary-project-signature-implementors) for options to handle these attributes during signature verification. ### Unsigned Attributes @@ -241,8 +241,8 @@ The `keyUsage` extension MUST be present and MUST be marked critical. Bit positi - The certificate MUST NOT chain to multiple parents/roots. - The certificate chain MUST NOT contain a certificate that is unrelated to the certificate chain. 1. Any certificate in the certificate chain MUST NOT use SHA1WithRSA and ECDSAWithSHA1 signatures. -1. Only Basic Constraints, Key Usage, and Extended Key Usage extensions of X.509 certificates are honored. For rest of the extensions, implementations of the Notary Project signature specification MUST fail open i.e. rest of the extensions MUST NOT be evaluated or honored. -1. The certificates in the certificate chain MUST be valid at signing time. Implementations of the Notary Project signature specification MUST NOT enforce validity period nesting, i.e the validity period for a given certificate may not fall entirely within the validity period of that certificate's issuer certificate. +1. Only Basic Constraints, Key Usage, and Extended Key Usage extensions of X.509 certificates are honored. For rest of the extensions, implementations of the Notary signature specification MUST fail open i.e. rest of the extensions MUST NOT be evaluated or honored. +1. The certificates in the certificate chain MUST be valid at signing time. Implementations of the Notary signature specification MUST NOT enforce validity period nesting, i.e the validity period for a given certificate may not fall entirely within the validity period of that certificate's issuer certificate. 1. In the absence of an Authentic Timestamp, each and every certificate in the certificate chain i.e. signing certificate, intermediate certificates, and the root certificate must be valid i.e. not expired at the time of signature verification. ## FAQ @@ -267,7 +267,7 @@ The signing time denotes the time at which the signature was generated. A X509 c ### Expiry -This is an optional feature that provides a "best by use" time for the artifact, as defined by the signer. The Notary Project signature specification 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. +This is an optional feature that provides a "best by use" time for the artifact, as defined by the signer. The Notary signature specification 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. ### Signature Portability @@ -283,35 +283,35 @@ Signatures associated with these artifacts require broad portability. E.g. Images for containerized applications and services used within an organization, or shared with limited authorized parties. Based on user requirements a private artifact can have different levels of portability, the signature’s portability should at least match the the artifact’s portability. -*The Notary Project signature portability* is based on the following +*The Notary signature portability* is based on the following #### Signature discovery -The Notary Project signature specification addressed signature discovery by storing signatures in the same registry (location) where an artifact is present. +The Notary signature specification addressed signature discovery by storing signatures in the same registry (location) where an artifact is present. This is supported through [OCI Distribution Referrers API][oci-distribution-referrers] which allows reference artifacts such as signatures, SBOMs to be associated with existing artifacts like Images. -The Notary Project signature specification allows multiple signatures to be associated with an artifact, and clients may automatically push signatures for an artifact to a destination registry when a signed artifact moves from one registry to other. +The Notary signature specification allows multiple signatures to be associated with an artifact, and clients may automatically push signatures for an artifact to a destination registry when a signed artifact moves from one registry to other. #### Verification requirements -The Notary Project signature specification supports a range of signed artifacts intended for public and private distribution. +The Notary signature specification supports a range of signed artifacts intended for public and private distribution. Signatures generated without extended signature attributes marked critical can be verified in any environment where Notation client or another Notary Project specification compliant verification tool is available, without any additional dependencies. It should be noted that revocations checks, which usually relies on an external mechanism such as CRL/OCSP may require the verification environment to have access to local network or public internet, to have access to the CRL/OCSP endpoint. -The Notary Project signature specification also supports signatures generated using compliant signing plugins, which allow vendors to optionally provide additional features on top of Notation standard features. +The Notary signature specification also supports signatures generated using compliant signing plugins, which allow vendors to optionally provide additional features on top of Notation standard features. Verification of these signatures may require additional dependencies like Notation compliant verification plugin, making these signatures more appropriate to use where broad portability may not be required for the associated signed artifact. This allows users to implement security controls required for their organizations, that are not broadly applicable and may take time to standardize. E.g. Integration with a signature transparency log as part of signature verification. Based on user’s requirements, a user can select appropriate signing mechanism that produces signatures with desired portability. -The Notary Project signatures without any critical extended attributes do not impose any additional dependency requirements for verifiers as these can be validated with just the Notation client. -Whereas, the Notary Project signatures that contain critical extended attributes will require additional dependencies for signature validation, either on Notation compliant plugins or equivalent tooling which may not be available in all environments. +The Notary signatures without any critical extended attributes do not impose any additional dependency requirements for verifiers as these can be validated with just the Notation client. +Whereas, the Notary signatures that contain critical extended attributes will require additional dependencies for signature validation, either on Notation compliant plugins or equivalent tooling which may not be available in all environments. Similarly, Notation compliant plugin vendors should be aware that usage of extended signed attributes which are marked critical in signature will have implications on portability of the signature. -### Guidelines for implementations of the Notary Project signature specification +### Guidelines for implementations of the Notary signature specification -Implementations of the Notary Project signature specification, can choose to be [Notation plugin protocol](./plugin-extensibility.md#plugin-contract) aware or not. If an implementation chooses to be plugin protocol aware, and it encounters the Verification Plugin and Verification Plugin minimum version attributes during signature verification, it MUST process these attributes. This involves finding the appropriate plugin and the version to use, and executing `verify-signature` plugin command with correct inputs and processing the plugin response, as per the [Verification Plugin interface](./plugin-extensibility.md#verification-extensibility). +Implementations of the Notary signature specification, can choose to be [Notation plugin protocol](./plugin-extensibility.md#plugin-contract) aware or not. If an implementation chooses to be plugin protocol aware, and it encounters the Verification Plugin and Verification Plugin minimum version attributes during signature verification, it MUST process these attributes. This involves finding the appropriate plugin and the version to use, and executing `verify-signature` plugin command with correct inputs and processing the plugin response, as per the [Verification Plugin interface](./plugin-extensibility.md#verification-extensibility). -Alternatively, an implementation of the Notary Project signature specification can choose not to implement plugin protocol. +Alternatively, an implementation of the Notary signature specification can choose not to implement plugin protocol. - The implementation MUST itself perform equivalent verification logic that is usually performed by plugin specified in the signature. - An implementation MUST fail signature verification if it cannot perform the equivalent verification logic, as skipping the plugin equivalent verification logic will cause incorrect and inconsistent signature verification behavior. From 692658b7d5bdfa1b54f41b24208050cb347a5da7 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 12 Jun 2023 14:31:05 +0800 Subject: [PATCH 10/18] update to the Notary signature Signed-off-by: Yi Zha --- specs/signature-specification.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/specs/signature-specification.md b/specs/signature-specification.md index 54e82157..db1a8dcc 100644 --- a/specs/signature-specification.md +++ b/specs/signature-specification.md @@ -46,7 +46,7 @@ Signature manifest example per OCI image manifest: Besides the [image manifest property requirements][image-manifest-property-descriptions], the properties have the following additional restrictions: - **`mediaType`** (*string*): This REQUIRED property MUST be `application/vnd.oci.image.manifest.v1+json`. -- **`config`** (*descriptor*): This property is REQUIRED to be compatible with [OCI image specification][oci-image-manifest]. The Notary signature specification doesn't require any configuration for a signature, and the configuration content is not consumed by the Notary Project tooling. +- **`config`** (*descriptor*): This property is REQUIRED to be compatible with [OCI image specification][oci-image-manifest]. The Notary signature specification doesn't require any configuration for a signature, and the configuration content is not consumed by the implementations of Notary signature specification. - **`mediaType`** (*string*): This REQUIRED property MUST be `application/vnd.cncf.notary.signature`. - **`digest`** (*string*): This REQUIRED property is the digest of the config content. - **`size`** (*int64*): This REQUIRED property specifies the size, in bytes, of the raw config content. @@ -57,7 +57,7 @@ Besides the [image manifest property requirements][image-manifest-property-descr - **`subject`** (*descriptor*): A REQUIRED artifact descriptor referencing the signed manifest. - **`annotations`** (*string-string map*): This REQUIRED property contains metadata for the image manifest. It is being used to store information about the signature. - Keys using the `io.cncf.notary` namespace are reserved for use in the Notary Project and MUST NOT be used by other specifications. + Keys using the `io.cncf.notary` namespace are reserved for use in the Notary signature specification and MUST NOT be used by other specifications. - **`io.cncf.notary.x509chain.thumbprint#S256`**: A REQUIRED annotation whose value contains the list of SHA-256 fingerprints of signing certificate and certificate chain (including root) used for signature generation. The list of fingerprints is present as a JSON array string, corresponding to ordered certificates in [*Certificate Chain* unsigned attribute](#unsigned-attributes) in the signature envelope. The annotation name contains the hash algorithm as a suffix (`#S256`) and can be extended to support other hashing algorithms in future. ### Signature Discovery @@ -69,7 +69,7 @@ Each the Notary signature refers to a signature envelope blob. ### Signature Filtering -An OCI artifact can have multiple signatures, The Notary Project tooling uses annotations of the signature artifact to filter relevant signatures based on the applicable trust policy. +An OCI artifact can have multiple signatures, the implementations of Notary signature specification uses annotations of the signature manifest to filter relevant signatures based on the applicable trust policy. The Notary signature manifest's `io.cncf.notary.x509chain.thumbprint#S256` annotation key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. ## Signature Envelope @@ -135,11 +135,11 @@ Signed attributes/claims are additional metadata apart from the payload, which a - Claims that MUST be processed by a verifier MUST be marked as critical. Some claims may be optional and critical, i.e. they MUST be processed by a verifier only if they are present. - Claims which are informational and do not influence signature verification MUST NOT be marked critical. -The Notary Project requires the signature envelope to support the following signed attributes/claims. +The Notary signature specification requires the signature envelope to support the following signed attributes/claims. #### Standard attributes -- **Signing Scheme** (critical): A REQUIRED claim that defines the [Notary Project Signing Scheme](./signing-scheme.md) used by the signature. This attribute dictates the rest of signature schema - the set of signed and unsigned attributes to be included in the signature. Supported values are `notary.x509` and `notary.x509.signingAuthority`. +- **Signing Scheme** (critical): A REQUIRED claim that defines the [Notary Signing Scheme](./signing-scheme.md) used by the signature. This attribute dictates the rest of signature schema - the set of signed and unsigned attributes to be included in the signature. Supported values are `notary.x509` and `notary.x509.signingAuthority`. - **Signing Time**: A claim that indicates the time at which the signature was generated. Though this claim is signed by the signing key, it’s considered unauthenticated as a signer can modify local time and manipulate this claim. More details [here](#signing-time). This claim is REQUIRED and only valid when signing scheme is `notary.x509` . - **Authentic Signing Time** (critical): The authenticated time at which the signature was generated. This claim is REQUIRED and only valid when signing scheme is `notary.x509.signingAuthority` . More details [here](#signing-time). - **Expiry** (critical): An OPTIONAL claim that provides a “best by use” time for the artifact, as defined by the signer. More details [here](#expiry). @@ -247,12 +247,12 @@ The `keyUsage` extension MUST be present and MUST be marked critical. Bit positi ## FAQ -**Q: How will the Notary Project specification support multiple signature envelope formats?** +**Q: How will the Notary signature specification support multiple signature envelope formats?** **A:** The `mediaType` of image manifest's layer identifies the signature envelope type. The client implementation can use the aforementioned `mediaType` to parse the signature envelope. -**Q: How will the Notary Project specification support multiple payload formats?** +**Q: How will the Notary signature specification support multiple payload formats?** **A:** The Signature envelope MUST have a versioning mechanism to support multiple payload formats. @@ -294,7 +294,7 @@ The Notary signature specification allows multiple signatures to be associated w #### Verification requirements The Notary signature specification supports a range of signed artifacts intended for public and private distribution. -Signatures generated without extended signature attributes marked critical can be verified in any environment where Notation client or another Notary Project specification compliant verification tool is available, without any additional dependencies. +Signatures generated without extended signature attributes marked critical can be verified in any environment where Notation client or another Notary signature specification compliant verification tool is available, without any additional dependencies. It should be noted that revocations checks, which usually relies on an external mechanism such as CRL/OCSP may require the verification environment to have access to local network or public internet, to have access to the CRL/OCSP endpoint. The Notary signature specification also supports signatures generated using compliant signing plugins, which allow vendors to optionally provide additional features on top of Notation standard features. From 891f6fb5045be66a7bc93606108c77b10a116429 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Tue, 13 Jun 2023 16:31:52 +0800 Subject: [PATCH 11/18] update per comments Signed-off-by: Yi Zha --- specs/signature-specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/signature-specification.md b/specs/signature-specification.md index db1a8dcc..c526ac68 100644 --- a/specs/signature-specification.md +++ b/specs/signature-specification.md @@ -7,7 +7,7 @@ This document provides the following details for the Notary signature: ## Storage -This section describes how the Notary signature are stored in the OCI Distribution conformant registry. +This section describes how a Notary signature is stored in an OCI Distribution conformant registry. OCI image manifest is used to store signatures in the registry, see [OCI image spec v1.1.0-rc3][oci-image-manifest] for details. The signature manifest has a configuration media type that specifies it's the Notary signature, a subject referencing the manifest of the artifact being signed, a layer referencing the signature, and a collection of annotations. From 198e2b1a7bf2403df326b10644bd28cbc5e679cd Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 22 Jun 2023 10:25:45 +0800 Subject: [PATCH 12/18] change Notary signature to Notary Project signature Signed-off-by: Yi Zha --- specs/signature-specification.md | 72 ++++++++++++++++---------------- 1 file changed, 36 insertions(+), 36 deletions(-) diff --git a/specs/signature-specification.md b/specs/signature-specification.md index c526ac68..1c573d96 100644 --- a/specs/signature-specification.md +++ b/specs/signature-specification.md @@ -1,15 +1,15 @@ # Signature Specification -This document provides the following details for the Notary signature: +This document provides the following details for the Notary Project signature: - **[Storage](#storage)**: Describes how signatures are stored and retrieved from an OCI registry. -- **[Signature Envelope](#signature-envelope)**: Describes the structure of the Notary signature. +- **[Signature Envelope](#signature-envelope)**: Describes the structure of the Notary Project signature. ## Storage -This section describes how a Notary signature is stored in an OCI Distribution conformant registry. +This section describes how a Notary Project signature is stored in an OCI Distribution conformant registry. OCI image manifest is used to store signatures in the registry, see [OCI image spec v1.1.0-rc3][oci-image-manifest] for details. -The signature manifest has a configuration media type that specifies it's the Notary signature, a subject referencing the manifest of the artifact being signed, a layer referencing the signature, and a collection of annotations. +The signature manifest has a configuration media type that specifies it's the Notary Project signature, a subject referencing the manifest of the artifact being signed, a layer referencing the signature, and a collection of annotations. ![Signature storage inside registry](../media/signature-specification.svg) @@ -46,7 +46,7 @@ Signature manifest example per OCI image manifest: Besides the [image manifest property requirements][image-manifest-property-descriptions], the properties have the following additional restrictions: - **`mediaType`** (*string*): This REQUIRED property MUST be `application/vnd.oci.image.manifest.v1+json`. -- **`config`** (*descriptor*): This property is REQUIRED to be compatible with [OCI image specification][oci-image-manifest]. The Notary signature specification doesn't require any configuration for a signature, and the configuration content is not consumed by the implementations of Notary signature specification. +- **`config`** (*descriptor*): This property is REQUIRED to be compatible with [OCI image specification][oci-image-manifest]. The Notary Project signature specification doesn't require any configuration for a signature, and the configuration content is not consumed by implementations of the Notary Project signature specification. - **`mediaType`** (*string*): This REQUIRED property MUST be `application/vnd.cncf.notary.signature`. - **`digest`** (*string*): This REQUIRED property is the digest of the config content. - **`size`** (*int64*): This REQUIRED property specifies the size, in bytes, of the raw config content. @@ -57,20 +57,20 @@ Besides the [image manifest property requirements][image-manifest-property-descr - **`subject`** (*descriptor*): A REQUIRED artifact descriptor referencing the signed manifest. - **`annotations`** (*string-string map*): This REQUIRED property contains metadata for the image manifest. It is being used to store information about the signature. - Keys using the `io.cncf.notary` namespace are reserved for use in the Notary signature specification and MUST NOT be used by other specifications. + Keys using the `io.cncf.notary` namespace are reserved for use in the Notary Project signature specification and MUST NOT be used by other specifications. - **`io.cncf.notary.x509chain.thumbprint#S256`**: A REQUIRED annotation whose value contains the list of SHA-256 fingerprints of signing certificate and certificate chain (including root) used for signature generation. The list of fingerprints is present as a JSON array string, corresponding to ordered certificates in [*Certificate Chain* unsigned attribute](#unsigned-attributes) in the signature envelope. The annotation name contains the hash algorithm as a suffix (`#S256`) and can be extended to support other hashing algorithms in future. ### Signature Discovery The client should be able to discover all the signatures belonging to an artifact (such as image manifest) by using [OCI Distribution Referrers API][oci-distribution-referrers]. OCI Distribution Referrers API returns a paginated list of all artifacts belonging to a target artifact (such as container images, SBoMs). -The implementation can filter the Notary signatures by either using OCI Distribution Referrers API or using custom logic on the client. -Each the Notary signature refers to a signature envelope blob. +The implementation can filter the Notary Project signatures by either using OCI Distribution Referrers API or using custom logic on the client. +Each Notary Project signature refers to a signature envelope blob. ### Signature Filtering -An OCI artifact can have multiple signatures, the implementations of Notary signature specification uses annotations of the signature manifest to filter relevant signatures based on the applicable trust policy. -The Notary signature manifest's `io.cncf.notary.x509chain.thumbprint#S256` annotation key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. +An OCI artifact can have multiple signatures, implementations of the Notary Project signature specification uses annotations of the signature manifest to filter relevant signatures based on the applicable trust policy. +The Notary Project signature manifest's `io.cncf.notary.x509chain.thumbprint#S256` annotation key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. ## Signature Envelope @@ -84,20 +84,20 @@ A signature envelope consists of the following components: A signature envelope is `e = {m, v, u, s}` where `s` is signature. -This specification defines the set of signed and unsigned attributes that make up a valid Notary signature. This specification aims to be be agnostic of signature envelope format (e.g. COSE, JWS), details of encoding the envelope in a specific signature envelope format are covered in in separate specs. +This specification defines the set of signed and unsigned attributes that make up a valid Notary Project signature. This specification aims to be be agnostic of signature envelope format (e.g. COSE, JWS), details of encoding the envelope in a specific signature envelope format are covered in in separate specs. -The Notary signature supports the following envelope formats: +The Notary Project signature supports the following envelope formats: - [JWS](./signature-envelope-jws.md) - [COSE](./signature-envelope-cose.md) ### Payload -The Notary signature payload is a JSON document with media type `application/vnd.cncf.notary.payload.v1+json` and has following properties. +The Notary Project signature payload is a JSON document with media type `application/vnd.cncf.notary.payload.v1+json` and has following properties. - `targetArtifact` : Required property whose value is the descriptor of the target artifact manifest that is being signed. Only [OCI descriptor][oci-descriptor] is supported. - Descriptor MUST contain `mediaType`, `digest`, `size` fields. - - Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules][annotation-rules]. The Notary signature uses annotations for storing both Notary specific and user defined metadata. The prefix `io.cncf.notary` in annotation keys is reserved for use in the Notary signature and MUST NOT be used outside this specification. + - Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules][annotation-rules]. The Notary Project signature uses annotations for storing both the Notary Project specific and user defined metadata. The prefix `io.cncf.notary` in annotation keys is reserved for use in the Notary Project signature and MUST NOT be used outside this specification. - Descriptor MAY contain `artifactType` field for the `config.mediaType` of OCI image based manifests. #### Examples @@ -135,11 +135,11 @@ Signed attributes/claims are additional metadata apart from the payload, which a - Claims that MUST be processed by a verifier MUST be marked as critical. Some claims may be optional and critical, i.e. they MUST be processed by a verifier only if they are present. - Claims which are informational and do not influence signature verification MUST NOT be marked critical. -The Notary signature specification requires the signature envelope to support the following signed attributes/claims. +The Notary Project signature specification requires the signature envelope to support the following signed attributes/claims. #### Standard attributes -- **Signing Scheme** (critical): A REQUIRED claim that defines the [Notary Signing Scheme](./signing-scheme.md) used by the signature. This attribute dictates the rest of signature schema - the set of signed and unsigned attributes to be included in the signature. Supported values are `notary.x509` and `notary.x509.signingAuthority`. +- **Signing Scheme** (critical): A REQUIRED claim that defines the [Notary Project Signing Scheme](./signing-scheme.md) used by the signature. This attribute dictates the rest of signature schema - the set of signed and unsigned attributes to be included in the signature. Supported values are `notary.x509` and `notary.x509.signingAuthority`. - **Signing Time**: A claim that indicates the time at which the signature was generated. Though this claim is signed by the signing key, it’s considered unauthenticated as a signer can modify local time and manipulate this claim. More details [here](#signing-time). This claim is REQUIRED and only valid when signing scheme is `notary.x509` . - **Authentic Signing Time** (critical): The authenticated time at which the signature was generated. This claim is REQUIRED and only valid when signing scheme is `notary.x509.signingAuthority` . More details [here](#signing-time). - **Expiry** (critical): An OPTIONAL claim that provides a “best by use” time for the artifact, as defined by the signer. More details [here](#expiry). @@ -147,19 +147,19 @@ The Notary signature specification requires the signature envelope to support th #### Extended attributes -Implementations of the Notary signature spec MAY include additional signed attributes in the signature envelope. +Implementations of the Notary Project signature specification MAY include additional signed attributes in the signature envelope. These attributes MAY be marked critical, i.e. the attribute MUST be understood and processed by a verifier, unknown critical attributes MUST cause signature verification to fail. Usage of extended signed attributes which are marked critical in signature will have implications on portability of the signature, these are discussed in [Signature Portability](#signature-portability) section. #### Extended attributes for *Notation* Plugins -Notation is a CLI and has set of libraries that offer an implementation of the Notary signature specification. Notation allows you to sign artifacts as well as verify artifacts against the Notary signatures. +Notation is a CLI and has set of libraries that offer an implementation of the Notary Project signature specification. Notation allows you to sign artifacts as well as verify artifacts against the Notary Project signatures. This section documents extended attributes used by Notation to support plugins. Plugins is a *Notation* concept that allows parts of signing and verification logic to be performed by an external provider. *Signing plugins* allow *Notation* to be extended for integration with remote keys remote key management services and signing services, where as *verification plugins* allow for customization of verification logic. Detailed specification for plugins can be found [here](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#notation-extensibility-for-signing-and-verification). -These extended attributes are documented in this spec, as other implementations of the Notary signature specification may encounter these attributes if they verify a signature that indicated it required a verification plugin for complete signature verification. +These extended attributes are documented in this spec, as other implementations of the Notary Project signature specification may encounter these attributes if they verify a signature that indicated it required a verification plugin for complete signature verification. - **Verification Plugin** (critical): An OPTIONAL attribute that specifies the name of the verification plugin that MAY be used to verify the signature e.g. “com.example.nv2plugin”. [Notation plugin](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#plugin-contract) aware implementations use this attribute to load and execute a *Notation* compliant plugin. @@ -169,7 +169,7 @@ A Notation plugin aware implementations MUST use this attribute to verify the si The plugin MUST use [Semantic Versioning](https://semver.org/) (SemVer) to use this feature i.e the `get-plugin-metadata` plugin command MUST return a SemVer compliant version in the response. A use case for this feature is for a plugin publisher to address security bug in older plugin version, by setting the minimum version to the plugin version with fixes. -See [Guidelines for implementations of the Notary signature specification](#guidelines-for-notary-project-signature-implementors) for options to handle these attributes during signature verification. +See [Guidelines for implementations of the Notary Project signature specification](#guidelines-for-notary-project-signature-implementors) for options to handle these attributes during signature verification. ### Unsigned Attributes @@ -241,18 +241,18 @@ The `keyUsage` extension MUST be present and MUST be marked critical. Bit positi - The certificate MUST NOT chain to multiple parents/roots. - The certificate chain MUST NOT contain a certificate that is unrelated to the certificate chain. 1. Any certificate in the certificate chain MUST NOT use SHA1WithRSA and ECDSAWithSHA1 signatures. -1. Only Basic Constraints, Key Usage, and Extended Key Usage extensions of X.509 certificates are honored. For rest of the extensions, implementations of the Notary signature specification MUST fail open i.e. rest of the extensions MUST NOT be evaluated or honored. -1. The certificates in the certificate chain MUST be valid at signing time. Implementations of the Notary signature specification MUST NOT enforce validity period nesting, i.e the validity period for a given certificate may not fall entirely within the validity period of that certificate's issuer certificate. +1. Only Basic Constraints, Key Usage, and Extended Key Usage extensions of X.509 certificates are honored. For rest of the extensions, implementations of the Notary Project signature specification MUST fail open i.e. rest of the extensions MUST NOT be evaluated or honored. +1. The certificates in the certificate chain MUST be valid at signing time. Implementations of the Notary Project signature specification MUST NOT enforce validity period nesting, i.e the validity period for a given certificate may not fall entirely within the validity period of that certificate's issuer certificate. 1. In the absence of an Authentic Timestamp, each and every certificate in the certificate chain i.e. signing certificate, intermediate certificates, and the root certificate must be valid i.e. not expired at the time of signature verification. ## FAQ -**Q: How will the Notary signature specification support multiple signature envelope formats?** +**Q: How will the Notary Project signature specification support multiple signature envelope formats?** **A:** The `mediaType` of image manifest's layer identifies the signature envelope type. The client implementation can use the aforementioned `mediaType` to parse the signature envelope. -**Q: How will the Notary signature specification support multiple payload formats?** +**Q: How will the Notary Project signature specification support multiple payload formats?** **A:** The Signature envelope MUST have a versioning mechanism to support multiple payload formats. @@ -267,7 +267,7 @@ The signing time denotes the time at which the signature was generated. A X509 c ### Expiry -This is an optional feature that provides a "best by use" time for the artifact, as defined by the signer. The Notary signature specification 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. +This is an optional feature that provides a "best by use" time for the artifact, as defined by the signer. The Notary Project signature specification 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. ### Signature Portability @@ -283,35 +283,35 @@ Signatures associated with these artifacts require broad portability. E.g. Images for containerized applications and services used within an organization, or shared with limited authorized parties. Based on user requirements a private artifact can have different levels of portability, the signature’s portability should at least match the the artifact’s portability. -*The Notary signature portability* is based on the following +*The Notary Project signature portability* is based on the following #### Signature discovery -The Notary signature specification addressed signature discovery by storing signatures in the same registry (location) where an artifact is present. +The Notary Project signature specification addressed signature discovery by storing signatures in the same registry (location) where an artifact is present. This is supported through [OCI Distribution Referrers API][oci-distribution-referrers] which allows reference artifacts such as signatures, SBOMs to be associated with existing artifacts like Images. -The Notary signature specification allows multiple signatures to be associated with an artifact, and clients may automatically push signatures for an artifact to a destination registry when a signed artifact moves from one registry to other. +The Notary Project signature specification allows multiple signatures to be associated with an artifact, and clients may automatically push signatures for an artifact to a destination registry when a signed artifact moves from one registry to other. #### Verification requirements -The Notary signature specification supports a range of signed artifacts intended for public and private distribution. -Signatures generated without extended signature attributes marked critical can be verified in any environment where Notation client or another Notary signature specification compliant verification tool is available, without any additional dependencies. +The Notary Project signature specification supports a range of signed artifacts intended for public and private distribution. +Signatures generated without extended signature attributes marked critical can be verified in any environment where Notation client or another Notary Project signature specification compliant verification tool is available, without any additional dependencies. It should be noted that revocations checks, which usually relies on an external mechanism such as CRL/OCSP may require the verification environment to have access to local network or public internet, to have access to the CRL/OCSP endpoint. -The Notary signature specification also supports signatures generated using compliant signing plugins, which allow vendors to optionally provide additional features on top of Notation standard features. +The Notary Project signature specification also supports signatures generated using compliant signing plugins, which allow vendors to optionally provide additional features on top of Notation standard features. Verification of these signatures may require additional dependencies like Notation compliant verification plugin, making these signatures more appropriate to use where broad portability may not be required for the associated signed artifact. This allows users to implement security controls required for their organizations, that are not broadly applicable and may take time to standardize. E.g. Integration with a signature transparency log as part of signature verification. Based on user’s requirements, a user can select appropriate signing mechanism that produces signatures with desired portability. -The Notary signatures without any critical extended attributes do not impose any additional dependency requirements for verifiers as these can be validated with just the Notation client. -Whereas, the Notary signatures that contain critical extended attributes will require additional dependencies for signature validation, either on Notation compliant plugins or equivalent tooling which may not be available in all environments. +The Notary Project signatures without any critical extended attributes do not impose any additional dependency requirements for verifiers as these can be validated with just the Notation client. +Whereas, the Notary Project signatures that contain critical extended attributes will require additional dependencies for signature validation, either on Notation compliant plugins or equivalent tooling which may not be available in all environments. Similarly, Notation compliant plugin vendors should be aware that usage of extended signed attributes which are marked critical in signature will have implications on portability of the signature. -### Guidelines for implementations of the Notary signature specification +### Guidelines for implementations of the Notary Project signature specification -Implementations of the Notary signature specification, can choose to be [Notation plugin protocol](./plugin-extensibility.md#plugin-contract) aware or not. If an implementation chooses to be plugin protocol aware, and it encounters the Verification Plugin and Verification Plugin minimum version attributes during signature verification, it MUST process these attributes. This involves finding the appropriate plugin and the version to use, and executing `verify-signature` plugin command with correct inputs and processing the plugin response, as per the [Verification Plugin interface](./plugin-extensibility.md#verification-extensibility). +Implementations of the Notary Project signature specification, can choose to be [Notation plugin protocol](./plugin-extensibility.md#plugin-contract) aware or not. If an implementation chooses to be plugin protocol aware, and it encounters the Verification Plugin and Verification Plugin minimum version attributes during signature verification, it MUST process these attributes. This involves finding the appropriate plugin and the version to use, and executing `verify-signature` plugin command with correct inputs and processing the plugin response, as per the [Verification Plugin interface](./plugin-extensibility.md#verification-extensibility). -Alternatively, an implementation of the Notary signature specification can choose not to implement plugin protocol. +Alternatively, an implementation of the Notary Project signature specification can choose not to implement plugin protocol. - The implementation MUST itself perform equivalent verification logic that is usually performed by plugin specified in the signature. - An implementation MUST fail signature verification if it cannot perform the equivalent verification logic, as skipping the plugin equivalent verification logic will cause incorrect and inconsistent signature verification behavior. From 838eaeae9c8e62664e24f044ad4400e0bf166cd2 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 20 Jul 2023 22:21:53 +0800 Subject: [PATCH 13/18] update per comments Signed-off-by: Yi Zha --- specs/signature-specification.md | 46 ++++++++++++++++---------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/specs/signature-specification.md b/specs/signature-specification.md index 1c573d96..3f3d1141 100644 --- a/specs/signature-specification.md +++ b/specs/signature-specification.md @@ -1,6 +1,6 @@ # Signature Specification -This document provides the following details for the Notary Project signature: +This document provides the following details for Notary Project signature: - **[Storage](#storage)**: Describes how signatures are stored and retrieved from an OCI registry. - **[Signature Envelope](#signature-envelope)**: Describes the structure of the Notary Project signature. @@ -9,7 +9,7 @@ This document provides the following details for the Notary Project signature: This section describes how a Notary Project signature is stored in an OCI Distribution conformant registry. OCI image manifest is used to store signatures in the registry, see [OCI image spec v1.1.0-rc3][oci-image-manifest] for details. -The signature manifest has a configuration media type that specifies it's the Notary Project signature, a subject referencing the manifest of the artifact being signed, a layer referencing the signature, and a collection of annotations. +The signature manifest has a configuration media type that specifies it's a Notary Project signature, a subject referencing the manifest of the artifact being signed, a layer referencing the signature, and a collection of annotations. ![Signature storage inside registry](../media/signature-specification.svg) @@ -46,7 +46,7 @@ Signature manifest example per OCI image manifest: Besides the [image manifest property requirements][image-manifest-property-descriptions], the properties have the following additional restrictions: - **`mediaType`** (*string*): This REQUIRED property MUST be `application/vnd.oci.image.manifest.v1+json`. -- **`config`** (*descriptor*): This property is REQUIRED to be compatible with [OCI image specification][oci-image-manifest]. The Notary Project signature specification doesn't require any configuration for a signature, and the configuration content is not consumed by implementations of the Notary Project signature specification. +- **`config`** (*descriptor*): This property is REQUIRED to be compatible with [OCI image specification][oci-image-manifest]. The Notary Project signature specification doesn't require any configuration for a signature, and the configuration content is not consumed by implementations of Notary Project signature specification. - **`mediaType`** (*string*): This REQUIRED property MUST be `application/vnd.cncf.notary.signature`. - **`digest`** (*string*): This REQUIRED property is the digest of the config content. - **`size`** (*int64*): This REQUIRED property specifies the size, in bytes, of the raw config content. @@ -57,19 +57,19 @@ Besides the [image manifest property requirements][image-manifest-property-descr - **`subject`** (*descriptor*): A REQUIRED artifact descriptor referencing the signed manifest. - **`annotations`** (*string-string map*): This REQUIRED property contains metadata for the image manifest. It is being used to store information about the signature. - Keys using the `io.cncf.notary` namespace are reserved for use in the Notary Project signature specification and MUST NOT be used by other specifications. + Keys using the `io.cncf.notary` namespace are reserved for use in Notary Project signature specification and MUST NOT be used by other specifications. - **`io.cncf.notary.x509chain.thumbprint#S256`**: A REQUIRED annotation whose value contains the list of SHA-256 fingerprints of signing certificate and certificate chain (including root) used for signature generation. The list of fingerprints is present as a JSON array string, corresponding to ordered certificates in [*Certificate Chain* unsigned attribute](#unsigned-attributes) in the signature envelope. The annotation name contains the hash algorithm as a suffix (`#S256`) and can be extended to support other hashing algorithms in future. ### Signature Discovery The client should be able to discover all the signatures belonging to an artifact (such as image manifest) by using [OCI Distribution Referrers API][oci-distribution-referrers]. OCI Distribution Referrers API returns a paginated list of all artifacts belonging to a target artifact (such as container images, SBoMs). -The implementation can filter the Notary Project signatures by either using OCI Distribution Referrers API or using custom logic on the client. +The implementation can filter Notary Project signatures by either using OCI Distribution Referrers API or using custom logic on the client. Each Notary Project signature refers to a signature envelope blob. ### Signature Filtering -An OCI artifact can have multiple signatures, implementations of the Notary Project signature specification uses annotations of the signature manifest to filter relevant signatures based on the applicable trust policy. +An OCI artifact can have multiple signatures, implementations of Notary Project signature specification uses annotations of the signature manifest to filter relevant signatures based on the applicable trust policy. The Notary Project signature manifest's `io.cncf.notary.x509chain.thumbprint#S256` annotation key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. ## Signature Envelope @@ -96,8 +96,8 @@ The Notary Project signature supports the following envelope formats: The Notary Project signature payload is a JSON document with media type `application/vnd.cncf.notary.payload.v1+json` and has following properties. - `targetArtifact` : Required property whose value is the descriptor of the target artifact manifest that is being signed. Only [OCI descriptor][oci-descriptor] is supported. - - Descriptor MUST contain `mediaType`, `digest`, `size` fields. - - Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules][annotation-rules]. The Notary Project signature uses annotations for storing both the Notary Project specific and user defined metadata. The prefix `io.cncf.notary` in annotation keys is reserved for use in the Notary Project signature and MUST NOT be used outside this specification. + - Descriptor MUST contain `mediaType`, `digest`, and `size` fields. + - Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules][annotation-rules]. The Notary Project signature uses annotations for storing both Notary Project specific and user defined metadata. The prefix `io.cncf.notary` in annotation keys is reserved for use in Notary Project signature and MUST NOT be used outside this specification. - Descriptor MAY contain `artifactType` field for the `config.mediaType` of OCI image based manifests. #### Examples @@ -147,19 +147,19 @@ The Notary Project signature specification requires the signature envelope to su #### Extended attributes -Implementations of the Notary Project signature specification MAY include additional signed attributes in the signature envelope. +Implementations of Notary Project signature specification MAY include additional signed attributes in the signature envelope. These attributes MAY be marked critical, i.e. the attribute MUST be understood and processed by a verifier, unknown critical attributes MUST cause signature verification to fail. Usage of extended signed attributes which are marked critical in signature will have implications on portability of the signature, these are discussed in [Signature Portability](#signature-portability) section. #### Extended attributes for *Notation* Plugins -Notation is a CLI and has set of libraries that offer an implementation of the Notary Project signature specification. Notation allows you to sign artifacts as well as verify artifacts against the Notary Project signatures. +[Notation](https://github.com/notaryproject/notation) is a CLI and has set of libraries that offer an implementation of Notary Project signature specification. Notation allows you to sign artifacts as well as verify artifacts against Notary Project signatures. This section documents extended attributes used by Notation to support plugins. Plugins is a *Notation* concept that allows parts of signing and verification logic to be performed by an external provider. -*Signing plugins* allow *Notation* to be extended for integration with remote keys remote key management services and signing services, where as *verification plugins* allow for customization of verification logic. +*Signing plugins* allow *Notation* to be extended for integration with remote keys, remote key management services, and signing services, where as *verification plugins* allow for customization of verification logic. Detailed specification for plugins can be found [here](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#notation-extensibility-for-signing-and-verification). -These extended attributes are documented in this spec, as other implementations of the Notary Project signature specification may encounter these attributes if they verify a signature that indicated it required a verification plugin for complete signature verification. +These extended attributes are documented in this spec, as other implementations of Notary Project signature specification may encounter these attributes if they verify a signature that indicated it required a verification plugin for complete signature verification. - **Verification Plugin** (critical): An OPTIONAL attribute that specifies the name of the verification plugin that MAY be used to verify the signature e.g. “com.example.nv2plugin”. [Notation plugin](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#plugin-contract) aware implementations use this attribute to load and execute a *Notation* compliant plugin. @@ -169,7 +169,7 @@ A Notation plugin aware implementations MUST use this attribute to verify the si The plugin MUST use [Semantic Versioning](https://semver.org/) (SemVer) to use this feature i.e the `get-plugin-metadata` plugin command MUST return a SemVer compliant version in the response. A use case for this feature is for a plugin publisher to address security bug in older plugin version, by setting the minimum version to the plugin version with fixes. -See [Guidelines for implementations of the Notary Project signature specification](#guidelines-for-notary-project-signature-implementors) for options to handle these attributes during signature verification. +See [Guidelines for implementations of Notary Project signature specification](#guidelines-for-notary-project-signature-implementors) for options to handle these attributes during signature verification. ### Unsigned Attributes @@ -241,18 +241,18 @@ The `keyUsage` extension MUST be present and MUST be marked critical. Bit positi - The certificate MUST NOT chain to multiple parents/roots. - The certificate chain MUST NOT contain a certificate that is unrelated to the certificate chain. 1. Any certificate in the certificate chain MUST NOT use SHA1WithRSA and ECDSAWithSHA1 signatures. -1. Only Basic Constraints, Key Usage, and Extended Key Usage extensions of X.509 certificates are honored. For rest of the extensions, implementations of the Notary Project signature specification MUST fail open i.e. rest of the extensions MUST NOT be evaluated or honored. -1. The certificates in the certificate chain MUST be valid at signing time. Implementations of the Notary Project signature specification MUST NOT enforce validity period nesting, i.e the validity period for a given certificate may not fall entirely within the validity period of that certificate's issuer certificate. -1. In the absence of an Authentic Timestamp, each and every certificate in the certificate chain i.e. signing certificate, intermediate certificates, and the root certificate must be valid i.e. not expired at the time of signature verification. +2. Only Basic Constraints, Key Usage, and Extended Key Usage extensions of X.509 certificates are honored. For rest of the extensions, implementations of Notary Project signature specification MUST fail open i.e. rest of the extensions MUST NOT be evaluated or honored. +3. The certificates in the certificate chain MUST be valid at signing time. Implementations of Notary Project signature specification MUST NOT enforce validity period nesting, i.e the validity period for a given certificate may not fall entirely within the validity period of that certificate's issuer certificate. +4. In the absence of an Authentic Timestamp, each and every certificate in the certificate chain i.e. signing certificate, intermediate certificates, and the root certificate must be valid i.e. not expired at the time of signature verification. ## FAQ -**Q: How will the Notary Project signature specification support multiple signature envelope formats?** +**Q: How will Notary Project signature specification support multiple signature envelope formats?** **A:** The `mediaType` of image manifest's layer identifies the signature envelope type. The client implementation can use the aforementioned `mediaType` to parse the signature envelope. -**Q: How will the Notary Project signature specification support multiple payload formats?** +**Q: How will Notary Project signature specification support multiple payload formats?** **A:** The Signature envelope MUST have a versioning mechanism to support multiple payload formats. @@ -294,7 +294,7 @@ The Notary Project signature specification allows multiple signatures to be asso #### Verification requirements The Notary Project signature specification supports a range of signed artifacts intended for public and private distribution. -Signatures generated without extended signature attributes marked critical can be verified in any environment where Notation client or another Notary Project signature specification compliant verification tool is available, without any additional dependencies. +Signatures generated without extended signature attributes marked critical can be verified in any environment where Notation or another Notary Project signature specification compliant verification tool is available, without any additional dependencies. It should be noted that revocations checks, which usually relies on an external mechanism such as CRL/OCSP may require the verification environment to have access to local network or public internet, to have access to the CRL/OCSP endpoint. The Notary Project signature specification also supports signatures generated using compliant signing plugins, which allow vendors to optionally provide additional features on top of Notation standard features. @@ -303,15 +303,15 @@ This allows users to implement security controls required for their organization E.g. Integration with a signature transparency log as part of signature verification. Based on user’s requirements, a user can select appropriate signing mechanism that produces signatures with desired portability. -The Notary Project signatures without any critical extended attributes do not impose any additional dependency requirements for verifiers as these can be validated with just the Notation client. +The Notary Project signatures without any critical extended attributes do not impose any additional dependency requirements for verifiers as these can be validated with just Notation. Whereas, the Notary Project signatures that contain critical extended attributes will require additional dependencies for signature validation, either on Notation compliant plugins or equivalent tooling which may not be available in all environments. Similarly, Notation compliant plugin vendors should be aware that usage of extended signed attributes which are marked critical in signature will have implications on portability of the signature. -### Guidelines for implementations of the Notary Project signature specification +### Guidelines for implementations of Notary Project signature specification -Implementations of the Notary Project signature specification, can choose to be [Notation plugin protocol](./plugin-extensibility.md#plugin-contract) aware or not. If an implementation chooses to be plugin protocol aware, and it encounters the Verification Plugin and Verification Plugin minimum version attributes during signature verification, it MUST process these attributes. This involves finding the appropriate plugin and the version to use, and executing `verify-signature` plugin command with correct inputs and processing the plugin response, as per the [Verification Plugin interface](./plugin-extensibility.md#verification-extensibility). +Implementations of Notary Project signature specification, can choose to be [Notation plugin protocol](./plugin-extensibility.md#plugin-contract) aware or not. If an implementation chooses to be plugin protocol aware, and it encounters the Verification Plugin and Verification Plugin minimum version attributes during signature verification, it MUST process these attributes. This involves finding the appropriate plugin and the version to use, and executing `verify-signature` plugin command with correct inputs and processing the plugin response, as per the [Verification Plugin interface](./plugin-extensibility.md#verification-extensibility). -Alternatively, an implementation of the Notary Project signature specification can choose not to implement plugin protocol. +Alternatively, an implementation of Notary Project signature specification can choose not to implement plugin protocol. - The implementation MUST itself perform equivalent verification logic that is usually performed by plugin specified in the signature. - An implementation MUST fail signature verification if it cannot perform the equivalent verification logic, as skipping the plugin equivalent verification logic will cause incorrect and inconsistent signature verification behavior. From d32dcfa2ad18fc068113048299aadd1a0871dde3 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Thu, 20 Jul 2023 22:27:57 +0800 Subject: [PATCH 14/18] update per comments Signed-off-by: Yi Zha --- specs/signature-specification.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/specs/signature-specification.md b/specs/signature-specification.md index 3f3d1141..d607943f 100644 --- a/specs/signature-specification.md +++ b/specs/signature-specification.md @@ -46,7 +46,7 @@ Signature manifest example per OCI image manifest: Besides the [image manifest property requirements][image-manifest-property-descriptions], the properties have the following additional restrictions: - **`mediaType`** (*string*): This REQUIRED property MUST be `application/vnd.oci.image.manifest.v1+json`. -- **`config`** (*descriptor*): This property is REQUIRED to be compatible with [OCI image specification][oci-image-manifest]. The Notary Project signature specification doesn't require any configuration for a signature, and the configuration content is not consumed by implementations of Notary Project signature specification. +- **`config`** (*descriptor*): This property is REQUIRED to be compatible with [OCI image specification][oci-image-manifest]. The Notary Project signature specification doesn't require any configuration for a signature, and the configuration content is not consumed by implementations of the Notary Project signature specification. - **`mediaType`** (*string*): This REQUIRED property MUST be `application/vnd.cncf.notary.signature`. - **`digest`** (*string*): This REQUIRED property is the digest of the config content. - **`size`** (*int64*): This REQUIRED property specifies the size, in bytes, of the raw config content. @@ -57,7 +57,7 @@ Besides the [image manifest property requirements][image-manifest-property-descr - **`subject`** (*descriptor*): A REQUIRED artifact descriptor referencing the signed manifest. - **`annotations`** (*string-string map*): This REQUIRED property contains metadata for the image manifest. It is being used to store information about the signature. - Keys using the `io.cncf.notary` namespace are reserved for use in Notary Project signature specification and MUST NOT be used by other specifications. + Keys using the `io.cncf.notary` namespace are reserved for use in the Notary Project signature specification and MUST NOT be used by other specifications. - **`io.cncf.notary.x509chain.thumbprint#S256`**: A REQUIRED annotation whose value contains the list of SHA-256 fingerprints of signing certificate and certificate chain (including root) used for signature generation. The list of fingerprints is present as a JSON array string, corresponding to ordered certificates in [*Certificate Chain* unsigned attribute](#unsigned-attributes) in the signature envelope. The annotation name contains the hash algorithm as a suffix (`#S256`) and can be extended to support other hashing algorithms in future. ### Signature Discovery @@ -69,7 +69,7 @@ Each Notary Project signature refers to a signature envelope blob. ### Signature Filtering -An OCI artifact can have multiple signatures, implementations of Notary Project signature specification uses annotations of the signature manifest to filter relevant signatures based on the applicable trust policy. +An OCI artifact can have multiple signatures, implementations of the Notary Project signature specification uses annotations of the signature manifest to filter relevant signatures based on the applicable trust policy. The Notary Project signature manifest's `io.cncf.notary.x509chain.thumbprint#S256` annotation key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. ## Signature Envelope @@ -147,19 +147,19 @@ The Notary Project signature specification requires the signature envelope to su #### Extended attributes -Implementations of Notary Project signature specification MAY include additional signed attributes in the signature envelope. +Implementations of the Notary Project signature specification MAY include additional signed attributes in the signature envelope. These attributes MAY be marked critical, i.e. the attribute MUST be understood and processed by a verifier, unknown critical attributes MUST cause signature verification to fail. Usage of extended signed attributes which are marked critical in signature will have implications on portability of the signature, these are discussed in [Signature Portability](#signature-portability) section. #### Extended attributes for *Notation* Plugins -[Notation](https://github.com/notaryproject/notation) is a CLI and has set of libraries that offer an implementation of Notary Project signature specification. Notation allows you to sign artifacts as well as verify artifacts against Notary Project signatures. +[Notation](https://github.com/notaryproject/notation) is a CLI and has set of libraries that offer an implementation of the Notary Project signature specification. Notation allows you to sign artifacts as well as verify artifacts against Notary Project signatures. This section documents extended attributes used by Notation to support plugins. Plugins is a *Notation* concept that allows parts of signing and verification logic to be performed by an external provider. *Signing plugins* allow *Notation* to be extended for integration with remote keys, remote key management services, and signing services, where as *verification plugins* allow for customization of verification logic. Detailed specification for plugins can be found [here](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#notation-extensibility-for-signing-and-verification). -These extended attributes are documented in this spec, as other implementations of Notary Project signature specification may encounter these attributes if they verify a signature that indicated it required a verification plugin for complete signature verification. +These extended attributes are documented in this spec, as other implementations of the Notary Project signature specification may encounter these attributes if they verify a signature that indicated it required a verification plugin for complete signature verification. - **Verification Plugin** (critical): An OPTIONAL attribute that specifies the name of the verification plugin that MAY be used to verify the signature e.g. “com.example.nv2plugin”. [Notation plugin](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#plugin-contract) aware implementations use this attribute to load and execute a *Notation* compliant plugin. @@ -169,7 +169,7 @@ A Notation plugin aware implementations MUST use this attribute to verify the si The plugin MUST use [Semantic Versioning](https://semver.org/) (SemVer) to use this feature i.e the `get-plugin-metadata` plugin command MUST return a SemVer compliant version in the response. A use case for this feature is for a plugin publisher to address security bug in older plugin version, by setting the minimum version to the plugin version with fixes. -See [Guidelines for implementations of Notary Project signature specification](#guidelines-for-notary-project-signature-implementors) for options to handle these attributes during signature verification. +See [Guidelines for implementations of the Notary Project signature specification](#guidelines-for-notary-project-signature-implementors) for options to handle these attributes during signature verification. ### Unsigned Attributes @@ -241,8 +241,8 @@ The `keyUsage` extension MUST be present and MUST be marked critical. Bit positi - The certificate MUST NOT chain to multiple parents/roots. - The certificate chain MUST NOT contain a certificate that is unrelated to the certificate chain. 1. Any certificate in the certificate chain MUST NOT use SHA1WithRSA and ECDSAWithSHA1 signatures. -2. Only Basic Constraints, Key Usage, and Extended Key Usage extensions of X.509 certificates are honored. For rest of the extensions, implementations of Notary Project signature specification MUST fail open i.e. rest of the extensions MUST NOT be evaluated or honored. -3. The certificates in the certificate chain MUST be valid at signing time. Implementations of Notary Project signature specification MUST NOT enforce validity period nesting, i.e the validity period for a given certificate may not fall entirely within the validity period of that certificate's issuer certificate. +2. Only Basic Constraints, Key Usage, and Extended Key Usage extensions of X.509 certificates are honored. For rest of the extensions, implementations of the Notary Project signature specification MUST fail open i.e. rest of the extensions MUST NOT be evaluated or honored. +3. The certificates in the certificate chain MUST be valid at signing time. Implementations of the Notary Project signature specification MUST NOT enforce validity period nesting, i.e the validity period for a given certificate may not fall entirely within the validity period of that certificate's issuer certificate. 4. In the absence of an Authentic Timestamp, each and every certificate in the certificate chain i.e. signing certificate, intermediate certificates, and the root certificate must be valid i.e. not expired at the time of signature verification. ## FAQ @@ -307,11 +307,11 @@ The Notary Project signatures without any critical extended attributes do not im Whereas, the Notary Project signatures that contain critical extended attributes will require additional dependencies for signature validation, either on Notation compliant plugins or equivalent tooling which may not be available in all environments. Similarly, Notation compliant plugin vendors should be aware that usage of extended signed attributes which are marked critical in signature will have implications on portability of the signature. -### Guidelines for implementations of Notary Project signature specification +### Guidelines for implementations of the Notary Project signature specification -Implementations of Notary Project signature specification, can choose to be [Notation plugin protocol](./plugin-extensibility.md#plugin-contract) aware or not. If an implementation chooses to be plugin protocol aware, and it encounters the Verification Plugin and Verification Plugin minimum version attributes during signature verification, it MUST process these attributes. This involves finding the appropriate plugin and the version to use, and executing `verify-signature` plugin command with correct inputs and processing the plugin response, as per the [Verification Plugin interface](./plugin-extensibility.md#verification-extensibility). +Implementations of the Notary Project signature specification, can choose to be [Notation plugin protocol](./plugin-extensibility.md#plugin-contract) aware or not. If an implementation chooses to be plugin protocol aware, and it encounters the Verification Plugin and Verification Plugin minimum version attributes during signature verification, it MUST process these attributes. This involves finding the appropriate plugin and the version to use, and executing `verify-signature` plugin command with correct inputs and processing the plugin response, as per the [Verification Plugin interface](./plugin-extensibility.md#verification-extensibility). -Alternatively, an implementation of Notary Project signature specification can choose not to implement plugin protocol. +Alternatively, an implementation of the Notary Project signature specification can choose not to implement plugin protocol. - The implementation MUST itself perform equivalent verification logic that is usually performed by plugin specified in the signature. - An implementation MUST fail signature verification if it cannot perform the equivalent verification logic, as skipping the plugin equivalent verification logic will cause incorrect and inconsistent signature verification behavior. From 03e4978c23c4b7a084756d4d40834109fc3e98f1 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Mon, 31 Jul 2023 19:34:15 +0800 Subject: [PATCH 15/18] update per comments Signed-off-by: Yi Zha --- specs/signature-specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/signature-specification.md b/specs/signature-specification.md index d607943f..5bce9ef9 100644 --- a/specs/signature-specification.md +++ b/specs/signature-specification.md @@ -98,7 +98,7 @@ The Notary Project signature payload is a JSON document with media type `applica - `targetArtifact` : Required property whose value is the descriptor of the target artifact manifest that is being signed. Only [OCI descriptor][oci-descriptor] is supported. - Descriptor MUST contain `mediaType`, `digest`, and `size` fields. - Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules][annotation-rules]. The Notary Project signature uses annotations for storing both Notary Project specific and user defined metadata. The prefix `io.cncf.notary` in annotation keys is reserved for use in Notary Project signature and MUST NOT be used outside this specification. - - Descriptor MAY contain `artifactType` field for the `config.mediaType` of OCI image based manifests. + - Descriptor MAY contain `artifactType` field for the `config.mediaType` of OCI image manifests. #### Examples From b049e49c6704d4d87e2aa829bb40261f440ebbdc Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Tue, 1 Aug 2023 16:51:49 +0800 Subject: [PATCH 16/18] update per comments Signed-off-by: Yi Zha --- specs/signature-specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/signature-specification.md b/specs/signature-specification.md index 5bce9ef9..f986e4b7 100644 --- a/specs/signature-specification.md +++ b/specs/signature-specification.md @@ -153,7 +153,7 @@ Usage of extended signed attributes which are marked critical in signature will #### Extended attributes for *Notation* Plugins -[Notation](https://github.com/notaryproject/notation) is a CLI and has set of libraries that offer an implementation of the Notary Project signature specification. Notation allows you to sign artifacts as well as verify artifacts against Notary Project signatures. +[Notation](https://github.com/notaryproject/notation) is a CLI and has set of libraries that offer an implementation of the Notary Project signature specification. Notation allows you to sign as well as verify artifacts against Notary Project signatures. This section documents extended attributes used by Notation to support plugins. Plugins is a *Notation* concept that allows parts of signing and verification logic to be performed by an external provider. From 8a592fb5963a887cb9ac86f6dca42dcd846b7d3e Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Tue, 1 Aug 2023 17:02:15 +0800 Subject: [PATCH 17/18] update per comments Signed-off-by: Yi Zha --- specs/signature-specification.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/signature-specification.md b/specs/signature-specification.md index f986e4b7..161c5cf1 100644 --- a/specs/signature-specification.md +++ b/specs/signature-specification.md @@ -118,7 +118,7 @@ The Notary Project signature payload is a JSON document with media type `applica "mediaType": "application/vnd.oci.image.manifest.v1+json", "digest": "sha256:73c803930ea3ba1e54bc25c2bdc53edd0284c62ed651fe7b00369da519a3c333", "size": 16724, - "artifactType": "application/vnd.cncf.notary.signature", + "artifactType": "application/vnd.oci.image.config.v1+json", "annotations": { "io.wabbit-networks.buildId": "123" // user defined metadata } From 863549fc97eb8bdaafc38cfa39358ef3a7a882a9 Mon Sep 17 00:00:00 2001 From: Yi Zha Date: Wed, 2 Aug 2023 13:22:55 +0800 Subject: [PATCH 18/18] update per comments Signed-off-by: Yi Zha --- specs/signature-specification.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specs/signature-specification.md b/specs/signature-specification.md index 161c5cf1..1b7d29ca 100644 --- a/specs/signature-specification.md +++ b/specs/signature-specification.md @@ -140,9 +140,9 @@ The Notary Project signature specification requires the signature envelope to su #### Standard attributes - **Signing Scheme** (critical): A REQUIRED claim that defines the [Notary Project Signing Scheme](./signing-scheme.md) used by the signature. This attribute dictates the rest of signature schema - the set of signed and unsigned attributes to be included in the signature. Supported values are `notary.x509` and `notary.x509.signingAuthority`. -- **Signing Time**: A claim that indicates the time at which the signature was generated. Though this claim is signed by the signing key, it’s considered unauthenticated as a signer can modify local time and manipulate this claim. More details [here](#signing-time). This claim is REQUIRED and only valid when signing scheme is `notary.x509` . -- **Authentic Signing Time** (critical): The authenticated time at which the signature was generated. This claim is REQUIRED and only valid when signing scheme is `notary.x509.signingAuthority` . More details [here](#signing-time). -- **Expiry** (critical): An OPTIONAL claim that provides a “best by use” time for the artifact, as defined by the signer. More details [here](#expiry). +- **Signing Time**: A claim that indicates the time at which the signature was generated. Though this claim is signed by the signing key, it's considered unauthenticated as a signer can modify local time and manipulate this claim. More details [here](#signing-time). This claim is REQUIRED and only valid when signing scheme is `notary.x509`. +- **Authentic Signing Time** (critical): The authenticated time at which the signature was generated. This claim allows a verifier to determine if the signature was generated when the certificate was valid. This claim is REQUIRED and only valid when signing scheme is `notary.x509.signingAuthority`. More details [here](#signing-time). +- **Expiry** (critical): An OPTIONAL claim that provides a "best by use" time for the artifact, as defined by the signer. More details [here](#expiry). - **Content Type** (critical): A REQUIRED claim that indicates the content type of the [payload](#payload). The supported value is `application/vnd.cncf.notary.payload.v1+json`. Other payload types MAY be supported in future. #### Extended attributes @@ -159,9 +159,9 @@ This section documents extended attributes used by Notation to support plugins. Plugins is a *Notation* concept that allows parts of signing and verification logic to be performed by an external provider. *Signing plugins* allow *Notation* to be extended for integration with remote keys, remote key management services, and signing services, where as *verification plugins* allow for customization of verification logic. Detailed specification for plugins can be found [here](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#notation-extensibility-for-signing-and-verification). -These extended attributes are documented in this spec, as other implementations of the Notary Project signature specification may encounter these attributes if they verify a signature that indicated it required a verification plugin for complete signature verification. +This specification documents these extended attributes, as implementations of the Notary Project signature specification may encounter these attributes, if they verify a signature that requires a verification plugin for complete signature verification. -- **Verification Plugin** (critical): An OPTIONAL attribute that specifies the name of the verification plugin that MAY be used to verify the signature e.g. “com.example.nv2plugin”. +- **Verification Plugin** (critical): An OPTIONAL attribute that specifies the name of the verification plugin that MAY be used to verify the signature e.g. "com.example.nv2plugin". [Notation plugin](https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#plugin-contract) aware implementations use this attribute to load and execute a *Notation* compliant plugin. The plugin participates in the overall signature verification workflow and performs specific steps in it. - **Verification Plugin Minimum Version** (critical): An OPTIONAL attribute that specifies the minimum version of the verification plugin that MUST be used to verify the signature. @@ -177,7 +177,7 @@ These attributes are considered unsigned with respect to the signing key that ge - **Certificate Chain**: This is a REQUIRED attribute that contains the ordered list of X.509 public certificates associated with the signing key used to generate the signature. The ordered list starts with the signing certificate, any intermediate certificates and ends with the root certificate. The certificate chain MUST be authenticated against a trust store as part of signature validation. Specific requirements for the certificates in the chain are provided [here](#certificate-requirements). - **Timestamp signature** : An OPTIONAL counter signature which provides [authentic timestamp](#signing-time)e.g. Time Stamp Authority (TSA) generated timestamp signature. Only [RFC3161][ietf-rfc3161] compliant TimeStampToken are currently supported. -- **Signing Agent**: An OPTIONAL claim that provides the identifier of the software (e.g. Notation) that produced the signature on behalf of the user. It is an opaque string set by the software that produces the signature. It's intended primarily for diagnostic and troubleshooting purposes, this attribute is unsigned, the verifier MUST NOT validate formatting, or fail validation based on the content of this claim. The suggested format is one or more tokens of the form `{id}/{version}` containing identifier and version of the software, separated by spaces. E.g. “notation/1.0.0”, “notation/1.0.0 myplugin/0.8”. +- **Signing Agent**: An OPTIONAL claim that provides the identifier of the software (e.g. Notation) that produced the signature on behalf of the user. It is an opaque string set by the software that produces the signature. It's intended primarily for diagnostic and troubleshooting purposes, this attribute is unsigned, the verifier MUST NOT validate formatting, or fail validation based on the content of this claim. The suggested format is one or more tokens of the form `{id}/{version}` containing identifier and version of the software, separated by spaces. E.g. "notation/1.0.0", "notation/1.0.0 myplugin/0.8". ## Signature Algorithm Requirements