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