path: root/Documentation/kdbus/kdbus.policy.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="kdbus.policy">

  <refentryinfo>
    <title>kdbus.policy</title>
    <productname>kdbus.policy</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>kdbus.policy</refentrytitle>
    <manvolnum>7</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>kdbus.policy</refname>
    <refpurpose>kdbus policy</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Description</title>

    <para>
      A kdbus policy restricts the possibilities of connections to own, see and
      talk to well-known names. A policy can be associated with a bus (through a
      policy holder connection) or a custom endpoint. kdbus stores its policy
      information in a database that can be accessed through the following
      ioctl commands:
    </para>

    <variablelist>
      <varlistentry>
        <term><constant>KDBUS_CMD_HELLO</constant></term>
        <listitem><para>
          When creating, or updating, a policy holder connection. See
          <citerefentry>
            <refentrytitle>kdbus.connection</refentrytitle>
            <manvolnum>7</manvolnum>
          </citerefentry>.
        </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><constant>KDBUS_CMD_ENDPOINT_MAKE</constant></term>
        <term><constant>KDBUS_CMD_ENDPOINT_UPDATE</constant></term>
        <listitem><para>
          When creating, or updating, a bus custom endpoint. See
          <citerefentry>
            <refentrytitle>kdbus.endpoint</refentrytitle>
            <manvolnum>7</manvolnum>
          </citerefentry>.
        </para></listitem>
      </varlistentry>
    </variablelist>

    <para>
      In all cases, the name and policy access information is stored in items
      of type <constant>KDBUS_ITEM_NAME</constant> and
      <constant>KDBUS_ITEM_POLICY_ACCESS</constant>. For this transport, the
      following rules apply.
    </para>

    <itemizedlist>
      <listitem>
        <para>
          An item of type <constant>KDBUS_ITEM_NAME</constant> must be followed
          by at least one <constant>KDBUS_ITEM_POLICY_ACCESS</constant> item.
        </para>
      </listitem>

      <listitem>
        <para>
          An item of type <constant>KDBUS_ITEM_NAME</constant> can be followed
          by an arbitrary number of
          <constant>KDBUS_ITEM_POLICY_ACCESS</constant> items.
        </para>
      </listitem>

      <listitem>
        <para>
          An arbitrary number of groups of names and access levels can be given.
        </para>
      </listitem>
    </itemizedlist>

    <para>
      Names passed in items of type <constant>KDBUS_ITEM_NAME</constant> must
      comply to the rules of valid kdbus.name. See
      <citerefentry>
        <refentrytitle>kdbus.name</refentrytitle>
        <manvolnum>7</manvolnum>
      </citerefentry>
      for more information.

      The payload of an item of type
      <constant>KDBUS_ITEM_POLICY_ACCESS</constant> is defined by the following
      struct. For more information on the layout of items, please refer to
      <citerefentry>
        <refentrytitle>kdbus.item</refentrytitle>
        <manvolnum>7</manvolnum>
      </citerefentry>.
    </para>

    <programlisting>
