source: postlfs/security/gnupg2.xml@ 4af155c

<?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">
  <!ENTITY gnupg2-download-ftp  "&gnupg-ftp;/gnupg/gnupg-&gnupg2-version;.tar.bz2">
  <!ENTITY gnupg2-md5sum        "089420cb30eee527afee667c56bb6b2e">
  <!ENTITY gnupg2-size          "7.0 MB">
  <!ENTITY gnupg2-buildsize     "127 MB (with tests)">
  <!ENTITY gnupg2-time          "0.7 SBU (with tests; using parallelism=4)">
]>

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


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

    &lfs113_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="libksba"/>, and
      <xref linkend="npth"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="gnutls"/> (required to communicate with keyservers
      using https or hkps protocol) and
      <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="fuse3"/>,
      <xref linkend="imagemagick"/> (for the <command>convert</command> utility,
      used for generating the documentation),
      <xref linkend="libusb"/>,
      an <xref linkend="server-mail"/>,
      <xref linkend="openldap"/>,
      <xref linkend="sqlite"/>,
      <xref linkend="texlive"/> (or <xref linkend="tl-installer"/>),
      <ulink url="https://mcj.sourceforge.net/">fig2dev</ulink> (for
      generating documentation),
      and <ulink url="https://www.chiark.greenend.org.uk/~ian/adns/">GNU
      adns</ulink>
    </para>


  </sect2>

  <sect2 role="installation">
    <title>Installation of GnuPG</title>
<!--  This is useless with 2.3.x.  If we need gpg-zip we'll have to fetch
      it somewhere.
    <para>
      By default GnuPG doesn't install the deprecated gpg-zip script,
      but it is still needed by some programs.  Make GnuPG install it with:
    </para>

<screen><userinput>sed -e '/noinst_SCRIPTS = gpg-zip/c sbin_SCRIPTS += gpg-zip' \
    -i tools/Makefile.in</userinput></screen>
-->
<!-- fixed in 2.4.0
    <para>
      First, fix an issue causing build failure if
      <application>OpenLDAP</application> is not installed:
    </para>

<screen><userinput>sed -e '/ks_ldap_free_state/i #if USE_LDAP' \
    -e '/ks_get_state =/a #endif'           \
    -i dirmngr/server.c</userinput></screen>
-->
    <para>
      Install <application>GnuPG</application> by running the following
      commands:
    </para>

<screen><userinput>mkdir build &amp;&amp;
cd    build &amp;&amp;

../configure --prefix=/usr           \
             --localstatedir=/var    \
             --sysconfdir=/etc       \
             --docdir=/usr/share/doc/gnupg-&gnupg2-version; &amp;&amp;
make &amp;&amp;

makeinfo --html --no-split -I doc -o doc/gnupg_nochunks.html ../doc/gnupg.texi &amp;&amp;
makeinfo --plaintext       -I doc -o doc/gnupg.txt           ../doc/gnupg.texi &amp;&amp;
make -C doc html</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="https://mcj.sourceforge.net/">fig2dev</ulink> is needed for
      the ps format):
    </para>

<screen remap="doc"><userinput>make -C doc pdf ps</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; &amp;&amp;
install -v -m644    doc/gnupg.html/* \
                    /usr/share/doc/gnupg-&gnupg2-version;/html</userinput></screen>
    <para>
      If you created alternate formats of the documentation, install them
      using the following command as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"
        remap="doc"><userinput>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>
      <command>mkdir build &amp;&amp; cd build</command>: the Gnupg2
      developers recommend to build the package in a dedicated directory.
    </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>

<!-- Unrecognized in 2.2.26, seems to get built automatically now.
    <para>
      <parameter>- -enable-symcryptrun</parameter>: This switch enables
      building the symcryptrun program.
    </para>
-->
    <para>
      <option>--enable-all-tests</option>: This switch allows more tests to be
      run with <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-card, gpg-connect-agent, gpg, gpgconf,
        gpgparsemail, gpgscm, gpgsm, gpgsplit, gpgtar, gpgv, gpg-wks-client,
        gpg-wks-server, 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 a 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>gpg</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-card">
        <term><command>gpg-card</command></term>
        <listitem>
          <para>
            is a tool to manage smart cards and tokens
          </para>
          <indexterm zone="gnupg2 gpg-card">
            <primary sortas="b-gpg-card">gpg-card</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>gpg</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="gpgsplit">
        <term><command>gpgsplit</command></term>
        <listitem>
          <para>
            splits an OpenPGP message into packets
          </para>
          <indexterm zone="gnupg2 gpgsplit">
            <primary sortas="b-gpgsplit">gpgsplit</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>gpg</command>
          </para>
          <indexterm zone="gnupg2 gpgv">
            <primary sortas="b-gpgv">gpgv</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gpg-wks-client">
        <term><command>gpg-wks-client</command></term>
        <listitem>
          <para>
            is a client for the
            <application>Web Key Service</application> protocol
          </para>
          <indexterm zone="gnupg2 gpg-wks-client">
            <primary sortas="b-gpg-wks-client">gpg-wks-client</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="gpg-wks-server">
        <term><command>gpg-wks-server</command></term>
        <listitem>
          <para>
            provides a server for the
            <application>Web Key Service</application> protocol
          </para>
          <indexterm zone="gnupg2 gpg-wks-server">
            <primary sortas="b-gpg-wks-server">gpg-wks-server</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>