INTERNET-DRAFT Greg Hudson Expires: ghudson@mit.edu MIT Presence Information Transfer Protocol draft-hudson-impp-pitp-00.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 a transfer protocol for watcher information. It allows clients to publish presence information for their own presentities, clients to fetch and subscribe to the presence information for other presentities, and servers to relay watcher requests and presence notifications between one another. 3. Terminology PITP stands for "Presence Information Transfer Protocol," the protocol specified in this document. PI stands for "Presence Information." The data format for presence information is specified in [XXX ref]. The terms "presentity" and "watcher" are defined in section 4 of this document. The term "principal" is used vaguely to refer to an entity (which may be a person, an organization, or a program) interacting with the presence system. PITP makes 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 entities who have presence information are called "presentities." The entities who fetch or subscribe to presence information 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 XXX. The authoritative source of PI for a presentity is the server(s) for that presentity's domain. However, a watcher in domain 1 does not connect directly to a presence server in domain 2 to retrieve presence information; instead, it connects to a server in its own domain, and its own server will forward the request to the authoritative source. For example, the watcher "presence:joe@example.net" fetches the presence information for the presentity "presence:harry@domain.com" by requesting it from a presence server for example.net, which 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, PITP can be used to transfer presence between servers within a domain as well as between servers in different domains. Thus, PITP 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. 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 client 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 PI. The representation of a watcher class is defined in section XXX. 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 a 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 XXX ref): (1) presence:fred@example.net -> PI1 (2) presence:harry@domain.com, presence:alice@domain.com -> PI2 (3) presence:*@example.net -> PI3 (4) presence:*@* -> PI4 (5) * -> PI5 A watcher "presence:fred@example.com" would receive PI1; a watcher "presence:tom@domain.com" would receive PI4. If example.net's servers run a local gateway (see section XXX) to a different presence service, a watcher from that namespace would receive PI5. 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 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 [XXX SRV ref] A presence client MAY support site-specific means of server discovery, but it SHOULD support the following standard discovery algorithm: the client performs a SRV lookup for its home domain using the service "presence-clients" and the protocol "tcp". 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 (TBD). After connection, the client SHOULD authenticate to the server using the auth-sasl command (see section XXX). 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. After connection, the initiating server SHOULD authenticate to the receiving server using the auth-sasl command (see section XXX). 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 service "presence-servers" and the protocol "tcp". 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 (TBD). After connection, the initiating server MUST, as its first command, authenticate to the receiving server using the auth-domain command (see section XXX). 7. Data flow PITP is a bidirectional asynchronous protocol; 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 PITP is not a lock-step protocol, deadlock is possible if both sides of a connection attempt to write too much data without reading pending data. A PITP server MUST prevent such deadlocks by reading data as it comes in, even if it has data to write. For a Unix socket 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 PITP client MAY perform blocking writes, since the server will prevent deadlocks. 8. Protocol message syntax The underlying character set for protocol messages in PITP is Unicode, represented in UTF-8 [XXX ref]. Payloads are an exception; they should be treated as unprocessed octets. A PITP implementation MUST properly handle arbitrary binary data in the payload. A protocol message is either a command or a response. 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. 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". The Content-Transfer-Encoding header from [RFC 2045] is not necessary in PITP and MUST NOT be included in any PITP command or response. A PITP implementation which receives a Content-Transfer-Encoding header MUST ignore it. Following is an ABNF [RFC 2234] grammar for protocol messages: pmessage = command / response command = ">" id 1*WSP method content response = "<" id 1*WSP status *WSP "(" method ")" content content = CRLF *header CRLF [payload] header = header-name ":" *WSP [header-value] CRLF header-value = *(1*printable [*WSP CRLF] 1*WSP) 1*printable payload = *OCTET id = 1*(ALPHA / DIGIT) method = 1*(ALPHA / DIGIT) status = %x6F.6B / %x6E.72.72.6f.72 ; "ok" or "error" header-name = 1*(%x21-39 / %x3B-7E) ; ASCII, no colons printable = %x21-7E / %x80-D7FF / %xE000-FFFD / %x10000-310FFFF Responses to commands do not necessarily arrive in order. The id part of a response is used to match it up with the corresponding command. 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. Method names and headers are case-sensitive. XXX example 9. Command methods Only the following commands are relevant to transfers between domains: change-notify fetch subscribe unsubscribe terminate-notify XXX example syntax (CRLF, asynchoronous) XXX errors 9.1. "change" method This command is normally sent by a client to a server to change the PI for a presentity. This command may also be sent by a server to another server in the same domain to relay a change request. This command MUST include the following headers: Presentity: URL of the presentity being changed Class: A decimal number specifying which watcher class to change the PI for. A payload MUST be included with this request. An ok response to this command indicates that the PI has been changed. An error response to this command indicates that the PI has not been changed. The Error-Type values for this operation are: auth Requestor is not authorized to control this presentity quota Change would result in unacceptable resource use on behalf of the presentity or principal resources A temporary resource failure occurred communications A temporary communciations failure occurred An error response MAY contain an Error-Description header giving a human-readable text description of the error. Here is an example of a change command and response: C: >1 change C: Presentity: joe@example.net C: Class: 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: Errror-Originator: impp.example.net S: Error-Type: auth S: Error-Description: Please authenticate first. 9.2. "change-notify" method This command is sent by a server to a client or other server to notify a watcher of a change in presence information for a presentity the watcher is subscribed to. This method MUST include the following headers: Presentity: URL of presentity whose PI has changed Watcher: URL of watcher subscribed to presentity An ok response to this command indicates that the notification was received by the watching client. An error response to this command means that the notification was not received. The Error-Type values for this method are: auth Requestor is not authorized to provide PI for this presentity not-subscribed Watcher is not subscribed to this presentity resources A temporary resource failure occurred communications A temporary communications failure occurred Here is an example of a change-notify command and response: S1: >A3X change-notify S1: Presentity: joe@example.net S1: Watcher: 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: