RFC 5025
Presence Authorization Rules
RFC 5025: Presence Authorization Rules 🎀
Okay bestie, this is RFC 5025, called Presence Authorization Rules. J. Rosenberg from Cisco wrote it, and it's a Standards Track doc from December 2007 📅. The header doesn't say it obsoletes or updates anything, so there's no other RFC it replaces or tweaks. Let's get into it 💅
Status of This Memo ✨
This doc is an Internet standards track protocol for the Internet community, and it's basically asking everyone for feedback and suggestions for improvements 🫶 Want the current standardization state and status? Check the current edition of the "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited, so share it with whoever 🌸
Abstract 🦋
Okay so, authorization is a huge deal in presence systems 👑 Authorization policies (also called authorization rules) decide what presence info goes to which watchers, and when. This spec defines an Extensible Markup Language (XML) document format for writing those rules down. Clients can edit these documents through the XML Configuration Access Protocol (XCAP), but other techniques are allowed too, so XCAP isn't the only way in 💜
Table of Contents 📚
1. Introduction ....................................................2
2. Terminology .....................................................3
3. Structure of Presence Authorization Documents ...................3
3.1. Conditions .................................................4
3.1.1. Identity ............................................4
3.1.1.1. Acceptable Forms of Authentication .........4
3.1.1.2. Computing a URI for the Watcher ............5
3.1.2. Sphere ..............................................6
3.2. Actions ....................................................7
3.2.1. Subscription Handling ...............................7
3.3. Transformations ............................................9
3.3.1. Providing Access to Data Component Elements .........9
3.3.1.1. Device Information .........................9
3.3.1.2. Person Information ........................10
3.3.1.3. Service Information .......................11
3.3.2. Providing Access to Presence Attributes ............12
3.3.2.1. Provide Activities ........................12
3.3.2.2. Provide Class .............................12
3.3.2.3. Provide DeviceID ..........................13
3.3.2.4. Provide Mood ..............................13
3.3.2.5. Provide Place-is ..........................13
3.3.2.6. Provide Place-type ........................13
3.3.2.7. Provide Privacy ...........................13
3.3.2.8. Provide Relationship ......................14
3.3.2.9. Provide Sphere ............................14
3.3.2.10. Provide Status-Icon ......................14
3.3.2.11. Provide Time-Offset ......................14
3.3.2.12. Provide User-Input .......................14
3.3.2.13. Provide Note .............................15
3.3.2.14. Provide Unknown Attribute ................15
3.3.2.15. Provide All Attributes ...................16
4. When to Apply the Authorization Policies .......................17
5. Implementation Requirements ....................................17
6. Example Document ...............................................18
7. XML Schema .....................................................19
8. Schema Extensibility ...........................................21
9. XCAP Usage .....................................................22
9.1. Application Unique ID .....................................22
9.2. XML Schema ................................................22
9.3. Default Namespace .........................................22
9.4. MIME Type .................................................22
9.5. Validation Constraints ....................................22
9.6. Data Semantics ............................................22
9.7. Naming Conventions ........................................23
9.8. Resource Interdependencies ................................23
9.9. Authorization Policies ....................................23
10. Security Considerations .......................................23
11. IANA Considerations ...........................................24
11.1. XCAP Application Usage ID ................................24
11.2. URN Sub-Namespace Registration ...........................25
11.3. XML Schema Registrations .................................25
12. Acknowledgements ..............................................26
13. References ....................................................26
13.1. Normative References .....................................26
13.2. Informative References ...................................271. Introduction ✨
Okay, so the SIP for Instant Messaging and Presence (SIMPLE) specs let a user called a watcher subscribe to another user called a presentity [17], so the watcher can learn that presentity's presence information [18] 👀 A presence agent handles this subscription. But presence info is sensitive, so the presence agent needs authorization from the presentity before it hands any of that info out 🔒 That's why we need a presence authorization document format, and this spec defines one, called a presence authorization document.
[8] defines a framework for representing authorization policies, and it works for systems like geo-location and presence 🌈 This spec builds on that framework. In the framework, an authorization policy is a set of rules, and each rule has conditions, actions, and transformations. The conditions say when the rule gets applied during presence server processing. The actions tell the server what to do. The transformations say how the presence data gets changed before it's shown to that watcher, which makes them a privacy filtering operation 🦋 [8] names a few conditions that are common to presence and location services, and it leaves the usage-specific details to other specs, like this one, to fill in.
Clients can manage a presence authorization document in a few ways. One of them is XCAP [2], and this spec explains the details you need to use XCAP for managing presence authorization documents 💖
2. Terminology 📖
In this doc, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are interpreted as described in RFC 2119 [1]. They tell you the requirement levels for compliant implementations 🎀
3. Structure of Presence Authorization Documents 🧚
A presence authorization document is an XML document, and it follows the schema defined in [8] 💅 These docs inherit the MIME type of common policy documents, which is application/auth-policy+xml. As [8] explains, the document is made of rules with three parts: conditions, actions, and transformations. Each action or transformation (also called a permission) is a positive grant of information to the watcher, so it can only add access, never take it away 🫶 Because of that, there's a well-defined way to combine actions and transformations that come from several sources. It's privacy safe, since leaving out an action or transformation can only mean the watcher sees less information 🔒✨
This section defines the new conditions, actions, and transformations that this spec introduces.
3.1. Conditions 🍓
3.1.1. Identity
Okay, here's the thing: the <identity> element is defined in [8], but that spec says each usage of the common policy framework has to define the protocol- and usage-specific details itself 🙈 So a usage of the framework needs to do two things:
- Define acceptable means of authentication.
- Define the procedure for representing the identity of the WR (Watcher/Requestor) as a URI or Internationalized Resource Identifier (IRI) [13].
This sub-section does that for systems based on [18]. It's written in general terms, so the recommendations here work for existing and future authentication mechanisms in SIP 🌸
3.1.1.1. Acceptable Forms of Authentication
When used with SIP, a request is considered authenticated if one of the following is true 🔐
The watcher proves its identity to the server through a form of cryptographic authentication, including authentication based on a shared secret or a certificate, and that authentication yields an identity for the watcher.
Or, the request comes from a sender that is asserting the identity of the watcher, and:
- the assertion includes a claim that the asserting party used a form of cryptographic authentication (as defined above) to determine the identity of the watcher, and
- the server trusts that assertion, and
- the assertion provides an identity in the form of a URI.
So based on that definition, valid authentication techniques include SIP [5], digest authentication [4], cryptographically verified identity assertions (RFC 4474 [15]), and identity assertions made in closed network environments (RFC 3325 [16]) 👑
Heads up: the anonymous authentication described on page 194 of RFC 3261 [5] is not considered a valid mechanism for authentication, because it doesn't produce an identity for the watcher 💀 However, an anonymous From header field, when used in conjunction with RFC 4474 [15], is considered an acceptable mechanism for authentication, since it still implies that the asserting node performed authentication that produced the identity of the watcher 🥹
Part 1 of 6 🦋 more parts coming next, bestie!
3.1.1.2. Computing a URI for the Watcher ✨
Figuring out the watcher's URI depends on how the identity was found: through authentication, or through an asserted identity. 🔍
If an identity assertion is being used, the asserted identity itself (which is a URI, for the acceptable forms of identity assertion) is the URI. If the assertion mechanism gives back multiple URIs for the watcher, then each one gets used for the comparisons outlined in [8]. If any of them match a <one> or <except> element, the watcher counts as a match. 🎀
If the identity is determined directly by a cryptographic authentication, that authentication must produce a URI, or it must produce some form of identifier that can be linked, through provisioning, to a URI that is bound to that identifier. 🔐
For example, with SIP Digest authentication, the authentication process produces a username scoped within a realm. That username and realm are bound to an Address of Record (AOR) through provisioning, and the resulting AOR is used as the watcher URI. Picture this "user record" in a database:
SIP AOR: sip:alice@example.com
digest username: ali
digest password: f779ajvvh8a6s6
digest realm: example.comSo if the presence server gets a SUBSCRIBE request, challenges it with the realm set to "example.com", and the follow-up SUBSCRIBE has an Authorization header field with a username of "ali" and a digest response generated with the password "f779ajvvh8a6s6", then the identity used in matching is "sip:alice@example.com". Ali is Alice, periodt 💅
In SIP systems, a user can have aliases, meaning multiple SIP AORs "assigned" to one user. In terms of this specification, there is no relationship between those aliases, so each one looks like a different user. 🙃 This is the outcome for systems where the watcher is in a different domain than the presentity. Even if the watcher and presentity are in the same domain, and the presence server knows about the watcher's aliases, those aliases are still not mapped to each other or used in any way. Not connected, not even a little bit 💀
SIP also allows anonymous requests. If a request is anonymous because the watcher used an authentication mechanism that doesn't give the presence server an identity (like the SIP digest "anonymous" username), the request is treated as unauthenticated (as discussed above), and it will only match an empty <identity> element. If a request is anonymous because it contains a Privacy header field [14], but it still has an asserted identity that meets the criteria defined above, that identity is used, and the fact that the request was anonymous has no effect on identity processing. Hiding your name doesn't mean hiding your identity, lol 🦋
Okay, and this one is a big deal: SIP uses both SIP URIs and tel URIs [12] as identifiers, and to make things extra confusing, a SIP URI can contain a phone number in its user part, in the same format you'd use in a tel URI. 😵💫 So a WR identity that is a SIP URI with a phone number will NOT match the <one> and <except> conditions whose 'id' is a tel URI with that same number. It works the other way too: if the WR identity is a tel URI, it will not match a SIP URI in the <one> or <except> conditions whose user part is a phone number. URIs with different schemes are never equivalent. Different schemes, different people, no exceptions 🌈
3.1.2. Sphere 🌸
The <sphere> element is defined in [8]. However, every application that uses the common policy specification needs to work out how the presence server computes the value of <sphere> for use in evaluating the condition. 🧩
To compute the value of <sphere>, the presence agent looks at all the published presence documents for the presentity. If at least one of them includes the <sphere> element [9] as part of the person data component [10], and all of the ones containing that element have the same value for it, that value is what's used for <sphere> in presence policy processing. If, however, the <sphere> element wasn't present in any of the published documents, or it was there but the values were inconsistent, its value is considered undefined for presence policy processing. Undefined energy, but make it make sense ✨
Be careful when using <sphere> as a condition for deciding subscription handling. Since the value of <sphere> changes dynamically, a state change can suddenly terminate a subscription. Aside from polling, the watcher has no way to know when their subscription would be reinstated as the value of <sphere> changes. That's why <sphere> is mostly useful for matching rules that define transformations. 💭
3.2. Actions 🎬
3.2.1. Subscription Handling 🔥
The <sub-handling> element specifies the subscription authorization decision the server should make. It also specifies whether or not the presence document for the watcher should be built using "polite blocking". The subscription authorization decision and polite blocking are specified together, since proper privacy handling needs a correlation between them. As discussed in [8], the combination algorithm runs independently for each permission, so if correlations exist between permissions, they must be merged into a single variable. That's exactly what happens here. The <sub-handling> element is an enumerated Integer type, and the defined values are:
block: This action tells the server to reject the subscription, putting it in the "terminated" state. It has a value of zero, and it's the default value. No value of the<sub-handling>element can ever be lower than this. Strictly speaking, a rule doesn't need an explicit block action, since the default when there's no action at all is block. It's included anyway, for completeness. 🚫confirm: This action tells the server to put the subscription in the "pending" state and wait for input from the presentity to decide how to proceed. It has a value of ten. 🤔polite-block: This action tells the server to put the subscription into the "active" state, and to produce a presence document that shows the presentity as unavailable. A reasonable document would leave out device and person information elements, and include only a single service whose basic status is set to closed [3]. This action has a value of twenty. 🙈allow: This action tells the server to put the subscription into the "active" state. This action has a value of thirty. 👑
NOTE WELL: Setting this element to block does not guarantee that a subscription is denied! If any matching rule has any other value for this element, the subscription gets treated based on the maximum of those other values. This follows the combining rules defined in [8]. Block isn't the boss here, bestie 💅
Future specifications that want to define new types of actions MUST define an entirely new action (separate from <sub-handling>), and define their own set of values for that action. A document can contain both <sub-handling> and a subscription handling action defined by a future specification. In that case, since each action is always a positive grant of information, the resulting action is the least restrictive one across both elements. Least restrictive wins, always 🦋
The exact behavior of a presence server when the sub-handling value changes can be described using the subscription processing state machine in Figure 1 of RFC 3857 [6]. 🧠
If the <sub-handling> permission changes to "block", a "rejected" event is generated into the subscription state machine for all affected subscriptions. This moves the state machine into the "terminated" state, which sends a NOTIFY to the watcher with a Subscription-State header field set to "terminated" and a reason of "rejected" [7], ending their subscription. 😢 If a new subscription comes in later, and the <sub-handling> value that applies to it is "block", the subscription processing follows the "subscribe, policy=reject" branch from the "init" state, and a 403 response to the SUBSCRIBE is generated.
If the <sub-handling> permission changes to "confirm", what happens next depends on the states of the affected subscriptions. Unfortunately, the state machine in RFC 3857 doesn't define an event for an authorization decision of "pending". If the subscription is in the "active" state, it moves back into the "pending" state. This sends a NOTIFY that updates the Subscription-State [7] to "pending". No reason is included in the Subscription-State header field, because none are defined for this case. No further documents are sent to this watcher. If the subscription is in the "pending", "waiting", or "terminated" states, nothing changes. If a new subscription comes in later, and the <sub-handling> value that applies to it is "confirm", the subscription processing follows the "subscribe, no policy" branch from the "init" state, and a 202 response to the SUBSCRIBE is generated, followed by a NOTIFY with Subscription-State set to "pending". No presence document is included in that NOTIFY. ⏳
If the <sub-handling> permission changes from "blocked" or "confirm" to "polite-block" or "allow", an "approved" event is generated into the state machine for all affected subscriptions. If the subscription was in the "pending" state, the state machine moves to the "active" state, which sends a NOTIFY with a Subscription-State header field of "active" and includes a presence document in that NOTIFY. Yay, the good vibes are back 🌈
If the subscription was in the "waiting" state, it moves into the "terminated" state. If a new subscription comes in later, and the <sub-handling> value that applies to it is "polite-block" or "allow", the subscription processing follows the "subscribe, policy=accept" branch from the "init" state, and a 200 OK response to the SUBSCRIBE is generated, followed by a NOTIFY with Subscription-State set to "active" and a presence document in the body of the NOTIFY. ✨
3.3. Transformations 🦋
The transformations defined here drive the behavior of the privacy filtering operation. Each transformation defines the visibility a watcher is granted to a particular component of the presence document. One group of transformations grants visibility to person, device, and service data elements based on identifying information for those elements. Another group provides access to particular data elements in the presence document. Two groups, one big privacy glow-up 🎀
3.3.1. Providing Access to Data Component Elements 💖
The transformations in this section provide access to person, device, and service data component elements. Once access has been granted to one of those elements, access to specific presence attributes for that element is controlled by the permissions defined in Section 3.3.2. Access to the element first, then the details, always in that order 🫶
3.3.1.1. Device Information 📱✨
okay so the <provide-devices> permission is what lets a watcher see the <device> info sitting in the presence document 👀 it's a set variable, which just means it's a bunch of members stacked together 🫶 each member is a way to point at a device or a whole group of them. this spec gives us three flavors: <class> (pick by class), <deviceID> (pick by device ID), and <occurrence-id> (pick by occurrence ID). the device ID and occurrence ID are defined in [10], so go peek there if you want the deets 💅 each member is identified by its type (class, deviceID, or occurrence-id) and its value (the value of the class, the value of the deviceID, or the value of the occurrence-id).
let's look at an example 🎀 say we have this <provide-devices> element:
<provide-devices>
<deviceID>urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6</deviceID>
<class>biz</class>
</provide-devices>that set has two members. now imagine it gets combined with a <provide-devices> element from a different rule:
<provide-devices>
<class>home</class>
<class>biz</class>
</provide-devices>the result of the set combination (using the union operation) is a set with three elements 🌈
<provide-devices>
<class>home</class>
<class>biz</class>
<deviceID>urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6</deviceID>
</provide-devices>the <provide-devices> element can also take on the special value <all-devices>, which is basically shorthand for every device occurrence present in the presence document 💖
permission is granted to see a particular device occurrence if one of the device identifiers in the set identifies that device occurrence. if a <class> permission is granted to the watcher and the class of the device occurrence matches the value of that <class> permission based on case-sensitive equality, the device occurrence gets included in the presence document. if a <deviceID> permission is granted and the deviceID of the device occurrence matches the value of that permission based on URI equivalence, same deal, it's in. if an <occurrence-id> permission is granted and the occurrence-id matches based on case-sensitive equality, it's included too. and a device occurrence is also included if the <all-devices> permission was granted to the watcher ✨
3.3.1.2. Person Information 🧚
the <provide-persons> permission lets a watcher see the <person> information in the presence document. it's also a set variable, and each member of the set gives a way to identify a person occurrence 🌸 this spec defines two types of elements in the set: <class>, which identifies a person occurrence by class, and <occurrence-id>, which identifies an occurrence by its occurrence ID. each member is identified by its type (class or occurrence-id) and its value (the value of the class or the value of the occurrence-id). the <provide-persons> element can also take on the special value <all-persons>, which is a short-hand notation for all person occurrences present in the presence document. the set combination is done identically to the <provide-devices> element, so no new drama there 🙃
permission is granted to see a particular person occurrence if one of the person identifiers in the set identifies that person occurrence. if a <class> permission is granted to the watcher and the class of the person occurrence matches the value of the <class> permission based on case-sensitive equality, the person occurrence is included in the presence document. if an <occurrence-id> permission is granted and the occurrence-id of the person occurrence matches the value of the <occurrence-id> permission based on case-sensitive equality, it's included as well. and a person occurrence is also included if the <all-persons> permission was granted to the watcher 💅
3.3.1.3. Service Information 🦋
the <provide-services> permission lets a watcher see service information present in <tuple> elements in the presence document. like <provide-devices>, it's a set variable, and each member gives a way to identify a service occurrence 🫶 this spec defines four types of elements in the set: <class>, which identifies a service occurrence by class; <occurrence-id>, which identifies a service by its occurrence ID; <service-uri>, which identifies a service by its service URI; and <service-uri-scheme>, which identifies a service by its service URI scheme. each member is identified by its type (class, occurrence-id, service-uri, or service-uri-scheme) and its value (the value of the class, the value of the occurrence-id, the value of the service-uri, or the value of the service-uri-scheme). the <provide-services> element can also take on the special value <all-services>, which is a short-hand notation for all service occurrences present in the presence document. the set combination is done identically to the <provide-persons> element 🌈
permission is granted to see a particular service occurrence if one of the service identifiers in the set identifies that service occurrence. if a <class> permission is granted to the watcher and the class of the service occurrence matches the value of the <class> permission based on case-sensitive equality, the service occurrence is included in the presence document. if a <service-uri> permission is granted and the service-uri of the service occurrence matches the value of that permission based on URI equivalence, it's included. if an <occurrence-id> permission is granted and the occurrence-id of the service occurrence matches based on case-sensitive equality, it's in. if a <service-uri-scheme> permission is granted and the scheme of the service URI for the service occurrence matches the value of <service-uri-scheme> based on case-sensitive equality, it's included too. and a service occurrence is also included if the <all-services> permission was granted to the watcher 🔥
3.3.2. Providing Access to Presence Attributes ✨
the permissions in Section 3.3.1 are the coarse-grained, big-picture stuff 🌸 they decide which specific services or devices get through, and which person information gets through, by allowing or blocking them.
once person, device, or service information is included in the document, the permissions in this section decide which presence attributes are reported there 💜 certain information is always reported, no matter what. specifically, the <contact>, <service-class> [9], <basic> status, and <timestamp> elements in all <tuple> elements, if present, are provided to watchers. the <timestamp> element in all <person> elements, if present, is provided to watchers. and the <timestamp> and <deviceID> elements in all <device> elements, if present, are provided to all watchers 🙈
3.3.2.1. Provide Activities 🏃♀️
this permission controls access to the <activities> element defined in [9]. the name of the element providing this permission is <provide-activities>, and it's a Boolean type. if its value is TRUE, then the <activities> element in the person data element is reported to the watcher. if FALSE, this presence attribute is removed if present 💅
3.3.2.2. Provide Class 🎀
this permission controls access to the <class> element defined in [9]. the name of the element providing this permission is <provide-class>, and it's a Boolean type. if its value is TRUE, then any <class> element in a person, service, or device data element is reported to the watcher. if FALSE, this presence attribute is removed if present ✨
3.3.2.3. Provide DeviceID 🧸
this permission controls access to the <deviceID> element in a <tuple> element, as defined in [9]. the name of the element providing this permission is <provide-deviceID>, and it's a Boolean type. if its value is TRUE, then the <deviceID> element in the service data element is reported to the watcher. if FALSE, this presence attribute is removed if present. quick note though: the <deviceID> in a device data element is always included, and this permission doesn't control it 🙃
3.3.2.4. Provide Mood 🌈
this permission controls access to the <mood> element defined in [9]. the name of the element providing this permission is <provide-mood>, and it's a Boolean type. if its value is TRUE, then the <mood> element in the person data element is reported to the watcher. if FALSE, this presence attribute is removed if present 💖
3.3.2.5. Provide Place-is 📍
this permission controls access to the <place-is> element defined in [9]. the name of the element providing this permission is <provide-place-is>, and it's a Boolean type. if its value is TRUE, then the <place-is> element in the person data element is reported to the watcher. if FALSE, this presence attribute is removed if present 🫶
3.3.2.6. Provide Place-type 🏡
this permission controls access to the <place-type> element defined in [9]. the name of the element providing this permission is <provide-place-type>, and it's a Boolean type. if its value is TRUE, then the <place-type> element in the person data element is reported to the watcher. if FALSE, this presence attribute is removed if present 🌸
3.3.2.7. Provide Privacy 🔒
this permission controls access to the <privacy> element defined in [9]. the name of the element providing this permission is <provide-privacy>, and it's a Boolean type. if its value is TRUE, then the <privacy> element in the person or service data element is reported to the watcher. if FALSE, this presence attribute is removed if present 👑
3.3.2.8. Provide Relationship 💞
this permission controls access to the <relationship> element defined in [9]. the name of the element providing this permission is <provide-relationship>, and it's a Boolean type. if its value is TRUE, then the <relationship> element in the service data element is reported to the watcher. if FALSE, this presence attribute is removed if present 🦋
3.3.2.9. Provide Sphere 🌙
this permission controls access to the <sphere> element defined in [9]. the name of the element providing this permission is <provide-sphere>, and it's a Boolean type. if its value is TRUE, then the <sphere> element in the person data element is reported to the watcher. if FALSE, this presence attribute is removed if present ✨
3.3.2.10. Provide Status-Icon 🖼️
this permission controls access to the <status-icon> element defined in [9]. the name of the element providing this permission is <provide-status-icon>, and it's a Boolean type. if its value is TRUE, then any <status-icon> element in the person or service data element is reported to the watcher. if FALSE, this presence attribute is removed if present 💅
3.3.2.11. Provide Time-Offset ⏰
okay so this permission is the gatekeeper for the <time-offset> element from [9] 💅 The element that controls it is <provide-time-offset>, and it's a Boolean, so it's just TRUE or FALSE 🎀
- If it's TRUE, the <time-offset> element in the person data element gets shown to the watcher 🦋
- If it's FALSE, that presence attribute gets removed (if it's even there) 🙈
3.3.2.12. Provide User-Input ⌨️
this one controls the <user-input> element from [9] ✨ The element is <provide-user-input>, and it's an enumerated integer type, which means it picks one of four values. That value decides what info goes to watchers in person, device, or service data elements 👑
false: <user-input> gets removed from the document. Its numeric value is 0 💀bare: <user-input> stays, but any "idle-threshold" and "since" attributes get removed. Its numeric value is 10 🌸thresholds: <user-input> stays, and only the "idle-threshold" attribute stays with it. Its numeric value is 20 🧚full: <user-input> stays, attributes and all. Its numeric value is 30 🌈
3.3.2.13. Provide Note 📝
this permission controls access to the <note> element from [3] for <tuple>, and from [10] for <person> and <device> 💜 The element is <provide-note>, and it's Boolean. If it's TRUE, any <note> elements in the person, service, or device data elements get reported to the watcher. If it's FALSE, the presence attribute gets removed if it's there 🫶
ngl this one has a twist 👀 <provide-note> has NO say over any <note> values inside <activities>, <mood>, <place-is>, <place-type>, <privacy>, <relationship>, or <service-class>. Those notes are basically the value of their parent element, so they show up whenever that parent element is allowed in the presence document 😭
For example, say an <activities> element is in the presence document and it has a <note>. That note goes to the watcher if <provide-activities> is given, even if <provide-note> is NOT given. iykyk 💅
3.3.2.14. Provide Unknown Attribute 🧩
okay this is my favourite one, honestly 😭 Systems need to be able to send proprietary or brand-new presence info, and users need to be able to set permissions on it, without the presence server and authorization system having to be upgraded first 💖 That's why <provide-unknown-attribute> exists. It says the unknown presence attribute with the given name and namespace should be included in the document. The name and namespace are supplied as mandatory attributes on the element, and the permission is Boolean 🦋
The value of the name attribute MUST be an unqualified element name, so a namespace prefix MUST NOT be included. The value of the ns attribute MUST be a namespace URI. Put together, they make a qualified element name, and that gets matched to every unknown child element of the Presence Information Data Format (PIDF) <tuple>, <device>, or <person> elements with the same qualified name 🔥 Here, "unknown" just means the presence server doesn't know any schemas that define authorization policies for that element. So by definition, this rule will NOT apply to the presence status extensions defined by RPID, because their authorization policies are defined right here 🎀
Here's the plot twist 🌪️ The meaning of <provide-unknown-attribute> can change if the presence server gets upgraded. Imagine a server that had an authorization document using <provide-unknown-attribute> set to TRUE for an attribute called foo. Back then the server didn't know that namespace or schema, so foo got shared with watchers 🙈 After an upgrade, though, the server now knows a namespace and schema with a permission that covers foo. Now that <provide-unknown-attribute> permission for foo gets ignored, and those elements get removed from presence documents sent to watchers. The system stays privacy safe, but the behaviour might not be what anyone expected 😬
So developers of systems that let clients set policies are advised to check the server's capabilities (using the mechanism in Section 8) before uploading a new authorization document. That way they can make sure the behaviour will be what they expect ✨
3.3.2.15. Provide All Attributes 👑
this permission is the big one: it grants access to all presence attributes in all the person, device, and tuple elements that are in the document. Which elements are in the document depends on the <provide-persons>, <provide-devices>, and <provide-services> permissions 💅 It's basically a macro that expands into every single permission: provide-activities, provide-class, provide-deviceID, provide-mood, provide-place-is, provide-place-type, provide-privacy, provide-relationship, provide-sphere, provide-status-icon, provide-time-offset, provide-user-input, provide-note, and provide-unknown-attribute. Each presence attribute in the document ends up with its own permission 🌈
What that means is, as long as a whole person, service, or device occurrence is provided, every single presence attribute gets granted to the watcher. That includes ones the server doesn't know about, and ones from future presence document extensions too 🧚 Main character energy, but also be careful 🫣
4. When to Apply the Authorization Policies ⏳
this spec doesn't say exactly when the privacy filtering parts of the authorization policy have to happen while presence data is processed 🤷♀️ BUT they do have to be applied so that the final presence document sent to the watcher follows the privacy policy in the authorization documents that apply to the user. There can be more than one of those, and the rules for combining them are in [8] 💜
Here's the more precise version. Say the presence document sent to a watcher is D, and applying the privacy filtering operation to a presence document x gives F(x). Then D MUST have the property that D = F(D). In other words, running the filter again wouldn't change the presence document at all, so filtering again is a no-op. A corollary of this is that F(F(D)) = D for all D 🔥
The subscription processing parts of the document get applied by the server when it decides whether to accept or reject the subscription 🎀
5. Implementation Requirements 🤝
okay so the rules in this document form a "contract" of sorts between the client that creates the document and the server that runs the policies inside it 🫶 Because of that, presence servers implementing this spec MUST support all of the conditions, actions, and transformations defined here. If servers only did a subset, clients would need a way to find out which subset is supported, and no such mechanism is defined 😭
It is RECOMMENDED that clients support all of the actions, transformations, and conditions defined in this spec. Here's why it matters: if a client only supports a subset, a user could edit their authorization rules from a different client that supports a different subset, and store those results on the server. Then when they go back to the first client, it might not be able to properly render or manipulate the document it gets from the server, since the document could contain conditions, actions, or transformations that client doesn't support 🙈 The only reason this requirement isn't a MUST is that there are valid situations where a user only ever manipulates their rules from one client, and then this problem never comes up 💅
This spec makes no normative recommendations on how presence authorization documents get transported from clients to their servers. Section 9 does define how to use XCAP, but XCAP is NOT normatively required by this spec 🦋
6. Example Document 🌸
this is a presence authorization document for the user "user@example.com" 💖 The watcher is allowed to access presence information (that's the 'allow' value for <sub-handling>). They get access to the presence data of all services whose contact URI schemes are sip and mailto ✨ Person information is shared too. BUT since there's no <provide-devices>, no device information goes to the watcher 🙅♀️ Inside the service and person info the watcher gets, the <activities> element shows up, and so does the <user-input> element. However, any "idle-threshold" and "since" attributes in <user-input> get removed 🧹 Last but not least, the presence attribute <foo> gets shown to the watcher, and any other presence attributes get removed 🎀
<?xml version="1.0" encoding="UTF-8"?>
<cr:ruleset xmlns="urn:ietf:params:xml:ns:pres-rules"
xmlns:pr="urn:ietf:params:xml:ns:pres-rules"
xmlns:cr="urn:ietf:params:xml:ns:common-policy">
<cr:rule id="a">
<cr:conditions>
<cr:identity>
<cr:one id="sip:user@example.com"/>
</cr:identity>
</cr:conditions>
<cr:actions>
<pr:sub-handling>allow</pr:sub-handling>
</cr:actions>
<cr:transformations>
<pr:provide-services>
<pr:service-uri-scheme>sip</pr:service-uri-scheme>
<pr:service-uri-scheme>mailto</pr:service-uri-scheme>
</pr:provide-services>
<pr:provide-persons>
<pr:all-persons/>
</pr:provide-persons>
<pr:provide-activities>true</pr:provide-activities>
<pr:provide-user-input>bare</pr:provide-user-input>
<pr:provide-unknown-attribute
ns="urn:vendor-specific:foo-namespace"
name="foo">true</pr:provide-unknown-attribute>
</cr:transformations>
</cr:rule>
</cr:ruleset>7. XML Schema ✨
Okay bestie, here's the schema 🧚 It's the exact blueprint for the permission documents, so I'm keeping every single character the same.
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="urn:ietf:params:xml:ns:pres-rules"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:cr="urn:ietf:params:xml:ns:common-policy"
xmlns:pr="urn:ietf:params:xml:ns:pres-rules"
elementFormDefault="qualified" attributeFormDefault="unqualified">
<xs:import namespace="urn:ietf:params:xml:ns:common-policy"/>
<xs:simpleType name="booleanPermission">
<xs:restriction base="xs:boolean"/>
</xs:simpleType>
<xs:element name="service-uri-scheme" type="xs:token"/>
<xs:element name="class" type="xs:token"/>
<xs:element name="occurrence-id" type="xs:token"/>
<xs:element name="service-uri" type="xs:anyURI"/>
<xs:complexType name="provideServicePermission">
<xs:choice>
<xs:element name="all-services">
<xs:complexType/>
</xs:element>
<xs:sequence minOccurs="0" maxOccurs="unbounded">
<xs:choice>
<xs:element ref="pr:service-uri"/>
<xs:element ref="pr:service-uri-scheme"/>
<xs:element ref="pr:occurrence-id"/>
<xs:element ref="pr:class"/>
<xs:any namespace="##other" processContents="lax"/>
</xs:choice>
</xs:sequence>
</xs:choice>
</xs:complexType>
<xs:element name="provide-services"
type="pr:provideServicePermission"/>
<xs:element name="deviceID" type="xs:anyURI"/>
<xs:complexType name="provideDevicePermission">
<xs:choice>
<xs:element name="all-devices">
<xs:complexType/>
</xs:element>
<xs:sequence minOccurs="0" maxOccurs="unbounded">
<xs:choice>
<xs:element ref="pr:deviceID"/>
<xs:element ref="pr:occurrence-id"/>
<xs:element ref="pr:class"/>
<xs:any namespace="##other" processContents="lax"/>
</xs:choice>
</xs:sequence>
</xs:choice>
</xs:complexType>
<xs:element name="provide-devices"
type="pr:provideDevicePermission"/>
<xs:complexType name="providePersonPermission">
<xs:choice>
<xs:element name="all-persons">
<xs:complexType/>
</xs:element>
<xs:sequence minOccurs="0" maxOccurs="unbounded">
<xs:choice>
<xs:element ref="pr:occurrence-id"/>
<xs:element ref="pr:class"/>
<xs:any namespace="##other" processContents="lax"/>
</xs:choice>
</xs:sequence>
</xs:choice>
</xs:complexType>
<xs:element name="provide-persons"
type="pr:providePersonPermission"/>
<xs:element name="provide-activities"
type="pr:booleanPermission"/>
<xs:element name="provide-class"
type="pr:booleanPermission"/>
<xs:element name="provide-deviceID"
type="pr:booleanPermission"/>
<xs:element name="provide-mood"
type="pr:booleanPermission"/>
<xs:element name="provide-place-is"
type="pr:booleanPermission"/>
<xs:element name="provide-place-type"
type="pr:booleanPermission"/>
<xs:element name="provide-privacy"
type="pr:booleanPermission"/>
<xs:element name="provide-relationship"
type="pr:booleanPermission"/>
<xs:element name="provide-status-icon"
type="pr:booleanPermission"/>
<xs:element name="provide-sphere"
type="pr:booleanPermission"/>
<xs:element name="provide-time-offset"
type="pr:booleanPermission"/>
<xs:element name="provide-user-input">
<xs:simpleType>
<xs:restriction base="xs:string">
<xs:enumeration value="false"/>
<xs:enumeration value="bare"/>
<xs:enumeration value="thresholds"/>
<xs:enumeration value="full"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:element name="provide-note" type="pr:booleanPermission"/>
<xs:element name="sub-handling">
<xs:simpleType>
<xs:restriction base="xs:token">
<xs:enumeration value="block"/>
<xs:enumeration value="confirm"/>
<xs:enumeration value="polite-block"/>
<xs:enumeration value="allow"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
<xs:complexType name="unknownBooleanPermission">
<xs:simpleContent>
<xs:extension base="pr:booleanPermission">
<xs:attribute name="name" type="xs:string" use="required"/>
<xs:attribute name="ns" type="xs:string" use="required"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
<xs:element name="provide-unknown-attribute"
type="pr:unknownBooleanPermission"/>
<xs:element name="provide-all-attributes">
<xs:complexType/>
</xs:element>
</xs:schema>8. Schema Extensibility 🦋
Okay so future changes to this spec are supposed to happen through extensions that define brand new types of permissions 💅 These extensions MUST exist within a different namespace. On top of that, the schema above and the namespace for the elements defined in it MUST NOT be altered by future specifications. If the basic schema, or how its elements get interpreted, changes, it could literally mess with user privacy because documents get misread 😭
When the set of permissions gets extended, the agent building the permission document (typically a SIP user agent, though not necessarily) needs to know which permissions the server supports 🫶 That way it knows how to build a document that actually gets the behavior it wants, since unknown permissions just get ignored by the server. So when presence authorization documents are transported using XCAP, the XCAP capabilities document stored at the server SHOULD contain the namespaces for the permissions the presence server supports. Then an agent can check that list before it builds a document. Smart, right? ✨
9. XCAP Usage 🎀
This section has all the details clients need to manipulate presence authorization documents from a server using XCAP. Let's go 🌸
9.1. Application Unique ID
XCAP requires application usages to define a unique application usage ID (AUID) in either the IETF tree or a vendor tree. This specification defines the pres-rules AUID within the IETF tree, via the IANA registration in Section 11.
9.2. XML Schema
XCAP requires application usages to define a schema for their documents. The schema for presence authorization documents is in Section 7 💖
9.3. Default Namespace
XCAP requires application usages to define the default namespace for their URIs. The default namespace is urn:ietf:params:xml:ns:pres-rules.
9.4. MIME Type
XCAP requires application usages to define the MIME type for documents they carry. Presence authorization documents inherit the MIME type of common policy documents, application/auth-policy+xml.
9.5. Validation Constraints
There are no additional constraints defined by this specification. Easy 🍓
9.6. Data Semantics
Semantics of a presence authorization document are discussed in Section 3.
9.7. Naming Conventions
When a presence agent receives a subscription for some user foo within a domain, it will look for all documents within http://[xcap root]/pres-rules/users/foo, and use all documents found beneath that point to guide authorization policy. If only a single document is used, it SHOULD be called index 📂
9.8. Resource Interdependencies
There are no additional resource interdependencies defined by this application usage. Nothing to see here, bestie 🙈
9.9. Authorization Policies
This application usage does not modify the default XCAP authorization policy, which is that only a user can read, write, or modify their own documents. A server can allow privileged users to modify documents that they don't own, but the establishment and indication of such policies are outside the scope of this document.
10. Security Considerations 🔥
Okay this section is SERIOUS, so read it carefully 😭
Presence authorization policies contain very sensitive information. They indicate which other users are "liked" or "disliked" by a user. As such, when these documents are transported over a network, they SHOULD be encrypted.
Modification of these documents by an attacker can disrupt the service seen by a user, often in subtle ways. As a result, when these documents are transported, the transport SHOULD provide authenticity and message integrity.
In the case where XCAP is used to transfer the document, both clients and servers MUST implement HTTP over Transport Layer Security (TLS) and HTTP Digest authentication. Sites SHOULD authenticate clients using digest authentication over TLS, and sites SHOULD define the root services URI as an https URI.
Authorization documents themselves exist for the purposes of providing a security function, which is privacy 🔒 The SIP presence specifications [18] require the usage of an authorization function prior to the granting of presence information, and this specification meets that need. Presence authorization documents inherit the privacy properties of the common policy format on which they are based. This format has been designed to be privacy-safe, which means that failure of the presence server to obtain or understand an authorization document can never reveal more information than is desired about the user, only less. This is a consequence of the fact that all permissions are positive grants of information, and not negative grants.
A consequence of this design is that the results of combining several authorization documents can be non-obvious to end users. For example, if one authorization document grants permission for all users from the example.com domain to see their presence, and another document blocks joe@example.com, the combination of these will still provide presence to joe@example.com. Designers of user interfaces are encouraged to carefully pay attention to the results of combining multiple rules 👀
Another concern is cases where a user sets their privacy preferences from one client, uploads their presence authorization document to a server, and then modifies them from a different client. If the clients support different subsets of the document format, users may be confused about what information is being revealed. Clients retrieving presence authorization documents from a server SHOULD render, to the users, information about rules that they do not understand, so that users can be certain what rules are in place 🫶
11. IANA Considerations 👑
There are several IANA considerations associated with this specification.
11.1. XCAP Application Usage ID
This section registers an XCAP Application Usage ID (AUID) according to the IANA procedures defined in [2].
Name of the AUID: pres-rules
Description: Presence rules are documents that describe the permissions that a presentity [17] has granted to users that seek to watch their presence.
11.2. URN Sub-Namespace Registration
This section registers a new XML namespace, per the guidelines in [11]
URI: The URI for this namespace is urn:ietf:params:xml:ns:pres-rules.
Registrant Contact: IETF, SIMPLE working group (simple@ietf.org), Jonathan Rosenberg (jdrosen@jdrosen.net).
XML:
BEGIN
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.0//EN"
"http://www.w3.org/TR/xhtml-basic/xhtml-basic10.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type"
content="text/html;charset=iso-8859-1"/>
<title>Presence Rules Namespace</title>
</head>
<body>
<h1>Namespace for Permission Statements</h1>
<h2>urn:ietf:params:xml:ns:pres-rules</h2>
<p>See <a href="http://www.rfc-editor.org/rfc/rfc5025.txt">
RFC5025</a>.</p>
</body>
</html>
END11.3. XML Schema Registrations ✨
okay so this section registers an XML schema following the procedures in [11] 🎀. the schema gets this URI: urn:ietf:params:xml:schema:pres-rules 💖
the registrant contacts are the IETF SIMPLE working group (simple@ietf.org) and Jonathan Rosenberg (jdrosen@jdrosen.net) 🫶. the XML for this schema is the sole content of Section 7, so go check there if you want the actual schema bits 🌸
12. Acknowledgements 🦋
the author thanks Richard Barnes, Jari Urpalainen, Jon Peterson, and Martin Hynar for their comments 💜 they're the real MVPs fr fr 👑
13. References 📚
13.1. Normative References 💅
- [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. 🔑 this is the one that defines the BCP 14 key words, so it's giving foundation vibes ✨
- [2] Rosenberg, J., "The Extensible Markup Language (XML) Configuration Access Protocol (XCAP)", RFC 4825, May 2007. 🎀
- [3] Sugano, H., Fujimoto, S., Klyne, G., Bateman, A., Carr, W., and J. Peterson, "Presence Information Data Format (PIDF)", RFC 3863, August 2004. 🌈
- [4] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, June 1999. 🔐
- [5] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: Session Initiation Protocol", RFC 3261, June 2002. 📞
- [6] Rosenberg, J., "A Watcher Information Event Template-Package for the Session Initiation Protocol (SIP)", RFC 3857, August 2004. 👀
- [7] Roach, A., "Session Initiation Protocol (SIP)-Specific Event Notification", RFC 3265, June 2002. 🔔
- [8] Schulzrinne, H., Tschofenig, H., Morris, J., Cuellar, J., Polk, J., and J. Rosenberg, "Common Policy: A Document Format for Expressing Privacy Preferences", RFC 4745, February 2007. 🙈
- [9] Schulzrinne, H., Gurbani, V., Kyzivat, P., and J. Rosenberg, "RPID: Rich Presence Extensions to the Presence Information Data Format (PIDF)", RFC 4480, July 2006. ⭐
- [10] Rosenberg, J., "A Data Model for Presence", RFC 4479, July 2006. 🧚
- [11] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. 🍓 this is the registry procedure section 11.3 leans on, so it's iconic 💖
- [12] Schulzrinne, H., "The tel URI for Telephone Numbers", RFC 3966, December 2004. ☎️
- [13] Duerst, M. and M. Suignard, "Internationalized Resource Identifiers (IRIs)", RFC 3987, January 2005. 🌐
- [14] Peterson, J., "A Privacy Mechanism for the Session Initiation Protocol (SIP)", RFC 3323, November 2002. 🫣
13.2. Informative References 🌸
- [15] Peterson, J. and C. Jennings, "Enhancements for Authenticated Identity Management in the Session Initiation Protocol (SIP)", RFC 4474, August 2006. 🪪
- [16] Jennings, C., Peterson, J., and M. Watson, "Private Extensions to the Session Initiation Protocol (SIP) for Asserted Identity within Trusted Networks", RFC 3325, November 2002. 🛡️
- [17] Day, M., Rosenberg, J., and H. Sugano, "A Model for Presence and Instant Messaging", RFC 2778, February 2000. 💬
- [18] Rosenberg, J., "A Presence Event Package for the Session Initiation Protocol (SIP)", RFC 3856, August 2004. 🦄
Author's Address 🏡
Jonathan Rosenberg Cisco Edison, NJ US
EMail: jdrosen@cisco.com URI: http://www.jdrosen.net
Full Copyright Statement ⚖️
Copyright (C) The IETF Trust (2007).
This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.
This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property 💎
The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.
📦 where this page comes from
- ietf: rfc5025 2007-12
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms