Chapter 17 - Service Configuration on the Internet pdf

HTTP TCP XCAP IP Figure 17.2: The XCAP protocol stack XCAP provides a client with the means to read, write, and modify XML application configuration data remotely stored on a server.. PU

Chapter 17

Service Configuration on the

Internet

Many services require a mechanism for allowing users to manage their service configuration For example, a presence server requires presentities (users) to authorize which watchers can see their presence information A Push-to-talk over Cellular (PoC) service requires users to create and manage groups Likewise a conference may require users to configure a dial-out

or dial-in list of participants, their privileges (who can speak or who can send or receive which media type), and so on All of these use cases share many commonalities: a user has

to perform non-real-time operations on a server to manipulate one or more documents that configure or personalize their instance of the service

Usually the user creates a configuration document locally in their terminal and then uploads it to a server Sometimes, the user just needs to make a small change to an existing document, so it is not worth uploading the complete document Instead, it is desireable to have the capability to update part of the document In some other cases the user changes their usual terminal and uses a different one, so they may first need to download a fresh copy of the current configuration document, make some changes, and upload it (either complete or a part of it) to the server

Typically, configuration documents are highly structured Owing to this, the trend nowadays is to use the Extensible Markup Language (XML) (specified by the World Wide Web Consortium in the W3C recommendation XML 1.1 [93]), for formatting documents that personalize the instance of the service

So, we know that configuration documents are effectively XML documents, but how are they sent to and received from the server that stores them? The XML Configuration Access Protocol (XCAP) solves this vacuum

17.1 The XML Configuration Access Protocol (XCAP)

The problem of document management can be depicted in its most simplified way as in Figure 17.1 A user creates an XML document in his computer and wants to upload it to a server The server will use the document at a later time to produce a personalized instance of the service

The problem to be solved requires designing a protocol that allows such an upload procedure HTTP (specified in RFC 2616 [144]) provides a good baseline, since it provides

´ıa- M ar t´ın

The 3G IP Multimedia Subsystem (IMS): Merging the Internet and the Cellular Worlds Third Edition

Gonzalo Camarillo and Miguel A Garc

© 2008 John Wiley & Sons, Ltd ISBN: 978- 0- 470- 51662- 1

server Terminal

Figure 17.1: Overview of Document Management

the POST and PUT methods for transferring files from the client to the server It also contains

a GET method for downloading a document from the server However, there are additional requirements that prevent the usage of HTTP For example, on many occasions users just need to modify a small piece of an existing XML document For instance, when a user wants

to add a “buddy” to his list of friends in the presence service: the user just wants to edit a few bytes of a potentially large document It is not worth uploading the whole XML document again, since the document is mostly unchanged, just the modified content HTTP alone does not offer that functionality

The IETF decided then to develop a set of conventions and rules for using HTTP to upload and download complete or portions of XML documents to and from a server This resulted in the creation of XCAP (specified in RFC 4825 [277]) XCAP is, therefore, not a new protocol, but a set of conventions for using HTTP for managing remotely stored XML documents Figure 17.2 shows a schematic representation of the protocol stack used by XCAP

HTTP TCP XCAP

IP

Figure 17.2: The XCAP protocol stack

XCAP provides a client with the means to read, write, and modify XML application configuration data remotely stored on a server This includes, for example, modifying the list

of users in a presence list, authorization policies (e.g., a list of authorized watchers) or the list

of participants in a conference XCAP does not control the user interface (e.g., the graphical representation of the list), rather, it focuses on the data structure

XCAP defines conventions that map XML documents and their components (e.g., elements, attributes) to HTTP URIs Therefore, XCAP provides a unique way to represent an XML document or a component with an HTTP URI It also defines the rules that govern how

17.1 THE XML CONFIGURATION ACCESS PROTOCOL (XCAP) 373

modification of one resource affects another This means that XCAP allows users to modify

an XML document, but still the resulting document has to be compliant with the original XML schema In addition, XCAP also defines the basic authorization policies associated with access to resources

XCAP implements a set of operations that are mapped to regular HTTP 1.1 methods The operations also set some HTTP headers to a particular value XCAP provides the client with the operations that can manipulate the whole XML document, an arbitrary XML element of the document, or an arbitrary XML attribute of an element For each of these levels, XCAP provides the means for creating, deleting, modifying, replacing, and fetching So combining all together, XCAP provides the means to create, delete, modify, replace or fetch a complete XML document, an element, or an attribute

