# XCAP

## Introduction

XCAP is a HTTP based protocol for access remote configuration data. Data is stored in XML format and the XCAP protocol allows to query, modify or delete parts of such data. This is in detail described in pres_rfc_xcap. The XCAP server is server able to handle XCAP requests.

The XCAP server may be used for storing presence interesting data. From the SIP_ROUTER's point of view these items are interesting:

- authorization data

- buddy lists

### XCAP authorization

Definition of authorization documents and theirs usage is specified in pres_draft_common_auth and especially for presence purposes in pres_draft_auth. Both documents are quite common and in SIP_ROUTER's presence modules implemented only partially. For more information about XCAP authorization see details in pa.xcap.

### Buddy lists

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 on it 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 and thus require TCP connection.

There may be not only lists for individual users with their contacts but there may be other sort of lists representing some logical entities such businessmen, technical support, ... 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 technical-support@somewhere.net if he needs help from them.

Lists of users - more common resource lists - are defined in pres_draft_rls and their usage with SIP in pres_draft_rls_sip. These lists are partially implemented in RLS module. For more information about resource lists see details in rls.xcap.

### Manipulation with XCAP documents

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 SIP_ROUTER although there are is not much client software supporting it.

## XCAP examples

XCAP documents examples published there doesn't use correct XML namespaces due to problems with XCAP server used for tests (problems querying partial documents with namespaces).

### Storing XCAP documents

There is a sample script in Python which stores XCAP documents onto a XCAP server. Documents are:

- rls-services document stored under name `index`

- buddy list for user Smith stored under name `smith`

- presence authorization document for user Smith stored under name `presence-rules.xml`

    #!/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()

### Example resource list document (list.xml)

Simple buddy lists which shows the possibility of nested lists.

    <?xml version="1.0" ?>
    <resource-lists>
    	<list name="default">
    		<list name="work">
    			<entry uri="sip:someone@someorg.org">
    				<display-name>Someone</display-name>
    			</entry>
    			<entry uri="sip:smith@someorg.org">
    				<display-name>Jonathan Smith</display-name>
    			</entry>
    		</list>
    		<entry uri="sip:vasek@someorg.org">
    			<display-name>Vasek</display-name>
    		</entry>
    		<entry uri="sip:vaclav.picbumprask@someorg.org">
    			<display-name>Vaclav Picbumprask</display-name>
    		</entry>
    	</list>
    </resource-lists>

### Example rls-services document (rls.xml)

Example document which is processed by Resource List Server (RLS module). This document can contain references to users buddy lists like smith-list@someorg.org which points to buddy list for user smith named default and can contain such lists directly.

    <?xml version="1.0" encoding="UTF-8"?>
    <rls-services>
    	<service uri="sip:smith-list@someorg.org">
    		<resource-list>http://localhost/xcap-root/resource-lists/users/smith/resource-list.xml/~~/resource-lists/list[@name=%22default%22]</resource-list>
    		<packages>
    			<package>presence</package>
    		</packages>
    	</service>
    	<service uri="sip:cz@someorg.org">
    		<list name="czech part of some org">
    			<entry uri="sip:abc@someorg.org">
    				<display-name>A B</display-name>
    			</entry>
    			<entry uri="sip:cde@someorg.org">
    				<display-name>C D</display-name>
    			</entry>
    			<entry uri="sip:efg@someorg.org">
    				<display-name>Ef Ge</display-name>
    			</entry>
    		</list>
    		<packages>
    			<package>presence</package>
    			<package>email</package>
    		</packages>
    	</service>
    </rls-services>

### Example presence authorization document (presence-rules.xml)

This document contains two rules:

- white list, which allows access to presence information from all from domain someorg.org

- black list, which denies access for user nemo@somewhere.net

    <?xml version="1.0" ?>
    <ruleset xmlns="urn:ietf:params:xml:ns:common-policy" xmlns:pr="urn:ietf:params:xml:ns:pres-rules">
    	<rule id="blacklist">
    		<conditions>
    			<identity>
    				<id>sip:nemo@somewhere.net</id>
    			</identity>
    		</conditions>
    		<actions>
    			<pr:sub-handling>block</pr:sub-handling>
    		</actions>
    		<transformations/>
    	</rule>

    	<rule id="whitelist">
    		<conditions>
    			<identity>
    				<domain domain="someorg.org"/>
    			</identity>
    		</conditions>
    		<actions>
    			<pr:sub-handling>allow</pr:sub-handling>
    		</actions>
    		<transformations/>
    	</rule>
    </ruleset>

## XCAP server simulation

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.

There are some disadvantages when the XCAP server is only simulated:

- no XML document validation

- unable to work with XPointer terms (mainly unable to work with parts of documents)

- possible synchronization problems (!)

  More clients used by one user working with the same document (authorization document, buddy list) may rewrite it to each other. When using regular XCAP server this will be done in one atomic query. In the case of simulation it is needed to download whole document, modify it and put it back.

Depending on your needs you can

- create hierarchical directory structure of XML documents according to pres_rfc_xcap

- allow upload (handle HTTP PUT method) which stores documents into the directory structure

- improve upload to validate documents according to schema (every sort of XCAP document should have their XSD published)

- allow document removing (handle DELETE method)

- process HTTP GET requests with a CGI-script so it processes queries for partial documents

### Directory structure

Presence modules use XCAP documents stored in structure like this:

### xcap-root

- `pres-rules`

  - `users`

    - `smith`

      - `presence-rules.xml` (file containg presence authorization rules for user smith)

    - `joe`

      - `presence-rules.xml` (file containing presence authorization rules for user joe)

    - ... (directories for other users)

- `resource-lists`

  - `users`

    - `smith`

      - `resource-list.xml` (file containing resources lists for user smith)

    - `joe`

      - `resource-list.xml` (file containing resource lists for user joe)

    - ... (directories for other users)

- `rls-services`

  - `global`

    - `index` (file containing global rls-services documents)

### Usage with SIP_ROUTER

You don't need a full XCAP server for presence authorization documents - these are read as standalone documents from directories of standalone users.

For resource lists you have to set RLS module parameters `mode` and/or `reduce_xcap_needs` to work as much as possible with XCAP server simulation.

### XCAP simulation examples

Examples presented here can be used as simple XCAP server simulation. It is able to handle PUT method (for whole XML documents).

#### Apache2 configuration

    ...
    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>
    ...

If apache is running on machine with SIP_ROUTER, you can use as xcap-root `http://localhost/xcap-root`.

#### Simple (and dangerous) cgi-script for upload

This code is written in C and it is able to create directories if needed, but its usage in presented form is really unsafe! You have to compile it and put into directory with other CGI scripts.

    #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;
    }