glib2 1.1.8-x86-mingw32 → 1.1.9-x86-mingw32

data/vendor/local/share/info/nettle.info

@@ -0,0 +1,3355 @@
+This is nettle.info, produced by makeinfo version 4.13 from
+nettle.texinfo.
+
+This manual is for the Nettle library (version 2.5), a low-level
+cryptographic library.
+
+   Originally written 2001 by Niels Möller, updated 2011.
+
+     This manual is placed in the public domain. You may freely copy
+     it, in whole or in part, with or without modification. Attribution
+     is appreciated, but not required.
+
+INFO-DIR-SECTION Encryption
+START-INFO-DIR-ENTRY
+* Nettle: (nettle).             A low-level cryptographic library.
+END-INFO-DIR-ENTRY
+
+
+File: nettle.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
+
+Nettle
+******
+
+This document describes the Nettle low-level cryptographic library. You
+can use the library directly from your C programs, or write or use an
+object-oriented wrapper for your favorite language or application.
+
+   This manual is for the Nettle library (version 2.5), a low-level
+cryptographic library.
+
+   Originally written 2001 by Niels Möller, updated 2011.
+
+     This manual is placed in the public domain. You may freely copy
+     it, in whole or in part, with or without modification. Attribution
+     is appreciated, but not required.
+
+* Menu:
+
+* Introduction::                What is Nettle?
+* Copyright::                   Your rights.
+* Conventions::                 General interface conventions.
+* Example::                     An example program.
+* Linking::                     Linking with the libnettle and libhogweed.
+* Reference::                   All Nettle functions and features.
+* Nettle soup::                 For the serious nettle hacker.
+* Installation::                How to install Nettle.
+* Index::                       Function and concept index.
+
+ --- The Detailed Node Listing ---
+
+Reference
+
+* Hash functions::
+* Cipher functions::
+* Cipher modes::
+* Keyed hash functions::
+* Public-key algorithms::
+* Randomness::
+* Ascii encoding::
+* Miscellaneous functions::
+* Compatibility functions::
+
+Cipher modes
+
+* CBC::
+* CTR::
+* GCM::
+
+Public-key algorithms
+
+* RSA::                         The RSA public key algorithm.
+* DSA::                         The DSA digital signature algorithm.
+
+
+File: nettle.info,  Node: Introduction,  Next: Copyright,  Prev: Top,  Up: Top
+
+1 Introduction
+**************
+
+Nettle is a cryptographic library that is designed to fit easily in more
+or less any context: In crypto toolkits for object-oriented languages
+(C++, Python, Pike, ...), in applications like LSH or GNUPG, or even in
+kernel space. In most contexts, you need more than the basic
+cryptographic algorithms, you also need some way to keep track of
+available algorithms, their properties and variants. You often have
+some algorithm selection process, often dictated by a protocol you want
+to implement.
+
+   And as the requirements of applications differ in subtle and not so
+subtle ways, an API that fits one application well can be a pain to use
+in a different context. And that is why there are so many different
+cryptographic libraries around.
+
+   Nettle tries to avoid this problem by doing one thing, the low-level
+crypto stuff, and providing a _simple_ but general interface to it.  In
+particular, Nettle doesn't do algorithm selection. It doesn't do memory
+allocation. It doesn't do any I/O.
+
+   The idea is that one can build several application and context
+specific interfaces on top of Nettle, and share the code, test cases,
+benchmarks, documentation, etc. Examples are the Nettle module for the
+Pike language, and LSH, which both use an object-oriented abstraction
+on top of the library.
+
+   This manual explains how to use the Nettle library. It also tries to
+provide some background on the cryptography, and advice on how to best
+put it to use.
+
+
+File: nettle.info,  Node: Copyright,  Next: Conventions,  Prev: Introduction,  Up: Top
+
+2 Copyright
+***********
+
+Nettle is distributed under the GNU Lesser General Public License
+(LGPL), see the file COPYING.LIB for details. A few of the individual
+files are in the public domain. To find the current status of particular
+files, you have to read the copyright notices at the top of the files.
+
+   This manual is in the public domain. You may freely copy it in whole
+or in part, e.g., into documentation of programs that build on Nettle.
+Attribution, as well as contribution of improvements to the text, is of
+course appreciated, but it is not required.
+
+   A list of the supported algorithms, their origins and licenses:
+
+_AES_
+     The implementation of the AES cipher (also known as rijndael) is
+     written by Rafael Sevilla. Assembler for x86 by Rafael Sevilla and
+     Niels Möller, Sparc assembler by Niels Möller. Released under the
+     LGPL.
+
+_ARCFOUR_
+     The implementation of the ARCFOUR (also known as RC4) cipher is
+     written by Niels Möller. Released under the LGPL.
+
+_ARCTWO_
+     The implementation of the ARCTWO (also known as RC2) cipher is
+     written by Nikos Mavroyanopoulos and modified by Werner Koch and
+     Simon Josefsson. Released under the LGPL.
+
+_BLOWFISH_
+     The implementation of the BLOWFISH cipher is written by Werner
+     Koch, copyright owned by the Free Software Foundation. Also hacked
+     by Simon Josefsson and Niels Möller. Released under the LGPL.
+
+_CAMELLIA_
+     The C implementation is by Nippon Telegraph and Telephone
+     Corporation (NTT), heavily modified by Niels Möller. Assembler for
+     x86 and x86_64 by Niels Möller. Released under the LGPL.
+
+_CAST128_
+     The implementation of the CAST128 cipher is written by Steve Reid.
+     Released into the public domain.
+
+_DES_
+     The implementation of the DES cipher is written by Dana L. How, and
+     released under the LGPL.
+
+_MD2_
+     The implementation of MD2 is written by Andrew Kuchling, and hacked
+     some by Andreas Sigfridsson and Niels Möller. Python Cryptography
+     Toolkit license (essentially public domain).
+
+_MD4_
+     This is almost the same code as for MD5 below, with modifications
+     by Marcus Comstedt. Released into the public domain.
+
+_MD5_
+     The implementation of the MD5 message digest is written by Colin
+     Plumb.  It has been hacked some more by Andrew Kuchling and Niels
+     Möller.  Released into the public domain.
+
+_RIPMED160_
+     The implementation of RIPEMD160 message digest is based on the
+     code in libgcrypt, copyright owned by the Free Software
+     Foundation. Ported to Nettle by Andres Mejia. Released under the
+     LGPL.
+
+_SALSA20_
+     The C implementation of SALSA20 is based on D. J. Bernstein's
+     reference implementation (in the public domain), adapted to Nettle
+     by Simon Josefsson, and heavily modified by Niels Möller. Assembly
+     for x86_64 by Niels Möller. Released under the LGPL.
+
+_SERPENT_
+     The implementation of the SERPENT cipher is based on the code in
+     libgcrypt, copyright owned by the Free Software Foundation.
+     Adapted to Nettle by Simon Josefsson and heavily modified by Niels
+     Möller. Assembly for x86_64 by Niels Möller. Released under the
+     LGPL.
+
+_SHA1_
+     The C implementation of the SHA1 message digest is written by Peter
+     Gutmann, and hacked some more by Andrew Kuchling and Niels Möller.
+     Released into the public domain. Assembler for x86 by Niels Möller,
+     released under the LGPL.
+
+_SHA224, SHA256, SHA384, and SHA512_
+     Written by Niels Möller, using Peter Gutmann's SHA1 code as a
+     model.  Released under the LGPL.
+
+_TWOFISH_
+     The implementation of the TWOFISH cipher is written by Ruud de
+     Rooij.  Released under the LGPL.
+
+_RSA_
+     Written by Niels Möller, released under the LGPL. Uses the GMP
+     library for bignum operations.
+
+_DSA_
+     Written by Niels Möller, released under the LGPL. Uses the GMP
+     library for bignum operations.
+
+
+File: nettle.info,  Node: Conventions,  Next: Example,  Prev: Copyright,  Up: Top
+
+3 Conventions
+*************
+
+For each supported algorithm, there is an include file that defines a
+_context struct_, a few constants, and declares functions for operating
+on the context. The context struct encapsulates all information needed
+by the algorithm, and it can be copied or moved in memory with no
+unexpected effects.
+
+   For consistency, functions for different algorithms are very similar,
+but there are some differences, for instance reflecting if the key setup
+or encryption function differ for encryption and decryption, and whether
+or not key setup can fail. There are also differences between algorithms
+that don't show in function prototypes, but which the application must
+nevertheless be aware of. There is no big difference between the
+functions for stream ciphers and for block ciphers, although they should
+be used quite differently by the application.
+
+   If your application uses more than one algorithm of the same type,
+you should probably create an interface that is tailor-made for your
+needs, and then write a few lines of glue code on top of Nettle.
+
+   By convention, for an algorithm named `foo', the struct tag for the
+context struct is `foo_ctx', constants and functions uses prefixes like
+`FOO_BLOCK_SIZE' (a constant) and `foo_set_key' (a function).
+
+   In all functions, strings are represented with an explicit length, of
+type `unsigned', and a pointer of type `uint8_t *' or `const uint8_t
+*'. For functions that transform one string to another, the argument
+order is length, destination pointer and source pointer. Source and
+destination areas are of the same length. Source and destination may be
+the same, so that you can process strings in place, but they _must not_
+overlap in any other way.
+
+   Many of the functions lack return value and can never fail. Those
+functions which can fail, return one on success and zero on failure.
+
+
+File: nettle.info,  Node: Example,  Next: Linking,  Prev: Conventions,  Up: Top
+
+4 Example
+*********
+
+A simple example program that reads a file from standard input and
+writes its SHA1 checksum on standard output should give the flavor of
+Nettle.
+
+     #include <stdio.h>
+     #include <stdlib.h>
+
+     #include <nettle/sha.h>
+
+     #define BUF_SIZE 1000
+
+     static void
+     display_hex(unsigned length, uint8_t *data)
+     {
+       unsigned i;
+
+       for (i = 0; i<length; i++)
+         printf("%02x ", data[i]);
+
+       printf("\n");
+     }
+
+     int
+     main(int argc, char **argv)
+     {
+       struct sha1_ctx ctx;
+       uint8_t buffer[BUF_SIZE];
+       uint8_t digest[SHA1_DIGEST_SIZE];
+
+       sha1_init(&ctx);
+       for (;;)
+       {
+         int done = fread(buffer, 1, sizeof(buffer), stdin);
+         sha1_update(&ctx, done, buffer);
+         if (done < sizeof(buffer))
+           break;
+       }
+       if (ferror(stdin))
+         return EXIT_FAILURE;
+
+       sha1_digest(&ctx, SHA1_DIGEST_SIZE, digest);
+
+       display_hex(SHA1_DIGEST_SIZE, digest);
+       return EXIT_SUCCESS;
+     }
+
+   On a typical Unix system, this program can be compiled and linked
+with the command line
+     cc sha-example.c -o sha-example -lnettle
+
+
+File: nettle.info,  Node: Linking,  Next: Reference,  Prev: Example,  Up: Top
+
+5 Linking
+*********
+
+Nettle actually consists of two libraries, `libnettle' and
+`libhogweed'. The `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 `-lnettle'. If an application also uses public-key
+algorithms, the recommended linker flags are `-lhogweed -lnettle
+-lgmp'. If the involved libraries are installed as dynamic libraries, it
+may be sufficient to link with just `-lhogweed', and the loader will
+resolve the dependencies automatically.
+
+
+File: nettle.info,  Node: Reference,  Next: Nettle soup,  Prev: Linking,  Up: Top
+
+6 Reference
+***********
+
+This chapter describes all the Nettle functions, grouped by family.
+
+* Menu:
+
+* Hash functions::
+* Cipher functions::
+* Cipher modes::
+* Keyed hash functions::
+* Public-key algorithms::
+* Randomness::
+* Ascii encoding::
+* Miscellaneous functions::
+* Compatibility functions::
+
+
+File: nettle.info,  Node: Hash functions,  Next: Cipher functions,  Prev: Reference,  Up: Reference
+
+6.1 Hash functions
+==================
+
+A cryptographic "hash function" is a function that takes variable size
+strings, and maps them to strings of fixed, short, length. There are
+naturally lots of collisions, as there are more possible 1MB files than
+20 byte strings. But the function is constructed such that is hard to
+find the collisions. More precisely, a cryptographic hash function `H'
+should have the following properties:
+
+_One-way_
+     Given a hash value `H(x)' it is hard to find a string `x' that
+     hashes to that value.
+
+_Collision-resistant_
+     It is hard to find two different strings, `x' and `y', such that
+     `H(x)' = `H(y)'.
+
+
+   Hash functions are useful as building blocks for digital signatures,
+message authentication codes, pseudo random generators, association of
+unique ids to documents, and many other things.
+
+   The most commonly used hash functions are MD5 and SHA1.
+Unfortunately, both these fail the collision-resistance requirement;
+cryptologists have found ways to construct colliding inputs. The
+recommended hash function for new applications is SHA256, even though
+it uses a structure similar to MD5 and SHA1. Constructing better hash
+functions is an urgent research problem.
+
+6.1.1 MD5
+---------
+
+MD5 is a message digest function constructed by Ronald Rivest, and
+described in `RFC 1321'. It outputs message digests of 128 bits, or 16
+octets. Nettle defines MD5 in `<nettle/md5.h>'.
+
+ -- Context struct: struct md5_ctx
+
+ -- Constant: MD5_DIGEST_SIZE
+     The size of an MD5 digest, i.e. 16.
+
+ -- Constant: MD5_DATA_SIZE
+     The internal block size of MD5. Useful for some special
+     constructions, in particular HMAC-MD5.
+
+ -- Function: void md5_init (struct md5_ctx *CTX)
+     Initialize the MD5 state.
+
+ -- Function: void md5_update (struct md5_ctx *CTX, unsigned LENGTH,
+          const uint8_t *DATA)
+     Hash some more data.
+
+ -- Function: void md5_digest (struct md5_ctx *CTX, unsigned LENGTH,
+          uint8_t *DIGEST)
+     Performs final processing and extracts the message digest, writing
+     it to DIGEST. LENGTH may be smaller than `MD5_DIGEST_SIZE', in
+     which case only the first LENGTH octets of the digest are written.
+
+     This function also resets the context in the same way as
+     `md5_init'.
+
+   The normal way to use MD5 is to call the functions in order: First
+`md5_init', then `md5_update' zero or more times, and finally
+`md5_digest'. After `md5_digest', the context is reset to its initial
+state, so you can start over calling `md5_update' to hash new data.
+
+   To start over, you can call `md5_init' at any time.
+
+6.1.2 MD2
+---------
+
+MD2 is another hash function of Ronald Rivest's, described in `RFC
+1319'. It outputs message digests of 128 bits, or 16 octets.  Nettle
+defines MD2 in `<nettle/md2.h>'.
+
+ -- Context struct: struct md2_ctx
+
+ -- Constant: MD2_DIGEST_SIZE
+     The size of an MD2 digest, i.e. 16.
+
+ -- Constant: MD2_DATA_SIZE
+     The internal block size of MD2.
+
+ -- Function: void md2_init (struct md2_ctx *CTX)
+     Initialize the MD2 state.
+
+ -- Function: void md2_update (struct md2_ctx *CTX, unsigned LENGTH,
+          const uint8_t *DATA)
+     Hash some more data.
+
+ -- Function: void md2_digest (struct md2_ctx *CTX, unsigned LENGTH,
+          uint8_t *DIGEST)
+     Performs final processing and extracts the message digest, writing
+     it to DIGEST. LENGTH may be smaller than `MD2_DIGEST_SIZE', in
+     which case only the first LENGTH octets of the digest are written.
+
+     This function also resets the context in the same way as
+     `md2_init'.
+
+6.1.3 MD4
+---------
+
+MD4 is a predecessor of MD5, described in `RFC 1320'. Like MD5, it is
+constructed by Ronald Rivest. It outputs message digests of 128 bits,
+or 16 octets. Nettle defines MD4 in `<nettle/md4.h>'. Use of MD4 is not
+recommended, but it is sometimes needed for compatibility with existing
+applications and protocols.
+
+ -- Context struct: struct md4_ctx
+
+ -- Constant: MD4_DIGEST_SIZE
+     The size of an MD4 digest, i.e. 16.
+
+ -- Constant: MD4_DATA_SIZE
+     The internal block size of MD4.
+
+ -- Function: void md4_init (struct md4_ctx *CTX)
+     Initialize the MD4 state.
+
+ -- Function: void md4_update (struct md4_ctx *CTX, unsigned LENGTH,
+          const uint8_t *DATA)
+     Hash some more data.
+
+ -- Function: void md4_digest (struct md4_ctx *CTX, unsigned LENGTH,
+          uint8_t *DIGEST)
+     Performs final processing and extracts the message digest, writing
+     it to DIGEST. LENGTH may be smaller than `MD4_DIGEST_SIZE', in
+     which case only the first LENGTH octets of the digest are written.
+
+     This function also resets the context in the same way as
+     `md4_init'.
+
+6.1.4 RIPEMD160
+---------------
+
+RIPEMD160 is a hash function designed by Hans Dobbertin, Antoon
+Bosselaers, and Bart Preneel, as a strengthened version of RIPEMD
+(which, like MD4 and MD5, fails the collision-resistance requirement).
+It produces message digests of 160 bits, or 20 octets. Nettle defined
+RIPEMD160 in `nettle/ripemd160.h'.
+
+ -- Context struct: struct ripemd160_ctx
+
+ -- Constant: RIPEMD160_DIGEST_SIZE
+     The size of an RIPEMD160 digest, i.e. 20.
+
+ -- Constant: RIPEMD160_DATA_SIZE
+     The internal block size of RIPEMD160.
+
+ -- Function: void ripemd160_init (struct ripemd160_ctx *CTX)
+     Initialize the RIPEMD160 state.
+
+ -- Function: void ripemd160_update (struct ripemd160_ctx *CTX,
+          unsigned LENGTH, const uint8_t *DATA)
+     Hash some more data.
+
+ -- Function: void ripemd160_digest (struct ripemd160_ctx *CTX,
+          unsigned LENGTH, uint8_t *DIGEST)
+     Performs final processing and extracts the message digest, writing
+     it to DIGEST. LENGTH may be smaller than `RIPEMD160_DIGEST_SIZE',
+     in which case only the first LENGTH octets of the digest are
+     written.
+
+     This function also resets the context in the same way as
+     `ripemd160_init'.
+
+6.1.5 SHA1
+----------
+
+SHA1 is a hash function specified by "NIST" (The U.S. National Institute
+for Standards and Technology). It outputs hash values of 160 bits, or 20
+octets. Nettle defines SHA1 in `<nettle/sha.h>'.
+
+   The functions are analogous to the MD5 ones.
+
+ -- Context struct: struct sha1_ctx
+
+ -- Constant: SHA1_DIGEST_SIZE
+     The size of an SHA1 digest, i.e. 20.
+
+ -- Constant: SHA1_DATA_SIZE
+     The internal block size of SHA1. Useful for some special
+     constructions, in particular HMAC-SHA1.
+
+ -- Function: void sha1_init (struct sha1_ctx *CTX)
+     Initialize the SHA1 state.
+
+ -- Function: void sha1_update (struct sha1_ctx *CTX, unsigned LENGTH,
+          const uint8_t *DATA)
+     Hash some more data.
+
+ -- Function: void sha1_digest (struct sha1_ctx *CTX, unsigned LENGTH,
+          uint8_t *DIGEST)
+     Performs final processing and extracts the message digest, writing
+     it to DIGEST. LENGTH may be smaller than `SHA1_DIGEST_SIZE', in
+     which case only the first LENGTH octets of the digest are written.
+
+     This function also resets the context in the same way as
+     `sha1_init'.
+
+6.1.6 SHA256
+------------
+
+SHA256 is another hash function specified by "NIST", intended as a
+replacement for SHA1, generating larger digests. It outputs hash values
+of 256 bits, or 32 octets. Nettle defines SHA256 in `<nettle/sha.h>'.
+
+   The functions are analogous to the MD5 ones.
+
+ -- Context struct: struct sha256_ctx
+
+ -- Constant: SHA256_DIGEST_SIZE
+     The size of an SHA256 digest, i.e. 32.
+
+ -- Constant: SHA256_DATA_SIZE
+     The internal block size of SHA256. Useful for some special
+     constructions, in particular HMAC-SHA256.
+
+ -- Function: void sha256_init (struct sha256_ctx *CTX)
+     Initialize the SHA256 state.
+
+ -- Function: void sha256_update (struct sha256_ctx *CTX, unsigned
+          LENGTH, const uint8_t *DATA)
+     Hash some more data.
+
+ -- Function: void sha256_digest (struct sha256_ctx *CTX, unsigned
+          LENGTH, uint8_t *DIGEST)
+     Performs final processing and extracts the message digest, writing
+     it to DIGEST. LENGTH may be smaller than `SHA256_DIGEST_SIZE', in
+     which case only the first LENGTH octets of the digest are written.
+
+     This function also resets the context in the same way as
+     `sha256_init'.
+
+6.1.7 SHA224
+------------
+
+SHA224 is a variant of SHA256, with a different initial state, and with
+the output truncated to 224 bits, or 28 octets. Nettle defines SHA224 in
+`<nettle/sha.h>'.
+
+   The functions are analogous to the MD5 ones.
+
+ -- Context struct: struct sha224_ctx
+
+ -- Constant: SHA224_DIGEST_SIZE
+     The size of an SHA224 digest, i.e. 28.
+
+ -- Constant: SHA224_DATA_SIZE
+     The internal block size of SHA224. Useful for some special
+     constructions, in particular HMAC-SHA224.
+
+ -- Function: void sha224_init (struct sha224_ctx *CTX)
+     Initialize the SHA224 state.
+
+ -- Function: void sha224_update (struct sha224_ctx *CTX, unsigned
+          LENGTH, const uint8_t *DATA)
+     Hash some more data.
+
+ -- Function: void sha224_digest (struct sha224_ctx *CTX, unsigned
+          LENGTH, uint8_t *DIGEST)
+     Performs final processing and extracts the message digest, writing
+     it to DIGEST. LENGTH may be smaller than `SHA224_DIGEST_SIZE', in
+     which case only the first LENGTH octets of the digest are written.
+
+     This function also resets the context in the same way as
+     `sha224_init'.
+
+6.1.8 SHA512
+------------
+
+SHA512 is a larger sibling to SHA256, with a very similar structure but
+with both the output and the internal variables of twice the size. The
+internal variables are 64 bits rather than 32, making it significantly
+slower on 32-bit computers. It outputs hash values of 512 bits, or 64
+octets. Nettle defines SHA512 in `<nettle/sha.h>'.
+
+   The functions are analogous to the MD5 ones.
+
+ -- Context struct: struct sha512_ctx
+
+ -- Constant: SHA512_DIGEST_SIZE
+     The size of an SHA512 digest, i.e. 64.
+
+ -- Constant: SHA512_DATA_SIZE
+     The internal block size of SHA512. Useful for some special
+     constructions, in particular HMAC-SHA512.
+
+ -- Function: void sha512_init (struct sha512_ctx *CTX)
+     Initialize the SHA512 state.
+
+ -- Function: void sha512_update (struct sha512_ctx *CTX, unsigned
+          LENGTH, const uint8_t *DATA)
+     Hash some more data.
+
+ -- Function: void sha512_digest (struct sha512_ctx *CTX, unsigned
+          LENGTH, uint8_t *DIGEST)
+     Performs final processing and extracts the message digest, writing
+     it to DIGEST. LENGTH may be smaller than `SHA512_DIGEST_SIZE', in
+     which case only the first LENGTH octets of the digest are written.
+
+     This function also resets the context in the same way as
+     `sha512_init'.
+
+6.1.9 SHA384
+------------
+
+SHA384 is a variant of SHA512, with a different initial state, and with
+the output truncated to 384 bits, or 48 octets. Nettle defines SHA384 in
+`<nettle/sha.h>'.
+
+   The functions are analogous to the MD5 ones.
+
+ -- Context struct: struct sha384_ctx
+
+ -- Constant: SHA384_DIGEST_SIZE
+     The size of an SHA384 digest, i.e. 48.
+
+ -- Constant: SHA384_DATA_SIZE
+     The internal block size of SHA384. Useful for some special
+     constructions, in particular HMAC-SHA384.
+
+ -- Function: void sha384_init (struct sha384_ctx *CTX)
+     Initialize the SHA384 state.
+
+ -- Function: void sha384_update (struct sha384_ctx *CTX, unsigned
+          LENGTH, const uint8_t *DATA)
+     Hash some more data.
+
+ -- Function: void sha384_digest (struct sha384_ctx *CTX, unsigned
+          LENGTH, uint8_t *DIGEST)
+     Performs final processing and extracts the message digest, writing
+     it to DIGEST. LENGTH may be smaller than `SHA384_DIGEST_SIZE', in
+     which case only the first LENGTH octets of the digest are written.
+
+     This function also resets the context in the same way as
+     `sha384_init'.
+
+6.1.10 `struct nettle_hash'
+---------------------------
+
+Nettle includes a struct including information about the supported hash
+functions. It is defined in `<nettle/nettle-meta.h>', and is used by
+Nettle's implementation of HMAC (*note Keyed hash functions::).
+
+ -- Meta struct: `struct nettle_hash' name context_size digest_size
+          block_size init update digest
+     The last three attributes are function pointers, of types
+     `nettle_hash_init_func', `nettle_hash_update_func', and
+     `nettle_hash_digest_func'. The first argument to these functions is
+     `void *' pointer to a context struct, which is of size
+     `context_size'.
+
+ -- Constant Struct: struct nettle_hash nettle_md2
+ -- Constant Struct: struct nettle_hash nettle_md4
+ -- Constant Struct: struct nettle_hash nettle_md5
+ -- Constant Struct: struct nettle_hash nettle_ripemd160
+ -- Constant Struct: struct nettle_hash nettle_sha1
+ -- Constant Struct: struct nettle_hash nettle_sha224
+ -- Constant Struct: struct nettle_hash nettle_sha256
+ -- Constant Struct: struct nettle_hash nettle_sha384
+ -- Constant Struct: struct nettle_hash nettle_sha512
+     These are all the hash functions that Nettle implements.
+
+     Nettle also exports a list of all these hashes.  This list can be
+     used to dynamically enumerate or search the supported algorithms:
+
+ -- Constant Struct: struct nettle_hash ** nettle_hashes
+
+
+File: nettle.info,  Node: Cipher functions,  Next: Cipher modes,  Prev: Hash functions,  Up: Reference
+
+6.2 Cipher functions
+====================
+
+A "cipher" is a function that takes a message or "plaintext" and a
+secret "key" and transforms it to a "ciphertext". Given only the
+ciphertext, but not the key, it should be hard to find the plaintext.
+Given matching pairs of plaintext and ciphertext, it should be hard to
+find the key.
+
+   There are two main classes of ciphers: Block ciphers and stream
+ciphers.
+
+   A block cipher can process data only in fixed size chunks, called
+"blocks". Typical block sizes are 8 or 16 octets. To encrypt arbitrary
+messages, you usually have to pad it to an integral number of blocks,
+split it into blocks, and then process each block. The simplest way is
+to process one block at a time, independent of each other. That mode of
+operation is called "ECB", Electronic Code Book mode.  However, using
+ECB is usually a bad idea. For a start, plaintext blocks that are equal
+are transformed to ciphertext blocks that are equal; that leaks
+information about the plaintext. Usually you should apply the cipher is
+some "feedback mode", "CBC" (Cipher Block Chaining) and "CTR" (Counter
+mode) being two of of the most popular. See *Note Cipher modes::, for
+information on how to apply CBC and CTR with Nettle.
+
+   A stream cipher can be used for messages of arbitrary length. A
+typical stream cipher is a keyed pseudo-random generator. To encrypt a
+plaintext message of N octets, you key the generator, generate N octets
+of pseudo-random data, and XOR it with the plaintext. To decrypt,
+regenerate the same stream using the key, XOR it to the ciphertext, and
+the plaintext is recovered.
+
+   *Caution:* The first rule for this kind of cipher is the same as for
+a One Time Pad: _never_ ever use the same key twice.
+
+   A common misconception is that encryption, by itself, implies
+authentication. Say that you and a friend share a secret key, and you
+receive an encrypted message. You apply the key, and get a plaintext
+message that makes sense to you. Can you then be sure that it really was
+your friend that wrote the message you're reading? The answer is no. For
+example, if you were using a block cipher in ECB mode, an attacker may
+pick up the message on its way, and reorder, delete or repeat some of
+the blocks. Even if the attacker can't decrypt the message, he can
+change it so that you are not reading the same message as your friend
+wrote. If you are using a block cipher in CBC mode rather than ECB, or
+are using a stream cipher, the possibilities for this sort of attack
+are different, but the attacker can still make predictable changes to
+the message.
+
+   It is recommended to _always_ use an authentication mechanism in
+addition to encrypting the messages. Popular choices are Message
+Authentication Codes like HMAC-SHA1 (*note Keyed hash functions::), or
+digital signatures like RSA.
+
+   Some ciphers have so called "weak keys", keys that results in
+undesirable structure after the key setup processing, and should be
+avoided. In Nettle, most key setup functions have no return value, but
+for ciphers with weak keys, the return value indicates whether or not
+the given key is weak. For good keys, key setup returns 1, and for weak
+keys, it returns 0. When possible, avoid algorithms that have weak
+keys. There are several good ciphers that don't have any weak keys.
+
+   To encrypt a message, you first initialize a cipher context for
+encryption or decryption with a particular key. You then use the context
+to process plaintext or ciphertext messages. The initialization is known
+as "key setup". With Nettle, it is recommended to use each context
+struct for only one direction, even if some of the ciphers use a single
+key setup function that can be used for both encryption and decryption.
+
+6.2.1 AES
+---------
+
+AES is a block cipher, specified by NIST as a replacement for the older
+DES standard. The standard is the result of a competition between
+cipher designers. The winning design, also known as RIJNDAEL, was
+constructed by Joan Daemen and Vincent Rijnmen.
+
+   Like all the AES candidates, the winning design uses a block size of
+128 bits, or 16 octets, and variable key-size, 128, 192 and 256 bits
+(16, 24 and 32 octets) being the allowed key sizes. It does not have
+any weak keys. Nettle defines AES in `<nettle/aes.h>'.
+
+ -- Context struct: struct aes_ctx
+
+ -- Constant: AES_BLOCK_SIZE
+     The AES block-size, 16
+
+ -- Constant: AES_MIN_KEY_SIZE
+
+ -- Constant: AES_MAX_KEY_SIZE
+
+ -- Constant: AES_KEY_SIZE
+     Default AES key size, 32
+
+ -- Function: void aes_set_encrypt_key (struct aes_ctx *CTX, unsigned
+          LENGTH, const uint8_t *KEY)
+ -- Function: void aes_set_decrypt_key (struct aes_ctx *CTX, unsigned
+          LENGTH, const uint8_t *KEY)
+     Initialize the cipher, for encryption or decryption, respectively.
+
+ -- Function: void aes_invert_key (struct aes_ctx *DST, const struct
+          aes_ctx *SRC)
+     Given a context SRC initialized for encryption, initializes the
+     context struct DST for decryption, using the same key. If the same
+     context struct is passed for both `src' and `dst', it is converted
+     in place. Calling `aes_set_encrypt_key' and `aes_invert_key' is
+     more efficient than calling `aes_set_encrypt_key' and
+     `aes_set_decrypt_key'. This function is mainly useful for
+     applications which needs to both encrypt and decrypt using the
+     _same_ key.
+
+ -- Function: void aes_encrypt (struct aes_ctx *CTX, unsigned LENGTH,
+          uint8_t *DST, const uint8_t *SRC)
+     Encryption function. LENGTH must be an integral multiple of the
+     block size. If it is more than one block, the data is processed in
+     ECB mode. `src' and `dst' may be equal, but they must not overlap
+     in any other way.
+
+ -- Function: void aes_decrypt (struct aes_ctx *CTX, unsigned LENGTH,
+          uint8_t *DST, const uint8_t *SRC)
+     Analogous to `aes_encrypt'
+
+6.2.2 ARCFOUR
+-------------
+
+ARCFOUR is a stream cipher, also known under the trade marked name RC4,
+and it is one of the fastest ciphers around. A problem is that the key
+setup of ARCFOUR is quite weak, you should never use keys with
+structure, keys that are ordinary passwords, or sequences of keys like
+"secret:1", "secret:2", .... If you have keys that don't look like
+random bit strings, and you want to use ARCFOUR, always hash the key
+before feeding it to ARCFOUR. Furthermore, the initial bytes of the
+generated key stream leak information about the key; for this reason, it
+is recommended to discard the first 512 bytes of the key stream.
+
+     /* A more robust key setup function for ARCFOUR */
+     void
+     arcfour_set_key_hashed(struct arcfour_ctx *ctx,
+                            unsigned length, const uint8_t *key)
+     {
+       struct sha256_ctx hash;
+       uint8_t digest[SHA256_DIGEST_SIZE];
+       uint8_t buffer[0x200];
+
+       sha256_init(&hash);
+       sha256_update(&hash, length, key);
+       sha256_digest(&hash, SHA256_DIGEST_SIZE, digest);
+
+       arcfour_set_key(ctx, SHA256_DIGEST_SIZE, digest);
+       arcfour_crypt(ctx, sizeof(buffer), buffer, buffer);
+     }
+
+   Nettle defines ARCFOUR in `<nettle/arcfour.h>'.
+
+ -- Context struct: struct arcfour_ctx
+
+ -- Constant: ARCFOUR_MIN_KEY_SIZE
+     Minimum key size, 1
+
+ -- Constant: ARCFOUR_MAX_KEY_SIZE
+     Maximum key size, 256
+
+ -- Constant: ARCFOUR_KEY_SIZE
+     Default ARCFOUR key size, 16
+
+ -- Function: void arcfour_set_key (struct arcfour_ctx *CTX, unsigned
+          LENGTH, const uint8_t *KEY)
+     Initialize the cipher. The same function is used for both
+     encryption and decryption.
+
+ -- Function: void arcfour_crypt (struct arcfour_ctx *CTX, unsigned
+          LENGTH, uint8_t *DST, const uint8_t *SRC)
+     Encrypt some data. The same function is used for both encryption
+     and decryption. Unlike the block ciphers, this function modifies
+     the context, so you can split the data into arbitrary chunks and
+     encrypt them one after another. The result is the same as if you
+     had called `arcfour_crypt' only once with all the data.
+
+6.2.3 ARCTWO
+------------
+
+ARCTWO (also known as the trade marked name RC2) is a block cipher
+specified in RFC 2268. Nettle also include a variation of the ARCTWO
+set key operation that lack one step, to be compatible with the reverse
+engineered RC2 cipher description, as described in a Usenet post to
+`sci.crypt' by Peter Gutmann.
+
+   ARCTWO uses a block size of 64 bits, and variable key-size ranging
+from 1 to 128 octets. Besides the key, ARCTWO also has a second
+parameter to key setup, the number of effective key bits, `ekb'.  This
+parameter can be used to artificially reduce the key size. In practice,
+`ekb' is usually set equal to the input key size.  Nettle defines
+ARCTWO in `<nettle/arctwo.h>'.
+
+   We do not recommend the use of ARCTWO; the Nettle implementation is
+provided primarily for interoperability with existing applications and
+standards.
+
+ -- Context struct: struct arctwo_ctx
+
+ -- Constant: ARCTWO_BLOCK_SIZE
+     The ARCTWO block-size, 8
+
+ -- Constant: ARCTWO_MIN_KEY_SIZE
+
+ -- Constant: ARCTWO_MAX_KEY_SIZE
+
+ -- Constant: ARCTWO_KEY_SIZE
+     Default ARCTWO key size, 8
+
+ -- Function: void arctwo_set_key_ekb (struct arctwo_ctx *CTX, unsigned
+          LENGTH, const uint8_t *KEY, unsigned EKB)
+ -- Function: void arctwo_set_key (struct arctwo_ctx *CTX, unsigned
+          LENGTH, const uint8_t *KEY)
+ -- Function: void arctwo_set_key_gutmann (struct arctwo_ctx *CTX,
+          unsigned LENGTH, const uint8_t *KEY)
+     Initialize the cipher. The same function is used for both
+     encryption and decryption. The first function is the most general
+     one, which lets you provide both the variable size key, and the
+     desired effective key size (in bits). The maximum value for EKB is
+     1024, and for convenience, `ekb = 0' has the same effect as `ekb =
+     1024'.
+
+     `arctwo_set_key(ctx, length, key)' is equivalent to
+     `arctwo_set_key_ekb(ctx, length, key, 8*length)', and
+     `arctwo_set_key_gutmann(ctx, length, key)' is equivalent to
+     `arctwo_set_key_ekb(ctx, length, key, 1024)'
+
+ -- Function: void arctwo_encrypt (struct arctwo_ctx *CTX, unsigned
+          LENGTH, uint8_t *DST, const uint8_t *SRC)
+     Encryption function. LENGTH must be an integral multiple of the
+     block size. If it is more than one block, the data is processed in
+     ECB mode. `src' and `dst' may be equal, but they must not overlap
+     in any other way.
+
+ -- Function: void arctwo_decrypt (struct arctwo_ctx *CTX, unsigned
+          LENGTH, uint8_t *DST, const uint8_t *SRC)
+     Analogous to `arctwo_encrypt'
+
+6.2.4 BLOWFISH
+--------------
+
+BLOWFISH is a block cipher designed by Bruce Schneier. It uses a block
+size of 64 bits (8 octets), and a variable key size, up to 448 bits. It
+has some weak keys. Nettle defines BLOWFISH in `<nettle/blowfish.h>'.
+
+ -- Context struct: struct blowfish_ctx
+
+ -- Constant: BLOWFISH_BLOCK_SIZE
+     The BLOWFISH block-size, 8
+
+ -- Constant: BLOWFISH_MIN_KEY_SIZE
+     Minimum BLOWFISH key size, 8
+
+ -- Constant: BLOWFISH_MAX_KEY_SIZE
+     Maximum BLOWFISH key size, 56
+
+ -- Constant: BLOWFISH_KEY_SIZE
+     Default BLOWFISH key size, 16
+
+ -- Function: int blowfish_set_key (struct blowfish_ctx *CTX, unsigned
+          LENGTH, const uint8_t *KEY)
+     Initialize the cipher. The same function is used for both
+     encryption and decryption. Checks for weak keys, returning 1 for
+     good keys and 0 for weak keys. Applications that don't care about
+     weak keys can ignore the return value.
+
+     `blowfish_encrypt' or `blowfish_decrypt' with a weak key will
+     crash with an assert violation.
+
+ -- Function: void blowfish_encrypt (struct blowfish_ctx *CTX, unsigned
+          LENGTH, uint8_t *DST, const uint8_t *SRC)
+     Encryption function. LENGTH must be an integral multiple of the
+     block size. If it is more than one block, the data is processed in
+     ECB mode. `src' and `dst' may be equal, but they must not overlap
+     in any other way.
+
+ -- Function: void blowfish_decrypt (struct blowfish_ctx *CTX, unsigned
+          LENGTH, uint8_t *DST, const uint8_t *SRC)
+     Analogous to `blowfish_encrypt'
+
+6.2.5 Camellia
+--------------
+
+Camellia is a block cipher developed by Mitsubishi and Nippon Telegraph
+and Telephone Corporation, described in `RFC3713', and recommended by
+some Japanese and European authorities as an alternative to AES. The
+algorithm is patented. The implementation in Nettle is derived from the
+implementation released by NTT under the GNU LGPL (v2.1 or later), and
+relies on the implicit patent license of the LGPL. There is also a
+statement of royalty-free licensing for Camellia at
+`http://www.ntt.co.jp/news/news01e/0104/010417.html', but this
+statement has some limitations which seem problematic for free software.
+
+   Camellia uses a the same block size and key sizes as AES: The block
+size is 128 bits (16 octets), and the supported key sizes are 128, 192,
+and 256 bits. Nettle defines Camellia in `<nettle/camellia.h>'.
+
+ -- Context struct: struct camellia_ctx
+
+ -- Constant: CAMELLIA_BLOCK_SIZE
+     The CAMELLIA block-size, 16
+
+ -- Constant: CAMELLIA_MIN_KEY_SIZE
+
+ -- Constant: CAMELLIA_MAX_KEY_SIZE
+
+ -- Constant: CAMELLIA_KEY_SIZE
+     Default CAMELLIA key size, 32
+
+ -- Function: void camellia_set_encrypt_key (struct camellia_ctx *CTX,
+          unsigned LENGTH, const uint8_t *KEY)
+ -- Function: void camellia_set_decrypt_key (struct camellia_ctx *CTX,
+          unsigned LENGTH, const uint8_t *KEY)
+     Initialize the cipher, for encryption or decryption, respectively.
+
+ -- Function: void camellia_invert_key (struct camellia_ctx *DST, const
+          struct camellia_ctx *SRC)
+     Given a context SRC initialized for encryption, initializes the
+     context struct DST for decryption, using the same key. If the same
+     context struct is passed for both `src' and `dst', it is converted
+     in place. Calling `camellia_set_encrypt_key' and
+     `camellia_invert_key' is more efficient than calling
+     `camellia_set_encrypt_key' and `camellia_set_decrypt_key'. This
+     function is mainly useful for applications which needs to both
+     encrypt and decrypt using the _same_ key.
+
+ -- Function: void camellia_crypt (struct camellia_ctx *CTX, unsigned
+          LENGTH, uint8_t *DST, const uint8_t *SRC)
+     The same function is used for both encryption and decryption.
+     LENGTH must be an integral multiple of the block size. If it is
+     more than one block, the data is processed in ECB mode. `src' and
+     `dst' may be equal, but they must not overlap in any other way.
+
+6.2.6 CAST128
+-------------
+
+CAST-128 is a block cipher, specified in `RFC 2144'. It uses a 64 bit
+(8 octets) block size, and a variable key size of up to 128 bits.
+Nettle defines cast128 in `<nettle/cast128.h>'.
+
+ -- Context struct: struct cast128_ctx
+
+ -- Constant: CAST128_BLOCK_SIZE
+     The CAST128 block-size, 8
+
+ -- Constant: CAST128_MIN_KEY_SIZE
+     Minimum CAST128 key size, 5
+
+ -- Constant: CAST128_MAX_KEY_SIZE
+     Maximum CAST128 key size, 16
+
+ -- Constant: CAST128_KEY_SIZE
+     Default CAST128 key size, 16
+
+ -- Function: void cast128_set_key (struct cast128_ctx *CTX, unsigned
+          LENGTH, const uint8_t *KEY)
+     Initialize the cipher. The same function is used for both
+     encryption and decryption.
+
+ -- Function: void cast128_encrypt (struct cast128_ctx *CTX, unsigned
+          LENGTH, uint8_t *DST, const uint8_t *SRC)
+     Encryption function. LENGTH must be an integral multiple of the
+     block size. If it is more than one block, the data is processed in
+     ECB mode. `src' and `dst' may be equal, but they must not overlap
+     in any other way.
+
+ -- Function: void cast128_decrypt (struct cast128_ctx *CTX, unsigned
+          LENGTH, uint8_t *DST, const uint8_t *SRC)
+     Analogous to `cast128_encrypt'
+
+6.2.7 DES
+---------
+
+DES is the old Data Encryption Standard, specified by NIST. It uses a
+block size of 64 bits (8 octets), and a key size of 56 bits. However,
+the key bits are distributed over 8 octets, where the least significant
+bit of each octet may be used for parity. A common way to use DES is to
+generate 8 random octets in some way, then set the least significant bit
+of each octet to get odd parity, and initialize DES with the resulting
+key.
+
+   The key size of DES is so small that keys can be found by brute
+force, using specialized hardware or lots of ordinary work stations in
+parallel. One shouldn't be using plain DES at all today, if one uses
+DES at all one should be using "triple DES", see DES3 below.
+
+   DES also has some weak keys. Nettle defines DES in `<nettle/des.h>'.
+
+ -- Context struct: struct des_ctx
+
+ -- Constant: DES_BLOCK_SIZE
+     The DES block-size, 8
+
+ -- Constant: DES_KEY_SIZE
+     DES key size, 8
+
+ -- Function: int des_set_key (struct des_ctx *CTX, const uint8_t *KEY)
+     Initialize the cipher. The same function is used for both
+     encryption and decryption. Parity bits are ignored. Checks for
+     weak keys, returning 1 for good keys and 0 for weak keys.
+     Applications that don't care about weak keys can ignore the return
+     value.
+
+ -- Function: void des_encrypt (struct des_ctx *CTX, unsigned LENGTH,
+          uint8_t *DST, const uint8_t *SRC)
+     Encryption function. LENGTH must be an integral multiple of the
+     block size. If it is more than one block, the data is processed in
+     ECB mode. `src' and `dst' may be equal, but they must not overlap
+     in any other way.
+
+ -- Function: void des_decrypt (struct des_ctx *CTX, unsigned LENGTH,
+          uint8_t *DST, const uint8_t *SRC)
+     Analogous to `des_encrypt'
+
+ -- Function: int des_check_parity (unsigned LENGTH, const uint8_t
+          *KEY);
+     Checks that the given key has correct, odd, parity. Returns 1 for
+     correct parity, and 0 for bad parity.
+
+ -- Function: void des_fix_parity (unsigned LENGTH, uint8_t *DST, const
+          uint8_t *SRC)
+     Adjusts the parity bits to match DES's requirements. You need this
+     function if you have created a random-looking string by a key
+     agreement protocol, and want to use it as a DES key. DST and SRC
+     may be equal.
+
+6.2.8 DES3
+----------
+
+The inadequate key size of DES has already been mentioned. One way to
+increase the key size is to pipe together several DES boxes with
+independent keys. It turns out that using two DES ciphers is not as
+secure as one might think, even if the key size of the combination is a
+respectable 112 bits.
+
+   The standard way to increase DES's key size is to use three DES
+boxes.  The mode of operation is a little peculiar: the middle DES box
+is wired in the reverse direction. To encrypt a block with DES3, you
+encrypt it using the first 56 bits of the key, then _decrypt_ it using
+the middle 56 bits of the key, and finally encrypt it again using the
+last 56 bits of the key. This is known as "ede" triple-DES, for
+"encrypt-decrypt-encrypt".
+
+   The "ede" construction provides some backward compatibility, as you
+get plain single DES simply by feeding the same key to all three boxes.
+That should help keeping down the gate count, and the price, of hardware
+circuits implementing both plain DES and DES3.
+
+   DES3 has a key size of 168 bits, but just like plain DES, useless
+parity bits are inserted, so that keys are represented as 24 octets
+(192 bits).  As a 112 bit key is large enough to make brute force
+attacks impractical, some applications uses a "two-key" variant of
+triple-DES.  In this mode, the same key bits are used for the first and
+the last DES box in the pipe, while the middle box is keyed
+independently. The two-key variant is believed to be secure, i.e. there
+are no known attacks significantly better than brute force.
+
+   Naturally, it's simple to implement triple-DES on top of Nettle's DES
+functions. Nettle includes an implementation of three-key "ede"
+triple-DES, it is defined in the same place as plain DES,
+`<nettle/des.h>'.
+
+ -- Context struct: struct des3_ctx
+
+ -- Constant: DES3_BLOCK_SIZE
+     The DES3 block-size is the same as DES_BLOCK_SIZE, 8
+
+ -- Constant: DES3_KEY_SIZE
+     DES key size, 24
+
+ -- Function: int des3_set_key (struct des3_ctx *CTX, const uint8_t
+          *KEY)
+     Initialize the cipher. The same function is used for both
+     encryption and decryption. Parity bits are ignored. Checks for
+     weak keys, returning 1 if all three keys are good keys, and 0 if
+     one or more key is weak.  Applications that don't care about weak
+     keys can ignore the return value.
+
+   For random-looking strings, you can use `des_fix_parity' to adjust
+the parity bits before calling `des3_set_key'.
+
+ -- Function: void des3_encrypt (struct des3_ctx *CTX, unsigned LENGTH,
+          uint8_t *DST, const uint8_t *SRC)
+     Encryption function. LENGTH must be an integral multiple of the
+     block size. If it is more than one block, the data is processed in
+     ECB mode. `src' and `dst' may be equal, but they must not overlap
+     in any other way.
+
+ -- Function: void des3_decrypt (struct des3_ctx *CTX, unsigned LENGTH,
+          uint8_t *DST, const uint8_t *SRC)
+     Analogous to `des_encrypt'
+
+6.2.9 Salsa20
+-------------
+
+Salsa20 is a fairly recent stream cipher designed by D. J. Bernstein. It
+is built on the observation that a cryptographic hash function can be
+used for encryption: Form the hash input from the secret key and a
+counter, xor the hash output and the first block of the plaintext, then
+increment the counter to process the next block (similar to CTR mode,
+see *note CTR::). Bernstein defined an encryption algorithm, Snuffle,
+in this way to ridicule United States export restrictions which treated
+hash functions as nice and harmless, but ciphers as dangerous munitions.
+
+   Salsa20 uses the same idea, but with a new specialized hash function
+to mix key, block counter, and a couple of constants (input and output
+are the same size, making it not directly applicable for use as a
+general hash function). It's also designed for speed; on x86_64, it is
+currently the fastest cipher offered by nettle. It uses a block size of
+512 bits (64 octets) and there are two specified key sizes, 128 and 256
+bits (16 and 32 octets).
+
+   When using Salsa20 to process a message, one specifies both a key
+and a "nonce", the latter playing a similar rôle to the initialization
+vector (IV) used with CBC or CTR mode. For this reason, Nettle uses the
+term IV to refer to the Salsa20 nonce. One can use the same key for
+several messages, provided one uses a unique random iv for each
+message. The iv is 64 bits (8 octets). The block counter is initialized
+to zero for each message, and is also 64 bits (8 octets). Nettle
+defines Salsa20 in `<nettle/salsa20.h>'.
+
+ -- Context struct: struct salsa20_ctx
+
+ -- Constant: SALSA20_MIN_KEY_SIZE
+ -- Constant: SALSA20_MAX_KEY_SIZE
+     The two supported key sizes, 16 and 32 octets.
+
+ -- Constant: SALSA20_KEY_SIZE
+     Recommended key size, 32.
+
+ -- Constant: SALSA20_BLOCK_SIZE
+     Salsa20 block size, 64.
+
+ -- Constant: SALSA20_IV_SIZE
+     Size of the IV, 8.
+
+ -- Function: void salsa20_set_key (struct salsa20_ctx *CTX, unsigned
+          LENGTH, const uint8_t *KEY)
+     Initialize the cipher. The same function is used for both
+     encryption and decryption. Before using the cipher, you _must_
+     also call `salsa20_set_iv', see below.
+
+ -- Function: void salsa20_set_iv (struct salsa20_ctx *CTX, const
+          uint8_t *IV)
+     Sets the IV. It is always of size `SALSA20_IV_SIZE', 8 octets.
+     This function also initializes the block counter, setting it to
+     zero.
+
+ -- Function: void salsa20_crypt (struct salsa20_ctx *CTX, unsigned
+          LENGTH, uint8_t *DST, const uint8_t *SRC)
+     Encrypts or decrypts the data of a message, using salsa20. When a
+     message is encrypted using a sequence of calls to `salsa20_crypt',
+     all but the last call _must_ use a length that is a multiple of
+     `SALSA20_BLOCK_SIZE'.
+
+
+6.2.10 SERPENT
+--------------
+
+SERPENT is one of the AES finalists, designed by Ross Anderson, Eli
+Biham and Lars Knudsen. Thus, the interface and properties are similar
+to AES'. One peculiarity is that it is quite pointless to use it with
+anything but the maximum key size, smaller keys are just padded to
+larger ones. Nettle defines SERPENT in `<nettle/serpent.h>'.
+
+ -- Context struct: struct serpent_ctx
+
+ -- Constant: SERPENT_BLOCK_SIZE
+     The SERPENT block-size, 16
+
+ -- Constant: SERPENT_MIN_KEY_SIZE
+     Minimum SERPENT key size, 16
+
+ -- Constant: SERPENT_MAX_KEY_SIZE
+     Maximum SERPENT key size, 32
+
+ -- Constant: SERPENT_KEY_SIZE
+     Default SERPENT key size, 32
+
+ -- Function: void serpent_set_key (struct serpent_ctx *CTX, unsigned
+          LENGTH, const uint8_t *KEY)
+     Initialize the cipher. The same function is used for both
+     encryption and decryption.
+
+ -- Function: void serpent_encrypt (struct serpent_ctx *CTX, unsigned
+          LENGTH, uint8_t *DST, const uint8_t *SRC)
+     Encryption function. LENGTH must be an integral multiple of the
+     block size. If it is more than one block, the data is processed in
+     ECB mode. `src' and `dst' may be equal, but they must not overlap
+     in any other way.
+
+ -- Function: void serpent_decrypt (struct serpent_ctx *CTX, unsigned
+          LENGTH, uint8_t *DST, const uint8_t *SRC)
+     Analogous to `serpent_encrypt'
+
+6.2.11 TWOFISH
+--------------
+
+Another AES finalist, this one designed by Bruce Schneier and others.
+Nettle defines it in `<nettle/twofish.h>'.
+
+ -- Context struct: struct twofish_ctx
+
+ -- Constant: TWOFISH_BLOCK_SIZE
+     The TWOFISH block-size, 16
+
+ -- Constant: TWOFISH_MIN_KEY_SIZE
+     Minimum TWOFISH key size, 16
+
+ -- Constant: TWOFISH_MAX_KEY_SIZE
+     Maximum TWOFISH key size, 32
+
+ -- Constant: TWOFISH_KEY_SIZE
+     Default TWOFISH key size, 32
+
+ -- Function: void twofish_set_key (struct twofish_ctx *CTX, unsigned
+          LENGTH, const uint8_t *KEY)
+     Initialize the cipher. The same function is used for both
+     encryption and decryption.
+
+ -- Function: void twofish_encrypt (struct twofish_ctx *CTX, unsigned
+          LENGTH, uint8_t *DST, const uint8_t *SRC)
+     Encryption function. LENGTH must be an integral multiple of the
+     block size. If it is more than one block, the data is processed in
+     ECB mode. `src' and `dst' may be equal, but they must not overlap
+     in any other way.
+
+ -- Function: void twofish_decrypt (struct twofish_ctx *CTX, unsigned
+          LENGTH, uint8_t *DST, const uint8_t *SRC)
+     Analogous to `twofish_encrypt'
+
+6.2.12 `struct nettle_cipher'
+-----------------------------
+
+Nettle includes a struct including information about some of the more
+regular cipher functions. It should be considered a little experimental,
+but can be useful for applications that need a simple way to handle
+various algorithms. Nettle defines these structs in
+`<nettle/nettle-meta.h>'.
+
+ -- Meta struct: `struct nettle_cipher' name context_size block_size
+          key_size set_encrypt_key set_decrypt_key encrypt decrypt
+     The last four attributes are function pointers, of types
+     `nettle_set_key_func' and `nettle_crypt_func'. The first argument
+     to these functions is a `void *' pointer to a context struct,
+     which is of size `context_size'.
+
+ -- Constant Struct: struct nettle_cipher nettle_aes128
+ -- Constant Struct: struct nettle_cipher nettle_aes192
+ -- Constant Struct: struct nettle_cipher nettle_aes256
+ -- Constant Struct: struct nettle_cipher nettle_arctwo40;
+ -- Constant Struct: struct nettle_cipher nettle_arctwo64;
+ -- Constant Struct: struct nettle_cipher nettle_arctwo128;
+ -- Constant Struct: struct nettle_cipher nettle_arctwo_gutmann128;
+ -- Constant Struct: struct nettle_cipher nettle_arcfour128
+ -- Constant Struct: struct nettle_cipher nettle_camellia128
+ -- Constant Struct: struct nettle_cipher nettle_camellia192
+ -- Constant Struct: struct nettle_cipher nettle_camellia256
+ -- Constant Struct: struct nettle_cipher nettle_cast128
+ -- Constant Struct: struct nettle_cipher nettle_serpent128
+ -- Constant Struct: struct nettle_cipher nettle_serpent192
+ -- Constant Struct: struct nettle_cipher nettle_serpent256
+ -- Constant Struct: struct nettle_cipher nettle_twofish128
+ -- Constant Struct: struct nettle_cipher nettle_twofish192
+ -- Constant Struct: struct nettle_cipher nettle_twofish256
+     Nettle includes such structs for all the _regular_ ciphers, i.e.
+     ones without weak keys or other oddities.
+
+     Nettle also exports a list of all these ciphers without weak keys
+     or other oddities.  This list can be used to dynamically enumerate
+     or search the supported algorithms:
+
+ -- Constant Struct: struct nettle_cipher ** nettle_ciphers
+
+
+File: nettle.info,  Node: Cipher modes,  Next: Keyed hash functions,  Prev: Cipher functions,  Up: Reference
+
+6.3 Cipher modes
+================
+
+Cipher modes of operation specifies the procedure to use when encrypting
+a message that is larger than the cipher's block size. As explained in
+*Note Cipher functions::, splitting the message into blocks and
+processing them independently with the block cipher (Electronic Code
+Book mode, ECB) leaks information. Besides ECB, Nettle provides three
+other modes of operation: Cipher Block Chaining (CBC), Counter mode
+(CTR), and Galois/Counter mode (gcm). CBC is widely used, but there are
+a few subtle issues of information leakage, see, e.g., SSH CBC
+vulnerability (http://www.kb.cert.org/vuls/id/958563). CTR and GCM were
+standardized more recently, and are believed to be more secure.  GCM
+includes message authentication; for the other modes, one should always
+use a MAC (*note Keyed hash functions::) or signature to authenticate
+the message.
+
+* Menu:
+
+* CBC::
+* CTR::
+* GCM::
+
+
+File: nettle.info,  Node: CBC,  Next: CTR,  Prev: Cipher modes,  Up: Cipher modes
+
+6.3.1 Cipher Block Chaining
+---------------------------
+
+When using CBC mode, plaintext blocks are not encrypted independently
+of each other, like in Electronic Cook Book mode. Instead, when
+encrypting a block in CBC mode, the previous ciphertext block is XORed
+with the plaintext before it is fed to the block cipher.  When
+encrypting the first block, a random block called an "IV", or
+Initialization Vector, is used as the "previous ciphertext block". The
+IV should be chosen randomly, but it need not be kept secret, and can
+even be transmitted in the clear together with the encrypted data.
+
+   In symbols, if `E_k' is the encryption function of a block cipher,
+and `IV' is the initialization vector, then `n' plaintext blocks
+`M_1',... `M_n' are transformed into `n' ciphertext blocks `C_1',...
+`C_n' as follows:
+
+     C_1 = E_k(IV  XOR M_1)
+     C_2 = E_k(C_1 XOR M_2)
+
+     ...
+
+     C_n = E_k(C_(n-1) XOR M_n)
+
+   Nettle's includes two functions for applying a block cipher in Cipher
+Block Chaining (CBC) mode, one for encryption and one for decryption.
+These functions uses `void *' to pass cipher contexts around.
+
+ -- Function: void cbc_encrypt (void *CTX, nettle_crypt_func F,
+          unsigned BLOCK_SIZE, uint8_t *IV, unsigned LENGTH, uint8_t
+          *DST, const uint8_t *SRC)
+ -- Function: void cbc_decrypt (void *CTX, void (*F)(), unsigned
+          BLOCK_SIZE, uint8_t *IV, unsigned LENGTH, uint8_t *DST, const
+          uint8_t *SRC)
+     Applies the encryption or decryption function F in CBC mode. The
+     final ciphertext block processed is copied into IV before
+     returning, so that large message be processed be a sequence of
+     calls to `cbc_encrypt'. The function F is of type
+
+     `void f (void *CTX, unsigned LENGTH, uint8_t DST, const uint8_t
+     *SRC)',
+
+     and the `cbc_encrypt' and `cbc_decrypt' functions pass their
+     argument CTX on to F.
+
+   There are also some macros to help use these functions correctly.
+
+ -- Macro: CBC_CTX (CONTEXT_TYPE, BLOCK_SIZE)
+     Expands to
+          {
+             context_type ctx;
+             uint8_t iv[block_size];
+          }
+
+   It can be used to define a CBC context struct, either directly,
+
+     struct CBC_CTX(struct aes_ctx, AES_BLOCK_SIZE) ctx;
+
+   or to give it a struct tag,
+
+     struct aes_cbc_ctx CBC_CTX (struct aes_ctx, AES_BLOCK_SIZE);
+
+ -- Macro: CBC_SET_IV (CTX, IV)
+     First argument is a pointer to a context struct as defined by
+     `CBC_CTX', and the second is a pointer to an Initialization Vector
+     (IV) that is copied into that context.
+
+ -- Macro: CBC_ENCRYPT (CTX, F, LENGTH, DST, SRC)
+ -- Macro: CBC_DECRYPT (CTX, F, LENGTH, DST, SRC)
+     A simpler way to invoke `cbc_encrypt' and `cbc_decrypt'. The first
+     argument is a pointer to a context struct as defined by `CBC_CTX',
+     and the second argument is an encryption or decryption function
+     following Nettle's conventions. The last three arguments define
+     the source and destination area for the operation.
+
+   These macros use some tricks to make the compiler display a warning
+if the types of F and CTX don't match, e.g. if you try to use an
+`struct aes_ctx' context with the `des_encrypt' function.
+
+
+File: nettle.info,  Node: CTR,  Next: GCM,  Prev: CBC,  Up: Cipher modes
+
+6.3.2 Counter mode
+------------------
+
+Counter mode (CTR) uses the block cipher as a keyed pseudo-random
+generator. The output of the generator is XORed with the data to be
+encrypted. It can be understood as a way to transform a block cipher to
+a stream cipher.
+
+   The message is divided into `n' blocks `M_1',...  `M_n', where `M_n'
+is of size `m' which may be smaller than the block size. Except for the
+last block, all the message blocks must be of size equal to the
+cipher's block size.
+
+   If `E_k' is the encryption function of a block cipher, `IC' is the
+initial counter, then the `n' plaintext blocks are transformed into `n'
+ciphertext blocks `C_1',...  `C_n' as follows:
+
+     C_1 = E_k(IC) XOR M_1
+     C_2 = E_k(IC + 1) XOR M_2
+
+     ...
+
+     C_(n-1) = E_k(IC + n - 2) XOR M_(n-1)
+     C_n = E_k(IC + n - 1) [1..m] XOR M_n
+
+   The IC is the initial value for the counter, it plays a similar rôle
+as the IV for CBC. When adding, `IC + x', IC is interpreted as an
+integer, in network byte order. For the last block, `E_k(IC + n - 1)
+[1..m]' means that the cipher output is truncated to `m' bytes.
+
+ -- Function: void ctr_crypt (void *CTX, nettle_crypt_func F, unsigned
+          BLOCK_SIZE, uint8_t *CTR, unsigned LENGTH, uint8_t *DST,
+          const uint8_t *SRC)
+     Applies the encryption function F in CTR mode. Note that for CTR
+     mode, encryption and decryption is the same operation, and hence F
+     should always be the encryption function for the underlying block
+     cipher.
+
+     When a message is encrypted using a sequence of calls to
+     `ctr_crypt', all but the last call _must_ use a length that is a
+     multiple of the block size.
+
+   Like for CBC, there are also a couple of helper macros.
+
+ -- Macro: CTR_CTX (CONTEXT_TYPE, BLOCK_SIZE)
+     Expands to
+          {
+             context_type ctx;
+             uint8_t ctr[block_size];
+          }
+
+ -- Macro: CTR_SET_COUNTER (CTX, IV)
+     First argument is a pointer to a context struct as defined by
+     `CTR_CTX', and the second is a pointer to an initial counter that
+     is copied into that context.
+
+ -- Macro: CTR_CRYPT (CTX, F, LENGTH, DST, SRC)
+     A simpler way to invoke `ctr_crypt'. The first argument is a
+     pointer to a context struct as defined by `CTR_CTX', and the second
+     argument is an encryption function following Nettle's conventions.
+     The last three arguments define the source and destination area
+     for the operation.
+
+
+File: nettle.info,  Node: GCM,  Prev: CTR,  Up: Cipher modes
+
+6.3.3 Galois counter mode
+-------------------------
+
+Galois counter mode is the combination of counter mode with message
+authentication based on universal hashing. The main objective of the
+design is to provide high performance for hardware implementations,
+where other popular MAC algorithms (*note Keyed hash functions::
+becomes a bottleneck for high-speed hardware implementations.  It was
+proposed by David A. McGrew and John Viega in 2005, and recommended by
+NIST in 2007, NIST Special Publication 800-38D
+(http://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf). It
+is constructed on top of a block cipher which must have a block size of
+128 bits.
+
+   GCM is applied to messages of arbitrary length. The inputs are:
+
+   * A key, which can be used for many messages.
+
+   * An initialization vector (IV) which _must_ be unique for each
+     message.
+
+   * Additional authenticated data, which is to be included in the
+     message authentication, but not encrypted. May be empty.
+
+   * The plaintext. Maybe empty.
+
+   The outputs are a ciphertext, of the same length as the plaintext,
+and a message digest of length 128 bits. Nettle's support for GCM
+consists of a low-level general interface, some convenience macros, and
+specific functions for GCM using AES as the underlying cipher. These
+interfaces are defined in `<nettle/gcm.h>'
+
+6.3.3.1 General GCM interface
+.............................
+
+ -- Context struct: struct gcm_key
+     Message independent hash subkey, and related tables.
+
+ -- Context struct: struct gcm_ctx
+     Holds state corresponding to a particular message.
+
+ -- Constant: GCM_BLOCK_SIZE
+     GCM's block size, 16.
+
+ -- Constant: GCM_IV_SIZE
+     Recommended size of the IV, 12. Other sizes are allowed.
+
+ -- Function: void gcm_set_key (struct gcm_key *KEY, void *CIPHER,
+          nettle_crypt_func *F)
+     Initializes KEY. CIPHER gives a context struct for the underlying
+     cipher, which must have been previously initialized for
+     encryption, and F is the encryption function.
+
+ -- Function: void gcm_set_iv (struct gcm_ctx *CTX, const struct
+          gcm_key *KEY, unsigned LENGTH, const uint8_t *IV)
+     Initializes CTX using the given IV. The KEY argument is actually
+     needed only if LENGTH differs from `GCM_IV_SIZE'.
+
+ -- Function: void gcm_update (struct gcm_ctx *CTX, const struct
+          gcm_key *KEY, unsigned LENGTH, const uint8_t *DATA)
+     Provides associated data to be authenticated. If used, must be
+     called before `gcm_encrypt' or `gcm_decrypt'. All but the last call
+     for each message _must_ use a length that is a multiple of the
+     block size.
+
+ -- Function: void gcm_encrypt (struct gcm_ctx *CTX, const struct
+          gcm_key *KEY void *CIPHER, nettle_crypt_func *F, unsigned
+          LENGTH, uint8_t *DST, const uint8_t *SRC)
+ -- Function: void gcm_decrypt (struct gcm_ctx *CTX, const struct
+          gcm_key *KEY, void *CIPHER, nettle_crypt_func *F, unsigned
+          LENGTH, uint8_t *DST, const uint8_t *SRC)
+     Encrypts or decrypts the data of a message. CIPHER is the context
+     struct for the underlying cipher and F is the encryption function.
+     All but the last call for each message _must_ use a length that is
+     a multiple of the block size.
+
+ -- Function: void gcm_digest (struct gcm_ctx *CTX, const struct
+          gcm_key *KEY, void *CIPHER, nettle_crypt_func *F, unsigned
+          LENGTH, uint8_t *DIGEST)
+     Extracts the message digest (also known "authentication tag").
+     This is the final operation when processing a message. LENGTH is
+     usually equal to `GCM_BLOCK_SIZE', but if you provide a smaller
+     value, only the first LENGTH octets of the digest are written.
+
+   To encrypt a message using GCM, first initialize a context for the
+underlying block cipher with a key to use for encryption. Then call the
+above functions in the following order: `gcm_set_key', `gcm_set_iv',
+`gcm_update', `gcm_encrypt', `gcm_digest'. The decryption procedure is
+analogous, just calling `gcm_decrypt' instead of `gcm_encrypt' (note
+that GCM decryption still uses the encryption function of the
+underlying block cipher). To process a new message, using the same key,
+call `gcm_set_iv' with a new iv.
+
+6.3.3.2 GCM helper macros
+.........................
+
+The following macros are defined.
+
+ -- Macro: GCM_CTX (CONTEXT_TYPE)
+     This defines an all-in-one context struct, including the context
+     of the underlying cipher, the hash subkey, and the per-message
+     state. It expands to
+          {
+             context_type cipher;
+             struct gcm_key key;
+             struct gcm_ctx gcm;
+          }
+
+   Example use:
+     struct gcm_aes_ctx GCM_CTX(struct aes_ctx);
+
+   The following macros operate on context structs of this form.
+
+ -- Macro: GCM_SET_KEY (CTX, SET_KEY, ENCRYPT, LENGTH, DATA)
+     First argument, CTX, is a context struct as defined by `GCM_CTX'.
+     SET_KEY and ENCRYPT are functions for setting the encryption key
+     and for encrypting data using the underlying cipher. LENGTH and
+     DATA give the key.
+
+ -- Macro: GCM_SET_IV (CTX, LENGTH, DATA)
+     First argument is a context struct as defined by `GCM_CTX'. LENGTH
+     and DATA give the initialization vector (IV).
+
+ -- Macro: GCM_UPDATE (CTX, LENGTH, DATA)
+     Simpler way to call `gcm_update'. First argument is a context
+     struct as defined by `GCM_CTX'
+
+ -- Macro: GCM_ENCRYPT (CTX, ENCRYPT, LENGTH, DST, SRC)
+ -- Macro: GCM_DECRYPT (CTX, ENCRYPT, LENGTH, DST, SRC)
+ -- Macro: GCM_DIGEST (CTX, ENCRYPT, LENGTH, DIGEST)
+     Simpler way to call `gcm_encrypt', `gcm_decrypt' or `gcm_digest'.
+     First argument is a context struct as defined by `GCM_CTX'. Second
+     argument, ENCRYPT, is a pointer to the encryption function of the
+     underlying cipher.
+
+6.3.3.3 GCM-AES interface
+.........................
+
+The following functions implement the common case of GCM using AES as
+the underlying cipher.
+
+ -- Context struct: struct gcm_aes_ctx
+     The context struct, defined using `GCM_CTX'.
+
+ -- Function: void gcm_aes_set_key (struct gcm_aes_ctx *CTX, unsigned
+          LENGTH, const uint8_t *KEY)
+     Initializes CTX using the given key. All valid AES key sizes can
+     be used.
+
+ -- Function: void gcm_aes_set_iv (struct gcm_aes_ctx *CTX, unsigned
+          LENGTH, const uint8_t *IV)
+     Initializes the per-message state, using the given IV.
+
+ -- Function: void gcm_aes_update (struct gcm_aes_ctx *CTX, unsigned
+          LENGTH, const uint8_t *DATA)
+     Provides associated data to be authenticated. If used, must be
+     called before `gcm_aes_encrypt' or `gcm_aes_decrypt'. All but the
+     last call for each message _must_ use a length that is a multiple
+     of the block size.
+
+ -- Function: void gcm_aes_encrypt (struct gcm_aes_ctx *CTX, unsigned
+          LENGTH, uint8_t *DST, const uint8_t *SRC)
+ -- Function: void gcm_aes_decrypt (struct gcm_aes_ctx *CTX, unsigned
+          LENGTH, uint8_t *DST, const uint8_t *SRC)
+     Encrypts or decrypts the data of a message. All but the last call
+     for each message _must_ use a length that is a multiple of the
+     block size.
+
+
+ -- Function: void gcm_aes_digest (struct gcm_aes_ctx *CTX, unsigned
+          LENGTH, uint8_t *DIGEST)
+     Extracts the message digest (also known "authentication tag").
+     This is the final operation when processing a message. LENGTH is
+     usually equal to `GCM_BLOCK_SIZE', but if you provide a smaller
+     value, only the first LENGTH octets of the digest are written.
+
+
+File: nettle.info,  Node: Keyed hash functions,  Next: Public-key algorithms,  Prev: Cipher modes,  Up: Reference
+
+6.4 Keyed Hash Functions
+========================
+
+A "keyed hash function", or "Message Authentication Code" (MAC) is a
+function that takes a key and a message, and produces fixed size MAC.
+It should be hard to compute a message and a matching MAC without
+knowledge of the key. It should also be hard to compute the key given
+only messages and corresponding MACs.
+
+   Keyed hash functions are useful primarily for message authentication,
+when Alice and Bob shares a secret: The sender, Alice, computes the MAC
+and attaches it to the message. The receiver, Bob, also computes the
+MAC of the message, using the same key, and compares that to Alice's
+value. If they match, Bob can be assured that the message has not been
+modified on its way from Alice.
+
+   However, unlike digital signatures, this assurance is not
+transferable.  Bob can't show the message and the MAC to a third party
+and prove that Alice sent that message. Not even if he gives away the
+key to the third party. The reason is that the _same_ key is used on
+both sides, and anyone knowing the key can create a correct MAC for any
+message. If Bob believes that only he and Alice knows the key, and he
+knows that he didn't attach a MAC to a particular message, he knows it
+must be Alice who did it. However, the third party can't distinguish
+between a MAC created by Alice and one created by Bob.
+
+   Keyed hash functions are typically a lot faster than digital
+signatures as well.
+
+6.4.1 HMAC
+----------
+
+One can build keyed hash functions from ordinary hash functions. Older
+constructions simply concatenate secret key and message and hashes
+that, but such constructions have weaknesses. A better construction is
+HMAC, described in `RFC 2104'.
+
+   For an underlying hash function `H', with digest size `l' and
+internal block size `b', HMAC-H is constructed as follows: From a given
+key `k', two distinct subkeys `k_i' and `k_o' are constructed, both of
+length `b'. The HMAC-H of a message `m' is then computed as `H(k_o |
+H(k_i | m))', where `|' denotes string concatenation.
+
+   HMAC keys can be of any length, but it is recommended to use keys of
+length `l', the digest size of the underlying hash function `H'. Keys
+that are longer than `b' are shortened to length `l' by hashing with
+`H', so arbitrarily long keys aren't very useful.
+
+   Nettle's HMAC functions are defined in `<nettle/hmac.h>'.  There are
+abstract functions that use a pointer to a `struct nettle_hash' to
+represent the underlying hash function and `void *' pointers that point
+to three different context structs for that hash function. There are
+also concrete functions for HMAC-MD5, HMAC-RIPEMD160 HMAC-SHA1,
+HMAC-SHA256, and HMAC-SHA512. First, the abstract functions:
+
+ -- Function: void hmac_set_key (void *OUTER, void *INNER, void *STATE,
+          const struct nettle_hash *H, unsigned LENGTH, const uint8_t
+          *KEY)
+     Initializes the three context structs from the key. The OUTER and
+     INNER contexts corresponds to the subkeys `k_o' and `k_i'. STATE
+     is used for hashing the message, and is initialized as a copy of
+     the INNER context.
+
+ -- Function: void hmac_update (void *STATE, const struct nettle_hash
+          *H, unsigned LENGTH, const uint8_t *DATA)
+     This function is called zero or more times to process the message.
+     Actually, `hmac_update(state, H, length, data)' is equivalent to
+     `H->update(state, length, data)', so if you wish you can use the
+     ordinary update function of the underlying hash function instead.
+
+ -- Function: void hmac_digest (const void *OUTER, const void *INNER,
+          void *STATE, const struct nettle_hash *H, unsigned LENGTH,
+          uint8_t *DIGEST)
+     Extracts the MAC of the message, writing it to DIGEST.  OUTER and
+     INNER are not modified. LENGTH is usually equal to
+     `H->digest_size', but if you provide a smaller value, only the
+     first LENGTH octets of the MAC are written.
+
+     This function also resets the STATE context so that you can start
+     over processing a new message (with the same key).
+
+   Like for CBC, there are some macros to help use these functions
+correctly.
+
+ -- Macro: HMAC_CTX (TYPE)
+     Expands to
+          {
+             type outer;
+             type inner;
+             type state;
+          }
+
+   It can be used to define a HMAC context struct, either directly,
+
+     struct HMAC_CTX(struct md5_ctx) ctx;
+
+   or to give it a struct tag,
+
+     struct hmac_md5_ctx HMAC_CTX (struct md5_ctx);
+
+ -- Macro: HMAC_SET_KEY (CTX, H, LENGTH, KEY)
+     CTX is a pointer to a context struct as defined by `HMAC_CTX', H
+     is a pointer to a `const struct nettle_hash' describing the
+     underlying hash function (so it must match the type of the
+     components of CTX). The last two arguments specify the secret key.
+
+ -- Macro: HMAC_DIGEST (CTX, H, LENGTH, DIGEST)
+     CTX is a pointer to a context struct as defined by `HMAC_CTX', H
+     is a pointer to a `const struct nettle_hash' describing the
+     underlying hash function. The last two arguments specify where the
+     digest is written.
+
+   Note that there is no `HMAC_UPDATE' macro; simply call `hmac_update'
+function directly, or the update function of the underlying hash
+function.
+
+6.4.2 Concrete HMAC functions
+-----------------------------
+
+Now we come to the specialized HMAC functions, which are easier to use
+than the general HMAC functions.
+
+6.4.2.1 HMAC-MD5
+................
+
+ -- Context struct: struct hmac_md5_ctx
+
+ -- Function: void hmac_md5_set_key (struct hmac_md5_ctx *CTX, unsigned
+          KEY_LENGTH, const uint8_t *KEY)
+     Initializes the context with the key.
+
+ -- Function: void hmac_md5_update (struct hmac_md5_ctx *CTX, unsigned
+          LENGTH, const uint8_t *DATA)
+     Process some more data.
+
+ -- Function: void hmac_md5_digest (struct hmac_md5_ctx *CTX, unsigned
+          LENGTH, uint8_t *DIGEST)
+     Extracts the MAC, writing it to DIGEST. LENGTH may be smaller than
+     `MD5_DIGEST_SIZE', in which case only the first LENGTH octets of
+     the MAC are written.
+
+     This function also resets the context for processing new messages,
+     with the same key.
+
+6.4.2.2 HMAC-RIPEMD160
+......................
+
+ -- Context struct: struct hmac_ripemd160_ctx
+
+ -- Function: void hmac_ripemd160_set_key (struct hmac_ripemd160_ctx
+          *CTX, unsigned KEY_LENGTH, const uint8_t *KEY)
+     Initializes the context with the key.
+
+ -- Function: void hmac_ripemd160_update (struct hmac_ripemd160_ctx
+          *CTX, unsigned LENGTH, const uint8_t *DATA)
+     Process some more data.
+
+ -- Function: void hmac_ripemd160_digest (struct hmac_ripemd160_ctx
+          *CTX, unsigned LENGTH, uint8_t *DIGEST)
+     Extracts the MAC, writing it to DIGEST. LENGTH may be smaller than
+     `RIPEMD160_DIGEST_SIZE', in which case only the first LENGTH
+     octets of the MAC are written.
+
+     This function also resets the context for processing new messages,
+     with the same key.
+
+6.4.2.3 HMAC-SHA1
+.................
+
+ -- Context struct: struct hmac_sha1_ctx
+
+ -- Function: void hmac_sha1_set_key (struct hmac_sha1_ctx *CTX,
+          unsigned KEY_LENGTH, const uint8_t *KEY)
+     Initializes the context with the key.
+
+ -- Function: void hmac_sha1_update (struct hmac_sha1_ctx *CTX,
+          unsigned LENGTH, const uint8_t *DATA)
+     Process some more data.
+
+ -- Function: void hmac_sha1_digest (struct hmac_sha1_ctx *CTX,
+          unsigned LENGTH, uint8_t *DIGEST)
+     Extracts the MAC, writing it to DIGEST. LENGTH may be smaller than
+     `SHA1_DIGEST_SIZE', in which case only the first LENGTH octets of
+     the MAC are written.
+
+     This function also resets the context for processing new messages,
+     with the same key.
+
+6.4.2.4 HMAC-SHA256
+...................
+
+ -- Context struct: struct hmac_sha256_ctx
+
+ -- Function: void hmac_sha256_set_key (struct hmac_sha256_ctx *CTX,
+          unsigned KEY_LENGTH, const uint8_t *KEY)
+     Initializes the context with the key.
+
+ -- Function: void hmac_sha256_update (struct hmac_sha256_ctx *CTX,
+          unsigned LENGTH, const uint8_t *DATA)
+     Process some more data.
+
+ -- Function: void hmac_sha256_digest (struct hmac_sha256_ctx *CTX,
+          unsigned LENGTH, uint8_t *DIGEST)
+     Extracts the MAC, writing it to DIGEST. LENGTH may be smaller than
+     `SHA256_DIGEST_SIZE', in which case only the first LENGTH octets
+     of the MAC are written.
+
+     This function also resets the context for processing new messages,
+     with the same key.
+
+6.4.2.5 HMAC-SHA512
+...................
+
+ -- Context struct: struct hmac_sha512_ctx
+
+ -- Function: void hmac_sha512_set_key (struct hmac_sha512_ctx *CTX,
+          unsigned KEY_LENGTH, const uint8_t *KEY)
+     Initializes the context with the key.
+
+ -- Function: void hmac_sha512_update (struct hmac_sha512_ctx *CTX,
+          unsigned LENGTH, const uint8_t *DATA)
+     Process some more data.
+
+ -- Function: void hmac_sha512_digest (struct hmac_sha512_ctx *CTX,
+          unsigned LENGTH, uint8_t *DIGEST)
+     Extracts the MAC, writing it to DIGEST. LENGTH may be smaller than
+     `SHA512_DIGEST_SIZE', in which case only the first LENGTH octets
+     of the MAC are written.
+
+     This function also resets the context for processing new messages,
+     with the same key.
+
+
+File: nettle.info,  Node: Public-key algorithms,  Next: Randomness,  Prev: Keyed hash functions,  Up: Reference
+
+6.5 Public-key algorithms
+=========================
+
+Nettle uses GMP, the GNU bignum library, for all calculations with
+large numbers. In order to use the public-key features of Nettle, you
+must install GMP, at least version 3.0, before compiling Nettle, and
+you need to link your programs with `-lhogweed -lnettle -lgmp'.
+
+   The concept of "Public-key" encryption and digital signatures was
+discovered by Whitfield Diffie and Martin E. Hellman and described in a
+paper 1976. In traditional, "symmetric", cryptography, sender and
+receiver share the same keys, and these keys must be distributed in a
+secure way. And if there are many users or entities that need to
+communicate, each _pair_ needs a shared secret key known by nobody else.
+
+   Public-key cryptography uses trapdoor one-way functions. A "one-way
+function" is a function `F' such that it is easy to compute the value
+`F(x)' for any `x', but given a value `y', it is hard to compute a
+corresponding `x' such that `y = F(x)'. Two examples are cryptographic
+hash functions, and exponentiation in certain groups.
+
+   A "trapdoor one-way function" is a function `F' that is one-way,
+unless one knows some secret information about `F'. If one knows the
+secret, it is easy to compute both `F' and it's inverse.  If this
+sounds strange, look at the RSA example below.
+
+   Two important uses for one-way functions with trapdoors are
+public-key encryption, and digital signatures. The public-key
+encryption functions in Nettle are not yet documented; the rest of this
+chapter is about digital signatures.
+
+   To use a digital signature algorithm, one must first create a
+"key-pair": A public key and a corresponding private key. The private
+key is used to sign messages, while the public key is used for verifying
+that that signatures and messages match. Some care must be taken when
+distributing the public key; it need not be kept secret, but if a bad
+guy is able to replace it (in transit, or in some user's list of known
+public keys), bad things may happen.
+
+   There are two operations one can do with the keys. The signature
+operation takes a message and a private key, and creates a signature for
+the message. A signature is some string of bits, usually at most a few
+thousand bits or a few hundred octets. Unlike paper-and-ink signatures,
+the digital signature depends on the message, so one can't cut it out of
+context and glue it to a different message.
+
+   The verification operation takes a public key, a message, and a
+string that is claimed to be a signature on the message, and returns
+true or false. If it returns true, that means that the three input
+values matched, and the verifier can be sure that someone went through
+with the signature operation on that very message, and that the
+"someone" also knows the private key corresponding to the public key.
+
+   The desired properties of a digital signature algorithm are as
+follows: Given the public key and pairs of messages and valid
+signatures on them, it should be hard to compute the private key, and
+it should also be hard to create a new message and signature that is
+accepted by the verification operation.
+
+   Besides signing meaningful messages, digital signatures can be used
+for authorization. A server can be configured with a public key, such
+that any client that connects to the service is given a random nonce
+message.  If the server gets a reply with a correct signature matching
+the nonce message and the configured public key, the client is granted
+access. So the configuration of the server can be understood as "grant
+access to whoever knows the private key corresponding to this
+particular public key, and to no others".
+
+* Menu:
+
+* RSA::                         The RSA public key algorithm.
+* DSA::                         The DSA digital signature algorithm.
+
+
+File: nettle.info,  Node: RSA,  Next: DSA,  Prev: Public-key algorithms,  Up: Public-key algorithms
+
+6.5.1 RSA
+---------
+
+The RSA algorithm was the first practical digital signature algorithm
+that was constructed. It was described 1978 in a paper by Ronald
+Rivest, Adi Shamir and L.M. Adleman, and the technique was also
+patented in the USA in 1983. The patent expired on September 20, 2000,
+and since that day, RSA can be used freely, even in the USA.
+
+   It's remarkably simple to describe the trapdoor function behind RSA.
+The "one-way"-function used is
+
+     F(x) = x^e mod n
+
+   I.e. raise x to the `e':th power, while discarding all multiples of
+`n'. The pair of numbers `n' and `e' is the public key.  `e' can be
+quite small, even `e = 3' has been used, although slightly larger
+numbers are recommended. `n' should be about 1000 bits or larger.
+
+   If `n' is large enough, and properly chosen, the inverse of F, the
+computation of `e':th roots modulo `n', is very difficult.  But,
+where's the trapdoor?
+
+   Let's first look at how RSA key-pairs are generated. First `n' is
+chosen as the product of two large prime numbers `p' and `q' of roughly
+the same size (so if `n' is 1000 bits, `p' and `q' are about 500 bits
+each). One also computes the number `phi = (p-1)(q-1)', in mathematical
+speak, `phi' is the order of the multiplicative group of integers
+modulo n.
+
+   Next, `e' is chosen. It must have no factors in common with `phi' (in
+particular, it must be odd), but can otherwise be chosen more or less
+randomly. `e = 65537' is a popular choice, because it makes raising to
+the `e''th power particularly efficient, and being prime, it usually
+has no factors common with `phi'.
+
+   Finally, a number `d', `d < n' is computed such that `e d mod phi =
+1'. It can be shown that such a number exists (this is why `e' and
+`phi' must have no common factors), and that for all x,
+
+     (x^e)^d mod n = x^(ed) mod n = (x^d)^e mod n = x
+
+   Using Euclid's algorithm, `d' can be computed quite easily from
+`phi' and `e'. But it is still hard to get `d' without knowing `phi',
+which depends on the factorization of `n'.
+
+   So `d' is the trapdoor, if we know `d' and `y = F(x)', we can
+recover x as `y^d mod n'. `d' is also the private half of the RSA
+key-pair.
+
+   The most common signature operation for RSA is defined in `PKCS#1',
+a specification by RSA Laboratories. The message to be signed is first
+hashed using a cryptographic hash function, e.g.  MD5 or SHA1. Next,
+some padding, the ASN.1 "Algorithm Identifier" for the hash function,
+and the message digest itself, are concatenated and converted to a
+number `x'. The signature is computed from `x' and the private key as
+`s = x^d mod n'(1) (*note RSA-Footnote-1::). The signature, `s' is a
+number of about the same size of `n', and it usually encoded as a
+sequence of octets, most significant octet first.
+
+   The verification operation is straight-forward, `x' is computed from
+the message in the same way as above. Then `s^e mod n' is computed, the
+operation returns true if and only if the result equals `x'.
+
+6.5.2 Nettle's RSA support
+--------------------------
+
+Nettle represents RSA keys using two structures that contain large
+numbers (of type `mpz_t').
+
+ -- Context struct: rsa_public_key size n e
+     `size' is the size, in octets, of the modulo, and is used
+     internally.  `n' and `e' is the public key.
+
+ -- Context struct: rsa_private_key size d p q a b c
+     `size' is the size, in octets, of the modulo, and is used
+     internally.  `d' is the secret exponent, but it is not actually
+     used when signing. Instead, the factors `p' and `q', and the
+     parameters `a', `b' and `c' are used. They are computed from `p',
+     `q' and `e' such that `a e mod (p - 1) = 1, b e mod (q - 1) = 1, c
+     q mod p = 1'.
+
+   Before use, these structs must be initialized by calling one of
+
+ -- Function: void rsa_public_key_init (struct rsa_public_key *PUB)
+ -- Function: void rsa_private_key_init (struct rsa_private_key *KEY)
+     Calls `mpz_init' on all numbers in the key struct.
+
+   and when finished with them, the space for the numbers must be
+deallocated by calling one of
+
+ -- Function: void rsa_public_key_clear (struct rsa_public_key *PUB)
+ -- Function: void rsa_private_key_clear (struct rsa_private_key *KEY)
+     Calls `mpz_clear' on all numbers in the key struct.
+
+   In general, Nettle's RSA functions deviates from Nettle's "no memory
+allocation"-policy. Space for all the numbers, both in the key structs
+above, and temporaries, are allocated dynamically. For information on
+how to customize allocation, see *Note GMP Allocation: (gmp)Custom
+Allocation.
+
+   When you have assigned values to the attributes of a key, you must
+call
+
+ -- Function: int rsa_public_key_prepare (struct rsa_public_key *PUB)
+ -- Function: int rsa_private_key_prepare (struct rsa_private_key *KEY)
+     Computes the octet size of the key (stored in the `size' attribute,
+     and may also do other basic sanity checks. Returns one if
+     successful, or zero if the key can't be used, for instance if the
+     modulo is smaller than the minimum size needed for RSA operations
+     specified by PKCS#1.
+
+   Before signing or verifying a message, you first hash it with the
+appropriate hash function. You pass the hash function's context struct
+to the RSA signature function, and it will extract the message digest
+and do the rest of the work. There are also alternative functions that
+take the hash digest as argument.
+
+   There is currently no support for using SHA224 or SHA384 with RSA
+signatures, since there's no gain in either computation time nor
+message size compared to using SHA256 and SHA512, respectively.
+
+   Creation and verification of signatures is done with the following
+functions:
+
+ -- Function: int rsa_md5_sign (const struct rsa_private_key *KEY,
+          struct md5_ctx *HASH, mpz_t SIGNATURE)
+ -- Function: int rsa_sha1_sign (const struct rsa_private_key *KEY,
+          struct sha1_ctx *HASH, mpz_t SIGNATURE)
+ -- Function: int rsa_sha256_sign (const struct rsa_private_key *KEY,
+          struct sha256_ctx *HASH, mpz_t SIGNATURE)
+ -- Function: int rsa_sha512_sign (const struct rsa_private_key *KEY,
+          struct sha512_ctx *HASH, mpz_t SIGNATURE)
+     The signature is stored in SIGNATURE (which must have been
+     `mpz_init''ed earlier). The hash context is reset so that it can be
+     used for new messages. Returns one on success, or zero on failure.
+     Signing fails if the key is too small for the given hash size,
+     e.g., it's not possible to create a signature using SHA512 and a
+     512-bit RSA key.
+
+ -- Function: int rsa_md5_sign_digest (const struct rsa_private_key
+          *KEY, const uint8_t *DIGEST, mpz_t SIGNATURE)
+ -- Function: int rsa_sha1_sign_digest (const struct rsa_private_key
+          *KEY, const uint8_t *DIGEST, mpz_t SIGNATURE);
+ -- Function: int rsa_sha256_sign_digest (const struct rsa_private_key
+          *KEY, const uint8_t *DIGEST, mpz_t SIGNATURE);
+ -- Function: int rsa_sha512_sign_digest (const struct rsa_private_key
+          *KEY, const uint8_t *DIGEST, mpz_t SIGNATURE);
+     Creates a signature from the given hash digest. DIGEST should
+     point to a digest of size `MD5_DIGEST_SIZE', `SHA1_DIGEST_SIZE',
+     or `SHA256_DIGEST_SIZE', respectively. The signature is stored in
+     SIGNATURE (which must have been `mpz_init':ed earlier). Returns
+     one on success, or zero on failure.
+
+ -- Function: int rsa_md5_verify (const struct rsa_public_key *KEY,
+          struct md5_ctx *HASH, const mpz_t SIGNATURE)
+ -- Function: int rsa_sha1_verify (const struct rsa_public_key *KEY,
+          struct sha1_ctx *HASH, const mpz_t SIGNATURE)
+ -- Function: int rsa_sha256_verify (const struct rsa_public_key *KEY,
+          struct sha256_ctx *HASH, const mpz_t SIGNATURE)
+ -- Function: int rsa_sha512_verify (const struct rsa_public_key *KEY,
+          struct sha512_ctx *HASH, const mpz_t SIGNATURE)
+     Returns 1 if the signature is valid, or 0 if it isn't. In either
+     case, the hash context is reset so that it can be used for new
+     messages.
+
+ -- Function: int rsa_md5_verify_digest (const struct rsa_public_key
+          *KEY, const uint8_t *DIGEST, const mpz_t SIGNATURE)
+ -- Function: int rsa_sha1_verify_digest (const struct rsa_public_key
+          *KEY, const uint8_t *DIGEST, const mpz_t SIGNATURE)
+ -- Function: int rsa_sha256_verify_digest (const struct rsa_public_key
+          *KEY, const uint8_t *DIGEST, const mpz_t SIGNATURE)
+ -- Function: int rsa_sha512_verify_digest (const struct rsa_public_key
+          *KEY, const uint8_t *DIGEST, const mpz_t SIGNATURE)
+     Returns 1 if the signature is valid, or 0 if it isn't. DIGEST
+     should point to a digest of size `MD5_DIGEST_SIZE',
+     `SHA1_DIGEST_SIZE', or `SHA256_DIGEST_SIZE', respectively.
+
+   If you need to use the RSA trapdoor, the private key, in a way that
+isn't supported by the above functions Nettle also includes a function
+that computes `x^d mod n' and nothing more, using the CRT optimization.
+
+ -- Function: void rsa_compute_root (struct rsa_private_key *KEY, mpz_t
+          X, const mpz_t M)
+     Computes `x = m^d', efficiently.
+
+   At last, how do you create new keys?
+
+ -- Function: int rsa_generate_keypair (struct rsa_public_key *PUB,
+          struct rsa_private_key *KEY, void *RANDOM_CTX,
+          nettle_random_func RANDOM, void *PROGRESS_CTX,
+          nettle_progress_func PROGRESS, unsigned N_SIZE, unsigned
+          E_SIZE);
+     There are lots of parameters. PUB and KEY is where the resulting
+     key pair is stored. The structs should be initialized, but you
+     don't need to call `rsa_public_key_prepare' or
+     `rsa_private_key_prepare' after key generation.
+
+     RANDOM_CTX and RANDOM is a randomness generator.
+     `random(random_ctx, length, dst)' should generate `length' random
+     octets and store them at `dst'. For advice, see *Note Randomness::.
+
+     PROGRESS and PROGRESS_CTX can be used to get callbacks during the
+     key generation process, in order to uphold an illusion of
+     progress. PROGRESS can be NULL, in that case there are no
+     callbacks.
+
+     SIZE_N is the desired size of the modulo, in bits. If SIZE_E is
+     non-zero, it is the desired size of the public exponent and a
+     random exponent of that size is selected. But if E_SIZE is zero,
+     it is assumed that the caller has already chosen a value for `e',
+     and stored it in PUB.  Returns one on success, and zero on
+     failure. The function can fail for example if if N_SIZE is too
+     small, or if E_SIZE is zero and `pub->e' is an even number.
+
+
+File: nettle.info,  Node: RSA-Footnotes,  Up: RSA
+
+   (1) Actually, the computation is not done like this, it is done more
+efficiently using `p', `q' and the Chinese remainder theorem (CRT). But
+the result is the same.
+
+
+File: nettle.info,  Node: DSA,  Prev: RSA,  Up: Public-key algorithms
+
+6.5.3 Nettle's DSA support
+--------------------------
+
+The DSA digital signature algorithm is more complex than RSA. It was
+specified during the early 1990s, and in 1994 NIST published FIPS 186
+which is the authoritative specification.  Sometimes DSA is referred to
+using the acronym DSS, for Digital Signature Standard. The most recent
+revision of the specification, FIPS186-3, was issueed in 2009, and it
+adds support for larger hash functions than sha1.
+
+   For DSA, the underlying mathematical problem is the computation of
+discreet logarithms. The public key consists of a large prime `p', a
+small prime `q' which is a factor of `p-1', a number `g' which
+generates a subgroup of order `q' modulo `p', and an element `y' in
+that subgroup.
+
+   In the original DSA, the size of `q' is fixed to 160 bits, to match
+with the SHA1 hash algorithm. The size of `p' is in principle
+unlimited, but the standard specifies only nine specific sizes: `512 +
+l*64', where `l' is between 0 and 8. Thus, the maximum size of `p' is
+1024 bits, and sizes less than 1024 bits are considered obsolete and not
+secure.
+
+   The subgroup requirement means that if you compute
+
+     g^t mod p
+
+   for all possible integers `t', you will get precisely `q' distinct
+values.
+
+   The private key is a secret exponent `x', such that
+
+     g^x = y mod p
+
+   In mathematical speak, `x' is the "discrete logarithm" of `y' mod
+`p', with respect to the generator `g'. The size of `x' will also be
+about the same size as `q'. The security of the DSA algorithm relies on
+the difficulty of the discrete logarithm problem. Current algorithms to
+compute discrete logarithms in this setting, and hence crack DSA, are
+of two types. The first type works directly in the (multiplicative)
+group of integers mod `p'. The best known algorithm of this type is the
+Number Field Sieve, and it's complexity is similar to the complexity of
+factoring numbers of the same size as `p'. The other type works in the
+smaller `q'-sized subgroup generated by `g', which has a more difficult
+group structure. One good algorithm is Pollard-rho, which has
+complexity `sqrt(q)'.
+
+   The important point is that security depends on the size of _both_
+`p' and `q', and they should be choosen so that the difficulty of both
+discrete logarithm methods are comparable. Today, the security margin
+of the original DSA may be uncomfortably small. Using a `p' of 1024
+bits implies that cracking using the number field sieve is expected to
+take about the same time as factoring a 1024-bit RSA modulo, and using
+a `q' of size 160 bits implies that cracking using Pollard-rho will
+take roughly `2^80' group operations. With the size of `q' fixed, tied
+to the SHA1 digest size, it may be tempting to increase the size of `p'
+to, say, 4096 bits. This will provide excellent resistance against
+attacks like the number field sieve which works in the large group. But
+it will do very little to defend against Pollard-rho attacking the small
+subgroup; the attacker is slowed down at most by a single factor of 10
+due to the more expensive group operation. And the attacker will surely
+choose the latter attack.
+
+   The signature generation algorithm is randomized; in order to create
+a DSA signature, you need a good source for random numbers (*note
+Randomness::). Let us describe the common case of a 160-bit `q'.
+
+   To create a signature, one starts with the hash digest of the
+message, `h', which is a 160 bit number, and a random number `k,
+0<k<q', also 160 bits. Next, one computes
+
+     r = (g^k mod p) mod q
+     s = k^-1 (h + x r) mod q
+
+   The signature is the pair `(r, s)', two 160 bit numbers. Note the
+two different mod operations when computing `r', and the use of the
+secret exponent `x'.
+
+   To verify a signature, one first checks that `0 < r,s < q', and then
+one computes backwards,
+
+     w = s^-1 mod q
+     v = (g^(w h) y^(w r) mod p) mod q
+
+   The signature is valid if `v = r'. This works out because `w = s^-1
+mod q = k (h + x r)^-1 mod q', so that
+
+     g^(w h) y^(w r) = g^(w h) (g^x)^(w r) = g^(w (h + x r)) = g^k
+
+   When reducing mod `q' this yields `r'. Note that when verifying a
+signature, we don't know either `k' or `x': those numbers are secret.
+
+   If you can choose between RSA and DSA, which one is best? Both are
+believed to be secure. DSA gained popularity in the late 1990s, as a
+patent free alternative to RSA. Now that the RSA patents have expired,
+there's no compelling reason to want to use DSA. Today, the original
+DSA key size does not provide a large security margin, and it should
+probably be phased out together with RSA keys of 1024 bits. Using the
+revised DSA algorithm with a larger hash function, in particular,
+SHA256, a 256-bit `q', and `p' of size 2048 bits or more, should
+provide for a more comfortable security margin, but these variants are
+not yet in wide use.
+
+   DSA signatures are smaller than RSA signatures, which is important
+for some specialized applications.
+
+   From a practical point of view, DSA's need for a good randomness
+source is a serious disadvantage. If you ever use the same `k' (and
+`r') for two different message, you leak your private key.
+
+6.5.4 Nettle's DSA support
+--------------------------
+
+Like for RSA, Nettle represents DSA keys using two structures,
+containing values of type `mpz_t'. For information on how to customize
+allocation, see *Note GMP Allocation: (gmp)Custom Allocation.
+
+   Most of the DSA functions are very similar to the corresponding RSA
+functions, but there are a few differences pointed out below. For a
+start, there are no functions corresponding to `rsa_public_key_prepare'
+and `rsa_private_key_prepare'.
+
+ -- Context struct: dsa_public_key p q g y
+     The public parameters described above.
+
+ -- Context struct: dsa_private_key x
+     The private key `x'.
+
+   Before use, these structs must be initialized by calling one of
+
+ -- Function: void dsa_public_key_init (struct dsa_public_key *PUB)
+ -- Function: void dsa_private_key_init (struct dsa_private_key *KEY)
+     Calls `mpz_init' on all numbers in the key struct.
+
+   When finished with them, the space for the numbers must be
+deallocated by calling one of
+
+ -- Function: void dsa_public_key_clear (struct dsa_public_key *PUB)
+ -- Function: void dsa_private_key_clear (struct dsa_private_key *KEY)
+     Calls `mpz_clear' on all numbers in the key struct.
+
+   Signatures are represented using the structure below, and need to be
+initialized and cleared in the same way as the key structs.
+
+ -- Context struct: dsa_signature r s
+
+ -- Function: void dsa_signature_init (struct dsa_signature *SIGNATURE)
+ -- Function: void dsa_signature_clear (struct dsa_signature *SIGNATURE)
+     You must call `dsa_signature_init' before creating or using a
+     signature, and call `dsa_signature_clear' when you are finished
+     with it.
+
+   For signing, you need to provide both the public and the private key
+(unlike RSA, where the private key struct includes all information
+needed for signing), and a source for random numbers.  Signatures can
+use the SHA1 or the SHA256 hash function, although the implementation
+of DSA with SHA256 should be considered somewhat experimental due to
+lack of official test vectors and interoperability testing.
+
+ -- Function: int dsa_sha1_sign (const struct dsa_public_key *PUB,
+          const struct dsa_private_key *KEY, void *RANDOM_CTX,
+          nettle_random_func RANDOM, struct sha1_ctx *HASH, struct
+          dsa_signature *SIGNATURE)
+ -- Function: int dsa_sha1_sign_digest (const struct dsa_public_key
+          *PUB, const struct dsa_private_key *KEY, void *RANDOM_CTX,
+          nettle_random_func RANDOM, const uint8_t *DIGEST, struct
+          dsa_signature *SIGNATURE)
+ -- Function: int dsa_sha256_sign (const struct dsa_public_key *PUB,
+          const struct dsa_private_key *KEY, void *RANDOM_CTX,
+          nettle_random_func RANDOM, struct sha256_ctx *HASH, struct
+          dsa_signature *SIGNATURE)
+ -- Function: int dsa_sha256_sign_digest (const struct dsa_public_key
+          *PUB, const struct dsa_private_key *KEY, void *RANDOM_CTX,
+          nettle_random_func RANDOM, const uint8_t *DIGEST, struct
+          dsa_signature *SIGNATURE)
+     Creates a signature from the given hash context or digest.
+     RANDOM_CTX and RANDOM is a randomness generator.
+     `random(random_ctx, length, dst)' should generate `length' random
+     octets and store them at `dst'. For advice, see *Note
+     Randomness::. Returns one on success, or zero on failure.  Signing
+     fails if the key size and the hash size don't match.
+
+   Verifying signatures is a little easier, since no randomness
+generator is needed. The functions are
+
+ -- Function: int dsa_sha1_verify (const struct dsa_public_key *KEY,
+          struct sha1_ctx *HASH, const struct dsa_signature *SIGNATURE)
+ -- Function: int dsa_sha1_verify_digest (const struct dsa_public_key
+          *KEY, const uint8_t *DIGEST, const struct dsa_signature
+          *SIGNATURE)
+ -- Function: int dsa_sha256_verify (const struct dsa_public_key *KEY,
+          struct sha256_ctx *HASH, const struct dsa_signature
+          *SIGNATURE)
+ -- Function: int dsa_sha256_verify_digest (const struct dsa_public_key
+          *KEY, const uint8_t *DIGEST, const struct dsa_signature
+          *SIGNATURE)
+     Verifies a signature. Returns 1 if the signature is valid,
+     otherwise 0.
+
+   Key generation uses mostly the same parameters as the corresponding
+RSA function.
+
+ -- Function: int dsa_generate_keypair (struct dsa_public_key *PUB,
+          struct dsa_private_key *KEY, void *RANDOM_CTX,
+          nettle_random_func RANDOM, void *PROGRESS_CTX,
+          nettle_progress_func PROGRESS, unsigned P_BITS, unsigned
+          Q_BITS)
+     PUB and KEY is where the resulting key pair is stored. The structs
+     should be initialized before you call this function.
+
+     RANDOM_CTX and RANDOM is a randomness generator.
+     `random(random_ctx, length, dst)' should generate `length' random
+     octets and store them at `dst'. For advice, see *Note Randomness::.
+
+     PROGRESS and PROGRESS_CTX can be used to get callbacks during the
+     key generation process, in order to uphold an illusion of
+     progress. PROGRESS can be NULL, in that case there are no
+     callbacks.
+
+     P_BITS and Q_BITS are the desired sizes of `p' and `q'. To
+     generate keys that conform to the original DSA standard, you must
+     use `q_bits = 160' and select P_BITS of the form `p_bits = 512 +
+     l*64', for `0 <= l <= 8', where the smaller sizes are no longer
+     recommended, so you should most likely stick to `p_bits = 1024'.
+     Non-standard sizes are possible, in particular `p_bits' larger
+     than 1024, although DSA implementations can not in general be
+     expected to support such keys. Also note that using very large
+     P_BITS, with Q_BITS fixed at 160, doesn't make much sense, because
+     the security is also limited by the size of the smaller prime.
+     Using a larger `q_bits' requires switchign to a larger hash
+     function. To generate DSA keys for use with SHA256, use `q_bits =
+     256' and, e.g., `p_bits = 2048'.
+
+     Returns one on success, and zero on failure. The function will
+     fail if Q_BITS is neither 160 nor 256, or if P_BITS is unreasonably
+     small.
+
+
+File: nettle.info,  Node: Randomness,  Next: Ascii encoding,  Prev: Public-key algorithms,  Up: Reference
+
+6.6 Randomness
+==============
+
+A crucial ingredient in many cryptographic contexts is randomness: Let
+`p' be a random prime, choose a random initialization vector `iv', a
+random key `k' and a random exponent `e', etc. In the theories, it is
+assumed that you have plenty of randomness around.  If this assumption
+is not true in practice, systems that are otherwise perfectly secure,
+can be broken. Randomness has often turned out to be the weakest link
+in the chain.
+
+   In non-cryptographic applications, such as games as well as
+scientific simulation, a good randomness generator usually means a
+generator that has good statistical properties, and is seeded by some
+simple function of things like the current time, process id, and host
+name.
+
+   However, such a generator is inadequate for cryptography, for at
+least two reasons:
+
+   * It's too easy for an attacker to guess the initial seed. Even if
+     it will take some 2^32 tries before he guesses right, that's far
+     too easy. For example, if the process id is 16 bits, the
+     resolution of "current time" is one second, and the attacker knows
+     what day the generator was seeded, there are only about 2^32
+     possibilities to try if all possible values for the process id and
+     time-of-day are tried.
+
+   * The generator output reveals too much. By observing only a small
+     segment of the generator's output, its internal state can be
+     recovered, and from there, all previous output and all future
+     output can be computed by the attacker.
+
+   A randomness generator that is used for cryptographic purposes must
+have better properties. Let's first look at the seeding, as the issues
+here are mostly independent of the rest of the generator. The initial
+state of the generator (its seed) must be unguessable by the attacker.
+So what's unguessable? It depends on what the attacker already knows.
+The concept used in information theory to reason about such things is
+called "entropy", or "conditional entropy" (not to be confused with the
+thermodynamic concept with the same name). A reasonable requirement is
+that the seed contains a conditional entropy of at least some 80-100
+bits. This property can be explained as follows: Allow the attacker to
+ask `n' yes-no-questions, of his own choice, about the seed. If the
+attacker, using this question-and-answer session, as well as any other
+information he knows about the seeding process, still can't guess the
+seed correctly, then the conditional entropy is more than `n' bits.
+
+   Let's look at an example. Say information about timing of received
+network packets is used in the seeding process. If there is some random
+network traffic going on, this will contribute some bits of entropy or
+"unguessability" to the seed. However, if the attacker can listen in to
+the local network, or if all but a small number of the packets were
+transmitted by machines that the attacker can monitor, this additional
+information makes the seed easier for the attacker to figure out. Even
+if the information is exactly the same, the conditional entropy, or
+unguessability, is smaller for an attacker that knows some of it already
+before the hypothetical question-and-answer session.
+
+   Seeding of good generators is usually based on several sources. The
+key point here is that the amount of unguessability that each source
+contributes, depends on who the attacker is. Some sources that have been
+used are:
+
+High resolution timing of i/o activities
+     Such as completed blocks from spinning hard disks, network
+     packets, etc.  Getting access to such information is quite system
+     dependent, and not all systems include suitable hardware. If
+     available, it's one of the better randomness source one can find
+     in a digital, mostly predictable, computer.
+
+User activity
+     Timing and contents of user interaction events is another popular
+     source that is available for interactive programs (even if I
+     suspect that it is sometimes used in order to make the user feel
+     good, not because the quality of the input is needed or used
+     properly). Obviously, not available when a machine is unattended.
+     Also beware of networks: User interaction that happens across a
+     long serial cable, TELNET session, or even SSH session may be
+     visible to an attacker, in full or partially.
+
+Audio input
+     Any room, or even a microphone input that's left unconnected, is a
+     source of some random background noise, which can be fed into the
+     seeding process.
+
+Specialized hardware
+     Hardware devices with the sole purpose of generating random data
+     have been designed. They range from radioactive samples with an
+     attached Geiger counter, to amplification of the inherent noise in
+     electronic components such as diodes and resistors, to
+     low-frequency sampling of chaotic systems. Hashing successive
+     images of a Lava lamp is a spectacular example of the latter type.
+
+Secret information
+     Secret information, such as user passwords or keys, or private
+     files stored on disk, can provide some unguessability. A problem
+     is that if the information is revealed at a later time, the
+     unguessability vanishes. Another problem is that this kind of
+     information tends to be fairly constant, so if you rely on it and
+     seed your generator regularly, you risk constructing almost
+     similar seeds or even constructing the same seed more than once.
+
+   For all practical sources, it's difficult but important to provide a
+reliable lower bound on the amount of unguessability that it provides.
+Two important points are to make sure that the attacker can't observe
+your sources (so if you like the Lava lamp idea, remember that you have
+to get your own lamp, and not put it by a window or anywhere else where
+strangers can see it), and that hardware failures are detected. What if
+the bulb in the Lava lamp, which you keep locked into a cupboard
+following the above advice, breaks after a few months?
+
+   So let's assume that we have been able to find an unguessable seed,
+which contains at least 80 bits of conditional entropy, relative to all
+attackers that we care about (typically, we must at the very least
+assume that no attacker has root privileges on our machine).
+
+   How do we generate output from this seed, and how much can we get?
+Some generators (notably the Linux `/dev/random' generator) tries to
+estimate available entropy and restrict the amount of output. The goal
+is that if you read 128 bits from `/dev/random', you should get 128
+"truly random" bits. This is a property that is useful in some
+specialized circumstances, for instance when generating key material for
+a one time pad, or when working with unconditional blinding, but in most
+cases, it doesn't matter much. For most application, there's no limit on
+the amount of useful "random" data that we can generate from a small
+seed; what matters is that the seed is unguessable and that the
+generator has good cryptographic properties.
+
+   At the heart of all generators lies its internal state. Future output
+is determined by the internal state alone. Let's call it the generator's
+key. The key is initialized from the unguessable seed. Important
+properties of a generator are:
+
+"Key-hiding"
+     An attacker observing the output should not be able to recover the
+     generator's key.
+
+"Independence of outputs"
+     Observing some of the output should not help the attacker to guess
+     previous or future output.
+
+"Forward secrecy"
+     Even if an attacker compromises the generator's key, he should not
+     be able to guess the generator output _before_ the key compromise.
+
+"Recovery from key compromise"
+     If an attacker compromises the generator's key, he can compute
+     _all_ future output. This is inevitable if the generator is seeded
+     only once, at startup. However, the generator can provide a
+     reseeding mechanism, to achieve recovery from key compromise. More
+     precisely: If the attacker compromises the key at a particular
+     time `t_1', there is another later time `t_2', such that if the
+     attacker observes all output generated between `t_1' and `t_2', he
+     still can't guess what output is generated after `t_2'.
+
+
+   Nettle includes one randomness generator that is believed to have all
+the above properties, and two simpler ones.
+
+   ARCFOUR, like any stream cipher, can be used as a randomness
+generator. Its output should be of reasonable quality, if the seed is
+hashed properly before it is used with `arcfour_set_key'. There's no
+single natural way to reseed it, but if you need reseeding, you should
+be using Yarrow instead.
+
+   The "lagged Fibonacci" generator in `<nettle/knuth-lfib.h>' is a
+fast generator with good statistical properties, but is *not* for
+cryptographic use, and therefore not documented here. It is included
+mostly because the Nettle test suite needs to generate some test data
+from a small seed.
+
+   The recommended generator to use is Yarrow, described below.
+
+6.6.1 Yarrow
+------------
+
+Yarrow is a family of pseudo-randomness generators, designed for
+cryptographic use, by John Kelsey, Bruce Schneier and Niels Ferguson.
+Yarrow-160 is described in a paper at
+`http://www.counterpane.com/yarrow.html', and it uses SHA1 and
+triple-DES, and has a 160-bit internal state. Nettle implements
+Yarrow-256, which is similar, but uses SHA256 and AES to get an
+internal state of 256 bits.
+
+   Yarrow was an almost finished project, the paper mentioned above is
+the closest thing to a specification for it, but some smaller details
+are left out. There is no official reference implementation or test
+cases.  This section includes an overview of Yarrow, but for the
+details of Yarrow-256, as implemented by Nettle, you have to consult
+the source code. Maybe a complete specification can be written later.
+
+   Yarrow can use many sources (at least two are needed for proper
+reseeding), and two randomness "pools", referred to as the "slow pool"
+and the "fast pool". Input from the sources is fed alternatingly into
+the two pools. When one of the sources has contributed 100 bits of
+entropy to the fast pool, a "fast reseed" happens and the fast pool is
+mixed into the internal state. When at least two of the sources have
+contributed at least 160 bits each to the slow pool, a "slow reseed"
+takes place. The contents of both pools are mixed into the internal
+state. These procedures should ensure that the generator will eventually
+recover after a key compromise.
+
+   The output is generated by using AES to encrypt a counter, using the
+generator's current key. After each request for output, another 256
+bits are generated which replace the key. This ensures forward secrecy.
+
+   Yarrow can also use a "seed file" to save state across restarts.
+Yarrow is seeded by either feeding it the contents of the previous seed
+file, or feeding it input from its sources until a slow reseed happens.
+
+   Nettle defines Yarrow-256 in `<nettle/yarrow.h>'.
+
+ -- Context struct: struct yarrow256_ctx
+
+ -- Context struct: struct yarrow_source
+     Information about a single source.
+
+ -- Constant: YARROW256_SEED_FILE_SIZE
+     Recommanded size of the Yarrow-256 seed file.
+
+ -- Function: void yarrow256_init (struct yarrow256_ctx *CTX, unsigned
+          NSOURCES, struct yarrow_source *SOURCES)
+     Initializes the yarrow context, and its NSOURCES sources. It's
+     possible to call it with NSOURCES=0 and SOURCES=NULL, if you don't
+     need the update features.
+
+ -- Function: void yarrow256_seed (struct yarrow256_ctx *CTX, unsigned
+          LENGTH, uint8_t *SEED_FILE)
+     Seeds Yarrow-256 from a previous seed file. LENGTH should be at
+     least `YARROW256_SEED_FILE_SIZE', but it can be larger.
+
+     The generator will trust you that the SEED_FILE data really is
+     unguessable. After calling this function, you _must_ overwrite the
+     old seed file with newly generated data from `yarrow256_random'.
+     If it's possible for several processes to read the seed file at
+     about the same time, access must be coordinated using some locking
+     mechanism.
+
+ -- Function: int yarrow256_update (struct yarrow256_ctx *CTX, unsigned
+          SOURCE, unsigned ENTROPY, unsigned LENGTH, const uint8_t
+          *DATA)
+     Updates the generator with data from source SOURCE (an index that
+     must be smaller than the number of sources). ENTROPY is your
+     estimated lower bound for the entropy in the data, measured in
+     bits.  Calling update with zero ENTROPY is always safe, no matter
+     if the data is random or not.
+
+     Returns 1 if a reseed happened, in which case an application using
+     a seed file may want to generate new seed data with
+     `yarrow256_random' and overwrite the seed file. Otherwise, the
+     function returns 0.
+
+ -- Function: void yarrow256_random (struct yarrow256_ctx *CTX,
+          unsigned LENGTH, uint8_t *DST)
+     Generates LENGTH octets of output. The generator must be seeded
+     before you call this function.
+
+     If you don't need forward secrecy, e.g. if you need non-secret
+     randomness for initialization vectors or padding, you can gain some
+     efficiency by buffering, calling this function for reasonably large
+     blocks of data, say 100-1000 octets at a time.
+
+ -- Function: int yarrow256_is_seeded (struct yarrow256_ctx *CTX)
+     Returns 1 if the generator is seeded and ready to generate output,
+     otherwise 0.
+
+ -- Function: unsigned yarrow256_needed_sources (struct yarrow256_ctx
+          *CTX)
+     Returns the number of sources that must reach the threshold before
+     a slow reseed will happen. Useful primarily when the generator is
+     unseeded.
+
+ -- Function: void yarrow256_fast_reseed (struct yarrow256_ctx *CTX)
+ -- Function: void yarrow256_slow_reseed (struct yarrow256_ctx *CTX)
+     Causes a fast or slow reseed to take place immediately, regardless
+     of the current entropy estimates of the two pools. Use with care.
+
+   Nettle includes an entropy estimator for one kind of input source:
+User keyboard input.
+
+ -- Context struct: struct yarrow_key_event_ctx
+     Information about recent key events.
+
+ -- Function: void yarrow_key_event_init (struct yarrow_key_event_ctx
+          *CTX)
+     Initializes the context.
+
+ -- Function: unsigned yarrow_key_event_estimate (struct
+          yarrow_key_event_ctx *CTX, unsigned KEY, unsigned TIME)
+     KEY is the id of the key (ASCII value, hardware key code, X
+     keysym, ..., it doesn't matter), and TIME is the timestamp of 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
+     precision, TIME should be provided in units of microseconds. But
+     if you use `gettimeofday' on a typical Unix system where the clock
+     ticks 10 or so microseconds at a time, TIME should be given in
+     units of 10 microseconds.
+
+     Returns an entropy estimate, in bits, suitable for calling
+     `yarrow256_update'. Usually, 0, 1 or 2 bits.
+
+
+File: nettle.info,  Node: Ascii encoding,  Next: Miscellaneous functions,  Prev: Randomness,  Up: Reference
+
+6.7 Ascii encoding
+==================
+
+Encryption will transform your data from text into binary format, and
+that may be a problem if you want, for example, to send the data as if
+it was plain text in an email (or store it along with descriptive text
+in a file). You may then use an encoding from binary to text: each
+binary byte is translated into a number of bytes of plain text.
+
+   A base-N encoding of data is one representation of data that only
+uses N different symbols (instead of the 256 possible values of a byte).
+
+   The base64 encoding will always use alphanumeric (upper and lower
+case) characters and the '+', '/' and '=' symbols to represent the
+data. Four output characters are generated for each three bytes of
+input. In case the length of the input is not a multiple of three,
+padding characters are added at the end.
+
+   The base16 encoding, also known as "hexadecimal", uses the decimal
+digits and the letters from A to F. Two hexadecimal digits are generated
+for each input byte. Base16 may be useful if you want to use the data
+for filenames or URLs, for example.
+
+   Nettle supports both base64 and base16 encoding and decoding.
+
+   Encoding and decoding uses a context struct to maintain its state
+(with the exception of base16 encoding, which doesn't need any). To
+encode or decode the your data, first initialize the context, then call
+the update function as many times as necessary, and complete the
+operation by calling the final function.
+
+   The following functions can be used to perform base64 encoding and
+decoding.  They are defined in `<nettle/base64.h>'.
+
+ -- Context struct: struct base64_encode_ctx
+
+ -- Function: void base64_encode_init (struct base64_encode_ctx *CTX)
+     Initializes a base64 context. This is necessary before starting an
+     encoding session.
+
+ -- Function: unsigned base64_encode_single (struct base64_encode_ctx
+          *CTX, uint8_t *DST, uint8_t SRC)
+     Encodes a single byte. Returns amount of output (always 1 or 2).
+
+ -- Macro: BASE64_ENCODE_LENGTH (LENGTH)
+     The maximum number of output bytes when passing LENGTH input bytes
+     to `base64_encode_update'.
+
+ -- Function: unsigned base64_encode_update (struct base64_encode_ctx
+          *CTX, uint8_t *DST, unsigned LENGTH, const uint8_t *SRC)
+     After CTX is initialized, this function may be called to encode
+     LENGTH bytes from SRC. The result will be placed in DST, and the
+     return value will be the number of bytes generated. Note that DST
+     must be at least of size BASE64_ENCODE_LENGTH(LENGTH).
+
+ -- Constant: BASE64_ENCODE_FINAL_LENGTH
+     The maximum amount of output from `base64_encode_final'.
+
+ -- Function: unsigned base64_encode_final (struct base64_encode_ctx
+          *CTX, uint8_t *DST)
+     After calling base64_encode_update one or more times, this function
+     should be called to generate the final output bytes, including any
+     needed paddding. The return value is the number of output bytes
+     generated.
+
+ -- Context struct: struct base64_decode_ctx
+
+ -- Function: void base64_decode_init (struct base64_decode_ctx *CTX)
+     Initializes a base64 decoding context. This is necessary before
+     starting a decoding session.
+
+ -- Function: int base64_decode_single (struct base64_decode_ctx *CTX,
+          uint8_t *DST, uint8_t SRC)
+     Decodes a single byte (SRC) and stores the result in DST.  Returns
+     amount of output (0 or 1), or -1 on errors.
+
+ -- Macro: BASE64_DECODE_LENGTH (LENGTH)
+     The maximum number of output bytes when passing LENGTH input bytes
+     to `base64_decode_update'.
+
+ -- Function: void base64_decode_update (struct base64_decode_ctx *CTX,
+          unsigned *DST_LENGTH, uint8_t *DST, unsigned SRC_LENGTH,
+          const uint8_t *SRC)
+     After CTX is initialized, this function may be called to decode
+     SRC_LENGTH bytes from SRC. DST should point to an area of size at
+     least BASE64_DECODE_LENGTH(LENGTH), and for sanity checking,
+     DST_LENGTH should be initialized to the size of that area before
+     the call.  DST_LENGTH is updated to the amount of decoded output.
+     The function will return 1 on success and 0 on error.
+
+ -- Function: int base64_decode_final (struct base64_decode_ctx *CTX)
+     Check that final padding is correct. Returns 1 on success, and 0 on
+     error.
+
+   Similarly to the base64 functions, the following functions perform
+base16 encoding, and are defined in `<nettle/base16.h>'. Note that
+there is no encoding context necessary for doing base16 encoding.
+
+ -- Function: void base16_encode_single (uint8_t *DST, uint8_t SRC)
+     Encodes a single byte. Always stores two digits in DST[0] and
+     DST[1].
+
+ -- Macro: BASE16_ENCODE_LENGTH (LENGTH)
+     The number of output bytes when passing LENGTH input bytes to
+     `base16_encode_update'.
+
+ -- Function: void base16_encode_update (uint8_t *DST, unsigned LENGTH,
+          const uint8_t *SRC)
+     Always stores BASE16_ENCODE_LENGTH(LENGTH) digits in DST.
+
+ -- Context struct: struct base16_decode_ctx
+
+ -- Function: void base16_decode_init (struct base16_decode_ctx *CTX)
+     Initializes a base16 decoding context. This is necessary before
+     starting a decoding session.
+
+ -- Function: int base16_decode_single (struct base16_decode_ctx *CTX,
+          uint8_t *DST, uint8_t SRC)
+     Decodes a single byte from SRC into DST. Returns amount of output
+     (0 or 1), or -1 on errors.
+
+ -- Macro: BASE16_DECODE_LENGTH (LENGTH)
+     The maximum number of output bytes when passing LENGTH input bytes
+     to `base16_decode_update'.
+
+ -- Function: int base16_decode_update (struct base16_decode_ctx *CTX,
+          unsigned *DST_LENGTH, uint8_t *DST, unsigned SRC_LENGTH,
+          const uint8_t *SRC)
+     After CTX is initialized, this function may be called to decode
+     SRC_LENGTH bytes from SRC. DST should point to an area of size at
+     least BASE16_DECODE_LENGTH(LENGTH), and for sanity checking,
+     DST_LENGTH should be initialized to the size of that area before
+     the call.  DST_LENGTH is updated to the amount of decoded output.
+     The function will return 1 on success and 0 on error.
+
+ -- Function: int base16_decode_final (struct base16_decode_ctx *CTX)
+     Checks that the end of data is correct (i.e., an even number of
+     hexadecimal digits have been seen). Returns 1 on success, and 0 on
+     error.
+
+
+File: nettle.info,  Node: Miscellaneous functions,  Next: Compatibility functions,  Prev: Ascii encoding,  Up: Reference
+
+6.8 Miscellaneous functions
+===========================
+
+ -- Function: uint8_t * memxor (uint8_t *DST, const uint8_t *SRC,
+          size_t N)
+     XORs the source area on top of the destination area. The interface
+     doesn't follow the Nettle conventions, because it is intended to be
+     similar to the ANSI-C `memcpy' function.
+
+   `memxor' is declared in `<nettle/memxor.h>'.
+
+
+File: nettle.info,  Node: Compatibility functions,  Prev: Miscellaneous functions,  Up: Reference
+
+6.9 Compatibility functions
+===========================
+
+For convenience, Nettle includes alternative interfaces to some
+algorithms, for compatibility with some other popular crypto toolkits.
+These are not fully documented here; refer to the source or to the
+documentation for the original implementation.
+
+   MD5 is defined in [RFC 1321], which includes a reference
+implementation.  Nettle defines a compatible interface to MD5 in
+`<nettle/md5-compat.h>'. This file defines the typedef `MD5_CTX', and
+declares the functions `MD5Init', `MD5Update' and `MD5Final'.
+
+   Eric Young's "libdes" (also part of OpenSSL) is a quite popular DES
+implementation. Nettle includes a subset if its interface in
+`<nettle/des-compat.h>'. This file defines the typedefs
+`des_key_schedule' and `des_cblock', two constants `DES_ENCRYPT' and
+`DES_DECRYPT', and declares one global variable `des_check_key', and
+the functions `des_cbc_cksum' `des_cbc_encrypt', `des_ecb2_encrypt',
+`des_ecb3_encrypt', `des_ecb_encrypt', `des_ede2_cbc_encrypt',
+`des_ede3_cbc_encrypt', `des_is_weak_key', `des_key_sched',
+`des_ncbc_encrypt' `des_set_key', and `des_set_odd_parity'.
+
+
+File: nettle.info,  Node: Nettle soup,  Next: Installation,  Prev: Reference,  Up: Top
+
+7 Traditional Nettle Soup
+*************************
+
+For the serious nettle hacker, here is a recipe for nettle soup. 4
+servings.
+
+     1 liter fresh nettles (urtica dioica)
+
+     2 tablespoons butter
+
+     3 tablespoons flour
+
+     1 liter stock (meat or vegetable)
+
+     1/2 teaspoon salt
+
+     a tad white pepper
+
+     some cream or milk
+
+   Gather 1 liter fresh nettles. Use gloves! Small, tender shoots are
+preferable but the tops of larger nettles can also be used.
+
+   Rinse the nettles very well. Boil them for 10 minutes in lightly
+salted water. Strain the nettles and save the water. Hack the nettles.
+Melt the butter and mix in the flour. Dilute with stock and the
+nettle-water you saved earlier. Add the hacked nettles. If you wish you
+can add some milk or cream at this stage. Bring to a boil and let boil
+for a few minutes.  Season with salt and pepper.
+
+   Serve with boiled egg-halves.
+
+
+File: nettle.info,  Node: Installation,  Next: Index,  Prev: Nettle soup,  Up: Top
+
+8 Installation
+**************
+
+Nettle uses `autoconf'. To build it, unpack the source and run
+
+     ./configure
+     make
+     make check
+     make install
+
+to install in under the default prefix, `/usr/local'.
+
+   To get a list of configure options, use `./configure --help'.
+
+   By default, both static and shared libraries are built and
+installed. To omit building the shared libraries, use the `
+--disable-shared' option to `./configure'.
+
+   Using GNU make is recommended. For other make programs, in particular
+BSD make, you may have to use the `--disable-dependency-tracking'
+option to `./configure'.
+
+
+File: nettle.info,  Node: Index,  Prev: Installation,  Up: Top
+
+Function and Concept Index
+**************************
+
+[index]
+* Menu:
+
+* aes_decrypt:                           Cipher functions.    (line 123)
+* aes_encrypt:                           Cipher functions.    (line 116)
+* aes_invert_key:                        Cipher functions.    (line 105)
+* aes_set_decrypt_key:                   Cipher functions.    (line 101)
+* aes_set_encrypt_key:                   Cipher functions.    (line  99)
+* arcfour_crypt:                         Cipher functions.    (line 175)
+* arcfour_set_key:                       Cipher functions.    (line 170)
+* arctwo_decrypt:                        Cipher functions.    (line 240)
+* arctwo_encrypt:                        Cipher functions.    (line 233)
+* arctwo_set_key:                        Cipher functions.    (line 217)
+* arctwo_set_key_ekb:                    Cipher functions.    (line 215)
+* arctwo_set_key_gutmann:                Cipher functions.    (line 219)
+* base16_decode_final:                   Ascii encoding.      (line 139)
+* base16_decode_init:                    Ascii encoding.      (line 116)
+* BASE16_DECODE_LENGTH:                  Ascii encoding.      (line 125)
+* base16_decode_single:                  Ascii encoding.      (line 121)
+* base16_decode_update:                  Ascii encoding.      (line 131)
+* BASE16_ENCODE_LENGTH:                  Ascii encoding.      (line 106)
+* base16_encode_single:                  Ascii encoding.      (line 102)
+* base16_encode_update:                  Ascii encoding.      (line 111)
+* base64_decode_final:                   Ascii encoding.      (line  94)
+* base64_decode_init:                    Ascii encoding.      (line  71)
+* BASE64_DECODE_LENGTH:                  Ascii encoding.      (line  80)
+* base64_decode_single:                  Ascii encoding.      (line  76)
+* base64_decode_update:                  Ascii encoding.      (line  86)
+* base64_encode_final:                   Ascii encoding.      (line  63)
+* base64_encode_init:                    Ascii encoding.      (line  40)
+* BASE64_ENCODE_LENGTH:                  Ascii encoding.      (line  48)
+* base64_encode_single:                  Ascii encoding.      (line  45)
+* base64_encode_update:                  Ascii encoding.      (line  53)
+* Block Cipher:                          Cipher functions.    (line  12)
+* blowfish_decrypt:                      Cipher functions.    (line 282)
+* blowfish_encrypt:                      Cipher functions.    (line 275)
+* blowfish_set_key:                      Cipher functions.    (line 265)
+* camellia_crypt:                        Cipher functions.    (line 332)
+* camellia_invert_key:                   Cipher functions.    (line 321)
+* camellia_set_decrypt_key:              Cipher functions.    (line 317)
+* camellia_set_encrypt_key:              Cipher functions.    (line 315)
+* cast128_decrypt:                       Cipher functions.    (line 372)
+* cast128_encrypt:                       Cipher functions.    (line 365)
+* cast128_set_key:                       Cipher functions.    (line 360)
+* CBC Mode:                              CBC.                 (line   6)
+* CBC_CTX:                               CBC.                 (line  51)
+* CBC_DECRYPT:                           CBC.                 (line  72)
+* cbc_decrypt:                           CBC.                 (line  37)
+* CBC_ENCRYPT:                           CBC.                 (line  71)
+* cbc_encrypt:                           CBC.                 (line  34)
+* CBC_SET_IV:                            CBC.                 (line  66)
+* Cipher:                                Cipher functions.    (line   6)
+* Cipher Block Chaining:                 CBC.                 (line   6)
+* Collision-resistant:                   Hash functions.      (line  18)
+* Conditional entropy:                   Randomness.          (line  51)
+* Counter Mode:                          CTR.                 (line   6)
+* CTR Mode:                              CTR.                 (line   6)
+* CTR_CRYPT:                             CTR.                 (line  60)
+* ctr_crypt:                             CTR.                 (line  36)
+* CTR_CTX:                               CTR.                 (line  48)
+* CTR_SET_COUNTER:                       CTR.                 (line  55)
+* des3_decrypt:                          Cipher functions.    (line 494)
+* des3_encrypt:                          Cipher functions.    (line 487)
+* des3_set_key:                          Cipher functions.    (line 476)
+* des_check_parity:                      Cipher functions.    (line 420)
+* des_decrypt:                           Cipher functions.    (line 416)
+* des_encrypt:                           Cipher functions.    (line 409)
+* des_fix_parity:                        Cipher functions.    (line 425)
+* des_set_key:                           Cipher functions.    (line 401)
+* dsa_generate_keypair:                  DSA.                 (line 210)
+* dsa_private_key_clear:                 DSA.                 (line 142)
+* dsa_private_key_init:                  DSA.                 (line 135)
+* dsa_public_key_clear:                  DSA.                 (line 141)
+* dsa_public_key_init:                   DSA.                 (line 134)
+* dsa_sha1_sign:                         DSA.                 (line 166)
+* dsa_sha1_sign_digest:                  DSA.                 (line 170)
+* dsa_sha1_verify:                       DSA.                 (line 190)
+* dsa_sha1_verify_digest:                DSA.                 (line 193)
+* dsa_sha256_sign:                       DSA.                 (line 174)
+* dsa_sha256_sign_digest:                DSA.                 (line 178)
+* dsa_sha256_verify:                     DSA.                 (line 196)
+* dsa_sha256_verify_digest:              DSA.                 (line 199)
+* dsa_signature_clear:                   DSA.                 (line 151)
+* dsa_signature_init:                    DSA.                 (line 150)
+* Entropy:                               Randomness.          (line  51)
+* Galois Counter Mode:                   GCM.                 (line   6)
+* GCM:                                   GCM.                 (line   6)
+* gcm_aes_decrypt:                       GCM.                 (line 167)
+* gcm_aes_digest:                        GCM.                 (line 174)
+* gcm_aes_encrypt:                       GCM.                 (line 165)
+* gcm_aes_set_iv:                        GCM.                 (line 154)
+* gcm_aes_set_key:                       GCM.                 (line 149)
+* gcm_aes_update:                        GCM.                 (line 158)
+* GCM_CTX:                               GCM.                 (line 102)
+* GCM_DECRYPT:                           GCM.                 (line 132)
+* gcm_decrypt:                           GCM.                 (line  74)
+* GCM_DIGEST:                            GCM.                 (line 133)
+* gcm_digest:                            GCM.                 (line  82)
+* GCM_ENCRYPT:                           GCM.                 (line 131)
+* gcm_encrypt:                           GCM.                 (line  71)
+* GCM_SET_IV:                            GCM.                 (line 123)
+* gcm_set_iv:                            GCM.                 (line  58)
+* GCM_SET_KEY:                           GCM.                 (line 117)
+* gcm_set_key:                           GCM.                 (line  52)
+* GCM_UPDATE:                            GCM.                 (line 127)
+* gcm_update:                            GCM.                 (line  63)
+* Hash function:                         Hash functions.      (line   6)
+* HMAC_CTX:                              Keyed hash functions.
+                                                              (line  88)
+* HMAC_DIGEST:                           Keyed hash functions.
+                                                              (line 110)
+* hmac_digest:                           Keyed hash functions.
+                                                              (line  76)
+* hmac_md5_digest:                       Keyed hash functions.
+                                                              (line 140)
+* hmac_md5_set_key:                      Keyed hash functions.
+                                                              (line 132)
+* hmac_md5_update:                       Keyed hash functions.
+                                                              (line 136)
+* hmac_ripemd160_digest:                 Keyed hash functions.
+                                                              (line 162)
+* hmac_ripemd160_set_key:                Keyed hash functions.
+                                                              (line 154)
+* hmac_ripemd160_update:                 Keyed hash functions.
+                                                              (line 158)
+* HMAC_SET_KEY:                          Keyed hash functions.
+                                                              (line 104)
+* hmac_set_key:                          Keyed hash functions.
+                                                              (line  61)
+* hmac_sha1_digest:                      Keyed hash functions.
+                                                              (line 184)
+* hmac_sha1_set_key:                     Keyed hash functions.
+                                                              (line 176)
+* hmac_sha1_update:                      Keyed hash functions.
+                                                              (line 180)
+* hmac_sha256_digest:                    Keyed hash functions.
+                                                              (line 206)
+* hmac_sha256_set_key:                   Keyed hash functions.
+                                                              (line 198)
+* hmac_sha256_update:                    Keyed hash functions.
+                                                              (line 202)
+* hmac_sha512_digest:                    Keyed hash functions.
+                                                              (line 228)
+* hmac_sha512_set_key:                   Keyed hash functions.
+                                                              (line 220)
+* hmac_sha512_update:                    Keyed hash functions.
+                                                              (line 224)
+* hmac_update:                           Keyed hash functions.
+                                                              (line  68)
+* Keyed Hash Function:                   Keyed hash functions.
+                                                              (line   6)
+* MAC:                                   Keyed hash functions.
+                                                              (line   6)
+* md2_digest:                            Hash functions.      (line  96)
+* md2_init:                              Hash functions.      (line  88)
+* md2_update:                            Hash functions.      (line  92)
+* md4_digest:                            Hash functions.      (line 129)
+* md4_init:                              Hash functions.      (line 121)
+* md4_update:                            Hash functions.      (line 125)
+* md5_digest:                            Hash functions.      (line  58)
+* md5_init:                              Hash functions.      (line  50)
+* md5_update:                            Hash functions.      (line  54)
+* memxor:                                Miscellaneous functions.
+                                                              (line   8)
+* Message Authentication Code:           Keyed hash functions.
+                                                              (line   6)
+* One-way:                               Hash functions.      (line  14)
+* One-way function:                      Public-key algorithms.
+                                                              (line  18)
+* Public Key Cryptography:               Public-key algorithms.
+                                                              (line  18)
+* Randomness:                            Randomness.          (line   6)
+* ripemd160_digest:                      Hash functions.      (line 162)
+* ripemd160_init:                        Hash functions.      (line 154)
+* ripemd160_update:                      Hash functions.      (line 158)
+* rsa_compute_root:                      RSA.                 (line 187)
+* rsa_generate_keypair:                  RSA.                 (line 196)
+* rsa_md5_sign:                          RSA.                 (line 130)
+* rsa_md5_sign_digest:                   RSA.                 (line 145)
+* rsa_md5_verify:                        RSA.                 (line 159)
+* rsa_md5_verify_digest:                 RSA.                 (line 171)
+* rsa_private_key_clear:                 RSA.                 (line  96)
+* rsa_private_key_init:                  RSA.                 (line  89)
+* rsa_private_key_prepare:               RSA.                 (line 109)
+* rsa_public_key_clear:                  RSA.                 (line  95)
+* rsa_public_key_init:                   RSA.                 (line  88)
+* rsa_public_key_prepare:                RSA.                 (line 108)
+* rsa_sha1_sign:                         RSA.                 (line 132)
+* rsa_sha1_sign_digest:                  RSA.                 (line 147)
+* rsa_sha1_verify:                       RSA.                 (line 161)
+* rsa_sha1_verify_digest:                RSA.                 (line 173)
+* rsa_sha256_sign:                       RSA.                 (line 134)
+* rsa_sha256_sign_digest:                RSA.                 (line 149)
+* rsa_sha256_verify:                     RSA.                 (line 163)
+* rsa_sha256_verify_digest:              RSA.                 (line 175)
+* rsa_sha512_sign:                       RSA.                 (line 136)
+* rsa_sha512_sign_digest:                RSA.                 (line 151)
+* rsa_sha512_verify:                     RSA.                 (line 165)
+* rsa_sha512_verify_digest:              RSA.                 (line 177)
+* salsa20_crypt:                         Cipher functions.    (line 554)
+* salsa20_set_iv:                        Cipher functions.    (line 548)
+* salsa20_set_key:                       Cipher functions.    (line 542)
+* serpent_decrypt:                       Cipher functions.    (line 597)
+* serpent_encrypt:                       Cipher functions.    (line 590)
+* serpent_set_key:                       Cipher functions.    (line 585)
+* sha1_digest:                           Hash functions.      (line 197)
+* sha1_init:                             Hash functions.      (line 189)
+* sha1_update:                           Hash functions.      (line 193)
+* sha224_digest:                         Hash functions.      (line 265)
+* sha224_init:                           Hash functions.      (line 257)
+* sha224_update:                         Hash functions.      (line 261)
+* sha256_digest:                         Hash functions.      (line 231)
+* sha256_init:                           Hash functions.      (line 223)
+* sha256_update:                         Hash functions.      (line 227)
+* sha384_digest:                         Hash functions.      (line 335)
+* sha384_init:                           Hash functions.      (line 327)
+* sha384_update:                         Hash functions.      (line 331)
+* sha512_digest:                         Hash functions.      (line 301)
+* sha512_init:                           Hash functions.      (line 293)
+* sha512_update:                         Hash functions.      (line 297)
+* Stream Cipher:                         Cipher functions.    (line  12)
+* twofish_decrypt:                       Cipher functions.    (line 633)
+* twofish_encrypt:                       Cipher functions.    (line 626)
+* twofish_set_key:                       Cipher functions.    (line 621)
+* yarrow256_fast_reseed:                 Randomness.          (line 277)
+* yarrow256_init:                        Randomness.          (line 226)
+* yarrow256_is_seeded:                   Randomness.          (line 267)
+* yarrow256_needed_sources:              Randomness.          (line 272)
+* yarrow256_random:                      Randomness.          (line 258)
+* yarrow256_seed:                        Randomness.          (line 232)
+* yarrow256_slow_reseed:                 Randomness.          (line 278)
+* yarrow256_update:                      Randomness.          (line 245)
+* yarrow_key_event_estimate:             Randomness.          (line 293)
+* yarrow_key_event_init:                 Randomness.          (line 289)
+
+
+
+Tag Table:
+Node: Top543
+Node: Introduction2159
+Node: Copyright3725
+Node: Conventions7757
+Node: Example9719
+Node: Linking10966
+Node: Reference11799
+Node: Hash functions12186
+Node: Cipher functions25387
+Node: Cipher modes54077
+Node: CBC55105
+Node: CTR58379
+Node: GCM60906
+Node: Keyed hash functions68467
+Node: Public-key algorithms77824
+Node: RSA81744
+Node: RSA-Footnotes92358
+Ref: RSA-Footnote-192411
+Node: DSA92580
+Node: Randomness103923
+Node: Ascii encoding119027
+Node: Miscellaneous functions125477
+Node: Compatibility functions125985
+Node: Nettle soup127230
+Node: Installation128223
+Node: Index128918
+
+End Tag Table
+
+
+Local Variables:
+coding: utf-8
+End: