XCAP Tutorial Jonathan Rosenberg. Ground Rules This is a session for level setting –People are at different points –We will start from the beginning NO

XCAP Tutorial

Jonathan Rosenberg

Ground Rules

• This is a session for level setting– People are at different points– We will start from the beginning

• NO QUESTION IS TOO STUPID

• Disrespect will not be tolerated

• Please interrupt and ask– PLEASE!

Agenda

• Understanding XML– Basic XML Concepts– Namespaces– Schema– XPath in Brief

• HTTP Concepts of Note– Etags

• XCAP Problem Definition

• XCAP Basics

XML Basics

• XML is a mechanism for representing structured data

• Data is represented by a tree

• Each node in the tree is an element

• Elements have attributes– Attributes qualify the data

• “Leaf” Elements can contain text content

<?xml version="1.0" encoding="UTF-8"?> <address-book> <!—This guy is a bozo -- <entry> <name>Jonathan Rosenberg</name> <email>[email protected]</email> <postal> <street paved=“true”>600 Lanidex Pl</street> <city>Parsippany</city> <state>NJ</state> <country>USA</country> </postal> <ietf-participant/> </entry> </address-book>

XML Basics

• XML Comments• Elements can be

empty– <el-name/> shorthand

• XML Declaration– Version– Encoding

• IETF uses UTF-8


XML Terms

• Well-formed– Meets basic constraints for all XML

documents– Each open tag has a matching close– Unique attribute names

• Valid– Meets the constraints defined by a schema or

DTD

XML Namespaces

• Problem– Want to combine content

from different systems into one document

– What if both sources define the same name?

• Example– Add information to address

book on whether data is synced with PC

– <state>synchronized</state>

– Which state is it?


XML Namespaces

• Solution: XML Namespace

• Elements and attributes are bound to a namespace when defined

• Namespace is identified with a unique URI

• A prefix is bound to that URI through a declaration in the document

• Each element is named with its qualified name– The prefix, followed by a

colon, followed by the local-name

<?xml version="1.0" encoding="UTF-8"? xmlns:post=“http://www.post.com” xmlns:sync=“http://www.sync.com”> <post:address-book> <!—This guy is a bozo -- <post:entry> <post:name>Jonathan Rosenberg</post:name> <post:email>[email protected]</post:email> <post:postal> <post:street paved=“true”>600 Lanidex Pl</post:street> <post:city>Parsippany</post:city> <post:state>NJ</post:state> <post:country>USA</post:country> </post:postal> <post:ietf-participant/> <sync:state>synchronized</sync:state> </entry> </address-book>

http://www.post.com/


Importance of Namespaces

• Namespaces are like option tags in SIP– Group a bunch of things together and give it a

name– Are useful for talking about extensibility– Are useful for negotiating extensibility

• Provide a generic grouping facility

XML Schema• Need a way to define the constraints on an XML document

– Analagous to a database schema– Similar to a grammar

• W3C has specified two ways– DTD

• Original method• Not an XML document• Limited expressiveness

– Schema• Newer• XML-based• Much more expressive• Much more complex• Works well with namespaces

• Trend is towards schema

Schema Example<?xml version="1.0" encoding="UTF-8"?><xs:schema targetNamespace="http://www.post.com" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://www.post.com" elementFormDefault="qualified" attributeFormDefault="unqualified"> <xs:element name="address-book"> <xs:complexType> <xs:sequence> <xs:element name="entry" minOccurs="0" maxOccurs="unbounded"> <xs:complexType> <xs:sequence> <xs:element name="name" type="xs:string"/> <xs:element name="email" type="xs:string"/> <xs:element name="postal"> <xs:complexType> <xs:sequence> <xs:element name="street" type="xs:string"/> <xs:element name="city" type="xs:string"/> <xs:element name="state"> <xs:simpleType> <xs:restriction base="xs:string"> <xs:enumeration value="NJ"/> <xs:enumeration value="NY"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="country" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:element> <xs:element name="ietf-participant"/> </xs:sequence> </xs:complexType> </xs:element> </xs:sequence> </xs:complexType> </xs:element></xs:schema>

