9bad05a1a30a7057c4d5d55be5382ab7fffb5093
[libgcrypt.git] / README
1                     libgcrypt - The GNU crypto library
2                    ------------------------------------
3                             Version 1.3.x
4
5     WARNING:  This is the development branch of Libgcrypt.  The stable
6     version is 1.2.x.
7     
8
9     Copyright 2000, 2002, 2003, 2004, 2007 Free Software Foundation, Inc.
10
11     This file is free software; as a special exception the author gives
12     unlimited permission to copy and/or distribute it, with or without
13     modifications, as long as this notice is preserved.
14
15     This file is distributed in the hope that it will be useful, but
16     WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
17     implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
18
19
20
21     Overview
22     --------
23
24     Libgcrypt is a general purpose crypto library based on the code
25     used in GnuPG.  We can't start with a new version number because
26     libgcrypt was part of GnuPG 1.1 and some applications already used
27     it and tested for the version number. We believe that the API can
28     stay as it is, except that new functions may be added in the
29     future.
30
31     Libgcrypt depends on the library `libgpg-error', which must be
32     installed correctly before Libgcrypt is to be built.
33
34
35     Mailing List
36     ------------
37
38     You may want to join the developer's mailing list
39     gcrypt-devel@gnupg.org by sending mail with a subject of
40     "subscribe" to gcrypt-devel-request@gnupg.org.  An archive of this
41     list is available at http://lists.gnupg.org .
42
43
44     License
45     -------
46     
47     The library is distributed under the terms of the GNU Lesser
48     General Public License (LGPL); see the file COPYING.LIB for the
49     actual terms.  The helper programs (gcryptrnd and getrandom) as
50     well as the documentation are distributed under the terms of the
51     GNU General Public License (GPL); see the file COPYING for teh
52     actual terms.
53
54     This library used to be available under the GPL - this was changed
55     with version 1.1.7 with the rationale that there are now many free
56     crypto libraries available and many of them come with capabilities
57     similar to Libcrypt.  We decided that to foster the use of
58     cryptography in Free Software an LGPLed library would make more
59     sense because it avoids problems due to license incompatibilities
60     between some Free Software licenses and the GPL.
61
62     Please note that in many cases it is better for a library to be
63     licensed under the GPL, so that it provides an advantage for free
64     software projects.  The Lesser GPL is so named because it does
65     less to protect the freedom of the users of the code that it
66     covers.  See http://www.gnu.org/philosophy/why-not-lgpl.html for
67     more explanation.
68
69
70     Configure options 
71     -----------------
72     Here is a list of configure options which are sometimes useful 
73     for installation.
74
75      --enable-m-guard
76                      Enable the integrated malloc checking code. Please
77                      note that this feature does not work on all CPUs
78                      (e.g. SunOS 5.7 on UltraSparc-2) and might give
79                      you a bus error.
80
81      --disable-asm
82                      Do not use assembler modules.  It is not possible 
83                      to use this on some CPU types.
84                     
85      --enable-ld-version-script
86                      Libgcrypt tries to build a library where internal
87                      symbols are not exported.  This requires support
88                      from ld and is currently enabled for a few OSes.
89                      If you know that your ld supports the so called
90                      ELF version scripts, you can use this option to
91                      force its use.  OTOH, if you get error message
92                      from the linker, you probably want to use this
93                      option to disable the use of version scripts.
94                      Note, that you should never ever use an
95                      undocumented symbol or one which is prefixed with
96                      an underscore. 
97
98      --enable-ciphers=list
99      --enable-pubkey-ciphers=list
100      --enable-digests=list
101                      If not otherwise specified, all algorithms
102                      included in the libgcrypt source tree are built.
103                      An exception are algorithms, which depend on
104                      features not provided by the system, like 64bit
105                      data types.  With these switches it is possible
106                      to select exactly those algorithm modules, which
107                      should be built.  The algorithms are to be
108                      separated by spaces, commas or colons.  To view
109                      the list used with the current build the program
110                      tests/version may be used.
111
112      --disable-endian-check
113                      Don't let configure test for the endianness but
114                      try to use the OS provided macros at compile
115                      time.  This is helpful to create OS X fat binaries.
116
117      --enable-random-daemon
118                      Include support for a global random damon and
119                      build the daemon.  This is an experimental feature.
120
121      --enable-mpi-path=EXTRA_PATH
122                      Prepend EXTRA_PATH to list of CPU specific
123                      optimizations.  For example, if you want to add
124                      optimizations forn a Intel Pentium 4 compatible
125                      CPU, you may use
126                         --enable-mpi-path=pentium4/sse2:pentium4/mmx
127                      Take care: The generated library may crash on
128                      non-compatible CPUs.
129
130      --enable-random=NAME 
131                      Force the use of the random gathering module
132                      NAME.  Default is either to use /dev/random or
133                      the auto mode.  Possible values for NAME are:
134                        egd - Use the module which accesses the
135                              Entropy Gathering Daemon. See the webpages
136                              for more information about it.
137                       unix - Use the standard Unix module which does not
138                              have a very good performance.
139                      linux - Use the module which accesses /dev/random.
140                              This is the first choice and the default one
141                              for GNU/Linux or *BSD.
142                       auto - Compile linux, egd and unix in and 
143                              automagically select at runtime.
144   
145
146
147
148     Contact
149     -------
150
151     See the file AUTHORS.
152