Commit 98a8b9e3 authored by Niels Möller's avatar Niels Möller

Updated for 2.0. New section on linking.

Rev: nettle/ChangeLog:1.26
Rev: nettle/nettle.texinfo:1.2
parent 3733ef05
2008-11-01 Niels Mller <nisse@lysator.liu.se> 2008-11-01 Niels Mller <nisse@lysator.liu.se>
* nettle.texinfo: Updated for 2.0. New section on linking.
* nettle-types.h, nettle-meta.h: Moved all typedefs for function * nettle-types.h, nettle-meta.h: Moved all typedefs for function
types to nettle-types.h. Use non-pointer types, so that the types types to nettle-types.h. Use non-pointer types, so that the types
can be used to declare functions. Updated all users. can be used to declare functions. Updated all users.
......
...@@ -16,7 +16,7 @@ ...@@ -16,7 +16,7 @@
@end direntry @end direntry
@set COPYRIGHT-YEARS 2001, 2004, 2005 @set COPYRIGHT-YEARS 2001, 2004, 2005
@set UPDATED-FOR 1.15 @set UPDATED-FOR 2.0
@c Latin-1 doesn't work with TeX output. @c Latin-1 doesn't work with TeX output.
@c Also lookout for é characters. @c Also lookout for é characters.
...@@ -115,12 +115,13 @@ This manual corresponds to version @value{UPDATED-FOR} of the library. ...@@ -115,12 +115,13 @@ This manual corresponds to version @value{UPDATED-FOR} of the library.
@menu @menu
* Introduction:: What is Nettle? * Introduction:: What is Nettle?
* Copyright:: Your rights. * Copyright:: Your rights.
* Conventions:: * Conventions:: General interface conventions.
* Example:: * Example:: An example program.
* Linking::
* Reference:: All Nettle functions and features. * Reference:: All Nettle functions and features.
* Nettle soup:: For the serious nettle hacker. * Nettle soup:: For the serious nettle hacker.
* Installation:: How to install Nettle. * Installation:: How to install Nettle.
* Index:: * Index:: Function and concept index.
@end menu @end menu
@end ifnottex @end ifnottex
...@@ -255,7 +256,7 @@ unexpected effects. ...@@ -255,7 +256,7 @@ unexpected effects.
For consistency, functions for different algorithms are very similar, For consistency, functions for different algorithms are very similar,
but there are some differences, for instance reflecting if the key setup but there are some differences, for instance reflecting if the key setup
or encryption function differ for encryption and encryption, and whether or encryption function differ for encryption and decryption, and whether
or not key setup can fail. There are also differences between algorithms or not key setup can fail. There are also differences between algorithms
that don't show in function prototypes, but which the application must that don't show in function prototypes, but which the application must
nevertheless be aware of. There is no big difference between the nevertheless be aware of. There is no big difference between the
...@@ -281,18 +282,41 @@ but they @emph{must not} overlap in any other way. ...@@ -281,18 +282,41 @@ but they @emph{must not} overlap in any other way.
@c FIXME: Say something about the name mangling. @c FIXME: Say something about the name mangling.
@node Example, Reference, Conventions, Top @node Example, Linking, Conventions, Top
@comment node-name, next, previous, up @comment node-name, next, previous, up
@chapter Example @chapter Example
A simple example program that reads a file from standard in and writes A simple example program that reads a file from standard input and
its SHA1 checksum on standard output should give the flavor of Nettle. writes its SHA1 checksum on standard output should give the flavor of
Nettle.
@example @example
@verbatiminclude sha-example.c @verbatiminclude sha-example.c
@end example @end example
@node Reference, Nettle soup, Example, Top On a typical Unix system, this program can be compiled and linked with
the command line
@example
cc sha-example.c -o sha-example -lnettle
@end example
@node Linking, Reference, Example, Top
@comment node-name, next, previous, up
@chapter Linking
Nettle actually consists of two libraries, @file{libnettle} and
@file{libhogweed}. The @file{libhogweed} library contains those
functions of Nettle that uses bignum operations, and depends on the GMP
library. With this division, linking works the same for both static and
dynamic libraries.
If an application uses only the symmetric crypto algorithms of
Nettle (i.e., block ciphers, hash functions, and the like), it's
sufficient to link with @code{-lnettle}. If an application also uses
public-key algorithms, it must be linked with @code{-lhogweed -lnettle
-lgmp}.
@node Reference, Nettle soup, Linking, Top
@comment node-name, next, previous, up @comment node-name, next, previous, up
@chapter Reference @chapter Reference
...@@ -1505,7 +1529,8 @@ the same key. ...@@ -1505,7 +1529,8 @@ the same key.
Nettle uses @acronym{GMP}, the GNU bignum library, for all calculations Nettle uses @acronym{GMP}, the GNU bignum library, for all calculations
with large numbers. In order to use the public-key features of Nettle, with large numbers. In order to use the public-key features of Nettle,
you must install @acronym{GMP}, at least version 3.0, before compiling you must install @acronym{GMP}, at least version 3.0, before compiling
Nettle, and you need to link your programs with @code{-lgmp}. Nettle, and you need to link your programs with @code{-lhogweed -lnettle
-lgmp}.
The concept of @dfn{Public-key} encryption and digital signatures was The concept of @dfn{Public-key} encryption and digital signatures was
discovered by Whitfield Diffie and Martin E. Hellman and described in a discovered by Whitfield Diffie and Martin E. Hellman and described in a
...@@ -2201,12 +2226,12 @@ Information about a single source. ...@@ -2201,12 +2226,12 @@ Information about a single source.
@end deftp @end deftp
@defvr Constant YARROW256_SEED_FILE_SIZE @defvr Constant YARROW256_SEED_FILE_SIZE
The size of the Yarrow-256 seed file. Recommanded size of the Yarrow-256 seed file.
@end defvr @end defvr
@deftypefun void yarrow256_init (struct yarrow256_ctx *@var{ctx}, unsigned @var{nsources}, struct yarrow_source *@var{sources}) @deftypefun void yarrow256_init (struct yarrow256_ctx *@var{ctx}, unsigned @var{nsources}, struct yarrow_source *@var{sources})
Initializes the yarrow context, and its @var{nsources} sources. It's Initializes the yarrow context, and its @var{nsources} sources. It's
possible to use call it with @var{nsources}=0 and @var{sources}=NULL, if possible to call it with @var{nsources}=0 and @var{sources}=NULL, if
you don't need the update features. you don't need the update features.
@end deftypefun @end deftypefun
...@@ -2216,9 +2241,9 @@ Seeds Yarrow-256 from a previous seed file. @var{length} should be at least ...@@ -2216,9 +2241,9 @@ Seeds Yarrow-256 from a previous seed file. @var{length} should be at least
The generator will trust you that the @var{seed_file} data really is The generator will trust you that the @var{seed_file} data really is
unguessable. After calling this function, you @emph{must} overwrite the old unguessable. After calling this function, you @emph{must} overwrite the old
seed file with the contents of @code{@var{ctx}->seed_file}. If it's seed file with newly generated data from @code{yarrow256_random}. If it's
possible for several processes to read the seed file at about the same possible for several processes to read the seed file at about the same
time, access must be coordinated, for example using lock files. time, access must be coordinated using some locking mechanism.
@end deftypefun @end deftypefun
@deftypefun int yarrow256_update (struct yarrow256_ctx *@var{ctx}, unsigned @var{source}, unsigned @var{entropy}, unsigned @var{length}, const uint8_t *@var{data}) @deftypefun int yarrow256_update (struct yarrow256_ctx *@var{ctx}, unsigned @var{source}, unsigned @var{entropy}, unsigned @var{length}, const uint8_t *@var{data})
...@@ -2228,9 +2253,10 @@ estimated lower bound for the entropy in the data, measured in bits. ...@@ -2228,9 +2253,10 @@ estimated lower bound for the entropy in the data, measured in bits.
Calling update with zero @var{entropy} is always safe, no matter if the Calling update with zero @var{entropy} is always safe, no matter if the
data is random or not. data is random or not.
Returns 1 if a reseed happened, in which case the seed file can be Returns 1 if a reseed happened, in which case an application using a
overwritten with the contents of @code{@var{ctx}->seed_file}. Otherwise, seed file may want to generate new seed data with
the function returns 0. @code{yarrow256_random} and overwrite the seed file. Otherwise, the
function returns 0.
@end deftypefun @end deftypefun
@deftypefun void yarrow256_random (struct yarrow256_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{dst}) @deftypefun void yarrow256_random (struct yarrow256_ctx *@var{ctx}, unsigned @var{length}, uint8_t *@var{dst})
...@@ -2253,8 +2279,9 @@ Returns the number of sources that must reach the threshold before a ...@@ -2253,8 +2279,9 @@ Returns the number of sources that must reach the threshold before a
slow reseed will happen. Useful primarily when the generator is unseeded. slow reseed will happen. Useful primarily when the generator is unseeded.
@end deftypefun @end deftypefun
@deftypefun void yarrow256_force_reseed (struct yarrow256_ctx *@var{ctx}) @deftypefun void yarrow256_fast_reseed (struct yarrow256_ctx *@var{ctx})
Causes a slow reseed to take place immediately, regardless of the @deftypefunx void yarrow256_slow_reseed (struct yarrow256_ctx *@var{ctx})
Causes a fast or slow reseed to take place immediately, regardless of the
current entropy estimates of the two pools. Use with care. current entropy estimates of the two pools. Use with care.
@end deftypefun @end deftypefun
...@@ -2271,7 +2298,7 @@ Initializes the context. ...@@ -2271,7 +2298,7 @@ Initializes the context.
@deftypefun unsigned yarrow_key_event_estimate (struct yarrow_key_event_ctx *@var{ctx}, unsigned @var{key}, unsigned @var{time}) @deftypefun unsigned yarrow_key_event_estimate (struct yarrow_key_event_ctx *@var{ctx}, unsigned @var{key}, unsigned @var{time})
@var{key} is the id of the key (ASCII value, hardware key code, X @var{key} is the id of the key (ASCII value, hardware key code, X
keysym, @dots{} it doesn't matter), and @var{time} is the timestamp of keysym, @dots{}, it doesn't matter), and @var{time} is the timestamp of
the event. The time must be given in units matching the resolution by the event. The time must be given in units matching the resolution by
which you read the clock. If you read the clock with microsecond which you read the clock. If you read the clock with microsecond
precision, @var{time} should be provided in units of microseconds. But precision, @var{time} should be provided in units of microseconds. But
...@@ -2325,7 +2352,7 @@ variable @code{des_check_key}, and the functions @code{des_cbc_cksum} ...@@ -2325,7 +2352,7 @@ variable @code{des_check_key}, and the functions @code{des_cbc_cksum}
@node Nettle soup, Installation, Reference, Top @node Nettle soup, Installation, Reference, Top
@comment node-name, next, previous, up @comment node-name, next, previous, up
@chapter Traditional Nettle Soup @chapter Traditional Nettle Soup
For the serious nettle hacker, here is a recipe for nettle soup. 4 servings For the serious nettle hacker, here is a recipe for nettle soup. 4 servings.
@itemize @w{} @itemize @w{}
@item @item
...@@ -2396,12 +2423,20 @@ make install ...@@ -2396,12 +2423,20 @@ make install
@end example @end example
@noindent @noindent
to install in the default location, @file{/usr/local}. The library is to install in the default location, @file{/usr/local}. The library files
installed in @file{/use/local/lib/libnettle.a} and the include files are are installed in @file{/use/local/lib/libnettle.a}
installed in @file{/use/local/include/nettle/}. @file{/use/local/lib/libhogweed.a} and the include files are installed
in @file{/use/local/include/nettle/}.
To get a list of configure options, use @code{./configure --help}.
By default, only static libraries are built and installed. To also build
and install shared libraries, use the @option{ --enable-shared} option
to @command{./configure}.
By default, only static libraries are built and installed. To build and Using GNU make is recommended. For other make programs, in particular
install a shared library, use @code{./configure --enable-shared}. BSD make, you may have to use the @option{--disable-dependency-tracking}
option to @command{./configure}.
@node Index, , Installation, Top @node Index, , Installation, Top
@comment node-name, next, previous, up @comment node-name, next, previous, up
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment