[OLD] [Draft] Notary V2 - Signature Format

Notary Issue #86

[OLD] [Draft] Notary V2 - Signature Format

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

Terminology

SignatureEnvelope(
$ε$ ): The standard data structure for storing a signed message. Signature envelope consist of following components:
- Payload(
  $m$ ): The data that is integrity protected - e.g. container image descriptor.
- Signed attributes(
  $μ$ ): The signature metadata that is integrity protected - e.g. signature expiration time, signing time, etc.
- Unsigned attributes(
  $\hat{μ}$ ): The signature metadata that is not integrity protected - e.g. keyid, publickey, etc.
- Cryptographic signatures(
  $s$ ): The digital signatures computed on payload and signed attributes.
A signature
$s = S i g n ($ K_priv,
$m, μ)$ where K_priv stands for signing key. A signature envelope
$ε = {m, (s_{0}, μ_{0}, {\hat{μ}}_{0}), \dots, (s_{n - 1}, μ_{n - 1}, {\hat{μ}}_{n - 1})}$ is a compact form of
$n$ signatures signing the same payload
$m$ .

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 →

Requirements

Signature Envelope and Signature

The signature envelope payload MUST contain a descriptor of the target manifest.
1. A descriptor MUST contain mediaType, digest, size fields.
2. A descriptor MAY contain the artifactType field for artifact manifests, or the config.mediaType for oci.image based manifests.
3. descriptor MAY contain a annotations field.
The signature envelope MUST be self contained to validate the integrity of the payload and signed attributes.
The signature envelope MAY contain arbitrary user supplied information, as key value pairs. If included, it MUST be integrity protected.
The signature envelope MAY contain information to determine the signature expiration time. If included, it MUST be integrity protected.
The signature envelope MAY contain information to determine the signature revocation status. If included, it MUST be integrity protected.
The signature MUST be detached a signature, with respect to the target manifest being signed.
The signature MUST be stored and transferred in a signature envelope.
If the signature was produced by a X.509 certificate, the signature MUST contain a certificate chain of the signing certificate as an unsigned attribute. This MAY be a partial certificate chain.
The signature MAY be timestamped by TSA, and this counter signature MUST be stored as an unsigned attribute.

Signature Format

