poly1305: silence compiler warning on clang/aarch64
[libgcrypt.git] / README
diff --git a/README b/README
index 9b0ec8c..c14181a 100644 (file)
--- a/README
+++ b/README
@@ -1,51 +1,75 @@
-                   libgcrypt - The GNU crypto library
+                   Libgcrypt - The GNU Crypto Library
                   ------------------------------------
-                           Version 1.1.90
+                             Version 1.7
 
-    THIS IS A PRE-RELEASE FOR THE FIRST STABLE VERSION 1.2.0, TO BE
-    RELEASED RSN.
+       Copyright (C) 1989,1991-2017 Free Software Foundation, Inc.
+       Copyright (C) 2012-2017 g10 Code GmbH
+       Copyright (C) 2013-2017 Jussi Kivilinna
 
+    Libgcrypt is free software.  See the file AUTHORS for full copying
+    notices, and LICENSES for notices about contributions that require
+    these additional notices to be distributed.
 
-    Copyright 2000, 2002, 2003 Free Software Foundation, Inc.
 
-    This file is free software; as a special exception the author gives
-    unlimited permission to copy and/or distribute it, with or without
-    modifications, as long as this notice is preserved.
+    Overview
+    --------
 
-    This file is distributed in the hope that it will be useful, but
-    WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
-    implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+    Libgcrypt is a general purpose crypto library based on the code
+    used in GnuPG.  Libgcrypt depends on the library `libgpg-error',
+    which must be installed correctly before Libgcrypt is to be built.
+    Libgcrypt is distributed under the LGPL, see the section "License"
+    below for details.
 
 
+    Build Instructions
+    ------------------
 
-    Overview
-    --------
+    The download canonical location for libgcrypt is:
 
-    Libgcrypt is a general purpose crypto library based on the code
-    used in GnuPG.  We can't start with a new version number because
-    libgcrypt was part of gnupg 1.1 and some applications already used
-    it and tested for the version number. We believe that the API can
-    stay as it is, except that new functions may be added in the
-    future.
+      ftp://ftp.gnupg.org/gcrypt/libgcrypt/
+    or
+      https://gnupg.org/ftp/gcrypt/libgcrypt/
+
+    To build libgcrypt you need libgpg-error:
 
-    Libgcrypt depends on the library `libgpg-error', which must be
-    installed correctly before Libgcrypt is to be built.
+      ftp://ftp.gnupg.org/gcrypt/libgpg-error/
+    or
+      https://gnupg.org/ftp/gcrypt/libgpg-error/
 
+    You should get the latest versions of course.
 
-    CVS
-    ---
+    After building and installing the libgpg-error package, you may
+    continue with Libgcrypt installation as with allmost all GNU
+    packages, you just have to do
 
