From 0bc9ec3da17059913383312b67b188374be5a270 Mon Sep 17 00:00:00 2001 From: Pritesh Bandi Date: Wed, 2 Feb 2022 17:11:32 -0800 Subject: [PATCH 1/2] Added support for signature filtering. Signed-off-by: Pritesh Bandi --- signature-specification.md | 9 +++++++-- signing-and-verification-workflow.md | 8 ++++++-- 2 files changed, 13 insertions(+), 4 deletions(-) diff --git a/signature-specification.md b/signature-specification.md index f4c92637..bced6fe3 100644 --- a/signature-specification.md +++ b/signature-specification.md @@ -20,7 +20,8 @@ The signature manifest has an artifact type which specifies it's a Notary V2 sig - **`blobs`** (*array of objects*): This REQUIRED property contains collection of only one [artifact descriptor](https://github.com/oras-project/artifacts-spec/blob/main/descriptor.md) referencing signature envelope. - **`mediaType`** (*string*): This REQUIRED property contains media type of signature envelope blob. The supported value is `application/jose+json` - **`subject`** (*descriptor*): A REQUIRED artifact descriptor referencing the signed manifest, including, but not limited to image manifest, image index, oras-artifact manifest. -- **`annotations`** (*string-string map*): This OPTIONAL property contains arbitrary metadata for the artifact manifest. It can be used to store information about the signature. +- **`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 `org.cncf.notary` namespace are reserved for use in Notary and MUST NOT be used by other specifications. + - **`org.cncf.notary.x509certs.fingerprint.sha256`**: A REQUIRED annotation whose value contains the list of SHA-256 fingureprint of signing certificate and certificate chain used for signature generation. The list of fingerprints is present as a JSON array string. ```json { @@ -38,7 +39,7 @@ The signature manifest has an artifact type which specifies it's a Notary V2 sig "size": 16724 }, "annotations": { - "org.cncf.notary.signature.subject": "wabbit-networks.io" + "org.cncf.notary.x509certs.fingerprint.sha256": "[\"B7A69A70992AE4F9FF103EBE04A2C3BA6C777E439253CE36562E6E98375068C3\" \"932EB6F5598435D4EF23F97B0B5ACB515FAE2B8D8FAC046AB813DDC419DD5E89\"]" } } ``` @@ -48,6 +49,10 @@ The signature manifest has an artifact type which specifies it's a Notary V2 sig The client should be able to discover all the signatures belonging to an artifact (such as image manifest) by using [ORAS Manifest Referrers API](https://github.com/oras-project/artifacts-spec/blob/main/manifest-referrers-api.md). ORAS Manifest 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 ORAS Manifest Referrers API or using custom logic on the client. 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.x509certs.fingerprint.sha256` annotations key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. ## Signature Envelope diff --git a/signing-and-verification-workflow.md b/signing-and-verification-workflow.md index 530f1912..0eccdfaa 100644 --- a/signing-and-verification-workflow.md +++ b/signing-and-verification-workflow.md @@ -46,11 +46,15 @@ The user wants to pull an OCI artifact only if they are signed by a trusted publ 1. **Get signature artifact manifest:** Download the Notary v2 signature's artifact manifest for the given artifact descriptor. 1. **Filter signature artifact manifest:** 1. Filter out the unsupported signature formats by comparing the signature envelope format type (`[descriptors].descriptor.mediaType`) in the signature manifest, with the supported formats defined in [signature specification](./signature-specification.md#storage). - 1. Depending upon the trust-store configuration, further filter out signature manifest. why? How? **TBD**(See [signature filtering](https://hackmd.io/@pritesh/signature_filtering)). + 1. Depending upon the trust-store and trust-policy configuration, further filter out signature manifests. + 1. Using the `scopes` configured in trust policies, get the applicable trust policy. + 1. From the trust policy, get the list of trusted signing certificates. If the trust policy contains multiple trust stores, create a list of trusted signing certificates by merging the trusted signing certificate list of each trust store. + 1. Calculate the SHA-256 fingerprint of all the trusted certificates and compare them against the list of SHA-256 certificate fingerprints present in `org.cncf.notary.x509certs.fingerprint.sha256` annotation of artifact manifest. + 1. If there is at least one match, continue to the next step. Otherwise, move to the next signature artifact descriptor(step 2.1). If all signature artifact descriptors have already been processed, fail the signature verification and exit. 1. If the artifact manifest is filtered out, skip the below steps and move to the next signature artifact descriptor(step 2.1). If all signature artifact descriptors have already been processed, fail the signature verification and exit. 1. **Get and verify signatures:** On the filtered Notary v2 signature artifact manifest, perform the following steps: 1. Download the signature envelope. 1. Verify the signature envelope using trust-store and trust-policy as mentioned in [signature evaluation](./trust-store-trust-policy-specification.md#signature-evaluation) section. - 1. If signature verification fails, skip the below steps and move to the next signature artifact descriptor(step 2.1). If all signature artifact manifests have already been processed, fail the signature verification and exit. + 1. If signature verification fails, skip the below steps and move to the next signature artifact descriptor(step 2.1). If all signature artifact descriptors have already been processed, fail the signature verification and exit. 1. If signature verification succeeds, compare the digest derived from the given OCI artifact reference with the signed digest present in the signature envelope's payload. If digests are equal, signature verification is considered successful. Otherwise, move to the next signature artifact descriptor(step 2.1). If all signature artifact descriptors have already been processed, fail the signature verification and exit. 1. **Get OCI artifact:** Using the verified digest, download the OCI artifact. This step is not in the purview of Notary v2. From 1269f46a249a498afb47ae2fa55629d17b0f422a Mon Sep 17 00:00:00 2001 From: Pritesh Bandi Date: Fri, 4 Feb 2022 17:42:35 -0800 Subject: [PATCH 2/2] some minor updates Signed-off-by: Pritesh Bandi --- signature-specification.md | 4 ++-- signing-and-verification-workflow.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/signature-specification.md b/signature-specification.md index bced6fe3..208e0001 100644 --- a/signature-specification.md +++ b/signature-specification.md @@ -21,7 +21,7 @@ The signature manifest has an artifact type which specifies it's a Notary V2 sig - **`mediaType`** (*string*): This REQUIRED property contains media type of signature envelope blob. The supported value is `application/jose+json` - **`subject`** (*descriptor*): A REQUIRED artifact descriptor referencing the signed manifest, including, but not limited to image manifest, image index, oras-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 `org.cncf.notary` namespace are reserved for use in Notary and MUST NOT be used by other specifications. - - **`org.cncf.notary.x509certs.fingerprint.sha256`**: A REQUIRED annotation whose value contains the list of SHA-256 fingureprint of signing certificate and certificate chain used for signature generation. The list of fingerprints is present as a JSON array string. + - **`org.cncf.notary.x509certs.fingerprint.sha256`**: A REQUIRED annotation whose value contains the list of SHA-256 fingerprint of signing certificate and certificate chain used for signature generation. The list of fingerprints is present as a JSON array string. ```json { @@ -52,7 +52,7 @@ ORAS Manifest Referrers API returns a paginated list of all artifacts belonging ### 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.x509certs.fingerprint.sha256` annotations key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. +The Notary v2 signature artifact's `org.cncf.notary.x509certs.fingerprint.sha256` annotations key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. ## Signature Envelope diff --git a/signing-and-verification-workflow.md b/signing-and-verification-workflow.md index 0eccdfaa..c4edcb4a 100644 --- a/signing-and-verification-workflow.md +++ b/signing-and-verification-workflow.md @@ -48,7 +48,7 @@ The user wants to pull an OCI artifact only if they are signed by a trusted publ 1. Filter out the unsupported signature formats by comparing the signature envelope format type (`[descriptors].descriptor.mediaType`) in the signature manifest, with the supported formats defined in [signature specification](./signature-specification.md#storage). 1. Depending upon the trust-store and trust-policy configuration, further filter out signature manifests. 1. Using the `scopes` configured in trust policies, get the applicable trust policy. - 1. From the trust policy, get the list of trusted signing certificates. If the trust policy contains multiple trust stores, create a list of trusted signing certificates by merging the trusted signing certificate list of each trust store. + 1. Get the list of trusted certificates from the trust stores specified in the applicable trust policy. If the trust policy contains multiple trust stores, create a list of trusted certificates by merging the trusted certificate list of each trust store. 1. Calculate the SHA-256 fingerprint of all the trusted certificates and compare them against the list of SHA-256 certificate fingerprints present in `org.cncf.notary.x509certs.fingerprint.sha256` annotation of artifact manifest. 1. If there is at least one match, continue to the next step. Otherwise, move to the next signature artifact descriptor(step 2.1). If all signature artifact descriptors have already been processed, fail the signature verification and exit. 1. If the artifact manifest is filtered out, skip the below steps and move to the next signature artifact descriptor(step 2.1). If all signature artifact descriptors have already been processed, fail the signature verification and exit.