source: postlfs/security/gnutls.xml@ 38b68055

<?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://mirrors.kernel.org/gnu/gnutls/gnutls-&gnutls-version;.tar.bz2">
  <!ENTITY gnutls-download-ftp  "ftp://ftp.gnutls.org/pub/gnutls/gnutls-&gnutls-version;.tar.bz2">
  <!ENTITY gnutls-md5sum        "eb0a6d7d3cb9ac684d971c14f9f6d3ba">
  <!ENTITY gnutls-size          "6.4 MB">
  <!ENTITY gnutls-buildsize     "96 MB">
  <!ENTITY gnutls-time          "1.0 SBU (additional 1.2 SBU to run 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>

    &lfs65_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="libgcrypt"/></para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="gtk-doc"/>,
    <xref linkend="guile"/>,
    <xref linkend="libtasn1"/>,
    <ulink url="http://webscripts.softpedia.com/script/Development-Scripts-js/C-C-Library/libcfg--26570.html">libcfg+</ulink>, 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>

    <!-- <bridgehead renderas="sect4">Optional Debugging Libraries</bridgehead>
    <para role="optional"><ulink url="http://dmalloc.com/">Dmalloc</ulink> and
    <ulink url="http://perens.com/FreeSoftware/ElectricFence/">Electric Fence</ulink></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
    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>

    <!-- There is no need to add this switch. Why would anyone not want to
         use the system-installed copy instead of the mini-tasn included
         inthe gnutls sources?
    <para><option>-with-included-libtasn1</option>: This option forces
    the use of the shipped version of <application>libtasn1</application>,
    instead of the system's installed version.</para>
    -->

    <xi:include xmlns:xi="http://www.w3.org/2003/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 Directory</segtitle>

      <seglistitem>
        <seg>certtool, gnutls-cli, gnutls-cli-debug, gnutls-serv,
        psktool, and srptool</seg>
        <seg>libgnutls.{so,a}, libgnutls-extra.{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="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="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>