diff --git a/signature-specification.md b/signature-specification.md index c0efa39c..624e137a 100644 --- a/signature-specification.md +++ b/signature-specification.md @@ -77,19 +77,19 @@ Notary v2 supports [JWS JSON Serialization](https://datatracker.ietf.org/doc/htm Notary v2 requires Payload to be the content **descriptor** of the subject manifest that is being signed. 1. Descriptor MUST contain `mediaType`, `digest`, `size` fields. -1. Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules](https://github.com/opencontainers/image-spec/blob/main/annotations.md#rules). - In Notary v2 annotations are being used to store signed attributes. - The annotations key prefix for Notary v2 use is not yet finalized. - See [issues-106](https://github.com/notaryproject/notaryproject/issues/106). +1. Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules](https://github.com/opencontainers/image-spec/blob/main/annotations.md#rules). Notary v2 uses annotations for storing both Notary specific and user defined signed attributes. The prefix `org.cncf.notary` in annotation keys is reserved for use in Notary v2 and MUST NOT be used outside this specification. 1. Descriptor MAY contain `artifactType` field for artifact manifests, or the `config.mediaType` for `oci.image` based manifests. Examples: ```jsonc { - "mediaType": "application/vnd.oci.image.manifest.v1+json", - "digest": "sha256:73c803930ea3ba1e54bc25c2bdc53edd0284c62ed651fe7b00369da519a3c333", - "size": 16724 + "mediaType": "application/vnd.oci.image.manifest.v1+json", + "digest": "sha256:73c803930ea3ba1e54bc25c2bdc53edd0284c62ed651fe7b00369da519a3c333", + "size": 16724, + "annotations": { + "io.wabbit-networks.buildId": "123" // user defined signed attribute. + } } ``` diff --git a/signing-and-verification-workflow.md b/signing-and-verification-workflow.md index 7b305d2d..0f248b11 100644 --- a/signing-and-verification-workflow.md +++ b/signing-and-verification-workflow.md @@ -16,9 +16,8 @@ The user wants to sign an OCI artifact and push the signature to a repository. 1. Verify that the signing certificate is valid and satisfies [certificate requirements](./signature-specification.md#certificate-requirements). 1. Verify that the signing algorithm satisfies [algorithm requirements](./signature-specification.md#signature-algorithm-requirements). 1. Generate signature. - 1. Generate signature using signature formats specified in [supported signature envelopes](./signature-specification.md#supported-signature-envelopes). - 1. If the user wants to timestamp the signature, obtain an [RFC-3161](https://datatracker.ietf.org/doc/html/rfc3161.html) compliant timestamp for the signature generated in the previous step. - Otherwise, continue to the next step. + 1. Generate signature using signature formats specified in [supported signature envelopes](./signature-specification.md#supported-signature-envelopes). Also, as part of this step, the user-defined/supplied custom attributes should be added to the annotations of the signature's descriptor. + 1. If the user wants to timestamp the signature, obtain an [RFC-3161](https://datatracker.ietf.org/doc/html/rfc3161.html) compliant timestamp for the signature generated in the previous step. Otherwise, continue to the next step. 1. Verify that the timestamp signing certificate satisfies [certificate requirements](./signature-specification.md#certificate-requirements). 1. Verify that the timestamp signing algorithm satisfies [algorithm requirements](./signature-specification.md#signature-algorithm-requirements). 1. Embed timestamp to the signature envelope.