Notary V2 - Signature Format

tags: `notary`

This document defines the requirements of the signature format and discusses the candidates for Notary V2.

Definition

A complete signature

Σ = (m, μ, \hat{μ}, σ) \leftarrow Sign (s k, m)

is a tuple of

Signed payload
$m$ .
Signed signature metadata
$μ$ .
Unsigned signature metadata
$\hat{μ}$ .
Cryptographic signature
$σ$ .

where

s k

stands for signing key.

Image Not Showing Possible Reasons

The image file may be corrupted
The server hosting the image is unavailable
The image path is incorrect
The image format is not supported

Learn More →

A signature envelope

ε_{n} = {m, (μ_{0}, {\hat{μ}}_{0}, σ_{0}), \dots, (μ_{n - 1}, {\hat{μ}}_{n - 1}, σ_{n - 1})}

is a compact form of

n

signatures signing the same payload

m

. It can be expanded to

Σ_{i} = (m, μ_{i}, {\hat{μ}}_{i}, σ_{i}), \forall i \in Z_{n}

A complete signature

Σ

can be viewed as a signature envelope

ε_{1}

Requirements

Since payload is about the metadata of the artifact manifest to be signed and it is not specific to any signature scheme, the payload requirements are discussed separately.

Payload

The payload MUST be a byte sequence.
The payload MUST contain a descriptor of the target manifest.
- A descriptor MUST contain mediaType, digest, size fields.
- A descriptor MAY contain a annotations field.
- A descriptor MAY contain the artifactType field for artifact manifests, or the config.mediaType for oci.image based manifests.
Artifact identity MAY be indicated in the payload.
- When indicated, the verifier SHOULD verify the origin against the signer.

Signature

A signature MUST be stored or transferred in a signature envelope.
A signature envelope SHOULD be encoded in a single file.
A signature envelope MUST contain one and only one complete signature.
Multiple signatures for a subject manifest MUST be represented as seperate signature manifest and signature envelope (blob) pairs.
The signing algorithm MAY be indicated in the signed signature metadata.
- There is a concern on the signing algorithm not matching the verification key.
  - See CS-DRNT15-1 Section 3.3.
  - Similar vulnerability is introduced in A cross-protocol attack on the TLS protocol by Mavrogiannopoulos et al.
  - Detailed discussions can be found at secure-systems-lab/dsse#35.
The signing timestamp MAY be in the signed signature metadata.
The signature expiry time MAY be in the signed signature metadata.
The signed signature metadata MAY contain information that allows verifiers to determine if the artifact is revoked.
- The contents of this attribute are pending the outcome of artifact level revocation design.
If the signature is timestamped by a TSA, the timestamp and the corresponding signatures MUST be stored in the unsigned signature metadata.
If the signature was produced by a X.509 certificate, the signature MUST contain the complete certificate chain of the signing certificate as an unsigned attribute.
The thumbprint of the signing certificate MAY be indicated in the unsigned signature metadata.

Signature Format

A signature format MUST be able to store the payload.
A signature format MUST be able to store the cryptographic signature.
A signature format MUST be able to store unsigned signature metadata.
- This requirement is essential for TSA. To time stamp a signature, the original signature must be generated first and then sent to a TSA for time stamping. Once obtained the timestamp signature, it will be attached to the original signature.
A signature format MAY be able to store signed signature metadata.
- In case of a signature format candidate being unable to store signed signature metadata, the signed signature metadata can be combined with the payload before signing. Since the payload contains the signature specific metadata, the signature format loses the ability to store multiple signatures.
Signature format MUST support referencing and inlining of different identity types such as key(s) and certificate(s).
Signature format SHOULD be easy to implement using existing Go libraries(Docker CLIs are developed in Go).
Signature format MAY be able to store multiple signatures generated using same or different cryptographicmaterials(identity types and signing algoritms).
Signature format MAY support counter signature.

Existing Formats

JWT variant

Notary v2 version <= prototype-2 defines a JWT-variant signature format.

Particularly, this JWT-variant is serialized in JWS Compact Serialization as defined by RFC7515 Section 7.1.

Pros:

Commonly used.
Libraries can be found for many languages.
More flexible.

Cons:

Consumes the header before authenticating.
- Verifiers can be tricked into MAC algorithms instead of asymmetric key signing.
- Example: RSA or HMAC?
This variant may not be compatible with all existing libraries.
Current implementation relies on docker/libtrust, which is archived.
Does not support unsigned signature metadata.
- Cannot be extended to support TSA.

Example:

eyJ0eXAiOiJ4NTA5IiwiYWxnIjoiUlMyNTYiLCJ4NWMiOlsiTUlJRHN6Q0NBcHVnQXdJQkFnSVVMMWFuRVUveUp5NjdWSlRiSGtOWDBiQk5BbkV3RFFZSktvWklodmNOQVFFTEJRQXdhVEVkTUJzR0ExVUVBd3dVY21WbmFYTjBjbmt1WlhoaGJYQnNaUzVqYjIweEZEQVNCZ05WQkFvTUMyVjRZVzF3YkdVZ2FXNWpNUXN3Q1FZRFZRUUdFd0pWVXpFVE1CRUdBMVVFQ0F3S1YyRnphR2x1WjNSdmJqRVFNQTRHQTFVRUJ3d0hVMlZoZEhSc1pUQWVGdzB5TURBM01qY3hORFF6TkRaYUZ3MHlNVEEzTWpjeE5EUXpORFphTUdreEhUQWJCZ05WQkFNTUZISmxaMmx6ZEhKNUxtVjRZVzF3YkdVdVkyOXRNUlF3RWdZRFZRUUtEQXRsZUdGdGNHeGxJR2x1WXpFTE1Ba0dBMVVFQmhNQ1ZWTXhFekFSQmdOVkJBZ01DbGRoYzJocGJtZDBiMjR4RURBT0JnTlZCQWNNQjFObFlYUjBiR1V3Z2dFaU1BMEdDU3FHU0liM0RRRUJBUVVBQTRJQkR3QXdnZ0VLQW9JQkFRRGtLd0FjVjQ0cHNqTjhubm8xZVozenYxWktVaEpBb3h3Qk9JR2ZJeEllK2lIdHBYTHZGRlZ3azVKYnh1K1BraWcyTjRCM0lscmovVnJ5aTBoeHA0bWFnMDJNNzMzYlhMUkVOU09GT05Sa3NscE84ekhVTjVwWWRuaFRTd1lUTGFwMSsxYmdjRlN1VVhMV2llcVpCNnFjN2tpdjNiajNTUGFmNDIrczQ4VjQ5dC9PcFh4THRnaVdMOVhrdURUWmN0cEpKQTR2SEhrNk91MGJjZzdpR20rTDF4d0lmYjhNbDRvV3ZUMFNGMzVmZ1cwOGJiTFhaMnYxWENMUnNyV1VnYnE0VStLeHRFcEczWElZY1loS3gxcklyVWhmRUprdUh6Z1BnbE0xMWdHNVcrQ3lmZyt3Zk9KaWc1cTZheElLV3pJZjZDOG04bG15NmJNK041RXNEOVN2QWdNQkFBR2pVekJSTUIwR0ExVWREZ1FXQkJUZjFoTTYvaWJHRit1L1NWQUs4OEZVTWp6Um9UQWZCZ05WSFNNRUdEQVdnQlRmMWhNNi9pYkdGK3UvU1ZBSzg4RlVNanpSb1RBUEJnTlZIUk1CQWY4RUJUQURBUUgvTUEwR0NTcUdTSWIzRFFFQkN3VUFBNElCQVFCZ3ZWYXU1KzJ3QXVDc21PeXlHMjhoMXp5QzRJUG1NbXBSWlRET3AvcExkd1hlSGpKcjhrRUMzbDkycUpFdmMrV0Fib0oxUm91Y0h5Y1VlN1JXaDJDNlpGL1dQQ0JMeVdHd25seXFHeVJNOS9qODZVSjFPZ2l1Wmw3a2w5enh3V29heFBCQ21IYTBSSG93ZFFCN0FWbHBxZzFjN0ZoS2poVUNCbUdUNFZlOHRWMGhkWnRyWm9RVis2eEhQYlVkMzdLVjFCMUJtZm8zbzRla29KS2hVdTk5RW8wM09wRTNKTHRNMTNBMUh4QUJFdVFHSFRJMHR5Y0RCQmRSbjNiMDNIb0loVTBWbnFqdnBWMUtQdnNyZ1lpLzBWU3RMTmV6WlBnR2UwZkczWGd5OHlla2RCOU5NVW4relpMQVRJNCt6OGo0UUg1V2o1WlBhVWt5b0FEMm9VSk8iXX0.eyJtZWRpYVR5cGUiOiJhcHBsaWNhdGlvbi92bmQuZG9ja2VyLmRpc3RyaWJ1dGlvbi5tYW5pZmVzdC52Mitqc29uIiwiZGlnZXN0Ijoic2hhMjU2OmM0NTE2YjhhMzExZTg1ZjFmMmE2MDU3M2FiZjRjNmI3NDBjYTNhZGU0MTI3ZTI5YjA1NjE2ODQ4ZGU0ODdkMzQiLCJzaXplIjo1MjgsInJlZmVyZW5jZXMiOlsicmVnaXN0cnkuZXhhbXBsZS5jb20vZXhhbXBsZTpsYXRlc3QiLCJyZWdpc3RyeS5leGFtcGxlLmNvbS9leGFtcGxlOnYxLjAiXSwiZXhwIjoxNjI4NTg3MTE5LCJpYXQiOjE1OTcwNTExMTksIm5iZiI6MTU5NzA1MTExOX0.MtQBOL2FERM2fMSikruHOMQdHuEXAE1wf6J6TfDY2W_7PfQQllBKbJJE0HqJ5ENAbuqNYHNZeIeKUCYFrNx2XgtrKuTe7WCa1ZZKDtp5bmANp484ekdl6lW23YB8r_SRtseJuibqjI3HuiMyELj9uYV1CdRYaD2BIZ_qxraYH1fMpjDWjehU4RYLI37hsSuDQ90o09BwaNfzbQXYPsGmkSUSmej7rOFPDnuwhNy4WcUed3kRKYEW8eIjO9OUBGQq3PWvhDjxZi3QF4QFDoiKBOXL70AjaiVIveQRkJI9-xHZSYwje9OFEMioeNWB5ceZR-r4L7VzDcU-Fxqjxn79Fw

If parsed,

