Write some more stuff

3 files changed, 561 insertions, 49 deletions

diff --git a/ChangeLog b/ChangeLog
index 809d9c6..1ad3635 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2006-04-21  David Zeuthen  <davidz@redhat.com>
+
+	* doc/spec/polkit-spec.xml.in: Write some more stuff 
+
 2006-04-04  Richard Hughes  <richard@hughsie.com>
 
 	* doc/Makefile.am: Add in the new spec directory so we add the folder
diff --git a/doc/spec/polkit-spec.html b/doc/spec/polkit-spec.html
index 2e8394d..efcaf12 100644
--- a/doc/spec/polkit-spec.html
+++ b/doc/spec/polkit-spec.html
@@ -77,7 +77,7 @@ HREF="#AEN15"
 ><DT
 ><A
 HREF="#operation"
->Theory of Operation</A
+>Theory of operation</A
 ></DT
 ><DD
 ><DL
@@ -103,6 +103,15 @@ HREF="#AEN37"
 HREF="#resources"
 >Resources</A
 ></DT
+><DD
+><DL
+><DT
+><A
+HREF="#AEN78"
+>Resource Identifiers</A
+></DT
+></DL
+></DD
 ><DT
 ><A
 HREF="#privileges"
@@ -112,41 +121,61 @@ HREF="#privileges"
 ><DL
 ><DT
 ><A
-HREF="#AEN87"
+HREF="#AEN88"
 >Privilege Descriptors</A
 ></DT
 ><DT
 ><A
-HREF="#AEN101"
+HREF="#AEN102"
 >File Format</A
 ></DT
 ><DD
 ><DL
 ><DT
 ><A
-HREF="#AEN106"
->Criteria for Possesing a Privilege</A
+HREF="#AEN107"
+><TT
+CLASS="literal"
+>RequiredPrivileges</TT
+>: Required Privileges</A
 ></DT
 ><DT
 ><A
-HREF="#AEN109"
->Required Privileges</A
+HREF="#AEN111"
+><TT
+CLASS="literal"
+>Allow, Deny</TT
+>: Criteria for Possesing a Privilege</A
 ></DT
 ><DT
 ><A
-HREF="#AEN112"
->Obtaining Privileges</A
+HREF="#AEN155"
+><TT
+CLASS="literal"
+>CanObtain</TT
+>: Obtaining Privileges</A
+></DT
+><DT
+><A
+HREF="#AEN165"
+><TT
+CLASS="literal"
+>CanGrant</TT
+>: Granting Privileges</A
 ></DT
 ><DT
 ><A
-HREF="#AEN115"
->Granting Privileges</A
+HREF="#AEN177"
+><TT
+CLASS="literal"
+>ObtainRequireRoot, ObtainPAMService</TT
+>: Authentication Requirements</A
 ></DT
 ></DL
 ></DD
 ><DT
 ><A
-HREF="#AEN118"
+HREF="#AEN190"
 >Privileges defined by PolicyKit</A
 ></DT
 ></DL
@@ -181,7 +210,7 @@ CLASS="chapter"
 ><A
 NAME="operation"
 ></A
->Theory of Operation</H1
+>Theory of operation</H1
 ><DIV
 CLASS="sect1"
 ><H2
@@ -421,8 +450,8 @@ NAME="resources"
       certain <I
 CLASS="emphasis"
 >resources</I
->. For example, for HAL,
-      it is possible to grant the
+>. For example, for HAL, it
+      is possible to grant the
       privilege <I
 CLASS="emphasis"
 >hal-storage-fixed-mount</I
@@ -433,31 +462,37 @@ CLASS="literal"
 >/dev/hda3</TT
 > partition.
     </P
+><DIV
+CLASS="sect1"
+><HR><H2
+CLASS="sect1"
+><A
+NAME="AEN78"
+>Resource Identifiers</A
+></H2
 ><P
-> 
-      Resource identifers are prefixed with a name identifying what
-      service they belong to. The following resource identifiers are
-      defined
-    </P
+> Resource identifers are prefixed with a name identifying
+	what service they belong to. The following resource
+	identifiers are defined
+      </P
 ><P
 ></P
 ><UL
 ><LI
 ><P
->&#13;	  <TT
+>&#13;	    <TT
 CLASS="literal"
 >hal://</TT
 >
-	</P
-><P
->&#13;	  HAL Unique Device Identifiers also known as HAL UDI's. Example: <TT
+	    HAL Unique Device Identifiers also known as HAL UID's. Example: <TT
 CLASS="literal"
 >hal:///org/freedesktop/Hal/devices/volume_uuid_1a28b356_9955_44f9_b268_6ed6639978f5</TT
 >
