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