]> Jabberwocky Tech

dshaw@jabberwocky.com

PGPKeys.EU

andrewg@andrewg.com

Proton AG

d.huigens@protonmail.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 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.

Conventions and Definitions The term "OpenPGP Certificate" is used in this document interchangeably with "OpenPGP Transferable Public Key", as defined in . 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.

Keyserver Use Cases A keyserver is typically used for the following (non-exhaustive) use cases:

Certificate Discovery 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.

Certificate Refresh 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 primary key fingerprint search.

Reference Resolution 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.

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 . When making a request over HKPS, a client SHOULD use the same domain-matching rules for TLS certificate verification as in HTTPS .

Request Paths HKP defines three paths, namely "/pks/v2" for the v2 API (), "/pks/lookup" for legacy lookups (), and "/pks/add" for legacy submission (). 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 . It should be noted that there is no "/pks/v1" path. The legacy paths may be considered as "HKP version 1", but contain no explicit version number as they pre-date the modern standard practice of API versioning.

Backwards Compatibility The legacy API is specified below () to describe the version of HKP already in long-standing deployed use. It is expected that existing public keyservers will continue to support this protocol for some time, and so a normative reference is provided in this document. A keyserver MAY choose to implement only the v2 API, for example if it does not expect to be used by legacy clients, or if it only serves v6 or later key material. The "/pks" prefix used in all HKP API paths is maintained for backwards-compatibility with the older install base. While the use of "/.well-known" for fixed paths is normally recommended, we have intentionally chosen to retain the "/pks" prefix in the v2 API. This facilitates a smooth upgrade pathway from legacy to v2, without requiring the reconfiguration of firewalls or HTTP proxies. The authors believe this is still compliant with modern best practice: The use of fixed paths is permitted in custom URL schemes such as hkp(s) () User-writable files under ./well-known are not recommended (), which might prevent an HKP service being served directly from a filesystem ()

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 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 400 Bad request The request was malformed 403 Forbidden The requested category/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 category/operation is not supported In addition, a client SHOULD understand 3xx redirect codes. A server that can distinguish a syntactically invalid HKP request path from a well-formed request that has no matching result MAY return 400 ("Bad Request") for the former case. Clients SHOULD NOT rely on this distinction, as static deployments MAY return 404 ("Not Found") or another appropriate unsuccessful response instead.

The v2 API The v2 API is a RESTful interface that uses the GET, PUT, POST, DELETE, HEAD, and OPTIONS methods. The URL path () is built up of the base path "/pks/v2", followed by request-specific URL path components.

v2 Lookup Format Certificate lookups are done via an HTTP GET request. v2 lookups normally include both "category" and "identifier" URL path components. They are appended to "/pks/v2" as follows:

/ ]]>

The "category" and "identifier" components MUST be supplied. When the v2 lookup format is being used, v2 output format () MUST be returned. The v2 lookup format is designed so that a basic HKP service can be implemented using static files. Category Identifier format Output data See certs/by-identity identity Certificate bundle certs/by-vfingerprint versioned fingerprint Certificate bundle certs/by-keyid key ID Certificate bundle canonical identity Canonical bundle index identity Index of certificates prefixlog date List of prefixes

The "certs/by-identity" Lookup Category A keyserver MAY support the "certs/by-identity" lookup category.

]]>

The "certs/by-identity" category identifies each certificate by matching the contents of its User ID packet(s) (). The response to a successful "certs/by-identity" request is a certificate bundle as specified in , which MUST NOT be ASCII-armored. A keyserver SHOULD limit the returned certificate bundle to a reasonable length. Results SHOULD be sorted in order of decreasing confidence in the identity link (), and then by creation date (most recent first). A keyserver MAY choose to only return results where the identity being searched for exceeds a minimum confidence value, and MAY treat "certs/by-identity" as a synonym for "canonical". If no certificates match the request, the keyserver SHOULD return an appropriate HTTP error code such as 404 ("Not Found").