XPath

• XCAP selection is based on XPath– Happens to be a subset– Not a normative usage

• XPath problem statement– How to point to specific pieces of an XML document– Example: “The third element named entry”– Example: “All of the elements in a document that have

the attribute paved equal to true.”

• XPath = XML Addressing

Basic Example

• Want to point to the email element

• XPath expressionaddress-book/entry/email

• Just like a unix filesystem path

• Each “directory” identifies an element name

<?xml version="1.0" encoding="UTF-8"? xmlns:post=“http://www.post.com” xmlns:sync=http://www.sync.com xmlns=“http://www.post.com”> <address-book> <!—This guy is a bozo -- <entry> <name>Jonathan R<name> <email>[email protected]</email> <postal> <street paved=“true”>600 Lx Pl</street> <city>Parsippany</city> <state>NJ</state> <country>USA</country> </postal> <ietf-participant/> <sync:state>synchronized</sync:state> </entry> </address-book>



http://www.sync.com/

Positional Selectors

• What if there are multiple elements with that name?– Can supply predicates which

select one of the matching ones

– Predicates appear in square brackets

• One such predicate is position– Indicates which one by its

place in the ordered sequence of matching elements

• Select second bar:foo/bar[2]

• Select first bar:foo/bar[1]

<foo> <bar>Hello</bar> <bar>There</bar></foo>

Select by Attribute Name

• You can select elements that have attributes with specific values

element[@name=“value”]

• foo/bar[@attr=“1”]• foo/bar[@attr=“2”]• foo/bar[@stuff=“LOTR”]

<foo> <bar attr=“1”>Hi</bar> <bar attr=“2”>How</bar> <bar stuff=“LOTR”>Are</bar></foo>

Selecting Elements

• The result of selecting an element includes– The element– Its children– Its attributes– Everything between

open bracket of open element to close bracket of close element

• XPath allows selecting multiple elements– XCAP does not use

this feature

Selecting Attributes

• An attribute is selected by prefixing its name with an “@”

• foo/bar[1]/@attr• foo/bar[@attr=“2”]/@bool

• foo/movie/@stuff• The selected object is

JUST the value– Different from elements– Name would be redundant

<foo> <bar attr=“1”>Hi</bar> <bar attr=“2” bool=“y”>How</bar> <movie stuff=“LOTR”>Are</bar></foo>

XCAP Problem Space

• Motivating use cases– Buddy Lists– Authorization Policies– Hard state presence data

Buddy List Use Case

• Client wants to subscribe to a list of users

• Send SUBSCRIBE to server using SIP event list extension

• Server retrieves list associated with buddylist URI– Generates SUBSCRIBEs to

them

• Client can manage that list– Add, remove, modify entries

Subscribe Joe

Subscribe Bob

Subscribe Mary

Subscribe List

ReadList

WriteList

DataManipulation

Server

Client

Standard Ifaces

Authorization Use Case

• User Hiroshi subscribes to Petri

• No auth policy in place, generates a winfo NOTIFY to Petri

• Petri needs to be able to set authorization decision for Hiroshi

• Want to be able to set such policies outside of a subscription as well

Subscribe Petri

ReadList

WriteList

DataManipulation

Server

Client

Standard Ifaces

winfo

Hard State Presence Management

• Hiroshi subscribes to Petri– Petri has been offline for

weeks

• Server sends NOTIFY with current presence state

• Petri wants to control default state when offline

• Set it to <activity>vacation</activity>

Subscribe Petri

ReadPIDF

WritePIDF

DataManipulation

Server

Client

Standard Ifaces

Notify

Functional Requirements• Create resource list/auth policies/default presence doc• Associate resource list/auth policies/default presence doc with

URI• Have client define URI• Have server assign URI• Modify contents of resource list/auth policies/default presence

doc• Extend resource list/auth policies/default presence doc in