{
    "typ": "x509",
    "alg": "RS256",
    "x5c": [
        "MIIDszCCApugAwIBAgIUL1anEU/yJy67VJTbHkNX0bBNAnEwDQYJKoZIhvcNAQELBQAwaTEdMBsGA1UEAwwUcmVnaXN0cnkuZXhhbXBsZS5jb20xFDASBgNVBAoMC2V4YW1wbGUgaW5jMQswCQYDVQQGEwJVUzETMBEGA1UECAwKV2FzaGluZ3RvbjEQMA4GA1UEBwwHU2VhdHRsZTAeFw0yMDA3MjcxNDQzNDZaFw0yMTA3MjcxNDQzNDZaMGkxHTAbBgNVBAMMFHJlZ2lzdHJ5LmV4YW1wbGUuY29tMRQwEgYDVQQKDAtleGFtcGxlIGluYzELMAkGA1UEBhMCVVMxEzARBgNVBAgMCldhc2hpbmd0b24xEDAOBgNVBAcMB1NlYXR0bGUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDkKwAcV44psjN8nno1eZ3zv1ZKUhJAoxwBOIGfIxIe+iHtpXLvFFVwk5Jbxu+Pkig2N4B3Ilrj/Vryi0hxp4mag02M733bXLRENSOFONRkslpO8zHUN5pYdnhTSwYTLap1+1bgcFSuUXLWieqZB6qc7kiv3bj3SPaf42+s48V49t/OpXxLtgiWL9XkuDTZctpJJA4vHHk6Ou0bcg7iGm+L1xwIfb8Ml4oWvT0SF35fgW08bbLXZ2v1XCLRsrWUgbq4U+KxtEpG3XIYcYhKx1rIrUhfEJkuHzgPglM11gG5W+Cyfg+wfOJig5q6axIKWzIf6C8m8lmy6bM+N5EsD9SvAgMBAAGjUzBRMB0GA1UdDgQWBBTf1hM6/ibGF+u/SVAK88FUMjzRoTAfBgNVHSMEGDAWgBTf1hM6/ibGF+u/SVAK88FUMjzRoTAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3DQEBCwUAA4IBAQBgvVau5+2wAuCsmOyyG28h1zyC4IPmMmpRZTDOp/pLdwXeHjJr8kEC3l92qJEvc+WAboJ1RoucHycUe7RWh2C6ZF/WPCBLyWGwnlyqGyRM9/j86UJ1OgiuZl7kl9zxwWoaxPBCmHa0RHowdQB7AVlpqg1c7FhKjhUCBmGT4Ve8tV0hdZtrZoQV+6xHPbUd37KV1B1Bmfo3o4ekoJKhUu99Eo03OpE3JLtM13A1HxABEuQGHTI0tycDBBdRn3b03HoIhU0VnqjvpV1KPvsrgYi/0VStLNezZPgGe0fG3Xgy8yekdB9NMUn+zZLATI4+z8j4QH5Wj5ZPaUkyoAD2oUJO"
    ]
}.{
    "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
    "digest": "sha256:c4516b8a311e85f1f2a60573abf4c6b740ca3ade4127e29b05616848de487d34",
    "size": 528,
    "references": [
        "registry.example.com/example:latest",
        "registry.example.com/example:v1.0"
    ],
    "exp": 1628587119,
    "iat": 1597051119,
    "nbf": 1597051119
}.[Signature]

JWS JSON Serialization

General JWS JSON serialization syntax is defined in RFC7515 Section 7.2.1.

Pros:

Well defined in RFC7515, RFC7518, RFC7519

Cons:

Security concerns on payload type.
- Resolved by signing cty header.

Here is an example:

Payload:

{
    "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
    "size": 525,
    "digest": "sha256:1b26826f602946860c279fce658f31050cff2c596583af237d971f4629b57792",
    "annotations": {
        "notary.v2.identity": "registry.wabbit.net/hello-world:1.0"
    }
}

Signed signature metadata:

{
    "alg": "RS256",
    "arl": "http://registry.wabbit.net/arl",
    "exp": "2021-09-20T16:02:40.3375379Z",
    "iat": "2021-06-22T16:02:40.3375379Z"
}

Complete JWS JSON Serialization:

{
    "payload": "ewogICAgIm1lZGlhVHlwZSI6ICJhcHBsaWNhdGlvbi92bmQuZG9ja2VyLmRpc3RyaWJ1dGlvbi5tYW5pZmVzdC52Mitqc29uIiwKICAgICJzaXplIjogNTI1LAogICAgImRpZ2VzdCI6ICJzaGEyNTY6MWIyNjgyNmY2MDI5NDY4NjBjMjc5ZmNlNjU4ZjMxMDUwY2ZmMmM1OTY1ODNhZjIzN2Q5NzFmNDYyOWI1Nzc5MiIsCiAgICAiYW5ub3RhdGlvbnMiOiB7CiAgICAgICAgIm5vdGFyeS52Mi5pZGVudGl0eSI6ICJyZWdpc3RyeS53YWJiaXQubmV0L2hlbGxvLXdvcmxkOjEuMCIKICAgIH0KfQ",
    "signatures": [
        {
            "protected": "ewogICAgImFsZyI6ICJSUzI1NiIsCiAgICAiYXJsIjogImh0dHA6Ly9yZWdpc3RyeS53YWJiaXQubmV0L2FybCIsCiAgICAiZXhwIjogIjIwMjEtMDktMjBUMTY6MDI6NDAuMzM3NTM3OVoiLAogICAgImlhdCI6ICIyMDIxLTA2LTIyVDE2OjAyOjQwLjMzNzUzNzlaIgp9Cg",
            "header": {
                "kid": "906ade40b96cff95e5b60f7e96f2cda7979c8ad5",
                "timestamp": "TimeStampToken/in/base64"
            },
            "signature": "r5ANOfLzS30CFId49egGiIQWcC-G_tX5dhsswigOUAGq1L2MIfuvV2xn4u8M33CJIbOM2e3doJSwdD6mI51y6A"
        }
    ]
}

If a JWS contains only one signature as above, the JWS can be flattened as

{
    "payload": "ewogICAgIm1lZGlhVHlwZSI6ICJhcHBsaWNhdGlvbi92bmQuZG9ja2VyLmRpc3RyaWJ1dGlvbi5tYW5pZmVzdC52Mitqc29uIiwKICAgICJzaXplIjogNTI1LAogICAgImRpZ2VzdCI6ICJzaGEyNTY6MWIyNjgyNmY2MDI5NDY4NjBjMjc5ZmNlNjU4ZjMxMDUwY2ZmMmM1OTY1ODNhZjIzN2Q5NzFmNDYyOWI1Nzc5MiIsCiAgICAiYW5ub3RhdGlvbnMiOiB7CiAgICAgICAgIm5vdGFyeS52Mi5pZGVudGl0eSI6ICJyZWdpc3RyeS53YWJiaXQubmV0L2hlbGxvLXdvcmxkOjEuMCIKICAgIH0KfQ",
    "protected": "ewogICAgImFsZyI6ICJSUzI1NiIsCiAgICAiYXJsIjogImh0dHA6Ly9yZWdpc3RyeS53YWJiaXQubmV0L2FybCIsCiAgICAiZXhwIjogIjIwMjEtMDktMjBUMTY6MDI6NDAuMzM3NTM3OVoiLAogICAgImlhdCI6ICIyMDIxLTA2LTIyVDE2OjAyOjQwLjMzNzUzNzlaIgp9Cg",
    "header": {
        "kid": "906ade40b96cff95e5b60f7e96f2cda7979c8ad5",
        "timestamp": "TimeStampToken/in/base64"
    },
    "signature": "r5ANOfLzS30CFId49egGiIQWcC-G_tX5dhsswigOUAGq1L2MIfuvV2xn4u8M33CJIbOM2e3doJSwdD6mI51y6A"
}