-        </P
+          </P
 ></LI
 ></UL
 ></DIV
+></DIV
 ><DIV
 CLASS="chapter"
 ><HR><H1
@@ -470,7 +505,7 @@ CLASS="sect1"
 ><H2
 CLASS="sect1"
 ><A
-NAME="AEN87"
+NAME="AEN88"
 >Privilege Descriptors</A
 ></H2
 ><P
@@ -513,7 +548,7 @@ CLASS="sect1"
 ><HR><H2
 CLASS="sect1"
 ><A
-NAME="AEN101"
+NAME="AEN102"
 >File Format</A
 ></H2
 ><P
@@ -534,11 +569,11 @@ WIDTH="100%"
 ><PRE
 CLASS="programlisting"
 >&#13;	[Policy]
+	RequiredPrivileges=
 	Allow=
 	Deny=
-	RequirePrivileges=
-	CanGrantToOthers=
 	CanObtain=
+	CanGrant=
 	ObtainRequireRoot=
 	ObtainPAMService=
       </PRE
@@ -550,11 +585,17 @@ CLASS="sect2"
 ><HR><H3
 CLASS="sect2"
 ><A
-NAME="AEN106"
->Criteria for Possesing a Privilege</A
+NAME="AEN107"
+><TT
+CLASS="literal"
+>RequiredPrivileges</TT
+>: Required Privileges</A
 ></H3
 ><P
->&#13;	  bar
+>&#13;	  This is a list of privileges the user must possess in order
+	  to possess the given privilege. If the user doesn't possess
+	  all of these privileges he is not considered to possess the
+	  given privilege. The list may be empty.
 	</P
 ></DIV
 ><DIV
@@ -562,11 +603,214 @@ CLASS="sect2"
 ><HR><H3
 CLASS="sect2"
 ><A
-NAME="AEN109"
->Required Privileges</A
+NAME="AEN111"
+><TT
+CLASS="literal"
+>Allow, Deny</TT
+>: Criteria for Possesing a Privilege</A
 ></H3
 ><P
