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