Dead Simple Signature Envelope (DSSE)

in-toto enhancement (ITE-5) introduces a SSL signing spec. This spec is inspired by PASETO, which is too opinionated. Later, this spec is evolved to Dead Simple Signature Envelope (DSSE) with its PAE() function updated.

Pros:

Simple.
Security decisions only depends on the authenticated fields.

Cons:

Less common.
Need to find the suitable algorithm according to the known keys by brute force

Example:

{
    "payload": "aGVsbG8gd29ybGQ=",
    "payloadType": "http://example.com/HelloWorld",
    "signatures": [
        {
            "keyid": "key id is optional",
            "sig": "y7BK8Mm8Mr4gxk4+G9X3BD1iBc/vVVuJuV4ubmsEK4m/8MhQOOS26ejx+weIjyAx8VjYoZRPpoXSNjHEzdE7nQ=="
        }
    ]
}

Red Hat's Simple Signing

Red Hat's simple signing format is intended for payloads. The payload format is adapted by atomic and later by cosign.

{
    "critical": {
           "identity": {
               "docker-reference": "testing/manifest"
           },
           "image": {
               "Docker-manifest-digest": "sha256:20be...fe55"
           },
           "type": "atomic container signature"
    },
    "optional": {
           "creator": "atomic",
           "timestamp": 1458239713
    }
}

It is a payload format not a signature format.

PKCS #7: Cryptographic Message Syntax (CMS)

PKCS #7: CMS is defined in RFC2315 and updated by RFC5652. The CMS is widely used for general digital signatures. For instances, RFC8551, NuGet.org.

The signature is stored in asn.1 DER binary format and optionally wrapped in PEM blocks.

Go Library: https://pkg.go.dev/go.mozilla.org/pkcs7

Pros:

Mature standard
Build-in signature attribute support
Build-in TSA support
Build-in CRL support

Cons:

Lack of stable Go library
Only supports certificates
- Many implementation only support X.509 certificates such as .net.

Recommendation

It is recommended to reuse existing signature format according the requirements. If there is no suitable candidate, extend the existing signature format for minimum viable product. If non of above meet the requirements, we may consider to design a new signature format.

JWS JSON Serialization

JWS JSON serialization meets our requirements.

Golang implementation is possible by combining

github.com/golang-jwt/jwt for signing / verifying JWT tokens.
github.com/shizhMSFT/go-jwsutil for JWS compact / JSON serialization conversion.
github.com/shizhMSFT/go-timestamp for timestamp request.
github.com/cloudflare/cfssl/crypto/pkcs7 for timestamp verification.
- Need ASN.1 BER to DER conversion.

Example by extending DSSE

The format is proposed by extending DSSE.

Payload:

{
    "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
    "size": 525,
    "digest": "sha256:1b26826f602946860c279fce658f31050cff2c596583af237d971f4629b57792",
    "annotations": {
        "notary.v2.identity": "registry.wabbit.net/hello-world:1.0"
    }
}

Signed signature metadata:

{
    "alg": "RS256",
    "arl": "http://registry.wabbit.net/arl",
    "exp": "2021-09-20T16:02:40.3375379Z",
    "iat": "2021-06-22T16:02:40.3375379Z"
}

Signature envelope:

{
    "payload": "ewogICAgIm1lZGlhVHlwZSI6ICJhcHBsaWNhdGlvbi92bmQuZG9ja2VyLmRpc3RyaWJ1dGlvbi5tYW5pZmVzdC52Mitqc29uIiwKICAgICJzaXplIjogNTI1LAogICAgImRpZ2VzdCI6ICJzaGEyNTY6MWIyNjgyNmY2MDI5NDY4NjBjMjc5ZmNlNjU4ZjMxMDUwY2ZmMmM1OTY1ODNhZjIzN2Q5NzFmNDYyOWI1Nzc5MiIsCiAgICAiYW5ub3RhdGlvbnMiOiB7CiAgICAgICAgIm5vdGFyeS52Mi5pZGVudGl0eSI6ICJyZWdpc3RyeS53YWJiaXQubmV0L2hlbGxvLXdvcmxkOjEuMCIKICAgIH0KfQ==",
    "payloadType": "application/vnd.cncf.notary.v2.descriptor",
    "signatures": [
        {
            "keyid": "906ade40b96cff95e5b60f7e96f2cda7979c8ad5",
            "metadata": "ewogICAgImFsZyI6ICJSUzI1NiIsCiAgICAiYXJsIjogImh0dHA6Ly9yZWdpc3RyeS53YWJiaXQubmV0L2FybCIsCiAgICAiZXhwIjogIjIwMjEtMDktMjBUMTY6MDI6NDAuMzM3NTM3OVoiLAogICAgImlhdCI6ICIyMDIxLTA2LTIyVDE2OjAyOjQwLjMzNzUzNzlaIgp9Cg==",
            "timestamp": "TimeStampToken/in/base64",
            "sig": "pi6YujSNkb4X1h81++AQpchnCEz9gtVXGICq/VG+4B1b8BemrVN18jRymesq9DEATHvIBJzvIK2OaLxKlZufdg=="
        }
    ]
}

[PB]Example using JWS JSON Serialization

The format is proposed using JWS JSON Serialization.

Payload:

{
    "notary.v2": { 
        "subjectManifest": {
            "mediaType": "application/vnd.oci.image.manifest.v1+json",
            "digest": "sha256:73c803930ea3ba1e54bc25c2bdc53edd0284c62ed651fe7b00369da519a3c333",
            "size": 16724,
            "annotations": {
                "org.acme-rockets.importDate": "2021-04-23T18:25:43.511Z"
          }
        },
        "signedAttrs": {
            "reserved": {
                "arl": "http://registry.wabbit.net/arl",
                "identity": "acme-rockets.io/net-monitor:v1"
            },
            "custom" : {
                "buildId": "0001",
                "imageScanned": "true"
            }
        }
    },
    "iat": "2021-06-22T16:02:40.3375379Z",
    "exp": "2021-09-20T16:02:40.3375379Z"
}

Payload contain the subject manifest and other attributes that has to be integrity protected.

notary.v2: Top level node and private claim, encapsulating the notary v2 data.
In order to leverage JWS claims functionality provided by libraries we have defined iat, exp as top level nodes.
subjectManifest: The image manifest that needs to be integrity protected.
signedAttrs: The additional metadata that needs to be signed.
- reserved: The signed attributes reserved for notary v2 use such as issuedAt(iat), expiration Time(exp), artifact revocation list(arl), etc.
- custom: The user defined signed attributes such as buildId, imageScanned, etc.
To start with we will only support iat, exp and notary.v2 claim. PB[add required and optional claims]

ProtectedHeader:

{
    "alg": "RS256",
    "cty": "application/<TBD>" 
}

JWS needs alogrithm(alg) to be present in header so we have added it as protected header.
cty: Content type used to declare the media type of the secured content(the payload)

SignatureEnvelope:

{
    "payload": "<Base64Url(Payload)>",
    "protected": "<Base64Url(ProtectedHeader)>"
    "header": {
      "timestamp": "<Base64Url(TimeStampToken)>",
      "kid": "906ade40b96cff95e5b60f7e96f2cda7979c8ad5",
      "x5c": ["<Base64(DER(leafCert))>", "<Base64(DER(intermediateCACert))>", "<Base64(DER(rootCert))>"]
    },
    "signature": "Base64Url( sign( ASCII( <Base64Url(Payload)>.<Base64Url(ProtectedHeader)> )))"  
}

protected: Base64Url encoded JSON object that contains the header parameters that are integrity
protected by the JWS Signature digital signature
header: JOSE Header containing the parameters describing the cryptographic
operations and parameters employed. header is not integrety protected by signature. To start with we will only support reserved set of headers. TODO: Fail the signature if contains extra header?
- timestamp: Base64Url encoded timestamp token generated by TSA.
- kid Hint indicating which key was used to generate the signature.
- x5c contains the X.509 public key certificate or certificate chain corresponding to the key used to used to generate the signature. If signature was generated by x509 certificate signature envelop must contain x5c
In case of x5c the leaf certificate's signing algorithm(with some additional conventions [TODO: add convention]) will be used for signature and this algorithm will be value of alg header. The verifier will make sure that the value of alg is same as that of leaf certificate's signing algorithm.

[PB] Example using DSSE

The format is proposed using extended version of DSSE.

Payload:

{ 
    "subjectManifest": {
        "mediaType": "application/vnd.oci.image.manifest.v1+json",
        "digest": "sha256:73c803930ea3ba1e54bc25c2bdc53edd0284c62ed651fe7b00369da519a3c333",
        "size": 16724,
        "annotations": {
            "org.acme-rockets.importDate": "2021-04-23T18:25:43.511Z"
      }
    },
    "signedAttrs": {
        "reserved": {
            "iat": "2021-06-22T16:02:40.3375379Z",
            "exp": "2021-09-20T16:02:40.3375379Z",
            "arl": "http://registry.wabbit.net/arl",
            "identity": "acme-rockets.io/net-monitor:v1"
        },
        "custom" : {
            "BuildId": "0001",
            "imageScanned": "true"
        }
    }
}

SignatureEnvelope:

{
    "payload": "<Base64(Payload)>",
    "payloadType": "application/<TBD>",
    "signatures": [
        {
            "keyid": "906ade40b96cff95e5b60f7e96f2cda7979c8ad5",
            "x5c": ["<Base64(DER(leafCert))>", "<Base64(DER(intermediateCACert))>", "<Base64(DER(rootCert))>"],
            "timestamp": "<Base64(TimeStampToken)>",
            "sig": "Base64( sign( <Base64(Payload)> ))"
        }
    ]
}

In SignatureEnvelope's signatures node user can either specify keyid or x5c. Currently DSSE doesn't support timestamp and x5c fields.

Open Questions

In Payload do we need subjectManifest#annotations? As we have already defined signedAttrs#custom node for user specific metadata?
Should signature varification fail if signature envelop contains unsupported fields?

Prototype scope [Draft]

Prototype
- Use defined payload format
- Verify including
  - Cert chain validation
    - Exclude revocation check
- TSA signature
- Signature expiry
- ARL field (placeholder)
  - Exclude ARL check
- Custom signed attributes (wrapped payload)
- Types of keys (different x5c)
  - RSA
  - ECDSA
  - EdDSA?

References

Steve Lasker

2021/06/16 21:16:43

- The signing algorithm MAY be indicated in the signed sig

Can we add MAY contain an artifactType to be consistent with the new manifest types? (Edited)

Shiwei Zhang

2021/06/17 01:00:41

Changing the descriptor spec is hard. We can put the artifactType field in the annotations field.

Milind

2021/06/17 00:14:00

Does this definition hold for detached signatures too? (Edited)

2021/06/17 00:36:41

No. No detached signatures allowed.

2021/06/23 00:00:01

I meant detached with respect to subject manifest.

2021/06/17 00:15:06

A signature envelope MUST contain one and only one complete signature.

Are multiple signatures contained in a single envelope when an image is signed multiple times? (Edited)

2021/06/22 09:04:38

Correct.

2021/07/02 14:59:30

I don't beleive we have a multiple signature scenario that gets captured in one file. Multiple entities can sign a single artifact, but they are each individual signatures (wabbit networks, docker, acme rockets, )

2021/06/17 00:16:17

- The sign

Can you define Artifact origin or give an example (Edited)

2021/06/17 01:06:08

Consider put the artifact origin to the `annotations` field as a structured annotation

2021/06/17 00:20:01

MUST instead of SHOULD? Are there cases where we can't include a signing timestamp? (Edited)

2021/06/17 01:09:26

Changed to MUST

2021/06/17 00:36:17

- Consumes th

It's not clear which area has the complexity and how it impacts us. (Edited)

2021/06/17 00:37:03

