README

   1                        The GNU Privacy Guard
   2                       =======================
   3                             Version 2.4
   4
   5           Copyright 1997-2019 Werner Koch
   6           Copyright 1998-2021 Free Software Foundation, Inc.
   7           Copyright 2003-2023 g10 Code GmbH
   8
   9
  10 * INTRODUCTION
  11
  12   GnuPG is a complete and free implementation of the OpenPGP standard
  13   as defined by RFC4880 (also known as PGP).  GnuPG enables encryption
  14   and signing of data and communication, and features a versatile key
  15   management system as well as access modules for public key
  16   directories.
  17
  18   GnuPG, also known as GPG, is a command line tool with features for
  19   easy integration with other applications.  A wealth of frontend
  20   applications and libraries are available that make use of GnuPG.
  21   Starting with version 2 GnuPG provides support for S/MIME and Secure
  22   Shell in addition to OpenPGP.
  23
  24   GnuPG is Free Software (meaning that it respects your freedom). It
  25   can be freely used, modified and distributed under the terms of the
  26   GNU General Public License.
  27
  28 * BUILD INSTRUCTIONS
  29
  30   GnuPG 2.4 depends on the following GnuPG related packages:
  31
  32     npth         (https://gnupg.org/ftp/gcrypt/npth/)
  33     libgpg-error (https://gnupg.org/ftp/gcrypt/libgpg-error/)
  34     libgcrypt    (https://gnupg.org/ftp/gcrypt/libgcrypt/)
  35     libksba      (https://gnupg.org/ftp/gcrypt/libksba/)
  36     libassuan    (https://gnupg.org/ftp/gcrypt/libassuan/)
  37
  38   You should get the latest versions of course, the GnuPG configure
  39   script complains if a version is not sufficient.
  40
  41   Several other standard libraries are also required.  The configure
  42   script prints diagnostic messages if one of these libraries is not
  43   available and a feature will not be available..
  44
  45   You also need the Pinentry package for most functions of GnuPG;
  46   however it is not a build requirement.  Pinentry is available at
  47   https://gnupg.org/ftp/gcrypt/pinentry/ .
  48
  49   After building and installing the above packages in the order as
  50   given above, you may continue with GnuPG installation (you may also
  51   just try to build GnuPG to see whether your already installed
  52   versions are sufficient).
  53
  54   As with all packages, you just have to do
  55
  56     mkdir build
  57     cd build
  58     ../configure
  59     make
  60     make check
  61     make install
  62
  63   The "make check" is optional but highly recommended.  To run even
  64   more tests you may add "--enable-all-tests" to the configure run.
  65   Before running the "make install" you might need to become root.
  66
  67   If everything succeeds, you have a working GnuPG with support for
  68   OpenPGP, S/MIME, ssh-agent, and smartcards.
  69
  70   In case of problem please ask on the gnupg-users@gnupg.org mailing
  71   list for advise.
  72
  73   Instruction on how to build for Windows can be found in the file
  74   doc/HACKING in the section "How to build an installer for Windows".
  75   This requires some experience as developer.
  76
  77   You may run
  78
  79     gpgconf -L
  80
  81   to view the directories used by GnuPG.
  82
  83   To quickly build all required software without installing it, the
  84   Speedo method may be used:
  85
  86     cd build
  87     make -f ../build-aux/speedo.mk  native
  88
  89   This method downloads all required libraries and does a native build
  90   of GnuPG to PLAY/inst/.  GNU make is required and you need to set
  91   LD_LIBRARY_PATH to $(pwd)/PLAY/inst/lib to test the binaries.
  92
  93 ** Specific build problems on some machines:
  94
  95 *** Apple OSX 10.x using XCode
  96
  97   On some versions the correct location of a header file can't be
  98   detected by configure.  To fix that you should run configure like
  99   this
 100
 101     ./configure  gl_cv_absolute_stdint_h=/usr/include/stdint.h
 102
 103   Add other options as needed.
 104
 105
 106 *** Systems without a full C99 compiler
 107
 108   If you run into problems with your compiler complaining about dns.c
 109   you may use
 110
 111     ./configure --disable-libdns
 112
 113   Add other options as needed.
 114
 115
 116
 117 * RECOMMENDATIONS
 118
 119 ** Key database daemon
 120
 121   Since version 2.3.0 it is possible to store the keys in an SQLite
 122   database instead of the keyring.kbx file.  This is in particular
 123   useful for large keyrings or if many instances of gpg and gpgsm may
 124   run concurrently.  This is implemented using another daemon process,
 125   the "keyboxd".  To enable the use of the keyboxd put the option
 126   "use-keyboxd" into the configuration file ~/.gnupg/common.conf or the
 127   global /etc/gnupg/common.conf.  See also doc/examples/common.conf.
 128   Only public keys and X.509 certificates are managed by the keyboxd;
 129   private keys are still stored as separate files.
 130
 131   Since version 2.4.1 the keyboxd will be used by default for a fresh
 132   install; i.e. if a ~/.gnupg directory did not yet exist.
 133
 134   Note that there is no automatic migration; if the use-keyboxd option
 135   is enabled keys are not taken from pubring.kbx.  To migrate existing
 136   keys to the keyboxd do this:
 137
 138   1. Disable the keyboxd (remove use-keyboxd from common.conf)
 139   2. Export all public keys
 140        gpg --export --export-options backup  > allkeys.gpg
 141        gpgsm --export --armor                > allcerts.gpg
 142   3. Enable the keyboxd (add use-keyboxd to common.conf)
 143   4. Import all public keys
 144        gpg --import --import-options restore < allkeys.gpg
 145        gpgsm --import                        < allcerts.crt
 146
 147 ** Socket directory
 148
 149   GnuPG uses Unix domain sockets to connect its components (on Windows
 150   an emulation of these sockets is used).  Depending on the type of
 151   the file system, it is sometimes not possible to use the GnuPG home
 152   directory (i.e. ~/.gnupg) as the location for the sockets.  To solve
 153   this problem GnuPG prefers the use of a per-user directory below the
 154   the /run (or /var/run) hierarchy for the sockets.  It is thus
 155   suggested to create per-user directories on system or session
 156   startup.  For example, the following snippet can be used in
 157   /etc/rc.local to create these directories:
 158
 159       [ ! -d /run/user ] && mkdir /run/user
 160       awk -F: </etc/passwd '$3 >= 1000 && $3 < 65000 {print $3}' \
 161         | ( while read uid rest; do
 162               if [ ! -d "/run/user/$uid" ]; then
 163                 mkdir /run/user/$uid
 164                 chown $uid /run/user/$uid
 165                 chmod 700 /run/user/$uid
 166               fi
 167             done )
 168
 169
 170 * DOCUMENTATION
 171
 172   The complete documentation is in the texinfo manual named
 173   `gnupg.info'.  Run "info gnupg" to read it.  If you want a
 174   printable copy of the manual, change to the "doc" directory and
 175   enter "make pdf" For a HTML version enter "make html" and point your
 176   browser to gnupg.html/index.html.  Standard man pages for all
 177   components are provided as well.  An online version of the manual is
 178   available at [[https://gnupg.org/documentation/manuals/gnupg/]] .  A
 179   version of the manual pertaining to the current development snapshot
 180   is at [[https://gnupg.org/documentation/manuals/gnupg-devel/]] .
 181
 182
 183 * Using the legacy version GnuPG 1.4
 184
 185   The 1.4 version of GnuPG is only intended to allow decryption of old
 186   data material using legacy keys which are not anymore supported by
 187   GnuPG 2.x.  To install both versions alongside, it is suggested to
 188   rename the 1.4 version of "gpg" to "gpg1" as well as the
 189   corresponding man page.  Newer releases of the 1.4 branch will
 190   likely do this by default.
 191
 192
 193 * HOW TO GET MORE INFORMATION
 194
 195   A description of new features and changes since version 2.1 can be
 196   found in the file "doc/whats-new-in-2.1.txt" and online at
 197   "https://gnupg.org/faq/whats-new-in-2.1.html" .
 198
 199   The primary WWW page is "https://gnupg.org"
 200   The primary FTP site is "https://gnupg.org/ftp/gcrypt/"
 201
 202   See [[https://gnupg.org/download/mirrors.html]] for a list of
 203   mirrors and use them if possible.  You may also find GnuPG mirrored
 204   on some of the regular GNU mirrors.
 205
 206   We have some mailing lists dedicated to GnuPG:
 207
 208      gnupg-announce@gnupg.org   For important announcements like new
 209                                 versions and such stuff.  This is a
 210                                 moderated list and has very low traffic.
 211                                 Do not post to this list.
 212
 213      gnupg-users@gnupg.org      For general user discussion and
 214                                 help.
 215
 216      gnupg-devel@gnupg.org      GnuPG developers main forum.
 217
 218   You subscribe to one of the list by sending mail with a subject of
 219   "subscribe" to x-request@gnupg.org, where x is the name of the
 220   mailing list (gnupg-announce, gnupg-users, etc.). See
 221   https://gnupg.org/documentation/mailing-lists.html for archives
 222   of the mailing lists.
 223
 224   Please direct bug reports to [[https://bugs.gnupg.org]] or post them
 225   direct to the mailing list <gnupg-devel@gnupg.org>.
 226
 227   Please direct questions about GnuPG to the users mailing list or one
 228   of the PGP newsgroups; please do not direct questions to one of the
 229   authors directly as we are busy working on improvements and bug
 230   fixes.  The mailing lists are watched by the authors and we try to
 231   answer questions as time allows us.
 232
 233   Commercial grade support for GnuPG is available; for a listing of
 234   offers see https://gnupg.org/service.html .  Maintaining and
 235   improving GnuPG requires a lot of time.  Since 2001, g10 Code GmbH,
 236   a German company owned and headed by GnuPG's principal author Werner
 237   Koch, is bearing the majority of these costs.
 238
 239 # This file is Free Software; as a special exception the authors gives
 240 # unlimited permission to copy and/or distribute it, with or without
 241 # modifications, as long as this notice is preserved. For conditions
 242 # of the whole package, please see the file COPYING.  This file is
 243 # distributed in the hope that it will be useful, but WITHOUT ANY
 244 # WARRANTY, to the extent permitted by law; without even the implied
 245 # warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 246 #
 247 # Local Variables:
 248 # mode:org
 249 # End: