No Description
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

xep-0314.xml 39KB

  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <!DOCTYPE xep SYSTEM 'xep.dtd' [
  3. <!ENTITY % ents SYSTEM 'xep.ent'>
  4. %ents;
  5. <!ENTITY LABEL "<tt>&lt;label/&gt;</tt>">
  6. <!ENTITY CATALOG "<tt>&lt;catalog/&gt;</tt>">
  7. <!ENTITY ITEM "<tt>&lt;item/&gt;</tt>">
  8. <!ENTITY SECURITYLABEL "<tt>&lt;securitylabel/&gt;</tt>">
  9. <!ENTITY DISPLAYMARKING "<tt>&lt;displaymarking/&gt;</tt>">
  10. <!ENTITY EQUIVALENTLABEL "<tt>&lt;equivalentlabel/&gt;</tt>">
  11. <!ENTITY HEADLINE "<tt>&lt;headline/&gt;</tt>">
  12. <!ENTITY IDENTITY "<tt>&lt;identity/&gt;</tt>">
  13. <!ENTITY PUBLISH "<tt>&lt;publish/&gt;</tt>">
  14. <!ENTITY ITEMNOTFOUND "<tt>&lt;item-not-found/&gt;</tt>">
  15. <!ENTITY NOTAUTHORIZED "<tt>&lt;not-authorized/&gt;</tt>">
  16. <!ENTITY NOTACCEPTABLE "<tt>&lt;not-acceptable/&gt;</tt>">
  17. <!ENTITY INSUFFICIENTCLEARANCE "<tt>&lt;insufficient-clearance/&gt;</tt>">
  18. <!ENTITY ITEMS "<tt>&lt;items/&gt;</tt>">
  19. <!ENTITY ASSOCIATE "<tt>&lt;associate/&gt;</tt>">
  20. <!ENTITY NSMAIN "urn:xmpp:sec-label:pubsub:0">
  21. <!ENTITY NSERRORS "urn:xmpp:sec-label:pubsub:errors:0">
  22. ]>
  23. <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
  24. <xep>
  25. <header>
  26. <title>Security Labels in PubSub</title>
  27. <abstract>This specification defines an extension to XEP-0258 (Security Labels) to allow for the
  28. use of security labels in XEP-0060 (Publish-Subscribe). This document describes how security
  29. label metadata can be applied to the various elements within Publish-Subscribe, including nodes
  30. and items.
  31. </abstract>
  33. <number>0314</number>
  34. <status>Deferred</status>
  35. <type>Standards Track</type>
  36. <sig>Standards</sig>
  37. <approver>Council</approver>
  38. <dependencies>
  39. <spec>XMPP Core</spec>
  40. <spec>XEP-0060</spec>
  41. <spec>XEP-0258</spec>
  42. </dependencies>
  43. <supersedes/>
  44. <supersededby/>
  45. <shortname>NOT_YET_ASSIGNED</shortname>
  46. <author>
  47. <firstname>Ashley</firstname>
  48. <surname>Ward</surname>
  49. <email></email>
  50. <jid></jid>
  51. <uri></uri>
  52. </author>
  53. <revision>
  54. <version>0.1</version>
  55. <date>2012-07-27</date>
  56. <initials>psa</initials>
  57. <remark><p>Initial published version.</p></remark>
  58. </revision>
  59. <revision>
  60. <version>0.0.1</version>
  61. <date>2012-06-08</date>
  62. <initials>asw</initials>
  63. <remark><p>First draft.</p></remark>
  64. </revision>
  65. </header>
  66. <section1 topic='Introduction' anchor='intro'>
  67. <p>The use of security labels within XMPP is currently defined in &xep0258;. This, however, does
  68. not cover the use of security labels within &xep0060;. This XEP defines a method to include
  69. security labels into publish-subscribe.</p>
  70. <p>This allows content publishers to limit visibility of any sensitive published items to only
  71. those users with appropriate clearance to view them.</p>
  72. <p>This document does not deal with the semantics of a Security Label or how the security policy
  73. is applied to decisions regarding Security Labels and Clearances.</p>
  74. <p>This document should be read in conjunction with &xep0060; and &xep0258;.</p>
  75. </section1>
  76. <section1 topic='Requirements' anchor='reqs'>
  77. <ul>
  78. <li>A publisher MUST be able to apply a Security Label to items within a node.</li>
  79. <li>A node creator SHOULD be able to apply a Security Label to a node (this controls which
  80. entities can access the node).</li>
  81. <li>A node creator SHOULD be able to apply a Clearance to a node (this controls which Security
  82. Labels can be applied to items within the node).</li>
  83. <li>A node creator MAY be able to apply a default Security Label to a node (this applies to
  84. items published to the node without a Security Label).</li>
  85. <li>Node lists returned by the server SHOULD NOT contain nodes that the requesting entity is
  86. not Cleared to view.</li>
  87. <li>Item lists returned by the server MUST NOT contain items that the requesting entity is not
  88. Cleared to view.</li>
  89. <li>A client SHOULD only publish items to a node that are compatible with the Clearance of the
  90. node (if the node has a Clearance), and a server MUST NOT store such items against the node
  91. or send any notifications of any such items to subscribers.</li>
  92. <li>Server responses from a request involving a node that the entity is not Cleared to view
  93. SHOULD be identical to a response as if that node did not exist.</li>
  94. <li>Server responses from a request involving an item that the entity is not Cleared to view
  95. MUST be identical to a response as if that item did not exist.</li>
  96. <li>A server MUST NOT notify or deliver items to an entity that the entity does not have
  97. appropriate Clearance to view.</li>
  98. </ul>
  99. </section1>
  100. <section1 topic='Glossary' anchor='glossary'>
  101. <p>In addition to the Glossary defined for &xep0060; the following terms are used:</p>
  102. <dl>
  103. <di>
  104. <dt>Security Label</dt>
  105. <dd>
  106. <p>A label that can be applied to content to restrict the visibility of the content to
  107. entities with appropriate Clearance.</p>
  108. <p>The schema is defined in &xep0258; with the XML namespace "urn:xmpp:sec-label:0".</p>
  109. </dd>
  110. </di>
  111. <di>
  112. <dt>Clearance</dt>
  113. <dd>A collection of Security Labels that an entity is authorized to access.</dd>
  114. </di>
  115. <di>
  116. <dt>Cleared</dt>
  117. <dd>An entity is Cleared to access content if the Access Control Decision Function (ACDF) of
  118. the server yields a <em>Grant</em> given the entity's Clearance, the Security Label of the
  119. content and the governing security policy.</dd>
  120. </di>
  121. </dl>
  122. </section1>
  123. <section1 topic='Entity Use Cases' anchor='entityusecases'>
  124. <p>This section defines the additions and caveats for the use cases and protocols defined in
  125. &xep0060;.</p>
  126. <section2 topic='Discovering Feature Support' anchor='entityusecases-discoveringfeaturesupport'>
  127. <p>A Security Label aware client SHOULD discover support for Security Labels within the
  128. &xep0060; service domain. If the service domain does not report support for Security Labels
  129. then the client SHOULD NOT publish with Security Labels.</p>
  130. <example caption='Service discovery information request'><![CDATA[
  131. <iq from='francisco@denmark.lit/barracks'
  132. id='disco1'
  133. to='pubsub.shakespeare.lit'
  134. type='get'>
  135. <query xmlns=''/>
  136. </iq>
  137. ]]></example>
  138. <example caption='Service discovery information response'><![CDATA[
  139. <iq from='pubsub.shakespeare.lit'
  140. id='disco1'
  141. to='francisco@denmark.lit/barracks'
  142. type='result'>
  143. <query xmlns=''>
  144. ...
  145. <feature var='urn:xmpp:sec-label:0'/>
  146. ...
  147. </query>
  148. </iq>
  149. ]]></example>
  150. <p>A server SHOULD provide label feature and information discovery for each node.</p>
  151. <p>Clients SHOULD discover label feature and information on a per-node basis.</p>
  152. <example caption='Label feature discovery request for a node'><![CDATA[
  153. <iq from='francisco@denmark.lit/barracks'
  154. id='disco2'
  155. to='pubsub.shakespeare.lit'
  156. type='get'>
  157. <query node='princely_musings' xmlns=''/>
  158. </iq>
  159. ]]></example>
  160. <example caption='Label feature discovery response for a node'><![CDATA[
  161. <iq from='pubsub.shakespeare.lit'
  162. id='disco2'
  163. to='francisco@denmark.lit/barracks'
  164. type='result'>
  165. <query node='princely_musings' xmlns=''>
  166. ...
  167. <feature var='urn:xmpp:sec-label:catalog:2'/>
  168. ...
  169. </query>
  170. </iq>
  171. ]]></example>
  172. <p>A server SHOULD provide Security Label catalog discovery for each node.</p>
  173. <p>Clients SHOULD discover the Security Label catalog on a per-node basis.</p>
  174. <p>The server SHOULD limit the catalog for a node to those labels that are compatible with any
  175. Clearance associated with the node.</p>
  176. <example caption='The client requests the catalog for a node'><![CDATA[
  177. <iq id='cat1'
  178. to='pubsub.shakespeare.lit'
  179. type='get'>
  180. <catalog xmlns='urn:xmpp:sec-label:catalog:2'
  181. to='pubsub.shakespeare.lit'
  182. node='princely_musings'/>
  183. </iq>
  184. ]]></example>
  185. <example caption='The server responds with the catalog for the node'><![CDATA[
  186. <iq from='pubsub.shakespeare.lit'
  187. id='cat1'
  188. to='francisco@denmark.lit/barracks'
  189. type='result'>
  190. <catalog xmlns='urn:xmpp:sec-label:catalog:2'
  191. to=''
  192. name='Default'
  193. desc='The set of labels applicable to the &quot;princely_musings&quot; node'
  194. restrict='false'
  195. node='princely_musings'>
  196. <item selector="Classified|SECRET">
  197. <securitylabel xmlns='urn:xmpp:sec-label:0'>
  198. <displaymarking fgcolor='black' bgcolor='red'>SECRET</displaymarking>
  199. <label>
  200. <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'
  201. >MQYCAQQGASk=</esssecuritylabel>
  202. </label>
  203. </securitylabel>
  204. </item>
  205. <item selector="Classified|CONFIDENTIAL">
  206. <securitylabel xmlns='urn:xmpp:sec-label:0'>
  207. <displaymarking fgcolor='black' bgcolor='navy'>CONFIDENTIAL</displaymarking>
  208. <label>
  209. <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'
  210. >MQYCAQMGASk</esssecuritylabel>
  211. </label>
  212. </securitylabel>
  213. </item>
  214. <item selector="Classified|RESTRICTED">
  215. <securitylabel xmlns='urn:xmpp:sec-label:0'>
  216. <displaymarking fgcolor='black' bgcolor='aqua'>RESTRICTED</displaymarking>
  217. <label>
  218. <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'
  219. >MQYCAQIGASk=</esssecuritylabel>
  220. </label>
  221. </securitylabel>
  222. </item>
  223. <item selector="UNCLASSIFIED" default="true"/>
  224. </catalog>
  225. </iq>
  226. ]]></example>
  227. </section2>
  228. <section2 topic='Discover Nodes' anchor='entityusecases-discovernodes'>
  229. <p>The server SHOULD NOT return any nodes that have a Security Label that the entity is not
  230. Cleared to view.</p>
  231. <example caption='Entity request list of top-level nodes'><![CDATA[
  232. <iq from='francisco@denmark.lit/barracks'
  233. id='nodes1'
  234. to='pubsub.shakespeare.lit'
  235. type='get'>
  236. <query xmlns=''/>
  237. </iq>
  238. ]]></example>
  239. <example caption='Server responds with list of nodes with Security Labels'><![CDATA[
  240. <iq type='result'
  241. from='pubsub.shakespeare.lit'
  242. to='francisco@denmark.lit/barracks'
  243. id='nodes1'
  244. xmlns:slps='urn:xmpp:sec-label:pubsub:0'>
  245. <query xmlns=''>
  246. <item jid='pubsub.shakespeare.lit'
  247. node='blogs'
  248. name='Weblog updates'
  249. slps:label='seclabel-1'/>
  250. <item jid='pubsub.shakespeare.lit'
  251. node='news'
  252. name='News and announcements'
  253. slps:label='seclabel-2'/>
  254. <securitylabel xmlns='urn:xmpp:sec-label:0' slps:id='seclabel-1'>
  255. <displaymarking fgcolor='black' bgcolor='green'>UNCLASSIFIED</displaymarking>
  256. <label>
  257. <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>MQMGASk=</esssecuritylabel>
  258. </label>
  259. </securitylabel>
  260. <securitylabel xmlns='urn:xmpp:sec-label:0' slps:id='seclabel-2'>
  261. <displaymarking fgcolor='black' bgcolor='red'>SECRET</displaymarking>
  262. <label>
  263. <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>MQYCAQIGASk=</esssecuritylabel>
  264. </label>
  265. </securitylabel>
  266. </query>
  267. </iq>
  268. ]]></example>
  269. </section2>
  270. <section2 topic='Discover Items for a Node' anchor='entityusecases-discoveritems'>
  271. <p>The item list MUST NOT contain items that the entity is not Cleared to view.</p>
  272. <p>The server SHOULD return an &ITEMNOTFOUND; error if the entity is not Cleared to view
  273. the node.</p>
  274. <p>See <link url='#subscriberusecases-retrieveitems'>Subscriber Use Cases: Retrieve Items from a
  275. Node</link> for more details of how Security Labels are respresented in the server response.
  276. </p>
  277. <example caption='Entity requests all of the items for a node'><![CDATA[
  278. <iq from='francisco@denmark.lit/barracks'
  279. id='items1'
  280. to='pubsub.shakespeare.lit'
  281. type='get'>
  282. <query xmlns=''
  283. node='princely_musings'/>
  284. </iq>
  285. ]]>
  286. </example>
  287. <example caption='Server responds with items in the node'><![CDATA[
  288. <iq from='pubsub.shakespeare.lit'
  289. id='items1'
  290. to='francisco@denmark.lit/barracks'
  291. type='result'
  292. xmlns:slps='urn:xmpp:sec-label:pubsub:0'>
  293. <query xmlns=''
  294. node='princely_musings'>
  295. <item
  296. jid='pubsub.shakespeare.lit'
  297. name='368866411b877c30064a5f62b917cffe'
  298. slps:label='seclabel-1'/>
  299. <item
  300. jid='pubsub.shakespeare.lit'
  301. name='3300659945416e274474e469a1f0154c'
  302. slps:label='seclabel-1'/>
  303. <item
  304. jid='pubsub.shakespeare.lit'
  305. name='4e30f35051b7b8b42abe083742187228'
  306. slps:label='seclabel-2'/>
  307. <item
  308. jid='pubsub.shakespeare.lit'
  309. name='ae890ac52d0df67ed7cfdf51b644e901'
  310. slps:label='seclabel-1'/>
  311. <securitylabel xmlns='urn:xmpp:sec-label:0' slps:id='seclabel-1'>
  312. <displaymarking fgcolor='black' bgcolor='green'>UNCLASSIFIED</displaymarking>
  313. <label>
  314. <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>MQMGASk=</esssecuritylabel>
  315. </label>
  316. </securitylabel>
  317. <securitylabel xmlns='urn:xmpp:sec-label:0' slps:id='seclabel-2'>
  318. <displaymarking fgcolor='black' bgcolor='red'>SECRET</displaymarking>
  319. <label>
  320. <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>MQYCAQIGASk=</esssecuritylabel>
  321. </label>
  322. </securitylabel>
  323. </query>
  324. </iq>
  325. ]]></example>
  326. </section2>
  327. </section1>
  328. <section1 topic='Subscriber Use Cases' anchor='subscriberusecases'>
  329. <section2 topic='Subscribe to a Node' anchor='subscriberusecases-subscribenode'>
  330. <p>The server SHOULD return an &ITEMNOTFOUND; error if the subscriber is not Cleared to view
  331. the node.</p>
  332. </section2>
  333. <section2 topic='Retrieve Items from a Node' anchor='subscriberusecases-retrieveitems'>
  334. <p>The server SHOULD return an &ITEMNOTFOUND; error if the subscriber is not Cleared to view the
  335. node.</p>
  336. <p>The item list MUST NOT contain items that the subscriber is not Cleared to view.</p>
  337. <p>The server MUST attach relevant &SECURITYLABEL; child elements to the &ITEMS; element.</p>
  338. <p>Each of these &SECURITYLABEL; elements MUST posess an 'id' attribute (from the &NSMAIN;
  339. namespace) which is unique within the stanza.</p>
  340. <p>The server SHOULD normalise the elements so that multiple &ITEM; elements with the same
  341. Security Label reference the same &SECURITYLABEL; element; However, the server might
  342. instead include a &SECURITYLABEL; element for each &ITEM; element regardless of whether there
  343. are duplicates.</p>
  344. <p>Each &ITEM; that has a Security Label MUST posess a 'label' attribute (from the &NSMAIN;
  345. namespace) that references the id of the relevant &SECURITYLABEL;.</p>
  346. <p>The server SHOULD NOT include &SECURITYLABEL; elements which are not referenced within the
  347. stanza.</p>
  348. <example caption='The server returns a list of items with Security Labels'><![CDATA[
  349. <iq from='pubsub.shakespeare.lit'
  350. id='items1'
  351. to='francisco@denmark.lit/barracks'
  352. type='result'
  353. xmlns:slps='urn:xmpp:sec-label:pubsub:0'>
  354. <pubsub xmlns=''>
  355. <items node='princely_musings'>
  356. <item id='368866411b877c30064a5f62b917cffe' slps:label='seclabel-1'>
  357. <entry xmlns=''>
  358. <title>The Uses of This World</title>
  359. <summary>
  360. O, that this too too solid flesh would melt
  361. Thaw and resolve itself into a dew!
  362. </summary>
  363. <link rel='alternate' type='text/html'
  364. href='http://denmark.lit/2003/12/13/atom03'/>
  365. <id>tag:denmark.lit,2003:entry-32396</id>
  366. <published>2003-12-12T17:47:23Z</published>
  367. <updated>2003-12-12T17:47:23Z</updated>
  368. </entry>
  369. </item>
  370. <item id='3300659945416e274474e469a1f0154c' slps:label='seclabel-1'>
  371. <entry xmlns=''>
  372. <title>Ghostly Encounters</title>
  373. <summary>
  374. O all you host of heaven! O earth! what else?
  375. And shall I couple hell? O, fie! Hold, hold, my heart;
  376. And you, my sinews, grow not instant old,
  377. But bear me stiffly up. Remember thee!
  378. </summary>
  379. <link rel='alternate' type='text/html'
  380. href='http://denmark.lit/2003/12/13/atom03'/>
  381. <id>tag:denmark.lit,2003:entry-32396</id>
  382. <published>2003-12-12T23:21:34Z</published>
  383. <updated>2003-12-12T23:21:34Z</updated>
  384. </entry>
  385. </item>
  386. <item id='4e30f35051b7b8b42abe083742187228' slps:label='seclabel-2'>
  387. <entry xmlns=''>
  388. <title>Alone</title>
  389. <summary>
  390. Now I am alone.
  391. O, what a rogue and peasant slave am I!
  392. </summary>
  393. <link rel='alternate' type='text/html'
  394. href='http://denmark.lit/2003/12/13/atom03'/>
  395. <id>tag:denmark.lit,2003:entry-32396</id>
  396. <published>2003-12-13T11:09:53Z</published>
  397. <updated>2003-12-13T11:09:53Z</updated>
  398. </entry>
  399. </item>
  400. <item id='ae890ac52d0df67ed7cfdf51b644e901' slps:label='seclabel-1'>
  401. <entry xmlns=''>
  402. <title>Soliloquy</title>
  403. <summary>
  404. To be, or not to be: that is the question:
  405. Whether 'tis nobler in the mind to suffer
  406. The slings and arrows of outrageous fortune,
  407. Or to take arms against a sea of troubles,
  408. And by opposing end them?
  409. </summary>
  410. <link rel='alternate' type='text/html'
  411. href='http://denmark.lit/2003/12/13/atom03'/>
  412. <id>tag:denmark.lit,2003:entry-32397</id>
  413. <published>2003-12-13T18:30:02Z</published>
  414. <updated>2003-12-13T18:30:02Z</updated>
  415. </entry>
  416. </item>
  417. <securitylabel xmlns='urn:xmpp:sec-label:0' slps:id='seclabel-1'>
  418. <displaymarking fgcolor='black' bgcolor='green'>UNCLASSIFIED</displaymarking>
  419. <label>
  420. <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>MQMGASk=</esssecuritylabel>
  421. </label>
  422. </securitylabel>
  423. <securitylabel xmlns='urn:xmpp:sec-label:0' slps:id='seclabel-2'>
  424. <displaymarking fgcolor='black' bgcolor='red'>SECRET</displaymarking>
  425. <label>
  426. <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>MQYCAQIGASk=</esssecuritylabel>
  427. </label>
  428. </securitylabel>
  429. </items>
  430. </pubsub>
  431. </iq>
  432. ]]></example>
  433. </section2>
  434. </section1>
  435. <section1 topic='Publisher Use Cases' anchor='publisherusecases'>
  436. <section2 topic='Publish an Item to a Node' anchor='publisherusecases-publishitem'>
  437. <p>A &PUBLISH; element MAY contain a &SECURITYLABEL; which the service must apply to all the
  438. items within the &PUBLISH;.</p>
  439. <p>If a publisher wishes to publish multiple items with different Security Labels, they MUST
  440. send multiple &IQ; stanzas - one for each Security Label.</p>
  441. <p>The server SHOULD apply the default label for the node to any items within a &PUBLISH; which
  442. does not contain a &SECURITYLABEL;.</p>
  443. <p>Any &SECURITYLABEL; within a &PUBLISH; should be compatible with any Clearance associated
  444. with the node, else the service MUST return an &INSUFFICIENTCLEARANCE; error.</p>
  445. <p>If a publisher attempts to publish to a node which the publisher is not Cleared to view, the
  446. service SHOULD return an &ITEMNOTFOUND; error.</p>
  447. <p>A publisher SHOULD not attempt to publish an item with a Security Label which is not suitable
  448. to the Clearance of the node.</p>
  449. <p>Any &PUBLISH; with a &SECURITYLABEL; should be compatible with the Clearance of the
  450. publishing entity, else the server MUST return an &INSUFFICIENTCLEARANCE; error.</p>
  451. <example caption='Publisher publishes an item with a Security Label'><![CDATA[
  452. <iq from='hamlet@denmark.lit/blogbot'
  453. id='pub1'
  454. to='pubsub.shakespeare.lit'
  455. type='set'>
  456. <pubsub xmlns=''>
  457. <publish node='princely_musings'>
  458. <item>
  459. <entry xmlns=''>
  460. <title>Soliloquy</title>
  461. <summary>
  462. To be, or not to be: that is the question:
  463. Whether 'tis nobler in the mind to suffer
  464. The slings and arrows of outrageous fortune,
  465. Or to take arms against a sea of troubles,
  466. And by opposing end them?
  467. </summary>
  468. <link rel='alternate' type='text/html'
  469. href='http://denmark.lit/2003/12/13/atom03'/>
  470. <id>tag:denmark.lit,2003:entry-32397</id>
  471. <published>2003-12-13T18:30:02Z</published>
  472. <updated>2003-12-13T18:30:02Z</updated>
  473. </entry>
  474. </item>
  475. <securitylabel xmlns='urn:xmpp:sec-label:0'>
  476. <displaymarking fgcolor='black' bgcolor='green'>UNCLASSIFIED</displaymarking>
  477. <label>
  478. <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>MQMGASk=</esssecuritylabel>
  479. </label>
  480. </securitylabel>
  481. </publish>
  482. </pubsub>
  483. </iq>
  484. ]]></example>
  485. <p>The service then notifies appropriately Cleared subscribers. The server MUST NOT notify
  486. subscribers that do not have appropriate Clearance to view the item.</p>
  487. <p>The server MUST include the &SECURITYLABEL; element as a child of the &MESSAGE; stanza. The
  488. server MUST NOT include the &SECURITYLABEL; element within the &ITEMS; element.</p>
  489. <p>The Security Label applies to the entire message (including all the items within the &ITEMS;
  490. element and any &BODY; if the entity's subscription is so configured).</p>
  491. <example caption='Subscriber receives event notification with payload'><![CDATA[
  492. <message from='pubsub.shakespeare.lit' id='foo' to='francisco@denmark.lit'>
  493. <event xmlns=''>
  494. <items node=princely_musings'>
  495. <item id='ae890ac52d0df67ed7cfdf51b644e901'>
  496. <entry xmlns=''>
  497. <title>Soliloquy</title>
  498. <summary>
  499. To be, or not to be: that is the question:
  500. Whether 'tis nobler in the mind to suffer
  501. The slings and arrows of outrageous fortune,
  502. Or to take arms against a sea of troubles,
  503. And by opposing end them?
  504. </summary>
  505. <link rel='alternate' type='text/html'
  506. href='http://denmark.lit/2003/12/13/atom03'/>
  507. <id>tag:denmark.lit,2003:entry-32397</id>
  508. <published>2003-12-13T18:30:02Z</published>
  509. <updated>2003-12-13T18:30:02Z</updated>
  510. </entry>
  511. </item>
  512. </items>
  513. </event>
  514. <securitylabel xmlns='urn:xmpp:sec-label:0'>
  515. <displaymarking fgcolor='black' bgcolor='green'>UNCLASSIFIED</displaymarking>
  516. <label>
  517. <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>MQMGASk=</esssecuritylabel>
  518. </label>
  519. </securitylabel>
  520. </message>
  521. ]]></example>
  522. <example caption='Subscriber receives event notification without payload'><![CDATA[
  523. <message from='pubsub.shakespeare.lit' id='foo' to='francisco@denmark.lit'>
  524. <event xmlns=''>
  525. <items node=princely_musings'>
  526. <item id='ae890ac52d0df67ed7cfdf51b644e901' />
  527. </items>
  528. </event>
  529. <securitylabel xmlns='urn:xmpp:sec-label:0'>
  530. <displaymarking fgcolor='black' bgcolor='green'>UNCLASSIFIED</displaymarking>
  531. <label>
  532. <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>MQMGASk=</esssecuritylabel>
  533. </label>
  534. </securitylabel>
  535. </message>
  536. ]]></example>
  537. <section3 topic='Error Cases'>
  538. <section4 topic='An Attempt to Publish an Item which Exceeds the Node&apos;s Clearance'
  539. anchor='publisherusecases-publishitem-errors-nodeclearance'>
  540. <p>If a publisher attempts to publish to a node with a Security Label that is incompatible
  541. with the Clearance of the node then the server MUST return an &INSUFFICIENTCLEARANCE;
  542. error.</p>
  543. <example caption='Publishing to a node with insufficient node Clearance'><![CDATA[
  544. <iq from='pubsub.shakespeare.lit'
  545. id='sub1'
  546. to='francisco@denmark.lit/barracks'
  547. type='error'>
  548. <error type='modify'>
  549. <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  550. <insufficient-clearance xmlns='urn:xmpp:sec-label:pubsub:errors:0'/>
  551. </error>
  552. </iq>
  553. ]]></example>
  554. </section4>
  555. <section4 topic='An Attempt to Publish an Item which is Incompatible with the Publisher&apos;s
  556. Clearance'
  557. anchor='publisherusecases-publishitem-errors-publisherclearance'>
  558. <p>If a publisher attempts to publish to a node with a Security Label that is incompatible
  559. with the Clearance of the publisher then the server MUST return an &INSUFFICIENTCLEARANCE;
  560. error.</p>
  561. <example caption='Publishing to a node with insufficient publisher Clearance'><![CDATA[
  562. <iq from='pubsub.shakespeare.lit'
  563. id='sub1'
  564. to='francisco@denmark.lit/barracks'
  565. type='error'>
  566. <error type='auth'>
  567. <insufficient-clearance xmlns='urn:xmpp:sec-label:pubsub:errors:0'/>
  568. </error>
  569. </iq>
  570. ]]></example>
  571. </section4>
  572. </section3>
  573. </section2>
  574. <section2 topic='Delete an item from a node' anchor='publisherusecases-deleteitem'>
  575. <p>The server SHOULD return an &ITEMNOTFOUND; error if the subscriber is not Cleared to view
  576. the node or item.</p>
  577. <p>The server MUST NOT send retract requests to subscribers who are not Cleared to view the
  578. item.</p>
  579. </section2>
  580. </section1>
  581. <section1 topic='Owner Use Cases' anchor='ownerusecases'>
  582. <section2 topic='Node Configuration'>
  583. <p>The server SHOULD allow for configuration of Security Label parameters for a node via node
  584. configuration mechanisms. This approach is intended to be ad-hoc and so this section is
  585. intended to be illustrative of one possible approach. Implementations are free to utilize
  586. other approaches.</p>
  587. <p>The server MUST disallow a node being created that has a default Security Label that is not
  588. within the clearance of the node.</p>
  589. <example caption='Node configuration form'><![CDATA[
  590. <iq from='pubsub.shakespeare.lit'
  591. id='config1'
  592. to='hamlet@denmark.lit/elsinore'
  593. type='result'>
  594. <pubsub xmlns=''>
  595. <configure node='princely_musings'>
  596. <x xmlns='jabber:x:data' type='form'>
  597. ...
  598. <field label='Node Label' type='list-single' var='sec-label#label'>
  599. <value>Catalog:UNCLASSIFIED</value>
  600. <option label='SECRET'><value>Catalog:SECRET</value></option>
  601. <option label='CONFIDENTIAL'><value>Catalog:CONFIDENTIAL</value></option>
  602. <option label='UNCLASSIFIED'><value>Catalog:UNCLASSIFIED</value></option>
  603. <option label='Custom'><value>Custom</value></option>
  604. </field>
  605. <field label='Custom Node Label' type='text-single'
  606. var='sec-label#custom-label'/>
  607. <field label='Node Clearance' type='list-multi' var='sec-label#clearance'>
  608. <value>Catalog:UNCLASSIFIED</value>
  609. <option label='SECRET'><value>Catalog:SECRET</value></option>
  610. <option label='CONFIDENTIAL'><value>Catalog:CONFIDENTIAL</value></option>
  611. <option label='UNCLASSIFIED'><value>Catalog:UNCLASSIFIED</value></option>
  612. <option label='Custom'><value>Custom</value></option>
  613. </field>
  614. <field label='Custom Node Clearance' type='text-single'
  615. var='sec-label#custom-clearance'/>
  616. </x>
  617. </configure>
  618. </pubsub>
  619. </iq>
  620. ]]></example>
  621. <section3 topic='Updating an Existing Node Configuration'
  622. anchor='ownerusercases-configuration-updating'>
  623. <p>Changing the Security Label or Clearance of an existing node is problematic for a number of
  624. reasons:</p>
  625. <ul>
  626. <li>Subscribers may no longer be Cleared to view a node to which they are already subscribed
  627. </li>
  628. <li>Existing items persisted within a node may be of a higher Security Label than the new
  629. node clearance allows</li>
  630. </ul>
  631. <p>For these reasons an implementation MAY wish to disallow changes to the Security Label of
  632. an existing node with subscribers, disallow changes to the Clearance of a node with items,
  633. or limit the options within the node configuration to those which do not cause a conflict.
  634. </p>
  635. <p>If an implementation chooses to allow a change to the clearance of a node that conflicts
  636. with the Security Label of existing items within the node then the server MUST purge the
  637. node of all items which are no longer within the updated clearance of the node, with or
  638. without notifying subscribers.</p>
  639. <p>If an implementation chooses to allow a change to the Security Label of the node that
  640. causes conflicts with existing subscribers to the node then the server MUST remove all
  641. subscriptions from subscribers that are no longer Cleared to view the node. The server MUST
  642. notify these subscribers. The server SHOULD send a Node Deletion notification, but might
  643. instead send a Subscription Cancellation notification if entities are to be aware of the
  644. existence of nodes they do not have Clearance to view.</p>
  645. <p>The server MUST prevent a change to the Security Label of the node which would prevent a
  646. node owner from accessing the node.</p>
  647. <example caption='Node Deletion Notification'><![CDATA[
  648. <message from='pubsub.shakespeare.lit' id='deletenotify1' to='francisco@denmark.lit'>
  649. <event xmlns=''>
  650. <delete node='princely_musings' />
  651. </event>
  652. </message>
  653. ]]></example>
  654. <example caption='Subscription Cancellation Notification'><![CDATA[
  655. <message from='pubsub.shakespeare.lit' id='unsubnotify1' to='horatio@denmark.lit'>
  656. <event xmlns=''>
  657. <subscription jid='horatio@denmark.lit' node='princely_musings' subscription='none'/>
  658. </event>
  659. </message>
  660. ]]></example>
  661. </section3>
  662. </section2>
  663. </section1>
  664. <section1 topic='Business Rules' anchor='rules'>
  665. <ol>
  666. <li>An entity SHOULD NOT be aware of the existance of nodes or items that they do
  667. not have appropriate Clearance to view (But see <link url='#impl-access'>Implementation Notes:
  668. Access to items for which the entity is not Cleared</link>)</li>
  669. <li>Items MUST only be accessible by entities with the appropriate Clearance</li>
  670. <li>If a node has an associated Clearance then the node MUST only deal with (i.e.
  671. persist or notify) items which are compatible with the Clearance</li>
  672. </ol>
  673. </section1>
  674. <section1 topic='Implementation Notes' anchor='impl'>
  675. <section2 topic='Access to Items for which the Entity is not Cleared' anchor='impl-access'>
  676. <p>The protocol defined has the intention that, as far as possible, an entity should be unaware of
  677. the existence of any nodes or items which they are not Cleared to view. Therefore server
  678. responses to a request for a node which the entity is not Cleared to view SHOULD be identical to
  679. a response as if that node did not exist (See <link url="#rules">BR1</link>), i.e. an
  680. &ITEMNOTFOUND; error is returned</p>
  681. <example caption="Request for a node that the entity is not Cleared to view"><![CDATA[
  682. <iq from='pubsub.shakespeare.lit'
  683. id='sub1'
  684. to='francisco@denmark.lit/barracks'
  685. type='error'>
  686. <error type='cancel'>
  687. <item-not-found xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  688. </error>
  689. </iq>
  690. ]]></example>
  691. <p>It is worth noting that there are certain situations where this is impossible, for example if
  692. an entity wishes to create a node with the same NodeID as an existing node that they are not
  693. Cleared to view.</p>
  694. <p>Alternatively, an implementation might wish to relax this rule and allow entities to become
  695. aware of nodes they do not have Clearance to view. In this case an &INSUFFICIENTCLEARANCE;
  696. error MAY be returned instead.</p>
  697. </section2>
  698. <section2 topic='Collection Nodes' anchor='impl-collections'>
  699. <p>If a service implements &xep0248; then there will need to be some consideration of node
  700. and item visibility within the node hierarchy.</p>
  701. <p>Due to the complexity of the access control policies involved, an implementation MAY choose
  702. to do one or more of the following to simplify the implementation:</p>
  703. <ul>
  704. <li>Prevent the use of Security Labels and/or Clearances on collection nodes.</li>
  705. <li>Prevent publishing items with Security Labels to non-orphan leaf nodes (i.e. leaf nodes
  706. with an association to a collection node).</li>
  707. <li>Prevent the association of leaf nodes containing Security Labelled items with collection
  708. nodes.</li>
  709. <li>Prevent the association of Security Labelled nodes with collection nodes.</li>
  710. </ul>
  711. <p>The rules and protocols defined elsewhere in this document are generally applicable to
  712. collection nodes with the following additions:</p>
  713. <section3 topic='Notifications' anchor='impl-collections-notifications'>
  714. <p>A collection node MUST NOT forward a publish notification with a Security Label that is
  715. incompatible with the Clearance of the collection node.</p>
  716. <p>A collection node SHOULD NOT forward a node change notification
  717. (create/update/delete/associate) where the Security Label of the affected node is
  718. incompatible with the Clearance of the collection node.</p>
  719. <p>The server SHOULD NOT send node change notifications to any entity where the Security Label
  720. of the affected node is incompatible with the Clearance of the entity.</p>
  721. </section3>
  722. <section3 topic='Retrieving Items on Collection Nodes' anchor='impl-collections-retrieveitems'>
  723. <p>The server MUST NOT return any items from leaf nodes where the individual Security Label of
  724. the item is incompatible with the Clearance of the requesting entity.</p>
  725. <p>The server SHOULD NOT return any items from any associated nodes where the Security Label
  726. of the leaf node, or any intermediate collection node on the node graph, is incompatible
  727. with the Clearance of the requesting entity.</p>
  728. </section3>
  729. <section3 topic='Associating a Node to a Collection' anchor='impl-collections-associating'>
  730. <p>A server SHOULD NOT allow an entity to associate, either through configuration or through
  731. an &ASSOCIATE; statement, a child node to a collection node if the Security Label of the
  732. child node is incompatible with the Clearance of the collection node.</p>
  733. </section3>
  734. </section2>
  735. <section2 topic='Implementation Specific Structuring within Items' anchor='impl-itemstructure'>
  736. <p>An implementation might choose to impose some kind of structure on items within a node. For
  737. example: items may include a list of blog posts, but may also include comments relating to
  738. specific blog posts from other users.</p>
  739. <p>An implementation MAY apply different logic to the visibility of items in this case,
  740. perhaps by disallowing access to comment items if the requester is not Cleared to view the
  741. associated blog post item, even if the individual Security Label on the comment item would not
  742. normally prevent access.</p>
  743. <p>However, the server MUST NOT allow access to an item if the requester is not Cleared to view
  744. the Security Label for the item (i.e. this mechanism must only be used to further restrict
  745. access to items and must not be used to widen access).</p>
  746. </section2>
  747. <section2 topic='Limiting Notifications to a Certain Clearance' anchor='impl-limitclearance'>
  748. <p>An implementation may wish to allow a subscriber to limit the sensitivity of items which are
  749. delivered for a certain subscription. For example: a subscriber may wish to only receive
  750. notifications of items which are unclassified, even if the node has a higher clearance.</p>
  751. <p>One way this could be implemented is by expanding the Data Form for the subscription options.
  752. </p>
  753. <example caption="Form with ability to limit subscription clearance"><![CDATA[
  754. <iq from='pubsub.shakespeare.lit'
  755. id='options1'
  756. to='francisco@denmark.lit/barracks'
  757. type='result'>
  758. <pubsub xmlns=''>
  759. <options node='princely_musings' jid='francisco@denmark.lit'>
  760. <x xmlns='jabber:x:data' type='form'>
  761. ...
  762. <field label='Limit Clearance' type='list-multi' var='sec-label#clearance'>
  763. <value>Catalog:UNCLASSIFIED</value>
  764. <option label='SECRET'><value>Catalog:SECRET</value></option>
  765. <option label='CONFIDENTIAL'><value>Catalog:CONFIDENTIAL</value></option>
  766. <option label='UNCLASSIFIED'><value>Catalog:UNCLASSIFIED</value></option>
  767. <option label='Custom'><value>Custom</value></option>
  768. </field>
  769. ...
  770. </x>
  771. </options>
  772. </pubsub>
  773. </iq>
  774. ]]></example>
  775. </section2>
  776. </section1>
  777. <section1 topic='Security Considerations' anchor='security'>
  778. <p>This document is an extension to &xep0258; and therefore any security considerations noted in
  779. that document will also apply to this document.</p>
  780. </section1>
  781. <section1 topic='IANA Considerations' anchor='iana'>
  782. <p>This document requires no interaction with the &IANA;</p>
  783. </section1>
  784. <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  785. <section2 topic='Protocol Namespaces' anchor='registrar-namespaces'>
  786. <p>This specification defines the following XML namespaces:</p>
  787. <ul>
  788. <li>&NSMAIN;</li>
  789. <li>&NSERRORS;</li>
  790. </ul>
  791. </section2>
  792. <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
  793. &NSVER;
  794. </section2>
  795. </section1>
  796. <section1 topic='XML Schema' anchor='schema'>
  797. <section2 topic='&NSMAIN;' anchor='schemas-main'>
  798. <code><![CDATA[
  799. <?xml version="1.0" encoding="utf-8" ?>
  800. <xs:schema
  801. elementFormDefault='qualified'
  802. targetNamespace='urn:xmpp:sec-label:pubsub:0'
  803. xmlns='urn:xmpp:sec-label:pubsub:0'
  804. xmlns:xs=''>
  805. <xs:annotation>
  806. <xs:documentation>
  807. The protocol documented by this schema is defined in
  808. XEP-xxxx:
  809. </xs:documentation>
  810. </xs:annotation>
  811. <xs:attribute name='label' type='xs:IDREF'>
  812. <xs:annotation>
  813. <xs:documentation>
  814. References an &quot;id&quot; value in a &lt;securitylabel&gt; element. The referenced
  815. Security Label MUST then be applied to the element content.
  816. </xs:documentation>
  817. </xs:annotation>
  818. </xs:attribute>
  819. <xs:attribute name='id' type='xs:ID'>
  820. <xs:annotation>
  821. <xs:documentation>
  822. Defines a unique (across the document) id for a &lt;securitylabel&gt; element that can be
  823. referenced from a &quot;label&quot; attribute.
  824. </xs:documentation>
  825. </xs:annotation>
  826. </xs:attribute>
  827. </xs:schema>
  828. ]]></code>
  829. </section2>
  830. <section2 topic='&NSERRORS;' anchor='schemas-error'>
  831. <code><![CDATA[
  832. <?xml version='1.0' encoding='UTF-8'?>
  833. <xs:schema
  834. elementFormDefault='qualified'
  835. targetNamespace='urn:xmpp:sec-label:pubsub:errors:0'
  836. xmlns='urn:xmpp:sec-label:pubsub:errors:0'
  837. xmlns:xs=''>
  838. <xs:annotation>
  839. <xs:documentation>
  840. This namespace is used for error reporting only, as
  841. defined in XEP-xxxx:
  843. </xs:documentation>
  844. </xs:annotation>
  845. <xs:element name='insufficient-clearance' type='empty'/>
  846. </xs:schema>
  847. ]]></code>
  848. </section2>
  849. </section1>
  850. <section1 topic='Acknowledgements' anchor='ack'>
  851. <p>Thanks to Dave Cridland, John Atherton, Kurt Zeilenga, Lloyd Watkin, Ralph Meijer and Stephen
  852. Welch for their contributions.</p>
  853. </section1>
  854. </xep>