INTERNET-DRAFT Greg Hudson Expires: November 3, 2000 ghudson@mit.edu MIT Instant Message and Presence Transfer Protocols draft-hudson-impp-transfer-proposal-01.txt 1. Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. 2. Abstract This document specifies transfer protocols for instant messages and presence information. The Presence Information Transfer Protocol (PITP) allows clients to set presence information for presentities they control and to request presence information from other presentities. The Instant Message Transfer Protocol (IMTP) allows clients to send and receive instant messages. Both protocols can also be used to relay instant message and presence requests between servers as necessary. These protocols are specified in the same document because they have very similar structure. However, they are two logically separate protocols. Sections specific to one or the other protocol will be recognizeable by a leading "PITP" or "IMTP". 3. Terminology PITP stands for "Presence Information Transfer Protocol," one of the protocols specified in this document. IMTP stands for "Instant Message Transfer Protocol," the other protocol specified in this document. PI stands for "Presence Information." The data format for presence information is specified in [PIDF]. IM stands for "Instant Message." Instant messages are opaque payloads tagged by a MIME [RFC 2045-2049] content type. The terms "presentity", "watcher", "sender", and "instant inbox" are defined in section 4. The terms "operation", "originator", "target", "relay" and "gateway" are defined in section 8. The term "watcher class" is defined in section 5. The term "principal" is used vaguely to refer to an entity (which is usually a person, but might be an organization or program in some cases) interacting with the presence or instant message system. IMTP and PITP make no assumptions about the nature of principals. The terms MUST, SHOULD, and MAY are used in uppercase with the meaning defined in [RFC 2119]. 4. Identifiers and domain architecture The abstract entities who have PI are called "presentities." The entities who fetch or subscribe to PI are called "watchers." Presentities and watchers both have identifiers within the "presence" URL scheme. A watcher with the same identifier as a presentity is assumed to be under the control of the same principal. A presence identifier has a local part and a domain part, as defined in section 9. The abstract entities who receive IMs are called "instant inboxes." The entities who send instant messages information are called "senders." Instant inboxes and senders both have identifiers within the "im" URL scheme. Just as with presence identifiers, a sender with the same identifier as an instant inbox is assumed to be under the control of the same principal, and an instant messaging identifier has a local part and a domain part, as defined in section 9. PITP and IMTP clients communicate only with the servers for the home domains of the identifiers they use. Servers relay requests to other servers as necessary. For example, if the watcher "presence:joe@example.net" wishes to fetch the presence information for the presentity "presence:harry@domain.com", it makes the request to a server serving its home domain, example.net. The example.net server will forward the request to a server for domain.com and forward back the response. A domain may be served by multiple servers. How the distribution of responsibility is carried out is beyond the scope of this protocol; however, IMTP and PITP can be used to relay operations between servers within a domain as well as between servers in different domains. Thus, PITP and IMTP can be used between the following pairs of parties: * A client and a server in its home domain * Two servers for the same domain * Two servers for different domains 5. (PITP) Presence store A presence server contains, at least abstractly, a store of dynamically changing PI. The view of the presence store from a watcher's perspective is very simple: each presentity has one piece of PI at any given time. The view of the presence store from a presentity's perspective is more complicated, since a principal may wish to reveal different presence information to different classes of watchers. >From a presentity's perspective, the presence store contains an enumerated list of mappings from watcher class to optional PI. Numbering of the mappings begins at 1. A watcher class is a set of identifier patterns, as defined in section 11.3. A watcher class matches any watcher which matches one or more of the patterns making up the class. When a watcher requests presence information, the server will provide it with the PI corresponding to the first matching watcher class in the list. If the matched watcher class has no PI, or if the watcher does not match any class in the list, the server will deny access to the presentity's PI. For example, at some particular time, the presentity "presence:joe@example.net" might have, on the example.net servers, the following PI mappings (where PI1..PI5 are placeholders for PI documents in the format specified in [PIDF]): (1) presence:fred@example.net -> PI1 (2) presence:harry@domain.com, presence:alice@domain.com -> (3) presence:*@example.net -> PI2 (4) presence:* -> PI3 (5) * -> PI4 A watcher "presence:fred@example.com" would receive PI1; a watcher "presence:harry@domain.com" would be denied a subscription or fetch. If example.net's servers run a local gateway (see section 8) to a different presence service, a watcher from that namespace would receive PI4. Note that it is easy to construct PI lists where specific watcher classes are shadowed by more general classes; for instance, if the list is: (1) presence:*@example.net -> PI1 (2) presence:fred@example.net -> PI2 then fred@example.net receives PI1 even though there is a more specific entry mapping to PI2. A user agent SHOULD detect and prevent or warn about cases such as this, but a server MUST NOT disallow them. 6. Making a connection As mentioned in section 4, a PITP or IMTP connection may be used in three different scenarios: a client may be connecting to a server in its home domain, a server may be relaying with another server in its own domain, or a server may be relaying with a server in a foreign domain. 6.1. Client-server connections A client MAY support site-specific means of server discovery, but it SHOULD support the following standard discovery algorithm: the client performs a SRV [RFC 2782] lookup for its home domain using the protocol "tcp" and the service "presence-clients" (for PITP) or "im-clients" (for IMTP). If no SRV record is present, the client performs an A look up on the domain and uses the resulting IP addresses with the allocated port XXX (for PITP) or XXX (for IMTP). 6.2. Server-server connections within a single domain If a domain has multiple servers, it may be necessary to relay presence operations between those servers. How a server chooses another server to connect to within the same domain is not within the scope of this specification. 6.3. Server-server connections between domains A server MUST discover a foreign domain's server using the following algorithm: the server performs a SRV lookup for the foreign domain using the protocol "tcp" and the service "presence-servers" (for PITP) or "im-servers" (for IMTP). If no SRV record is present, the server performs an A lookup on the foreign domain and uses the resulting IP addresses with the allocated port XXX (for PITP) or XXX (for IMTP). 6.4. Initial data from server After accepting a connection, a server volunteers a list of SASL [RFC 2222] authentication mechanisms it supports using the "mech" syntax defined in section 10. Implementators should note that this mechanism list is not integrity-protected. The measures documented in [RFC 2222] section 9 will help to prevent an attacker from forcing a negotiation of a weak mechanism; also, because the mechanism list is retransmitted after the negotiation of a security layer (see section 14.1), servers and clients can help reduce the risk of such an attack by only supporting mechanisms which negotiate an integrity-protecting security layer. XXX NOTE: it is my hope to define a SASL or GSSAPI mechanism for authentication between two administrative domains using public keys in the DNS, and require this mechanism to be implemented by all servers (although the mechanism would fall back to authentication-by-assertion in the event that either party has no public key in the DNS, so this would not force all server implementations to include crypto support). This mechanism would provide good authentication strength in the presence of DNSSEC deployment and some authentication strength (since DNS spoofing attacks are not currently trivial) in the absence of DNSSEC deployment. 7. Connections and data flow PITP and IMTP data consists of mechanism lists, nops, commands, responses; the syntax of these protocol messages is defined in section 10. Each command corresponds to a single response. Responses to commands do not necessarily arrive in order. PITP and IMTP are bidirectional asynchronous protocols; once a connection is established, commands and responses may flow in either direction, and either side may send multiple commands without waiting for a response. Because these are not lock-step protocols, deadlock is possible if both sides of a connection attempt to write too much data without reading pending data. A server MUST prevent such deadlocks by reading data as it comes in, even if it has data to write. For a Unix sockets implementation, this means the server must perform writes in non-blocking mode, or use select() or poll() to detect the writeability of a socket before writing data, or use separate threads for reading and for writing on each connection. A client MAY perform blocking writes, since the server will prevent deadlocks. The lifetime of a connection varies according to what type of connection it is. For a client-server connection, a connection lasts as long as the client wants to be able to receive data from the server, or has data to send to the server. For instance, an IMTP client listening on an instant inbox will hold its connection open as long as it wants to be able to receive messages send to that inbox. For a server-server connection between two different domains, connections may be closed by either side at any time when there are no outstanding commands on the connection from that server's point of view. Any commands sent to a server which closed the connection before sending a reply can safely be assumed to have gone unprocessed. For a server-server connection within a domain, the lifetime of the connection is implementation-defined. The connection might be permanent, or it might end after a single transaction, or it might use a mechanism similar to the one for inter-domain connections. 8. Relays and gateways In this specification, an "operation" refers to the process of communicating a request from an originator to a target, possibly through one or more relays or gateways, and communicating back a reply. The mechanism through which an operation occurs is a series of protocol messages; for instance, if im:joe@example.net wishes to send an IM to im:tara@domain.com, the sequence of protocol operations might be: Joe's client -> example.net: send example.net -> domain.com: send domain.com -> Tara's client: send Tara's client -> domain.com: ok (send) domain.com -> example.net ok (send) example.net -> Joe's client: ok (send) (where "example.net" is an abbreviation for "a server for the domain example.net" and likewise for "domain.com"). Of course, the originator only sees itself sending the command and eventually receiving the response, and the target only sees itself receiving the command and sending the response. A server is said to be acting as a relay when it receives a command or response and continues the operation by forwarding the request or reply to another PITP or IMTP entity. A server is said to be acting as a gateway when it receives a command or responds and continues the operation by forwarding it to another entity using a different protocol. If a relay receives a command or response with a header it does not recognize, it MUST include the unmodified header in the command or response it sends to the next hop. Under appropriate circumstances, a relay MAY reject a command with an appropriate error response and decline to forward it. A relay MUST forward the command if it does not respond with an error. If a relay forwards a command, it MUST NOT respond to the command before it receives a response from the next hop. A gateway can operate in one of two different ways. A "local gateway" supports URL schemes other than "presence" (for PITP) or "im" (for IMTP), thus allowing its clients to communicate with presence or IM services using other protocols. A "remote gateway" uses regular presence or im identifiers, but forwards operations using a protocol other than PITP or IMTP for some or all local parts. 8.1. Authorization to represent source identifiers Most PITP and IMTP commands include a source identifier (see section 12). To prevent forgery, the receiver of a command needs to decide if the sending connection is authorized to communicate the intentions of the specified source identifier. The principles PITP and IMTP apply to this authorization task are: * Within a domain, authorization is a site-specific issue. * Between domains, a server for domain X is authorized only to communicate the intentions of an identifier within domain X. * A client's view of the entire presence or IM service is through its server, so a client trusts its server to communicate the intentions of all identifiers. Following are specific rules to be applied by clients and servers to implement the above principles. If a client is sending a command to a server, the server SHOULD reject the command with an error type of "source-authorization" if the domain part of the source identifier is not a domain served by the server. Beyond that, it is a site-specific decision whether to allow a given client connection to act on behalf of a given identifier based on the credentials the client has presented using the auth-sasl command. If a server S1 sends a command to another server S2 in the same domain, it is a site-specific decision whether to allow the command. If a server S1 sends a command to another server S2 in a different domain, the server S2 MUST reject the command with an error type of "source-authorization" if the domain part of the source identifier is not the same as the domain S1 authenticated as. The server S2 SHOULD NOT reject the command on the basis of the source address otherwise. If a server is sending a command to a client, the client SHOULD NOT reject the command on the basis of the source address regarldess of what the source address is. 9. Identifier syntax Following is an ABNF [RFC 2234] syntax for a presence or instant messaging URL. Note that presence and instant message identifiers use only US-ASCII characters. presence-id = word-presence ":" local-part "@" domain im-id = word-im ":" local-part "@" domain local-part = dotted-string / quoted-string domain = 1*domain-label *("." 1*domain-label) domain-label = (ALPHA / DIGIT) [*(ALPHA / DIGIT / "-") (ALPHA / DIGIT)] dotted-string = 1*atext *("." 1*atext) quoted-string = DQUOTE *qcontent DQUOTE qcontent = qtext / quoted-pair quoted-pair = "\" (%x1-9 / %xB-C / %xE-7E) qtext = %x1-8 / %xB-C / %xD-1F / %x20-21 / %x23-5B / %x5D-7E atext = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "/" / "=" / "?" /"^" / "_" / "`" / "{" / "|" / "}" / "~" / ALPHA / DIGIT / %x1-8 / %xB-C / %xD-1F / %x7F scheme = presence-scheme / im-scheme word-presence = %x70.72.65.73.65.6E.63.65 word-im = %x69.6D Following are some examples of valid presence and instant messaging identifiers: presence:joe@example.net im:"Jane Smith"@domain.com im:"a\""@example.com A user agent for PITP or IMTP SHOULD recognize a presence or instant messaging identifier without the scheme if it is entered in a presence or instant messaging context. Similarly, a user agent SHOULD display a presence or instant messaging identifier without the scheme if it is displayed in a presence or instant messaging context. The syntax for the local part of presence and im URLs is very similar to the syntax for email addresses in [RFC 822]. However, note that a CR or LF is never valid in a presence or im URL and that comments and group specifications are not allowed. Also note that, unlike a mailto URL [RFC 2368], a presence or imto URL cannot contain multiple addresses. 10. Protocol message syntax The underlying character set for protocol messages in PITP and IMTP is Unicode, represented in UTF-8 [RFC 2279]. Payloads are an exception; they should be treated as unprocessed octets. An implementation MUST properly handle arbitrary binary data in the payload. A protocol message is either a mechanism list, a NOP, a command, or a response. A mechanism list advertises supported SASL mechanisms and is sent by the receiver of a connection at two specific times (upon receiving a connection and upon completing a SASL authentication). A NOP has no effect and does not incur a reply. Commands and responses both begin with a start line, continue with a series of headers terminated by a blank line, and are possibly followed by a payload. The presence of a payload is signalled by a Content-Length header, which specifies (as an unsigned US-ASCII decimal integer) the number of octets in the payload. Headers may be "folded" across several lines by including leading whitespace on the continuation lines. Folding whitespace is part of the header value and is thus only valid where whitespace and CRLF is allowed in the particular header value; for instance, folding cannot occur within a presence or im URL. A payload MUST NOT be included unless the description of the particular method allows it. If a payload is included, the protocol message headers MAY include a Content-Type as specified in [RFC 2045]; if no Content-Type is provided, the default is "application/presence" for PITP commands, "text/plain; charset=UTF-8" for IMTP commands, and "application/octet-stream" for the auth command. The Content-Transfer-Encoding header from [RFC 2045] is not necessary in IMTP or PITP and MUST NOT be included in any command or response. An implementation which receives a Content-Transfer-Encoding header should reject the command with an Error-Type of "malformed". Following is an ABNF [RFC 2234] grammar for protocol messages: pmessage = mech / nop / command / response mech = "=" word-mech *(" " mechname) CRLF mechname = 1*20(ALPHA / DIGIT / "-" / "_") nop = "=" word-nop CRLF command = ">" id 1*WSP method content response = "<" id 1*WSP status *WSP "(" method ")" content content = CRLF *header CRLF [payload] header = header-name ":" [header-value] CRLF header-value = *([fws] printable) *WSP payload = *OCTET fws = [*WSP CRLF] 1*WSP id = 1*(ALPHA / DIGIT) method = 1*(ALPHA / DIGIT) status = word-ok / word-error header-name = 1*(%x21-39 / %x3B-7E) ; ASCII, no colons printable = %x21-7E / %x80-D7FF / %xE000-FFFD / %x10000-310FFFF word-ok = %x6F.6B word-error = %x6E.72.72.6F.72 word-nop = %x6E.6F.70 word-mech = %x6D.65.63.38 The id part of a response is used to match it up with the corresponding command, since responses to commands do not necessarily arrive in order. The simplest choice for ID strings is a counter ("1" for the first command, "2" for the second, etc.), but any combination of US-ASCII letters and digits is acceptable. Once an ID string has been used for a command, it MUST NOT be reused on that connection by the same requestor until the response to that command has been received. The syntaxes of particular headers are defined in section 11. A header value MUST match the header-value syntax defined above as well as the syntax of the specific header defined in section 11. If a client or server receives a protocol message with a header name it does not recognize, it MUST process the message as if the header were not present, with the exception that a server MUST forward the unknown header to the next hop if it is acting as a relay. A header name MUST NOT be repeated unless the description of a method in sections 14-16 allows it. If a client or server receives a message with a repeated header of a type which must not be repeated, it MUST process the message as if only the first value of the header is present, with the exception that a server acting as a relay MUST forward all of the header values if it is supposed to forward the header at all. The meanings of particular methods are defined in sections 14-16. If a client or server receives a protocol message with a method it does not recognize, it MUST reject the message with an error type of "unknown-method" (see section 12). Method names and headers are case-sensitive. Examples of protocol messages can be found in the definitions of the particular methods. 11. Header syntaxes This section describes the syntax and interpretation of the headers defined in this standard. The actual usage of headers is defined in the descriptions of particular methods in sections 14-16. 11.1. Headers containing URLs Several headers used in PITP and IMTP contain a single URL. The syntax for such a header is: url-hdr = [fws] url *WSP where the "url" syntactic element conforms to the URL syntax defined in [RFC 1738]. Normally, this URL will be a presence identifier for PIDF commands or an IM identifier for IMTP commands, but it may be a different type of URL if a local gateway is in use (see section 8). Headers which include URLs include: Protocol Header Methods using header -------- ------ -------------------- PITP Watcher fetch, fetch-notify PITP Presentity (most) IMTP Sender send IMTP Inbox listen, send IMTP Orig-Sender send IMTP Orig-Inbox send 11.2. Headers containing origination points The "Error-Originator" header, used in error responses, and the "Unreliable" header, used in successful "send" and "change-notify" responses, both contain points of origin for the error or unreliability indication. The syntax for this header is: origin-hdr = [fws] (domain / url) *WSP where the "domain" syntactic element is defined in section 9 and the "url" syntactic element conforms to the URL syntax defined in [RFC 1738]. The presence or absence of a colon easily disambiguates domains from URLs. A URL origin-hdr indicates origination from a client representing the given URL. A domain origin-hdr indicates origination from a server representing the given domain. 11.3. Headers containing identifier patterns Several headers in PITP and IMTP contain an identifier pattern. These headers have the following syntax: idpattern-hdr = [fws] ("*" / our-ptrn / generic-ptrn) *WSP our-ptrn = (word-presence / word-im) ":" ("*" / "*@" ["*."] domain-part / local-part "@" domain-part) generic-ptrn = scheme ":" ("*" / scheme-specific-part) where the "scheme" and "scheme-specific-part" syntactic elements conform to the syntax defined in [RFC 1738], and the "presence-scheme", "local-part", and "domain-part" syntactic elements are defined in section 9. An id-pattern header specifies a pattern matching a class of URLs. It can match the following kids of classes: * Any URL ("*") * Any URL with a particular scheme ("scheme:*") * Any presence or IM identifier with a particular domain ("presence:*@domain" or "im:*@domain") * Any presence or IM identifier in a subdomain of a particular domain ("presence:*@*.domain" or "im:*@*.domain") * A specific URL Headers which include identifier patterns include: Protocol Header Methods using header -------- ------ -------------------- PITP Wpattern get-class (response), insert-mapping, set-class IMTP Only listen IMTP Except listen 11.4. The "Astrength" header When a server acts as a relay, it MUST communicate to the next node a rough indication of the authentication strength of the previous hops using the "Astrength" header. The syntax for the Astrength header is: astrength-hdr = [fws] astrength *WSP astrength = %x73.74.72.6F.6E.67 ; "strong" / %x6D.65.64.69.75.6D ; "medium" / %x77.65.61.6B ; "weak" / %x6E.6F.6E.65 ; "none" The meanings of the astrength values are: strong Message authenticity and integrity cannot be compromised by an attacker who has full control of all network links, assuming no compromise of keying materials, installed software, or cryptographic algorithms. medium Message authenticity or integrity could be compromised by a packet substitution or DNS spoofing attack. weak Message could be forged by an attacker who has previously been a passive listener on one or more network links. none Message could be forged by an attacker with no special information. Examples of medium protection include one-time passwords [RFC 2289] and HTTP digest authentication [RFC 2617 section 3]. Examples of weak protection include cleartext passwords or security protocols subject to replay attacks. If a server or client receives a protocol message with no Astrength header, it should assume that the sender is the originator of the operation and thus the equivalent Astrength is "strong". A server relaying a message MUST communicate the weaker of the strength of the connection it received the message on and the Astrength value communicated from the last entity. A relay or gateway MAY choose to reject a command with a "source-authorization" error because it does not come with sufficient authentication strength (either as reported by the Astrength value or based on the connection from the immediate requestor). A relay MUST NOT reject a response on the basis of insufficient authentication strength. Note that, separately from connection-level authentication, an operation may be authenticated using an end-to-end signature. The Astrength header does not bear any relation to this kind of authentication. An example scenario: an IMTP client connects to a server for example.net and, without authenticating, issues a "send" command from alice@example.net to bob@domain.com. The example.net server connects to domain.com, authenticates using DNSSEC-signed public keys and forwards the IM with "Astrength: none" because the previous link was unauthenticated. The domain.com server sends the message to the clients receiving messages for bob@domain.com with "Astrength: none" since that was the authentication value claimed by example.net, even though domain.com received the message over a strongly authenticated link. Another example scenario: an IMTP client connects to a server for example.net and authenticates using some strong SASL mechanism as alice. It then issues a "send" command from alice@example.net to bob@domain.com. The example.net server connects to domain.com and authenticates, but example.net's public key DNS record is not signed, so it could have been forged by a DNS spoofing attack. The example.net server sends the IM with "Astrength: strong" because it received the message from Alice over a strongly authenticated link; however, the domain.com server will weaken the Astrength to "Medium" when forwarding the message to Bob's clients. 11.5. (PITP) The "Mapping" header The Mapping header is used in the following PITP methods: change delete-mapping fetch-for-update get-class insert-mapping set-class The Mapping header has the following syntax: mapping-hdr = [fws] positive-digit *DIGIT *WSP positive-digit = %x31-39 ; 1-9 The sequence of digits represents an positive number, which selects the PI mapping the operation applies to. 11.6. The "Mechanism" header The Mechanism header is used with the "auth" method. It has the following syntax: mechanism-hdr = [fws] mechname *WSP where the "mechname" syntactic element is defined in section 10. 11.7. (PITP) The "Subscription" header The Subscription header is used in the following PITP methods: change-notify start-wi (response) subscribe subscribe-notify terminate terminate-notify unsubscribe It has the following syntax: subscription-hdr= [fws] connection-id [fws] "/" [fws] url *WSP connection-id = *(ALPHA / DIGIT) where the "url" syntactic element conforms to the syntax defined in [RFC 1738]. The URL part of a Subscription header specifies the watcher who is making or who made the subscription. The connection ID part of a Subscription header is an opaque token stored with a subscription and is used by the watcher's server to distinguish between different client connections using the same watcher identifier. A client originating a subscribe operation MUST leave the connection-id blank; if it does not, the receiving server MUST reject the command with an Error-Type of "malformed". The receiving server SHOULD generate a token identifying the client connection and use it when forwarding the subscribe command or when providing watcher information to other clients. When the server forwards a change-notify or terminate-notify command to the watching client, it MUST use a blank connection-id. Similarly, a client originating an unsubscribe operation MUST leave the connection-id blank, or the server MUST reject the command with an Error-Type of "malformed". The receiving server MUST use the same connection-id as it generated for the subscription command when forwarding the unsubscription command or when providing watcher information to other clients. 11.8. (IMTP) The "Visited" header The Visited header is used with the IMTP "send" command. This header helps to prevent IM routing loops by giving a list of domains (server names or IM domains) an IM has passed through. It has the following syntax: visited-hdr = *([fws] domain) *WSP where the "domain" syntactic element is described in section 9. 12. Error responses Error responses MUST contain an Error-Type header specifying the type of error. Error types are case sensitive. Possible error types are defined later in this section and in sections 14-16 in the definitions of particular command methods. An error response MAY contain an Error-Description header giving a human-readable description of the error. A relay MUST include the values of the Error-Type and Error-Description (if present) unmodified, when passing on the error response. When a client or server originates an error response, it MUST NOT include an Error-Originator header. When a server relays an error response which does not include an Error-Originator header, it MUST add in the relayed response an Error-Originator header specifying which party generated the error, using the origin-hdr syntax. When a server relays an error response which does include an Error-Originator header, it MUST include the value of that header unmodified when passing on the response. The following Error-Type values may occur in response to any command: malformed The command is not properly formed. unknown-method The client or server does not recognize the specified method. resources A temporary resource failure occurred. communications A temporary communications failure occurred. Most commands include a header which indicates what URL the command is acting on the behalf of. The following Error-Type values may occur in response to any command which involves a source URL: source-authorization The requestor is not authorized to represent the intentions of the source URL. quota The command would result in unacceptable resource use on behalf of the source URL. Some commands include a header which indicates what URL the command is targeting, separate from the URL is acting on the behalf of. The following Error-Type values may occur in response to any command which involves a target URL. target-authorization The source URL is not authorized to perform the requested operation on the target URL. target-not-found The target URL does not exist. The following table clarifies which headers specify the source and target URLs for the methods defined in sections 14-16. If this table does not list a source header for a method, then "source-authorization" and "quota" are not valid responses; likewise, if this table does not list a target header for a method, then "target-authorization" is not a valid response. Method Source Header Target Header ------ ------------- ------------- change Presentity n/a change-notify Presentity n/a delete-mapping Presentity n/a fetch Watcher Presentity fetch-for-update Presentity n/a fetch-notify n/a n/a get-class Presentity n/a insert-mapping Presentity n/a set-class Presentity n/a start-wi Presentity n/a subscribe Subscription Presentity subscribe-notify n/a n/a terminate Presentity n/a terminate-notify n/a n/a unsubscribe Subscription n/a unsubscribe-notify n/a n/a listen Inbox n/a send Sender Inbox 13. Notation used in command examples The following three sections define the command methods used in PITP and IMTP. Most definitions include examples of exchanges between clients and servers or between two servers. A leading "C: " indicates text sent by a hypothetical client, and a leading "S: " indicates text sent by a server. Similarly, "S1: " and "S2: " indicate text sent by one or the other of two servers. All lines in examples are terminated by a CRLF pair. (Note that command payloads can consist of arbitrary octets; for clarity, all of the payloads in the examples consist of CRLF-terminated lines.) 14. Common command methods This section describes commands common to both protocols. 14.1. "auth" method This command begins or continues a SASL [RFC 2222] authentication exchange. It MUST only be sent by the party which initiated a TCP connection. This command MUST include the following header if it is beginning an authentication exchange, but MUST NOT include it if it is continuing an authentication exchange: Mechanism: A mechanism-hdr specifying the SASL mechanism to use If this command is continuing an authentication exchange, it MAY include the following header in order to abort the exchange: Abort: No value--header value MUST be left blank and MUST be ignored if present If this command is beginning an authentication exchange, it MAY include a payload containing the initial SASL response. If this command is continuing an authentication exchange and does not include the "Abort:" header, it MUST include a payload containing the response to the last challenge. All payloads used in the SASL authentication exchange MUST have the content type "application/octet-stream", which is the default for this command. An ok response to this method indicates that the authentication exchange is has completed successfully, or has been aborted if the command inclded the "Abort:" header. An ok response MAY include a payload containing SASL additional data. An error response to this method may indicate that the authentication has failed, or it may simply mean that another token exchange is required. There are two Error-Type values particular to this method: sasl-challenge More data is required for the exchange sasl-failure Authentication has failed An error reply with type sasl-challenge MUST include a payload containing the SASL challenge data. The initiator of an authentication exchange MUST NOT send any commands other than auth commands until the exchange is complete. If the authentication exchange negotiates a security layer, it takes effect beginning with the first octet of the protocol message following the transmission or reception of the ok response. Upon the successful completion of an authentication exchange, the receiver of the auth command MUST, before sending any other commands or responses, transmit a "mech" protocol message reiterating its list of supported mechanisms. This mechanism list MUST be identical to the one it advertised at the beginning of the connection. If the mechanism list does not match, the initiator of the authentication exchange SHOULD assume that an attacker has compromised the mechanism negotiation and close the connection. The GSSAPI service name for PITP is "PITP"; the GSSAPI service name for IMTP is "IMTP". 14.2. "shutdown" command This command is sent by a server to a client to negotiate a graceful shutdown of the connection. There are no special headers for this command. This command is only particularly useful for domains with SRV records or site-specific server selection algorithms which could select multiple servers. Upon receiving the command, the client SHOULD attempt to make a connection to a different server for the domain, establish subscriptions or IM forwarding on the new connection, and then close its connection to the old server. An ok response indicates that the client has received the shutdown request. If this command is accidentally sent to a server which has not yet authenticated as such, then the server SHOULD respond with "unknown-method". A client MAY respond to this command with a "communications" error if it could not establish contact with another server, but the server MAY abort the connection in the face of such an error. 15. PITP commands A remote gateway which only uses PITP to communicate with other servers only needs to understand the following commands: auth (from section 14) change-notify fetch subscribe terminate-notify unsubscribe The other commands can only be sent by clients, or perhaps forwarded between servers in the same domain. 15.1. "change" method This command instructs a server to change the PI for a presentity. This command MUST include the following headers: Presentity: A url-hdr specifying the presentity being changed Mapping: A mapping-hdr specifying which PI mapping to change the PI for A payload MAY be included with this command, specifying the new PI. If the payload is omitted, then the mapping will have no PI. An ok response to this command indicates that the PI has been changed or removed. The changing or removal of a mapping's may change the PI of the presentity or result in a denial of access from the point of view of some currently subscribed watchers. The server MUST issue change-notify or terminate-notify requests to update those watchers. An error response to this command indicates that the PI has not been changed. The Error-Type values particular to this method are: mapping-range The specified mapping number is greater than the number of mappings for the presentity. update-race There was a fetch-for-update command prior to this change request, and the PI for the specified mapping has changed since then. Here is an example of a change command and response: C: >1 change C: Presentity: joe@example.net C: Mapping: 1 C: Content-Length: 134 C: C: date = "Thu, 30 Mar 2000 09:59:34 -0500" C: contact = mailto:joe@example.net C: contact = imto:joe@example.net { C: status = deferred C: } S: <1 error (change) S: Error-Originator: impp.example.net S: Error-Type: auth S: Error-Description: Please authenticate first. 15.2. "change-notify" method This command is sent to notify a watcher of a change in presence information for a presentity the watcher is subscribed to. This command MUST include the following headers: Presentity: A url-hdr specifying the presentity whose PI has changed Subscription: A subscription-hdr specifying the watcher and connection ID of the subscription A payload MUST be included with this command, specifying the new PI for the presentity. An ok response to this command indicates that the notification was received by the watching client. If the receiver of this command is a gateway to a protocol which cannot provide a final acknowledgement from a receiving client it MUST include the following header: Unreliable: An origin-hdr giving the point beyond which reliability could not be guaranteed An error response to this command means that the notification was not received. The Error-Type values particular to this method are: not-subscribed Watcher is not subscribed to this presentity with specified connection ID Here is an example of a change-notify command and response: S1: >A3X change-notify S1: Presentity: joe@example.net S1: Subscription: 1/fred@domain.com S1: Content-Length: 134 S1: S1: date = "Thu, 30 Mar 2000 09:59:34 -0500" S1: contact = mailto:joe@example.net S1: contact = imto:joe@example.net { S1: status = deferred S1: } S2: 1 send C: Sender: joe@example.net C: Inbox: fred@domain.com C: Content-Length: 18 C: C: Testing, testing S: <1 ok (send) S: Unreliable: domain.com S: Content-Length: 191 S: S: Your message has been sent to my one-way pager. Hopefully S: I will get it. However, I have shut off my pager's alert S: noise because I am asleep, so I won't read it until S: tomorrow morning. 17. Security considerations 18. IANA considerations 19. References [PIDF] G. Hudson. "Presence Information Data Format." Work in progress, draft-hudson-impp-pidf-proposal-00.txt. [RFC 822] D. Crocker. "Standard for the format of ARPA Internet text messages." RFC 822, August 1982. [RFC 1738] T. Berners-Lee, L. Masinter, M. McCahill. "Uniform Resource Locators (URL)." RFC 1738, December 1994. [RFC 2045-2049] N. Freed, N. Borenstein. "Multipurpose Internet Mail Extensions (MIME)." RFC 2045-2049, November 1996. [RFC 2119] S. Bradner. "Key Words for Use in RFCs to Indicate Requirement Levels." RFC 2119, March 1997. [RFC 2222] J. Myers. "Simple Authentication and Security Layer (SASL)." RFC 2222, October 1997. [RFC 2234] D. Crocker, Ed., P. Overell. "Augmented BNF for Syntax Specifications: ABNF." RFC 2234, November 1997. [RFC 2279] F. Yergeau. "UTF-8, a transformation format of ISO 10646." RFC 2279, January 1998. [RFC 2289] N. Haller, C. Metz, P. Nesser, M. Straw. "A One-Time Password System." RFC 2289, February 1998. [RFC 2368] P. Hoffman, L. Masinter, J. Zawinski. "The mailto URL scheme." RFC 2368, July 1998. [RFC 2617] J. Franks, P. Hallam-Baker, J. Hostetler, S. Lawrence, P. Leach, A. Luotonen, L. Stewart. "HTTP Authentication: Basic and Digest Access Authentication." RFC 2617, June 1999. [RFC 2782] A. Gulbrandsen, P. Vixie, L. Esibov. "A DNS RR for specifying the location of services (DNS SRV)." RFC 2782, February 2000. [Unicode] The Unicode Consortium. "The Unicode Standard Version 3.0." Addison-Wesley, February 2000. 20. Author's address Greg Hudson Massachusetts Institute of Technology Cambridge, MA 02139 ghudson@mit.edu