The signature format MUST be able to store payload.
The signature format MUST be able to store cryptographic signature.
The signature format MUST support referencing and in-lining of different signing identity types represnted as keyIds or X.509 certificate chains.
The signature format MUST be able store unsigned signature attributes such as timestamp signature(TSA).
Signature format SHOULD be easy to implement using existing Go libraries (Docker CLI is implemented in Go).
The signature format MAY be able store signed attributes. In case signature format doesn't support signed attributes, they 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.
The signature format MAY store multiple signatures generated using same or different cryptographic materials(signing identity types and signing algorithms)
The signature format SHOULD NOT indicate signing algorithm, if present it MUST be a signed attribute. (There are concerns on the signing algorithm not matching the verification key, see CS-DRNT15-1 Section 3.3, A cross-protocol attack on the TLS protocol, secure-systems-lab/dsse#35)

Signature Formats Explored

JWS Compact Serialization (JWT) - RFC7515 Section 3.1

Notary v2 prototype2 shows JWS compact serialization.

Pros:

Widely used in systems such as OpenId.
Signing libraries available in Go: golang-jwt/jwt, square/go-jose, lestrrat-go/jwx.
Native support for certificate(s) and keyid.
Native support for signed attributes.

Cons

Has a history of vulnerable implementations due to the complexity and lack of specificity in the RFC. Vulnerabilities example: algorithm substitution attack, bypassing signature verification by setting alg=none.
Does not support unsigned attributes which means we cannot timestamp signature.
As alg is a required header, implementing a format which instead gets the signing algorithm from the certificate, key store or application mapping, requires workarounds.
Supports a single signature in an envelope.

#### Example (Click to show details)

Payload: aka claims

{
    "notary.v2": { 
        "subjectManifest": {...},
        "signedAttrs": {
            "reserved": {...},
            "custom" : {...}
        }
    },
    "iat": "1624377760337",
    "exp": "1632153760337"
}

ProtectedHeader:

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

SignatureEnvelope:

 <Base64Url(ProtectedHeader)>.<Base64Url(Payload)>.Base64Url( sign( ASCII(<Base64Url(ProtectedHeader)>.<Base64Url(Payload)> )))

JWS JSON Serialization - RFC7515 Section 3.2

Pros:

JWS is an IETF proposed (RFC 7515) standard with guidance around representation, serialization and verification.
Signing libraries available in Go: square/go-jose, lestrrat-go/jwx.
Native support for certificate(s) and keyid.
Native support for signed and unsigned attributes.
Supports multiple signatures in the same envelope.

Cons:

Has a history of vulnerable implementations such as algorithm substitution attack, bypassing signature verification by setting alg=none. Some of the main concerns raised for JWS, can they be addressed with additional layer of validation on top of core libraries.
As specification is complex and lacks specificity, there is probability of user shooting themselves in the foot with incorrect implementation, or insufficient validations.

#### Example (Click to show details)

Payload: aka claims

{
    "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": "1624377760337",
    "exp": "1632153760337"
}

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. This claim MUST be present.
subjectManifest: The image manifest that needs to be integrity protected.
signedAttrs: Contains additional attributes that needs to be integrity protected.
- reserved: Collection of attributes reserved for notary v2 use such as artifact revocation list(arl),identity, etc.
- custom: Collection of user defined attributes such as buildId, imageScanned, etc. Use of this field is OPTIONAL.
iat: Issued at identifies the time at which the JWT was issued. This claim MUST be present.
exp: Expiration time identifies the expiration time on or after which the JWT must not be accepted for processing. This claim MUST be present.
In order to leverage JWS claims validation functionality already provided by libraries we have defined iat, exp as top-level nodes.

ProtectedHeader:

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

alg: JWS needs algorithm(alg) to be present in header so we have added it as protected header. This header MUST be present.
cty: Content type(cty) used to declare the media type of the secured content(the payload). This header MUST be present.
crit: Indicates the list of headers that implementation MUST understood and process. This header MUST be present.

SignatureEnvelope:

{
    "payload": "<Base64Url(Payload)>",
    "signatures": [
        {
            "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)> )))"  
        }
    ]
}

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

{
    "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(ProtectedHeader)>.<Base64Url(Payload)> )))"  
}

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 integrity protected by signature. To start with we will only support reserved set of headers.
- timestamp: Base64Url encoded timestamp token generated by TSA. Use of this is OPTIONAL.
- kid Hint indicating which key was used to generate the signature. Use of this is OPTIONAL.
- x5c Contains the X.509 public key certificate or certificate chain corresponding to the key used to generate the signature. Use of this is OPTIONAL. If signature was generated by x509 certificate signature envelop MUST contain x5c.
The header node MUST contain either kid or x5c but not both.
In case of x5c, the leaf certificate's public key algorithm(with some additional conventions) will be used for signature generation and this algorithm must match with alg header value. The verifier will make sure that the value of alg header is same as that of leaf certificate's signing algorithm.
- Additional convention for algorithm: If the x509 certificate does not indicate the hash algorithm (as is the case of ECDSA), then the implementation will use hard-code a mapping similar to that of JWS.
Implementation should only support predefined set of asymmetric signing algorithms, which means value of alg will always be from a predefined set of values.

Dead Simple Signature Envelope (DSSE)

Pros:

Simple, lesser probability of user shooting themselves in the foot.
Signing libraries available in Go: in-toto-golang.

Cons:

No published RFC(or draft) and not commonly used. Only known usage is in-toto and that implementation also diverges from specification, see.
No native support for signed attributes but we can add them to the payload, by creating a wrapped payload that includes original payload and other attributes to be signed.
No native support for inlining of certificate(s). See dsse/issues/42
Support for timestamp is under consideration. See dsse/issues/33

#### Example (Click to show details)

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))>"],   // field not supported
            "timestamp": "<Base64(TimeStampToken)>",   // field  under consideration 
            "sig": "Base64( sign( <Base64(Payload)> ))"
        }
    ]
}

