Merge pull request deislabs#295 from thomastaylor312/docs/keyring-pro…

…tocol-spec

docs(spec): Adds new Keyring protocol spec

docs/README.md

@@ -211,7 +211,7 @@ roles = ["creator"]
 A user only needs one such keypair (though a user is free to have more).
 This file can be moved from system to system, just like OpenPGP or SSH key sets.
 
-- To create a signing key for a client, use `bindle create-key`
+- To create a signing key for a client, use `bindle keys create`
 - By default, if Bindle does not find an existing keyring, it creates one of these when it first starts.
 
 ## Specification
@@ -221,7 +221,8 @@ This file can be moved from system to system, just like OpenPGP or SSH key sets.
 3. The [parcel spec](parcel-spec.md) defines the parcel format.
 4. The [label spec](label-spec.md) describes the parcel label format.
 5. The [protocol specification](protocol-spec.md) describes the HTTP protocol for storing and retrieving Bindles.
-6. Finally, the [Standalone Bindle Specification](standalone-bindle-spec.md) describes a format for packaging up a Bindle into a portable artifact
+6. The [keyring protocol specification](keyring-protocol-spec.md) describes an HTTPS protocol for distributing keys.
+7. Finally, the [Standalone Bindle Specification](standalone-bindle-spec.md) describes a format for packaging up a Bindle into a portable artifact.
 
 ## Additional Docs
 

docs/bindle-spec.md

@@ -80,3 +80,4 @@ If that doesn't make sense, you haven't seen Stargazer Tianyan yet.
 - The [Protocol Specification](protocol-spec.md) describes how Bindles are transported from place to place, and how parcels are intelligently fetched based on need.
 - The [Signing Specification](signing-spec.md) describes how Bindles may be signed and verified
 - The [Standalone Bindle Specification](standalone-bindle-spec.md) describes a format for packaging up a Bindle into a portable artifact
+- The [Keyring Protocol Specification](keyring-protocol-spec.md) describes an HTTPS protocol for distributing keys

docs/keyring-protocol-spec.md

@@ -0,0 +1,43 @@
+# Keyring Protocol Specification
+
+This specification describes an HTTPS protocol for fetching public key entries for use in Bindle
+keyrings. It is _not required_ to distribute keys in this manner, but it does allow for a convenient
+way to distribute well known keys.
+
+## Path and Protocols
+
+Implementations MUST use HTTP secured with TLS (i.e. HTTPS) in order to guarantee that the received
+data has not been tampered with. Implementations are not required to only host this protocol as part
+of a single server (e.g. they can serve other endpoints besides the keys).
+
+It is RECOMMENDED that implementations serve this protocol on the `/bindle-keys` path, mounted onto
+any path prefixes (e.g. `/api/v1/bindle-keys`).
+
+## Verbs and Parameters
+
+Implementations MUST support the `GET` HTTP verb and MAY support `HEAD`. All other verbs MUST NOT be
+used.
+
+Implementations MUST support the following query string parameters. Other parameters MAY be added by
+implementations, but they are considered non standard. If no query string parameters are specified,
+implementations SHOULD return all available keys.
+
+- `roles`: A comma delimited list of roles to filter on. All keys with these roles will be returned.
+  Example: `roles=creator,approver`. Allowed roles can be found in the [signing
+  spec](./signing-spec.md#signing-and-roles)
+
+## Response Data
+
+Implementations MUST return a keyring response in TOML as specified in the [signing
+spec](./signing-spec.md#keyrings). Implementations MAY also support other serialization formats such
+as JSON. Different formats MUST be requested with the HTTP `Accept` header. If no `Accept` header is
+specified, implementations MUST return the response as TOML
+
+## Authentication and Authorization
+
+Implementations MAY require authentication and authorization
+
+## Exclusions
+
+This specification explicitly excludes any guidelines on how keys may be uploaded to a server as
+there could be many different methods of uploading keys depending on the circumstances

docs/protocol-spec.md

@@ -1,6 +1,6 @@
 # The Bindle Protocol
 
-Bindle uses HTTP/2 with TLS as a transport protocol. All bodies and responses expect to use the TOML, with the `application/toml` content type. Other content types may be supported (such as the reference server supporting `application/json`), but are not required by the specification
+Bindle uses HTTP/2 with TLS as a transport protocol. All bodies and responses expect to use TOML, with the `application/toml` content type. Other content types may be supported (such as the reference server supporting `application/json`), but are not required by the specification
 
 The HTTP endpoints defined above MAY exist as a subpath on a server, or in the server's root. For example, `https://example.com/v1/_i/foo` and `https://example.com/_i/foo` are both legal paths for the specification below. However, `https://example.com/_i/v1/foo` is not (or, rather, it is a legal URI for a package named `v1/foo`).
 
@@ -22,6 +22,7 @@ HTTP Endpoints:
 - `/login`: Triggers a login flow for the API
   - `GET`: Redirects to the login provider to start an OIDC device login flow. It will trigger a Device Authorization Flow as defined in [RFC8628](https://datatracker.ietf.org/doc/html/rfc8628). The response will be a standard response as defined in [Section 3.2]( https://datatracker.ietf.org/doc/html/rfc8628#section-3.2) with 2 additional parameters: `client_id` will contain the client ID of the OIDC provider, and `token_url` will contain the OAuth2 token authorization endpoint for use in obtaining tokens. This endpoint supports the following query parameters:
     - `provider` (required): The name of the provider to use: For example: `provider=github`.
+- `/bindle-keys`: An OPTIONAL implementation of the [keyring protocol specification](./keyring-protocol-spec.md). The reference implementation only exposes public keys with the `host` role, but other implementations MAY support all types of keys
 
 While bindle names MAY be hierarchical, neither the `_i` nor the `_p` endpoints support listing the contents of a URI. This constraint is for both scalability and security reasons. To list available bindles, agents MUST use the `_q` endpoint if implemented. In absence of the `_q` endpoint, this specification does not support any way to list available bindles. However, implementations MAY support alternative endpoints, provided that the URI for those endpoints does not begin with the `_` character.