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