idnits 2.17.1 draft-ietf-find-cip-trans-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-26) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. 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. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == 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 463 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The abstract seems to contain references ([CIP-MIME], [CIP-ARCH]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 315 has weird spacing: '... format speci...' == Line 351 has weird spacing: '...empt to send ...' == 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). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: CIP solves this problem by fiat. CIP requests sent using the mail transport MUST include a Reply-To header as specified by RFC-822. Any mail received for processing by a CIP server implementing the mail transport without a Reply-To header MUST be ignored, and a message should be logged for the local administrator. The receiver MUST not attempt to reply with an error to any address derived from the incoming mail. -- 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.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC2045' is mentioned on line 146, but not defined == Missing Reference: 'RFC2069' is mentioned on line 402, but not defined ** Obsolete undefined reference: RFC 2069 (Obsoleted by RFC 2617) == Unused Reference: 'RFC 2045' is defined on line 407, but no explicit reference was found in the text == Unused Reference: 'RFC 2069' is defined on line 414, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2068 (Obsoleted by RFC 2616) ** Obsolete normative reference: RFC 2069 (Obsoleted by RFC 2617) -- Possible downref: Non-RFC (?) normative reference: ref. 'CIP-ARCH' -- Possible downref: Non-RFC (?) normative reference: ref. 'CIP-MIME' ** Obsolete normative reference: RFC 2234 (ref. 'ABNF') (Obsoleted by RFC 4234) -- Possible downref: Non-RFC (?) normative reference: ref. 'CIP-TIO' ** Obsolete normative reference: RFC 2246 (ref. 'TLS') (Obsoleted by RFC 4346) ** Obsolete normative reference: RFC 2487 (ref. 'SMTPTLS') (Obsoleted by RFC 3207) -- Possible downref: Non-RFC (?) normative reference: ref. 'MHREG' Summary: 14 errors (**), 0 flaws (~~), 10 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 FIND Working Group J. Allen 2 Internet Draft WebTV 3 Paul J. Leach 4 Expires October 99 Microsoft 5 Roland Hedberg 6 Catalogix 8 CIP Transport Protocols 10 Status of this Memo 12 This document is an Internet-Draft and is in full conformance 13 with all provisions of section 10 of RFC 2026. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its wroking groups. Note that 17 other groups may also distribute working documents as 18 Internet-Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six 21 months and may be updated, replaced, or obsoleted by other 22 documents at any time. It is inappropriate to use Internet-Drafts 23 as reference material or to cite them other than as "work in 24 progress". 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt. 29 Distribution of this document is unlimited. Please send comments 30 to the FIND working group at . Discussions of 31 the working group are archived at 32 . 34 Abstract 36 This document specifies three protocols for transporting CIP 37 requests, responses and index objects, utilizing TCP, mail, 38 and HTTP. The objects themselves are defined in [CIP-MIME] and the 39 overall CIP architecture is defined in [CIP-ARCH]. 41 1. Protocol 43 In this section, the actual protocol for transmitting CIP index 44 objects and maintaining the mesh is presented. While companion 45 documents ([CIP-ARCH] and [CIP-MIME]) describe the concepts 46 involved and the formats of the CIP MIME objects, this document is 47 the authoritative definition of the message formats and transfer 48 mechanisms of CIP used over TCP, HTTP and mail. 50 1.1 Philosophy 52 The philosophy of the CIP protocol design is one of building-block 53 design. Instead of relying on bulky protocol definition tools, or 54 ad-hoc text encodings, CIP draws on existing, well understood 55 Internet technologies like MIME, RFC-822, Whois++, FTP, and SMTP. 56 Hopefully this will serve to ease implementation and consensus 57 building. It should also stand as an example of a simple way to 58 leverage existing Internet technologies to easily implement new 59 application-level services. 61 1.2 Conventions 63 The key words "MUST" and "MAY" in this document are to be 64 interpreted as described in "Key words for use in RFCs to Indicate 65 Requirement Levels" [KEYWORDS]. 67 Formal syntax is defined using ABNF [ABNF]. 69 In examples octets sent by the sender-CIP are preceded by ">>> " 70 and those sent by the receiver-CIP by "<<< ". 72 2 MIME message exchange mechanisms 74 CIP relies on interchange of standard MIME messages for all 75 requests and replies. These messages are passed over a bidirectional, 76 reliable transport system. This document defines transport over 77 reliable network streams (via TCP), via HTTP, and via the Internet 78 mail infrastructure. 80 The CIP server which initiates the connection (conventionally 81 referred to as a client) will be referred to below as the sender-CIP. 82 The CIP server which accepts a sender-CIP's incoming connection and 83 responds to the sender-CIP's requests is called a receiver-CIP. 85 2.1 The Stream Transport 87 CIP messages are transmitted over bi-directional TCP connections via 88 a simple text protocol. The transaction can take place over any TCP 89 port, as specified by the mesh configuration. There is no "well 90 known port" for CIP transactions. All configuration information in 91 the system must include both a hostname and a port. 93 All sender-CIP actions (including requests, connection initiation, 94 and connection finalization) are acknowledged by the receiver-CIP 95 with a response code. See section 2.1.1 for the format of these 96 codes, a list of the responses a CIP server may generate, and the 97 expected sender-CIP action for each. 99 In order to maintain backwards compatibility with existing Whois++ 100 servers, CIPv3 sender-CIPs MUST first verify that the newer protocol 101 is supported. They do this by sending the following illegal Whois++ 102 system command: "# CIP-Version: 3". On existing Whois++ 103 servers implementing version 1 and 2 of CIP, this results in a 104 500-series response code, and the server terminates the connection. 105 If the server implements CIPv3, it MUST instead respond with 106 response code 300. Future versions of CIP can be correctly 107 negotiated using this technique with a different string (i.e. 108 "CIP-Version: 4"). An example of this short interchange is given 109 below. 111 Note: If a sender-CIP can safely assume that the server implements 112 CIPv3, it may choose to send the "# CIP-Version: 3" string and 113 immediately follow it with the CIPv3 request. This optimization, 114 useful only in known homogeneous CIPv3 meshes, avoids waiting for 115 the roundtrip inherent in the negotiation. 117 Once a sender-CIP has successfully verified that the server supports 118 CIPv3 requests, it can send the request, formatted as a MIME message 119 with Mime-Version and Content-Type headers (only), using the network 120 standard line ending: "". 122 Cip-Req = Req-Hdrs CRLF Req-Body 124 Req-Hdrs = *( Version-Hdr | Req-Cntnt-Hdr ) 125 Req-Body = Body ; format of request body as in [CIP-MIME] 127 Body = Data CRLF "." CRLF 128 Data = ; data with CRLF "." CRLF replaced by 129 ; CRLF ".." CRLF 131 Version-Hdr = "Mime-Version:" "1.0" CRLF 132 Req-Cntnt-Hdr = "Content-Type:" Req-Content CRLF 133 Req-Content = ; format is specified in [CIP-MIME] 135 Cip-Rsp = Rsp-Code CRLF [ Rsp-Hdrs CRLF Rsp-Body ] 136 [ Indx-Cntnt-Hdr CRLF Index-Body ] 137 Rsp-Code = DIGIT DIGIT DIGIT Comment 138 Comment = ; any chars except CR and LF 139 Rsp-Hdrs = *( Version-Hdr | Rsp-Cntnt-Hdr ) 140 Rsp-Cntnt-Hdr = "Content-Type:" Rsp-Content CRLF 141 Rsp-Content = ; format is specified in [CIP-MIME] 142 Rsp-Body = Body ; format of response body as in [CIP-MIME] 144 Indx-Cntnt-Hdr = "Content-Type:" Indx-Obj-Type CRLF 145 Indx-Obj-Type = ; any registered index object's MIME-type 146 ; the format is specified in [RFC2045] 147 Index-Body = Body ; format defined in each index 148 ; specifications 150 CRLF = CR LF ; Internet standard newline 151 CR = %x0D ; carriage return 152 LF = %x0A ; linefeed 153 DIGIT = %x30-39 155 The message is terminated using SMTP-style message termination. 156 The data is sent octet-for-octet, except when the pattern 157 1*["."] is seen, in which case one more period 158 is added. 159 When the data is finished, the octet pattern "." is 160 transmitted to the receiver-CIP. 161 On the receiver-CIP's side, the reverse transformation is applied, 162 and the message read consists of all bytes up to, but not including, 163 the terminating pattern. 165 In response to the request, the receiver-CIP sends a response code, 166 from either the 200, 400, or 500 series. The receiver-CIP then 167 processes the request and replies, if necessary, with a MIME message. 168 This reply is also delimited by an SMTP-style message terminator. 170 After responding with a response code, the receiver-CIP MUST prepare 171 to read another request message, resetting state to the point when 172 the sender-CIP has just verified the CIP version. If the sender-CIP 173 is finished making requests, it may close the connection. In 174 response the receiver-CIP MUST abort reading the message and prepare 175 for a new sender-CIP connection (resetting its state completely). 177 An example is given below. It is again worth reiterating that the 178 command format is defined in [CIP-MIME] whereas the message body is 179 defined in each index object definition. In this example the index 180 object definition in [CIP-TIO] will be used. Line endings are 181 explicitly shown in anglebrackets; newlines in this text are added 182 only for readability. 183 Comments occur in curly-brackets. 185 { sender-CIP connects to receiver-CIP } 186 <<< % 220 Example CIP server ready 187 >>> # CIP-Version: 3 188 <<< % 300 CIPv3 OK! 189 >>> Mime-Version: 1.0 190 >>> Content-type: application/index.cmd.datachanged; type= 191 >>> x-tagged-index-1; dsi=1.2.752.17.5.10 192 >>> 193 >>> updatetype: incremental tagbased 194 >>> thisupdate: 855938804 195 >>> lastupdate: 855940000 196 >>> . 197 <<< % 200 Good MIME message received 198 >>> MIME-Version: 1.0 199 >>> Content-Type: application/index.obj.tagged; 200 >>> dsi=1.2.752.17.5.10; 201 >>> base-uri="ldap://ldap.umu.se/dc=umu,dc=se" 202 >>> 203 >>> version: x-tagged-index-1 204 >>> updatetype: incremental 205 >>> lastupdate: 855940000 206 >>> thisupdate: 855938804 207 >>> BEGIN IO-schema 208 >>> cn: TOKEN 209 >>> sn: FULL 210 >>> title: FULL 211 >>> END IO-Schema 212 >>> BEGIN Update Block 213 >>> BEGIN Old 214 >>> title: 3/testpilot 215 >>> END Old 216 >>> BEGIN New 217 >>> title: 3/chiefpilot 218 >>> END New 219 >>> END Update Block 220 >>> . 221 <<< % 200 Good MIME message received 222 { Sender-CIP shuts down socket for writing } 223 <<< % 222 Connection closing in response to sender-CIP shutdown 224 { receiver-CIP closes its side, resets, and awaits a 225 new sender-CIP } 227 An example of an unsuccessful version negotiation looks like this: 229 { sender-CIP connects to receiver-CIP } 230 <<< % 220 Whois++ server ready 231 >>> # CIP-Version: 3 232 <<< % 500 Syntax error 233 { server closes connection } 235 The sender-CIP may attempt to retry using version 1 or 2 protocol. 236 Sender-CIP may cache results of this unsuccessful negotiation to 237 avoid later attempts. 239 2.1.1 Transport specific response codes 241 The following response codes are used with the stream transport: 243 Code Suggested description Sender-CIP action 244 text 246 200 MIME request received Expect no output, continue session 247 and processed (or close) 249 201 MIME request received Read a response, delimited by SMTP- 250 and processed, output style message delimiter. 251 follows 253 220 Initial server banner Continue with Whois++ interaction, 254 message or attempt CIP version negotiation. 256 222 Connection closing (in Done with transaction. 257 response to sender-CIP 258 close) 260 300 Requested CIP version Continue with CIP transaction, in 261 accepted the specified version. 263 400 Temporarily unable to Retry at a later time. May be used 264 process request to indicate that the server does not 265 currently have the resources 266 available to accept an index. 268 500 Bad MIME message format Retry with correctly formatted MIME 270 501 Unknown or missing Retry with correct CIP command 271 request in 272 application/index.cmd 274 502 Request is missing Retry with correct CIP attributes. 275 required CIP attributes 277 520 Aborting connection for Alert local administrator. 278 some unexpected reason 280 530 Request requires valid Sign the request, if possible, and 281 signature retry. Otherwise, report problem to 282 the administrator. 284 531 Request has invalid Report problem to the administrator. 285 signature 287 532 Cannot check signature Alert local administrator, who should 288 cooperate with remote administrator 289 tp diagnose and resolve the problem. 290 (Probably missing a public key.) 292 2.2 Internet mail infrastructure as transport 294 As an alternative to TCP streams, CIP transactions can take place 295 over the existing Internet mail infrastructure. There are two 296 motivations for this feature of CIP. First, it lowers the barriers 297 to entry for leaf servers. When the need for a full TCP 298 implementation is relaxed, leaf nodes (which, by definition, only 299 send index objects) can consist of as little as a database and an 300 indexing program (possibly written in a very high level language) 301 to participate in the mesh. 303 Second, it keeps with the philosophy of making use of existing 304 Internet technology. The MIME messages used for requests and 305 responses are, by definition of the MIME specification, suitable 306 for transport via the Internet mail infrastructure. With a few 307 simple rules, we open up an entirely different way to interact with 308 CIP servers which choose to implement this transport. See Protocol 309 Conformance, below, for details on what options server implementers 310 have about supporting the various transports. 312 The basic rhythm of request/response is maintained when using the 313 mail transport. The following sections clarify some special cases 314 which need to be considered for mail transport of CIP objects. In 315 general, all mail protocols and mail format specifications 316 (especially MIME Security Multiparts) can be used with the CIP mail 317 transport. 319 2.2.1 CIP-Version negotiation 321 Since no information on which CIP-version is in use is present in 322 the MIME message, this information has to be carried in the 323 mailheader. Therefor CIP requests sent using the mail transport 324 MUST include a CIP-version headerline, to be registered according 325 to [MHREG]. 326 The format of this line is: 328 DIGIT = %x30-39 329 number = 1*DIGIT 330 cipversion = "CIP-Version:" number["." number] 332 2.2.2 Return path 334 When CIP transactions take place over a bidirectional stream, the 335 return path for errors and results is implicit. Using mail as a 336 transport introduces difficulties to the recipient, because it's 337 not always clear from the headers exactly where the reply should go, 338 though in practice there are some heuristics used by MUA's. 340 CIP solves this problem by fiat. CIP requests sent using the mail 341 transport MUST include a Reply-To header as specified by RFC-822. 342 Any mail received for processing by a CIP server implementing the 343 mail transport without a Reply-To header MUST be ignored, and a 344 message should be logged for the local administrator. The receiver 345 MUST not attempt to reply with an error to any address derived 346 from the incoming mail. 348 If there are no circumstances under which a response is to be sent 349 to a CIP request, the sender should include a Reply-To header with 350 the address "<>" in it. 351 Receivers MUST never attempt to send replies to that address, as 352 it is defined to be invalid (both here, and by the BNF grammar in 353 RFC-822). It should be noted that, in general, it is a bad idea to 354 turn off error reporting in this way. However, in the simplest case 355 of an index pushing program, this MAY be a desirable simplification. 357 2.3 HTTP transport 359 HTTP MAY also be used to transport CIP objects, since they are just 360 MIME objects. A transaction is performed by using the POST method to 361 send an application/index.cmd and returning an 362 application/index.response or an application/index.obj in the HTTP 363 reply. The URL that is the target of the post is a configuration 364 parameter of the CIP-sender to CIP-receiver relationship. 366 Example: 368 { the client opens the connection and sends a POST } 369 >>> POST / HTTP/1.1 370 >>> Host: cip.some.corp 371 >>> Content-type: application/index.cmd.noop 372 >>> Date: Thu, 6 Jun 1997 18:16:03 GMT 373 >>> Content-Length: 2 374 >>> Connection: close 375 >>> 376 { the server processes the request } 377 <<< HTTP/1.1 204 No Content 378 { the server closes the connection } 380 In addition to leveraging the security capabilities that come with 381 HTTP, there are other HTTP features that MAY be useful in a CIP 382 context. A CIP client MAY use the Accept-Charset and Accept-Language 383 HTTP headers to express a desire to retrieve an index in a particular 384 character set or natural language. It MAY use the Accept-Encoding 385 header to (e.g.) indicate that it can handle compressed responses, 386 which the CIP server MAY send in conjunction with the Transfer- 387 Encoding header. It MAY use the If-Modified-Since header to prevent 388 wasted transmission of an index that has not changed since the last 389 poll. A CIP server can use the Retry-After header to request that 390 the client retry later when the server is less busy. 392 3. Security considerations 394 There are two levels at which the index information can be 395 protected; the first is by use of the technology available for 396 securing MIME [MIME-SEC] objects, and secondly by using the 397 technology available for securing the transport. 399 When it comes to transport the stream transport can be protected by 400 the use of TLS [TLS] . For HTTP the Security is handled by 401 using HTTP Basic Authentication [RFC 2068], HTTP Message Digest 402 Authentication [RFC2069] or SSL/TLS. Extra protection for the SMTP 403 exchange can be achieve by the use of Secure SMTP over TLS [SMTPTLS]. 405 4. References 407 [RFC 2045] Freed, N., Borenstein, N., "Multipurpose Internet Mail 408 Extensions (MIME) Part One: Format of Internet Message Bodies", 409 November, 1996 411 [RFC 2068] Fielding, et.al., "Hypertext Transfer Protocol -- 412 HTTP/1.1", January, 1997. 414 [RFC 2069] Franks, et. al., "An Extension to HTTP: Digest Access 415 Authentication", January, 1997. 417 [CIP-ARCH] Allen, J., Mealling, M, "The Common Indexing Protocol", 418 work in progress. 420 [CIP-MIME] Allen, J., Mealling, M., "MIME Object Definitions for the 421 Common Indexing Protocol", work in progress. 423 [ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax 424 Specifications: ABNF", RFC 2234, November 1997. 426 [CIP-TIO] Hedberg, et.al. "A Tagged Index Object for use in the 427 Common Indexing Protocol", work in progress. 429 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate 430 Requirement Levels", RFC 2119, Harvard University, March 1997. 432 [MIME-SEC] Galvin, Murphy, Crocker, Freed, "Security Multiparts for 433 MIME: Multipart/Signed and Multipart/Encrypted", RFC 1847, Trusted 434 Information Systems, CyberCash, Innosoft International, October 435 1995. 437 [TLS] Dierks, T., Allen, C., "The TLS Protocol Version 1.0", RFC 438 2246, Certicom, January 1999. 440 [SMTPTLS] Hoffman, P., "SMTP Service Extension for Secure SMTP over 441 TLS", RFC 2487, Internet Mail Consortium, January 1999. 443 [MHREG] Jacob, P., "Mail and Netnews Header Registration Procedure", 444 work in progress. 446 5. Authors' Addresses 448 Jeff R. Allen Paul J. Leach 449 246 Hawthorne St. Microsoft 450 Palo Alto, CA 94301 1 Microsoft Way 451 USA Redmond, WA 98052 452 EMail: jeff.allen@acm.org Email: paulle@microsoft.com 454 Roland Hedberg 455 Catalogix 456 Dalsveien 53 457 0775 Oslo 458 Norway 459 EMail: roland@catalogix.ac.se