source: postlfs/security/gnutls.xml@ 2a05c87

<?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 "http://ftp.gnu.org/gnu/gnutls/gnutls-&gnutls-version;.tar.xz">
  <!ENTITY gnutls-download-ftp  "ftp://ftp.gnu.org/gnu/gnutls/gnutls-&gnutls-version;.tar.xz">
  <!ENTITY gnutls-md5sum        "5e87bd73a237749e2acbbb7161f11d5e">
  <!ENTITY gnutls-size          "4.6 MB">
  <!ENTITY gnutls-buildsize     "120 MB">
  <!ENTITY gnutls-time          "1.6 SBU (including the test suite)">
]>

<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 a library 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.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>

    &lfs70_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">Optional</bridgehead>
    <para role="optional">
      <xref linkend="gtk-doc"/>,
      <xref linkend="guile"/>,
      <xref linkend="libidn"/>,
      <xref linkend="libtasn1"/>,
      <xref linkend="p11-kit"/> and
      <ulink url="http://valgrind.org/">Valgrind</ulink> (used during the test suite)</para>

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

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

  </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 &amp;&amp;
make</userinput></screen>

    <para>To test the results, issue: <command>make check</command>.</para>

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

<screen role="root"><userinput>make install &amp;&amp;
install -v -m755 -d /usr/share/doc/gnutls-&gnutls-version; &amp;&amp;
install -v -m644    doc/*.{html,png,eps,pdf,ps} doc/cyclo/*.html \
                    /usr/share/doc/gnutls-&gnutls-version; &amp;&amp;
cp -v -R            doc/credentials \
                    /usr/share/doc/gnutls-&gnutls-version;</userinput></screen>

    <para>If you did not pass the <option>--enable-gtk-doc</option> parameter
    to the <command>configure</command> script, 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>

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

  </sect2>

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

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

      <seglistitem>
        <seg>certtool, crywrap, gnutls-cli, gnutls-cli-debug, gnutls-serv,
        ocsptool, p11tool, psktool, and srptool</seg>
        <seg>libgnutls.{so,a}, libgnutls-openssl.{so,a}, and libgnutlsxx.{so,a}</seg>
        <seg>/usr/include/gnutls,
        /usr/share/doc/gnutls-&gnutls-version;, and
        /usr/share/gtk-doc/html/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="crywrap">
        <term><command>crywrap</command></term>
        <listitem>
          <para>is a simple wrapper that waits for TLS/SSL connections, and
          proxies them to an unencrypted location.</para>
          <indexterm zone="gnutls crywrap">
            <primary sortas="b-crywrap">crywrap</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 GNU TLS.</para>
          <indexterm zone="gnutls srptool">
            <primary sortas="b-srptool">srptool</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libgnutls">
        <term><filename class='libraryfile'>libgnutls.{so,a}</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,a}</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>