diff options
| -rw-r--r-- | ChangeLog | 9 | ||||
| -rw-r--r-- | configure.in | 34 | ||||
| -rw-r--r-- | doc/spec/polkit-spec.html | 275 | ||||
| -rw-r--r-- | doc/spec/polkit-spec.xml.in | 86 | ||||
| -rw-r--r-- | polkitd/polkit-session.c | 4 |
5 files changed, 399 insertions, 9 deletions
@@ -1,3 +1,12 @@ +2006-03-29 David Zeuthen <davidz@redhat.com> + + * configure.in: Add docbook detection + + * doc/spec/*: New files + + * polkitd/polkit-session.c (polkit_session_finalize): Free the + questions to prevent memory leak + 2006-03-27 Richard Hughes <richard@hughsie.com> * .cvsignore, doc/.cvsignore, libpolkit/.cvsignore, diff --git a/configure.in b/configure.in index f253620..17e4080 100644 --- a/configure.in +++ b/configure.in @@ -48,6 +48,7 @@ AC_DEFINE_UNQUOTED(POLKIT_GROUP,"$POLKIT_GROUP", [Group for PolicyKit]) # Taken from dbus AC_ARG_ENABLE(ansi, [ --enable-ansi enable -ansi -pedantic gcc flags],enable_ansi=$enableval,enable_ansi=no) AC_ARG_ENABLE(verbose-mode, [ --enable-verbose-mode support verbose debug mode],enable_verbose_mode=$enableval,enable_verbose_mode=$USE_MAINTAINER_MODE) +AC_ARG_ENABLE(docbook-docs, [ --enable-docbook-docs build documentation (requires docbook2html)],enable_docbook_docs=$enableval,enable_docbook_docs=auto) GTK_DOC_CHECK([1.3]) @@ -147,6 +148,35 @@ AC_SUBST(DBUS_GLIB_LIBS) AC_CHECK_FUNCS(getgrouplist) +# DocBook Documentation + +AC_PATH_PROG(DOCBOOK, docbook2html, no) + +AC_MSG_CHECKING([whether to build DocBook documentation]) + +if test x$DOCBOOK = xno ; then + have_docbook=no +else + have_docbook=yes +fi + +if test x$enable_docbook_docs = xauto ; then + if test x$have_docbook = xno ; then + enable_docbook_docs=no + else + enable_docbook_docs=yes + fi +fi + +if test x$enable_docbook_docs = xyes; then + if test x$have_docbook = xno; then + AC_MSG_ERROR([Building DocBook docs explicitly required, but DocBook not found]) + fi +fi + +AM_CONDITIONAL(DOCBOOK_DOCS_ENABLED, test x$enable_docbook_docs = xyes) +AC_MSG_RESULT(yes) + AS_AC_EXPAND(LOCALSTATEDIR, $localstatedir) AS_AC_EXPAND(SYSCONFDIR, $sysconfdir) AS_AC_EXPAND(DATADIR, $datadir) @@ -324,6 +354,8 @@ libpolkit/Makefile tools/Makefile doc/Makefile doc/api/Makefile +doc/spec/Makefile +doc/spec/polkit-spec.xml privileges/Makefile ]) @@ -346,6 +378,7 @@ echo " compiler: ${CC} cflags: ${CFLAGS} cppflags: ${CPPFLAGS} + DocBook: ${DOCBOOK} user for PolicyKit: ${POLKIT_USER} group for PolicyKit: ${POLKIT_GROUP} pidfile for polkitd: ${POLKITD_PID_FILE} @@ -361,6 +394,7 @@ echo " Maintainer mode: ${USE_MAINTAINER_MODE} Building verbose mode: ${enable_verbose_mode} Building api docs: ${enable_gtk_doc} + Building docs: ${enable_docbook_docs} " # (distro-tweaks required) diff --git a/doc/spec/polkit-spec.html b/doc/spec/polkit-spec.html index ba96e0a..2e8394d 100644 --- a/doc/spec/polkit-spec.html +++ b/doc/spec/polkit-spec.html @@ -76,8 +76,8 @@ HREF="#AEN15" ></DD ><DT ><A -HREF="#privileges" ->Theory of operation</A +HREF="#operation" +>Theory of Operation</A ></DT ><DD ><DL @@ -98,6 +98,59 @@ HREF="#AEN37" ></DT ></DL ></DD +><DT +><A +HREF="#resources" +>Resources</A +></DT +><DT +><A +HREF="#privileges" +>Privileges</A +></DT +><DD +><DL +><DT +><A +HREF="#AEN87" +>Privilege Descriptors</A +></DT +><DT +><A +HREF="#AEN101" +>File Format</A +></DT +><DD +><DL +><DT +><A +HREF="#AEN106" +>Criteria for Possesing a Privilege</A +></DT +><DT +><A +HREF="#AEN109" +>Required Privileges</A +></DT +><DT +><A +HREF="#AEN112" +>Obtaining Privileges</A +></DT +><DT +><A +HREF="#AEN115" +>Granting Privileges</A +></DT +></DL +></DD +><DT +><A +HREF="#AEN118" +>Privileges defined by PolicyKit</A +></DT +></DL +></DD ></DL ></DIV ><DIV @@ -126,9 +179,9 @@ NAME="AEN15" CLASS="chapter" ><HR><H1 ><A -NAME="privileges" +NAME="operation" ></A ->Theory of operation</H1 +>Theory of Operation</H1 ><DIV CLASS="sect1" ><H2 @@ -314,7 +367,13 @@ CLASS="literal" CLASS="literal" >PolicyKit</TT > service to release the - privilege for the user as it is no longer needed. + privilege for the user as it is no longer needed. Should the + process crash while holding a privilege, + the <TT +CLASS="literal" +>PolicyKit</TT +> service will be notifed and + the privilege will automatically be revoked. </P ><P > Hence, <TT @@ -334,6 +393,14 @@ CLASS="emphasis" obtaining the privilege may use the obtained privilege. </P ><P +> In addition, privileges may be restricted to + certain <I +CLASS="emphasis" +>resources</I +>; this is discussed in + more detail in XXX. + </P +><P > <IMG SRC="polkit-arch.png"> </P @@ -342,6 +409,204 @@ SRC="polkit-arch.png"> </P ></DIV ></DIV +><DIV +CLASS="chapter" +><HR><H1 +><A +NAME="resources" +></A +>Resources</H1 +><P +> PolicyKit allows granting privileges only on + certain <I +CLASS="emphasis" +>resources</I +>. For example, for HAL, + it is possible to grant the + privilege <I +CLASS="emphasis" +>hal-storage-fixed-mount</I +> to the + user with uid 500 but only for the HAL device object + representing e.g. the <TT +CLASS="literal" +>/dev/hda3</TT +> partition. + </P +><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 +CLASS="literal" +>hal://</TT +> + </P +><P +> HAL Unique Device Identifiers also known as HAL UDI's. Example: <TT +CLASS="literal" +>hal:///org/freedesktop/Hal/devices/volume_uuid_1a28b356_9955_44f9_b268_6ed6639978f5</TT +> + </P +></LI +></UL +></DIV +><DIV +CLASS="chapter" +><HR><H1 +><A +NAME="privileges" +></A +>Privileges</H1 +><DIV +CLASS="sect1" +><H2 +CLASS="sect1" +><A +NAME="AEN87" +>Privilege Descriptors</A +></H2 +><P +> + Applications, such as HAL, installs <I +CLASS="emphasis" +>privilege descriptors</I +> using the <TT +CLASS="literal" +>polkit-policy-descriptor-install</TT +> commandline utility. The descriptor contains the following information + </P +><P +></P +><UL +><LI +><P +> Criteria for determining if a given user possess the privilege on a given resource. + </P +></LI +><LI +><P +> What other privileges a given user must also possess. + </P +></LI +><LI +><P +> Information on whether the user can obtain the privilege, and if he can, whether only temporarily or permanently. + </P +></LI +><LI +><P +> Whether a user with the privilege may permanently grant it to other users. + </P +></LI +></UL +></DIV +><DIV +CLASS="sect1" +><HR><H2 +CLASS="sect1" +><A +NAME="AEN101" +>File Format</A +></H2 +><P +> A developer of a system-wide application wanting to define a + privilege must create a privilege descriptor. This is a a + simple <TT +CLASS="literal" +>.ini</TT +>-like config file. Here is what + the skeleton looks like: + </P +><TABLE +BORDER="0" +BGCOLOR="#E0E0E0" +WIDTH="100%" +><TR +><TD +><PRE +CLASS="programlisting" +> [Policy] + Allow= + Deny= + RequirePrivileges= + CanGrantToOthers= + CanObtain= + ObtainRequireRoot= + ObtainPAMService= + </PRE +></TD +></TR +></TABLE +><DIV +CLASS="sect2" +><HR><H3 +CLASS="sect2" +><A +NAME="AEN106" +>Criteria for Possesing a Privilege</A +></H3 +><P +> bar + </P +></DIV +><DIV +CLASS="sect2" +><HR><H3 +CLASS="sect2" +><A +NAME="AEN109" +>Required Privileges</A +></H3 +><P +> bar + </P +></DIV +><DIV +CLASS="sect2" +><HR><H3 +CLASS="sect2" +><A +NAME="AEN112" +>Obtaining Privileges</A +></H3 +><P +> bar1 + </P +></DIV +><DIV +CLASS="sect2" +><HR><H3 +CLASS="sect2" +><A +NAME="AEN115" +>Granting Privileges</A +></H3 +><P +> bar2 + </P +></DIV +></DIV +><DIV +CLASS="sect1" +><HR><H2 +CLASS="sect1" +><A +NAME="AEN118" +>Privileges defined by PolicyKit</A +></H2 +><P +> baz + </P +></DIV +></DIV ></DIV ></BODY ></HTML diff --git a/doc/spec/polkit-spec.xml.in b/doc/spec/polkit-spec.xml.in index 729dd16..9fc8ad6 100644 --- a/doc/spec/polkit-spec.xml.in +++ b/doc/spec/polkit-spec.xml.in @@ -37,7 +37,7 @@ </sect1> </chapter> - <chapter id="privileges"> + <chapter id="operation"> <title>Theory of operation</title> <sect1> @@ -143,7 +143,10 @@ privilege (after successful authentication) he can now invoke <literal>Mount</literal> and after this succeeds he may tell the <literal>PolicyKit</literal> service to release the - privilege for the user as it is no longer needed. + privilege for the user as it is no longer needed. Should the + process crash while holding a privilege, + the <literal>PolicyKit</literal> service will be notifed and + the privilege will automatically be revoked. </para> <para> @@ -156,6 +159,12 @@ </para> <para> + In addition, privileges may be restricted to + certain <emphasis>resources</emphasis>; this is discussed in + more detail in XXX. + </para> + + <para> <inlinegraphic fileref="polkit-arch.png" format="PNG"/> </para> @@ -165,5 +174,78 @@ </sect1> </chapter> + + + <chapter id="resources"> + <title>Resources</title> + + 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. + + <sect1> + <title>Resource Identifiers</title> + <para> Resource identifers are prefixed with a name identifying + what service they belong to. The following resource + identifiers are defined + </para> + + <itemizedlist> + <listitem> + <para> + <literal>hal://</literal> + HAL Unique Device Identifiers also known as HAL UID's. Example: <literal>hal:///org/freedesktop/Hal/devices/volume_uuid_1a28b356_9955_44f9_b268_6ed6639978f5</literal> + </para> + </listitem> + </itemizedlist> + + </sect1> + + </chapter> + + + <chapter id="privileges"> + <title>Privileges</title> + + <sect1> + <title>Privilege Descriptors</title> + <para> + Applications, such as HAL, installs <emphasis>privilege descriptors</emphasis> using the <literal>polkit-policy-descriptor-install</literal> commandline utility. The descriptor contains the following information + </para> + + <itemizedlist> + <listitem> + <para> + What users and groups possess the privilege + </para> + </listitem> + + <listitem> + <para> + foo + </para> + </listitem> + </itemizedlist> + + </sect1> + + <sect1> + <title>Temporary Privileges</title> + <para> + bar + </para> + </sect1> + + <sect1> + <title>Privileges defined by PolicyKit</title> + <para> + baz + </para> + </sect1> + + </chapter> </book> diff --git a/polkitd/polkit-session.c b/polkitd/polkit-session.c index 3521830..458e854 100644 --- a/polkitd/polkit-session.c +++ b/polkitd/polkit-session.c @@ -117,8 +117,8 @@ polkit_session_finalize (PolicyKitSession *session) g_free (session->priv->auth_denied_reason); if (session->priv->auth_questions != NULL) { - //g_slist_foreach (session->priv->auth_questions, (GFunc) g_free, NULL); - //g_free (session->priv->auth_questions); + g_slist_foreach (session->priv->auth_questions, (GFunc) g_free, NULL); + g_slist_free (session->priv->auth_questions); } g_free (session->priv); |