hierarchical way• Delete a piece of resource list/auth policies/default presence

doc• Fetch current resource list/auth policies/default presence doc• Allow multiple clients to access and modify a shared resource

list/auth policies/default presence doc

Performance Requirements

• Protocol will be used on wireless air interfaces• Means that it is

– unacceptable to push the entire resource list/auth policies/default presence doc when a change is needed

– Unacceptable to get the entire resource list/auth policies/default presence doc when the client needs to look at it

• Implies local cache

• Pushing and pulling partial pieces of the data is essential• Invalidation of cached data• Synchronization of data

Key Observations

• Clearly a general problem here– Allowing a user to managed provisioned data that is

accessed by a network application• Apply some basic design principles

– Separate protocol machinery from data schema– Don’t box yourself into a corner with the data schema– Bandwidth efficiency important– Lower the deployment bar

• This is a well-trod space– LDAP, ACAP, SNMP, relational DB cover related

spaces, none successfully deployed to broad end client bases

XCAP Architecture

• Same as previous pictures

• Scope limited to client to XCAP server

• Access from Network App could be XCAP– Acts as a client

• There may be no network app– XCAP server is repository

for client data

Network App

NotStandardized

XCAPServer

Client

XCAP

NotStandardized

The Big “Aha”

• XCAP is about clients getting, deleting and putting pieces of hierarchically organized data

• Ideally XCAP should leverage technologies widely found in phones, PCs and other client devices

• XCAP can just BE HTTP, by defining the URI hierarchy to extend into “web documents”

• HTTP URIs can represent any resource– Don’t need to exist on a disk– Interpretation is up to the server

• XCAP defines that interpretation

HTTP in Brief

• Clients invoke methods on server– GET – retrieve content– PUT – place content– POST – pass data to a process– HEAD – get meta-data, not content– OPTIONS – query server for capabilities– DELETE – remove a resource from a server

• Requests and responses contain bodies

Fetch a document


GET http://server.com/dir/foo HTTP/1.1

HTTP/1.1 200 OKContent-Type: application/xmlContent-Length: …


http://server.com/dir/foo

XCAP Scope

• Application Usages– Details how you use XCAP for a new app (i.e., CPCP)– Server assigned data

• Naming convention for URIs– Document selector – picks the “XML Document” based on a

defined document hierarchy– Component selector – picks an element or attribute within the

document• Using GET, PUT and DELETE for management of

elements and attributes• Error content• Extensibility of data• Etag advice

Application Usage

• Defines what an application needs to do to be used with XCAP– Define an Application Unique ID– Define the XML Schema for the data– Define data semantics– Specify naming conventions – binding between

application and XCAP– Data interdependencies (aka server computed data)– Authorization policies

AUID

• Unique Identifier for each application• Two sub-namespaces

– IETF tree: tokens in RFC documents• IANA Registry

– Vendor tree: proprietary data• Start with reverse DNS name of enterprise

• Examples– IETF Tree

• “resource-lists” draft-ietf-simple-xcap-list-usage• “pidf-manipulation” draft-isomaki-simple-xcap-pidf-manipulation-

usage-00 • “rules” draft-rosenberg-simple-rules

– Vendor Tree• “com.example.customer-list”

AUID Grammar

AUID = global-auid / vendor-auidglobal-auid = auidauid = alphanum / mark vendor-auid = rev-hostname "." auid rev-hostname = toplabel *( "." domainlabel ) domainlabel = alphanum / alphanum *( alphanum / "-" ) alphanum toplabel = ALPHA / ALPHA *( alphanum / "-" ) alphanum

Naming Conventions

• An app will have “hooks” into XCAP– Points of operation of application when XCAP is used– Need to define how that is done

• Example: Presence List– Fetch document whose uri attribute of <resource-list>

is equal to request URI of SUBSCRIBE

• Example: Authorization– Fetch authorization policy documents underneath

http://server.com/rules/users/<username> where username identifies the presentity

http://server.com/rules/users/%3Cusername

Data Interdependencies