The "certs/by-vfingerprint" Lookup Category A keyserver MAY support the "certs/by-vfingerprint" lookup category.

/ ]]>

The "certs/by-vfingerprint" category identifies each certificate by the versioned fingerprint of its primary key or a subkey. The one-octet version and 20- or 32-octet fingerprint are provided in the subsequent path components in hexadecimal encoding. The version and fingerprint MUST be padded to standard length with leading zeros, i.e 2 hex digits for the version, and 40 or 64 hex digits for the fingerprint. Unlike legacy fingerprint lookups (), no "0x" prefix is used. The hexadecimal digits are not case sensitive. This is the same octet sequence used in the Issuer Fingerprint and Intended Recipient Fingerprint subpackets (), formatted for readability. A keyserver: SHOULD include matches with both primary key and subkey fingerprints. MAY omit matches with encryption-only subkeys. If no certificates match the request, the keyserver SHOULD return an appropriate HTTP error code such as 404 ("Not Found").

The "certs/by-keyid" Lookup Category A keyserver MAY support the "certs/by-keyid" lookup category.

]]>

The "certs/by-keyid" category identifies each certificate by the Key ID of its primary key or a subkey (). The Key ID is provided in the "identifier" path component as 16 hexadecimal digits, without a preceding "0x". The hexadecimal digits are not case sensitive. A keyserver: SHOULD include matches with both primary key and subkey Key IDs. MAY omit matches with encryption-only subkeys. If no certificates match the request, the keyserver SHOULD return an appropriate HTTP error code such as 404 ("Not Found"). "certs/by-keyid" 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 (), and so certificates with versions greater than 4 MUST NOT be returned in response to a "certs/by-keyid" request.

The "canonical" Lookup Category A keyserver MAY support the "canonical" lookup category.

]]>

The "canonical" category is similar to the "certs/by-identity" category, but is intended specifically for certificate discovery (). A keyserver MUST return either the canonical bundle of the identity being searched for (), or a 404 Not Found error.

The "index" Lookup Category A keyserver MAY support the "index" lookup category.

]]>

This requests a list of certificates on the keyserver whose User IDs match the identity given in the "identifier" path component (). This list is returned in JSON format as specified in . A keyserver SHOULD limit the returned index to a reasonable length. Results SHOULD be sorted in order of decreasing confidence in that identity (), and then by creation date (most recent first). A keyserver MAY choose to only return results where the identity being searched for exceeds a minimum confidence value. If no certificates match the request, the keyserver SHOULD return an appropriate HTTP error code such as 404 ("Not Found").

The "prefixlog" Lookup Category A keyserver MAY support the "prefixlog" lookup category.

]]>

"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 "identifier" path component using the "full-date" format as per , i.e. "2025-12-31". The returned data is a list of CRLF-separated, hexadecimal-encoded, primary key fingerprint prefixes, and each prefix is truncated at a hex-digit (nybble) 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 "certs/by-vfingerprint" 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 the prefixlog endpoint always returns fingerprint prefixes, regardless of fingerprint version. This contrasts with v4 Key IDs, which are constructed from fingerprint suffixes. A keyserver MUST NOT support indexing or downloading certificates by prefix.

OPTIONS Lookup Method A client MAY attempt to detect which lookup categories a keyserver supports by making an OPTIONS request () to a lookup path with the "category" path component present but the "identifier" component absent. A keyserver that supports the lookup category MAY respond with: a 200 "OK" code, an Allow: response header that includes the value "GET" (). 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 "category" and "identifier" path components present. A keyserver SHOULD return an error code such as 403 "Forbidden" to such a request.

HEAD Lookup Method A client MAY attempt to retrieve the metadata of a certificate or certificate bundle by making a HEAD request () to a full lookup path, with the "category" and "identifier" components present. A keyserver SHOULD respond with the same header fields that it would have responded with if a GET request had been made.

