diff --git a/docs/README.md b/docs/README.md index 53f7d57..2baa514 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/bindle-spec.md b/docs/bindle-spec.md index 6240663..de17d72 100644 --- a/docs/bindle-spec.md +++ b/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 diff --git a/docs/keyring-protocol-spec.md b/docs/keyring-protocol-spec.md new file mode 100644 index 0000000..0f6355b --- /dev/null +++ b/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 diff --git a/docs/protocol-spec.md b/docs/protocol-spec.md index 7a7dfbd..5558da7 100644 --- a/docs/protocol-spec.md +++ b/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.