idnits 2.17.1 draft-ietf-rescap-proto-format-01.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 579 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 are 3 instances 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 391 has weird spacing: '...4-octet strin...' == Line 496 has weird spacing: '...request x000...' == Line 497 has weird spacing: '...request x000...' == Line 498 has weird spacing: '...request x000...' == Line 499 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 (August 8, 2000) is 8624 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 431, but no explicit reference was found in the text -- Possible downref: Normative reference to a draft: ref. 'RESCAP-MAIN' ** Downref: Normative reference to an Informational draft: draft-ietf-rescap-req (ref. 'RESCAP-REQUIRE') ** 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 (~~), 9 warnings (==), 3 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-01.txt Internet Mail Consortium 3 August 8, 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 Servers conforming to this specification MUST check the tag of the 161 first item in the request, and MUST reject a request that starts with 162 an item whose tag is not x0001. The tag in the FullRequest item acts like 163 a version number for requests. If this specification is updated in 164 the future in an incompatible fashion, the future specification will 165 use a different tag for the first request item. 167 3.1.2 BaseURI 169 The BaseURI item (tag x0002) specifies the Internet resource for which 170 the rescap client wants information. The structure of the item is a URI 171 string as defined in [URI] for a single resource. Every FullRequest 172 MUST include exactly one BaseURI item. 174 3.1.3 ItemsToReturn 176 The ItemsToReturn item (tag x0003) lists the response-type items that 177 the client would like the server to return. It is a request, not a 178 demand; the server is allowed to return any response-type item it 179 chooses. The client can use this item to specify that it only is 180 interested in a limited number of response-type items, and that the 181 server should not waste its time or bandwidth returning any items not 182 listed in the ItemsToReturn item. The structure of the item is a 183 sequence of tag values, each of which is two octets long. 185 If the ItemsToReturn item is not included in a request, the server may 186 return whatever information it pleases about the resource named in the 187 BaseURI item. If the ItemsToReturn item is included and its length is 188 zero, the client wants the server to return all the information it has 189 about the resource named in the BaseURI item. If the ItemsToReturn item 190 is included and its length is greater than zero, the client wants the 191 server to return only response-type items of the type listed in the 192 ItemsToReturn item. 194 Note that it is not an error for the client to list items in the 195 ItemsToReturn item that cannot be returned to by the server. 197 3.1.4 AuthInTheClear 199 The AuthInTheClear item (tag x0005) holds a sequence of binary octets. 200 The format of the sequence is determined by private agreement between 201 the client and the server. This item MUST only be sent when using 202 the secure form of rescap. It MUST NOT be used in the basic form 203 of rescap. 205 3.1.5 AuthIP 207 The AuthIP item (tag x0008) is a zero-length item that indicates that 208 the client requests that it gain some authorization simply based on the 209 IP address of the client, which the server will determine by examining 210 the IP address of the connection. This item MAY be used in either the 211 basic form or the secure form of rescap. 213 3.1.6 PrivUseRequest00 through PrivUseRequest255 215 The PrivUseRequest00 through PrivUseRequest255 items (tags xFE00 216 through xFEFF) are reserved for private use as request-type items and 217 will never be assigned by IANA. These tags may be used by protocol 218 developers to test protocols that they are developing, such as during 219 the process of preparing Internet Drafts that contain registration for 220 future request-type items. The structure of the items is undefined. 222 3.2 Basic response types 224 Servers MUST implement the FullResponse and Status types, and SHOULD 225 implement the Referral type. Servers SHOULD implement the TTLOfInfo, 226 ExpirationOfInfo, and DateOfChange types. Servers MAY implement the 227 PrivUseResponse types. 229 Clients MUST be able to interpret the FullResponse, Status, and 230 Referral types; clients SHOULD be able to process Referrals by fetching 231 the information from the referred-to host. A rescap client SHOULD NOT 232 attempt to make any use of the user response-type items that it does 233 not fully understand. 235 Note: clients MUST parse TTLOfInfo, ExpirationOfInfo, and DateOfChange 236 items even if the clients do not know how to check the expiration or 237 modification of information (such as a client that does not know when 238 the information will be delivered to the user or a client that does not 239 know the current time). These items encapsulate other response items 240 that the client may want to deliver to the user regardless of the 241 expiration status. Clients that cannot check the expiration or 242 creation information MUST treat the enclosed response-type data as if 243 it appeared outside of the time-specific types, and in the case of 244 TTLOfInfo and ExpirationOfInfo, SHOULD indicate to the user that the 245 server put an expiration on the information and that the expiration was 246 not checked. 248 3.2.1 FullResponse 250 The FullResponse item (tag x000C) is used to encapsulate the other 251 response-type items. A rescap server's Response to a client MUST be a 252 single FullResponse item. The structure of the item is a two-octet 253 integer that specifies the number of items that follow that are part of 254 the FullResponse item. If the number of items that follows the FullResponse 255 item is larger than that indicated in the FullResponse item, the server 256 MUST ignore them. 258 The items that are encapsulated by the FullResponse item MUST be 259 response-type items. A FullResponse item MUST NOT encapsulate another 260 FullResponse item. Note that some items contain other items; the 261 prohibition against request-type items is only for items directly 262 encapsulated in the FullResponse item, not items that are encapsulated 263 in lower-level items. 265 A FullResponse item MUST contain one or more instance of a Status item, 266 and MAY contain zero or more instances of each of other response-type 267 items. Note that some response-type items further restrict the number 268 of times those items can appear in a FullResponse item. 270 Clients conforming to this specification MUST check the tag of the 271 first item in the response, and MUST reject a response that starts with 272 an item whose tag is not x000C. The tag in the FullResponse item acts like 273 a version number for responses. If this specification is updated in 274 the future in an incompatible fashion, the future specification will 275 use a different tag for the first response item. 277 3.2.2 Status 279 The Status item (tag x000D) gives status information to the client 280 about its request. The structure of the status tag is a sequence of a 281 one-octet main status code, a one-octet secondary status code, and an 282 optional string that is a sequence of characters from the ISO/IEC 283 10646-1 character set encoded with the UTF-8 transformation format 284 defined in [UTF8]. A FullResponse MUST have at least one Status item 285 and MAY have more than one Status item. A rescap server SHOULD include 286 only as many Status items as necessary for a client to process the 287 response. 289 The optional string may be used to transmit status information, but it 290 is optional. In fact, a rescap server that is trying to keep its 291 responses as short as possible SHOULD NOT include a string at all. 293 The rescap client MAY choose to display the string to the client. 294 However, because there is no way to know the languages understood by 295 the user, the string may be of little or no use to them. 297 Note: If a client sent a request over UDP and receives a Status 298 item of x0201, the client SHOULD sent the same request over TCP. 300 The values for the main status code (the first octet of the Status 301 item) are based loosely on those in SMTP. They are: 302 x00 - positive completion 303 x01 - transient negative completion 304 x02 - permanent negative completion 305 x03 - informational 307 A rescap client MAY use just the main status code to decide how to 308 display any results of the request to the user who made the request. 310 The complete list of status codes is: 312 x0000 The request was fully processable 314 x0100 Too busy; try again whenever you feel like it 315 x0101 Too busy; try again later than 10 seconds from now 316 x0102 Too busy; try again later than 60 seconds from now 317 x0103 Too busy; the Referral item in the response leads to another 318 rescap server authoritative for this resource 320 x0200 The body of the request was longer than what was indicated in the 321 length 322 x0201 The body of the request was shorter than what was indicated in 323 the length 324 x0202 The request included items not of request-type 325 x0203 The request included more than one BaseURI item 326 x0204 This server is not authoritative for the resource named in the 327 BaseURI item and no referral is available 328 x0205 This server is not authoritative for the resource named in the 329 BaseURI item; the URI in the Referral item leads you to a server 330 that this server believes is authoritative 332 x0300 Successful authorization through AuthInTheClear 333 x0301 Successful authorization through AuthIP 334 x0302 Some items requested in the ItemsToReturn were not returned due 335 to insufficient authentication or lack of authentication 337 3.2.3 Referral 339 The Referral item (tag x000E) tells the client that another rescap 340 server has authoritative information for the requested resource. If some 341 information may be available from several sources, an "authoritative" 342 source is one whose response should be regarded as superseding all 343 others in the event of any discrepancy. The structure of the Referral 344 item is a URI string as defined in [URI] for a single resource. The 345 scheme in the URI MUST be "rescap-basic" or "rescap-secure". If a 346 FullResponse item contains a Referral item or a Referral item enclosed 347 in a SignedResponse or an EncryptedResponse item, there MUST NOT be any 348 other items in the FullResponse item other than Status items. 350 3.2.4 TTLOfInfo 352 The TTLOfInfo item (tag x0017) specifies how long the server assures 353 that the information enclosed in the item will be valid. The TTLOfInfo 354 item has the structure of a four-octet integer followed by a two-octet 355 integer. The four-octet integer represents the number of seconds before 356 the server no longer assures that the listed items are valid. Note: 357 this value is approximate and probably will only be accurate within 358 minutes or tens of seconds. The two-octet integer is the number of the 359 following items that are covered by the TTL; these MUST be response- 360 type items. 362 If a rescap client does not support expiration of items, it MUST treat 363 the items in a TTLOfInfo item as if they appeared outside of a 364 TTLOfInfo item. This allows a server to respond with TTLOfInfo without 365 knowing whether or not the client handles the expiration time listed in 366 the item. 368 3.2.5 ExpirationOfInfo 370 The ExpirationOfInfo item (tag x0018) specifies the final time in the 371 future that the server assures that the information enclosed in the 372 item will be valid. The ExpirationOfInfo item has the structure of a 373 14-octet string followed by a two-octet integer. The 14- octet ASCII 374 string represents the date at Greenwich Mean Time in YYYYMMDDHHMMSS 375 format after which the server no longer assures that the listed items 376 are valid. The two-octet integer is the number of the following items 377 that are covered by the expiration time; these MUST be response-type 378 items. 380 If a rescap client does not support expiration of items, it MUST treat 381 the items in a ExpirationOfInfo item as if they appeared outside of a 382 ExpirationOfInfo item. This allows a server to respond with 383 ExpirationOfInfo without knowing whether or not the client handles the 384 expiration time listed in the item. 386 3.2.6 DateOfChange 388 The DateOfChange item (tag x001C) specifies the time that the server 389 last changed the value of the attribute (or, if it has never been 390 changed, first created the value). The DateOfChange item has the 391 structure of a 14-octet string followed by a two-octet integer. The 392 14-octet ASCII string represents the date at Greenwich Mean Time as a 393 string of ASCII characters in YYYYMMDDHHMMSS format. The two-octet 394 integer is the number of the following items that are covered by the 395 date of change; these MUST be response-type items. 397 If a rescap client does not support showing modification times of 398 items, it MUST treat the items in a DateOfChange item as if they 399 appeared outside of a DateOfChange item. This allows a server to 400 respond with DateOfChange without knowing whether or not the client 401 handles the display of modification time listed in the item. 403 3.2.7 PrivUseResponse00 through PrivUseResponse255 405 The PrivUseResponse00 through PrivUseResponse255 items (tags xFF00 406 through xFFFF) are reserved for private use as response-type items and 407 will never be assigned by IANA. These tags may be used by protocol 408 developers to test protocols that they are developing, such as during 409 the process of preparing Internet Drafts that contain registration for 410 future response-type items. The structure of the items is undefined. 412 4. Security Considerations 414 This document inherits all of the security considerations of 415 [RESCAP-MAIN]. 417 A server may choose to allow authorization through two mechanisms. 418 AuthInTheClear can only be used in secure form rescap, is simple client 419 identification; AuthIP, can be used in either basic form or secure 420 form. Both provide simple authentication based on a single identifier 421 for the client. 423 5. References 425 [MUSTSHOULD] "Key words for use in RFCs to Indicate Requirement 426 Levels", RFC 2119. 428 [RESCAP-MAIN] "The rescap Resolution Protocol", 429 draft-ietf-rescap-proto-main. 431 [RESCAP-REQUIRE] "ResCap Requirements", draft-ietf-rescap-req. 433 [URI] "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396. 435 [UTF8] "UTF-8, a transformation format of ISO 10646", RFC 2279. 437 A. IANA Considerations 439 A.1 Item registry 441 IANA will maintain a registry of all rescap items. The registry will be 442 populated by the items in this specification and any other RFC. The 443 RFCs must give sufficient detail so that interoperability between 444 independent implementations is possible. The registry will contain the 445 name of the item, the tag value, the type, and the RFC which defines 446 the item. Each name in the registry must be unique, and each tag value 447 must also be unique. The types in the registry are "request-type" and 448 "response-type". IANA should also list the RFC in which the items are 449 defined so that protocol designers know where to find the document 450 defining the items. 452 Each RFC that defines rescap items must include an application of the 453 form: 455 To: iana@iana.org 456 From: 457 Subject: Registration of rescap items 459 The following are the rescap items defined in this document. 461 Item Type Tag 463 A.2 Status value registry 465 IANA will maintain a registry of all rescap status values. The registry 466 will be populated by the status values in this specification and any 467 other RFC. The RFCs must give sufficient detail so that 468 interoperability between independent implementations is possible. The 469 registry will contain the value of the status value, a brief 470 description of the meaning of the value, and the RFC which defines the 471 value. Each value in the registry must be unique. IANA should also list 472 the RFC in which the status values are defined so that protocol 473 designers know where to find the document defining the status values. 475 Each RFC that defines rescap status values must include an application 476 of the form: 478 To: iana@iana.org 479 From: 480 Subject: Registration of rescap status values 482 The following are the rescap status values defined in this document. 484 Value Meaning 486 B. Registration of rescap Types and Status Values 488 B.1 Registration of rescap Types 490 To: iana@iana.org 491 From: Paul Hoffman 492 Subject: Registration of rescap items 493 The following are the rescap items defined in this document. 495 Item Type Tag 496 FullRequest request x0001 497 BaseURI request x0002 498 ItemsToReturn request x0003 499 AuthInTheClear request x0005 500 AuthIP request x0008 501 FullResponse response x000C 502 Status response x000D 503 Referral response x000E 504 TTLOfInfo response x0017 505 ExpirationOfInfo response x0018 506 DateOfChange response x001C 507 PrivUseRequest00 through 508 PrivUseRequest255 request xFE00-xFEFF 509 PrivUseResponse00 through 510 PrivUseResponse255 response xFF00-xFFFF 512 B.2 Registration of rescap Status Values 514 To: iana@iana.org 515 From: Paul Hoffman 516 Subject: Registration of rescap status values 518 The following are the rescap status values defined in this document. 520 Value Meaning 521 x0000 The request was fully processable 522 x0001 Successful authorization through AuthInTheClear 523 x0002 Successful authorization through AuthDigest 525 x0100 Too busy; try again whenever you feel like it 526 x0101 Too busy; try again later than 10 seconds from now 527 x0102 Too busy; try again later than 60 seconds from now 528 x0103 Too busy; the Referral item in the response leads to another 529 rescap server authoritative for this resource 531 x0200 The body of the request was longer than what was indicated in the 532 length 533 x0201 The body of the request was shorter than what was indicated in 534 the length 535 x0202 The request included items not of request-type 536 x0203 The request included more than one BaseURI item 537 x0204 This server is not authoritative for the resource named in the 538 BaseURI item and no referral is available 539 x0205 This server is not authoritative for the resource named in the 540 BaseURI item; the URI in the Referral item leads you to a server 541 that this server believes is authoritative 543 x0300 Successful authorization through AuthInTheClear 544 x0301 Successful authorization through AuthIP 545 x0302 Some items requested in the ItemsToReturn were not returned due 546 to insufficient authentication or lack of authentication 548 C. Acknowledgments 550 Graham Klyne provided suggestions for early versions of the first draft. 551 Chris Newman devised the method of encapsulation that works with the 552 method of fragmentation. 554 D. Changes Between -00 and -01 Versions of This Document 556 Added notes in 3.1.1 and 3.2.1 about the tag value acting like a version 557 number. 559 Changed the URL schemes in 3.2.3. 561 E. Author Contact Information 563 Paul Hoffman 564 Internet Mail Consortium 565 127 Segre Place 566 Santa Cruz, CA 95060 USA 567 phoffman@imc.org