v2 Identity Lookups The format of User IDs in OpenPGP has historically been vaguely specified and loosely interpreted (see ). A particular identity may therefore be represented by an arbitrary number of different User ID packets. Implementers should bear in mind that end users will typically search for identities, and not specific representations of that identity. For example, the User ID strings Andrew Gallagher <andrew@example.com> and Andrew B. Gallagher (work email) <andrew@example.com> are both representations of the underlying identity andrew@example.com. v2 "certs/by-identity", "canonical" and "index" lookup requests MUST only return results if the "identifier" path component exactly matches one of the following: The portion between angle brackets (<...>) in an email-address style User ID. The full text string in a non-email-address User ID. A keyserver SHOULD parse an email-address style User ID defensively. In particular, if there is more than one substring of a User ID that could reasonably be interpreted as an email address, then a keyserver SHOULD NOT return an identity match on either substring. Text lookups SHOULD NOT be case sensitive. DNS names are not case sensitive, therefore any identity that contains a DNS name (including email addresses) cannot be reliably located using case sensitive matching. Since the interpretation of User IDs is application-specific, a client MUST check that any User IDs returned from a keyserver are correctly case matched for the intended application.

Lookup Examples Get all certificates containing the email address dshaw@example.com:

Get certificate 0xCAFEDADACAFEDADACAFEDADACAFEDADACAFEDADACAFEDADACAFEDADACAFEDADA (v6 fingerprint):

Get certificate 0xDEADBEEFDECAFBAD (64-bit Key ID):

v2 Submission Format A keyserver MAY accept submissions via an HTTP POST or PUT request, as specified in . v2 submission requests include a "category" URL path component, and optionally an "identifier" path component. These are appended to "/pks/v2" as follows:

PUT /pks/v2// ]]>

The "category" path component MUST be supplied. In PUT submission requests, the "identifier" path component is required. In POST submission requests, the "identifier" path component is omitted. Category Method Input data Output data See certs POST certificate bundle submission response sendtoken POST email address (none) canonical PUT canonical bundle submission response Unless otherwise specified, a keyserver SHOULD respond to v2 submissions with a JSON document as described in . If a keyserver does not support submission 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 category.

The v2 "certs" Submission Category A keyserver MAY support the "certs" submission category.

A keyserver that implements it SHOULD support the basic submission workflow described in . It MAY support other workflows; if so it SHOULD advertise them as described in . A keyserver MAY verify the request and reject any submissions that cannot be verified. This verification SHOULD use a reliable means of authentication, such as login credentials or a Bearer token ().

The v2 "sendtoken" Submission Category A keyserver MAY support the "sendtoken" submission category.

The body of the POST request is a single email address. It SHOULD have a content-type of text/plain. The keyserver SHOULD respond with an empty document. A keyserver that supports the "sendtoken" request category SHOULD attempt to verify the email address by sending a time-limited Bearer token via email. A client that receives the verification email can then use the token in a canonical submission request (). 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 . A human-readable document containing instructions for manual submission. The context for the JSON-LD document is http://hockeypuck.io/contexts/hkp-sendtoken.jsonld (( TBC, issue #40 )), which contains the following fields: Field JSON-LD Type Required Description url http://schema.org/url yes URL to be used for submission token http://schema.org/accessCode yes verification token expires http://schema.org/expires yes expiry time of the token The URL is the full URL to be used for submission, including the identifier component. The token is a randomly-generated string suitable for inclusion verbatim in an Authentication: Bearer HTTP header (). Timestamps MUST be given in UTC, in format without milliseconds, i.e. yyyy-mm-dd hh:mm:ssZ. A receiving client MUST ignore any unknown JSON fields. (( 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 ))

Sample JSON-LD Document

The v2 "canonical" Submission Category A keyserver MAY support the "canonical" submission category.

]]>

