ecc: Fix ecc_verify for cofactor support.
[libgcrypt.git] / README
1                     Libgcrypt - The GNU Crypto Library
2                    ------------------------------------
3                              Version 1.7
4
5        Copyright (C) 1989,1991-2016 Free Software Foundation, Inc.
6        Copyright (C) 2012-2016 g10 Code GmbH
7        Copyright (C) 2013-2016 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       ftp://ftp.gnupg.org/gcrypt/libgcrypt/
30
31     To build libgcrypt you need libgpg-error:
32
33       ftp://ftp.gnupg.org/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 and on systems providing the dladdr function.
163
164      --disable-padlock-support
165                      Disable support for the PadLock engine of VIA
166                      processors.  The default is to use PadLock if
167                      available.  Try this if you get problems with
168                      assembler code.
169
170      --disable-aesni-support
171                      Disable support for the AES-NI instructions of
172                      newer Intel CPUs.  The default is to use AES-NI
173                      if available.  Try this if you get problems with
174                      assembler code.
175
176      --disable-O-flag-munging
177                      Some code is too complex for some compilers while
178                      in higher optimization modes, thus the compiler
179                      invocation is modified to use a lower
180                      optimization level.  Usually this works very well
181                      but on some platforms these rules break the
182                      invocation.  This option may be used to disable
183                      the feature under the assumption that either good
184                      CFLAGS are given or the compiler can grok the code.
185
186
187
188
189     Build Problems
190     --------------
191
192     We can't check all assembler files, so if you have problems
193     assembling them (or the program crashes) use --disable-asm with
194     ./configure.  If you opt to delete individual replacement files in
195     hopes of using the remaining ones, be aware that the configure
196     scripts may consider several subdirectories to get all available
197     assembler files; be sure to delete the correct ones.  Never delete
198     udiv-qrnnd.S in any CPU directory, because there may be no C
199     substitute (in mpi/genereic).  Don't forget to delete
200     "config.cache" and run "./config.status --recheck".  We got a few
201     reports about problems using versions of gcc earlier than 2.96
202     along with a non-GNU assembler (as).  If this applies to your
203     platform, you can either upgrade gcc to a more recent version, or
204     use the GNU assembler.
205
206     Some make tools are broken - the best solution is to use GNU's
207     make.  Try gmake or grab the sources from a GNU archive and
208     install them.
209
210     Specific problems on some machines:
211
212       * IBM RS/6000 running AIX
213
214         Due to a change in gcc (since version 2.8) the MPI stuff may
215         not build. In this case try to run configure using:
216             CFLAGS="-g -O2 -mcpu=powerpc" ./configure
217
218       * SVR4.2 (ESIX V4.2 cc)
219
220         Due to problems with the ESIX as(1), you probably want to do:
221             CFLAGS="-O -K pentium" ./configure --disable-asm
222
223       * SunOS 4.1.4
224
225          ./configure ac_cv_sys_symbol_underscore=yes
226
227       * Sparc64 CPUs
228
229         We have reports about failures in the AES module when
230         compiling using gcc (e.g. version 4.1.2) and the option -O3;
231         using -O2 solves the problem.
232
233
234     License
235     -------
236
237     The library is distributed under the terms of the GNU Lesser
238     General Public License (LGPL); see the file COPYING.LIB for the
239     actual terms.
240
241     The helper programs as well as the documentation are distributed
242     under the terms of the GNU General Public License (GPL); see the
243     file COPYING for the actual terms.
244
245     The file LICENSES has notices about contributions that require
246     that these additional notices are distributed.
247
248
249     Contact
250     -------
251
252     See the file AUTHORS.
253
254     Commercial grade support for Libgcrypt is available; for a listing
255     of offers see https://www.gnupg.org/service.html .
256
257     Maintenance and development of Libgcrypt is mostly financed by
258     donations.  We currently employ 3 full-time developers, one
259     part-timer, and one contractor.  They all work on GnuPG and
260     closely related software like Libgcrypt.  Please visit
261     https://gnupg.org/donate/ to see out how you can help.
262
263
264   This file is Free Software; as a special exception the authors gives
265   unlimited permission to copy and/or distribute it, with or without
266   modifications, as long as this notice is preserved. For conditions
267   of the whole package, please see the file COPYING.  This file is
268   distributed in the hope that it will be useful, but WITHOUT ANY
269   WARRANTY, to the extent permitted by law; without even the implied
270   warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.