• In many cases a user defines all of their own data– PIDF manipulation usage– Authorization policies

• In some cases a few pieces of it are “filled in” by the server– Resource list URIs for lists – need to be unique, can

be server assigned– Client can also define them

• Application usage specifies what pieces server fills in, and how

Modeling Server Computed Data

• Think of the application usage as a client of XCAP

• Handset puts a new resource list, URI not present (1)

• Application learns of change (4)

• Acting as a client, application modifies data, setting URI (5)

• This is a model, not an implementation requirement– Impacts Etag usage (later)

Authorization Policies

• Who is allowed to access (R/W) XCAP data?– Application specific

• Policies are specified by application usage• XCAP defines a “default”

– A user can read and write their own data– A user can only access their own data– Global data is readable by everyone,

writeable by no one except privileged users

Definition Example

• Basic address book from before

• Would author an RFC structured as follows

Document Contents

• AUID– Want this to be global– Pick an appropriate AUID

• address-book

– Add an IANA Considerations section registering the AUID

• XML Schema– Include it– IANA registry for schema

and namespace

• Naming Conventions– No server app– No naming conventions

• No data interdependencies

• Default authorization policy

Semantics

• An address book is a series of <entry> elements

• Each <entry> is information about an entry in the address book– It has a <name>, which is the use persons

first and last name– It has an <email> element, which contains the

email address of the person– It has a <postal> element that has the postal

address

The Document Hierarchy

• XCAP defines URIs as two parts– Document selector – chooses the XML

document– Node selector – chooses the XML component

(element, attribute)• XPath subset discussed previously

• XML documents organized into a mandatory hierarchy– Borrows from ACAP concepts

Hierarchy Structure

• Top is the Root Services URI– Identifies start of XCAP tree

• http://server.example.com/xcap-root• http://www.example.com/docs/xml/ietf/xcap/root

• Next is the AUID• Next is “users” or “global”

– “users” are for per-user documents– “global” are for data that is not user specific – for reading by all

users of the app

• Within users, next is username• Underneath username is anything• Eventually leads to document

http://server.example.com/xcap-root



The HierarchyRoot services

AUID 1 AUID 2

users global

petri hiroshi

doc1 dir1

Example 1• http://xcap.example.com/address-book/users/petri/

adbook1/address-book/entry/name


adbook1

Client Operations

• Retrieving– Document– Element– Attribute

• Deleting– Document– Element– Attribute

• Modifying– Document– Element– Attribute

• Adding– Document– Element– Attribute

KEY CONSTRAINTCan only affect one element, attribute

or document at a time

Fetching a DocumentGET http://xcap.example.com/address-book/users/petri/adbook1 HTTP/1.1

HTTP/1.1 200 OKContent-Type: application/adbook+xmlContent-Length: …



adbook1

Fetching an ElementGET http://xcap.example.com/address-book/users/petri/adbook1/

address-book/entry/name HTTP/1.1

HTTP/1.1 200 OKContent-Type: application/xml-fragment-bodyContent-Length: …

<name>Jonathan Rosenberg</name>


adbook1

http://xcap.example.com/address-book/users/petri/adbook1/address-book/entry/name


Fetching an AttributeGET http://xcap.example.com/address-book/users/petri/adbook1/

address-book/entry/street/@paved HTTP/1.1

HTTP/1.1 200 OKContent-Type: application/xml-attribute-valueContent-Length: …

true


adbook1

Delete a DocumentDELETE http://xcap.example.com/address-book/users/petri/adbook1 HTTP/1.1

HTTP/1.1 200 OK


adbook1

NULL

Deleting an ElementDELETE http://xcap.example.com/address-book/users/petri/adbook1/

address-book/entry/name/email HTTP/1.1

HTTP/1.1 200 OK


adbook1

<?xml version="1.0" encoding="UTF-8"?> <address-book> <!—This guy is a bozo -- <entry> <name>Jonathan Rosenberg</name> <postal> <street paved=“true”>600 Lanidex Pl</street> <city>Parsippany</city> <state>NJ</state> <country>USA</country> </postal> <ietf-participant/> </entry> </address-book>




