ipc/kdbus/Documentation/kdbus.policy.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <refentry id="kdbus.policy">
   6
   7   <refentryinfo>
   8     <title>kdbus.policy</title>
   9     <productname>kdbus.policy</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>kdbus.policy</refentrytitle>
  14     <manvolnum>7</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>kdbus.policy</refname>
  19     <refpurpose>kdbus policy</refpurpose>
  20   </refnamediv>
  21
  22   <refsect1>
  23     <title>Description</title>
  24
  25     <para>
  26       A kdbus policy restricts the possibilities of connections to own, see and
  27       talk to well-known names. A policy can be associated with a bus (through a
  28       policy holder connection) or a custom endpoint. kdbus stores its policy
  29       information in a database that can be accessed through the following
  30       ioctl commands:
  31     </para>
  32
  33     <variablelist>
  34       <varlistentry>
  35         <term><constant>KDBUS_CMD_HELLO</constant></term>
  36         <listitem><para>
  37           When creating, or updating, a policy holder connection. See
  38           <citerefentry>
  39             <refentrytitle>kdbus.connection</refentrytitle>
  40             <manvolnum>7</manvolnum>
  41           </citerefentry>.
  42         </para></listitem>
  43       </varlistentry>
  44
  45       <varlistentry>
  46         <term><constant>KDBUS_CMD_ENDPOINT_MAKE</constant></term>
  47         <term><constant>KDBUS_CMD_ENDPOINT_UPDATE</constant></term>
  48         <listitem><para>
  49           When creating, or updating, a bus custom endpoint. See
  50           <citerefentry>
  51             <refentrytitle>kdbus.endpoint</refentrytitle>
  52             <manvolnum>7</manvolnum>
  53           </citerefentry>.
  54         </para></listitem>
  55       </varlistentry>
  56     </variablelist>
  57
  58     <para>
  59       In all cases, the name and policy access information is stored in items
  60       of type <constant>KDBUS_ITEM_NAME</constant> and
  61       <constant>KDBUS_ITEM_POLICY_ACCESS</constant>. For this transport, the
  62       following rules apply.
  63     </para>
  64
  65     <itemizedlist>
  66       <listitem>
  67         <para>
  68           An item of type <constant>KDBUS_ITEM_NAME</constant> must be followed
  69           by at least one <constant>KDBUS_ITEM_POLICY_ACCESS</constant> item.
  70         </para>
  71       </listitem>
  72
  73       <listitem>
  74         <para>
  75           An item of type <constant>KDBUS_ITEM_NAME</constant> can be followed
  76           by an arbitrary number of
  77           <constant>KDBUS_ITEM_POLICY_ACCESS</constant> items.
  78         </para>
  79       </listitem>
  80
  81       <listitem>
  82         <para>
  83           An arbitrary number of groups of names and access levels can be given.
  84         </para>
  85       </listitem>
  86     </itemizedlist>
  87
  88     <para>
  89       Names passed in items of type <constant>KDBUS_ITEM_NAME</constant> must
  90       comply to the rules of valid kdbus.name. See
  91       <citerefentry>
  92         <refentrytitle>kdbus.name</refentrytitle>
  93         <manvolnum>7</manvolnum>
  94       </citerefentry>
  95       for more information.
  96
  97       The payload of an item of type
  98       <constant>KDBUS_ITEM_POLICY_ACCESS</constant> is defined by the following
  99       struct. For more information on the layout of items, please refer to
 100       <citerefentry>
 101         <refentrytitle>kdbus.item</refentrytitle>
 102         <manvolnum>7</manvolnum>
 103       </citerefentry>.
 104     </para>
 105
 106     <programlisting>
 107 struct kdbus_policy_access {
 108   __u64 type;
 109   __u64 access;
 110   __u64 id;
 111 };
 112     </programlisting>
 113
 114     <para>The fields in this struct are described below.</para>
 115
 116     <variablelist>
 117       <varlistentry>
 118         <term><varname>type</varname></term>
 119         <listitem>
 120           <para>
 121             One of the following.
 122           </para>
 123
 124           <variablelist>
 125             <varlistentry>
 126               <term><constant>KDBUS_POLICY_ACCESS_USER</constant></term>
 127               <listitem><para>
 128                 Grant access to a user with the UID stored in the
 129                 <varname>id</varname> field.
 130               </para></listitem>
 131             </varlistentry>
 132
 133             <varlistentry>
 134               <term><constant>KDBUS_POLICY_ACCESS_GROUP</constant></term>
 135               <listitem><para>
 136                 Grant access to a user with the GID stored in the
 137                 <varname>id</varname> field.
 138               </para></listitem>
 139             </varlistentry>
 140
 141             <varlistentry>
 142               <term><constant>KDBUS_POLICY_ACCESS_WORLD</constant></term>
 143               <listitem><para>
 144                 Grant access to everyone. The <varname>id</varname> field
 145                 is ignored.
 146               </para></listitem>
 147             </varlistentry>
 148           </variablelist>
 149         </listitem>
 150       </varlistentry>
 151
 152       <varlistentry>
 153         <term><varname>access</varname></term>
 154         <listitem>
 155           <para>
 156             The access to grant. One of the following.
 157           </para>
 158
 159           <variablelist>
 160             <varlistentry>
 161               <term><constant>KDBUS_POLICY_SEE</constant></term>
 162               <listitem><para>
 163                 Allow the name to be seen.
 164               </para></listitem>
 165             </varlistentry>
 166
 167             <varlistentry>
 168               <term><constant>KDBUS_POLICY_TALK</constant></term>
 169               <listitem><para>
 170                 Allow the name to be talked to.
 171               </para></listitem>
 172             </varlistentry>
 173
 174             <varlistentry>
 175               <term><constant>KDBUS_POLICY_OWN</constant></term>
 176               <listitem><para>
 177                 Allow the name to be owned.
 178               </para></listitem>
 179             </varlistentry>
 180           </variablelist>
 181         </listitem>
 182       </varlistentry>
 183
 184       <varlistentry>
 185         <term><varname>id</varname></term>
 186         <listitem><para>
 187            For <constant>KDBUS_POLICY_ACCESS_USER</constant>, stores the UID.
 188            For <constant>KDBUS_POLICY_ACCESS_GROUP</constant>, stores the GID.
 189         </para></listitem>
 190       </varlistentry>
 191
 192     </variablelist>
 193
 194     <para>
 195       All endpoints of buses have an empty policy database by default.
 196       Therefore, unless policy rules are added, all operations will also be
 197       denied by default. Also see
 198       <citerefentry>
 199         <refentrytitle>kdbus.endpoint</refentrytitle>
 200         <manvolnum>7</manvolnum>
 201       </citerefentry>.
 202     </para>
 203   </refsect1>
 204
 205   <refsect1>
 206     <title>Wildcard names</title>
 207     <para>
 208       Policy holder connections may upload names that contain the wildcard
 209       suffix (<literal>".*"</literal>). Such a policy entry is effective for
 210       every well-known name that extends the provided name by exactly one more
 211       level.
 212
 213       For example, the name <literal>foo.bar.*</literal> matches both
 214       <literal>"foo.bar.baz"</literal> and
 215       <literal>"foo.bar.bazbaz"</literal> are, but not
 216       <literal>"foo.bar.baz.baz"</literal>.
 217
 218       This allows connections to take control over multiple names that the
 219       policy holder doesn't need to know about when uploading the policy.
 220
 221       Such wildcard entries are not allowed for custom endpoints.
 222     </para>
 223   </refsect1>
 224
 225   <refsect1>
 226     <title>Privileged connections</title>
 227     <para>
 228       The policy database is overruled when action is taken by a privileged
 229       connection. Please refer to
 230       <citerefentry>
 231         <refentrytitle>kdbus.connection</refentrytitle>
 232         <manvolnum>7</manvolnum>
 233       </citerefentry>
 234       for more information on what makes a connection privileged.
 235     </para>
 236   </refsect1>
 237
 238   <refsect1>
 239     <title>Examples</title>
 240     <para>
 241       For instance, a set of policy rules may look like this:
 242     </para>
 243
 244     <programlisting>
 245 KDBUS_ITEM_NAME: str='org.foo.bar'
 246 KDBUS_ITEM_POLICY_ACCESS: type=USER, access=OWN, ID=1000
 247 KDBUS_ITEM_POLICY_ACCESS: type=USER, access=TALK, ID=1001
 248 KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=SEE
 249
 250 KDBUS_ITEM_NAME: str='org.blah.baz'
 251 KDBUS_ITEM_POLICY_ACCESS: type=USER, access=OWN, ID=0
 252 KDBUS_ITEM_POLICY_ACCESS: type=WORLD, access=TALK
 253     </programlisting>
 254
 255     <para>
 256       That means that 'org.foo.bar' may only be owned by UID 1000, but every
 257       user on the bus is allowed to see the name. However, only UID 1001 may
 258       actually send a message to the connection and receive a reply from it.
 259
 260       The second rule allows 'org.blah.baz' to be owned by UID 0 only, but
 261       every user may talk to it.
 262     </para>
 263   </refsect1>
 264
 265   <refsect1>
 266     <title>TALK access and multiple well-known names per connection</title>
 267     <para>
 268       Note that TALK access is checked against all names of a connection. For
 269       example, if a connection owns both <constant>'org.foo.bar'</constant> and
 270       <constant>'org.blah.baz'</constant>, and the policy database allows
 271       <constant>'org.blah.baz'</constant> to be talked to by WORLD, then this
 272       permission is also granted to <constant>'org.foo.bar'</constant>. That
 273       might sound illogical, but after all, we allow messages to be directed to
 274       either the ID or a well-known name, and policy is applied to the
 275       connection, not the name. In other words, the effective TALK policy for a
 276       connection is the most permissive of all names the connection owns.
 277
 278       For broadcast messages, the receiver needs TALK permissions to the sender
 279       to receive the broadcast.
 280     </para>
 281     <para>
 282       Both the endpoint and the bus policy databases are consulted to allow
 283       name registry listing, owning a well-known name and message delivery.
 284       If either one fails, the operation is failed with
 285       <varname>errno</varname> set to <constant>EPERM</constant>.
 286
 287       For best practices, connections that own names with a restricted TALK
 288       access should not install matches. This avoids cases where the sent
 289       message may pass the bloom filter due to false-positives and may also
 290       satisfy the policy rules.
 291
 292       Also see
 293       <citerefentry>
 294         <refentrytitle>kdbus.match</refentrytitle>
 295         <manvolnum>7</manvolnum>
 296       </citerefentry>.
 297     </para>
 298   </refsect1>
 299
 300   <refsect1>
 301     <title>Implicit policies</title>
 302     <para>
 303       Depending on the type of the endpoint, a set of implicit rules that
 304       override installed policies might be enforced.
 305
 306       On default endpoints, the following set is enforced and checked before
 307       any user-supplied policy is checked.
 308     </para>
 309
 310     <itemizedlist>
 311       <listitem>
 312         <para>
 313           Privileged connections always override any installed policy. Those
 314           connections could easily install their own policies, so there is no
 315           reason to enforce installed policies.
 316         </para>
 317       </listitem>
 318       <listitem>
 319         <para>
 320           Connections can always talk to connections of the same user. This
 321           includes broadcast messages.
 322         </para>
 323       </listitem>
 324     </itemizedlist>
 325
 326     <para>
 327       Custom endpoints have stricter policies. The following rules apply:
 328     </para>
 329
 330     <itemizedlist>
 331       <listitem>
 332         <para>
 333           Policy rules are always enforced, even if the connection is a
 334           privileged connection.
 335         </para>
 336       </listitem>
 337       <listitem>
 338         <para>
 339           Policy rules are always enforced for <constant>TALK</constant> access,
 340           even if both ends are running under the same user. This includes
 341           broadcast messages.
 342         </para>
 343       </listitem>
 344       <listitem>
 345         <para>
 346           To restrict the set of names that can be seen, endpoint policies can
 347           install <constant>SEE</constant> policies.
 348         </para>
 349       </listitem>
 350     </itemizedlist>
 351   </refsect1>
 352
 353   <refsect1>
 354     <title>See Also</title>
 355     <simplelist type="inline">
 356       <member>
 357         <citerefentry>
 358           <refentrytitle>kdbus</refentrytitle>
 359           <manvolnum>7</manvolnum>
 360         </citerefentry>
 361       </member>
 362       <member>
 363         <citerefentry>
 364           <refentrytitle>kdbus.bus</refentrytitle>
 365           <manvolnum>7</manvolnum>
 366         </citerefentry>
 367       </member>
 368       <member>
 369         <citerefentry>
 370           <refentrytitle>kdbus.endpoint</refentrytitle>
 371           <manvolnum>7</manvolnum>
 372         </citerefentry>
 373       </member>
 374       <member>
 375         <citerefentry>
 376           <refentrytitle>kdbus.fs</refentrytitle>
 377           <manvolnum>7</manvolnum>
 378         </citerefentry>
 379       </member>
 380       <member>
 381         <citerefentry>
 382           <refentrytitle>kdbus.item</refentrytitle>
 383           <manvolnum>7</manvolnum>
 384         </citerefentry>
 385       </member>
 386       <member>
 387         <citerefentry>
 388           <refentrytitle>kdbus.message</refentrytitle>
 389           <manvolnum>7</manvolnum>
 390         </citerefentry>
 391       </member>
 392       <member>
 393         <citerefentry>
 394           <refentrytitle>kdbus.name</refentrytitle>
 395           <manvolnum>7</manvolnum>
 396         </citerefentry>
 397       </member>
 398       <member>
 399         <citerefentry>
 400           <refentrytitle>kdbus.pool</refentrytitle>
 401           <manvolnum>7</manvolnum>
 402         </citerefentry>
 403       </member>
 404     </simplelist>
 405   </refsect1>
 406 </refentry>