source: postlfs/security/gnutls.xml@ 8cb62480

<?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 gnutls-download-http "&gnupg-http;/gnutls/v3.6/gnutls-&gnutls-version;.tar.xz">
  <!ENTITY gnutls-download-ftp  "&gnupg-ftp;/gnutls/v3.6/gnutls-&gnutls-version;.tar.xz">
  <!ENTITY gnutls-download-ftp  " ">
  <!ENTITY gnutls-md5sum        "92a8049e618afa60e2c852da1884c457">
  <!ENTITY gnutls-size          "7.8 MB">
  <!ENTITY gnutls-buildsize     "142 MB (add 99 MB for tests)">
  <!ENTITY gnutls-time          "0.6 SBU (using parallelism=4; add 7.7 SBU for tests)">
]>

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

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

  <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
      TLS protocol specification:
    </para>

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

    <para>
      <application>GnuTLS</application> provides support for TLS 1.3, TLS 1.2, TLS 1.1,
      TLS 1.0, and SSL 3.0 protocols, 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>

    &lfs84_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>

    <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="doxygen"/>,
      <xref linkend="gtk-doc"/>,
      <xref linkend="guile"/>,
      <xref linkend="libidn"/> or 
      <xref linkend="libidn2"/>
      <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="http://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
      version shipped in the <application>GnuTLS</application> tarball will be
      used instead.
    </para></note>

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

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

    <!-- Remove this at 3.6.8 or 3.7.0 -->
    <note><para>
      The package tarball extracts into directory gnutls-3.6.7, instead of
      gnutls-&gnutls-version;.
    </para></note>

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

<screen><userinput>./configure --prefix=/usr \
            --docdir=/usr/share/doc/gnutls-&gnutls-version; \
            --disable-guile \
            --with-default-trust-store-pkcs11="pkcs11:" &amp;&amp;
make</userinput></screen>

    <para>
      To test the results, issue: <command>make check</command>.  If a prior
      version of <application>GnuTLS</application> (or the same version but
      without all of the recommended dependencies) has been installed, some
      tests may fail. If <filename>/usr/lib/libgnutls.so</filename> and the
      target of that symlink are moved or renamed so that they cannot be found,
      all tests should pass and the install procedure will restore
      <filename>libgnutls.so</filename> and the versioned library it points to.
    </para>

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

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

    <para>
      If you passed <option>--enable-gtk-doc</option> to the
      <command>configure</command> script, the API will automatically be
      installed.  Otherwise, if desired, you can still install the API
      documentation to the <filename
      class="directory">/usr/share/gtk-doc/html/gnutls</filename> directory
      using the following command as the <systemitem
      class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make -C doc/reference install-data-local</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>

    <para>
      <parameter>--disable-guile</parameter>: This switch disables GUILE support,
      since GnuTLS does not support Guile-2.2.x yet.
    </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>

  </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,
          libgnutls-openssl.so (optional), and
          /usr/lib/guile/2.2/guile-gnutls-v-2.so
        </seg>
        <seg>
          /usr/{include,share/gtk-doc/html,share/guile/site/2.2}/gnutls
        </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>