Figure 17.3 shows an example of an XCAP request in which Alice is sending an HTTP PUT request to create a new presence list We provide details of how to manipulate presence lists in Chapter 19 For the time being, just notice that XCAP is merely HTTP and XML with some additional rules We are going to describe the basics of XML in Section 17.2

PUT /pr-lists/users/sip:alice@example.com/friends.xml HTTP/1.1 Host: xcap.example.com

Content-Type: application/resource-lists+xml

Content-Length: 460

<?xml version="1.0" encoding="UTF-8"?>

<resource-lists

xmlns="urn:ietf:params:xml:ns:resource-lists">

<list name="family" uri="sip:family@example.com">

<entry name="Bob" uri="sip:bob@home1.com">

<display-name>Bob</display-name>

</entry>

<entry name="Cynthia" uri="sip:cynthia@example.com">

<display-name>Cynthia</display-name>

</entry>

</list>

</resource-lists>

Figure 17.3: Example of an XCAP operation

XCAP defines two functional elements: an XCAP client and an XCAP server They are depicted in Figure 17.4 An XCAP client is an HTTP 1.1 compliant client that supports the rules and conventions specified by XCAP; it sends HTTP requests and receives HTTP responses An XCAP server is an HTTP 1.1 compliant server that also supports the rules and conventions specified by XCAP; it receives HTTP requests and generates HTTP responses

17.1.1 XCAP Application Usage

As explained in the previous section, XCAP is a generic protocol that can be used for a number of purposes related to application data configuration of XML documents stored in a server We have also seen that there are a several applications that utilize XCAP For example,

in the presence service, presentities use XCAP to control whether watchers can see all

Figure 17.4: XCAP functional elements

or part of the presence information (watcher authorization is described in greater detail in Section 19.14) In a centralized conference service, the creator of a dial-out conference can use XCAP to configure the list of participants of the conference In general, whenever there

is a need to configure configuration application data, such as a list remotely stored in XML format, XCAP is a good protocol to fulfill these needs

Owing to this versatility XCAP introduces the concept of an application usage An

application usage defines how a particular application uses XCAP to interact with the XCAP server For instance, each of the previously mentioned applications of XCAP (presence list management, authorization policies, and conference list management) constitutes an application usage on its own Each application usage is identified by an AUID (Application Unique ID) that uniquely identifies the application usage There are two types of AUIDs: standard (i.e., application usages standardized in the IETF) and vendor-proprietary (i.e., private application usages)

The IETF has defined a number of XCAP application usages related to the presence service

XCAP application usage for resource lists Specified in RFC 4826 [273], provides the

means to manipulate resource lists that are typically used as presence lists

XCAP application usage for presence authorization Defined in RFC 5025 [276], allows

a client to specify presence authorization rules, i.e., the set of rules that grants certain watchers the permissions to access certain subsets of the presentity’s presence information

XCAP application usage for manipulating presence documents Specified in RFC 4827

[175], allows users to perform hard state manipulation of presence data, i.e., set the presence status by configuration (i.e., using XCAP), as opposed to the soft state manipulation performed through the more common presence publication, i.e., using

the SIP PUBLISH method

17.2 An Overview of XML

XML documents constitute a very important aspect for configuring applications Usually, the application configuration data are stored in XML format, therefore, XML documents (or portions of them) are transported between the client and the server While there is extensive literature on XML, we provide a high-level overview that allows readers to better understand the protocol used for manipulating XML documents

17.2 AN OVERVIEW OF XML 375

XML documents are text-based documents and, thus, are human-readable XML documents contain a structured representation of data, but the document itself does not do anything Therefore, an XML document merely provides the means to represent structured data

The XML document in Figure 17.5 contains the representation of the data pertaining to the second edition of this book, which we assume is stored in a file named ims.xml Let

us use this example to further illustrate a few concepts The first line of the document is the XML declaration that defines the XML version and the encoding used in the document Then, the data that constitute the tree follow through the following lines Each node in the

tree is called an XML element XML elements start with the name of the element enclosed in

angle brackets, e.g <book>, and terminates with a closing tag that contains a slash ’/’ and the name of the element, e.g </book>

<?xml version="1.0" encoding="UTF-8"?>

<book xmlns="urn:org:miguel:book"

isbn="0470018186" edition="2">

<title>The 3G IP Multimedia Subsystem (IMS)</title>

<subtitle>Merging the Internet and the cellular worlds</subtitle>

<author id="1">Gonzalo Camarillo</author>

<author id="2">Miguel A Garcia-Martin</author>

