source: postlfs/security/gnutls.xml@ 6075712

<?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 gnutls-download-http "&gnupg-http;/gnutls/v3.8/gnutls-&gnutls-version;.tar.xz">
  <!ENTITY gnutls-download-ftp  " ">
  <!ENTITY gnutls-md5sum        "46777802233eb7203d47a8b8880c8c90">
  <!ENTITY gnutls-size          "6.4 MB">
  <!ENTITY gnutls-buildsize     "154 MB (add 115 MB for tests)">
  <!ENTITY gnutls-time          "0.5 SBU (add 1.5 SBU for tests; both using parallelism=8)">
]>

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


  <title>GnuTLS-&gnutls-version;</title>

  <indexterm zone="gnutls">
    <primary sortas="a-GnuTLS">GnuTLS</primary>
  </indexterm>

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

    <para>
      The <application>GnuTLS</application> package contains libraries and
      userspace tools which provide a secure layer over a reliable transport
      layer. Currently the <application>GnuTLS</application> library implements
      the proposed standards by the IETF's TLS working group. Quoting from the
      <ulink url="https://datatracker.ietf.org/doc/rfc8446/">
        TLS 1.3 protocol specification
      </ulink>:
    </para>

    <para>
      <quote>
        TLS allows client/server applications to communicate over the Internet
        in a way that is designed to prevent eavesdropping, tampering, and
        message forgery.
      </quote>
    </para>

    <para>
      <application>GnuTLS</application> provides support for TLS 1.3, TLS 1.2,
      TLS 1.1, TLS 1.0, and (optionally) SSL 3.0 protocols. It also supports
      TLS extensions, including server name and max record size. Additionally,
      the library supports authentication using the SRP protocol, X.509
      certificates, and OpenPGP keys, along with support for the TLS
      Pre-Shared-Keys (PSK) extension, the Inner Application (TLS/IA)
      extension, and X.509 and OpenPGP certificate handling.
    </para>

    &lfs122_checked;

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

    <note>
      <para>
        When extracting this package tarball, it expands to the gnutls-3.8.7
        directory, instead of the expected gnutls-3.8.7.1 directory.
      </para>
    </note>

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

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="nettle"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="make-ca"/>,
      <xref linkend="libunistring"/>,
      <xref linkend="libtasn1"/>, and
      <xref linkend="p11-kit"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="brotli"/>,
      <xref linkend="doxygen"/>,
      <xref linkend="gtk-doc"/>,
      <xref linkend="libidn"/> or
      <xref linkend="libidn2"/>,
      <xref linkend="libseccomp"/>,
      <xref linkend="net-tools"/> (used during the test suite),
      <xref linkend="texlive"/> or <xref linkend="tl-installer"/>,
      <xref linkend="unbound"/> (to build the DANE library),
      <xref linkend="valgrind"/> (used during the test suite),
      <ulink url="&gnu-http;/autogen/">autogen</ulink>,
      <ulink url="https://cmocka.org/">cmocka</ulink> and
      <ulink url="https://ftp.debian.org/debian/pool/main/d/datefudge/">datefudge</ulink> (used during the test suite if the DANE library is built), and
      <ulink url="&sourceforge-dl;/trousers/">Trousers</ulink> (Trusted Platform Module support)
    </para>

    <note><para>
 <!-- Note that if you do not install <xref linkend="libtasn1"/>, an older
       3.8.0 includes minitasn1 4.19 which is current at the moment. ken -->
      Note that if you do not install <xref linkend="libtasn1"/>, a
      version shipped in the <application>GnuTLS</application> tarball will be
      used instead.
    </para></note>

  </sect2>

  <sect2 role="installation">
    <title>Installation of GnuTLS</title>

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

<screen><userinput>./configure --prefix=/usr \
            --docdir=/usr/share/doc/gnutls-&gnutls-version; \
            --with-default-trust-store-pkcs11="pkcs11:" &amp;&amp;
make</userinput></screen>
<!-- - -disable-rpath \
     Old gnutls versions (around 3.5) had a problem with rpath, because
     libraries in the build tree were linked with rpath pointing to the
     system libraries, so that tests failed. Present versions don't have
     this problem, and do exactly what is expected without using the
     disable-rpath option: rpath pointing to the build tree when libraries
     are first linked, but rpath removed when libraries are relinked at
     install time. -->

    <para>
      One test hangs the test procedure.  Disable it:
      <command>sed '/ocsp-must-staple-connection/d' -i tests/Makefile</command>.
      To test the results, now issue: <command>make check</command>.
    </para>

    <para>
      Now, install the package as the &root; user:
    </para>

<screen role="root"><userinput>make install</userinput></screen>

  </sect2>

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

    <para>
      <parameter>--with-default-trust-store-pkcs11="pkcs11:"</parameter>: This
      switch tells gnutls to use the PKCS #11 trust store as the default trust.
      Omit this switch if <xref linkend="p11-kit"/> is not installed.
    </para>
    <!-- see above
    <para>
      <parameter>- -disable-rpath</parameter>: This switch prevents building
      GnuTLS utilities and tests with hardcoded runtime library search path.
      Hardcoded rpath is unneeded for BLFS, and it causes test failures if
      an old version of GnuTLS is installed.
    </para>
    -->
    <para>
      <option>--with-default-trust-store-file=/etc/pki/tls/certs/ca-bundle.crt</option>:
      This switch tells <command>configure</command> where to find the
      legacy CA certificate bundle and to use it instead of PKCS #11 module
      by default. Use this if <xref linkend="p11-kit"/> is not installed.
    </para>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/gtk-doc-rebuild.xml"/>

    <para>
      <option>--enable-openssl-compatibility</option>:
      Use this switch if you wish to build the OpenSSL compatibility library.
    </para>

    <para>
      <option>--without-p11-kit</option>: use this switch if you have not
      installed <application>p11-kit</application>.
    </para>

    <para>
      <option>--with-included-unistring</option>: uses the bundled version of
      libunistring, instead of the system one. Use this switch if you have not
      installed <xref linkend="libunistring"/>.
    </para>

    <para>
      <option>--disable-dsa</option>: completely disables DSA algorithm support.
    </para>

  </sect2>

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

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

      <seglistitem>
        <seg>
          certtool,
          danetool,
          gnutls-cli,
          gnutls-cli-debug,
          gnutls-serv,
          ocsptool,
          p11tool,
          psktool, and
          srptool
        </seg>
        <seg>
          libgnutls.so,
          libgnutls-dane.so,
          libgnutlsxx.so, and
          libgnutls-openssl.so (optional)
        </seg>
        <seg>
          /usr/include/gnutls and
          /usr/share/doc/gnutls-&gnutls-version;
        </seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="certtool">
        <term><command>certtool</command></term>
        <listitem>
          <para>
            is used to generate X.509 certificates, certificate requests,
            and private keys
          </para>
          <indexterm zone="gnutls certtool">
            <primary sortas="b-certtool">certtool</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="danetool">
        <term><command>danetool</command></term>
        <listitem>
          <para>
            is a tool used to generate and check DNS resource records
            for the DANE protocol
          </para>
          <indexterm zone="gnutls danetool">
            <primary sortas="b-danetool">danetool</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gnutls-cli">
        <term><command>gnutls-cli</command></term>
        <listitem>
          <para>
            is a simple client program to set up a TLS connection to some
            other computer
          </para>
          <indexterm zone="gnutls gnutls-cli">
            <primary sortas="b-gnutls-cli">gnutls-cli</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gnutls-cli-debug">
        <term><command>gnutls-cli-debug</command></term>
        <listitem>
          <para>
            is a simple client program to set up a TLS connection to some
            other computer and produces very verbose progress results
          </para>
          <indexterm zone="gnutls gnutls-cli-debug">
            <primary sortas="b-gnutls-cli-debug">gnutls-cli-debug</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gnutls-serv">
        <term><command>gnutls-serv</command></term>
        <listitem>
          <para>
            is a simple server program that listens to incoming TLS
            connections
          </para>
          <indexterm zone="gnutls gnutls-serv">
            <primary sortas="b-gnutls-serv">gnutls-serv</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ocsptool">
        <term><command>ocsptool</command></term>
        <listitem>
          <para>
            is a program that can parse and print information about OCSP
            requests/responses, generate requests and verify responses
          </para>
          <indexterm zone="gnutls ocsptool">
            <primary sortas="b-ocsptool">ocsptool</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="p11tool">
        <term><command>p11tool</command></term>
        <listitem>
          <para>
            is a program that allows handling data from PKCS #11 smart cards
            and security modules
          </para>
          <indexterm zone="gnutls p11tool">
            <primary sortas="b-p11tool">p11tool</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="psktool">
        <term><command>psktool</command></term>
        <listitem>
          <para>
            is a simple program that generates random keys for use with TLS-PSK
          </para>
          <indexterm zone="gnutls psktool">
            <primary sortas="b-psktool">psktool</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="srptool">
        <term><command>srptool</command></term>
        <listitem>
          <para>
            is a simple program that emulates the programs in the Stanford
            SRP (Secure Remote Password) libraries using GnuTLS
          </para>
          <indexterm zone="gnutls srptool">
            <primary sortas="b-srptool">srptool</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libgnutls">
        <term><filename class="libraryfile">libgnutls.so</filename></term>
        <listitem>
          <para>
            contains the core API functions and X.509 certificate API functions
          </para>
          <indexterm zone="gnutls libgnutls">
            <primary sortas="c-libgnutls">libgnutls.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>