idnits 2.17.1 draft-ietf-rescap-proto-format-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: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 589 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Authors' Addresses Section. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There is 1 instance of too long lines in the document, the longest one being 3 characters in excess of 72. ** There are 14 instances of lines with control characters in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 377 has weird spacing: '...4-octet strin...' == Line 485 has weird spacing: '...request x000...' == Line 486 has weird spacing: '...request x000...' == Line 487 has weird spacing: '...request x000...' == Line 488 has weird spacing: '...request x000...' == (9 more instances...) -- 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 (January 30, 2000) is 8850 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) == Unused Reference: 'RESCAP-REQUIRE' is defined on line 417, but no explicit reference was found in the text == Unused Reference: 'SHA-1' is defined on line 419, but no explicit reference was found in the text -- No information found for draft-draft-hoffman-rescap-proto-main - is the name correct? -- Possible downref: Normative reference to a draft: ref. 'RESCAP-MAIN' ** Downref: Normative reference to an Informational draft: draft-ietf-rescap-req (ref. 'RESCAP-REQUIRE') -- Possible downref: Non-RFC (?) normative reference: ref. 'SHA-1' ** Obsolete normative reference: RFC 2396 (ref. 'URI') (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 2279 (ref. 'UTF8') (Obsoleted by RFC 3629) Summary: 9 errors (**), 0 flaws (~~), 10 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet Draft Paul Hoffman 2 draft-ietf-rescap-proto-format-00.txt Internet Mail Consortium 3 January 30, 2000 4 Expires in six months 6 The rescap Request and Response Format 8 Status of this memo 10 This document is an Internet-Draft and is in full conformance with all 11 provisions of Section 10 of RFC2026. 13 Internet-Drafts are working documents of the Internet Engineering Task 14 Force (IETF), its areas, and its working groups. Note that other 15 groups may also distribute working documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six months 18 and may be updated, replaced, or obsoleted by other documents at any 19 time. It is inappropriate to use Internet-Drafts as reference material 20 or to cite them other than as "work in progress." 22 The list of current Internet-Drafts can be accessed at 23 http://www.ietf.org/ietf/1id-abstracts.txt 25 The list of Internet-Draft Shadow Directories can be accessed at 26 http://www.ietf.org/shadow.html. 28 Abstract 30 The rescap protocol is a general client-server resolution protocol that 31 translates resource identifiers to a list of attributes. For instance, 32 a rescap client can ask a rescap server for the attributes of a 33 particular mail user. rescap is very light-weight and acts only as a 34 resolution protocol, not a directory service. This document describes 35 the format of rescap requests and responses. 37 1. Introduction 39 The rescap protocol is described in [RESCAP-MAIN]. This document 40 specifies the format the request and response messages. It also 41 defines the required rescap items that must be supported. 43 This document and others relating to the rescap protocol are being 44 discussed in the recap WG of the IETF on the rescap@cs.utk.edu mailing 45 list. To subscribe, send a message to rescap-request@cs.utk.edu. An 46 archive of the mailing list is available at 47 . 49 1.1 Terminology 51 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 52 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 53 document are to be interpreted as described in [MUSTSHOULD]. 55 Hexadecimal values are indicated as "xNN" or "xNNNN". For example, 56 xA0B1 corresponds to the octet xA0 followed by the octet xB1. 58 2. Request and Response Format 60 Rescap requests and responses have a simple format. The format is 61 optimized for simple processing in small clients. It is also optimized 62 for size so that it is more likely that requests and responses can fit 63 in single UDP datagrams. 65 The basic unit of a rescap request or response is the item. An item 66 consists of exactly three parts: 67 - a two-octet tag 68 - a two-octet length 69 - content whose length and structure are defined by the tag 70 Each of the three parts of an are in network byte order, as is the 71 entire item. 73 The tag values are given in this document and in other documents that 74 profile rescap for various resource types. The length is the length of 75 the content of the item, measured in octets. Some tags define 76 fixed-length content, while other tags define variable-length content. 78 A program parsing a request or response can easily skip over items 79 whose tags it doesn't recognize by reading the tag, reading the length, 80 and skipping over the number of octets given in the length to get to 81 the beginning of the next item. 83 There are two types of items: request-type items and response-type 84 items. The type of the item is given in each item's specification. 86 2.1 Long content 88 The most significant bit of the two-octet length part of an item is a 89 continuation marker. If the continuation marker is "1", the item has 90 been split into two or more fragments. The item following an item whose 91 continuation marker is "1" MUST have the same tag value as the 92 preceding item. The first fragment that has a continuation marker of 93 "0" is the last fragment in the item. When reconstructing a fragmented 94 item, the content of all fragments are appended in the same sequence 95 that they appeared in the data steam. 97 A consequence of this design is that any item whose length is greater 98 than x7FFF MUST be split into at least two packets. Any item MAY be 99 split into fragments. A process interpreting a stream of rescap items 100 MUST be able to correctly handle long content. That is, if an item has 101 a continuation marker of "1" in the length part, the process MUST read 102 the next item, check that the tag matches that of the preceding item, 103 and append the content of the second item to that of the first item, 104 until the process comes to an item with the continuation marker set to 105 "0". It is an error if the process comes to an item with a different 106 tag value than the preceding item if that preceding item had a 107 continuation marker of "1". 109 Design note: the method of using a two-octet length and checking for 110 the special value for the continuation marker was chosen instead of 111 using a four-octet length in order to keep the size of the rescap 112 response shorter, and therefore make it more likely that a response 113 would fit in a single UDP datagram. The vast majority of items will 114 probably have lengths less than x7FFF. The continuation marker allows a 115 program to marshal fewer than x7FFF octets if it has memory 116 constraints. The cost of having to check for the special case of a 117 continuation marker seems to be worth the tradeoff of making every item 118 two octets longer. 120 3. Basic requests and responses 122 The items in this section are included in a rescap client's request to 123 a rescap server and in the server's response to the client. A rescap 124 request is always a FullRequest item; that item contains other 125 request-type items. A rescap response is always a FullResponse item; 126 that item contains other response-type items. 128 3.1 Basic request types 130 Clients MUST be able to emit the FullRequest and BaseURI types, and 131 SHOULD be able to emit ItemsToReturn. Clients MAY implement the 132 AuthInTheClear, AuthIP, and PrivUseRequest types. Servers MUST be able 133 to interpret the FullRequest, BaseURI, and ItemsToReturn types, 134 although servers do not have to comply with the request in 135 ItemsToReturn. For instance, a server may not want to return certain 136 items due to lack of authorization or due to the response becoming too 137 long. 139 3.1.1 FullRequest 141 The FullRequest item (tag x0001) is used to encapsulate the other 142 request-type items. A rescap client's request to the server MUST be a 143 single FullRequest item. The structure of the item is a two-octet 144 integer that specifies the number of items that follow that are part of 145 the FullRequest. If the number of items that follows the FullRequest 146 item is larger than that indicated in the FullRequest item, the server 147 MUST ignore them. 149 The items that are encapsulated by the FullRequest item MUST be 150 request-type items. A FullRequest item MUST NOT encapsulate another 151 FullRequest item. Note that some items contain other items; the 152 prohibition against response-type items is only for items directly 153 encapsulated in the FullRequest item, not items that are encapsulated 154 in lower-level items. 156 A FullRequest item MUST contain exactly one instance of a BaseURI item, 157 and MAY contain zero or one instances of each of the other request-type 158 items. 160 3.1.2 BaseURI 162 The BaseURI item (tag x0002) specifies the Internet resource for which 163 the rescap client wants information. The structure of the item is a URI 164 string as defined in [URI] for a single resource. Every FullRequest 165 MUST include exactly one BaseURI item. 167 3.1.3 ItemsToReturn 169 The ItemsToReturn item (tag x0003) lists the response-type items that 170 the client would like the server to return. It is a request, not a 171 demand; the server is allowed to return any response-type item it 172 chooses. The client can use this item to specify that it only is 173 interested in a limited number of response-type items, and that the 174 server should not waste its time or bandwidth returning any items not 175 listed in the ItemsToReturn item. The structure of the item is a 176 sequence of tag values, each of which is two octets long. 178 If the ItemsToReturn item is not included in a request, the server may 179 return whatever information it pleases about the resource named in the 180 BaseURI item. If the ItemsToReturn item is included and its length is 181 zero, the client wants the server to return all the information it has 182 about the resource named in the BaseURI item. If the ItemsToReturn item 183 is included and its length is greater than zero, the client wants the 184 server to return only response-type items of the type listed in the 185 ItemsToReturn item. 187 Note that it is not an error for the client to list items in the 188 ItemsToReturn item that cannot be returned to by the server. 190 3.1.4 AuthInTheClear 192 The AuthInTheClear item (tag x0005) holds a sequence of binary octets. 193 The format of the sequence is determined by private agreement between 194 the client and the server. This item MUST only be sent when using 195 the secure form of rescap. It MUST NOT be used in the basic form 196 of rescap. 198 3.1.5 AuthIP 200 The AuthIP item (tag x0008) is a zero-length item that indicates that 201 the client requests that it gain some authorization simply based on the 202 IP address of the client, which the server will determine by examining 203 the IP address of the connection. This item MAY be used in either the 204 basic form or the secure form of rescap. 206 3.1.6 PrivUseRequest00 through PrivUseRequest255 208 The PrivUseRequest00 through PrivUseRequest255 items (tags xFE00 209 through xFEFF) are reserved for private use as request-type items and 210 will never be assigned by IANA. These tags may be used by protocol 211 developers to test protocols that they are developing, such as during 212 the process of preparing Internet Drafts that contain registration for 213 future request-type items. The structure of the items is undefined. 215 3.2 Basic response types 217 Servers MUST implement the FullResponse and Status types, and SHOULD 218 implement the Referral type. Servers SHOULD implement the TTLOfInfo, 219 ExpirationOfInfo, and DateOfChange types. Servers MAY implement the 220 PrivUseResponse types. 222 Clients MUST be able to interpret the FullResponse, Status, and 223 Referral types; clients SHOULD be able to process Referrals by fetching 224 the information from the referred-to host. A rescap client SHOULD NOT 225 attempt to make any use of the user response-type items that it does 226 not fully understand. 228 Note: clients MUST parse TTLOfInfo, ExpirationOfInfo, and DateOfChange 229 items even if the clients do not know how to check the expiration or 230 modification of information (such as a client that does not know when 231 the information will be delivered to the user or a client that does not 232 know the current time). These items encapsulate other response items 233 that the client may want to deliver to the user regardless of the 234 expiration status. Clients that cannot check the expiration or 235 creation information MUST treat the enclosed response-type data as if 236 it appeared outside of the time-specific types, and in the case of 237 TTLOfInfo and ExpirationOfInfo, SHOULD indicate to the user that the 238 server put an expiration on the information and that the expiration was 239 not checked. 241 3.2.1 FullResponse 243 The FullResponse item (tag x000C) is used to encapsulate the other 244 response-type items. A rescap server's Response to a client MUST be a 245 single FullResponse item. The structure of the item is a two-octet 246 integer that specifies the number of items that follow that are part of 247 the FullResponse item. If the number of items that follows the FullResponse 248 item is larger than that indicated in the FullResponse item, the server 249 MUST ignore them. 251 The items that are encapsulated by the FullResponse item MUST be 252 response-type items. A FullResponse item MUST NOT encapsulate another 253 FullResponse item. Note that some items contain other items; the 254 prohibition against request-type items is only for items directly 255 encapsulated in the FullResponse item, not items that are encapsulated 256 in lower-level items. 258 A FullResponse item MUST contain one or more instance of a Status item, 259 and MAY contain zero or more instances of each of other response-type 260 items. Note that some response-type items further restrict the number 261 of times those items can appear in a FullResponse item. 263 3.2.2 Status 265 The Status item (tag x000D) gives status information to the client 266 about its request. The structure of the status tag is a sequence of a 267 one-octet main status code, a one-octet secondary status code, and an 268 optional string that is a sequence of characters from the ISO/IEC 269 10646-1 character set encoded with the UTF-8 transformation format 270 defined in [UTF8]. A FullResponse MUST have at least one Status item 271 and MAY have more than one Status item. A rescap server SHOULD include 272 only as many Status items as necessary for a client to process the 273 response. 275 The optional string may be used to transmit status information, but it 276 is optional. In fact, a rescap server that is trying to keep its 277 responses as short as possible SHOULD NOT include a string at all. 279 The rescap client MAY choose to display the string to the client. 280 However, because there is no way to know the languages understood by 281 the user, the string may be of little or no use to them. 283 Note: If a client sent a request over UDP and receives a Status 284 item of x0201, the client SHOULD sent the same request over TCP. 286 The values for the main status code (the first octet of the Status 287 item) are based loosely on those in SMTP. They are: 288 x00 - positive completion 289 x01 - transient negative completion 290 x02 - permanent negative completion 291 x03 - informational 293 A rescap client MAY use just the main status code to decide how to 294 display any results of the request to the user who made the request. 296 The complete list of status codes is: 298 x0000 The request was fully processable 300 x0100 Too busy; try again whenever you feel like it 301 x0101 Too busy; try again later than 10 seconds from now 302 x0102 Too busy; try again later than 60 seconds from now 303 x0103 Too busy; the Referral item in the response leads to another 304 rescap server authoritative for this resource 306 x0200 The body of the request was longer than what was indicated in the 307 length 308 x0201 The body of the request was shorter than what was indicated in 309 the length 310 x0202 The request included items not of request-type 311 x0203 The request included more than one BaseURI item 312 x0204 This server is not authoritative for the resource named in the 313 BaseURI item and no referral is available 314 x0205 This server is not authoritative for the resource named in the 315 BaseURI item; the URI in the Referral item leads you to a server 316 that this server believes is authoritative 318 x0300 Successful authorization through AuthInTheClear 319 x0301 Successful authorization through AuthIP 320 x0302 Some items requested in the ItemsToReturn were not returned due 321 to insufficient authentication or lack of authentication 323 3.2.3 Referral 325 The Referral item (tag x000E) tells the client that another rescap 326 server has authoritative information for the requested resource. If 327 some information may be available from several sources, an 328 "authoritative" source is one whose response should be regarded as 329 superseding all others in the event of any discrepancy. The structure 330 of the Referral item is a URI string as defined in [URI] for a single 331 resource. The scheme in the URI MUST be "rescap". If a FullResponse 332 item contains a Referral item or a Referral item enclosed in a 333 SignedResponse or an EncryptedResponse item, there MUST NOT be any 334 other items in the FullResponse item other than Status items. 336 3.2.4 TTLOfInfo 338 The TTLOfInfo item (tag x0017) specifies how long the server assures 339 that the information enclosed in the item will be valid. The TTLOfInfo 340 item has the structure of a four-octet integer followed by a two-octet 341 integer. The four-octet integer represents the number of seconds before 342 the server no longer assures that the listed items are valid. Note: 343 this value is approximate and probably will only be accurate within 344 minutes or tens of seconds. The two-octet integer is the number of the 345 following items that are covered by the TTL; these MUST be response- 346 type items. 348 If a rescap client does not support expiration of items, it MUST treat 349 the items in a TTLOfInfo item as if they appeared outside of a 350 TTLOfInfo item. This allows a server to respond with TTLOfInfo without 351 knowing whether or not the client handles the expiration time listed in 352 the item. 354 3.2.5 ExpirationOfInfo 356 The ExpirationOfInfo item (tag x0018) specifies the final time in the 357 future that the server assures that the information enclosed in the 358 item will be valid. The ExpirationOfInfo item has the structure of a 359 14-octet string followed by a two-octet integer. The 14- octet ASCII 360 string represents the date at Greenwich Mean Time in YYYYMMDDHHMMSS 361 format after which the server no longer assures that the listed items 362 are valid. The two-octet integer is the number of the following items 363 that are covered by the expiration time; these MUST be response-type 364 items. 366 If a rescap client does not support expiration of items, it MUST treat 367 the items in a ExpirationOfInfo item as if they appeared outside of a 368 ExpirationOfInfo item. This allows a server to respond with 369 ExpirationOfInfo without knowing whether or not the client handles the 370 expiration time listed in the item. 372 3.2.6 DateOfChange 374 The DateOfChange item (tag x001C) specifies the time that the server 375 last changed the value of the attribute (or, if it has never been 376 changed, first created the value). The DateOfChange item has the 377 structure of a 14-octet string followed by a two-octet integer. The 378 14-octet ASCII string represents the date at Greenwich Mean Time as a 379 string of ASCII characters in YYYYMMDDHHMMSS format. The two-octet 380 integer is the number of the following items that are covered by the 381 date of change; these MUST be response-type items. 383 If a rescap client does not support showing modification times of 384 items, it MUST treat the items in a DateOfChange item as if they 385 appeared outside of a DateOfChange item. This allows a server to 386 respond with DateOfChange without knowing whether or not the client 387 handles the display of modification time listed in the item. 389 3.2.7 PrivUseResponse00 through PrivUseResponse255 391 The PrivUseResponse00 through PrivUseResponse255 items (tags xFF00 392 through xFFFF) are reserved for private use as response-type items and 393 will never be assigned by IANA. These tags may be used by protocol 394 developers to test protocols that they are developing, such as during 395 the process of preparing Internet Drafts that contain registration for 396 future response-type items. The structure of the items is undefined. 398 4. Security Considerations 400 This document inherits all of the security considerations of 401 [RESCAP-MAIN]. 403 A server may choose to allow authorization through two mechanisms. 404 AuthInTheClear can only be used in secure form rescap, is simple client 405 identification; AuthIP, can be used in either basic form or secure 406 form. Both provide simple authentication based on a single identifier 407 for the client. 409 5. References 411 [MUSTSHOULD] "Key words for use in RFCs to Indicate Requirement 412 Levels", RFC 2119. 414 [RESCAP-MAIN] "The rescap Resolution Protocol", 415 draft-draft-hoffman-rescap-proto-main. 417 [RESCAP-REQUIRE] "ResCap Requirements", draft-ietf-rescap-req. 419 [SHA-1] "Secure Hash Standard", NIST FIPS publication 180-1, 420 April 1995. 422 [URI] "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396. 424 [UTF8] "UTF-8, a transformation format of ISO 10646", RFC 2279. 426 A. IANA Considerations 428 A.1 Item registry 430 IANA will maintain a registry of all rescap items. The registry will be 431 populated by the items in this specification and any other RFC. The 432 RFCs must give sufficient detail so that interoperability between 433 independent implementations is possible. The registry will contain the 434 name of the item, the tag value, the type, and the RFC which defines 435 the item. Each name in the registry must be unique, and each tag value 436 must also be unique. The types in the registry are "request-type" and 437 "response-type". IANA should also list the RFC in which the items are 438 defined so that protocol designers know where to find the document 439 defining the items. 441 Each RFC that defines rescap items must include an application of the 442 form: 444 To: iana@iana.org 445 From: 446 Subject: Registration of rescap items 448 The following are the rescap items defined in this document. 450 Item Type Tag 452 A.2 Status value registry 454 IANA will maintain a registry of all rescap status values. The registry 455 will be populated by the status values in this specification and any 456 other RFC. The RFCs must give sufficient detail so that 457 interoperability between independent implementations is possible. The 458 registry will contain the value of the status value, a brief 459 description of the meaning of the value, and the RFC which defines the 460 value. Each value in the registry must be unique. IANA should also list 461 the RFC in which the status values are defined so that protocol 462 designers know where to find the document defining the status values. 464 Each RFC that defines rescap status values must include an application 465 of the form: 467 To: iana@iana.org 468 From: 469 Subject: Registration of rescap status values 471 The following are the rescap status values defined in this document. 473 Value Meaning 475 B. Registration of rescap Types and Status Values 477 B.1 Registration of rescap Types 479 To: iana@iana.org 480 From: Paul Hoffman 481 Subject: Registration of rescap items 482 The following are the rescap items defined in this document. 484 Item Type Tag 485 FullRequest request x0001 486 BaseURI request x0002 487 ItemsToReturn request x0003 488 AuthInTheClear request x0005 489 AuthIP request x0008 490 FullResponse response x000C 491 Status response x000D 492 Referral response x000E 493 TTLOfInfo response x0017 494 ExpirationOfInfo response x0018 495 DateOfChange response x001C 496 PrivUseRequest00 through 497 PrivUseRequest255 request xFE00-xFEFF 498 PrivUseResponse00 through 499 PrivUseResponse255 response xFF00-xFFFF 501 B.2 Registration of rescap Status Values 503 To: iana@iana.org 504 From: Paul Hoffman 505 Subject: Registration of rescap status values 507 The following are the rescap status values defined in this document. 509 Value Meaning 510 x0000 The request was fully processable 511 x0001 Successful authorization through AuthInTheClear 512 x0002 Successful authorization through AuthDigest 514 x0100 Too busy; try again whenever you feel like it 515 x0101 Too busy; try again later than 10 seconds from now 516 x0102 Too busy; try again later than 60 seconds from now 517 x0103 Too busy; the Referral item in the response leads to another 518 rescap server authoritative for this resource 520 x0200 The body of the request was longer than what was indicated in the 521 length 522 x0201 The body of the request was shorter than what was indicated in 523 the length 524 x0202 The request included items not of request-type 525 x0203 The request included more than one BaseURI item 526 x0204 This server is not authoritative for the resource named in the 527 BaseURI item and no referral is available 528 x0205 This server is not authoritative for the resource named in the 529 BaseURI item; the URI in the Referral item leads you to a server 530 that this server believes is authoritative 532 x0300 Successful authorization through AuthInTheClear 533 x0301 Successful authorization through AuthIP 534 x0302 Some items requested in the ItemsToReturn were not returned due 535 to insufficient authentication or lack of authentication 537 C. Acknowledgments 539 Graham Klyne provided suggestions for early versions of the first draft. 540 Chris Newman devised the method of encapsulation that works with the 541 method of fragmentation. 543 D. Changes Between Versions of This Document 545 This document began as a single document that included the material 546 in [RESCAP-MAIN]. It was split into two so that people could think 547 about each part separately. Thus, a great deal has been cut out and 548 moved to the other draft. 550 Changed the security model significantly in line with the main 551 document. This eliminated all of the signed and encrypted items, 552 leaving only two authentication types. This also caused there to 553 be no more data-type items, which simplified things a bit. 555 3.1.1, 3.1.2, 3.2.4, 3.2.5, 3.2.6: Changed the method of encapsulation 556 from making the items fully encapsulate their content to just 557 containing the number of following items that are considered 558 encapsulated. 560 3.2.2: Created informational type of response. 562 3.2.4: Added note at the end of the first paragraph to make the 563 granularity fuzzy. 565 3.2.5: Clarified that the time was a string. 567 3.2.6: Clarified that the time was a string. 569 E. Author Contact Information 571 Paul Hoffman 572 Internet Mail Consortium 573 127 Segre Place 574 Santa Cruz, CA 95060 USA 575 phoffman@imc.org