->&#13;	  bar
+>&#13;	  Both <TT
+CLASS="literal"
+>Allow</TT
+> and <TT
+CLASS="literal"
+>Deny</TT
+>
+	  contains lists describing what users are allowed
+	  respectively denied the privilege. The elements of in each
+	  list are of the form
+	  <TT
+CLASS="literal"
+>type:value[:resource]</TT
+>.  where the last
+	  part, resource, may be omitted. The following types are
+	  supported:
+	</P
+><P
+></P
+><UL
+><LI
+><P
+><TT
+CLASS="literal"
+>uid</TT
+>: Unix user identifer; either
+	    a positive integer or Unix username. Special values
+	    include <TT
+CLASS="literal"
+>__all__</TT
+> (for denoting all
+	    users) and <TT
+CLASS="literal"
+>__none__</TT
+> (for denoting no
+	    users).</P
+></LI
+><LI
+><P
+><TT
+CLASS="literal"
+>gid</TT
+>: Unix group identifier,
+	    either a positive integer or Unix groupname. Special
+	    values include <TT
+CLASS="literal"
+>__all__</TT
+> (for denoting
+	    all groups) and <TT
+CLASS="literal"
+>__none__</TT
+> (for denoting
+	    no groups).</P
+></LI
+></UL
+><P
+>&#13;	  To determine if a given user is allowed for a given
+	  privilege (for a given resource), first
+	  the <TT
+CLASS="literal"
+>RequiredPrivileges</TT
+> list is consulted
+	  as described above. If the user possess all of the listed
+	  privileges, the <TT
+CLASS="literal"
+>Allow</TT
+> list is now
+	  consulted. For each element we it is tested whether the user
+	  matches. If there are no elements for which the user is
+	  matches, the user is said not to possess the given privilege
+	  (for the given resource).
+	</P
+><P
+>&#13;	  If there is a match in the <TT
+CLASS="literal"
+>Allow</TT
+> list,
+	  the <TT
+CLASS="literal"
+>Deny</TT
+> list is now consulted. If the
+	  user matches any of the elements we know he doesn't possess
+	  the given privilege. If no elements match we can conclude
+	  that the user indeed possesses the given privilege (for the
+	  given resource).
+	</P
+><P
+>&#13;	  This logic is best described by a few examples
+	</P
+><P
+></P
+><UL
+><LI
+><P
+>&#13;	      <TT
+CLASS="literal"
+>&#13;		Allow="uid:davidz uid:501:hal:///deviceFoo gid:admins
+		uid:502"
+	      </TT
+>
+	    </P
+><P
+>&#13;	      <TT
+CLASS="literal"
+>&#13;		Deny="gid:dooders uid:502:hal:///deviceBar"
+	      </TT
+>
+	    </P
+><P
+>&#13;		User <TT
+CLASS="literal"
+>davidz</TT
+> possess this
+		privilege. All members of
+		the <TT
+CLASS="literal"
+>dooders</TT
+> group is denied this
+		privilege. User 501 is allowed this privilege but only
+		on the <TT
+CLASS="literal"
+>hal:///deviceFoo</TT
+>
+		resource. All users in the <TT
+CLASS="literal"
+>admin</TT
+>
+		group posseses the privilege. User 502 is allowed this
+		privilege but not on
+		the <TT
+CLASS="literal"
+>hal:///deviceBar</TT
+>
+		resource.
+	    </P
+></LI
+><LI
+><P
+>&#13;	      <TT
+CLASS="literal"
+>&#13;		Allow="uid:__all__"
+	      </TT
+>
+	    </P
+><P
+>&#13;	      <TT
+CLASS="literal"
+>&#13;		Deny="gid:normalstaff"
+	      </TT
+>
+	    </P
+><P
+>&#13;	        All users expect those in
+	        the <TT
+CLASS="literal"
+>normalstaff</TT
+> group posseses this
+	        privilege.
+	    </P
+></LI
+></UL
+></DIV
+><DIV
+CLASS="sect2"
+><HR><H3
+CLASS="sect2"
+><A
+NAME="AEN155"
+><TT
+CLASS="literal"
+>CanObtain</TT
+>: Obtaining Privileges</A
+></H3
+><P
+>&#13;	  This property denotes whether an user can obtain the
+	  privilege by authentication. It can assume the values
+	  <TT
+CLASS="literal"
+>True</TT
+> (the user can obtain the privilege
+	  permanently), <TT
+CLASS="literal"
+>Temporary</TT
+> (the user can
+	  only obtain the privilege temporarily) and
+	  <TT
+CLASS="literal"
+>False</TT
+> (the user can never obtain the
+	  privilege through authentication).
+	</P
+><P
+>&#13;	  The authentication required are specified in
+	  the <TT
+CLASS="literal"
+>ObtainRequireRoot</TT
+>
+	  and <TT
+CLASS="literal"
+>ObtainPAMService</TT
+> properties.
 	</P
 ></DIV
 ><DIV
@@ -574,11 +818,44 @@ CLASS="sect2"
 ><HR><H3
 CLASS="sect2"
 ><A
-NAME="AEN112"
->Obtaining Privileges</A
+NAME="AEN165"
+><TT
+CLASS="literal"
+>CanGrant</TT
+>: Granting Privileges</A
 ></H3
 ><P
->&#13;	  bar1
+>&#13;	  This property (it can assume the
+	  values <TT
+CLASS="literal"
+>True</TT
+> and <TT
+CLASS="literal"
+>False</TT
+>)
+	  describes whether an user with the given privilege can grant
+	  it to other users, e.g. modify the <TT
+CLASS="literal"
+>Allow</TT
+>
+	  and <TT
+CLASS="literal"
+>Deny</TT
+> properties.
+	</P
+><P
+>&#13;	  The property <TT
+CLASS="literal"
+>CanObtain</TT
+> needs to have the
+	  value <TT
+CLASS="literal"
+>True</TT
+> if this property assumes the
+	  value <TT
+CLASS="literal"
+>True</TT
+>.
 	</P
 ></DIV
 ><DIV
@@ -586,11 +863,50 @@ CLASS="sect2"
 ><HR><H3
 CLASS="sect2"
 ><A
-NAME="AEN115"
->Granting Privileges</A
+NAME="AEN177"
+><TT
+CLASS="literal"
+>ObtainRequireRoot, ObtainPAMService</TT
+>: Authentication Requirements</A
 ></H3
 ><P
