diff --git a/dist/assets/site.css b/dist/assets/site.css index 881b9aa..c480fb0 100644 --- a/dist/assets/site.css +++ b/dist/assets/site.css @@ -47,6 +47,31 @@ code.snippet { padding: 1em; } +.example { + display: flex; +} +.example div { + flex: 1; + min-width: 0; +} + +blockquote { + background: #f9f9f9; + border-left: 10px solid #ccc; + margin: 1.5em 10px; + padding: 0.5em 10px; +} +blockquote:before { + color: #ccc; + font-size: 4em; + line-height: 0.1em; + margin-right: 0.25em; + vertical-align: -0.4em; +} +blockquote p { + display: inline; +} + li { text-align: left; } diff --git a/dist/templates/about/api.html.hbs b/dist/templates/about/api.html.hbs index dfb1e35..7eb9848 100644 --- a/dist/templates/about/api.html.hbs +++ b/dist/templates/about/api.html.hbs @@ -6,50 +6,146 @@ Hagrid implements both the legacy HKP interface, as well as our native interface, VKS.
-Hagrid has its own URL scheme to fetch keys.
-GET /vks/v1/by-fingerprint/<FINGERPRINT>
+ Retrieves the key with the given Fingerprint.
+ The Fingerprint may refer to the primary key, or any subkey.
+ Hexadecimal digits MUST be uppercase,
+ and MUST NOT be prefixed with 0x
.
+ The returned key is ASCII Armored, and has a content-type of application/pgp-keys
.
+
- Retrieves the key with the
- given Fingerprint. Fingerprint may refer to the
- primary key, or any subkey. Hexadecimal digits MUST be uppercase,
- and MUST NOT be prefixed with 0x
. The returned key
- is ASCII Armored.
-
+ Retrieves the key with the given long KeyID.
+ The KeyID may refer to the primary key, or any subkey.
+ Hexadecimal digits MUST be uppercase,
+ and MUST NOT be prefixed with 0x
.
+ The returned key is ASCII Armored, and has a content-type of application/pgp-keys
.
+
GET /vks/v1/by-keyid/<KEY-ID>
+ Retrieves the key with the given E-Mail Address.
+ Only exact matches are accepted.
+ Lookup by e-mail address requires opt-in by the key's owner.
+ The returned key is ASCII Armored, and has a content-type of application/pgp-keys
.
+
- Retrieves the key with the given
- long KeyID. KeyID may refer to the primary key,
- or any subkey. Hexadecimal digits MUST be uppercase, and MUST NOT
- be prefixed with 0x
. returned key is ASCII
- Armored.
-
+ Keys may be submitted using a POST request to /vks/v1/upload.
+ The body of the request must be application/json
.
+ The JSON data must contain a single field keytext
,
+ which must contain the keys to submit.
+ Key data can be formatted in ASCII Armor, or base64.
+
GET /vks/v1/by-email/<URL-encoded user ID>
+ The returned JSON data
+ contains the fields token
, key_fpr
,
+ and status
.
+ The token
field contains an opaque value,
+ which can be used to perform request-verify requests
+ (see below).
+ The key_fpr
field contains the uploaded key's fingerprint.
+ The status
token contains a map of email addresses
+ contained in the key, with one of the values
+ unpublished
,
+ published
,
+ revoked
, or
+ pending
,
+ indicating the status of this e-mail address.
+
- Retrieves the key with the given User ID. Only exact - matches are accepted. Lookup by User ID requires opt-in - by the key's owner. The returned key is ASCII Armored. -
++{ + "keytext": "<ASCII ARMORED KEY>" +} ++
+{ + "key_fpr": "<FINGERPRINT>" + "status": { + "address@example.org": "unpublished" + }, + "token": "..." +} ++
POST /vks/v1/publish
+ A key that has been uploaded + can be made discoverable by one or more of its e-mail addresses + by proving ownership of the address + via a verification e-mail. + This endpoint requests verification + for one or more e-mail addresses. +
+
+ The call must include an opaque token
value
+ (obtained via /vks/v1/upload)
+ and an addresses
field,
+ which is a list of e-mail addresses (not full User IDs)
+ to request verification mails for.
+ The reply will be the same as for the /vks/v1/upload endpoint,
+ with addresses marked as pending
where a verification email
+ has been sent.
+
- Keys may be submitted using a POST request
- to /vks/v1/publish
, the body of the request being
- a multipart/form-data
query. keytext
- must be the keys to submit, either ASCII Armored or not.
- More than one key may be submitted in one request. Hagrid will
- send verification emails to every non-expired User ID.
-
+{ + "token": "...", + "addresses": [ + "address@example.org" + ] +} ++
+{ + "key_fpr": "<FINGERPRINT>" + "status": { + "address@example.org": "pending" + }, + "token": "..." +} ++
Hagrid implements a subset of the HKP @@ -57,54 +153,64 @@ without modification.
-GET /pks/lookup?op=get&options=mr&search=<QUERY>
Returns an ASCII Armored key matching the query. Query may be:
-localpart@example.org
.069C0C348DD82C19
, optionally prefixed by 0x
).
+ GET /pks/lookup?op=get&options=mr&search=<QUERY>
+
+ Returns an ASCII Armored key matching the query. Query may be:
+ +localpart@example.org
.069C0C348DD82C19
, optionally prefixed by 0x
).
+ 8E8C33FA4626337976D97978069C0C348DD82C19
,
+ optionally prefixed by 0x
).
+ + Note that while the hexadecimal digits may use either case, using + upper case letters is slightly more efficient with Hagrid. +
8E8C33FA4626337976D97978069C0C348DD82C19
,
- optionally prefixed by 0x
).
+ GET /pks/lookup?op=index&options=mr&search=<QUERY>
+ + Returns + a machine-readable + list of keys matching the query. Query may have the forms + detailed above. Hagrid always returns either one or no keys at + all. +
+
+ Keys may be submitted using a POST request to /pks/add,
+ the body of the request being
+ a application/x-www-form-urlencoded
query.
+ keytext
must be the keys to submit,
+ which must be ASCII Armored.
+ More than one key may be submitted in one request.
+ For verification of e-mail addresses,
+ the /vks/v1/upload endpoint
+ must be used instead.
+
- Note that while the hexadecimal digits may use either case, using - upper case letters is more efficient with Hagrid. -
- -GET /pks/lookup?op=index&options=mr&search=<QUERY>
- Returns - a machine-readable - list of keys matching the query. Query may have the forms - detailed above. Hagrid always returns either one or no keys at - all. -
- -POST /pks/add
- Keys may be submitted using a POST request
- to /pks/add
, the body of the request being
- a application/x-www-form-urlencoded
query.
- keytext
must be the keys to submit, which must
- be ASCII Armored. More than one key may be submitted in
- one request.
- By design, Hagrid cannot (or intentionally chooses not to) implement, - the full HKP protocol. The main limitations are: + By design, Hagrid does not implement the full HKP protocol. The specific + limitations are:
- « Back -
+