<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE section PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'
	'http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd'>

<section><title>XCAP</title>

<section><title>Introduction</title>

<para>XCAP is a HTTP based protocol for access remote configuration data. Data
is stored in XML format and XCAP protocol allows to query, modify or delete
parts of such data. This is in detail described in <xref
linkend="pres_draft_xcap"/>. XCAP server is server able to handle XCAP requests.
</para>

<para>XCAP server may be used for storing <quote>presence interesting</quote>
data. From the SER's point of view are interesting:
<itemizedlist>
	<listitem><para>authorization data</para></listitem>
	<listitem><para><quote>buddy lists</quote></para></listitem>
</itemizedlist>
</para>

<section><title>XCAP authorization</title>
<para>Definition of authorization documents and theirs usage is specified in <xref 
linkend="pres_draft_common_auth"/> and especially for presence purposes in <xref 
linkend="pres_draft_auth"/>. Both documents are quite common and in SER's
presence modules implemented only partialy.
</para>
</section> <!-- XCAP authorization -->

<section><title>Buddy lists</title>
<para>XCAP server may be used for storing lists of users too. These lists may be
used for presence subscriptions - subscription to such list means subscription
to all users at once. This reduces number of created subscriptions and may
reduce data transfers between server and client too; but presence documents for
lists of users may be very big.</para>

<para>There may be not only lists for individual users with their contacts but 
there may be other sort of lists representing some <quote>logical
entities</quote> such <quote>businessmen</quote>, <quote>technical
support</quote>, ... which are used in cases like if some customer needs someone
from technical support department and doesn't want to remeber all people
there. Such customer may simply watch presence state of
<quote>technical-support@somewhere.net</quote> if he needs help from them.
</para>

<para>Lists of users - more common resource lists - are defined in <xref
linkend="pres_draft_rls"/> and their usage with SIP in <xref
linkend="pres_draft_rls_sip"/>. These lists are partialy implemented in <link
linkend="pres_rls">RLS module</link>.
</para>
</section> <!-- buddy lists -->

<section><title>Manipulation with XCAP documents</title>
<para>Manipulating with XCAP documents is quite simple because XCAP uses
standard HTTP methods like GET, PUT or DELETE. Every web browser may be
used to read XCAP data and it is quite simple to write utility to write data
to XCAP server. These features allow to use XCAP with SER although there are is 
not much client software supporting it.
</para>
</section> <!-- manipulating documents -->

</section> <!-- XCAP introduction -->

<section><title>XCAP authorization and SER</title>

<section><title>Authorization document URI</title>
<para>Authorization documents are read for presentities according to their presentity
URIs. Presentity URI is AOR of SUBSCRIBE request. Resulting URI will be:</para>
<para>
<filename>&lt;xcap-root&gt;/pres-rules/users/&lt;username&gt;/presence-rules.xml</filename>
where <parameter>&lt;xcap-root&gt;</parameter> is set in configuration and
<parameter>&lt;username&gt;</parameter> is username from presentity URI.
</para>

<example><title>authorization document uri</title>
<para>For example for presentity <literal>sip:smith@iptel.org</literal> and
<parameter>xcap-root</parameter> <literal>http://localhost/xcap-root</literal> will be
the URI for the authorization document
<filename>http://localhost/xcap-root/pres-rules/users/smith/presence-rules.xml</filename>
</para>
</example>

</section>

<section><title>Disadvantages</title>
<para>One of the worst disadvantages of XCAP authorization is slowness of XCAP
queries compared to - for example - data stored in local database. This is the
reason for caching XCAP queries and responses, but there is a problem - how to
detect changes in data stored on XCAP server. One of possible solutions is to 
implement client for <quote>XCAP change notifications</quote> described in <xref
linkend="pres_draft_xcap_change"/> and <xref linkend="pres_draft_xcap_profiles"/>
(planned in future versions).</para>
</section>

<section><title>Standard incompliances</title>
<para>SER's XCAP authorization support is not finished yet, there are some standard
incompliances now:
<itemizedlist>
	<listitem><para>ignored sphere</para></listitem>
	<listitem><para>ignored date and time conditions</para></listitem>
	<listitem><para>ignored transformations</para></listitem>