Consumes the header before authenticating. - Verifiers can be tricked into MAC algorithms instead of asymmetric key signing.

Would like to understand this better. (Edited)

2021/06/22 09:23:25

Provided an example

2021/06/17 00:39:35

Signature may contain customer defined metadata (Edited)

2021/06/17 00:55:32

Customer defined metadata can go to the `annotations` field.

2021/06/22 19:10:44

The metadata can be per signature, annotations are associated with the target manifest.

2021/07/02 14:40:21

Can we identify some customer-defined usec ases for metadata? (Edited)

2021/06/17 00:40:14

Need to find the suitable algorithm according to the known keys by brute force

This was unclear to me, lets discuss (Edited)

2021/06/17 00:41:30

JWT

How does this contrast with JWS? (Edited)

2021/06/22 09:22:50

You may view JWT as an abstract class of JWS

Ian M

2021/06/17 00:46:29

Can we prescribe what is the required or acceptable implementations? (Edited)

2021/06/17 01:00:57

Formats

Should CMS be considered as an option https://datatracker.ietf.org/doc/html/rfc5652 (Edited)

2021/06/17 01:29:41

Too complex

Sajay Antony

2021/06/17 01:21:32

Would you be able to provide a rough sample which can help the discussion easier? (Edited)

2021/06/17 01:43:22

I will provide a rough sample

Michael Brown

2021/06/17 21:59:06

signature

I'm not sure what this mean. What's the delta between this and whichever requirements aren't being satisfied? (Edited)

mnm678

2021/06/17 22:20:08

The algorithm is supposed to be specified when the key is distributed so that it is not contained in unsigned metadata, and can be known before verification (Edited)

2021/06/17 22:21:48

Example: ```json { "payload"

There's also a go implementation for in-toto: https://github.com/in-toto/in-toto-golang/pull/101 (Edited)

2021/06/22 09:26:57

Removed the cons

2021/06/17 22:25:18

The signing algorithm MAY be indicated in the signed signature metadata.

Why? The signing algorithm needs to be known before verification of the signature, so this is the same as having an unauthenticated signing algorithm. For security, it's better to ensure that the signing algorithm is distributed along with the trusted key so that it cannot be interfered with. (Edited)

2021/06/22 09:19:10

I am also considering the same thing. That's why I have the supplied statement that the hint may be ignored by the verifier.

Dan Lorenc

2021/06/18 00:01:06

In Cosign, simple signing is the "thing that is signed", or the payload. The equivalent here in this proposal is the OCI Descriptor (which I actually prefer and want to switch to in cosign as well). (Edited)

2021/06/18 00:02:21

Cosign just embeds all the signature format information inside a few separate fields of an existing OCI descriptor. You can see a bit more here: https://github.com/sigstore/cosign/blob/main/SPEC.md I proposed this switch for nv2 back in February here: https://github.com/notaryproject/nv2/issues/40 (Edited)

2021/06/18 13:39:30

- The

I would drop this to a MAY. The verifier is the one that knows whether the artifact has been copied, mirrored or moved around - not the publisher/signer. (Edited)

mtrmac

2021/06/18 15:06:33

If we need to add fields that are not in the spec, and there is the `urls` field that we don’t really want (and don’t want consumers to interpret) and changing the spec is hard, that seems like a good reason not to use the spec? (Edited)

2021/06/22 09:06:58

Agreed. We only use a subset of the descriptor spec.

2021/06/22 09:07:35

If `urls` are provided, the verifiers should ignore that field.

2021/06/18 15:08:02

Same question - not where to put it but _what it means_. Is “origin” the host name of the internal build host signing this? If not, what does it mean? “identity of the thing being signed” makes a lot of sense to me, but that’s not an origin. (Edited)

2021/06/22 09:15:10

“identity of the thing being signed” sounds better. Changed "origin" to "identity"

Brandon Mitchell

2021/06/18 15:09:30

I'm also trying to understand what the origin is and how it would be verified. Seems like the signing key and certificate chain would be the only thing that needs verification. (Edited)

2021/06/18 15:10:25

Simple signing currently wraps this in an OpenPGP signature, or hypothetically in a X.509 format or possibly something else. Simple signing is not in the business of cryptographically dealing with untrusted data and being resistant to side-channel attacks, or whatever; it farms that out to a pre-existing widely-used (and hopefully good) implementation, and only handles a payload after it has been authenticated by that implementation. (Edited)

2021/06/18 15:11:39

- There is a concern on the signing algorithm not matching

How would the algorithm be ignored? Does the verification have a different way to know the needed algorithm, and if so, shouldn't that be used in favor of the signature provided data? (Edited)

2021/06/22 09:21:56

The algorithm might be tied to the verification key.

2021/06/18 15:13:21

I’m not at all happy about designing a new “envelope”; it’s taking on difficult work that is not Notary-specific and with no specific reason for Notary to do something different from everyone else. We don’t need to be cryptographically dealing with untrusted data and being resistant to side-channel attacks, and the like – and we don’t need the paperwork for the new envelope format to be acceptable to governments as _correctly_ using approved algorithms. (Edited)

2021/06/18 15:19:03

Agreed, my preference is to avoid reinventing the wheel.

2021/06/18 15:13:26

It would help if we separate out requirements of what goes into the signature vs. attributes we expect from the signature format. (Edited)

2021/06/18 15:14:11

Example: ``` eyJ0eXAiOiJ4NTA5IiwiYWxnIjoiUlMyNTYiLCJ4NWMiO

Is efficiency a requirement? Presumably this step is performed shortly before transferring 10s to 100s of MB between the client and registry. (Edited)

2021/06/18 15:14:41

