Merge pull request #1484 from poettering/ask-pass-kernel-keyring

cache harddisk passwords in the kernel keyring

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>