# XCAP authorization

## Presence authorization documents

Presence authorization documents are described in and they are not fully supported now. We ignore sphere, transformations and date and time conditions. [Are there any clients supporting this?].

### presence authorization document

This document has two rules: one named blacklist disabling subscriptions from user smith and one named whitelist enabling subscriptions from all other users from domain test-domain.com. (It doesn't depend on names of rules but on actions for them.)

    <?xml version="1.0" encoding="UTF-8" standalone="no" ?>
    <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:smith@test-domain.com</id>
    			</identity>
    		</conditions>
    		<actions>
    			<pr:sub-handling>block</pr:sub-handling>
    		</actions>
    		<transformations/>
    	</rule>

    	<rule id="whitelist">
    		<conditions>
    			<identity>
    				<domain domain="test-domain.com"/>
    				<except entity="smith"/>
    			</identity>
    		</conditions>
    		<actions>
    			<pr:sub-handling>allow</pr:sub-handling>
    		</actions>
    		<transformations/>
    	</rule>
    </ruleset>

## Presence authorization document URI

Authorization documents are read for presentities according to their presentity URIs (presentity URI is URI in To header of SUBSCRIBE request). Resulting XCAP URI with authorization document is:

`<xcap-root>/pres-rules/users/<username>/presence-rules.xml`,

where `<xcap-root>` is set in configuration of XCAP module and `<username>` is UUID (unique user identification used in SER everywhere) discovered from presentity URI.

If you need to use other filename than default presence-rules.xml, you can redefine it by parameter `pres_rules_file`. Problem can be, that `pres_rules_file` is specified as module parameter and thus common for all users.

### presence authorization document uri

For example for presentity `sip:joe@someorg.org` with UUID joe and `xcap-root` `http://localhost/xcap-root` will be the URI for the authorization document `http://localhost/xcap-root/pres-rules/users/joe/presence-rules.xml`

## Message authorization documents

Message authorization documents are described in . We ignore sphere, transformations and date and time conditions like in the case of presence authorization.

### message authorization document

This document has one rule named blacklist disabling messages sent from users jan@test-domain.com and jana@test-domain.com.

    <?xml version="1.0" encoding="UTF-8" standalone="no" ?>
    <ruleset xmlns="urn:ietf:params:xml:ns:common-policy" xmlns:im="urn:iptel:xml:ns:im-rules">
    	<rule id="blacklist">
    		<conditions>
    			<identity>
    				<id>sip:jana@test-domain.com</id>
    				<id>sip:jan@test-domain.com</id>
    			</identity>
    		</conditions>
    		<actions>
    			<im:im-handling>block</im:im-handling>
    		</actions>
    		<transformations/>
    	</rule>
    </ruleset>

## Message authorization document URI

Authorization documents are read for recipients according to To URIs. Resulting URI for XCAP query will be:

`<xcap-root>/im-rules/users/<username>/im-rules.xml` where `<xcap-root>` is set in configuration of XCAP module, im-rules.xml is default filename for message authorization rules (may be redefined in `authorize_message` call parameter) and `<username>` is UUID discovered from To URI.

### message authorization document uri

For example for recipient `sip:smith@someorg.org` with UUID smith and `xcap-root` `http://localhost/xcap-root` will be the URI for the authorization document `http://localhost/xcap-root/im-rules/users/smith/im-rules.xml`

## Disadvantages

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 XCAP change notifications described in and (planned in future versions).

## Standard incompliances

XCAP authorization support is not finished yet, there are some standard incompliances now:

- ignored sphere

- ignored date and time conditions

- ignored transformations

- Presentity URI is taken from To header field instead of AOR because AOR in consequent SUBSCRIBE requests is set to "contact to server URI" instead of user's URI (RFCs contradict themselves).

- We use UUID instead of whole presentity URI as `<username>` due to possibility of using the same authorization document for more user's aliases (TODO: control this by module parameter?).

- According to current presence authorization draft should presence server look for ALL authorization documents within user's directory on XCAP server, but listing documents on XCAP server is NOT defined. This will be partialy solved in future by possibility of having list of authorization documents as user's attributes.