distribution: Add in-scope and out-of-scope wording

Docker's use of Bearer requires information beyond what's covered in
RFC 6749 and 6750 [1].  Folks writing a client that will interact with
a Docker registry that uses that auth approach will need a "Docker
registry's 'Bearer' additions" spec to follow, but Derek believes the
situation is salvageable with external work [2].

Also pin the docker/registry links to a specific version so the links
will survive future docker/registry changes (including removing the
docs after the OCI picks them up).  As long as the TOB-selected
version isn't far behind (how far will the spec move during a week of
voting?), it should be easy for the new maintainets to catch up on any
subsequent drift.

The signing scope is from Stephen in [3].  The discovery scope is from
Derek [4].  The content-management scope is from Stephen [5] and Liang
[6].

[1]: xiekeyang/oci-discovery#64 (comment)
[2]: #37 (comment)
[3]: #35 (comment)
[4]: #34 (comment)
[5]: #35 (comment)
[6]: #37 (comment)

Signed-off-by: W. Trevor King <[email protected]>

Author: wking

proposals/distribution.md

@@ -1,12 +1,12 @@
 # Abstract
 
-The Docker registry protocol has become the defacto standard across the container registry world ([https://github.com/docker/distribution/blob/master/docs/spec/api.md](https://github.com/docker/distribution/blob/master/docs/spec/api.md)).
+The Docker registry protocol has become the defacto standard across the container registry world.
 
 In the OCI, having a solid, common distribution specification with conformance testing will ensure long lasting security and interoperability throughout the container ecosystem.
 
 ## Proposal
 
-TL;DR; Move [https://github.com/docker/distribution/tree/master/docs/spec](https://github.com/docker/distribution/tree/master/docs/spec) to [https://github.com/opencontainers/distribution-spec](https://github.com/opencontainers/distribution-spec)
+TL;DR; Move [`api.md`][api.md] to a new [distribution-spec project](https://github.com/opencontainers/distribution-spec).
 
 This proposal covers the distribution API spec, and while it does not cover the code for the docker-registry, that implementation is considered the reference implementation. There are other implementations of this protocol, not all are open-source though (Google gcr.io, Amazon ECR, CoreOS Quay, Gitlab registry, JFrog Artifactory registry, Huawei Dockyard, etc).
 
@@ -57,10 +57,90 @@ The API spec is currently considered v2 and we will start the specification at v
 
 ## Frequently Asked Questions (FAQ)
 
-* Does this include the code of the docker-registry?
-    * No. This is an API specification discussion.
+**Q: Does this include the code of the docker-registry?**
+
+A: No. This is an API specification discussion.
+
+**Q: Does this change the OCI Charter or Scope Table?**
+
+A: Not the charter, but it does change the scope table.
+This project is scoped to specifying per-image client ↔ registry interaction with an [HTTP][rfc7230]-based protocol.
+The following scope entries should be removed from the [scope table][scope]:
+
+* “Use of Hash as Content Addressable name for immutable containers”.
+    This entry is in scope for this project, and a more detailed entry will be added as described below.
+* “Creating Reference spec for optional DNS based naming & distribution”.
+    This entry conflates naming and distribution, which will be separated by this proposal.
+* “Standardizing on a particular Distribution method”.
+    This proposal will provide one (of possibly many) distribution specifications, so the old “There is no current agreement on how to distribute content” no longer applies.
+
+The following entries should be added to the [scope table][scope]:
+
+* “Specifying authentication and authorization schemes”.
+    Docker's current registry uses an [extension][token] of the [`Bearer`][rfc6750] [auth scheme][rfc7235-s2.1].
+    Work on specifying Docker's scheme will continue independently, and is orthogonal to the registry API.
+
+    * What: Specifying authentication and authorization schemes
+    * In/Out/Future: Out of scope
+    * Status: N/A
+    * Description: Defining protocols for authenticating and authorizing distribution access.
+    * Why: As a HTTP-based protocol, clients and servers can negotiate authentication via HTTP's [challenge-response authentication framework][rfc7235-s2.1].
+        There is no need for the distribution specification to choose a particular authentication scheme, because clients receiving 401 and 407 responses can use IANA's [HTTP Authentication Scheme Registry][iana-auth] to look up referenced schemes and take appropriate action.
+frameworkIt is reasonable to provide a standardized way to use DNS based distribution in conjunction with OCI without requiring its use.
+
+* “Creating a reference spec for optional DNS based naming and discovery”.
+    Discovery and registry protocols are completely separate and do not need to be added together.
+    This entry replaces part of the previous “Creating Reference spec for optional DNS based naming & distribution” entry.
+
+    * What: Creating a reference spec for optional DNS based naming and discovery
+    * In/Out/Future: In scope for future specification
+    * Status: Not currently being worked
+    * Description: Define a protocol for resolving an image name to retrieval information.
+        When we address this, we will also allow for alternative, parallel name-to-image discovery protocols in parallel with the OCI-specified protocol.
+    * Why: It is reasonable to provide a standardized way to use DNS based distribution in conjunction with OCI without requiring its use.
+        There are many good use cases for DNS based distribution, but not all use cases support this.
+        Furthermore, encoding the location of a bundle into the bundle can cause issues with downloads from alternate locations other than the origin specified in the name.
+
+* “Specifying a distribution method”.
+    This entry replaces part of the previous “Creating Reference spec for optional DNS based naming & distribution” and “Standardizing on a particular Distribution method” entries.
+
+    Retrieving images covers the current “tag listing”, because tags are entries in the image format's manifests array.
+    Other tag-listing endpoints needed for backwards-compatibility are therefore in scope as well.
+
+    Repository actions and listing images within a repository are considered part of distribution policy or content management and are out of scope for this entry's per-image action.
+
+    * What: Specifying a distribution method
+    * In/Out/Future: In scope
+    * Status: In progress (see opencontainers/distribution-spec)
+    * Description: Define a protocol for image, manifest, config, and blob creation, retrieval, and deletion.
+        Listing, creating, and deleting repositories and listing images within repositories are both out of scope for this entry.
+    * Why: This specification will provide on (of possibly many) distribution specifications.
+        Alternative distribution specifications may be developed for uses cases not covered by this specification, but defining them is out of scope for the OCI.
+
+* “Retrieving images by their content-addressable hash”.
+    Docker's registery API does not currently provide endpoints for fetching image or manifest objects by digest, but this is the project where that will happen.
+
+    * What: Retrieving images by their content-addressable hash
+    * In/Out/Future: In scope
+    * Status: In progress (see opencontainers/distribution-spec)
+    * Description: Specify a protocol for retrieving an image from a distribution engine by the image's content-addressable hash.
+    * Why: Using a hash as a name is a way to ensure a unique and container name without relying on a particular naming authority/or system.
+        Using hashing for name is an acceptable addition as it does not encode any centralized namespace.
+
+The following entries should remain in the [scope table][scope] but not be addressed by this project:
+
+* “Specifying way to attach signatures”.
+    We don't need to address this as part of distribution, because all resources are content-addressable and can be signed in external systems.
 
 ## Related GitHub Issues
 
 * Simplifies tag listing: docker/distribution#2169
 * Allows listing of manifests: docker/distribution#2199
+
+[api.md]: https://github.com/docker/distribution/blob/cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md
+[iana-auth]: http://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml
+[rfc6750]: https://tools.ietf.org/html/rfc6750
+[rfc7230]: https://tools.ietf.org/html/rfc7230
+[rfc7235-s2.1]: https://tools.ietf.org/html/rfc7235#section-2.1
+[scope]: https://www.opencontainers.org/about/oci-scope-table
+[token]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/auth/token.md