XEP-0258: Security Labels in XMPP

Abstract:

This document describes the use of security labels in XMPP. The document specifies
how security label meta-data is carried in XMPP, when this meta-data should or should
not be provided, and how the meta-data is to be processed.

NOTICE: The protocol defined herein is a Draft Standard of the XMPP Standards Foundation. Implementations are encouraged and the protocol is appropriate for deployment in production systems, but some changes to the protocol are possible before it becomes a Final Standard.

A security label, sometimes referred to as a confidentiality label, is a structured
representation of the sensitivity of a piece of information. A security label is used in
conjunction with a clearance, a structured representation of what information
sensitivities a person (or other entity) is authorized to access, and a security policy
to control access to each piece of information. For instance, a message could be labeled
as "SECRET", and hence requiring the sender and the receiver to each have a clearance
granting access to "SECRET" information. X.841 [1] provides a discussion of security
labels, clearances, and security policy.

Sensitivity-based authorization is used in networks which operate under a set of
information classification rules, such as in government agency networks. The
standardized formats for security labels, clearances, and security policy are
generalized and do have application in non-government networks.

This document describes the use of security labels in XMPP [2]. The document specifies how
security label meta-data is carried in XMPP. It standardizes a mechanism for carrying
ESS Security Labels in XMPP, as well as provides for use of other label formats. ESS
Security Labels are specified in RFC 2634 [3]. ESS Security Labels are commonly used in
conjunction with X.500 [4] clearances and either X.841 or SDN.801c [5] security
policies.

An entity (client or server) which supports the XMPP Security Label protocol MUST report
that fact by including a service discovery feature of "urn:xmpp:sec-label:0" in
response to a Service Discovery (XEP-0030) [7] information request.

Clients wishing to include a XMPP Security Label element in any stanza they generate
SHOULD determine if their server supports the XMPP Security Label protocol. If their
server does not support XMPP Security Label, the client SHOULD NOT generate XMPP
Security Labels as the server not supporting this protocol will generally ignore XMPP
Security Labels as they would any other unrecognized element.

As each service domain may have different support for security labels, servers should
advertise and clients should perform appropriate discovery lookups on a per service
basis.

The security label meta-data is carried in an <securitylabel/> element. The
<securitylabel/> element which contains one and only one <label/> element, zero or more
<equivalentlabel/> elements, and an optional <displaymarking/> element.

The <label/> provides the primary security label. It is commonly issued by the sender
under the security policy of that they and their home server operating under. The
<label/> contains either a single element representing the primary security label or is
empty to indicate use of a default.

Each <equivalentlabel/> represents an equivalent security label under other policies. Each
<equivalentlabel/> contains a single element representing the equivalent label. This
element might be used when a recipient is known to hold a clearance under a different
policy than the sender.

The <displaymarking/> element contains a display string for use by implementations which
are unable to utilize the applicable security policy to generate display markings. The
element may optionally contain two attributes, fgcolor= and bgcolor=,
whose values are HTML color strings (e.g., 'red' or '#ff0000'), for
use in colorizing the display marking. The fgcolor= default is black.
The bgcolor= default is white.

A client can request a catalog for a particular JID by sending a catalog discovery
request to the client's server. Where the JID is hosted by some other server, the
client's server is expected to produce a suitable catalog (or fail the request). The
client's server may, as needed, query catalogs from other servers in order to fulfill
the client's request.

While this specification does not preclude a client from directing a catalog request
elsewhere, it is noted that catalog returned by a party other than its server may not be
directly usable by the client. For instance, the client's server might require a
particular only-locally-known label be used in messages to a particular remote JID.

It is RECOMMENDED the server publish catalogs of security label for use by clients.

Two identical catalog requests may return different results, even for the same
requester, as the results may depend on numerous factors. It is suggested that clients
request a catalog for use in a short-lived context, such as short-lived 1-to-1 chat
session, for all use in stanzas of that session. For use in long-lived context, such
as a long-lived Multi-User Chat session, it is suggested the client request the
current catalog when the user becomes present after a period of extended absence.
Alternatively, a client could simply cache catalog results for a configurable amount of
time. With either approach, it is also suggested clients provide a means for the user
to request an immediate refresh of all catalogs in all contexts. This is useful where
the user made changes to a personal label catalog which the XMPP server uses as input
in processing catalog requests. Note: there is no requirement that XMPP servers
support 'personal label catalogs' (such details are beyond the scope of this document).