The request path is the same as the one used for the "canonical" lookup category (). A keyserver that implements it SHOULD support the basic submission workflow described in . It MAY support other workflows; if so it SHOULD advertise them as described in . This instructs the server that for the identity () supplied in the request path: The certificates contained in the submission that have the corresponding identity are regarded by the owner as canonical for that identity, The owner wishes for these certificates to be served in the same order and format that they appear in the submission, and: Any certificates for that identity that are not contained in the submission are not (or no longer) canonical for that identity. A keyserver MUST verify the request and reject any submissions that cannot be verified. This verification SHOULD use a reliable means of authentication, such as login credentials or a Bearer token (). Once the keyserver verifies the submission, it stores the resulting canonical bundle () and updates any internal confidence values as necessary ().

Basic Submission Basic submission uses a content-type of application/pgp (). The body of the POST or PUT request contains a certificate bundle as specified in , which MUST NOT be ASCII-armored.

Token Authentication When using token authentication with a basic submission workflow, the client adds an Authentication request header containing a Bearer token obtained via a "sendtoken" request ().

]]>

This token MUST correspond to one of the identities present in the canonical bundle being submitted. A client SHOULD remove any User IDs not related to the token. A keyserver MAY reject a canonical bundle that contains User IDs not related to the token.

Advanced Submission Advanced submission uses a content-type of multipart/form-data. The body of the POST or PUT request contains a multipart with one or more parts. The required part has a content-type of application/pgp and MUST be named "keytext" (). This part contains a certificate bundle as specified in , 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.

Submission Feature Detection Using OPTIONS A client MAY attempt to detect which certificate submission workflows a keyserver supports by making an OPTIONS request () to a submission path with the "category" path component present but the "identifier" path component absent. A keyserver that supports v2 submission SHOULD respond with: a 200 code, an Allow: response header that includes the value "POST" or "PUT" as appropriate (), one or more Accept: response header(s) (). Accept response media types MAY include: application/pgp - basic submission without proof application/pgp;proof=tokens - basic submission with token proof multipart/form-data;proof=dkim - advanced submission with DKIM proof (EXPERIMENTAL) (( TODO: check the requirements for CORS preflight, issue #38 )) (( TODO: can we represent acceptable proof types by some other means? issue #54 ))

Canonical Bundles A certificate bundle submitted or returned via a "canonical" request is called a "canonical bundle". A canonical bundle represents both the list of certificates that the key holder wishes to be associated with an identity, and their preferred form of those certificates. A keyserver SHOULD serve only canonical bundles in response to a "canonical" lookup request. A keyserver MAY serve full copies of the matching certificate(s) in response to a "certs" lookup request. For example, a full copy may include valid certificate components obtained by non-canonical submission, but not present in the canonical bundle. When submitting a canonical bundle, any new certificate components SHOULD be merged into the full copy of the corresponding certificate, if the keyserver supports it. Any valid key or self-certification revocations known to the keyserver SHOULD be merged into the corresponding canonical bundle(s), if any. This applies both to revocations already present in the key store, and to those submitted at any later date. A keyserver SHOULD NOT modify a canonical bundle in any other way. A keyserver that accepts submissions MUST allow a valid key revocation certificate for any key to be submitted without identity verification. A valid key revocation signature SHOULD be applied to all copies of the key that it revokes, and SHOULD be served in response to all requests for that key. An implementation MAY however omit some revocations for brevity - for example, if two valid revocations exist with different timestamps but otherwise identical effect, an implementation MAY serve the older revocation and omit the newer one. Other methods such as are more appropriate for controlling the form of certificates returned by non-canonical requests.

Submission Examples (( TODO: issue #39 ))

The Legacy API For backwards compatibility with the existing installed client base, a Legacy API is defined. New implementations SHOULD use the v2 API. The Legacy API is specified to document deployed HKP behavior and to preserve interoperability with existing clients and servers. Implementations of the v2 API are not required to implement the Legacy API unless they claim Legacy API compatibility. Normative requirements in this section apply only to implementations that explicitly support the Legacy API.

Legacy Lookup Format Legacy certificate lookups are done via an HTTP GET request. The URL path () is always "/pks/lookup", and is followed by a request-specific query string (). No URL path components under "/pks/lookup" are used. Most Legacy lookups contain both the "op" (operation) and "search" variables. These roughly correspond to the "category" and "identifier" components of the v2 API, but with subtly different semantics. The "op" variable determines what operation the keyserver will execute, and the "search" variable determines which certificates are operated on. The "op" and "search" variables are supplied as HTTP query strings, in the form <variable-name>=<value>:

&search=[&...] ]]>

The "op" variable MUST be supplied, and the "search" variable MUST be supplied unless the "stats" operation is being requested (). There may also be modifier variables, as specified in below. Keyservers MUST ignore any unknown query string parameters.

The "op" (Operation) Lookup Variable The "op" (operation) variable specifies the lookup operation to be performed on the keyserver. The "op" variable is generally accompanied by a "search" variable 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. Operation Search format Output data See get text Certificate bundle hget SKS hash Certificate bundle index text Index of certificates vindex text Index of certificates stats (none) Implementation info

The "get" Operation 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" variable. The response to a successful "get" operation is an ASCII-armored certificate bundle as specified in . 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 identity (), and then by creation date (most recent first). A keyserver MAY choose to only return results where the identity 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").

The "hget" (hash get) Operation A keyserver MAY support the "hget" operation. "hget" requests a certificate from a keyserver by specifying its digest. The digest is provided in the "search" variable 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").

The "index" Operation 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" variable. 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 identity (), 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").

