add some more code comments and documentation

Add some more insight into my head.

5 files changed, 288 insertions, 1 deletions

diff --git a/docs/Makefile.am b/docs/Makefile.am
index f136ab9..9eeed6e 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -1,6 +1,8 @@
 IMAGE_FILES =				\
 	ohm-logo.png			\
 	ohm-logo.svg			\
+	ohm-dbus-access.png		\
+	ohm-dbus-access.svg		\
 	ohm-structure.png		\
 	ohm-structure.svg		\
 	ohm-sessions.png		\
diff --git a/docs/index.html b/docs/index.html
index 9366606..b349832 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -197,7 +197,14 @@
         key is tried to be set, the set method will fail.
         This is a way to enforce fine-grained rules on users when writing
         PolicyKit rules for every action would be too great an overhead.
-      </p></div><p>
+      </p></div><div class="mediaobject" align="center"><a name="plugins-dbus"></a><img src="ohm-dbus-access.png" align="middle"></div><p>
+      Plugins have direct access to the keystore and can read and write any key
+      even if private.
+      The DBUS interface to the keystore is however limited to only setting
+      public keys to enforce security policy.
+      The DBUS interface should only be used to set preferences, it should
+      never be used to set or change policy - this is the job for the plugin.
+    </p><p>
       Plugins can tell <code class="literal">ohmd</code> that other plugins are required
       for certain functionality, for instance, the backlight unit on a mobile
       phone may require the temperature module to be present, so it can do the