struct kdbus_policy_access {
  __u64 type;
  __u64 access;
  __u64 id;
};
    </programlisting>

    <para>The fields in this struct are described below.</para>

    <variablelist>
      <varlistentry>
        <term><varname>type</varname></term>
        <listitem>
          <para>
            One of the following.
          </para>

          <variablelist>
            <varlistentry>
              <term><constant>KDBUS_POLICY_ACCESS_USER</constant></term>
              <listitem><para>
                Grant access to a user with the UID stored in the
                <varname>id</varname> field.
              </para></listitem>
            </varlistentry>

            <varlistentry>
              <term><constant>KDBUS_POLICY_ACCESS_GROUP</constant></term>
              <listitem><para>
                Grant access to a user with the GID stored in the
                <varname>id</varname> field.
              </para></listitem>
            </varlistentry>

            <varlistentry>
              <term><constant>KDBUS_POLICY_ACCESS_WORLD</constant></term>
              <listitem><para>
                Grant access to everyone. The <varname>id</varname> field
                is ignored.
              </para></listitem>
            </varlistentry>
          </variablelist>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>access</varname></term>
        <listitem>
          <para>
            The access to grant. One of the following.
          </para>

          <variablelist>
            <varlistentry>
              <term><constant>KDBUS_POLICY_SEE</constant></term>
              <listitem><para>
                Allow the name to be seen.
              </para></listitem>
            </varlistentry>

            <varlistentry>
              <term><constant>KDBUS_POLICY_TALK</constant></term>
              <listitem><para>
                Allow the name to be talked to.
              </para></listitem>
            </varlistentry>

            <varlistentry>
              <term><constant>KDBUS_POLICY_OWN</constant></term>
              <listitem><para>
                Allow the name to be owned.
              </para></listitem>
            </varlistentry>
          </variablelist>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>id</varname></term>
        <listitem><para>
           For <constant>KDBUS_POLICY_ACCESS_USER</constant>, stores the UID.
           For <constant>KDBUS_POLICY_ACCESS_GROUP</constant>, stores the GID.
        </para></listitem>
      </varlistentry>

    </variablelist>

    <para>
      All endpoints of buses have an empty policy database by default.
      Therefore, unless policy rules are added, all operations will also be
      denied by default. Also see
      <citerefentry>
        <refentrytitle>kdbus.endpoint</refentrytitle>
        <manvolnum>7</manvolnum>
      </citerefentry>.
    </para>
  </refsect1>

  <refsect1>
    <title>Wildcard names</title>
    <para>
      Policy holder connections may upload names that contain the wildcard
      suffix (<literal>".*"</literal>). Such a policy entry is effective for
      every well-known name that extends the provided name by exactly one more
      level.

      For example, the name <literal>foo.bar.*</literal> matches both
      <literal>"foo.bar.baz"</literal> and
      <literal>"foo.bar.bazbaz"</literal> are, but not
      <literal>"foo.bar.baz.baz"</literal>.

      This allows connections to take control over multiple names that the
      policy holder doesn't need to know about when uploading the policy.

      Such wildcard entries are not allowed for custom endpoints.
    </para>
  </refsect1>

  <refsect1>
    <title>Privileged connections</title>
    <para>
      The policy database is overruled when action is taken by a privileged
      connection. Please refer to
      <citerefentry>
        <refentrytitle>kdbus.connection</refentrytitle>
        <manvolnum>7</manvolnum>
      </citerefentry>
      for more information on what makes a connection privileged.
    </para>
  </refsect1>

  <refsect1>
    <title>Examples</title>
    <para>
      For instance, a set of policy rules may look like this:
    </para>

    <programlisting>
KDBUS_ITEM_NAME: str='org.foo.bar'
KDBUS_ITEM_POLICY_ACCESS: type=USER, access=OWN, ID=1000
KDBUS_ITEM_POLICY_ACCESS: type=USER, access=TALK, ID=1001
KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=SEE