The "vindex" (verbose index) Operation (Deprecated) A keyserver MAY support the "vindex" operation. The "vindex" operation is deprecated. 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".

The "stats" (statistics/status) Operation (Deprecated) A keyserver MAY support the "stats" operation. The "stats" operation is deprecated. 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" variable SHOULD NOT be supplied, and SHOULD be ignored if received.

The "search" Lookup Variable The "search" variable contains arbitrary text encoded as usual for a HTTP URL. This text may represent a Key ID, or fingerprint, or some text from a User ID on the certificate being sought, depending on the operation.

Legacy Key ID and Fingerprint Searches To search for a certificate by the Key ID or fingerprint of a primary key or subkey, a client SHOULD use a v2 lookup and either the "certs/by-keyid" () or "certs/by-vfingerprint" () lookup category (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" variable. SHOULD include matches with both primary key and subkey fingerprints and Key IDs. MAY omit matches with encryption-only subkeys. 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 (). V3 certificates are no longer considered secure, but MAY be distributed for historical reference.

Legacy Text Searches To perform a Legacy search for a certificate by the text of a User ID, a client SHOULD use the "get" 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 (). Legacy text searches SHOULD only return results if the "search" variable 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. Text searches SHOULD NOT be case sensitive. DNS names are not case sensitive, therefore any User ID that contains a DNS name (including email addresses) cannot be reliably located using case sensitive matching. Since the interpretation of User IDs is application-specific, a client MUST check that any User IDs returned from a keyserver are correctly case matched for the intended application. A client making a Legacy text search SHOULD set the modifier variable "exact=on" (). 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: Canonicalise to Unicode Normalization Form C . Do not use punycode . 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 legacy 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.

Legacy Lookup Examples Search for all certificates containing the email address dshaw@example.com, using plaintext HTTP:

Get certificate 0xDEADBEEFDECAFBADDEADBEEFDECAFBADDEADBEEFDECAFBAD (v4 fingerprint), using HTTPS:

Get certificate 0xDEADBEEFDECAFBAD (64-bit Key ID), using HTTPS:

Legacy Submission Format Legacy certificate submissions are performed via an HTTP POST request. The URL path () is always "/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 . The ASCII armored certificate bundle MUST be form-urlencoded as specified in . There may also be modifier variables, as specified in below. Modifiers 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. 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 legacy submission API.

Legacy Modifier Variables These variables are used to modify basic Legacy requests. Name Context Value See options any list of flags fingerprint lookup "on" or "off" hash lookup "on" or "off" exact lookup "on" or "off"

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". Name Context See nm submission mr lookup

The "nm" (No Modification) Option 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 "mr" (Machine-Readable) Option 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 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 "fingerprint" Variable 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 (). 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.

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 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.

The "exact" Variable 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" variable in text searches (). 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. "exact" is meaningful for Legacy lookups only.

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. 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 , depending on the request.

v2 Output Format Clients making v2 requests: MUST silently ignore any primary keys with unknown versions or algorithms. MUST silently ignore any subkeys with unknown algorithms. MUST silently ignore any unknown fields in JSON responses. In response to a v2 request, a keyserver: MUST set the HTTP header Access-Control-Allow-Origin: *, as specified in . MUST use the format specified in when responding to "index" lookups. MUST use the format specified in when responding to "certs" submissions. MUST return non-armored (binary) certificate bundles in response to lookup requests. MUST set Content-Type: application/json for JSON responses. MUST set Content-Type: application/pgp when returning non-armored certificate bundles (). MAY set Last-Modified: to indicate the modification date of the requested certificate or certificate bundle ().

v2 Indexes A v2 "index" request SHOULD return a JSON list of certificates. If the search was for an identity, it SHOULD be sorted in decreasing order of confidence (). Each certificate object contains some or all of the following fields: Field Type Required Description version integer yes version of the primary key fingerprint string yes fingerprint of the primary key creation string   creation date of the key expiration string   expiration date of the key isExpired boolean     isRevoked boolean     algorithm algorithm   () userIDs userID array   () subkeys subkey array   () Field Type Required Description code integer yes algorithm ID name string   a human-readable identifier for the algorithm bitLength integer   key length in bits (DSA/RSA/ElGamal keys only) Field Type Required Description uidString string yes User ID string contents 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   () Field Type Required Description version integer yes version of the subkey fingerprint string yes fingerprint of the subkey creation string   creation date of the subkey expiration string   expiration date of the subkey isExpired boolean     isRevoked boolean     algorithm algorithm   () Fingerprints are given in hexadecimal notation, without any "0x" prefix. Timestamps MUST be given in UTC, in format without milliseconds, i.e. yyyy-mm-dd hh:mm:ssZ. Algorithm IDs are as specified in . 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.

v2 and Legacy Submission Responses A v2 or Legacy submission 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 Required 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 . 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.

Legacy machine-readable Output Clients requesting machine-readable output in Legacy lookup requests: SHOULD supply options=mr (). MUST silently ignore any content preceding or following a returned armored key block. MUST silently ignore any primary keys with unknown versions or algorithms. MUST silently ignore any subkeys with unknown algorithms. Keyservers returning Legacy machine-readable output: MUST set the HTTP header Access-Control-Allow-Origin: *, as specified in . 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" and "hget" operations); see . MAY set Last-Modified: to indicate the modification date of the requested certificate or certificate bundle (). 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. 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 .

Legacy machine-readable Indexes 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:

: ]]>

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:

