xeps/xep-0314.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
  <!ENTITY LABEL "<tt>&lt;label/&gt;</tt>">
  <!ENTITY CATALOG "<tt>&lt;catalog/&gt;</tt>">
  <!ENTITY ITEM "<tt>&lt;item/&gt;</tt>">
  <!ENTITY SECURITYLABEL "<tt>&lt;securitylabel/&gt;</tt>">
  <!ENTITY DISPLAYMARKING "<tt>&lt;displaymarking/&gt;</tt>">
  <!ENTITY EQUIVALENTLABEL "<tt>&lt;equivalentlabel/&gt;</tt>">
  <!ENTITY HEADLINE "<tt>&lt;headline/&gt;</tt>">
  <!ENTITY IDENTITY "<tt>&lt;identity/&gt;</tt>">
  <!ENTITY PUBLISH "<tt>&lt;publish/&gt;</tt>">
  <!ENTITY ITEMNOTFOUND "<tt>&lt;item-not-found/&gt;</tt>">
  <!ENTITY NOTAUTHORIZED "<tt>&lt;not-authorized/&gt;</tt>">
  <!ENTITY NOTACCEPTABLE "<tt>&lt;not-acceptable/&gt;</tt>">
  <!ENTITY INSUFFICIENTCLEARANCE "<tt>&lt;insufficient-clearance/&gt;</tt>">
  <!ENTITY ITEMS "<tt>&lt;items/&gt;</tt>">
  <!ENTITY ASSOCIATE "<tt>&lt;associate/&gt;</tt>">
  <!ENTITY NSMAIN "urn:xmpp:sec-label:pubsub:0">
  <!ENTITY NSERRORS "urn:xmpp:sec-label:pubsub:errors:0">
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>Security Labels in PubSub</title>
  <abstract>This specification defines an extension to XEP-0258 (Security Labels) to allow for the
    use of security labels in XEP-0060 (Publish-Subscribe). This document describes how security
    label metadata can be applied to the various elements within Publish-Subscribe, including nodes
    and items.
  </abstract>
  &LEGALNOTICE;
  <number>0314</number>
  <status>Deferred</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
    <spec>XEP-0060</spec>
    <spec>XEP-0258</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>NOT_YET_ASSIGNED</shortname>
  <author>
    <firstname>Ashley</firstname>
    <surname>Ward</surname>
    <email>ashley.ward@surevine.com</email>
    <jid>ashward@jabber.org</jid>
    <uri>http://www.surevine.com/</uri>
  </author>
  <revision>
    <version>0.1</version>
    <date>2012-07-27</date>
    <initials>psa</initials>
    <remark><p>Initial published version.</p></remark>
  </revision>
  <revision>
    <version>0.0.1</version>
    <date>2012-06-08</date>
    <initials>asw</initials>
    <remark><p>First draft.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>The use of security labels within XMPP is currently defined in &xep0258;. This, however, does
    not cover the use of security labels within &xep0060;. This XEP defines a method to include
    security labels into publish-subscribe.</p>
  <p>This allows content publishers to limit visibility of any sensitive published items to only
    those users with appropriate clearance to view them.</p>
  <p>This document does not deal with the semantics of a Security Label or how the security policy
    is applied to decisions regarding Security Labels and Clearances.</p>
  <p>This document should be read in conjunction with &xep0060; and &xep0258;.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
  <ul>
    <li>A publisher MUST be able to apply a Security Label to items within a node.</li>
    <li>A node creator SHOULD be able to apply a Security Label to a node (this controls which
      entities can access the node).</li>
    <li>A node creator SHOULD be able to apply a Clearance to a node (this controls which Security
      Labels can be applied to items within the node).</li>
    <li>A node creator MAY be able to apply a default Security Label to a node (this applies to
      items published to the node without a Security Label).</li>
    <li>Node lists returned by the server SHOULD NOT contain nodes that the requesting entity is
      not Cleared to view.</li>
    <li>Item lists returned by the server MUST NOT contain items that the requesting entity is not
      Cleared to view.</li>
    <li>A client SHOULD only publish items to a node that are compatible with the Clearance of the
      node (if the node has a Clearance), and a server MUST NOT store such items against the node
      or send any notifications of any such items to subscribers.</li>
    <li>Server responses from a request involving a node that the entity is not Cleared to view
      SHOULD be identical to a response as if that node did not exist.</li>
    <li>Server responses from a request involving an item that the entity is not Cleared to view
      MUST be identical to a response as if that item did not exist.</li>
    <li>A server MUST NOT notify or deliver items to an entity that the entity does not have
      appropriate Clearance to view.</li>
  </ul>