In SignatureEnvelope's signatures node, MUST contain either keyid or x5c but not both.

PKCS 7: Cryptographic Message Syntax (CMS) - RFC2315, RFC5652

Pros:

Widely used and battle tested, one of the mature standards.
Native support for signed and unsigned attributes.
TSA timestamp signatures are in PKCS7 format so system will need to understand only one signing format.

Cons:

Lack of stable Go library and it's not straight forward to implement the specification. mozilla.org/pkcs7
Closely tied to X509 certificates, no provision for supporting raw signing key.

#### Example (Click to show details)

The signature is stored in ASN.1 DER binary format and optionally wrapped in PEM blocks. Payload aka eContent

{
    "notary.v2": { 
        "subjectManifest": {...},
        "signedAttrs": {
            "reserved": {...},
            "custom" : {...}
        }
    }
}

signedAttrs:

"signingTime": "2021-06-22T16:02:40.3375379Z",
"expirationTime": "2021-09-20T16:02:40.3375379Z",
"cmsAlgorithmProtection": "..."

unsignedAttrs:

"timestamp": "...."

Signature Envelope:

ContentInfo ::= SEQUENCE {
  contentType ContentType,
  content [0] SignedData }

  ContentType ::= OBJECT IDENTIFIER

  SignedData ::= SEQUENCE {
    version CMSVersion,
    digestAlgorithms DigestAlgorithmIdentifiers,
    encapContentInfo EncapsulatedContentInfo,
    certificates [0] IMPLICIT CertificateSet OPTIONAL,
    crls [1] IMPLICIT RevocationInfoChoices OPTIONAL,
    signerInfos SignerInfos }

      CMSVersion ::= INTEGER{ v0(0), v1(1), v2(2), v3(3), v4(4), v5(5) }
    
      DigestAlgorithmIdentifiers ::= SET OF DigestAlgorithmIdentifier

      EncapsulatedContentInfo ::= SEQUENCE {
        eContentType ContentType,
        eContent [0] EXPLICIT OCTET STRING OPTIONAL }

      SignerInfos ::= SET OF SignerInfo

      SignerInfo ::= SEQUENCE {
        version CMSVersion,
        sid SignerIdentifier,
        digestAlgorithm DigestAlgorithmIdentifier,
        signedAttrs [0] IMPLICIT SignedAttributes OPTIONAL,
        signatureAlgorithm SignatureAlgorithmIdentifier,
        signature SignatureValue,
        unsignedAttrs [1] IMPLICIT UnsignedAttributes OPTIONAL }


        SignerIdentifier ::= CHOICE {
          issuerAndSerialNumber IssuerAndSerialNumber,
          subjectKeyIdentifier [0] SubjectKeyIdentifier }

        SignedAttributes ::= SET SIZE (1..MAX) OF Attribute

        UnsignedAttributes ::= SET SIZE (1..MAX) OF Attribute

          Attribute ::= SEQUENCE {
            attrType OBJECT IDENTIFIER,
            attrValues SET OF AttributeValue }

            AttributeValue ::= ANY
        SignatureValue ::= OCTET STRING

Platform Agnostic Security Tokens (PASETO)

Pros:

Simple, lesser probability of user shooting themselves in the foot.
Signing libraries available in Go: lib/paseto, o1egl/paseto.

Cons:

No published RFC, although there is one in draft.
Doesn't provides algorithm agility instead uses predefined algo(for recommended version v2, signing algo is Ed25519) which might not be supported by smart cards, HSMs and cloud based Key Management Systems. Also given that v2 only support Ed25519 signing algo, which is not FIPS-2 approved thus system using it cannot be FIPS-2 compliant.
No native support for referencing or inlining of certificate(s), keyId and timestamp (TSA).These are supported through a signed footer which can contain any structure.
No native support for unsigned attributes and TSA signature.
Doesn't support multiple signature in one signature envelope.

