source: general/genlib/keyutils.xml@ f9a99954

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY keyutils-download-http "https://git.kernel.org/pub/scm/linux/kernel/git/dhowells/keyutils.git/snapshot/keyutils-&keyutils-version;.tar.gz">
  <!ENTITY keyutils-download-ftp  " ">
  <!ENTITY keyutils-md5sum        "6b70b2b381c1b6d9adfaf66d5d3e7c00">
  <!ENTITY keyutils-size          "136 KB">
  <!ENTITY keyutils-buildsize     "2.6 MB (with tests)">
  <!ENTITY keyutils-time          "less than 0.1 SBU (add 0.4 SBU for tests)">
]>

<sect1 id="keyutils" xreflabel="keyutils-&keyutils-version;">
  <?dbhtml filename="keyutils.html"?>


  <title>keyutils-&keyutils-version;</title>

  <indexterm zone="keyutils">
    <primary sortas="a-keyutils">keyutils</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to keyutils</title>

    <para>
      <application>Keyutils</application> is a set of utilities for managing
      the key retention facility in the kernel, which can be used by
      filesystems, block devices and more to gain and retain the authorization
      and encryption keys required to perform secure operations.
    </para>

    &lfs121_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&keyutils-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&keyutils-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &keyutils-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &keyutils-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &keyutils-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &keyutils-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Keyutils Dependencies</bridgehead>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="lsb-tools"/> (referred by the test suite)
    </para>
  </sect2>

  <sect2 role="kernel" id="keyutils-test-kernel"
         xreflabel="Keyutils Kernel Configuration">
    <title>Kernel Configuration</title>

    <para>
      If running the test suite, some tests needs the following kernel
      features enabled:
    </para>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="keyutils-test-kernel.xml"/>

    <indexterm zone="keyutils keyutils-test-kernel">
      <primary sortas="d-keyutils">keyutils (testing)</primary>
    </indexterm>
  </sect2>
  <sect2 role="installation">
    <title>Installation of keyutils</title>

    <para>
      Install <application>keyutils</application> by running the following
      commands:
    </para>

<screen><userinput>make</userinput></screen>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make NO_ARLIB=1 LIBDIR=/usr/lib BINDIR=/usr/bin SBINDIR=/usr/sbin install</userinput></screen>

    <para>
      The test suite can only run after installing this package.
      To test the results, issue, as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root" remap="test"><userinput>make -k test</userinput></screen>

    <para>
      If <xref linkend='lsb-tools'/> is not installed, the test suite will
      output some lines complaining the <command>lsb_release</command>
      command not available but it won't affect the test result.  One test
      named <literal>TRY ADDING ASYMMETRIC KEYS</literal> is known to fail
      due to the removal of the support for SHA1 with RSA signature
      algorithm from Linux kernel version 6.7 <!-- commit 16ab7cb5825f -->
      or newer.
    </para>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

<!--
    <para>
      <command>sed ... Makefile</command>: This command ensures the pkgconfig
      file is placed in the correct directory.
    </para>

    <para>
      <command>sed ... tests/toolbox.inc.sh</command>: In LFS, GCC has been
      configured with <option>- -enable-default-pie</option> so
      <command>/usr/bin/bash</command> is a PIE, but the test script does
      not anticipate it.  Fix this oversight so the test can run on a LFS
      system.
    </para>
-->

    <para>
      <parameter>NO_ARLIB=1</parameter>: This make flag disables installing the
      static library.
    </para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring keyutils</title>

    <sect3 id="keyutils-config">
      <title>Config Files</title>

      <para>
        <filename>/etc/request-key.conf</filename> and
        <filename>/etc/request-key.d/*</filename>
      </para>

      <indexterm zone="keyutils keyutils-config">
        <primary sortas="e-etc-request-key.conf">/etc/request-key.conf</primary>
      </indexterm>

      <indexterm zone="keyutils keyutils-config">
        <primary sortas="e-etc-request-key.d">/etc/request-key.d/*</primary>
      </indexterm>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Library</segtitle>
      <segtitle>Installed Directory</segtitle>

      <seglistitem>
        <seg>keyctl, key.dns_resolver, and request-key</seg>
        <seg>libkeyutils.so</seg>
        <seg>/etc/keyutils,
        /etc/request-key.d,
        and /usr/share/keyutils</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="keyctl">
        <term><command>keyctl</command></term>
        <listitem>
          <para>
            controls the key management facility with a variety of subcommands
          </para>
          <indexterm zone="keyutils keyctl">
            <primary sortas="b-keyctl">keyctl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="key.dns_resolver">
        <term><command>key.dns_resolver</command></term>
        <listitem>
          <para>
            is invoked by <command>request-key</command> on behalf of the
            kernel when kernel services (such as NFS, CIFS and AFS) need to
            perform a hostname lookup and the kernel does not have the key
            cached.  It is not ordinarily intended to be called directly
          </para>
          <indexterm zone="keyutils key.dns_resolver">
            <primary sortas="b-key.dns_resolver">key.dns_resolver</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="request-key">
        <term><command>request-key</command></term>
        <listitem>
          <para>
            is invoked by the kernel when the kernel is asked for a key that it
            doesn't have immediately available. The kernel creates a temporary
            key and then calls out to this program to instantiate it.  It is
            not intended to be called directly
          </para>
          <indexterm zone="keyutils request-key">
            <primary sortas="b-request-keyt-key">request-key</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libkeyutils">
        <term><filename class="libraryfile">libkeyutils.so</filename></term>
        <listitem>
          <para>
            contains the keyutils library API instantiation
          </para>
          <indexterm zone="keyutils libkeyutils">
            <primary sortas="c-libkeyutils">libkeyutils.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>