RFC 2653
CIP Transport Protocols
CIP Transport Protocols 🎀
Okay bestie, this is Part 1 of 3 of RFC 2653 💖
The title block is giving old-school standards energy ✨. It's RFC 2653, titled "CIP Transport Protocols", published in August 1999 🦋. It's on the Standards Track and it came out of the Network Working Group. The authors are J. Allen (WebTV Networks, Inc.), P. Leach (Microsoft), and R. Hedberg (Catalogix) 👑. There's no Obsoletes or Updates line in the header, so it isn't replacing or changing any other RFC 🙈.
Status of this Memo
Okay so this is an Internet standards track protocol for the Internet community 💅. It's basically asking everyone to talk about it and suggest improvements 🫶. For the standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1) 📚. And the distribution of this memo is unlimited 🌈.
Copyright Notice
Copyright (C) The Internet Society (1999). All Rights Reserved. 💜
Abstract
This doc lays out three protocols for moving CIP requests, responses, and index objects around 🧚. Those protocols use TCP, mail, and HTTP 📬. The objects themselves are defined in [CIP-MIME], and the overall CIP architecture is defined in [CIP-ARCH] ✨.
1. Protocol ✨
This section is where the actual protocol for sending CIP index objects and keeping the mesh healthy gets introduced 🕸️. The companion documents, [CIP-ARCH] and [CIP-MIME], explain the concepts and the formats of the CIP MIME objects 🍓. But this document is the authoritative definition of the message formats and transfer mechanisms that CIP uses over TCP, HTTP, and mail 💖. So if you're implementing, this is your source of truth, bestie 🫶.
1.1. Philosophy
The whole CIP design is about building blocks 🧸. Instead of leaning on bulky protocol definition tools or ad-hoc text encodings, CIP borrows from technologies the Internet already understands well 💅. That means MIME, RFC-822, Whois++, FTP, and SMTP 📮. Hopefully this makes it easier to implement and easier for people to agree on it 🌸. It's also meant to be a clean example of how you can use existing Internet tech to build brand-new application-level services without starting from scratch 👑.
1.2. Conventions
Here's the rule: the key words MUST and MAY in this document are to be read as described in "Key words for use in RFCs to Indicate Requirement Levels" [KEYWORDS] 🔥.
Formal syntax is written in ABNF [ABNF] 📝.
In the examples, octets sent by the sender-CIP start with >>> and octets sent by the receiver-CIP start with <<< 👀.
2. MIME message exchange mechanisms
Okay, the big idea here: CIP depends on swapping standard MIME messages for every request and reply 💌. Those messages travel over a bidirectional, reliable transport system ✨. This document defines transport over reliable network streams (via TCP), over HTTP, and through the Internet mail infrastructure 🦋.
The CIP server that starts the connection (usually just called a client) is what this doc calls the sender-CIP 🚀. The CIP server that accepts the sender-CIP's incoming connection and responds to its requests is the receiver-CIP 🫧. So basically: one side asks, the other side answers, and everybody keeps it iconic 💅✨.
2.1. The Stream Transport ✨
okay so CIP messages travel over bi-directional TCP connections using a super simple text protocol 🦋 The transaction can happen on any TCP port, as long as the mesh configuration says so. There is no "well known port" for CIP, so every config entry has to include both a hostname and a port. 💅
Every sender-CIP action gets a reply from the receiver-CIP in the form of a response code. That covers requests, connection initiation, and connection finalization. The format of these codes, the full list of responses a CIP server can send, and what the sender-CIP should do next for each one are all in section 2.1.1 🎀
Now here's the part I'm obsessed with 😭 CIPv3 sender-CIPs MUST first check that the newer protocol is supported before doing anything else, because existing Whois++ servers need to keep working. They do this by sending the illegal Whois++ system command # CIP-Version: 3<cr><lf>. On existing servers that implement version 1 and 2 of CIP, that gets a 500-series response code and the server closes the connection. If the server implements CIPv3, it MUST instead respond with response code 300. Future versions can be negotiated the same way with a different string, like CIP-Version: 4. There's an example of this quick back-and-forth further down 🧚
Note: if a sender-CIP can safely assume the server is CIPv3, it may send the # CIP-Version: 3 string and immediately follow it with the CIPv3 request. This shortcut is only useful in known homogeneous CIPv3 meshes, because it skips the roundtrip that negotiation normally takes. 🔥
Once a sender-CIP has confirmed that the server supports CIPv3 requests, it can send the request. The request is formatted as a MIME message with only Mime-Version and Content-Type headers, and every line ends with the network standard line ending, <cr><lf>. 🌸
The grammar looks like this:
Cip-Req = Req-Hdrs CRLF Req-Body
Req-Hdrs = *( Version-Hdr | Req-Cntnt-Hdr )
Req-Body = Body ; format of request body as in [CIP-MIME]
Body = Data CRLF "." CRLF
Data = ; data with CRLF "." CRLF replaced by
; CRLF ".." CRLF
Version-Hdr = "Mime-Version:" "1.0" CRLF
Req-Cntnt-Hdr = "Content-Type:" Req-Content CRLF
Req-Content = ; format is specified in [CIP-MIME]
Cip-Rsp = Rsp-Code CRLF [ Rsp-Hdrs CRLF Rsp-Body ]
[ Indx-Cntnt-Hdr CRLF Index-Body ]
Rsp-Code = DIGIT DIGIT DIGIT Comment
Comment = ; any chars except CR and LF
Rsp-Hdrs = *( Version-Hdr | Rsp-Cntnt-Hdr )
Rsp-Cntnt-Hdr = "Content-Type:" Rsp-Content CRLF
Rsp-Content = ; format is specified in [CIP-MIME]
Rsp-Body = Body ; format of response body as in [CIP-MIME]
Indx-Cntnt-Hdr = "Content-Type:" Indx-Obj-Type CRLF
Indx-Obj-Type = ; any registered index object's MIME-type
; the format is specified in [RFC2045]
Index-Body = Body ; format defined in each index
; specifications
CRLF = CR LF ; Internet standard newline
CR = %x0D ; carriage return
LF = %x0A ; linefeed
DIGIT = %x30-39Messages end with SMTP-style message termination 💖 The data is sent octet-for-octet, except when the pattern <cr><lf>1*["."]<cr><lf> shows up. In that case, one more period gets added. When the data is done, the octet pattern <cr><lf>.<cr><lf> is sent to the receiver-CIP.
The receiver-CIP does the reverse transformation. The message it reads is everything up to, but not including, that terminating pattern. 🫶
After getting a request, the receiver-CIP replies with a response code from the 200, 400, or 500 series. Then it processes the request and, if needed, sends back a MIME message. That reply is also wrapped in an SMTP-style terminator. 💅
Once the receiver-CIP has sent a response code, it MUST get ready to read another request, going back to the state right after the sender-CIP verified the CIP version. If the sender-CIP is done making requests, it can close the connection. When that happens, the receiver-CIP MUST stop reading the message and get ready for a brand new sender-CIP connection, which means resetting its state completely. 😭
Here's an example. The command format is defined in [CIP-MIME], and the message body is defined in each index object definition. This example uses the index object definition in [CIP-TIO]. Line endings are shown in angle brackets, and the newlines are only there so it's easier to read. Comments are in curly brackets. 🧚
{ sender-CIP connects to receiver-CIP }
<<< % 220 Example CIP server ready<cr><lf>
>>> # CIP-Version: 3<cr><lf>
<<< % 300 CIPv3 OK!<cr><lf>
>>> Mime-Version: 1.0<cr><lf>
>>> Content-type: application/index.cmd.datachanged; type=
>>> x-tagged-index-1; dsi=1.2.752.17.5.10<cr><lf>
>>> <cr><lf>
>>> updatetype: incremental tagbased<cr><lf>
>>> thisupdate: 855938804<cr><lf>
>>> lastupdate: 855940000<cr><lf>
>>> .<cr><lf>
<<< % 200 Good MIME message received
>>> MIME-Version: 1.0<cr><lf>
>>> Content-Type: application/index.obj.tagged;
>>> dsi=1.2.752.17.5.10;
>>> base-uri="ldap://ldap.umu.se/dc=umu,dc=se"<cr><lf>
>>> <cr><lf>
>>> version: x-tagged-index-1<cr><lf>
>>> updatetype: incremental<cr><lf>
>>> lastupdate: 855940000<cr><lf>
>>> thisupdate: 855938804<cr><lf>
>>> BEGIN IO-schema<cr><lf>
>>> cn: TOKEN<cr><lf>
>>> sn: FULL<cr><lf>
>>> title: FULL<cr><lf>
>>> END IO-Schema<cr><lf>
>>> BEGIN Update Block<cr><lf>
>>> BEGIN Old<cr><lf>
>>> title: 3/testpilot<cr><lf>
>>> END Old<cr><lf>
>>> BEGIN New<cr><lf>
>>> title: 3/chiefpilot<cr><lf>
>>> END New<cr><lf>
>>> END Update Block<cr><lf>
>>> .<cr><lf>
<<< % 200 Good MIME message received
{ Sender-CIP shuts down socket for writing }
<<< % 222 Connection closing in response to sender-CIP shutdown
{ receiver-CIP closes its side, resets, and awaits a
new sender-CIP }Here's what a failed version negotiation looks like 💀
{ sender-CIP connects to receiver-CIP }
<<< % 220 Whois++ server ready<cr><lf>
>>> # CIP-Version: 3<cr><lf>
<<< % 500 Syntax error<cr><lf>
{ server closes connection }If that happens, the sender-CIP may retry using the version 1 or 2 protocol. It may also cache the result of the failed negotiation so it doesn't keep trying later. 🌈
2.1.1. Transport specific response codes 🍓
These are the response codes used with the stream transport:
Code Suggested description Sender-CIP action
text
200 MIME request received Expect no output, continue session
and processed (or close)
201 MIME request received Read a response, delimited by SMTP-
and processed, output style message delimiter.
follows
220 Initial server banner Continue with Whois++ interaction,
message or attempt CIP version negotiation.
222 Connection closing (in Done with transaction.
response to sender-CIP
close)
300 Requested CIP version Continue with CIP transaction, in
accepted the specified version.
400 Temporarily unable to Retry at a later time. May be used
process request to indicate that the server does not
currently have the resources
available to accept an index.
500 Bad MIME message format Retry with correctly formatted MIME
501 Unknown or missing Retry with correct CIP command
request in
application/index.cmd
502 Request is missing Retry with correct CIP attributes.
required CIP attributes
520 Aborting connection for Alert local administrator.
some unexpected reason
530 Request requires valid Sign the request, if possible, and
signature retry. Otherwise, report problem to
the administrator.
531 Request has invalid Report problem to the administrator.
signature
532 Cannot check signature Alert local administrator, who should
cooperate with remote administrator
tp diagnose and resolve the problem.
(Probably missing a public key.)2.2. Internet mail infrastructure as transport ✨
okay so instead of TCP streams, CIP transactions can also run over the existing Internet mail infrastructure 📬 there are two reasons this is a big deal. first, it lowers the barrier for leaf servers 🦋 if you don't need a full TCP implementation, a leaf node (which by definition only sends index objects) can be just a database plus an indexing program, maybe written in a super high level language. so cute, so easy to join the mesh 🧚
second, it's giving "use stuff that already exists" 💅 the MIME messages used for requests and responses are, by the definition of the MIME spec, fine to send through the mail system. with a few simple rules we unlock a whole new way to talk to CIP servers that choose to support this transport 🌸 check out Protocol Conformance below for the details on what options server implementers have for the different transports.
the basic request/response rhythm stays the same over mail 🎀 the next sections cover the special cases you need to think about for mail transport of CIP objects. generally speaking, all mail protocols and mail format specs (especially MIME Security Multiparts) can be used with the CIP mail transport 💜
2.2.1. CIP-Version negotiation
okay this one is key 🔑 the MIME message doesn't say which CIP version is in use, so that info has to live in the mail header instead. so CIP requests sent over the mail transport MUST include a CIP-version headerline, registered according to [MHREG]. the format looks like this:
DIGIT = %x30-39
number = 1*DIGIT
cipversion = "CIP-Version:" <sp> number["." number]2.2.2. Return path
over a bidirectional stream, the return path for errors and results is just implicit 🌈 mail is messier, though. the recipient often can't tell from the headers exactly where the reply should go 😭 in practice MUAs use some heuristics, but it's not guaranteed.
CIP just solves this by fiat 👑 CIP requests sent over the mail transport MUST include a Reply-To header as specified by RFC-822. any mail a CIP server running the mail transport gets for processing without a Reply-To header MUST be ignored, and a message should be logged for the local admin. and the receiver MUST not attempt to reply with an error to any address derived from the incoming mail 🙅♀️
if there's no situation where a response should be sent back to a CIP request, the sender should include a Reply-To header with the address "<>" in it. receivers MUST never attempt to send replies to that address, since it's defined to be invalid (both here and by the BNF grammar in RFC-822) 💀
it should be noted that turning off error reporting like this is generally a bad idea 🙈 BUT for the simplest case, an index pushing program, it MAY be a desirable simplification ✨
2.3. HTTP transport
HTTP MAY also be used to transport CIP objects 🍓 since they're just MIME objects, it's giving perfect fit 💖 a transaction happens by using the POST method to send an application/index.cmd, and then you get back an application/index.response or an application/index.obj in the HTTP reply. the URL that gets targeted by the post is a configuration parameter of the CIP-sender to CIP-receiver relationship.
example time 🎀
{ the client opens the connection and sends a POST }
>>> POST / HTTP/1.1<cr><lf>
>>> Host: cip.some.corp<cr><lf>
>>> Content-type: application/index.cmd.noop<cr><lf>
>>> Date: Thu, 6 Jun 1997 18:16:03 GMT<cr><lf>
>>> Content-Length: 2<cr><lf>
>>> Connection: close<cr><lf>
>>> <cr><lf>
{ the server processes the request }
<<< HTTP/1.1 204 No Content<cr><lf>
{ the server closes the connection }on top of the security stuff HTTP already brings 🔐 there are other HTTP features that MAY be useful in a CIP context too 🫶 a CIP client MAY use the Accept-Charset and Accept-Language HTTP headers to say it wants an index in a particular character set or natural language 🌍 it MAY use the Accept-Encoding header to (for example) say it can handle compressed responses, which the CIP server MAY send along with the Transfer-Encoding header 🗜️ it MAY use the If-Modified-Since header to avoid wasting transmission on an index that hasn't changed since the last poll 🙌 and a CIP server can use the Retry-After header to tell the client to come back later when it's less busy 😴
3. Security Considerations 🔒
okay this section is SERIOUS 😤 the index info can be protected at two levels. the first is the tech available for securing MIME [MIME-SEC] objects, and the second is the tech available for securing the transport itself.
for transport, the stream transport can be protected with TLS [TLS] . for HTTP, security is handled with HTTP Basic Authentication [RFC 2616], HTTP Message Digest Authentication [RFC2617], or SSL/TLS. extra protection for the SMTP exchange can be achieved with Secure SMTP over TLS [SMTPTLS] 💅🔥
4. References 📚
[RFC 2045] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part One: Format of Internet Message
Bodies", RFC 2045, November 1996.
[RFC 2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC 2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
Leach, P., Luotonen, A. and L. Stewart, "HTTP
Authentication: Basic and Digest Access Authentication",
RFC 2617, June 1999.
[CIP-ARCH] Allen, J. and M. Mealling, "The Architecture of the Common
Indexing Protocol (CIP)", RFC 2651, August 1999.
[CIP-MIME] Allen, J. and M. Mealling, "MIME Object Definitions for
the Common Indexing Protocol (CIP)", RFC 2652, August
1999.
[ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997.
[CIP-TIO] Hedberg, R., Greenblatt, B., Moats, R. and M. Wahl, "A
Tagged Index Object for use in the Common Indexing
Protocol", RFC 2654, August 1999.
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[MIME-SEC] Galvin, J., Murphy, S., Crocker, S. and N. Freed,
"Security Multiparts for MIME: Multipart/Signed and
Multipart/Encrypted", RFC 1847, October 1995.
[TLS] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
RFC 2246, January 1999.
[SMTPTLS] Hoffman, P., "SMTP Service Extension for Secure SMTP over
TLS", RFC 2487, January 1999.
[MHREG] Jacob, P., "Mail and Netnews Header Registration
Procedure", Work in Progress.5. Authors' Addresses 🧑💻
Jeff R. Allen
246 Hawthorne St.
Palo Alto, CA 94301
EMail: jeff.allen@acm.org
Paul J. Leach
Microsoft
1 Microsoft Way
Redmond, WA 98052
EMail: paulle@microsoft.com
Roland Hedberg
Catalogix
Dalsveien 53
0775 Oslo
Norway
EMail: roland@catalogix.ac.se6. Full Copyright Statement ⚖️
this legal bit has to stay exactly as written, so no glow-up here 🙏
Copyright (C) The Internet Society (1999). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.Acknowledgement 🌷
funding for the RFC Editor function is currently provided by the Internet Society 💜
📦 where this page comes from
- ietf: rfc2653 1999-08
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms