PolicyKit/doc/spec polkit-spec.html, 1.2, 1.3 polkit-spec.xml.in,
1.3, 1.4
David Zeuthen
david at kemper.freedesktop.org
Fri Apr 21 19:24:02 PDT 2006
Update of /cvs/hal/PolicyKit/doc/spec
In directory kemper:/tmp/cvs-serv9240/doc/spec
Modified Files:
polkit-spec.html polkit-spec.xml.in
Log Message:
2006-04-21 David Zeuthen <davidz at redhat.com>
* doc/spec/polkit-spec.xml.in: Write some more stuff
Index: polkit-spec.html
===================================================================
RCS file: /cvs/hal/PolicyKit/doc/spec/polkit-spec.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- polkit-spec.html 29 Mar 2006 16:15:28 -0000 1.2
+++ polkit-spec.html 22 Apr 2006 02:24:00 -0000 1.3
@@ -77,7 +77,7 @@
><DT
><A
HREF="#operation"
->Theory of Operation</A
+>Theory of operation</A
></DT
><DD
><DL
@@ -103,6 +103,15 @@
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 @@
><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="#AEN115"
->Granting Privileges</A
+HREF="#AEN165"
+><TT
+CLASS="literal"
+>CanGrant</TT
+>: Granting Privileges</A
+></DT
+><DT
+><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 @@
><A
NAME="operation"
></A
->Theory of Operation</H1
+>Theory of operation</H1
><DIV
CLASS="sect1"
><H2
@@ -421,8 +450,8 @@
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 @@
>/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 @@
><H2
CLASS="sect1"
><A
-NAME="AEN87"
+NAME="AEN88"
>Privilege Descriptors</A
></H2
><P
@@ -513,7 +548,7 @@
><HR><H2
CLASS="sect1"
><A
-NAME="AEN101"
+NAME="AEN102"
>File Format</A
></H2
><P
@@ -534,11 +569,11 @@
><PRE
CLASS="programlisting"
> [Policy]
+ RequiredPrivileges=
Allow=
Deny=
- RequirePrivileges=
- CanGrantToOthers=
CanObtain=
+ CanGrant=
ObtainRequireRoot=
ObtainPAMService=
</PRE
@@ -550,11 +585,17 @@
><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,23 +603,214 @@
><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="AEN112"
->Obtaining Privileges</A
+NAME="AEN155"
+><TT
+CLASS="literal"
+>CanObtain</TT
+>: Obtaining Privileges</A
></H3
><P
-> bar1
+> 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
@@ -586,11 +818,95 @@
><HR><H3
CLASS="sect2"
><A
-NAME="AEN115"
->Granting Privileges</A
+NAME="AEN165"
+><TT
+CLASS="literal"
+>CanGrant</TT
+>: Granting Privileges</A
></H3
><P
-> bar2
+> 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
+CLASS="sect2"
+><HR><H3
+CLASS="sect2"
+><A
+NAME="AEN177"
+><TT
+CLASS="literal"
+>ObtainRequireRoot, ObtainPAMService</TT
+>: Authentication Requirements</A
+></H3
+><P
+> 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 @@
><HR><H2
CLASS="sect1"
><A
-NAME="AEN118"
+NAME="AEN190"
>Privileges defined by PolicyKit</A
></H2
><P
Index: polkit-spec.xml.in
===================================================================
RCS file: /cvs/hal/PolicyKit/doc/spec/polkit-spec.xml.in,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- polkit-spec.xml.in 4 Apr 2006 19:04:20 -0000 1.3
+++ polkit-spec.xml.in 22 Apr 2006 02:24:00 -0000 1.4
@@ -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>
- foo
+ What other privileges a given user must also possess.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ 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>
More information about the hal-commit
mailing list