If catalog is restrictive, as indicated by the restrict= attribute with value of
true, the client SHOULD restrict the user to choosing one of the items from the catalog
and use the label of that item (or no label if the selected item is empty).

One and only one of the items may have a default= attribute with value of true.
The client should default the label selection to this item in cases where the user has
not selected an item.

An item may have no security label. Such an item explicitly offers a choice of sending a
stanza without a label. A non-restrictive catalog implicitly offers this choice when it
does not contain an empty item.

Each catalog provided should only contain labels for which the client is allowed to use
(based upon the user's authorization) in a particular context (such as in chat room). A
catalog may not include the complete set of labels available for the use by the client
in the context.

Note: the single catalog per context approach used here is likely inadequate in
environments where there are a large number of labels in use. It is expected that a more
sophisticated approach will be introduced in a subsequent revision of this
specification.

As each service domain may have different support for security labels, servers should
advertise and clients should perform appropriate discovery lookups on a per service
basis.

To indicate the support for label catalog discovery, a server advertises the
urn:xmpp:sec-label:catalog:2 feature. The following pair of examples
illustrates this feature discovery.

Items in the catalog may contain a selector= attribute. The value of this
attribute represents the item's placement in a hierarchical organization of the items.
If one item has a selector= attribute, all items should have a
selector= attribute. The value of the selector= attribute conforms
to the selector-value ABNF production:

selector-value = (<item>"|")*<item>

where <item/> is a sequence of characters not including "|".

A value of "X|Y|Z" indicates that this item is "Z" in the the "Y" subset of the "X"
subset of items. This information may be used, for instance, in generating label
selection menus in graphical user interfaces.

The following example pair illustrates catalog discovery. The client directs the <iq/> to
its server regardless of which catalog it requests via the to= attribute of in
<catalog/> element. The client SHOULD NOT provide a from= attribute in the
<catalog/> element.

Where the server needs to obtain a catalog from another server in order to respond to
its client, it can send an <iq/> to that server requesting that catalog. The requesting
server provides the bare JID of the requesting user in the from= attribute in
the <catalog/> element when it desires a catalog to be prepared specifically for the
user. Otherwise the from= attribute in the <catalog/> element is absent.

The sensitivity-based access control decisions discussed herein are to be made
independently of other access control decisions or other facilities. That is, the
sensitivity-based access control decisions are not conditional on other factors.

It is intended that <securitylabel/> elements are only used as prescribed by this
document, documents extending this document, or other formal specifications. Any other
use of <securitylabel/> SHOULD be viewed as a protocol violation. The stanza SHOULD be
discarded with, if appropriate, an error response. Such error responses SHOULD NOT
include content from the violating stanza, excepting that necessary to well-formed error
responses. Error responses MUST NOT contain a <securitylabel/> element. Any such error
response violates this protocol and MUST be discarded by servers implementing this
specification. Error responses MUST NOT be subjected to security label authorization
checks. However, this prohibition does not preclude a server from taking appropriate
action to prevent the disclosure of sensitive information, such as closing the
stream.

When use of a <securitylabel/> element is prescribed, that use is RECOMMENDED. Absence of
a <securitylabel/> element implies the stanza has the default label as specified in the
governing security policy. Given that the governing policy may not specify a default
label, hence denying access to the stanza, supporting clients SHOULD provide a
<securitylabel/> element where prescribed.

Typically, a client would allow the user to choose populate the <securitylabel/> from one
of from a small set of security labels selections known to it (through configuration
and/or discovery and/or other means), such as from a pull-down menu. That selection
would include appropriate values for the <label/>, <displaymarking/>, and
<equivalentlabel/> elements.

A policy-aware client may provide the user with an interface allowing the user to produce
custom labeling data for inclusion in this set. A policy-aware client SHOULD preclude
the user from producing <label/> values which the user's own clearance does not grant
access to, and SHOULD preclude sending any label which the user's own clearance does not
grant access to. Each <equivalentlabel/> value, if any, MUST be equivalent under an
equivalent policy to the <label/>. The <displaymarking/> element SHOULD be set the display
marking prescribed for the <label/> under the governing policy, or, if the governing
policy prescribes no display marking for the <label/>, absent.

A client which receives a stanza with <securitylabel/> element is to prominently display
the <displaymarking/> value. A policy-aware client may alternatively prominently display
the marking for the <label/> prescribed by the governing policy.

Each server is expected to make a number of sensitivity-based authorization decisions.
Each decision is made by evaluating an Access Control Decision Function (ACDF) with a
governing policy, a clearance, and a security label. The ACDF yields either
Grant or Deny.

If the user holds a valid clearance (known to the server) under the governing policy, the
clearance input is the user's clearance. Otherwise, if the governing policy provides a
default clearance, the clearance input is the default clearance. Otherwise, the
clearance input is the nil clearance. The nil clearance is a clearance for which the
ACDF always returns Deny when given as the clearance input.

If the stanza contains a <securitylabel/> element and the either the <label/> element or
one of the <equivalentlabel/> elements contain an appropriate label, that label input is
that label. Otherwise, the label input is the default label provided the governing
policy or, if no default label is provided, the nil label. The nil label is a label for
which the ACDF always returns Deny when given as the label input.

The term "effective clearance" and "effective label" refer, respectively, to the
clearance and label provided as input to the ACDF.

Not all sensitivity-based authorization decisions an XMPP server might make involve a
user clearance and/or stanza label. A server may only provide service to users which
hold an appropriate clearance as determined by calling the ACDF with the user's
clearance and a label associated with the service. A clearance might also be associated
with the service to restrict the set of labels may be used in labeling stanzas. Labels
and clearances can also be associated with network interfaces, remote servers, and chat
rooms.

Sending groupchat messages is similar to sending normal messages, however their
are a few differences.

Groupchat messages are addressed to the room. The room clearance must be suitable
for the message label, else it should be rejected.

The room's clearance may allow a variety of labels to be used. Not all
participants may be cleared for all labels allowed in the room. The server MUST
only deliver messages to participants for which they are cleared to receive.

Private messages SHOULD be handled much like groupchat messages, including
rejection of messages for a label not suitable for the room. The server MUST NOT
deliver messages to participants for which they are cleared to receive.

A stanza intended to change the room subject SHOULD not carry a security label
and SHOULD NOT be subject to security-label authorization checks. Such a stanza
does not have any impact on the security-label parameters associated with the
room.

The server may allow for configuration of security label parameters via room
configuration mechanisms. The approach is intended to be ad-hoc. Hence this
section is intended to be illustrative of one possible approach. Implementations
are free to utilize other approaches.

In the above example, the server allows the room label to be set to one of to a
subset of labels from the label catalog (see below), using the display name for
selection, as well as custom label support. For custom label choice support, the
server offers an single text box for entry of an appropriate text string
indicating the label to use. Likewise for the room clearance and default room
clearance.

Though offering choices from the label catalog is often desirable, a server could
only offer custom label and/or clearance support.

This extension is itself extensible. In particular, the <label/> and <equivalentlabel/>
elements are designed to hold a range of security labels formats. XML name spaces SHOULD
be used to avoid name clashes.

Future documents may specify how security-labels are used in other areas of XMPP, such
as PubSub.

This document is all about authorization, a key aspect of security. Hence, security
considerations are discussed through this document.

Nothing in this document ensures appropriate labeling the sensitivity of a piece of
information. Addressing inappropriate labeling of information is beyond the scope of
this document.

Certain XMPP stanzas, such as <presence/> stanzas, are not themselves subject to any
sensitivity-based authorization decisions, and may be forwarded throughout the XMPP
network. The content of these stanzas should not contain information requiring
sensitivity-based dissemination controls.

It is desirable to securely bind the security label to the object it labels. This may be
accomplished through use of digital signatures. Specification of such is left to a
future document.

If the protocol defined in this specification undergoes a revision that is not fully backwards-compatible with an older version, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of XEP-0053.

Kurt Zeilenga

Appendix C: Legal Notices

Copyright

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Appendix F: Requirements Conformance

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

8. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

9. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <https://xmpp.org/registrar/>.