doc/presence/draft_iptel_im_rules.xml
c5e54444
 <?xml version='1.0' encoding='UTF-8'?>
 <!DOCTYPE article PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'
 	'http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd'>
 	
 <article lang="en" id="im_rules"><title>MESSAGE authorization rules</title>
 <articleinfo><author><firstname>Vaclav</firstname><surname>Kubart</surname></author>
 </articleinfo>
bf267db9
 <abstract><para>This document follows specification of authorization documents
 suggested by <xref linkend="common_auth"/> and defines a document format for
c5e54444
 storing rules for authorization of instant messages.
 </para></abstract>
 
 <section><title>Terms</title>
 <para>
 <variablelist><title></title>
 <varlistentry>
 	<term>sender</term>
 	<listitem><para>User sending the instant message represented by URI present
 	in From header field.
 	</para></listitem>
 </varlistentry>
 <varlistentry>
 	<term>recipient</term>
 	<listitem><para>User receiving the instant message represented by AOR/To
 	URI.</para></listitem>
 </varlistentry>
 </variablelist>
 </para>
 </section>
 
 <!-- ******************** Documents ********************* -->
 <section id="docs"><title>Instant message authorization documents</title>
 <para>Instant message authorization document is XML document formated according
bf267db9
 to the schema defined in <xref linkend="common_auth"/>. It inherits the MIME
c5e54444
 type of common policy documents defined there - application/auth-policy+xml.
 </para>
 
bf267db9
 <para>All XML elements designed in this document belong to the
981aebf6
 <quote>urn:iptel:xml:ns:im-rules</quote> namespace.
 <note>
 <para>This namespace breaks conventions mentioned in the document which was used
bf267db9
 as a source but it will stay here due to compatibility reasons if there will be no
981aebf6
 problems with it.</para>
 </note>
 </para>
c5e54444
 
 <section><title>Conditions</title>
bf267db9
 <para>Conditions are processed according to the specification in <xref linkend="common_auth"/>.
c5e54444
 </para>
 
 <!--<section><title>Identity representation by URI</title>
 <para>
 </para>
 </section>-->
 
 <section><title>Sphere</title>
 <para>If the "instant messaging server" (proxy) trying to resolve authorization
bf267db9
 rules is bound together with the presence server it can take the sphere value from the
 presence server as defined in <xref linkend="pres_auth"/>, otherwise sphere
 value is considered undefined in terms of common policy processing.</para>
c5e54444
 
 <!-- <para>This sphere
 handling is due to near relation between presence and instant messaging.
 </para>-->
 
 </section>
 
 </section>
 
 <section><title>Actions</title>
 <para>This document defines one action - &lt;im-handling&gt;. It
 is defined an enumerated integer type (like sub-handling in <xref
 linkend="pres_auth"/>). Possible values are:</para>
 <variablelist><title></title>
 <varlistentry>
 	<term>block (value 0)</term>
 	<listitem><para>The message should not be delivered to the user and should
bf267db9
 	be rejected with a 403 Forbidden result code. This is the dafault value of
c5e54444
 	im-handling.
 	</para></listitem>
 </varlistentry>
 <varlistentry>
 	<term>allow (value 1)</term>
 	<listitem><para>The message should be delivered to the destination user.
 	</para></listitem>
 </varlistentry>
 </variablelist>
 
 
bf267db9
 <para>In the future these values may change.</para>
c5e54444
 <para>If there are more matching rules, the resulting action will be the maximum
 of their &lt;im-handling&gt; values.
 </para>
 </section>
 
 <section><title>Transformations</title>
 <para>Transformations are not defined at this moment. In the future there can be
 for example length limitations or some flagging (like <quote>spam</quote>) or
 rate limitations.
 </para>
 </section>
 
 
 </section>
 
 <section><title>Example</title>
 <para>
 <programlisting><![CDATA[
 <?xml version="1.0"?>
 <ruleset xmlns="urn:ietf:params:xml:ns:common-policy"
 xmlns:im="urn:iptel:xml:ns:im-rules">
   <rule id="whitelist">
     <conditions>
       <identity>
bf267db9
         <id>sip:jan@example.com</id>
         <id>sip:pavel@example.com</id>
         <id>sip:vasek@example.com</id>
         <id>sip:ja@example.com</id>
c5e54444
       </identity>
     </conditions>
     <actions>
       <im:im-handling>allow</im:im-handling>
     </actions>
     <transformations/>
   </rule>
   <rule id="blacklist">
     <conditions>
       <identity>
bf267db9
         <id>sip:smith@example.com</id>
c5e54444
       </identity>
     </conditions>
     <actions>
       <im:im-handling>block</im:im-handling>
     </actions>
     <transformations/>
   </rule>
 </ruleset>
 ]]></programlisting>
 </para>
 </section>
 
 
 <section><title>Usage with XCAP</title>
 <para>This document defines <quote>im-rules</quote> as unique application usage
 ID (AUID) requiered by XCAP specification.
 </para>
 
 <section><title>Naming conventions</title>
 <para>When an instant message comes to a IM/presence server (proxy) within its
 domain, the server should look for document
 [xcap-root]/im-rules/users/[recipient username]/im-rules.xml and process rules
 in it.</para>
 </section>
 
 </section>
 
 <!-- ******************** Bibliography ********************* -->
 
 <bibliography id="bib">
 <note><para>There might be new versions of internet drafts and thus links to
 them my be obsolete. In such case try increment version in link or find the
 draft on <ulink url="http://www.ietf.org">IETF</ulink> by name.</para></note>
 
 <biblioentry id="common_auth">
 <abbrev>common auth</abbrev>
 <title><ulink
 url="http://www.ietf.org/internet-drafts/draft-ietf-geopriv-common-policy-05.txt"
 >draft-ietf-geopriv-common-policy-05.txt</ulink></title>
 </biblioentry>
 
 <biblioentry id="pres_auth">
 <abbrev>presence auth</abbrev>
 <title><ulink url="http://www.ietf.org/internet-drafts/draft-ietf-simple-presence-rules-03.txt"
 >draft-ietf-simple-presence-rules-03.txt</ulink> - presence authorization XML based data format 
 and usage with XCAP</title>
 </biblioentry>
 
 </bibliography>
 
 </article>