xeps/xep-0314.xml

866 lines
39 KiB
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>