[apparmor] [PATCH 1/4 v2] parser: Update man page for DBus rules

[Tyler Hicks]

Document the DBus rule syntax and provide several examples.

Signed-off-by: Tyler Hicks <tyhicks at canonical.com>
---

Thanks for the review, Seth! I've addressed your comments, along with a couple
other things that I spotted while making those changes.

* Changes in v2:
  - Adjust the last DBus example
    + Show an example of peer=(name=(N1|N2))
    + Shorten the example path from /com/example/sample/object/name to
      /com/example/path
    + Convert it from a (send, receive) rule to a send rule, since both send
      and receive permissions are a bit ambiguous when specifying so many
      conditionals. Conditionalized send rules should be tailored to the
      *peer's* path, interface, and members. Conditionalized receive rules are
      tailored to the *subject's* path, interface, and members.
  - Add a bind example
  - Add a receive example
  - Fix "permission" -> "permissions" typo

 parser/apparmor.d.pod | 84 +++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 82 insertions(+), 2 deletions(-)

diff --git a/parser/apparmor.d.pod b/parser/apparmor.d.pod
index 046c47c..17e0ed4 100644
--- a/parser/apparmor.d.pod
+++ b/parser/apparmor.d.pod
@@ -3,7 +3,7 @@
 #                  2008, 2009
 #    NOVELL (All rights reserved)
 #
-#    Copyright (c) 2010 - 2012
+#    Copyright (c) 2010 - 2013
 #    Canonical Ltd. (All rights reserved)
 #
 #    This program is free software; you can redistribute it and/or
@@ -54,7 +54,7 @@ B<COMMENT> = '#' I<TEXT>
 
 B<TEXT> = any characters
 
-B<PROFILE> = [ I<COMMENT> ... ] [ I<VARIABLE ASSIGNMENT> ... ] ( '"' I<PROGRAM> '"' | I<PROGRAM> ) [ 'flags=(complain)' ]'{' [ ( I<RESOURCE RULE> | I<COMMENT> | I<INCLUDE> | I<SUBPROFILE> | 'capability ' I<CAPABILITY> | I<NETWORK RULE> | I<MOUNT RULE> | I<FILE RULE> | 'change_profile -> ' I<PROGRAMCHILD> ) ... ] '}'
+B<PROFILE> = [ I<COMMENT> ... ] [ I<VARIABLE ASSIGNMENT> ... ] ( '"' I<PROGRAM> '"' | I<PROGRAM> ) [ 'flags=(complain)' ]'{' [ ( I<RESOURCE RULE> | I<COMMENT> | I<INCLUDE> | I<SUBPROFILE> | 'capability ' I<CAPABILITY> | I<NETWORK RULE> | I<MOUNT RULE> | I<DBUS RULE> | I<FILE RULE> | 'change_profile -> ' I<PROGRAMCHILD> ) ... ] '}'
 
 B<SUBPROFILE> = [ I<COMMENT> ... ] ( I<PROGRAMHAT> | 'profile ' I<PROGRAMCHILD> ) '{' [ ( I<FILE RULE> | I<COMMENT> | I<INCLUDE> ) ... ] '}'
 