</section1>
<section1 topic='Glossary' anchor='glossary'>
  <p>In addition to the Glossary defined for &xep0060; the following terms are used:</p>
  <dl>
    <di>
      <dt>Security Label</dt>
      <dd>
        <p>A label that can be applied to content to restrict the visibility of the content to
          entities with appropriate Clearance.</p>
        <p>The schema is defined in &xep0258; with the XML namespace "urn:xmpp:sec-label:0".</p>
      </dd>
    </di>
  	<di>
  	 <dt>Clearance</dt>
  	 <dd>A collection of Security Labels that an entity is authorized to access.</dd>
    </di>
    <di>
     <dt>Cleared</dt>
     <dd>An entity is Cleared to access content if the Access Control Decision Function (ACDF) of
       the server yields a <em>Grant</em> given the entity's Clearance, the Security Label of the
       content and the governing security policy.</dd>
    </di>
  </dl>
</section1>
<section1 topic='Entity Use Cases' anchor='entityusecases'>
  <p>This section defines the additions and caveats for the use cases and protocols defined in
    &xep0060;.</p>
  <section2 topic='Discovering Feature Support' anchor='entityusecases-discoveringfeaturesupport'>
    <p>A Security Label aware client SHOULD discover support for Security Labels within the
      &xep0060; service domain. If the service domain does not report support for Security Labels
      then the client SHOULD NOT publish with Security Labels.</p>
    <example caption='Service discovery information request'><![CDATA[
<iq from='francisco@denmark.lit/barracks'
    id='disco1'
    to='pubsub.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
      ]]></example>
    <example caption='Service discovery information response'><![CDATA[
<iq from='pubsub.shakespeare.lit'
    id='disco1'
    to='francisco@denmark.lit/barracks'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='urn:xmpp:sec-label:0'/>
    ...
  </query>
</iq>
      ]]></example>
  	<p>A server SHOULD provide label feature and information discovery for each node.</p>
    <p>Clients SHOULD discover label feature and information on a per-node basis.</p>
  	<example caption='Label feature discovery request for a node'><![CDATA[
<iq from='francisco@denmark.lit/barracks'
    id='disco2'
    to='pubsub.shakespeare.lit'
    type='get'>
  <query node='princely_musings' xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
  	  ]]></example>
    <example caption='Label feature discovery response for a node'><![CDATA[
<iq from='pubsub.shakespeare.lit'
    id='disco2'
    to='francisco@denmark.lit/barracks'
    type='result'>
  <query node='princely_musings' xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='urn:xmpp:sec-label:catalog:2'/>
    ...
  </query>
</iq>
      ]]></example>
    <p>A server SHOULD provide Security Label catalog discovery for each node.</p>
    <p>Clients SHOULD discover the Security Label catalog on a per-node basis.</p>
    <p>The server SHOULD limit the catalog for a node to those labels that are compatible with any
      Clearance associated with the node.</p>
    <example caption='The client requests the catalog for a node'><![CDATA[
<iq id='cat1'
    to='pubsub.shakespeare.lit'
    type='get'>
  <catalog xmlns='urn:xmpp:sec-label:catalog:2'
           to='pubsub.shakespeare.lit'
           node='princely_musings'/>
</iq>
      ]]></example>
    <example caption='The server responds with the catalog for the node'><![CDATA[
<iq from='pubsub.shakespeare.lit'
    id='cat1'
    to='francisco@denmark.lit/barracks'
    type='result'>
  <catalog xmlns='urn:xmpp:sec-label:catalog:2'
      to='example.com'
      name='Default'
      desc='The set of labels applicable to the &quot;princely_musings&quot; node'
      restrict='false'
      node='princely_musings'>
    <item selector="Classified|SECRET">
      <securitylabel xmlns='urn:xmpp:sec-label:0'>
        <displaymarking fgcolor='black' bgcolor='red'>SECRET</displaymarking>
        <label>
          <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'
            >MQYCAQQGASk=</esssecuritylabel>
        </label>
      </securitylabel>
    </item>
    <item selector="Classified|CONFIDENTIAL">
      <securitylabel xmlns='urn:xmpp:sec-label:0'>
        <displaymarking fgcolor='black' bgcolor='navy'>CONFIDENTIAL</displaymarking>
        <label>
          <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'
            >MQYCAQMGASk</esssecuritylabel>
        </label>
      </securitylabel>
    </item>
    <item selector="Classified|RESTRICTED">
      <securitylabel xmlns='urn:xmpp:sec-label:0'>
        <displaymarking fgcolor='black' bgcolor='aqua'>RESTRICTED</displaymarking>
        <label>
          <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'
            >MQYCAQIGASk=</esssecuritylabel>
        </label>
      </securitylabel>
    </item>
    <item selector="UNCLASSIFIED" default="true"/>
  </catalog>
</iq>
      ]]></example>
  </section2>
  <section2 topic='Discover Nodes' anchor='entityusecases-discovernodes'>
  	<p>The server SHOULD NOT return any nodes that have a Security Label that the entity is not
  		Cleared to view.</p>
    <example caption='Entity request list of top-level nodes'><![CDATA[
<iq from='francisco@denmark.lit/barracks'
    id='nodes1'
    to='pubsub.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
  	]]></example>
    <example caption='Server responds with list of nodes with Security Labels'><![CDATA[
<iq type='result'
    from='pubsub.shakespeare.lit'
    to='francisco@denmark.lit/barracks'
    id='nodes1'
    xmlns:slps='urn:xmpp:sec-label:pubsub:0'>
  <query xmlns='http://jabber.org/protocol/disco#items'>
    <item jid='pubsub.shakespeare.lit'
          node='blogs'
          name='Weblog updates'
          slps:label='seclabel-1'/>
    <item jid='pubsub.shakespeare.lit'
          node='news'
          name='News and announcements'
          slps:label='seclabel-2'/>
    <securitylabel xmlns='urn:xmpp:sec-label:0' slps:id='seclabel-1'>
      <displaymarking fgcolor='black' bgcolor='green'>UNCLASSIFIED</displaymarking>
      <label>
        <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>MQMGASk=</esssecuritylabel>
      </label>
    </securitylabel>
    <securitylabel xmlns='urn:xmpp:sec-label:0' slps:id='seclabel-2'>
      <displaymarking fgcolor='black' bgcolor='red'>SECRET</displaymarking>
      <label>
        <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>MQYCAQIGASk=</esssecuritylabel>
      </label>
    </securitylabel>
  </query>
</iq>
    ]]></example>
  </section2>
  <section2 topic='Discover Items for a Node' anchor='entityusecases-discoveritems'>
  	<p>The item list MUST NOT contain items that the entity is not Cleared to view.</p>
  	<p>The server SHOULD return an &ITEMNOTFOUND; error if the entity is not Cleared to view
        the node.</p>
    <p>See <link url='#subscriberusecases-retrieveitems'>Subscriber Use Cases: Retrieve Items from a
      Node</link> for more details of how Security Labels are respresented in the server response.
      </p>
    <example caption='Entity requests all of the items for a node'><![CDATA[
<iq from='francisco@denmark.lit/barracks'
    id='items1'
    to='pubsub.shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#items'
         node='princely_musings'/>
</iq>
    ]]>
    </example>
    <example caption='Server responds with items in the node'><![CDATA[
<iq from='pubsub.shakespeare.lit'
    id='items1'
    to='francisco@denmark.lit/barracks'
    type='result'
    xmlns:slps='urn:xmpp:sec-label:pubsub:0'>
  <query xmlns='http://jabber.org/protocol/disco#items'
         node='princely_musings'>
    <item
      jid='pubsub.shakespeare.lit'
      name='368866411b877c30064a5f62b917cffe'
      slps:label='seclabel-1'/>
    <item
      jid='pubsub.shakespeare.lit'
      name='3300659945416e274474e469a1f0154c'
      slps:label='seclabel-1'/>
    <item
      jid='pubsub.shakespeare.lit'
      name='4e30f35051b7b8b42abe083742187228'
      slps:label='seclabel-2'/>
    <item
      jid='pubsub.shakespeare.lit'
      name='ae890ac52d0df67ed7cfdf51b644e901'
      slps:label='seclabel-1'/>
    <securitylabel xmlns='urn:xmpp:sec-label:0' slps:id='seclabel-1'>
      <displaymarking fgcolor='black' bgcolor='green'>UNCLASSIFIED</displaymarking>
      <label>
        <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>MQMGASk=</esssecuritylabel>
      </label>
    </securitylabel>
    <securitylabel xmlns='urn:xmpp:sec-label:0' slps:id='seclabel-2'>
      <displaymarking fgcolor='black' bgcolor='red'>SECRET</displaymarking>
      <label>
        <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>MQYCAQIGASk=</esssecuritylabel>
      </label>
    </securitylabel>
  </query>
</iq>
    ]]></example>
  </section2>
