Internet DRAFT - draft-hudson-impp-transfer-proposal
draft-hudson-impp-transfer-proposal
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 -> <no PI>
(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: <A3X ok (change-notify)
S2: AStrength: strong
S2:
15.3. The "delete-mapping" method
This command instructs a server to delete a watcher mapping and
associated presence information 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
delete
An ok response to this command indicates that the mapping has been
deleted. All mappings in the presentity's list after the specified
mapping number have their mapping numbers decreased by 1 to keeping
the mapping numbers consecutive.
Note that the deletion of a mapping 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 means that the mapping has not been
deleted. 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.
15.4. "fetch" method
This command requests the current PI for a presentity. This command
MUST include the following headers:
Watcher: A url-hdr specifying the watcher observing the
PI
Presentity: A url-hdr specifying the presentity to fetch
PI for
An ok response to this command MUST include a payload specifying the
current PI for the presentity. An error response indicates that the
fetch failed. There are no Error-Type values particular to this
method.
15.5. "fetch-for-update" method
This command is used by a client to request the PI for a presentity it
controls in preparation for an update. This command MUST include the
following headers:
Presentity: A url-hdr specifying the presentity being
updated
Mapping: A mapping-hdr specifying the PI mapping being
updated
An ok response to this command MUST include a payload specifying the
current PI for the specified presentity and mapping number. The next
change command on this connection for the specified mapping will fail
with an error type of "update-race" if the PI has changed due to a
request from a different client between the fetch-for-update command
and the change command.
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.
15.6. "fetch-notify" method
This command is sent by a server to inform a client of a fetch
operation for a presentity it is receiving watcher information for.
This command MUST include the following headers:
Watcher: A url-hdr specifying the watcher which
performed the fetch operation
Presentity: A url-hdr specifying the presentity whose PI
was fetched
An ok response to this command indicates that the notify operation was
received by the client. There are no Error-Type values particular to
this method.
15.7. "get-class" method
This command requests the watcher class for a PI mapping for a
presentity (see section 5). This command UST include the following
headers:
Presentity: A url-hdr specifying the presentity to fetch
the watcher class for
Mapping: A mapping-hdr specifying the PI mapping to
fetch the watcher class for
An ok response to this command conveys the watcher class for the
specified mapping to the requester using zero or more of the following
header:
Wpattern: An idpattern-hdr specifying a pattern of
watchers in the watcher class
The Error-Type values for this method are:
mapping-range The specified mapping number is greater than
the number of mappings for the presentity.
15.8. "insert-mapping" method
This command instructs a server to insert a PI mapping (see section 5)
into the list for a presentity. This command MUST include the
following header:
Presentity: A url-hdr specifying the presentity being
changed
Mapping: A mapping-hdr specifying where to insert the
new PI mapping into the list
This command conveys the watcher class for the new mapping using zero
or more of the following header:
Wpattern: An idpattern-hdr specifying a pattern of
watchers to match
A payload MAY be included with this command, specifying the initial PI
for the new watcher mapping. If no payload is included, the mapping
will intially have no PI.
An ok response to this command indicates that the mapping has been
added. Any existing PI mappings with numbers equal to or greater than
the specified mapping number will have their mapping numbers increased
by 1 to make room for the new mapping.
Note that the addition of a mapping 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 mapping has not
been added. The Error-Type values particular to this method are:
mapping-range The specified mapping number is greater than
the number of existing mappings for the
presentity plus one
15.9. "set-class" method
This command instructs a server to set the watcher class for a PI
mapping to a different value. This command MUST contain the following
headers:
Presentity: A url-hdr specifying the presentity being
changed
Mapping: A mapping-hdr specifying the PI mapping to
change
This command conveys the watcher class for the new mapping using zero
or more of the following header:
Wpattern: An idpattern-hdr specifying a pattern of
watchers to match
An ok response to this command indicates that the mapping has been
changed to the new watcher class. Note that changing a mapping's
watcher class may change the PI of the presentity from the point of
view of some currently subscribed watchers. The server MUST issue
change-notify commands to update those watchers with the proper PI.
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.
15.10. "start-wi" method
This command instructs a server to start sending watcher information
to a client. This command MUST contain the following header:
Presentity: A url-hdr specifying the presentity to receive
watcher information for
An ok response to this command indicates that the server will begin
sending watcher information in the form of fetch-notify,
subscribe-notify, and unsubscribe-notify events. An ok response also
conveys the current subscribers to the presentity using zero or more
instances of the following header:
Subscription: A subscription-hdr specifying a watcher
subscribing to the specified presentity and
its connection ID
There are no Error-Type values particular to this operation.
15.11. "subscribe" method
This command requests a subscription to a presentity from a specified
watcher. This command MUST contain the following headers:
Subscription: A subscription-hdr specifying the watcher and
connection ID of the subscription
Presentity: A url-hdr specifying the presentity to
subscribe to
An ok response to this command indicates that the subscription was
successful and the client will receive change-notify requests when the
presentity's PI changes. An ok response also MUST contain a payload
giving the current PI for the presentity.
A client MUST end its subscriptions with the unsubscribe command
before closing its connection to a server. If a client does not do
so, the server SHOULD end the clients' subscriptions to presentities
in other domains, but the server MAY simply wait for the next
change-notify or terminate-notify operation for that subscription and
respond with an error type of "not-subscribed".
There are no Error-Type values particular to this method.
15.12. "subscribe-notify" method
This command is sent by a server to inform a client that a
subscription was made to a presentity it is receiving watcher
information for. This command MUST include the following headers:
Subscription: A subscription-hdr specifying the watcher and
connection ID of the subscription
Presentity: A url-hdr specifying the presentity whose PI
was subscribed to
An ok response to this command indicates that the notify operation was
received by the client.
There are no Error-Type values particular to this method.
15.13. "terminate" method
This command instructs a server to terminate the a subscription to a
presentity. Unlike the unsubscribe command, this command is issued on
the behalf of the presentity, not the watcher, and this command does
not cross domains. This command MUST include the following headers:
Presentity: A url-hdr specifying the presentity to
terminate the subscription to
Subscription: A subscription-hdr specifying the watcher and
connection ID of the subscription to terminate
An ok response to this command indicates that the subscription has
been terminated. A server MUST send an unsubscribe-notify command to
any connections receiving watcher information for the presentity when
a subscription is terminated (which may include the connection which
sent the terminate command).
The Error-Type values particular to this method are:
not-subscribed Watcher is not subscribed to this presentity
with specified connection ID
15.14. "terminate-notify" method
This command notifies a client that its subscription to a presentity
has been terminated. This command MUST include the following headers:
Presentity: A url-hdr specifying the presentity to which
the subscription was terminated
Subscription: A subscription-hdr specifying the watcher and
connection ID of the subscription which was
terminated
An ok response to this command indicates that the subscribing client
has received the notification. The Error-Type values particular to
this method are:
not-subscribed Watcher is not subscribed to this presentity
with specified connection ID
15.15. "unsubscribe" method
This command instructs a server to terminate a subscription to a
presentity. This command MUST include the following headers:
Subscription: A subscription-hdr specifying the watcher and
connection ID of the subscription to end
Presentity: A url-hdr specifying the presentity subscribed
to
An ok response to this command indicates that the subscription was
successfully ended.
The Error-Type values particular to this method are:
not-subscribed Watcher is not subscribed to this presentity
with specified connection ID
15.16. "unsubscribe-notify" method
This command is sent by a server to inform a client that an
unsubscription was made from a presentity it is receiving watcher
information for. This command MUST include the following headers:
Subscription: A url-hdr specifying the watcher and
connection ID of the subscription
Presentity: A url-hdr specifying the presentity whose PI
was unsubscribed from
An ok response to this command indicates that the notify operation was
received by the client.
There are no Error-Type values particular to this method.
16. IMTP commands
16.1. "listen" command
This command is sent by a client to a server to request reception of
messages sent to a specified instant inbox. This command MUST include
the following headers:
Inbox: A url-hdr giving the inbox to receive messages
from
This command MAY use one or more instances of the following headers to
restrict the client to listening for specific senders:
Only: An idpattern-hdr specifying senders to receive
messages from
Except: An idpattern-hdr specifying senders not to
receive messages from
If any Only headers are included, then the server MUST NOT forward
messages to the client if the sender does not match one of the
identifier patterns in an Only header. If any Except headers are
included, then the server MUST NOT forward messages to the client if
the sender matches one of the identifier patterns in an Except header.
If a sender fails to meet the criteria for forwarding to this client
connection, then the server MUST act as if this client connection were
not listening to the inbox (i.e. forward to other client connections
listening on the same inbox if the sender matches the forwarding
criteria for those inboxes, or reject the send command with a
"no-listeners" error if there are no such connections).
If the client connection is already listening to the specified inbox,
then this command acts as a request to update the forwarding criteria
for the inbox. The server MUST, if it accepts the command, discard
all previous Only and Except filters and begin using the ones
specified in the command.
An ok response to this command indicates that the server will forward
messages to the client as specified by the headers. There are no
Error-Type values particular to this method.
16.2. "send" method
This command causes an IM to be sent to an instant inbox. This
command MUST include the following headers:
Sender: A url-hdr giving the sender of the IM
Inbox: A url-hdr giving the recipient of the IM
A relay MUST also include the following header:
Visited: A visited-hdr giving a list of domains the
IM has passed through
The value of the Visited header MUST be composed of the domain list
send from the previous node, if any, followed by a domain representing
the relay. This domain MAY be the domain served by the relay server,
a fully-qualified hostname of the server machine, or some other domain
under the administrative control of the server operators; care must be
taken not to conflict with the domain used by servers under other
administrative control.
This command MAY include the following headers:
Orig-Sender: A url-hdr giving the original sender of the IM
Orig-Inbox: A url-hdr giving the original recipient of the
IM
The Orig-Inbox header may occur multiple times. If any Orig-Inbox
headers are included, they MUST specify all of the recipients
originally specified for the IM (including the URL specified by the
Inbox header, if that was one of the original recipients). The
Orig-Sender and Orig-Inbox headers are useful when a message passes
through a redistribution list; the Orig-Inbox header can also be used
to indicate when a message is sent to multiple recipients. User
interfaces should note that the Orig-Sender header is not protected by
the source address authorization scheme defined in section 8.1.
A payload MUST be included with this command, specifying the IM to
send.
An ok response to this command indicates that the IM has been received
by the instant inbox. 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
Relay MUST include the unmodified Unreliable header when passing on a
response.
An ok response to this command MAY include a payload. In this case,
the payload should be treated as a "vacation"-style message indicating
that the IM has been received but will not be read immediately.
If the receiver of this command is a server for the home domain of the
inbox and there are multiple client connections listening to that
inbox, the server is faced with the task of combining several
responses into one. The following rules apply to this operation:
* If at least one of the clients gives an ok response, the
server MUST give an ok response.
* If at least one of the clients responds with a payload, the
server MUST include one of the payloads.
* If multiple clients respond with payloads, the server may
use any algorithm to pick which payload to include.
* If all clients respond with errors, the server may use any
algorithm to pick which error to report.
The Error-Type values particular to this method are:
no-listeners No clients are listening to this instant inbox
loop The message was routed through a loop and
cannot be delivered
Here is an example of a send command and response:
C: >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