<publisher>John Wiley and Sons, Ltd</publisher>

</book>

Figure 17.5: Example of an XML document: ims.xml

XML elements can contain other child elements, processing instructions, namespace declarations, comments, and text nodes In the example in Figure 17.5, the book element contains the title, subtitle, and so on, child elements

XML elements usually contain a text node that represents a value In the example in

Figure 17.5, the value of the title element is “The 3G IP Multimedia Subsystem (IMS)” XML elements can be also empty, in which case, a compact notation can indicate the beginning and end tags of the empty element by including a slash ’/’ at the end of the element name For example, <test/> is an empty element

Last, XML elements can contain attributes that further characterize the element, typically

by defining its metadata In Figure 17.5, the book element contains three attributes: xmlns, isbn, and edition Unlike elements, attributes cannot be empty and can only appear once

in a given element

XML is extensible, so new elements and attributes can be added whenever they are needed This is, perhaps, the most important property of XML

An XML document is said to be well formed when it meets the basic constraints for all

XML documents For example, each open tag has a closing tag (except for the compact notation of empty elements); the names of the attributes are unique; elements are properly nested; attributes values must be quoted, etc

Sometimes XML documents need to be drafted according to a predefined structure that provides additional constraints of the data In the example of Figure 17.5, there should not be two title elements, but there can be several author elements All of these constraints, which are specific to the type of data that the XML document represents, are typically defined in separate additional documents, for example, in Document Type Definition (DTD)

documents, XML schema documents or RelaxNG documents An XML document is said to

be valid when it meets the constraints defined in the DTD, XML schema, RelaxNG, or any

other document that defines the constraints

17.2.1 XML Namespaces

When XML designers create XML documents, they need to give names to the XML elements and attributes of the document It is easy to foresee that sooner or later there will be conflicts

in the names given to XML elements and attributes, e.g., two designers could create the book element in different documents, each one with a different structure and syntax Furthermore,

if these two book elements were part of the same XML document as sibling nodes, then it would not be possible to determine which is which

To solve this problem, XML introduces the concept of namespaces, which are specified in

the W3C Recommendation “Namespaces in XML 1.1 (Second Edition)” [92] A namespace

is an abstract space where names pertaining to XML elements and attributes belong to By making namespaces globally unique, it is possible to differentiate, e.g., two book elements that belong to two different XML schemas So, the namespace provides the XML document with a context where the document makes sense

Namespaces are identified by International Resource Identifiers (IRI), specified in RFC 3987 [125] In the case of IETF documents, IRIs are usually URNs, specified in RFC 3986 [86], and they are registered under the tree urn:ietf:params:xml:ns A URN is

a persistent name that identifies a resource independently of its location An XML document must indicate at least one namespace where the elements, attributes, etc belong, but it is also possible, and it is actually very common, to create an XML document that contains elements and attributes belonging to different namespaces Usually, a namespace declaration

is included in the root element of the document, indicating all of the namespaces used in the document The declaration is made in xmlns attributes that modify the root element The namespace declaration typically contains the default namespace and additional namespaces used throughout the document The default namespace applies to any unprefixed element Additional namespaces are mapped to a prefix, so it is easier to distinguish those elements that belong to other non-default namespaces

Let us illustrate the concept with the example of Figure 17.6, which is an exten-sion of our XML document for representing books The document now defines two namespaces with the “xmlns” attributes of the book element The default namespace

is “urn:org:miguel:book” Any element that is not prepended by a prefix belongs to that namespace A second namespace named “urn:org:miguel:classification” is declared This second namespace is mapped to the prefix “cl”, so any XML element (and attributes of it) prefixed with “cl” belongs to that namespace So, the example shows the elements class, technical, internet, telecom, and wireless that belong to the

“urn:org:miguel:classification” namespace We can also see that some of these elements are, in fact, empty XML elements, since the element tag serves as both opening and closing tag

17.3 HTTP URIs that Identify XCAP Resources

We have discussed earlier that XCAP is used to manage remotely stored XML documents XCAP is able to manage XML documents, XML elements, XML element values, and XML

attributes Each of them is considered a resource and it is identified with a URI Actually,

17.3 HTTP URIS THAT IDENTIFY XCAP RESOURCES 377

<?xml version="1.0" encoding="UTF-8"?>

<book xmlns="urn:org:miguel:book"

xmlns:cl="urn:org:miguel:classification"

isbn="0470018186" edition="2">

<title>The 3G IP Multimedia Subsystem</title>

