]> Jabberwocky Tech

dshaw@jabberwocky.com

PGPKeys.EU

andrewg@andrewg.com

sec openpgp Internet-Draft 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. The latest revision of this draft can be found at . Status information for this document may be found at . Discussion of this document takes place on the OpenPGP Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction For ease of use, public key cryptography requires a key distribution system. For many years, the most commonly used system has been a key server - a server that stores public keys and can be searched for a given key. The HTTP Keyserver Protocol is a OpenPGP keyserver implemented using HTTP.

Conventions and Definitions 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 when, and only when, they appear in all capitals, as shown here.

HKP and HTTP As HKP is implemented over HTTP, everything in 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" . 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 . See for an automated way for clients to discover the correct port.

Request Paths HKP defines two paths, namely "/pks/lookup" for lookups (see ) and "/pks/add" for submission (see ). 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 .

HTTP Status Codes When a status or error code needs to be returned by a keyserver, the most appropriate HTTP code from 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 key 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 202 Accepted Submitted key was altered to match keyserver policy 403 Forbidden The requested operation is not permitted 404 Not found The search returned no results, or path not found 410 Gone Key has been permanently deleted, e.g. due to RTBF 413 Content too large The search returned too many responses 422 Unprocessable content Submitted key was rejected as per keyserver policy 501 Not implemented The requested operation is not supported In addition, a client SHOULD understand 3xx redirect codes. (( andrewg : In draft-shaw-00 it was suggested that a novel header be used for statuses that could not be represented by the HTTP response codes of the time. This was only partially specified, and it is unclear if any implementations of this header existed. In the meantime many new HTTP response codes have been defined, so I am using them instead - even if their semantics does not exactly match that of . NB therefore that codes 202, 410, 413, 422 may not have been implemented anywhere yet. )) (( andrewg : note also that 413 and 202 may be incorrect usage, see issues #25 and #26 respectively. ))

Looking up Data from a Keyserver Key lookups are done via an HTTP GET request. Specifically, the abs_path () is built up of the base path "/pks/lookup", followed by request-specific URL components. These components differ slightly between the Legacy and v1 request 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 keys are operated on. There may also be modifier variables, as specified in below. Variables are passed using HTTP query strings as specified in . HTTP query strings MAY be given in any order. Keyservers MUST ignore any unknown query strings.

Legacy and v1 Request Formats For backwards compatibility with the existing installed client base, a Legacy request format is defined. New implementations SHOULD use the v1 request format.

Legacy Request Format In the Legacy request format, the "op" and "search" fields are supplied as HTTP query strings, in the form "<field-name>=<value>":

&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 ). No URL path components under "/pks/lookup" are used.

v1 Request Format In the v1 request format, the values of the "op" and "search" fields are supplied as URL path components. They are appended to "/pks/lookup/v1" as follows:

/[?...] ]]>

The "op" and "search" fields MUST be supplied. Modifier variables are supplied as HTTP query strings, same as in the Legacy request format. If the v1 request format is being used, machine readable output format () MUST be returned. Note that the "stats" operation MUST NOT be used in v1 request format (see ). The v1 request format is designed so that a basic HKP service can be implemented using static files.

The "op" (operation) Field The "op" field specifies the operation to be performed on the keyserver. The "op" field is generally used with the "search" field to specify the keys that should be operated on. 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.

The "get" Operation A keyserver SHOULD support the "get" operation. The "get" operation requests keys from the keyserver by textual search. A string that specifies which key(s) to return is provided in the "search" field. The response to a successful "get" request is a HTTP document containing an ASCII-armored keyring as specified in . The response MAY be wrapped in any HTML or other text desired, except that the actual key data consisting of an initial line break, the "-----BEGIN PGP PUBLIC KEY BLOCK-----" header, the armored key data itself, the "-----END PGP PUBLIC KEY BLOCK-----" header, and a final line break MUST NOT be modified from the form specified in . A keyserver SHOULD limit the returned keyring to a reasonable length. Entries SHOULD be sorted in order of decreasing confidence (), and then by creation date (most recent first). If no keys match the request, the keyserver SHOULD return an appropriate HTTP error code such as 404 ("Not Found").