-    If you are using the CVS version, make sure that you have the
-    latest GNU build tools installed and run ./autogen.sh before
-    trying to build the library.  Instead of running autogen.sh,
-    something like `autoreconf -i --symlink' can be used to prepare
-    the tree for building as well.
+       ./configure
+       make
+       make check
+       make install
+
+    The "make check" is not required but a good idea to see whether
+    the library works as expected.  The check takes some while and
+    prints some benchmarking results.  Before doing "make install" you
+    probably need to become root.
+
+    To build libgcrypt for Microsoft Windows, you need to have the
+    mingw32 cross-building toolchain installed.  Instead of running a
+    plain configure you use
+
+      ./autogen.sh --build-w32
+      make
+      make install
+
+    By default this command sequences expectsd a libgpg-error
+    installed below $HOME/w32root and installs libgcrypt to that
+    directory too.  See the autogen.sh code for details.
+
+    The documentation is available as an Info file (gcrypt.info).  To
+    build documentation in PDF, run this:
+
+      cd doc
+      make pdf
 
-    You also need to enable maintainer mode at configure time with the
-    `--enable-maintainer-mode' configure switch; without this switch,
-    the documentation can not be build, since the file `version.texi',
-    which is needed for building the documentation, will only be
-    generated, if maintainer mode is enabled.
 
 
     Mailing List
     You may want to join the developer's mailing list
     gcrypt-devel@gnupg.org by sending mail with a subject of
     "subscribe" to gcrypt-devel-request@gnupg.org.  An archive of this
-    list is available at http://lists.gnupg.org .
+    list is available at https://lists.gnupg.org .
 
 
-    License
-    -------
-    
-    Most of this library is distributed under the terms of the GNU
-    Lesser General Public License (LGPL); see the file COPYING.LIB for
-    the actual terms.  However some parts are distributed under the
-    GNU General Public License (GPL) so if you configure Libgcrypt to
-    include these modules, you have to comply with the conditions of
-    the GPL as found in the file COPYING.  The modules under the GPL
-    are:
-
-      rndunix - Entropy gatherer for Unices without a /dev/random
-      rndw32  - Entropy gatherer for MS Windows
-
-    The documentation is available under the terms of the GNU Free
-    Documentation License; see the file COPYING.DOC for the terms.
-
-    This library used to be available under the GPL - this was changed
-    with version 1.1.7 with the rationale that there are now many free
-    crypto libraries available and many of them come with capabilities
-    similar to Libcrypt.  We decided that to foster the use of
-    cryptography in Free Software an LGPLed library would make more
-    sense because it avoids problems due to license incompatibilities
-    between some Free Software licenses and the GPL. 
-
-    Please note that in many cases it is better for a library to be
-    licensed under the GPL, so that it provides an advantage for free
-    software projects.  The Lesser GPL is so named because it does
-    less to protect the freedom of the users of the code that it
-    covers.  See http://www.gnu.org/philosophy/why-not-lgpl.html for
-    more explanation.
-
-
-    Configure options 
+    Configure options
     -----------------
-    Here is a list of configure options which are sometimes useful 
+    Here is a list of configure options which are sometimes useful
     for installation.
 
+     --enable-large-data-tests
+                     With this option a "make check" will take really
+                     long due to extra checks for the hash algorithms.
+
      --enable-m-guard
                      Enable the integrated malloc checking code. Please
                      note that this feature does not work on all CPUs
                      you a bus error.
 
      --disable-asm
-                     Do not use assembler modules.  It is not possible 
+                     Do not use assembler modules.  It is not possible
                      to use this on some CPU types.
-                    
+
      --enable-ld-version-script
                      Libgcrypt tries to build a library where internal
                      symbols are not exported.  This requires support
                     features not provided by the system, like 64bit
                     data types.  With these switches it is possible
                      to select exactly those algorithm modules, which
-                    should be built.
+                    should be built.  The algorithms are to be
+                     separated by spaces, commas or colons.  To view
+                     the list used with the current build the program
+                     tests/version may be used.
+
+     --disable-endian-check
+                     Don't let configure test for the endianness but
+                     try to use the OS provided macros at compile
+                     time.  This is helpful to create OS X fat binaries.
+
+     --enable-random-daemon
+                     Include support for a global random daemon and
+                     build the daemon.  This is an experimental feature.
+
+     --enable-mpi-path=EXTRA_PATH
+                     Prepend EXTRA_PATH to list of CPU specific
+                     optimizations.  For example, if you want to add
+                     optimizations forn a Intel Pentium 4 compatible
+                     CPU, you may use
+                        --enable-mpi-path=pentium4/sse2:pentium4/mmx
+                     Take care: The generated library may crash on
+                     non-compatible CPUs.
+
+     --enable-random=NAME
+                     Force the use of the random gathering module
+                    NAME.  Default is either to use /dev/random or
+                    the auto mode.  Possible values for NAME are:
+                      egd - Use the module which accesses the
+                            Entropy Gathering Daemon. See the webpages
+                            for more information about it.
+                     unix - Use the standard Unix module which does not
+                            have a very good performance.
+                    linux - Use the module which accesses /dev/random.
+                            This is the first choice and the default one
+                            for GNU/Linux or *BSD.
+                      auto - Compile linux, egd and unix in and
+                             automagically select at runtime.
+
+     --enable-hmac-binary-check
+                     Include support to check the binary at runtime
+                     against a HMAC checksum.  This works only in FIPS
+                     mode and on systems providing the dladdr function.
+
+     --disable-padlock-support
+                     Disable support for the PadLock engine of VIA
+                     processors.  The default is to use PadLock if
+                     available.  Try this if you get problems with
+                     assembler code.
+
+     --disable-aesni-support
+                     Disable support for the AES-NI instructions of
+                     newer Intel CPUs.  The default is to use AES-NI
+                     if available.  Try this if you get problems with
+                     assembler code.
+
+     --disable-O-flag-munging
+                     Some code is too complex for some compilers while
+                     in higher optimization modes, thus the compiler
+                     invocation is modified to use a lower
+                     optimization level.  Usually this works very well
+                     but on some platforms these rules break the
+                     invocation.  This option may be used to disable
+                     the feature under the assumption that either good
+                     CFLAGS are given or the compiler can grok the code.
+
+
+
+
+    Build Problems
+    --------------
+
+    We can't check all assembler files, so if you have problems
+    assembling them (or the program crashes) use --disable-asm with
+    ./configure.  If you opt to delete individual replacement files in
+    hopes of using the remaining ones, be aware that the configure
+    scripts may consider several subdirectories to get all available
+    assembler files; be sure to delete the correct ones.  Never delete
+    udiv-qrnnd.S in any CPU directory, because there may be no C
+    substitute (in mpi/genereic).  Don't forget to delete
+    "config.cache" and run "./config.status --recheck".  We got a few
+    reports about problems using versions of gcc earlier than 2.96
+    along with a non-GNU assembler (as).  If this applies to your
+    platform, you can either upgrade gcc to a more recent version, or
+    use the GNU assembler.
+
+    Some make tools are broken - the best solution is to use GNU's
+    make.  Try gmake or grab the sources from a GNU archive and
+    install them.
+
+    Specific problems on some machines:
+
+      * IBM RS/6000 running AIX
+
+       Due to a change in gcc (since version 2.8) the MPI stuff may
+       not build. In this case try to run configure using:
+           CFLAGS="-g -O2 -mcpu=powerpc" ./configure
+
+      * SVR4.2 (ESIX V4.2 cc)
+
+        Due to problems with the ESIX as(1), you probably want to do:
+            CFLAGS="-O -K pentium" ./configure --disable-asm
+
+      * SunOS 4.1.4
+
+         ./configure ac_cv_sys_symbol_underscore=yes
+
+      * Sparc64 CPUs
+
+        We have reports about failures in the AES module when
+        compiling using gcc (e.g. version 4.1.2) and the option -O3;
+        using -O2 solves the problem.
+
+
+    License
+    -------
+
+    The library is distributed under the terms of the GNU Lesser
+    General Public License (LGPL); see the file COPYING.LIB for the
+    actual terms.
+
+    The helper programs as well as the documentation are distributed
+    under the terms of the GNU General Public License (GPL); see the
+    file COPYING for the actual terms.
+
+    The file LICENSES has notices about contributions that require
+    that these additional notices are distributed.
+
+
+    Contact
+    -------
+
+    See the file AUTHORS.
+
+    Commercial grade support for Libgcrypt is available; for a listing
+    of offers see https://www.gnupg.org/service.html .
+
+    Maintenance and development of Libgcrypt is mostly financed by
+    donations.  We currently employ 3 full-time developers, one
+    part-timer, and one contractor.  They all work on GnuPG and
+    closely related software like Libgcrypt.  Please visit
+    https://gnupg.org/donate/ to see out how you can help.
+
+
+  This file is Free Software; as a special exception the authors gives
+  unlimited permission to copy and/or distribute it, with or without
+  modifications, as long as this notice is preserved. For conditions
+  of the whole package, please see the file COPYING.  This file is
+  distributed in the hope that it will be useful, but WITHOUT ANY
+  WARRANTY, to the extent permitted by law; without even the implied
+  warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.