From ff2bce27319a0a0bca924820c353fae3b9046e91 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Fri, 25 Nov 2022 16:54:21 +0100 Subject: [PATCH] manifest/schema1: mark docker manifest v2, schema 1 deprecated Docker Image manifest v2, schema version 1 is deprecated since 2015, when manifest v2, schema version 2 was introduced (2e3f4934a73b27c22ae8966549e11920ffb28b81). Users should no longer use this specification other than for backward compatibility. Signed-off-by: Sebastiaan van Stijn --- configuration/configuration.go | 16 ++++++- docs/spec/manifest-v2-1.md | 7 +++ manifest/schema1/config_builder.go | 24 ++++++++-- manifest/schema1/manifest.go | 69 ++++++++++++++++++++++----- manifest/schema1/reference_builder.go | 23 +++++++-- manifest/schema1/sign.go | 6 +++ manifest/schema1/verify.go | 6 +++ testutil/manifests.go | 5 +- 8 files changed, 133 insertions(+), 23 deletions(-) diff --git a/configuration/configuration.go b/configuration/configuration.go index c0d799f3b..1f773976b 100644 --- a/configuration/configuration.go +++ b/configuration/configuration.go @@ -203,12 +203,24 @@ type Configuration struct { // Compatibility is used for configurations of working with older or deprecated features. Compatibility struct { - // Schema1 configures how schema1 manifests will be handled + // Schema1 configures how schema1 manifests will be handled. + // + // Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since + // 2015. These options should only be used if you need to provide + // backward compatibility. Schema1 struct { // TrustKey is the signing key to use for adding the signature to // schema1 manifests. + // + // Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since + // 2015. These options should only be used if you need to provide + // backward compatibility. TrustKey string `yaml:"signingkeyfile,omitempty"` - // Enabled determines if schema1 manifests should be pullable + // Enabled determines if schema1 manifests should be pullable. + // + // Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since + // 2015. These options should only be used if you need to provide + // backward compatibility. Enabled bool `yaml:"enabled,omitempty"` } `yaml:"schema1,omitempty"` } `yaml:"compatibility,omitempty"` diff --git a/docs/spec/manifest-v2-1.md b/docs/spec/manifest-v2-1.md index 48e455e11..4572fb233 100644 --- a/docs/spec/manifest-v2-1.md +++ b/docs/spec/manifest-v2-1.md @@ -6,6 +6,13 @@ keywords: registry, on-prem, images, tags, repository, distribution, api, advanc # Image Manifest Version 2, Schema 1 +> **Deprecated** +> +> Image Manifest v2, Schema 1 is deprecated. Use [Image Manifest v2, Schema 2](manifest-v2-2.md), +> or the [OCI Image Specification](https://github.com/opencontainers/image-spec). +> Image Manifest v2, Schema 1 should not be used for purposes other than backward +> compatibility. + This document outlines the format of the V2 image manifest. The image manifest described herein was introduced in the Docker daemon in the [v1.3.0 release](https://github.com/docker/docker/commit/9f482a66ab37ec396ac61ed0c00d59122ac07453). diff --git a/manifest/schema1/config_builder.go b/manifest/schema1/config_builder.go index fac177b8b..77fdfee99 100644 --- a/manifest/schema1/config_builder.go +++ b/manifest/schema1/config_builder.go @@ -52,6 +52,10 @@ type configManifestBuilder struct { // schema version from an image configuration and a set of descriptors. // It takes a BlobService so that it can add an empty tar to the blob store // if the resulting manifest needs empty layers. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015, +// use Docker Image Manifest v2, Schema 2, or the OCI Image Specification v1. +// This package should not be used for purposes other than backward compatibility. func NewConfigManifestBuilder(bs distribution.BlobService, pk libtrust.PrivateKey, ref reference.Named, configJSON []byte) distribution.ManifestBuilder { return &configManifestBuilder{ bs: bs, @@ -61,7 +65,10 @@ func NewConfigManifestBuilder(bs distribution.BlobService, pk libtrust.PrivateKe } } -// Build produces a final manifest from the given references +// Build produces a final manifest from the given references. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. func (mb *configManifestBuilder) Build(ctx context.Context) (m distribution.Manifest, err error) { type imageRootFS struct { Type string `json:"type"` @@ -238,7 +245,10 @@ func (mb *configManifestBuilder) emptyTar(ctx context.Context) (digest.Digest, e return descriptor.Digest, nil } -// AppendReference adds a reference to the current ManifestBuilder +// AppendReference adds a reference to the current ManifestBuilder. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. func (mb *configManifestBuilder) AppendReference(d distribution.Describable) error { descriptor := d.Descriptor() @@ -250,12 +260,18 @@ func (mb *configManifestBuilder) AppendReference(d distribution.Describable) err return nil } -// References returns the current references added to this builder +// References returns the current references added to this builder. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. func (mb *configManifestBuilder) References() []distribution.Descriptor { return mb.descriptors } -// MakeV1ConfigFromConfig creates an legacy V1 image config from image config JSON +// MakeV1ConfigFromConfig creates an legacy V1 image config from image config JSON. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. func MakeV1ConfigFromConfig(configJSON []byte, v1ID, parentV1ID string, throwaway bool) ([]byte, error) { // Top-level v1compatibility string should be a modified version of the // image config. diff --git a/manifest/schema1/manifest.go b/manifest/schema1/manifest.go index 994728803..cd2a5783c 100644 --- a/manifest/schema1/manifest.go +++ b/manifest/schema1/manifest.go @@ -1,3 +1,9 @@ +// Package schema1 provides definitions for the deprecated Docker Image +// Manifest v2, Schema 1 specification. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. This package should not be used for purposes +// other than backward compatibility. package schema1 import ( @@ -10,18 +16,30 @@ import ( "github.com/opencontainers/go-digest" ) -const ( - // MediaTypeManifest specifies the mediaType for the current version. Note - // that for schema version 1, the the media is optionally "application/json". - MediaTypeManifest = "application/vnd.docker.distribution.manifest.v1+json" - // MediaTypeSignedManifest specifies the mediatype for current SignedManifest version - MediaTypeSignedManifest = "application/vnd.docker.distribution.manifest.v1+prettyjws" - // MediaTypeManifestLayer specifies the media type for manifest layers - MediaTypeManifestLayer = "application/vnd.docker.container.image.rootfs.diff+x-gtar" -) +// MediaTypeManifest specifies the mediaType for the current version. Note +// that for schema version 1, the the media is optionally "application/json". +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. +const MediaTypeManifest = "application/vnd.docker.distribution.manifest.v1+json" + +// MediaTypeSignedManifest specifies the mediatype for current SignedManifest version +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. +const MediaTypeSignedManifest = "application/vnd.docker.distribution.manifest.v1+prettyjws" + +// MediaTypeManifestLayer specifies the media type for manifest layers +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. +const MediaTypeManifestLayer = "application/vnd.docker.container.image.rootfs.diff+x-gtar" // SchemaVersion provides a pre-initialized version structure for this // packages version of the manifest. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. var SchemaVersion = manifest.Versioned{ SchemaVersion: 1, } @@ -55,13 +73,19 @@ func init() { } } -// FSLayer is a container struct for BlobSums defined in an image manifest +// FSLayer is a container struct for BlobSums defined in an image manifest. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. type FSLayer struct { // BlobSum is the tarsum of the referenced filesystem image layer BlobSum digest.Digest `json:"blobSum"` } -// History stores unstructured v1 compatibility information +// History stores unstructured v1 compatibility information. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. type History struct { // V1Compatibility is the raw v1 compatibility information V1Compatibility string `json:"v1Compatibility"` @@ -69,6 +93,9 @@ type History struct { // Manifest provides the base accessible fields for working with V2 image // format in the registry. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. type Manifest struct { manifest.Versioned @@ -91,6 +118,9 @@ type Manifest struct { // SignedManifest provides an envelope for a signed image manifest, including // the format sensitive raw bytes. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. type SignedManifest struct { Manifest @@ -105,6 +135,9 @@ type SignedManifest struct { } // UnmarshalJSON populates a new SignedManifest struct from JSON data. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. func (sm *SignedManifest) UnmarshalJSON(b []byte) error { sm.all = make([]byte, len(b)) // store manifest and signatures in all @@ -136,7 +169,10 @@ func (sm *SignedManifest) UnmarshalJSON(b []byte) error { return nil } -// References returns the descriptors of this manifests references +// References returns the descriptors of this manifests references. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. func (sm SignedManifest) References() []distribution.Descriptor { dependencies := make([]distribution.Descriptor, len(sm.FSLayers)) for i, fsLayer := range sm.FSLayers { @@ -153,6 +189,9 @@ func (sm SignedManifest) References() []distribution.Descriptor { // contents. Applications requiring a marshaled signed manifest should simply // use Raw directly, since the the content produced by json.Marshal will be // compacted and will fail signature checks. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. func (sm *SignedManifest) MarshalJSON() ([]byte, error) { if len(sm.all) > 0 { return sm.all, nil @@ -163,6 +202,9 @@ func (sm *SignedManifest) MarshalJSON() ([]byte, error) { } // Payload returns the signed content of the signed manifest. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. func (sm SignedManifest) Payload() (string, []byte, error) { return MediaTypeSignedManifest, sm.all, nil } @@ -170,6 +212,9 @@ func (sm SignedManifest) Payload() (string, []byte, error) { // Signatures returns the signatures as provided by // (*libtrust.JSONSignature).Signatures. The byte slices are opaque jws // signatures. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. func (sm *SignedManifest) Signatures() ([][]byte, error) { jsig, err := libtrust.ParsePrettySignature(sm.all, "signatures") if err != nil { diff --git a/manifest/schema1/reference_builder.go b/manifest/schema1/reference_builder.go index a1c0ed038..13713b527 100644 --- a/manifest/schema1/reference_builder.go +++ b/manifest/schema1/reference_builder.go @@ -21,6 +21,9 @@ type referenceManifestBuilder struct { // NewReferenceManifestBuilder is used to build new manifests for the current // schema version using schema1 dependencies. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. func NewReferenceManifestBuilder(pk libtrust.PrivateKey, ref reference.Named, architecture string) distribution.ManifestBuilder { tag := "" if tagged, isTagged := ref.(reference.Tagged); isTagged { @@ -54,7 +57,10 @@ func (mb *referenceManifestBuilder) Build(ctx context.Context) (distribution.Man return Sign(&m, mb.pk) } -// AppendReference adds a reference to the current ManifestBuilder +// AppendReference adds a reference to the current ManifestBuilder. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. func (mb *referenceManifestBuilder) AppendReference(d distribution.Describable) error { r, ok := d.(Reference) if !ok { @@ -67,7 +73,10 @@ func (mb *referenceManifestBuilder) AppendReference(d distribution.Describable) return nil } -// References returns the current references added to this builder +// References returns the current references added to this builder. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. func (mb *referenceManifestBuilder) References() []distribution.Descriptor { refs := make([]distribution.Descriptor, len(mb.Manifest.FSLayers)) for i := range mb.Manifest.FSLayers { @@ -79,15 +88,21 @@ func (mb *referenceManifestBuilder) References() []distribution.Descriptor { return refs } -// Reference describes a manifest v2, schema version 1 dependency. +// Reference describes a Manifest v2, schema version 1 dependency. // An FSLayer associated with a history entry. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. type Reference struct { Digest digest.Digest Size int64 // if we know it, set it for the descriptor. History History } -// Descriptor describes a reference +// Descriptor describes a reference. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. func (r Reference) Descriptor() distribution.Descriptor { return distribution.Descriptor{ MediaType: MediaTypeManifestLayer, diff --git a/manifest/schema1/sign.go b/manifest/schema1/sign.go index c862dd812..920fdb2dc 100644 --- a/manifest/schema1/sign.go +++ b/manifest/schema1/sign.go @@ -10,6 +10,9 @@ import ( // Sign signs the manifest with the provided private key, returning a // SignedManifest. This typically won't be used within the registry, except // for testing. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. func Sign(m *Manifest, pk libtrust.PrivateKey) (*SignedManifest, error) { p, err := json.MarshalIndent(m, "", " ") if err != nil { @@ -40,6 +43,9 @@ func Sign(m *Manifest, pk libtrust.PrivateKey) (*SignedManifest, error) { // SignWithChain signs the manifest with the given private key and x509 chain. // The public key of the first element in the chain must be the public key // corresponding with the sign key. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. func SignWithChain(m *Manifest, key libtrust.PrivateKey, chain []*x509.Certificate) (*SignedManifest, error) { p, err := json.MarshalIndent(m, "", " ") if err != nil { diff --git a/manifest/schema1/verify.go b/manifest/schema1/verify.go index ef59065cd..5d20cc5bb 100644 --- a/manifest/schema1/verify.go +++ b/manifest/schema1/verify.go @@ -9,6 +9,9 @@ import ( // Verify verifies the signature of the signed manifest returning the public // keys used during signing. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. func Verify(sm *SignedManifest) ([]libtrust.PublicKey, error) { js, err := libtrust.ParsePrettySignature(sm.all, "signatures") if err != nil { @@ -22,6 +25,9 @@ func Verify(sm *SignedManifest) ([]libtrust.PublicKey, error) { // VerifyChains verifies the signature of the signed manifest against the // certificate pool returning the list of verified chains. Signatures without // an x509 chain are not checked. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. func VerifyChains(sm *SignedManifest, ca *x509.CertPool) ([][]*x509.Certificate, error) { js, err := libtrust.ParsePrettySignature(sm.all, "signatures") if err != nil { diff --git a/testutil/manifests.go b/testutil/manifests.go index cf80bb47b..8886ec3e7 100644 --- a/testutil/manifests.go +++ b/testutil/manifests.go @@ -40,7 +40,10 @@ func MakeManifestList(blobstatter distribution.BlobStatter, manifestDigests []di } // MakeSchema1Manifest constructs a schema 1 manifest from a given list of digests and returns -// the digest of the manifest +// the digest of the manifest. +// +// Deprecated: Docker Image Manifest v2, Schema 1 is deprecated since 2015. +// Use Docker Image Manifest v2, Schema 2, or the OCI Image Specification. func MakeSchema1Manifest(digests []digest.Digest) (distribution.Manifest, error) { manifest := schema1.Manifest{ Versioned: manifest.Versioned{