The "authget" (authoritative get) Operation 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 key discovery (). The keyserver SHOULD only return results where the User ID being searched for has a nonzero confidence value (). If a keyserver is being used for key discovery, it MUST return only results for which it is has complete confidence. In addition, exact textual matching MUST be used even if the "exact" variable is set to "off" ().

The "since" Operation A keyserver MAY support the "since" operation. "since" requests a list of fingerprint prefixes that indicate which TPKs have been modified since midnight UTC on a specific date. The date is provided in the "search" field in ISO format with no time component, i.e. "2025-12-01". The returned data is a list of CRLF-separated, hexadecimal-encoded fingerprint prefixes. 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. A client MUST NOT make any assumptions about the length of the prefixes returned. A client that wishes to update its local keyring from a keyserver MAY first make a "since" 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 keyring, and make subsequent "vfpget" requests as appropriate (). 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 key version. This contrasts with key IDs, which are version-dependent. A keyserver SHOULD NOT support lookup by prefix.

The "index" Operation A keyserver MAY support the "index" operation. The "index" operation requests a list of keys 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 key, but this is not required. A keyserver SHOULD limit the returned index to a reasonable length. Entries SHOULD be sorted in order of decreasing confidence, and then by creation date (most recent first). If no keys match the request, the keyserver SHOULD return an appropriate HTTP error code such as 404 ("Not Found").

The "vindex" (verbose index) Operation A keyserver MAY support the "vindex" operation. The "vindex" operation is similar to "index" in that it provides a list of keys on the keyserver that match the text in the "search" field. Historically, a "vindex" response was the same as "index" with the addition of showing the signatures on each key, but this is not required. The "vindex" operation only differs from the "index" operation in Legacy human readable mode, and a server MAY treat the two operations as synonyms. A server that supports "vindex" SHOULD treat it as a synonym for "index" in machine-readable mode. A client SHOULD NOT make machine-readable "vindex" requests.

