Skip to content

Commit 25e9940

Browse files
author
Patrick Zheng
authored
docs: remove blob related specs (#311)
* update for v1.1.0 release Signed-off-by: Patrick Zheng <patrickzheng@microsoft.com> * update Signed-off-by: Patrick Zheng <patrickzheng@microsoft.com> --------- Signed-off-by: Patrick Zheng <patrickzheng@microsoft.com>
1 parent 00abcea commit 25e9940

File tree

6 files changed

+36
-277
lines changed

6 files changed

+36
-277
lines changed

‎specs/signature-envelope-cose.md‎

Lines changed: 2 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ This specification implements the [Notary Project signature specification](signa
44
CBOR Object Signing and Encryption (COSE). COSE ([RFC8152](https://datatracker.ietf.org/doc/html/rfc8152)) is a CBOR based envelope format for digital signatures over any type of payload (e.g. CBOR, JSON, binary).
55
Notary Project specifically supports [COSE_Sign1_Tagged](https://datatracker.ietf.org/doc/html/rfc8152#section-4.2) as a signature envelope.
66

7-
## OCI Signature Storage
7+
## Signature Storage
88

99
A COSE signature envelope will be stored in an OCI registry as a blob, and referenced in the signature manifest as a layer blob with `mediaType` of `"application/cose"`.
1010

@@ -36,15 +36,12 @@ Signature Manifest Example
3636
}
3737
}
3838
```
39-
## Blob Signature Storage
40-
41-
For detached signatures associated with arbitrary blobs, a COSE signature envelope will be stored on the file system as a binary file with `cose` as the file extension.
4239

4340
## COSE Payload
4441

4542
The COSE envelope contains the [Notary Project signature Payload](./signature-specification.md#payload).
4643

47-
Example of the Notary Project OCI signature payload:
44+
Example
4845

4946
```jsonc
5047
{
@@ -59,21 +56,6 @@ Example of the Notary Project OCI signature payload:
5956
}
6057
```
6158

62-
Example of the Notary Project blob signature payload:
63-
64-
```jsonc
65-
{
66-
"targetArtifact": {
67-
"mediaType": "application/octet-stream",
68-
"digest": "sha256:2f3a23b6373afb134ddcd864be8e037e34a662d090d33ee849471ff73c873345",
69-
"size": 1024,
70-
"annotations": {
71-
"io.wabbit-networks.buildId": "123" // user defined metadata
72-
}
73-
}
74-
}
75-
```
76-
7759
## Protected Header
7860

7961
The COSE envelope for the Notary Project signature uses the following header parameters:

‎specs/signature-envelope-jws.md‎

Lines changed: 3 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,9 @@
22

33
This specification implements the [Notary Project signature specification](./signature-specification.md) using JSON Web Signature (JWS). JWS ([RFC7515](https://datatracker.ietf.org/doc/html/rfc7515)) is a JSON based envelope format for digital signatures over any type of payload (e.g. JSON, binary). JWS is the Notary Project supported signature format and specifically uses the *JWS JSON Serialization* representation.
44

5-
## OCI Signature Storage
5+
## Signature Storage
66

7-
A JWS signature envelope will be stored in an OCI registry as a layer, and referenced in the signature manifest as a layer blob with `mediaType` of `"application/jose+json"`.
7+
A JWS signature envelope will be stored in an OCI registry as a blob, and referenced in the signature manifest as a layer blob with `mediaType` of `"application/jose+json"`.
88

99
Signature Manifest Example
1010

@@ -35,15 +35,11 @@ Signature Manifest Example
3535
}
3636
```
3737

38-
## Blob Signature Storage
39-
40-
For detached signatures associated with blobs, a JWS signature envelope will be stored on the file system with `jws` as the file extension.
41-
4238
## JWS Payload
4339

4440
The JWS envelope contains the [Notary Project signature payload](./signature-specification.md#payload).
4541

46-
Example of the Notary Project OCI signature payload
42+
Example
4743

4844
```jsonc
4945
{
@@ -58,21 +54,6 @@ Example of the Notary Project OCI signature payload
5854
}
5955
```
6056

61-
Example of the Notary Project blob signature payload:
62-
63-
```jsonc
64-
{
65-
"targetArtifact": {
66-
"mediaType": "application/octet-stream",
67-
"digest": "sha256:2f3a23b6373afb134ddcd864be8e037e34a662d090d33ee849471ff73c873345",
68-
"size": 1024,
69-
"annotations": {
70-
"io.wabbit-networks.buildId": "123" // user defined metadata
71-
}
72-
}
73-
}
74-
```
75-
7657
## Protected Headers
7758

7859
The JWS envelope for the Notary Project signature uses following headers

‎specs/signature-specification.md‎

Lines changed: 16 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,7 @@
33
This document provides the following details for Notary Project signature:
44

55
- **[Signature Envelope](#signature-envelope)**: Describes the structure of the Notary Project signature.
6-
- **[OCI Signatures](#oci-signatures)**: Describes how signatures for OCI artifacts are stored and retrieved from an OCI registry.
7-
- **[Blob Signatures](#blob-signatures)**: Describes how signatures for signed Blobs are stored on file system.
6+
- **[Signature](#signature)**: Describes how signatures are stored and retrieved from an OCI registry.
87

98
## Signature Envelope
109

@@ -30,25 +29,15 @@ The Notary Project signature supports following envelope formats:
3029
The Notary Project signature payload is a JSON document with media type `application/vnd.cncf.notary.payload.v1+json` and has following properties.
3130

3231
- `targetArtifact` : Required property whose value is the descriptor of the target artifact manifest that is being signed.
33-
- For OCI artifacts, this MUST be a valid [OCI descriptor][oci-descriptor].
32+
- This MUST be a valid [OCI descriptor][oci-descriptor].
3433
- Descriptor MUST contain `mediaType`, `digest`, and `size` fields.
3534
- Descriptor MAY contain `annotations` and if present it MUST follow the [annotation rules][annotation-rules].
3635
- Descriptor MAY contain `artifactType` field for the `config.mediaType` of OCI image manifests.
37-
- For Blob artifacts, the descriptor MUST describe the blob that is being signed
38-
- Descriptor MUST contain `mediaType`, `digest`, and `size` fields.
39-
- `digest` MUST be in the format of `<digest algorithm>:<digest value>`. Example: `sha256:2f3a23b6373afb134ddcd864be8e037e34a662d090d33ee849471ff73c873345`
40-
- `digest algorithm` MUST be deduced from signing certificate's public key. See [Algorithm Selection](#algorithm-selection)
41-
- `mediaType` can be any arbitrary media type that the user provides to describe the blob. An example can be `application/octet-stream`
42-
- `size` MUST be the raw size of the blob in bytes.
43-
- Blob descriptors MAY optionally contain `annotations` and if present it MUST follow the [annotation rules][annotation-rules].
4436

4537
NOTE: The Notary Project signature uses annotations for storing both Notary Project specific and user defined metadata. The prefix `io.cncf.notary` in `annotations` key is reserved for use in Notary Project signature and MUST NOT be used outside this specification.
4638

47-
4839
#### Examples
4940

50-
##### OCI Payload
51-
5241
```jsonc
5342
{
5443
"targetArtifact": {
@@ -58,7 +47,7 @@ NOTE: The Notary Project signature uses annotations for storing both Notary Proj
5847
}
5948
}
6049
```
61-
##### OCI Payload with artifactType and annotations
50+
##### Payload with artifactType and annotations
6251

6352
```jsonc
6453
{
@@ -73,31 +62,6 @@ NOTE: The Notary Project signature uses annotations for storing both Notary Proj
7362
}
7463
}
7564
```
76-
##### Blob Payload
77-
78-
```jsonc
79-
{
80-
"targetArtifact": {
81-
"mediaType": "application/octet-stream",
82-
"digest": "sha256:2f3a23b6373afb134ddcd864be8e037e34a662d090d33ee849471ff73c873345",
83-
"size": 1024
84-
}
85-
}
86-
```
87-
##### Blob Payload with annotations
88-
89-
```jsonc
90-
{
91-
"targetArtifact": {
92-
"mediaType": "application/octet-stream",
93-
"digest": "sha256:2f3a23b6373afb134ddcd864be8e037e34a662d090d33ee849471ff73c873345",
94-
"size": 1024,
95-
"annotations": {
96-
"io.wabbit-networks.buildId": "123" // user defined metadata
97-
}
98-
}
99-
}
100-
```
10165

10266
### Signed Attributes
10367

@@ -152,10 +116,10 @@ These attributes are considered unsigned with respect to the signing key that ge
152116
- **Timestamp Signature**: An OPTIONAL countersignature generated by a trusted third party, such as a Timestamp Authority (TSA). Its purpose is to demonstrate that the primitive signature, computed on payload and signed attributes, was generated before the timestamp. Only [RFC 3161][ietf-rfc3161] compliant timestamp signatures are supported. If present, this claim is validated and used solely under the [`notary.x509`](./signing-scheme.md/#notaryx509) signing scheme.
153117
- **Signing Agent**: An OPTIONAL claim that provides the identifier of the software (e.g. Notation) that produced the signature on behalf of the user. It is an opaque string set by the software that produces the signature. It's intended primarily for diagnostic and troubleshooting purposes, this attribute is unsigned, the verifier MUST NOT validate formatting, or fail validation based on the content of this claim. The suggested format is one or more tokens of the form `{id}/{version}` containing identifier and version of the software, separated by spaces. E.g. "notation/1.0.0", "notation/1.0.0 myplugin/0.8".
154118

155-
## OCI Signatures
119+
## Signature
156120

157121
This section describes how a Notary Project signature is stored in an OCI Distribution conformant registry.
158-
OCI image manifest is used to store signatures in the registry, see [OCI image spec v1.1.0-rc3][oci-image-manifest] for details.
122+
OCI image manifest is used to store signatures in the registry, see [OCI image spec v1.1.0][oci-image-manifest] for details.
159123
The signature manifest has a configuration media type that specifies it's a Notary Project signature, a subject referencing the manifest of the artifact being signed, a layer referencing the signature, and a collection of annotations.
160124

161125
![Signature storage inside registry](../media/oci-signature-specification.svg)
@@ -207,29 +171,18 @@ Besides the [image manifest property requirements][image-manifest-property-descr
207171
Keys using the `io.cncf.notary` namespace are reserved for use in the Notary Project signature specification and MUST NOT be used by other specifications.
208172
- **`io.cncf.notary.x509chain.thumbprint#S256`**: A REQUIRED annotation whose value contains the list of SHA-256 fingerprints of signing certificate and certificate chain (including root) used for signature generation. The list of fingerprints is present as a JSON array string, corresponding to ordered certificates in [*Certificate Chain* unsigned attribute](#unsigned-attributes) in the signature envelope. The annotation name contains the hash algorithm as a suffix (`#S256`) and can be extended to support other hashing algorithms in future.
209173

210-
### OCI Signature Discovery
174+
### Signature Discovery
211175

212176
The client should be able to discover all the signatures belonging to an artifact (such as image manifest) by using [OCI Distribution Referrers API][oci-distribution-referrers].
213177
OCI Distribution Referrers API returns a paginated list of all artifacts belonging to a target artifact (such as container images, SBoMs).
214178
The implementation can filter Notary Project signatures by either using OCI Distribution Referrers API or using custom logic on the client.
215179
Each Notary Project signature refers to a signature envelope blob.
216180

217-
### OCI Signature Filtering
181+
### Signature Filtering
218182

219183
An OCI artifact can have multiple signatures, implementations of the Notary Project signature specification uses annotations of the signature manifest to filter relevant signatures based on the applicable trust policy.
220184
The Notary Project signature manifest's `io.cncf.notary.x509chain.thumbprint#S256` annotation key MUST contain the list of SHA-256 fingerprints of certificate and certificate chain used for signing.
221185

222-
## Blob Signatures
223-
224-
The Notary Project facilitates signing arbitrary blobs using detached signatures. These detached signatures can be transported via any preferred medium and verified on the receiving end. A detached signature refers to a signature that is not embedded within (and therefore does not modify) the original blob, instead it consists of a detached signature envelope with a signature over the unique representation of the blob (i.e. blob's digest). The file extension can either be 'jws' or 'cose', indicating the signature envelope format.
225-
226-
![Signature storage inside file system](../media/blob-signature-specification.svg)
227-
228-
### Differences between OCI and blob signatures
229-
230-
1. Apart from the `payload` field, all other fields of a signature envelope are identical between OCI and blob signatures.
231-
1. OCI signatures have signature manifest files, containing the mediaType of the signature envelope (application/jose+json or application/cose). However, blob signatures lack such manifest file and this mediaType information is instead found in the signature file extension.
232-
233186
## Signature Algorithm Requirements
234187

235188
The implementation MUST support the following set of algorithms:
@@ -331,7 +284,7 @@ An `authentic signing time` is a signing time authenticated by a `Signing Author
331284

332285
This is an optional feature that provides a "best by use" time for the artifact, as defined by the signer. The Notary Project signature specification allows users to include an optional expiry time when they generate a signature. The expiry time is not set by default and requires explicit configuration by users at the time of signature generation. The artifact is considered expired when the current time is greater than or equal to expiry time, users performing verification can either configure their trust policies to fail the verification or even accept the artifact with expiry date in the past using policy. This is an advanced feature that allows implementing controls for user defined semantics like deprecation for older artifacts, or block older artifacts in a production environment. Users should only include an expiry time in the signed artifact after considering the behavior they expect for consumers of the artifact after it expires. Users can choose to consume an artifact even after the expiry time based on their specific needs.
333286

334-
### OCI Signature Portability
287+
### Signature Portability
335288

336289
Portability of signatures is associated with the portability of associated artifacts which are being signed.
337290
OCI artifacts are inherently registry agnostic, artifacts can be pulled from and pushed to any OCI compliant registry to which a user has access.
@@ -345,13 +298,13 @@ Signatures associated with these artifacts require broad portability.
345298
E.g. Images for containerized applications and services used within an organization, or shared with limited authorized parties.
346299
Based on user requirements a private artifact can have different levels of portability, the signature’s portability should at least match the the artifact’s portability.
347300

348-
*The Notary Project OCI signature portability* is based on the following
301+
*The Notary Project signature portability* is based on the following
349302

350303
#### Signature discovery
351304

352-
The Notary Project OCI signature specification addressed signature discovery by storing signatures in the same registry (location) where an artifact is present.
305+
The Notary Project signature specification addressed signature discovery by storing signatures in the same registry (location) where an artifact is present.
353306
This is supported through [OCI Distribution Referrers API][oci-distribution-referrers] which allows reference artifacts such as signatures, SBOMs to be associated with existing artifacts like Images.
354-
The Notary Project OCI signature specification allows multiple signatures to be associated with an artifact, and clients may automatically push signatures for an artifact to a destination registry when a signed artifact moves from one registry to other.
307+
The Notary Project signature specification allows multiple signatures to be associated with an artifact, and clients may automatically push signatures of an artifact to a destination registry when a signed artifact moves from one registry to another.
355308

356309
#### Verification requirements
357310

@@ -369,9 +322,6 @@ The Notary Project signatures without any critical extended attributes do not im
369322
Whereas, the Notary Project signatures that contain critical extended attributes will require additional dependencies for signature validation, either on Notation compliant plugins or equivalent tooling which may not be available in all environments.
370323
Similarly, Notation compliant plugin vendors should be aware that usage of extended signed attributes which are marked critical in signature will have implications on portability of the signature.
371324

372-
### Blob Signature Portability
373-
Notary Project blob signatures provide the maximum portability as there are no requirements on storage or transport medium. Users can store and transport their blobs and associated detached signatures as required.
374-
375325
### Guidelines for implementations of the Notary Project signature specification
376326

377327
Implementations of the Notary Project signature specification, can choose to be [Notation plugin protocol](./plugin-extensibility.md#plugin-contract) aware or not. If an implementation chooses to be plugin protocol aware, and it encounters the Verification Plugin and Verification Plugin minimum version attributes during signature verification, it MUST process these attributes. This involves finding the appropriate plugin and the version to use, and executing `verify-signature` plugin command with correct inputs and processing the plugin response, as per the [Verification Plugin interface](./plugin-extensibility.md#verification-extensibility).
@@ -382,9 +332,9 @@ Alternatively, an implementation of the Notary Project signature specification c
382332
- An implementation MUST fail signature verification if it cannot perform the equivalent verification logic, as skipping the plugin equivalent verification logic will cause incorrect and inconsistent signature verification behavior.
383333
- An implementation MAY choose to support a set of known plugin’s verification logic and fail others.
384334

385-
[annotation-rules]: https://github.com/opencontainers/image-spec/blob/v1.0.0/annotations.md#rules
386-
[oci-descriptor]: https://github.com/opencontainers/image-spec/blob/v1.0.0/descriptor.md
335+
[annotation-rules]: https://github.com/opencontainers/image-spec/blob/v1.1.0/annotations.md#rules
336+
[oci-descriptor]: https://github.com/opencontainers/image-spec/blob/v1.1.0/descriptor.md
387337
[ietf-rfc3161]: https://datatracker.ietf.org/doc/html/rfc3161#section-2.4.2
388-
[oci-distribution-referrers]: https://github.com/opencontainers/distribution-spec/blob/v1.0.0/spec.md#listing-referrers
389-
[oci-image-manifest]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc3/manifest.md
390-
[image-manifest-property-descriptions]: https://github.com/opencontainers/image-spec/blob/v1.1.0-rc3/manifest.md#image-manifest-property-descriptions
338+
[oci-distribution-referrers]: https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#listing-referrers
339+
[oci-image-manifest]: https://github.com/opencontainers/image-spec/blob/v1.1.0/manifest.md
340+
[image-manifest-property-descriptions]: https://github.com/opencontainers/image-spec/blob/v1.1.0/manifest.md#image-manifest-property-descriptions

0 commit comments

Comments
 (0)