<subtitle>Merging the Internet and the cellular worlds</subtitle>

<author id="1">Gonzalo Camarillo</author>

<author id="2">Miguel A Garcia-Martin</author>

<publisher>John Wiley and Sons, Ltd</publisher>

<cl:class>

<cl:technical true="yes"/>

<cl:internet true="yes"/>

<cl:telecom true="yes"/>

<cl:wireless true="yes"/>

</cl:class>

</book>

Figure 17.6: Various namespaces in an XML document

since XCAP is not a new protocol, but a set of conventions to use HTTP for managing XML documents, there are no XCAP URIs, but rather, HTTP URIs that represent XCAP resources Let us take a closer look at the mechanism that XCAP utilizes to identify resources

Figure 17.7 shows a schematic representation of an HTTP URI that represents an XCAP resource, while Figure 17.8 shows an example of it Actually, the example in Figure 17.8 represents the id attribute whose value is “2” of the <author> element that we saw in Figure 17.5

XCAP resource = XCAP root

+ document selector [+ node selector separator]

[+ node selector]

[+ query]

Figure 17.7: Construction of HTTP URIs that represent XCAP resources

http://xcap.example.com/root/bibliography/users/sip:miguel@example.com /ims.xml/~~/book/author[@id="2"]

Figure 17.8: An HTTP URI that represents an XCAP resource

The HTTP URI represented in Figure 17.8 starts with the HTTP URI scheme, “http://”, followed by the hostname of the server, “xcap.example.com”, and XCAP root locator,

“/root” All three form the XCAP root URI that identifies the hierarchy where XCAP

services are located in the HTTP server So, in the example, the XCAP root URI indicates an HTTP protocol operation on a server called “xcap.example.com” on a (potentially virtual) directory called “/root”

The XCAP root URI is followed by a document selector, which starts with the application usage to which the document pertains, in the example, the “bibliography”

XCAP application usage Then, there are one of two possible subtrees, which identify

either the “global” subtree or the “users” subtree, and are identified with the literals

global or users, respectively The global subtree contains all of the documents where data is set by all users The “users” subtree contains documents that apply to a particular user The name of the user follows the users subtree, so, the example in Figure 17.8

refers to user “sip:miguel@example.com”, so the URI is referring to a document owned

by that user Then the actual XML document follows, in the example, “ims.xml”

To summarize: Figure 17.8 is selecting an XML document named “ims.xml” of the

“bibliography” application usage; the “ims.xml” document is located in the user directory

“sip:miguel@example.com”

The document selector is followed by double tilde characters “∼∼”, which are called the node selector separators and are used to separate the document selector from the node selector which follows The node selector identifies an XML element, attribute, etc within the selected document In the example in Figure 17.8 the node selector points to the book

element and its child author element whose attribute “id” has the value “2” This is denoted

as “/book/author[@id="2"]”

Last, an optional query component can be concatenated to the HTTP URI that represents

an XCAP resource This is used, for example, when XML namespaces have to be included

in the URI In most cases, the query component is not needed because the default namespace

for the application usage is assumed

Usually HTTP URIs that represent XCAP resources are included in the Request-URI

of HTTP requests The encoding rules of the Request-URI field in an HTTP request does

not allow the presence of some characters, such as square brackets Owing to this, special

characters are percent-encoded in Request-URIs, so a ’[’ character is encoded as a ’%5b’,

a ’]’ character is encoded as ’%5d’, and the double quotes ’"’ as ’%22’ Therefore, when

the example of an HTTP URI that we saw in Figure 17.8 is included in a Request-URI, it

yields the percent-encoded HTTP URI of Figure 17.9

http://xcap.example.com/root/bibliography/users/sip:miguel@example.com /ims.xml/~~/book/author%5b@id=%222%22%5d

Figure 17.9: A percent-encoded HTTP URI representing an XCAP resource

As we indicated earlier, XCAP allows an XCAP client to do different types of operations in

a remote XML document XCAP operations are mapped to HTTP requests, whose Request-URI values indicate the resource (document, element, attribute) that are to be created, deleted,

replaced, modified, or fetched Let us take a deeper look at these operations and how they are mapped to HTTP 1.1 requests

17.4.1 Create or Replace Operations

To create a new XML document in a remote server or to replace an existing one, an XCAP

client invokes the HTTP PUT method The Request-URI in the HTTP PUT request identifies

the XML document that is to be created (if it previously did not exist) or replaced (if it existed) The XML document to be created or replaced is attached to the request as a MIME

