source: postlfs/security/p11-kit.xml@ 64be6a1

<?xml version="1.0" encoding="ISO-8859-1"?>
<!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 p11-kit-download-http "https://github.com/p11-glue/p11-kit/releases/download/&p11-kit-version;/p11-kit-&p11-kit-version;.tar.gz">
  <!ENTITY p11-kit-download-ftp  " ">
  <!ENTITY p11-kit-md5sum        "85e1cdb5fce0087711ba2521975f0420">
  <!ENTITY p11-kit-size          "1.2 MB">
  <!ENTITY p11-kit-buildsize     "45 MB (add 168 MB for tests)">
  <!ENTITY p11-kit-time          "0.4 SBU (add 0.6 SBU for tests)">
]>

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

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>p11-kit-&p11-kit-version;</title>

  <indexterm zone="p11-kit">
    <primary sortas="a-p11-kit">p11-kit</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to p11-kit</title>

    <para>
      The <application>p11-kit</application> package provides a way to load and
      enumerate PKCS #11 (a Cryptographic Token Interface Standard) modules.
    </para>

    &lfs83_checked;

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

    <bridgehead renderas="sect3">p11-kit Dependencies</bridgehead>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="libtasn1"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="make-ca"/> (runtime), 
      <xref linkend="nss"/> (runtime),
      <xref linkend="gtk-doc"/> and
      <xref linkend="libxslt"/>
    </para>

    <para condition="html" role="usernotes">User Notes:
      <ulink url="&blfs-wiki;/p11-kit"/>
    </para>
  </sect2>

  <sect2 role="installation">
    <title>Installation of p11-kit</title>

    <para>Prepare the distribution specific anchor hook:</para>

<screen><userinput>sed '20,$ d' -i trust/trust-extract-compat.in &amp;&amp;
cat &gt;&gt; trust/trust-extract-compat.in &lt;&lt; "EOF"
<literal># LFS uses make-ca to manage certificates
if [ -f /etc/make-ca.conf ]; then
    . /etc/make-ca.conf
else
    #Use defaults if make-ca.conf does not exist
    ANCHORDIR="/etc/pki/anchors"
    ANCHORLIST="/etc/pki/anchors.txt"
    LOCALDIR="/etc/ssl/local"
    CERTLIST=""
fi

# Create a list of certificates not present at previous run
for ca in `/bin/ls -1 --color=none "${ANCHORDIR}"` ; do
    /bin/grep "${ca}" "${ANCHORLIST}" 2>&amp;1>/dev/null || CERTLIST="${CERTLIST} ${ca}"
done

# Dump to a temporary directory
TEMPDIR=`mktemp -d`
/usr/bin/trust extract --filter=certificates --format=openssl-directory --overwrite \
    "${TEMPDIR}"

# Copy new certificates to LOCALDIR
for certificate in `echo "${CERTLIST}"` ; do
    LABEL=`/bin/grep -m 1 "label:" "${ANCHORDIR}/${certificate}"`
    LABELNEW=`echo "${LABEL}" | /bin/sed -e 's@^label: @@' -e 's@"@@g' -e 's@ @_@g'`
    cp -v "${TEMPDIR}/${LABELNEW}.pem" "${LOCALDIR}"
    unset LABEL LABELNEW
done

# Clean up
rm -rf "${TEMPDIR}"
unset ANCHORDIR ANCHORLIST LOCALDIR CERTLIST TEMPDIR

# Generate a new trust store
/usr/sbin/make-ca -f</literal>
EOF</userinput></screen>

    <para>
      Install <application>p11-kit</application> by running the following
      commands:
    </para>

<screen><userinput>./configure --prefix=/usr     \
            --sysconfdir=/etc \
            --with-trust-paths=/etc/pki/anchors &amp;&amp;
make</userinput></screen>

    <para>
      To test the results, issue: <command>make check</command>. 
      One test, test-token 6, is known to fail.
    </para>

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

<screen role="root"><userinput>make install &amp;&amp;
ln -s /usr/libexec/p11-kit/trust-extract-compat \
      /usr/bin/update-ca-certificates</userinput></screen>

  </sect2>

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

    <para>
      <parameter>--with-trust-paths=/etc/pki/anchors</parameter>: this switch
      sets the location of trusted certificates used by libp11-kit.so.
    </para>

    <para>
      <option>--with-hash-impl=freebl</option>: Use this switch if you want to
      use the Freebl library from <application>NSS</application> for SHA1 and
      MD5 hashing.
    </para>

    <para>
      <option>--enable-doc</option>: Use this switch if you have installed
      <xref linkend="gtk-doc"/> and <xref linkend="libxslt"/> and wish to
      rebuild the documentation and generate manual pages.
    </para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring p11-kit</title>

    <para>The <application>p11-kit</application> trust module
    (<filename>/usr/lib/pkcs11/p11-kit-trust.so</filename>) can be used as a
    drop-in replacement for <filename>/usr/lib/libnssckbi.so</filename> to
    transparently make the system CAs available to
    <application>NSS</application> aware applications, rather than the static
    list provided by <filename>/usr/lib/libnssckbi.so</filename>. As the
    <systemitem class="username">root</systemitem> user, execute the following
    commands:</para>

<screen role="root"><userinput>if [ -e /usr/lib/libnssckbi.so ]; then
  readlink /usr/lib/libnssckbi.so ||
  rm -v /usr/lib/libnssckbi.so    &amp;&amp;
  ln -sfv ./pkcs11/p11-kit-trust.so /usr/lib/libnssckbi.so
fi</userinput></screen>

  </sect2>

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

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          p11-kit and trust
        </seg>
        <seg>
          libp11-kit.so and p11-kit-proxy.so
        </seg>
        <seg>
          /etc/pkcs11,
          /usr/include/p11-kit-1,
          /usr/lib/{p11-kit,pkcs11},
          /usr/share/gtk-doc/html/p11-kit, and
          /usr/share/p11-kit
        </seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="p11-kit-prog">
        <term><command>p11-kit</command></term>
        <listitem>
          <para>
            is a command line tool that can be used to perform operations
             on PKCS#11 modules configured on the system.
          </para>
          <indexterm zone="p11-kit p11-kit-prog">
            <primary sortas="b-p11-kit">p11-kit</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="trust">
        <term><command>trust</command></term>
        <listitem>
          <para>
            is a command line tool to examine and modify the shared trust
            policy store.
          </para>
          <indexterm zone="p11-kit trust">
            <primary sortas="b-trust">trust</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="update-ca-certificates">
        <term><command>update-ca-certificates</command></term>
        <listitem>
          <para>
            is a command line tool to both extract local certificates from an
            upadated anchor store, and regenerate all anchors and certificate
            stores on the system.
          </para>
          <indexterm zone="p11-kit update-ca-certificates">
            <primary sortas="b-trust">update-ca-certificates</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libp11-kit">
        <term><filename class="libraryfile">libp11-kit.so</filename></term>
        <listitem>
          <para>
            contains functions used to coordinate initialization and
            finalization of any PKCS#11 module.
          </para>
          <indexterm zone="p11-kit libp11-kit">
            <primary sortas="c-libp11-kit">libp11-kit.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="p11-kit-proxy">
        <term><filename class="libraryfile">p11-kit-proxy.so</filename></term>
        <listitem>
          <para>
            is the PKCS#11 proxy module.
          </para>
          <indexterm zone="p11-kit p11-kit-proxy">
            <primary sortas="c-p11-kit-proxy">p11-kit-proxy.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>