RFC 3922

Mapping the Extensible Messaging and Presence Protocol (XMPP) to Common Presence and Instant Messaging (CPIM)

📅 published October 2004, from ietf

Mapping the Extensible Messaging and Presence Protocol (XMPP) to Common Presence and Instant Messaging (CPIM) 🎀

RFC: 3922
Stream: Network Working Group
Author: P. Saint-Andre, Jabber Software Foundation
Category: Standards Track
Date: October 2004
Obsoletes/Updates: The title block doesn't list any RFCs this one obsoletes or updates. 🫶

okay bestie, RFC 3922 is the doc that explains how XMPP (the protocol behind a lot of chat apps 💬) talks to the CPIM world, so an XMPP user and a non-XMPP user can actually message each other. it's giving bridge building 🌉✨

Status of This Memo 📝

this is a standards track protocol doc for the internet community, and it's asking for discussion and suggestions for improvements 💅 for the current standardization state and status, check the "Internet Official Protocol Standards" (STD 1). distribution of this memo is unlimited 🌸

Copyright Notice 💜

Abstract 🦋

this memo describes a mapping between the Extensible Messaging and Presence Protocol (XMPP) and the Common Presence and Instant Messaging (CPIM) specifications. the whole point 🔥

Table of Contents 🧚

1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  2
2.  Approach . . . . . . . . . . . . . . . . . . . . . . . . . . .  3
3.  Address Mapping  . . . . . . . . . . . . . . . . . . . . . . .  4
4.  Syntax Mapping of Instant Messages . . . . . . . . . . . . . .  5
5.  Syntax Mapping of Presence Information . . . . . . . . . . . . 13
6.  XMPP-CPIM Gateway as Presence Service  . . . . . . . . . . . . 26
7.  Security Considerations  . . . . . . . . . . . . . . . . . . . 31
8.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 33
Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 34

1. Introduction ✨

1.1. Overview 🌈

okay so the Instant Messaging and Presence (IMPP) Working Group came up with an abstract framework for interoperability among instant messaging (IM) and presence systems that are compliant with [IMP-REQS]. this framework is commonly called Common Presence and Instant Messaging or "CPIM". the CPIM family includes a Common Profile for Instant Messaging [CPIM] (also called CPIM), a Common Profile for Presence [CPP], a CPIM Message Format [MSGFMT], and a Common Presence Information Data Format [PIDF]. (to avoid confusion, Common Presence and Instant Messaging is called "the CPIM specifications" as a group, and the Common Profile for Instant Messaging is just called "CPIM" 🫶)

this memo describes how XMPP ([XMPP-CORE], [XMPP-IM]) maps onto the abstract model in the CPIM specifications. the main goal is building gateways between XMPP services and non-XMPP services that conform to [IMP-REQS] 🎀 a gateway like this (called an "XMPP-CPIM gateway") can interpret one service's protocols and translate them into the other's. picture it like this 👇

  +-------------+        +-------------+        +------------+
  |             |        |             |        |            |
  |    XMPP     |        |  XMPP-CPIM  |        |  Non-XMPP  |
  |   Service   | <----> |   Gateway   | <----> |  Service   |
  |             |        |             |        |            |
  +-------------+        +-------------+        +------------+

this memo defines a mapping for a gateway that translates between XMPP and a non-XMPP protocol through the CPIM specifications. that gateway is NOT an intermediate hop on a network of non-XMPP servers (whose native formats might or might not be defined by the CPIM specifications) 🙅‍♀️ it's a dedicated translator between XMPP and a non-XMPP protocol, where the CPIM specifications define the common formats the protocols get translated into so they can work together 💖

the mapping here applies to instant messages and presence information that are not encrypted or signed for end-to-end security. for secure communications to or from an XMPP service through an XMPP-CPIM gateway, check out [XMPP-E2E] 🔐

1.2. Terminology 🧁

this memo inherits vocabulary from [IMP-MODEL]. terms like CLOSED, INSTANT INBOX, INSTANT MESSAGE, OPEN, PRESENCE SERVICE, PRESENTITY, SUBSCRIPTION, and WATCHER mean the same thing they do there ✨

this memo also inherits vocabulary from [XMPP-CORE]. terms like ENTITY, NODE IDENTIFIER, DOMAIN IDENTIFIER, RESOURCE IDENTIFIER, MESSAGE STANZA, and PRESENCE STANZA mean the same thing they do there too 💅

1.3. Conventions Used in this Document 📏

the capitalized key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [TERMS] 🫶

2. Approach 🍓

okay real talk, XMPP and CPIM are super different technologies 😭 so you have to be careful when mapping between XMPP and the abstract syntax defined by the CPIM specifications 🧐

at its core, XMPP is a data transport protocol for streaming XML elements (called "stanzas") between any two endpoints on the network 🌐 message and presence stanzas are two of the core data elements in XMPP, and they're often used to swap instant messages and presence information between IM users. (the inherent extensibility of XML means apps can also use these stanza types for other purposes, which is iconic) XMPP is not based on [MIME]. instead, [XMPP-CORE] defines XML schemas for both message and presence stanzas. for example, the <body/> child of a message stanza holds XML character data that's usually meant to be read by a human user 💬

the CPIM specifications provide common formats for instant messaging and presence through two [MIME] content-types: "Message/CPIM" for messages ([MSGFMT]) and "application/pidf+xml" for presence ([PIDF]). the syntax of "Message/CPIM" objects is similar to, but stricter than, the one defined in [RFC2822], and it can include arbitrary MIME media types [MIMETYPES] 🎀 meanwhile, each "application/pidf+xml" object is a complete XML document whose structure is defined by an XML schema 📄

so the approach here is to specify mappings from XMPP elements and attributes to the headers and MIME formats defined by [MSGFMT] and [PIDF], so the semantics in [CPIM] and [CPP] are followed 💖 and mappings in the opposite direction get specified too, of course 🔁

3. Address Mapping 🗺️

3.1. Overview 🦋

address mapping might be needed because the address formats used to identify XMPP entities (specified in [XMPP-CORE]) are different from the ones used to identify instant inboxes (the im: URI scheme specified in [CPIM]) and presentities (the pres: URI scheme specified in [CPP]). specifically, im: and pres: URIs allow different characters than XMPP addresses do:

the following [US-ASCII] characters are allowed in im:/pres: URIs but not in XMPP addresses: #26; (&), #27; ('), and #2f; (/).
a lot of non-US-ASCII (specifically, UTF-8) characters are allowed in XMPP addresses but not in im:/pres: URIs, since XMPP allows internationalized local-part addresses 🌍

note: in this doc we only talk about characters allowed in local-part addresses. we ruled mapping domain names out of scope for the initial version, since that's a job for the Domain Name System and the translation of fully internationalized domain names 🙈

3.2. XMPP to CPIM 🌸

here's the high-level algorithm for mapping an XMPP address to an im: or pres: URI:

split the XMPP address into the node identifier (local-part; mapping described in the remaining steps), the domain identifier (hostname; mapping is out of scope), and the resource identifier (specifier for a particular device or connection; discard this for cross-system interoperability) 🫧
apply the Nodeprep profile of [STRINGPREP] (as specified in [XMPP-CORE]) for canonicalization (OPTIONAL)
translate #26; to &, #27; to ', and #2f; to / respectively
for each byte, if the byte is not in the set A-Za-z0-9!$*.?_~+=, change it to %hexhex as described in Section 2.2.5 of [URL-GUIDE]
combine the resulting local-part with the mapped hostname to form a local@domain address
prepend the 'im:' scheme (for XMPP <message/> stanzas) or the 'pres:' scheme (for XMPP <presence/> stanzas) 🎀

3.3. CPIM to XMPP 💫

here's the high-level algorithm for mapping an im: or pres: URI to an XMPP address:

remove the URI scheme
split at the first '@' character into local-part and hostname (mapping the latter is out of scope)
translate %hexhex to equivalent octets as described in Section 2.2.5 of [URL-GUIDE]
treat the result as a UTF-8 string
translate & to #26;, ' to #27;, and / to #2f respectively
apply the Nodeprep profile of [STRINGPREP] (as specified in [XMPP-CORE]) for canonicalization (OPTIONAL)
recombine the local-part with the mapped hostname to form a local@domain address 🧚

4. Syntax Mapping of Instant Messages 💌

this section describes how a gateway SHOULD map instant messages between an XMPP service and a non-XMPP service. it uses a "Message/CPIM" object as the bearer of encapsulated text content, so it follows the instant messaging semantics defined by [CPIM] 🫶

4.1. Message Syntax Mapping from XMPP to CPIM Specifications 🔁

this section defines how syntax primitives map from XMPP message stanzas to "Message/CPIM" objects with encapsulated text content ✨

note: as [MIME] specifies, the default Content-type of a MIME object is Content-type: text/plain; charset=us-ascii. XMPP uses the [UTF-8] character encoding exclusively, so the encapsulated MIME object a gateway generates MUST set the "Content-type" MUST be set to "text/plain" and the charset MUST be set to "utf-8" 💅

4.1.1. From Address 💖

the 'from' attribute of an XMPP message stanza maps to the 'From' header of a "Message/CPIM" object. in XMPP, the sender's server stamps or validates the "from" address and sets its value to the full <user@host/resource> that was negotiated between client and server during authentication and resource binding (as defined in [XMPP-CORE]) 🔐 so an XMPP-CPIM gateway gets a message stanza from the sender's XMPP server with a "from" address in the form <user@host/resource>. to map the 'from' attribute of an XMPP message stanza to the 'From' header of a "Message/CPIM" object, the gateway MUST remove the resource identifier, MUST append the "im:" Instant Messaging URI scheme to the front of the address, and MAY include a CPIM "Formal-name" for the sender (if known) 🎀

Example: From Address Mapping 🦋

XMPP 'from' attribute

<message from='juliet@example.com/balcony'>
  ...
</message>

CPIM 'From' header

From: Juliet Capulet <im:juliet@example.com>

4.1.2. To Address 📬

okay so the to attribute on an XMPP message stanza gets mapped to the To header of a "Message/CPIM" object. 💌 The sender SHOULD include a to attribute on a message stanza, and they MUST include it if the message is meant for another user. 🫶 So the XMPP-CPIM gateway gets a stanza from the sender's XMPP server with a "to" address that looks like <user@host> or <user@host/resource>. 🦋