urrent implementation relies on [docker/libtrust](https://github.com/docker/libtrust), which is archived.

We should be able to use a different implementation or fork from this repo. (Edited)

2021/06/18 15:16:11

This variant may not be compatible with all existing libraries.

We shouldn't be comparing a single implementation of an option vs any theoretical implementation of other options. (Edited)

2021/06/18 15:28:22

Links to conversations about “signing tags” and “world-wide identity” (signing expected-vendor/mysql:10.0 vs. some-other-vendor/mysql:0.0.1-testing) (Edited)

2021/06/18 15:30:29

- The signing algorithm MAY be indicated in the signed signature metadata.

Consider adding an optional list of tags being signed in addition to the descriptor. (Edited)

2021/06/22 09:05:23

It goes to the `annotations` field.

2021/06/18 15:37:35

https://github.com/notaryproject/nv2/discussions/31 (Edited)

2021/06/18 15:44:20

@mtrmac do you have a recommendation we could discuss as a potential option. (Edited)

mnltejaswini

2021/06/18 16:59:18

A complete signature $\Sigma$ can be viewed as a signature envelope $\varepsilon_1$.

A complete signature is viewed as ε1 , does this imply that the envelope will have only one signature? (Edited)

2021/06/22 09:02:50

No, it's the other way around. The envelope can have many signatures. You may think a complete signature is a special case of the signature envelope where n = 1.

2021/06/22 15:23:22

So there are three terms here, complete signature, signature envelope and the actual signature. So the complete signature is an envelope with one signature? Sorry, if I am missing any cryptography jargon, what does complete mean here? (Edited)

2021/06/18 17:14:21

For my clarification, m is the original payload that will be signed? (Edited)

2021/06/22 08:58:14

m is not the original payload (i.e. the manifest) but its metdata such as its descriptor.

2021/06/22 15:31:24

I understand, original payload doesn't mean the actual data blob, here it is the json descriptor. In the expression $\Sigma = (m, \mu, \hat\mu, \sigma) \gets \mathbf{Sign}(sk, m)$ both left hand and right hand side share the same variable "m" so there is no change in the state of m before and after signing. "signed payload m" means the payload "m" that will be signed

2021/06/18 17:15:17

Signed signature metadata

What is the difference between signed/unsigned signature metadata? does that mean metadata will also be included for signing or does it mean it is a signature metadata? (Edited)

2021/06/22 08:59:42

signed signature metadata are signed / authenicated by the signing key. Therefore, no one except the signer can change its value.

2021/06/22 09:00:15

unsigned signature metadata is not protected, and can be changed by anyone.

2021/06/18 17:17:35

Is the descriptor of the payload also signed? (Edited)

2021/06/22 09:09:44

The descriptor of the manifest is in the payload. The payload will be signed.

2021/06/22 21:26:59

```json { "payload": "ewogICAgIm1lZGlhVHlwZSI6ICJhcHBsaWNhdGlvbi92bmQuZG9ja2VyLmRpc3RyaWJ1dGlvbi5tYW5pZmVzdC52Mitqc29uIiwKICAgICJzaXplIjogNTI1LAogICAgImRpZ2VzdCI6ICJzaGEyNTY6MWIyNjgyNmY2MDI5NDY4NjBjMjc5ZmNlNjU4ZjMxMDUwY2ZmMmM1OTY1ODNhZjIzN2Q5NzFmNDYyOWI1Nzc5MiIsCiAgICAiYW5ub3RhdGlvbnMiOiB7CiAgICAgICAgIm5vdGFyeS52Mi5pZGVudGl0eSI6ICJyZWdpc3RyeS53YWJiaXQubmV0L2hlbGxvLXdvcmxkOjEuMCIKICAgIH0KfQ==", "payloadType": "application/vnd.cncf.notary.v2.descriptor", "signatures": [ { "keyid": "906ade40b96cff95e5b60f7e96f2cda7979c8ad5", "metadata": "ewogICAgImFsZyI6ICJSUzI1NiIsCiAgICAiYXJsIjogImh0dHA6Ly9yZWdpc3RyeS53YWJiaXQubmV0L2FybCIsCiAgICAiZXhwIjogIjIwMjEtMDktMjBUMTY6MDI6NDAuMzM3NTM3OVoiLAogICAgImlhdCI6ICIyMDIxLTA2LTIyVDE2OjAyOjQwLjMzNzUzNzlaIgp9Cg==", "timestamp": "TimeStampToken/in/base64", "sig": "pi6YujSNkb4X1h81++AQpchnCEz9gtVXGICq/VG+4B1b8BemrVN18jRymesq9DEATHvIBJzvIK2OaLxKlZufdg==" } ] } ```

How is this metadata included in the signature? I don't think this is part of the SSL spec. (Edited)

2021/06/23 00:43:17

This example is an extension to the SSL spec. The metadata is base64 encoded like the payload.

2021/06/23 00:09:01

I'm not sure if the signature envelope definition is relevant. (Edited)

2021/06/23 00:14:56

What is the purpose of the annotations field? Are any of these attributes used in validation? (Edited)

2021/06/23 00:16:01

What is the purpose of this attribute? (Edited)

2021/06/23 00:20:01

- The thumbprint of the signing certificate MAY be indicated in the unsigne

Should this be MUST? How will be verification component know the certificate chain if this is not present? (Edited)

2021/06/23 00:28:46

Which aspects are complex and how do they impact us? (Edited)

2021/06/23 00:29:26

## Recommendation

Can you provide an example here, and the impact of inconsistent encoding? (Edited)

2021/06/23 14:27:45

The problem is that if it's included, some people will use the one that's listed, and if an attacker changes this algorithm, it can invalidate the security of the signature. An example of this attack is described here: https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/ (Edited)

2021/06/25 14:47:10

Artifact identity MAY be indicated in the payload.

We should clarify the purpose of this attribute. (Edited)

2021/06/25 14:49:13

SHOULD verify the origin against the signer.

This specifies a mechanism to achieve something, what is the associated requirement? (Edited)

2021/06/29 05:42:47

What is the proposal for indicating this identity? Who identity is being indicated? (Edited)

2021/07/02 16:10:21

```json { "alg": "RS256", "arl": "http://registry.wabbit.net/arl", "exp": "2021-09-20T16:02:40.3375379Z", "iat": "2021-06-22T16:02:40.3375379Z" } ```

The algorithm should be transmitted with the key, not put in the metadata. This leaves it open for various attacks, including: https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/, https://github.com/google/security-research/security/advisories/GHSA-wqgp-vphw-hphf, https://github.com/theupdateframework/notary/blob/master/docs/resources/ncc_docker_notary_audit_2015_07_31.pdf (Edited)

2021/07/08 00:55:32

Build-in TSA support -

If TSA is typically in this format then wouldn't this be the format of choice? (Edited)

2021/07/08 01:14:12

- *Signature format SHOULD be easy to implement using existing Go libraries(Docker CLIs are developed in Go).*

Make it SHOULD? (Edited)

2021/07/09 15:22:20

This requirement is essential for TSA._ To time stamp a signature, the original signature must be generated first and then sent to a TSA for time stamping. Once obtained the timestamp signature, it will be attached to the original signature.

I don't see this as a requirement when dealing with content stored on a registry. If there's separate content being uploaded, it can be a separate blob, or a different field of an overarching "signature blob" layout. (Edited)

2021/07/20 00:44:29

``json { "payload": "<Base64Url(Payload)>", "protected": "<Base64Url(ProtectedHeader)>" "header": { "timestamp": "<Base64Url(TimeStampToken)>", "kid": "906ade40b96cff95e5b60f7e96f2cda7979c8ad5", "x5c": ["<Base64(DER(leafCert))>", "<Base64(DER(intermediateCACert))>", "<Base64(DER(rootCert))>"] }, "signature": "Base64Url( sign( ASCII( <Base64Url(Payload)>.<Base64Url(ProtectedHeader)> )))" } ```

Why does the signed metadata present in the `header`? (Edited)

2021/07/20 00:45:53

`json {

1. Will annotations be used for customer specified key-value pairs? 2. How do we differentiate between customer defined kv vs standard ones like notary.v2.identity? 3. Are there any size limitations of number of annotations that can be supported? (Edited)

2021/07/20 00:46:55

A2: Standard ones will have standard labels.

2021/07/20 00:47:51

A3: That's a good question. Do we even have an official size limit for manifests in the registry?

Pritesh Bandi

2021/07/20 00:49:28

A3.. Unless we have limit on size of signature envelop we can support any number of annotations.

2021/07/20 00:47:37

``json { "alg": "RS256",

How is this different from kid ? (Edited)

2021/07/20 00:48:24

I think the key here means annotation keys, not signing keys.

2021/07/20 00:48:49

what does annotation keys mean?

2021/07/20 00:48:26

`header` contains all the headers(protected+unprotected). The `protected` includes the header elements that we want to be integrity protected (Edited)

2021/07/20 00:49:55

I think the first statement is valid in memory when parsing it. Otherwise, it does not make sense to have duplicated headers.

2021/07/20 00:53:48

See https://datatracker.ietf.org/doc/html/rfc7515#section-7.2.1

2021/07/20 00:54:02

Yep, i agree on reading more i think we we wont need protected headers in the headers section

2021/07/20 00:49:32

We probably should avoid using alg as much as possible, discover alg from x5c or from nv2 library defined mapping in cases where partial algorithm is available, e.g. encryption alg is present but hashing is not. (Edited)

2021/07/20 00:50:47

We may not need signed key of we use annotations for custom kv pairs. (Edited)

2021/07/20 00:52:07

Is exp signature expiry, and iat signature time? Do JWS libraries validate the sign using these header attributes?. (Edited)

2021/07/20 00:55:09

Yes, those fields are standard fields. However, the implementations varies. I can't remember if golang-jwt verifies exp or not.

2021/07/20 00:52:16

I am trying to understand the use case of including annotations in the payload (from E2E , let's assume in k8, when we are trying to verify authenticity of the image being pulled, will these annotations be used? for any other custom key-value pairs that needs integrity and authenticity, do we need to include them in the signed metadata section? (Edited)

2021/07/20 00:53:54

How does anyone know the TSA server that is used to obtain this timestamp? Is it needed? (Edited)

2021/07/20 00:54:29

JWS defines a number of ways keys can be specified - kid, jku, x5c, x5u etc. We should define which ones we will support. (Edited)

2021/07/20 00:54:55

Is the format of this exp and other time related claims an agreement between client and server or is it standard? I have seen different formats for these claims (Edited)

2021/07/20 00:57:20

See https://www.rfc-editor.org/rfc/rfc7519.html#section-4.1

2021/07/20 00:56:02

The x5c example can show [leaf, intermediate ..., root] (Edited)

2021/07/20 00:59:51

Agree,

2021/07/20 00:56:23

Can we standardize reserving a claim (something like critical ) in the signed metadata to include some mandatory claims that are specific to cloud providers (Edited)

2021/07/20 00:57:16

We need to define what media types can be signed for nv2, as I understand it can be image manifest and image index manifest, its that correct? (Edited)

2021/07/20 00:59:35

Can we key name like "notary.v2" instead of "annotations" for reserved attributes? (Edited)

2021/07/20 00:59:57

```json { "payload": "<Base64(Payload)>", "payloadType": "application/<TBD>", "signatures": [

Discuss about payloadType value (Edited)

2021/07/20 01:01:03

Definitely, it is not a "application/vnd.cncf.notary.v2.descriptor"

2021/07/20 01:02:02

Is there a need for payload type (like DSSE) or version headers? (Edited)

2021/07/20 01:41:18

Existing claim cty

2021/07/20 01:34:36

https://github.com/golang-jwt/jwt (Edited)

2021/07/21 14:41:27

Change "When" to "If" (Edited)

2021/07/21 14:42:52

MUST

Should we make it `SHOULD`? If the signature is for internal use, a key id / thumbprint is sufficient as certs may exist locally. (Edited)

Notary V2 - Signature Format

tags: notary

Definition

Requirements

Payload

Signature

Signature Format

Existing Formats

JWT variant

JWS JSON Serialization

Dead Simple Signature Envelope (DSSE)

Red Hat's Simple Signing

PKCS #7: Cryptographic Message Syntax (CMS)

Recommendation

JWS JSON Serialization

Example by extending DSSE

[PB]Example using JWS JSON Serialization

[PB] Example using DSSE

Open Questions

Prototype scope [Draft]

References

Read more

Notary Security Topics

tags: `notary`