summaryrefslogtreecommitdiff
path: root/README
blob: 938c6c6c10316d9744a64aa9f0a88ad7315b370a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
		    Libgcrypt - The GNU Crypto Library
		   ------------------------------------
                             Version 1.7

     ====  THIS IS A DEVELOPMENT VERSION - NOT FOR REAL USE ====

       Copyright (C) 1989,1991-2012 Free Software Foundation, Inc.
       Copyright (C) 2012-2013 g10 Code GmbH
       Copyright (C) 2013 Jussi Kivilinna

    Libgcrypt is free software.  See the file AUTHORS for full copying
    notices, and LICENSES for notices about contributions that require
    these additional notices to be distributed.


    Overview
    --------

    Libgcrypt is a general purpose crypto library based on the code
    used in GnuPG.  Libgcrypt depends on the library `libgpg-error',
    which must be installed correctly before Libgcrypt is to be built.
    Libgcrypt is distributed under the LGPL, see the section "License"
    below for details.


    Build Instructions
    ------------------

    The download canonical location for libgcrypt is:

      ftp://ftp.gnupg.org/gcrypt/libgcrypt/

    To build libgcrypt you need libgpg-error:

      ftp://ftp.gnupg.org/gcrypt/libgpg-error/

    You should get the latest versions of course.

    After building and installing the libgpg-error package, you may
    continue with Libgcrypt installation as with allmost all GNU
    packages, you just have to do

       ./configure
       make
       make check
       make install

    The "make check" is not required but a good idea to see whether
    the library works as expected.  The check takes some while and
    prints some benchmarking results.  Before doing "make install" you
    probably need to become root.

    To build libgcrypt for Microsoft Windows, you need to have the
    mingw32 cross-building toolchain installed.  Instead of running a
    plain configure you use

      ./autogen.sh --build-w32
      make
      make install

    By default this command sequences expectsd a libgpg-error
    installed below $HOME/w32root and installs libgcrypt to that
    directory too.  See the autogen.sh code for details.

    The documentation is available as an Info file (gcrypt.info).  To
    build documentation in PDF, run this:

      cd doc
      make pdf



    Mailing List
    ------------

    You may want to join the developer's mailing list
    gcrypt-devel@gnupg.org by sending mail with a subject of
    "subscribe" to gcrypt-devel-request@gnupg.org.  An archive of this
    list is available at http://lists.gnupg.org .


    Configure options
    -----------------
    Here is a list of configure options which are sometimes useful
    for installation.

     --enable-large-data-tests
                     With this option a "make check" will take really
                     long due to extra checks for the hash algorithms.

     --enable-m-guard
                     Enable the integrated malloc checking code. Please
                     note that this feature does not work on all CPUs
                     (e.g. SunOS 5.7 on UltraSparc-2) and might give
                     you a bus error.

     --disable-asm
                     Do not use assembler modules.  It is not possible
                     to use this on some CPU types.

     --enable-ld-version-script
                     Libgcrypt tries to build a library where internal
                     symbols are not exported.  This requires support
                     from ld and is currently enabled for a few OSes.
                     If you know that your ld supports the so called
                     ELF version scripts, you can use this option to
                     force its use.  OTOH, if you get error message
                     from the linker, you probably want to use this
                     option to disable the use of version scripts.
                     Note, that you should never ever use an
                     undocumented symbol or one which is prefixed with
                     an underscore.

     --enable-ciphers=list
     --enable-pubkey-ciphers=list
     --enable-digests=list
                     If not otherwise specified, all algorithms
                     included in the libgcrypt source tree are built.
		     An exception are algorithms, which depend on
		     features not provided by the system, like 64bit
		     data types.  With these switches it is possible
                     to select exactly those algorithm modules, which
		     should be built.  The algorithms are to be
                     separated by spaces, commas or colons.  To view
                     the list used with the current build the program
                     tests/version may be used.

     --disable-endian-check
                     Don't let configure test for the endianness but
                     try to use the OS provided macros at compile
                     time.  This is helpful to create OS X fat binaries.

     --enable-random-daemon
                     Include support for a global random daemon and
                     build the daemon.  This is an experimental feature.

     --enable-mpi-path=EXTRA_PATH
                     Prepend EXTRA_PATH to list of CPU specific
                     optimizations.  For example, if you want to add
                     optimizations forn a Intel Pentium 4 compatible
                     CPU, you may use
                        --enable-mpi-path=pentium4/sse2:pentium4/mmx
                     Take care: The generated library may crash on
                     non-compatible CPUs.

     --enable-random=NAME
                     Force the use of the random gathering module
		     NAME.  Default is either to use /dev/random or
		     the auto mode.  Possible values for NAME are:
		       egd - Use the module which accesses the
			     Entropy Gathering Daemon. See the webpages
			     for more information about it.
		      unix - Use the standard Unix module which does not
			     have a very good performance.
		     linux - Use the module which accesses /dev/random.
			     This is the first choice and the default one
			     for GNU/Linux or *BSD.
                      auto - Compile linux, egd and unix in and
                             automagically select at runtime.

     --enable-hmac-binary-check
                     Include support to check the binary at runtime
                     against a HMAC checksum.  This works only in FIPS
                     mode and on systems providing the dladdr function.

     --disable-padlock-support
                     Disable support for the PadLock engine of VIA
                     processors.  The default is to use PadLock if
                     available.  Try this if you get problems with
                     assembler code.

     --disable-aesni-support
                     Disable support for the AES-NI instructions of
                     newer Intel CPUs.  The default is to use AES-NI
                     if available.  Try this if you get problems with
                     assembler code.

     --disable-O-flag-munging
                     Some code is too complex for some compilers while
                     in higher optimization modes, thus the compiler
                     invocation is modified to use a lower
                     optimization level.  Usually this works very well
                     but on some platforms these rules break the
                     invocation.  This option may be used to disable
                     the feature under the assumption that either good
                     CFLAGS are given or the compiler can grok the code.




    Build Problems
    --------------

    We can't check all assembler files, so if you have problems
    assembling them (or the program crashes) use --disable-asm with
    ./configure.  If you opt to delete individual replacement files in
    hopes of using the remaining ones, be aware that the configure
    scripts may consider several subdirectories to get all available
    assembler files; be sure to delete the correct ones.  Never delete
    udiv-qrnnd.S in any CPU directory, because there may be no C
    substitute (in mpi/genereic).  Don't forget to delete
    "config.cache" and run "./config.status --recheck".  We got a few
    reports about problems using versions of gcc earlier than 2.96
    along with a non-GNU assembler (as).  If this applies to your
    platform, you can either upgrade gcc to a more recent version, or
    use the GNU assembler.

    Some make tools are broken - the best solution is to use GNU's
    make.  Try gmake or grab the sources from a GNU archive and
    install them.

    Specific problems on some machines:

      * IBM RS/6000 running AIX

	Due to a change in gcc (since version 2.8) the MPI stuff may
	not build. In this case try to run configure using:
	    CFLAGS="-g -O2 -mcpu=powerpc" ./configure

      * SVR4.2 (ESIX V4.2 cc)

        Due to problems with the ESIX as(1), you probably want to do:
            CFLAGS="-O -K pentium" ./configure --disable-asm

      * SunOS 4.1.4

         ./configure ac_cv_sys_symbol_underscore=yes

      * Sparc64 CPUs

        We have reports about failures in the AES module when
        compiling using gcc (e.g. version 4.1.2) and the option -O3;
        using -O2 solves the problem.


    License
    -------

    The library is distributed under the terms of the GNU Lesser
    General Public License (LGPL); see the file COPYING.LIB for the
    actual terms.  The helper programs (e.g. gcryptrnd and getrandom)
    as well as the documentation are distributed under the terms of
    the GNU General Public License (GPL); see the file COPYING for the
    actual terms.  The file LICENSES has notices about contributions
    that require these additional notices are distributed.

    This library used to be available under the GPL - this was changed
    with version 1.1.7 with the rationale that there are now many free
    crypto libraries available and many of them come with capabilities
    similar to Libcrypt.  We decided that to foster the use of
    cryptography in Free Software an LGPLed library would make more
    sense because it avoids problems due to license incompatibilities
    between some Free Software licenses and the GPL.

    Please note that in many cases it is better for a library to be
    licensed under the GPL, so that it provides an advantage for free
    software projects.  The Lesser GPL is so named because it does
    less to protect the freedom of the users of the code that it
    covers.  See http://www.gnu.org/philosophy/why-not-lgpl.html for
    more explanation.


    Contact
    -------

    See the file AUTHORS.

    Commercial grade support for Libgcrypt is available; please see
    http://www.gnupg.org/service.html .

    Commercial grade support for Libgcrypt is available; for a listing
    of offers see http://www.gnupg.org/service.html .  The driving
    force behind the development of Libgcrypt is the company of its
    principal author, Werner Koch.  Maintenance and improvement of
    Libgcrypt takes up a lot resources.  To allow him to continue his
    work, he asks to either purchase a support contract, engage them
    for custom enhancements, or to donate money.  See http://g10code.com .


  This file is Free Software; as a special exception the authors gives
  unlimited permission to copy and/or distribute it, with or without
  modifications, as long as this notice is preserved. For conditions
  of the whole package, please see the file COPYING.  This file is
  distributed in the hope that it will be useful, but WITHOUT ANY
  WARRANTY, to the extent permitted by law; without even the implied
  warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.