The "stats" (statistics/status) Operation A keyserver MAY support the "stats" operation in Legacy request format. The "stats" operation is deprecated, and MUST NOT be used in a v1 request. It is RECOMMENDED to use a URL outside "/pks/lookup" (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 "vfpget" (versioned fingerprint get) Operation A keyserver MAY support the "vfpget" operation. "vfpget" requests a key 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 key version number and N octets of fingerprint. This is the same octet sequence used in the Issuer Fingerprint and Intended Recipient Fingerprint subpackets (). If no keys match the request, the keyserver SHOULD return an appropriate HTTP error code such as 404 ("Not Found").

The "kidget" (keyid get) Operation A keyserver MAY support the "kidget" operation. "kidget" requests a key from a keyserver by specifying its key ID (). 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 keys match the request, the keyserver SHOULD return an appropriate HTTP error code such as 404 ("Not Found").

The "hget" (hash get) Operation A keyserver MAY support the "hget" operation. "hget" requests a key from a keyserver by specifying its 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 keys match the request, the keyserver SHOULD return an appropriate HTTP error code such as 404 ("Not Found").

Other Operations Other site-specific or nonstandard operations can be indicated by prefixing the operation name with the string "x-".

The "search" Field 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 key being sought, depending on the operation.

Key ID and Fingerprint Searches To search for a key by its key ID or fingerprint, a client SHOULD use a v1 request and either the "kidget" or "vfpget" operation (as appropriate). If making a Legacy request, 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. The hexadecimal digits are not case sensitive. A keyserver: SHOULD accept fingerprints and MAY accept 64-bit key IDs in the Legacy request "search" field. MUST NOT return results for 32-bit "short key ID" searches, as these do not provide sufficient collision resistance. MUST NOT return v6 keys in the results for Legacy machine readable requests, but MAY do so for Legacy human readable requests (see also ). V3 keys are no longer considered secure, but MAY be distributed for historical reference.

Text Searches To search for a key by the text of a user ID, a client SHOULD use the "get", "authget", or "index" operation (as appropriate) and SHOULD NOT prefix the "search" string with "0x". A keyserver MUST NOT return v6 keys in the results for Legacy machine readable requests, but MAY do so for Legacy human readable requests (see also ). Otherwise, how a keyserver handles textual search is implementation defined. See also the definition of the "exact" variable () for a method to give additional instructions to the server on how the search is to be executed.

Lookup Examples Search for all keys containing the string "dshaw", using plaintext HTTP: Legacy request format:

v1 request format:

Get key 0xDEADBEEFDECAFBAD (64-bit key ID), using HTTPS: Legacy request format:

v1 request format:

Submitting Keys To A Keyserver A keyserver MAY accept submissions via an HTTP POST request. Specifically, the abs_path () is set to "/pks/add", and the key data is provided via HTTP POST as specified in , and . The body of the POST message contains a "keytext" variable which contains an ASCII-armored keyring as specified in . The ASCII armored keyring should also be urlencoded as specified in . Note that more than one key may be submitted in a single transaction. There may also be modifier variables, as specified in below. If a keyserver does not support adding keys via HTTP, then requests to do so should return an appropriate HTTP error code, such as 403 ("Forbidden") if key submission has been disallowed, or 501 ("Not Implemented") if the server does not support HTTP key submission. The keyserver MUST NOT return an error code (such as 404 ("Not Found")) that could be mistaken by the client for a valid response.

Modifier Variables These variables are used to modify basic requests.

The "options" Variable 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".

The "mr" (Machine Readable) Option The machine readable option instructs the server that a program (rather than a person) is making the request, so the output SHOULD be in machine readable format. If the v1 request format () is being used, machine readable output MUST be returned, so this option has no effect. See for the specific details of machine readable output.

The "nm" (No Modification) Option As keyservers may modify submitted keys to suit a particular policy, this option is used to inform the keyserver that the submitter would rather have the submission fail completely then have the submitted key(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 key was submitted, the keyserver MAY trim any noncompliant user IDs before accepting the key. If this option was set, then such a key submission SHOULD fail with an appropriate error code such as 422 (Unprocessable content). "nm" is meaningful for submissions only.

Other Options Other site-specific or nonstandard options can be indicated by prefixing the option name with the string "x-". Non-standard options MUST represent boolean values with a default value of "false".

The "fingerprint" Variable This variable takes one argument: "on" or "off". If present and on, it instructs the server to provide the key fingerprint for each key in an "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 machine readable indexes, a value of "on" indicates that the "keyid" field SHOULD contain the fingerprint, except for v3 keys (see ). An implementation SHOULD treat this variable as being "on" for all 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 lookups only.

The "hash" Variable This variable takes one argument: "on" or "off". If present and on, it instructs the server to provide the digest of each key in an "index" or "vindex" operation in the Legacy human readable output format. This variable has no effect on any other operation, or on 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 lookups only.

The "exact" Variable This variable takes one argument: "on" or "off". If set to "on", it instructs the server to search for an exact match for the contents of the "search" field. An implementation SHOULD set the default behaviour to "on" and MAY ignore this variable. When "exact" is set to "on", 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. In either case, the string matching SHOULD NOT be case sensitive. "exact" is meaningful for lookups only.

Other Variables Other site-specific or nonstandard variables can be indicated by prefixing the variable name with the string "x-".

Output Formats 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. By contrast, the v1 request format MUST return machine readable output. For interoperability, the machine readable output MUST carefully follow the guidelines given here. A client implementation SHOULD request machine readable output and SHOULD NOT attempt to parse human readable output.

Machine Readable Output Clients requesting machine readable output: SHOULD use the v1 request format, or else supply "options=mr" () in a Legacy request. MUST silently ignore any content preceding or following a returned armored key block. MUST silently ignore any keys with unknown versions or algorithms. Keyservers returning machine readable output: MUST set the HTTP header "Access-Control-Allow-Origin: *", as specified in . MUST set "Content-Type: application/pgp-keys" when returning keys (the "get", "vfpget", "kidget", and "hget" operations), as specified in . MUST use the format specified in when returning indexes (the "index" and "vindex" operations). MAY return statistics in JSON format , the schema of which is otherwise implementation-dependent.

Machine Readable Indexes The machine readable index format is a list of newline-separated records. 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:

: ]]>

Field Description version the version of this output format count the number of keys 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 keys, and not the number of lines returned. That is, it SHOULD match the number of "pub:" lines returned. The key listings themselves are made up of several records per key. The first record specifies the primary key:

:::::: ]]>

Field Description keyid the fingerprint or the key ID algorithm the algorithm ID keylen the key length in bits creationdate creation date of the key expirationdate expiration date of the key flags letter codes to indicate details of the key keyversion the version of the primary key Since it is not possible to calculate the key ID from a V3 key fingerprint, for V3 keys the "keyid" field SHOULD contain the 16-digit key ID only. Otherwise, a keyserver SHOULD return a fingerprint if available (see ). The algorithm ID is as specified in , i.e. 1==RSA, 17==DSA, etc. Following the "pub" record are one or more "uid" records to indicate user IDs on the key:

::: ]]>

Field Description uidstring the user ID string creationdate creation date of the User ID expirationdate expiration date of the User ID flags letter codes to indicate details of the User ID confidence the confidence that the server has in this User ID The user ID string MUST use HTTP % encoding for anything that isn't 7-bit safe as well as for the ":" and "%" characters. Any other characters MAY be HTTP encoded, as desired. The information for the "creationdate", "expirationdate", and "flags" fields is taken from the User ID self-signature, if any, and applies to the user ID in question, not to the key as a whole. The "confidence" value is specified in . 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. Client implementations MUST ignore unknown flags. Flag Description r revoked d disabled e expired Note that empty fields are allowed. For example, a 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. Client implementations MUST ignore unknown trailing fields. All dates are given in the number of seconds since midnight 1/1/1970 UTC.

Legacy Machine Readable Indexes For backwards compatibility with the installed client base, Legacy machine readable requests SHOULD return a restricted index format: The "keyversion" field and its preceding colon, and any subsequent fields, SHOULD be omitted. The "confidence" field and its preceding colon, and any subsequent fields, SHOULD be omitted. Version 6 (and later) keys SHOULD be omitted.

Confidence 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 deliverability or third-party certifications. A keyserver MAY publish its internal confidence value as a number between 0 and 255, where values of 120 or greater indicate "complete confidence". This is numerically compatible with the "trust amount" field specified in , but it is not required to calculate it in the same way or represent it internally as an integer value. Keyserver confidence 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 the confidence value returned from a keyserver, and SHOULD perform its own checks.

Keyring Format HKP uses an ASCII-armored keyring as its primary data representation for both input and output. A keyring is a sequence of one or more OpenPGP Transferable Public Keys, concatenated directly, as specified in Sections and of . An ASCII-armored keyring is a keyring that has been encoded as a single armored block, as specified in .

Detached Revocations For OpenPGP keys prior to v6, revocation signatures have customarily been distributed as a detached "revocation certificate", as per . An HKP server SHOULD allow submission of these detached revocations. An HKP implementation MAY accept or serve an ASCII-armored "mixed keyring" where one or more revoked transferable public keys have been replaced by their detached revocation certificate(s). Such a "mixed keyring" MUST be sorted so that all detached revocation certificates appear first. This ensures that detached revocations cannot be mistaken for signatures over another key.

Locating a HKP Keyserver Clients are usually manually configured with the address of a HKP keyserver. Client implementations should be aware that it is reasonably common practice to use a single name in DNS that resolves to multiple address records. When receiving a DNS response with multiple addresses, clients SHOULD try each address until a server is reached. The order to try these addresses in is implementation defined. A far more flexible scheme for listing multiple HKP keyservers in DNS is the use of DNS SRV records as specified in . DNS SRV allows for different priorities and weights to be applied to each HKP keyserver in the list, which allows an administrator much more control over how clients will contact the servers. The SRV symbolic service name for HKP keyservers is "hkp" when used over plaintext HTTP, or "hkps" when using HTTPS. For example, the SRV record for HKP keyservers in domain "example.com" would be "_hkp._tcp.example.com". SRV records contain the port that the target server runs on, so SRV can also be used to automatically discover the proper port for contacting a HKP keyserver. HKP clients SHOULD support SRV records.

Key Discovery Well-known URIs are commonly used by clients to discover the location of internet services. We can use the "openpgpkey" well-known base path to locate an HKPS service for key discovery. This is done by serving an "hkps" discovery file that redirects a client to an authoritative HKPS service for the domain in question.