</section1>
<section1 topic='Subscriber Use Cases' anchor='subscriberusecases'>
  <section2 topic='Subscribe to a Node' anchor='subscriberusecases-subscribenode'>
  	<p>The server SHOULD return an &ITEMNOTFOUND; error if the subscriber is not Cleared to view
  		the node.</p>
  </section2>
  <section2 topic='Retrieve Items from a Node' anchor='subscriberusecases-retrieveitems'>
  	<p>The server SHOULD return an &ITEMNOTFOUND; error if the subscriber is not Cleared to view the
  	  node.</p>
  	<p>The item list MUST NOT contain items that the subscriber is not Cleared to view.</p>
  	<p>The server MUST attach relevant &SECURITYLABEL; child elements to the &ITEMS; element.</p>
  	<p>Each of these &SECURITYLABEL; elements MUST posess an 'id' attribute (from the &NSMAIN;
  	  namespace) which is unique within the stanza.</p>
  	<p>The server SHOULD normalise the elements so that multiple &ITEM; elements with the same
  	  Security Label reference the same &SECURITYLABEL; element; However, the server might
  	  instead include a &SECURITYLABEL; element for each &ITEM; element regardless of whether there
  	  are duplicates.</p>
  	<p>Each &ITEM; that has a Security Label MUST posess a 'label' attribute (from the &NSMAIN;
      namespace) that references the id of the relevant &SECURITYLABEL;.</p>
  	<p>The server SHOULD NOT include &SECURITYLABEL; elements which are not referenced within the
  	  stanza.</p>
  	<example caption='The server returns a list of items with Security Labels'><![CDATA[
<iq from='pubsub.shakespeare.lit'
    id='items1'
    to='francisco@denmark.lit/barracks'
    type='result'
    xmlns:slps='urn:xmpp:sec-label:pubsub:0'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <items node='princely_musings'>
      <item id='368866411b877c30064a5f62b917cffe' slps:label='seclabel-1'>
        <entry xmlns='http://www.w3.org/2005/Atom'>
          <title>The Uses of This World</title>
          <summary>
O, that this too too solid flesh would melt
Thaw and resolve itself into a dew!
          </summary>
          <link rel='alternate' type='text/html'
                href='http://denmark.lit/2003/12/13/atom03'/>
          <id>tag:denmark.lit,2003:entry-32396</id>
          <published>2003-12-12T17:47:23Z</published>
          <updated>2003-12-12T17:47:23Z</updated>
        </entry>
      </item>
      <item id='3300659945416e274474e469a1f0154c' slps:label='seclabel-1'>
        <entry xmlns='http://www.w3.org/2005/Atom'>
          <title>Ghostly Encounters</title>
          <summary>
O all you host of heaven! O earth! what else?
And shall I couple hell? O, fie! Hold, hold, my heart;
And you, my sinews, grow not instant old,
But bear me stiffly up. Remember thee!
          </summary>
          <link rel='alternate' type='text/html'
                href='http://denmark.lit/2003/12/13/atom03'/>
          <id>tag:denmark.lit,2003:entry-32396</id>
          <published>2003-12-12T23:21:34Z</published>
          <updated>2003-12-12T23:21:34Z</updated>
        </entry>
      </item>
      <item id='4e30f35051b7b8b42abe083742187228' slps:label='seclabel-2'>
        <entry xmlns='http://www.w3.org/2005/Atom'>
          <title>Alone</title>
          <summary>
Now I am alone.
O, what a rogue and peasant slave am I!
          </summary>
          <link rel='alternate' type='text/html'
                href='http://denmark.lit/2003/12/13/atom03'/>
          <id>tag:denmark.lit,2003:entry-32396</id>
          <published>2003-12-13T11:09:53Z</published>
          <updated>2003-12-13T11:09:53Z</updated>
        </entry>
      </item>
      <item id='ae890ac52d0df67ed7cfdf51b644e901' slps:label='seclabel-1'>
        <entry xmlns='http://www.w3.org/2005/Atom'>
          <title>Soliloquy</title>
          <summary>
To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them?
          </summary>
          <link rel='alternate' type='text/html'
                href='http://denmark.lit/2003/12/13/atom03'/>
          <id>tag:denmark.lit,2003:entry-32397</id>
          <published>2003-12-13T18:30:02Z</published>
          <updated>2003-12-13T18:30:02Z</updated>
        </entry>
      </item>
      <securitylabel xmlns='urn:xmpp:sec-label:0' slps:id='seclabel-1'>
        <displaymarking fgcolor='black' bgcolor='green'>UNCLASSIFIED</displaymarking>
        <label>
          <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>MQMGASk=</esssecuritylabel>
        </label>
      </securitylabel>
      <securitylabel xmlns='urn:xmpp:sec-label:0' slps:id='seclabel-2'>
        <displaymarking fgcolor='black' bgcolor='red'>SECRET</displaymarking>
        <label>
          <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>MQYCAQIGASk=</esssecuritylabel>
        </label>
      </securitylabel>
    </items>
  </pubsub>
</iq>
]]></example>  	
  </section2>
