# Updates to Signature specification

This document provides details of Notary signature, it specifies the set of signed and unsigned attributes that make up the signature, their purpose and how they influence the signature verification. This specification aims to be be agnostic of signature envelope format (like COSE, JWS), details of encoding the envelope in a specific signature envelope format will be covered in separate spec.

Notation is a reference implementation of the Notary v2 standards. Though the specification contains implementations hint for Notation, the specification is intended to be open for implementation by any library/tooling. The specification also supports a plugin model for extensible signing and verification logic. Implementations may choose to implement the plugin model, specifically for signature verification, if they intend to verify signatures produced by Notation, in addition to signatures produced by their own implementation.

## Signature Envelope

The Signature Envelope is a standard data structure for creating a signed message. A signature envelope consists of the following components:

* Payload m: The data that is integrity protected - e.g. descriptor of the artifact being signed.
* Signed attributes/claims v: The signature metadata that is integrity protected - e.g. signature expiration time, signing time, etc.
* Unsigned attributes u: This OPTIONAL property represents signature metadata that is not integrity protected - e.g. timestamp, certificates, etc.
* Cryptographic signatures s: The digital signatures computed on payload and signed attributes.

A signature envelope is e = {m, v, u, s} where s is signature.

## Payload

Notary v2 requires Payload to be the content descriptor (https://github.com/opencontainers/image-spec/blob/main/descriptor.md) of the subject manifest that is being signed.

*Examples of OCI descriptor:*

{
   "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "digest": "sha256:73c803930ea3ba1e54bc25c2bdc53edd0284c62ed651fe7b00369da519a3c333",
    "size": 16724,
    "annotations": {
        "io.wabbit-networks.buildId": "123"  // user defined signed attribute.
    }
}

{
   "mediaType": "sbom/example",
   "digest": "sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0",
   "size": 32654
}

## Signed Attributes

Notary v2 requires the signature envelope to support the following signed attributes/claims. These claims are used during signature verification and MUST NOT be stored/appended in the payload, as the payload will only be parsed and processed once the signature has been verified. Additionally claims which MUST be processed by a verifier are marked as critical, claims which are informational and do not influence signature verification MUST NOT be marked critical.

### Standard attributes

* **Notary Signature profile** (critical): A Notary signature profile defines the supported identity type, trust model and its features. The signature profile dictates which set of claims are supported in the signature, if they are required or optional, and if they are critical. The signature profile also dictates the elements of the Notation trust policy, and the verification process itself. Notary currently supports a following values for this claim notary.signer.x509 and notary.signingservice.x509, more details here. Additional trust models (e.g. Notary TUF, ledger based) will be supported by introducing new signature profiles. Future signature profiles may reuse them or define new ones as required.
* **Signing time**: The time at which the signature was generated. This is a REQUIRED claim for signature profile notary.signer.x509. Though this claim is signed by the signing key, it’s considered unauthenticated as a signer can modify local time and manipulate this claim. More details here .
* **Trusted signing time** (critical) *:* The time at which the signature was generated. This is an authenticated signing time which can be generated by a trusted time-stamper, like a signing service. This is a REQUIRED claim for signature profile notary.signingservice.x509 . More details here -.
* **Signature Expiry** (critical): The time when a signature is considered to be expired. This is an OPTIONAL claim.
* **Content type** (critical): The content type of the payload. Notary currently supports OCI descriptor of a subject manifest as the payload, supported value is application/vnd.cncf.oras.artifact.descriptor.v1+json, other payload types MAY be supported in future. This is a REQUIRED claim.
* **Client identifier**: The version of a client (e.g. Notation) that produced the signature. This is an REQUIRED claim. It uses the HTTP user agent format e.g. “notation/1.0.0”. This claim in intended to be used for diagnostic and troubleshooting purposes.

### Attributes to support plugins

Signing plugins allow client tools like Notation to be extended for integration with remote keys remote key management services (KMS) and signing services, verification plugins allow for extended verification logic, further details can be found here (https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#notation-extensibility-for-signing-and-verification). Following signed attributes are used when signatures are generated by plugins.

* **Signing Plugin identifier** : The version of the plugin that produced the signature. This is a REQUIRED claim when a plugin is used to generate signature. This claim in intended to be used for diagnostic and troubleshooting purposes. It uses the HTTP user agent format e.g. “com.example.nv2plugin/1.0.0”. The claim MAY also be used by plugins which implement verification logic to implement backwards compatibility.
* **Verification plugin required** (critical) : A signing plugin generated signature can define additional critical and non critical custom claims. If additional critical claims are included in the signature envelope, the client MUST either know how to process the additional critical claims or use a plugin identified by Verification plugin required to process additional critical claims using the plugin. The value of this claim is a plugin name “com.example.nv2plugin” (TODO address versioning). The extensibility (https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#plugin-installation-and-config) spec provides details of protocol used to load and execute a plugin . A verifier MUST fail signature verification if cannot process all the critical claims in the signature envelope. This is an OPTIONAL claim.
* **Verification plugin URL** : A URL to the plugin required to verify signatures. REQUIRED if Verification plugin identifier claim is present. An https URL MUST be specified. It’s intended to be displayed to users to help discover the plugin required to verify signatures.

Unsigned Attributes

* **Certificate Chain** : This property contains the list of X.509 certificate or certificate chain. This is a REQUIRED attribute. The certificate chain is authenticated using against a trust store as part of signature validation.
* **TSA counter signature** : The time stamp token generated for a given signature. Only RFC3161 (https://datatracker.ietf.org/doc/html/rfc3161#section-2.4.2) compliant TimeStampToken are supported. This is an OPTIONAL attribute.

## Appendix 1

### Signature Profile

`notary.signer.x509 `- This signature profile defines set of claims associated with traditional x509 PKI, where trusted CA issue signing certificates to end users (end entities), and the user owns the signing key and generates signatures.

`notary.signingservice.x509` - This signature profile defines set of claims associated with a signing service that uses X509 PKI. The signing service manages the keys of behalf of the user, and generates signatures.

TSA signature is required in a notary.signer.x509 signature requires a TSA signature for determining an authenticated signing time (timestamp), and optional for notary.signingservice.x509 which uses the trusted signing time claim instead.

### Signing time

The signing time denoted the time at which signature was generated. X509 certificates have defined lifetime during which they can be used to generate signatures. Signatures generated after the certificate expires are considered invalid. A trusted timestamp allows a verifier to determine if the signature was generated when the certificate was valid. It also allows a verifier to determine if a signature be treated as valid when a certificate is revoked, if the certificate was revoked after the signature was generated. In the absence of a trusted timestamp, signatures are considered invalid after certificate expires, and all signatures are considered revoked when a certificate is revoked.

**Signing time** : If the signing time is signed by a user controlled signing key, it’s considered untrusted/unauthenticated claim as the signer can modify local time and manipulate it.

**Trusted signing time** :If the signature is generated by a signing service that manages keys on behalf of the user, and the user and verifier trust the signing service, a timestamp generated by the signing service is considered trusted.

**TSA counter signature** : Only supports a RFC3161 (https://datatracker.ietf.org/doc/html/rfc3161#section-2.4.2) compliant TSA countersignature to provide a trusted timestamp.

# Appendix 2

Trust policy changes

**Before**

{
    "version": "1.0",
    "trustPolicies": [
        {
            "name": "verify-signature",
            "scopes": [
                "wabbit-networks.io/software/product1"
                "wabbit-networks.io/software/product2" ],
            "trustStores": [ "trust-store-name-1", "trust-store-name-2" ],
            "trustAnchors": [
                "subject: C=US, ST=WA, L=Seattle, O=acme-rockets.io"
            ],
            "expiryValidations": {
                "signatureExpiry": "enforce | warn",
                "signingIdentityExpiry": "enforce | warn",
                "timestampExpiry": "enforce | warn"
            },
            "revocationValidations": {
                "signingIdentityRevocation": "enforceWithFailOpen | enforceWithFailClose | warn | skip",
                "timestampRevocation": "enforceWithFailOpen | enforceWithFailClose | warn | skip"
            }
        },
        {
            "name": "skip-signature-verification",
            "scopes": [ "wabbit-networks.io/software/unsigned/productA" ],
            "skipSignatureVerification": true
        }
    ]
}

*After*

* Expiry and revocation check for TSA will not be performed as part of signature verification. TSAs are valid for ~10 years and TSA certs are rotated every year, most tools do not check for TSA expiry. Revocation check for TSA adds additional latency and brittleness to verification process, without additional security. Only scenario it protects against is when a signing key and TSA key is compromised at the same time.
* We’ll provided preset verification policy switched, and the ability to override values.

{
    "version": "1.0",
    "trustPolicies": [
        {
            "name": "verify-signature",
            "scopes": [
                "wabbit-networks.io/software/product1"
                "wabbit-networks.io/software/product2" ],
            "trustStores": [ "trust-store-name-1", "trust-store-name-2" ],
            "trustAnchors": [
                "subject: C=US, ST=WA, L=Seattle, O=acme-rockets.io"
            ],
            "verificationProfile":"strict | audit"
        },
        {
            "name": "verify-signature",
            "scopes": [
                "wabbit-networks.io/software/product1"
                "wabbit-networks.io/software/product2" ],
            "trustStores": [ "trust-store-name-1", "trust-store-name-2" ],
            "trustAnchors": [
                "subject: C=US, ST=WA, L=Seattle, O=acme-rockets.io"
            ],
            "verificationProfile" :
            {
                "preset" : "strict",
                "override" {
                 "revocationCheck" : "enforce_ignoreErrors"
                }
            }
        },
        {
            "name": "skip-signature-verification",
            "scopes": [ "wabbit-networks.io/software/unsigned/productA" ],
            "skipSignatureVerification": true
        }
    ]
}


**Trust Store Dir**

\trust_store
    \x509
        \ca_roots
            \public-ca-roots
            \dockerhub
        \tsa_roots
            \public-tsa-roots
        \signing_service_roots
            \