17.4 XCAP OPERATIONS 379

body, and it is identified by a Content-Type header field with the value defined by the application usage Figure 17.10 shows an example of an XCAP operation that creates or replaces an “ims.xml” document

PUT /root/bibliography/users/sip:miguel@example.com/ims.xml HTTP/1.1 Host: xcap.example.com

Content-Type: application/bibliography+xml

<?xml version="1.0" encoding="UTF-8"?>

<book xmlns="urn:org:miguel:book"

isbn="0470018186" edition="2">

<title>The 3G IP Multimedia Subsystem</title>

<subtitle>Merging the Internet and the cellular worlds</subtitle>

<author id="1">Gonzalo Camarillo</author>

<author id="2">Miguel A Garcia-Martin</author>

<publisher>John Wiley and Sons, Ltd</publisher>

</book>

Figure 17.10: Creating or replacing a complete XML document

If the XCAP client wishes to create or replace a single element or attribute of an existing XML document, the operation is similar: the XCAP client invokes the HTTP PUT method

with a Request-URI that points to the XML element or attribute that is to be created or

modified The Content-Type header field is set to either “application/xcap-el+xml”

or “application/xcap-att+xml”, depending on whether the operation affects an element

or an attribute, respectively The PUT request then contains an XML body that includes the element or attribute to be created or replaced For example, Figure 17.11 inserts a keywords element as a child element of book, in the “ims.xml” document

PUT /root/bibliography/users/sip:miguel@example.com/ims.xml/

~~/book/keywords HTTP/1.1

Host: xcap.example.com

Content-Type: application/xcap-el+xml

<keywords>

<keyword>IMS</keyword>

<keyword>multimedia</keyword>

<keyword>3G</keyword>

</keywords>

Figure 17.11: Adding an element to an XML document

Since both create and replace operations are mapped onto the same HTTP request, there must be a way to differentiate them There is, and it is very simple: if the node selector does not match an existing element, then it is a create operation; if the node selector selects an existing element within the document, then it is a replace operation

17.4.2 Delete Operations

To delete an XML document, element, or attribute in a remote server, an XCAP client creates

a DELETE HTTP request The Request-URI uniquely selects the document, element, or

attribute to be deleted Upon reception of the DELETE method, the server deletes the document or attribute If it is an element, it deletes the element with all of its attributes and child elements The resulting document must still be in conformance with the application usage, i.e., it must be compliant with the XML Schema that determines which elements and attributes are mandatory and optional and further constraints, otherwise, the server will not honor the delete request Figure 17.12 shows an example of a delete operation that removes the “ims.xml” document from the server

DELETE /root/bibliography/users/sip:miguel@example.com/ims.xml HTTP/1.1 Host: xcap.example.com

Figure 17.12: Deleting an XML document

17.4.3 Fetching Operations

There are many cases in which an XCAP client needs to fetch an existing document, element,

or attribute, that is remotely stored For example, if a user is using a new terminal, he most likely does not have any of the XML documents that he created earlier with a different terminal In this case, before he manipulates his data, he must first fetch existing documents from the server

To fetch a document, element, or attribute, the client creates an HTTP GET request This requires that the XCAP client has knowledge of the name of the XML document The

Request-URI selects the document, element, or attribute to be fetched The server will reply

in a 200 (OK) response that contains a MIME body If a full XML document was requested, the response contains the document If an element or attribute was requested, the response contains the requested element or attribute, properly identified with a Content-Type header

17.5 Entity Tags and Conditional Operations

The concept of entity tags is not new to XCAP, since it is inherited from HTTP, so we need to

go back to HTTP for a proper description An entity tag is an opaque string of characters that

is associated to the contents of a resource, for example, a web page If the resource (e.g, the web page) changes its contents, e.g., due to an update, then the HTTP server creates a new entity tag for such resource15 So, we can consider an entity tag as a sort of fingerprint of a resource

Entity tags are transported in ETag header fields that are part of HTTP responses Figure 17.13 depicts a couple of HTTP requests where the corresponding responses contains

an ETag header field A client invokes the HTTP GET method to request a given resource (1) The HTTP server answers with a 200 (OK) response (2) that contains the requested content,

as a MIME body, and an ETag header field whose value identifies the served version of the content When the content changes, perhaps due to some external action, the server assigns

a new entity tag If, later, the client (or any other client) requests the same resource (3),

15 Creation of entity tags is optional for HTTP servers, however, it is mandatory for XCAP servers