Deleting an AttributeDELETE http://xcap.example.com/address-book/users/petri/adbook1/

address-book/entry/name/postal/street/@paved HTTP/1.1

HTTP/1.1 200 OK


adbook1

<?xml version="1.0" encoding="UTF-8"?> <address-book> <!—This guy is a bozo -- <entry> <name>Jonathan Rosenberg</name> <postal> <street>600 Lanidex Pl</street> <city>Parsippany</city> <state>NJ</state> <country>USA</country> </postal> <ietf-participant/> </entry> </address-book>




Modify vs. Add• Modify and Add look the same

– PUT Request– Body contains content

• Behavior depends on URI– Server checks if resource exist

• URI resolves to an existing doc, element in a doc, or attribute in an element

– If not, the operation is add• New content is added such that

– URI now resolves to the content in the body– Schema constraints are obeyed– Otherwise inserted after all siblings

– If so, the operation is modify• New content replaces the content selected by the URI

Insert an ElementPUT http://xcap.example.com/address-book/users/petri/adbook1/

address-book/entry/phone HTTP/1.1Content-Type: application/xml-fragment-body

<phone>+19739525000</phone>

HTTP/1.1 200 OK


adbook1

<?xml version="1.0" encoding="UTF-8"?> <address-book> <!—This guy is a bozo -- <entry> <name>Jonathan Rosenberg</name> <phone>+19739525000</phone> <email>[email protected]</email> <postal> <street paved=“true”>600 Lanidex Pl</street> <city>Parsippany</city> <state>NJ</state> <country>USA</country> </postal> <ietf-participant/> </entry> </address-book>

Modify an ElementPUT http://xcap.example.com/address-book/users/petri/adbook1/

address-book/entry/name HTTP/1.1Content-Type: application/xml-fragment-body

<name>Jonathan D. Rosenberg</name>

HTTP/1.1 200 OK


adbook1

<?xml version="1.0" encoding="UTF-8"?> <address-book> <!—This guy is a bozo -- <entry> <name>Jonathan D. Rosenberg</name> <email>[email protected]</email> <postal> <street paved=“true”>600 Lanidex Pl</street> <city>Parsippany</city> <state>NJ</state> <country>USA</country> </postal> <ietf-participant/> </entry> </address-book>

Server Error Handling• Server error handling is specified in HTTP specification• Most XCAP-specific cases are details within 404 or 409

– 409 (Conflict) The request could not be completed due to a conflict with the current state of the resource.

– 404 (Not Found) The server has not found anything matching the Request-URI.

• XCAP Specific error cases– Result of operation results an a document that is not well-formed

or valid (409)– Resource identified in a request corresponds to multiple

elements or attributes (409)– Application usage not understood (409)– Document, element or attribute does not exist (404)– Client provided data that violates a uniqueness requirement

(409)– Request did not contain valid xml-frag-body (409?)

Conveying Conflict Details

• HTTP recommends including a 409 body detailing problem so client can retry

• XCAP defines an XML body format for response– application/xcap-error+xml MIME type– Root element <xcap-error>– Child is specific to the error

• Detailed error information can be dependent on the error

• Defined errors match ones on previous slide

URI Exists Error

• Client attempts to set a URI with a uniqueness constraint, and the value exists already

• Happens in resource lists• Server error response

indicates– URI(s) which had this

problem– Optional suggested

alternates

<?xml version="1.0" encoding="UTF-8"?><xcap-error xmlns="urn:ietf:params:xml:ns:xcap-error"> <uri-exists> <exists uri="sip:[email protected]"> <alt-uri>sip:[email protected]</alt-uri> </exists> </uri-exists></xcap-error>

Handling Multiple Writers

• Synchronization problems occur when multiple clients can manipulate the same document

• Especially true when a client needs to do multiple HTTP operations to affect a change– XCAP provides no lock– But we want to detect this

