Updated the architecture chapter
[libgcrypt.git] / README
1                     libgcrypt - The GNU crypto library
2                    ------------------------------------
3                             Version 1.4.2rc2
4  
5
6     Copyright 2000, 2002, 2003, 2004, 2007,
7               2008 Free Software Foundation, Inc.
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 damon 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        
172
173
174     License
175     -------
176     
177     The library is distributed under the terms of the GNU Lesser
178     General Public License (LGPL); see the file COPYING.LIB for the
179     actual terms.  The helper programs (e.g. gcryptrnd and getrandom)
180     as well as the documentation are distributed under the terms of
181     the GNU General Public License (GPL); see the file COPYING for the
182     actual terms.
183
184     This library used to be available under the GPL - this was changed
185     with version 1.1.7 with the rationale that there are now many free
186     crypto libraries available and many of them come with capabilities
187     similar to Libcrypt.  We decided that to foster the use of
188     cryptography in Free Software an LGPLed library would make more
189     sense because it avoids problems due to license incompatibilities
190     between some Free Software licenses and the GPL.
191
192     Please note that in many cases it is better for a library to be
193     licensed under the GPL, so that it provides an advantage for free
194     software projects.  The Lesser GPL is so named because it does
195     less to protect the freedom of the users of the code that it
196     covers.  See http://www.gnu.org/philosophy/why-not-lgpl.html for
197     more explanation.
198
199
200     Contact
201     -------
202
203     See the file AUTHORS.
204
205     Commercial grade support for Libgcrypt is available; please see
206     http://www.gnupg.org/service.html .
207
208
209   This file is Free Software; as a special exception the authors gives
210   unlimited permission to copy and/or distribute it, with or without
211   modifications, as long as this notice is preserved. For conditions
212   of the whole package, please see the file COPYING.  This file is
213   distributed in the hope that it will be useful, but WITHOUT ANY
214   WARRANTY, to the extent permitted by law; without even the implied
215   warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
216