Skip to content

Latest commit

 

History

History
72 lines (58 loc) · 6.74 KB

signing-and-verification-workflow.md

File metadata and controls

72 lines (58 loc) · 6.74 KB
Raw

Signing and Verification Workflow

This document describes the workflow of signing and verifying OCI artifacts.

Signing workflow

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

Signing Prerequisites

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

Signing 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.
    2. Verify that the signing algorithm satisfies algorithm requirements.
    3. Generate signature.
      1. Generate signature using signature formats specified in 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.
      2. If the user wants to timestamp the signature, obtain an RFC-3161 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.
        2. Verify that the timestamp signing algorithm satisfies algorithm requirements.
      3. Embed timestamp to the signature envelope.
  2. Push the signature envelope: Push the signature envelope generated in the previous step to the repository.
  3. Generate signature artifact manifest: As described in signature specification create the Notary Project signature manifest for the signature envelope generated in step 1.
  4. Push signature artifact manifest: Push the Notary Project signature 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.

Verification workflow

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

Verification 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 a fully qualified reference is wabbit-networks.io/software:latest where latest is a tag pointing to an artifact. The user must resolve the 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 required for signature verification.

Verification Steps

  1. Should implementations of this specification verify the signature? : Depending upon trust-policy configuration, determine whether implementations of this specification need 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.
  2. Get signature artifact descriptors: Using the OCI Distribution Referrers API download the Notary Project signature manifest descriptors. The artifactType parameter is set to the Notary Project signature's artifact type application/vnd.cncf.notary.signature.
  3. For each signature artifact descriptor, perform the following steps:
    1. Get signature artifact manifest: Download the Notary Project signature's manifest for the given artifact descriptor.
    2. 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.
      2. 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.
        2. 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 io.cncf.notary.x509certs.fingerprint.sha256 annotation of artifact manifest.
          2. If there is at least one match, continue to the next step. Otherwise, move to the next signature artifact descriptor(step 3.1). If all signature artifact descriptors have already been processed, fail the signature verification and exit.
      3. If the artifact manifest is filtered out, skip the below steps and move to the next signature artifact descriptor(step 3.1). If all signature artifact descriptors have already been processed, fail the signature verification and exit.
    3. Get and verify signatures: On the filtered manifest of the Notary Project signature, perform the following steps:
      1. Download the signature envelope.
      2. Verify the signature envelope using trust-store and trust-policy as mentioned in signature evaluation section.
      3. If the signature verification fails, skip the below steps and move to the next signature artifact descriptor(step 3.1). If all signature artifact descriptors have already been processed, fail the signature verification and exit.
      4. 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 3.1). If all signature artifact descriptors have already been processed, fail the signature verification and exit.
  4. Get OCI artifact: Using the verified digest, download the OCI artifact. This step is not in the purview of Notary Project.