</itemizedlist>
</para>
</section>

</section> <!-- XCAP authorization in SER -->

<section><title>Resource lists and SER</title>
<para>There is a problem of resource lists usage: The draft <xref
linkend="pres_draft_rls"/> describes that a Resource Lists Server operates with
<quote>rls-services</quote> document - NOT directly with the user's buddy list,
but tested client software doesn't store <quote>rls-services</quote> documents,
only <quote>resource list documents</quote> (buddy lists).</para>

<para>It is possible now to change mode of processing subscriptions (see <link
linkend="rls.parameters">RLS module parameters</link> so it works directly with
resource list documents published by client instead of rls-services document.
</para>

<section><title>RLS document URI</title>
<para>The construction of rls-services document URI is described in <xref
linkend="pres_draft_rls"/>. Only in short: the AOR from SIP SUBSCRIBE request is
combined with XCAP root given in configuration like this:</para>
<para>
<filename>&lt;xcap-root&gt;/rls-services/global/index/~~/rls-services/service[@uri=%22&lt;AOR&gt;%22]</filename>.
</para>
<para><emphasis>
This URI doesn't not specify namespaces as mentioned in definition, but this is 
due to problems with XCAP server used for tests (problems querying
parts of documents with namespaces).</emphasis></para>
<example><title>rls-services uri example</title>
<itemizedlist>
	<listitem><para><varname>xcap-root</varname> = <literal>http://localhost/xcap-root</literal></para></listitem>
	<listitem><para><varname>AOR</varname> = <literal>sip:smith-list@iptel.org</literal></para></listitem>
</itemizedlist>
<para>Resulting rls-services document describing the list will be get from URI: 
<filename>http://localhost/xcap-root/rls-services/global/index/~~/rls-services/service[@uri=%22&lt;smith-list@iptel.org&gt;%22]</filename>,
which means the <literal>service</literal> element with
<parameter>uri</parameter> parameter value
<literal>smith-list@iptel.org</literal> stored in rls-services document named
index.
</para></example>

<section><title>Disadvantages</title>
<para>Working with URIs presented in this section have one big disadvantage - it
needs full XCAP server which is able to work with partial documents and able to
process XPointer expressions in XCAP queries.</para>

<para>Due to unavailability of free XCAP servers is there a possibility to
use SER's RLS server in mode of <emphasis>reduced XCAP server needs</emphasis> 
(see <link linkend="rls.parameters">RLS module parameters</link>). If operating 
in this mode, RLS requests full rls-service document from uri 
<filename>&lt;xcap-root&gt;/rls-services/global/index</filename>, inspects it
and finds requested resource list according to URI and AOR by itself.
(Only if possible! There can't be links 
to partial documents in rls-services document.)
</para>
</section> <!-- disadvantages -->

</section>

<section><title>Standard incompliances</title>
<para>SER's resource lists support is not finished yet, there are some standard
incompliances now:
<itemizedlist>
	<listitem><para>uri canonicalization not done yet according to definition</para></listitem>
	<listitem><para>no subscriptions made to external servers (subscriptions
	only within one SER instance)</para></listitem>
	<listitem><para>full status documents only</para></listitem>
</itemizedlist>
</para>
</section>

</section> <!-- resource lists and SER -->

<section id="xcap.examples"><title>XCAP examples</title>
<note><para>XCAP documents examples published there doesn't use correct XML
namespaces due to problems with XCAP server used for tests (probles querying
partial documents with namespaces).</para></note>

<example><title>Storing XCAP documents</title>
<para>There is a sample script in Python which stores XCAP documents onto a XCAP
server. Documents are:
<itemizedlist>
	<listitem><para><link linkend="rls.xml">rls-services document</link> stored
	under name <filename>index</filename>
	</para></listitem>
	<listitem><para><link linkend="list.xml">buddy list</link> for user Smith
	stored under name <filename>smith</filename></para></listitem>
	<listitem><para><link linkend="pres-rules.xml">presence authorization
	document</link> for user Smith stored under name
	<filename>presence-rules.xml</filename></para></listitem>
</itemizedlist>
</para>
<programlisting>
#!/usr/bin/python
import httplib, urllib

machine = "localhost"

#
# store rls-services document
#

uri = "/xcap-root/rls-services/global/index"
headers = {"Content-Type": "application/rls-services+xml"}
bf = file("rls.xml", "r")
body = bf.read(65536);
conn = httplib.HTTPConnection(machine)
conn.request("PUT", uri, body, headers)

response = conn.getresponse()
print "Storing rls-services document: ", response.status, response.reason
data = response.read()
conn.close()

#
# store resource-list document for user
#

uri = "/xcap-root/resource-lists/users/smith/resource-list.xml"
headers = {"Content-Type": "application/resource-lists+xml"}
bf = file("list.xml", "r")
body = bf.read(65536);
conn = httplib.HTTPConnection(machine)
conn.request("PUT", uri, body, headers)

response = conn.getresponse()
print "Storing resource-lists document: ", response.status, response.reason
data = response.read()
conn.close()

#
# store presence authorization rules
#

uri = "/xcap-root/pres-rules/users/smith/presence-rules.xml"
headers = {"Content-Type": "application/pres-rules+xml"}
bf = file("presence-rules.xml", "r")
body = bf.read(65536);
conn = httplib.HTTPConnection(machine)
conn.request("PUT", uri, body, headers)

response = conn.getresponse()
print "Storing pres-rules document: ", response.status, response.reason
data = response.read()
conn.close()
</programlisting>
</example>

<example id="list.xml"><title>Example resource list document (list.xml)</title>
<para>Simple buddy lists which shows the possibility of nested lists.
</para>
<programlisting>
&lt;?xml version="1.0" ?&gt;
&lt;resource-lists&gt;
	&lt;list name="default"&gt;
		&lt;list name="work"&gt;
			&lt;entry uri="sip:someone@iptel.org"&gt;
				&lt;display-name&gt;Someone&lt;/display-name&gt;
			&lt;/entry&gt;
			&lt;entry uri="sip:smith@iptel.org"&gt;
				&lt;display-name&gt;Jonathan Smith&lt;/display-name&gt;
			&lt;/entry&gt;
		&lt;/list&gt;
		&lt;entry uri="sip:vasek@iptel.org"&gt;
			&lt;display-name&gt;Vasek&lt;/display-name&gt;
		&lt;/entry&gt;
		&lt;entry uri="sip:vaclav.kubart@iptel.org"&gt;
			&lt;display-name&gt;Vaclav Kubart&lt;/display-name&gt;
		&lt;/entry&gt;
	&lt;/list&gt;
&lt;/resource-lists&gt;
</programlisting>
</example>

<example id="rls.xml"><title>Example rls-services document (rls.xml)</title>
<para>Example document which is processed by Resource List Server (RLS module).
This document can contain references to users buddy lists like
<quote>smith-list@iptel.org</quote> which points to buddy list for user smith
named <quote>default</quote> and can contain such lists directly.
<!--<caution><para>EyeBeam stores user's <quote>buddy list</quote> in 
<filename>&lt;XCAP-root&gt;/users/&lt;username&gt;/resource-list.xml</filename>, 
not in
<filename>&lt;XCAP-root&gt;/users/&lt;username&gt;</filename> which was used in 
these examples.</para></caution>-->
</para>
<programlisting>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;rls-services&gt;
	&lt;service uri="sip:smith-list@iptel.org"&gt;
		&lt;resource-list&gt;http://localhost/xcap-root/resource-lists/users/smith/resource-list.xml/~~/resource-lists/list[@name=%22default%22]&lt;/resource-list&gt;
		&lt;packages&gt;
			&lt;package&gt;presence&lt;/package&gt;
		&lt;/packages&gt;
	&lt;/service&gt;
	&lt;service uri="sip:cz@iptel.org"&gt;
		&lt;list name="czech iptel"&gt;
			&lt;entry uri="sip:abc@iptel.org"&gt;
				&lt;display-name&gt;A B&lt;/display-name&gt;
			&lt;/entry&gt;
			&lt;entry uri="sip:cde@iptel.org"&gt;
				&lt;display-name&gt;C D&lt;/display-name&gt;
			&lt;/entry&gt;
			&lt;entry uri="sip:efg@iptel.org"&gt;
				&lt;display-name&gt;Ef Ge&lt;/display-name&gt;
			&lt;/entry&gt;
		&lt;/list&gt;
		&lt;packages&gt;
			&lt;package&gt;presence&lt;/package&gt;
			&lt;package&gt;email&lt;/package&gt;
		&lt;/packages&gt;
	&lt;/service&gt;
&lt;/rls-services&gt;
</programlisting>
</example>

<example id="pres-rules.xml"><title>Example presence authorization document (presence-rules.xml)</title>
<para>This document contains two rules: 
<itemizedlist>
	<listitem><para><quote>white list</quote>, which allows
	access to presence information from all from domain iptel.org
	</para></listitem>
	<listitem><para><quote>black list</quote>, which denies access for user
	nemo@somewhere.net</para></listitem>	
</itemizedlist></para>
<programlisting>
&lt;?xml version="1.0" ?&gt;
&lt;ruleset xmlns="urn:ietf:params:xml:ns:common-policy" xmlns:pr="urn:ietf:params:xml:ns:pres-rules"&gt;
	&lt;rule id="blacklist"&gt;
		&lt;conditions&gt;
			&lt;identity&gt;
				&lt;id&gt;sip:nemo@somewhere.net&lt;/id&gt;
			&lt;/identity&gt;
		&lt;/conditions&gt;
		&lt;actions&gt;
			&lt;pr:sub-handling&gt;block&lt;/pr:sub-handling&gt;
		&lt;/actions&gt;
		&lt;transformations/&gt;
	&lt;/rule&gt;
	
	&lt;rule id="whitelist"&gt;
		&lt;conditions&gt;
			&lt;identity&gt;
				&lt;domain domain="iptel.org"/&gt;
			&lt;/identity&gt;
		&lt;/conditions&gt;
		&lt;actions&gt;
			&lt;pr:sub-handling&gt;allow&lt;/pr:sub-handling&gt;
		&lt;/actions&gt;
		&lt;transformations/&gt;
	&lt;/rule&gt;
&lt;/ruleset&gt;
</programlisting>
</example>

</section>

<!-- There
exist extensions for particular types of configuration - for purpose of this
document only configuration from presence area will be mentioned.
</para>-->

<section><title>XCAP server simulation</title>
<para>XCAP server is a HTTP server with some features like document validation
or ability of working with parts of stored documents. If you have no XCAP
server, you can simulate it using standard web server. There are not many XCAP
servers available today, thus the simulation may be interesting for - at least -
demonstration or testing purposes.
</para>

<para>Depending on your needs you can
<itemizedlist>
	<listitem><para>create hierarchical directory structure of XML documents according to
	<xref linkend="pres_draft_xcap"/></para></listitem>
	<listitem><para>allow upload (handle HTTP PUT method) which stores documents into the 
	directory structure</para></listitem>
	<listitem><para>improve upload to validate documents according to schema
	(every sort of XCAP document should have their XSD published)</para></listitem>
	<listitem><para>allow document removing (handle DELETE method)</para></listitem>
	<listitem><para>process HTTP GET requests with a CGI-script so it processes
	queries for partial documents</para></listitem>
</itemizedlist>
</para>

<section><title>Directory structure</title>
<para>Presence modules use XCAP documents stored in structure like this:
<itemizedlist><title>xcap-root</title>
	<listitem><para><filename>pres-rules</filename></para>
	<itemizedlist>
		<listitem><para><filename>users</filename></para>
		<itemizedlist>
			<listitem><para><filename>smith</filename></para>
			<itemizedlist>
				<listitem><para><filename>presence-rules.xml</filename> (file
				containg presence authorization rules for user smith)</para></listitem>
			</itemizedlist>
			</listitem>
			<listitem><para><filename>joe</filename></para>
			<itemizedlist>
				<listitem><para><filename>presence-rules.xml</filename> (file containing
				presence authorization rules for user joe)</para></listitem>
			</itemizedlist>
			</listitem>
			<listitem><para>... (directories for other users)</para></listitem>
		</itemizedlist>
		</listitem>
	</itemizedlist></listitem>
	
	<listitem><para><filename>resource-lists</filename></para>
	<itemizedlist>
		<listitem><para><filename>users</filename></para>
		<itemizedlist>
			<listitem><para><filename>smith</filename></para>
			<itemizedlist>
				<listitem><para><filename>resource-list.xml</filename> (file
				containing resources lists for user smith)</para></listitem>
			</itemizedlist>
			</listitem>
			<listitem><para><filename>joe</filename></para>
			<itemizedlist>
				<listitem><para><filename>resource-list.xml</filename> (file
				containing resource lists for user joe)</para></listitem>
			</itemizedlist>
			</listitem>
			<listitem><para>... (directories for other users)</para></listitem>
		</itemizedlist>
		</listitem>
		<!-- rls-services globals used instead this
		<listitem><para><filename>global</filename></para>
		<itemizedlist>
			<listitem><para><filename>index</filename> (file containing global
			resource lists)</para></listitem>
		</itemizedlist>
		</listitem>-->
	</itemizedlist></listitem>
	
	<listitem><para><filename>rls-services</filename></para>
	<itemizedlist>
		<listitem><para><filename>global</filename></para>
		<itemizedlist>
			<listitem><para><filename>index</filename> (file containing global
			rls-services documents)</para></listitem>
		</itemizedlist>
		</listitem>
	</itemizedlist></listitem>
	
</itemizedlist>
</para>
</section> <!-- directory structure -->

<section><title>Usage with SER</title>
<para>You don't need a full XCAP server for presence authorization documents -
these are read as standalone documents from directories of standalone users.
</para>

<para>For resource lists you have to set <link linkend="rls.parameters">RLS module 
parameters</link> <varname>mode</varname> and/or
<varname>reduce_xcap_needs</varname> 
to work as much as possible with XCAP server simulation.
</para>
</section>

<section><title>XCAP simulation examples</title>
<para>Examples presented here can be used as simple XCAP server simulation. It
is able to handle PUT method (for whole XML documents).
</para>

<example><title>Apache2 configuration</title>
<programlisting><![CDATA[
...
Alias /xcap-root /var/simulated-xcap-root
<Directory /var/simulated-xcap-root>
	Options Indexes FollowSymLinks MultiViews
	Script PUT /cgi-bin/upload
	<Limit PUT DELETE GET>
		Order Allow,Deny
		Deny from none
		Allow from all
	</Limit>
</Directory>
...
]]></programlisting>
<para>If apache is running on machine with SER, you can use as xcap-root
<literal>http://localhost/xcap-root</literal>.
</para>
</example>

<example><title>Simple (and dangerous) cgi-script for upload</title>
<para>This code is written in C and it is able to create directories if needed, but its usage in
presented form is realy unsafe! You have to compile it and put into directory
with other CGI scripts.</para>
<programlisting><![CDATA[
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#include <sys/stat.h>
#include <sys/types.h>

void copy_file(const char *filename)
{
	char buf[2048];
	int r;
	FILE *f;
	
	f = fopen(filename, "wb");
	if (f) {
		while (!feof(stdin)) {
			r = fread(buf, 1, sizeof(buf), stdin);
			fwrite(buf, 1, r, f);
		}
		fclose(f);
	}
}

int main(int argc, char **argv)
{
	char *filename, *x;
	char tmp[1024];
	int res = 0;
	
	filename = getenv ("PATH_TRANSLATED");

	strcpy(tmp, filename);
	x = strrchr(tmp, '/');
	if (x) {
		*x = 0;
		res = mkdir(tmp, 0755);		/* ! dangerous ! */
	}
	else {
		printf("Status: 500\n");
		printf("Content-Type: text/html\n\n");
		printf("<html><head/>\n<body>Incorrect filename</body></html>\n");	
		return -1;
	}
	
	copy_file(filename); /* ! dangerous ! */
		
	printf("Status: 200\n");
	printf("Content-Type: text/html\n\n");
	printf("<html><head><title>Upload</title>\n</head>\n<body>Finished...</body></html>\n");
	
	return 0;
}
]]></programlisting>
</example>

</section><!-- XCAP simulation examples -->

</section> <!-- XCAP server simulation -->

</section>