idnits 2.17.1 draft-shaw-openpgp-hkp-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 33 instances of lines with control characters in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 2003) is 7710 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Downref: Normative reference to an Informational RFC: RFC 1945 (ref. '2') ** Obsolete normative reference: RFC 1866 (ref. '3') (Obsoleted by RFC 2854) ** Obsolete normative reference: RFC 2440 (ref. '4') (Obsoleted by RFC 4880) Summary: 5 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet-Draft D. Shaw 2 Expires September 2003 Jabberwocky Tech 3 March 2003 5 The OpenPGP HTTP Keyserver Protocol (HKP) 6 draft-shaw-openpgp-hkp-00.txt 8 Status of this Memo 10 This document is an Internet-Draft and is in full conformance with 11 all provisions of Section 10 of RFC2026. 13 Internet-Drafts are working documents of the Internet Engineering 14 Task Force (IETF), its areas, and its working groups. Note that 15 other groups may also distribute working documents as 16 Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six months 19 and may be updated, replaced, or obsoleted by other documents at any 20 time. It is inappropriate to use Internet-Drafts as reference 21 material or to cite them other than as "work in progress." 23 The list of current Internet-Drafts can be accessed at 24 http://www.ietf.org/ietf/1id-abstracts.txt 26 The list of Internet-Draft Shadow Directories can be accessed at 27 http://www.ietf.org/shadow.html. 29 Abstract 31 This document specifies a series of conventions to implement an 32 OpenPGP keyserver using the Hypertext Transfer Protocol (HTTP). As 33 this document is a codification and extension of a protocol that is 34 already in wide use, strict attention is paid to backward 35 compatibility with these existing implementations. 37 Table of Contents 39 Status of this Memo ...................................... 1 40 Abstract ................................................. 1 41 Table of Contents ........................................ 1 42 1. Introduction ............................................. 2 43 1.1 Terms ................................................ 2 44 2. HKP and HTTP ............................................. 2 45 3. Requesting Data From A Keyserver ......................... 3 46 3.1 Basic Variables ...................................... 3 47 3.1.1 The "search" variable .......................... 3 48 3.1.1.1 Key ID and V4 Fingerprint Searches ..... 3 49 3.1.1.2 V3 Fingerprint Searches ................ 3 50 3.1.1.3 Text Searches .......................... 4 51 3.1.2 The "op" (operation) Variable .................. 4 52 3.1.2.1 The "get" operation .................... 4 53 3.1.2.2 The "index" operation .................. 4 54 3.1.2.3 The "vindex" (verbose index) operation.. 4 55 3.1.2.4 Other operations ....................... 5 57 3.2 Modifier Variables ................................... 5 58 3.2.1 The "options" variable ......................... 5 59 3.2.2 The "fingerprint" variable ..................... 5 60 3.2.3 The "exact" variable ........................... 6 61 3.2.3 Other variables ................................ 6 62 3.4 Request Examples ..................................... 6 63 4. Submitting Keys To A Keyserver ........................... 6 64 5. Output Formats ........................................... 6 65 5.1 Machine Readable Output .............................. 7 66 5.2 Machine Readable Indexes ............................. 7 67 6. Extended Status Codes .................................... 8 68 7. Locating a HKP Keyserver ................................. 9 69 8. Security Considerations .................................. 9 70 9. IANA Considerations ...................................... 9 71 10. Normative References ..................................... 10 72 11. Author's Address ......................................... 10 74 1. Introduction 76 For ease of use, public key cryptography requires a key distribution 77 system. For many years, the most commonly used system has been a key 78 server - a server that stores public keys and can be searched for a 79 given key. The HTTP Keyserver Protocol is a OpenPGP keyserver 80 implemented using HTTP. 82 1.1. Terms 84 This document uses the terms "MUST", "SHOULD" and "MAY" as defined in 85 RFC-2119 [1], along with the negated forms of those terms. 87 2. HKP and HTTP 89 As HKP is implemented over HTTP, everything in RFC-1945 [2] applies 90 to HKP as well, and HKP error codes are the same as the ones used in 91 HTTP. In order to give as much information to the client about error 92 conditions, is good practice to return the most specific error code 93 possible: for example, returning 404 ("Not Found") rather than 400 94 ("Bad Request") when a key is not found. 96 This document gives suggested HTTP error codes for several common 97 situations. Note that these are only suggestions, and 98 implementations may have good reasons (such as not revealing the 99 reason why a request failed) for using other error codes. 101 Due the very large deployment of HKP clients based on HTTP version 102 1.0, HKP keyservers MUST support HTTP 1.0. HKP keyservers MAY 103 additionally support other HTTP versions. 105 [ dshaw : I expect this to be controversial, but we've got tons of 106 deployed code that only works with 1.0. I'd be willing to discuss 107 removing this MUST or make it a SHOULD and add a "implementation 108 notes" section pointing out the problem instead. ] 110 By convention and history, HKP uses HTTP on TCP port 11371. It has 111 been suggested by some that for reasons of maximum compatibility 112 with firewalls and filtering HTTP proxies, it is better to use the 113 standard HTTP port (TCP port 80). See section 7, Locating a HKP 114 Keyserver for an automated way for clients to discover the correct 115 port. 117 3. Requesting Data From A Keyserver 119 Keyserver requests are done via a HTTP GET URL that encodes the 120 request within it. Specifically, the abs_path (see [2], section 121 3.2) is built up of the base request "/pks/lookup", followed by any 122 variables. Arguments are passed through the usual means as 123 specified in [3], section 8.2.2. The variables may be given in any 124 order. Keyservers MUST ignore any unknown variables. 126 3.1. Basic Variables 128 All HKP requests contain the "op" (operation) and "search" 129 variables. The "op" variable determines what operation the 130 keyserver will take, and the "search" variable determines that keys 131 are operated on. 133 3.1.1. The "search" Variable 135 The search variable contains arbitrary text encoded as usual for a 136 HTTP URL. This text may represent the key ID of the key being 137 sought or some text from a user ID on the key being sought. 139 If any particular type of searching is not supported, the keyserver 140 should return an appropriate HTTP error code such as 501 ("Not 141 Implemented"). The server MUST NOT return an error code (such as 142 404 ("Not Found")) that could be mistaken by the client for a valid 143 response. 145 3.1.1.1. Key ID and V4 Fingerprint Searches 147 If a key is being sought by its key ID, the key ID string is 148 prefixed with an "0x" to indicate a hexadecimal number. Key ID 149 strings may be 8 digits (32-bit key ID), 16 digits (64-bit key ID), 150 32 digits (version 3 fingerprint), or 40 digits (version 4 151 fingerprint). The hexadecimal digits are not case sensitive. 153 A keyserver that allows searching by keyid MUST accept the 160-bit 154 version 4 fingerprint, 64-bit key IDs, and 32-bit key IDs in the 155 "search" variable. Note this does not mean that the keyserver will 156 actually use the full length of the request in the search, as it 157 may internally create a 32-bit or 64-bit key ID from a version 4 158 fingerprint (by taking the low-order 32 or 64 bits respectively), 159 or a 32-bit key ID from a 64-bit key ID (by taking low-order 32 160 bits). That said, a keyserver SHOULD use at least 64 bits of the 161 key ID if available. 163 3.1.1.2. V3 Fingerprint Searches 164 The 128-bit version 3 fingerprint is represented by a leading "0x", 165 followed by 32 case-insensitive hexadecimal digits. Note that v3 166 fingerprints are treated differently and not grouped with keyid or 167 v4 fingerprint searches as it is not possible to calculate a 64-bit 168 or 32-bit keyid from a v3 fingerprint. 170 3.1.1.3. Text Searches 172 How a keyserver handles a textual search is implementation defined. 173 See also the definition of the "exact" variable for a method to 174 give additional instructions to the server on how the search is to 175 be executed. 177 3.1.2. The "op" (operation) Variable 179 The op variable specifies the operation to be performed on the 180 keyserver. The op variable is generally used with the "search" 181 variable to specify the keys that should be operated on. 183 3.1.2.1. The "get" operation 185 The "get" operation requests keys from the keyserver. A string that 186 specifies which key(s) to return is provided in the "search" 187 variable. 189 The response to a successful "get" request is a HTTP document 190 containing a keyring as specified in RFC-2440 [4], section 11.1, and 191 ASCII armored as specified in section 6.2. 193 The response may be wrapped in any HTML or other text desired, except 194 that the actual key data consisting of an initial line break, the 195 "-----BEGIN PGP PUBLIC KEY BLOCK-----" header, the armored key data 196 itself, the "-----END PGP PUBLIC KEY BLOCK-----" header, and a final 197 line break MUST NOT be modified from the form specified in [4]. 199 If no keys match the request, the keyserver should return an 200 appropriate HTTP error code such as 404 ("Not Found"). 202 3.1.2.2. The "index" Operation 204 The "index" operation requests a list of keys on the keyserver that 205 match the text or key ID in the "search" variable. Historically, the 206 "index" operation returned a human readable HTML document containing 207 links for each found key, but this is not required. 209 If the "index" operation is not supported, the keyserver should 210 return an appropriate HTTP error code such as 501 ("Not 211 Implemented"). 213 3.1.2.3. The "vindex" (verbose index) Operation 215 The "vindex" operation is similar to "index" in that it provides a 216 list of keys on the keyserver that match the text of key ID in the 217 "search" variable. Historically, a "vindex" response was the same as 218 "index" with the addition of showing the signatures on each key, but 219 this is not required. 221 If the "vindex" operation is not supported, the keyserver should 222 return an appropriate HTTP error code such as 501 ("Not 223 Implemented"). 225 3.1.2.4. Other Operations 227 Other site-specific or nonstandard operations can be indicated by 228 prefixing the operation name with the string "x-". 230 3.2. Modifier Variables 232 These variables are used to modify basic requests. 234 3.2.1. The "options" Variable 236 This variable takes one or more arguments, separated by commas. 237 These are used to modify the behavior of the keyserver on a 238 per-request basis. 240 3.2.1.1. The "mr" (Machine Readable) Option 242 The machine readable option instructs the server that a program 243 (rather than a person) is making the request, so the output may be 244 customized for that use. See Section 5, Output Formats for the 245 specific details of machine readable output. 247 3.2.1.2. The "nm" (No Modification) Option 249 As keyservers may modify submitted keys to suit a particular 250 policy, this option is used to inform the keyserver that the 251 submitter would rather have the submission fail completely then 252 have the submitted key(s) modified. An example of this would be a 253 keyserver that does not accept user IDs with an email address 254 outside of the local domain. If such a key was submitted, the 255 keyserver could trim any noncompliant user IDs before accepting the 256 key. If this option was set, then the key submission would fail. 258 3.2.1.3. Other Options 260 Other site-specific or nonstandard options can be indicated by 261 prefixing the option name with the string "x-". 263 3.2.2. The "fingerprint" Variable 265 This variable takes one argument: "on" or "off". If present and 266 on, it instructs the server to provide the key fingerprint for each 267 key in an "index" or "vindex" operation. This variable has no 268 effect on any other operation. The exact format of the displayed 269 fingerprint, like the "index" and "vindex" operations themselves, 270 is implementation defined. 272 3.2.3. The "exact" Variable 274 This variable takes one argument: "on" or "off". If present and 275 on, it instructs the server to search for an exact match for the 276 contents of the "search" variable. The exact meaning of "exact 277 match" is implementation defined. 279 3.2.3. Other Variables 281 Other site-specific or nonstandard variables can be indicated by 282 prefixing the variable name with the string "x-". 284 3.4. Request Examples 286 Search for all keys containing the string "dshaw": 287 http://keys.example.com:11371/pks/lookup?search=dshaw&op=index 289 Get key 0x99242560 (32-bit key ID): 290 http://keys.example.com:11371/pks/lookup?op=get&search=0x99242560 292 4. Submitting Keys To A Keyserver 294 Keyserver submissions are done via a HTTP POST URL. Specifically, 295 the abs_path (see [2], section 3.2) is set to "/pks/add", and the key 296 data is provided via HTTP POST as specified in [2], section 8.3, and 297 [3], section 8.2.3. 299 The body of the POST message contains a "keytext" variable which is 300 set to an ASCII armored keyring as specified in [4], sections 6.2 301 and 11.1. The ASCII armored keyring should also be urlencoded as 302 specified in [3], section 8.2.1. Note that more than one key may 303 be submitted in a single transaction. 305 There may also be an "options" variable, as specified in section 306 3.2.1 above. 308 If a keyserver does not support adding keys via HTTP, then requests 309 to do so should return an appropriate HTTP error code, such as 403 310 ("Forbidden") if key submission has been disallowed, or 501 ("Not 311 Implemented") if the server does not support HTTP key submission. 312 The keyserver MUST NOT return an error code (such as 404 ("Not 313 Found")) that could be mistaken by the client for a valid response. 315 5. Output Formats 317 HKP is intended for both human and programmatic use. The "machine 318 readable" option is used to tailor the output for a given use. In 319 general, the "human readable" output is implementation specific. 320 For interoperability, the "machine readable" output MUST carefully 321 follow the guidelines given here. 323 Note that there is an installed base of programs that do in fact 324 attempt to parse the human readable "index" format used in the pksd 325 keyserver. Care should be taken with the choice of an "index" format 326 if compatibility with these programs is desired. 328 5.1. Machine Readable Output 330 When machine readable output is requested, several changes are made 331 to output: 333 - Key retrievals (op=get) do not contain any text aside from the 334 ASCII armored keyring. The document is also sent to the user 335 using Content-Type: application/pgp-keys as specified in RFC-3156 336 [6]. 338 - Key indexes (op=index) use the format specified in Section 5.2, 339 Machine Readable Indexes. 341 5.2. Machine Readable Indexes 343 The machine readable index format is a list of records that can be 344 easily parsed by a machine. The document is 7-bit clean, and as such 345 is sent with no encoding and Content-Type: text/plain. 347 The machine readable response begins with an optional information 348 line: 350 info:: 352 = this is the version of this output format. 353 Currently, this is the number 1. 355 = the number of keys returned in this response. Note 356 this is the number of keys, and not the number of 357 lines returned. That is, it should match the number 358 of "pub:" lines returned. 360 If this optional line is not included, or the version information is 361 not supplied, the version number is assumed to be 1. 363 The key listings themselves are made up of several lines per key. 364 The first line specifies the primary key: 366 pub:::::: 368 = this is either the fingerprint or the key ID of the 369 key. Either the 16-digit or 8-digit key IDs are 370 acceptable, but obviously the fingerprint is best. A 371 keyserver should use the most specific of the key IDs 372 that it has available. Since it is not possible to 373 calculate the key ID from a V3 key fingerprint, for V3 374 keys this should be either the 16-digit or 8-digit 375 key ID only. 377 = the algorithm number from [4]. (i.e. 1==RSA, 17==DSA, 378 etc). 380 = the key length (i.e. 1024, 2048, 4096, etc.) 382 = creation date of the key in standard RFC-2440 383 [4] form (i.e. number of seconds since 1/1/1970 384 UTC time) 386 = expiration date of the key in standard 387 RFC-2440 [4] form (i.e. number of seconds 388 since 1/1/1970 UTC time) 390 = letter codes to indicate details of the key, if any. 391 Flags may be in any order. The meaning of "disabled" 392 is implementation-specific. Note that individual 393 flags may be unimplemented, so the absence of a given 394 flag does not necessarily mean the absence of the 395 detail. 397 r == revoked 398 d == disabled 399 e == expired 401 Following the "pub" line are one or more "uid" lines to indicate user 402 IDs on the key: 404 uid:::: 406 = the user ID string, with HTTP %-escaping 407 for anything that isn't 7-bit safe as 408 well as for the ":" character. Any other 409 characters may be escaped, as desired. 411 creationdate, expirationdate, and flags mean the same here as in the 412 "pub" line. The information is taken from the self-signature, if 413 any, and applies to the user ID in question, and not to the key as a 414 whole. 416 Note that empty fields are allowed. For example, a key with no 417 expiration date would have the field empty. Also, 418 a keyserver that does not track a particular piece of information 419 may leave that field empty as well. Colons for empty fields on the 420 end of each line may be left off, if desired. 422 6. Extended Status Codes 424 As HKP is implemented over HTTP, when a status or error code needs 425 to be returned, the most appropriate HTTP code should be used. 427 Occasionally there is a need to express a condition that cannot be 428 expressed via the HTTP 1.0 status code list. In these cases, an 429 additional HTTP header may be added to the response. This 430 additional header is of the form "X-HKP-Status:" and is followed by 431 one of the following status codes: 433 xxx - Submitted key was altered to match keyserver policy. 435 xxx - Submitted key was rejected as per keyserver policy. 436 xxx - The search resulted in more responses then the keyserver 437 was willing to return. 439 7. Locating a HKP Keyserver 441 Clients are usually manually configured with the address of a HKP 442 keyserver. Client implementors should be aware that it is 443 reasonably common practice to use a single name in DNS that 444 resolves to multiple address records. When receiving a DNS 445 response with multiple addresses, clients SHOULD try each address 446 until a server is reached. The order to try these addresses in is 447 implementation defined. 449 A far more flexible scheme for listing multiple HKP keyservers in 450 DNS is the use of DNS SRV records as specified in RFC-2782 [5]. 451 DNS SRV allows for different priorities and weights to be applied 452 to each HKP keyserver in the list, which allows an administrator 453 much more control over how clients will contact the servers. The 454 SRV symbolic service name for HKP keyservers is "hkp". For 455 example, the SRV record for HKP keyservers in domain "example.com" 456 would be "_hkp._tcp.example.com". 458 SRV records contain the port that the target server runs on, so SRV 459 can also be used to automatically discover the proper port for 460 contacting a HKP keyserver. 462 An additional use of SRV records is when a client needs to locate a 463 specified key by email address. For example, a client trying to 464 locate a key for isabella@silvie.example.com could consult 465 "_hkp._tcp.silvie.example.com". 467 HKP clients SHOULD support SRV records. 469 8. Security Considerations 471 As described here, a keyserver is a searchable database of public 472 keys accessed over the network. While there may be security 473 considerations arising from distributing keys in this manner, this 474 does not impact the security of OpenPGP itself. 476 Without some sort of trust relationship between the client and 477 server, information returned from a keyserver in search results 478 cannot be trusted by the client until the OpenPGP client actually 479 retrieves and checks the key for itself. This is important and 480 must be stressed: without a specific reason to treat information 481 otherwise, all search results must be regarded as untrustworthy and 482 informational only. 484 9. IANA Considerations 486 This document assigns the DNS SRV symbolic name "hkp". 488 10. Normative References 490 [1] S. Bradner, "Key words for use in RFCs to Indicate 491 Requirement Level", BCP 14, RFC 2119, March 1997. 493 [2] T. Berners-Lee, "Hypertext Transfer Protocol 1.0", 494 RFC 1945, May 1996. 496 [3] T. Berners-Lee, "Hypertext Markup Language - 2.0", 497 RFC 1866, November 1995. 499 [4] J. Callas, L. Donnerhacke, H. Finney and R. Thayer, 500 "OpenPGP Message Format", RFC 2440, November 1998. 502 [5] A. Gulbrandsen, P. Vixie, and L. Esibov, "A DNS RR for 503 specifying the location of services (DNS SRV)", RFC 504 2782, February 2000. 506 [6] M. Elkins, D. Del Torto, R. Levien, and T. Roessler, 507 "MIME Security with OpenPGP", RFC 3156, August 2001. 509 11. Author's Address 511 David Shaw 512 16 Farina Road 513 Newton, MA 02459 515 Email: dshaw@jabberwocky.com 516 Tel: +1 (617) 332-8443 518 This document is a formalization and extension of the HKP 519 originally implemented in the PKS keyserver by Marc Horowitz, which 520 in turn was based on earlier work by Brian LaMacchia and Michael 521 Graff. Without their grounding, this document would not exist. 523 The author would also like to thank Peter Gutmann for his work on 524 the Certstore protocol, some of which was applicable here, and the 525 members of the pgp-keyserver-folk mailing list who contributed 526 valuable comments and suggestions.