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-0258.xml 43KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883
  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <!DOCTYPE xep SYSTEM 'xep.dtd' [
  3. <!ENTITY % ents SYSTEM 'xep.ent'>
  4. <!ENTITY LABEL "<tt>&lt;label/&gt;</tt>">
  5. <!ENTITY CATALOG "<tt>&lt;catalog/&gt;</tt>">
  6. <!ENTITY ITEM "<tt>&lt;item/&gt;</tt>">
  7. <!ENTITY SECURITYLABEL "<tt>&lt;securitylabel/&gt;</tt>">
  8. <!ENTITY DISPLAYMARKING "<tt>&lt;displaymarking/&gt;</tt>">
  9. <!ENTITY EQUIVALENTLABEL "<tt>&lt;equivalentlabel/&gt;</tt>">
  10. <!ENTITY HEADLINE "<tt>&lt;headline/&gt;</tt>">
  11. <!ENTITY IDENTITY "<tt>&lt;identity/&gt;</tt>">
  12. %ents;
  13. ]>
  14. <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
  15. <xep>
  16. <header>
  17. <title>Security Labels in XMPP</title>
  18. <abstract>This document describes the use of security labels in XMPP. The document specifies
  19. how security label meta-data is carried in XMPP, when this meta-data should or should
  20. not be provided, and how the meta-data is to be processed.</abstract> &LEGALNOTICE;
  21. <number>0258</number>
  22. <status>Draft</status>
  23. <type>Standards Track</type>
  24. <sig>Standards</sig>
  25. <approver>Council</approver>
  26. <dependencies>
  27. <spec>XMPP Core</spec>
  28. <spec>XEP-0001</spec>
  29. </dependencies>
  30. <supersedes/>
  31. <supersededby/>
  32. <shortname>sec-label</shortname>
  33. <schemaloc>
  34. <ns>extension</ns>
  35. <url>http://xmpp.org/schemas/sec-label.xsd</url>
  36. </schemaloc>
  37. <schemaloc>
  38. <ns>catalog</ns>
  39. <url>http://xmpp.org/schemas/sec-label-catalog.xsd</url>
  40. </schemaloc>
  41. <schemaloc>
  42. <ns>esssecuritylabel</ns>
  43. <url>http://xmpp.org/schemas/sec-label-ess.xsd</url>
  44. </schemaloc>
  45. <author>
  46. <firstname>Kurt</firstname>
  47. <surname>Zeilenga</surname>
  48. <email>Kurt.Zeilenga@Isode.COM</email>
  49. <jid>Kurt.Zeilenga@Isode.COM</jid>
  50. </author>
  51. <revision>
  52. <version>1.1</version>
  53. <date>2013-04-08</date>
  54. <initials>kdz</initials>
  55. <remark><p>Clarify catalogs are temporal objects. Offer client handling suggestions.</p></remark>
  56. </revision>
  57. <revision>
  58. <version>1.0</version>
  59. <date>2011-11-10</date>
  60. <initials>psa</initials>
  61. <remark><p>Per a vote of the XMPP Council, advanced specification to Draft; corrected version of catalog namespace in schema.</p></remark>
  62. </revision>
  63. <revision>
  64. <version>0.10</version>
  65. <date>2011-11-03</date>
  66. <initials>kdz</initials>
  67. <remark>
  68. <p>Address last call comments.</p>
  69. </remark>
  70. </revision>
  71. <revision>
  72. <version>0.9</version>
  73. <date>2011-09-21</date>
  74. <initials>kdz</initials>
  75. <remark>
  76. <p>Add optional <tt>from=</tt> attribute to catalog element for S2S requests. Make
  77. editorial changes.</p>
  78. </remark>
  79. </revision>
  80. <revision>
  81. <version>0.8</version>
  82. <date>2011-08-11</date>
  83. <initials>kdz</initials>
  84. <remark>
  85. <p>Correct catalog schema.</p>
  86. </remark>
  87. </revision>
  88. <revision>
  89. <version>0.7</version>
  90. <date>2011-03-08</date>
  91. <initials>kdz</initials>
  92. <remark>
  93. <p>Illustrate XEP Multi-User Chat room security label configuration. Make
  94. clarifications and minor editorial changes.</p>
  95. </remark>
  96. </revision>
  97. <revision>
  98. <version>0.6</version>
  99. <date>2010-07-30</date>
  100. <initials>kdz</initials>
  101. <remark>
  102. <p>Extend catalog handling. Minor editorial changes.</p>
  103. </remark>
  104. </revision>
  105. <revision>
  106. <version>0.5</version>
  107. <date>2009-07-27</date>
  108. <initials>kdz</initials>
  109. <remark>
  110. <p>Remove &LABEL;/&EQUIVALENTLABEL; <tt>type=</tt> attribute. Clarify label catalog
  111. discovery. Clarify syntax of <tt>selector=</tt> attribute.</p>
  112. </remark>
  113. </revision>
  114. <revision>
  115. <version>0.4</version>
  116. <date>2009-07-23</date>
  117. <initials>kdz</initials>
  118. <remark>
  119. <p>Update label catalogs to include user input selector.</p>
  120. </remark>
  121. </revision>
  122. <revision>
  123. <version>0.3</version>
  124. <date>2009-03-20</date>
  125. <initials>kdz</initials>
  126. <remark>
  127. <p>Add text regarding default bg/fg colors. Correct examples.</p>
  128. </remark>
  129. </revision>
  130. <revision>
  131. <version>0.2</version>
  132. <date>2009-03-10</date>
  133. <initials>kdz</initials>
  134. <remark>
  135. <p>Reworked discovery and various updates.</p>
  136. </remark>
  137. </revision>
  138. <revision>
  139. <version>0.1</version>
  140. <date>2009-01-05</date>
  141. <initials>psa</initials>
  142. <remark>
  143. <p>Initial published version.</p>
  144. </remark>
  145. </revision>
  146. <revision>
  147. <version>0.0.081203</version>
  148. <date>2008-12-03</date>
  149. <initials>kdz</initials>
  150. <remark>
  151. <p>Initial draft.</p>
  152. </remark>
  153. </revision>
  154. </header>
  155. <section1 topic="Introduction" anchor="intro">
  156. <p>A security label, sometimes referred to as a confidentiality label, is a structured
  157. representation of the sensitivity of a piece of information. A security label is used in
  158. conjunction with a clearance, a structured representation of what information
  159. sensitivities a person (or other entity) is authorized to access, and a security policy
  160. to control access to each piece of information. For instance, a message could be labeled
  161. as "SECRET", and hence requiring the sender and the receiver to each have a clearance
  162. granting access to "SECRET" information. &X.841; provides a discussion of security
  163. labels, clearances, and security policy.</p>
  164. <p>Sensitivity-based authorization is used in networks which operate under a set of
  165. information classification rules, such as in government agency networks. The
  166. standardized formats for security labels, clearances, and security policy are
  167. generalized and do have application in non-government networks.</p>
  168. <p>This document describes the use of security labels in &xmpp;. The document specifies how
  169. security label meta-data is carried in XMPP. It standardizes a mechanism for carrying
  170. ESS Security Labels in XMPP, as well as provides for use of other label formats. ESS
  171. Security Labels are specified in &rfc2634;. ESS Security Labels are commonly used in
  172. conjunction with &X.500; clearances and either X.841 or &SDN.801c; security
  173. policies.</p>
  174. <example caption="Message with ESS Security Label"><![CDATA[
  175. <message to='romeo@example.net' from='juliet@example.com/balcony'>
  176. <body>This content is classified.</body>
  177. <securitylabel xmlns='urn:xmpp:sec-label:0'>
  178. <displaymarking fgcolor='black' bgcolor='red'>SECRET</displaymarking>
  179. <label><esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'>
  180. MQYCAQQGASk=
  181. </esssecuritylabel></label>
  182. </securitylabel>
  183. </message>
  184. ]]></example>
  185. <example caption="Message with IC-ISM Label"><![CDATA[
  186. <message to='romeo@example.net' from='juliet@example.com/balcony'>
  187. <body>This content is classified.</body>
  188. <securitylabel xmlns='urn:xmpp:sec-label:0'>
  189. <displaymarking fgcolor='black' bgcolor='red'>SECRET</displaymarking>
  190. <label><icismlabel xmlns='http://example.gov/IC-ISM/0' classification='S'
  191. ownerProducer='USA'/></label>
  192. </securitylabel>
  193. </message>
  194. ]]></example>
  195. <p>Note: The &IC-ISM; label example is for <em>illustrative purposes only</em>.</p>
  196. <p>The document details when security label meta-data should or should not be provided, and
  197. how this meta-data is to be processed.</p>
  198. <p>This document does not provide:</p>
  199. <ul>
  200. <li>any mechanism for a client to discover the security policy in force at its home
  201. server, or any other server;</li>
  202. <li>any mechanism for a client to discover the user's clearance, or the clearance of
  203. associated with any resource; nor</li>
  204. <li>any administrative mechanism for a client to configure configure policy,
  205. clearance, and labels of any resource.</li>
  206. </ul>
  207. <p>Such mechanisms may be introduced in subsequent documents.</p>
  208. <p>This document does not discuss how one might securely bind a security label to a stanza.
  209. It is expected a subsequent document will tackle this topic.</p>
  210. </section1>
  211. <section1 topic="Discovering Feature Support" anchor="disco">
  212. <p>An entity (client or server) which supports the XMPP Security Label protocol MUST report
  213. that fact by including a service discovery feature of "<tt>urn:xmpp:sec-label:0</tt>" in
  214. response to a &xep0030; information request.</p>
  215. <p>Clients wishing to include a XMPP Security Label element in any stanza they generate
  216. SHOULD determine if their server supports the XMPP Security Label protocol. If their
  217. server does not support XMPP Security Label, the client SHOULD NOT generate XMPP
  218. Security Labels as the server not supporting this protocol will generally ignore XMPP
  219. Security Labels as they would any other unrecognized element.</p>
  220. <p>As each service domain may have different support for security labels, servers should
  221. advertise and clients should perform appropriate discovery lookups on a per service
  222. basis.</p>
  223. <example caption="Service Discovery information request"><![CDATA[
  224. <iq type='get'
  225. from='user@example.com/Work'
  226. to='example.com'
  227. id='disco1'>
  228. <query xmlns='http://jabber.org/protocol/disco#info'/>
  229. </iq>
  230. ]]></example>
  231. <example caption="Service Discovery information response"><![CDATA[
  232. <iq type='result'
  233. from='example.com'
  234. to='user@example.com/Work'
  235. id='disco1'>
  236. <query xmlns='http://jabber.org/protocol/disco#info'>
  237. ...
  238. <feature var='urn:xmpp:sec-label:0'/>
  239. ...
  240. </query>
  241. </iq>
  242. ]]></example>
  243. </section1>
  244. <section1 topic="Protocol" anchor="protocol">
  245. <p>An element, &SECURITYLABEL;, is defined to carry security label meta-data. This meta-data
  246. includes a security label, zero or more equivalent security labels, and optionally
  247. display marking data.</p>
  248. <example caption="Labeled Message"><![CDATA[
  249. <message to='romeo@example.net' from='juliet@example.com/balcony'>
  250. <body>This content is classified.</body>
  251. <securitylabel xmlns='urn:xmpp:sec-label:0'>
  252. <displaymarking fgcolor='black' bgcolor='red'>SECRET</displaymarking>
  253. <label>
  254. <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'
  255. >MQYCAQIGASk=</esssecuritylabel>
  256. </label>
  257. <equivalentlabel>
  258. <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'
  259. >MRUCAgD9DA9BcXVhIChvYnNvbGV0ZSk=</esssecuritylabel>
  260. </equivalentlabel>
  261. </securitylabel>
  262. </message>
  263. ]]></example>
  264. <p>The security label meta-data is carried in an &SECURITYLABEL; element. The
  265. &SECURITYLABEL; element which contains one and only one &LABEL; element, zero or more
  266. &EQUIVALENTLABEL; elements, and an optional &DISPLAYMARKING; element.</p>
  267. <p>The &LABEL; provides the primary security label. It is commonly issued by the sender
  268. under the security policy of that they and their home server operating under. The
  269. &LABEL; contains either a single element representing the primary security label or is
  270. empty to indicate use of a default.</p>
  271. <p>Each &EQUIVALENTLABEL; represents an equivalent security label under other policies. Each
  272. &EQUIVALENTLABEL; contains a single element representing the equivalent label. This
  273. element might be used when a recipient is known to hold a clearance under a different
  274. policy than the sender.</p>
  275. <p>The &DISPLAYMARKING; element contains a display string for use by implementations which
  276. are unable to utilize the applicable security policy to generate display markings. The
  277. element may optionally contain two attributes, <tt>fgcolor=</tt> and <tt>bgcolor=</tt>,
  278. whose values are HTML color strings (e.g., '<tt>red</tt>' or '<tt>#ff0000</tt>'), for
  279. use in colorizing the display marking. The <tt>fgcolor=</tt> default is <tt>black</tt>.
  280. The <tt>bgcolor=</tt> default is <tt>white</tt>. </p>
  281. </section1>
  282. <section1 topic="Label Catalog Discovery" anchor="label-catalog">
  283. <p>A client can request a catalog for a particular JID by sending a catalog discovery
  284. request to the client's server. Where the JID is hosted by some other server, the
  285. client's server is expected to produce a suitable catalog (or fail the request). The
  286. client's server may, as needed, query catalogs from other servers in order to fulfill
  287. the client's request.</p>
  288. <p>While this specification does not preclude a client from directing a catalog request
  289. elsewhere, it is noted that catalog returned by a party other than its server may not be
  290. directly usable by the client. For instance, the client's server might require a
  291. particular only-locally-known label be used in messages to a particular remote JID.</p>
  292. <p>It is RECOMMENDED the server publish catalogs of security label for use by clients.</p>
  293. <p>Two identical catalog requests may return different results, even for the same
  294. requester, as the results may depend on numerous factors. It is suggested that clients
  295. request a catalog for use in a short-lived context, such as short-lived 1-to-1 chat
  296. session, for all use in stanzas of that session. For use in long-lived context, such
  297. as a long-lived Multi-User Chat session, it is suggested the client request the
  298. current catalog when the user becomes present after a period of extended absence.
  299. Alternatively, a client could simply cache catalog results for a configurable amount of
  300. time. With either approach, it is also suggested clients provide a means for the user
  301. to request an immediate refresh of all catalogs in all contexts. This is useful where
  302. the user made changes to a personal label catalog which the XMPP server uses as input
  303. in processing catalog requests. Note: there is no requirement that XMPP servers
  304. support 'personal label catalogs' (such details are beyond the scope of this document).</p>
  305. <p>If catalog is restrictive, as indicated by the <tt>restrict=</tt> attribute with value of
  306. true, the client SHOULD restrict the user to choosing one of the items from the catalog
  307. and use the label of that item (or no label if the selected item is empty).</p>
  308. <p>One and only one of the items may have a <tt>default=</tt> attribute with value of true.
  309. The client should default the label selection to this item in cases where the user has
  310. not selected an item.</p>
  311. <p>An item may have no security label. Such an item explicitly offers a choice of sending a
  312. stanza without a label. A non-restrictive catalog implicitly offers this choice when it
  313. does not contain an empty item.</p>
  314. <p>Each catalog provided should only contain labels for which the client is allowed to use
  315. (based upon the user's authorization) in a particular context (such as in chat room). A
  316. catalog may not include the complete set of labels available for the use by the client
  317. in the context.</p>
  318. <p><em>Note:</em> the single catalog per context approach used here is likely inadequate in
  319. environments where there are a large number of labels in use. It is expected that a more
  320. sophisticated approach will be introduced in a subsequent revision of this
  321. specification.</p>
  322. <p>As each service domain may have different support for security labels, servers should
  323. advertise and clients should perform appropriate discovery lookups on a per service
  324. basis.</p>
  325. <p>To indicate the support for label catalog discovery, a server advertises the
  326. <tt>urn:xmpp:sec-label:catalog:2</tt> feature. The following pair of examples
  327. illustrates this feature discovery.</p>
  328. <p>Items in the catalog may contain a <tt>selector=</tt> attribute. The value of this
  329. attribute represents the item's placement in a hierarchical organization of the items.
  330. If one item has a <tt>selector=</tt> attribute, all items should have a
  331. <tt>selector=</tt> attribute. The value of the <tt>selector=</tt> attribute conforms
  332. to the <tt>selector-value</tt> ABNF production:
  333. </p>
  334. <code><![CDATA[selector-value = (<item>"|")*<item>]]></code>
  335. <p>where &ITEM; is a sequence of characters not including "|".</p>
  336. <p>A value of "X|Y|Z" indicates that this item is "Z" in the the "Y" subset of the "X"
  337. subset of items. This information may be used, for instance, in generating label
  338. selection menus in graphical user interfaces.</p>
  339. <p><em>Note:</em> use of unnecessarily deep hierarchies should be avoided.</p>
  340. <example caption="Label Catalog Feature Discovery request"><![CDATA[
  341. <iq type='get'
  342. to='example.com'
  343. from='user@example.com/Work'
  344. id='disco1'>
  345. <query xmlns='http://jabber.org/protocol/disco#info'/>
  346. </iq>
  347. ]]></example>
  348. <example caption="Label Information Feature Discovery response"><![CDATA[
  349. <iq type='result'
  350. from='example.com'
  351. to='user@example.com/Work'
  352. id='disco1'>
  353. <query xmlns='http://jabber.org/protocol/disco#info'>
  354. ...
  355. <feature var='urn:xmpp:sec-label:catalog:2'/>
  356. ...
  357. </query>
  358. </iq>
  359. ]]></example>
  360. <p>The following example pair illustrates catalog discovery. The client directs the <tt>&IQ;</tt> to
  361. its server regardless of which catalog it requests via the <tt>to=</tt> attribute of in
  362. &CATALOG; element. The client SHOULD NOT provide a <tt>from=</tt> attribute in the
  363. &CATALOG; element.</p>
  364. <example caption="Label Catalog request"><![CDATA[
  365. <iq to='example.com' type='get' id='cat1'>
  366. <catalog xmlns='urn:xmpp:sec-label:catalog:2' to='example.com'/>
  367. </iq>
  368. ]]></example>
  369. <example caption="Label Catalog Get response"><![CDATA[
  370. <iq type='result' to='user@example.com/Work' id='cat1'>
  371. <catalog xmlns='urn:xmpp:sec-label:catalog:2'
  372. to='example.com' name='Default'
  373. desc='an example set of labels'
  374. restrict='false'>
  375. <item selector="Classified|SECRET">
  376. <securitylabel xmlns='urn:xmpp:sec-label:0'>
  377. <displaymarking fgcolor='black' bgcolor='red'>SECRET</displaymarking>
  378. <label>
  379. <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'
  380. >MQYCAQQGASk=</esssecuritylabel>
  381. </label>
  382. </securitylabel>
  383. </item>
  384. <item selector="Classified|CONFIDENTIAL">
  385. <securitylabel xmlns='urn:xmpp:sec-label:0'>
  386. <displaymarking fgcolor='black' bgcolor='navy'>CONFIDENTIAL</displaymarking>
  387. <label>
  388. <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'
  389. >MQYCAQMGASk</esssecuritylabel>
  390. </label>
  391. </securitylabel>
  392. </item>
  393. <item selector="Classified|RESTRICTED">
  394. <securitylabel xmlns='urn:xmpp:sec-label:0'>
  395. <displaymarking fgcolor='black' bgcolor='aqua'>RESTRICTED</displaymarking>
  396. <label>
  397. <esssecuritylabel xmlns='urn:xmpp:sec-label:ess:0'
  398. >MQYCAQIGASk=</esssecuritylabel>
  399. </label>
  400. </securitylabel>
  401. </item>
  402. <item selector="UNCLASSIFIED" default="true"/>
  403. </catalog>
  404. </iq>
  405. ]]></example>
  406. <p> Where the server needs to obtain a catalog from another server in order to respond to
  407. its client, it can send an &IQ; to that server requesting that catalog. The requesting
  408. server provides the bare JID of the requesting user in the <tt>from=</tt> attribute in
  409. the &CATALOG; element when it desires a catalog to be prepared specifically for the
  410. user. Otherwise the <tt>from=</tt> attribute in the &CATALOG; element is absent. </p>
  411. </section1>
  412. <section1 topic="Use in XMPP" anchor="xmpp-use">
  413. <p>The sensitivity-based access control decisions discussed herein are to be made
  414. independently of other access control decisions or other facilities. That is, the
  415. sensitivity-based access control decisions are not conditional on other factors.</p>
  416. <p>It is intended that &SECURITYLABEL; elements are only used as prescribed by this
  417. document, documents extending this document, or other formal specifications. Any other
  418. use of &SECURITYLABEL; SHOULD be viewed as a protocol violation. The stanza SHOULD be
  419. discarded with, if appropriate, an error response. Such error responses SHOULD NOT
  420. include content from the violating stanza, excepting that necessary to well-formed error
  421. responses. Error responses MUST NOT contain a &SECURITYLABEL; element. Any such error
  422. response violates this protocol and MUST be discarded by servers implementing this
  423. specification. Error responses MUST NOT be subjected to security label authorization
  424. checks. However, this prohibition does not preclude a server from taking appropriate
  425. action to prevent the disclosure of sensitive information, such as closing the
  426. stream.</p>
  427. <p>When use of a &SECURITYLABEL; element is prescribed, that use is RECOMMENDED. Absence of
  428. a &SECURITYLABEL; element implies the stanza has the default label as specified in the
  429. governing security policy. Given that the governing policy may not specify a default
  430. label, hence denying access to the stanza, supporting clients SHOULD provide a
  431. &SECURITYLABEL; element where prescribed.</p>
  432. <p>Typically, a client would allow the user to choose populate the &SECURITYLABEL; from one
  433. of from a small set of security labels selections known to it (through configuration
  434. and/or discovery and/or other means), such as from a pull-down menu. That selection
  435. would include appropriate values for the &LABEL;, &DISPLAYMARKING;, and
  436. &EQUIVALENTLABEL; elements.</p>
  437. <p>A policy-aware client may provide the user with an interface allowing the user to produce
  438. custom labeling data for inclusion in this set. A policy-aware client SHOULD preclude
  439. the user from producing &LABEL; values which the user's own clearance does not grant
  440. access to, and SHOULD preclude sending any label which the user's own clearance does not
  441. grant access to. Each &EQUIVALENTLABEL; value, if any, MUST be equivalent under an
  442. equivalent policy to the &LABEL;. The &DISPLAYMARKING; element SHOULD be set the display
  443. marking prescribed for the &LABEL; under the governing policy, or, if the governing
  444. policy prescribes no display marking for the &LABEL;, absent.</p>
  445. <p>A client which receives a stanza with &SECURITYLABEL; element is to prominently display
  446. the &DISPLAYMARKING; value. A policy-aware client may alternatively prominently display
  447. the marking for the &LABEL; prescribed by the governing policy.</p>
  448. <p>Each server is expected to make a number of sensitivity-based authorization decisions.
  449. Each decision is made by evaluating an Access Control Decision Function (ACDF) with a
  450. governing policy, a clearance, and a security label. The ACDF yields either
  451. <em>Grant</em> or <em>Deny</em>.</p>
  452. <p>If the user holds a valid clearance (known to the server) under the governing policy, the
  453. clearance input is the user's clearance. Otherwise, if the governing policy provides a
  454. default clearance, the clearance input is the default clearance. Otherwise, the
  455. clearance input is the nil clearance. The nil clearance is a clearance for which the
  456. ACDF always returns Deny when given as the clearance input.</p>
  457. <p>If the stanza contains a &SECURITYLABEL; element and the either the &LABEL; element or
  458. one of the &EQUIVALENTLABEL; elements contain an appropriate label, that label input is
  459. that label. Otherwise, the label input is the default label provided the governing
  460. policy or, if no default label is provided, the nil label. The nil label is a label for
  461. which the ACDF always returns Deny when given as the label input.</p>
  462. <p>The term "effective clearance" and "effective label" refer, respectively, to the
  463. clearance and label provided as input to the ACDF.</p>
  464. <p>Not all sensitivity-based authorization decisions an XMPP server might make involve a
  465. user clearance and/or stanza label. A server may only provide service to users which
  466. hold an appropriate clearance as determined by calling the ACDF with the user's
  467. clearance and a label associated with the service. A clearance might also be associated
  468. with the service to restrict the set of labels may be used in labeling stanzas. Labels
  469. and clearances can also be associated with network interfaces, remote servers, and chat
  470. rooms.</p>
  471. <section2 topic="Use in Instant Messaging" anchor="im-use">
  472. <p>A client may provide a &SECURITYLABEL; element in any <tt>&MESSAGE;</tt> it sends.</p>
  473. <!--
  474. <p>The server will make, at a minimum, the following accessing control decisions:
  475. <ul>
  476. <li>TBD</li>
  477. </ul>
  478. </p>
  479. -->
  480. </section2>
  481. <section2 topic="Use in Group Chat and Multi-User Chat" anchor="muc-use">
  482. <p>A client may provide a &SECURITYLABEL; element in <tt>&MESSAGE;</tt> stanzas.</p>
  483. <section3 topic="Discovery" anchor="muc-disco">
  484. <p>A server SHOULD provide a label feature and information discovery for the
  485. room.</p>
  486. <p>Clients SHOULD discover label feature and information on a per room basis.</p>
  487. </section3>
  488. <section3 topic="Sending Messages" anchor="muc-send">
  489. <p>Sending groupchat messages is similar to sending normal messages, however their
  490. are a few differences.</p>
  491. <p>Groupchat messages are addressed to the room. The room clearance must be suitable
  492. for the message label, else it should be rejected.</p>
  493. <p>The room's clearance may allow a variety of labels to be used. Not all
  494. participants may be cleared for all labels allowed in the room. The server MUST
  495. only deliver messages to participants for which they are cleared to receive.</p>
  496. </section3>
  497. <section3 topic="Room History" anchor="muc-history">
  498. <p>The server MUST only deliver messages to participants for which they are cleared
  499. to receive.</p>
  500. </section3>
  501. <section3 topic="Private Messages" anchor="muc-private">
  502. <p>Private messages SHOULD be handled much like groupchat messages, including
  503. rejection of messages for a label not suitable for the room. The server MUST NOT
  504. deliver messages to participants for which they are cleared to receive.</p>
  505. </section3>
  506. <section3 topic="Invitations" anchor="muc-invite">
  507. <p>Invitations may be labeled.</p>
  508. </section3>
  509. <section3 topic="Room Subject" anchor="muc-subject">
  510. <p>A stanza intended to change the room subject SHOULD not carry a security label
  511. and SHOULD NOT be subject to security-label authorization checks. Such a stanza
  512. does not have any impact on the security-label parameters associated with the
  513. room.</p>
  514. </section3>
  515. <section3 topic="Room Configuration" anchor="muc-config">
  516. <p>The server may allow for configuration of security label parameters via room
  517. configuration mechanisms. The approach is intended to be ad-hoc. Hence this
  518. section is intended to be illustrative of one possible approach. Implementations
  519. are free to utilize other approaches.</p>
  520. <example caption="Room Configuration Form"><![CDATA[
  521. <iq from='room@muc.example.com'
  522. id='create1'
  523. to='user@example.com/Work'
  524. type='result'>
  525. <query xmlns='http://jabber.org/protocol/muc#owner'>
  526. <x xmlns='jabber:x:data' type='form'>
  527. <title>"darkcave" room configuration</title>
  528. ...
  529. <field label='Room Label' type='list-single' var='sec-label#label'>
  530. <value>Catalog:UNCLASSIFIED</value>
  531. <option label='SECRET'><value>Catalog:SECRET</value></option>
  532. <option label='CONFIDENTIAL'><value>Catalog:CONFIDENTIAL</value></option>
  533. <option label='UNCLASSIFED'><value>Catalog:UNCLASSIFIED</value></option>
  534. <option label='Custom'><value>Custom</value></option>
  535. </field>
  536. <field label='Custom Room Label' type='text-single'
  537. var='sec-label#custom-label'/>
  538. <field label='Room Allowed Markings' type='list-multi' var='sec-label#clearance'>
  539. <value>Catalog:UNCLASSIFIED</value>
  540. <option label='SECRET'><value>Catalog:SECRET</value></option>
  541. <option label='CONFIDENTIAL'><value>Catalog:CONFIDENTIAL</value></option>
  542. <option label='UNCLASSIFED'><value>Catalog:UNCLASSIFIED</value></option>
  543. <option label='Custom'><value>Custom</value></option>
  544. </field>
  545. <field label='Custom Room Clearance' type='text-single'
  546. var='sec-label#custom-clearance'/>
  547. </x>
  548. </query>
  549. </iq>
  550. ]]></example>
  551. <p>In the above example, the server allows the room label to be set to one of to a
  552. subset of labels from the label catalog (see below), using the display name for
  553. selection, as well as custom label support. For custom label choice support, the
  554. server offers an single text box for entry of an appropriate text string
  555. indicating the label to use. Likewise for the room clearance and default room
  556. clearance.</p>
  557. <p>Though offering choices from the label catalog is often desirable, a server could
  558. only offer custom label and/or clearance support.</p>
  559. <example caption="Room Configuration Form"><![CDATA[
  560. <iq from='room@muc.example.com'
  561. id='create1'
  562. to='user@example.com/Work'
  563. type='result'>
  564. <query xmlns='http://jabber.org/protocol/muc#owner'>
  565. <x xmlns='jabber:x:data' type='form'>
  566. <title>"darkcave" room configuration</title>
  567. ...
  568. <field label='Room Label' type='text-single'
  569. var='sec-label#custom-label'/>
  570. <field label='Room Clearance' type='text-single'
  571. var='sec-label#custom-clearance'/>
  572. </x>
  573. </query>
  574. </iq>
  575. ]]></example>
  576. </section3>
  577. </section2>
  578. <section2 topic="Use in Presence" anchor="presence-use">
  579. <p>&SECURITYLABEL; elements are not to appear in <tt>&PRESENCE;</tt> stanzas. Server SHALL treat
  580. any <tt>&PRESENCE;</tt> stanza that contains a &SECURITYLABEL; as a protocol violation.</p>
  581. <p>Presence information is subject to sensitivity-base authorization decisions, however
  582. these decisions are made are made using a label associated with the presence
  583. resource, such as a chat room's label.</p>
  584. </section2>
  585. </section1>
  586. <section1 topic="Extension Considerations" anchor="exts">
  587. <p> This extension is itself extensible. In particular, the &LABEL; and &EQUIVALENTLABEL;
  588. elements are designed to hold a range of security labels formats. XML name spaces SHOULD
  589. be used to avoid name clashes. </p>
  590. <p> Future documents may specify how security-labels are used in other areas of XMPP, such
  591. as PubSub.</p>
  592. </section1>
  593. <!--
  594. <section1 topic='Implementation Notes' anchor='impl'>
  595. <p>OPTIONAL.</p>
  596. </section1>
  597. -->
  598. <section1 topic="Security Considerations" anchor="security">
  599. <p>This document is all about authorization, a key aspect of security. Hence, security
  600. considerations are discussed through this document.</p>
  601. <p>Nothing in this document ensures appropriate labeling the sensitivity of a piece of
  602. information. Addressing inappropriate labeling of information is beyond the scope of
  603. this document.</p>
  604. <p>Certain XMPP stanzas, such as <tt>&PRESENCE;</tt> stanzas, are not themselves subject to any
  605. sensitivity-based authorization decisions, and may be forwarded throughout the XMPP
  606. network. The content of these stanzas should not contain information requiring
  607. sensitivity-based dissemination controls.</p>
  608. <p>It is desirable to securely bind the security label to the object it labels. This may be
  609. accomplished through use of digital signatures. Specification of such is left to a
  610. future document. </p>
  611. </section1>
  612. <section1 topic="IANA Considerations" anchor="iana">
  613. <p>This document requires no interaction with &IANA;.</p>
  614. </section1>
  615. <section1 topic="XMPP Registrar Considerations" anchor="registrar">
  616. <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
  617. <p>This specification defines the following XML namespaces:</p>
  618. <ul>
  619. <li>urn:xmpp:sec-label:0</li>
  620. <li>urn:xmpp:sec-label:catalog:2</li>
  621. <li>urn:xmpp:sec-label:ess:0</li>
  622. </ul>
  623. <p>The &REGISTRAR; includes the foregoing namespaces in the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
  624. </section2>
  625. <section2 topic='Protocol Versioning' anchor='registrar-versioning'>
  626. &NSVER;
  627. </section2>
  628. </section1>
  629. <section1 topic="XML Schemas" anchor="schema">
  630. <section2 topic="Extension Schema" anchor="schema-sl">
  631. <code><![CDATA[
  632. <?xml version='1.0' encoding='UTF-8'?>
  633. <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="urn:xmpp:sec-label:0"
  634. xmlns="urn:xmpp:sec-label:0" elementFormDefault="qualified">
  635. <xs:annotation>
  636. <xs:documentation>
  637. The protocol documented by this schema is defined in
  638. XEP-0258: http://xmpp.org/extensions/xep-0258.html
  639. </xs:documentation>
  640. </xs:annotation>
  641. <xs:simpleType name="colorCSS">
  642. <xs:annotation>
  643. <xs:documentation>CSS colors (W3C colors + "orange")</xs:documentation>
  644. </xs:annotation>
  645. <xs:restriction base="xs:string">
  646. <xs:enumeration value="aqua"/>
  647. <xs:enumeration value="black"/>
  648. <xs:enumeration value="blue"/>
  649. <xs:enumeration value="fuschia"/>
  650. <xs:enumeration value="gray"/>
  651. <xs:enumeration value="green"/>
  652. <xs:enumeration value="lime"/>
  653. <xs:enumeration value="maroon"/>
  654. <xs:enumeration value="navy"/>
  655. <xs:enumeration value="olive"/>
  656. <xs:enumeration value="purple"/>
  657. <xs:enumeration value="red"/>
  658. <xs:enumeration value="silver"/>
  659. <xs:enumeration value="teal"/>
  660. <xs:enumeration value="white"/>
  661. <xs:enumeration value="yellow"/>
  662. <xs:enumeration value="orange"/>
  663. </xs:restriction>
  664. </xs:simpleType>
  665. <xs:simpleType name="colorRGB">
  666. <xs:annotation>
  667. <xs:documentation>Hex encoded RGB</xs:documentation>
  668. </xs:annotation>
  669. <xs:restriction base="xs:string">
  670. <xs:pattern value="#[0-9A-Fa-f]{6}"/>
  671. </xs:restriction>
  672. </xs:simpleType>
  673. <xs:simpleType name="color">
  674. <xs:annotation>
  675. <xs:documentation>Color</xs:documentation>
  676. </xs:annotation>
  677. <xs:union memberTypes="colorCSS colorRGB"/>
  678. </xs:simpleType>
  679. <xs:complexType name="displaymarking">
  680. <xs:annotation>
  681. <xs:documentation>Display Marking</xs:documentation>
  682. <xs:documentation>String to be prominently displayed along with labeled
  683. object.</xs:documentation>
  684. </xs:annotation>
  685. <xs:simpleContent>
  686. <xs:extension base="xs:string">
  687. <xs:attribute name="bgcolor" type="color" use="optional" default="white"/>
  688. <xs:attribute name="fgcolor" type="color" use="optional" default="black"/>
  689. </xs:extension>
  690. </xs:simpleContent>
  691. </xs:complexType>
  692. <xs:complexType name="label">
  693. <xs:choice minOccurs="0">
  694. <xs:any namespace="##other" processContents="lax"/>
  695. </xs:choice>
  696. </xs:complexType>
  697. <xs:element name="securitylabel">
  698. <xs:annotation>
  699. <xs:documentation>A Security Label</xs:documentation>
  700. </xs:annotation>
  701. <xs:complexType>
  702. <xs:sequence>
  703. <xs:element name="displaymarking" type="displaymarking">
  704. <xs:annotation>
  705. <xs:documentation>A Display Marking</xs:documentation>
  706. <xs:documentation>To be prominently displayed</xs:documentation>
  707. </xs:annotation>
  708. </xs:element>
  709. <xs:element name="label" type="label">
  710. <xs:annotation>
  711. <xs:documentation>The Primary Label</xs:documentation>
  712. </xs:annotation>
  713. </xs:element>
  714. <xs:element name="equivalentlabel" type="label" minOccurs="0" maxOccurs="unbounded">
  715. <xs:annotation>
  716. <xs:documentation>An Equivalent Label</xs:documentation>
  717. </xs:annotation>
  718. </xs:element>
  719. </xs:sequence>
  720. </xs:complexType>
  721. </xs:element>
  722. </xs:schema>
  723. ]]></code>
  724. <p>A copy of this schema is available at <link
  725. url="http://xmpp.org/schemas/sec-label.xsd">
  726. http://xmpp.org/schemas/sec-label.xsd</link>.</p>
  727. </section2>
  728. <section2 topic="&lt;catalog/&gt; schema" anchor="schema-catalog">
  729. <code><![CDATA[
  730. <?xml version="1.0" encoding="UTF-8"?>
  731. <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:sl="urn:xmpp:sec-label:0"
  732. xmlns="urn:xmpp:sec-label:catalog:2" targetNamespace="urn:xmpp:sec-label:catalog:2"
  733. elementFormDefault="qualified">
  734. <xs:annotation>
  735. <xs:documentation>
  736. The protocol documented by this schema is defined in
  737. XEP-0258: http://xmpp.org/extensions/xep-0258.html
  738. </xs:documentation>
  739. </xs:annotation>
  740. <xs:import schemaLocation="sec-label.xsd" namespace="urn:xmpp:sec-label:0"/>
  741. <xs:attribute name="to" type="xs:string">
  742. <xs:annotation>
  743. <xs:documentation>Target JabberId</xs:documentation>
  744. </xs:annotation>
  745. </xs:attribute>
  746. <xs:attribute name="from" type="xs:string">
  747. <xs:annotation>
  748. <xs:documentation>Target JabberId</xs:documentation>
  749. </xs:annotation>
  750. </xs:attribute>
  751. <xs:attribute name="name" type="xs:string">
  752. <xs:annotation>
  753. <xs:documentation>Name</xs:documentation>
  754. </xs:annotation>
  755. </xs:attribute>
  756. <xs:attribute name="desc" type="xs:string">
  757. <xs:annotation>
  758. <xs:documentation>Description</xs:documentation>
  759. </xs:annotation>
  760. </xs:attribute>
  761. <xs:attribute name="id" type="xs:string">
  762. <xs:annotation>
  763. <xs:documentation>Identifer for current revision, commonly a hash</xs:documentation>
  764. </xs:annotation>
  765. </xs:attribute>
  766. <xs:attribute name="size" type="xs:integer">
  767. <xs:annotation>
  768. <xs:documentation>Number of items</xs:documentation>
  769. </xs:annotation>
  770. </xs:attribute>
  771. <xs:attribute name="restrict" type="xs:boolean">
  772. <xs:annotation>
  773. <xs:documentation>Restrictive</xs:documentation>
  774. </xs:annotation>
  775. </xs:attribute>
  776. <xs:attribute name="selector" type="xs:string">
  777. <xs:annotation>
  778. <xs:documentation>User input selector</xs:documentation>
  779. </xs:annotation>
  780. </xs:attribute>
  781. <xs:attribute name="default" type="xs:boolean">
  782. <xs:annotation>
  783. <xs:documentation>default selection</xs:documentation>
  784. </xs:annotation>
  785. </xs:attribute>
  786. <xs:element name="catalog">
  787. <xs:annotation>
  788. <xs:documentation>A Catalog of Labels</xs:documentation>
  789. </xs:annotation>
  790. <xs:complexType>
  791. <xs:sequence>
  792. <xs:element name="item" minOccurs="0" maxOccurs="unbounded">
  793. <xs:complexType>
  794. <xs:sequence minOccurs="0">
  795. <xs:element ref="sl:securitylabel"/>
  796. </xs:sequence>
  797. <xs:attribute ref="selector" use="optional"/>
  798. <xs:attribute ref="default" use="optional"/>
  799. </xs:complexType>
  800. </xs:element>
  801. </xs:sequence>
  802. <xs:attribute ref="to" use="optional"/>
  803. <xs:attribute ref="from" use="optional"/>
  804. <xs:attribute ref="name" use="optional"/>
  805. <xs:attribute ref="desc" use="optional"/>
  806. <xs:attribute ref="id" use="optional"/>
  807. <xs:attribute ref="size" use="optional"/>
  808. <xs:attribute ref="restrict" use="optional"/>
  809. </xs:complexType>
  810. </xs:element>
  811. </xs:schema>
  812. ]]></code>
  813. <p>A copy of this schema is available at <link
  814. url="http://xmpp.org/schemas/sec-label-catalog.xsd">
  815. http://xmpp.org/schemas/sec-label-catalog.xsd</link>.</p>
  816. </section2>
  817. <section2 topic="&lt;esssecuritylabel/&gt; schema" anchor="schema-ess">
  818. <code><![CDATA[
  819. <?xml version="1.0" encoding="UTF-8"?>
  820. <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="urn:xmpp:sec-label:ess:0"
  821. xmlns="urn:xmpp:sec-label:ess:0" elementFormDefault="qualified">
  822. <xs:annotation>
  823. <xs:documentation>
  824. The protocol documented by this schema is defined in
  825. XEP-0258: http://xmpp.org/extensions/xep-0258.html
  826. </xs:documentation>
  827. </xs:annotation>
  828. <xs:element name="esssecuritylabel" type="xs:base64Binary">
  829. <xs:annotation>
  830. <xs:documentation>An S/MIME ESS SecurityLabel [RFC2634]</xs:documentation>
  831. <xs:documentation>Value is the base64 encoding of the BER/DER encoding of an ASN.1
  832. ESSSecurityLabel type as defined in RFC 2634. </xs:documentation>
  833. </xs:annotation>
  834. </xs:element>
  835. </xs:schema>
  836. ]]></code>
  837. <p>A copy of this schema is available at <link
  838. url="http://xmpp.org/schemas/sec-label-ess.xsd">
  839. http://xmpp.org/schemas/sec-label-ess.xsd</link>.</p>
  840. </section2>
  841. </section1>
  842. </xep>