KDBUS_ITEM_NAME: str='org.blah.baz'
KDBUS_ITEM_POLICY_ACCESS: type=USER, access=OWN, ID=0
KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=TALK
    </programlisting>

    <para>
      That means that 'org.foo.bar' may only be owned by UID 1000, but every
      user on the bus is allowed to see the name. However, only UID 1001 may
      actually send a message to the connection and receive a reply from it.

      The second rule allows 'org.blah.baz' to be owned by UID 0 only, but
      every user may talk to it.
    </para>
  </refsect1>

  <refsect1>
    <title>TALK access and multiple well-known names per connection</title>
    <para>
      Note that TALK access is checked against all names of a connection. For
      example, if a connection owns both <constant>'org.foo.bar'</constant> and
      <constant>'org.blah.baz'</constant>, and the policy database allows
      <constant>'org.blah.baz'</constant> to be talked to by WORLD, then this
      permission is also granted to <constant>'org.foo.bar'</constant>. That
      might sound illogical, but after all, we allow messages to be directed to
      either the ID or a well-known name, and policy is applied to the
      connection, not the name. In other words, the effective TALK policy for a
      connection is the most permissive of all names the connection owns.

      For broadcast messages, the receiver needs TALK permissions to the sender
      to receive the broadcast.
    </para>
    <para>
      Both the endpoint and the bus policy databases are consulted to allow
      name registry listing, owning a well-known name and message delivery.
      If either one fails, the operation is failed with
      <varname>errno</varname> set to <constant>EPERM</constant>.

      For best practices, connections that own names with a restricted TALK
      access should not install matches. This avoids cases where the sent
      message may pass the bloom filter due to false-positives and may also
      satisfy the policy rules.

      Also see
      <citerefentry>
        <refentrytitle>kdbus.match</refentrytitle>
        <manvolnum>7</manvolnum>
      </citerefentry>.
    </para>
  </refsect1>

  <refsect1>
    <title>Implicit policies</title>
    <para>
      Depending on the type of the endpoint, a set of implicit rules that
      override installed policies might be enforced.

      On default endpoints, the following set is enforced and checked before
      any user-supplied policy is checked.
    </para>

    <itemizedlist>
      <listitem>
        <para>
          Privileged connections always override any installed policy. Those
          connections could easily install their own policies, so there is no
          reason to enforce installed policies.
        </para>
      </listitem>
      <listitem>
        <para>
          Connections can always talk to connections of the same user. This
          includes broadcast messages.
        </para>
      </listitem>
    </itemizedlist>

    <para>
      Custom endpoints have stricter policies. The following rules apply:
    </para>

    <itemizedlist>
      <listitem>
        <para>
          Policy rules are always enforced, even if the connection is a
          privileged connection.
        </para>
      </listitem>
      <listitem>
        <para>
          Policy rules are always enforced for <constant>TALK</constant> access,
          even if both ends are running under the same user. This includes
          broadcast messages.
        </para>
      </listitem>
      <listitem>
        <para>
          To restrict the set of names that can be seen, endpoint policies can
          install <constant>SEE</constant> policies.
        </para>
      </listitem>
    </itemizedlist>
  </refsect1>

  <refsect1>
    <title>See Also</title>
    <simplelist type="inline">
      <member>
        <citerefentry>
          <refentrytitle>kdbus</refentrytitle>
          <manvolnum>7</manvolnum>
        </citerefentry>
      </member>
      <member>
        <citerefentry>
          <refentrytitle>kdbus.bus</refentrytitle>
          <manvolnum>7</manvolnum>
        </citerefentry>
      </member>
      <member>
        <citerefentry>
          <refentrytitle>kdbus.endpoint</refentrytitle>
          <manvolnum>7</manvolnum>
        </citerefentry>
      </member>
      <member>
        <citerefentry>
          <refentrytitle>kdbus.fs</refentrytitle>
          <manvolnum>7</manvolnum>
        </citerefentry>
      </member>
      <member>
        <citerefentry>
          <refentrytitle>kdbus.item</refentrytitle>
          <manvolnum>7</manvolnum>
        </citerefentry>
      </member>
      <member>
        <citerefentry>
          <refentrytitle>kdbus.message</refentrytitle>
          <manvolnum>7</manvolnum>
        </citerefentry>
      </member>
      <member>
        <citerefentry>
          <refentrytitle>kdbus.name</refentrytitle>
          <manvolnum>7</manvolnum>
        </citerefentry>
      </member>
      <member>
        <citerefentry>
          <refentrytitle>kdbus.pool</refentrytitle>
          <manvolnum>7</manvolnum>
        </citerefentry>
      </member>
    </simplelist>
  </refsect1>
</refentry>