-
Notifications
You must be signed in to change notification settings - Fork 44
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
COSE envelope signature spec updates #148
Changes from 1 commit
3d8617b
33d1ee9
3e93835
e7cf5df
e1183b8
68e31b4
379e642
32507a5
b5b27d4
26f2ccb
e7c8b55
5e2f76a
cf533b8
fa0d6aa
d65a512
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
Updates to signature specification * Moves signed attributes out of payload * Defines new signed attributes and marks them as critical/informational * Introduces signature scheme to support different trust models Signed-off-by: Milind Gokarn <[email protected]>
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,10 +1,9 @@ | ||
# Signature Specification | ||
|
||
This document describes how Notary v2 signatures are created and stored. | ||
The document has the following sections: | ||
This document provides the following details for Notary v2 signatures: | ||
|
||
- **[Storage](#storage)**: Describes how signatures are stored in OCI registry. | ||
- **[Signature Envelope](#signature-envelope)**: Describes how signatures are created. | ||
- **[Storage](#storage)**: Describes how signatures are stored and retrieved from an OCI registry. | ||
- **[Signature Envelope](#signature-envelope)**: Describes the structure of a Notary v2 signature. | ||
|
||
## Storage | ||
|
||
|
@@ -22,7 +21,7 @@ The signature manifest has an artifact type that specifies it's a Notary V2 sign | |
- **`annotations`** (*string-string map*): This REQUIRED property contains metadata for the artifact manifest. | ||
It is being used to store information about the signature. | ||
Keys using the `io.cncf.notary` namespace are reserved for use in Notary and MUST NOT be used by other specifications. | ||
- **`io.cncf.notary.x509certs.fingerprint.sha256`**: A REQUIRED annotation whose value contains the list of SHA-256 fingerprint of signing certificate and certificate chain used for signature generation. | ||
- **`io.cncf.notary.x509.fingerprint.sha256`**: A REQUIRED annotation whose value contains the list of SHA-256 fingerprint of signing certificate and certificate chain used for signature generation. | ||
The list of fingerprints is present as a JSON array string. | ||
|
||
### Signature Discovery | ||
|
@@ -35,25 +34,26 @@ Each Notary signature artifact refers to a signature envelope blob. | |
### Signature Filtering | ||
|
||
An OCI artifact can have multiple signatures, Notary v2 uses annotations of the signature artifact to filter relevant signatures based on the applicable trust policy. | ||
The Notary v2 signature artifact's `io.cncf.notary.x509certs.fingerprint.sha256` annotations key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. | ||
The Notary v2 signature artifact's `io.cncf.notary.x509.fingerprint.sha256` annotations key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing. | ||
|
||
## 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. | ||
- Payload/Message `m`: The data that is integrity protected - e.g. descriptor of the artifact being signed. | ||
- Signed attributes `v`: The signature metadata that is integrity protected - e.g. signature expiration time, creation time, etc. | ||
- Unsigned attributes `u`: This OPTIONAL property represents signature metadata that is not integrity protected by this envelope- e.g. timestamp, certificates, etc. | ||
We anticipate all unsigned attributes contain signed content. | ||
- Unsigned attributes `u`: Unsigned attributes `u`: These attributes are not signed by the signing key that generates the signature. We anticipate unsigned attributes contain content that may be signed by an different party e.g. Certificate chain signed by a CA, or TSA countersignature signed by the TSA. | ||
- 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. | ||
|
||
Notary v2 supports multiple envelope formats, including: | ||
This specification defines the set of signed and unsigned attributes that make up a valid The Notary v2 signature. This specification aims to be be agnostic of signature envelope format (e.g. COSE, JWS), details of encoding the envelope in a specific signature envelope format are covered in in separate specs. | ||
|
||
Notary v2 supports the following envelope formats: | ||
|
||
- [COSE Sign1](./signature-envelope-cose.md) | ||
- [JWT](./signature-envelope-jwt.md) | ||
- [JWS](./signature-envelope-jws.md) | ||
|
||
### Payload | ||
|
||
|
@@ -71,7 +71,7 @@ Notary v2 requires Payload to be the content **descriptor** of the subject manif | |
"digest": "sha256:73c803930ea3ba1e54bc25c2bdc53edd0284c62ed651fe7b00369da519a3c333", | ||
"size": 16724, | ||
"annotations": { | ||
"io.wabbit-networks.buildId": "123" // user defined signed attribute. | ||
"io.wabbit-networks.buildId": "123" // user defined metadata | ||
} | ||
} | ||
``` | ||
|
@@ -84,20 +84,42 @@ Notary v2 requires Payload to be the content **descriptor** of the subject manif | |
} | ||
``` | ||
|
||
### Signature Scheme | ||
|
||
Notary will initially support X509 PKI based identities, which has well established standards for establishing and trusting signing identities, managing key lifetimes and rotation, and revocation. There is interest in the community to support additional trust models based on other standards and techniques (Notary TUF, ledger based). Notary addresses future support for additional trust models through an abstraction called Signature Scheme. A Signature Scheme defines the the specific trust model used for generation and verification of signatures. It includes the supported identity type (e.g. X509 certificates), set of signed and unsigned attributes in the signature to support the trust model, which attributes are required/optional and critical/informational, the signature verification logic, and verification policy switches that are supported (e.g. revocation checks can be skipped, audited, enforced) and how they are processed during signature verification. Notary v2 defines the following signature schemes. | ||
|
||
`notary.signer.x509` - This signature scheme defines the trust model that uses traditional X509 based PKI. Users owns signing keys and use CA issued certificates to represent identity. | ||
|
||
`notary.signingservice.x509` - This signature scheme defines the trust model for a signing service that uses X509 based PKI. In this model, a trusted signing service manages the keys of behalf of the user, and generates signatures. The end user does not have direct access to signing keys. | ||
|
||
When Notary supports additional signature schemes, Notary verification policy may have breaking changes to support newer concepts introduced by the signature scheme, and existing signed artifacts will need to be resigned if they are required to be validated using the new trust system introduced by the signature scheme. | ||
|
||
### Signed Attributes | ||
|
||
Notary v2 requires the signature envelope to support the following signed attributes: | ||
Signed attributes/claims are additional metadata apart from the payload, which are required to support the signature verification process. | ||
|
||
- Any claims MUST NOT be stored/appended in the payload itself, as the payload is only parsed and processed once the signature has been verified (signature is valid, and from a trusted key) and trust is established. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Wouldn't |
||
- Specific claims can be either required or optional. | ||
- Claims that if present, MUST be processed by a verifier MUST be marked as critical. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I don't understand this requirement. It seems that this excludes certain envelope formats, but see also my other comment in -jws.md about how |
||
- Claims which are informational and do not influence signature verification MUST NOT be marked critical. | ||
|
||
- **Creation time**: The time at which the signature was generated. | ||
Its value should be numeric representing the number of seconds (not milliseconds) since Epoch. | ||
- **Expiration time**: The time after which signature shouldn't be considered valid. | ||
Its value should be numeric representing the number of seconds since Epoch. | ||
The value MUST be equal or greater than the `Creation time` | ||
This is an OPTIONAL attribute. | ||
Notary v2 requires the signature envelope to support the following signed attributes/claims. | ||
|
||
#### Standard attributes | ||
|
||
- **Notary Signature scheme** (critical): The trust model used by Notary currently supports the following values for this claim `notary.signer.x509` and `notary.signingservice.x509`. Both signature schemes use the same set of claims defined in this document. One difference is that `notary.signer.x509` uses a TSA signature to determine authenticated signing time (timestamp), and `notary.signingservice.x509` uses the trusted signing time claim instead, with optional support for TSA signatures. Signature verification MUST consider the signature to be invalid if any other value is used. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I couldn't find this claim in the JWS md for example. Shouldn't it be there? |
||
- **Signing time**: The time at which the signature was generated. This is a REQUIRED claim for signature scheme `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](#signing-time). | ||
- **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 scheme `notary.signingservice.x509` . More details [here](#signing-time). | ||
- **Signature Expiry** (critical): The time when a signature is considered to be expired. This is an OPTIONAL claim. [Open issue](https://github.com/notaryproject/notaryproject/issues/141) tracking if this attribute should be removed. | ||
- **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 OPTIONAL claim. It uses the following format `{client}/{version}` e.g. “notation/1.0.0”. This claim in intended to be used for diagnostic and troubleshooting purposes. | ||
|
||
### Unsigned Attributes | ||
|
||
- **Certificates**: The ordered collection of X.509 certificates with a signing certificate as the first entry. | ||
These attributes are considered unsigned with respect to the signing key that generates the signature. These attributes are typically signed by a third party (e.g. CA, TSA). | ||
|
||
- **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](ietf-rfc3161) compliant TimeStampToken are supported. This is an OPTIONAL attribute. | ||
|
||
### Algorithm Selection | ||
|
||
|
@@ -148,6 +170,12 @@ The client implementation can use the aforementioned `mediaType` to parse the si | |
[COSE_Sign1_Tagged](./signature-envelope-cose.md) signature envelope versioning is achieved by the `cty` field in ProtectedHeaders. | ||
[JWS JSON serialization](./signature-envelope-jwt.md) signature envelope versioning is achieved by the `cty` field in ProtectedHeaders. | ||
|
||
## Appendix | ||
|
||
### Signing time | ||
|
||
The signing time denotes the time at which the signature was generated. A X509 certificate has a defined [validity](https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.5) during which it can be used to generate signatures. The signing time must be greater than or equal to certificate's `notBefore` attribute, and signing time must be less than or equal to certificate's `notAfter` attribute. 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. | ||
|
||
[annotation-rules]: https://github.com/opencontainers/image-spec/blob/main/annotations.md#rules | ||
[artifact-descriptor]: https://github.com/oras-project/artifacts-spec/blob/main/descriptor.md | ||
[ietf-cose]: https://datatracker.ietf.org/doc/html/rfc8152 | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not clear how the fingerprints are computed exactly.