README

   1                     Libgcrypt - The GNU Crypto Library
   2                    ------------------------------------
   3                              Version 1.10
   4
   5        Copyright (C) 1989,1991-2018 Free Software Foundation, Inc.
   6        Copyright (C) 2012-2022 g10 Code GmbH
   7        Copyright (C) 2013-2022 Jussi Kivilinna
   8
   9     Libgcrypt is free software.  See the file AUTHORS for full copying
  10     notices, and LICENSES for notices about contributions that require
  11     these additional notices to be distributed.
  12
  13
  14     Overview
  15     --------
  16
  17     Libgcrypt is a general purpose crypto library based on the code
  18     used in GnuPG.  Libgcrypt depends on the library `libgpg-error',
  19     which must be installed correctly before Libgcrypt is to be built.
  20     Libgcrypt is distributed under the LGPL, see the section "License"
  21     below for details.
  22
  23
  24     Build Instructions
  25     ------------------
  26
  27     The download canonical location for libgcrypt is:
  28
  29       https://gnupg.org/ftp/gcrypt/libgcrypt/
  30
  31     To build libgcrypt you need libgpg-error:
  32
  33       https://gnupg.org/ftp/gcrypt/libgpg-error/
  34
  35     You should get the latest versions of course.
  36
  37     After building and installing the libgpg-error package, you may
  38     continue with Libgcrypt installation as with allmost all GNU
  39     packages, you just have to do
  40
  41        ./configure
  42        make
  43        make check
  44        make install
  45
  46     The "make check" is not required but a good idea to see whether
  47     the library works as expected.  The check takes some while and
  48     prints some benchmarking results.  Before doing "make install" you
  49     probably need to become root.
  50
  51     To build libgcrypt for Microsoft Windows, you need to have the
  52     mingw32 cross-building toolchain installed.  Instead of running a
  53     plain configure you use
  54
  55       ./autogen.sh --build-w32
  56       make
  57       make install
  58
  59     By default this command sequences expectsd a libgpg-error
  60     installed below $HOME/w32root and installs libgcrypt to that
  61     directory too.  See the autogen.sh code for details.
  62
  63     The documentation is available as an Info file (gcrypt.info).  To
  64     build documentation in PDF, run this:
  65
  66       cd doc
  67       make pdf
  68
  69
  70
  71     Mailing List
  72     ------------
  73
  74     You may want to join the developer's mailing list
  75     gcrypt-devel@gnupg.org by sending mail with a subject of
  76     "subscribe" to gcrypt-devel-request@gnupg.org.  An archive of this
  77     list is available at https://lists.gnupg.org .
  78
  79
  80     Configure options
  81     -----------------
  82     Here is a list of configure options which are sometimes useful
  83     for installation.
  84
  85      --enable-large-data-tests
  86                      With this option a "make check" will take really
  87                      long due to extra checks for the hash algorithms.
  88
  89      --enable-m-guard
  90                      Enable the integrated malloc checking code. Please
  91                      note that this feature does not work on all CPUs
  92                      (e.g. SunOS 5.7 on UltraSparc-2) and might give
  93                      you a bus error.
  94
  95      --disable-asm
  96                      Do not use assembler modules.  It is not possible
  97                      to use this on some CPU types.
  98
  99      --enable-ld-version-script
 100                      Libgcrypt tries to build a library where internal
 101                      symbols are not exported.  This requires support
 102                      from ld and is currently enabled for a few OSes.
 103                      If you know that your ld supports the so called
 104                      ELF version scripts, you can use this option to
 105                      force its use.  OTOH, if you get error message
 106                      from the linker, you probably want to use this
 107                      option to disable the use of version scripts.
 108                      Note, that you should never ever use an
 109                      undocumented symbol or one which is prefixed with
 110                      an underscore.
 111
 112      --enable-ciphers=list
 113      --enable-pubkey-ciphers=list
 114      --enable-digests=list
 115                      If not otherwise specified, all algorithms
 116                      included in the libgcrypt source tree are built.
 117                      An exception are algorithms, which depend on
 118                      features not provided by the system, like 64bit
 119                      data types.  With these switches it is possible
 120                      to select exactly those algorithm modules, which
 121                      should be built.  The algorithms are to be
 122                      separated by spaces, commas or colons.  To view
 123                      the list used with the current build the program
 124                      tests/version may be used.
 125
 126      --disable-endian-check
 127                      Don't let configure test for the endianness but
 128                      try to use the OS provided macros at compile
 129                      time.  This is helpful to create OS X fat binaries.
 130
 131      --enable-random-daemon
 132                      Include support for a global random daemon and
 133                      build the daemon.  This is an experimental feature.
 134
 135      --enable-mpi-path=EXTRA_PATH
 136                      Prepend EXTRA_PATH to list of CPU specific
 137                      optimizations.  For example, if you want to add
 138                      optimizations forn a Intel Pentium 4 compatible
 139                      CPU, you may use
 140                         --enable-mpi-path=pentium4/sse2:pentium4/mmx
 141                      Take care: The generated library may crash on
 142                      non-compatible CPUs.
 143
 144      --enable-random=NAME
 145                      Force the use of the random gathering module
 146                      NAME.  Default is either to use /dev/random or
 147                      the auto mode.  Possible values for NAME are:
 148                        egd - Use the module which accesses the
 149                              Entropy Gathering Daemon. See the webpages
 150                              for more information about it.
 151                       unix - Use the standard Unix module which does not
 152                              have a very good performance.
 153                      linux - Use the module which accesses /dev/random.
 154                              This is the first choice and the default one
 155                              for GNU/Linux or *BSD.
 156                       auto - Compile linux, egd and unix in and
 157                              automagically select at runtime.
 158
 159      --enable-hmac-binary-check
 160                      Include support to check the binary at runtime
 161                      against a HMAC checksum.  This works only in FIPS
 162                      mode on systems providing the dladdr function and using
 163                      the ELF binary format.
 164
 165      --with-fips-module-version=version
 166                      Specify a string used as a module version for FIPS
 167                      certification purposes.
 168
 169      --disable-padlock-support
 170                      Disable support for the PadLock engine of VIA
 171                      processors.  The default is to use PadLock if
 172                      available.  Try this if you get problems with
 173                      assembler code.
 174
 175      --disable-aesni-support
 176                      Disable support for the AES-NI instructions of
 177                      newer Intel CPUs.  The default is to use AES-NI
 178                      if available.  Try this if you get problems with
 179                      assembler code.
 180
 181      --disable-O-flag-munging
 182                      Some code is too complex for some compilers while
 183                      in higher optimization modes, thus the compiler
 184                      invocation is modified to use a lower
 185                      optimization level.  Usually this works very well
 186                      but on some platforms these rules break the
 187                      invocation.  This option may be used to disable
 188                      the feature under the assumption that either good
 189                      CFLAGS are given or the compiler can grok the code.
 190
 191
 192
 193
 194     Build Problems
 195     --------------
 196
 197     If you have a problem with a a certain release, please first check
 198     the Release-info URL given in the NEWS file.
 199
 200     We can't check all assembler files, so if you have problems
 201     assembling them (or the program crashes) use --disable-asm with
 202     ./configure.  If you opt to delete individual replacement files in
 203     hopes of using the remaining ones, be aware that the configure
 204     scripts may consider several subdirectories to get all available
 205     assembler files; be sure to delete the correct ones.  Never delete
 206     udiv-qrnnd.S in any CPU directory, because there may be no C
 207     substitute (in mpi/genereic).  Don't forget to delete
 208     "config.cache" and run "./config.status --recheck".  We got a few
 209     reports about problems using versions of gcc earlier than 2.96
 210     along with a non-GNU assembler (as).  If this applies to your
 211     platform, you can either upgrade gcc to a more recent version, or
 212     use the GNU assembler.
 213
 214     Some make tools are broken - the best solution is to use GNU's
 215     make.  Try gmake or grab the sources from a GNU archive and
 216     install them.
 217
 218     Specific problems on some machines:
 219
 220       * AArch64 (GCC 11.1 and 11.2)
 221
 222         Because of the bug in GCC (fixed in 11.3), with the option
 223         -O3, vectorization results wrong code for the function
 224         buf_eq_const.  Please use -O2 or -fno-tree-loop-vectorize.
 225
 226       * IBM RS/6000 running AIX
 227
 228         Due to a change in gcc (since version 2.8) the MPI stuff may
 229         not build. In this case try to run configure using:
 230             CFLAGS="-g -O2 -mcpu=powerpc" ./configure
 231
 232       * SVR4.2 (ESIX V4.2 cc)
 233
 234         Due to problems with the ESIX as(1), you probably want to do:
 235             CFLAGS="-O -K pentium" ./configure --disable-asm
 236
 237       * SunOS 4.1.4
 238
 239          ./configure ac_cv_sys_symbol_underscore=yes
 240
 241       * Sparc64 CPUs
 242
 243         We have reports about failures in the AES module when
 244         compiling using gcc (e.g. version 4.1.2) and the option -O3;
 245         using -O2 solves the problem.
 246
 247
 248     License
 249     -------
 250
 251     The library is distributed under the terms of the GNU Lesser
 252     General Public License (LGPL); see the file COPYING.LIB for the
 253     actual terms.
 254
 255     The helper programs as well as the documentation are distributed
 256     under the terms of the GNU General Public License (GPL); see the
 257     file COPYING for the actual terms.
 258
 259     The file LICENSES has notices about contributions that require
 260     that these additional notices are distributed.
 261
 262
 263     Contact
 264     -------
 265
 266     See the file AUTHORS.
 267
 268     Commercial grade support for Libgcrypt is available; for a listing
 269     of offers see https://www.gnupg.org/service.html .
 270
 271     Since 2001 maintenance and development of Libgcrypt is done by
 272     g10 Code GmbH and until 2021 mostly financed by donations.
 273
 274   This file is Free Software; as a special exception the authors gives
 275   unlimited permission to copy and/or distribute it, with or without
 276   modifications, as long as this notice is preserved. For conditions
 277   of the whole package, please see the file COPYING.  This file is
 278   distributed in the hope that it will be useful, but WITHOUT ANY
 279   WARRANTY, to the extent permitted by law; without even the implied
 280   warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.