Notary Issue #86
This document defines the requirements of the signature format and discusses the candidates for Notary V2.
Definition
A complete signature is a tuple of
- Signed payload .
- Signed signature metadata .
- Unsigned signature metadata .
- Cryptographic signature .
where 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 is a compact form of signatures signing the same payload . It can be expanded to .
A complete signature can be viewed as a signature envelope .
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.
- 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.
- 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.
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:
If parsed,
JWS JSON Serialization
General JWS JSON serialization syntax is defined in RFC7515 Section 7.2.1.
Pros:
Cons:
Here is an example:
Payload:
Signed signature metadata:
Complete JWS JSON Serialization:
If a JWS contains only one signature as above, the JWS can be flattened as
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:
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.
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
Example by extending DSSE
The format is proposed by extending DSSE.
Payload:
Signed signature metadata:
Signature envelope:
[PB]Example using JWS JSON Serialization
The format is proposed using JWS JSON Serialization.
Payload:
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:
- 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:
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:
SignatureEnvelope:
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
- TSA signature
- Signature expiry
- ARL field (placeholder)
- Custom signed attributes (wrapped payload)
- Types of keys (different x5c)
References