::::: ]]>

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 (). Fingerprints and long Key IDs are given in hexadecimal notation, without any "0x" prefix. Timestamps are given in seconds since midnight on 1st January 1970. Algorithm IDs are as specified in . Following the "pub" record are one or more "uid" records to indicate User IDs on the certificate:

::: ]]>

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 percent-encoding () for anything that isn't 7-bit safe as well as for any : and % characters that appear in a field value. Any other characters MAY be percent-encoded, 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-01 00: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.

Media Types Existing OpenPGP media types are insufficient for the purposes of this document. We therefore specify a new media type for binary OpenPGP data, and update the existing application/pgp-keys media type.

The application/pgp Media Type While legacy HKP uses ASCII-armored certificates, the v2 API uses binary format, and only defines media types for ASCII-armored OpenPGP data. We therefore define a new media type for binary OpenPGP data. While it is specified here for use in the v2 HKP API, it is not restricted to certificates and MAY be used in other contexts for any binary OpenPGP data. It is the receiver's responsibility to check that the OpenPGP packet sequence is reasonable in context; the receiver SHOULD NOT rely solely on the media type. Type Extension Description application/pgp pgp A sequence of one or more binary OpenPGP packets

The application/pgp-keys Media Type defines the application/pgp-keys media type as:

• A MIME body part of the content type "application/pgp-keys" contains ASCII-armored transferable Public Key Packets...