diff --git a/docs/ohm-dbus-access.png b/docs/ohm-dbus-access.png
new file mode 100644
index 0000000..093cf6b
--- /dev/null
+++ b/docs/ohm-dbus-access.png
diff --git a/docs/ohm-dbus-access.svg b/docs/ohm-dbus-access.svg
new file mode 100644
index 0000000..679b437
--- /dev/null
+++ b/docs/ohm-dbus-access.svg
@@ -0,0 +1,263 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://web.resource.org/cc/"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="744.09448819"
+   height="1052.3622047"
+   id="svg2"
+   sodipodi:version="0.32"
+   inkscape:version="0.44.1"
+   sodipodi:docbase="/home/hughsie/ohm.git/docs"
+   sodipodi:docname="ohm-dbus-access.svg"
+   inkscape:export-filename="/home/hughsie/ohm.git/docs/ohm-dbus-access.png"
+   inkscape:export-xdpi="70.519997"
+   inkscape:export-ydpi="70.519997">
+  <defs
+     id="defs4">
+    <marker
+       inkscape:stockid="Arrow1Mstart"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow1Mstart"
+       style="overflow:visible">
+      <path
+         id="path4888"
+         d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none"
+         transform="scale(0.4) translate(10,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow1Lstart"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow1Lstart"
+       style="overflow:visible">
+      <path
+         id="path4894"
+         d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none"
+         transform="scale(0.8) translate(12.5,0)" />
+    </marker>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     gridtolerance="10000"
+     guidetolerance="10"
+     objecttolerance="10"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.7"
+     inkscape:cx="335.42706"
+     inkscape:cy="592.80201"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="true"
+     inkscape:grid-points="true"
+     inkscape:object-nodes="true"
+     inkscape:object-points="true"
+     inkscape:object-bbox="true"
+     inkscape:window-width="1270"
+     inkscape:window-height="721"
+     inkscape:window-x="0"
+     inkscape:window-y="25" />
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:black;stroke-width:1.91293883;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:1.91293887, 22.95526639;stroke-dashoffset:0;stroke-opacity:1"
+       d="M 220.95647,312.31865 L 601.91089,313.20341"
+       id="path2839"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;fill-rule:evenodd;stroke:black;stroke-width:2.95138264;stroke-linecap:square;stroke-linejoin:miter;marker-start:url(#Arrow1Mstart);stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+       d="M 250,328.63 C 250,290.08787 250,290.08787 250,290.08787"
+       id="path3826"
+       sodipodi:nodetypes="cc" />
+    <rect
+       style="opacity:1;fill:#ad7fa8;fill-opacity:1;stroke:black;stroke-width:0;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect1882"
+       width="200"
+       height="80"
+       x="220"
+       y="212.36218" />
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="316.28711"
+       y="246.9657"
+       id="text1942"><tspan
+         sodipodi:role="line"
+         x="316.28711"
+         y="246.9657"
+         style="font-size:28px;text-align:center;text-anchor:middle"
+         id="tspan1938">Session</tspan><tspan
+         sodipodi:role="line"
+         x="316.28711"
+         y="281.9657"
+         style="font-size:28px;text-align:center;text-anchor:middle"
+         id="tspan3019">Preferences</tspan></text>
+    <rect
+       style="opacity:1;fill:#729fcf;fill-opacity:1;stroke:black;stroke-width:0;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect1876"
+       width="110"
+       height="400"
+       x="280"
+       y="332.36218" />
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="287.83203"
+       y="372.04968"
+       id="text1946"><tspan
+         sodipodi:role="line"
+         id="tspan1948"
+         x="287.83203"
+         y="372.04968"
+         style="font-size:40px">OHM</tspan></text>
+    <rect
+       style="opacity:1;fill:#afeded;fill-opacity:1;stroke:black;stroke-width:0;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect3740"
+       width="210"
+       height="80"
+       x="390"
+       y="332.36218" />
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="397.75391"
+       y="371.79578"
+       id="text3742"><tspan
+         sodipodi:role="line"
+         id="tspan3744"
+         x="397.75391"
+         y="371.79578"
+         style="font-size:28">Backlight</tspan></text>
+    <rect
+       style="opacity:1;fill:#eded8d;fill-opacity:1;stroke:black;stroke-width:0;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect3746"
+       width="210"
+       height="80"
+       x="390"
+       y="412.36218" />
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="397.75391"
+       y="451.79578"
+       id="text3748"><tspan
+         sodipodi:role="line"
+         id="tspan3750"
+         x="397.75391"
+         y="451.79578"
+         style="font-size:28">Inhibit</tspan></text>
+    <rect
+       style="opacity:1;fill:#eda328;fill-opacity:1;stroke:black;stroke-width:0;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect3756"
+       width="210"
+       height="80"
+       x="390"
+       y="492.36218" />
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="397.25195"
+       y="521.53796"
+       id="text3758"><tspan
+         sodipodi:role="line"
+         id="tspan3760"
+         x="397.25195"
+         y="521.53796"
+         style="font-size:28px">Heat Mgmt</tspan><tspan
+         sodipodi:role="line"
+         x="397.25195"
+         y="556.53796"
+         style="font-size:28px"
+         id="tspan3762">Policy</tspan></text>
+    <rect
+       style="opacity:1;fill:#a7a328;fill-opacity:1;stroke:black;stroke-width:0;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect3784"
+       width="210"
+       height="80"
+       x="390"
+       y="572.36218" />
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="397.25195"
+       y="601.53796"
+       id="text3786"><tspan
+         sodipodi:role="line"
+         x="397.25195"
+         y="601.53796"
+         style="font-size:28px"
+         id="tspan3790">Internal</tspan><tspan
+         sodipodi:role="line"
+         x="397.25195"
+         y="636.53796"
+         style="font-size:28px"
+         id="tspan3794">Protected IP</tspan></text>
+    <rect
+       style="opacity:1;fill:#e9b96e;fill-opacity:1;stroke:black;stroke-width:0;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect1886"
+       width="60"
+       height="180"
+       x="220"
+       y="332.36218" />
+    <text
+       xml:space="preserve"
+       style="font-size:12px;font-style:normal;font-weight:normal;fill:black;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;font-family:Bitstream Vera Sans"
+       x="249.5625"
+       y="375.69031"
+       id="text1898"><tspan
+         sodipodi:role="line"
+         id="tspan1900"
+         x="249.5625"
+         y="375.69031"
+         style="font-size:32px;text-align:center;text-anchor:middle">D</tspan><tspan
+         sodipodi:role="line"
+         x="249.5625"
+         y="415.69031"
+         style="font-size:32px;text-align:center;text-anchor:middle"
+         id="tspan1942">B</tspan><tspan
+         sodipodi:role="line"
+         x="249.5625"
+         y="455.69031"
+         style="font-size:32px;text-align:center;text-anchor:middle"
+         id="tspan1944">U</tspan><tspan
+         sodipodi:role="line"
+         x="249.5625"
+         y="495.69031"
+         style="font-size:32px;text-align:center;text-anchor:middle"
+         id="tspan1940">S</tspan></text>
+    <rect
+       style="opacity:1;fill:#c00;fill-opacity:1;stroke:black;stroke-width:0;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+       id="rect3015"
+       width="9.4923725"
+       height="180"
+       x="270"
+       y="332.36218" />
+  </g>
+</svg>
diff --git a/docs/plugins.xml b/docs/plugins.xml
index dddf39f..c200336 100644
--- a/docs/plugins.xml
+++ b/docs/plugins.xml
@@ -43,6 +43,21 @@
       </para>
     </note>
 
+    <mediaobject id="plugins-dbus">
+      <imageobject>
+        <imagedata format="PNG" fileref="ohm-dbus-access.png" align="center"/>
+      </imageobject>
+    </mediaobject>
+
+    <para>
+      Plugins have direct access to the keystore and can read and write any key
+      even if private.
+      The DBUS interface to the keystore is however limited to only setting
+      public keys to enforce security policy.
+      The DBUS interface should only be used to set preferences, it should
+      never be used to set or change policy - this is the job for the plugin.
+    </para>
+
     <para>
       Plugins can tell <literal>ohmd</literal> that other plugins are required
       for certain functionality, for instance, the backlight unit on a mobile