1<?xml version='1.0' encoding='UTF-8'?> 2<!DOCTYPE section PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN' 3 'http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd'> 4 5<section><title>XCAP</title> 6 7<section><title>Introduction</title> 8 9<para>XCAP is a HTTP based protocol for access remote configuration data. Data 10is stored in XML format and the XCAP protocol allows to query, modify or delete 11parts of such data. This is in detail described in <xref 12linkend="pres_rfc_xcap"/>. The XCAP server is server able to handle XCAP requests. 13</para> 14 15<para>The XCAP server may be used for storing <quote>presence interesting</quote> 16data. From the SIP_ROUTER's point of view these items are interesting: 17<itemizedlist> 18 <listitem><para>authorization data</para></listitem> 19 <listitem><para><quote>buddy lists</quote></para></listitem> 20</itemizedlist> 21</para> 22 23<section><title>XCAP authorization</title> 24<para>Definition of authorization documents and theirs usage is specified in <xref 25linkend="pres_draft_common_auth"/> and especially for presence purposes in <xref 26linkend="pres_draft_auth"/>. Both documents are quite common and in SIP_ROUTER's 27presence modules implemented only partialy. For more information about XCAP 28authorization see details in <xref linkend="pa.xcap"/>.</para> 29</section> <!-- XCAP authorization --> 30 31<section><title>Buddy lists</title> 32<para>XCAP server may be used for storing lists of users too. These lists may be 33used for presence subscriptions - subscription to such list means subscription 34to all users on it at once. This reduces number of created subscriptions and may 35reduce data transfers between server and client too; but presence documents for 36lists of users may be very big and thus require TCP connection.</para> 37 38<para>There may be not only lists for individual users with their contacts but 39there may be other sort of lists representing some <quote>logical 40entities</quote> such <quote>businessmen</quote>, <quote>technical 41support</quote>, ... which are used in cases like if some customer needs someone 42from technical support department and doesn't want to remeber all people 43there. Such customer may simply watch presence state of 44<quote>technical-support@somewhere.net</quote> if he needs help from them. 45</para> 46 47<para>Lists of users - more common resource lists - are defined in <xref 48linkend="pres_draft_rls"/> and their usage with SIP in <xref 49linkend="pres_draft_rls_sip"/>. These lists are partialy implemented in <link 50linkend="pres_rls">RLS module</link>. 51For more information about resource lists see details in <xref 52linkend="rls.xcap"/>.</para> 53</section> <!-- buddy lists --> 54 55<section><title>Manipulation with XCAP documents</title> 56<para>Manipulating with XCAP documents is quite simple because XCAP uses 57standard HTTP methods like GET, PUT or DELETE. Every web browser may be 58used to read XCAP data and it is quite simple to write utility to write data 59to XCAP server. These features allow to use XCAP with SIP_ROUTER although there are is 60not much client software supporting it. 61</para> 62</section> <!-- manipulating documents --> 63 64</section> <!-- XCAP introduction --> 65 66<section id="xcap.examples"><title>XCAP examples</title> 67<note><para>XCAP documents examples published there doesn't use correct XML 68namespaces due to problems with XCAP server used for tests (problems querying 69partial documents with namespaces).</para></note> 70 71<example><title>Storing XCAP documents</title> 72<para>There is a sample script in Python which stores XCAP documents onto a XCAP 73server. Documents are: 74<itemizedlist> 75 <listitem><para><link linkend="rls.xml">rls-services document</link> stored 76 under name <filename>index</filename> 77 </para></listitem> 78 <listitem><para><link linkend="list.xml">buddy list</link> for user Smith 79 stored under name <filename>smith</filename></para></listitem> 80 <listitem><para><link linkend="pres-rules.xml">presence authorization 81 document</link> for user Smith stored under name 82 <filename>presence-rules.xml</filename></para></listitem> 83</itemizedlist> 84</para> 85<programlisting> 86#!/usr/bin/python 87import httplib, urllib 88 89machine = "localhost" 90 91# 92# store rls-services document 93# 94 95uri = "/xcap-root/rls-services/global/index" 96headers = {"Content-Type": "application/rls-services+xml"} 97bf = file("rls.xml", "r") 98body = bf.read(65536); 99conn = httplib.HTTPConnection(machine) 100conn.request("PUT", uri, body, headers) 101 102response = conn.getresponse() 103print "Storing rls-services document: ", response.status, response.reason 104data = response.read() 105conn.close() 106 107# 108# store resource-list document for user 109# 110 111uri = "/xcap-root/resource-lists/users/smith/resource-list.xml" 112headers = {"Content-Type": "application/resource-lists+xml"} 113bf = file("list.xml", "r") 114body = bf.read(65536); 115conn = httplib.HTTPConnection(machine) 116conn.request("PUT", uri, body, headers) 117 118response = conn.getresponse() 119print "Storing resource-lists document: ", response.status, response.reason 120data = response.read() 121conn.close() 122 123# 124# store presence authorization rules 125# 126 127uri = "/xcap-root/pres-rules/users/smith/presence-rules.xml" 128headers = {"Content-Type": "application/pres-rules+xml"} 129bf = file("presence-rules.xml", "r") 130body = bf.read(65536); 131conn = httplib.HTTPConnection(machine) 132conn.request("PUT", uri, body, headers) 133 134response = conn.getresponse() 135print "Storing pres-rules document: ", response.status, response.reason 136data = response.read() 137conn.close() 138</programlisting> 139</example> 140 141<example id="list.xml"><title>Example resource list document (list.xml)</title> 142<para>Simple buddy lists which shows the possibility of nested lists. 143</para> 144<programlisting> 145<?xml version="1.0" ?> 146<resource-lists> 147 <list name="default"> 148 <list name="work"> 149 <entry uri="sip:someone@someorg.org"> 150 <display-name>Someone</display-name> 151 </entry> 152 <entry uri="sip:smith@someorg.org"> 153 <display-name>Jonathan Smith</display-name> 154 </entry> 155 </list> 156 <entry uri="sip:vasek@someorg.org"> 157 <display-name>Vasek</display-name> 158 </entry> 159 <entry uri="sip:vaclav.picbumprask@someorg.org"> 160 <display-name>Vaclav Picbumprask</display-name> 161 </entry> 162 </list> 163</resource-lists> 164</programlisting> 165</example> 166 167<example id="rls.xml"><title>Example rls-services document (rls.xml)</title> 168<para>Example document which is processed by Resource List Server (RLS module). 169This document can contain references to users buddy lists like 170<quote>smith-list@someorg.org</quote> which points to buddy list for user smith 171named <quote>default</quote> and can contain such lists directly. 172<!--<caution><para>EyeBeam stores user's <quote>buddy list</quote> in 173<filename><XCAP-root>/users/<username>/resource-list.xml</filename>, 174not in 175<filename><XCAP-root>/users/<username></filename> which was used in 176these examples.</para></caution>--> 177</para> 178<programlisting> 179<?xml version="1.0" encoding="UTF-8"?> 180<rls-services> 181 <service uri="sip:smith-list@someorg.org"> 182 <resource-list>http://localhost/xcap-root/resource-lists/users/smith/resource-list.xml/~~/resource-lists/list[@name=%22default%22]</resource-list> 183 <packages> 184 <package>presence</package> 185 </packages> 186 </service> 187 <service uri="sip:cz@someorg.org"> 188 <list name="czech part of some org"> 189 <entry uri="sip:abc@someorg.org"> 190 <display-name>A B</display-name> 191 </entry> 192 <entry uri="sip:cde@someorg.org"> 193 <display-name>C D</display-name> 194 </entry> 195 <entry uri="sip:efg@someorg.org"> 196 <display-name>Ef Ge</display-name> 197 </entry> 198 </list> 199 <packages> 200 <package>presence</package> 201 <package>email</package> 202 </packages> 203 </service> 204</rls-services> 205</programlisting> 206</example> 207 208<example id="pres-rules.xml"><title>Example presence authorization document (presence-rules.xml)</title> 209<para>This document contains two rules: 210<itemizedlist> 211 <listitem><para><quote>white list</quote>, which allows 212 access to presence information from all from domain someorg.org 213 </para></listitem> 214 <listitem><para><quote>black list</quote>, which denies access for user 215 nemo@somewhere.net</para></listitem> 216</itemizedlist></para> 217<programlisting> 218<?xml version="1.0" ?> 219<ruleset xmlns="urn:ietf:params:xml:ns:common-policy" xmlns:pr="urn:ietf:params:xml:ns:pres-rules"> 220 <rule id="blacklist"> 221 <conditions> 222 <identity> 223 <id>sip:nemo@somewhere.net</id> 224 </identity> 225 </conditions> 226 <actions> 227 <pr:sub-handling>block</pr:sub-handling> 228 </actions> 229 <transformations/> 230 </rule> 231 232 <rule id="whitelist"> 233 <conditions> 234 <identity> 235 <domain domain="someorg.org"/> 236 </identity> 237 </conditions> 238 <actions> 239 <pr:sub-handling>allow</pr:sub-handling> 240 </actions> 241 <transformations/> 242 </rule> 243</ruleset> 244</programlisting> 245</example> 246 247</section> 248 249<!-- There 250exist extensions for particular types of configuration - for purpose of this 251document only configuration from presence area will be mentioned. 252</para>--> 253 254<section><title>XCAP server simulation</title> 255<para>XCAP server is a HTTP server with some features like document validation 256or ability of working with parts of stored documents. If you have no XCAP 257server, you can simulate it using standard web server. There are not many XCAP 258servers available today, thus the simulation may be interesting for - at least - 259demonstration or testing purposes. 260</para> 261 262<para>There are some disadvantages when the XCAP server is only simulated: 263<itemizedlist> 264 <listitem><para>no XML document validation</para></listitem> 265 <listitem><para>unable to work with XPointer terms (mainly unable to work 266 with parts of documents)</para></listitem> 267 <listitem><para>possible synchronization problems (!)</para> 268 <para>More clients used by one user working with the same document 269 (authorization document, buddy list) may rewrite it to each other. 270 When using regular XCAP server this will be done in one atomic query. 271 In the case of simulation it is needed to download whole document, 272 modify it and put it back.</para> 273 </listitem> 274</itemizedlist> 275</para> 276 277<para>Depending on your needs you can 278<itemizedlist> 279 <listitem><para>create hierarchical directory structure of XML documents according to 280 <xref linkend="pres_rfc_xcap"/></para></listitem> 281 <listitem><para>allow upload (handle HTTP PUT method) which stores documents into the 282 directory structure</para></listitem> 283 <listitem><para>improve upload to validate documents according to schema 284 (every sort of XCAP document should have their XSD published)</para></listitem> 285 <listitem><para>allow document removing (handle DELETE method)</para></listitem> 286 <listitem><para>process HTTP GET requests with a CGI-script so it processes 287 queries for partial documents</para></listitem> 288</itemizedlist> 289</para> 290 291<section><title>Directory structure</title> 292<para>Presence modules use XCAP documents stored in structure like this: 293<itemizedlist><title>xcap-root</title> 294 <listitem><para><filename>pres-rules</filename></para> 295 <itemizedlist> 296 <listitem><para><filename>users</filename></para> 297 <itemizedlist> 298 <listitem><para><filename>smith</filename></para> 299 <itemizedlist> 300 <listitem><para><filename>presence-rules.xml</filename> (file 301 containg presence authorization rules for user smith)</para></listitem> 302 </itemizedlist> 303 </listitem> 304 <listitem><para><filename>joe</filename></para> 305 <itemizedlist> 306 <listitem><para><filename>presence-rules.xml</filename> (file containing 307 presence authorization rules for user joe)</para></listitem> 308 </itemizedlist> 309 </listitem> 310 <listitem><para>... (directories for other users)</para></listitem> 311 </itemizedlist> 312 </listitem> 313 </itemizedlist></listitem> 314 315 <listitem><para><filename>resource-lists</filename></para> 316 <itemizedlist> 317 <listitem><para><filename>users</filename></para> 318 <itemizedlist> 319 <listitem><para><filename>smith</filename></para> 320 <itemizedlist> 321 <listitem><para><filename>resource-list.xml</filename> (file 322 containing resources lists for user smith)</para></listitem> 323 </itemizedlist> 324 </listitem> 325 <listitem><para><filename>joe</filename></para> 326 <itemizedlist> 327 <listitem><para><filename>resource-list.xml</filename> (file 328 containing resource lists for user joe)</para></listitem> 329 </itemizedlist> 330 </listitem> 331 <listitem><para>... (directories for other users)</para></listitem> 332 </itemizedlist> 333 </listitem> 334 <!-- rls-services globals used instead this 335 <listitem><para><filename>global</filename></para> 336 <itemizedlist> 337 <listitem><para><filename>index</filename> (file containing global 338 resource lists)</para></listitem> 339 </itemizedlist> 340 </listitem>--> 341 </itemizedlist></listitem> 342 343 <listitem><para><filename>rls-services</filename></para> 344 <itemizedlist> 345 <listitem><para><filename>global</filename></para> 346 <itemizedlist> 347 <listitem><para><filename>index</filename> (file containing global 348 rls-services documents)</para></listitem> 349 </itemizedlist> 350 </listitem> 351 </itemizedlist></listitem> 352 353</itemizedlist> 354</para> 355</section> <!-- directory structure --> 356 357<section><title>Usage with SIP_ROUTER</title> 358<para>You don't need a full XCAP server for presence authorization documents - 359these are read as standalone documents from directories of standalone users. 360</para> 361 362<para>For resource lists you have to set <link linkend="rls.parameters">RLS module 363parameters</link> <varname>mode</varname> and/or 364<varname>reduce_xcap_needs</varname> 365to work as much as possible with XCAP server simulation. 366</para> 367</section> 368 369<section><title>XCAP simulation examples</title> 370<para>Examples presented here can be used as simple XCAP server simulation. It 371is able to handle PUT method (for whole XML documents). 372</para> 373 374<example><title>Apache2 configuration</title> 375<programlisting><![CDATA[ 376... 377Alias /xcap-root /var/simulated-xcap-root 378<Directory /var/simulated-xcap-root> 379 Options Indexes FollowSymLinks MultiViews 380 Script PUT /cgi-bin/upload 381 <Limit PUT DELETE GET> 382 Order Allow,Deny 383 Deny from none 384 Allow from all 385 </Limit> 386</Directory> 387... 388]]></programlisting> 389<para>If apache is running on machine with SIP_ROUTER, you can use as xcap-root 390<literal>http://localhost/xcap-root</literal>. 391</para> 392</example> 393 394<example><title>Simple (and dangerous) cgi-script for upload</title> 395<para>This code is written in C and it is able to create directories if needed, but its usage in 396presented form is realy unsafe! You have to compile it and put into directory 397with other CGI scripts.</para> 398<programlisting><![CDATA[ 399#include <stdio.h> 400#include <stdlib.h> 401#include <string.h> 402 403#include <sys/stat.h> 404#include <sys/types.h> 405 406void copy_file(const char *filename) 407{ 408 char buf[2048]; 409 int r; 410 FILE *f; 411 412 f = fopen(filename, "wb"); 413 if (f) { 414 while (!feof(stdin)) { 415 r = fread(buf, 1, sizeof(buf), stdin); 416 fwrite(buf, 1, r, f); 417 } 418 fclose(f); 419 } 420} 421 422int main(int argc, char **argv) 423{ 424 char *filename, *x; 425 char tmp[1024]; 426 int res = 0; 427 428 filename = getenv ("PATH_TRANSLATED"); 429 430 strcpy(tmp, filename); 431 x = strrchr(tmp, '/'); 432 if (x) { 433 *x = 0; 434 res = mkdir(tmp, 0755); /* ! dangerous ! */ 435 } 436 else { 437 printf("Status: 500\n"); 438 printf("Content-Type: text/html\n\n"); 439 printf("<html><head/>\n<body>Incorrect filename</body></html>\n"); 440 return -1; 441 } 442 443 copy_file(filename); /* ! dangerous ! */ 444 445 printf("Status: 200\n"); 446 printf("Content-Type: text/html\n\n"); 447 printf("<html><head><title>Upload</title>\n</head>\n<body>Finished...</body></html>\n"); 448 449 return 0; 450} 451]]></programlisting> 452</example> 453 454</section><!-- XCAP simulation examples --> 455 456</section> <!-- XCAP server simulation --> 457 458</section> 459