Add docbook detection

New files
Free the questions to prevent memory leak

diff --git a/ChangeLog b/ChangeLog
index 4441fc2..443e51b 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -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 (file)
--- 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 (file)
--- 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
 >&#13; Hence, <TT
@@ -334,6 +393,14 @@ CLASS="emphasis"
        obtaining the privilege may use the obtained privilege.
       </P
 ><P
+>&#13; In addition, privileges may be restricted to
+       certain <I
+CLASS="emphasis"
+>resources</I
+>; this is discussed in
+       more detail in XXX.
+      </P
+><P
 >&#13; <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
+>&#13;      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
+>&#13;   <TT
+CLASS="literal"
+>hal://</TT
+>
+       </P
+><P
+>&#13;   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
+>&#13;     Criteria for determining if a given user possess the privilege on a given resource.
+          </P
+></LI
+><LI
+><P
+>&#13;     What other privileges a given user must also possess.
+          </P
+></LI
+><LI
+><P
+>&#13;     Information on whether the user can obtain the privilege, and if he can, whether only temporarily or permanently.
+          </P
+></LI
+><LI
+><P
+>&#13;     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
+>&#13; 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"
+>&#13; [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
+>&#13;   bar
+       </P
+></DIV
+><DIV
+CLASS="sect2"
+><HR><H3
+CLASS="sect2"
+><A
+NAME="AEN109"
+>Required Privileges</A
+></H3
+><P
+>&#13;   bar
+       </P
+></DIV
+><DIV
+CLASS="sect2"
+><HR><H3
+CLASS="sect2"
+><A
+NAME="AEN112"
+>Obtaining Privileges</A
+></H3
+><P
+>&#13;   bar1
+       </P
+></DIV
+><DIV
+CLASS="sect2"
+><HR><H3
+CLASS="sect2"
+><A
+NAME="AEN115"
+>Granting Privileges</A
+></H3
+><P
+>&#13;   bar2
+       </P
+></DIV
+></DIV
+><DIV
+CLASS="sect1"
+><HR><H2
+CLASS="sect1"
+><A
+NAME="AEN118"
+>Privileges defined by PolicyKit</A
+></H2
+><P
+>&#13; 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 (file)
--- 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 (file)
--- 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);