source: postlfs/security/gnupg2.xml@ 85d2158

<?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 gnupg2-download-http "&gnupg-http;/gnupg/gnupg-&gnupg2-version;.tar.bz2">
  <!-- Something is wrong with ftp server and it confuses curl when currency runs it -->
  <!-- <!ENTITY gnupg2-download-ftp  "&gnupg-ftp;/gnupg/gnupg-&gnupg2-version;.tar.bz2"> -->
  <!ENTITY gnupg2-download-ftp  " ">
  <!ENTITY gnupg2-md5sum        "fc13424af7747a5dd6edb6086ec0cb2f">
  <!ENTITY gnupg2-size          "6.3 MB">
  <!ENTITY gnupg2-buildsize     "99 MB (with all tests; add 24 MB for docs)">
  <!ENTITY gnupg2-time          "0.4 SBU (using parallelism=4; add 1.4 SBU for tests)">
]>

<sect1 id="gnupg2" xreflabel="GnuPG-&gnupg2-version;">
  <?dbhtml filename="gnupg.html"?>

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

  <title>GnuPG-&gnupg2-version;</title>

  <indexterm zone="gnupg2">
    <primary sortas="a-GnuPG">GnuPG</primary>
  </indexterm>

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

    <para>The <application>GnuPG</application> package is GNU's tool for
    secure communication and data storage. It can be used to encrypt data and
    to create digital signatures. It includes an advanced key management
    facility and is compliant with the proposed OpenPGP Internet standard as
    described in RFC2440 and the S/MIME standard as described by several RFCs.
    GnuPG 2 is the stable version of GnuPG integrating support for OpenPGP and
    S/MIME.</para>

    &lfs82_checked;

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

    <bridgehead renderas="sect3">GnuPG 2 Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="libassuan"/>,
      <xref linkend="libgcrypt"/>,
      <xref linkend="libgpg-error"/>,
      <xref linkend="libksba"/>, and
      <xref linkend="npth"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="pinentry"/> (Run-time requirement for most of
      the package's functionality)
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="curl"/>,
      <xref linkend="gnutls"/>,
      <xref linkend="imagemagick"/> (for the <command>convert</command> utility,
      used for generating the documentation),
      <xref linkend="libusb-compat"/>,
      an <xref linkend="server-mail"/>,
      <xref linkend="openldap"/>,
      <xref linkend="sqlite"/>,
      <xref linkend="texlive"/> (or <xref linkend="tl-installer"/>),
      <ulink url="http://mcj.sourceforge.net/">fig2dev</ulink> (for
      generating documentation),
      and <ulink url="http://www.chiark.greenend.org.uk/~ian/adns/">GNU
      adns</ulink>
    </para>

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

  </sect2>

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

    <warning>
      <para>
        If you are upgrading from gnupg prior to version 2.1, upstream
        developers recommend to backup
        <filename class="directory">~/.gnupg</filename>, because some additional
        configuration will probably be necessary, and you could lose your keys.
        You can find instructions at
        <ulink url="http://jo-ke.name/wp/?p=111"></ulink> and
        <ulink url="https://wiki.archlinux.org/index.php/GnuPG#.22Lost.22_keys.2C_upgrading_to_gnupg_version_2.1"></ulink>.
      </para>
    </warning>

    <para>If the top directory path where the source is unpacked contains
    symbolic links, the openpgp tests may fail. If this is your case and
    you wish to run the test suite, fix that with:</para>

<screen><userinput>sed -e '/noinst_SCRIPTS = gpg-zip/c sbin_SCRIPTS += gpg-zip' \
    -i tools/Makefile.in</userinput></screen>

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

<screen><userinput>./configure --prefix=/usr            \
            --enable-symcryptrun     \
            --docdir=/usr/share/doc/gnupg-&gnupg2-version; &amp;&amp;
make &amp;&amp;

makeinfo --html --no-split -o doc/gnupg_nochunks.html doc/gnupg.texi &amp;&amp;
makeinfo --plaintext       -o doc/gnupg.txt           doc/gnupg.texi</userinput></screen>

    <para>If you have <xref linkend="texlive"/>
    installed and you wish to create documentation in alternate formats,
    issue the following commands
    (<ulink url="http://mcj.sourceforge.net/">fig2dev</ulink> is needed for
    the ps format):</para>

<screen><userinput>make -C doc pdf ps html</userinput></screen>

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

    <para>Note that if you have already installed
    <application>GnuPG</application>, the instructions below will overwrite
    <filename>/usr/share/man/man1/gpg-zip.1</filename>. 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/gnupg-&gnupg2-version;/html            &amp;&amp;
install -v -m644    doc/gnupg_nochunks.html \
                    /usr/share/doc/gnupg-&gnupg2-version;/html/gnupg.html &amp;&amp;
install -v -m644    doc/*.texi doc/gnupg.txt \
                    /usr/share/doc/gnupg-&gnupg2-version;</userinput></screen>
<!-- Now intalls as gpg, not gpg2.  This should be no longer needed.
    <para>The BLFS editors recommend the creation of symlinks for compatibility
    with the first version of GnuPG, because some programs or scripts need
    them. Issue, as <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>for f in gpg gpgv
do
  ln -svf ${f}2.1 /usr/share/man/man1/$f.1 &amp;&amp;
  ln -svf ${f}2   /usr/bin/$f
done
unset f</userinput></screen>
-->
    <para>If you created alternate formats of the documentation, install it
    using the following command as the
    <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>install -v -m644 doc/gnupg.html/* \
                 /usr/share/doc/gnupg-&gnupg2-version;/html &amp;&amp;
install -v -m644 doc/gnupg.{pdf,dvi,ps} \
                 /usr/share/doc/gnupg-&gnupg2-version;</userinput></screen>

  </sect2>

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

    <para><command>sed ... tools/Makefile.in</command>:
    This command is needed to build the gpg-zip program.</para>

    <para><parameter>--docdir=/usr/share/doc/gnupg-&gnupg2-version;</parameter>:
    This switch changes the default docdir to <filename
    class="directory">/usr/share/doc/gnupg-&gnupg2-version;</filename>.</para>

    <para><parameter>--enable-symcryptrun</parameter>: This switch enables
    building the symcryptrun program.</para>

    <para>
      <option>--enable-all-tests</option>: allows more tests to be run whith
      <command>make check</command>.
    </para>
    <para><option>--enable-g13</option>: This switch enables building the
    g13 program.</para>

  </sect2>

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

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

      <seglistitem>
        <seg>addgnupghome, applygnupgdefaults, dirmngr, dirmngr-client, g13
        (optional), gpg-agent, gpg-connect-agent, gpg, gpgconf, gpgparsemail, 
        gpgscm, gpgsm, gpgtar, gpgv, gpg-zip, kbxutil, symcryptrun, 
        and watchgnupg</seg>
        <seg>None</seg>
        <seg>/usr/share/doc/gnupg-&gnupg2-version; and
        /usr/share/gnupg</seg>
      </seglistitem>
    </segmentedlist>

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

      <varlistentry id="addgnupghome">
        <term><command>addgnupghome</command></term>
        <listitem>
          <para>is used to create and populate user's
          <filename class='directory'>~/.gnupg</filename> directories</para>
          <indexterm zone="gnupg2 addgnupghome">
            <primary sortas="b-addgnupghome">addgnupghome</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="applygnupgdefaults">
        <term><command>applygnupgdefaults</command></term>
        <listitem>
          <para>is a wrapper script used to run <command>gpgconf</command>
          with the <parameter>--apply-defaults</parameter> parameter on all
          user's GnuPG home directories.</para>
          <indexterm zone="gnupg2 applygnupgdefaults">
            <primary sortas="b-applygnupgdefaults">applygnupgdefaults</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dirmngr">
        <term><command>dirmngr</command></term>
        <listitem>
          <para> is a tool that takes care of accessing the OpenPGP keyservers.
          </para>
          <indexterm zone="gnupg2 dirmngr">
            <primary sortas="b-dirmngr">dirmngr</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dirmngr-client">
        <term><command>dirmngr-client</command></term>
        <listitem>
          <para> is a tool to contact a running dirmngr and test whether a
          certificate has been revoked. </para>
          <indexterm zone="gnupg2 dirmngr-client">
            <primary sortas="b-dirmngr-client">dirmngr-client</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="g13">
        <term><command>g13</command></term>
        <listitem>
          <para>is a tool to create, mount or unmount an encrypted file system
          container (optional).</para>
          <indexterm zone="gnupg2 g13">
            <primary sortas="b-g13">g13</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gpg-agent">
        <term><command>gpg-agent</command></term>
        <listitem>
          <para>is a daemon used to manage secret (private) keys independently
          from any protocol. It is used as a backend for <command>gpg2</command>
          and <command>gpgsm</command> as well as for a couple of other
          utilities.</para>
          <indexterm zone="gnupg2 gpg-agent">
            <primary sortas="b-gpg-agent">gpg-agent</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gpg-connect-agent">
        <term><command>gpg-connect-agent</command></term>
        <listitem>
          <para>is a utility used to communicate with a running
          <command>gpg-agent</command>.</para>
          <indexterm zone="gnupg2 gpg-connect-agent">
            <primary sortas="b-gpg-connect-agent">gpg-connect-agent</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gpg">
        <term><command>gpg</command></term>
        <listitem>
          <para>is the OpenPGP part of the GNU Privacy Guard (GnuPG). It is a
          tool used to provide digital encryption and signing services using
          the OpenPGP standard.</para>
          <indexterm zone="gnupg2 gpg">
            <primary sortas="b-gpg">gpg</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gpgconf">
        <term><command>gpgconf</command></term>
        <listitem>
          <para>is a utility used to automatically and reasonably safely
          query and modify configuration files in the
          <filename class='directory'>~/.gnupg</filename> home directory. It is
          designed not to be invoked manually by the user, but automatically by
          graphical user interfaces.</para>
          <indexterm zone="gnupg2 gpgconf">
            <primary sortas="b-gpgconf">gpgconf</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gpgparsemail">
        <term><command>gpgparsemail</command></term>
        <listitem>
          <para>is a utility currently only useful for debugging. Run it with
          <parameter>--help</parameter> for usage information.</para>
          <indexterm zone="gnupg2 gpgparsemail">
            <primary sortas="b-gpgparsemail">gpgparsemail</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gpgscm">
        <term><command>gpgscm</command></term>
        <listitem>
          <para>executes the given scheme program or spawns an interactive
          shell.</para>
          <indexterm zone="gnupg2 gpgscm">
            <primary sortas="b-gpgscm">gpgscm</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gpgsm">
        <term><command>gpgsm</command></term>
        <listitem>
          <para>is a tool similar to <command>gpg2</command> used to provide
          digital encryption and signing services on X.509 certificates and the
          CMS protocol. It is mainly used as a backend for S/MIME mail
          processing.</para>
          <indexterm zone="gnupg2 gpgsm">
            <primary sortas="b-gpgsm">gpgsm</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gpgtar">
        <term><command>gpgtar</command></term>
        <listitem>
          <para> is a tool to encrypt or sign files into an archive.</para>
          <indexterm zone="gnupg2 gpgtar">
            <primary sortas="b-gpgtar">gpgtar</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gpgv">
        <term><command>gpgv</command></term>
        <listitem>
          <para>is a verify only version of <command>gpg2</command>.</para>
          <indexterm zone="gnupg2 gpgv">
            <primary sortas="b-gpgv">gpgv</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gpg-zip">
        <term><command>gpg-zip</command></term>
        <listitem>
          <para> encrypts or signs files into an archive.</para>
          <indexterm zone="gnupg2 gpg-zip">
            <primary sortas="b-gpg-zip">gpg-zip</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="kbxutil">
        <term><command>kbxutil</command></term>
        <listitem>
          <para>is used to list, export and import Keybox data.</para>
          <indexterm zone="gnupg2 kbxutil">
            <primary sortas="b-kbxutil">kbxutil</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="symcryptrun">
        <term><command>symcryptrun</command></term>
        <listitem>
          <para>is a simple symmetric encryption tool.</para>
          <indexterm zone="gnupg2 symcryptrun">
            <primary sortas="b-symcryptrun">symcryptrun</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="watchgnupg">
        <term><command>watchgnupg</command></term>
        <listitem>
          <para>is used to listen to a Unix Domain socket created by any of
          the GnuPG tools.</para>
          <indexterm zone="gnupg2 watchgnupg">
            <primary sortas="b-watchgnupg">watchgnupg</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>