8e75e4003538514861ca6b22f9fdea0d3c32e999
[libgcrypt.git] / README
1                     libgcrypt - The GNU crypto library
2                    ------------------------------------
3                             Version 1.4.0
4
5     Copyright 2000, 2002, 2003, 2004, 2007 Free Software Foundation, Inc.
6
7     This file is free software; as a special exception the author gives
8     unlimited permission to copy and/or distribute it, with or without
9     modifications, as long as this notice is preserved.
10
11     This file is distributed in the hope that it will be useful, but
12     WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
13     implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
14
15
16
17     Overview
18     --------
19
20     Libgcrypt is a general purpose crypto library based on the code
21     used in GnuPG.  Libgcrypt depends on the library `libgpg-error',
22     which must be installed correctly before Libgcrypt is to be built.
23     Libgcrypt is distributed under the LGPL, see the section "License"
24     below for details.
25
26
27     Build Instructions
28     ------------------
29
30     The download canonical location for libgcrypt is:
31
32       ftp://ftp.gnupg.org/gcrypt/libgcrypt/
33      
34     To build libgcrypt you need libgpg-error:
35
36       ftp://ftp.gnupg.org/gcrypt/libgpg-error/
37
38     You should get the latest versions of course.
39
40     After building and installing the libgpg-error package, you may
41     continue with Libgcrypt installation As with allmost all GNU
42     packages, you just have to do
43
44        ./configure
45        make
46        make check
47        make install
48
49     The "make check" is not required but a good idea to see whether
50     the library works as expected.  The check takes some while and
51     prints some benchmarking results.  Before doing "make install" you
52     probably need to become root.
53
54     To build libgcrypt for Microsoft Windows, you need to have the
55     mingw32 cross-building toolchain installed.  Instead of running a
56     plain configure you use
57
58       ./autogen.sh --build-w32
59       make
60       make install
61       
62     By default this command sequences expectsd a libgpg-error
63     installed below $HOME/w32root and installs libgcrypt to that
64     directory too.  See the autogen.sh code for details.
65
66     The documentation is available as an Info file (gcrypt.info).  To
67     build documentation in PDF, run this:
68
69       cd doc
70       make pdf
71
72
73
74     Mailing List
75     ------------
76
77     You may want to join the developer's mailing list
78     gcrypt-devel@gnupg.org by sending mail with a subject of
79     "subscribe" to gcrypt-devel-request@gnupg.org.  An archive of this
80     list is available at http://lists.gnupg.org .
81
82
83     Configure options 
84     -----------------
85     Here is a list of configure options which are sometimes useful 
86     for installation.
87
88      --enable-m-guard
89                      Enable the integrated malloc checking code. Please
90                      note that this feature does not work on all CPUs
91                      (e.g. SunOS 5.7 on UltraSparc-2) and might give
92                      you a bus error.
93
94      --disable-asm
95                      Do not use assembler modules.  It is not possible 
96                      to use this on some CPU types.
97                     
98      --enable-ld-version-script
99                      Libgcrypt tries to build a library where internal
100                      symbols are not exported.  This requires support
101                      from ld and is currently enabled for a few OSes.
102                      If you know that your ld supports the so called
103                      ELF version scripts, you can use this option to
104                      force its use.  OTOH, if you get error message
105                      from the linker, you probably want to use this
106                      option to disable the use of version scripts.
107                      Note, that you should never ever use an
108                      undocumented symbol or one which is prefixed with
109                      an underscore. 
110
111      --enable-ciphers=list
112      --enable-pubkey-ciphers=list
113      --enable-digests=list
114                      If not otherwise specified, all algorithms
115                      included in the libgcrypt source tree are built.
116                      An exception are algorithms, which depend on
117                      features not provided by the system, like 64bit
118                      data types.  With these switches it is possible
119                      to select exactly those algorithm modules, which
120                      should be built.  The algorithms are to be
121                      separated by spaces, commas or colons.  To view
122                      the list used with the current build the program
123                      tests/version may be used.
124
125      --disable-endian-check
126                      Don't let configure test for the endianness but
127                      try to use the OS provided macros at compile
128                      time.  This is helpful to create OS X fat binaries.
129
130      --enable-random-daemon
131                      Include support for a global random damon and
132                      build the daemon.  This is an experimental feature.
133
134      --enable-mpi-path=EXTRA_PATH
135                      Prepend EXTRA_PATH to list of CPU specific
136                      optimizations.  For example, if you want to add
137                      optimizations forn a Intel Pentium 4 compatible
138                      CPU, you may use
139                         --enable-mpi-path=pentium4/sse2:pentium4/mmx
140                      Take care: The generated library may crash on
141                      non-compatible CPUs.
142
143      --enable-random=NAME 
144                      Force the use of the random gathering module
145                      NAME.  Default is either to use /dev/random or
146                      the auto mode.  Possible values for NAME are:
147                        egd - Use the module which accesses the
148                              Entropy Gathering Daemon. See the webpages
149                              for more information about it.
150                       unix - Use the standard Unix module which does not
151                              have a very good performance.
152                      linux - Use the module which accesses /dev/random.
153                              This is the first choice and the default one
154                              for GNU/Linux or *BSD.
155                       auto - Compile linux, egd and unix in and 
156                              automagically select at runtime.
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
165
166     License
167     -------
168     
169     The library is distributed under the terms of the GNU Lesser
170     General Public License (LGPL); see the file COPYING.LIB for the
171     actual terms.  The helper programs (gcryptrnd and getrandom) as
172     well as the documentation are distributed under the terms of the
173     GNU General Public License (GPL); see the file COPYING for teh
174     actual terms.
175
176     This library used to be available under the GPL - this was changed
177     with version 1.1.7 with the rationale that there are now many free
178     crypto libraries available and many of them come with capabilities
179     similar to Libcrypt.  We decided that to foster the use of
180     cryptography in Free Software an LGPLed library would make more
181     sense because it avoids problems due to license incompatibilities
182     between some Free Software licenses and the GPL.
183
184     Please note that in many cases it is better for a library to be
185     licensed under the GPL, so that it provides an advantage for free
186     software projects.  The Lesser GPL is so named because it does
187     less to protect the freedom of the users of the code that it
188     covers.  See http://www.gnu.org/philosophy/why-not-lgpl.html for
189     more explanation.
190
191
192     Contact
193     -------
194
195     See the file AUTHORS.
196
197     Commercial grade support for Libgcrypt is available; please see
198     http://www.gnupg.org/service.html .
199
200
201   This file is Free Software; as a special exception the authors gives
202   unlimited permission to copy and/or distribute it, with or without
203   modifications, as long as this notice is preserved. For conditions
204   of the whole package, please see the file COPYING.  This file is
205   distributed in the hope that it will be useful, but WITHOUT ANY
206   WARRANTY, to the extent permitted by law; without even the implied
207   warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
208