Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add support for signature filtering. #131

Merged
merged 2 commits into from
Feb 7, 2022
Merged

Add support for signature filtering. #131

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0bc9ec3
Added support for signature filtering.
Feb 3, 2022
1269f46
some minor updates
Feb 5, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions signature-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 fingerprint of signing certificate and certificate chain used for signature generation. The list of fingerprints is present as a JSON array string.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: On the naming of fingerprint and thumbprint, which one is more popular or consistent?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: You may also want to note that the fingerprint is in HEX format.


```json
{
Expand All @@ -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\"]"
}
}
```
Expand All @@ -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 `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

Expand Down
8 changes: 6 additions & 2 deletions signing-and-verification-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. 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.
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.