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