The "openpgpkey" Well-Known Base Path defines the well-known "openpgpkey" base path for a given domain as:

/.well-known/openpgpkey// ]]>

The "hkps" discovery file is placed under this directory, which is shared with other discovery methods such as WKD. The domain is repeated in a trailing path component in order to simplify serving multiple discovery files from a single host. Some web hosting providers automatically return a zero length file successfully when a nonexistent file is requested, therefore: If the file "<base-path>/hkps" exists, and is of non-zero size, it SHOULD be used. If the file "<base-path>/hkps" does not exist, or is of zero size, then it MUST be ignored, and a client MAY fall back to other key discovery methods. Requests for the discovery file MUST be made over HTTPS. The alternative "direct" well-known base path from MUST NOT be used for HKPS discovery.

The "hkps" Discovery File The discovery file contains a sequence of lines containing keywords and one or more values, separated by colons. Blank lines and comment lines beginning with "#" MUST be ignored. The following keywords are defined:

server:[:[:]] ]]>

If "port" is not given, it defaults to 443. "options" is a colon-separated list of options. No options are currently defined, and unknown options MUST be ignored. Unknown keywords MUST be ignored. The discovery file is parsed by a client as follows: If a "version" line does not exist, a client MUST NOT continue with HKPS discovery, and MAY fall back to other discovery methods. If a "version" line exists but a "server" line does not, then the HKP service is located on the same hostname as the discovery file. If more than one "server" line exists, a client SHOULD try them in the given order, returning after the first successful response; a 404 ("Not Found") or 410 ("Gone") response in this context counts as a success. Thus a minimal HKPS discovery file will contain just "version:1". In addition: Only HKPS version 1 is supported in the discovery file, and clients MUST use the v1 request format and HTTPS for HKPS key discovery. If a client wishes to receive v6 or higher keys it SHOULD make an HKPS discovery request. If a server wishes to serve v6 or higher keys it SHOULD NOT do so over WKD, for compatibility with clients that do not support v6 keys.

Key Discovery Example For example, a client trying to locate a key for isabella@silvie.example.com could consult:

This discovery file might contain the following lines:

On finding this file, a client SHOULD make a GET request for the following URL:

The domain owner MUST ensure that any keys returned from this keyserver are valid keys for the identity in the search field. This MAY be achieved at low cost by serving the keys from a static filesystem.

Security Considerations As described here, a keyserver is a searchable database of public keys accessed over the network. While there may be security considerations arising from distributing arbitrary keys 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 key for itself. This is important and must be stressed: without a specific reason to treat information otherwise, all search results must be regarded as untrustworthy and informational only. The sole exception to the above is if the openpgp key discovery method has been used, and all requests in the chain of indirection have been made over HTTPS/HKPS. In such a scenario, a client MAY assume that any keys returned are authoritative for the requested identity.

IANA Considerations This document allocates the ports 11371 and 11372, the URI schemes "hkp" and "hkps", and the well-known URI suffix "openpgpkey".

Updated Registry Entries IANA is requested to update the contact details for port 11371 in the "Service Name and Transport Protocol Port Number" registry to "Daphne Shaw".

New Registry Entries IANA is requested to add the following entry to the "Service Name and Transport Protocol Port Number" registry as per : Service Name Port Transport Protocol Description Contact hkps 11372 tcp and udp OpenPGP HTTP Keyserver (Secure) Daphne Shaw IANA is requested to add the following entries to the "URI Schemes" registry as per : URI Scheme Description Status Reference hkp OpenPGP HTTP Keyserver Permanent This document hkps OpenPGP HTTP Keyserver (Secure) Permanent This document IANA is requested to add the following entry to the "Well-Known URIs" registry as per : URI Suffix Change Controller Reference Status Related Information openpgpkey OpenPGP WG This document permanent

