diff options
| -rw-r--r-- | ChangeLog | 4 | ||||
| -rw-r--r-- | doc/spec/polkit-spec.html | 400 | ||||
| -rw-r--r-- | doc/spec/polkit-spec.xml.in | 206 |
3 files changed, 561 insertions, 49 deletions
@@ -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 -> <TT +> <TT CLASS="literal" >hal://</TT > - </P -><P -> 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" > [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 -> bar +> 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 -> bar +> 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 +> 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 +> 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 +> This logic is best described by a few examples + </P +><P +></P +><UL +><LI +><P +> <TT +CLASS="literal" +> Allow="uid:davidz uid:501:hal:///deviceFoo gid:admins + uid:502" + </TT +> + </P +><P +> <TT +CLASS="literal" +> Deny="gid:dooders uid:502:hal:///deviceBar" + </TT +> + </P +><P +> 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 +> <TT +CLASS="literal" +> Allow="uid:__all__" + </TT +> + </P +><P +> <TT +CLASS="literal" +> Deny="gid:normalstaff" + </TT +> + </P +><P +> 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 +> 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 +> 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 -> bar1 +> 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 +> 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 -> bar2 +> 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 +> 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> |