From cd10a3fd64b60d76d04809b49a61bd1cfd394532 Mon Sep 17 00:00:00 2001 From: Daniel Mack Date: Mon, 26 Jan 2015 21:40:39 +0100 Subject: [PATCH] doc: add kdbus.policy.7 Signed-off-by: Daniel Mack --- doc/Makefile | 1 + doc/kdbus.message.xml | 6 +- doc/kdbus.policy.xml | 341 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 345 insertions(+), 3 deletions(-) create mode 100644 doc/kdbus.policy.xml diff --git a/doc/Makefile b/doc/Makefile index 3f14c72..324988d 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -7,6 +7,7 @@ docs= \ kdbus.item.xml \ kdbus.message.xml \ kdbus.names.xml \ + kdbus.policy.xml \ kdbus.pool.xml manpages=$(docs:.xml=.7) diff --git a/doc/kdbus.message.xml b/doc/kdbus.message.xml index 9c529a4..039599f 100644 --- a/doc/kdbus.message.xml +++ b/doc/kdbus.message.xml @@ -694,9 +694,9 @@ struct kdbus_msg_info { - kdbus_msg.src_id == KDBUS_SRC_ID_KERNEL - kdbus_msg.dst_id == KDBUS_DST_ID_BROADCAST - kdbus_msg.payload_type == KDBUS_PAYLOAD_KERNEL + kdbus_msg.src_id == KDBUS_SRC_ID_KERNEL + kdbus_msg.dst_id == KDBUS_DST_ID_BROADCAST + kdbus_msg.payload_type == KDBUS_PAYLOAD_KERNEL Has exactly one of the aforementioned items attached diff --git a/doc/kdbus.policy.xml b/doc/kdbus.policy.xml new file mode 100644 index 0000000..0e9f14e --- /dev/null +++ b/doc/kdbus.policy.xml @@ -0,0 +1,341 @@ + + + + + + + kdbus.policy + kdbus.policy + + + + kdbus.policy + 7 + + + + kdbus.policy + kdbus policy + + + + Description + + + 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: + + + + + KDBUS_CMD_HELLO + + When creating, or updating, a policy holder connection. See + kdbus.connection7. + + + + + KDBUS_CMD_ENDPOINT_MAKE + KDBUS_CMD_ENDPOINT_UPDATE + + When creating, or updating, a bus custom endpoint. See + kdbus.endpoint7. + + + + + + In all cases, the name and policy access information is stored in items + of type KDBUS_ITEM_NAME and + KDBUS_ITEM_POLICY_ACCESS. For this transport, the + following rules apply. + + + + + + An item of type KDBUS_ITEM_NAME must be followed + by at least one KDBUS_ITEM_POLICY_ACCESS item. + + + + + + An item of type KDBUS_ITEM_NAME can be followed + by an arbitrary number of KDBUS_ITEM_POLICY_ACCESS + items. + + + + + + An arbitrary number of groups of names and access levels can be given. + + + + + + Names passed in items of type KDBUS_ITEM_NAME must + comply to the rules of valid kdbus names. See + kdbus.names7 + for more information. + + The payload of an item of type KDBUS_ITEM_POLICY_ACCESS + is defined by the following struct. For more information on the layout + of items, please refer to + kdbus.item7. + + + +struct kdbus_policy_access { + __u64 type; + __u64 access; + __u64 id; +}; + + + The fields in this struct are described below. + + + + type + + + One of the following. + + + + + KDBUS_POLICY_ACCESS_USER + + Grant access to a user with the UID stored in the + id field. + + + + + KDBUS_POLICY_ACCESS_GROUP + + Grant access to a user with the GID stored in the + id field. + + + + + KDBUS_POLICY_ACCESS_WORLD + + Grant access to everyone. The id field + is ignored. + + + + + + + + access + + + The access to grant. One of the following. + + + + + KDBUS_POLICY_SEE + + Allow the name to be seen. + + + + + KDBUS_POLICY_TALK + + Allow the name to be talked to. + + + + + KDBUS_POLICY_OWN + + Allow the name to be owned. + + + + + + + + id + + For KDBUS_POLICY_ACCESS_USER, stores the UID. + For KDBUS_POLICY_ACCESS_GROUP, stores the GID. + + + + + + + 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 + kdbus.endpoint7. + + + + + Wildcard names + + Policy holder connections may upload names that contain the wildcard suffix + (".*"). 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 "foo.bar.*" matches both "foo.bar.baz" and + "foo.bar.bazbaz" are, but not "foo.bar.baz.baz". + + 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. + + + + + Privileged connections + + The policy database is overruled when action is taken by a privileged + connection. Please refer to + kdbus.connection7 + for more information on what makes a connection privileged. + + + + + Examples + + For instance, a set of policy rules may look like this: + + + +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 + + + + 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. + + + + + TALK access and multiple well-known names per connection + + Note that TALK access is checked against all names of a connection. + For example, if a connection owns both 'org.foo.bar' and 'org.blah.baz', and + the policy database allows 'org.blah.baz' to be talked to by WORLD, then this + permission is also granted to 'org.foo.bar'. 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. + + + 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 + -EPERM. + + 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 + kdbus.match7. + + + + + Implicit policies + + 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. + + + + + + Privileged connections always override any installed policy. Those + connections could easily install their own policies, so there is no + reason to enforce installed policies. + + + + + Connections can always talk to connections of the same user. This + includes broadcast messages. + + + + + + Custom endpoints have stricter policies. The following rules apply: + + + + + + Policy rules are always enforced, even if the connection is a privileged + connection. + + + + + Policy rules are always enforced for TALK access, + even if both ends are running under the same user. This includes + broadcast messages. + + + + + To restrict the set of names that can be seen, endpoint policies can + install SEE policies. + + + + + + + See Also + + kdbus7 + kdbus.bus7 + kdbus.endpoint7 + kdbus.fs7 + kdbus.item7 + kdbus.message7 + kdbus.names7 + kdbus.pool7 + + + -- 2.34.1