.. include:: ../vars.rst

.. _chapter-data-tagging:

************
Data Tagging
************

Data tagging is the ability to add labels or tags to data. You can use data tags to add attributes to the exchanged data, thus providing applications and services with additional metadata. Data tags allow you to label the data produced by a specific |DW|, so matching |DRs| can use these labels to enrich the samples that come from that |DW|.

|CONNEXT| implements data tagging through the DATATAG QosPolicy (see :link_connext_dds_pro_um:`DATATAG QosPolicy in the Core Libraries User's Manual <#users_manual/DATATAG_Qos.htm>`). This policy allows you to associate a set of tags in the form of :value:`(name, value)` pairs with a |DW| or |DR|. As defined by the DDS Security specification, the |DW| data tag is implemented as an immutable DataWriterQos; the |DR| data tag is implemented as an immutable DataReaderQos. Therefore, this QoS policy cannot be modified after the |EP| has been created.

As a consequence of the above, the metadata for all samples from a |DW| is the same. Therefore, the tag is only exchanged in the |EP_disc| phase, instead of being sent with each sample. This approach allows for high performance and directly supports typical use cases where each application or |DP| writes data on a |TOPIC| with a common set of tags. For use cases where an application needs to add different metadata depending on some criteria, it can create multiple |DWs| with different tags, and use the appropriate |DW| depending on the metadata the application wants to associate with the sent samples.

The |AccessControlPlugin| can determine whether a |DP| has permission to publish or subscribe using certain tags. More concretely, you can grant |DPs| permission to publish or subscribe to specific |TOPICs| with specific data tags, as described in :ref:`p2_core/access_control:Data Tags`.


Example Use Case
================

Consider the example where a DDS application in an aircraft owned by American Airlines® sends information about its status to nearby airports. To identify the flight, each status update should contain the flight number. You can implement this behavior using data tags. Before the take-off of flight *AA1234*, you can set the data tag :xmlval:`(flightNo, AA1234)` for the |DW| publishing the :topic:`StatusUpdate` |TOPIC|. An attacker may want to set a different data tag -- for instance, using a different carrier prefix and number, like :xmlval:`(flightNo, AS4321)`. To avoid this scenario, the *Airlines Status Updates Consortium* should ensure that the |PermissionsDoc| for an aircraft only has permission to publish status updates for the flight numbers that they could potentially have. Hence, this American Airlines aircraft would have the following permissions:

.. code-block:: xml

  <allow_rule>
    <publish>
      <topics>
        <topic>StatusUpdate</topic>
      </topics>
      <data_tags>
        <tag>
          <name>flightNo</name>
          <value>AA*</value>
        </tag>
      </data_tags>
    </publish>
  </allow_rule>

If this aircraft tries to publish with a :xmlval:`flightNo` tag that does not start with :xmlval:`AA`, it will not be allowed to join the system. More generally, the |AccessControlPlugin| will ensure that |EPs| associated with a data tag can only communicate if they have permission to have that data tag.


Limitations
===========

Data tags permissions enforcement is not designed as a mechanism to provide data-based permissions, but as a mechanism to create rules around what metadata |DWs| and |DRs| can announce (as part of their discovery information).

In this sense, even if the |AccessControlPlugin| can grant a |DP| permission to create |DWs| and |DRs| with specific data tags, it cannot prevent that |DP| from publishing or subscribing to |TOPICs| without announcing any data tags. In other words, the |AccessControlPlugin| cannot enforce the presence of a certain tag. Therefore, if an entity does not present any data tags, it will be allowed in the system.

Using data tags as a mechanism to provide data-based permissions is not supported, nor defined in the current OMG DDS Security specification. Therefore, you can not deny |DWs| or |DRs| with no data tags from joining the system. For example, consider a grant containing the following :xmltag:`allow_rule` in a |PermissionsDoc|:

.. code-block:: xml

  <allow_rule>
    <publish>
      <topics>
        <topic>Square</topic>
      </topics>
      <data_tags>
        <tag>
          <name>Title</name>
          <value>Engineer</value>
        </tag>
      <data_tags>
    </publish>
  </allow_rule>

This grant will not prevent a malicious insider from creating a |DW| with no data tags and then publishing fake status updates on the |TOPIC| :topic:`Square`.

Note that you can read the announced data tags at the application level and make decisions based on that information (see :link_connext_dds_api_cpp:`on_subscription_matched <classDDSDataReaderListener.html#a6f83d0704634023dd8e1a66f83f3e022>` and :link_connext_dds_api_cpp:`on_publication_matched <classDDSDataWriterListener.html#ab7b1ca573cb1be49aeda49846cc20b8d>` callbacks). For example, you could decide to ignore a remote |DW| that has announced no data tags. However, bear in mind that the participant can still join the system before the application ignores it. Therefore it will have access to the symmetric keys associated with the |TOPIC|, retaining access to the data shared through the wire.

In conclusion, data tags permissions enforcement should only be used as a mechanism to limit what metadata a |DP| can announce. In order to restrict |DP| access to |TOPICs| based on a |DW|/|DR|-level categorization, |PARTITIONs| can be used instead.