To make that work, the gateway MUST remove the resource identifier (if it's there), MUST stick the "im:" Instant Messaging URI scheme on the front of the address, and MAY add a CPIM "Formal-name" for the recipient if it knows one. ✨ Main character energy, the address gets a whole glow-up. 💅

Example: To Address Mapping

XMPP 'to' attribute
  <message to='romeo@example.net/orchard'>
    ...
  </message>

CPIM 'To' header
  To: Romeo Montague <im:romeo@example.net>

4.1.3. Stanza ID 🪪

An XMPP message stanza MAY have an id attribute, and the sending app uses it to keep track of stanzas. 🧚 It is NOT a globally-unique identifier like the MIME Content-ID header is, so it's not the same thing, ngl. 🙈 Because of that, the id SHOULD NOT be mapped to that header. 🚫

BUT (and this is the iconic part) if the id is known to be unique, like if the XMPP server generated it to be unique and the XMPP-CPIM gateway knows that for sure, then it SHOULD be mapped. 🔥

4.1.4. Message Type 🎀

An XMPP message stanza MAY have a type attribute, which the sending app uses to capture the conversational context of the message. 💬 There's no mapping from the XMPP type attribute to a "Message/CPIM" header, common MIME features, or encapsulated text content, so it just doesn't carry over. 🥲 So if a stanza hits an XMPP-CPIM gateway with a type attribute, the gateway SHOULD ignore the value. 🙅‍♀️

4.1.5. Message Thread 🧵

An XMPP message stanza MAY contain a <thread/> child element to say which conversation thread the message belongs to. 🌸 Same deal as the type attribute, though: there's no mapping of an XMPP <thread/> element to a "Message/CPIM" header, common MIME features, or encapsulated text content. 😭 So if a stanza that goes through an XMPP-CPIM gateway has a <thread/> child element, the gateway SHOULD ignore the value provided.

4.1.6. Message Subject 🌈

An XMPP message stanza MAY include a <subject/> child element. 💌 If it's there, it maps to the Subject header of a "Message/CPIM" object. 🔥 To do that, the gateway SHOULD simply map the XML character data of the XMPP <subject/> element to the value of the Subject header. Easy peasy. 🧁

The <subject/> element MAY include an xml:lang attribute that says what language the subject is written in. 🌍 If there's an xml:lang attribute, it MUST be mapped by putting ;lang=tag after the header name and colon, where tag is the value of the xml:lang attribute. 💅 Slay the formatting.

Example: Subject Mapping

XMPP <subject/> element
  <subject>Hi!</subject>
  <subject xml:lang='cz'>Ahoj!</subject>

CPIM 'Subject' header
  Subject: Hi!
  Subject:;lang=cz Ahoj!

4.1.7. Message Body 💖

The <body/> child element of an XMPP message stanza is the one that carries the primary meaning of the message. 🫶 Its XML character data maps to the encapsulated text message content. 📝 This is the heart of the whole message, bestie. 💜

Example: Message Body

XMPP message <body/>
  <message>
    <body>Wherefore art thou, Romeo?</body>
  </message>

Encapsulated MIME text content
  Content-type: text/plain; charset=utf-8
  Content-ID: <123456789@example.net>

  Wherefore art thou, Romeo?

4.1.8. Message Extensions 🧩

As defined in [XMPP-CORE], an XMPP message stanza can have "extended" content in any namespace, to add to or extend the meaning of the core message stanza. 🪄 The exception is extended info qualified by the urn:ietf:params:xml:ns:xmpp-e2e namespace (defined in [XMPP-E2E]). For everything else, an XMPP-CPIM gateway SHOULD ignore that info and NOT pass it through to the intended recipient. 🙃 No mapping for it is defined, so it's basically a "not today" situation. 🙈

4.1.9. Gateway-Generated CPIM Syntax 🛠️

CPIM specifies "Message/CPIM" headers beyond the ones described above, but there's no exact match for them in the core XMPP specs. 🤷‍♀️ These include:

cc -- specifies the address of an entity that is to receive a "courtesy copy" of the message (i.e., a non-primary addressee)
DateTime -- specifies the datetime at which the message was sent
NS -- specifies the namespace of a feature extension
Require -- specifies mandatory-to-recognize features

An XMPP-CPIM gateway MAY independently generate such headers based on its own info (for example, the datetime at which it received a message stanza from an XMPP entity), or based on data encoded in non-core XMPP extensions. 🧠 The rules for doing that, though, are out of scope for this memo. 🫠

4.2. Message Syntax Mapping from CPIM Specifications to XMPP 🔁

This section defines how syntax primitives from "Message/CPIM" objects with encapsualted text content map to XMPP message stanzas. 🦋 It's the reverse trip, and it's giving full circle. 🌀

4.2.1. From Address 💌

The From header of a "Message/CPIM" object maps to the from attribute of an XMPP message stanza. 🎀 To do that, the gateway MUST remove the "im:" Instant Messaging URI scheme from the front of the address, and MUST remove the CPIM "Formal-name" (if one was provided). ✂️

Example: From Address Mapping

CPIM 'From' header
  From: Romeo Montague <im:romeo@example.net>

XMPP 'from' attribute
  <message from='romeo@example.net'>
    ...
  </message>

4.2.2. To Address 📫

The To header of a "Message/CPIM" object maps to the to attribute of an XMPP message stanza. 💖 To map it, the gateway MUST remove the "im:" Instant Messaging URI scheme from the front of the address and MUST remove the CPIM "Formal-name" (if provided). 🧹 If the gateway knows the resource identifier that the XMPP entity is using, it MAY append that resource identifier to the address. 🌷

Example: To Address Mapping

CPIM 'To' header
  To: Juliet Capulet <im:juliet@example.com>

XMPP 'to' attribute
  <message to='juliet@example.com/balcony'>
    ...
  </message>

4.2.3. Courtesy Copy 🙊

The core XMPP spec doesn't have syntax for a "courtesy copy" (a non-primary addressee) on a message stanza. 🥺 So if an XMPP-CPIM gateway receives a "Message/CPIM" object with a cc header, the gateway SHOULD NOT pass the info in that header on to the XMPP recipient. 🚫

4.2.4. DateTime Header 🕰️

The core XMPP spec also doesn't have syntax for saying when a message stanza was sent. ⏰ So if an XMPP-CPIM gateway receives a "Message/CPIM" object with a DateTime header, the gateway SHOULD NOT pass the info in that header on to the XMPP recipient. 🙅‍♀️

4.2.5. Message Subject 🌺

The Subject header of a "Message/CPIM" object maps to the <subject/> child element of an XMPP message stanza. 💅 To map it, the gateway SHOULD simply map the value of the Subject header to the XML character data of the <subject/> element. 🎀 The Subject header MAY specify the "lang" the subject is written in. If "lang" info is provided, it MUST be mapped to the xml:lang attribute of the <subject/> element, where the value of xml:lang is the "tag" value from the ;lang=tag string after the CPIM Subject header name and colon. 🌍✨

Example: Subject Mapping

CPIM 'Subject' header
  Subject: Hi!
  Subject:;lang=cz Ahoj!

XMPP <subject/> element
  <subject>Hi!</subject>
  <subject xml:lang='cz'>Ahoj!</subject>

4.2.6. Header Extensions 🎁

"Message/CPIM" objects MAY include an optional NS header to specify the namespace of a feature extension. 🧩 An XMPP-CPIM gateway MUST NOT pass such headers through to the XMPP recipient, and no mapping for them is defined. 🙃 Not allowed to come to the party, sorry. 💀

4.2.7. Require Header 🔒

"Message/CPIM" objects MAY include an optional Require header to specify mandatory-to-recognize features. 🧐 Generally, the non-XMPP sending app would include it to (1) insist that the receiving app needs to understand functionality specified by a particular header, or (2) indicate that some non-header semantics need to be implemented by the receiving app in order to understand the contents of the message (for example, "Locale.MustRenderKanji"). 🇯🇵

Here's the tricky bit: those mandatory-to-recognize features would be required of the XMPP receiving app, not the XMPP-CPIM gateway itself. 😵‍💫 So the gateway can't properly handle the Require header without detailed knowledge of what the XMPP receiving app can do. 🫠 That's why it seems right that the XMPP-CPIM gateway SHOULD return a warning or error to the non-XMPP sending app if a "Message/CPIM" object includes one or more Require headers. The exact nature of that warning or error depends on the non-XMPP tech the foreign system uses, and it's not defined here. 🌀 Furthermore, any mapping of the Require header into XMPP or an XMPP extension is left up to the implementation or to a future specification. 🔮

⚠️ Gateways can't just guess what the receiving app supports, so the warning-or-error move is the safe play here.

4.2.8. MIME Content-ID 🆔

XMPP doesn't have an element or attribute that captures a globally unique ID like the Content-ID MIME header defined in [MIME]. 🥲 If an XMPP-CPIM gateway receives a MIME object that includes a Content-ID, it MAY provide that Content-ID as the value of the message stanza's id attribute, but this is OPTIONAL. 🫧

Example: Content-ID for Encapsulated Object

MIME header
  Content-ID: <123456789@example.net>

XMPP 'id' attribute (OPTIONAL)
  <message id='123456789@example.net'>
    ...
  </message>

4.2.9. Message Body 💬

If the Content-type of an encapsulated MIME object is "text/plain", then the encapsulated text message content maps to the XML character data of the <body/> child element of an XMPP message stanza. 🌟

Example: Message Body

Encapsulated MIME text content
  Content-type: text/plain; charset=utf-8
  Content-ID: <123456789@example.net>

  Wherefore art thou?

XMPP message <body/>
  <message id='123456789@example.net'>
    <body>Wherefore art thou?</body>
  </message>

If the Content-Type is NOT "text/plain", the XMPP-CPIM gateway MAY map the content to an XMPP extension, but it MUST NOT map it to the <body/> child of the XMPP message stanza, which is only allowed to contain XML character data. 🚫 The only exception is a multi-part MIME object of the kind specified in [XMPP-E2E], which gets mapped as that memo describes. 🔐

If the charset is "US-ASCII" or "UTF-8", the gateway MUST map the "Message/CPIM" object; otherwise it SHOULD NOT. 🌈 Charset check, periodt. ✅

4.2.10. Gateway-Generated XMPP Syntax 🪄

XMPP specifies a type attribute for XMPP message stanzas, which lets the sender define the conversational context of the message. 💭 There's no exact analogue for this attribute in CPIM. 🤍 An XMPP-CPIM gateway MAY independently generate the type attribute based on its own info, but this is OPTIONAL, and the rules for doing so are out of scope for this memo. 🌸

5. Syntax Mapping of Presence Information 🧚✨

Okay bestie, section 5 is where presence gets its glow-up 💅 This is how a gateway SHOULD map presence info between an XMPP service and a non-XMPP service. It uses a "Message/CPIM" object as the bearer of an encapsulated [PIDF] object, so everything still follows the presence semantics defined by [CPP] 💜

5.1. Presence Syntax Mapping from XMPP to CPIM Specifications 🎀

This section maps the syntax pieces from XMPP presence stanzas over to "Message/CPIM" objects with encapsulated "application/pidf+xml" objects. It's giving organized 🍓

Note: As specified in [MIME], the default Content-type of a MIME object is Content-type: text/plain; charset=us-ascii. XMPP uses the [UTF-8] character encoding exclusively, and PIDF specifies the "application/pidf+xml" MIME type, so the encapsulated MIME object an XMPP-CPIM gateway makes for presence info MUST set the 'Content-type' header for that object. The "Content-type" MUST be set to "application/pidf+xml" and the charset MUST be set to "utf-8". 🙈

5.1.1. From Address 💌

The 'from' attribute of an XMPP presence stanza maps to the 'From' header of a "Message/CPIM" object. In XMPP, the sender's server stamps or validates the "from" address and sets it to the <user@host/resource> that got negotiated between client and server during authenticating and resource binding, as defined in [XMPP-CORE]. So an XMPP-CPIM gateway gets a presence stanza from the sender's XMPP server with a "from" address shaped like <user@host/resource> 🫶

To map the 'from' attribute of an XMPP presence stanza to the 'From' header of a "Message/CPIM" object, the gateway MUST remove the resource identifier, MUST add the "im:" Instant Messaging URI scheme to the front of the address, and MAY include a CPIM "Formal-name" for the sender (if known).

Example: From Address Mapping

XMPP 'from' attribute
  <presence from='juliet@example.com/balcony'>
    ...
  </presence>

CPIM 'From' header
  From: Juliet Capulet <im:juliet@example.com>

Also, the 'from' attribute of an XMPP presence stanza maps to the 'entity' attribute of a PIDF <presence/> root element. To map the XMPP 'from' attribute to the PIDF 'entity' attribute, the gateway MUST remove the resource identifier and MUST add the "pres:" Instant Messaging URI scheme to the front of the address. 🦋

Example: From Address Mapping (PIDF)

XMPP 'from' attribute
  <presence from='juliet@example.com/balcony'>
    ...
  </presence>

PIDF 'entity' attribute
  <presence entity='pres:juliet@example.com'>
    ...
  </presence>

Last thing: an XMPP-CPIM gateway SHOULD map the resource identifier from the XMPP address in the 'from' attribute to the 'id' attribute of the PIDF <tuple/> child element. ✨

Example: Resource Identifier Mapping

XMPP 'from' attribute
  <presence from='juliet@example.com/balcony'>
    ...
  </presence>

PIDF 'id' for <tuple/>
  <presence entity='pres:juliet@example.com'>
    <tuple id='balcony'>
      ...
    </tuple>
  </presence>

5.1.2. To Address 📬

The 'to' attribute of an XMPP presence stanza maps to the 'To' header of a "Message/CPIM" object. In XMPP, the sender MAY include a 'to' attribute on a presence stanza, and MUST include it if the presence stanza is meant for delivery straight to another user. (Presence stanzas meant for broadcasting get stamped with a 'to' address by the sender's server, so that part's handled 🧚) So an XMPP-CPIM gateway gets a presence stanza from the sender's XMPP server with a "to" address shaped like <user@host> or <user@host/resource>.

To map the 'to' attribute of an XMPP presence stanza to the 'To' header of a "Message/CPIM" object, the gateway MUST remove the resource identifier (if one's included), MUST add the "im:" Instant Messaging URI scheme to the front of the address, and MAY include a CPIM "Formal-name" for the recipient (if known).

Example: To Address Mapping

XMPP 'to' attribute
  <presence to='romeo@example.net/orchard'>
    ...
  </presence>

CPIM 'To' header
  To: Romeo Montague <im:romeo@example.net>

5.1.3. Stanza ID 🪪

An XMPP presence stanza MAY have an 'id' attribute. The sending app uses it to track stanzas, and it is not a globally-unique identifier like the one defined by the MIME Content-ID header. Since the XMPP 'id' attribute doesn't mean the same thing as the MIME Content-ID header, it SHOULD NOT be mapped to that header. The exception: if the 'id' is known to be unique (for example, the XMPP server generated it to be unique and the XMPP-CPIM gateway knows that), then it SHOULD be mapped. 🔍

5.1.4. Presence Type 🌈

An XMPP presence stanza MAY have a 'type' attribute. If there's no 'type' attribute, the stanza says the sender is available, and that maps to the PIDF basic presence type of OPEN. If the 'type' attribute is "unavailable", the stanza says the sender is no longer available, and that maps to the PIDF basic presence type of CLOSED. So both no 'type' attribute AND a 'type' set to "unavailable" line up with the [CPP] "notify operation" 🙌

All the other presence types are for managing presence subscriptions or probing for current presence. Their mappings live under XMPP-CPIM Gateway as Presence Service (Section 6) 🌸

Example: Available Presence

XMPP available presence
  <presence from='juliet@example.com/balcony'/>

PIDF basic presence (OPEN)
  <?xml version='1.0' encoding='UTF-8'?>
  <presence xmlns='urn:ietf:params:xml:ns:pidf'
            entity='pres:juliet@example.com'>

    <tuple id='balcony'>
      <status>
        <basic>open</basic>
      </status>
    </tuple>
  </presence>

Example: Unavailable Presence

XMPP unavailable presence
  <presence from='juliet@example.com/balcony' type='unavailable'/>

PIDF basic presence (CLOSED)
  <?xml version='1.0' encoding='UTF-8'?>
  <presence xmlns='urn:ietf:params:xml:ns:pidf'
            entity='pres:romeo@example.net'>
    <tuple id='balcony'>
      <status>
        <basic>closed</basic>
      </status>
    </tuple>
  </presence>

5.1.5. Show Element 🫧

The <show/> child element of an XMPP presence stanza tells you more about the sender's availability. The XML character data of the XMPP <show/> element maps to the extended <status/> content in PIDF. The defined values of <show/> are 'away', 'chat', 'dnd', and 'xa'. As soon as values get specified for extended status states in the 'urn:ietf:params:xml:ns:pidf:im' namespace, the XMPP values will map over to the PIDF values. 💭

Example: Show Element

XMPP <show/> element
  <presence from='juliet@example.com/balcony'>
    <show>away</show>
  </presence>

PIDF extended presence information
  <?xml version='1.0' encoding='UTF-8'?>
  <presence xmlns='urn:ietf:params:xml:ns:pidf'
            xmlns:im='urn:ietf:params:xml:ns:pidf:im'
            entity='pres:juliet@example.com'>
    <tuple id='balcony'>
      <status>
        <basic>open</basic>
        <im:im>away</im:im>
      </status>
    </tuple>
  </presence>

5.1.6. Status Element 📝

The <status/> child element of an XMPP presence stanza is a user-defined, natural-language description of the sender's detailed availability. The XMPP <status/> element maps to the PIDF <note/> child of the PIDF <tuple/> element. 🎀

Example: Status Element

XMPP <status/> element
  <presence from='juliet@example.com/balcony'>
    <show>away</show>
    <status>retired to the chamber</status>
  </presence>

PIDF <note/> element
  <?xml version='1.0' encoding='UTF-8'?>
  <presence xmlns='urn:ietf:params:xml:ns:pidf'
            xmlns:im='urn:ietf:params:xml:ns:pidf:im'
            entity='pres:juliet@example.com'>
    <tuple id='balcony'>
      <status>
        <basic>open</basic>
        <im:im>away</im:im>
      </status>
      <note>retired to the chamber</note>
    </tuple>
  </presence>

5.1.7. Presence Priority 👑

An XMPP presence stanza MAY contain a <priority/> child element whose value is an integer from -128 to +127. The value of this element MAY map to the 'priority' attribute of the <contact/> child of the PIDF <tuple/> element. If the XMPP <priority/> element's value is negative, an XMPP-CPIM gateway MUST NOT map the value. 🚫

The range of allowed values for the PIDF 'priority' attribute is any decimal number from zero to one inclusive, with a maximum of three decimal places. If an XMPP-CPIM gateway does map these values, it SHOULD treat XMPP <priority>0</priority> as PIDF priority='0' and XMPP <priority>127</priority> as PIDF priority='1', and map the values in between so they're unique. For example: XMPP priority 1 to PIDF priority 0.007, XMPP priority 2 to PIDF priority 0.015, and so on up through XMPP priority 126 to PIDF priority 0.992. Note that this is just an example, and the exact mapping shall be determined by the XMPP-CPIM gateway 🧠

Example: Presence Priority

XMPP <status/> element
  <presence from='juliet@example.com/balcony'>
    <priority>13</priority>
  </presence>

PIDF <note/> element
  <?xml version='1.0' encoding='UTF-8'?>
  <presence xmlns='urn:ietf:params:xml:ns:pidf'
            entity='pres:juliet@example.com'>
    <tuple id='balcony'>
      ...
      <contact priority='0.102'>im:juliet@example.com</contact>
    </tuple>
  </presence>

5.1.8. Presence Extensions 🧩

As defined in [XMPP-CORE], an XMPP presence stanza may contain "extended" content in any namespace to supplement or extend the semantics of the core presence stanza. Except for extended info qualified by the 'urn:ietf:params:xml:ns:xmpp-e2e' namespace (defined in [XMPP-E2E]), an XMPP-CPIM gateway SHOULD ignore that info and not pass it through the gateway to the intended recipient. No mapping for this info is defined. 🙈

5.1.9. Gateway-Generated CPIM and PIDF Syntax 🌟

5.1.9.1. CPIM Message Headers 💖

CPIM specifies "Message/CPIM" headers beyond the ones described above, but the core XMPP specifications don't have an exact analogue for them. These include:

cc -- specifies the address of an entity that is to receive a "courtesy copy" of the presence information (i.e., a non-primary addressee)
DateTime -- specifies the datetime at which the presence information was sent
NS -- specifies the namespace of a feature extension
Subject -- specifies the subject or topic of the encapsulated "Message/CPIM" object
Require -- specifies mandatory-to-recognize features

An XMPP-CPIM gateway MAY independently generate such headers based on its own info (for example, the datetime it got a presence stanza from an XMPP entity), or based on data encoded in non-core XMPP extensions. The rules for doing that are out of scope for this memo 🦋

5.1.9.2. PIDF Elements ✨

Okay so PIDF has a few XML elements that don't have a direct match in the core XMPP specs 🥺 Two of them are the main ones to know:

<contact/> 💌 -- specifies an address (e.g., an im:, tel:, or mailto: URI) at which one may communicate with the presentity; an XMPP-CPIM gateway MAY include this element, in which case it SHOULD set its value to the <user@host> of the XMPP sender, prepended by the "im:" Instant Messaging URI scheme.
<timestamp/> ⏰ -- specifies the datetime at which the presence information was sent; an XMPP-CPIM gateway MAY independently generate this element based on its own information (e.g., the datetime at which it received the presence stanza from an XMPP entity) or based on data encoded in non-core XMPP extensions, but rules for doing so are out of scope for this memo.

5.2. Presence Syntax Mapping from CPIM Specifications to XMPP 🦋

This section defines the mapping of syntax primitives from "Message/CPIM" objects with encapsulated "application/pidf+xml" objects to XMPP presence stanzas. It's the reverse trip, bestie 🔁

Note: An XMPP-CPIM gateway MUST NOT map to an XMPP presence stanza a "Message/CPIM" object whose encapsulated MIME object has a Content-type other than "application/pidf+xml" (with the exception of multi-part MIME objects as specified in [XMPP-E2E]).

5.2.1. From Address 💕

The 'From' header of a "Message/CPIM" object maps to the <user@host> portion of the 'from' attribute of an XMPP presence stanza, and the 'id' attribute of the PIDF <tuple/> child element maps to the resource identifier portion XMPP 'from' attribute. So to map the CPIM and PIDF info to the XMPP 'from' attribute, the gateway MUST remove the "im:" Instant Messaging URI scheme from the front of the address and MUST remove the CPIM "Formal-name" (if provided) to generate the <user@host> portion of the XMPP 'from' attribute, then add a '/' character followed by the value of the PIDF <tuple/> element's 'id' attribute. ✨

Example: From Address Mapping

CPIM 'From' header
  From: Romeo Montague <im:romeo@example.net>

XMPP 'from' attribute
  <presence from='romeo@example.net'>
    ...
  </presence>

Example: Resource Identifier Mapping

XMPP 'from' attribute
  <presence from='juliet@example.com/balcony'>
    ...
  </presence>

PIDF 'id' for <tuple/>
  <presence entity='pres:juliet@example.com'>
    <tuple id='balcony'>
      ...
    </tuple>
  </presence>

5.2.2. To Address 🎯

The 'To' header of a "Message/CPIM" object maps to the 'to' attribute of an XMPP presence stanza. To map the CPIM 'To' header to the XMPP 'to' attribute, the gateway MUST remove the "im:" Instant Messaging URI scheme from the front of the address and MUST remove the CPIM "Formal-name" (if provided). If the gateway knows the resource identifier in use by the XMPP entity, the gateway MAY append the resource identifier to the address. 🧠

Example: To Address Mapping

CPIM 'To' header
  To: Juliet Capulet <im:juliet@example.com>

XMPP 'to' attribute
  <presence to='juliet@example.com/balcony'>
    ...
  </presence>

5.2.3. Courtesy Copy 🙈

The core XMPP specification doesn't include syntax for specifying a "courtesy copy" (non-primary addressee) for a presence stanza. So if an XMPP-CPIM gateway receives a "Message/CPIM" object with encapsulated PIDF object that contains a 'cc' header, it SHOULD NOT pass the information contained in that header on to the XMPP recipient. 🚫

5.2.4. DateTime Header ⏳

The core XMPP specification doesn't include syntax for specifying the datetime at which a presence stanza was sent. So if an XMPP-CPIM gateway receives a "Message/CPIM" object with encapsulated PIDF object that contains a 'DateTime' header, it SHOULD NOT pass the information contained in that header on to the XMPP recipient. 🕰️

5.2.5. Subject Header 📝

An XMPP presence stanza contains no information that can be mapped to the 'Subject' header of a "Message/CPIM" object. So if an XMPP-CPIM gateway receives a "Message/CPIM" object with encapsulated PIDF object that contains a 'Subject' header, it SHOULD NOT pass the information contained in that header on to the XMPP recipient. 🙅‍♀️

5.2.6. Header Extensions 🧩

"Message/CPIM" objects MAY include an optional 'NS' header to specify the namespace of a feature extension. An XMPP-CPIM gateway MUST NOT pass such headers through to the XMPP recipient, and no mapping for such headers is defined. 🔒

5.2.7. Require Header 🛑

"Message/CPIM" objects MAY include an optional 'Require' header to specify mandatory-to-recognize features. An XMPP-CPIM gateway MUST NOT pass such headers through to the XMPP recipient, and no mapping for such headers is defined. 💀

5.2.8. MIME Content-ID 🆔

XMPP doesn't have an element or attribute that captures a globally unique ID like the Content-ID MIME header defined in [MIME]. If an XMPP-CPIM gateway receives a MIME object that includes a Content-ID, it MAY provide the Content-ID as the value of the presence stanza's 'id' attribute, but this is OPTIONAL. 🌈

Example: Content-ID for Encapsulated Object

MIME header
  Content-ID: <123456789@example.net>

XMPP 'id' attribute (OPTIONAL)
  <presence id='123456789@example.net'>
    ...
  </presence>

5.2.9. Basic Presence Status 🟢

The basic presence status types defined in PIDF are OPEN and CLOSED. The PIDF basic presence status of OPEN maps to an XMPP presence stanza that has no 'type' attribute (indicating default availability). The PIDF basic presence status of CLOSED maps to an XMPP presence stanza that has a 'type' attribute with a value of "unavailable". 🔴

Example: OPEN Presence

PIDF basic presence (OPEN)
  <?xml version='1.0' encoding='UTF-8'?>
  <presence xmlns='urn:ietf:params:xml:ns:pidf'
            entity='pres:romeo@example.net'>
    <tuple id='orchard'>
      <status>
        <basic>open</basic>
      </status>
    </tuple>
  </presence>

XMPP available presence
  <presence from='romeo@example.net/orchard'/>

Example: CLOSED Presence

PIDF basic presence (CLOSED)
  <?xml version='1.0' encoding='UTF-8'?>
  <presence xmlns='urn:ietf:params:xml:ns:pidf'
            entity='pres:romeo@example.net'>
    <tuple id='orchard'>
      <status>
        <basic>closed</basic>
      </status>
    </tuple>
  </presence>

XMPP unavailable presence
  <presence from='romeo@example.net/orchard'
            type='unavailable'/>

5.2.10. Extended Status Information 🌸

PIDF documents may contain extended <status/> content. As of this writing there are no pre-defined extended status states that can be mapped to the defined values of the XMPP <show/> element ('away', 'chat', 'dnd', and 'xa'). Once PIDF extensions for such extended status states are defined within the Internet Standards Process, a gateway SHOULD map those extensions. However, any such mapping is out of scope for this memo, since the relevant PIDF extensions haven't been defined yet. 🔮

Example: Extended Status Information (provisional)

PIDF extended presence information
  <?xml version='1.0' encoding='UTF-8'?>
  <presence xmlns='urn:ietf:params:xml:ns:pidf'
            xmlns:im='urn:ietf:params:xml:ns:pidf:im'
            entity='pres:romeo@example.net'>
    <tuple id='orchard'>
      <status>
        <basic>open</basic>
        <im:im>busy</im:im>
      </status>
    </tuple>
  </presence>

XMPP <show/> element
  <presence from='romeo@example.net/orchard'>
    <show>dnd</show>
  </presence>

5.2.11. Note Element 📣

A PIDF <tuple/> element may contain a <note/> child that provides a user-defined, natural-language description of the sender's detailed availability state. The PIDF <note/> element maps to the XMPP <status/> element. 💬

Example: Note Element

PIDF <note/> element
  <?xml version='1.0' encoding='UTF-8'?>
  <presence xmlns='urn:ietf:params:xml:ns:pidf'
            xmlns:im='urn:ietf:params:xml:ns:pidf:im'
            entity='pres:romeo@example.net'>
    <tuple id='orchard'>
      <status>
        <basic>open</basic>
        <im:im>busy</im:im>
      </status>
      <note>Wooing Juliet</note>
    </tuple>
  </presence>

XMPP <status/> element
  <presence from='romeo@example.net/orchard'>
    <show>dnd</show>
    <status>Wooing Juliet</status>
  </presence>

A PIDF document with zero tuples MAY contain one or more <note/> elements as direct children of the PIDF <presence/> element. There is no mapping of such a PIDF document to an XMPP presence stanza. An entity on the non-XMPP side of an XMPP-CPIM gateway SHOULD NOT send such a PIDF document to an XMPP recipient if possible, and an XMPP-CPIM gateway MUST NOT map such a PIDF document to an XMPP presence stanza (see Zero Resources (Section 6.3.2)). 🚧

5.2.12. Contact Element 📇

A PIDF document may contain a <contact/> element specifying the URI of an address at which the principal can be contacted (e.g., an im:, tel:, or mailto: URI). The core XMPP specification doesn't include syntax for specifying the URI of a contact address, since the contact address is implicit in the 'from' attribute of the XMPP presence stanza. So if an XMPP-CPIM gateway receives a "Message/CPIM" object with encapsulated PIDF object that contains a <contact/> element, it SHOULD NOT pass the XML character data of the <contact/> element on to the XMPP recipient. (However, see Inclusion of Complete PIDF Document (Section 5.2.15) below.) 📬

Example: PIDF Contact Element

PIDF <contact/> element
  <?xml version='1.0' encoding='UTF-8'?>
  <presence xmlns='urn:ietf:params:xml:ns:pidf'
            entity='pres:romeo@example.net'>
    <tuple id='orchard'>
      ...
      <contact>im:romeo@example.net</contact>
    </tuple>
  </presence>

XMPP presence stanza
  <presence from='romeo@example.net/orchard'/>

5.2.13. Presence Priority 🏆

The <contact/> child of the PIDF <tuple/> element MAY have a 'priority' attribute whose value is a decimal number between zero and one (with a maximum of three decimal places). The value of this attribute MAY be mapped to the <priority/> child element of an XMPP presence stanza. An XMPP-CPIM gateway MUST NOT map PIDF priority values to negative values of the XMPP <priority/> element. If an XMPP-CPIM gateway maps these values, it SHOULD treat PIDF priority='0' as XMPP <priority>0</priority> and PIDF priority='1' as <priority>127</priority>, mapping intermediate values appropriately so that they are unique (e.g., PIDF priorities between 0.001 and 0.007 to XMPP priority 1, PIDF priorities between 0.008 and 0.015 to XMPP priority 2, and so on up through mapping PIDF priorities between 0.992 and 0.999 to XMPP priority 126; note that this is an example only, and that the exact mapping shall be determined by the XMPP-CPIM gateway). 🌟

5.2.14. Timestamp Element ⏱️

The core XMPP specification doesn't include syntax for specifying the datetime or timestamp at which a presence stanza was sent. So if an XMPP-CPIM gateway receives a "Message/CPIM" object with encapsulated PIDF object that contains a <timestamp/> element, it SHOULD NOT pass the XML character data of the <timestamp/> element on to the XMPP recipient. 🫶

5.2.15. Inclusion of Complete PIDF Document 🎀

Okay so some PIDF bits just don't fit into XMPP presence stanza syntax, like the character data inside a <contact/> element 🥺. But an XMPP client might still be able to handle that info by parsing a native PIDF document, so there's a workaround ✨. An XMPP-CPIM gateway MAY include the complete PIDF document as a child element of the presence stanza, as described in [XMPP-PIDF]. And if an XMPP client doesn't understand this extra data, it naturally MUST ignore it. That's giving "not my problem, skip" energy 💅

6. XMPP-CPIM Gateway as Presence Service 🦋

[CPP] defines semantics for an abstract presence service. An XMPP-CPIM gateway MAY function as one of those, and if it does, an XMPP entity can use defined XMPP syntax to interact with the gateway's presence service. Because [PIDF] doesn't specify syntax for semantic operations like subscribe, this section only covers the XMPP interactions with the presence service offered by an XMPP-CPIM gateway, not the translation of that XMPP syntax into PIDF 🧚

Note: Detailed information about XMPP presence services can be found in [XMPP-IM]. As much as possible, an XMPP-CPIM gateway SHOULD implement the syntax, semantics, and server business rules defined therein. 🌸

6.1. Requesting a Subscription

Okay, so if an XMPP entity wants to subscribe to the presence info of a non-XMPP presentity through an XMPP-CPIM gateway, it MUST send a presence stanza of type "subscribe" to the target presentity. Here's the syntax mapping:

The XMPP 'from' attribute (user@host) MUST be mapped to the CPP "watcher parameter" field (pres:user@host). The XMPP-CPIM gateway MUST append the pres: Presence URI scheme to the front of the address.
The XMPP 'to' attribute (user@host) MUST be mapped to the CPP "target parameter" field (pres:user@host). The XMPP-CPIM gateway MUST append the pres: Presence URI scheme to the front of the address.
There is no XMPP mapping for the CPP "duration parameter", since XMPP subscriptions stay active until they've been explicitly "unsubscribed" 💀
The XMPP 'id' attribute SHOULD be mapped to the CPP "TransID" field.

If the target presentity approves the subscription request (through whatever protocol it uses to interact with the gateway), the XMPP-CPIM gateway MUST return a presence stanza of type "subscribed" to the XMPP entity and notify the XMPP entity of the target's current available presence. From then on, until the subscription is cancelled, the gateway MUST notify the subscribing XMPP entity every time the target's presence information changes 👑

If the target presentity denies the subscription request, the XMPP-CPIM gateway MUST return a presence stanza of type "unsubscribed" to the XMPP entity and MUST NOT invoke the notify operation. Rejected is rejected 🙈

Besides approval and denial, one of the following exceptions may occur:

The target parameter (XMPP "to" address) does not refer to a valid presentity. If this exception occurs, the XMPP-CPIM gateway MUST return an <item-not-found/> stanza error to the XMPP entity.
Access control rules do not permit the entity to subscribe to the target. If this exception occurs, the XMPP-CPIM gateway MUST return a <forbidden/> stanza error to the XMPP entity.
There exists a pre-existing subscription or in-progress subscribe operation between the XMPP entity and the target presentity. If this exception occurs, the XMPP-CPIM gateway SHOULD return a <conflict/> stanza error to the XMPP entity.

XMPP services assume a subscription is active until it's explicitly terminated. However, non-XMPP services may implement subscriptions of limited duration, which must be periodically refreshed to mimic the permanence of XMPP subscriptions. So an XMPP-to-CPIM gateway may need to send those refreshes to the non-XMPP entity on behalf of the XMPP entity, so the subscription doesn't expire 🔄 Whether refreshes are necessary depends on the native protocol of the CPIM-aware non-XMPP service the gateway is translating to.

6.2. Receiving a Subscription Request

If a non-XMPP presentity wants to subscribe to the presence info of an XMPP entity through an XMPP-CPIM gateway, it MUST use whatever protocol it uses to interact with the gateway to request the subscription. Subject to local access rules, the gateway MUST then send a presence stanza of type "subscribe" to the XMPP entity from the non-XMPP watcher. The syntax mapping goes like this:

The CPP "watcher parameter" field (pres:user@host) MUST be mapped to the XMPP 'from' attribute (user@host). The XMPP-CPIM gateway MUST remove the pres: Presence URI scheme from the front of the address.
The CPP "target parameter" field (pres:user@host) MUST be mapped to the XMPP 'to' attribute (user@host). The XMPP-CPIM gateway MUST remove the pres: Presence URI scheme from the front of the address.
There is no XMPP mapping for the CPP "duration parameter", since XMPP subscriptions are active until they have been explicitly "unsubscribed" 🥀
The CPP "TransID" field SHOULD be mapped to the XMPP 'id' attribute.

If the target XMPP entity approves the subscription request, it MUST send a presence stanza of type "subscribed" to the watcher presentity. The XMPP-CPIM gateway MUST then notify the watcher presentity of the target XMPP entity's current available presence. From then on, until the subscription is cancelled, the gateway MUST notify the watcher presentity every time the target's presence information changes ✨

If the target XMPP entity denies the subscription request, it MUST send a presence stanza of type "unsubscribed" to the watcher presentity. The XMPP-CPIM gateway MUST NOT invoke the notify operation.

Besides approval and denial, one of the following exceptions MAY occur:

The target parameter (XMPP "to" address) does not refer to a valid XMPP entity
Access control rules do not permit the watcher presentity to subscribe to the target XMPP entity
There exists a pre-existing subscription or in-progress subscribe operation between the watcher presentity and the target XMPP entity

If any of these exceptions occurs, the XMPP-CPIM gateway MUST inform the watcher presentity of the failure.

XMPP services assume a subscription is active until it's explicitly terminated. Apart from handling duration parameters whose value is zero, handling duration parameters is highly dependent on the implementation and requirements of the XMPP-CPIM gateway. Since there are no explicit requirements for supporting a "duration parameter" specified in either [IMP-MODEL] or [IMP-REQS], duration parameter mapping is a local issue that falls outside the scope of this memo. However, an XMPP-CPIM gateway MAY keep track of the duration parameter if it's received from an entity on the non-XMPP service, and delete the subscription after that duration parameter expires ⏳

6.3. The Notify Operation

An XMPP-CPIM gateway invokes the CPP "notify operation" whenever the presence information associated with an XMPP entity or CPP presentity changes and there are subscribers to that information on the other side of the gateway. The syntax mapping for presence information related to a notify operation is defined under Mapping for Presence (Section 5) 📬

6.3.1. Multiple Resources

Semantically, PIDF has the notion of multiple presence "tuples". Normally a PIDF document will contain at least one tuple, but it MAY contain more than one tuple (or zero tuples, which the next section covers). In XMPP terms, each tuple would map to presence info for a separate resource. But XMPP can't send presence info about more than one resource at a time, since the resource generating the presence info is contained in the 'from' address of a presence stanza 🙃 So an XMPP-CPIM gateway that acts as a presence service SHOULD split a PIDF document with multiple tuples into multiple XMPP presence stanzas, and SHOULD generate only one PIDF document (with multiple tuples) if an XMPP user currently has multiple connected resources.

To avoid multiplying XMPP stanzas beyond necessity, an XMPP-CPIM gateway SHOULD generate an XMPP presence stanza only if the presence information in a PIDF tuple communicates a change in the availability status of the device or application associated with that tuple ID.

To follow the PIDF recommendation of putting info about multiple "resources" in multiple tuples rather than in multiple PIDF documents, an XMPP-CPIM gateway SHOULD include information about all of an XMPP user's resources in one PIDF document (with one tuple for each resource), even if the availability status of only one resource has changed 🌈

6.3.2. Zero Resources

A PIDF document may contain zero tuples. For example:

PIDF Document with Zero Tuples

<presence entity='pres:juliet@example.com'
          xmlns='urn:ietf:params:xml:ns:pidf'/>

Because (1) the 'entity' attribute of a PIDF <presence/> element maps to the <user@host> portion of an XMPP address, and (2) the 'id' attribute of a PIDF <tuple/> element maps to the resource identifier portion of an XMPP address, a PIDF document with zero tuples would provide presence info about a <user@host> rather than a <user@host/resource> when mapped to XMPP. Notifications about a mere user instead of one of their resources are pretty much meaningless in XMPP, but an XMPP-CPIM gateway SHOULD still map a PIDF document with zero tuples to an XMPP presence stanza whose 'from' address is the user@host of the non-XMPP entity. However, an XMPP-CPIM gateway MUST NOT generate a PIDF document with zero <tuple/> children when receiving a presence stanza from an XMPP entity. In other words, all PIDF documents the gateway sends to a non-XMPP service MUST contain at least one <tuple/> element 🫶

6.4. Unsubscribing

If an XMPP entity wants to unsubscribe from the presence of a non-XMPP presentity through an XMPP-CPIM gateway, it MUST send a presence stanza of type "unsubscribe" to the target presentity. The syntax mapping goes like this:

The XMPP 'from' attribute (user@host) MUST be mapped to the CPP "watcher parameter" field (pres:user@host). The XMPP-CPIM gateway MUST append the pres: Presence URI scheme to the front of the address.
The XMPP 'to' attribute (user@host) MUST be mapped to the CPP "target parameter" field (pres:user@host). The XMPP-CPIM gateway MUST append the pres: Presence URI scheme to the front of the address.
The CPP "duration parameter" MUST be set to zero.
The XMPP 'id' attribute SHOULD be mapped to the CPP "TransID" field.

If the target parameter (XMPP "to" address) does not refer to a valid presentity, the XMPP-CPIM gateway MUST return an <item-not-found/> stanza error to the XMPP entity 🔍

Once the XMPP-CPIM gateway receives the presence stanza of type "unsubscribe" from the XMPP entity, it MUST NOT send further presence notifications to that XMPP entity. Bye bye notifs 👋🦋

6.5. Cancelling a Subscription ✨

okay so, if an XMPP entity wants to cancel a non-XMPP presentity's subscription to its presence through an XMPP-CPIM gateway, it MUST send a presence stanza of type unsubscribed to the target presentity 💅. The syntax mapping goes like this:

The XMPP from attribute (user@host) MUST be mapped to the CPP "watcher parameter" field (pres:user@host). The XMPP-CPIM gateway MUST add the pres: Presence URI scheme to the front of the address 🎀
The XMPP to attribute (user@host) MUST be mapped to the CPP "target parameter" field (pres:user@host). The XMPP-CPIM gateway MUST add the pres: Presence URI scheme to the front of the address 🦋
The CPP "duration parameter" MUST be set to zero ⭐
The XMPP id attribute SHOULD be mapped to the CPP "TransID" field 🌸

Then, once the gateway gets that unsubscribed stanza from the XMPP entity, it MUST NOT send any more presence notifications to the watcher presentity. Done and done, no more updates for them 🙈💀

7. Security Considerations 🔒

okay, this part is SERIOUS bestie 😭 Detailed security considerations for instant messaging and presence protocols live in [IMP-REQS], specifically in Sections 5.1 through 5.4. Go read those too, no skipping!

This document explains how to swap instant messages and presence info through a gateway that implements [CPIM] and [CPP]. Such a gateway MUST be compliant with the minimum security requirements of the instant messaging and presence protocols it talks to 🔥. Bringing gateways into the security model of instant messaging and presence (the one in RFC 2779) also brings in some brand new risks 🥺. The big one: end-to-end security properties, especially confidentiality and integrity, between IM and presence user agents that connect through an XMPP-CPIM gateway can only be provided if common formats are supported. Those formats are fully specified in [XMPP-E2E] 🔐✨

8. References 📚

8.1. Normative References

[CPIM]       Peterson, J., "Common Profile for Instant Messaging
             (CPIM)", RFC 3860, August 2004.

[CPP]        Peterson, J., "Common Profile for Presence (CPP)", RFC
             3859, August 2004.

[IMP-MODEL]  Day, M., Rosenberg, J., and H. Sugano, "A Model for
             Presence and Instant Messaging", RFC 2778, February
             2000.

[IMP-REQS]   Day, M., Aggarwal, S., Mohr, G., and J. Vincent,
             "Instant Messaging / Presence Protocol Requirements",
             RFC 2779, February 2000.

[MIME]       Freed, N. and N. Borenstein, "Multipurpose Internet Mail
             Extensions (MIME) Part One: Format of Internet Message
             Bodies", RFC 2045, November 1996.

[MSGFMT]     Klyne, G. and D. Atkins, "Common Presence and Instant
             Messaging (CPIM): Message Format", RFC 3862, August
             2004.

[PIDF]       Sugano, H., Fujimoto, S., Klyne, G., Bateman, A., Carr,
             W., and J. Peterson, "Presence Information Data Format
             (PIDF)", RFC 3863, August 2004.

[STRINGPREP] Hoffman, P. and M. Blanchet, "Preparation of
             Internationalized Strings (stringprep)", RFC 3454,
             December 2002.

[TERMS]      Bradner, S., "Key words for use in RFCs to Indicate
             Requirement Levels", BCP 14, RFC 2119, March 1997.

[URL-GUIDE]  Masinter, L., Alvestrand, H., Zigmond, D., and R. Petke,
             "Guidelines for new URL Schemes", RFC 2718, November
             1999.

[US-ASCII]   Cerf, V., "ASCII format for network interchange", RFC
             20, October 1969.

[UTF-8]      Yergeau, F., "UTF-8, a transformation format of ISO
             10646", STD 63, RFC 3629, November 2003.

[XMPP-CORE]  Saint-Andre, P., Ed., "Extensible Messaging and Presence
             Protocol (XMPP): Core", RFC 3920, October 2004.

[XMPP-E2E]   Saint-Andre, P., Ed., "End-to-End Signing and Object
             Encryption in the Extensible Messaging and Presence
             Protocol (XMPP)", RFC 3923, October 2004.

[XMPP-IM]    Saint-Andre (ed.), P., "Extensible Messaging and
             Presence Protocol (XMPP): Instant Messaging and
             Presence", RFC 3921, October 2004.

8.2. Informative References

[RFC2822]    Resnick, P., Ed., "Internet Message Format", RFC 2822,
             April 2001.

[MIMETYPES]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
             Extensions (MIME) Part Two: Media Types", RFC 2046,
             November 1996.

[XMPP-PIDF]  Saint-Andre, P., "Transporting Presence Information
             Data/Format (PIDF) over the Extensible Messaging and
             Presence Protocol (XMPP)", Work in Progress, February
             2004.

Author's Address 🖊️

Peter Saint-Andre
Jabber Software Foundation

EMail: stpeter@jabber.org

This document is subject to the rights, licenses and restrictions in BCP 78. Except as BCP 78 sets out, the authors keep all their rights 💜.

This document and the info in it are handed over "AS IS". THE CONTRIBUTOR, THE ORGANIZATION HE/S HE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED. That includes, but isn't limited to, any warranty that using the information won't infringe any rights, and any implied warranties of merchantability or fitness for a particular purpose 😭

Intellectual Property 🧠

The IETF takes no position on whether any Intellectual Property Rights (or other rights) that someone might claim over the tech in this document are valid or in scope, or on whether licenses for them are available. It also doesn't say it has done its own independent search for those rights. For the IETF's rules on rights in its documents, check BCP 78 and BCP 79 📖

You can get copies of IPR disclosures sent to the IETF Secretariat, plus any assurances of licenses, or the results of any attempt to get a general license for implementers or users, from the IETF's online IPR repository at http://www.ietf.org/ipr.

The IETF also invites anyone to flag any copyrights, patents, patent applications, or other proprietary rights that might cover tech needed to implement this standard. Send that info to the IETF at ietf-ipr@ietf.org 🫶

Acknowledgement 🌷

Funding for the RFC Editor function is currently provided by the Internet Society. Thank you, Internet Society 👑✨

📦 where this page comes from

ietf: rfc3922 2004-10
💖 girlified by claude-haiku-5-5 on 2026-10-17: a language model's rewrite of the original, under its terms

RFC 3922

Mapping the Extensible Messaging and Presence Protocol (XMPP) to Common Presence and Instant Messaging (CPIM) 🎀

Status of This Memo 📝

Copyright Notice 💜

Abstract 🦋

Table of Contents 🧚

1. Introduction ✨

1.1. Overview 🌈

1.2. Terminology 🧁

1.3. Conventions Used in this Document 📏

2. Approach 🍓

3. Address Mapping 🗺️

3.1. Overview 🦋

3.2. XMPP to CPIM 🌸

3.3. CPIM to XMPP 💫

4. Syntax Mapping of Instant Messages 💌

4.1. Message Syntax Mapping from XMPP to CPIM Specifications 🔁

4.1.1. From Address 💖

4.1.2. To Address 📬

4.1.3. Stanza ID 🪪

4.1.4. Message Type 🎀

4.1.5. Message Thread 🧵

4.1.6. Message Subject 🌈

4.1.7. Message Body 💖

4.1.8. Message Extensions 🧩

4.1.9. Gateway-Generated CPIM Syntax 🛠️

4.2. Message Syntax Mapping from CPIM Specifications to XMPP 🔁

4.2.1. From Address 💌

4.2.2. To Address 📫

4.2.3. Courtesy Copy 🙊

4.2.4. DateTime Header 🕰️

4.2.5. Message Subject 🌺

4.2.6. Header Extensions 🎁

4.2.7. Require Header 🔒

4.2.8. MIME Content-ID 🆔

4.2.9. Message Body 💬

4.2.10. Gateway-Generated XMPP Syntax 🪄

5. Syntax Mapping of Presence Information 🧚✨

5.1. Presence Syntax Mapping from XMPP to CPIM Specifications 🎀

5.1.1. From Address 💌

5.1.2. To Address 📬

5.1.3. Stanza ID 🪪

5.1.4. Presence Type 🌈

5.1.5. Show Element 🫧

5.1.6. Status Element 📝

5.1.7. Presence Priority 👑

5.1.8. Presence Extensions 🧩

5.1.9. Gateway-Generated CPIM and PIDF Syntax 🌟

5.1.9.1. CPIM Message Headers 💖

5.1.9.2. PIDF Elements ✨

5.2. Presence Syntax Mapping from CPIM Specifications to XMPP 🦋

5.2.1. From Address 💕

5.2.2. To Address 🎯

5.2.3. Courtesy Copy 🙈

5.2.4. DateTime Header ⏳

5.2.5. Subject Header 📝

5.2.6. Header Extensions 🧩

5.2.7. Require Header 🛑

5.2.8. MIME Content-ID 🆔

5.2.9. Basic Presence Status 🟢

5.2.10. Extended Status Information 🌸

5.2.11. Note Element 📣

5.2.12. Contact Element 📇

5.2.13. Presence Priority 🏆

5.2.14. Timestamp Element ⏱️

5.2.15. Inclusion of Complete PIDF Document 🎀

6. XMPP-CPIM Gateway as Presence Service 🦋

6.1. Requesting a Subscription

6.2. Receiving a Subscription Request

6.3. The Notify Operation

6.3.1. Multiple Resources

6.3.2. Zero Resources

6.4. Unsubscribing

6.5. Cancelling a Subscription ✨

7. Security Considerations 🔒

8. References 📚

8.1. Normative References

8.2. Informative References

Author's Address 🖊️

Full Copyright Statement ©️