Implement lockdown for the Local Authority implementation

5 files changed, 158 insertions, 5 deletions

diff --git a/docs/man/Makefile.am b/docs/man/Makefile.am
index 076608b..6f164c9 100644
--- a/docs/man/Makefile.am
+++ b/docs/man/Makefile.am
@@ -10,6 +10,7 @@ man_MANS = 				\
 	pkexec.1			\
 	pkcheck.1			\
 	pkaction.1			\
+	pklalockdown.1			\
 	$(NULL)
 
 %.8 %.1 : %.xml
@@ -24,6 +25,7 @@ EXTRA_DIST = 				\
 	pkexec.xml			\
 	pkcheck.xml			\
 	pkaction.xml			\
+	pklalockdown.xml		\
 	$(NULL)
 
 clean-local:
diff --git a/docs/man/pklalockdown.xml b/docs/man/pklalockdown.xml
new file mode 100644
index 0000000..74e4f5d
--- /dev/null
+++ b/docs/man/pklalockdown.xml
@@ -0,0 +1,136 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<refentry id="pklalockdown.1" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <refentryinfo>
+    <title>pklalockdown</title>
+    <date>May 2009</date>
+    <productname>polkit</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>pklalockdown</refentrytitle>
+    <manvolnum>1</manvolnum>
+    <refmiscinfo class="version"></refmiscinfo>
+  </refmeta>
+
+  <refnamediv>
+    <refname>pklalockdown</refname>
+    <refpurpose>Configure lockdown for the Local Authority</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>pklalockdown</command>
+      <arg><option>--version</option></arg>
+      <arg><option>--help</option></arg>
+    </cmdsynopsis>
+
+    <cmdsynopsis>
+      <command>pklalockdown</command>
+      <arg choice="plain">
+        <option>--lockdown</option>
+        <replaceable>action</replaceable>
+      </arg>
+    </cmdsynopsis>
+
+    <cmdsynopsis>
+      <command>pklalockdown</command>
+      <arg choice="plain">
+        <option>--remove-lockdown</option>
+        <replaceable>action</replaceable>
+      </arg>
+    </cmdsynopsis>
+
+  </refsynopsisdiv>
+
+  <refsect1 id="pklalockdown-description">
+    <title>DESCRIPTION</title>
+    <para>
+      <command>pklalockdown</command> is used to configure lockdown
+      for the Local Authority.
+    </para>
+    <para>
+      The effect of locking down an action is that administrator
+      authentication is always needed in order for subjects to acquire
+      the authorization for the action in question (and the subject
+      has to be in an active session on a local console). The obtained
+      authorization is temporary and as such typically expires five
+      minutes after being obtained.
+    </para>
+    <para>
+      To lock down <replaceable>action</replaceable> use the <option>--lockdown</option> option.
+      To remove a lockdown for <replaceable>action</replaceable> use the <option>--remove-lockdown</option> option.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pklalockdown-required-auhtz">
+    <title>REQUIRED AUTHORIZATIONS</title>
+    <para>
+      The <emphasis>org.freedesktop.policykit.localauthority.lockdown</emphasis>
+      authorization is needed to add or remove lockdown. By default,
+      this authorization requires administrator authentication and
+      cannot be retained.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pklalockdown-impl-details">
+    <title>IMPLEMENTATION DETAILS</title>
+    <para>
+      Lockdown is implemented through <filename>.pkla</filename>
+      files. Locked down actions supersede other most other Local
+      Authority configuration as the <filename>.pkla</filename> files
+      are placed
+      in <filename>/var/lib/polkit-1/localauthority90-mandatory.d</filename>.
+    <para>
+    </para>
+      Programs checking authorizations can check whether an action is
+      locked down via by checking
+      the <emphasis>polkit.localauthority.lockdown</emphasis> key/value pair in
+      the details of the authorization response.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pklalockdown-return-values">
+    <title>RETURN VALUE</title>
+    <para>
+      On success <command>pklalockdown</command> returns 0. Otherwise a
+      non-zero value is returned and a diagnostic message is printed
+      on standard error.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pklalockdown-author"><title>AUTHOR</title>
+    <para>
+      Written by David Zeuthen <email>davidz@redhat.com</email> with
+      a lot of help from many others.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pklalockdown-bugs">
+    <title>BUGS</title>
+    <para>
+      Please send bug reports to either the distribution or the
+      polkit-devel mailing list,
+      see the link <ulink url="http://lists.freedesktop.org/mailman/listinfo/polkit-devel"/>
+      on how to subscribe.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pklalockdown-see-also">
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+        <refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pkcheck</refentrytitle><manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pklocalauthority</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>
+    </para>
+  </refsect1>
+</refentry>
diff --git a/docs/man/pklocalauthority.xml b/docs/man/pklocalauthority.xml
index 52dded2..495aa41 100644
--- a/docs/man/pklocalauthority.xml
+++ b/docs/man/pklocalauthority.xml
@@ -155,7 +155,7 @@
     <para>
       Each group in a <filename>.pkla</filename> must have a name that
       is unique within the file it belongs to. The following keys are