#### Example (Click to show details)

payload

{ 
    "subjectManifest": {...},
    "signedAttrs": {
        "reserved": {
            "iat": "2021-06-22T16:02:40.3375379Z",
            "exp": "2021-09-20T16:02:40.3375379Z",
            ...
        },
        "custom" : {...}
    }
}

footer

{
    "x5c": ["<Base64(DER(leafCert))>", "<Base64(DER(intermediateCACert))>", "<Base64(DER(rootCert))>"],
    "timestamp": "<Base64(TimeStampToken)>" 
}

Signature Envelope:

<version>.<purpose>.Base64Url(<payload><Sign(PAE(<version><purpose><payload>))>).Base64Url(<footer>)

version: v2, v2 is recommended version.
Purpose: public, public is used for signing.
PAE: Pre-Authentication Encoding

Red Hat's Simple Signing - Simple Signing

It’s used by Red Hat for signing container image. Simple signing is not a signature format instead defines the payload format which is then signed using PGP to create detached signature. The payload format is adapted by atomic and later by cosign.

#### Example (Click to show details)

payload:

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

Recommendation

Signature format

Recommendation is to use JWS JSON Serialization because of following reasons:

Specs are part of an RFC standard.
Native support for certificate(s), keyid, signed and unsigned attributes.
Signing libraries available in Go: square/go-jose, lestrrat-go/jwx, golang-jwt/jwt library to produce/consume a JWS in compact serialization and convert it to/from JSON serialization by custom code
Security related concerns can be addressed with proper implementations.

Concerns with DSSE:

No published RFC (or draft) and is a new format that is used in few projects.
Does not currently support TSA signature and certificate(s) chain as part of the envelope. See dsse/42, dsse/33
Additional effort required to certify implementations with security groups of cloud service providers, before adoption.
Being a new format, additional effort is involved to get the implementations reviewed and certified by the compliance & security boards of cloud service providers before its usage. This is part of component governance which is considered as a strict requirement to adopt technologies and implementations in cloud environments.

Payload

Example of payload in recommended format.<TBD>

References

tags: `notary`

Shiwei Zhang

2021/07/27 15:37:38

integrity

How about authenticity? (Edited)

Milind

2021/07/28 06:11:09

Authenticity implies, the signer was verified/authenticated to be trusted. Which is part of cert validation. I'm open to refining this in next iteration.

2021/07/27 15:42:43

The signature envelope MAY contain arbitrary user supplied information, as key value pairs. If included, it MUST be integrity protected. 1. The signature envelope MAY contain information to determine the signature expiration time. If included, it MUST be integrity protected. 1. The signature envelope MAY contain information to determine the signature revocation status. If included, it MUST be integrity protected.

Where are those information exactly stored? Payload or Signed Attributed? (Edited)

Pritesh Bandi

2021/07/28 05:07:19

For requirement purpose we don't care if they are stored in payload or signed attributes until they integrity protected.

2021/07/27 15:44:03

a certificate chain

Why the complete chain? Can it be a partial chain? Usually, the root CA is available locally. (Edited)

2021/07/28 05:05:10

+1 IMO we should allow partial cert chain There is use case where an enterprise might want use one root CA to sign multiple applications but isolate the trust for the applications using different intermediateCA.

2021/07/28 05:05:36

For Eg: Artifact1's cert-chain: leaf1->intermediateCA01 Artifact2's cert-chain: leaf2->intermediateCA02 Both intermediateCA01 and intermediateCA02 chains to single rootCA but by not including rootCA in certificate chain, the consumers are forced to trust different intermediateCAs. Pros: In case intermediteCA002 is compromised only Artifact2 is compromised.

2021/07/28 06:12:13

I relaxed the requirement for now, till we discuss this in detail.

2021/07/27 15:47:08

1. The sign

