diff options
Diffstat (limited to 'Documentation/kdbus/kdbus.policy.xml')
| -rw-r--r-- | Documentation/kdbus/kdbus.policy.xml | 406 |
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> |