</section1>
<section1 topic='Publisher Use Cases' anchor='publisherusecases'>
  <section2 topic='Publish an Item to a Node' anchor='publisherusecases-publishitem'>
  	<p>A &PUBLISH; element MAY contain a &SECURITYLABEL; which the service must apply to all the
  		items within the &PUBLISH;.</p>
  	<p>If a publisher wishes to publish multiple items with different Security Labels, they MUST
  		send multiple &IQ; stanzas - one for each Security Label.</p>
  	<p>The server SHOULD apply the default label for the node to any items within a &PUBLISH; which
  		does not contain a &SECURITYLABEL;.</p>
  	<p>Any &SECURITYLABEL; within a &PUBLISH; should be compatible with any Clearance associated
  	  with the node, else the service MUST return an &INSUFFICIENTCLEARANCE; error.</p>
  	<p>If a publisher attempts to publish to a node which the publisher is not Cleared to view, the
  		service SHOULD return an &ITEMNOTFOUND; error.</p>
  	<p>A publisher SHOULD not attempt to publish an item with a Security Label which is not suitable
  	  to the Clearance of the node.</p>
  	<p>Any &PUBLISH; with a &SECURITYLABEL; should be compatible with the Clearance of the
  	  publishing entity, else the server MUST return an &INSUFFICIENTCLEARANCE; error.</p>
  	<example caption='Publisher publishes an item with a Security Label'><![CDATA[
<iq from='hamlet@denmark.lit/blogbot'
    id='pub1'
    to='pubsub.shakespeare.lit'
    type='set'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <publish node='princely_musings'>
      <item>
        <entry xmlns='http://www.w3.org/2005/Atom'>
          <title>Soliloquy</title>
          <summary>
To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them?
          </summary>
          <link rel='alternate' type='text/html'
                href='http://denmark.lit/2003/12/13/atom03'/>
          <id>tag:denmark.lit,2003:entry-32397</id>
          <published>2003-12-13T18:30:02Z</published>
          <updated>2003-12-13T18:30:02Z</updated>
        </entry>
      </item>
      <securitylabel xmlns='urn:xmpp:sec-label:0'>
        <displaymarking fgcolor='black' bgcolor='green'>UNCLASSIFIED</displaymarking>
        <label>
          <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>MQMGASk=</esssecuritylabel>
        </label>
      </securitylabel>
    </publish>
  </pubsub>
</iq>
    	]]></example>
    <p>The service then notifies appropriately Cleared subscribers. The server MUST NOT notify
    	subscribers that do not have appropriate Clearance to view the item.</p>
    <p>The server MUST include the &SECURITYLABEL; element as a child of the &MESSAGE; stanza. The
      server MUST NOT include the &SECURITYLABEL; element within the &ITEMS; element.</p>
    <p>The Security Label applies to the entire message (including all the items within the &ITEMS;
      element and any &BODY; if the entity's subscription is so configured).</p>
  	<example caption='Subscriber receives event notification with payload'><![CDATA[
<message from='pubsub.shakespeare.lit' id='foo' to='francisco@denmark.lit'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node=princely_musings'>
      <item id='ae890ac52d0df67ed7cfdf51b644e901'>
        <entry xmlns='http://www.w3.org/2005/Atom'>
          <title>Soliloquy</title>
          <summary>
To be, or not to be: that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take arms against a sea of troubles,
And by opposing end them?
          </summary>
          <link rel='alternate' type='text/html'
                href='http://denmark.lit/2003/12/13/atom03'/>
          <id>tag:denmark.lit,2003:entry-32397</id>
          <published>2003-12-13T18:30:02Z</published>
          <updated>2003-12-13T18:30:02Z</updated>
        </entry>
      </item>
    </items>
  </event>
  <securitylabel xmlns='urn:xmpp:sec-label:0'>
    <displaymarking fgcolor='black' bgcolor='green'>UNCLASSIFIED</displaymarking>
    <label>
      <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>MQMGASk=</esssecuritylabel>
    </label>
  </securitylabel>
</message>
    ]]></example>
    <example caption='Subscriber receives event notification without payload'><![CDATA[
<message from='pubsub.shakespeare.lit' id='foo' to='francisco@denmark.lit'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <items node=princely_musings'>
      <item id='ae890ac52d0df67ed7cfdf51b644e901' />
    </items>
  </event>
  <securitylabel xmlns='urn:xmpp:sec-label:0'>
    <displaymarking fgcolor='black' bgcolor='green'>UNCLASSIFIED</displaymarking>
    <label>
      <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>MQMGASk=</esssecuritylabel>
    </label>
  </securitylabel>
</message>
    ]]></example>
    <section3 topic='Error Cases'>
      <section4 topic='An Attempt to Publish an Item which Exceeds the Node&apos;s Clearance'
        anchor='publisherusecases-publishitem-errors-nodeclearance'>
        <p>If a publisher attempts to publish to a node with a Security Label that is incompatible
          with the Clearance of the node then the server MUST return an &INSUFFICIENTCLEARANCE;
          error.</p>
        <example caption='Publishing to a node with insufficient node Clearance'><![CDATA[
<iq from='pubsub.shakespeare.lit'
    id='sub1'
    to='francisco@denmark.lit/barracks'
    type='error'>
  <error type='modify'>
    <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
    <insufficient-clearance xmlns='urn:xmpp:sec-label:pubsub:errors:0'/>
  </error>
</iq>
        ]]></example>
      </section4>
      <section4 topic='An Attempt to Publish an Item which is Incompatible with the Publisher&apos;s
        Clearance'
        anchor='publisherusecases-publishitem-errors-publisherclearance'>
        <p>If a publisher attempts to publish to a node with a Security Label that is incompatible
          with the Clearance of the publisher then the server MUST return an &INSUFFICIENTCLEARANCE;
          error.</p>
        <example caption='Publishing to a node with insufficient publisher Clearance'><![CDATA[
<iq from='pubsub.shakespeare.lit'
    id='sub1'
    to='francisco@denmark.lit/barracks'
    type='error'>
  <error type='auth'>
    <insufficient-clearance xmlns='urn:xmpp:sec-label:pubsub:errors:0'/>
  </error>
</iq>
        ]]></example>
      </section4>
    </section3>
  </section2>
  <section2 topic='Delete an item from a node' anchor='publisherusecases-deleteitem'>
    <p>The server SHOULD return an &ITEMNOTFOUND; error if the subscriber is not Cleared to view
      the node or item.</p>
    <p>The server MUST NOT send retract requests to subscribers who are not Cleared to view the
      item.</p>
  </section2>
</section1>
<section1 topic='Owner Use Cases' anchor='ownerusecases'>
  <section2 topic='Node Configuration'>
    <p>The server SHOULD allow for configuration of Security Label parameters for a node via node
      configuration mechanisms. This approach is intended to be ad-hoc and so this section is
      intended to be illustrative of one possible approach. Implementations are free to utilize
      other approaches.</p>
    <p>The server MUST disallow a node being created that has a default Security Label that is not
      within the clearance of the node.</p>
    <example caption='Node configuration form'><![CDATA[
<iq from='pubsub.shakespeare.lit'
    id='config1'
    to='hamlet@denmark.lit/elsinore'
    type='result'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
    <configure node='princely_musings'>
      <x xmlns='jabber:x:data' type='form'>
        ...
        <field label='Node Label' type='list-single' var='sec-label#label'>
          <value>Catalog:UNCLASSIFIED</value>
          <option label='SECRET'><value>Catalog:SECRET</value></option>
          <option label='CONFIDENTIAL'><value>Catalog:CONFIDENTIAL</value></option>
          <option label='UNCLASSIFIED'><value>Catalog:UNCLASSIFIED</value></option>
          <option label='Custom'><value>Custom</value></option>
        </field>
        <field label='Custom Node Label' type='text-single'
             var='sec-label#custom-label'/>

        <field label='Node Clearance' type='list-multi' var='sec-label#clearance'>
          <value>Catalog:UNCLASSIFIED</value>
          <option label='SECRET'><value>Catalog:SECRET</value></option>
          <option label='CONFIDENTIAL'><value>Catalog:CONFIDENTIAL</value></option>
          <option label='UNCLASSIFIED'><value>Catalog:UNCLASSIFIED</value></option>
          <option label='Custom'><value>Custom</value></option>
        </field>
        <field label='Custom Node Clearance' type='text-single'
            var='sec-label#custom-clearance'/>
      </x>
    </configure>
  </pubsub>
</iq>
    ]]></example>
    <section3 topic='Updating an Existing Node Configuration'
              anchor='ownerusercases-configuration-updating'>
      <p>Changing the Security Label or Clearance of an existing node is problematic for a number of
        reasons:</p>
      <ul>
        <li>Subscribers may no longer be Cleared to view a node to which they are already subscribed
          </li>
        <li>Existing items persisted within a node may be of a higher Security Label than the new
          node clearance allows</li>
      </ul>
      <p>For these reasons an implementation MAY wish to disallow changes to the Security Label of
        an existing node with subscribers, disallow changes to the Clearance of a node with items,
        or limit the options within the node configuration to those which do not cause a conflict.
        </p>
      <p>If an implementation chooses to allow a change to the clearance of a node that conflicts
        with the Security Label of existing items within the node then the server MUST purge the
        node of all items which are no longer within the updated clearance of the node, with or
        without notifying subscribers.</p>
      <p>If an implementation chooses to allow a change to the Security Label of the node that
        causes conflicts with existing subscribers to the node then the server MUST remove all
        subscriptions from subscribers that are no longer Cleared to view the node. The server MUST
        notify these subscribers. The server SHOULD send a Node Deletion notification, but might
        instead send a Subscription Cancellation notification if entities are to be aware of the
        existence of nodes they do not have Clearance to view.</p>
      <p>The server MUST prevent a change to the Security Label of the node which would prevent a
        node owner from accessing the node.</p>
      <example caption='Node Deletion Notification'><![CDATA[
<message from='pubsub.shakespeare.lit' id='deletenotify1' to='francisco@denmark.lit'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <delete node='princely_musings' />
  </event>
</message>
      ]]></example>
      <example caption='Subscription Cancellation Notification'><![CDATA[
<message from='pubsub.shakespeare.lit' id='unsubnotify1' to='horatio@denmark.lit'>
  <event xmlns='http://jabber.org/protocol/pubsub#event'>
    <subscription jid='horatio@denmark.lit' node='princely_musings' subscription='none'/>
  </event>
</message>
      ]]></example>
    </section3>
  </section2>
</section1>
<section1 topic='Business Rules' anchor='rules'>
  <ol>
    <li>An entity SHOULD NOT be aware of the existance of nodes or items that they do
      not have appropriate Clearance to view (But see <link url='#impl-access'>Implementation Notes:
      Access to items for which the entity is not Cleared</link>)</li>
    <li>Items MUST only be accessible by entities with the appropriate Clearance</li>
    <li>If a node has an associated Clearance then the node MUST only deal with (i.e.
      persist or notify) items which are compatible with the Clearance</li>
  </ol>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
  <section2 topic='Access to Items for which the Entity is not Cleared' anchor='impl-access'>
    <p>The protocol defined has the intention that, as far as possible, an entity should be unaware of
    	the existence of any nodes or items which they are not Cleared to view. Therefore server
    	responses to a request for a node which the entity is not Cleared to view SHOULD be identical to
    	a response as if that node did not exist (See <link url="#rules">BR1</link>), i.e. an
    	&ITEMNOTFOUND; error is returned</p>
    <example caption="Request for a node that the entity is not Cleared to view"><![CDATA[
<iq from='pubsub.shakespeare.lit'
    id='sub1'
    to='francisco@denmark.lit/barracks'
    type='error'>
  <error type='cancel'>
    <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
    ]]></example>
    <p>It is worth noting that there are certain situations where this is impossible, for example if
      an entity wishes to create a node with the same NodeID as an existing node that they are not
      Cleared to view.</p>
    <p>Alternatively, an implementation might wish to relax this rule and allow entities to become
      aware of nodes they do not have Clearance to view. In this case an &INSUFFICIENTCLEARANCE;
      error MAY be returned instead.</p>
  </section2>
  <section2 topic='Collection Nodes' anchor='impl-collections'>
    <p>If a service implements &xep0248; then there will need to be some consideration of node
      and item visibility within the node hierarchy.</p>
    <p>Due to the complexity of the access control policies involved, an implementation MAY choose
      to do one or more of the following to simplify the implementation:</p>
    <ul>
      <li>Prevent the use of Security Labels and/or Clearances on collection nodes.</li>
      <li>Prevent publishing items with Security Labels to non-orphan leaf nodes (i.e. leaf nodes
        with an association to a collection node).</li>
      <li>Prevent the association of leaf nodes containing Security Labelled items with collection
        nodes.</li>
      <li>Prevent the association of Security Labelled nodes with collection nodes.</li>
    </ul>
    <p>The rules and protocols defined elsewhere in this document are generally applicable to
      collection nodes with the following additions:</p>
    <section3 topic='Notifications' anchor='impl-collections-notifications'>
      <p>A collection node MUST NOT forward a publish notification with a Security Label that is
        incompatible with the Clearance of the collection node.</p>
      <p>A collection node SHOULD NOT forward a node change notification
        (create/update/delete/associate) where the Security Label of the affected node is
        incompatible with the Clearance of the collection node.</p>
      <p>The server SHOULD NOT send node change notifications to any entity where the Security Label
        of the affected node is incompatible with the Clearance of the entity.</p>
    </section3>
    <section3 topic='Retrieving Items on Collection Nodes' anchor='impl-collections-retrieveitems'>
      <p>The server MUST NOT return any items from leaf nodes where the individual Security Label of
        the item is incompatible with the Clearance of the requesting entity.</p>
      <p>The server SHOULD NOT return any items from any associated nodes where the Security Label
        of the leaf node, or any intermediate collection node on the node graph, is incompatible
        with the Clearance of the requesting entity.</p>
    </section3>
    <section3 topic='Associating a Node to a Collection' anchor='impl-collections-associating'>
      <p>A server SHOULD NOT allow an entity to associate, either through configuration or through
        an &ASSOCIATE; statement, a child node to a collection node if the Security Label of the
        child node is incompatible with the Clearance of the collection node.</p>
    </section3>
  </section2>
  <section2 topic='Implementation Specific Structuring within Items' anchor='impl-itemstructure'>
    <p>An implementation might choose to impose some kind of structure on items within a node. For
      example: items may include a list of blog posts, but may also include comments relating to
      specific blog posts from other users.</p>
    <p>An implementation MAY apply different logic to the visibility of items in this case,
      perhaps by disallowing access to comment items if the requester is not Cleared to view the
      associated blog post item, even if the individual Security Label on the comment item would not
      normally prevent access.</p>
    <p>However, the server MUST NOT allow access to an item if the requester is not Cleared to view
      the Security Label for the item (i.e. this mechanism must only be used to further restrict
      access to items and must not be used to widen access).</p>
  </section2>
  <section2 topic='Limiting Notifications to a Certain Clearance' anchor='impl-limitclearance'>
    <p>An implementation may wish to allow a subscriber to limit the sensitivity of items which are
      delivered for a certain subscription. For example: a subscriber may wish to only receive
      notifications of items which are unclassified, even if the node has a higher clearance.</p>
    <p>One way this could be implemented is by expanding the Data Form for the subscription options.
      </p>
      <example caption="Form with ability to limit subscription clearance"><![CDATA[
<iq from='pubsub.shakespeare.lit'
    id='options1'
    to='francisco@denmark.lit/barracks'
    type='result'>
  <pubsub xmlns='http://jabber.org/protocol/pubsub'>
    <options node='princely_musings' jid='francisco@denmark.lit'>
      <x xmlns='jabber:x:data' type='form'>
        ...
        <field label='Limit Clearance' type='list-multi' var='sec-label#clearance'>
          <value>Catalog:UNCLASSIFIED</value>
          <option label='SECRET'><value>Catalog:SECRET</value></option>
          <option label='CONFIDENTIAL'><value>Catalog:CONFIDENTIAL</value></option>
          <option label='UNCLASSIFIED'><value>Catalog:UNCLASSIFIED</value></option>
          <option label='Custom'><value>Custom</value></option>
        </field>
        ...
      </x>
    </options>
  </pubsub>
</iq>
]]></example>
  </section2>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>This document is an extension to &xep0258; and therefore any security considerations noted in
  	that document will also apply to this document.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with the &IANA;</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
	<section2 topic='Protocol Namespaces' anchor='registrar-namespaces'>
		<p>This specification defines the following XML namespaces:</p>
		<ul>
      <li>&NSMAIN;</li>
		  <li>&NSERRORS;</li>
		</ul>
	</section2>
	<section2 topic='Protocol Versioning' anchor='registrar-versioning'>
    &NSVER;
	</section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
  <section2 topic='&NSMAIN;' anchor='schemas-main'>
    <code><![CDATA[
<?xml version="1.0" encoding="utf-8" ?>

<xs:schema
    elementFormDefault='qualified'
    targetNamespace='urn:xmpp:sec-label:pubsub:0'
    xmlns='urn:xmpp:sec-label:pubsub:0'
    xmlns:xs='http://www.w3.org/2001/XMLSchema'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-xxxx: http://www.xmpp.org/extensions/xep-xxxx.html
    </xs:documentation>
  </xs:annotation>

  <xs:attribute name='label' type='xs:IDREF'>
    <xs:annotation>
      <xs:documentation>
        References an &quot;id&quot; value in a &lt;securitylabel&gt; element. The referenced
        Security Label MUST then be applied to the element content.
      </xs:documentation>
    </xs:annotation>
  </xs:attribute>
  
  <xs:attribute name='id' type='xs:ID'>
    <xs:annotation>
      <xs:documentation>
        Defines a unique (across the document) id for a &lt;securitylabel&gt; element that can be
        referenced from a &quot;label&quot; attribute.
      </xs:documentation>
    </xs:annotation>
  </xs:attribute>
  
</xs:schema>
    ]]></code>
  </section2>
  <section2 topic='&NSERRORS;' anchor='schemas-error'>
    <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
    elementFormDefault='qualified'
    targetNamespace='urn:xmpp:sec-label:pubsub:errors:0'
    xmlns='urn:xmpp:sec-label:pubsub:errors:0'
    xmlns:xs='http://www.w3.org/2001/XMLSchema'>

  <xs:annotation>
    <xs:documentation>
      This namespace is used for error reporting only, as
      defined in XEP-xxxx:

      http://xmpp.org/extensions/xep-xxxx.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='insufficient-clearance' type='empty'/>
  
</xs:schema>
    ]]></code>
  </section2>
</section1>

<section1 topic='Acknowledgements' anchor='ack'>
  <p>Thanks to Dave Cridland, John Atherton, Kurt Zeilenga, Lloyd Watkin, Ralph Meijer and Stephen
    Welch for their contributions.</p>
</section1>
</xep>