What's "dual signing"? (Edited)

2021/07/28 05:11:20

dual signing: Signing an application with two different signatures. This might be required for backward compatibility/algorithm deprecation.

2021/07/27 15:47:47

f present it MUST be a signed attribute.

There is an issue on the verificiation process: We need to decode and parse the signed attributes before verifying it. The worst is that we actually need to always decode and parse the unverified attributes even if the `alg` attribute is not there. (Edited)

2021/07/27 15:51:49

igning libraries

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

2021/07/28 06:16:38

Added

2021/07/27 15:54:36

- Signing li

Not really. Actually, some libraries implies JWS JSON serialization is insecure. See https://github.com/google/jws#out-of-scope (Edited)

2021/07/28 06:19:08

Good point, removed it.

2021/07/27 15:58:35

in-toto-golang

This library implement diverges from the reference implementation for multi-signature verification. See: https://github.com/secure-systems-lab/dsse/issues/40#issuecomment-882771124 (Edited)

2021/08/03 21:18:45

Added it in cons

2021/07/27 15:59:38

:::spoiler #### Example (Click to show details) ++Payload++: ```json { "subjectManifest"

Will "descriptor" be better than "subjectManifest"? (Edited)

2021/07/27 16:07:17

Doesn't provides algorithm agility instead uses predefined algo(for recommended version v2, signing algo is Ed25519)

This is critical if the algorithm cannot be changed later. Also, Ed25519 is NOT a FIPS 140-2 approved algorithm. (Edited)

2021/08/03 21:17:58

Added as cons

2021/07/28 06:15:30

Changed to SHOULD NOT to make it a stronger statement. (Edited)

mnltejaswini

2021/08/10 01:07:06

Pros

1. JWS is an IETF proposed (RFC 7515) standard with lot of guidance around representation, serialization and verification (Edited)

2021/08/10 01:07:13

2. Component governance is considered as a strict requirement as we use technologies and implementations in cloud environments. There are several libraries for JWS that are already registered under the Governance service and approved by the crypto board. Getting new implementations/libraries approved and registered would involve processes that might take additional time than we anticipate. (Edited)

2021/08/10 01:09:00

3. Some of the main concerns raised for JWS, can they be addressed with proper implementations. (Edited)

2021/08/10 01:09:16

4. We also can consider addressing any gaps in the standard if *needed*. Experts within Microsoft are ready to offer help. This follows the same philosophy of reusing things instead of re-inventing which is usually discouraged in security domains. (Edited)

2021/08/10 23:32:53

golang-jwt/jwt](github.com/golang-jwt/jwt) library to produce/consume a JWS in compact serialization and convert it to/from JSON serialization by custom code

@shizh I pulled this from one of the email conversations with crypto board, can you please review and update if needed. (Edited)

2021/08/11 12:14:11

It is good enough. Changing the serialization won't impact the verification process or the integrity of signed content.

2021/08/11 12:17:46

An analogy is like signatures can be stored in CD, Tape, HDD, or even printed on a real paper. The serialization / encoding won't hurt.

2021/08/11 01:07:46

and i

do you want to rephrase as "is a new format" indicating the maturity level? (Edited)

[OLD] [Draft] Notary V2 - Signature Format

Terminology

Requirements

Signature Envelope and Signature

Signature Format

Signature Formats Explored

JWS Compact Serialization (JWT) - RFC7515 Section 3.1

Pros:

Cons

JWS JSON Serialization - RFC7515 Section 3.2

Pros:

Cons:

Dead Simple Signature Envelope (DSSE)

Pros:

Cons:

PKCS 7: Cryptographic Message Syntax (CMS) - RFC2315, RFC5652

Pros:

Cons:

Platform Agnostic Security Tokens (PASETO)

Pros:

Cons:

Red Hat's Simple Signing - Simple Signing

Recommendation

Signature format

Payload

References

tags: notary

Read more

Untitled

Sign arbitrary data

Notation Debug Logs

[Draft] Verification extensibility

tags: `notary`