-      required in each group
+      are processed.
     </para>
     <variablelist>
       <varlistentry>
@@ -214,12 +214,23 @@
           </para>
         </listitem>
       </varlistentry>
+      <varlistentry>
+        <term><emphasis>ReturnValue</emphasis></term>
+        <listitem>
+          <para>
+            A semi-colon separated list of key/value pairs (of the
+            form key=value) that are add to the details of
+            authorization result on positive matches.
+          </para>
+        </listitem>
+      </varlistentry>
     </variablelist>
     <para>
       All keys specified above are required except that only at least
       one
       of <emphasis>RequireAny</emphasis>, <emphasis>RequireInactive</emphasis>
-      and <emphasis>RequireActive</emphasis> is present.
+      and <emphasis>RequireActive</emphasis> is
+      present. The <emphasis>ReturnValue</emphasis> key is optional.
     </para>
   </refsect1>
 
@@ -240,8 +251,10 @@
       authorization check matches the data from the authorization
       check, then the authorization result
       from <emphasis>RequireAny</emphasis>, <emphasis>RequireInactive</emphasis>
-      or <emphasis>RequireActive</emphasis> is used. Finally, the
-      authorization entries are consulted using the user identity.
+      or <emphasis>RequireActive</emphasis> is used
+      and <emphasis>ReturnValue</emphasis> is added to the
+      authorization result. Finally, the authorization entries are
+      consulted using the user identity in the same manner.
     </para>
     <para>
       Note that processing continues even after a match. This allows
diff --git a/docs/polkit/polkit-1-docs.xml b/docs/polkit/polkit-1-docs.xml
index f09954b..357efdf 100644
--- a/docs/polkit/polkit-1-docs.xml
+++ b/docs/polkit/polkit-1-docs.xml
@@ -110,10 +110,11 @@
     <title>Manual Pages</title>
     <xi:include href="../man/polkit.xml"/>
     <xi:include href="../man/polkitd.xml"/>
-    <xi:include href="../man/pklocalauthority.xml"/>
     <xi:include href="../man/pkcheck.xml"/>
     <xi:include href="../man/pkaction.xml"/>
     <xi:include href="../man/pkexec.xml"/>
+    <xi:include href="../man/pklocalauthority.xml"/>
+    <xi:include href="../man/pklalockdown.xml"/>
   </part>
 
   <chapter id="polkit-hierarchy">
diff --git a/docs/polkit/polkit-1-sections.txt b/docs/polkit/polkit-1-sections.txt
index 333e2c8..f5bc3a8 100644
--- a/docs/polkit/polkit-1-sections.txt
+++ b/docs/polkit/polkit-1-sections.txt
@@ -64,6 +64,7 @@ polkit_authorization_result_get_is_authorized
 polkit_authorization_result_get_is_challenge
 polkit_authorization_result_get_retains_authorization
 polkit_authorization_result_get_temporary_authorization_id
+polkit_authorization_result_get_local_authority_lock_down
 polkit_authorization_result_get_details
 <SUBSECTION Standard>
 PolkitAuthorizationResultClass