condition and recover

• Common problem

Solution: Etags

• ETag from HTTP– Entity tags are used

for comparing two or more entities from the same requested resource.

– An entity tag MUST be unique across all versions of all entities associated with a particular resource.

• What does this mean?– ETag is a version

identifier for a resource

– Server assigns the etag

– It changes every time the resource changes

How are they used?

• HTTP defines several conditional headers– If-Match: only process this request if the entity

tag matches that held by the server– If-None-Match: only process this request if the

entity tag does not match– If-Range: asks for the byte range that has

changed

• Server returns 412 if condition fails

Example Revisited

• User A has version ABC• Adds buddy, adds If-

Match: ABC• Buddy added, new

version DEF• User B also has version

ABC• Tries to modify it, but it

fails• B can now fetch it and

make its diff against the current version

Data Extensibility

• XCAP servers MUST understand the application usages they manage

• They don’t need to understand any namespaces but the root ones– Document extensions don’t need to be understood

• Sometimes, an extension requires the server to understand– Setting a URI– Guaranteeing Uniqueness

Current Solution

• Defines a “mandatory-ns” element

• This attribute is present as a child of the root element in any document

• Indicates what namespaces are mandatory

<?xml version="1.0" encoding="UTF-8"?> <address-book xmlns:conf=“urn:ietf:2233”> <mandatory-ns> <ns>urn:ietf:2233</ns> </mandatory-ns> <!—This guy is a bozo --> <entry> <name>Jonathan Rosenberg</name> <email>[email protected]</email> <postal> <street paved=“true”>600 Lanidex Pl</street> <city>Parsippany</city> <state>NJ</state> <country>USA</country> </postal> <conference-uri/> <ietf-participant/> </entry> </address-book>

Presence Authorization

• Specified as a ruleset

• Each ruleset is a series of rules

• Each rule has three parts– Condition – does this rule apply?– Action – what do you do if it does?– Transformation – how do you restrict the data

seen by a requestor?

Permission Model

• Each action or transformation is called a permission

• A permission is a positive grant of information– There can never be negative grants, i.e., “don’t send

information X”

• If there is no permission for something, you get nothing

• Implication is that the system is privacy safe

Privacy Safe

• If a server doesn’t understand a permission, less information is sent than desired, never more

• If a server cannot obtain a rule from a remote source, less information is sent than desired, never more

• No network failures or other transient problems can result in more information being sent than is desired

Common Policy

• draft-ietf-geopriv-common-policy

• Defines framework

• Defines common elements in all systems– <identity> - condition matching based on user

identity– <sphere> - condition based on your presence

status– <validity> - time range

Current Presence Authorization Elements

• Extends the set defined in common-policy with presence-specific data

• New conditions– <anonymous> - is the subscription anonymous

• Actions– <accept-subscription> - accept the presence subscription– <provide-presence> - polite blocking or not

• Transformations– <show-namespace> - provide elements from a specific

namespace– <show-tuple> - provide elements from specified tuples– <show-element> - provide elements with a specific name

<?xml version="1.0" encoding="UTF-8"?> <cr:ruleset xmlns="urn:ietf:params:xml:ns:pres-rules" xmlns:cr="urn:ietf:params:xml:ns:common-policy" xmlns:rpid="urn:ietf:params:xml:ns:rpid" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <cr:rule id="1"> <cr:conditions> <cr:identity> <cr:uri>[email protected]</cr:uri> </cr:identity> </cr:conditions> <cr:actions> <accept-subscription>true</accept-subscription> <provide-presence>true</provide-presence> </cr:actions> <cr:transformations> <show-namespace> <ns>urn:ietf:params:xml:ns:rpid</ns> </show-namespace> <show-element> <basic-elements/> <el>rpid:placetype</el> </show-element> </cr:transformations> </cr:rule> </cr:ruleset>

Documents

XCAP Tutorial Jonathan Rosenberg. Ground Rules This is a session for level setting –People are at different points –We will start from the beginning NO