->&#13;	  bar2
+>&#13;	  If the property <TT
+CLASS="literal"
+>CanObtain</TT
+> assumes the
+	  value <TT
+CLASS="literal"
+>True</TT
+>
+	  or <TT
+CLASS="literal"
+>Temporary</TT
+> it means the user can
+	  authenticate to gain a privilege.
+	</P
+><P
+>&#13;	  The <TT
+CLASS="literal"
+>ObtainRequireRoot</TT
+> property specifies
+	  whether authentication requires the super user password
+	  (<TT
+CLASS="literal"
+>True</TT
+>) or the users own password
+	  (<TT
+CLASS="literal"
+>False</TT
+>). In addition, it can be specified
+	  what PAM service (for example <TT
+CLASS="literal"
+>pam_rps</TT
+>) is
+	  to be used for authentication through the
+	  property <TT
+CLASS="literal"
+>ObtainPAMService</TT
+>.
 	</P
 ></DIV
 ></DIV
@@ -599,7 +915,7 @@ CLASS="sect1"
 ><HR><H2
 CLASS="sect1"
 ><A
-NAME="AEN118"
+NAME="AEN190"
 >Privileges defined by PolicyKit</A
 ></H2
 ><P
diff --git a/doc/spec/polkit-spec.xml.in b/doc/spec/polkit-spec.xml.in
index aded386..3111c91 100644
--- a/doc/spec/polkit-spec.xml.in
+++ b/doc/spec/polkit-spec.xml.in
@@ -183,9 +183,9 @@
       PolicyKit allows granting privileges only on
       certain <emphasis>resources</emphasis>. For example, for HAL, it
       is possible to grant the
-      privilege <emphasis>hal-storage-fixed-mount</emphasis> to the user
-      with uid 500 but only for the HAL device object representing
-      e.g. the <literal>/dev/hda3</literal> partition.
+      privilege <emphasis>hal-storage-fixed-mount</emphasis> to the
+      user with uid 500 but only for the HAL device object
+      representing e.g. the <literal>/dev/hda3</literal> partition.
     </para>
 
     <sect1>
@@ -209,6 +209,7 @@
   </chapter>
 
 
+
   <chapter id="privileges">
     <title>Privileges</title>
 
@@ -221,13 +222,25 @@
       <itemizedlist>
         <listitem>
 	  <para>
-	    What users and groups possess the privilege
+	    Criteria for determining if a given user possess the privilege on a given resource.
+          </para>
+	</listitem>
+
+        <listitem>
+	  <para>
+	    What other privileges a given user must also possess.
           </para>
 	</listitem>
 
         <listitem>
 	  <para>
-	    foo
+	    Information on whether the user can obtain the privilege, and if he can, whether only temporarily or permanently.
+          </para>
+	</listitem>
+
+        <listitem>
+	  <para>
+	    Whether a user with the privilege may permanently grant it to other users.
           </para>
 	</listitem>
       </itemizedlist>
@@ -235,10 +248,189 @@
     </sect1>
 
     <sect1>
-      <title>Temporary Privileges</title>
+      <title>File Format</title>
       <para>
-	bar
+	A developer of a system-wide application wanting to define a
+	privilege must create a privilege descriptor. This is a a
+	simple <literal>.ini</literal>-like config file. Here is what
+	the skeleton looks like:
       </para>
+
+      <programlisting>
+	[Policy]
+	RequiredPrivileges=
+	Allow=
+	Deny=
+	CanObtain=
+	CanGrant=
+	ObtainRequireRoot=
+	ObtainPAMService=
+      </programlisting>
+
+      <sect2>
+	<title><literal>RequiredPrivileges</literal>: Required Privileges</title>
+	<para>
+	  This is a list of privileges the user must possess in order
+	  to possess the given privilege. If the user doesn't possess
+	  all of these privileges he is not considered to possess the
+	  given privilege. The list may be empty.
+	</para>
+      </sect2>
+
+      <sect2>
+	<title><literal>Allow, Deny</literal>: Criteria for Possesing a Privilege</title>
+	<para>
+	  Both <literal>Allow</literal> and <literal>Deny</literal>
+	  contains lists describing what users are allowed
+	  respectively denied the privilege. The elements of in each
+	  list are of the form
+	  <literal>type:value[:resource]</literal>.  where the last
+	  part, resource, may be omitted. The following types are
+	  supported:
+	</para>
+	<itemizedlist>
+          <listitem>
+	    <para><literal>uid</literal>: Unix user identifer; either
+	    a positive integer or Unix username. Special values
+	    include <literal>__all__</literal> (for denoting all
+	    users) and <literal>__none__</literal> (for denoting no
+	    users).</para>
+	  </listitem>
+
+          <listitem>
+	    <para><literal>gid</literal>: Unix group identifier,
+	    either a positive integer or Unix groupname. Special
+	    values include <literal>__all__</literal> (for denoting
+	    all groups) and <literal>__none__</literal> (for denoting
+	    no groups).</para>
+	  </listitem>
+	</itemizedlist>
+	<para>
+	  To determine if a given user is allowed for a given
+	  privilege (for a given resource), first
+	  the <literal>RequiredPrivileges</literal> list is consulted
+	  as described above. If the user possess all of the listed
+	  privileges, the <literal>Allow</literal> list is now
+	  consulted. For each element we it is tested whether the user
+	  matches. If there are no elements for which the user is
+	  matches, the user is said not to possess the given privilege
+	  (for the given resource).
+	</para>
+	<para>
+	  If there is a match in the <literal>Allow</literal> list,
+	  the <literal>Deny</literal> list is now consulted. If the
+	  user matches any of the elements we know he doesn't possess
+	  the given privilege. If no elements match we can conclude
+	  that the user indeed possesses the given privilege (for the
+	  given resource).
+	</para>
+	<para>
+	  This logic is best described by a few examples
+	</para>
+	<itemizedlist>
+
+          <listitem>
+	    <para>
+	      <literal>
+		Allow="uid:davidz uid:501:hal:///deviceFoo gid:admins
+		uid:502"
+	      </literal>
+	    </para>
+	    <para>
+	      <literal>
+		Deny="gid:dooders uid:502:hal:///deviceBar"
+	      </literal>
+	    </para>
+	    <para>
+		User <literal>davidz</literal> possess this
+		privilege. All members of
+		the <literal>dooders</literal> group is denied this
+		privilege. User 501 is allowed this privilege but only
+		on the <literal>hal:///deviceFoo</literal>
+		resource. All users in the <literal>admin</literal>
+		group posseses the privilege. User 502 is allowed this
+		privilege but not on
+		the <literal>hal:///deviceBar</literal>
+		resource.
+	    </para>
+	  </listitem>
+
+          <listitem>
+	    <para>
+	      <literal>
+		Allow="uid:__all__"
+	      </literal>
+	    </para>
+	    <para>
+	      <literal>
+		Deny="gid:normalstaff"
+	      </literal>
+	    </para>
+	    <para>
+	        All users expect those in
+	        the <literal>normalstaff</literal> group posseses this
+	        privilege.
+	    </para>
+	  </listitem>
+
+	</itemizedlist>
+
+      </sect2>
+
+      
+      <sect2>
+	<title><literal>CanObtain</literal>: Obtaining Privileges</title>
+	<para>
+	  This property denotes whether an user can obtain the
+	  privilege by authentication. It can assume the values
+	  <literal>True</literal> (the user can obtain the privilege
+	  permanently), <literal>Temporary</literal> (the user can
+	  only obtain the privilege temporarily) and
+	  <literal>False</literal> (the user can never obtain the
+	  privilege through authentication).
+	</para>
+	<para>
+	  The authentication required are specified in
+	  the <literal>ObtainRequireRoot</literal>
+	  and <literal>ObtainPAMService</literal> properties.
+	</para>
+      </sect2>
+      
+      <sect2>
+	<title><literal>CanGrant</literal>: Granting Privileges</title>
+	<para>
+	  This property (it can assume the
+	  values <literal>True</literal> and <literal>False</literal>)
+	  describes whether an user with the given privilege can grant
+	  it to other users, e.g. modify the <literal>Allow</literal>
+	  and <literal>Deny</literal> properties.
+	</para>
+	<para>
+	  The property <literal>CanObtain</literal> needs to have the
+	  value <literal>True</literal> if this property assumes the
+	  value <literal>True</literal>.
+	</para>
+      </sect2>
+
+      <sect2>
+	<title><literal>ObtainRequireRoot, ObtainPAMService</literal>: Authentication Requirements</title>
+	<para>
+	  If the property <literal>CanObtain</literal> assumes the
+	  value <literal>True</literal>
+	  or <literal>Temporary</literal> it means the user can
+	  authenticate to gain a privilege.
+	</para>
+	<para>
+	  The <literal>ObtainRequireRoot</literal> property specifies
+	  whether authentication requires the super user password
+	  (<literal>True</literal>) or the users own password
+	  (<literal>False</literal>). In addition, it can be specified
+	  what PAM service (for example <literal>pam_rps</literal>) is
+	  to be used for authentication through the
+	  property <literal>ObtainPAMService</literal>.
+	</para>
+      </sect2>
+      
     </sect1>
 
     <sect1>