ask-password: add support for caching passwords in the kernel keyring

This adds support for caching harddisk passwords in the kernel keyring
if it is available, thus supporting caching without Plymouth being
around.

This is also useful for hooking up "gdm-auto-login" with the collected
boot-time harddisk password, in order to support gnome keyring
passphrase unlocking via the HDD password, if it is the same.

Any passwords added to the kernel keyring this way have a timeout of
2.5min at which time they are purged from the kernel.

1 files changed, 57 insertions, 13 deletions

diff --git a/man/systemd-ask-password.xml b/man/systemd-ask-password.xml
index 877c71af53..10bb529b81 100644
--- a/man/systemd-ask-password.xml
+++ b/man/systemd-ask-password.xml
@@ -1,4 +1,4 @@
-<?xml version='1.0'?> <!--*-nxml-*-->
+<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 
@@ -72,17 +72,28 @@
     plugged in or at boot, entering an SSL certificate passphrase for
     web and VPN servers.</para>
 
-    <para>Existing agents are: a boot-time password agent asking the
-    user for passwords using Plymouth; a boot-time password agent
-    querying the user directly on the console; an agent requesting
-    password input via a
-    <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    message; an agent suitable for running in a GNOME session; a
-    command line agent which can be started temporarily to process
-    queued password requests; a TTY agent that is temporarily spawned
-    during
-    <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    invocations.</para>
+    <para>Existing agents are:
+    <itemizedlist>
+
+      <listitem><para>A boot-time password agent asking the user for
+      passwords using Plymouth</para></listitem>
+
+      <listitem><para>A boot-time password agent querying the user
+      directly on the console</para></listitem>
+
+      <listitem><para>An agent requesting password input via a
+      <citerefentry
+      project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      message</para></listitem>
+
+      <listitem><para>A command line agent which can be started
+      temporarily to process queued password
+      requests</para></listitem>
+
+      <listitem><para>A TTY agent that is temporarily spawned during
+      <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      invocations</para></listitem>
+    </itemizedlist></para>
 
     <para>Additional password agents may be implemented according to
     the <ulink
@@ -112,6 +123,38 @@
       </varlistentry>
 
       <varlistentry>
+        <term><option>--id=</option></term>
+        <listitem><para>Specify an identifier for this password
+        query. This identifier is freely choosable and allows
+        recognition of queries by involved agents. It should include
+        the subsystem doing the query and the specific object the
+        query is done for. Example:
+        <literal>--id=cryptsetup:/dev/sda5</literal>.</para></listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><option>--keyname=</option></term>
+        <listitem><para>Configure a kernel keyring key name to use as
+        cache for the password. If set, then the tool will try to push
+        any collected passwords into the kernel keyring of the root
+        user, as a key of the specified name. If combined with
+        <option>--accept-cached</option> it will also try to retrieve
+        the such cached passwords from the key in the kernel keyring
+        instead of querying the user right-away. By using this option
+        the kernel keyring may be used as effective cache to avoid
+        repeatedly asking users for passwords, if there are multiple
+        objects that may be unlocked with the same password. The
+        cached key will have a timeout of 2.5min set, after which it
+        will be purged from the kernel keyring. Note that it is
+        possible to cache multiple passwords under the same keyname,
+        in which case they will be stored as NUL-separated list of
+        passwords. Use
+        <citerefentry><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+        to access the cached key via the kernel keyring
+        directly. Example: <literal>--keyname=cryptsetup</literal></para></listitem>
+      </varlistentry>
+
+      <varlistentry>
         <term><option>--timeout=</option></term>
 
         <listitem><para>Specify the query timeout in seconds. Defaults
@@ -138,7 +181,7 @@
         <term><option>--accept-cached</option></term>
 
         <listitem><para>If passed, accept cached passwords, i.e.
-        passwords previously typed in.</para></listitem>
+        passwords previously typed in. </para></listitem>
       </varlistentry>
 
       <varlistentry>
@@ -166,6 +209,7 @@
     <para>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     </para>