diff --git a/keps/kep1.md b/keps/kep1.md new file mode 100644 index 0000000000000000000000000000000000000000..7cfbdc3cad6151a3935f7db202e1b5b5bf937a3c --- /dev/null +++ b/keps/kep1.md @@ -0,0 +1,107 @@ +KEP #1: Simple v6 compatible API + +# Motivation + +The upcoming RFC based on the "crypto-refresh" draft will introduce a version 6 of the OpenPGP packet format. +Hagrid currently supports only the public key format version 4, which is incompatible to v6. +Keyservers in particular play a role for the transition and rollover from v4 to v6 certificates. + +This proposal is meant to serve as a baseline for discussion of new APIs for v6 support. + +# Proposed solution + +This proposed solution effectively copies the existing API, introducing v4 and v6 variants that are almost fully independent from one another. +The certificate storage backends of v4 and v6 certificates are not shared, and do not interact in any way. + +This means that certificates are uploaded and managed fully separately. + +## Retrieval API + +The current API assumes that all certificates are v4 certificates. +The available routes are specifically: +* `/v1/by-email` +* `/v1/by-fingerprint` +* `/v1/by-keyid` + +We introduce a /v2/ API, that trivially adds a v4 vs v6 indicator to each route: + +* `/v2/4/by-email` +* `/v2/4/by-fingerprint` +* `/v2/4/by-keyid` +* `/v2/6/by-email` +* `/v2/6/by-fingerprint` +* `/v2/6/by-keyid` + +The v6 routes behave identically to v4 ones, except they return a v6 certificate. + +## Upload API + +For upload, the following endpoints exist: +* `/v1/upload` +* `/v1/request-verify` + +The existing APIs could be reused without change in routes, by allowing processing of v6 certificates. +However, to reflect the independent nature of v4 and v6 retrieval endpoints, we introduce the same distinction: +* `/v2/4/upload` +* `/v2/4/request-verify` +* `/v2/6/upload` +* `/v2/6/request-verify` + +The semantics remain the same, for v4 and v6 certificates respectively. + +## Management UI + +The management UI shall show v4 and v6 certificates for the managed email address on the same page, but separated. + +# Rationale + +This spec is likely the simplest possible option, and its primary merit is simplicity: +The entire spec can be written on a napkin, explained in few minutes, and is very resistant to misinterpretation by implementers. + +No assumptions are changed about the way Hagrid currently works. +This means little additional reasoning or implementation work is required to put it into practice. + +Since no v6 clients or keyservers exist, it is also difficult to anticipate their needs. +With a simple and relatively unopinionated approach, the step to a more integrated at a later time when more experience with v6 clients is available remains tangible. + +# Drawbacks + +The main drawback of this method is the need for clients to perform two requests to retrieve both certificates. +In terms of loading time, this is somewhat offset by the simplicity of both requests, and multiplexing features of HTTP 2. +The shape of the modern web also demonstrates that this is not a big issue in practice; +For instance, displaying google.com in a browser performs more than 30 requests at the time of writing. + +Another potential drawback is that any version we deploy will likely have to be supported forever, even if a more advanced API is introduced later. + +There is also a window of success with this approach that is not ideal, but just good enough to remove future incentives to move to a more advanced approach. + +Depending on perspective, KOO might also miss an opportunity to pioneer the API landscape with a stronger and more opinionated approach. + +# Implementation concerns + +Almost all control flow required already exists, and can likely be easily copied into a v6 variant. + +The management UI will have to handle two certificates, but this as well can likely be achieved by copying and adapting of existing flows. + +One concern is the path length of certificate symlinks by fingerprint, which might exceed the maximum length for direct resolution in ext4. +This should be checked during implementation. + +# Extensions + +## Combined requests + +A simple extension would be to offer a `/v2/4+6` endpoint, that serves the content of both individual endpoints. +This would allow clients to retrieve all data with a single roundtrip. +However, for clients using HTTP 2, the benefit of this extra route is small. + +# Alternatives + +## Extend v1 API + +A similar alternative would be to eschew a version 2 of the VKS API, by only introducing a `/v1/6/` route. +However, that leaves the non-marked namespace to v4, reinforcing the impression that v4 is the default and v6 is something else. +It is also ambiguous without context whether the regular `/v1/` routes will return only v4, or both v4 and v6. + +## More complicated approaches + +To be determined