summaryrefslogtreecommitdiff
path: root/Documentation/kdbus/kdbus.policy.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/kdbus/kdbus.policy.xml')
-rw-r--r--Documentation/kdbus/kdbus.policy.xml406
1 files changed, 406 insertions, 0 deletions
diff --git a/Documentation/kdbus/kdbus.policy.xml b/Documentation/kdbus/kdbus.policy.xml
new file mode 100644
index 000000000..673241638
--- /dev/null
+++ b/Documentation/kdbus/kdbus.policy.xml
@@ -0,0 +1,406 @@
+<?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>