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

Added signing and verification workflows #122

Merged
merged 3 commits into from
Feb 3, 2022
Merged

Added signing and verification workflows #122

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
33576d5
Added signing and verification workflows
Jan 11, 2022
90371bf
Fix defination of fail open and fail close
Feb 2, 2022
2ab406b
some more minor changes
Feb 3, 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
24 changes: 22 additions & 2 deletions signature-specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ The signature manifest has an artifact type which specifies it's a Notary V2 sig

- **`artifactType`** (*string*): This REQUIRED property references the Notary version of the signature: `application/vnd.cncf.notary.v2.signature`.
- **`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`
- **`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.

Expand Down Expand Up @@ -204,7 +204,7 @@ Since Notary v2 restricts one signature per signature envelope, the compliant si
4. Signing certificate MUST be a valid codesigning certificate.
5. Only JWS JSON flattened format is supported. See 'Signature Envelope' section.

## Signature Algorithms
## Signature Algorithm Requirements

The implementation MUST support the following set of algorithms:
1. RSASSA-PSS with SHA-256
Expand All @@ -230,6 +230,26 @@ The signing certificate's public key algorithm and size MUST be used to determin
| EC | 384 | ECDSA on secp384r1 with SHA-384 |
| EC | 512 | ECDSA on secp521r1 with SHA-512 |

### Certificate Requirements

The **signing certificate** MUST meet the following minimum requirements:

- The keyUsage extension MUST be present and MUST be marked critical. The bit positions for digitalSignature MUST be set ([RFC-5280](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.3)).
- The extKeyUsage extension MUST be present and its value MUST be id-kp-codeSigning ([RFC-5280](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.12)).
- If the basicConstraints extension is present, the cA field MUST be set false ([RFC-5280](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.9)).
- The certificate MUST abide by the following key length restrictions:
- For RSA public key, the key length MUST be 2048 bits or higher.
- For ECDSA public key, the key length MUST be 256 bits or higher.

The **timestamping certificate** MUST meet the following minimum requirements:

- The keyUsage extension MUST be present and MUST be marked critical. The bit positions for digitalSignature MUST be set ([RFC-5280](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.3)).
- The extKeyUsage extension MUST be present and and MUST be marked critical. The value of extension MUST be id-kp-timeStamping ([RFC-5280](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.12)).
- If the basicConstraints extension is present, the cA field MUST be set false ([RFC-5280](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.9)).
- The certificate MUST abide by the following key length restrictions:
- For RSA public key, the key length MUST be 2048 bits or higher.
- For ECDSA public key, the key length MUST be 256 bits or higher.

## FAQ

**Q1.** How will Notary v2 support multiple signature envelope format?
Expand Down
56 changes: 56 additions & 0 deletions signing-and-verification-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Signing and Verification Workflow

This document describes how Notary v2 signs and verifies OCI artifacts.

## Signing workflow

The user wants to sign an OCI artifact and push the signature to a repository.

### Prerequisite

- User has access to the signing certificate and private key or a remote signing service through a notation plug-in.

### Steps

1. **Generate signature:** Using notation CLI or any other compliant signing tool, sign the OCI artifact. The signing tool should follow the following guideline.
1. Verify that the signing certificate is valid and satisfies [certificate requirements](./signature-specification.md#certificate-requirements).
SteveLasker marked this conversation as resolved.
Show resolved Hide resolved
1. Verify that the signing algorithm satisfies [algorithm requirements](./signature-specification.md#signature-algorithm-requirements).
Copy link
Contributor

Choose a reason for hiding this comment

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

The signing algorithm MUST implement the Notary v2 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. Verify that the timestamp signing certificate satisfies [certificate requirements](./signature-specification.md#certificate-requirements).
Copy link
Contributor

Choose a reason for hiding this comment

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

If provided, the timestamp signing certificate MUST satisfy certificate requirements.

1. Verify that the timestamp signing algorithm satisfies [algorithm requirements](./signature-specification.md#signature-algorithm-requirements).
Copy link
Contributor

Choose a reason for hiding this comment

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

The timestamp signing algorithm MUST satisfy the Notary v2 algorithm requirements.

1. Embed timestamp to the signature envelope.
1. **Push the signature envelope:** Push the signature envelope generated in the previous step to the repository.
1. **Generate signature artifact manifest:** As decribed in [signature specification](./signature-specification.md#storage) create the Notary v2 signature artifact manifest for the signature envelope generated in step 1.
1. **Push signature artifact manifest:** Push Notary v2 signature artifact manifest to the repository.

The user pushes the OCI artifact to the repository before the signature generation process as the signature reference must exist for the signature push to succeed. See: [ORAS Artifact Push Validation](https://github.com/oras-project/artifacts-spec/blob/main/artifact-manifest.md#push-validation) for more info.

## Verification workflow
priteshbandi marked this conversation as resolved.
Show resolved Hide resolved

The user wants to pull an OCI artifact only if they are signed by a trusted publisher and the signature is valid.

### Prerequisites

- User has a fully qualified reference to an OCI artifact they want to pull. If the fully qualified artifact reference contains a tag then the user needs to resolve this tag to a digest.

E.g. If fully qualified reference is `wabbit-networks.io/software:Latest` where `Latest` is a tag pointing to an artifact. The user must resolve `Latest` tag to a digest and construct a new artifact reference using the resolved digest `wabbit-networks.io/software@sha256:${digest}`.
- User has configured [trust store and trust policy](./trust-store-trust-policy-specification.md) required for signature verification.

### Steps

1. **Should Notary v2 verify the signature? :** Depending upon [trust-policy](./trust-store-trust-policy-specification.md#trust-policy) configuration, determine whether Notary v2 needs to verify the signature or not. If signature verification should be skipped for the given artifact, skip the below steps and directly jump to step 4.
1. **Get signature artifact descriptors:** Using the ORAS [Manifest Referrers API](https://github.com/oras-project/artifacts-spec/blob/main/manifest-referrers-api.md) download the Notary v2 signature artifact descriptors. The `artifactType` parameter is set to Notary v2 signature's artifact type `application/vnd.cncf.notary.v2.signature`. Note that all ORAS implementations may not support filtering using `artifactType`.
1. For each signature artifact descriptor, perform the following steps:
1. **Get signature artifact manifest:** Download the Notary v2 signature's artifact manifest for the given artifact descriptor.
1. **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. 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 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.
Copy link
Contributor

Choose a reason for hiding this comment

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

The signed payload of a signature contains the descriptor of the target OCI artifact, which includes digest, size, and media type.

Instead of using the verified digest, we should say using the verified descriptor.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Have mentioned digest instead of descriptor because we haven't verified the descriptor inside the signature envelope with the actual OCI artifact's descriptor (the one stored in the registry).

Loading