Also, states:

• Transferable Public Key packet sequences may be concatenated to allow transferring multiple public keys in one operation

It is however established (but currently unspecified) practice for web APIs to serve v4 detached revocation signatures () in the same packet sequence as OpenPGP certificates, for example in [I-D.koch-openpgp-webkey-service] which states:

• To ease distribution of revoked keys, a server may return revoked keys in addition to a new key. The keys are returned by a single request as concatenated key blocks.

In practice, the most common implementation represents revoked keys as detached revocation signatures, and places them after the new key in the returned packet sequence. This is not interoperable however, as conforming implementations will treat such a signature as an invalid signature over the preceding key, and discard it. In addition, a keyserver may not wish to store or serve the User IDs of revoked (and therefore unusable) keys, following the principle of data minimization. permits revoked certificates that contain no User IDs, but earlier specifications did not, and some legacy clients cannot process them. To ensure that revocations are correctly parsed by both legacy and conforming implementations, detached revocation signatures must be placed in an unambiguous position in the packet sequence. The specification of application/pgp-keys is therefore extended to permit a sequence of zero or more v4 detached revocations to precede any certificates in the OpenPGP packet sequence. For convenience this can be referred to as a "mixed keyring", i.e. a keyring containing a mixture of v4 detached revocations and full certificates. By analogy with the packet grammar of a "mixed keyring" is as follows, where square brackets indicate optionality and ellipsis indicates repetition:

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 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 (). 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. 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.

Certificate Bundle Format 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 and of . An ASCII-armored certificate bundle is a certificate bundle that has been encoded as a single armored block, as specified in . The Legacy API uses ASCII-armored certificate bundles exclusively, whereas the v2 API uses non-armored certificate bundles exclusively. 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.

Detached Revocations For OpenPGP certificates prior to version 6, 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 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.

Certificate Discovery Using HKPS SRV records 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 "openpgpkey" SRV Record 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:

]]>

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.

Discovery Lookup Over HKPS When making an HKPS discovery request, a client SHOULD use an HTTP GET request to an authoritative keyserver using the "canonical" lookup category, with the email address in the "identifier" component. Note that discovery is performed using the "canonical" lookup category, 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 "identifier" component. 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.

Certificate Discovery Example A client trying to locate a certificate for isabella@example.com makes a DNS request for the SRV record at _openpgpkey._https.example.com.. This would return:

On finding this record, the client makes an HTTP GET request for the following URL:

The keyserver returns the canonical bundle for isabella@example.com, and the client proceeds to check its validity according to the local policy.

Security Considerations 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.

IANA Considerations This document allocates the ports 11371 and 11372, the service names "hkps" and "openpgpkey", and the URI schemes "hkp" and "hkps".

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". IANA is also requested to update the following existing template in the "Media Types" registry, where ((THIS DOCUMENT)) should be replaced by the RFC number of this document: application/pgp-keys:

New Registry Entries IANA is requested to add the following entries to the "Service Name and Transport Protocol Port Number" registry as per : 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 : URI Scheme Description Status Reference hkp OpenPGP HTTP Keyserver Permanent This document hkps OpenPGP HTTP Keyserver (Secure) Permanent This document IANA is requested to register the following new template in the "Media Types" registry, where ((THIS DOCUMENT)) should be replaced by the RFC number of this document: application/pgp:

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 defines a date and time format for use in Internet protocols that is a profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar. A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] 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. 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. Many application technologies enable secure communication between two entities by means of Transport Layer Security (TLS) with Internet Public Key Infrastructure using X.509 (PKIX) certificates. This document specifies procedures for representing and verifying the identity of application services in such interactions. This document obsoletes RFC 6125. 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"). audriga GmbH This document specifies how a machine-readable variant of its content can be added to email messages. 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. Punycode is a simple and efficient transfer encoding syntax designed for use with Internationalized Domain Names in Applications (IDNA). It uniquely and reversibly transforms a Unicode string into an ASCII string. ASCII characters in the Unicode string are represented literally, and non-ASCII characters are represented by ASCII characters that are allowed in host name labels (letters, digits, and hyphens). This document defines a general algorithm called Bootstring that allows a string of basic code points to uniquely represent any string of code points drawn from a larger set. Punycode is an instance of Bootstring that uses particular parameter values specified by this document, appropriate for IDNA. [STANDARDS-TRACK] 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. 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. Section 1.1.1 of RFC 3986 defines URI syntax as "a federated and extensible naming system wherein each scheme's specification may further restrict the syntax and semantics of identifiers using that scheme." In other words, the structure of a URI is defined by its scheme. While it is common for schemes to further delegate their substructure to the URI's owner, publishing independent standards that mandate particular forms of substructure in URIs is often problematic. This document provides guidance on the specification of URI substructure in standards. This document obsoletes RFC 7320 and updates RFC 3986. ACLU An OpenPGP certificate can grow in size without bound when third- party certifications are included. This document describes a way for the owner of the certificate to explicitly approve of specific third- party certifications, so that relying parties can safely prune the certificate of any unapproved certifications. ACLU OpenPGP User IDs are UTF-8 strings. Existing documents claim that by conventione, they contain "an RFC 2822 name-addr object", but that's not the case. This document attempts to better describe the actual conventions about User IDs in the deployed OpenPGP ecosystem.

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. The "prefixlog" request category 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 Kahn Gillmor, Heiko Schäfer, Justus Winter and Vincent Breitmoser for help with the v2 request format.

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

Changes Between draft-ietf-openpgp-hkp-00 and draft-ietf-openpgp-hkp-01 Expanded JSON response specifications. Split vfingerprint identifiers into separate version and fingerprint components. Legacy API requirements are only normative for implementations that explicitly support it. Included media type updates directly in this document. Expanded discussion of "/pks" path prefix and "legacy" vs "v1" nomenclature. Added reference to RFC9525 for domain-matching. Clients MUST silently ignore _sub_keys with unknown algorithms. Added note about distinction between 400 and 404.

Changes Between draft-gallagher-openpgp-hkp-10 and draft-ietf-openpgp-hkp-00 None

Changes Between draft-gallagher-openpgp-hkp-09 and draft-gallagher-openpgp-hkp-10 Added JSON-LD example. Fixed some obsolete references.

Changes Between draft-gallagher-openpgp-hkp-08 and draft-gallagher-openpgp-hkp-09 Refactored to separate v2 and Legacy sections. v2 API is now RESTful. v2 uses "category" and "identifier" instead of "op" and "search". v2 keywords are less terse. Defined "canonical bundle". Defined "identity". Resurrected SRV-based discovery. Added basic vs advanced submission. Added structured email. Specified bearer token authentication. Specified use of OPTIONS and HEAD. Specified the Last-Modified response header. Clarify subkey lookups. Sideline inexact matching. Discourage badly-behaved User IDs. Removed some misused HTTP return codes. Added tabular summaries. Added Daniel Huigens as co-author.

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

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 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.

Changes Between draft-gallagher-openpgp-hkp-03 and draft-gallagher-openpgp-hkp-04 Reworded certificate lookups section 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.