Adding gcry_mpi_lshift.
[libgcrypt.git] / README
1                     libgcrypt - The GNU crypto library
2                    ------------------------------------
3                             Version 1.4.2rc1
4  
5                      *** Warning: RELEASE CANDIDATE ***
6
7     Copyright 2000, 2002, 2003, 2004, 2007,
8               2008 Free Software Foundation, Inc.
9
10     This file is free software; as a special exception the author gives
11     unlimited permission to copy and/or distribute it, with or without
12     modifications, as long as this notice is preserved.
13
14     This file is distributed in the hope that it will be useful, but
15     WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
16     implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
17
18
19
20     Overview
21     --------
22
23     Libgcrypt is a general purpose crypto library based on the code
24     used in GnuPG.  Libgcrypt depends on the library `libgpg-error',
25     which must be installed correctly before Libgcrypt is to be built.
26     Libgcrypt is distributed under the LGPL, see the section "License"
27     below for details.
28
29
30     Build Instructions
31     ------------------
32
33     The download canonical location for libgcrypt is:
34
35       ftp://ftp.gnupg.org/gcrypt/libgcrypt/
36      
37     To build libgcrypt you need libgpg-error:
38
39       ftp://ftp.gnupg.org/gcrypt/libgpg-error/
40
41     You should get the latest versions of course.
42
43     After building and installing the libgpg-error package, you may
44     continue with Libgcrypt installation As with allmost all GNU
45     packages, you just have to do
46
47        ./configure
48        make
49        make check
50        make install
51
52     The "make check" is not required but a good idea to see whether
53     the library works as expected.  The check takes some while and
54     prints some benchmarking results.  Before doing "make install" you
55     probably need to become root.
56
57     To build libgcrypt for Microsoft Windows, you need to have the
58     mingw32 cross-building toolchain installed.  Instead of running a
59     plain configure you use
60
61       ./autogen.sh --build-w32
62       make
63       make install
64       
65     By default this command sequences expectsd a libgpg-error
66     installed below $HOME/w32root and installs libgcrypt to that
67     directory too.  See the autogen.sh code for details.
68
69     The documentation is available as an Info file (gcrypt.info).  To
70     build documentation in PDF, run this:
71
72       cd doc
73       make pdf
74
75
76
77     Mailing List
78     ------------
79
80     You may want to join the developer's mailing list
81     gcrypt-devel@gnupg.org by sending mail with a subject of
82     "subscribe" to gcrypt-devel-request@gnupg.org.  An archive of this
83     list is available at http://lists.gnupg.org .
84
85
86     Configure options 
87     -----------------
88     Here is a list of configure options which are sometimes useful 
89     for installation.
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 damon 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      --disable-padlock-support
162                      Disable support for the PadLock engine of VIA
163                      processors.  The default is to use PadLock if
164                      available.  Try this if you get problems with
165                      assembler code.
166
167
168
169     License
170     -------
171     
172     The library is distributed under the terms of the GNU Lesser
173     General Public License (LGPL); see the file COPYING.LIB for the
174     actual terms.  The helper programs (gcryptrnd and getrandom) as
175     well as the documentation are distributed under the terms of the
176     GNU General Public License (GPL); see the file COPYING for teh
177     actual terms.
178
179     This library used to be available under the GPL - this was changed
180     with version 1.1.7 with the rationale that there are now many free
181     crypto libraries available and many of them come with capabilities
182     similar to Libcrypt.  We decided that to foster the use of
183     cryptography in Free Software an LGPLed library would make more
184     sense because it avoids problems due to license incompatibilities
185     between some Free Software licenses and the GPL.
186
187     Please note that in many cases it is better for a library to be
188     licensed under the GPL, so that it provides an advantage for free
189     software projects.  The Lesser GPL is so named because it does
190     less to protect the freedom of the users of the code that it
191     covers.  See http://www.gnu.org/philosophy/why-not-lgpl.html for
192     more explanation.
193
194
195     Contact
196     -------
197
198     See the file AUTHORS.
199
200     Commercial grade support for Libgcrypt is available; please see
201     http://www.gnupg.org/service.html .
202
203
204   This file is Free Software; as a special exception the authors gives
205   unlimited permission to copy and/or distribute it, with or without
206   modifications, as long as this notice is preserved. For conditions
207   of the whole package, please see the file COPYING.  This file is
208   distributed in the hope that it will be useful, but WITHOUT ANY
209   WARRANTY, to the extent permitted by law; without even the implied
210   warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
211