Skip to content

Commit

Permalink
Merge pull request #295 from thomastaylor312/docs/keyring-protocol-spec
Browse files Browse the repository at this point in the history
docs(spec): Adds new Keyring protocol spec
  • Loading branch information
thomastaylor312 authored Feb 11, 2022
2 parents 7ce2004 + 209531a commit c76b022
Show file tree
Hide file tree
Showing 4 changed files with 49 additions and 3 deletions.
5 changes: 3 additions & 2 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand Down
1 change: 1 addition & 0 deletions docs/bindle-spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
43 changes: 43 additions & 0 deletions docs/keyring-protocol-spec.md
Original file line number Diff line number Diff line change
@@ -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
3 changes: 2 additions & 1 deletion docs/protocol-spec.md
Original file line number Diff line number Diff line change
@@ -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`).

Expand All @@ -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.

Expand Down

0 comments on commit c76b022

Please sign in to comment.