| Internet-Draft | HKP | August 2025 |
| Shaw & Gallagher | Expires 2 March 2026 | [Page] |
This document specifies a series of conventions to implement an OpenPGP keyserver using the Hypertext Transfer Protocol (HTTP). As this document is a codification and extension of a protocol that is already in wide use, strict attention is paid to backward compatibility with these existing implementations.¶
This note is to be removed before publishing as an RFC.¶
The latest revision of this draft can be found at https://andrewgdotcom.gitlab.io/draft-gallagher-openpgp-hkp. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-gallagher-openpgp-hkp/.¶
Discussion of this document takes place on the OpenPGP Working Group mailing list (mailto:openpgp@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/openpgp/. Subscribe at https://www.ietf.org/mailman/listinfo/openpgp/.¶
Source for this draft and an issue tracker can be found at https://gitlab.com/andrewgdotcom/draft-gallagher-openpgp-hkp.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 2 March 2026.¶
Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
For ease of use, public key cryptography requires a key distribution system. For many years, the most commonly used system has been a keyserver - a server that stores public keys and/or certificates, with a searchable interface. The HTTP Keyserver Protocol is a OpenPGP keyserver implemented using HTTP.¶
The term "OpenPGP Certificate" is used in this document interchangeably with "OpenPGP Transferable Public Key", as defined in Section 10.1 of [RFC9580].¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
A keyserver is typically used for the following (non-exhaustive) use cases:¶
When initiating secure communication with a new correspondent, a client will typically attempt to discover the encryption key(s) that it should use. This is a subtle issue with many security considerations, however many discovery methods involve looking up a certificate on a server using a human-readable identifier such as an email address.¶
Certificates in OpenPGP are dynamic objects, therefore it is important to refresh known certificates in order to pick up the latest changes. These changes can include new subkeys and User IDs, updated self-signatures and third-party certifications, and revocations. In some cases it may no longer be possible to search by User ID, therefore it is RECOMMENDED that clients refresh known certificates by fingerprint search.¶
The OpenPGP wire format includes fields that reference primary keys or subkeys by either Key ID or fingerprint. A client may therefore wish to search for previously unknown certificates based on such a reference.¶
As HKP is implemented over HTTP, everything in [RFC1945] applies to HKP as well, and HKP error codes are the same as the ones used in HTTP.¶
Due the very large deployment of HKP clients based on HTTP version 1.0, HKP keyservers MUST support HTTP 1.0. HKP keyservers MAY additionally support other HTTP versions.¶
(( dshaw : I expect this to be controversial, but we've got tons of deployed code that only works with 1.0. I'd be willing to discuss removing this MUST or make it a SHOULD and add a "implementation notes" section pointing out the problem instead. See issue #5. ))¶
When used over HTTPS, HKP is commonly referred to as "HKPS".¶
HKP(S) are distinguished from generic use of HTTP(S) by using the URI schemes "hkp" and "hkps" [RFC7595]. HKP is assigned port number 11371 and HKPS is assigned 11372 (although this is rarely used in practice). For reasons of maximum compatibility with firewalls and filtering HTTP proxies, HKP(S) are often served over the standard HTTP(S) port(s) (TCP ports 80 and 443).¶
By convention and history, HKP defaults to HTTP on TCP port 11371, and HKPS defaults to HTTPS on TCP port 443.¶
(( andrewg : if we assign hkps, we appear to be required to specify a dedicated port, even though nobody uses it. See issue #14. ))¶
A keyserver SHOULD support both HKP and HKPS. A client SHOULD use HKPS, or a transport method with equivalent security properties, such as Tor hidden services [TOR].¶
HKP defines three paths, namely "/pks/lookup" for legacy lookups (see Section 5), "/pks/add" for legacy submission (see Section 6), and "/pks/v2" for lookups and submission in the v2 API. Paths beginning with "/pks/v<?>" are reserved for future versions of HKP.¶
A keyserver MAY support requests to other paths under "/pks", but these are outside the scope of this document. These alternative paths have historically been used to provide human-readable interfaces such as HTML forms, and functionality extensions such as [SKS].¶
When a status or error code needs to be returned by a keyserver, the most appropriate HTTP code from [RFC9110] should be used. It is good practice to return the most specific error code possible: for example, returning 404 ("Not Found") rather than 400 ("Bad Request") when a certificate is not found.¶
This document gives suggested HTTP error codes for several common situations. Note that these are only suggestions, and implementations may have good reasons (such as not revealing the reason why a request failed) for using other error codes.¶
Clients SHOULD understand the following codes:¶
| Status Code | Description |
|---|---|
| 200 OK | Request succeeded |
| 403 Forbidden | The requested operation is not permitted |
| 404 Not found | The search returned no results, or path not found |
| 410 Gone | Requested data has been permanently deleted, e.g. due to RTBF |
| 422 Unprocessable content | Submission was not well formed |
| 501 Not implemented | The requested operation is not supported |
In addition, a client SHOULD understand 3xx redirect codes.¶
HKP specifies the GET, OPTIONS and HEAD methods for lookup paths (Section 5) and the POST and OPTIONS methods for submission paths (Section 6).¶
Certificate lookups are done via an HTTP GET request. Specifically, the abs_path (Section 3.2 of [RFC1945]) is built up of the base path "/pks/lookup" or "/pks/v2", followed by request-specific URL components. These components differ slightly between the Legacy and v2 lookup formats (see below).¶
Most HKP lookups contain both the "op" (operation) and "search" fields. The "op" field determines what operation the keyserver will execute, and the "search" field determines which certificates are operated on.¶
There may also be modifier variables, as specified in Section 7 below. Variables are passed using HTTP query strings as specified in Section 8.2.2 of [RFC1866]. HTTP query strings MAY be given in any order. Keyservers MUST ignore any unknown query strings.¶
For backwards compatibility with the existing installed client base, a Legacy lookup format is defined. New implementations SHOULD use the v2 lookup format.¶
In the Legacy lookup format, the "op" and "search" fields are supplied as HTTP query strings, in the form "<field-name>=<value>":¶
/pks/lookup?op=<op>&search=<search>[&...]¶
They are treated in the same way as modifier variables, including arbitrary ordering, however the "op" field MUST be supplied, and the "search" field MUST be supplied unless the "stats" operation is being requested (see Section 5.2.9). No URL path components under "/pks/lookup" are used.¶
In the v2 lookup format, the values of the "op" and "search" fields are supplied as URL path components. They are appended to "/pks/v2" as follows:¶
/pks/v2/<op>/<search>[?...]¶
The "op" and "search" fields MUST be supplied. Modifier variables are supplied as HTTP query strings, in the form "<field-name>=<value>".¶
If the v2 lookup format is being used, v2 output format (Section 8) MUST be returned.¶
The v2 lookup format is designed so that a basic HKP service can be implemented using static files.¶
The operation ("op") field specifies the lookup operation to be performed on the keyserver. The "op" field is generally accompanied by a "search" field to specify the certificates that should be looked up.¶
If a particular operation is not supported, the keyserver SHOULD return an appropriate HTTP error code such as 501 ("Not Implemented"). The server SHOULD NOT return an error code (such as 404 ("Not Found")) that could be interpreted by the client as an explicit statement of non-existence.¶
| Name | Legacy | Search field | Output data | See |
|---|---|---|---|---|
| get | text | Certificate bundle | Section 5.2.1 | |
| authget | UID or email | Certificate bundle | Section 5.2.2 | |
| prefixlog | date | List of prefixes | Section 5.2.3 | |
| vfpget | versioned fp | Certificate bundle | Section 5.2.4 | |
| kidget | key ID | Certificate bundle | Section 5.2.5 | |
| hget | SKS hash | Certificate bundle | Section 5.2.6 | |
| index | text | Index of certificates | Section 5.2.7 | |
| vindex | yes | text | Index of certificates | Section 5.2.8 |
| stats | yes | (none) | Implementation info | Section 5.2.9 |
A keyserver MAY support the "get" operation.¶
The "get" operation requests certificates from the keyserver by textual search. A string that specifies which certificate(s) to return is provided in the "search" field.¶
The response to a successful "get" operation is a HTTP document containing a certificate bundle as specified in Section 10.¶
A keyserver SHOULD limit the returned certificate bundle to a reasonable length. Results from a User ID search SHOULD be sorted in order of decreasing confidence in that User ID (Section 9), and then by creation date (most recent first). A keyserver MAY choose to only return results where the User ID being searched for has a nonzero confidence value. If no certificates match the request, the keyserver SHOULD return an appropriate HTTP error code such as 404 ("Not Found").¶
A keyserver SHOULD support the "authget" operation.¶
The "authget" operation is similar to the "get" operation, but is used for authoritative lookups by User ID only, in particular during certificate discovery. The keyserver SHOULD only return results where the User ID being searched for has a nonzero confidence value (Section 9). If a keyserver is being used for certificate discovery, it MUST return only results for which it is has complete confidence.¶
A keyserver MAY support the "prefixlog" operation.¶
"prefixlog" requests a list of fingerprint prefixes that indicate which certificates have been modified since 00:00:00 UTC on a specific date. The date is provided in the "search" field in ISO 8601 format with no time component, i.e. "2025-12-01".¶
The returned data is a list of CRLF-separated, hexadecimal-encoded fingerprint prefixes, and each prefix is truncated at a hex-digit boundary. Fingerprint prefixes do not include the version number. The keyserver SHOULD calibrate the prefix length so that it is long enough to provide collision resistance, but short enough to maintain a useful anonymity cohort. For example, if the prefix length was too short, clients could be induced to make excessive numbers of network requests. A client MUST NOT make any assumptions about the length of the prefixes returned.¶
A client that wishes to update its local keystore from a keyserver MAY first make a "prefixlog" request with the date of the last successful refresh. It can then compare the returned list of prefixes to see if any of them are present in its local keystore, and make subsequent "vfpget" requests as appropriate (Section 5.2.4). In this way, it can avoid making unnecessary requests that will return no updates, but will still leak information to the keyserver.¶
Note that prefixes are always used, regardless of fingerprint version. This contrasts with Key IDs, which are version-dependent.¶
A keyserver MUST NOT support indexing or downloading certificates by prefix.¶
A keyserver MAY support the "vfpget" operation.¶
"vfpget" requests a certificate from a keyserver by specifying its versioned fingerprint. The versioned fingerprint is provided in the "search" field in hexadecimal encoding, without a preceding "0x". The hexadecimal digits are not case sensitive.¶
A versioned fingerprint consists of one octet of fingerprint version number and N octets of fingerprint. This is the same octet sequence used in the Issuer Fingerprint and Intended Recipient Fingerprint subpackets (Section 5.2.3 of [RFC9580]).¶
If no certificates match the request, the keyserver SHOULD return an appropriate HTTP error code such as 404 ("Not Found").¶
A keyserver MAY support the "kidget" operation.¶
"kidget" requests a certificate from a keyserver by specifying its Key ID (Section 5.5.4 of [RFC9580]). The Key ID is provided in the "search" field as 16 hexadecimal digits, without a preceding "0x". The hexadecimal digits are not case sensitive.¶
If no certificates match the request, the keyserver SHOULD return an appropriate HTTP error code such as 404 ("Not Found").¶
"kidget" is only required for locating a signing key that made either a V3 signature, or a V4 signature with an Issuer Key ID subpacket and no Issuer Fingerprint subpacket. Issuer Key ID subpackets are not specified for use in later signature versions (Section 5.2.3.12 of [RFC9580]), and so certificates with versions greater than 4 MUST NOT be returned in response to a "kidget" operation.¶
A keyserver MAY support the "hget" operation.¶
"hget" requests a certificate from a keyserver by specifying its [SKS] digest. The digest is provided in the "search" field in hexadecimal encoding, without a preceding "0x". The hexadecimal digits are not case sensitive.¶
If no certificates match the request, the keyserver SHOULD return an appropriate HTTP error code such as 404 ("Not Found").¶
A keyserver MAY support the "index" operation.¶
The "index" operation requests a list of certificates on the keyserver that match the text in the "search" field. Historically, the "index" operation returned a human-readable HTML document containing links for each found certificate, but this is not required.¶
A keyserver SHOULD limit the returned index to a reasonable length. Results from a User ID search SHOULD be sorted in order of decreasing confidence in that User ID (Section 9), and then by creation date (most recent first). If no certificates match the request, the keyserver SHOULD return an appropriate HTTP error code such as 404 ("Not Found").¶
A keyserver MAY support the "vindex" operation for Legacy lookups. The "vindex" operation is deprecated and MUST NOT be used in a v2 lookup.¶
Historically, a "vindex" response was the same as "index" with the addition of showing the signatures on each certificate, but this is not required. A server that supports "vindex" SHOULD treat it as a synonym for "index".¶
A keyserver MAY support the "stats" operation in Legacy lookup format. The "stats" operation is deprecated, and MUST NOT be used in a v2 lookup. It is RECOMMENDED to use a URL outside the standard HKP paths (such as "/pks/stats") instead.¶
The output of the "stats" operation is implementation-dependent, but may include diagnostic output, configuration state, or other metadata. The "search" field SHOULD NOT be supplied, and SHOULD be ignored if received.¶
The "search" field contains arbitrary text encoded as usual for a HTTP URL. This text may represent the Key ID, or fingerprint, or some text from a User ID on the certificate being sought, depending on the operation.¶
To search for a certificate by its Key ID or fingerprint, a client SHOULD use a v2 lookup and either the "kidget" (Section 5.2.5) or "vfpget" (Section 5.2.4) operation (as appropriate).¶
If making a Legacy lookup, a client SHOULD use the "get" operation and prefix the "search" string with "0x" to indicate a hexadecimal number. Key ID strings are 16 hexadecimal digits (64 bits). Fingerprint strings are either 32 (version 3), 40 (version 4), or 64 (version 6) hexadecimal digits and do not include the version number. The hexadecimal digits are not case sensitive.¶
A keyserver:¶
SHOULD accept fingerprints and MAY accept 64-bit Key IDs in the Legacy lookup "search" field.¶
MUST NOT return results for 32-bit "short Key ID" searches, as these do not provide sufficient collision resistance.¶
MUST NOT return certificates with versions later than 4 for Key ID searches.¶
MUST NOT return version 6 (or later) certificates in the results for Legacy machine-readable requests, but MAY do so for Legacy human-readable requests (see Section 8.3).¶
V3 certificates are no longer considered secure, but MAY be distributed for historical reference.¶
To search for a certificate by the text of a User ID, a client SHOULD use the "get", "authget", or "index" operation (as appropriate) and MUST NOT prefix the "search" string with "0x". A keyserver MUST NOT return version 6 (or later) certificates in the results for Legacy machine-readable requests, but MAY do so for Legacy human-readable requests (see also Section 8.3.1).¶
A keyserver SHOULD only return results if the "search" field exactly matches one of the following:¶
The full text string of a User ID.¶
The portion between angle brackets ("<...>") in an email-address style User ID.¶
A keyserver MAY return results for non-exact matches in a Legacy request. A client making a Legacy text search SHOULD therefore set the modifier variable "exact=on" (see Section 7.5).¶
To ensure that relevant results are returned, it is RECOMMENDED that implementations limit themselves to a subset of UTF-8 when generating both User IDs and search strings:¶
Use lowercase in the domain part of email addresses.¶
Avoid leading or trailing whitespace.¶
Avoid control characters, including format effectors (such as tabs or newlines).¶
A keyserver MUST NOT return text search results for a search string that begins with "0x". Since the "0x" prefix is generally understood as indicating a fingerprint or key ID, violating this convention could enable a key substitution attack.¶
A client MAY attempt to detect which lookup operations a keyserver supports by making an OPTIONS request (Section 9.3.7 of [RFC9110]) to a lookup path with the "op" field present but the "search" field absent.¶
A keyserver that supports the lookup operation MAY respond with:¶
a 200 "OK" code,¶
an "Allow:" response header that includes the value "GET" (Section 10.2.1 of [RFC9110]).¶
Otherwise, it SHOULD respond with an error code such as 501 "Not Implemented". Note however that a keyserver that does not support OPTIONS (for example, if it is implemented using static files) MAY return another error code such as 404 "Not Found" or 405 "Method Not Allowed".¶
A client SHOULD NOT attempt to make a GET request to a lookup path without both the "op" and "search" fields present. A keyserver SHOULD return an error code such as 403 "Forbidden" to such a request.¶
A client MAY attempt to retrieve the metadata of a certificate or certificate bundle by making a HEAD request (Section 9.3.2 of [RFC9110]) to a full lookup path, with the "op" and "search" fields present. A keyserver SHOULD respond with the same header fields that it would have responded with if a GET request had been made.¶
Search for all certificates containing the email address "dshaw@example.com", using plaintext HTTP:¶
Legacy lookup format:¶
http://keys.example.com:11371/pks/lookup?search=dshaw@example.com&op=index¶
v2 lookup format:¶
http://keys.example.com:11371/pks/v2/index/dshaw@example.com¶
Get certificate 0xDEADBEEFDECAFBAD (64-bit Key ID), using HTTPS:¶
A keyserver MAY accept submissions via an HTTP POST request, as specified in Section 8.3 of [RFC1945], and Section 8.2.3 of [RFC1866]. Specifically, the abs_path (Section 3.2 of [RFC1945]) is built up of the base path "/pks/add" or "/pks/v2", followed by request-specific URL components. These components, and the form of the POST body, differ between the Legacy and v2 submission formats (see below).¶
There may also be modifier variables, as specified in Section 7 below. Modifiers are passed using HTTP query strings as specified in Section 8.2.2 of [RFC1866]. HTTP query strings MAY be given in any order. Keyservers MUST ignore any unknown query strings.¶
For backwards compatibility with the existing installed client base, a Legacy submission format is defined. New implementations SHOULD use the v2 submission format. Note that more than one certificate may be submitted in a single transaction.¶
If a keyserver does not support adding certificates via HTTP, then requests to do so should return an appropriate HTTP error code, such as 403 ("Forbidden") if certificate submission has been disallowed, or 404 ("Not Found") if the server does not support the requested submission format.¶
In the Legacy submission format, the abs_path (Section 3.2 of [RFC1945]) is always "/pks/add":¶
/pks/add[?...]¶
No URL path components under "/pks/add" are used, and there are no mandatory query strings.¶
The body of the POST message has a content-type of "application/x-www-form-urlencoded". It contains a "keytext" field whose value is an ASCII-armored certificate bundle as specified in Section 10. The ASCII armored certificate bundle should also be urlencoded as specified in Section 8.2.1 of [RFC1866].¶
In the v2 submission format, the value of the operation field is supplied as a URL path component, and is appended to "/pks/v2" as follows:¶
/pks/v2/<op>[?...]¶
The "op" field MUST be supplied. Unlike lookup requests, there is no "search" field defined.¶
The operation ("op") field specifies the submission operation to be performed on the keyserver. If a particular submission operation is not supported, the keyserver SHOULD return an appropriate HTTP error code such as 501 ("Not Implemented").¶
| Name | Legacy | Input data | Output data | See |
|---|---|---|---|---|
| add | various | submission response | Section 6.2.1 | |
| tokensend | email list | (none) | Section 6.2.2 |
A keyserver MAY support the "add" operation. A keyserver that implements submission SHOULD support the basic submission workflow described in Section 6.2.1.1. It MAY support other workflows; if so it SHOULD advertise them as described in Section 6.3.¶
A keyserver SHOULD respond to "add" operations with a JSON document as described in Section 8.2.¶
Basic submission uses a content-type of "application/pgp-keys;armor=no". The body of the POST message contains a certificate bundle as specified in Section 10, which MUST NOT be ASCII-armored.¶
The URL MAY additionally contain a "tokens" query parameter (Section 7.2). The "add" operation MAY have limited effect or fail entirely if a token corresponding to the email address in any of the submitted User IDs is not provided. If so, the keyserver SHOULD advertise this (see Section 6.3).¶
(Note that a keyserver MAY accept other forms of User ID verification, so the lack of a "tokens" query parameter will not necessarily result in submission failure.)¶
Advanced submission uses a content-type of "multipart/form-data". The body of the POST message contains a multipart with one or more parts. The required part has a content type of "application/pgp-keys;armor=no" and MUST be named "keytext". This part contains a certificate bundle as specified in Section 10, which MUST NOT be ASCII-armored.¶
Other parts MAY be included as required by an advanced submission workflow. No advanced submission workflows are currently specified.¶
A keyserver MAY support the "tokensend" operation.¶
The body of the POST message is a CRLF-separated list of email addresses. It SHOULD have a content-type of "text/plain". The keyserver SHOULD respond with an empty document.¶
A keyserver that supports the "tokensend" operation SHOULD attempt to verify each address by sending a time-limited auth token via email. A client that receives the verification email can then use the token(s) in a basic submission request (Section 6.2.1.1). A keyserver MAY limit the number and frequency of verification requests.¶
The verification email SHOULD contain a multipart/alternative message with two parts:¶
A JSON-LD structured mail document [I-D.ietf-sml-structured-email].¶
A human-readable document containing instructions for manual submission.¶
The schema for the JSON-LD document is (( TBC, issue #40 )), and it contains the following fields:¶
| Field | Type | Description |
|---|---|---|
| string | email address being verified | |
| url | string | URL to be used for submission |
| token | string | verification token |
| expires | timestamp | expiry time of the token |
Timestamps are given in ISO 8601 format.¶
A client that wishes to verify multiple email addresses on the same certificate bundle MAY wait until multiple verification emails have arrived and then submit the certificate bundle with multiple tokens in the "tokens" field (comma separated). A client MAY therefore submit a certificate bundle any number of times with various combinations of tokens; a keyserver SHOULD handle such repeat submissions gracefully (( TBC: how exactly? issue #39 )).¶
(( TBC: this follows a prove-then-submit model, which is the inverse of KOO's current submit-then-prove process. The rationale is that submit-then-prove often silently degrades to "submit-then-forget-to-prove". Failed advance proofs are less likely to be mis-reported as a success. In addition, prove-then-submit more easily generalises to other forms of verification. Is this defensible? issue #41 ))¶
A client MAY attempt to detect which certificate submission workflows a keyserver supports by making an OPTIONS request (Section 9.3.7 of [RFC9110]) to the path /pks/v2/add.
A keyserver that supports v2 submission SHOULD respond with:¶
a 200 code,¶
an "Allow:" response header that includes the value "POST" (Section 10.2.1 of [RFC9110]),¶
one or more "Accept:" response header(s) (Section 12.5.1 of [RFC9110]).¶
Accept response media types MAY include:¶
application/pgp-keys - basic submission without proof¶
application/pgp-keys;proof=tokens - basic submission with token proof¶
multipart/form-data;proof=dkim - advanced submission with DKIM proof (EXPERIMENTAL)¶
(( TBC: check the requirements for CORS preflight, issue #38 ))¶
(( to be completed, issue #39 ))¶
These variables are used to modify basic requests.¶
| Name | Legacy | Context | Value | See |
|---|---|---|---|---|
| options | any | list of flags | Section 7.1 | |
| tokens | submission | list of flags | Section 7.2 | |
| fingerprint | yes | lookup | "on" or "off" | Section 7.3 |
| hash | yes | lookup | "on" or "off" | Section 7.4 |
| exact | yes | lookup | "on" or "off" | Section 7.5 |
This variable takes one or more option values, separated by commas. These are used to modify the behavior of the keyserver on a per-request basis. Each value indicates a boolean flag, where the presence of the value indicates "true" and the absence "false".¶
| Name | Legacy | Context | See |
|---|---|---|---|
| nm | submission | Section 7.1.1 | |
| cb | submission | Section 7.1.2 | |
| mr | yes | lookup | Section 7.1.3 |
As keyservers may modify submitted certificates to suit a particular policy, this option is used to inform the keyserver that the submitter would rather have the submission fail completely than have the submitted certificate(s) modified. An example of this would be a keyserver that does not accept User IDs with an email address outside of the local domain. If such a certificate was submitted, the keyserver MAY trim any noncompliant User IDs before accepting the certificate. If this option was set, then such a certificate submission SHOULD fail with an appropriate error code such as 422 (Unprocessable content).¶
"nm" is meaningful for submissions only.¶
The canonical bundle option instructs the server that for each proof of User ID (such as a verification token, see Section 6.2.2) contained in the submission:¶
The certificates contained in the submission that have the corresponding User ID are regarded by the owner as canonical for that User ID,¶
The owner wishes for these certificates to be served in the same order that they appear in the submission, and:¶
Any certificates with that User ID that are not contained in the submission are not (or no longer) canonical for that User ID.¶
When a keyserver verifies the proof of each User ID, it updates its internal confidence value accordingly (see Section 9).¶
Canonicality only affects the identity and order of certificate(s) returned by User ID lookups, and not to the particular form of the certificate(s) returned. Other methods such as [I-D.dkg-openpgp-1pa3pc] are more appropriate for controlling the form of certificates. In particular, a keyserver MUST allow a valid revocation certificate for any key to be uploaded without identity verification.¶
"cb" is meaningful for submissions only.¶
The machine-readable option instructs the server that a program (rather than a person) is making a Legacy request, so the output SHOULD be in Legacy machine-readable format. If a v2 request format is being used, this option has no effect. See Section 8.3 for the specific details of Legacy machine-readable output.¶
An implementation that does not wish to provide a human-readable interface MAY choose to behave as if this option is always present. Implementations SHOULD NOT provide a Legacy interface without supporting machine-readable output.¶
"mr" is meaningful for Legacy lookups only.¶
The "tokens" variable contains a comma-separated list of one or more tokens obtained via the "tokensend" operation (Section 6.2.2). These tokens SHOULD correspond to one or more User IDs present in the certificate bundle being submitted. A keyserver MAY refuse to serve the certificate(s) when queried by User ID if a valid token was not supplied.¶
"tokens" is meaningful for submissions only.¶
This variable takes one argument: "on" or "off". If present and on, it instructs the server to provide the primary key fingerprint for each certificate in a Legacy "index" or "vindex" operation. This variable has no effect on any other operation. The exact format of the displayed fingerprint, like the "index" and "vindex" operations themselves, is implementation defined in Legacy human-readable output. In Legacy machine-readable indexes, a value of "on" indicates that the "keyid" field SHOULD contain the fingerprint, except for v3 certificates (see Section 8.3.1). An implementation SHOULD treat this variable as being "on" for all Legacy machine-readable indexes. An implementation MAY decide to ignore this variable and/or set the default behaviour to "on" for Legacy human-readable indexes.¶
"fingerprint" is meaningful for Legacy lookups only.¶
This variable takes one argument: "on" or "off". If present and on, it instructs the server to provide the [SKS] digest of each certificate in an "index" or "vindex" operation in the Legacy human-readable output format. This variable has no effect on any other operation, or on Legacy machine-readable output. The exact format of the displayed digest, like the "index" and "vindex" operations themselves, is implementation defined. An implementation MAY decide to ignore this variable and/or set the default behaviour to "on".¶
"hash" is meaningful for Legacy lookups only.¶
This variable takes one argument: "on" or "off". If set to "off", it instructs the server that it MAY use non-exact matching for the contents of the "search" field in text searches (Section 5.3.2). How a keyserver handles non-exact text searches is implementation defined. For example, a keyserver MAY use case-insensitive or tokenized searching.¶
A keyserver implementation SHOULD set the default behaviour to "on" and MAY ignore this variable for Legacy "get" and Legacy "(v)index" lookups. A keyserver implementation MUST ignore this variable and treat all searches as exact for all other lookups.¶
"exact" is meaningful for Legacy lookups only.¶
HKP was originally intended for both human and programmatic use. In general, the Legacy human-readable output is implementation specific. The "machine-readable" option is used to tailor the output of Legacy requests for automated use. For interoperability, the Legacy machine-readable output MUST carefully follow the guidelines given here. A client implementation SHOULD NOT attempt to parse Legacy human-readable output.¶
The v2 API always returns either non-armored certificate bundles or JSON [RFC8259], depending on the request.¶
Clients making v2 requests:¶
MUST silently ignore any primary keys with unknown versions or algorithms.¶
MUST silently ignore any unknown JSON fields in "index" and "add" responses.¶
In response to a v2 request, a keyserver:¶
MUST set the HTTP header "Access-Control-Allow-Origin: *", as specified in [CORS].¶
MUST use the format specified in Section 8.1.1 when responding to "index" operations.¶
MUST use the format specified in Section 8.2 when responding to "add" operations.¶
MUST return non-armored (binary) certificate bundles in response to lookup requests.¶
MUST set "Content-Type: application/json" for "index" and "add" responses.¶
MUST set "Content-Type: application/pgp-keys;armor=no" when returning non-armored certificate bundles (see Section 5 of [I-D.gallagher-openpgp-media-types])¶
MAY set "Last-Modified:" to indicate the modification date of the requested certificate or certificate bundle (Section 8.8.2 of [RFC9110]).¶
A v2 "index" operation SHOULD return a JSON list of certificates. If the search was for a User ID, it SHOULD be sorted in decreasing order of confidence (Section 9). Each certificate object contains some or all of the following fields:¶
| Field | Type | Description |
|---|---|---|
| version | integer | version of the primary key (REQUIRED) |
| fingerprint | string | fingerprint of the primary key (REQUIRED) |
| creation | string | creation date of the key |
| expiration | string | expiration date of the key |
| isExpired | boolean | |
| isRevoked | boolean | |
| algorithm | algorithm | (Table 8) |
| userIDs | userID array | (Table 9) |
| subkeys | subkey array | (Table 10) |
| Field | Type | Description |
|---|---|---|
| code | integer | algorithm ID (REQUIRED) |
| name | string | a human-readable identifier for the algorithm |
| bitLength | integer | key length in bits (DSA/RSA/ElGamal keys only) |
| Field | Type | Description |
|---|---|---|
| uidString | string | User ID string contents (REQUIRED) |
| creation | string | creation date of (the first signature over) the User ID |
| expiration | string | expiration date of the User ID |
| isExpired | boolean | |
| isRevoked | boolean | |
| confidence | integer | (Section 9) |
| Field | Type | Description |
|---|---|---|
| version | integer | version of the subkey (REQUIRED) |
| fingerprint | string | fingerprint of the subkey (REQUIRED) |
| creation | string | creation date of the subkey |
| expiration | string | expiration date of the subkey |
| isExpired | boolean | |
| isRevoked | boolean | |
| algorithm | algorithm | (Table 8) |
Fingerprints and long Key IDs are given in hexadecimal notation, without any "0x" prefix. Timestamps are given in ISO 8601 format. Algorithm IDs are as specified in Section 9.1 of [RFC9580].¶
The only required fields are the version and fingerprint of any key material, and the uidString of any User IDs. Implementations MAY omit algorithms, subkeys and User IDs from indexes; however if they are present they MUST contain the required fields.¶
An "add" operation MAY return an empty response, or it MAY return a JSON object summarising the changes. The JSON object MAY contain any or all of the following fields, each of which is an array of certificate objects:¶
| Field | Type | Description |
|---|---|---|
| inserted | certificate array | newly added certificates |
| updated | certificate array | updated certificates |
| deleted | certificate array | deleted certificates |
| ignored | certificate array | certificates with no new information |
| invalid | certificate array | certificates that could not be processed |
Each certificate object MUST contain "version" and "fingerprint" fields, as in Table 7.¶
Certificates in the "ignored" and "invalid" arrays MAY also contain a "comment" field describing the reason for their rejection. The comment is a human-readable string, and MAY be displayed to the user.¶
Clients requesting machine-readable output in Legacy requests:¶
SHOULD supply "options=mr" (Section 7.1.3).¶
MUST silently ignore any content preceding or following a returned armored key block.¶
MUST silently ignore any primary keys with unknown versions or algorithms.¶
Keyservers returning Legacy machine-readable output:¶
MUST set the HTTP header "Access-Control-Allow-Origin: *", as specified in [CORS].¶
MUST return ASCII-armored certificate bundles.¶
MUST NOT return version 6 (or later) certificates.¶
MUST set "Content-Type: application/pgp-keys" when returning ASCII-armored certificate bundles (the "get", "vfpget", "kidget", and "hget" operations), as specified in Section 7 of [RFC3156].¶
MAY set "Last-Modified:" to indicate the modification date of the requested certificate or certificate bundle (Section 8.8.2 of [RFC9110]).¶
MUST use the format specified in Section 8.3.1 when returning indexes (the "index" and "vindex" operations).¶
MAY return statistics in JSON format [RFC8259], the schema of which is otherwise implementation-dependent.¶
ASCII-armored responses MAY be wrapped in any HTML or other text desired, except that the actual certificate data consisting of an initial line break, the "-----BEGIN PGP PUBLIC KEY BLOCK-----" header, the armored certificate data itself, the "-----END PGP PUBLIC KEY BLOCK-----" footer, and a final line break MUST NOT be modified from the form specified in [RFC9580].¶
The Legacy machine-readable index format is a list of newline-separated records, consisting of colon-separated fields. The document is 7-bit clean, and as such is sent with no encoding and Content-Type: text/plain.¶
The machine-readable response MAY be prefixed by an information record:¶
info:<version>:<count>¶
| Field | Description |
|---|---|
| version | the version of this output format |
| count | the number of certificates returned |
If this line is not included, or the version information is not supplied, the version number is assumed to be 1. Currently, only version 1 is defined.¶
Note that "count" is the number of certificates, and not the number of lines returned. That is, it SHOULD match the number of "pub:" lines returned.¶
The certificate listings themselves are made up of several records per certificate. The first record specifies the primary key:¶
pub:<keyID>:<code>:<bitLength>:<creation>:<expiration>:<flags>¶
| Field | Description |
|---|---|
| keyID | fingerprint or long Key ID |
| code | algorithm ID |
| bitLength | key length in bits |
| creation | creation date of the key |
| expiration | expiration date of the key |
| flags | letter codes to indicate details of the key |
Since it is not possible to calculate the Key ID from a V3 fingerprint, for V3 primary keys the "keyID" field SHOULD contain the 16-digit long Key ID only. Otherwise, a keyserver SHOULD return a fingerprint if available (see Section 7.3).¶
Algorithm IDs are as specified in Section 9.1 of [RFC9580], i.e. 1==RSA, 17==DSA, etc.¶
Following the "pub" record are one or more "uid" records to indicate User IDs on the certificate:¶
uid:<uidString>:<creation>:<expiration>:<flags>¶
| Field | Description |
|---|---|
| uidString | User ID string contents |
| creation | creation date of (the first self-signature over) the User ID |
| expiration | expiration date of the User ID |
| flags | letter codes to indicate details of the User ID |
The User ID string MUST use urlencoding for anything that isn't 7-bit safe as well as for the ":" and "%" characters. Any other characters MAY be urlencoded, as desired.¶
The information for the "creation", "expiration", and "flags" fields is taken from the User ID self-signature, if any, and applies to the User ID in question, not to the certificate as a whole.¶
Primary key and User ID records may contain a "flags" field containing a sequence of alphabetical characters, one per flag. Flags MAY be given in any order. The meaning of "disabled" is implementation-specific. Note that individual flags may be unimplemented, so the absence of a given flag does not necessarily mean the absence of the detail.¶
| Flag | Description |
|---|---|
r
|
revoked |
d
|
disabled |
e
|
expired |
Note that empty fields are allowed. For example, a primary key with no expiration date would have the "expirationdate" field empty. Also, a keyserver that does not track a particular piece of information may leave that field empty as well. Colons for empty fields on the end of each line MAY be left off, if desired. All dates are given in the number of seconds since 1970-01-01T00:00:00 UTC.¶
For backwards compatibility with the installed client base, Legacy machine-readable lookup requests MUST omit version 6 (and later) certificates from the returned indexes.¶
Traditionally, keyservers did not perform any checks against uploaded content other than simple parseability. This left them open to abuse such as flooding and third-party signature spam. Most modern keyservers are now able to perform cryptographic validity tests, and automated content moderation is generally possible.¶
It is RECOMMENDED that a keyserver assigns a "confidence" value to each User ID in its database. The exact definition of "confidence" is implementation-dependent, but MAY include checks such as email verification or third-party certifications.¶
A keyserver MAY represent confidence as a number between 0 and 255, where values of 120 or greater indicate "complete confidence", in a v2 Index User ID object (see Table 9). This is numerically compatible with the "trust amount" field specified in Section 5.2.3.21 of [RFC9580], but it is not required to calculate it in the same way or represent it internally as an integer value. The confidence field in a v2 Index User ID object is intended as a heuristic for sorting and filtering responses to lookup requests, and is not a replacement for cryptographic verification. A client SHOULD NOT rely on this confidence field, and SHOULD perform its own checks. A keyserver that wishes to publish a cryptographically-verifiable statement about its internal confidence value MAY do so using a certification signature.¶
HKP uses a "certificate bundle" as its primary data representation for both input and output.¶
A certificate bundle is a sequence of one or more OpenPGP certificates (Transferable Public Keys), concatenated directly, as specified in Sections 10.1 and 3.6 of [RFC9580]. An ASCII-armored certificate bundle is a certificate bundle that has been encoded as a single armored block, as specified in Section 6.2 of [RFC9580].¶
Certificate bundles are often called "keyrings", however the term "keyring" is used to refer to several related but distinct concepts:¶
A sequence of one or more Transferable Public Keys ("public keyring")¶
A sequence of one or more Transferable Secret Keys ("private/secret keyring")¶
A sequence of packets forming a single Transferable Public Key¶
A sequence of packets forming a single Transferable Secret Key¶
It is therefore RECOMMENDED that implementations avoid using the term "keyring" without qualification.¶
For OpenPGP certificates prior to version 6, revocation signatures have customarily been distributed as a detached "revocation certificate", as per Section 10.1.3 of [RFC9580]. An HKP server SHOULD allow submission of these detached revocations.¶
An HKP implementation MAY accept or serve an ASCII-armored "mixed certificate bundle" where one or more revoked certificates have been replaced by their detached revocation certificate(s). Such a "mixed certificate bundle" MUST be sorted so that all detached revocation certificates appear first. This ensures that detached revocations cannot be mistaken for signatures over another primary key.¶
Mixed certificate bundles MUST NOT be served in responses to v2 lookup requests.¶
SRV records [RFC2782] are commonly used by clients to discover the location of internet services. We can use the "openpgpkey" service name to locate an HKPS service for certificate discovery. HKP clients SHOULD support SRV records.¶
The service name for HKPS discovery is "openpgpkey", and the protocol name is "https". The service and protocol labels are therefore "_openpgpkey" and "_https" respectively. These are prepended to the domain part of the email addresses for which certificates are being published:¶
_openpgpkey._https.<domain-part>¶
A domain owner wishing to publish OpenPGP certificates for their users would create one or more SRV records at this location, each referencing the address and port number of a keyserver that is authoritative for that domain. Each unique domain part for which email addresses are supported will have its own SRV records.¶
When making an HKPS discovery request, a client SHOULD use an HTTP GET request to an authoritative keyserver using the "authget" lookup operation, with the email address in the "search" field.¶
Note that discovery is performed using the "authget" operation, to ensure that the discovery results have been filtered. The domain owner SHOULD take reasonable steps to ensure that any certificates returned from this lookup request are valid certificates for the identity in the search field. Discovery MAY be implemented at low cost by serving such requests from a static filesystem.¶
It is RECOMMENDED that certificates returned from discovery are subject to further verification on the client side wherever possible, to mitigate against compromise of the discovery server.¶
A client trying to locate a certificate for isabella@silvie.example.com makes a DNS request for the SRV record at _openpgpkey._https.example.com..
This would return:¶
_openpgpkey._https.example.com. 3600 IN SRV 1 1 443 keyserver.example.com¶
On finding this record, the client makes an HTTP GET request for the following URL:¶
hkps://keyserver.example.com:443/pks/v2/authget/isabella@silvie.example.com¶
The keyserver returns the certificate for isabella@silvie.example.com, and the client proceeds to check its validity according to the local policy.¶
As described here, a keyserver is a searchable database of OpenPGP Certificates accessed over the network. While there may be security considerations arising from distributing arbitrary certificates in this manner, this does not impact the security of OpenPGP itself.¶
Without some sort of trust relationship between the client and server, information returned from a keyserver in arbitrary search results cannot be trusted by the client until the OpenPGP client actually retrieves and checks the certificate for itself. This is important and must be stressed: without a specific reason to treat information otherwise, all search results SHOULD be regarded as untrustworthy and informational only.¶
This document allocates the ports 11371 and 11372, the service names "hkps" and "openpgpkey", and the URI schemes "hkp" and "hkps".¶
IANA is requested to update the contact details for port 11371 in the "Service Name and Transport Protocol Port Number" registry to "Daphne Shaw".¶
IANA is requested to add the following entries to the "Service Name and Transport Protocol Port Number" registry as per [RFC6335]:¶
| Service Name | Port | Transport Protocol | Description | Contact | Reference |
|---|---|---|---|---|---|
| hkps | 11372 | tcp and udp | OpenPGP HTTP Keyserver (Secure) | Daphne Shaw | This document |
| openpgpkey | OpenPGP Certificate Discovery | Daphne Shaw | This document |
IANA is requested to add the following entries to the "URI Schemes" registry as per [RFC7595]:¶
| URI Scheme | Description | Status | Reference |
|---|---|---|---|
| hkp | OpenPGP HTTP Keyserver | Permanent | This document |
| hkps | OpenPGP HTTP Keyserver (Secure) | Permanent | This document |
This document is a formalization and extension of HKP, originally implemented in the PKS keyserver by Marc Horowitz, which in turn was based on earlier work by Brian LaMacchia and Michael Graff. The "prefixlog" operation is based on an earlier proposal by Daniel Kahn Gillmor and Vincent Breitmoser.¶
The authors would like to thank Peter Gutmann for his work on the Certstore protocol, some of which was applicable here, and the members of the pgp-keyserver-folk mailing list who contributed valuable comments and suggestions. They would also like to thank Bart Butler, Daniel Huigens, Daniel Kahn Gillmor, Heiko Schäfer, Justus Winter and Vincent Breitmoser for help with the v2 request format.¶
Note to RFC Editor: this section should be removed before publication.¶
Resurrected SRV-based discovery.¶
Added basic vs advanced submission.¶
Added structured email.¶
Specified use of OPTIONS and HEAD.¶
Specified the Last-Modified response header.¶
Sideline inexact matching.¶
Discourage badly-behaved User IDs.¶
Removed some misused HTTP return codes.¶
Added tabular summaries.¶
Reordered legacy features to end of lists.¶
Verified uploads now use prove-then-submit workflow.¶
Removed SRV and discovery discussion (temporarily?).¶
Added definitions of "discovery", "refresh" and "reference resolution".¶
Normalised "certificate" terminology and warned about unqualified use of "keyring".¶
Renumbered HKPv1 to HKPv2 for avoidance of confusion, and reordered path components.¶
HKPv2 is now explicitly a binary protocol, and uses simplified paths.¶
Defined v2 submission requests and "cb" option.¶
Explicitly forbade mixed certificate bundle responses to v2 lookups.¶
"since" is now "prefixlog".¶
"get" operation is now MAY.¶
"x-*" parameters are no longer specified (as per RFC6648).¶
Fixed several errata.¶
Expanded commentary and guidance.¶
Updated references.¶
Allow detached revocations in keyrings.¶
Redesigned v2 request format to use path components for required fields.¶
Added openpgpkey discovery file.¶
Added "vfpget" and "kidget" operations.¶
Added meaningful "exact" semantics.¶
HKPS is now SHOULD.¶
Defined port 11372.¶
IANA registry tables.¶
Deprecated op=stats.¶
Clients SHOULD supply the v=1 api-versioning variable.¶
machine-readable output includes key version field.¶
Clients MUST silently ignore leading and trailing cruft, trailing unknown fields, and unknown flags.¶
Clients MUST silently ignore keys with unknown versions or algorithms.¶
All other m-r index specs (CORS, Content-Type etc.) are now MUST.¶
Included the hash variable from SKS.¶