idnits 2.17.1 draft-ietf-find-cip-trans-00.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. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** 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 329 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 a Security Considerations 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.) ** There are 3 instances of too long lines in the document, the longest one being 1 character in excess of 72. ** 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 17 has weird spacing: '...and may be up...' == Line 242 has weird spacing: '... format speci...' == Line 266 has weird spacing: '...empt to send ...' -- 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 (June 5, 1997) is 9822 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) -- Missing reference section? 'CIP-MIME' on line 317 looks like a reference -- Missing reference section? 'CIP-ARCH' on line 315 looks like a reference -- Missing reference section? 'RFC 2068' on line 311 looks like a reference -- Missing reference section? 'RFC 2069' on line 313 looks like a reference Summary: 10 errors (**), 0 flaws (~~), 5 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 in 6 months Microsoft 5 June 5, 1997 7 CIP Transport Protocols 9 Status of this Memo 11 This document is an Internet-Draft. Internet-Drafts are working 12 documents of the Internet Engineering Task Force (IETF), its areas, and 13 its working groups. Note that other groups may also distribute working 14 documents as Internet-Drafts. 16 Internet-Drafts are draft documents valid for a maximum of six months 17 and may be updated, replaced, or obsoleted by other documents at any 18 time. It is inappropriate to use Internet-Drafts as reference material 19 or to cite them other than as "work in progress". 21 WARNING: The specification in this document is subject to change, and 22 will certainly change. It is inappropriate AND STUPID to implement to 23 the proposed specification in this document. In particular, anyone who 24 implements to this specification and then complains when it changes will 25 be properly viewed as an idiot, and any such complaints shall be 26 ignored. YOU HAVE BEEN WARNED. 28 To learn the current status of any Internet-Draft, please check the 1id- 29 abstracts.txt listing contained in the Internet-Drafts Shadow 30 Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), 31 munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or 32 ftp.isi.edu (US West Coast). 34 Distribution of this document is unlimited. Please send comments to the 35 FIND working group at . Discussions of the working 36 group are archived at . 39 Abstract 41 This document specifies three protocols for transporting CIP requests, 42 responses and index objects, utilizing TCP, mail, and HTTP. The objects 43 themselves are defined in [CIP-MIME] and the overall CIP architecture is 44 defined in [CIP-ARCH]. 46 1. Protocol 48 In this section, the actual protocol for transmitting CIP index objects 49 and maintaining the mesh is presented. While companion documents ([CIP- 50 ARCH] and [CIP-MIME]) describes the concepts involved and the formats of 51 the CIP MIME objects, this document is the authoritative definition of 52 the message formats and transfer mechanisms of CIP used over TCP, HTTP 53 and mail. 55 1.1 Philosophy 57 The philosophy of the CIP protocol design is one of building-block 58 design. Instead of relying on bulky protocol definition tools, or ad-hoc 59 text encodings, CIP draws on existing, well understood Internet 60 technologies like MIME, RFC-822, Whois++, FTP, and SMTP. Hopefully this 61 will serve to ease implementation and consensus building. It should also 62 stand as an example of a simple way to leverage existing Internet 63 technologies to easily implement new application-level services. 65 1.2 MIME message exchange mechanisms 67 CIP relies on interchange of standard MIME messages for all requests and 68 replies. These messages are passed over a bidirectional, reliable 69 transport system. This document defines transport over reliable network 70 streams (via TCP), via HTTP, and via the Internet mail infrastructure. 72 The CIP server which initiates the connection (conventionally referred 73 to as a client) will be referred to below as the sender-CIP. The CIP 74 server which accepts a sender-CIP's incoming connection and responds to 75 the sender-CIP's requests is called a receiver-CIP. 77 1.3 The Stream Transport 79 CIP messages are transmitted over bi-directional TCP connections via a 80 simple text protocol. The transaction can take place over any TCP port, 81 as specified by the mesh configuration. There is no "well known port" 82 for CIP transactions. All configuration information in the system must 83 include both a hostname and a port. 85 All sender-CIP actions (including requests, connection initiation, and 86 connection finalization) are acknowledged by the receiver-CIP with a 87 response code. See section 2.3.1 for the format of these codes, a list 88 of the responses a CIP server may generate, and the expected sender-CIP 89 action for each. 91 In order to maintain backwards compatibility with existing Whois++ 92 servers, CIPv3 sender-CIPs must first verify that the newer protocol is 93 supported. They do this by sending the following illegal Whois++ system 94 command: "# CIP-Version: 3". On existing Whois++ servers 95 implementing version 1 and 2 of CIP, this results in a 500-series 96 response code, and the server terminates the connection. If the server 97 implements CIPv3, it must instead respond with response code 300. Future 98 versions of CIP can be correctly negotiated using this technique with a 99 different string (i.e. "CIP-Version: 4"). An example of this short 100 interchange is given below. 102 Note: If a sender-CIP can safely assume that the server implements 103 CIPv3, it may choose to send the "# CIP-Version: 3" string and 104 immediately follow it with the CIPv3 request. This optimization, useful 105 only in known homogeneous CIPv3 meshes, avoids waiting for the round- 106 trip inherent in the negotiation. 108 Once a sender-CIP has successfully verified that the server supports 109 CIPv3 requests, it can send the request, formatted as a MIME message 110 with Mime-Version and Content-Type headers (only), using the network 111 standard line ending: "". A more precise specification is as 112 follows: 114 Cip-Req = Req-Hdrs CRLF Req-Body 115 Req-Hdrs = *( Version-Hdr | Req-Cntnt-Hdr ) 116 Req-Body = Body { format of request body as in [CIP-MIME] } 117 Body = Data CRLF "." CRLF 118 Data = { data with CRLF "." CRLF replaced by CRLF ".." CRLF } 119 Version-Hdr = "Mime-Version:" "1.0" CRLF 120 Req-Cntnt-Hdr = "Content-Type:" Req-Content CRLF 121 Req-Content = { format is specified in [CIP-MIME] } 123 Cip-Rsp = Rsp-Code CRLF [ Rsp-Hdrs CRLF Rsp-Body ] 124 [ Indx-Cntnt-Hdr CRLF Index-Body ] 125 Rsp-Code = DIGIT DIGIT DIGIT Comment 126 Comment = { any chars except CR and LF } 127 Rsp-Hdrs = *( Version-Hdr | Rsp-Cntnt-Hdr ) 128 Rsp-Cntnt-Hdr = "Content-Type:" Rsp-Content CRLF 129 Req-Content = { format is specified in [CIP-MIME] } 130 Rsp-Body = Body { format of response body as in [CIP-MIME] } 132 Indx-Cntnt-Hdr = "Content-Type:" Indx-Obj-Type CRLF 133 Indx-Obj-Type = { any registered index object's MIME-type } 134 Index-Body = Body 136 The message is terminated using SMTP-style message termination. The data 137 is sent octet-for-octet, except when the pattern "." is 138 seen, in which case the period is repeated, resulting in the following 139 pattern: "..". When the data is finished, the octet 140 pattern "." is transmitted to the receiver-CIP. On the 141 receiver-CIP's side, the reverse transformation is applied, and the 142 message read consists of all bytes up to, but not including, the 143 terminating pattern. 145 In response to the request, the receiver-CIP sends a response code, from 146 either the 200, 400, or 500 series. The receiver-CIP then processes the 147 request and replies, if necessary, with a MIME message. This reply is 148 also delimited by an SMTP-style message terminator. 150 After responding with a response code, the receiver-CIP must prepare to 151 read another request message, resetting state to the point when the 152 sender-CIP has just verified the CIP version. If the sender-CIP is 153 finished making requests, it may close the connection. In response the 154 receiver-CIP must abort reading the message and prepare for a new sender- 155 CIP connection (resetting it's state completely). 157 An example is given below. In this (and all further examples) octets 158 sent by the sender-CIP are preceded by ">>> " and those sent by the 159 receiver-CIP by "<<< ". Line endings are explicitly shown in angle- 160 brackets; newlines in this text are added only for readability. Comments 161 occur in curly-brackets. 163 { sender-CIP connects to receiver-CIP } 164 <<< % 220 Example CIP server ready 165 >>> # CIP-Version: 3 166 <<< % 300 CIPv3 OK! 167 >>> Mime-Version: 1.0 168 >>> Content-type: application/cip-request; request="noop" 169 >>> 170 { 171 This example uses the "noop" request. Receiver-CIPs must simply 172 ignore this request. The actual text in the following request is: 173 "This next line is only a dot..". 174 } 175 >>> The next line is only a dot: 176 >>> .. 177 >>> 178 >>> . 179 <<< % 200 Good MIME message received 180 { sender-CIP shuts down socket for writing } 181 <<< % 222 Connection closing in response to sender-CIP shutdown 182 { receiver-CIP closes its side, resets, and awaits a new sender-CIP 183 } 185 An example of an unsuccessful version negotiation looks like this: 187 { sender-CIP connects to receiver-CIP } 188 <<< % 220 Whois++ server ready 189 >>> # CIP-Version: 3 190 <<< % 500 Syntax error 191 { server closes connection } 193 The sender-CIP may attempt to retry using version 1 or 2 protocol. 194 Sender-CIP may cache results of this unsuccessful negotiation to avoid 195 later attempts. 197 1.3.1 Transport specific response codes 198 The following response codes are used with the stream transport: 200 Code Suggested description Sender-CIP action 201 text 202 220 Initial server banner Continue with Whois++ interaction, or 203 message attempt CIP version negotiation. 204 300 Requested CIP version Continue with CIP transaction, in the 205 accepted specified version. 206 222 Connection closing (in Done with transaction. 207 response to sender-CIP 208 close) 209 200 MIME request received Expect no output, continue session (or 210 and processed close) 211 201 MIME request received Read a response, delimited by SMTP- 212 and processed, output style message delimiter. 213 follows 214 400 Temporarily unable to Retry at a later time. May be used to 215 process request indicate that the server does not 216 currently have the resources available 217 to accept an index. 218 500 Bad MIME message format Retry with correctly formatted MIME 220 1.4 Internet mail infrastructure as transport 222 As an alternative to TCP streams, CIP transactions can take place over 223 the existing Internet mail infrastructure. There are two motivations for 224 this feature of CIP. First, it lowers the barriers to entry for leaf 225 servers. When the need for a full TCP implementation is relaxed, leaf 226 nodes (which, by definition, only send index objects) can consist of as 227 little as a database and a indexing program (possibly written in a very 228 high level language) to participate in the mesh. 230 Second, it keeps with the philosophy of making use of existing Internet 231 technology. The MIME messages used for requests and responses are, by 232 definition of the MIME specification, suitable for transport via the 233 Internet mail infrastructure. With a few simple rules, we open up an 234 entirely different way to interact with CIP servers which choose to 235 implement this transport. See Protocol Conformance, below, for details 236 on what options server implementers have about supporting the various 237 transports. 239 The basic rhythm of request/response is maintained when using the mail 240 transport. The following sections clarify some special cases which need 241 to be considered for mail transport of CIP objects. In general, all mail 242 protocols and mail format specifications (especially MIME Security 243 Multiparts) can be used with the CIP mail transport. 245 [ Note to reviewers: What about version negotiation for mail transport? 246 Should we add a CIP-Version header? ] 248 1.4.1 Return path 250 When CIP transactions take place over a bidirectional stream, the return 251 path for errors and results is implicit. Using mail as a transport 252 introduces difficulties to the recipient, because it's not always clear 253 from the headers exactly where the reply should go, though in practice 254 there are some heuristics used by MUA's. 256 CIP solves this problem by fiat. CIP requests sent using the mail 257 transport must include a Reply-To header as specified by RFC-822. Any 258 mail received for processing by a CIP server implementing the mail 259 transport without a Reply-To header must be ignored, and a message 260 should be logged for the local administrator. The receiver must not 261 attempt to reply with an error to any address derived from the incoming 262 mail. 264 If under no circumstances is a response to be sent to a CIP request, the 265 sender should include a Reply-To header with the address "<>" in it. 266 Receivers must never attempt to send replies to that address, as it is 267 defined to be invalid (both here, and by the BNF grammar in RFC-822). 268 It should be noted that, in general, it is a bad idea to turn off error 269 reporting in this way. However, in the simplest case of an index pushing 270 program, this may be a desirable simplification. 272 1.5 HTTP transport 274 HTTP may also be used to transport CIP objects, since they are just MIME 275 objects. A transaction is performed by using the POST method to send an 276 application/cip-request and returning an application/cip-response or an 277 application/cip-index-object in the HTTP reply. The URL that is the 278 target of the post is a configuration parameter of the CIP-sender to CIP- 279 receiver relationship. Security is handled by using HTTP Basic 280 Authentication [RFC 2068] or HTTP Message Digest Authentication [RFC 281 2069], or SSL/TLS. 283 Example: 285 { the client opens the connection and sends a POST } 286 >>> POST / HTTP/1.1 287 >>> Host: cip.some.corp 288 >>> Content-type: application/cip-request; request="noop" 289 >>> Date: Thu, 6 Jun 1997 18:16:03 GMT 290 >>> Content-Length: 43 291 >>> Connection: close 292 >>> 293 >>> This is some text that will be ignored. 294 { the server processes the request } 295 <<< HTTP/1.1 204 No Content 296 { the server closes the connection } 298 In addition to leveraging the security capabilities that come with HTTP, 299 there are other HTTP features that may be useful in a CIP context. A CIP 300 client may use the Accept-Charset and Accept-Language HTTP headers to 301 express a desire to retrieve an index in a particular character set or 302 natural language. It may use the Accept-Encoding header to (e.g.) 303 indicate that it can handle compressed responses, which the CIP server 304 may send in conjunction with the Transfer-Encoding header. It may use 305 the If-Modified-Since header to prevent wasted transmission of an index 306 that has not changed since the last poll. A CIP server can use the Retry- 307 After header to request that the client retry later when the server is 308 less busy. 310 2. References 311 [RFC 2068] Fielding, et.al., "Hypertext Transfer Protocol -- HTTP/1.1", 312 January, 1997 313 [RFC 2069] Franks, et. al., "An Extension to HTTP: Digest Access 314 Authentication", January, 1997 315 [CIP-ARCH] Allen, J., Mealling, M, "The Common Indexing Protocol", work 316 in progress 317 [CIP-MIME] Allen, J., Mealling, M., "MIME Object Definitions for the 318 Common Indexing Protocol", work in progress 320 3. Authors' Addresses 322 Jeff R. Allen Paul J. Leach 323 246 Hawthorne St. Microsoft 324 Palo Alto, CA 94301 1 Microsoft Way 325 USA Redmond, WA 98052 326 EMail: jeff.allen@acm.org Email: paulle@microsoft.com