@@ -99,6 +99,34 @@ B<MOUNT FLAGS> = ( 'ro' | 'rw' | 'nosuid' | 'suid' | 'nodev' | 'dev' | 'noexec'
 
 B<MOUNT EXPRESSION> = ( I<ALPHANUMERIC> | I<AARE> ) ...
 
+B<DBUS RULE> = ( I<DBUS MESSAGE RULE> | I<DBUS SERVICE RULE> | I<DBUS COMBINED RULE> )
+
+B<DBUS MESSAGE RULE> = [ 'audit' ] [ 'deny' ] 'dbus' [ I<DBUS ACCESS EXPRESSION> ] [ I<DBUS BUS> ] [ I<DBUS PATH> ] [ I<DBUS INTERFACE> ] [ I<DBUS MEMBER> ] [ I<DBUS PEER> ]
+
+B<DBUS SERVICE RULE> = [ 'audit' ] [ 'deny' ] 'dbus' [ I<DBUS ACCESS EXPRESSION> ] [ I<DBUS BUS> ] [ I<DBUS NAME> ]
+
+B<DBUS COMBINED RULE> = [ 'audit' ] [ 'deny' ] 'dbus' [ I<DBUS ACCESS EXPRESSION> ] [ I<DBUS BUS> ]
+
+B<DBUS ACCESS EXPRESSION> = ( I<DBUS ACCESS> | '(' I<DBUS ACCESS LIST> ')' )
+
+B<DBUS BUS> = 'bus' '=' '(' 'system' | 'session' | '"' I<AARE> '"' | I<AARE> ')'
+
+B<DBUS PATH> = 'path' '=' '(' '"' I<AARE> '"' | I<AARE> ')'
+
+B<DBUS INTERFACE> = 'interface' '=' '(' '"' I<AARE> '"' | I<AARE> ')'
+
+B<DBUS MEMBER> = 'member' '=' '(' '"' I<AARE> '"' | I<AARE> ')'
+
+B<DBUS PEER> = 'peer' '=' '(' [ I<DBUS NAME> ] [ I<DBUS LABEL> ] ')'
+
+B<DBUS NAME> = 'name' '=' '(' '"' I<AARE> '"' | I<AARE> ')'
+
+B<DBUS LABEL> = 'label' '=' '(' '"' I<AARE> '"' | I<AARE> ')'
+
+B<DBUS ACCESS LIST> = Comma separated list of I<DBUS ACCESS>
+
+B<DBUS ACCESS> = ( 'send' | 'receive' | 'bind' )  (some accesses are incompatible with some rules; see below.)
+
 B<AARE> = B<?*[]{}^> (see below for meanings)
 
 B<FILE RULE> = I<RULE QUALIFIER> ( '"' I<FILEGLOB> '"' | I<FILEGLOB> ) I<ACCESS> ','
@@ -625,6 +653,58 @@ $ mount -o nodev,user /dev/foo /mnt
 
 =back
 
+=head2 DBus rules
+
+AppArmor supports DBus mediation. The mediation is performed in conjunction
+with the DBus daemon. The DBus daemon verifies that communications over the
+bus are permitted by AppArmor policy.
+
+AppArmor DBus rules are accumulated so that the granted DBus permissions are
+the union of all the listed DBus rule permissions.
+
+AppArmor DBus rules are broad and general and become more restrictive as
+further information is specified. Policy may be specified down to the interface
+member level (method or signal name), however the contents of messages are not
+examined.
+
+Some AppArmor DBus permissions are not compatible with all AppArmor DBus rules.
+The 'bind' permission cannot be used in message rules. The 'send' and 'receive'
+permissions cannot be used in service rules.
+
+AppArmor DBus permissions are implied when a rule does not explicitly state an
+access list. By default, all DBus permissions are implied. Only message
+permissions are implied for message rules and only service permissions are
+implied for service rules.
+
+Example AppArmor DBus rules:
+
+    # Allow all DBus access
+    dbus,
+
+    # Explicitly allow all DBus access,
+    dbus (send, receive, bind),
+
+    # Deny send/receive/bind access to the session bus
+    deny dbus bus=session,
+
+    # Allow bind access for a particular name on any bus
+    dbus bind name=com.example.ExampleName,
+
+    # Allow receive access for a particular path and interface
+    dbus receive path=/com/example/path interface=com.example.Interface,
+
+    # Deny send/receive access to the system bus for a particular interface
+    deny dbus bus=system interface=com.example.ExampleInterface,
+
+    # Allow send access for a particular path, interface, member, and pair of
+    # peer names:
+    dbus send
+         bus=session
+         path=/com/example/path
+         interface=com.example.Interface
+         member=ExampleMethod
+         peer=(name=(com.example.ExampleName1|com.example.ExampleName2)),
+
 =head2 Variables
 
 AppArmor's policy language allows embedding variables into file rules
-- 
1.8.3.2