2003-03-18 Havoc Pennington <hp@redhat.com>

	* doc/TODO: some notes on high-level todo items. Little nitpick
	stuff is all in @todo, so no need to add it here.

	* doc/config-file.txt: some notes on how config file might look

3 files changed, 202 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index d4747dd0..242af3d5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2003-03-18  Havoc Pennington  <hp@redhat.com>
+
+	* doc/TODO: some notes on high-level todo items. Little nitpick
+	stuff is all in @todo, so no need to add it here.
+
+	* doc/config-file.txt: some notes on how config file might look
+
 2003-03-18  Anders Carlsson  <andersca@codefactory.se>
 
 	* configure.in: 0.6
diff --git a/doc/TODO b/doc/TODO
new file mode 100644
index 00000000..dffb7389
--- /dev/null
+++ b/doc/TODO
@@ -0,0 +1,41 @@
+
+ - Service and message names should be more carefully restricted;
+   they should have a max length, may not be an empty string, 
+   and perhaps should not be allowed to be a glob such as "*" since
+   the config file could conveniently use such notation. 
+
+   Suggest requiring length > 0, length < max, 
+   name contains at least one ".", no initial ".", and valid UTF-8. 
+   That would prohibit plain "*" but not "foo.bar.baz.operator*"
+
+   For maximum convenience from all programming languages, we could go
+   further and just categorically ban nearly all non-alphanumeric
+   characters.
+
+ - Message matching rules (so broadcasts can be filtered) need sorting
+   out.
+
+ - How we will handle DCOP needs sorting out. Among other things, we
+   need to check that service and service-ownership semantics map to DCOP 
+   reasonably well.
+
+ - Activation needs some careful additional thinking-through.
+
+ - Recursive/composite/etc. types and associated API, see mailing list.
+
+ - dbus-bus.h should contain convenience API for connecting to system 
+   and login-session message buses (automatically handling env
+   variables etc.)
+
+ - Configuration file (working on that now)
+
+ - Property list feature on message bus (list of properties associated 
+   with a connection). May also include message matching rules 
+   that involve the properties of the source or destination
+   connection.
+
+ - Implement all the needed resource limits to keep clients from
+   killing the message bus.
+
+
+
diff --git a/doc/config-file.txt b/doc/config-file.txt
new file mode 100644
index 00000000..c78a65b7
--- /dev/null
+++ b/doc/config-file.txt
@@ -0,0 +1,154 @@
+
+D-BUS message bus daemon configuration
+===
+
+The message bus daemon has a configuration file that specializes it
+for a particular application. For example, one configuration 
+file might set up the message bus to be a systemwide message bus, 
+while another might set it up to be a per-user login session bus.
+
+The configuration file also establishes resource limits, security
+parameters, and so forth.
+
+The configuration file is not part of any interoperability
+specification and its backward compatibility is not guaranteed; this
+document is documentation, not specification.
+
+A DTD should be written here eventually, but for now I suck.
+
+Doctype declaration:
+
+   <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
+    "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
+
+Elements:
+
+ <busconfig>
+ 
+    Root element.
+
+ <include>
+  ignore_missing="(yes|no)"   optional attribute, defaults to no
+   
+    Include a file <include>filename.conf</include> at this point.
+
+ <user>
+
+    The user account the daemon should run as, as either a username or
+    a UID. If the daemon doesn't have and cannot change to this UID on
+    startup, it will exit.  If this element is not present, the daemon 
+    will not change or care about its UID.
+ 
+    The last <user> entry in the file "wins", the others are ignored.
+
+ <listen>
+  address="name"    mandatory attribute
+
+    Add an address that the bus should listen on. The 
+    address is in the standard D-BUS format that contains 
+    a transport name plus possible parameters/options.
+
+    Example: <listen address="unix:path=/tmp/foo"/>
+
+    If there are multiple <listen> elements, then the bus listens 
+    on multiple addresses.
+
+ <auth>
+
+    Lists permitted authorization mechanisms. If this element doesn't
+    exist, then all known mechanisms are allowed.  If there are
+    multiple <auth> elements, the last one wins (they are not merged).
+
+ <policy>
+  context="(default|required)"   one of the context/user/group
+                                 attributes is mandatory
+  user="username or userid"
+  group="group name or gid"
+
+    Encloses a policy to be applied to a particular set of 
+    connections to the bus. A policy is made up of <limit>, 
+    <allow>, <deny> elements.
+  
+    Policies are applied to a connection as follows:
+       - all context="default" policies are applied
+       - all group="connection's user's group" policies are applied
+       - all user="connection's auth user" policies are applied
+       - all context="required" policies are applied
+
+    Policies applied later will override those applied earlier, 
+    when the policies overlap. Multiple policies with the same 
+    user/group/context are applied in the order they appear 
+    in the config file.
+
+ <limit>
+  name="resource name"  mandatory
+  
+    Appears below a <policy> element and establishes a resource
+    limit. For example:
+      <limit name="max_message_size">64</limit>
+      <limit name="max_connections">512</limit>
+
+ <deny>
+  send="messagename"
+  receive="messagename"
+  own="servicename"
+  send_to="servicename"
+  receive_from="servicename"
+
+    Examples:
+       <deny send="org.freedesktop.System.Reboot"/> 
+       <deny receive="org.freedesktop.System.Reboot"/>
+       <deny own="org.freedesktop.System"/>
+       <deny send_to="org.freedesktop.System"/>
+       <deny receive_from="org.freedesktop.System"/>
+
+    send_to and receive_from mean that messages may not be sent to 
+    or received from the *owner* of the given service, not that 
+    they may not be sent *to that service name*. That is, if 
+    a connection owns services A, B, C, and sending to A is denied, 
+    sending to B or C will not work either.
+
+    For "servicename" or "messagename" the character "*" can be
+    substituted, meaning "any." Complex globs like "foo.bar.*" aren't
+    allowed for now because they'd be work to implement and maybe 
+    encourage sloppy security anyway.
+
+    FIXME should we allow send/send_to and receive/receive_from 
+    to both be specified, in which case they would be ANDed together?
+    e.g. <deny send="foo.bar" send_to="foo.blah"/> would deny 
+    messages of the given name AND to the given service.
+
+    Probably need to see how hard/slow all this will be to implement.
+
+ <allow>
+  send="messagename"
+  receive="messagename"
+  own="servicename"
+  send_to="servicename"
+  receive_from="servicename"
+
+    Makes an exception to previous <deny> statements. Works 
+    just like <deny> but with the inverse meaning.
+
+    An <allow> only punches holes in the equivalent <deny>, it does
+    not unconditionally allow the message. For example:
+
+      <deny send="*"/>
+      <deny send_to="*"/>
+      <allow send="org.foo.Bar"/>
+
+    Here the policy still doesn't allow sending any messages, because 
+    no recipients have been allowed. You have to add 
+    <allow send_to="something"/> to make the policy useful.
+
+  
+
+    
+
+
+ 
+ 
+
+ 
+   
+   
\ No newline at end of file