The Hypertext Transfer Protocol (HTTP) is an application-level protocol with the lightness and speed necessary for distributed, collaborative, hypermedia information systems. This memo provides information for the Internet community. This memo does not specify an Internet standard of any kind. This document defines a HTML 2.0 (to distinguish it from the previous informal specifications). [STANDARDS-TRACK] This document describes a DNS RR which specifies the location of the server(s) for a specific protocol and domain. [STANDARDS-TRACK] This document describes how the OpenPGP Message Format can be used to provide privacy and authentication using the Multipurpose Internet Mail Extensions (MIME) security content types described in RFC 1847. [STANDARDS-TRACK] This document updates the guidelines and recommendations, as well as the IANA registration processes, for the definition of Uniform Resource Identifier (URI) schemes. It obsoletes RFC 4395. This memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes. In doing so, it obsoletes RFC 5785 and updates the URI schemes defined in RFC 7230 to reserve that space. It also updates RFC 7595 to track URI schemes that support well-known URIs in their registry. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. This document specifies the message formats used in OpenPGP. OpenPGP provides encryption with public key or symmetric cryptographic algorithms, digital signatures, compression, and key management. This document is maintained in order to publish all necessary information needed to develop interoperable applications based on the OpenPGP format. It is not a step-by-step cookbook for writing an application. It describes only the format and methods needed to read, check, generate, and write conforming packets crossing any network. It does not deal with storage and implementation questions. It does, however, discuss implementation issues necessary to avoid security flaws. This document obsoletes RFCs 4880 ("OpenPGP Message Format"), 5581 ("The Camellia Cipher in OpenPGP"), and 6637 ("Elliptic Curve Cryptography (ECC) in OpenPGP"). In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document defines the procedures that the Internet Assigned Numbers Authority (IANA) uses when handling assignment and other requests related to the Service Name and Transport Protocol Port Number registry. It also discusses the rationale and principles behind these procedures and how they facilitate the long-term sustainability of the registry. This document updates IANA's procedures by obsoleting the previous UDP and TCP port assignment procedures defined in Sections 8 and 9.1 of the IANA Allocation Guidelines, and it updates the IANA service name and port assignment procedures for UDP-Lite, the Datagram Congestion Control Protocol (DCCP), and the Stream Control Transmission Protocol (SCTP). It also updates the DNS SRV specification to clarify what a service name is and how it is registered. This memo documents an Internet Best Current Practice. JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. g10 Code GmbH This specification describes a service to locate OpenPGP keys by mail address using a Web service and the HTTPS protocol. It also provides a method for secure communication between the key owner and the mail provider to publish and revoke the public key.

Acknowledgments 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. Without their grounding, this document would not exist. The openpgpkey discovery file is based on previous work by Werner Koch, without whom the key discovery method would not exist in its current form. The "since" 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, and Justus Winter for help with the v1 request format and discovery file specifications.

Document History Note to RFC Editor: this section should be removed before publication.

Changes Between draft-gallagher-openpgp-hkp-06 and draft-gallagher-openpgp-hkp-07 Added "authget" and "since" operations. Defined confidence. Added more explicit guidance re sorting, filtering and error codes. Key version MR output field is now "keyversion" to distinguish from the output format version.

Changes Between draft-gallagher-openpgp-hkp-05 and draft-gallagher-openpgp-hkp-06 Updated references.

Changes Between draft-gallagher-openpgp-hkp-04 and draft-gallagher-openpgp-hkp-05 Allow detached revocations in keyrings. Redesigned v1 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.

Changes Between draft-gallagher-openpgp-hkp-03 and draft-gallagher-openpgp-hkp-04 Reworded for clarity. Separate section for keyring format. Specify detached revocations. Updated references.

Changes Between draft-gallagher-openpgp-hkp-02 and draft-gallagher-openpgp-hkp-03 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.

Changes Between draft-gallagher-openpgp-hkp-01 and draft-gallagher-openpgp-hkp-02 Tightened up BCP-14 language. Included op=hget from SKS. Options now strictly boolean with default false, variables less strict. More detail about HTTP status code usage.

Changes Between draft-shaw-openpgp-hkp-00 and draft-gallagher-openpgp-hkp-01 Improved text structure. Added references to HTTPS/HKPS, and hkp:/hkps: URL schemes. Forbade short IDs and deprecated V3 keys. Included op=stats from SKS. Mentioned CORS. Made use of terminology more consistent. Replaced custom status codes with standard HTTP status codes.