nettle.html

   1 <html lang="en">
   2 <head>
   3 <title>Nettle: a low-level cryptographic library</title>
   4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   5 <meta name="description" content="Nettle: a low-level cryptographic library">
   6 <meta name="generator" content="makeinfo 4.13">
   7 <link title="Top" rel="top" href="#Top">
   8 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
   9 <!--
  10 This manual is for the Nettle library (version 2.7), a
  11 low-level cryptographic library.
  12
  13 Originally written 2001 by Niels Möller, updated 2013.
  14
  15      This manual is placed in the public domain. You may freely copy
  16      it, in whole or in part, with or without modification. Attribution
  17      is appreciated, but not required.
  18    -->
  19 <meta http-equiv="Content-Style-Type" content="text/css">
  20 <style type="text/css"><!--
  21   pre.display { font-family:inherit }
  22   pre.format  { font-family:inherit }
  23   pre.smalldisplay { font-family:inherit; font-size:smaller }
  24   pre.smallformat  { font-family:inherit; font-size:smaller }
  25   pre.smallexample { font-size:smaller }
  26   pre.smalllisp    { font-size:smaller }
  27   span.sc    { font-variant:small-caps }
  28   span.roman { font-family:serif; font-weight:normal; }
  29   span.sansserif { font-family:sans-serif; font-weight:normal; }
  30 --></style>
  31 </head>
  32 <body>
  33 <h1 class="settitle">Nettle: a low-level cryptographic library</h1>
  34    <div class="contents">
  35 <h2>Table of Contents</h2>
  36 <ul>
  37 <li><a name="toc_Top" href="#Top">Nettle</a>
  38 <li><a name="toc_Introduction" href="#Introduction">1 Introduction</a>
  39 <li><a name="toc_Copyright" href="#Copyright">2 Copyright</a>
  40 <li><a name="toc_Conventions" href="#Conventions">3 Conventions</a>
  41 <li><a name="toc_Example" href="#Example">4 Example</a>
  42 <li><a name="toc_Linking" href="#Linking">5 Linking</a>
  43 <li><a name="toc_Reference" href="#Reference">6 Reference</a>
  44 <ul>
  45 <li><a href="#Hash-functions">6.1 Hash functions</a>
  46 <ul>
  47 <li><a href="#Recommended-hash-functions">6.1.1 Recommended hash functions</a>
  48 <ul>
  49 <li><a href="#Recommended-hash-functions">6.1.1.1 <acronym>SHA256</acronym></a>
  50 <li><a href="#Recommended-hash-functions">6.1.1.2 <acronym>SHA224</acronym></a>
  51 <li><a href="#Recommended-hash-functions">6.1.1.3 <acronym>SHA512</acronym></a>
  52 <li><a href="#Recommended-hash-functions">6.1.1.4 <acronym>SHA384</acronym></a>
  53 <li><a href="#Recommended-hash-functions">6.1.1.5 <acronym>SHA3-224</acronym></a>
  54 <li><a href="#Recommended-hash-functions">6.1.1.6 <acronym>SHA3-256</acronym></a>
  55 <li><a href="#Recommended-hash-functions">6.1.1.7 <acronym>SHA3-384</acronym></a>
  56 <li><a href="#Recommended-hash-functions">6.1.1.8 <acronym>SHA3-512</acronym></a>
  57 </li></ul>
  58 <li><a href="#Legacy-hash-functions">6.1.2 Legacy hash functions</a>
  59 <ul>
  60 <li><a href="#Legacy-hash-functions">6.1.2.1 <acronym>MD5</acronym></a>
  61 <li><a href="#Legacy-hash-functions">6.1.2.2 <acronym>MD2</acronym></a>
  62 <li><a href="#Legacy-hash-functions">6.1.2.3 <acronym>MD4</acronym></a>
  63 <li><a href="#Legacy-hash-functions">6.1.2.4 <acronym>RIPEMD160</acronym></a>
  64 <li><a href="#Legacy-hash-functions">6.1.2.5 <acronym>SHA1</acronym></a>
  65 <li><a href="#Legacy-hash-functions">6.1.2.6 <acronym>GOSTHASH94</acronym></a>
  66 </li></ul>
  67 <li><a href="#nettle_005fhash-abstraction">6.1.3 The nettle_hash abstraction</a>
  68 </li></ul>
  69 <li><a href="#Cipher-functions">6.2 Cipher functions</a>
  70 <ul>
  71 <li><a href="#Cipher-functions">6.2.1 AES</a>
  72 <li><a href="#Cipher-functions">6.2.2 ARCFOUR</a>
  73 <li><a href="#Cipher-functions">6.2.3 ARCTWO</a>
  74 <li><a href="#Cipher-functions">6.2.4 BLOWFISH</a>
  75 <li><a href="#Cipher-functions">6.2.5 Camellia</a>
  76 <li><a href="#Cipher-functions">6.2.6 CAST128</a>
  77 <li><a href="#Cipher-functions">6.2.7 DES</a>
  78 <li><a href="#Cipher-functions">6.2.8 DES3</a>
  79 <li><a href="#Cipher-functions">6.2.9 Salsa20</a>
  80 <li><a href="#Cipher-functions">6.2.10 SERPENT</a>
  81 <li><a href="#Cipher-functions">6.2.11 TWOFISH</a>
  82 <li><a href="#Cipher-functions">6.2.12 <code>struct nettle_cipher</code></a>
  83 </li></ul>
  84 <li><a href="#Cipher-modes">6.3 Cipher modes</a>
  85 <ul>
  86 <li><a href="#CBC">6.3.1 Cipher Block Chaining</a>
  87 <li><a href="#CTR">6.3.2 Counter mode</a>
  88 <li><a href="#GCM">6.3.3 Galois counter mode</a>
  89 <ul>
  90 <li><a href="#GCM">6.3.3.1 General <acronym>GCM</acronym> interface</a>
  91 <li><a href="#GCM">6.3.3.2 <acronym>GCM</acronym> helper macros</a>
  92 <li><a href="#GCM">6.3.3.3 <acronym>GCM</acronym>-<acronym>AES</acronym> interface</a>
  93 </li></ul>
  94 </li></ul>
  95 <li><a href="#Keyed-hash-functions">6.4 Keyed Hash Functions</a>
  96 <ul>
  97 <li><a href="#Keyed-hash-functions">6.4.1 <acronym>HMAC</acronym></a>
  98 <li><a href="#Keyed-hash-functions">6.4.2 Concrete <acronym>HMAC</acronym> functions</a>
  99 <ul>
 100 <li><a href="#Keyed-hash-functions">6.4.2.1 <acronym>HMAC-MD5</acronym></a>
 101 <li><a href="#Keyed-hash-functions">6.4.2.2 <acronym>HMAC-RIPEMD160</acronym></a>
 102 <li><a href="#Keyed-hash-functions">6.4.2.3 <acronym>HMAC-SHA1</acronym></a>
 103 <li><a href="#Keyed-hash-functions">6.4.2.4 <acronym>HMAC-SHA256</acronym></a>
 104 <li><a href="#Keyed-hash-functions">6.4.2.5 <acronym>HMAC-SHA512</acronym></a>
 105 </li></ul>
 106 <li><a href="#Keyed-hash-functions">6.4.3 <acronym>UMAC</acronym></a>
 107 </li></ul>
 108 <li><a href="#Key-derivation-functions">6.5 Key derivation Functions</a>
 109 <ul>
 110 <li><a href="#Key-derivation-functions">6.5.1 <acronym>PBKDF2</acronym></a>
 111 <li><a href="#Key-derivation-functions">6.5.2 Concrete <acronym>PBKDF2</acronym> functions</a>
 112 <ul>
 113 <li><a href="#Key-derivation-functions">6.5.2.1 <acronym>PBKDF2-HMAC-SHA1</acronym></a>
 114 <li><a href="#Key-derivation-functions">6.5.2.2 <acronym>PBKDF2-HMAC-SHA256</acronym></a>
 115 </li></ul>
 116 </li></ul>
 117 <li><a href="#Public_002dkey-algorithms">6.6 Public-key algorithms</a>
 118 <ul>
 119 <li><a href="#RSA">6.6.1 <acronym>RSA</acronym></a>
 120 <li><a href="#RSA">6.6.2 Nettle's <acronym>RSA</acronym> support</a>
 121 <li><a href="#DSA">6.6.3 <acronym>DSA</acronym></a>
 122 <li><a href="#DSA">6.6.4 Nettle's <acronym>DSA</acronym> support</a>
 123 <li><a href="#Elliptic-curves">6.6.5 <acronym>Elliptic curves</acronym></a>
 124 <ul>
 125 <li><a href="#Elliptic-curves">6.6.5.1 Side-channel silence</a>
 126 </li></ul>
 127 <li><a href="#Elliptic-curves">6.6.6 ECDSA</a>
 128 </li></ul>
 129 <li><a href="#Randomness">6.7 Randomness</a>
 130 <ul>
 131 <li><a href="#Randomness">6.7.1 Yarrow</a>
 132 </li></ul>
 133 <li><a href="#ASCII-encoding">6.8 ASCII encoding</a>
 134 <li><a href="#Miscellaneous-functions">6.9 Miscellaneous functions</a>
 135 <li><a href="#Compatibility-functions">6.10 Compatibility functions</a>
 136 </li></ul>
 137 <li><a name="toc_Nettle-soup" href="#Nettle-soup">7 Traditional Nettle Soup</a>
 138 <li><a name="toc_Installation" href="#Installation">8 Installation</a>
 139 <li><a name="toc_Index" href="#Index">Function and Concept Index</a>
 140 </li></ul>
 141 </div>
 142
 143
 144
 145 <div class="node">
 146 <a name="Top"></a>
 147 <p><hr>
 148 Next:&nbsp;<a rel="next" accesskey="n" href="#Introduction">Introduction</a>,
 149 Previous:&nbsp;<a rel="previous" accesskey="p" href="#dir">(dir)</a>,
 150 Up:&nbsp;<a rel="up" accesskey="u" href="#dir">(dir)</a>
 151
 152 </div>
 153
 154 <!-- node-name,  next,  previous,  up -->
 155 <h2 class="unnumbered">Nettle</h2>
 156
 157 <p>This document describes the Nettle low-level cryptographic library. You
 158 can use the library directly from your C programs, or write or use an
 159 object-oriented wrapper for your favorite language or application.
 160
 161    <p>This manual is for the Nettle library (version 2.7), a
 162 low-level cryptographic library.
 163
 164    <p>Originally written 2001 by Niels Möller, updated 2013.
 165
 166    <blockquote>
 167 This manual is placed in the public domain. You may freely copy it, in
 168 whole or in part, with or without modification. Attribution is
 169 appreciated, but not required.
 170 </blockquote>
 171
 172 <ul class="menu">
 173 <li><a accesskey="1" href="#Introduction">Introduction</a>:                 What is Nettle?
 174 <li><a accesskey="2" href="#Copyright">Copyright</a>:                    Your rights.
 175 <li><a accesskey="3" href="#Conventions">Conventions</a>:                  General interface conventions.
 176 <li><a accesskey="4" href="#Example">Example</a>:                      An example program.
 177 <li><a accesskey="5" href="#Linking">Linking</a>:                      Linking with libnettle and libhogweed.
 178 <li><a accesskey="6" href="#Reference">Reference</a>:                    All Nettle functions and features.
 179 <li><a accesskey="7" href="#Nettle-soup">Nettle soup</a>:                  For the serious nettle hacker.
 180 <li><a accesskey="8" href="#Installation">Installation</a>:                 How to install Nettle.
 181 <li><a accesskey="9" href="#Index">Index</a>:                        Function and concept index.
 182
 183 </li></ul>
 184 <p>--- The Detailed Node Listing ---
 185
 186 <p>Reference
 187
 188 </p>
 189 <ul class="menu">
 190 <li><a href="#Hash-functions">Hash functions</a>
 191 <li><a href="#Cipher-functions">Cipher functions</a>
 192 <li><a href="#Cipher-modes">Cipher modes</a>
 193 <li><a href="#Keyed-hash-functions">Keyed hash functions</a>
 194 <li><a href="#Key-derivation-functions">Key derivation functions</a>
 195 <li><a href="#Public_002dkey-algorithms">Public-key algorithms</a>
 196 <li><a href="#Randomness">Randomness</a>
 197 <li><a href="#ASCII-encoding">ASCII encoding</a>
 198 <li><a href="#Miscellaneous-functions">Miscellaneous functions</a>
 199 <li><a href="#Compatibility-functions">Compatibility functions</a>
 200
 201 </li></ul>
 202 <p>Cipher modes
 203
 204 </p>
 205 <ul class="menu">
 206 <li><a href="#CBC">CBC</a>
 207 <li><a href="#CTR">CTR</a>
 208 <li><a href="#GCM">GCM</a>
 209
 210 </li></ul>
 211 <p>Public-key algorithms
 212
 213 </p>
 214 <ul class="menu">
 215 <li><a href="#RSA">RSA</a>:                          The RSA public key algorithm.
 216 <li><a href="#DSA">DSA</a>:                          The DSA digital signature algorithm.
 217 <li><a href="#Elliptic-curves">Elliptic curves</a>:              Elliptic curves and ECDSA
 218
 219    </ul>
 220
 221 <div class="node">
 222 <a name="Introduction"></a>
 223 <p><hr>
 224 Next:&nbsp;<a rel="next" accesskey="n" href="#Copyright">Copyright</a>,
 225 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Top">Top</a>,
 226 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
 227
 228 </div>
 229
 230 <!-- node-name,  next,  previous,  up -->
 231 <h2 class="chapter">1 Introduction</h2>
 232
 233 <p>Nettle is a cryptographic library that is designed to fit easily in more
 234 or less any context: In crypto toolkits for object-oriented languages
 235 (C++, Python, Pike, ...), in applications like LSH or GNUPG, or even in
 236 kernel space. In most contexts, you need more than the basic
 237 cryptographic algorithms, you also need some way to keep track of available
 238 algorithms, their properties and variants. You often have some algorithm
 239 selection process, often dictated by a protocol you want to implement.
 240
 241    <p>And as the requirements of applications differ in subtle and not so
 242 subtle ways, an API that fits one application well can be a pain to use
 243 in a different context. And that is why there are so many different
 244 cryptographic libraries around.
 245
 246    <p>Nettle tries to avoid this problem by doing one thing, the low-level
 247 crypto stuff, and providing a <em>simple</em> but general interface to it.
 248 In particular, Nettle doesn't do algorithm selection. It doesn't do
 249 memory allocation. It doesn't do any I/O.
 250
 251    <p>The idea is that one can build several application and context specific
 252 interfaces on top of Nettle, and share the code, test cases, benchmarks,
 253 documentation, etc. Examples are the Nettle module for the Pike
 254 language, and LSH, which both use an object-oriented abstraction on top
 255 of the library.
 256
 257    <p>This manual explains how to use the Nettle library. It also tries to
 258 provide some background on the cryptography, and advice on how to best
 259 put it to use.
 260
 261 <div class="node">
 262 <a name="Copyright"></a>
 263 <p><hr>
 264 Next:&nbsp;<a rel="next" accesskey="n" href="#Conventions">Conventions</a>,
 265 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Introduction">Introduction</a>,
 266 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
 267
 268 </div>
 269
 270 <!-- node-name,  next,  previous,  up -->
 271 <h2 class="chapter">2 Copyright</h2>
 272
 273 <p>Nettle is distributed under the GNU Lesser General Public License
 274 (LGPL), see the file COPYING.LIB for details. A few of the individual
 275 files are in the public domain. To find the current status of particular
 276 files, you have to read the copyright notices at the top of the files.
 277
 278    <p>This manual is in the public domain. You may freely copy it in whole or
 279 in part, e.g., into documentation of programs that build on Nettle.
 280 Attribution, as well as contribution of improvements to the text, is of
 281 course appreciated, but it is not required.
 282
 283    <p>A list of the supported algorithms, their origins and licenses:
 284
 285      <dl>
 286 <dt><em>AES</em><dd>The implementation of the AES cipher (also known as rijndael) is written
 287 by Rafael Sevilla. Assembler for x86 by Rafael Sevilla and
 288 Niels Möller, Sparc assembler by Niels Möller. Released under the
 289 LGPL.
 290
 291      <br><dt><em>ARCFOUR</em><dd>The implementation of the ARCFOUR (also known as RC4) cipher is written
 292 by Niels Möller. Released under the LGPL.
 293
 294      <br><dt><em>ARCTWO</em><dd>The implementation of the ARCTWO (also known as RC2) cipher is written
 295 by Nikos Mavroyanopoulos and modified by Werner Koch and Simon
 296 Josefsson. Released under the LGPL.
 297
 298      <br><dt><em>BLOWFISH</em><dd>The implementation of the BLOWFISH cipher is written by Werner Koch,
 299 copyright owned by the Free Software Foundation. Also hacked by Simon
 300 Josefsson and Niels Möller. Released under the LGPL.
 301
 302      <br><dt><em>CAMELLIA</em><dd>The C implementation is by Nippon Telegraph and Telephone Corporation
 303 (NTT), heavily modified by Niels Möller. Assembler for x86 and x86_64
 304 by Niels Möller. Released under the LGPL.
 305
 306      <br><dt><em>CAST128</em><dd>The implementation of the CAST128 cipher is written by Steve Reid.
 307 Released into the public domain.
 308
 309      <br><dt><em>DES</em><dd>The implementation of the DES cipher is written by Dana L. How, and
 310 released under the LGPL.
 311
 312      <br><dt><em>GOSTHASH94</em><dd>The C implementation of the GOST94 message digest is written by
 313 Aleksey Kravchenko and was ported from the rhash library by Nikos
 314 Mavrogiannopoulos. It is released under the MIT license.
 315
 316      <br><dt><em>MD2</em><dd>The implementation of MD2 is written by Andrew Kuchling, and hacked
 317 some by Andreas Sigfridsson and Niels Möller. Python Cryptography
 318 Toolkit license (essentially public domain).
 319
 320      <br><dt><em>MD4</em><dd>This is almost the same code as for MD5 below, with modifications by
 321 Marcus Comstedt. Released into the public domain.
 322
 323      <br><dt><em>MD5</em><dd>The implementation of the MD5 message digest is written by Colin Plumb.
 324 It has been hacked some more by Andrew Kuchling and Niels Möller.
 325 Released into the public domain.
 326
 327      <br><dt><em>PBKDF2</em><dd>The C implementation of PBKDF2 is based on earlier work for Shishi and
 328 GnuTLS by Simon Josefsson.  Released under the LGPL.
 329
 330      <br><dt><em>RIPEMD160</em><dd>The implementation of RIPEMD160 message digest is based on the code in
 331 libgcrypt, copyright owned by the Free Software Foundation. Ported to
 332 Nettle by Andres Mejia. Released under the LGPL.
 333
 334      <br><dt><em>SALSA20</em><dd>The C implementation of SALSA20 is based on D. J. Bernstein's reference
 335 implementation (in the public domain), adapted to Nettle by Simon
 336 Josefsson, and heavily modified by Niels Möller. Assembly for x86_64 and
 337 ARM by Niels Möller. Released under the LGPL.
 338
 339      <br><dt><em>SERPENT</em><dd>The implementation of the SERPENT cipher is based on the code in libgcrypt,
 340 copyright owned by the Free Software Foundation. Adapted to Nettle by
 341 Simon Josefsson and heavily modified by Niels Möller. Assembly for
 342 x86_64 by Niels Möller. Released under the LGPL.
 343
 344      <br><dt><em>SHA1</em><dd>The C implementation of the SHA1 message digest is written by Peter
 345 Gutmann, and hacked some more by Andrew Kuchling and Niels Möller.
 346 Released into the public domain. Assembler for x86, x86_64 and ARM by
 347 Niels Möller, released under the LGPL.
 348
 349      <br><dt><em>SHA2</em><dd>Written by Niels Möller, using Peter Gutmann's SHA1 code as a model.
 350 Released under the LGPL.
 351
 352      <br><dt><em>SHA3</em><dd>Written by Niels Möller. Released under the LGPL.
 353
 354      <br><dt><em>TWOFISH</em><dd>The implementation of the TWOFISH cipher is written by Ruud de Rooij.
 355 Released under the LGPL.
 356
 357      <br><dt><em>UMAC</em><dd>Written by Niels Möller. Released under the LGPL.
 358
 359      <br><dt><em>RSA</em><dd>Written by Niels Möller, released under the LGPL. Uses the GMP library
 360 for bignum operations.
 361
 362      <br><dt><em>DSA</em><dd>Written by Niels Möller, released under the LGPL. Uses the GMP library
 363 for bignum operations.
 364
 365      <br><dt><em>ECDSA</em><dd>Written by Niels Möller, released under the LGPL. Uses the GMP library
 366 for bignum operations. Development of Nettle's ECC support was funded by
 367 the .SE Internet Fund.
 368 </dl>
 369
 370 <div class="node">
 371 <a name="Conventions"></a>
 372 <p><hr>
 373 Next:&nbsp;<a rel="next" accesskey="n" href="#Example">Example</a>,
 374 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Copyright">Copyright</a>,
 375 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
 376
 377 </div>
 378
 379 <!-- node-name,  next,  previous,  up -->
 380 <h2 class="chapter">3 Conventions</h2>
 381
 382 <p>For each supported algorithm, there is an include file that defines a
 383 <em>context struct</em>, a few constants, and declares functions for
 384 operating on the context. The context struct encapsulates all information
 385 needed by the algorithm, and it can be copied or moved in memory with no
 386 unexpected effects.
 387
 388    <p>For consistency, functions for different algorithms are very similar,
 389 but there are some differences, for instance reflecting if the key setup
 390 or encryption function differ for encryption and decryption, and whether
 391 or not key setup can fail. There are also differences between algorithms
 392 that don't show in function prototypes, but which the application must
 393 nevertheless be aware of. There is no big difference between the
 394 functions for stream ciphers and for block ciphers, although they should
 395 be used quite differently by the application.
 396
 397    <p>If your application uses more than one algorithm of the same type, you
 398 should probably create an interface that is tailor-made for your needs,
 399 and then write a few lines of glue code on top of Nettle.
 400
 401    <p>By convention, for an algorithm named <code>foo</code>, the struct tag for the
 402 context struct is <code>foo_ctx</code>, constants and functions uses prefixes
 403 like <code>FOO_BLOCK_SIZE</code> (a constant) and <code>foo_set_key</code> (a
 404 function).
 405
 406    <p>In all functions, strings are represented with an explicit length, of
 407 type <code>unsigned</code>, and a pointer of type <code>uint8_t *</code> or
 408 <code>const uint8_t *</code>. For functions that transform one string to
 409 another, the argument order is length, destination pointer and source
 410 pointer. Source and destination areas are of the same length. Source and
 411 destination may be the same, so that you can process strings in place,
 412 but they <em>must not</em> overlap in any other way.
 413
 414    <p>Many of the functions lack return value and can never fail. Those
 415 functions which can fail, return one on success and zero on failure.
 416
 417 <!-- FIXME: Say something about the name mangling. -->
 418 <div class="node">
 419 <a name="Example"></a>
 420 <p><hr>
 421 Next:&nbsp;<a rel="next" accesskey="n" href="#Linking">Linking</a>,
 422 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Conventions">Conventions</a>,
 423 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
 424
 425 </div>
 426
 427 <!-- node-name,  next,  previous,  up -->
 428 <h2 class="chapter">4 Example</h2>
 429
 430 <p>A simple example program that reads a file from standard input and
 431 writes its SHA1 check-sum on standard output should give the flavor of
 432 Nettle.
 433
 434 <pre class="example"><pre class="verbatim">     #include &lt;stdio.h>
 435      #include &lt;stdlib.h>
 436
 437      #include &lt;nettle/sha1.h>
 438
 439      #define BUF_SIZE 1000
 440
 441      static void
 442      display_hex(unsigned length, uint8_t *data)
 443      {
 444        unsigned i;
 445
 446        for (i = 0; i&lt;length; i++)
 447          printf("%02x ", data[i]);
 448
 449        printf("\n");
 450      }
 451
 452      int
 453      main(int argc, char **argv)
 454      {
 455        struct sha1_ctx ctx;
 456        uint8_t buffer[BUF_SIZE];
 457        uint8_t digest[SHA1_DIGEST_SIZE];
 458
 459        sha1_init(&amp;ctx);
 460        for (;;)
 461        {
 462          int done = fread(buffer, 1, sizeof(buffer), stdin);
 463          sha1_update(&amp;ctx, done, buffer);
 464          if (done &lt; sizeof(buffer))
 465            break;
 466        }
 467        if (ferror(stdin))
 468          return EXIT_FAILURE;
 469
 470        sha1_digest(&amp;ctx, SHA1_DIGEST_SIZE, digest);
 471
 472        display_hex(SHA1_DIGEST_SIZE, digest);
 473        return EXIT_SUCCESS;
 474      }
 475 </pre></pre>
 476    <p>On a typical Unix system, this program can be compiled and linked with
 477 the command line
 478 <pre class="example">     gcc sha-example.c -o sha-example -lnettle
 479 </pre>
 480    <div class="node">
 481 <a name="Linking"></a>
 482 <p><hr>
 483 Next:&nbsp;<a rel="next" accesskey="n" href="#Reference">Reference</a>,
 484 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Example">Example</a>,
 485 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
 486
 487 </div>
 488
 489 <!-- node-name,  next,  previous,  up -->
 490 <h2 class="chapter">5 Linking</h2>
 491
 492 <p>Nettle actually consists of two libraries, <samp><span class="file">libnettle</span></samp> and
 493 <samp><span class="file">libhogweed</span></samp>. The <samp><span class="file">libhogweed</span></samp> library contains those
 494 functions of Nettle that uses bignum operations, and depends on the GMP
 495 library. With this division, linking works the same for both static and
 496 dynamic libraries.
 497
 498    <p>If an application uses only the symmetric crypto algorithms of Nettle
 499 (i.e., block ciphers, hash functions, and the like), it's sufficient to
 500 link with <code>-lnettle</code>. If an application also uses public-key
 501 algorithms, the recommended linker flags are <code>-lhogweed -lnettle
 502 -lgmp</code>. If the involved libraries are installed as dynamic libraries, it
 503 may be sufficient to link with just <code>-lhogweed</code>, and the loader
 504 will resolve the dependencies automatically.
 505
 506 <div class="node">
 507 <a name="Reference"></a>
 508 <p><hr>
 509 Next:&nbsp;<a rel="next" accesskey="n" href="#Nettle-soup">Nettle soup</a>,
 510 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Linking">Linking</a>,
 511 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
 512
 513 </div>
 514
 515 <!-- node-name,  next,  previous,  up -->
 516 <h2 class="chapter">6 Reference</h2>
 517
 518 <p>This chapter describes all the Nettle functions, grouped by family.
 519
 520 <ul class="menu">
 521 <li><a accesskey="1" href="#Hash-functions">Hash functions</a>
 522 <li><a accesskey="2" href="#Cipher-functions">Cipher functions</a>
 523 <li><a accesskey="3" href="#Cipher-modes">Cipher modes</a>
 524 <li><a accesskey="4" href="#Keyed-hash-functions">Keyed hash functions</a>
 525 <li><a accesskey="5" href="#Key-derivation-functions">Key derivation functions</a>
 526 <li><a accesskey="6" href="#Public_002dkey-algorithms">Public-key algorithms</a>
 527 <li><a accesskey="7" href="#Randomness">Randomness</a>
 528 <li><a accesskey="8" href="#ASCII-encoding">ASCII encoding</a>
 529 <li><a accesskey="9" href="#Miscellaneous-functions">Miscellaneous functions</a>
 530 <li><a href="#Compatibility-functions">Compatibility functions</a>
 531 </ul>
 532
 533 <div class="node">
 534 <a name="Hash-functions"></a>
 535 <p><hr>
 536 Next:&nbsp;<a rel="next" accesskey="n" href="#Cipher-functions">Cipher functions</a>,
 537 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Reference">Reference</a>,
 538 Up:&nbsp;<a rel="up" accesskey="u" href="#Reference">Reference</a>
 539
 540 </div>
 541
 542 <!-- node-name,  next,  previous,  up -->
 543 <h3 class="section">6.1 Hash functions</h3>
 544
 545 <p><a name="index-Hash-function-1"></a>A cryptographic <dfn>hash function</dfn> is a function that takes variable
 546 size strings, and maps them to strings of fixed, short, length. There
 547 are naturally lots of collisions, as there are more possible 1MB files
 548 than 20 byte strings. But the function is constructed such that is hard
 549 to find the collisions. More precisely, a cryptographic hash function
 550 <code>H</code> should have the following properties:
 551
 552      <dl>
 553 <dt><em>One-way</em><dd><a name="index-One_002dway-2"></a>Given a hash value <code>H(x)</code> it is hard to find a string <code>x</code>
 554 that hashes to that value.
 555
 556      <br><dt><em>Collision-resistant</em><dd><a name="index-Collision_002dresistant-3"></a>It is hard to find two different strings, <code>x</code> and <code>y</code>, such
 557 that <code>H(x)</code> = <code>H(y)</code>.
 558
 559    </dl>
 560
 561    <p>Hash functions are useful as building blocks for digital signatures,
 562 message authentication codes, pseudo random generators, association of
 563 unique ids to documents, and many other things.
 564
 565    <p>The most commonly used hash functions are MD5 and SHA1. Unfortunately,
 566 both these fail the collision-resistance requirement; cryptologists have
 567 found ways to construct colliding inputs. The recommended hash functions
 568 for new applications are SHA2 (with main variants SHA256 and SHA512). At
 569 the time of this writing (December 2012), the winner of the NIST SHA3
 570 competition has recently been announced, and the new SHA3 (earlier known
 571 as Keccak) and other top SHA3 candidates may also be reasonable
 572 alternatives.
 573
 574 <ul class="menu">
 575 <li><a accesskey="1" href="#Recommended-hash-functions">Recommended hash functions</a>
 576 <li><a accesskey="2" href="#Legacy-hash-functions">Legacy hash functions</a>
 577 <li><a accesskey="3" href="#nettle_005fhash-abstraction">nettle_hash abstraction</a>
 578 </ul>
 579
 580 <div class="node">
 581 <a name="Recommended-hash-functions"></a>
 582 <p><hr>
 583 Next:&nbsp;<a rel="next" accesskey="n" href="#Legacy-hash-functions">Legacy hash functions</a>,
 584 Up:&nbsp;<a rel="up" accesskey="u" href="#Hash-functions">Hash functions</a>
 585
 586 </div>
 587
 588 <!-- node-name,  next,  previous,  up -->
 589 <h4 class="subsection">6.1.1 Recommended hash functions</h4>
 590
 591 <p>The following hash functions have no known weaknesses, and are suitable
 592 for new applications. The SHA2 family of hash functions were specified
 593 by <dfn>NIST</dfn>, intended as a replacement for <acronym>SHA1</acronym>.
 594
 595 <h5 class="subsubsection">6.1.1.1 <acronym>SHA256</acronym></h5>
 596
 597 <p>SHA256 is a member of the SHA2 family. It outputs hash values of 256
 598 bits, or 32 octets. Nettle defines SHA256 in <samp><span class="file">&lt;nettle/sha2.h&gt;</span></samp>.
 599
 600 <div class="defun">
 601 &mdash; Context struct: <b>struct sha256_ctx</b><var><a name="index-struct-sha256_005fctx-4"></a></var><br>
 602         </div>
 603
 604 <div class="defun">
 605 &mdash; Constant: <b>SHA256_DIGEST_SIZE</b><var><a name="index-SHA256_005fDIGEST_005fSIZE-5"></a></var><br>
 606 <blockquote><p>The size of a SHA256 digest, i.e. 32.
 607 </p></blockquote></div>
 608
 609 <div class="defun">
 610 &mdash; Constant: <b>SHA256_DATA_SIZE</b><var><a name="index-SHA256_005fDATA_005fSIZE-6"></a></var><br>
 611 <blockquote><p>The internal block size of SHA256. Useful for some special constructions,
 612 in particular HMAC-SHA256.
 613 </p></blockquote></div>
 614
 615 <div class="defun">
 616 &mdash; Function: void <b>sha256_init</b> (<var>struct sha256_ctx *ctx</var>)<var><a name="index-sha256_005finit-7"></a></var><br>
 617 <blockquote><p>Initialize the SHA256 state.
 618 </p></blockquote></div>
 619
 620 <div class="defun">
 621 &mdash; Function: void <b>sha256_update</b> (<var>struct sha256_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-sha256_005fupdate-8"></a></var><br>
 622 <blockquote><p>Hash some more data.
 623 </p></blockquote></div>
 624
 625 <div class="defun">
 626 &mdash; Function: void <b>sha256_digest</b> (<var>struct sha256_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-sha256_005fdigest-9"></a></var><br>
 627 <blockquote><p>Performs final processing and extracts the message digest, writing it
 628 to <var>digest</var>. <var>length</var> may be smaller than
 629 <code>SHA256_DIGEST_SIZE</code>, in which case only the first <var>length</var>
 630 octets of the digest are written.
 631
 632         <p>This function also resets the context in the same way as
 633 <code>sha256_init</code>.
 634 </p></blockquote></div>
 635
 636    <p>Earlier versions of nettle defined SHA256 in the header file
 637 <samp><span class="file">&lt;nettle/sha.h&gt;</span></samp>, which is now deprecated, but kept for
 638 compatibility.
 639
 640 <h5 class="subsubsection">6.1.1.2 <acronym>SHA224</acronym></h5>
 641
 642 <p>SHA224 is a variant of SHA256, with a different initial state, and with
 643 the output truncated to 224 bits, or 28 octets. Nettle defines SHA224 in
 644 <samp><span class="file">&lt;nettle/sha2.h&gt;</span></samp> (and in <samp><span class="file">&lt;nettle/sha.h&gt;</span></samp>, for backwards
 645 compatibility).
 646
 647 <div class="defun">
 648 &mdash; Context struct: <b>struct sha224_ctx</b><var><a name="index-struct-sha224_005fctx-10"></a></var><br>
 649         </div>
 650
 651 <div class="defun">
 652 &mdash; Constant: <b>SHA224_DIGEST_SIZE</b><var><a name="index-SHA224_005fDIGEST_005fSIZE-11"></a></var><br>
 653 <blockquote><p>The size of a SHA224 digest, i.e. 28.
 654 </p></blockquote></div>
 655
 656 <div class="defun">
 657 &mdash; Constant: <b>SHA224_DATA_SIZE</b><var><a name="index-SHA224_005fDATA_005fSIZE-12"></a></var><br>
 658 <blockquote><p>The internal block size of SHA224. Useful for some special constructions,
 659 in particular HMAC-SHA224.
 660 </p></blockquote></div>
 661
 662 <div class="defun">
 663 &mdash; Function: void <b>sha224_init</b> (<var>struct sha224_ctx *ctx</var>)<var><a name="index-sha224_005finit-13"></a></var><br>
 664 <blockquote><p>Initialize the SHA224 state.
 665 </p></blockquote></div>
 666
 667 <div class="defun">
 668 &mdash; Function: void <b>sha224_update</b> (<var>struct sha224_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-sha224_005fupdate-14"></a></var><br>
 669 <blockquote><p>Hash some more data.
 670 </p></blockquote></div>
 671
 672 <div class="defun">
 673 &mdash; Function: void <b>sha224_digest</b> (<var>struct sha224_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-sha224_005fdigest-15"></a></var><br>
 674 <blockquote><p>Performs final processing and extracts the message digest, writing it
 675 to <var>digest</var>. <var>length</var> may be smaller than
 676 <code>SHA224_DIGEST_SIZE</code>, in which case only the first <var>length</var>
 677 octets of the digest are written.
 678
 679         <p>This function also resets the context in the same way as
 680 <code>sha224_init</code>.
 681 </p></blockquote></div>
 682
 683 <h5 class="subsubsection">6.1.1.3 <acronym>SHA512</acronym></h5>
 684
 685 <p>SHA512 is a larger sibling to SHA256, with a very similar structure but
 686 with both the output and the internal variables of twice the size. The
 687 internal variables are 64 bits rather than 32, making it significantly
 688 slower on 32-bit computers. It outputs hash values of 512 bits, or 64
 689 octets. Nettle defines SHA512 in <samp><span class="file">&lt;nettle/sha2.h&gt;</span></samp> (and in
 690 <samp><span class="file">&lt;nettle/sha.h&gt;</span></samp>, for backwards compatibility).
 691
 692 <div class="defun">
 693 &mdash; Context struct: <b>struct sha512_ctx</b><var><a name="index-struct-sha512_005fctx-16"></a></var><br>
 694         </div>
 695
 696 <div class="defun">
 697 &mdash; Constant: <b>SHA512_DIGEST_SIZE</b><var><a name="index-SHA512_005fDIGEST_005fSIZE-17"></a></var><br>
 698 <blockquote><p>The size of a SHA512 digest, i.e. 64.
 699 </p></blockquote></div>
 700
 701 <div class="defun">
 702 &mdash; Constant: <b>SHA512_DATA_SIZE</b><var><a name="index-SHA512_005fDATA_005fSIZE-18"></a></var><br>
 703 <blockquote><p>The internal block size of SHA512. Useful for some special constructions,
 704 in particular HMAC-SHA512.
 705 </p></blockquote></div>
 706
 707 <div class="defun">
 708 &mdash; Function: void <b>sha512_init</b> (<var>struct sha512_ctx *ctx</var>)<var><a name="index-sha512_005finit-19"></a></var><br>
 709 <blockquote><p>Initialize the SHA512 state.
 710 </p></blockquote></div>
 711
 712 <div class="defun">
 713 &mdash; Function: void <b>sha512_update</b> (<var>struct sha512_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-sha512_005fupdate-20"></a></var><br>
 714 <blockquote><p>Hash some more data.
 715 </p></blockquote></div>
 716
 717 <div class="defun">
 718 &mdash; Function: void <b>sha512_digest</b> (<var>struct sha512_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-sha512_005fdigest-21"></a></var><br>
 719 <blockquote><p>Performs final processing and extracts the message digest, writing it
 720 to <var>digest</var>. <var>length</var> may be smaller than
 721 <code>SHA512_DIGEST_SIZE</code>, in which case only the first <var>length</var>
 722 octets of the digest are written.
 723
 724         <p>This function also resets the context in the same way as
 725 <code>sha512_init</code>.
 726 </p></blockquote></div>
 727
 728 <h5 class="subsubsection">6.1.1.4 <acronym>SHA384</acronym></h5>
 729
 730 <p>SHA384 is a variant of SHA512, with a different initial state, and with
 731 the output truncated to 384 bits, or 48 octets. Nettle defines SHA384 in
 732 <samp><span class="file">&lt;nettle/sha2.h&gt;</span></samp> (and in <samp><span class="file">&lt;nettle/sha.h&gt;</span></samp>, for backwards
 733 compatibility).
 734
 735 <div class="defun">
 736 &mdash; Context struct: <b>struct sha384_ctx</b><var><a name="index-struct-sha384_005fctx-22"></a></var><br>
 737         </div>
 738
 739 <div class="defun">
 740 &mdash; Constant: <b>SHA384_DIGEST_SIZE</b><var><a name="index-SHA384_005fDIGEST_005fSIZE-23"></a></var><br>
 741 <blockquote><p>The size of a SHA384 digest, i.e. 48.
 742 </p></blockquote></div>
 743
 744 <div class="defun">
 745 &mdash; Constant: <b>SHA384_DATA_SIZE</b><var><a name="index-SHA384_005fDATA_005fSIZE-24"></a></var><br>
 746 <blockquote><p>The internal block size of SHA384. Useful for some special constructions,
 747 in particular HMAC-SHA384.
 748 </p></blockquote></div>
 749
 750 <div class="defun">
 751 &mdash; Function: void <b>sha384_init</b> (<var>struct sha384_ctx *ctx</var>)<var><a name="index-sha384_005finit-25"></a></var><br>
 752 <blockquote><p>Initialize the SHA384 state.
 753 </p></blockquote></div>
 754
 755 <div class="defun">
 756 &mdash; Function: void <b>sha384_update</b> (<var>struct sha384_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-sha384_005fupdate-26"></a></var><br>
 757 <blockquote><p>Hash some more data.
 758 </p></blockquote></div>
 759
 760 <div class="defun">
 761 &mdash; Function: void <b>sha384_digest</b> (<var>struct sha384_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-sha384_005fdigest-27"></a></var><br>
 762 <blockquote><p>Performs final processing and extracts the message digest, writing it
 763 to <var>digest</var>. <var>length</var> may be smaller than
 764 <code>SHA384_DIGEST_SIZE</code>, in which case only the first <var>length</var>
 765 octets of the digest are written.
 766
 767         <p>This function also resets the context in the same way as
 768 <code>sha384_init</code>.
 769 </p></blockquote></div>
 770
 771 <h5 class="subsubsection">6.1.1.5 <acronym>SHA3-224</acronym></h5>
 772
 773 <p>The SHA3 hash functions were specified by NIST in response to weaknesses
 774 in SHA1, and doubts about SHA2 hash functions which structurally are
 775 very similar to SHA1. The standard is a result of a competition, where
 776 the winner, also known as Keccak, was designed by Guido Bertoni, Joan
 777 Daemen, Michaël Peeters and Gilles Van Assche. It is structurally very
 778 different from all widely used earlier hash functions. Like SHA2, there
 779 are several variants, with output sizes of 224, 256, 384 and 512 bits
 780 (28, 32, 48 and 64 octets, respectively).
 781
 782    <p>Nettle defines SHA3-224 in <samp><span class="file">&lt;nettle/sha3.h&gt;</span></samp>.
 783
 784 <div class="defun">
 785 &mdash; Context struct: <b>struct sha3_224_ctx</b><var><a name="index-struct-sha3_005f224_005fctx-28"></a></var><br>
 786         </div>
 787
 788 <div class="defun">
 789 &mdash; Constant: <b>SHA3_224_DIGEST_SIZE</b><var><a name="index-SHA3_005f224_005fDIGEST_005fSIZE-29"></a></var><br>
 790 <blockquote><p>The size of a SHA3_224 digest, i.e., 28.
 791 </p></blockquote></div>
 792
 793 <div class="defun">
 794 &mdash; Constant: <b>SHA3_224_DATA_SIZE</b><var><a name="index-SHA3_005f224_005fDATA_005fSIZE-30"></a></var><br>
 795 <blockquote><p>The internal block size of SHA3_224.
 796 </p></blockquote></div>
 797
 798 <div class="defun">
 799 &mdash; Function: void <b>sha3_224_init</b> (<var>struct sha3_224_ctx *ctx</var>)<var><a name="index-sha3_005f224_005finit-31"></a></var><br>
 800 <blockquote><p>Initialize the SHA3-224 state.
 801 </p></blockquote></div>
 802
 803 <div class="defun">
 804 &mdash; Function: void <b>sha3_224_update</b> (<var>struct sha3_224_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-sha3_005f224_005fupdate-32"></a></var><br>
 805 <blockquote><p>Hash some more data.
 806 </p></blockquote></div>
 807
 808 <div class="defun">
 809 &mdash; Function: void <b>sha3_224_digest</b> (<var>struct sha3_224_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-sha3_005f224_005fdigest-33"></a></var><br>
 810 <blockquote><p>Performs final processing and extracts the message digest, writing it
 811 to <var>digest</var>. <var>length</var> may be smaller than
 812 <code>SHA3_224_DIGEST_SIZE</code>, in which case only the first <var>length</var>
 813 octets of the digest are written.
 814
 815         <p>This function also resets the context.
 816 </p></blockquote></div>
 817
 818 <h5 class="subsubsection">6.1.1.6 <acronym>SHA3-256</acronym></h5>
 819
 820 <p>This is SHA3 with 256-bit output size, and possibly the most useful
 821 of the SHA3 hash functions.
 822
 823    <p>Nettle defines SHA3-256 in <samp><span class="file">&lt;nettle/sha3.h&gt;</span></samp>.
 824
 825 <div class="defun">
 826 &mdash; Context struct: <b>struct sha3_256_ctx</b><var><a name="index-struct-sha3_005f256_005fctx-34"></a></var><br>
 827         </div>
 828
 829 <div class="defun">
 830 &mdash; Constant: <b>SHA3_256_DIGEST_SIZE</b><var><a name="index-SHA3_005f256_005fDIGEST_005fSIZE-35"></a></var><br>
 831 <blockquote><p>The size of a SHA3_256 digest, i.e., 32.
 832 </p></blockquote></div>
 833
 834 <div class="defun">
 835 &mdash; Constant: <b>SHA3_256_DATA_SIZE</b><var><a name="index-SHA3_005f256_005fDATA_005fSIZE-36"></a></var><br>
 836 <blockquote><p>The internal block size of SHA3_256.
 837 </p></blockquote></div>
 838
 839 <div class="defun">
 840 &mdash; Function: void <b>sha3_256_init</b> (<var>struct sha3_256_ctx *ctx</var>)<var><a name="index-sha3_005f256_005finit-37"></a></var><br>
 841 <blockquote><p>Initialize the SHA3-256 state.
 842 </p></blockquote></div>
 843
 844 <div class="defun">
 845 &mdash; Function: void <b>sha3_256_update</b> (<var>struct sha3_256_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-sha3_005f256_005fupdate-38"></a></var><br>
 846 <blockquote><p>Hash some more data.
 847 </p></blockquote></div>
 848
 849 <div class="defun">
 850 &mdash; Function: void <b>sha3_256_digest</b> (<var>struct sha3_256_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-sha3_005f256_005fdigest-39"></a></var><br>
 851 <blockquote><p>Performs final processing and extracts the message digest, writing it
 852 to <var>digest</var>. <var>length</var> may be smaller than
 853 <code>SHA3_256_DIGEST_SIZE</code>, in which case only the first <var>length</var>
 854 octets of the digest are written.
 855
 856         <p>This function also resets the context.
 857 </p></blockquote></div>
 858
 859 <h5 class="subsubsection">6.1.1.7 <acronym>SHA3-384</acronym></h5>
 860
 861 <p>This is SHA3 with 384-bit output size.
 862
 863    <p>Nettle defines SHA3-384 in <samp><span class="file">&lt;nettle/sha3.h&gt;</span></samp>.
 864
 865 <div class="defun">
 866 &mdash; Context struct: <b>struct sha3_384_ctx</b><var><a name="index-struct-sha3_005f384_005fctx-40"></a></var><br>
 867         </div>
 868
 869 <div class="defun">
 870 &mdash; Constant: <b>SHA3_384_DIGEST_SIZE</b><var><a name="index-SHA3_005f384_005fDIGEST_005fSIZE-41"></a></var><br>
 871 <blockquote><p>The size of a SHA3_384 digest, i.e., 48.
 872 </p></blockquote></div>
 873
 874 <div class="defun">
 875 &mdash; Constant: <b>SHA3_384_DATA_SIZE</b><var><a name="index-SHA3_005f384_005fDATA_005fSIZE-42"></a></var><br>
 876 <blockquote><p>The internal block size of SHA3_384.
 877 </p></blockquote></div>
 878
 879 <div class="defun">
 880 &mdash; Function: void <b>sha3_384_init</b> (<var>struct sha3_384_ctx *ctx</var>)<var><a name="index-sha3_005f384_005finit-43"></a></var><br>
 881 <blockquote><p>Initialize the SHA3-384 state.
 882 </p></blockquote></div>
 883
 884 <div class="defun">
 885 &mdash; Function: void <b>sha3_384_update</b> (<var>struct sha3_384_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-sha3_005f384_005fupdate-44"></a></var><br>
 886 <blockquote><p>Hash some more data.
 887 </p></blockquote></div>
 888
 889 <div class="defun">
 890 &mdash; Function: void <b>sha3_384_digest</b> (<var>struct sha3_384_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-sha3_005f384_005fdigest-45"></a></var><br>
 891 <blockquote><p>Performs final processing and extracts the message digest, writing it
 892 to <var>digest</var>. <var>length</var> may be smaller than
 893 <code>SHA3_384_DIGEST_SIZE</code>, in which case only the first <var>length</var>
 894 octets of the digest are written.
 895
 896         <p>This function also resets the context.
 897 </p></blockquote></div>
 898
 899 <h5 class="subsubsection">6.1.1.8 <acronym>SHA3-512</acronym></h5>
 900
 901 <p>This is SHA3 with 512-bit output size.
 902
 903    <p>Nettle defines SHA3-512 in <samp><span class="file">&lt;nettle/sha3.h&gt;</span></samp>.
 904
 905 <div class="defun">
 906 &mdash; Context struct: <b>struct sha3_512_ctx</b><var><a name="index-struct-sha3_005f512_005fctx-46"></a></var><br>
 907         </div>
 908
 909 <div class="defun">
 910 &mdash; Constant: <b>SHA3_512_DIGEST_SIZE</b><var><a name="index-SHA3_005f512_005fDIGEST_005fSIZE-47"></a></var><br>
 911 <blockquote><p>The size of a SHA3_512 digest, i.e. 64.
 912 </p></blockquote></div>
 913
 914 <div class="defun">
 915 &mdash; Constant: <b>SHA3_512_DATA_SIZE</b><var><a name="index-SHA3_005f512_005fDATA_005fSIZE-48"></a></var><br>
 916 <blockquote><p>The internal block size of SHA3_512.
 917 </p></blockquote></div>
 918
 919 <div class="defun">
 920 &mdash; Function: void <b>sha3_512_init</b> (<var>struct sha3_512_ctx *ctx</var>)<var><a name="index-sha3_005f512_005finit-49"></a></var><br>
 921 <blockquote><p>Initialize the SHA3-512 state.
 922 </p></blockquote></div>
 923
 924 <div class="defun">
 925 &mdash; Function: void <b>sha3_512_update</b> (<var>struct sha3_512_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-sha3_005f512_005fupdate-50"></a></var><br>
 926 <blockquote><p>Hash some more data.
 927 </p></blockquote></div>
 928
 929 <div class="defun">
 930 &mdash; Function: void <b>sha3_512_digest</b> (<var>struct sha3_512_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-sha3_005f512_005fdigest-51"></a></var><br>
 931 <blockquote><p>Performs final processing and extracts the message digest, writing it
 932 to <var>digest</var>. <var>length</var> may be smaller than
 933 <code>SHA3_512_DIGEST_SIZE</code>, in which case only the first <var>length</var>
 934 octets of the digest are written.
 935
 936         <p>This function also resets the context.
 937 </p></blockquote></div>
 938
 939 <div class="node">
 940 <a name="Legacy-hash-functions"></a>
 941 <p><hr>
 942 Next:&nbsp;<a rel="next" accesskey="n" href="#nettle_005fhash-abstraction">nettle_hash abstraction</a>,
 943 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Recommended-hash-functions">Recommended hash functions</a>,
 944 Up:&nbsp;<a rel="up" accesskey="u" href="#Hash-functions">Hash functions</a>
 945
 946 </div>
 947
 948 <!-- node-name,  next,  previous,  up -->
 949 <h4 class="subsection">6.1.2 Legacy hash functions</h4>
 950
 951 <p>The hash functions in this section all have some known weaknesses, and
 952 should be avoided for new applications. These hash functions are mainly
 953 useful for compatibility with old applications and protocols. Some are
 954 still considered safe as building blocks for particular constructions,
 955 e.g., there seems to be no known attacks against HMAC-SHA1 or even
 956 HMAC-MD5. In some important cases, use of a &ldquo;legacy&rdquo; hash function
 957 does not in itself make the application insecure; if a known weakness is
 958 relevant depends on how the hash function is used, and on the threat
 959 model.
 960
 961 <h5 class="subsubsection">6.1.2.1 <acronym>MD5</acronym></h5>
 962
 963 <p>MD5 is a message digest function constructed by Ronald Rivest, and
 964 described in <cite>RFC 1321</cite>. It outputs message digests of 128 bits, or
 965 16 octets. Nettle defines MD5 in <samp><span class="file">&lt;nettle/md5.h&gt;</span></samp>.
 966
 967 <div class="defun">
 968 &mdash; Context struct: <b>struct md5_ctx</b><var><a name="index-struct-md5_005fctx-52"></a></var><br>
 969         </div>
 970
 971 <div class="defun">
 972 &mdash; Constant: <b>MD5_DIGEST_SIZE</b><var><a name="index-MD5_005fDIGEST_005fSIZE-53"></a></var><br>
 973 <blockquote><p>The size of an MD5 digest, i.e. 16.
 974 </p></blockquote></div>
 975
 976 <div class="defun">
 977 &mdash; Constant: <b>MD5_DATA_SIZE</b><var><a name="index-MD5_005fDATA_005fSIZE-54"></a></var><br>
 978 <blockquote><p>The internal block size of MD5. Useful for some special constructions,
 979 in particular HMAC-MD5.
 980 </p></blockquote></div>
 981
 982 <div class="defun">
 983 &mdash; Function: void <b>md5_init</b> (<var>struct md5_ctx *ctx</var>)<var><a name="index-md5_005finit-55"></a></var><br>
 984 <blockquote><p>Initialize the MD5 state.
 985 </p></blockquote></div>
 986
 987 <div class="defun">
 988 &mdash; Function: void <b>md5_update</b> (<var>struct md5_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-md5_005fupdate-56"></a></var><br>
 989 <blockquote><p>Hash some more data.
 990 </p></blockquote></div>
 991
 992 <div class="defun">
 993 &mdash; Function: void <b>md5_digest</b> (<var>struct md5_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-md5_005fdigest-57"></a></var><br>
 994 <blockquote><p>Performs final processing and extracts the message digest, writing it
 995 to <var>digest</var>. <var>length</var> may be smaller than
 996 <code>MD5_DIGEST_SIZE</code>, in which case only the first <var>length</var>
 997 octets of the digest are written.
 998
 999         <p>This function also resets the context in the same way as
1000 <code>md5_init</code>.
1001 </p></blockquote></div>
1002
1003    <p>The normal way to use MD5 is to call the functions in order: First
1004 <code>md5_init</code>, then <code>md5_update</code> zero or more times, and finally
1005 <code>md5_digest</code>. After <code>md5_digest</code>, the context is reset to
1006 its initial state, so you can start over calling <code>md5_update</code> to
1007 hash new data.
1008
1009    <p>To start over, you can call <code>md5_init</code> at any time.
1010
1011 <h5 class="subsubsection">6.1.2.2 <acronym>MD2</acronym></h5>
1012
1013 <p>MD2 is another hash function of Ronald Rivest's, described in
1014 <cite>RFC 1319</cite>. It outputs message digests of 128 bits, or 16 octets.
1015 Nettle defines MD2 in <samp><span class="file">&lt;nettle/md2.h&gt;</span></samp>.
1016
1017 <div class="defun">
1018 &mdash; Context struct: <b>struct md2_ctx</b><var><a name="index-struct-md2_005fctx-58"></a></var><br>
1019         </div>
1020
1021 <div class="defun">
1022 &mdash; Constant: <b>MD2_DIGEST_SIZE</b><var><a name="index-MD2_005fDIGEST_005fSIZE-59"></a></var><br>
1023 <blockquote><p>The size of an MD2 digest, i.e. 16.
1024 </p></blockquote></div>
1025
1026 <div class="defun">
1027 &mdash; Constant: <b>MD2_DATA_SIZE</b><var><a name="index-MD2_005fDATA_005fSIZE-60"></a></var><br>
1028 <blockquote><p>The internal block size of MD2.
1029 </p></blockquote></div>
1030
1031 <div class="defun">
1032 &mdash; Function: void <b>md2_init</b> (<var>struct md2_ctx *ctx</var>)<var><a name="index-md2_005finit-61"></a></var><br>
1033 <blockquote><p>Initialize the MD2 state.
1034 </p></blockquote></div>
1035
1036 <div class="defun">
1037 &mdash; Function: void <b>md2_update</b> (<var>struct md2_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-md2_005fupdate-62"></a></var><br>
1038 <blockquote><p>Hash some more data.
1039 </p></blockquote></div>
1040
1041 <div class="defun">
1042 &mdash; Function: void <b>md2_digest</b> (<var>struct md2_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-md2_005fdigest-63"></a></var><br>
1043 <blockquote><p>Performs final processing and extracts the message digest, writing it
1044 to <var>digest</var>. <var>length</var> may be smaller than
1045 <code>MD2_DIGEST_SIZE</code>, in which case only the first <var>length</var>
1046 octets of the digest are written.
1047
1048         <p>This function also resets the context in the same way as
1049 <code>md2_init</code>.
1050 </p></blockquote></div>
1051
1052 <h5 class="subsubsection">6.1.2.3 <acronym>MD4</acronym></h5>
1053
1054 <p>MD4 is a predecessor of MD5, described in <cite>RFC 1320</cite>. Like MD5, it
1055 is constructed by Ronald Rivest. It outputs message digests of 128 bits,
1056 or 16 octets. Nettle defines MD4 in <samp><span class="file">&lt;nettle/md4.h&gt;</span></samp>. Use of MD4 is
1057 not recommended, but it is sometimes needed for compatibility with
1058 existing applications and protocols.
1059
1060 <div class="defun">
1061 &mdash; Context struct: <b>struct md4_ctx</b><var><a name="index-struct-md4_005fctx-64"></a></var><br>
1062         </div>
1063
1064 <div class="defun">
1065 &mdash; Constant: <b>MD4_DIGEST_SIZE</b><var><a name="index-MD4_005fDIGEST_005fSIZE-65"></a></var><br>
1066 <blockquote><p>The size of an MD4 digest, i.e. 16.
1067 </p></blockquote></div>
1068
1069 <div class="defun">
1070 &mdash; Constant: <b>MD4_DATA_SIZE</b><var><a name="index-MD4_005fDATA_005fSIZE-66"></a></var><br>
1071 <blockquote><p>The internal block size of MD4.
1072 </p></blockquote></div>
1073
1074 <div class="defun">
1075 &mdash; Function: void <b>md4_init</b> (<var>struct md4_ctx *ctx</var>)<var><a name="index-md4_005finit-67"></a></var><br>
1076 <blockquote><p>Initialize the MD4 state.
1077 </p></blockquote></div>
1078
1079 <div class="defun">
1080 &mdash; Function: void <b>md4_update</b> (<var>struct md4_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-md4_005fupdate-68"></a></var><br>
1081 <blockquote><p>Hash some more data.
1082 </p></blockquote></div>
1083
1084 <div class="defun">
1085 &mdash; Function: void <b>md4_digest</b> (<var>struct md4_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-md4_005fdigest-69"></a></var><br>
1086 <blockquote><p>Performs final processing and extracts the message digest, writing it
1087 to <var>digest</var>. <var>length</var> may be smaller than
1088 <code>MD4_DIGEST_SIZE</code>, in which case only the first <var>length</var>
1089 octets of the digest are written.
1090
1091         <p>This function also resets the context in the same way as
1092 <code>md4_init</code>.
1093 </p></blockquote></div>
1094
1095 <h5 class="subsubsection">6.1.2.4 <acronym>RIPEMD160</acronym></h5>
1096
1097 <p>RIPEMD160 is a hash function designed by Hans Dobbertin, Antoon
1098 Bosselaers, and Bart Preneel, as a strengthened version of RIPEMD
1099 (which, like MD4 and MD5, fails the collision-resistance requirement).
1100 It produces message digests of 160 bits, or 20 octets. Nettle defined
1101 RIPEMD160 in <samp><span class="file">nettle/ripemd160.h</span></samp>.
1102
1103 <div class="defun">
1104 &mdash; Context struct: <b>struct ripemd160_ctx</b><var><a name="index-struct-ripemd160_005fctx-70"></a></var><br>
1105         </div>
1106
1107 <div class="defun">
1108 &mdash; Constant: <b>RIPEMD160_DIGEST_SIZE</b><var><a name="index-RIPEMD160_005fDIGEST_005fSIZE-71"></a></var><br>
1109 <blockquote><p>The size of a RIPEMD160 digest, i.e. 20.
1110 </p></blockquote></div>
1111
1112 <div class="defun">
1113 &mdash; Constant: <b>RIPEMD160_DATA_SIZE</b><var><a name="index-RIPEMD160_005fDATA_005fSIZE-72"></a></var><br>
1114 <blockquote><p>The internal block size of RIPEMD160.
1115 </p></blockquote></div>
1116
1117 <div class="defun">
1118 &mdash; Function: void <b>ripemd160_init</b> (<var>struct ripemd160_ctx *ctx</var>)<var><a name="index-ripemd160_005finit-73"></a></var><br>
1119 <blockquote><p>Initialize the RIPEMD160 state.
1120 </p></blockquote></div>
1121
1122 <div class="defun">
1123 &mdash; Function: void <b>ripemd160_update</b> (<var>struct ripemd160_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-ripemd160_005fupdate-74"></a></var><br>
1124 <blockquote><p>Hash some more data.
1125 </p></blockquote></div>
1126
1127 <div class="defun">
1128 &mdash; Function: void <b>ripemd160_digest</b> (<var>struct ripemd160_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-ripemd160_005fdigest-75"></a></var><br>
1129 <blockquote><p>Performs final processing and extracts the message digest, writing it
1130 to <var>digest</var>. <var>length</var> may be smaller than
1131 <code>RIPEMD160_DIGEST_SIZE</code>, in which case only the first <var>length</var>
1132 octets of the digest are written.
1133
1134         <p>This function also resets the context in the same way as
1135 <code>ripemd160_init</code>.
1136 </p></blockquote></div>
1137
1138 <h5 class="subsubsection">6.1.2.5 <acronym>SHA1</acronym></h5>
1139
1140 <p>SHA1 is a hash function specified by <dfn>NIST</dfn> (The U.S. National
1141 Institute for Standards and Technology). It outputs hash values of 160
1142 bits, or 20 octets. Nettle defines SHA1 in <samp><span class="file">&lt;nettle/sha1.h&gt;</span></samp> (and
1143 in <samp><span class="file">&lt;nettle/sha.h&gt;</span></samp>, for backwards compatibility).
1144
1145 <div class="defun">
1146 &mdash; Context struct: <b>struct sha1_ctx</b><var><a name="index-struct-sha1_005fctx-76"></a></var><br>
1147         </div>
1148
1149 <div class="defun">
1150 &mdash; Constant: <b>SHA1_DIGEST_SIZE</b><var><a name="index-SHA1_005fDIGEST_005fSIZE-77"></a></var><br>
1151 <blockquote><p>The size of a SHA1 digest, i.e. 20.
1152 </p></blockquote></div>
1153
1154 <div class="defun">
1155 &mdash; Constant: <b>SHA1_DATA_SIZE</b><var><a name="index-SHA1_005fDATA_005fSIZE-78"></a></var><br>
1156 <blockquote><p>The internal block size of SHA1. Useful for some special constructions,
1157 in particular HMAC-SHA1.
1158 </p></blockquote></div>
1159
1160 <div class="defun">
1161 &mdash; Function: void <b>sha1_init</b> (<var>struct sha1_ctx *ctx</var>)<var><a name="index-sha1_005finit-79"></a></var><br>
1162 <blockquote><p>Initialize the SHA1 state.
1163 </p></blockquote></div>
1164
1165 <div class="defun">
1166 &mdash; Function: void <b>sha1_update</b> (<var>struct sha1_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-sha1_005fupdate-80"></a></var><br>
1167 <blockquote><p>Hash some more data.
1168 </p></blockquote></div>
1169
1170 <div class="defun">
1171 &mdash; Function: void <b>sha1_digest</b> (<var>struct sha1_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-sha1_005fdigest-81"></a></var><br>
1172 <blockquote><p>Performs final processing and extracts the message digest, writing it
1173 to <var>digest</var>. <var>length</var> may be smaller than
1174 <code>SHA1_DIGEST_SIZE</code>, in which case only the first <var>length</var>
1175 octets of the digest are written.
1176
1177         <p>This function also resets the context in the same way as
1178 <code>sha1_init</code>.
1179 </p></blockquote></div>
1180
1181 <h5 class="subsubsection">6.1.2.6 <acronym>GOSTHASH94</acronym></h5>
1182
1183 <p>The GOST94 or GOST R 34.11-94 hash algorithm is a Soviet-era algorithm
1184 used in Russian government standards (see <cite>RFC 4357</cite>).
1185 It outputs message digests of 256 bits, or 32 octets.
1186 Nettle defines GOSTHASH94 in <samp><span class="file">&lt;nettle/gosthash94.h&gt;</span></samp>.
1187
1188 <div class="defun">
1189 &mdash; Context struct: <b>struct gosthash94_ctx</b><var><a name="index-struct-gosthash94_005fctx-82"></a></var><br>
1190         </div>
1191
1192 <div class="defun">
1193 &mdash; Constant: <b>GOSTHASH94_DIGEST_SIZE</b><var><a name="index-GOSTHASH94_005fDIGEST_005fSIZE-83"></a></var><br>
1194 <blockquote><p>The size of a GOSTHASH94 digest, i.e. 32.
1195 </p></blockquote></div>
1196
1197 <div class="defun">
1198 &mdash; Constant: <b>GOSTHASH94_DATA_SIZE</b><var><a name="index-GOSTHASH94_005fDATA_005fSIZE-84"></a></var><br>
1199 <blockquote><p>The internal block size of GOSTHASH94, i.e., 32.
1200 </p></blockquote></div>
1201
1202 <div class="defun">
1203 &mdash; Function: void <b>gosthash94_init</b> (<var>struct gosthash94_ctx *ctx</var>)<var><a name="index-gosthash94_005finit-85"></a></var><br>
1204 <blockquote><p>Initialize the GOSTHASH94 state.
1205 </p></blockquote></div>
1206
1207 <div class="defun">
1208 &mdash; Function: void <b>gosthash94_update</b> (<var>struct gosthash94_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-gosthash94_005fupdate-86"></a></var><br>
1209 <blockquote><p>Hash some more data.
1210 </p></blockquote></div>
1211
1212 <div class="defun">
1213 &mdash; Function: void <b>gosthash94_digest</b> (<var>struct gosthash94_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-gosthash94_005fdigest-87"></a></var><br>
1214 <blockquote><p>Performs final processing and extracts the message digest, writing it
1215 to <var>digest</var>. <var>length</var> may be smaller than
1216 <code>GOSTHASH94_DIGEST_SIZE</code>, in which case only the first <var>length</var>
1217 octets of the digest are written.
1218
1219         <p>This function also resets the context in the same way as
1220 <code>gosthash94_init</code>.
1221 </p></blockquote></div>
1222
1223 <div class="node">
1224 <a name="nettle_hash-abstraction"></a>
1225 <a name="nettle_005fhash-abstraction"></a>
1226 <p><hr>
1227 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Legacy-hash-functions">Legacy hash functions</a>,
1228 Up:&nbsp;<a rel="up" accesskey="u" href="#Hash-functions">Hash functions</a>
1229
1230 </div>
1231
1232 <!-- node-name,  next,  previous,  up -->
1233 <h4 class="subsection">6.1.3 The nettle_hash abstraction</h4>
1234
1235 <p>Nettle includes a struct including information about the supported hash
1236 functions. It is defined in <samp><span class="file">&lt;nettle/nettle-meta.h&gt;</span></samp>, and is used
1237 by Nettle's implementation of <acronym>HMAC</acronym> (see <a href="#Keyed-hash-functions">Keyed hash functions</a>).
1238
1239 <div class="defun">
1240 &mdash; Meta struct: <code>struct nettle_hash</code><var> name context_size digest_size block_size init update digest<a name="index-g_t_0040code_007bstruct-nettle_005fhash_007d-88"></a></var><br>
1241 <blockquote><p>The last three attributes are function pointers, of types
1242 <code>nettle_hash_init_func</code>, <code>nettle_hash_update_func</code>, and
1243 <code>nettle_hash_digest_func</code>. The first argument to these functions is
1244 <code>void *</code> pointer to a context struct, which is of size
1245 <code>context_size</code>.
1246 </p></blockquote></div>
1247
1248 <div class="defun">
1249 &mdash; Constant Struct: struct nettle_hash <b>nettle_md2</b><var><a name="index-nettle_005fmd2-89"></a></var><br>
1250 &mdash; Constant Struct: struct nettle_hash <b>nettle_md4</b><var><a name="index-nettle_005fmd4-90"></a></var><br>
1251 &mdash; Constant Struct: struct nettle_hash <b>nettle_md5</b><var><a name="index-nettle_005fmd5-91"></a></var><br>
1252 &mdash; Constant Struct: struct nettle_hash <b>nettle_ripemd160</b><var><a name="index-nettle_005fripemd160-92"></a></var><br>
1253 &mdash; Constant Struct: struct nettle_hash <b>nettle_sha1</b><var><a name="index-nettle_005fsha1-93"></a></var><br>
1254 &mdash; Constant Struct: struct nettle_hash <b>nettle_sha224</b><var><a name="index-nettle_005fsha224-94"></a></var><br>
1255 &mdash; Constant Struct: struct nettle_hash <b>nettle_sha256</b><var><a name="index-nettle_005fsha256-95"></a></var><br>
1256 &mdash; Constant Struct: struct nettle_hash <b>nettle_sha384</b><var><a name="index-nettle_005fsha384-96"></a></var><br>
1257 &mdash; Constant Struct: struct nettle_hash <b>nettle_sha512</b><var><a name="index-nettle_005fsha512-97"></a></var><br>
1258 &mdash; Constant Struct: struct nettle_hash <b>nettle_sha3_256</b><var><a name="index-nettle_005fsha3_005f256-98"></a></var><br>
1259 &mdash; Constant Struct: struct nettle_hash <b>nettle_gosthash94</b><var><a name="index-nettle_005fgosthash94-99"></a></var><br>
1260 <blockquote><p>These are all the hash functions that Nettle implements.
1261 </p></blockquote></div>
1262
1263    <p>Nettle also exports a list of all these hashes.
1264
1265 <div class="defun">
1266 &mdash; Constant Array: struct nettle_hash ** <b>nettle_hashes</b><var><a name="index-nettle_005fhashes-100"></a></var><br>
1267 <blockquote><p>This list can be used to dynamically enumerate or search the supported
1268 algorithms. NULL-terminated.
1269 </p></blockquote></div>
1270
1271 <div class="node">
1272 <a name="Cipher-functions"></a>
1273 <p><hr>
1274 Next:&nbsp;<a rel="next" accesskey="n" href="#Cipher-modes">Cipher modes</a>,
1275 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Hash-functions">Hash functions</a>,
1276 Up:&nbsp;<a rel="up" accesskey="u" href="#Reference">Reference</a>
1277
1278 </div>
1279
1280 <!-- node-name,  next,  previous,  up -->
1281 <h3 class="section">6.2 Cipher functions</h3>
1282
1283 <p><a name="index-Cipher-101"></a>
1284 A <dfn>cipher</dfn> is a function that takes a message or <dfn>plaintext</dfn>
1285 and a secret <dfn>key</dfn> and transforms it to a <dfn>ciphertext</dfn>. Given
1286 only the ciphertext, but not the key, it should be hard to find the
1287 plaintext. Given matching pairs of plaintext and ciphertext, it should
1288 be hard to find the key.
1289
1290    <p><a name="index-Block-Cipher-102"></a><a name="index-Stream-Cipher-103"></a>
1291 There are two main classes of ciphers: Block ciphers and stream ciphers.
1292
1293    <p>A block cipher can process data only in fixed size chunks, called
1294 <dfn>blocks</dfn>. Typical block sizes are 8 or 16 octets. To encrypt
1295 arbitrary messages, you usually have to pad it to an integral number of
1296 blocks, split it into blocks, and then process each block. The simplest
1297 way is to process one block at a time, independent of each other. That
1298 mode of operation is called <dfn>ECB</dfn>, Electronic Code Book mode.
1299 However, using <acronym>ECB</acronym> is usually a bad idea. For a start, plaintext blocks
1300 that are equal are transformed to ciphertext blocks that are equal; that
1301 leaks information about the plaintext. Usually you should apply the
1302 cipher is some &ldquo;feedback mode&rdquo;, <dfn>CBC</dfn> (Cipher Block Chaining) and
1303 <dfn>CTR</dfn> (Counter mode) being two of
1304 of the most popular. See See <a href="#Cipher-modes">Cipher modes</a>, for information on
1305 how to apply <acronym>CBC</acronym> and <acronym>CTR</acronym> with Nettle.
1306
1307    <p>A stream cipher can be used for messages of arbitrary length. A typical
1308 stream cipher is a keyed pseudo-random generator. To encrypt a plaintext
1309 message of <var>n</var> octets, you key the generator, generate <var>n</var>
1310 octets of pseudo-random data, and XOR it with the plaintext. To decrypt,
1311 regenerate the same stream using the key, XOR it to the ciphertext, and
1312 the plaintext is recovered.
1313
1314    <p><strong>Caution:</strong> The first rule for this kind of cipher is the
1315 same as for a One Time Pad: <em>never</em> ever use the same key twice.
1316
1317    <p>A common misconception is that encryption, by itself, implies
1318 authentication. Say that you and a friend share a secret key, and you
1319 receive an encrypted message. You apply the key, and get a plaintext
1320 message that makes sense to you. Can you then be sure that it really was
1321 your friend that wrote the message you're reading? The answer is no. For
1322 example, if you were using a block cipher in ECB mode, an attacker may
1323 pick up the message on its way, and reorder, delete or repeat some of
1324 the blocks. Even if the attacker can't decrypt the message, he can
1325 change it so that you are not reading the same message as your friend
1326 wrote. If you are using a block cipher in <acronym>CBC</acronym> mode rather than
1327 ECB, or are using a stream cipher, the possibilities for this sort of
1328 attack are different, but the attacker can still make predictable
1329 changes to the message.
1330
1331    <p>It is recommended to <em>always</em> use an authentication mechanism in
1332 addition to encrypting the messages. Popular choices are Message
1333 Authentication Codes like <acronym>HMAC-SHA1</acronym> (see <a href="#Keyed-hash-functions">Keyed hash functions</a>), or digital signatures like <acronym>RSA</acronym>.
1334
1335    <p>Some ciphers have so called &ldquo;weak keys&rdquo;, keys that results in
1336 undesirable structure after the key setup processing, and should be
1337 avoided. In Nettle, most key setup functions have no return value, but
1338 for ciphers with weak keys, the return value indicates whether or not
1339 the given key is weak. For good keys, key setup returns 1, and for weak
1340 keys, it returns 0. When possible, avoid algorithms that
1341 have weak keys. There are several good ciphers that don't have any weak
1342 keys.
1343
1344    <p>To encrypt a message, you first initialize a cipher context for
1345 encryption or decryption with a particular key. You then use the context
1346 to process plaintext or ciphertext messages. The initialization is known
1347 as <dfn>key setup</dfn>. With Nettle, it is recommended to use each
1348 context struct for only one direction, even if some of the ciphers use a
1349 single key setup function that can be used for both encryption and
1350 decryption.
1351
1352 <h4 class="subsection">6.2.1 AES</h4>
1353
1354 <p>AES is a block cipher, specified by NIST as a replacement for
1355 the older DES standard. The standard is the result of a competition
1356 between cipher designers. The winning design, also known as RIJNDAEL,
1357 was constructed by Joan Daemen and Vincent Rijnmen.
1358
1359    <p>Like all the AES candidates, the winning design uses a block size of 128
1360 bits, or 16 octets, and variable key-size, 128, 192 and 256 bits (16, 24
1361 and 32 octets) being the allowed key sizes. It does not have any weak
1362 keys. Nettle defines AES in <samp><span class="file">&lt;nettle/aes.h&gt;</span></samp>.
1363
1364 <div class="defun">
1365 &mdash; Context struct: <b>struct aes_ctx</b><var><a name="index-struct-aes_005fctx-104"></a></var><br>
1366         </div>
1367
1368 <div class="defun">
1369 &mdash; Constant: <b>AES_BLOCK_SIZE</b><var><a name="index-AES_005fBLOCK_005fSIZE-105"></a></var><br>
1370 <blockquote><p>The AES block-size, 16.
1371 </p></blockquote></div>
1372
1373 <div class="defun">
1374 &mdash; Constant: <b>AES_MIN_KEY_SIZE</b><var><a name="index-AES_005fMIN_005fKEY_005fSIZE-106"></a></var><br>
1375         </div>
1376
1377 <div class="defun">
1378 &mdash; Constant: <b>AES_MAX_KEY_SIZE</b><var><a name="index-AES_005fMAX_005fKEY_005fSIZE-107"></a></var><br>
1379         </div>
1380
1381 <div class="defun">
1382 &mdash; Constant: <b>AES_KEY_SIZE</b><var><a name="index-AES_005fKEY_005fSIZE-108"></a></var><br>
1383 <blockquote><p>Default AES key size, 32.
1384 </p></blockquote></div>
1385
1386 <div class="defun">
1387 &mdash; Function: void <b>aes_set_encrypt_key</b> (<var>struct aes_ctx *ctx, unsigned length, const uint8_t *key</var>)<var><a name="index-aes_005fset_005fencrypt_005fkey-109"></a></var><br>
1388 &mdash; Function: void <b>aes_set_decrypt_key</b> (<var>struct aes_ctx *ctx, unsigned length, const uint8_t *key</var>)<var><a name="index-aes_005fset_005fdecrypt_005fkey-110"></a></var><br>
1389 <blockquote><p>Initialize the cipher, for encryption or decryption, respectively.
1390 </p></blockquote></div>
1391
1392 <div class="defun">
1393 &mdash; Function: void <b>aes_invert_key</b> (<var>struct aes_ctx *dst, const struct aes_ctx *src</var>)<var><a name="index-aes_005finvert_005fkey-111"></a></var><br>
1394 <blockquote><p>Given a context <var>src</var> initialized for encryption, initializes the
1395 context struct <var>dst</var> for decryption, using the same key. If the same
1396 context struct is passed for both <code>src</code> and <code>dst</code>, it is
1397 converted in place. Calling <code>aes_set_encrypt_key</code> and
1398 <code>aes_invert_key</code> is more efficient than calling
1399 <code>aes_set_encrypt_key</code> and <code>aes_set_decrypt_key</code>. This function
1400 is mainly useful for applications which needs to both encrypt and
1401 decrypt using the <em>same</em> key.
1402 </p></blockquote></div>
1403
1404 <div class="defun">
1405 &mdash; Function: void <b>aes_encrypt</b> (<var>struct aes_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-aes_005fencrypt-112"></a></var><br>
1406 <blockquote><p>Encryption function. <var>length</var> must be an integral multiple of the
1407 block size. If it is more than one block, the data is processed in ECB
1408 mode. <code>src</code> and <code>dst</code> may be equal, but they must not overlap
1409 in any other way.
1410 </p></blockquote></div>
1411
1412 <div class="defun">
1413 &mdash; Function: void <b>aes_decrypt</b> (<var>struct aes_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-aes_005fdecrypt-113"></a></var><br>
1414 <blockquote><p>Analogous to <code>aes_encrypt</code>
1415 </p></blockquote></div>
1416
1417 <h4 class="subsection">6.2.2 ARCFOUR</h4>
1418
1419 <p>ARCFOUR is a stream cipher, also known under the trade marked name RC4,
1420 and it is one of the fastest ciphers around. A problem is that the key
1421 setup of ARCFOUR is quite weak, you should never use keys with
1422 structure, keys that are ordinary passwords, or sequences of keys like
1423 &ldquo;secret:1&rdquo;, &ldquo;secret:2&rdquo;, <small class="enddots">...</small>. If you have keys that don't look
1424 like random bit strings, and you want to use ARCFOUR, always hash the
1425 key before feeding it to ARCFOUR. Furthermore, the initial bytes of the
1426 generated key stream leak information about the key; for this reason, it
1427 is recommended to discard the first 512 bytes of the key stream.
1428
1429 <pre class="example">     /* A more robust key setup function for ARCFOUR */
1430      void
1431      arcfour_set_key_hashed(struct arcfour_ctx *ctx,
1432                             unsigned length, const uint8_t *key)
1433      {
1434        struct sha256_ctx hash;
1435        uint8_t digest[SHA256_DIGEST_SIZE];
1436        uint8_t buffer[0x200];
1437
1438        sha256_init(&amp;hash);
1439        sha256_update(&amp;hash, length, key);
1440        sha256_digest(&amp;hash, SHA256_DIGEST_SIZE, digest);
1441
1442        arcfour_set_key(ctx, SHA256_DIGEST_SIZE, digest);
1443        arcfour_crypt(ctx, sizeof(buffer), buffer, buffer);
1444      }
1445 </pre>
1446    <p>Nettle defines ARCFOUR in <samp><span class="file">&lt;nettle/arcfour.h&gt;</span></samp>.
1447
1448 <div class="defun">
1449 &mdash; Context struct: <b>struct arcfour_ctx</b><var><a name="index-struct-arcfour_005fctx-114"></a></var><br>
1450         </div>
1451
1452 <div class="defun">
1453 &mdash; Constant: <b>ARCFOUR_MIN_KEY_SIZE</b><var><a name="index-ARCFOUR_005fMIN_005fKEY_005fSIZE-115"></a></var><br>
1454 <blockquote><p>Minimum key size, 1.
1455 </p></blockquote></div>
1456
1457 <div class="defun">
1458 &mdash; Constant: <b>ARCFOUR_MAX_KEY_SIZE</b><var><a name="index-ARCFOUR_005fMAX_005fKEY_005fSIZE-116"></a></var><br>
1459 <blockquote><p>Maximum key size, 256.
1460 </p></blockquote></div>
1461
1462 <div class="defun">
1463 &mdash; Constant: <b>ARCFOUR_KEY_SIZE</b><var><a name="index-ARCFOUR_005fKEY_005fSIZE-117"></a></var><br>
1464 <blockquote><p>Default ARCFOUR key size, 16.
1465 </p></blockquote></div>
1466
1467 <div class="defun">
1468 &mdash; Function: void <b>arcfour_set_key</b> (<var>struct arcfour_ctx *ctx, unsigned length, const uint8_t *key</var>)<var><a name="index-arcfour_005fset_005fkey-118"></a></var><br>
1469 <blockquote><p>Initialize the cipher. The same function is used for both encryption and
1470 decryption.
1471 </p></blockquote></div>
1472
1473 <div class="defun">
1474 &mdash; Function: void <b>arcfour_crypt</b> (<var>struct arcfour_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-arcfour_005fcrypt-119"></a></var><br>
1475 <blockquote><p>Encrypt some data. The same function is used for both encryption and
1476 decryption. Unlike the block ciphers, this function modifies the
1477 context, so you can split the data into arbitrary chunks and encrypt
1478 them one after another. The result is the same as if you had called
1479 <code>arcfour_crypt</code> only once with all the data.
1480 </p></blockquote></div>
1481
1482 <h4 class="subsection">6.2.3 ARCTWO</h4>
1483
1484 <p>ARCTWO (also known as the trade marked name RC2) is a block cipher
1485 specified in RFC 2268. Nettle also include a variation of the ARCTWO
1486 set key operation that lack one step, to be compatible with the
1487 reverse engineered RC2 cipher description, as described in a Usenet
1488 post to <code>sci.crypt</code> by Peter Gutmann.
1489
1490    <p>ARCTWO uses a block size of 64 bits, and variable key-size ranging
1491 from 1 to 128 octets. Besides the key, ARCTWO also has a second
1492 parameter to key setup, the number of effective key bits, <code>ekb</code>.
1493 This parameter can be used to artificially reduce the key size. In
1494 practice, <code>ekb</code> is usually set equal to the input key size.
1495 Nettle defines ARCTWO in <samp><span class="file">&lt;nettle/arctwo.h&gt;</span></samp>.
1496
1497    <p>We do not recommend the use of ARCTWO; the Nettle implementation is
1498 provided primarily for interoperability with existing applications and
1499 standards.
1500
1501 <div class="defun">
1502 &mdash; Context struct: <b>struct arctwo_ctx</b><var><a name="index-struct-arctwo_005fctx-120"></a></var><br>
1503         </div>
1504
1505 <div class="defun">
1506 &mdash; Constant: <b>ARCTWO_BLOCK_SIZE</b><var><a name="index-ARCTWO_005fBLOCK_005fSIZE-121"></a></var><br>
1507 <blockquote><p>The ARCTWO block-size, 8.
1508 </p></blockquote></div>
1509
1510 <div class="defun">
1511 &mdash; Constant: <b>ARCTWO_MIN_KEY_SIZE</b><var><a name="index-ARCTWO_005fMIN_005fKEY_005fSIZE-122"></a></var><br>
1512         </div>
1513
1514 <div class="defun">
1515 &mdash; Constant: <b>ARCTWO_MAX_KEY_SIZE</b><var><a name="index-ARCTWO_005fMAX_005fKEY_005fSIZE-123"></a></var><br>
1516         </div>
1517
1518 <div class="defun">
1519 &mdash; Constant: <b>ARCTWO_KEY_SIZE</b><var><a name="index-ARCTWO_005fKEY_005fSIZE-124"></a></var><br>
1520 <blockquote><p>Default ARCTWO key size, 8.
1521 </p></blockquote></div>
1522
1523 <div class="defun">
1524 &mdash; Function: void <b>arctwo_set_key_ekb</b> (<var>struct arctwo_ctx *ctx, unsigned length, const uint8_t *key, unsigned ekb</var>)<var><a name="index-arctwo_005fset_005fkey_005fekb-125"></a></var><br>
1525 &mdash; Function: void <b>arctwo_set_key</b> (<var>struct arctwo_ctx *ctx, unsigned length, const uint8_t *key</var>)<var><a name="index-arctwo_005fset_005fkey-126"></a></var><br>
1526 &mdash; Function: void <b>arctwo_set_key_gutmann</b> (<var>struct arctwo_ctx *ctx, unsigned length, const uint8_t *key</var>)<var><a name="index-arctwo_005fset_005fkey_005fgutmann-127"></a></var><br>
1527 <blockquote><p>Initialize the cipher. The same function is used for both encryption
1528 and decryption. The first function is the most general one, which lets
1529 you provide both the variable size key, and the desired effective key
1530 size (in bits). The maximum value for <var>ekb</var> is 1024, and for
1531 convenience, <code>ekb = 0</code> has the same effect as <code>ekb = 1024</code>.
1532
1533         <p><code>arctwo_set_key(ctx, length, key)</code> is equivalent to
1534 <code>arctwo_set_key_ekb(ctx, length, key, 8*length)</code>, and
1535 <code>arctwo_set_key_gutmann(ctx, length, key)</code> is equivalent to
1536 <code>arctwo_set_key_ekb(ctx, length, key, 1024)</code>
1537 </p></blockquote></div>
1538
1539 <div class="defun">
1540 &mdash; Function: void <b>arctwo_encrypt</b> (<var>struct arctwo_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-arctwo_005fencrypt-128"></a></var><br>
1541 <blockquote><p>Encryption function. <var>length</var> must be an integral multiple of the
1542 block size. If it is more than one block, the data is processed in ECB
1543 mode. <code>src</code> and <code>dst</code> may be equal, but they must not
1544 overlap in any other way.
1545 </p></blockquote></div>
1546
1547 <div class="defun">
1548 &mdash; Function: void <b>arctwo_decrypt</b> (<var>struct arctwo_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-arctwo_005fdecrypt-129"></a></var><br>
1549 <blockquote><p>Analogous to <code>arctwo_encrypt</code>
1550 </p></blockquote></div>
1551
1552 <h4 class="subsection">6.2.4 BLOWFISH</h4>
1553
1554 <p>BLOWFISH is a block cipher designed by Bruce Schneier. It uses a block
1555 size of 64 bits (8 octets), and a variable key size, up to 448 bits. It
1556 has some weak keys. Nettle defines BLOWFISH in <samp><span class="file">&lt;nettle/blowfish.h&gt;</span></samp>.
1557
1558 <div class="defun">
1559 &mdash; Context struct: <b>struct blowfish_ctx</b><var><a name="index-struct-blowfish_005fctx-130"></a></var><br>
1560         </div>
1561
1562 <div class="defun">
1563 &mdash; Constant: <b>BLOWFISH_BLOCK_SIZE</b><var><a name="index-BLOWFISH_005fBLOCK_005fSIZE-131"></a></var><br>
1564 <blockquote><p>The BLOWFISH block-size, 8.
1565 </p></blockquote></div>
1566
1567 <div class="defun">
1568 &mdash; Constant: <b>BLOWFISH_MIN_KEY_SIZE</b><var><a name="index-BLOWFISH_005fMIN_005fKEY_005fSIZE-132"></a></var><br>
1569 <blockquote><p>Minimum BLOWFISH key size, 8.
1570 </p></blockquote></div>
1571
1572 <div class="defun">
1573 &mdash; Constant: <b>BLOWFISH_MAX_KEY_SIZE</b><var><a name="index-BLOWFISH_005fMAX_005fKEY_005fSIZE-133"></a></var><br>
1574 <blockquote><p>Maximum BLOWFISH key size, 56.
1575 </p></blockquote></div>
1576
1577 <div class="defun">
1578 &mdash; Constant: <b>BLOWFISH_KEY_SIZE</b><var><a name="index-BLOWFISH_005fKEY_005fSIZE-134"></a></var><br>
1579 <blockquote><p>Default BLOWFISH key size, 16.
1580 </p></blockquote></div>
1581
1582 <div class="defun">
1583 &mdash; Function: int <b>blowfish_set_key</b> (<var>struct blowfish_ctx *ctx, unsigned length, const uint8_t *key</var>)<var><a name="index-blowfish_005fset_005fkey-135"></a></var><br>
1584 <blockquote><p>Initialize the cipher. The same function is used for both encryption and
1585 decryption. Checks for weak keys, returning 1
1586 for good keys and 0 for weak keys. Applications that don't care about
1587 weak keys can ignore the return value.
1588
1589         <p><code>blowfish_encrypt</code> or <code>blowfish_decrypt</code> with a weak key will
1590 crash with an assert violation.
1591 </p></blockquote></div>
1592
1593 <div class="defun">
1594 &mdash; Function: void <b>blowfish_encrypt</b> (<var>struct blowfish_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-blowfish_005fencrypt-136"></a></var><br>
1595 <blockquote><p>Encryption function. <var>length</var> must be an integral multiple of the
1596 block size. If it is more than one block, the data is processed in ECB
1597 mode. <code>src</code> and <code>dst</code> may be equal, but they must not overlap
1598 in any other way.
1599 </p></blockquote></div>
1600
1601 <div class="defun">
1602 &mdash; Function: void <b>blowfish_decrypt</b> (<var>struct blowfish_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-blowfish_005fdecrypt-137"></a></var><br>
1603 <blockquote><p>Analogous to <code>blowfish_encrypt</code>
1604 </p></blockquote></div>
1605
1606 <h4 class="subsection">6.2.5 Camellia</h4>
1607
1608 <p>Camellia is a block cipher developed by Mitsubishi and Nippon Telegraph
1609 and Telephone Corporation, described in <cite>RFC3713</cite>, and recommended
1610 by some Japanese and European authorities as an alternative to AES. The
1611 algorithm is patented. The implementation in Nettle is derived from the
1612 implementation released by NTT under the GNU LGPL (v2.1 or later), and
1613 relies on the implicit patent license of the LGPL. There is also a
1614 statement of royalty-free licensing for Camellia at
1615 <a href="http://www.ntt.co.jp/news/news01e/0104/010417.html">http://www.ntt.co.jp/news/news01e/0104/010417.html</a>, but this
1616 statement has some limitations which seem problematic for free software.
1617
1618    <p>Camellia uses a the same block size and key sizes as AES: The block size
1619 is 128 bits (16 octets), and the supported key sizes are 128, 192, and
1620 256 bits. Nettle defines Camellia in <samp><span class="file">&lt;nettle/camellia.h&gt;</span></samp>.
1621
1622 <div class="defun">
1623 &mdash; Context struct: <b>struct camellia_ctx</b><var><a name="index-struct-camellia_005fctx-138"></a></var><br>
1624         </div>
1625
1626 <div class="defun">
1627 &mdash; Constant: <b>CAMELLIA_BLOCK_SIZE</b><var><a name="index-CAMELLIA_005fBLOCK_005fSIZE-139"></a></var><br>
1628 <blockquote><p>The CAMELLIA block-size, 16.
1629 </p></blockquote></div>
1630
1631 <div class="defun">
1632 &mdash; Constant: <b>CAMELLIA_MIN_KEY_SIZE</b><var><a name="index-CAMELLIA_005fMIN_005fKEY_005fSIZE-140"></a></var><br>
1633         </div>
1634
1635 <div class="defun">
1636 &mdash; Constant: <b>CAMELLIA_MAX_KEY_SIZE</b><var><a name="index-CAMELLIA_005fMAX_005fKEY_005fSIZE-141"></a></var><br>
1637         </div>
1638
1639 <div class="defun">
1640 &mdash; Constant: <b>CAMELLIA_KEY_SIZE</b><var><a name="index-CAMELLIA_005fKEY_005fSIZE-142"></a></var><br>
1641 <blockquote><p>Default CAMELLIA key size, 32.
1642 </p></blockquote></div>
1643
1644 <div class="defun">
1645 &mdash; Function: void <b>camellia_set_encrypt_key</b> (<var>struct camellia_ctx *ctx, unsigned length, const uint8_t *key</var>)<var><a name="index-camellia_005fset_005fencrypt_005fkey-143"></a></var><br>
1646 &mdash; Function: void <b>camellia_set_decrypt_key</b> (<var>struct camellia_ctx *ctx, unsigned length, const uint8_t *key</var>)<var><a name="index-camellia_005fset_005fdecrypt_005fkey-144"></a></var><br>
1647 <blockquote><p>Initialize the cipher, for encryption or decryption, respectively.
1648 </p></blockquote></div>
1649
1650 <div class="defun">
1651 &mdash; Function: void <b>camellia_invert_key</b> (<var>struct camellia_ctx *dst, const struct camellia_ctx *src</var>)<var><a name="index-camellia_005finvert_005fkey-145"></a></var><br>
1652 <blockquote><p>Given a context <var>src</var> initialized for encryption, initializes the
1653 context struct <var>dst</var> for decryption, using the same key. If the same
1654 context struct is passed for both <code>src</code> and <code>dst</code>, it is
1655 converted in place. Calling <code>camellia_set_encrypt_key</code> and
1656 <code>camellia_invert_key</code> is more efficient than calling
1657 <code>camellia_set_encrypt_key</code> and <code>camellia_set_decrypt_key</code>. This function
1658 is mainly useful for applications which needs to both encrypt and
1659 decrypt using the <em>same</em> key.
1660 </p></blockquote></div>
1661
1662 <div class="defun">
1663 &mdash; Function: void <b>camellia_crypt</b> (<var>struct camellia_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-camellia_005fcrypt-146"></a></var><br>
1664 <blockquote><p>The same function is used for both encryption and decryption.
1665 <var>length</var> must be an integral multiple of the block size. If it is
1666 more than one block, the data is processed in ECB mode. <code>src</code> and
1667 <code>dst</code> may be equal, but they must not overlap in any other way.
1668 </p></blockquote></div>
1669
1670 <h4 class="subsection">6.2.6 CAST128</h4>
1671
1672 <p>CAST-128 is a block cipher, specified in <cite>RFC 2144</cite>. It uses a 64
1673 bit (8 octets) block size, and a variable key size of up to 128 bits.
1674 Nettle defines cast128 in <samp><span class="file">&lt;nettle/cast128.h&gt;</span></samp>.
1675
1676 <div class="defun">
1677 &mdash; Context struct: <b>struct cast128_ctx</b><var><a name="index-struct-cast128_005fctx-147"></a></var><br>
1678         </div>
1679
1680 <div class="defun">
1681 &mdash; Constant: <b>CAST128_BLOCK_SIZE</b><var><a name="index-CAST128_005fBLOCK_005fSIZE-148"></a></var><br>
1682 <blockquote><p>The CAST128 block-size, 8.
1683 </p></blockquote></div>
1684
1685 <div class="defun">
1686 &mdash; Constant: <b>CAST128_MIN_KEY_SIZE</b><var><a name="index-CAST128_005fMIN_005fKEY_005fSIZE-149"></a></var><br>
1687 <blockquote><p>Minimum CAST128 key size, 5.
1688 </p></blockquote></div>
1689
1690 <div class="defun">
1691 &mdash; Constant: <b>CAST128_MAX_KEY_SIZE</b><var><a name="index-CAST128_005fMAX_005fKEY_005fSIZE-150"></a></var><br>
1692 <blockquote><p>Maximum CAST128 key size, 16.
1693 </p></blockquote></div>
1694
1695 <div class="defun">
1696 &mdash; Constant: <b>CAST128_KEY_SIZE</b><var><a name="index-CAST128_005fKEY_005fSIZE-151"></a></var><br>
1697 <blockquote><p>Default CAST128 key size, 16.
1698 </p></blockquote></div>
1699
1700 <div class="defun">
1701 &mdash; Function: void <b>cast128_set_key</b> (<var>struct cast128_ctx *ctx, unsigned length, const uint8_t *key</var>)<var><a name="index-cast128_005fset_005fkey-152"></a></var><br>
1702 <blockquote><p>Initialize the cipher. The same function is used for both encryption and
1703 decryption.
1704 </p></blockquote></div>
1705
1706 <div class="defun">
1707 &mdash; Function: void <b>cast128_encrypt</b> (<var>struct cast128_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-cast128_005fencrypt-153"></a></var><br>
1708 <blockquote><p>Encryption function. <var>length</var> must be an integral multiple of the
1709 block size. If it is more than one block, the data is processed in ECB
1710 mode. <code>src</code> and <code>dst</code> may be equal, but they must not overlap
1711 in any other way.
1712 </p></blockquote></div>
1713
1714 <div class="defun">
1715 &mdash; Function: void <b>cast128_decrypt</b> (<var>struct cast128_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-cast128_005fdecrypt-154"></a></var><br>
1716 <blockquote><p>Analogous to <code>cast128_encrypt</code>
1717 </p></blockquote></div>
1718
1719 <h4 class="subsection">6.2.7 DES</h4>
1720
1721 <p>DES is the old Data Encryption Standard, specified by NIST. It uses a
1722 block size of 64 bits (8 octets), and a key size of 56 bits. However,
1723 the key bits are distributed over 8 octets, where the least significant
1724 bit of each octet may be used for parity. A common way to use DES is to
1725 generate 8 random octets in some way, then set the least significant bit
1726 of each octet to get odd parity, and initialize DES with the resulting
1727 key.
1728
1729    <p>The key size of DES is so small that keys can be found by brute force,
1730 using specialized hardware or lots of ordinary work stations in
1731 parallel. One shouldn't be using plain DES at all today, if one uses
1732 DES at all one should be using &ldquo;triple DES&rdquo;, see DES3 below.
1733
1734    <p>DES also has some weak keys. Nettle defines DES in <samp><span class="file">&lt;nettle/des.h&gt;</span></samp>.
1735
1736 <div class="defun">
1737 &mdash; Context struct: <b>struct des_ctx</b><var><a name="index-struct-des_005fctx-155"></a></var><br>
1738         </div>
1739
1740 <div class="defun">
1741 &mdash; Constant: <b>DES_BLOCK_SIZE</b><var><a name="index-DES_005fBLOCK_005fSIZE-156"></a></var><br>
1742 <blockquote><p>The DES block-size, 8.
1743 </p></blockquote></div>
1744
1745 <div class="defun">
1746 &mdash; Constant: <b>DES_KEY_SIZE</b><var><a name="index-DES_005fKEY_005fSIZE-157"></a></var><br>
1747 <blockquote><p>DES key size, 8.
1748 </p></blockquote></div>
1749
1750 <div class="defun">
1751 &mdash; Function: int <b>des_set_key</b> (<var>struct des_ctx *ctx, const uint8_t *key</var>)<var><a name="index-des_005fset_005fkey-158"></a></var><br>
1752 <blockquote><p>Initialize the cipher. The same function is used for both encryption and
1753 decryption. Parity bits are ignored. Checks for weak keys, returning 1
1754 for good keys and 0 for weak keys. Applications that don't care about
1755 weak keys can ignore the return value.
1756 </p></blockquote></div>
1757
1758 <div class="defun">
1759 &mdash; Function: void <b>des_encrypt</b> (<var>struct des_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-des_005fencrypt-159"></a></var><br>
1760 <blockquote><p>Encryption function. <var>length</var> must be an integral multiple of the
1761 block size. If it is more than one block, the data is processed in ECB
1762 mode. <code>src</code> and <code>dst</code> may be equal, but they must not overlap
1763 in any other way.
1764 </p></blockquote></div>
1765
1766 <div class="defun">
1767 &mdash; Function: void <b>des_decrypt</b> (<var>struct des_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-des_005fdecrypt-160"></a></var><br>
1768 <blockquote><p>Analogous to <code>des_encrypt</code>
1769 </p></blockquote></div>
1770
1771 <div class="defun">
1772 &mdash; Function: int <b>des_check_parity</b> (<var>unsigned length, const uint8_t *key</var>)<var>;<a name="index-des_005fcheck_005fparity-161"></a></var><br>
1773 <blockquote><p>Checks that the given key has correct, odd, parity. Returns 1 for
1774 correct parity, and 0 for bad parity.
1775 </p></blockquote></div>
1776
1777 <div class="defun">
1778 &mdash; Function: void <b>des_fix_parity</b> (<var>unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-des_005ffix_005fparity-162"></a></var><br>
1779 <blockquote><p>Adjusts the parity bits to match DES's requirements. You need this
1780 function if you have created a random-looking string by a key agreement
1781 protocol, and want to use it as a DES key. <var>dst</var> and <var>src</var> may
1782 be equal.
1783 </p></blockquote></div>
1784
1785 <h4 class="subsection">6.2.8 DES3</h4>
1786
1787 <p>The inadequate key size of DES has already been mentioned. One way to
1788 increase the key size is to pipe together several DES boxes with
1789 independent keys. It turns out that using two DES ciphers is not as
1790 secure as one might think, even if the key size of the combination is a
1791 respectable 112 bits.
1792
1793    <p>The standard way to increase DES's key size is to use three DES boxes.
1794 The mode of operation is a little peculiar: the middle DES box is wired
1795 in the reverse direction. To encrypt a block with DES3, you encrypt it
1796 using the first 56 bits of the key, then <em>decrypt</em> it using the
1797 middle 56 bits of the key, and finally encrypt it again using the last
1798 56 bits of the key. This is known as &ldquo;ede&rdquo; triple-DES, for
1799 &ldquo;encrypt-decrypt-encrypt&rdquo;.
1800
1801    <p>The &ldquo;ede&rdquo; construction provides some backward compatibility, as you get
1802 plain single DES simply by feeding the same key to all three boxes. That
1803 should help keeping down the gate count, and the price, of hardware
1804 circuits implementing both plain DES and DES3.
1805
1806    <p>DES3 has a key size of 168 bits, but just like plain DES, useless parity
1807 bits are inserted, so that keys are represented as 24 octets (192 bits).
1808 As a 112 bit key is large enough to make brute force attacks
1809 impractical, some applications uses a &ldquo;two-key&rdquo; variant of triple-DES.
1810 In this mode, the same key bits are used for the first and the last DES
1811 box in the pipe, while the middle box is keyed independently. The
1812 two-key variant is believed to be secure, i.e. there are no known
1813 attacks significantly better than brute force.
1814
1815    <p>Naturally, it's simple to implement triple-DES on top of Nettle's DES
1816 functions. Nettle includes an implementation of three-key &ldquo;ede&rdquo;
1817 triple-DES, it is defined in the same place as plain DES,
1818 <samp><span class="file">&lt;nettle/des.h&gt;</span></samp>.
1819
1820 <div class="defun">
1821 &mdash; Context struct: <b>struct des3_ctx</b><var><a name="index-struct-des3_005fctx-163"></a></var><br>
1822         </div>
1823
1824 <div class="defun">
1825 &mdash; Constant: <b>DES3_BLOCK_SIZE</b><var><a name="index-DES3_005fBLOCK_005fSIZE-164"></a></var><br>
1826 <blockquote><p>The DES3 block-size is the same as DES_BLOCK_SIZE, 8.
1827 </p></blockquote></div>
1828
1829 <div class="defun">
1830 &mdash; Constant: <b>DES3_KEY_SIZE</b><var><a name="index-DES3_005fKEY_005fSIZE-165"></a></var><br>
1831 <blockquote><p>DES key size, 24.
1832 </p></blockquote></div>
1833
1834 <div class="defun">
1835 &mdash; Function: int <b>des3_set_key</b> (<var>struct des3_ctx *ctx, const uint8_t *key</var>)<var><a name="index-des3_005fset_005fkey-166"></a></var><br>
1836 <blockquote><p>Initialize the cipher. The same function is used for both encryption and
1837 decryption. Parity bits are ignored. Checks for weak keys, returning 1
1838 if all three keys are good keys, and 0 if one or more key is weak.
1839 Applications that don't care about weak keys can ignore the return
1840 value.
1841 </p></blockquote></div>
1842
1843    <p>For random-looking strings, you can use <code>des_fix_parity</code> to adjust
1844 the parity bits before calling <code>des3_set_key</code>.
1845
1846 <div class="defun">
1847 &mdash; Function: void <b>des3_encrypt</b> (<var>struct des3_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-des3_005fencrypt-167"></a></var><br>
1848 <blockquote><p>Encryption function. <var>length</var> must be an integral multiple of the
1849 block size. If it is more than one block, the data is processed in ECB
1850 mode. <code>src</code> and <code>dst</code> may be equal, but they must not overlap
1851 in any other way.
1852 </p></blockquote></div>
1853
1854 <div class="defun">
1855 &mdash; Function: void <b>des3_decrypt</b> (<var>struct des3_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-des3_005fdecrypt-168"></a></var><br>
1856 <blockquote><p>Analogous to <code>des_encrypt</code>
1857 </p></blockquote></div>
1858
1859 <h4 class="subsection">6.2.9 Salsa20</h4>
1860
1861 <p>Salsa20 is a fairly recent stream cipher designed by D. J. Bernstein. It
1862 is built on the observation that a cryptographic hash function can be
1863 used for encryption: Form the hash input from the secret key and a
1864 counter, xor the hash output and the first block of the plaintext, then
1865 increment the counter to process the next block (similar to CTR mode, see
1866 see <a href="#CTR">CTR</a>). Bernstein defined an encryption algorithm, Snuffle,
1867 in this way to ridicule United States export restrictions which treated hash
1868 functions as nice and harmless, but ciphers as dangerous munitions.
1869
1870    <p>Salsa20 uses the same idea, but with a new specialized hash function to
1871 mix key, block counter, and a couple of constants. It's also designed
1872 for speed; on x86_64, it is currently the fastest cipher offered by
1873 nettle. It uses a block size of 512 bits (64 octets) and there are two
1874 specified key sizes, 128 and 256 bits (16 and 32 octets).
1875
1876    <p><strong>Caution:</strong> The hash function used in Salsa20 is <em>not</em>
1877 directly applicable for use as a general hash function. It's <em>not</em>
1878 collision resistant if arbitrary inputs are allowed, and furthermore,
1879 the input and output is of fixed size.
1880
1881    <p>When using Salsa20 to process a message, one specifies both a key and a
1882 <dfn>nonce</dfn>, the latter playing a similar rôle to the initialization
1883 vector (<acronym>IV</acronym>) used with <acronym>CBC</acronym> or <acronym>CTR</acronym> mode. For
1884 this reason, Nettle uses the term <acronym>IV</acronym> to refer to the Salsa20
1885 nonce. One can use the same key for several messages, provided one uses
1886 a unique random <acronym>iv</acronym> for each message. The <acronym>iv</acronym> is 64
1887 bits (8 octets). The block counter is initialized to zero for each
1888 message, and is also 64 bits (8 octets). Nettle defines Salsa20 in
1889 <samp><span class="file">&lt;nettle/salsa20.h&gt;</span></samp>.
1890
1891 <div class="defun">
1892 &mdash; Context struct: <b>struct salsa20_ctx</b><var><a name="index-struct-salsa20_005fctx-169"></a></var><br>
1893         </div>
1894
1895 <div class="defun">
1896 &mdash; Constant: <b>SALSA20_MIN_KEY_SIZE</b><var><a name="index-SALSA20_005fMIN_005fKEY_005fSIZE-170"></a></var><br>
1897 &mdash; Constant: <b>SALSA20_MAX_KEY_SIZE</b><var><a name="index-SALSA20_005fMAX_005fKEY_005fSIZE-171"></a></var><br>
1898 <blockquote><p>The two supported key sizes, 16 and 32 octets.
1899 </p></blockquote></div>
1900
1901 <div class="defun">
1902 &mdash; Constant: <b>SALSA20_KEY_SIZE</b><var><a name="index-SALSA20_005fKEY_005fSIZE-172"></a></var><br>
1903 <blockquote><p>Recommended key size, 32.
1904 </p></blockquote></div>
1905
1906 <div class="defun">
1907 &mdash; Constant: <b>SALSA20_BLOCK_SIZE</b><var><a name="index-SALSA20_005fBLOCK_005fSIZE-173"></a></var><br>
1908 <blockquote><p>Salsa20 block size, 64.
1909 </p></blockquote></div>
1910
1911 <div class="defun">
1912 &mdash; Constant: <b>SALSA20_IV_SIZE</b><var><a name="index-SALSA20_005fIV_005fSIZE-174"></a></var><br>
1913 <blockquote><p>Size of the <acronym>IV</acronym>, 8.
1914 </p></blockquote></div>
1915
1916 <div class="defun">
1917 &mdash; Function: void <b>salsa20_set_key</b> (<var>struct salsa20_ctx *ctx, unsigned length, const uint8_t *key</var>)<var><a name="index-salsa20_005fset_005fkey-175"></a></var><br>
1918 <blockquote><p>Initialize the cipher. The same function is used for both encryption and
1919 decryption. Before using the cipher, you <em>must</em> also call
1920 <code>salsa20_set_iv</code>, see below.
1921 </p></blockquote></div>
1922
1923 <div class="defun">
1924 &mdash; Function: void <b>salsa20_set_iv</b> (<var>struct salsa20_ctx *ctx, const uint8_t *iv</var>)<var><a name="index-salsa20_005fset_005fiv-176"></a></var><br>
1925 <blockquote><p>Sets the <acronym>IV</acronym>. It is always of size <code>SALSA20_IV_SIZE</code>, 8
1926 octets. This function also initializes the block counter, setting it to
1927 zero.
1928 </p></blockquote></div>
1929
1930 <div class="defun">
1931 &mdash; Function: void <b>salsa20_crypt</b> (<var>struct salsa20_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-salsa20_005fcrypt-177"></a></var><br>
1932 <blockquote><p>Encrypts or decrypts the data of a message, using salsa20. When a
1933 message is encrypted using a sequence of calls to <code>salsa20_crypt</code>,
1934 all but the last call <em>must</em> use a length that is a multiple of
1935 <code>SALSA20_BLOCK_SIZE</code>.
1936 </p></blockquote></div>
1937
1938    <p>The full salsa20 cipher uses 20 rounds of mixing. Variants of Salsa20
1939 with fewer rounds are possible, and the 12-round variant is specified by
1940 eSTREAM, see <a href="http://www.ecrypt.eu.org/stream/finallist.html">http://www.ecrypt.eu.org/stream/finallist.html</a>.
1941 Nettle calls this variant <code>salsa20r12</code>. It uses the same context
1942 struct and key setup as the full salsa20 cipher, but a separate function
1943 for encryption and decryption.
1944
1945 <div class="defun">
1946 &mdash; Function: void <b>salsa20r12_crypt</b> (<var>struct salsa20_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-salsa20r12_005fcrypt-178"></a></var><br>
1947 <blockquote><p>Encrypts or decrypts the data of a message, using salsa20 reduced to 12
1948 rounds.
1949 </p></blockquote></div>
1950
1951 <h4 class="subsection">6.2.10 SERPENT</h4>
1952
1953 <p>SERPENT is one of the AES finalists, designed by Ross Anderson, Eli
1954 Biham and Lars Knudsen. Thus, the interface and properties are similar
1955 to AES'. One peculiarity is that it is quite pointless to use it with
1956 anything but the maximum key size, smaller keys are just padded to
1957 larger ones. Nettle defines SERPENT in <samp><span class="file">&lt;nettle/serpent.h&gt;</span></samp>.
1958
1959 <div class="defun">
1960 &mdash; Context struct: <b>struct serpent_ctx</b><var><a name="index-struct-serpent_005fctx-179"></a></var><br>
1961         </div>
1962
1963 <div class="defun">
1964 &mdash; Constant: <b>SERPENT_BLOCK_SIZE</b><var><a name="index-SERPENT_005fBLOCK_005fSIZE-180"></a></var><br>
1965 <blockquote><p>The SERPENT block-size, 16.
1966 </p></blockquote></div>
1967
1968 <div class="defun">
1969 &mdash; Constant: <b>SERPENT_MIN_KEY_SIZE</b><var><a name="index-SERPENT_005fMIN_005fKEY_005fSIZE-181"></a></var><br>
1970 <blockquote><p>Minimum SERPENT key size, 16.
1971 </p></blockquote></div>
1972
1973 <div class="defun">
1974 &mdash; Constant: <b>SERPENT_MAX_KEY_SIZE</b><var><a name="index-SERPENT_005fMAX_005fKEY_005fSIZE-182"></a></var><br>
1975 <blockquote><p>Maximum SERPENT key size, 32.
1976 </p></blockquote></div>
1977
1978 <div class="defun">
1979 &mdash; Constant: <b>SERPENT_KEY_SIZE</b><var><a name="index-SERPENT_005fKEY_005fSIZE-183"></a></var><br>
1980 <blockquote><p>Default SERPENT key size, 32.
1981 </p></blockquote></div>
1982
1983 <div class="defun">
1984 &mdash; Function: void <b>serpent_set_key</b> (<var>struct serpent_ctx *ctx, unsigned length, const uint8_t *key</var>)<var><a name="index-serpent_005fset_005fkey-184"></a></var><br>
1985 <blockquote><p>Initialize the cipher. The same function is used for both encryption and
1986 decryption.
1987 </p></blockquote></div>
1988
1989 <div class="defun">
1990 &mdash; Function: void <b>serpent_encrypt</b> (<var>struct serpent_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-serpent_005fencrypt-185"></a></var><br>
1991 <blockquote><p>Encryption function. <var>length</var> must be an integral multiple of the
1992 block size. If it is more than one block, the data is processed in ECB
1993 mode. <code>src</code> and <code>dst</code> may be equal, but they must not overlap
1994 in any other way.
1995 </p></blockquote></div>
1996
1997 <div class="defun">
1998 &mdash; Function: void <b>serpent_decrypt</b> (<var>struct serpent_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-serpent_005fdecrypt-186"></a></var><br>
1999 <blockquote><p>Analogous to <code>serpent_encrypt</code>
2000 </p></blockquote></div>
2001
2002 <h4 class="subsection">6.2.11 TWOFISH</h4>
2003
2004 <p>Another AES finalist, this one designed by Bruce Schneier and others.
2005 Nettle defines it in <samp><span class="file">&lt;nettle/twofish.h&gt;</span></samp>.
2006
2007 <div class="defun">
2008 &mdash; Context struct: <b>struct twofish_ctx</b><var><a name="index-struct-twofish_005fctx-187"></a></var><br>
2009         </div>
2010
2011 <div class="defun">
2012 &mdash; Constant: <b>TWOFISH_BLOCK_SIZE</b><var><a name="index-TWOFISH_005fBLOCK_005fSIZE-188"></a></var><br>
2013 <blockquote><p>The TWOFISH block-size, 16.
2014 </p></blockquote></div>
2015
2016 <div class="defun">
2017 &mdash; Constant: <b>TWOFISH_MIN_KEY_SIZE</b><var><a name="index-TWOFISH_005fMIN_005fKEY_005fSIZE-189"></a></var><br>
2018 <blockquote><p>Minimum TWOFISH key size, 16.
2019 </p></blockquote></div>
2020
2021 <div class="defun">
2022 &mdash; Constant: <b>TWOFISH_MAX_KEY_SIZE</b><var><a name="index-TWOFISH_005fMAX_005fKEY_005fSIZE-190"></a></var><br>
2023 <blockquote><p>Maximum TWOFISH key size, 32.
2024 </p></blockquote></div>
2025
2026 <div class="defun">
2027 &mdash; Constant: <b>TWOFISH_KEY_SIZE</b><var><a name="index-TWOFISH_005fKEY_005fSIZE-191"></a></var><br>
2028 <blockquote><p>Default TWOFISH key size, 32.
2029 </p></blockquote></div>
2030
2031 <div class="defun">
2032 &mdash; Function: void <b>twofish_set_key</b> (<var>struct twofish_ctx *ctx, unsigned length, const uint8_t *key</var>)<var><a name="index-twofish_005fset_005fkey-192"></a></var><br>
2033 <blockquote><p>Initialize the cipher. The same function is used for both encryption and
2034 decryption.
2035 </p></blockquote></div>
2036
2037 <div class="defun">
2038 &mdash; Function: void <b>twofish_encrypt</b> (<var>struct twofish_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-twofish_005fencrypt-193"></a></var><br>
2039 <blockquote><p>Encryption function. <var>length</var> must be an integral multiple of the
2040 block size. If it is more than one block, the data is processed in ECB
2041 mode. <code>src</code> and <code>dst</code> may be equal, but they must not overlap
2042 in any other way.
2043 </p></blockquote></div>
2044
2045 <div class="defun">
2046 &mdash; Function: void <b>twofish_decrypt</b> (<var>struct twofish_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-twofish_005fdecrypt-194"></a></var><br>
2047 <blockquote><p>Analogous to <code>twofish_encrypt</code>
2048 </p></blockquote></div>
2049
2050 <!-- @node nettle_cipher, Cipher Block Chaining, Cipher functions, Reference -->
2051 <!-- @comment  node-name,  next,  previous,  up -->
2052 <h4 class="subsection">6.2.12 <code>struct nettle_cipher</code></h4>
2053
2054 <p>Nettle includes a struct including information about some of the more
2055 regular cipher functions. It should be considered a little experimental,
2056 but can be useful for applications that need a simple way to handle
2057 various algorithms. Nettle defines these structs in
2058 <samp><span class="file">&lt;nettle/nettle-meta.h&gt;</span></samp>.
2059
2060 <div class="defun">
2061 &mdash; Meta struct: <code>struct nettle_cipher</code><var> name context_size block_size key_size set_encrypt_key set_decrypt_key encrypt decrypt<a name="index-g_t_0040code_007bstruct-nettle_005fcipher_007d-195"></a></var><br>
2062 <blockquote><p>The last four attributes are function pointers, of types
2063 <code>nettle_set_key_func</code> and <code>nettle_crypt_func</code>. The first
2064 argument to these functions is a <code>void *</code> pointer to a context
2065 struct, which is of size <code>context_size</code>.
2066 </p></blockquote></div>
2067
2068 <div class="defun">
2069 &mdash; Constant Struct: struct nettle_cipher <b>nettle_aes128</b><var><a name="index-nettle_005faes128-196"></a></var><br>
2070 &mdash; Constant Struct: struct nettle_cipher <b>nettle_aes192</b><var><a name="index-nettle_005faes192-197"></a></var><br>
2071 &mdash; Constant Struct: struct nettle_cipher <b>nettle_aes256</b><var><a name="index-nettle_005faes256-198"></a></var><br>
2072
2073    &mdash; Constant Struct: struct nettle_cipher <b>nettle_arctwo40</b><var><a name="index-nettle_005farctwo40-199"></a></var><br>
2074 &mdash; Constant Struct: struct nettle_cipher <b>nettle_arctwo64</b><var><a name="index-nettle_005farctwo64-200"></a></var><br>
2075 &mdash; Constant Struct: struct nettle_cipher <b>nettle_arctwo128</b><var><a name="index-nettle_005farctwo128-201"></a></var><br>
2076 &mdash; Constant Struct: struct nettle_cipher <b>nettle_arctwo_gutmann128</b><var><a name="index-nettle_005farctwo_005fgutmann128-202"></a></var><br>
2077
2078    &mdash; Constant Struct: struct nettle_cipher <b>nettle_arcfour128</b><var><a name="index-nettle_005farcfour128-203"></a></var><br>
2079
2080    &mdash; Constant Struct: struct nettle_cipher <b>nettle_camellia128</b><var><a name="index-nettle_005fcamellia128-204"></a></var><br>
2081 &mdash; Constant Struct: struct nettle_cipher <b>nettle_camellia192</b><var><a name="index-nettle_005fcamellia192-205"></a></var><br>
2082 &mdash; Constant Struct: struct nettle_cipher <b>nettle_camellia256</b><var><a name="index-nettle_005fcamellia256-206"></a></var><br>
2083
2084    &mdash; Constant Struct: struct nettle_cipher <b>nettle_cast128</b><var><a name="index-nettle_005fcast128-207"></a></var><br>
2085
2086    &mdash; Constant Struct: struct nettle_cipher <b>nettle_serpent128</b><var><a name="index-nettle_005fserpent128-208"></a></var><br>
2087 &mdash; Constant Struct: struct nettle_cipher <b>nettle_serpent192</b><var><a name="index-nettle_005fserpent192-209"></a></var><br>
2088 &mdash; Constant Struct: struct nettle_cipher <b>nettle_serpent256</b><var><a name="index-nettle_005fserpent256-210"></a></var><br>
2089
2090    &mdash; Constant Struct: struct nettle_cipher <b>nettle_twofish128</b><var><a name="index-nettle_005ftwofish128-211"></a></var><br>
2091 &mdash; Constant Struct: struct nettle_cipher <b>nettle_twofish192</b><var><a name="index-nettle_005ftwofish192-212"></a></var><br>
2092 &mdash; Constant Struct: struct nettle_cipher <b>nettle_twofish256</b><var><a name="index-nettle_005ftwofish256-213"></a></var><br>
2093 <blockquote><p>Nettle includes such structs for all the <em>regular</em> ciphers, i.e.
2094 ones without weak keys or other oddities.
2095 </p></blockquote></div>
2096
2097    <p>Nettle also exports a list of all these ciphers without weak keys or
2098 other oddities.
2099
2100 <div class="defun">
2101 &mdash; Constant Array: struct nettle_cipher ** <b>nettle_ciphers</b><var><a name="index-nettle_005fciphers-214"></a></var><br>
2102 <blockquote><p>This list can be used to dynamically enumerate or search the supported
2103 algorithms. NULL-terminated.
2104 </p></blockquote></div>
2105
2106 <div class="node">
2107 <a name="Cipher-modes"></a>
2108 <p><hr>
2109 Next:&nbsp;<a rel="next" accesskey="n" href="#Keyed-hash-functions">Keyed hash functions</a>,
2110 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Cipher-functions">Cipher functions</a>,
2111 Up:&nbsp;<a rel="up" accesskey="u" href="#Reference">Reference</a>
2112
2113 </div>
2114
2115 <!-- node-name,  next,  previous,  up -->
2116 <h3 class="section">6.3 Cipher modes</h3>
2117
2118 <p>Cipher modes of operation specifies the procedure to use when encrypting
2119 a message that is larger than the cipher's block size. As explained in
2120 See <a href="#Cipher-functions">Cipher functions</a>, splitting the message into blocks and
2121 processing them independently with the block cipher (Electronic Code
2122 Book mode, <acronym>ECB</acronym>) leaks information. Besides <acronym>ECB</acronym>,
2123 Nettle provides three other modes of operation: Cipher Block Chaining
2124 (<acronym>CBC</acronym>), Counter mode (<acronym>CTR</acronym>), and Galois/Counter mode
2125 (<acronym>GCM</acronym>). <acronym>CBC</acronym> is widely used, but there are a few
2126 subtle issues of information leakage, see, e.g.,
2127 <a href="http://www.kb.cert.org/vuls/id/958563"><acronym>SSH</acronym> <acronym>CBC</acronym> vulnerability</a>. <acronym>CTR</acronym> and <acronym>GCM</acronym>
2128 were standardized more recently, and are believed to be more secure.
2129 <acronym>GCM</acronym> includes message authentication; for the other modes, one
2130 should always use a <acronym>MAC</acronym> (see <a href="#Keyed-hash-functions">Keyed hash functions</a>) or
2131 signature to authenticate the message.
2132
2133 <ul class="menu">
2134 <li><a accesskey="1" href="#CBC">CBC</a>
2135 <li><a accesskey="2" href="#CTR">CTR</a>
2136 <li><a accesskey="3" href="#GCM">GCM</a>
2137 </ul>
2138
2139 <div class="node">
2140 <a name="CBC"></a>
2141 <p><hr>
2142 Next:&nbsp;<a rel="next" accesskey="n" href="#CTR">CTR</a>,
2143 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Cipher-modes">Cipher modes</a>,
2144 Up:&nbsp;<a rel="up" accesskey="u" href="#Cipher-modes">Cipher modes</a>
2145
2146 </div>
2147
2148 <!-- node-name,  next,  previous,  up -->
2149 <h4 class="subsection">6.3.1 Cipher Block Chaining</h4>
2150
2151 <p><a name="index-Cipher-Block-Chaining-215"></a><a name="index-CBC-Mode-216"></a>
2152 When using <acronym>CBC</acronym> mode, plaintext blocks are not encrypted
2153 independently of each other, like in Electronic Cook Book mode. Instead,
2154 when encrypting a block in <acronym>CBC</acronym> mode, the previous ciphertext
2155 block is XORed with the plaintext before it is fed to the block cipher.
2156 When encrypting the first block, a random block called an <dfn>IV</dfn>, or
2157 Initialization Vector, is used as the &ldquo;previous ciphertext block&rdquo;. The
2158 IV should be chosen randomly, but it need not be kept secret, and can
2159 even be transmitted in the clear together with the encrypted data.
2160
2161    <p>In symbols, if <code>E_k</code> is the encryption function of a block cipher,
2162 and <code>IV</code> is the initialization vector, then <code>n</code> plaintext blocks
2163 <code>M_1</code>,<small class="dots">...</small> <code>M_n</code> are transformed into <code>n</code> ciphertext blocks
2164 <code>C_1</code>,<small class="dots">...</small> <code>C_n</code> as follows:
2165
2166 <pre class="example">     C_1 = E_k(IV  XOR M_1)
2167      C_2 = E_k(C_1 XOR M_2)
2168
2169      ...
2170
2171      C_n = E_k(C_(n-1) XOR M_n)
2172 </pre>
2173    <p>Nettle's includes two functions for applying a block cipher in Cipher
2174 Block Chaining (<acronym>CBC</acronym>) mode, one for encryption and one for
2175 decryption. These functions uses <code>void *</code> to pass cipher contexts
2176 around.
2177
2178 <div class="defun">
2179 &mdash; Function: void <b>cbc_encrypt</b> (<var>void *ctx, nettle_crypt_func f, unsigned block_size, uint8_t *iv, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-cbc_005fencrypt-217"></a></var><br>
2180 &mdash; Function: void <b>cbc_decrypt</b> (<var>void *ctx, void </var>(<var>*f</var>)()<var>, unsigned block_size, uint8_t *iv, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-cbc_005fdecrypt-218"></a></var><br>
2181 <blockquote>
2182         <p>Applies the encryption or decryption function <var>f</var> in <acronym>CBC</acronym>
2183 mode. The final ciphertext block processed is copied into <var>iv</var>
2184 before returning, so that large message be processed be a sequence of
2185 calls to <code>cbc_encrypt</code>. The function <var>f</var> is of type
2186
2187         <p><code>void f (void *</code><var>ctx</var><code>, unsigned </code><var>length</var><code>, uint8_t </code><var>dst</var><code>,
2188 const uint8_t *</code><var>src</var><code>)</code>,
2189
2190      <p class="noindent">and the <code>cbc_encrypt</code> and <code>cbc_decrypt</code> functions pass their
2191 argument <var>ctx</var> on to <var>f</var>.
2192 </p></blockquote></div>
2193
2194    <p>There are also some macros to help use these functions correctly.
2195
2196 <div class="defun">
2197 &mdash; Macro: <b>CBC_CTX</b> (<var>context_type, block_size</var>)<var><a name="index-CBC_005fCTX-219"></a></var><br>
2198 <blockquote><p>Expands to
2199      <pre class="example">          {
2200              context_type ctx;
2201              uint8_t iv[block_size];
2202           }
2203 </pre>
2204         </blockquote></div>
2205
2206    <p>It can be used to define a <acronym>CBC</acronym> context struct, either directly,
2207
2208 <pre class="example">     struct CBC_CTX(struct aes_ctx, AES_BLOCK_SIZE) ctx;
2209 </pre>
2210    <p>or to give it a struct tag,
2211
2212 <pre class="example">     struct aes_cbc_ctx CBC_CTX (struct aes_ctx, AES_BLOCK_SIZE);
2213 </pre>
2214    <div class="defun">
2215 &mdash; Macro: <b>CBC_SET_IV</b> (<var>ctx, iv</var>)<var><a name="index-CBC_005fSET_005fIV-220"></a></var><br>
2216 <blockquote><p>First argument is a pointer to a context struct as defined by <code>CBC_CTX</code>,
2217 and the second is a pointer to an Initialization Vector (IV) that is
2218 copied into that context.
2219 </p></blockquote></div>
2220
2221 <div class="defun">
2222 &mdash; Macro: <b>CBC_ENCRYPT</b> (<var>ctx, f, length, dst, src</var>)<var><a name="index-CBC_005fENCRYPT-221"></a></var><br>
2223 &mdash; Macro: <b>CBC_DECRYPT</b> (<var>ctx, f, length, dst, src</var>)<var><a name="index-CBC_005fDECRYPT-222"></a></var><br>
2224 <blockquote><p>A simpler way to invoke <code>cbc_encrypt</code> and <code>cbc_decrypt</code>. The
2225 first argument is a pointer to a context struct as defined by
2226 <code>CBC_CTX</code>, and the second argument is an encryption or decryption
2227 function following Nettle's conventions. The last three arguments define
2228 the source and destination area for the operation.
2229 </p></blockquote></div>
2230
2231    <p>These macros use some tricks to make the compiler display a warning if
2232 the types of <var>f</var> and <var>ctx</var> don't match, e.g. if you try to use
2233 an <code>struct aes_ctx</code> context with the <code>des_encrypt</code> function.
2234
2235 <div class="node">
2236 <a name="CTR"></a>
2237 <p><hr>
2238 Next:&nbsp;<a rel="next" accesskey="n" href="#GCM">GCM</a>,
2239 Previous:&nbsp;<a rel="previous" accesskey="p" href="#CBC">CBC</a>,
2240 Up:&nbsp;<a rel="up" accesskey="u" href="#Cipher-modes">Cipher modes</a>
2241
2242 </div>
2243
2244 <!-- node-name,  next,  previous,  up -->
2245 <h4 class="subsection">6.3.2 Counter mode</h4>
2246
2247 <p><a name="index-Counter-Mode-223"></a><a name="index-CTR-Mode-224"></a>
2248 Counter mode (<acronym>CTR</acronym>) uses the block cipher as a keyed
2249 pseudo-random generator. The output of the generator is XORed with the
2250 data to be encrypted. It can be understood as a way to transform a block
2251 cipher to a stream cipher.
2252
2253    <p>The message is divided into <code>n</code> blocks <code>M_1</code>,<small class="dots">...</small>
2254 <code>M_n</code>, where <code>M_n</code> is of size <code>m</code> which may be smaller
2255 than the block size. Except for the last block, all the message blocks
2256 must be of size equal to the cipher's block size.
2257
2258    <p>If <code>E_k</code> is the encryption function of a block cipher, <code>IC</code> is
2259 the initial counter, then the <code>n</code> plaintext blocks are
2260 transformed into <code>n</code> ciphertext blocks <code>C_1</code>,<small class="dots">...</small>
2261 <code>C_n</code> as follows:
2262
2263 <pre class="example">     C_1 = E_k(IC) XOR M_1
2264      C_2 = E_k(IC + 1) XOR M_2
2265
2266      ...
2267
2268      C_(n-1) = E_k(IC + n - 2) XOR M_(n-1)
2269      C_n = E_k(IC + n - 1) [1..m] XOR M_n
2270 </pre>
2271    <p>The <acronym>IC</acronym> is the initial value for the counter, it plays a
2272 similar rôle as the <acronym>IV</acronym> for <acronym>CBC</acronym>. When adding,
2273 <code>IC + x</code>, <acronym>IC</acronym> is interpreted as an integer, in network
2274 byte order. For the last block, <code>E_k(IC + n - 1) [1..m]</code> means that
2275 the cipher output is truncated to <code>m</code> bytes.
2276
2277 <div class="defun">
2278 &mdash; Function: void <b>ctr_crypt</b> (<var>void *ctx, nettle_crypt_func f, unsigned block_size, uint8_t *ctr, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-ctr_005fcrypt-225"></a></var><br>
2279 <blockquote>
2280         <p>Applies the encryption function <var>f</var> in <acronym>CTR</acronym> mode. Note that
2281 for <acronym>CTR</acronym> mode, encryption and decryption is the same operation,
2282 and hence <var>f</var> should always be the encryption function for the
2283 underlying block cipher.
2284
2285         <p>When a message is encrypted using a sequence of calls to
2286 <code>ctr_crypt</code>, all but the last call <em>must</em> use a length that is
2287 a multiple of the block size.
2288 </p></blockquote></div>
2289
2290    <p>Like for <acronym>CBC</acronym>, there are also a couple of helper macros.
2291
2292 <div class="defun">
2293 &mdash; Macro: <b>CTR_CTX</b> (<var>context_type, block_size</var>)<var><a name="index-CTR_005fCTX-226"></a></var><br>
2294 <blockquote><p>Expands to
2295      <pre class="example">          {
2296              context_type ctx;
2297              uint8_t ctr[block_size];
2298           }
2299 </pre>
2300         </blockquote></div>
2301
2302 <div class="defun">
2303 &mdash; Macro: <b>CTR_SET_COUNTER</b> (<var>ctx, iv</var>)<var><a name="index-CTR_005fSET_005fCOUNTER-227"></a></var><br>
2304 <blockquote><p>First argument is a pointer to a context struct as defined by
2305 <code>CTR_CTX</code>, and the second is a pointer to an initial counter that
2306 is copied into that context.
2307 </p></blockquote></div>
2308
2309 <div class="defun">
2310 &mdash; Macro: <b>CTR_CRYPT</b> (<var>ctx, f, length, dst, src</var>)<var><a name="index-CTR_005fCRYPT-228"></a></var><br>
2311 <blockquote><p>A simpler way to invoke <code>ctr_crypt</code>. The first argument is a
2312 pointer to a context struct as defined by <code>CTR_CTX</code>, and the second
2313 argument is an encryption function following Nettle's conventions. The
2314 last three arguments define the source and destination area for the
2315 operation.
2316 </p></blockquote></div>
2317
2318 <div class="node">
2319 <a name="GCM"></a>
2320 <p><hr>
2321 Previous:&nbsp;<a rel="previous" accesskey="p" href="#CTR">CTR</a>,
2322 Up:&nbsp;<a rel="up" accesskey="u" href="#Cipher-modes">Cipher modes</a>
2323
2324 </div>
2325
2326 <!-- node-name,  next,  previous,  up -->
2327 <h4 class="subsection">6.3.3 Galois counter mode</h4>
2328
2329 <p><a name="index-Galois-Counter-Mode-229"></a><a name="index-GCM-230"></a>
2330 Galois counter mode is the combination of counter mode with message
2331 authentication based on universal hashing. The main objective of the
2332 design is to provide high performance for hardware implementations,
2333 where other popular <acronym>MAC</acronym> algorithms (see <a href="#Keyed-hash-functions">Keyed hash functions</a> becomes a bottleneck for high-speed hardware implementations.
2334 It was proposed by David A. McGrew and John Viega in 2005, and
2335 recommended by NIST in 2007,
2336 <a href="http://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf">NIST Special Publication 800-38D</a>. It is constructed on top of a block
2337 cipher which must have a block size of 128 bits.
2338
2339    <p><acronym>GCM</acronym> is applied to messages of arbitrary length. The inputs
2340 are:
2341
2342      <ul>
2343 <li>A key, which can be used for many messages.
2344 <li>An initialization vector (<acronym>IV</acronym>) which <em>must</em> be unique for
2345 each message.
2346 <li>Additional authenticated data, which is to be included in the message
2347 authentication, but not encrypted. May be empty.
2348 <li>The plaintext. Maybe empty.
2349 </ul>
2350
2351    <p>The outputs are a ciphertext, of the same length as the plaintext, and a
2352 message digest of length 128 bits. Nettle's support for <acronym>GCM</acronym>
2353 consists of a low-level general interface, some convenience macros, and
2354 specific functions for <acronym>GCM</acronym> using <acronym>AES</acronym> as the
2355 underlying cipher. These interfaces are defined in <samp><span class="file">&lt;nettle/gcm.h&gt;</span></samp>
2356
2357 <h5 class="subsubsection">6.3.3.1 General <acronym>GCM</acronym> interface</h5>
2358
2359 <div class="defun">
2360 &mdash; Context struct: <b>struct gcm_key</b><var><a name="index-struct-gcm_005fkey-231"></a></var><br>
2361 <blockquote><p>Message independent hash sub-key, and related tables.
2362 </p></blockquote></div>
2363
2364 <div class="defun">
2365 &mdash; Context struct: <b>struct gcm_ctx</b><var><a name="index-struct-gcm_005fctx-232"></a></var><br>
2366 <blockquote><p>Holds state corresponding to a particular message.
2367 </p></blockquote></div>
2368
2369 <div class="defun">
2370 &mdash; Constant: <b>GCM_BLOCK_SIZE</b><var><a name="index-GCM_005fBLOCK_005fSIZE-233"></a></var><br>
2371 <blockquote><p><acronym>GCM</acronym>'s block size, 16.
2372 </p></blockquote></div>
2373
2374 <div class="defun">
2375 &mdash; Constant: <b>GCM_IV_SIZE</b><var><a name="index-GCM_005fIV_005fSIZE-234"></a></var><br>
2376 <blockquote><p>Recommended size of the <acronym>IV</acronym>, 12. Other sizes are allowed.
2377 </p></blockquote></div>
2378
2379 <div class="defun">
2380 &mdash; Function: void <b>gcm_set_key</b> (<var>struct gcm_key *key, void *cipher, nettle_crypt_func *f</var>)<var><a name="index-gcm_005fset_005fkey-235"></a></var><br>
2381 <blockquote><p>Initializes <var>key</var>. <var>cipher</var> gives a context struct for the
2382 underlying cipher, which must have been previously initialized for
2383 encryption, and <var>f</var> is the encryption function.
2384 </p></blockquote></div>
2385
2386 <div class="defun">
2387 &mdash; Function: void <b>gcm_set_iv</b> (<var>struct gcm_ctx *ctx, const struct gcm_key *key, unsigned length, const uint8_t *iv</var>)<var><a name="index-gcm_005fset_005fiv-236"></a></var><br>
2388 <blockquote><p>Initializes <var>ctx</var> using the given <acronym>IV</acronym>. The <var>key</var>
2389 argument is actually needed only if <var>length</var> differs from
2390 <code>GCM_IV_SIZE</code>.
2391 </p></blockquote></div>
2392
2393 <div class="defun">
2394 &mdash; Function: void <b>gcm_update</b> (<var>struct gcm_ctx *ctx, const struct gcm_key *key, unsigned length, const uint8_t *data</var>)<var><a name="index-gcm_005fupdate-237"></a></var><br>
2395 <blockquote><p>Provides associated data to be authenticated. If used, must be called
2396 before <code>gcm_encrypt</code> or <code>gcm_decrypt</code>. All but the last call
2397 for each message <em>must</em> use a length that is a multiple of the
2398 block size.
2399 </p></blockquote></div>
2400
2401 <div class="defun">
2402 &mdash; Function: void <b>gcm_encrypt</b> (<var>struct gcm_ctx *ctx, const struct gcm_key *key void *cipher, nettle_crypt_func *f, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-gcm_005fencrypt-238"></a></var><br>
2403 &mdash; Function: void <b>gcm_decrypt</b> (<var>struct gcm_ctx *ctx, const struct gcm_key *key, void *cipher, nettle_crypt_func *f, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-gcm_005fdecrypt-239"></a></var><br>
2404 <blockquote><p>Encrypts or decrypts the data of a message. <var>cipher</var> is the context
2405 struct for the underlying cipher and <var>f</var> is the encryption function.
2406 All but the last call for each message <em>must</em> use a length that is
2407 a multiple of the block size.
2408 </p></blockquote></div>
2409
2410 <div class="defun">
2411 &mdash; Function: void <b>gcm_digest</b> (<var>struct gcm_ctx *ctx, const struct gcm_key *key, void *cipher, nettle_crypt_func *f, unsigned length, uint8_t *digest</var>)<var><a name="index-gcm_005fdigest-240"></a></var><br>
2412 <blockquote><p>Extracts the message digest (also known &ldquo;authentication tag&rdquo;). This is
2413 the final operation when processing a message. <var>length</var> is usually
2414 equal to <code>GCM_BLOCK_SIZE</code>, but if you provide a smaller value,
2415 only the first <var>length</var> octets of the digest are written.
2416 </p></blockquote></div>
2417
2418    <p>To encrypt a message using <acronym>GCM</acronym>, first initialize a context for
2419 the underlying block cipher with a key to use for encryption. Then call
2420 the above functions in the following order: <code>gcm_set_key</code>,
2421 <code>gcm_set_iv</code>, <code>gcm_update</code>, <code>gcm_encrypt</code>,
2422 <code>gcm_digest</code>. The decryption procedure is analogous, just calling
2423 <code>gcm_decrypt</code> instead of <code>gcm_encrypt</code> (note that
2424 <acronym>GCM</acronym> decryption still uses the encryption function of the
2425 underlying block cipher). To process a new message, using the same key,
2426 call <code>gcm_set_iv</code> with a new <acronym>iv</acronym>.
2427
2428 <h5 class="subsubsection">6.3.3.2 <acronym>GCM</acronym> helper macros</h5>
2429
2430 <p>The following macros are defined.
2431
2432 <div class="defun">
2433 &mdash; Macro: <b>GCM_CTX</b> (<var>context_type</var>)<var><a name="index-GCM_005fCTX-241"></a></var><br>
2434 <blockquote><p>This defines an all-in-one context struct, including the context of the
2435 underlying cipher, the hash sub-key, and the per-message state. It expands
2436 to
2437      <pre class="example">          {
2438              context_type cipher;
2439              struct gcm_key key;
2440              struct gcm_ctx gcm;
2441           }
2442 </pre>
2443         </blockquote></div>
2444
2445    <p>Example use:
2446 <pre class="example">     struct gcm_aes_ctx GCM_CTX(struct aes_ctx);
2447 </pre>
2448    <p>The following macros operate on context structs of this form.
2449
2450 <div class="defun">
2451 &mdash; Macro: <b>GCM_SET_KEY</b> (<var>ctx, set_key, encrypt, length, data</var>)<var><a name="index-GCM_005fSET_005fKEY-242"></a></var><br>
2452 <blockquote><p>First argument, <var>ctx</var>, is a context struct as defined
2453 by <code>GCM_CTX</code>. <var>set_key</var> and <var>encrypt</var> are functions for
2454 setting the encryption key and for encrypting data using the underlying
2455 cipher. <var>length</var> and <var>data</var> give the key.
2456 </p></blockquote></div>
2457
2458 <div class="defun">
2459 &mdash; Macro: <b>GCM_SET_IV</b> (<var>ctx, length, data</var>)<var><a name="index-GCM_005fSET_005fIV-243"></a></var><br>
2460 <blockquote><p>First argument is a context struct as defined by
2461 <code>GCM_CTX</code>. <var>length</var> and <var>data</var> give the initialization
2462 vector (<acronym>IV</acronym>).
2463 </p></blockquote></div>
2464
2465 <div class="defun">
2466 &mdash; Macro: <b>GCM_UPDATE</b> (<var>ctx, length, data</var>)<var><a name="index-GCM_005fUPDATE-244"></a></var><br>
2467 <blockquote><p>Simpler way to call <code>gcm_update</code>. First argument is a context
2468 struct as defined by <code>GCM_CTX</code>
2469 </p></blockquote></div>
2470
2471 <div class="defun">
2472 &mdash; Macro: <b>GCM_ENCRYPT</b> (<var>ctx, encrypt, length, dst, src</var>)<var><a name="index-GCM_005fENCRYPT-245"></a></var><br>
2473 &mdash; Macro: <b>GCM_DECRYPT</b> (<var>ctx, encrypt, length, dst, src</var>)<var><a name="index-GCM_005fDECRYPT-246"></a></var><br>
2474 &mdash; Macro: <b>GCM_DIGEST</b> (<var>ctx, encrypt, length, digest</var>)<var><a name="index-GCM_005fDIGEST-247"></a></var><br>
2475 <blockquote><p>Simpler way to call <code>gcm_encrypt</code>, <code>gcm_decrypt</code> or
2476 <code>gcm_digest</code>. First argument is a context struct as defined by
2477 <code>GCM_CTX</code>. Second argument, <var>encrypt</var>, is a pointer to the
2478 encryption function of the underlying cipher.
2479 </p></blockquote></div>
2480
2481 <h5 class="subsubsection">6.3.3.3 <acronym>GCM</acronym>-<acronym>AES</acronym> interface</h5>
2482
2483 <p>The following functions implement the common case of <acronym>GCM</acronym> using
2484 <acronym>AES</acronym> as the underlying cipher.
2485
2486 <div class="defun">
2487 &mdash; Context struct: <b>struct gcm_aes_ctx</b><var><a name="index-struct-gcm_005faes_005fctx-248"></a></var><br>
2488 <blockquote><p>The context struct, defined using <code>GCM_CTX</code>.
2489 </p></blockquote></div>
2490
2491 <div class="defun">
2492 &mdash; Function: void <b>gcm_aes_set_key</b> (<var>struct gcm_aes_ctx *ctx, unsigned length, const uint8_t *key</var>)<var><a name="index-gcm_005faes_005fset_005fkey-249"></a></var><br>
2493 <blockquote><p>Initializes <var>ctx</var> using the given key. All valid <acronym>AES</acronym> key
2494 sizes can be used.
2495 </p></blockquote></div>
2496
2497 <div class="defun">
2498 &mdash; Function: void <b>gcm_aes_set_iv</b> (<var>struct gcm_aes_ctx *ctx, unsigned length, const uint8_t *iv</var>)<var><a name="index-gcm_005faes_005fset_005fiv-250"></a></var><br>
2499 <blockquote><p>Initializes the per-message state, using the given <acronym>IV</acronym>.
2500 </p></blockquote></div>
2501
2502 <div class="defun">
2503 &mdash; Function: void <b>gcm_aes_update</b> (<var>struct gcm_aes_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-gcm_005faes_005fupdate-251"></a></var><br>
2504 <blockquote><p>Provides associated data to be authenticated. If used, must be called
2505 before <code>gcm_aes_encrypt</code> or <code>gcm_aes_decrypt</code>. All but the last call
2506 for each message <em>must</em> use a length that is a multiple of the
2507 block size.
2508 </p></blockquote></div>
2509
2510 <div class="defun">
2511 &mdash; Function: void <b>gcm_aes_encrypt</b> (<var>struct gcm_aes_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-gcm_005faes_005fencrypt-252"></a></var><br>
2512 &mdash; Function: void <b>gcm_aes_decrypt</b> (<var>struct gcm_aes_ctx *ctx, unsigned length, uint8_t *dst, const uint8_t *src</var>)<var><a name="index-gcm_005faes_005fdecrypt-253"></a></var><br>
2513 <blockquote><p>Encrypts or decrypts the data of a message. All but the last call for
2514 each message <em>must</em> use a length that is a multiple of the block
2515 size.
2516
2517         </blockquote></div>
2518
2519 <div class="defun">
2520 &mdash; Function: void <b>gcm_aes_digest</b> (<var>struct gcm_aes_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-gcm_005faes_005fdigest-254"></a></var><br>
2521 <blockquote><p>Extracts the message digest (also known &ldquo;authentication tag&rdquo;). This is
2522 the final operation when processing a message. <var>length</var> is usually
2523 equal to <code>GCM_BLOCK_SIZE</code>, but if you provide a smaller value,
2524 only the first <var>length</var> octets of the digest are written.
2525 </p></blockquote></div>
2526
2527 <div class="node">
2528 <a name="Keyed-hash-functions"></a>
2529 <p><hr>
2530 Next:&nbsp;<a rel="next" accesskey="n" href="#Key-derivation-functions">Key derivation functions</a>,
2531 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Cipher-modes">Cipher modes</a>,
2532 Up:&nbsp;<a rel="up" accesskey="u" href="#Reference">Reference</a>
2533
2534 </div>
2535
2536 <!-- node-name,  next,  previous,  up -->
2537 <h3 class="section">6.4 Keyed Hash Functions</h3>
2538
2539 <p><a name="index-Keyed-Hash-Function-255"></a><a name="index-Message-Authentication-Code-256"></a><a name="index-MAC-257"></a>
2540 A <dfn>keyed hash function</dfn>, or <dfn>Message Authentication Code</dfn>
2541 (<acronym>MAC</acronym>) is a function that takes a key and a message, and
2542 produces fixed size <acronym>MAC</acronym>. It should be hard to compute a
2543 message and a matching <acronym>MAC</acronym> without knowledge of the key. It
2544 should also be hard to compute the key given only messages and
2545 corresponding <acronym>MAC</acronym>s.
2546
2547    <p>Keyed hash functions are useful primarily for message authentication,
2548 when Alice and Bob shares a secret: The sender, Alice, computes the
2549 <acronym>MAC</acronym> and attaches it to the message. The receiver, Bob, also computes
2550 the <acronym>MAC</acronym> of the message, using the same key, and compares that
2551 to Alice's value. If they match, Bob can be assured that
2552 the message has not been modified on its way from Alice.
2553
2554    <p>However, unlike digital signatures, this assurance is not transferable.
2555 Bob can't show the message and the <acronym>MAC</acronym> to a third party and
2556 prove that Alice sent that message. Not even if he gives away the key to
2557 the third party. The reason is that the <em>same</em> key is used on both
2558 sides, and anyone knowing the key can create a correct <acronym>MAC</acronym> for
2559 any message. If Bob believes that only he and Alice knows the key, and
2560 he knows that he didn't attach a <acronym>MAC</acronym> to a particular message,
2561 he knows it must be Alice who did it. However, the third party can't
2562 distinguish between a <acronym>MAC</acronym> created by Alice and one created by
2563 Bob.
2564
2565    <p>Keyed hash functions are typically a lot faster than digital signatures
2566 as well.
2567
2568 <h4 class="subsection">6.4.1 <acronym>HMAC</acronym></h4>
2569
2570 <p><a name="index-HMAC-258"></a>
2571 One can build keyed hash functions from ordinary hash functions. Older
2572 constructions simply concatenate secret key and message and hashes that, but
2573 such constructions have weaknesses. A better construction is
2574 <acronym>HMAC</acronym>, described in <cite>RFC 2104</cite>.
2575
2576    <p>For an underlying hash function <code>H</code>, with digest size <code>l</code> and
2577 internal block size <code>b</code>, <acronym>HMAC-H</acronym> is constructed as
2578 follows: From a given key <code>k</code>, two distinct subkeys <code>k_i</code> and
2579 <code>k_o</code> are constructed, both of length <code>b</code>. The
2580 <acronym>HMAC-H</acronym> of a message <code>m</code> is then computed as <code>H(k_o |
2581 H(k_i | m))</code>, where <code>|</code> denotes string concatenation.
2582
2583    <p><acronym>HMAC</acronym> keys can be of any length, but it is recommended to use
2584 keys of length <code>l</code>, the digest size of the underlying hash function
2585 <code>H</code>. Keys that are longer than <code>b</code> are shortened to length
2586 <code>l</code> by hashing with <code>H</code>, so arbitrarily long keys aren't
2587 very useful.
2588
2589    <p>Nettle's <acronym>HMAC</acronym> functions are defined in <samp><span class="file">&lt;nettle/hmac.h&gt;</span></samp>.
2590 There are abstract functions that use a pointer to a <code>struct
2591 nettle_hash</code> to represent the underlying hash function and <code>void *</code>
2592 pointers that point to three different context structs for that hash
2593 function. There are also concrete functions for <acronym>HMAC-MD5</acronym>,
2594 <acronym>HMAC-RIPEMD160</acronym> <acronym>HMAC-SHA1</acronym>, <acronym>HMAC-SHA256</acronym>, and
2595 <acronym>HMAC-SHA512</acronym>. First, the abstract functions:
2596
2597 <div class="defun">
2598 &mdash; Function: void <b>hmac_set_key</b> (<var>void *outer, void *inner, void *state, const struct nettle_hash *H, unsigned length, const uint8_t *key</var>)<var><a name="index-hmac_005fset_005fkey-259"></a></var><br>
2599 <blockquote><p>Initializes the three context structs from the key. The <var>outer</var> and
2600 <var>inner</var> contexts corresponds to the subkeys <code>k_o</code> and
2601 <code>k_i</code>. <var>state</var> is used for hashing the message, and is
2602 initialized as a copy of the <var>inner</var> context.
2603 </p></blockquote></div>
2604
2605 <div class="defun">
2606 &mdash; Function: void <b>hmac_update</b> (<var>void *state, const struct nettle_hash *H, unsigned length, const uint8_t *data</var>)<var><a name="index-hmac_005fupdate-260"></a></var><br>
2607 <blockquote><p>This function is called zero or more times to process the message.
2608 Actually, <code>hmac_update(state, H, length, data)</code> is equivalent to
2609 <code>H-&gt;update(state, length, data)</code>, so if you wish you can use the
2610 ordinary update function of the underlying hash function instead.
2611 </p></blockquote></div>
2612
2613 <div class="defun">
2614 &mdash; Function: void <b>hmac_digest</b> (<var>const void *outer, const void *inner, void *state, const struct nettle_hash *H, unsigned length, uint8_t *digest</var>)<var><a name="index-hmac_005fdigest-261"></a></var><br>
2615 <blockquote><p>Extracts the <acronym>MAC</acronym> of the message, writing it to <var>digest</var>.
2616 <var>outer</var> and <var>inner</var> are not modified. <var>length</var> is usually
2617 equal to <code>H-&gt;digest_size</code>, but if you provide a smaller value,
2618 only the first <var>length</var> octets of the <acronym>MAC</acronym> are written.
2619
2620         <p>This function also resets the <var>state</var> context so that you can start
2621 over processing a new message (with the same key).
2622 </p></blockquote></div>
2623
2624    <p>Like for <acronym>CBC</acronym>, there are some macros to help use these
2625 functions correctly.
2626
2627 <div class="defun">
2628 &mdash; Macro: <b>HMAC_CTX</b> (<var>type</var>)<var><a name="index-HMAC_005fCTX-262"></a></var><br>
2629 <blockquote><p>Expands to
2630      <pre class="example">          {
2631              type outer;
2632              type inner;
2633              type state;
2634           }
2635 </pre>
2636         </blockquote></div>
2637
2638    <p>It can be used to define a <acronym>HMAC</acronym> context struct, either
2639 directly,
2640
2641 <pre class="example">     struct HMAC_CTX(struct md5_ctx) ctx;
2642 </pre>
2643    <p>or to give it a struct tag,
2644
2645 <pre class="example">     struct hmac_md5_ctx HMAC_CTX (struct md5_ctx);
2646 </pre>
2647    <div class="defun">
2648 &mdash; Macro: <b>HMAC_SET_KEY</b> (<var>ctx, H, length, key</var>)<var><a name="index-HMAC_005fSET_005fKEY-263"></a></var><br>
2649 <blockquote><p><var>ctx</var> is a pointer to a context struct as defined by
2650 <code>HMAC_CTX</code>, <var>H</var> is a pointer to a <code>const struct
2651 nettle_hash</code> describing the underlying hash function (so it must match
2652 the type of the components of <var>ctx</var>). The last two arguments specify
2653 the secret key.
2654 </p></blockquote></div>
2655
2656 <div class="defun">
2657 &mdash; Macro: <b>HMAC_DIGEST</b> (<var>ctx, H, length, digest</var>)<var><a name="index-HMAC_005fDIGEST-264"></a></var><br>
2658 <blockquote><p><var>ctx</var> is a pointer to a context struct as defined by
2659 <code>HMAC_CTX</code>, <var>H</var> is a pointer to a <code>const struct
2660 nettle_hash</code> describing the underlying hash function. The last two
2661 arguments specify where the digest is written.
2662 </p></blockquote></div>
2663
2664    <p>Note that there is no <code>HMAC_UPDATE</code> macro; simply call
2665 <code>hmac_update</code> function directly, or the update function of the
2666 underlying hash function.
2667
2668 <h4 class="subsection">6.4.2 Concrete <acronym>HMAC</acronym> functions</h4>
2669
2670 <p>Now we come to the specialized <acronym>HMAC</acronym> functions, which are
2671 easier to use than the general <acronym>HMAC</acronym> functions.
2672
2673 <h5 class="subsubsection">6.4.2.1 <acronym>HMAC-MD5</acronym></h5>
2674
2675 <div class="defun">
2676 &mdash; Context struct: <b>struct hmac_md5_ctx</b><var><a name="index-struct-hmac_005fmd5_005fctx-265"></a></var><br>
2677      </div>
2678
2679 <div class="defun">
2680 &mdash; Function: void <b>hmac_md5_set_key</b> (<var>struct hmac_md5_ctx *ctx, unsigned key_length, const uint8_t *key</var>)<var><a name="index-hmac_005fmd5_005fset_005fkey-266"></a></var><br>
2681 <blockquote><p>Initializes the context with the key.
2682 </p></blockquote></div>
2683
2684 <div class="defun">
2685 &mdash; Function: void <b>hmac_md5_update</b> (<var>struct hmac_md5_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-hmac_005fmd5_005fupdate-267"></a></var><br>
2686 <blockquote><p>Process some more data.
2687 </p></blockquote></div>
2688
2689 <div class="defun">
2690 &mdash; Function: void <b>hmac_md5_digest</b> (<var>struct hmac_md5_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-hmac_005fmd5_005fdigest-268"></a></var><br>
2691 <blockquote><p>Extracts the <acronym>MAC</acronym>, writing it to <var>digest</var>. <var>length</var> may be smaller than
2692 <code>MD5_DIGEST_SIZE</code>, in which case only the first <var>length</var>
2693 octets of the <acronym>MAC</acronym> are written.
2694
2695         <p>This function also resets the context for processing new messages, with
2696 the same key.
2697 </p></blockquote></div>
2698
2699 <h5 class="subsubsection">6.4.2.2 <acronym>HMAC-RIPEMD160</acronym></h5>
2700
2701 <div class="defun">
2702 &mdash; Context struct: <b>struct hmac_ripemd160_ctx</b><var><a name="index-struct-hmac_005fripemd160_005fctx-269"></a></var><br>
2703      </div>
2704
2705 <div class="defun">
2706 &mdash; Function: void <b>hmac_ripemd160_set_key</b> (<var>struct hmac_ripemd160_ctx *ctx, unsigned key_length, const uint8_t *key</var>)<var><a name="index-hmac_005fripemd160_005fset_005fkey-270"></a></var><br>
2707 <blockquote><p>Initializes the context with the key.
2708 </p></blockquote></div>
2709
2710 <div class="defun">
2711 &mdash; Function: void <b>hmac_ripemd160_update</b> (<var>struct hmac_ripemd160_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-hmac_005fripemd160_005fupdate-271"></a></var><br>
2712 <blockquote><p>Process some more data.
2713 </p></blockquote></div>
2714
2715 <div class="defun">
2716 &mdash; Function: void <b>hmac_ripemd160_digest</b> (<var>struct hmac_ripemd160_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-hmac_005fripemd160_005fdigest-272"></a></var><br>
2717 <blockquote><p>Extracts the <acronym>MAC</acronym>, writing it to <var>digest</var>. <var>length</var> may be smaller than
2718 <code>RIPEMD160_DIGEST_SIZE</code>, in which case only the first <var>length</var>
2719 octets of the <acronym>MAC</acronym> are written.
2720
2721         <p>This function also resets the context for processing new messages, with
2722 the same key.
2723 </p></blockquote></div>
2724
2725 <h5 class="subsubsection">6.4.2.3 <acronym>HMAC-SHA1</acronym></h5>
2726
2727 <div class="defun">
2728 &mdash; Context struct: <b>struct hmac_sha1_ctx</b><var><a name="index-struct-hmac_005fsha1_005fctx-273"></a></var><br>
2729      </div>
2730
2731 <div class="defun">
2732 &mdash; Function: void <b>hmac_sha1_set_key</b> (<var>struct hmac_sha1_ctx *ctx, unsigned key_length, const uint8_t *key</var>)<var><a name="index-hmac_005fsha1_005fset_005fkey-274"></a></var><br>
2733 <blockquote><p>Initializes the context with the key.
2734 </p></blockquote></div>
2735
2736 <div class="defun">
2737 &mdash; Function: void <b>hmac_sha1_update</b> (<var>struct hmac_sha1_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-hmac_005fsha1_005fupdate-275"></a></var><br>
2738 <blockquote><p>Process some more data.
2739 </p></blockquote></div>
2740
2741 <div class="defun">
2742 &mdash; Function: void <b>hmac_sha1_digest</b> (<var>struct hmac_sha1_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-hmac_005fsha1_005fdigest-276"></a></var><br>
2743 <blockquote><p>Extracts the <acronym>MAC</acronym>, writing it to <var>digest</var>. <var>length</var> may be smaller than
2744 <code>SHA1_DIGEST_SIZE</code>, in which case only the first <var>length</var>
2745 octets of the <acronym>MAC</acronym> are written.
2746
2747         <p>This function also resets the context for processing new messages, with
2748 the same key.
2749 </p></blockquote></div>
2750
2751 <h5 class="subsubsection">6.4.2.4 <acronym>HMAC-SHA256</acronym></h5>
2752
2753 <div class="defun">
2754 &mdash; Context struct: <b>struct hmac_sha256_ctx</b><var><a name="index-struct-hmac_005fsha256_005fctx-277"></a></var><br>
2755      </div>
2756
2757 <div class="defun">
2758 &mdash; Function: void <b>hmac_sha256_set_key</b> (<var>struct hmac_sha256_ctx *ctx, unsigned key_length, const uint8_t *key</var>)<var><a name="index-hmac_005fsha256_005fset_005fkey-278"></a></var><br>
2759 <blockquote><p>Initializes the context with the key.
2760 </p></blockquote></div>
2761
2762 <div class="defun">
2763 &mdash; Function: void <b>hmac_sha256_update</b> (<var>struct hmac_sha256_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-hmac_005fsha256_005fupdate-279"></a></var><br>
2764 <blockquote><p>Process some more data.
2765 </p></blockquote></div>
2766
2767 <div class="defun">
2768 &mdash; Function: void <b>hmac_sha256_digest</b> (<var>struct hmac_sha256_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-hmac_005fsha256_005fdigest-280"></a></var><br>
2769 <blockquote><p>Extracts the <acronym>MAC</acronym>, writing it to <var>digest</var>. <var>length</var> may be smaller than
2770 <code>SHA256_DIGEST_SIZE</code>, in which case only the first <var>length</var>
2771 octets of the <acronym>MAC</acronym> are written.
2772
2773         <p>This function also resets the context for processing new messages, with
2774 the same key.
2775 </p></blockquote></div>
2776
2777 <h5 class="subsubsection">6.4.2.5 <acronym>HMAC-SHA512</acronym></h5>
2778
2779 <div class="defun">
2780 &mdash; Context struct: <b>struct hmac_sha512_ctx</b><var><a name="index-struct-hmac_005fsha512_005fctx-281"></a></var><br>
2781      </div>
2782
2783 <div class="defun">
2784 &mdash; Function: void <b>hmac_sha512_set_key</b> (<var>struct hmac_sha512_ctx *ctx, unsigned key_length, const uint8_t *key</var>)<var><a name="index-hmac_005fsha512_005fset_005fkey-282"></a></var><br>
2785 <blockquote><p>Initializes the context with the key.
2786 </p></blockquote></div>
2787
2788 <div class="defun">
2789 &mdash; Function: void <b>hmac_sha512_update</b> (<var>struct hmac_sha512_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-hmac_005fsha512_005fupdate-283"></a></var><br>
2790 <blockquote><p>Process some more data.
2791 </p></blockquote></div>
2792
2793 <div class="defun">
2794 &mdash; Function: void <b>hmac_sha512_digest</b> (<var>struct hmac_sha512_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-hmac_005fsha512_005fdigest-284"></a></var><br>
2795 <blockquote><p>Extracts the <acronym>MAC</acronym>, writing it to <var>digest</var>. <var>length</var> may be smaller than
2796 <code>SHA512_DIGEST_SIZE</code>, in which case only the first <var>length</var>
2797 octets of the <acronym>MAC</acronym> are written.
2798
2799         <p>This function also resets the context for processing new messages, with
2800 the same key.
2801 </p></blockquote></div>
2802
2803 <h4 class="subsection">6.4.3 <acronym>UMAC</acronym></h4>
2804
2805 <p><a name="index-UMAC-285"></a>
2806 <acronym>UMAC</acronym> is a message authentication code based on universal
2807 hashing, and designed for high performance on modern processors (in
2808 contrast to GCM, See <a href="#GCM">GCM</a>, which is designed primarily for hardware
2809 performance). On processors with good integer multiplication
2810 performance, it can be 10 times faster than SHA256 and SHA512.
2811 <acronym>UMAC</acronym> is specified in <cite>RFC 4418</cite>.
2812
2813    <p>The secret key is always 128 bits (16 octets). The key is used as an
2814 encryption key for the <acronym>AES</acronym> block cipher. This cipher is used
2815 in counter mode to generate various internal subkeys needed in
2816 <acronym>UMAC</acronym>. Messages are of arbitrary size, and for each message,
2817 <acronym>UMAC</acronym> also needs a unique nonce. Nonce values must not be
2818 reused for two messages with the same key, but they need not be kept
2819 secret.
2820
2821    <p>The nonce must be at least one octet, and at most 16; nonces shorter
2822 than 16 octets are zero-padded. Nettle's implementation of
2823 <acronym>UMAC</acronym> increments the nonce for automatically each message, so
2824 explicitly setting the nonce for each message is optional. This
2825 auto-increment uses network byte order and it takes the length of the
2826 nonce into acount. E.g., if the initial nonce is &ldquo;abc&rdquo; (3 octets),
2827 this value is zero-padded to 16 octets for the first message. For the
2828 next message, the nonce is incremented to &ldquo;abd&rdquo;, and this incremented
2829 value is zero-padded to 16 octets.
2830
2831    <p><acronym>UMAC</acronym> is defined in four variants, for different output sizes:
2832 32 bits (4 octest), 64 bits (8 octets), 96 bits (12 octets) and 128 bits
2833 (16 octets), corresponding to different tradeoffs between speed and
2834 security. Using a shorter output size sometimes (but not always!) gives
2835 the same result as using a longer output size and truncating the result.
2836 So it is important to use the right variant. For consistency with other
2837 hash and <acronym>MAC</acronym> functions, Nettle's <code>_digest</code> functions for
2838 <acronym>UMAC</acronym> accept a length parameter so that the output can be
2839 truncated to any desired size, but it is recommended to stick to the
2840 specified output size and select the <acronym>umac</acronym> variant
2841 corresponding to the desired size.
2842
2843    <p>The internal block size of <acronym>UMAC</acronym> is 1024 octets, and it also
2844 generates more than 1024 bytes of subkeys. This makes the size of the
2845 context struct a bit larger than other hash functions and <acronym>MAC</acronym>
2846 algorithms in Nettle.
2847
2848    <p>Nettle defines <acronym>UMAC</acronym> in <samp><span class="file">&lt;nettle/umac.h&gt;</span></samp>.
2849
2850 <div class="defun">
2851 &mdash; Context struct: <b>struct umac32_ctx</b><var><a name="index-struct-umac32_005fctx-286"></a></var><br>
2852 &mdash; Context struct: <b>struct umac64_ctx</b><var><a name="index-struct-umac64_005fctx-287"></a></var><br>
2853 &mdash; Context struct: <b>struct umac96_ctx</b><var><a name="index-struct-umac96_005fctx-288"></a></var><br>
2854 &mdash; Context struct: <b>struct umac128_ctx</b><var><a name="index-struct-umac128_005fctx-289"></a></var><br>
2855 <blockquote><p>Each <acronym>UMAC</acronym> variant uses its own context struct.
2856 </p></blockquote></div>
2857
2858 <div class="defun">
2859 &mdash; Constant: <b>UMAC_KEY_SIZE</b><var><a name="index-UMAC_005fKEY_005fSIZE-290"></a></var><br>
2860 <blockquote><p>The UMAC key size, 16.
2861 </p></blockquote></div>
2862
2863 <div class="defun">
2864 &mdash; Constant: <b>UMAC32_DIGEST_SIZE</b><var><a name="index-UMAC32_005fDIGEST_005fSIZE-291"></a></var><br>
2865 <blockquote><p>The size of an UMAC32 digest, 4.
2866 </p></blockquote></div>
2867
2868 <div class="defun">
2869 &mdash; Constant: <b>UMAC64_DIGEST_SIZE</b><var><a name="index-UMAC64_005fDIGEST_005fSIZE-292"></a></var><br>
2870 <blockquote><p>The size of an UMAC64 digest, 8.
2871 </p></blockquote></div>
2872
2873 <div class="defun">
2874 &mdash; Constant: <b>UMAC96_DIGEST_SIZE</b><var><a name="index-UMAC96_005fDIGEST_005fSIZE-293"></a></var><br>
2875 <blockquote><p>The size of an UMAC96 digest, 12.
2876 </p></blockquote></div>
2877
2878 <div class="defun">
2879 &mdash; Constant: <b>UMAC128_DIGEST_SIZE</b><var><a name="index-UMAC128_005fDIGEST_005fSIZE-294"></a></var><br>
2880 <blockquote><p>The size of an UMAC128 digest, 16.
2881 </p></blockquote></div>
2882
2883 <div class="defun">
2884 &mdash; Constant: <b>UMAC128_DATA_SIZE</b><var><a name="index-UMAC128_005fDATA_005fSIZE-295"></a></var><br>
2885 <blockquote><p>The internal block size of UMAC.
2886 </p></blockquote></div>
2887
2888 <div class="defun">
2889 &mdash; Function: void <b>umac32_set_key</b> (<var>struct umac32_ctx *ctx, const uint8_t *key</var>)<var><a name="index-umac32_005fset_005fkey-296"></a></var><br>
2890 &mdash; Function: void <b>umac64_set_key</b> (<var>struct umac64_ctx *ctx, const uint8_t *key</var>)<var><a name="index-umac64_005fset_005fkey-297"></a></var><br>
2891 &mdash; Function: void <b>umac96_set_key</b> (<var>struct umac96_ctx *ctx, const uint8_t *key</var>)<var><a name="index-umac96_005fset_005fkey-298"></a></var><br>
2892 &mdash; Function: void <b>umac128_set_key</b> (<var>struct umac128_ctx *ctx, const uint8_t *key</var>)<var><a name="index-umac128_005fset_005fkey-299"></a></var><br>
2893 <blockquote><p>These functions initialize the <acronym>UMAC</acronym> context struct. They also
2894 initialize the nonce to zero (with length 16, for auto-increment).
2895 </p></blockquote></div>
2896
2897 <div class="defun">
2898 &mdash; Function: void <b>umac32_set_nonce</b> (<var>struct umac32_ctx *ctx, unsigned length, const uint8_t *nonce</var>)<var><a name="index-umac32_005fset_005fnonce-300"></a></var><br>
2899 &mdash; Function: void <b>umac64_set_nonce</b> (<var>struct umac64_ctx *ctx, unsigned length, const uint8_t *nonce</var>)<var><a name="index-umac64_005fset_005fnonce-301"></a></var><br>
2900 &mdash; Function: void <b>umac96_set_nonce</b> (<var>struct umac96_ctx *ctx, unsigned length, const uint8_t *nonce</var>)<var><a name="index-umac96_005fset_005fnonce-302"></a></var><br>
2901 &mdash; Function: void <b>umac128_set_nonce</b> (<var>struct umac128_ctx *ctx, unsigned length, const uint8_t *nonce</var>)<var><a name="index-umac128_005fset_005fnonce-303"></a></var><br>
2902 <blockquote><p>Sets the nonce to be used for the next message. In general, nonces
2903 should be set before processing of the message. This is not strictly
2904 required for <acronym>UMAC</acronym> (the nonce only affects the final processing
2905 generating the digest), but it is nevertheless recommended that this
2906 function is called <em>before</em> the first <code>_update</code> call for the
2907 message.
2908 </p></blockquote></div>
2909
2910 <div class="defun">
2911 &mdash; Function: void <b>umac32_update</b> (<var>struct umac32_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-umac32_005fupdate-304"></a></var><br>
2912 &mdash; Function: void <b>umac64_update</b> (<var>struct umac64_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-umac64_005fupdate-305"></a></var><br>
2913 &mdash; Function: void <b>umac96_update</b> (<var>struct umac96_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-umac96_005fupdate-306"></a></var><br>
2914 &mdash; Function: void <b>umac128_update</b> (<var>struct umac128_ctx *ctx, unsigned length, const uint8_t *data</var>)<var><a name="index-umac128_005fupdate-307"></a></var><br>
2915 <blockquote><p>These functions are called zero or more times to process the message.
2916 </p></blockquote></div>
2917
2918 <div class="defun">
2919 &mdash; Function: void <b>umac32_digest</b> (<var>struct umac32_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-umac32_005fdigest-308"></a></var><br>
2920 &mdash; Function: void <b>umac64_digest</b> (<var>struct umac64_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-umac64_005fdigest-309"></a></var><br>
2921 &mdash; Function: void <b>umac96_digest</b> (<var>struct umac96_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-umac96_005fdigest-310"></a></var><br>
2922 &mdash; Function: void <b>umac128_digest</b> (<var>struct umac128_ctx *ctx, unsigned length, uint8_t *digest</var>)<var><a name="index-umac128_005fdigest-311"></a></var><br>
2923 <blockquote><p>Extracts the <acronym>MAC</acronym> of the message, writing it to <var>digest</var>.
2924 <var>length</var> is usually equal to the specified output size, but if you
2925 provide a smaller value, only the first <var>length</var> octets of the
2926 <acronym>MAC</acronym> are written. These functions reset the context for
2927 processing of a new message with the same key. The nonce is incremented
2928 as described above, the new value is used unless you call the
2929 <code>_set_nonce</code> function explicitly for each message.
2930 </p></blockquote></div>
2931
2932 <div class="node">
2933 <a name="Key-derivation-functions"></a>
2934 <p><hr>
2935 Next:&nbsp;<a rel="next" accesskey="n" href="#Public_002dkey-algorithms">Public-key algorithms</a>,
2936 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Keyed-hash-functions">Keyed hash functions</a>,
2937 Up:&nbsp;<a rel="up" accesskey="u" href="#Reference">Reference</a>
2938
2939 </div>
2940
2941 <!-- node-name,  next,  previous,  up -->
2942 <h3 class="section">6.5 Key derivation Functions</h3>
2943
2944 <p><a name="index-Key-Derivation-Function-312"></a><a name="index-Password-Based-Key-Derivation-Function-313"></a><a name="index-PKCS-_00235-314"></a><a name="index-KDF-315"></a><a name="index-PBKDF-316"></a>
2945 A <dfn>key derivation function</dfn> (<acronym>KDF</acronym>) is a function that from
2946 a given symmetric key derives other symmetric keys.  A sub-class of KDFs
2947 is the <dfn>password-based key derivation functions</dfn> (<acronym>PBKDFs</acronym>),
2948 which take as input a password or passphrase, and its purpose is
2949 typically to strengthen it and protect against certain pre-computation
2950 attacks by using salting and expensive computation.
2951
2952 <h4 class="subsection">6.5.1 <acronym>PBKDF2</acronym></h4>
2953
2954 <p>The most well known PBKDF is the <code>PKCS #5 PBKDF2</code> described in
2955 <cite>RFC 2898</cite> which uses a pseudo-random function such as
2956 <acronym>HMAC-SHA1</acronym>.
2957
2958    <p>Nettle's <acronym>PBKDF2</acronym> functions are defined in
2959 <samp><span class="file">&lt;nettle/pbkdf2.h&gt;</span></samp>.  There is an abstract function that operate on
2960 any PRF implemented via the <code>nettle_hash_update_func</code>,
2961 <code>nettle_hash_digest_func</code> interfaces.  There is also helper macros
2962 and concrete functions PBKDF2-HMAC-SHA1 and PBKDF2-HMAC-SHA256.  First,
2963 the abstract function:
2964
2965 <div class="defun">
2966 &mdash; Function: void <b>pbkdf2</b> (<var>void *mac_ctx, nettle_hash_update_func *update, nettle_hash_digest_func *digest, unsigned digest_size, unsigned iterations, unsigned salt_length, const uint8_t *salt, unsigned length, uint8_t *dst</var>)<var><a name="index-pbkdf2-317"></a></var><br>
2967 <blockquote><p>Derive symmetric key from a password according to PKCS #5 PBKDF2.  The
2968 PRF is assumed to have been initialized and this function will call the
2969 <var>update</var> and <var>digest</var> functions passing the <var>mac_ctx</var>
2970 context parameter as an argument in order to compute digest of size
2971 <var>digest_size</var>.  Inputs are the salt <var>salt</var> of length
2972 <var>salt_length</var>, the iteration counter <var>iterations</var> (&gt; 0), and the
2973 desired derived output length <var>length</var>.  The output buffer is
2974 <var>dst</var> which must have room for at least <var>length</var> octets.
2975 </p></blockquote></div>
2976
2977    <p>Like for CBC and HMAC, there is a macro to help use the function
2978 correctly.
2979
2980 <div class="defun">
2981 &mdash; Macro: <b>PBKDF2</b> (<var>ctx, update, digest, digest_size, iterations, salt_length, salt, length, dst</var>)<var><a name="index-PBKDF2-318"></a></var><br>
2982 <blockquote><p><var>ctx</var> is a pointer to a context struct passed to the <var>update</var>
2983 and <var>digest</var> functions (of the types <code>nettle_hash_update_func</code>
2984 and <code>nettle_hash_digest_func</code> respectively) to implement the
2985 underlying PRF with digest size of <var>digest_size</var>.  Inputs are the
2986 salt <var>salt</var> of length <var>salt_length</var>, the iteration counter
2987 <var>iterations</var> (&gt; 0), and the desired derived output length
2988 <var>length</var>.  The output buffer is <var>dst</var> which must have room for
2989 at least <var>length</var> octets.
2990 </p></blockquote></div>
2991
2992 <h4 class="subsection">6.5.2 Concrete <acronym>PBKDF2</acronym> functions</h4>
2993
2994 <p>Now we come to the specialized <acronym>PBKDF2</acronym> functions, which are
2995 easier to use than the general <acronym>PBKDF2</acronym> function.
2996
2997 <h5 class="subsubsection">6.5.2.1 <acronym>PBKDF2-HMAC-SHA1</acronym></h5>
2998
2999 <div class="defun">
3000 &mdash; Function: void <b>pbkdf2_hmac_sha1</b> (<var>unsigned key_length, const uint8_t *key, unsigned iterations, unsigned salt_length, const uint8_t *salt, unsigned length, uint8_t *dst</var>)<var><a name="index-pbkdf2_005fhmac_005fsha1-319"></a></var><br>
3001 <blockquote><p>PBKDF2 with HMAC-SHA1.  Derive <var>length</var> bytes of key into buffer
3002 <var>dst</var> using the password <var>key</var> of length <var>key_length</var> and
3003 salt <var>salt</var> of length <var>salt_length</var>, with iteration counter
3004 <var>iterations</var> (&gt; 0).  The output buffer is <var>dst</var> which must have
3005 room for at least <var>length</var> octets.
3006 </p></blockquote></div>
3007
3008 <h5 class="subsubsection">6.5.2.2 <acronym>PBKDF2-HMAC-SHA256</acronym></h5>
3009
3010 <div class="defun">
3011 &mdash; Function: void <b>pbkdf2_hmac_sha256</b> (<var>unsigned key_length, const uint8_t *key, unsigned iterations, unsigned salt_length, const uint8_t *salt, unsigned length, uint8_t *dst</var>)<var><a name="index-pbkdf2_005fhmac_005fsha256-320"></a></var><br>
3012 <blockquote><p>PBKDF2 with HMAC-SHA256.  Derive <var>length</var> bytes of key into buffer
3013 <var>dst</var> using the password <var>key</var> of length <var>key_length</var> and
3014 salt <var>salt</var> of length <var>salt_length</var>, with iteration counter
3015 <var>iterations</var> (&gt; 0).  The output buffer is <var>dst</var> which must have
3016 room for at least <var>length</var> octets.
3017 </p></blockquote></div>
3018
3019 <div class="node">
3020 <a name="Public-key-algorithms"></a>
3021 <a name="Public_002dkey-algorithms"></a>
3022 <p><hr>
3023 Next:&nbsp;<a rel="next" accesskey="n" href="#Randomness">Randomness</a>,
3024 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Key-derivation-functions">Key derivation functions</a>,
3025 Up:&nbsp;<a rel="up" accesskey="u" href="#Reference">Reference</a>
3026
3027 </div>
3028
3029 <!-- node-name,  next,  previous,  up -->
3030 <h3 class="section">6.6 Public-key algorithms</h3>
3031
3032 <p>Nettle uses <acronym>GMP</acronym>, the GNU bignum library, for all calculations
3033 with large numbers. In order to use the public-key features of Nettle,
3034 you must install <acronym>GMP</acronym>, at least version 3.0, before compiling
3035 Nettle, and you need to link your programs with <code>-lhogweed -lnettle
3036 -lgmp</code>.
3037
3038    <p>The concept of <dfn>Public-key</dfn> encryption and digital signatures was
3039 discovered by Whitfield Diffie and Martin E. Hellman and described in a
3040 paper 1976. In traditional, &ldquo;symmetric&rdquo;, cryptography, sender and
3041 receiver share the same keys, and these keys must be distributed in a
3042 secure way. And if there are many users or entities that need to
3043 communicate, each <em>pair</em> needs a shared secret key known by nobody
3044 else.
3045
3046    <p><a name="index-Public-Key-Cryptography-321"></a><a name="index-One_002dway-function-322"></a>
3047 Public-key cryptography uses trapdoor one-way functions. A
3048 <dfn>one-way function</dfn> is a function <code>F</code> such that it is easy to
3049 compute the value <code>F(x)</code> for any <code>x</code>, but given a value
3050 <code>y</code>, it is hard to compute a corresponding <code>x</code> such that
3051 <code>y = F(x)</code>. Two examples are cryptographic hash functions, and
3052 exponentiation in certain groups.
3053
3054    <p>A <dfn>trapdoor one-way function</dfn> is a function <code>F</code> that is
3055 one-way, unless one knows some secret information about <code>F</code>. If one
3056 knows the secret, it is easy to compute both <code>F</code> and it's inverse.
3057 If this sounds strange, look at the <acronym>RSA</acronym> example below.
3058
3059    <p>Two important uses for one-way functions with trapdoors are public-key
3060 encryption, and digital signatures. The public-key encryption functions
3061 in Nettle are not yet documented; the rest of this chapter is about
3062 digital signatures.
3063
3064    <p>To use a digital signature algorithm, one must first create a
3065 <dfn>key-pair</dfn>: A public key and a corresponding private key. The private
3066 key is used to sign messages, while the public key is used for verifying
3067 that that signatures and messages match. Some care must be taken when
3068 distributing the public key; it need not be kept secret, but if a bad
3069 guy is able to replace it (in transit, or in some user's list of known
3070 public keys), bad things may happen.
3071
3072    <p>There are two operations one can do with the keys. The signature
3073 operation takes a message and a private key, and creates a signature for
3074 the message. A signature is some string of bits, usually at most a few
3075 thousand bits or a few hundred octets. Unlike paper-and-ink signatures,
3076 the digital signature depends on the message, so one can't cut it out of
3077 context and glue it to a different message.
3078
3079    <p>The verification operation takes a public key, a message, and a string
3080 that is claimed to be a signature on the message, and returns true or
3081 false. If it returns true, that means that the three input values
3082 matched, and the verifier can be sure that someone went through with the
3083 signature operation on that very message, and that the &ldquo;someone&rdquo; also
3084 knows the private key corresponding to the public key.
3085
3086    <p>The desired properties of a digital signature algorithm are as follows:
3087 Given the public key and pairs of messages and valid signatures on them,
3088 it should be hard to compute the private key, and it should also be hard
3089 to create a new message and signature that is accepted by the
3090 verification operation.
3091
3092    <p>Besides signing meaningful messages, digital signatures can be used for
3093 authorization. A server can be configured with a public key, such that
3094 any client that connects to the service is given a random nonce message.
3095 If the server gets a reply with a correct signature matching the nonce
3096 message and the configured public key, the client is granted access. So
3097 the configuration of the server can be understood as &ldquo;grant access to
3098 whoever knows the private key corresponding to this particular public
3099 key, and to no others&rdquo;.
3100
3101 <ul class="menu">
3102 <li><a accesskey="1" href="#RSA">RSA</a>:                          The RSA public key algorithm.
3103 <li><a accesskey="2" href="#DSA">DSA</a>:                          The DSA digital signature algorithm.
3104 <li><a accesskey="3" href="#Elliptic-curves">Elliptic curves</a>:              Elliptic curves and ECDSA
3105 </ul>
3106
3107 <div class="node">
3108 <a name="RSA"></a>
3109 <p><hr>
3110 Next:&nbsp;<a rel="next" accesskey="n" href="#DSA">DSA</a>,
3111 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Public_002dkey-algorithms">Public-key algorithms</a>,
3112 Up:&nbsp;<a rel="up" accesskey="u" href="#Public_002dkey-algorithms">Public-key algorithms</a>
3113
3114 </div>
3115
3116 <!-- node-name,  next,  previous,  up -->
3117 <h4 class="subsection">6.6.1 <acronym>RSA</acronym></h4>
3118
3119 <p>The <acronym>RSA</acronym> algorithm was the first practical digital signature
3120 algorithm that was constructed. It was described 1978 in a paper by
3121 Ronald Rivest, Adi Shamir and L.M. Adleman, and the technique was also
3122 patented in the <acronym>USA</acronym> in 1983. The patent expired on September 20, 2000, and since
3123 that day, <acronym>RSA</acronym> can be used freely, even in the <acronym>USA</acronym>.
3124
3125    <p>It's remarkably simple to describe the trapdoor function behind
3126 <acronym>RSA</acronym>. The &ldquo;one-way&rdquo;-function used is
3127
3128 <pre class="example">     F(x) = x^e mod n
3129 </pre>
3130    <p>I.e. raise x to the <code>e</code>'th power, while discarding all multiples of
3131 <code>n</code>. The pair of numbers <code>n</code> and <code>e</code> is the public key.
3132 <code>e</code> can be quite small, even <code>e = 3</code> has been used, although
3133 slightly larger numbers are recommended. <code>n</code> should be about 1000
3134 bits or larger.
3135
3136    <p>If <code>n</code> is large enough, and properly chosen, the inverse of F,
3137 the computation of <code>e</code>'th roots modulo <code>n</code>, is very difficult.
3138 But, where's the trapdoor?
3139
3140    <p>Let's first look at how <acronym>RSA</acronym> key-pairs are generated. First
3141 <code>n</code> is chosen as the product of two large prime numbers <code>p</code>
3142 and <code>q</code> of roughly the same size (so if <code>n</code> is 1000 bits,
3143 <code>p</code> and <code>q</code> are about 500 bits each). One also computes the
3144 number <code>phi = (p-1)(q-1)</code>, in mathematical speak, <code>phi</code> is the
3145 order of the multiplicative group of integers modulo n.
3146
3147    <p>Next, <code>e</code> is chosen. It must have no factors in common with <code>phi</code> (in
3148 particular, it must be odd), but can otherwise be chosen more or less
3149 randomly. <code>e = 65537</code> is a popular choice, because it makes raising
3150 to the <code>e</code>'th power particularly efficient, and being prime, it
3151 usually has no factors common with <code>phi</code>.
3152
3153    <p>Finally, a number <code>d</code>, <code>d &lt; n</code> is computed such that <code>e d
3154 mod phi = 1</code>. It can be shown that such a number exists (this is why
3155 <code>e</code> and <code>phi</code> must have no common factors), and that for all x,
3156
3157 <pre class="example">     (x^e)^d mod n = x^(ed) mod n = (x^d)^e mod n = x
3158 </pre>
3159    <p>Using Euclid's algorithm, <code>d</code> can be computed quite easily from
3160 <code>phi</code> and <code>e</code>. But it is still hard to get <code>d</code> without
3161 knowing <code>phi</code>, which depends on the factorization of <code>n</code>.
3162
3163    <p>So <code>d</code> is the trapdoor, if we know <code>d</code> and <code>y = F(x)</code>, we can
3164 recover x as <code>y^d mod n</code>. <code>d</code> is also the private half of
3165 the <acronym>RSA</acronym> key-pair.
3166
3167    <p>The most common signature operation for <acronym>RSA</acronym> is defined in
3168 <cite>PKCS#1</cite>, a specification by RSA Laboratories. The message to be
3169 signed is first hashed using a cryptographic hash function, e.g.
3170 <acronym>MD5</acronym> or <acronym>SHA1</acronym>. Next, some padding, the <acronym>ASN.1</acronym>
3171 &ldquo;Algorithm Identifier&rdquo; for the hash function, and the message digest
3172 itself, are concatenated and converted to a number <code>x</code>. The
3173 signature is computed from <code>x</code> and the private key as <code>s = x^d
3174 mod n</code><a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a>. The signature, <code>s</code> is a
3175 number of about the same size of <code>n</code>, and it usually encoded as a
3176 sequence of octets, most significant octet first.
3177
3178    <p>The verification operation is straight-forward, <code>x</code> is computed
3179 from the message in the same way as above. Then <code>s^e mod n</code> is
3180 computed, the operation returns true if and only if the result equals
3181 <code>x</code>.
3182
3183 <h4 class="subsection">6.6.2 Nettle's <acronym>RSA</acronym> support</h4>
3184
3185 <p>Nettle represents <acronym>RSA</acronym> keys using two structures that contain
3186 large numbers (of type <code>mpz_t</code>).
3187
3188 <div class="defun">
3189 &mdash; Context struct: <b>rsa_public_key</b><var> size n e<a name="index-rsa_005fpublic_005fkey-323"></a></var><br>
3190 <blockquote><p><code>size</code> is the size, in octets, of the modulo, and is used internally.
3191 <code>n</code> and <code>e</code> is the public key.
3192 </p></blockquote></div>
3193
3194 <div class="defun">
3195 &mdash; Context struct: <b>rsa_private_key</b><var> size d p q a b c<a name="index-rsa_005fprivate_005fkey-324"></a></var><br>
3196 <blockquote><p><code>size</code> is the size, in octets, of the modulo, and is used internally.
3197 <code>d</code> is the secret exponent, but it is not actually used when
3198 signing. Instead, the factors <code>p</code> and <code>q</code>, and the parameters
3199 <code>a</code>, <code>b</code> and <code>c</code> are used. They are computed from <code>p</code>,
3200 <code>q</code> and <code>e</code> such that <code>a e mod (p - 1) = 1, b e mod (q -
3201 1) = 1, c q mod p = 1</code>.
3202 </p></blockquote></div>
3203
3204    <p>Before use, these structs must be initialized by calling one of
3205
3206 <div class="defun">
3207 &mdash; Function: void <b>rsa_public_key_init</b> (<var>struct rsa_public_key *pub</var>)<var><a name="index-rsa_005fpublic_005fkey_005finit-325"></a></var><br>
3208 &mdash; Function: void <b>rsa_private_key_init</b> (<var>struct rsa_private_key *key</var>)<var><a name="index-rsa_005fprivate_005fkey_005finit-326"></a></var><br>
3209 <blockquote><p>Calls <code>mpz_init</code> on all numbers in the key struct.
3210 </p></blockquote></div>
3211
3212    <p>and when finished with them, the space for the numbers must be
3213 deallocated by calling one of
3214
3215 <div class="defun">
3216 &mdash; Function: void <b>rsa_public_key_clear</b> (<var>struct rsa_public_key *pub</var>)<var><a name="index-rsa_005fpublic_005fkey_005fclear-327"></a></var><br>
3217 &mdash; Function: void <b>rsa_private_key_clear</b> (<var>struct rsa_private_key *key</var>)<var><a name="index-rsa_005fprivate_005fkey_005fclear-328"></a></var><br>
3218 <blockquote><p>Calls <code>mpz_clear</code> on all numbers in the key struct.
3219 </p></blockquote></div>
3220
3221    <p>In general, Nettle's <acronym>RSA</acronym> functions deviates from Nettle's &ldquo;no
3222 memory allocation&rdquo;-policy. Space for all the numbers, both in the key structs
3223 above, and temporaries, are allocated dynamically. For information on how
3224 to customize allocation, see
3225 See <a href="gmp.html#Custom-Allocation">GMP Allocation</a>.
3226
3227    <p>When you have assigned values to the attributes of a key, you must call
3228
3229 <div class="defun">
3230 &mdash; Function: int <b>rsa_public_key_prepare</b> (<var>struct rsa_public_key *pub</var>)<var><a name="index-rsa_005fpublic_005fkey_005fprepare-329"></a></var><br>
3231 &mdash; Function: int <b>rsa_private_key_prepare</b> (<var>struct rsa_private_key *key</var>)<var><a name="index-rsa_005fprivate_005fkey_005fprepare-330"></a></var><br>
3232 <blockquote><p>Computes the octet size of the key (stored in the <code>size</code> attribute,
3233 and may also do other basic sanity checks. Returns one if successful, or
3234 zero if the key can't be used, for instance if the modulo is smaller
3235 than the minimum size needed for <acronym>RSA</acronym> operations specified by PKCS#1.
3236 </p></blockquote></div>
3237
3238    <p>Before signing or verifying a message, you first hash it with the
3239 appropriate hash function. You pass the hash function's context struct
3240 to the <acronym>RSA</acronym> signature function, and it will extract the message
3241 digest and do the rest of the work. There are also alternative functions
3242 that take the hash digest as argument.
3243
3244    <p>There is currently no support for using SHA224 or SHA384 with
3245 <acronym>RSA</acronym> signatures, since there's no gain in either computation
3246 time nor message size compared to using SHA256 and SHA512, respectively.
3247
3248    <p>Creation and verification of signatures is done with the following functions:
3249
3250 <div class="defun">
3251 &mdash; Function: int <b>rsa_md5_sign</b> (<var>const struct rsa_private_key *key, struct md5_ctx *hash, mpz_t signature</var>)<var><a name="index-rsa_005fmd5_005fsign-331"></a></var><br>
3252 &mdash; Function: int <b>rsa_sha1_sign</b> (<var>const struct rsa_private_key *key, struct sha1_ctx *hash, mpz_t signature</var>)<var><a name="index-rsa_005fsha1_005fsign-332"></a></var><br>
3253 &mdash; Function: int <b>rsa_sha256_sign</b> (<var>const struct rsa_private_key *key, struct sha256_ctx *hash, mpz_t signature</var>)<var><a name="index-rsa_005fsha256_005fsign-333"></a></var><br>
3254 &mdash; Function: int <b>rsa_sha512_sign</b> (<var>const struct rsa_private_key *key, struct sha512_ctx *hash, mpz_t signature</var>)<var><a name="index-rsa_005fsha512_005fsign-334"></a></var><br>
3255 <blockquote><p>The signature is stored in <var>signature</var> (which must have been
3256 <code>mpz_init</code>'ed earlier). The hash context is reset so that it can be
3257 used for new messages. Returns one on success, or zero on failure.
3258 Signing fails if the key is too small for the given hash size, e.g.,
3259 it's not possible to create a signature using SHA512 and a 512-bit
3260 <acronym>RSA</acronym> key.
3261 </p></blockquote></div>
3262
3263 <div class="defun">
3264 &mdash; Function: int <b>rsa_md5_sign_digest</b> (<var>const struct rsa_private_key *key, const uint8_t *digest, mpz_t signature</var>)<var><a name="index-rsa_005fmd5_005fsign_005fdigest-335"></a></var><br>
3265 &mdash; Function: int <b>rsa_sha1_sign_digest</b> (<var>const struct rsa_private_key *key, const uint8_t *digest, mpz_t signature</var>)<var>;<a name="index-rsa_005fsha1_005fsign_005fdigest-336"></a></var><br>
3266 &mdash; Function: int <b>rsa_sha256_sign_digest</b> (<var>const struct rsa_private_key *key, const uint8_t *digest, mpz_t signature</var>)<var>;<a name="index-rsa_005fsha256_005fsign_005fdigest-337"></a></var><br>
3267 &mdash; Function: int <b>rsa_sha512_sign_digest</b> (<var>const struct rsa_private_key *key, const uint8_t *digest, mpz_t signature</var>)<var>;<a name="index-rsa_005fsha512_005fsign_005fdigest-338"></a></var><br>
3268 <blockquote><p>Creates a signature from the given hash digest. <var>digest</var> should
3269 point to a digest of size <code>MD5_DIGEST_SIZE</code>,
3270 <code>SHA1_DIGEST_SIZE</code>, or <code>SHA256_DIGEST_SIZE</code>, respectively. The
3271 signature is stored in <var>signature</var> (which must have been
3272 <code>mpz_init</code>:ed earlier). Returns one on success, or zero on failure.
3273 </p></blockquote></div>
3274
3275 <div class="defun">
3276 &mdash; Function: int <b>rsa_md5_verify</b> (<var>const struct rsa_public_key *key, struct md5_ctx *hash, const mpz_t signature</var>)<var><a name="index-rsa_005fmd5_005fverify-339"></a></var><br>
3277 &mdash; Function: int <b>rsa_sha1_verify</b> (<var>const struct rsa_public_key *key, struct sha1_ctx *hash, const mpz_t signature</var>)<var><a name="index-rsa_005fsha1_005fverify-340"></a></var><br>
3278 &mdash; Function: int <b>rsa_sha256_verify</b> (<var>const struct rsa_public_key *key, struct sha256_ctx *hash, const mpz_t signature</var>)<var><a name="index-rsa_005fsha256_005fverify-341"></a></var><br>
3279 &mdash; Function: int <b>rsa_sha512_verify</b> (<var>const struct rsa_public_key *key, struct sha512_ctx *hash, const mpz_t signature</var>)<var><a name="index-rsa_005fsha512_005fverify-342"></a></var><br>
3280 <blockquote><p>Returns 1 if the signature is valid, or 0 if it isn't. In either case,
3281 the hash context is reset so that it can be used for new messages.
3282 </p></blockquote></div>
3283
3284 <div class="defun">
3285 &mdash; Function: int <b>rsa_md5_verify_digest</b> (<var>const struct rsa_public_key *key, const uint8_t *digest, const mpz_t signature</var>)<var><a name="index-rsa_005fmd5_005fverify_005fdigest-343"></a></var><br>
3286 &mdash; Function: int <b>rsa_sha1_verify_digest</b> (<var>const struct rsa_public_key *key, const uint8_t *digest, const mpz_t signature</var>)<var><a name="index-rsa_005fsha1_005fverify_005fdigest-344"></a></var><br>
3287 &mdash; Function: int <b>rsa_sha256_verify_digest</b> (<var>const struct rsa_public_key *key, const uint8_t *digest, const mpz_t signature</var>)<var><a name="index-rsa_005fsha256_005fverify_005fdigest-345"></a></var><br>
3288 &mdash; Function: int <b>rsa_sha512_verify_digest</b> (<var>const struct rsa_public_key *key, const uint8_t *digest, const mpz_t signature</var>)<var><a name="index-rsa_005fsha512_005fverify_005fdigest-346"></a></var><br>
3289 <blockquote><p>Returns 1 if the signature is valid, or 0 if it isn't. <var>digest</var> should
3290 point to a digest of size <code>MD5_DIGEST_SIZE</code>,
3291 <code>SHA1_DIGEST_SIZE</code>, or <code>SHA256_DIGEST_SIZE</code>, respectively.
3292 </p></blockquote></div>
3293
3294    <p>If you need to use the <acronym>RSA</acronym> trapdoor, the private key, in a way
3295 that isn't supported by the above functions Nettle also includes a
3296 function that computes <code>x^d mod n</code> and nothing more, using the
3297 <acronym>CRT</acronym> optimization.
3298
3299 <div class="defun">
3300 &mdash; Function: void <b>rsa_compute_root</b> (<var>struct rsa_private_key *key, mpz_t x, const mpz_t m</var>)<var><a name="index-rsa_005fcompute_005froot-347"></a></var><br>
3301 <blockquote><p>Computes <code>x = m^d</code>, efficiently.
3302 </p></blockquote></div>
3303
3304    <p>At last, how do you create new keys?
3305
3306 <div class="defun">
3307 &mdash; Function: int <b>rsa_generate_keypair</b> (<var>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</var>)<var>;<a name="index-rsa_005fgenerate_005fkeypair-348"></a></var><br>
3308 <blockquote><p>There are lots of parameters. <var>pub</var> and <var>key</var> is where the
3309 resulting key pair is stored. The structs should be initialized, but you
3310 don't need to call <code>rsa_public_key_prepare</code> or
3311 <code>rsa_private_key_prepare</code> after key generation.
3312
3313         <p><var>random_ctx</var> and <var>random</var> is a randomness generator.
3314 <code>random(random_ctx, length, dst)</code> should generate <code>length</code>
3315 random octets and store them at <code>dst</code>. For advice, see
3316 See <a href="#Randomness">Randomness</a>.
3317
3318         <p><var>progress</var> and <var>progress_ctx</var> can be used to get callbacks
3319 during the key generation process, in order to uphold an illusion of
3320 progress. <var>progress</var> can be NULL, in that case there are no
3321 callbacks.
3322
3323         <p><var>size_n</var> is the desired size of the modulo, in bits. If <var>size_e</var>
3324 is non-zero, it is the desired size of the public exponent and a random
3325 exponent of that size is selected. But if <var>e_size</var> is zero, it is
3326 assumed that the caller has already chosen a value for <code>e</code>, and
3327 stored it in <var>pub</var>.
3328 Returns one on success, and zero on failure. The function can fail for
3329 example if if <var>n_size</var> is too small, or if <var>e_size</var> is zero and
3330 <code>pub-&gt;e</code> is an even number.
3331 </p></blockquote></div>
3332
3333 <div class="node">
3334 <a name="DSA"></a>
3335 <p><hr>
3336 Next:&nbsp;<a rel="next" accesskey="n" href="#Elliptic-curves">Elliptic curves</a>,
3337 Previous:&nbsp;<a rel="previous" accesskey="p" href="#RSA">RSA</a>,
3338 Up:&nbsp;<a rel="up" accesskey="u" href="#Public_002dkey-algorithms">Public-key algorithms</a>
3339
3340 </div>
3341
3342 <!-- node-name,  next,  previous,  up -->
3343 <h4 class="subsection">6.6.3 <acronym>DSA</acronym></h4>
3344
3345 <p>The <acronym>DSA</acronym> digital signature algorithm is more complex than
3346 <acronym>RSA</acronym>. It was specified during the early 1990s, and in 1994 NIST
3347 published <acronym>FIPS</acronym> 186 which is the authoritative specification.
3348 Sometimes <acronym>DSA</acronym> is referred to using the acronym <acronym>DSS</acronym>,
3349 for Digital Signature Standard. The most recent revision of the
3350 specification, FIPS186-3, was issued in 2009, and it adds support for
3351 larger hash functions than <acronym>sha1</acronym>.
3352
3353    <p>For <acronym>DSA</acronym>, the underlying mathematical problem is the
3354 computation of discrete logarithms. The public key consists of a large
3355 prime <code>p</code>, a small prime <code>q</code> which is a factor of <code>p-1</code>,
3356 a number <code>g</code> which generates a subgroup of order <code>q</code> modulo
3357 <code>p</code>, and an element <code>y</code> in that subgroup.
3358
3359    <p>In the original <acronym>DSA</acronym>, the size of <code>q</code> is fixed to 160
3360 bits, to match with the <acronym>SHA1</acronym> hash algorithm. The size of
3361 <code>p</code> is in principle unlimited, but the
3362 standard specifies only nine specific sizes: <code>512 + l*64</code>, where
3363 <code>l</code> is between 0 and 8. Thus, the maximum size of <code>p</code> is 1024
3364 bits, and sizes less than 1024 bits are considered obsolete and not
3365 secure.
3366
3367    <p>The subgroup requirement means that if you compute
3368
3369 <pre class="example">     g^t mod p
3370 </pre>
3371    <p>for all possible integers <code>t</code>, you will get precisely <code>q</code>
3372 distinct values.
3373
3374    <p>The private key is a secret exponent <code>x</code>, such that
3375
3376 <pre class="example">     g^x = y mod p
3377 </pre>
3378    <p>In mathematical speak, <code>x</code> is the <dfn>discrete logarithm</dfn> of
3379 <code>y</code> mod <code>p</code>, with respect to the generator <code>g</code>. The size
3380 of <code>x</code> will also be about the same size as <code>q</code>. The security of the
3381 <acronym>DSA</acronym> algorithm relies on the difficulty of the discrete
3382 logarithm problem. Current algorithms to compute discrete logarithms in
3383 this setting, and hence crack <acronym>DSA</acronym>, are of two types. The first
3384 type works directly in the (multiplicative) group of integers mod
3385 <code>p</code>. The best known algorithm of this type is the Number Field
3386 Sieve, and it's complexity is similar to the complexity of factoring
3387 numbers of the same size as <code>p</code>. The other type works in the
3388 smaller <code>q</code>-sized subgroup generated by <code>g</code>, which has a more
3389 difficult group structure. One good algorithm is Pollard-rho, which has
3390 complexity <code>sqrt(q)</code>.
3391
3392    <p>The important point is that security depends on the size of <em>both</em>
3393 <code>p</code> and <code>q</code>, and they should be chosen so that the difficulty
3394 of both discrete logarithm methods are comparable. Today, the security
3395 margin of the original <acronym>DSA</acronym> may be uncomfortably small. Using a
3396 <code>p</code> of 1024 bits implies that cracking using the number field sieve
3397 is expected to take about the same time as factoring a 1024-bit
3398 <acronym>RSA</acronym> modulo, and using a <code>q</code> of size 160 bits implies
3399 that cracking using Pollard-rho will take roughly <code>2^80</code> group
3400 operations. With the size of <code>q</code> fixed, tied to the <acronym>SHA1</acronym>
3401 digest size, it may be tempting to increase the size of <code>p</code> to,
3402 say, 4096 bits. This will provide excellent resistance against attacks
3403 like the number field sieve which works in the large group. But it will
3404 do very little to defend against Pollard-rho attacking the small
3405 subgroup; the attacker is slowed down at most by a single factor of 10
3406 due to the more expensive group operation. And the attacker will surely
3407 choose the latter attack.
3408
3409    <p>The signature generation algorithm is randomized; in order to create a
3410 <acronym>DSA</acronym> signature, you need a good source for random numbers
3411 (see <a href="#Randomness">Randomness</a>). Let us describe the common case of a 160-bit
3412 <code>q</code>.
3413
3414    <p>To create a signature, one starts with the hash digest of the message,
3415 <code>h</code>, which is a 160 bit number, and a random number <code>k,
3416 0&lt;k&lt;q</code>, also 160 bits. Next, one computes
3417
3418 <pre class="example">     r = (g^k mod p) mod q
3419      s = k^-1 (h + x r) mod q
3420 </pre>
3421    <p>The signature is the pair <code>(r, s)</code>, two 160 bit numbers. Note the
3422 two different mod operations when computing <code>r</code>, and the use of the
3423 secret exponent <code>x</code>.
3424
3425    <p>To verify a signature, one first checks that <code>0 &lt; r,s &lt; q</code>, and
3426 then one computes backwards,
3427
3428 <pre class="example">     w = s^-1 mod q
3429      v = (g^(w h) y^(w r) mod p) mod q
3430 </pre>
3431    <p>The signature is valid if <code>v = r</code>. This works out because <code>w =
3432 s^-1 mod q = k (h + x r)^-1 mod q</code>, so that
3433
3434 <pre class="example">     g^(w h) y^(w r) = g^(w h) (g^x)^(w r) = g^(w (h + x r)) = g^k
3435 </pre>
3436    <p>When reducing mod <code>q</code> this yields <code>r</code>. Note that when
3437 verifying a signature, we don't know either <code>k</code> or <code>x</code>: those
3438 numbers are secret.
3439
3440    <p>If you can choose between <acronym>RSA</acronym> and <acronym>DSA</acronym>, which one is
3441 best? Both are believed to be secure. <acronym>DSA</acronym> gained popularity in
3442 the late 1990s, as a patent free alternative to <acronym>RSA</acronym>. Now that
3443 the <acronym>RSA</acronym> patents have expired, there's no compelling reason to
3444 want to use <acronym>DSA</acronym>. Today, the original <acronym>DSA</acronym> key size
3445 does not provide a large security margin, and it should probably be
3446 phased out together with <acronym>RSA</acronym> keys of 1024 bits. Using the
3447 revised <acronym>DSA</acronym> algorithm with a larger hash function, in
3448 particular, <acronym>SHA256</acronym>, a 256-bit <code>q</code>, and <code>p</code> of size
3449 2048 bits or more, should provide for a more comfortable security
3450 margin, but these variants are not yet in wide use.
3451
3452    <p><acronym>DSA</acronym> signatures are smaller than <acronym>RSA</acronym> signatures,
3453 which is important for some specialized applications.
3454
3455    <p>From a practical point of view, <acronym>DSA</acronym>'s need for a good
3456 randomness source is a serious disadvantage. If you ever use the same
3457 <code>k</code> (and <code>r</code>) for two different message, you leak your private
3458 key.
3459
3460 <h4 class="subsection">6.6.4 Nettle's <acronym>DSA</acronym> support</h4>
3461
3462 <p>Like for <acronym>RSA</acronym>, Nettle represents <acronym>DSA</acronym> keys using two
3463 structures, containing values of type <code>mpz_t</code>. For information on
3464 how to customize allocation, see See <a href="gmp.html#Custom-Allocation">GMP Allocation</a>.
3465
3466    <p>Most of the <acronym>DSA</acronym> functions are very similar to the
3467 corresponding <acronym>RSA</acronym> functions, but there are a few differences
3468 pointed out below. For a start, there are no functions corresponding to
3469 <code>rsa_public_key_prepare</code> and <code>rsa_private_key_prepare</code>.
3470
3471 <div class="defun">
3472 &mdash; Context struct: <b>dsa_public_key</b><var> p q g y<a name="index-dsa_005fpublic_005fkey-349"></a></var><br>
3473 <blockquote><p>The public parameters described above.
3474 </p></blockquote></div>
3475
3476 <div class="defun">
3477 &mdash; Context struct: <b>dsa_private_key</b><var> x<a name="index-dsa_005fprivate_005fkey-350"></a></var><br>
3478 <blockquote><p>The private key <code>x</code>.
3479 </p></blockquote></div>
3480
3481    <p>Before use, these structs must be initialized by calling one of
3482
3483 <div class="defun">
3484 &mdash; Function: void <b>dsa_public_key_init</b> (<var>struct dsa_public_key *pub</var>)<var><a name="index-dsa_005fpublic_005fkey_005finit-351"></a></var><br>
3485 &mdash; Function: void <b>dsa_private_key_init</b> (<var>struct dsa_private_key *key</var>)<var><a name="index-dsa_005fprivate_005fkey_005finit-352"></a></var><br>
3486 <blockquote><p>Calls <code>mpz_init</code> on all numbers in the key struct.
3487 </p></blockquote></div>
3488
3489    <p>When finished with them, the space for the numbers must be
3490 deallocated by calling one of
3491
3492 <div class="defun">
3493 &mdash; Function: void <b>dsa_public_key_clear</b> (<var>struct dsa_public_key *pub</var>)<var><a name="index-dsa_005fpublic_005fkey_005fclear-353"></a></var><br>
3494 &mdash; Function: void <b>dsa_private_key_clear</b> (<var>struct dsa_private_key *key</var>)<var><a name="index-dsa_005fprivate_005fkey_005fclear-354"></a></var><br>
3495 <blockquote><p>Calls <code>mpz_clear</code> on all numbers in the key struct.
3496 </p></blockquote></div>
3497
3498    <p>Signatures are represented using the structure below, and need to be
3499 initialized and cleared in the same way as the key structs.
3500
3501 <div class="defun">
3502 &mdash; Context struct: <b>dsa_signature</b><var> r s<a name="index-dsa_005fsignature-355"></a></var><br>
3503         </div>
3504
3505 <div class="defun">
3506 &mdash; Function: void <b>dsa_signature_init</b> (<var>struct dsa_signature *signature</var>)<var><a name="index-dsa_005fsignature_005finit-356"></a></var><br>
3507 &mdash; Function: void <b>dsa_signature_clear</b> (<var>struct dsa_signature *signature</var>)<var><a name="index-dsa_005fsignature_005fclear-357"></a></var><br>
3508 <blockquote><p>You must call <code>dsa_signature_init</code> before creating or using a
3509 signature, and call <code>dsa_signature_clear</code> when you are finished
3510 with it.
3511 </p></blockquote></div>
3512
3513    <p>For signing, you need to provide both the public and the private key
3514 (unlike <acronym>RSA</acronym>, where the private key struct includes all
3515 information needed for signing), and a source for random numbers.
3516 Signatures can use the <acronym>SHA1</acronym> or the <acronym>SHA256</acronym> hash
3517 function, although the implementation of <acronym>DSA</acronym> with
3518 <acronym>SHA256</acronym> should be considered somewhat experimental due to lack
3519 of official test vectors and interoperability testing.
3520
3521 <div class="defun">
3522 &mdash; Function: int <b>dsa_sha1_sign</b> (<var>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</var>)<var><a name="index-dsa_005fsha1_005fsign-358"></a></var><br>
3523 &mdash; Function: int <b>dsa_sha1_sign_digest</b> (<var>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</var>)<var><a name="index-dsa_005fsha1_005fsign_005fdigest-359"></a></var><br>
3524 &mdash; Function: int <b>dsa_sha256_sign</b> (<var>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</var>)<var><a name="index-dsa_005fsha256_005fsign-360"></a></var><br>
3525 &mdash; Function: int <b>dsa_sha256_sign_digest</b> (<var>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</var>)<var><a name="index-dsa_005fsha256_005fsign_005fdigest-361"></a></var><br>
3526 <blockquote><p>Creates a signature from the given hash context or digest.
3527 <var>random_ctx</var> and <var>random</var> is a randomness generator.
3528 <code>random(random_ctx, length, dst)</code> should generate <code>length</code>
3529 random octets and store them at <code>dst</code>. For advice, see
3530 See <a href="#Randomness">Randomness</a>. Returns one on success, or zero on failure.
3531 Signing fails if the key size and the hash size don't match.
3532 </p></blockquote></div>
3533
3534    <p>Verifying signatures is a little easier, since no randomness generator is
3535 needed. The functions are
3536
3537 <div class="defun">
3538 &mdash; Function: int <b>dsa_sha1_verify</b> (<var>const struct dsa_public_key *key, struct sha1_ctx *hash, const struct dsa_signature *signature</var>)<var><a name="index-dsa_005fsha1_005fverify-362"></a></var><br>
3539 &mdash; Function: int <b>dsa_sha1_verify_digest</b> (<var>const struct dsa_public_key *key, const uint8_t *digest, const struct dsa_signature *signature</var>)<var><a name="index-dsa_005fsha1_005fverify_005fdigest-363"></a></var><br>
3540 &mdash; Function: int <b>dsa_sha256_verify</b> (<var>const struct dsa_public_key *key, struct sha256_ctx *hash, const struct dsa_signature *signature</var>)<var><a name="index-dsa_005fsha256_005fverify-364"></a></var><br>
3541 &mdash; Function: int <b>dsa_sha256_verify_digest</b> (<var>const struct dsa_public_key *key, const uint8_t *digest, const struct dsa_signature *signature</var>)<var><a name="index-dsa_005fsha256_005fverify_005fdigest-365"></a></var><br>
3542 <blockquote><p>Verifies a signature. Returns 1 if the signature is valid, otherwise 0.
3543 </p></blockquote></div>
3544
3545    <p>Key generation uses mostly the same parameters as the corresponding
3546 <acronym>RSA</acronym> function.
3547
3548 <div class="defun">
3549 &mdash; Function: int <b>dsa_generate_keypair</b> (<var>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</var>)<var><a name="index-dsa_005fgenerate_005fkeypair-366"></a></var><br>
3550 <blockquote><p><var>pub</var> and <var>key</var> is where the resulting key pair is stored. The
3551 structs should be initialized before you call this function.
3552
3553         <p><var>random_ctx</var> and <var>random</var> is a randomness generator.
3554 <code>random(random_ctx, length, dst)</code> should generate <code>length</code>
3555 random octets and store them at <code>dst</code>. For advice, see
3556 See <a href="#Randomness">Randomness</a>.
3557
3558         <p><var>progress</var> and <var>progress_ctx</var> can be used to get callbacks
3559 during the key generation process, in order to uphold an illusion of
3560 progress. <var>progress</var> can be NULL, in that case there are no
3561 callbacks.
3562
3563         <p><var>p_bits</var> and <var>q_bits</var> are the desired sizes of <code>p</code> and
3564 <code>q</code>. To generate keys that conform to the original <acronym>DSA</acronym>
3565 standard, you must use <code>q_bits = 160</code> and select <var>p_bits</var> of
3566 the form <code>p_bits = 512 + l*64</code>, for <code>0 &lt;= l &lt;= 8</code>, where the
3567 smaller sizes are no longer recommended, so you should most likely stick
3568 to <code>p_bits = 1024</code>. Non-standard sizes are possible, in particular
3569 <code>p_bits</code> larger than 1024, although <acronym>DSA</acronym> implementations
3570 can not in general be expected to support such keys. Also note that
3571 using very large <var>p_bits</var>, with <var>q_bits</var> fixed at 160, doesn't
3572 make much sense, because the security is also limited by the size of the
3573 smaller prime. Using a larger <code>q_bits</code> requires switching to a
3574 larger hash function. To generate <acronym>DSA</acronym> keys for use with
3575 <acronym>SHA256</acronym>, use <code>q_bits = 256</code> and, e.g., <code>p_bits =
3576 2048</code>.
3577
3578         <p>Returns one on success, and zero on failure. The function will fail if
3579 <var>q_bits</var> is neither 160 nor 256, or if <var>p_bits</var> is unreasonably
3580 small.
3581 </p></blockquote></div>
3582
3583 <div class="node">
3584 <a name="Elliptic-curves"></a>
3585 <p><hr>
3586 Previous:&nbsp;<a rel="previous" accesskey="p" href="#DSA">DSA</a>,
3587 Up:&nbsp;<a rel="up" accesskey="u" href="#Public_002dkey-algorithms">Public-key algorithms</a>
3588
3589 </div>
3590
3591 <!-- node-name,  next,  previous,  up -->
3592 <h4 class="subsection">6.6.5 <acronym>Elliptic curves</acronym></h4>
3593
3594 <p>For cryptographic purposes, an elliptic curve is a mathematical group of
3595 points, and computing logarithms in this group is computationally
3596 difficult problem. Nettle uses additive notation for elliptic curve
3597 groups. If P and Q are two points, and k is an
3598 integer, the point sum, P + Q, and the multiple k P can be
3599 computed efficiently, but given only two points P and Q,
3600 finding an integer k such that Q = k P is the elliptic
3601 curve discrete logarithm problem.
3602
3603    <p>Nettle supports standard curves which are all of the form y^2 =
3604 x^3 - 3 x + b (mod p), i.e., the points have coordinates (x,y),
3605 both considered as integers modulo a specified prime p. Curves
3606 are represented as a <code>struct ecc_curve</code>. Supported curves are
3607 declared in <samp><span class="file">&lt;nettle/ecc-curve.h&gt;</span></samp>, e.g., <code>nettle_secp_256r1</code>
3608 for a standardized curve using the 256-bit prime p = 2^256 -
3609 2^224 + 2^192 + 2^96 - 1. The contents of these structs is not
3610 visible to nettle users. The &ldquo;bitsize of the curve&rdquo; is used as a
3611 shorthand for the bitsize of the curve's prime p, e.g., 256 bits
3612 for <code>nettle_secp_256r1</code>.
3613
3614 <h5 class="subsubsection">6.6.5.1 Side-channel silence</h5>
3615
3616 <p>Nettle's implementation of the elliptic curve operations is intended to
3617 be side-channel silent. The side-channel attacks considered are:
3618
3619      <ul>
3620 <li>Timing attacks
3621 If the timing of operations depends on secret values, an attacker
3622 interacting with your system can measure the response time, and infer
3623 information about your secrets, e.g., a private signature key.
3624
3625      <li>Attacks using memory caches
3626 Assume you have some secret data on a multi-user system, and that this
3627 data is properly protected so that other users get no direct access to
3628 it. If you have a process operating on the secret data, and this process
3629 does memory accesses depending on the data, e.g, an internal lookup
3630 table in some cryptographic algorithm, an attacker running a separate
3631 process on the same system may use behavior of internal CPU caches to
3632 get information about your secrets.
3633 </ul>
3634
3635    <p>Nettle's ECC implementation is designed to be <dfn>side-channel silent</dfn>,
3636 and not leak any information to these attacks. Timing and memory
3637 accesses depend only on the size of the input data and its location in
3638 memory, not on the actual data bits. This implies a performance penalty
3639 in several of the building blocks.
3640
3641 <h4 class="subsection">6.6.6 ECDSA</h4>
3642
3643 <p>ECDSA is a variant of the DSA digital signature scheme (see <a href="#DSA">DSA</a>),
3644 which works over an elliptic curve group rather than over a (subgroup
3645 of) integers modulo p. Like DSA, creating a signature requires a unique
3646 random nonce (repeating the nonce with two different messages reveals
3647 the private key, and any leak or bias in the generation of the nonce
3648 also leaks information about the key).
3649
3650    <p>Unlike DSA, signatures are in general not tied to any particular hash
3651 function or even hash size. Any hash function can be used, and the hash
3652 value is truncated or padded as needed to get a size matching the curve
3653 being used. It is recommended to use a strong cryptographic hash
3654 function with digest size close to the bit size of the curve, e.g.,
3655 SHA256 is a reasonable choice when using ECDSA signature over the curve
3656 secp256r1. A protocol or application using ECDSA has to specify which
3657 curve and which hash function to use, or provide some mechanism for
3658 negotiating.
3659
3660    <p>Nettle defines ECDSA in <samp><span class="file">&lt;nettle/ecdsa.h&gt;</span></samp>. We first need
3661 to define the data types used to represent public and private keys.
3662
3663 <div class="defun">
3664 &mdash; struct: <b>struct ecc_point</b><var><a name="index-struct-ecc_005fpoint-367"></a></var><br>
3665 <blockquote><p>Represents a point on an elliptic curve. In particular, it is used to
3666 represent an ECDSA public key.
3667 </p></blockquote></div>
3668
3669 <div class="defun">
3670 &mdash; Function: void <b>ecc_point_init</b> (<var>struct ecc_point *p, const structecc_curve *ecc</var>)<var><a name="index-ecc_005fpoint_005finit-368"></a></var><br>
3671 <blockquote><p>Initializes <var>p</var> to represent points on the given curve <var>ecc</var>.
3672 Allocates storage for the coordinates, using the same allocation
3673 functions as GMP.
3674 </p></blockquote></div>
3675
3676 <div class="defun">
3677 &mdash; Function: void <b>ecc_point_clear</b> (<var>struct ecc_point *p</var>)<var><a name="index-ecc_005fpoint_005fclear-369"></a></var><br>
3678 <blockquote><p>Deallocate storage.
3679 </p></blockquote></div>
3680
3681 <div class="defun">
3682 &mdash; Function: int <b>ecc_point_set</b> (<var>struct ecc_point *p, const mpz_t x, const mpz_t y</var>)<var><a name="index-ecc_005fpoint_005fset-370"></a></var><br>
3683 <blockquote><p>Check that the given coordinates represent a point on the curve. If so,
3684 the coordinates are copied and converted to internal representation, and
3685 the function returns 1. Otherwise, it returns 0. Currently, the
3686 infinity point (or zero point, with additive notation) i snot allowed.
3687 </p></blockquote></div>
3688
3689 <div class="defun">
3690 &mdash; Function: void <b>ecc_point_get</b> (<var>const struct ecc_point *p, mpz_t x, mpz_t y</var>)<var><a name="index-ecc_005fpoint_005fget-371"></a></var><br>
3691 <blockquote><p>Extracts the coordinate of the point <var>p</var>. The output parameters
3692 <var>x</var> or <var>y</var> may be NULL if the caller doesn't want that
3693 coordinate.
3694 </p></blockquote></div>
3695
3696 <div class="defun">
3697 &mdash; struct: <b>struct ecc_scalar</b><var><a name="index-struct-ecc_005fscalar-372"></a></var><br>
3698 <blockquote><p>Represents an integer in the range 0 &lt; x &lt; group order, where the
3699 &ldquo;group order&rdquo; refers to the order of an ECC group. In particular, it
3700 is used to represent an ECDSA private key.
3701 </p></blockquote></div>
3702
3703 <div class="defun">
3704 &mdash; Function: void <b>ecc_scalar_init</b> (<var>struct ecc_scalar *s, const struct ecc_curve *ecc</var>)<var><a name="index-ecc_005fscalar_005finit-373"></a></var><br>
3705 <blockquote><p>Initializes <var>s</var> to represent a scalar suitable for the given curve
3706 <var>ecc</var>. Allocates storage using the same allocation functions as GMP.
3707 </p></blockquote></div>
3708
3709 <div class="defun">
3710 &mdash; Function: void <b>ecc_scalar_clear</b> (<var>struct ecc_scalar *s</var>)<var><a name="index-ecc_005fscalar_005fclear-374"></a></var><br>
3711 <blockquote><p>Deallocate storage.
3712 </p></blockquote></div>
3713
3714 <div class="defun">
3715 &mdash; Function: int <b>ecc_scalar_set</b> (<var>struct ecc_scalar *s, const mpz_t z</var>)<var><a name="index-ecc_005fscalar_005fset-375"></a></var><br>
3716 <blockquote><p>Check that <var>z</var> is in the correct range. If so, copies the value to
3717 <var>s</var> and returns 1, otherwise returns 0.
3718 </p></blockquote></div>
3719
3720 <div class="defun">
3721 &mdash; Function: void <b>ecc_scalar_get</b> (<var>const struct ecc_scalar *s, mpz_t z</var>)<var><a name="index-ecc_005fscalar_005fget-376"></a></var><br>
3722 <blockquote><p>Extracts the scalar, in GMP <code>mpz_t</code> representation.
3723 </p></blockquote></div>
3724
3725    <p>To create and verify ECDSA signatures, the following functions are used.
3726
3727 <div class="defun">
3728 &mdash; Function: void <b>ecdsa_sign</b> (<var>const struct ecc_scalar *key, void *random_ctx, nettle_random_func *random, unsigned digest_length, const uint8_t *digest, struct dsa_signature *signature</var>)<var><a name="index-ecdsa_005fsign-377"></a></var><br>
3729 <blockquote><p>Uses the private key <var>key</var> to create a signature on <var>digest</var>.
3730 <var>random_ctx</var> and <var>random</var> is a randomness generator.
3731 <code>random(random_ctx, length, dst)</code> should generate <code>length</code>
3732 random octets and store them at <code>dst</code>. The signature is stored in
3733 <var>signature</var>, in the same was as for plain DSA.
3734 </p></blockquote></div>
3735
3736 <div class="defun">
3737 &mdash; Function: int <b>ecdsa_verify</b> (<var>const struct ecc_point *pub, unsigned length, const uint8_t *digest, const struct dsa_signature *signature</var>)<var><a name="index-ecdsa_005fverify-378"></a></var><br>
3738 <blockquote><p>Uses the public key <var>pub</var> to verify that <var>signature</var> is a valid
3739 signature for the message digest <var>digest</var> (of <var>length</var> octets).
3740 Returns 1 if the signature is valid, otherwise 0.
3741 </p></blockquote></div>
3742
3743    <p>Finally, to generation of new an ECDSA key pairs
3744
3745 <div class="defun">
3746 &mdash; Function: void <b>ecdsa_generate_keypair</b> (<var>struct ecc_point *pub, struct ecc_scalar *key, void *random_ctx, nettle_random_func *random</var>)<var>;<a name="index-ecdsa_005fgenerate_005fkeypair-379"></a></var><br>
3747 <blockquote><p><var>pub</var> and <var>key</var> is where the resulting key pair is stored. The
3748 structs should be initialized, for the desired ECC curve, before you call this function.
3749
3750         <p><var>random_ctx</var> and <var>random</var> is a randomness generator.
3751 <code>random(random_ctx, length, dst)</code> should generate <code>length</code>
3752 random octets and store them at <code>dst</code>. For advice, see
3753 See <a href="#Randomness">Randomness</a>.
3754 </p></blockquote></div>
3755
3756 <div class="node">
3757 <a name="Randomness"></a>
3758 <p><hr>
3759 Next:&nbsp;<a rel="next" accesskey="n" href="#ASCII-encoding">ASCII encoding</a>,
3760 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Public_002dkey-algorithms">Public-key algorithms</a>,
3761 Up:&nbsp;<a rel="up" accesskey="u" href="#Reference">Reference</a>
3762
3763 </div>
3764
3765 <!-- node-name,  next,  previous,  up -->
3766 <h3 class="section">6.7 Randomness</h3>
3767
3768 <p><a name="index-Randomness-380"></a>
3769 A crucial ingredient in many cryptographic contexts is randomness: Let
3770 <code>p</code> be a random prime, choose a random initialization vector
3771 <code>iv</code>, a random key <code>k</code> and a random exponent <code>e</code>, etc. In
3772 the theories, it is assumed that you have plenty of randomness around.
3773 If this assumption is not true in practice, systems that are otherwise
3774 perfectly secure, can be broken. Randomness has often turned out to be
3775 the weakest link in the chain.
3776
3777    <p>In non-cryptographic applications, such as games as well as scientific
3778 simulation, a good randomness generator usually means a generator that
3779 has good statistical properties, and is seeded by some simple function
3780 of things like the current time, process id, and host name.
3781
3782    <p>However, such a generator is inadequate for cryptography, for at least
3783 two reasons:
3784
3785      <ul>
3786 <li>It's too easy for an attacker to guess the initial seed. Even if it will
3787 take some 2^32 tries before he guesses right, that's far too easy. For
3788 example, if the process id is 16 bits, the resolution of &ldquo;current time&rdquo;
3789 is one second, and the attacker knows what day the generator was seeded,
3790 there are only about 2^32 possibilities to try if all possible values
3791 for the process id and time-of-day are tried.
3792
3793      <li>The generator output reveals too much. By observing only a small segment
3794 of the generator's output, its internal state can be recovered, and from
3795 there, all previous output and all future output can be computed by the
3796 attacker.
3797 </ul>
3798
3799    <p>A randomness generator that is used for cryptographic purposes must have
3800 better properties. Let's first look at the seeding, as the issues here
3801 are mostly independent of the rest of the generator. The initial state
3802 of the generator (its seed) must be unguessable by the attacker. So
3803 what's unguessable? It depends on what the attacker already knows. The
3804 concept used in information theory to reason about such things is called
3805 &ldquo;entropy&rdquo;, or &ldquo;conditional entropy&rdquo; (not to be confused with the
3806 thermodynamic concept with the same name). A reasonable requirement is
3807 that the seed contains a conditional entropy of at least some 80-100
3808 bits. This property can be explained as follows: Allow the attacker to
3809 ask <code>n</code> yes-no-questions, of his own choice, about the seed. If
3810 the attacker, using this question-and-answer session, as well as any
3811 other information he knows about the seeding process, still can't guess
3812 the seed correctly, then the conditional entropy is more than <code>n</code>
3813 bits.
3814
3815    <p><a name="index-Entropy-381"></a><a name="index-Conditional-entropy-382"></a>
3816 Let's look at an example. Say information about timing of received
3817 network packets is used in the seeding process. If there is some random
3818 network traffic going on, this will contribute some bits of entropy or
3819 &ldquo;unguessability&rdquo; to the seed. However, if the attacker can listen in to
3820 the local network, or if all but a small number of the packets were
3821 transmitted by machines that the attacker can monitor, this additional
3822 information makes the seed easier for the attacker to figure out. Even
3823 if the information is exactly the same, the conditional entropy, or
3824 unguessability, is smaller for an attacker that knows some of it already
3825 before the hypothetical question-and-answer session.
3826
3827    <p>Seeding of good generators is usually based on several sources. The key
3828 point here is that the amount of unguessability that each source
3829 contributes, depends on who the attacker is. Some sources that have been
3830 used are:
3831
3832      <dl>
3833 <dt>High resolution timing of i/o activities<dd>Such as completed blocks from spinning hard disks, network packets, etc.
3834 Getting access to such information is quite system dependent, and not
3835 all systems include suitable hardware. If available, it's one of the
3836 better randomness source one can find in a digital, mostly predictable,
3837 computer.
3838
3839      <br><dt>User activity<dd>Timing and contents of user interaction events is another popular source
3840 that is available for interactive programs (even if I suspect that it is
3841 sometimes used in order to make the user feel good, not because the
3842 quality of the input is needed or used properly). Obviously, not
3843 available when a machine is unattended. Also beware of networks: User
3844 interaction that happens across a long serial cable, <acronym>TELNET</acronym>
3845 session, or even <acronym>SSH</acronym> session may be visible to an attacker, in
3846 full or partially.
3847
3848      <br><dt>Audio input<dd>Any room, or even a microphone input that's left unconnected, is a
3849 source of some random background noise, which can be fed into the
3850 seeding process.
3851
3852      <br><dt>Specialized hardware<dd>Hardware devices with the sole purpose of generating random data have
3853 been designed. They range from radioactive samples with an attached
3854 Geiger counter, to amplification of the inherent noise in electronic
3855 components such as diodes and resistors, to low-frequency sampling of
3856 chaotic systems. Hashing successive images of a Lava lamp is a
3857 spectacular example of the latter type.
3858
3859      <br><dt>Secret information<dd>Secret information, such as user passwords or keys, or private files
3860 stored on disk, can provide some unguessability. A problem is that if
3861 the information is revealed at a later time, the unguessability
3862 vanishes. Another problem is that this kind of information tends to be
3863 fairly constant, so if you rely on it and seed your generator regularly,
3864 you risk constructing almost similar seeds or even constructing the same
3865 seed more than once.
3866 </dl>
3867
3868    <p>For all practical sources, it's difficult but important to provide a
3869 reliable lower bound on the amount of unguessability that it provides.
3870 Two important points are to make sure that the attacker can't observe
3871 your sources (so if you like the Lava lamp idea, remember that you have
3872 to get your own lamp, and not put it by a window or anywhere else where
3873 strangers can see it), and that hardware failures are detected. What if
3874 the bulb in the Lava lamp, which you keep locked into a cupboard
3875 following the above advice, breaks after a few months?
3876
3877    <p>So let's assume that we have been able to find an unguessable seed,
3878 which contains at least 80 bits of conditional entropy, relative to all
3879 attackers that we care about (typically, we must at the very least
3880 assume that no attacker has root privileges on our machine).
3881
3882    <p>How do we generate output from this seed, and how much can we get? Some
3883 generators (notably the Linux <samp><span class="file">/dev/random</span></samp> generator) tries to
3884 estimate available entropy and restrict the amount of output. The goal
3885 is that if you read 128 bits from <samp><span class="file">/dev/random</span></samp>, you should get 128
3886 &ldquo;truly random&rdquo; bits. This is a property that is useful in some
3887 specialized circumstances, for instance when generating key material for
3888 a one time pad, or when working with unconditional blinding, but in most
3889 cases, it doesn't matter much. For most application, there's no limit on
3890 the amount of useful &ldquo;random&rdquo; data that we can generate from a small
3891 seed; what matters is that the seed is unguessable and that the
3892 generator has good cryptographic properties.
3893
3894    <p>At the heart of all generators lies its internal state. Future output
3895 is determined by the internal state alone. Let's call it the generator's
3896 key. The key is initialized from the unguessable seed. Important
3897 properties of a generator are:
3898
3899      <dl>
3900 <dt><dfn>Key-hiding</dfn><dd>An attacker observing the output should not be able to recover the
3901 generator's key.
3902
3903      <br><dt><dfn>Independence of outputs</dfn><dd>Observing some of the output should not help the attacker to guess
3904 previous or future output.
3905
3906      <br><dt><dfn>Forward secrecy</dfn><dd>Even if an attacker compromises the generator's key, he should not be
3907 able to guess the generator output <em>before</em> the key compromise.
3908
3909      <br><dt><dfn>Recovery from key compromise</dfn><dd>If an attacker compromises the generator's key, he can compute
3910 <em>all</em> future output. This is inevitable if the generator is seeded
3911 only once, at startup. However, the generator can provide a reseeding
3912 mechanism, to achieve recovery from key compromise. More precisely: If
3913 the attacker compromises the key at a particular time <code>t_1</code>, there
3914 is another later time <code>t_2</code>, such that if the attacker observes all
3915 output generated between <code>t_1</code> and <code>t_2</code>, he still can't guess
3916 what output is generated after <code>t_2</code>.
3917
3918    </dl>
3919
3920    <p>Nettle includes one randomness generator that is believed to have all
3921 the above properties, and two simpler ones.
3922
3923    <p><acronym>ARCFOUR</acronym>, like any stream cipher, can be used as a randomness
3924 generator. Its output should be of reasonable quality, if the seed is
3925 hashed properly before it is used with <code>arcfour_set_key</code>. There's
3926 no single natural way to reseed it, but if you need reseeding, you
3927 should be using Yarrow instead.
3928
3929    <p>The &ldquo;lagged Fibonacci&rdquo; generator in <samp><span class="file">&lt;nettle/knuth-lfib.h&gt;</span></samp> is a
3930 fast generator with good statistical properties, but is <strong>not</strong> for
3931 cryptographic use, and therefore not documented here. It is included
3932 mostly because the Nettle test suite needs to generate some test data
3933 from a small seed.
3934
3935    <p>The recommended generator to use is Yarrow, described below.
3936
3937 <h4 class="subsection">6.7.1 Yarrow</h4>
3938
3939 <p>Yarrow is a family of pseudo-randomness generators, designed for
3940 cryptographic use, by John Kelsey, Bruce Schneier and Niels Ferguson.
3941 Yarrow-160 is described in a paper at
3942 <a href="http://www.counterpane.com/yarrow.html">http://www.counterpane.com/yarrow.html</a>, and it uses <acronym>SHA1</acronym>
3943 and triple-DES, and has a 160-bit internal state. Nettle implements
3944 Yarrow-256, which is similar, but uses <acronym>SHA256</acronym> and
3945 <acronym>AES</acronym> to get an internal state of 256 bits.
3946
3947    <p>Yarrow was an almost finished project, the paper mentioned above is the
3948 closest thing to a specification for it, but some smaller details are
3949 left out. There is no official reference implementation or test cases.
3950 This section includes an overview of Yarrow, but for the details of
3951 Yarrow-256, as implemented by Nettle, you have to consult the source
3952 code. Maybe a complete specification can be written later.
3953
3954    <p>Yarrow can use many sources (at least two are needed for proper
3955 reseeding), and two randomness &ldquo;pools&rdquo;, referred to as the &ldquo;slow pool&rdquo; and
3956 the &ldquo;fast pool&rdquo;. Input from the sources is fed alternatingly into the
3957 two pools. When one of the sources has contributed 100 bits of entropy
3958 to the fast pool, a &ldquo;fast reseed&rdquo; happens and the fast pool is mixed
3959 into the internal state. When at least two of the sources have
3960 contributed at least 160 bits each to the slow pool, a &ldquo;slow reseed&rdquo;
3961 takes place. The contents of both pools are mixed into the internal
3962 state. These procedures should ensure that the generator will eventually
3963 recover after a key compromise.
3964
3965    <p>The output is generated by using <acronym>AES</acronym> to encrypt a counter,
3966 using the generator's current key. After each request for output,
3967 another 256 bits are generated which replace the key. This ensures
3968 forward secrecy.
3969
3970    <p>Yarrow can also use a <dfn>seed file</dfn> to save state across restarts.
3971 Yarrow is seeded by either feeding it the contents of the previous seed
3972 file, or feeding it input from its sources until a slow reseed happens.
3973
3974    <p>Nettle defines Yarrow-256 in <samp><span class="file">&lt;nettle/yarrow.h&gt;</span></samp>.
3975
3976 <div class="defun">
3977 &mdash; Context struct: <b>struct yarrow256_ctx</b><var><a name="index-struct-yarrow256_005fctx-383"></a></var><br>
3978         </div>
3979
3980 <div class="defun">
3981 &mdash; Context struct: <b>struct yarrow_source</b><var><a name="index-struct-yarrow_005fsource-384"></a></var><br>
3982 <blockquote><p>Information about a single source.
3983 </p></blockquote></div>
3984
3985 <div class="defun">
3986 &mdash; Constant: <b>YARROW256_SEED_FILE_SIZE</b><var><a name="index-YARROW256_005fSEED_005fFILE_005fSIZE-385"></a></var><br>
3987 <blockquote><p>Recommended size of the Yarrow-256 seed file.
3988 </p></blockquote></div>
3989
3990 <div class="defun">
3991 &mdash; Function: void <b>yarrow256_init</b> (<var>struct yarrow256_ctx *ctx, unsigned nsources, struct yarrow_source *sources</var>)<var><a name="index-yarrow256_005finit-386"></a></var><br>
3992 <blockquote><p>Initializes the yarrow context, and its <var>nsources</var> sources. It's
3993 possible to call it with <var>nsources</var>=0 and <var>sources</var>=NULL, if
3994 you don't need the update features.
3995 </p></blockquote></div>
3996
3997 <div class="defun">
3998 &mdash; Function: void <b>yarrow256_seed</b> (<var>struct yarrow256_ctx *ctx, unsigned length, uint8_t *seed_file</var>)<var><a name="index-yarrow256_005fseed-387"></a></var><br>
3999 <blockquote><p>Seeds Yarrow-256 from a previous seed file. <var>length</var> should be at least
4000 <code>YARROW256_SEED_FILE_SIZE</code>, but it can be larger.
4001
4002         <p>The generator will trust you that the <var>seed_file</var> data really is
4003 unguessable. After calling this function, you <em>must</em> overwrite the old
4004 seed file with newly generated data from <code>yarrow256_random</code>. If it's
4005 possible for several processes to read the seed file at about the same
4006 time, access must be coordinated using some locking mechanism.
4007 </p></blockquote></div>
4008
4009 <div class="defun">
4010 &mdash; Function: int <b>yarrow256_update</b> (<var>struct yarrow256_ctx *ctx, unsigned source, unsigned entropy, unsigned length, const uint8_t *data</var>)<var><a name="index-yarrow256_005fupdate-388"></a></var><br>
4011 <blockquote><p>Updates the generator with data from source <var>SOURCE</var> (an index that
4012 must be smaller than the number of sources). <var>entropy</var> is your
4013 estimated lower bound for the entropy in the data, measured in bits.
4014 Calling update with zero <var>entropy</var> is always safe, no matter if the
4015 data is random or not.
4016
4017         <p>Returns 1 if a reseed happened, in which case an application using a
4018 seed file may want to generate new seed data with
4019 <code>yarrow256_random</code> and overwrite the seed file. Otherwise, the
4020 function returns 0.
4021 </p></blockquote></div>
4022
4023 <div class="defun">
4024 &mdash; Function: void <b>yarrow256_random</b> (<var>struct yarrow256_ctx *ctx, unsigned length, uint8_t *dst</var>)<var><a name="index-yarrow256_005frandom-389"></a></var><br>
4025 <blockquote><p>Generates <var>length</var> octets of output. The generator must be seeded
4026 before you call this function.
4027
4028         <p>If you don't need forward secrecy, e.g. if you need non-secret
4029 randomness for initialization vectors or padding, you can gain some
4030 efficiency by buffering, calling this function for reasonably large
4031 blocks of data, say 100-1000 octets at a time.
4032 </p></blockquote></div>
4033
4034 <div class="defun">
4035 &mdash; Function: int <b>yarrow256_is_seeded</b> (<var>struct yarrow256_ctx *ctx</var>)<var><a name="index-yarrow256_005fis_005fseeded-390"></a></var><br>
4036 <blockquote><p>Returns 1 if the generator is seeded and ready to generate output,
4037 otherwise 0.
4038 </p></blockquote></div>
4039
4040 <div class="defun">
4041 &mdash; Function: unsigned <b>yarrow256_needed_sources</b> (<var>struct yarrow256_ctx *ctx</var>)<var><a name="index-yarrow256_005fneeded_005fsources-391"></a></var><br>
4042 <blockquote><p>Returns the number of sources that must reach the threshold before a
4043 slow reseed will happen. Useful primarily when the generator is unseeded.
4044 </p></blockquote></div>
4045
4046 <div class="defun">
4047 &mdash; Function: void <b>yarrow256_fast_reseed</b> (<var>struct yarrow256_ctx *ctx</var>)<var><a name="index-yarrow256_005ffast_005freseed-392"></a></var><br>
4048 &mdash; Function: void <b>yarrow256_slow_reseed</b> (<var>struct yarrow256_ctx *ctx</var>)<var><a name="index-yarrow256_005fslow_005freseed-393"></a></var><br>
4049 <blockquote><p>Causes a fast or slow reseed to take place immediately, regardless of the
4050 current entropy estimates of the two pools. Use with care.
4051 </p></blockquote></div>
4052
4053    <p>Nettle includes an entropy estimator for one kind of input source: User
4054 keyboard input.
4055
4056 <div class="defun">
4057 &mdash; Context struct: <b>struct yarrow_key_event_ctx</b><var><a name="index-struct-yarrow_005fkey_005fevent_005fctx-394"></a></var><br>
4058 <blockquote><p>Information about recent key events.
4059 </p></blockquote></div>
4060
4061 <div class="defun">
4062 &mdash; Function: void <b>yarrow_key_event_init</b> (<var>struct yarrow_key_event_ctx *ctx</var>)<var><a name="index-yarrow_005fkey_005fevent_005finit-395"></a></var><br>
4063 <blockquote><p>Initializes the context.
4064 </p></blockquote></div>
4065
4066 <div class="defun">
4067 &mdash; Function: unsigned <b>yarrow_key_event_estimate</b> (<var>struct yarrow_key_event_ctx *ctx, unsigned key, unsigned time</var>)<var><a name="index-yarrow_005fkey_005fevent_005festimate-396"></a></var><br>
4068 <blockquote><p><var>key</var> is the id of the key (ASCII value, hardware key code, X
4069 keysym, <small class="dots">...</small>, it doesn't matter), and <var>time</var> is the timestamp of
4070 the event. The time must be given in units matching the resolution by
4071 which you read the clock. If you read the clock with microsecond
4072 precision, <var>time</var> should be provided in units of microseconds. But
4073 if you use <code>gettimeofday</code> on a typical Unix system where the clock
4074 ticks 10 or so microseconds at a time, <var>time</var> should be given in
4075 units of 10 microseconds.
4076
4077         <p>Returns an entropy estimate, in bits, suitable for calling
4078 <code>yarrow256_update</code>. Usually, 0, 1 or 2 bits.
4079 </p></blockquote></div>
4080
4081 <div class="node">
4082 <a name="ASCII-encoding"></a>
4083 <p><hr>
4084 Next:&nbsp;<a rel="next" accesskey="n" href="#Miscellaneous-functions">Miscellaneous functions</a>,
4085 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Randomness">Randomness</a>,
4086 Up:&nbsp;<a rel="up" accesskey="u" href="#Reference">Reference</a>
4087
4088 </div>
4089
4090 <!-- node-name,  next,  previous,  up -->
4091 <h3 class="section">6.8 ASCII encoding</h3>
4092
4093 <p>Encryption will transform your data from text into binary format, and that
4094 may be a problem if you want, for example, to send the data as if it was
4095 plain text in an email (or store it along with descriptive text in a
4096 file). You may then use an encoding from binary to text: each binary byte
4097 is translated into a number of bytes of plain text.
4098
4099    <p>A base-N encoding of data is one representation of data that only uses N
4100 different symbols (instead of the 256 possible values of a byte).
4101
4102    <p>The base64 encoding will always use alphanumeric (upper and lower case)
4103 characters and the '+', '/' and '=' symbols to represent the data. Four
4104 output characters are generated for each three bytes of input. In case
4105 the length of the input is not a multiple of three, padding characters
4106 are added at the end.
4107
4108    <p>The base16 encoding, also known as &ldquo;hexadecimal&rdquo;, uses the decimal
4109 digits and the letters from A to F. Two hexadecimal digits are generated
4110 for each input byte. Base16 may be useful if you want to use the data
4111 for filenames or URLs, for example.
4112
4113    <p>Nettle supports both base64 and base16 encoding and decoding.
4114
4115    <p>Encoding and decoding uses a context struct to maintain its state (with
4116 the exception of base16 encoding, which doesn't need any). To encode or
4117 decode the your data, first initialize the context, then call the update
4118 function as many times as necessary, and complete the operation by
4119 calling the final function.
4120
4121    <p>The following functions can be used to perform base64 encoding and decoding.
4122 They are defined in <samp><span class="file">&lt;nettle/base64.h&gt;</span></samp>.
4123
4124 <div class="defun">
4125 &mdash; Context struct: <b>struct base64_encode_ctx</b><var><a name="index-struct-base64_005fencode_005fctx-397"></a></var><br>
4126         </div>
4127
4128 <div class="defun">
4129 &mdash; Function: void <b>base64_encode_init</b> (<var>struct base64_encode_ctx *ctx</var>)<var><a name="index-base64_005fencode_005finit-398"></a></var><br>
4130 <blockquote><p>Initializes a base64 context. This is necessary before starting an encoding
4131 session.
4132 </p></blockquote></div>
4133
4134 <div class="defun">
4135 &mdash; Function: unsigned <b>base64_encode_single</b> (<var>struct base64_encode_ctx *ctx, uint8_t *dst, uint8_t src</var>)<var><a name="index-base64_005fencode_005fsingle-399"></a></var><br>
4136 <blockquote><p>Encodes a single byte. Returns amount of output (always 1 or 2).
4137 </p></blockquote></div>
4138
4139 <div class="defun">
4140 &mdash; Macro: <b>BASE64_ENCODE_LENGTH</b> (<var>length</var>)<var><a name="index-BASE64_005fENCODE_005fLENGTH-400"></a></var><br>
4141 <blockquote><p>The maximum number of output bytes when passing <var>length</var> input bytes
4142 to <code>base64_encode_update</code>.
4143 </p></blockquote></div>
4144
4145 <div class="defun">
4146 &mdash; Function: unsigned <b>base64_encode_update</b> (<var>struct base64_encode_ctx *ctx, uint8_t *dst, unsigned length, const uint8_t *src</var>)<var><a name="index-base64_005fencode_005fupdate-401"></a></var><br>
4147 <blockquote><p>After <var>ctx</var> is initialized, this function may be called to encode <var>length</var>
4148 bytes from <var>src</var>. The result will be placed in <var>dst</var>, and the return value
4149 will be the number of bytes generated. Note that <var>dst</var> must be at least of size
4150 BASE64_ENCODE_LENGTH(<var>length</var>).
4151 </p></blockquote></div>
4152
4153 <div class="defun">
4154 &mdash; Constant: <b>BASE64_ENCODE_FINAL_LENGTH</b><var><a name="index-BASE64_005fENCODE_005fFINAL_005fLENGTH-402"></a></var><br>
4155 <blockquote><p>The maximum amount of output from <code>base64_encode_final</code>.
4156 </p></blockquote></div>
4157
4158 <div class="defun">
4159 &mdash; Function: unsigned <b>base64_encode_final</b> (<var>struct base64_encode_ctx *ctx, uint8_t *dst</var>)<var><a name="index-base64_005fencode_005ffinal-403"></a></var><br>
4160 <blockquote><p>After calling base64_encode_update one or more times, this function
4161 should be called to generate the final output bytes, including any
4162 needed paddding. The return value is the number of output bytes
4163 generated.
4164 </p></blockquote></div>
4165
4166 <div class="defun">
4167 &mdash; Context struct: <b>struct base64_decode_ctx</b><var><a name="index-struct-base64_005fdecode_005fctx-404"></a></var><br>
4168         </div>
4169
4170 <div class="defun">
4171 &mdash; Function: void <b>base64_decode_init</b> (<var>struct base64_decode_ctx *ctx</var>)<var><a name="index-base64_005fdecode_005finit-405"></a></var><br>
4172 <blockquote><p>Initializes a base64 decoding context. This is necessary before starting a decoding
4173 session.
4174 </p></blockquote></div>
4175
4176 <div class="defun">
4177 &mdash; Function: int <b>base64_decode_single</b> (<var>struct base64_decode_ctx *ctx, uint8_t *dst, uint8_t src</var>)<var><a name="index-base64_005fdecode_005fsingle-406"></a></var><br>
4178 <blockquote><p>Decodes a single byte (<var>src</var>) and stores the result in <var>dst</var>.
4179 Returns amount of output (0 or 1), or -1 on errors.
4180 </p></blockquote></div>
4181
4182 <div class="defun">
4183 &mdash; Macro: <b>BASE64_DECODE_LENGTH</b> (<var>length</var>)<var><a name="index-BASE64_005fDECODE_005fLENGTH-407"></a></var><br>
4184 <blockquote><p>The maximum number of output bytes when passing <var>length</var> input bytes
4185 to <code>base64_decode_update</code>.
4186 </p></blockquote></div>
4187
4188 <div class="defun">
4189 &mdash; Function: void <b>base64_decode_update</b> (<var>struct base64_decode_ctx *ctx, unsigned *dst_length, uint8_t *dst, unsigned src_length, const uint8_t *src</var>)<var><a name="index-base64_005fdecode_005fupdate-408"></a></var><br>
4190 <blockquote><p>After <var>ctx</var> is initialized, this function may be called to decode <var>src_length</var>
4191 bytes from <var>src</var>. <var>dst</var> should point to an area of size at least
4192 BASE64_DECODE_LENGTH(<var>length</var>), and for sanity checking, <var>dst_length</var>
4193 should be initialized to the size of that area before the call.
4194 <var>dst_length</var> is updated to the amount of decoded output. The function will return
4195 1 on success and 0 on error.
4196 </p></blockquote></div>
4197
4198 <div class="defun">
4199 &mdash; Function: int <b>base64_decode_final</b> (<var>struct base64_decode_ctx *ctx</var>)<var><a name="index-base64_005fdecode_005ffinal-409"></a></var><br>
4200 <blockquote><p>Check that final padding is correct. Returns 1 on success, and 0 on
4201 error.
4202 </p></blockquote></div>
4203
4204    <p>Similarly to the base64 functions, the following functions perform base16 encoding,
4205 and are defined in <samp><span class="file">&lt;nettle/base16.h&gt;</span></samp>. Note that there is no encoding context
4206 necessary for doing base16 encoding.
4207
4208 <div class="defun">
4209 &mdash; Function: void <b>base16_encode_single</b> (<var>uint8_t *dst, uint8_t src</var>)<var><a name="index-base16_005fencode_005fsingle-410"></a></var><br>
4210 <blockquote><p>Encodes a single byte. Always stores two digits in <var>dst</var>[0] and <var>dst</var>[1].
4211 </p></blockquote></div>
4212
4213 <div class="defun">
4214 &mdash; Macro: <b>BASE16_ENCODE_LENGTH</b> (<var>length</var>)<var><a name="index-BASE16_005fENCODE_005fLENGTH-411"></a></var><br>
4215 <blockquote><p>The number of output bytes when passing <var>length</var> input bytes to
4216 <code>base16_encode_update</code>.
4217 </p></blockquote></div>
4218
4219 <div class="defun">
4220 &mdash; Function: void <b>base16_encode_update</b> (<var>uint8_t *dst, unsigned length, const uint8_t *src</var>)<var><a name="index-base16_005fencode_005fupdate-412"></a></var><br>
4221 <blockquote><p>Always stores BASE16_ENCODE_LENGTH(<var>length</var>) digits in <var>dst</var>.
4222 </p></blockquote></div>
4223
4224 <div class="defun">
4225 &mdash; Context struct: <b>struct base16_decode_ctx</b><var><a name="index-struct-base16_005fdecode_005fctx-413"></a></var><br>
4226         </div>
4227
4228 <div class="defun">
4229 &mdash; Function: void <b>base16_decode_init</b> (<var>struct base16_decode_ctx *ctx</var>)<var><a name="index-base16_005fdecode_005finit-414"></a></var><br>
4230 <blockquote><p>Initializes a base16 decoding context. This is necessary before starting a decoding
4231 session.
4232 </p></blockquote></div>
4233
4234 <div class="defun">
4235 &mdash; Function: int <b>base16_decode_single</b> (<var>struct base16_decode_ctx *ctx, uint8_t *dst, uint8_t src</var>)<var><a name="index-base16_005fdecode_005fsingle-415"></a></var><br>
4236 <blockquote><p>Decodes a single byte from <var>src</var> into <var>dst</var>. Returns amount of output (0 or 1), or -1 on errors.
4237 </p></blockquote></div>
4238
4239 <div class="defun">
4240 &mdash; Macro: <b>BASE16_DECODE_LENGTH</b> (<var>length</var>)<var><a name="index-BASE16_005fDECODE_005fLENGTH-416"></a></var><br>
4241 <blockquote><p>The maximum number of output bytes when passing <var>length</var> input bytes
4242 to <code>base16_decode_update</code>.
4243 </p></blockquote></div>
4244
4245 <div class="defun">
4246 &mdash; Function: int <b>base16_decode_update</b> (<var>struct base16_decode_ctx *ctx, unsigned *dst_length, uint8_t *dst, unsigned src_length, const uint8_t *src</var>)<var><a name="index-base16_005fdecode_005fupdate-417"></a></var><br>
4247 <blockquote><p>After <var>ctx</var> is initialized, this function may be called to decode <var>src_length</var>
4248 bytes from <var>src</var>. <var>dst</var> should point to an area of size at least
4249 BASE16_DECODE_LENGTH(<var>length</var>), and for sanity checking, <var>dst_length</var>
4250 should be initialized to the size of that area before the call.
4251 <var>dst_length</var> is updated to the amount of decoded output. The function will return
4252 1 on success and 0 on error.
4253 </p></blockquote></div>
4254
4255 <div class="defun">
4256 &mdash; Function: int <b>base16_decode_final</b> (<var>struct base16_decode_ctx *ctx</var>)<var><a name="index-base16_005fdecode_005ffinal-418"></a></var><br>
4257 <blockquote><p>Checks that the end of data is correct (i.e., an even number of
4258 hexadecimal digits have been seen). Returns 1 on success, and 0 on
4259 error.
4260 </p></blockquote></div>
4261
4262 <div class="node">
4263 <a name="Miscellaneous-functions"></a>
4264 <p><hr>
4265 Next:&nbsp;<a rel="next" accesskey="n" href="#Compatibility-functions">Compatibility functions</a>,
4266 Previous:&nbsp;<a rel="previous" accesskey="p" href="#ASCII-encoding">ASCII encoding</a>,
4267 Up:&nbsp;<a rel="up" accesskey="u" href="#Reference">Reference</a>
4268
4269 </div>
4270
4271 <!-- node-name,  next,  previous,  up -->
4272 <h3 class="section">6.9 Miscellaneous functions</h3>
4273
4274 <div class="defun">
4275 &mdash; Function: uint8_t * <b>memxor</b> (<var>uint8_t *dst, const uint8_t *src, size_t n</var>)<var><a name="index-memxor-419"></a></var><br>
4276 <blockquote><p>XORs the source area on top of the destination area. The interface
4277 doesn't follow the Nettle conventions, because it is intended to be
4278 similar to the ANSI-C <code>memcpy</code> function.
4279 </p></blockquote></div>
4280
4281    <p><code>memxor</code> is declared in <samp><span class="file">&lt;nettle/memxor.h&gt;</span></samp>.
4282
4283 <div class="node">
4284 <a name="Compatibility-functions"></a>
4285 <p><hr>
4286 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Miscellaneous-functions">Miscellaneous functions</a>,
4287 Up:&nbsp;<a rel="up" accesskey="u" href="#Reference">Reference</a>
4288
4289 </div>
4290
4291 <!-- node-name,  next,  previous,  up -->
4292 <h3 class="section">6.10 Compatibility functions</h3>
4293
4294 <p>For convenience, Nettle includes alternative interfaces to some
4295 algorithms, for compatibility with some other popular crypto toolkits.
4296 These are not fully documented here; refer to the source or to the
4297 documentation for the original implementation.
4298
4299    <p>MD5 is defined in [RFC 1321], which includes a reference implementation.
4300 Nettle defines a compatible interface to MD5 in
4301 <samp><span class="file">&lt;nettle/md5-compat.h&gt;</span></samp>. This file defines the typedef
4302 <code>MD5_CTX</code>, and declares the functions <code>MD5Init</code>, <code>MD5Update</code> and
4303 <code>MD5Final</code>.
4304
4305    <p>Eric Young's &ldquo;libdes&rdquo; (also part of OpenSSL) is a quite popular DES
4306 implementation. Nettle includes a subset if its interface in
4307 <samp><span class="file">&lt;nettle/des-compat.h&gt;</span></samp>. This file defines the typedefs
4308 <code>des_key_schedule</code> and <code>des_cblock</code>, two constants
4309 <code>DES_ENCRYPT</code> and <code>DES_DECRYPT</code>, and declares one global
4310 variable <code>des_check_key</code>, and the functions <code>des_cbc_cksum</code>
4311 <code>des_cbc_encrypt</code>, <code>des_ecb2_encrypt</code>,
4312 <code>des_ecb3_encrypt</code>, <code>des_ecb_encrypt</code>,
4313 <code>des_ede2_cbc_encrypt</code>, <code>des_ede3_cbc_encrypt</code>,
4314 <code>des_is_weak_key</code>, <code>des_key_sched</code>, <code>des_ncbc_encrypt</code>
4315 <code>des_set_key</code>, and <code>des_set_odd_parity</code>.
4316
4317 <div class="node">
4318 <a name="Nettle-soup"></a>
4319 <p><hr>
4320 Next:&nbsp;<a rel="next" accesskey="n" href="#Installation">Installation</a>,
4321 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Reference">Reference</a>,
4322 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
4323
4324 </div>
4325
4326 <!-- node-name,  next,  previous,  up -->
4327 <h2 class="chapter">7 Traditional Nettle Soup</h2>
4328
4329 <p>For the serious nettle hacker, here is a recipe for nettle soup. 4 servings.
4330
4331      <ul>
4332 <li>1 liter fresh nettles (urtica dioica)
4333 <li>2 tablespoons butter
4334 <li>3 tablespoons flour
4335 <li>1 liter stock (meat or vegetable)
4336 <li>1/2 teaspoon salt
4337 <li>a tad white pepper
4338 <li>some cream or milk
4339 </ul>
4340
4341    <p>Gather 1 liter fresh nettles. Use gloves! Small, tender shoots are
4342 preferable but the tops of larger nettles can also be used.
4343
4344    <p>Rinse the nettles very well. Boil them for 10 minutes in lightly salted
4345 water. Strain the nettles and save the water. Hack the nettles. Melt the
4346 butter and mix in the flour. Dilute with stock and the nettle-water you
4347 saved earlier. Add the hacked nettles. If you wish you can add some milk
4348 or cream at this stage. Bring to a boil and let boil for a few minutes.
4349 Season with salt and pepper.
4350
4351    <p>Serve with boiled egg-halves.
4352
4353 <!-- And the original Swedish version. -->
4354 <div class="node">
4355 <a name="Installation"></a>
4356 <p><hr>
4357 Next:&nbsp;<a rel="next" accesskey="n" href="#Index">Index</a>,
4358 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Nettle-soup">Nettle soup</a>,
4359 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
4360
4361 </div>
4362
4363 <!-- node-name,  next,  previous,  up -->
4364 <h2 class="chapter">8 Installation</h2>
4365
4366 <p>Nettle uses <samp><span class="command">autoconf</span></samp>. To build it, unpack the source and run
4367
4368 <pre class="example">     ./configure
4369      make
4370      make check
4371      make install
4372 </pre>
4373    <p class="noindent">to install in under the default prefix, <samp><span class="file">/usr/local</span></samp>.
4374
4375    <p>To get a list of configure options, use <code>./configure --help</code>.
4376
4377    <p>By default, both static and shared libraries are built and installed. To
4378 omit building the shared libraries, use the <samp><span class="option"> --disable-shared</span></samp>
4379 option to <samp><span class="command">./configure</span></samp>.
4380
4381    <p>Using GNU make is recommended. For other make programs, in particular
4382 BSD make, you may have to use the <samp><span class="option">--disable-dependency-tracking</span></samp>
4383 option to <samp><span class="command">./configure</span></samp>.
4384
4385 <div class="node">
4386 <a name="Index"></a>
4387 <p><hr>
4388 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Installation">Installation</a>,
4389 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
4390
4391 </div>
4392
4393 <!-- node-name,  next,  previous,  up -->
4394 <h2 class="unnumbered">Function and Concept Index</h2>
4395
4396 <ul class="index-cp" compact>
4397 <li><a href="#index-aes_005fdecrypt-113"><code>aes_decrypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4398 <li><a href="#index-aes_005fencrypt-112"><code>aes_encrypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4399 <li><a href="#index-aes_005finvert_005fkey-111"><code>aes_invert_key</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4400 <li><a href="#index-aes_005fset_005fdecrypt_005fkey-110"><code>aes_set_decrypt_key</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4401 <li><a href="#index-aes_005fset_005fencrypt_005fkey-109"><code>aes_set_encrypt_key</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4402 <li><a href="#index-arcfour_005fcrypt-119"><code>arcfour_crypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4403 <li><a href="#index-arcfour_005fset_005fkey-118"><code>arcfour_set_key</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4404 <li><a href="#index-arctwo_005fdecrypt-129"><code>arctwo_decrypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4405 <li><a href="#index-arctwo_005fencrypt-128"><code>arctwo_encrypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4406 <li><a href="#index-arctwo_005fset_005fkey-126"><code>arctwo_set_key</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4407 <li><a href="#index-arctwo_005fset_005fkey_005fekb-125"><code>arctwo_set_key_ekb</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4408 <li><a href="#index-arctwo_005fset_005fkey_005fgutmann-127"><code>arctwo_set_key_gutmann</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4409 <li><a href="#index-base16_005fdecode_005ffinal-418"><code>base16_decode_final</code></a>: <a href="#ASCII-encoding">ASCII encoding</a></li>
4410 <li><a href="#index-base16_005fdecode_005finit-414"><code>base16_decode_init</code></a>: <a href="#ASCII-encoding">ASCII encoding</a></li>
4411 <li><a href="#index-BASE16_005fDECODE_005fLENGTH-416"><code>BASE16_DECODE_LENGTH</code></a>: <a href="#ASCII-encoding">ASCII encoding</a></li>
4412 <li><a href="#index-base16_005fdecode_005fsingle-415"><code>base16_decode_single</code></a>: <a href="#ASCII-encoding">ASCII encoding</a></li>
4413 <li><a href="#index-base16_005fdecode_005fupdate-417"><code>base16_decode_update</code></a>: <a href="#ASCII-encoding">ASCII encoding</a></li>
4414 <li><a href="#index-BASE16_005fENCODE_005fLENGTH-411"><code>BASE16_ENCODE_LENGTH</code></a>: <a href="#ASCII-encoding">ASCII encoding</a></li>
4415 <li><a href="#index-base16_005fencode_005fsingle-410"><code>base16_encode_single</code></a>: <a href="#ASCII-encoding">ASCII encoding</a></li>
4416 <li><a href="#index-base16_005fencode_005fupdate-412"><code>base16_encode_update</code></a>: <a href="#ASCII-encoding">ASCII encoding</a></li>
4417 <li><a href="#index-base64_005fdecode_005ffinal-409"><code>base64_decode_final</code></a>: <a href="#ASCII-encoding">ASCII encoding</a></li>
4418 <li><a href="#index-base64_005fdecode_005finit-405"><code>base64_decode_init</code></a>: <a href="#ASCII-encoding">ASCII encoding</a></li>
4419 <li><a href="#index-BASE64_005fDECODE_005fLENGTH-407"><code>BASE64_DECODE_LENGTH</code></a>: <a href="#ASCII-encoding">ASCII encoding</a></li>
4420 <li><a href="#index-base64_005fdecode_005fsingle-406"><code>base64_decode_single</code></a>: <a href="#ASCII-encoding">ASCII encoding</a></li>
4421 <li><a href="#index-base64_005fdecode_005fupdate-408"><code>base64_decode_update</code></a>: <a href="#ASCII-encoding">ASCII encoding</a></li>
4422 <li><a href="#index-base64_005fencode_005ffinal-403"><code>base64_encode_final</code></a>: <a href="#ASCII-encoding">ASCII encoding</a></li>
4423 <li><a href="#index-base64_005fencode_005finit-398"><code>base64_encode_init</code></a>: <a href="#ASCII-encoding">ASCII encoding</a></li>
4424 <li><a href="#index-BASE64_005fENCODE_005fLENGTH-400"><code>BASE64_ENCODE_LENGTH</code></a>: <a href="#ASCII-encoding">ASCII encoding</a></li>
4425 <li><a href="#index-base64_005fencode_005fsingle-399"><code>base64_encode_single</code></a>: <a href="#ASCII-encoding">ASCII encoding</a></li>
4426 <li><a href="#index-base64_005fencode_005fupdate-401"><code>base64_encode_update</code></a>: <a href="#ASCII-encoding">ASCII encoding</a></li>
4427 <li><a href="#index-Block-Cipher-102">Block Cipher</a>: <a href="#Cipher-functions">Cipher functions</a></li>
4428 <li><a href="#index-blowfish_005fdecrypt-137"><code>blowfish_decrypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4429 <li><a href="#index-blowfish_005fencrypt-136"><code>blowfish_encrypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4430 <li><a href="#index-blowfish_005fset_005fkey-135"><code>blowfish_set_key</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4431 <li><a href="#index-camellia_005fcrypt-146"><code>camellia_crypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4432 <li><a href="#index-camellia_005finvert_005fkey-145"><code>camellia_invert_key</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4433 <li><a href="#index-camellia_005fset_005fdecrypt_005fkey-144"><code>camellia_set_decrypt_key</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4434 <li><a href="#index-camellia_005fset_005fencrypt_005fkey-143"><code>camellia_set_encrypt_key</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4435 <li><a href="#index-cast128_005fdecrypt-154"><code>cast128_decrypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4436 <li><a href="#index-cast128_005fencrypt-153"><code>cast128_encrypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4437 <li><a href="#index-cast128_005fset_005fkey-152"><code>cast128_set_key</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4438 <li><a href="#index-CBC-Mode-216">CBC Mode</a>: <a href="#CBC">CBC</a></li>
4439 <li><a href="#index-CBC_005fCTX-219"><code>CBC_CTX</code></a>: <a href="#CBC">CBC</a></li>
4440 <li><a href="#index-CBC_005fDECRYPT-222"><code>CBC_DECRYPT</code></a>: <a href="#CBC">CBC</a></li>
4441 <li><a href="#index-cbc_005fdecrypt-218"><code>cbc_decrypt</code></a>: <a href="#CBC">CBC</a></li>
4442 <li><a href="#index-CBC_005fENCRYPT-221"><code>CBC_ENCRYPT</code></a>: <a href="#CBC">CBC</a></li>
4443 <li><a href="#index-cbc_005fencrypt-217"><code>cbc_encrypt</code></a>: <a href="#CBC">CBC</a></li>
4444 <li><a href="#index-CBC_005fSET_005fIV-220"><code>CBC_SET_IV</code></a>: <a href="#CBC">CBC</a></li>
4445 <li><a href="#index-Cipher-101">Cipher</a>: <a href="#Cipher-functions">Cipher functions</a></li>
4446 <li><a href="#index-Cipher-Block-Chaining-215">Cipher Block Chaining</a>: <a href="#CBC">CBC</a></li>
4447 <li><a href="#index-Collision_002dresistant-3">Collision-resistant</a>: <a href="#Hash-functions">Hash functions</a></li>
4448 <li><a href="#index-Conditional-entropy-382">Conditional entropy</a>: <a href="#Randomness">Randomness</a></li>
4449 <li><a href="#index-Counter-Mode-223">Counter Mode</a>: <a href="#CTR">CTR</a></li>
4450 <li><a href="#index-CTR-Mode-224">CTR Mode</a>: <a href="#CTR">CTR</a></li>
4451 <li><a href="#index-CTR_005fCRYPT-228"><code>CTR_CRYPT</code></a>: <a href="#CTR">CTR</a></li>
4452 <li><a href="#index-ctr_005fcrypt-225"><code>ctr_crypt</code></a>: <a href="#CTR">CTR</a></li>
4453 <li><a href="#index-CTR_005fCTX-226"><code>CTR_CTX</code></a>: <a href="#CTR">CTR</a></li>
4454 <li><a href="#index-CTR_005fSET_005fCOUNTER-227"><code>CTR_SET_COUNTER</code></a>: <a href="#CTR">CTR</a></li>
4455 <li><a href="#index-des3_005fdecrypt-168"><code>des3_decrypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4456 <li><a href="#index-des3_005fencrypt-167"><code>des3_encrypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4457 <li><a href="#index-des3_005fset_005fkey-166"><code>des3_set_key</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4458 <li><a href="#index-des_005fcheck_005fparity-161"><code>des_check_parity</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4459 <li><a href="#index-des_005fdecrypt-160"><code>des_decrypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4460 <li><a href="#index-des_005fencrypt-159"><code>des_encrypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4461 <li><a href="#index-des_005ffix_005fparity-162"><code>des_fix_parity</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4462 <li><a href="#index-des_005fset_005fkey-158"><code>des_set_key</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4463 <li><a href="#index-dsa_005fgenerate_005fkeypair-366"><code>dsa_generate_keypair</code></a>: <a href="#DSA">DSA</a></li>
4464 <li><a href="#index-dsa_005fprivate_005fkey_005fclear-354"><code>dsa_private_key_clear</code></a>: <a href="#DSA">DSA</a></li>
4465 <li><a href="#index-dsa_005fprivate_005fkey_005finit-352"><code>dsa_private_key_init</code></a>: <a href="#DSA">DSA</a></li>
4466 <li><a href="#index-dsa_005fpublic_005fkey_005fclear-353"><code>dsa_public_key_clear</code></a>: <a href="#DSA">DSA</a></li>
4467 <li><a href="#index-dsa_005fpublic_005fkey_005finit-351"><code>dsa_public_key_init</code></a>: <a href="#DSA">DSA</a></li>
4468 <li><a href="#index-dsa_005fsha1_005fsign-358"><code>dsa_sha1_sign</code></a>: <a href="#DSA">DSA</a></li>
4469 <li><a href="#index-dsa_005fsha1_005fsign_005fdigest-359"><code>dsa_sha1_sign_digest</code></a>: <a href="#DSA">DSA</a></li>
4470 <li><a href="#index-dsa_005fsha1_005fverify-362"><code>dsa_sha1_verify</code></a>: <a href="#DSA">DSA</a></li>
4471 <li><a href="#index-dsa_005fsha1_005fverify_005fdigest-363"><code>dsa_sha1_verify_digest</code></a>: <a href="#DSA">DSA</a></li>
4472 <li><a href="#index-dsa_005fsha256_005fsign-360"><code>dsa_sha256_sign</code></a>: <a href="#DSA">DSA</a></li>
4473 <li><a href="#index-dsa_005fsha256_005fsign_005fdigest-361"><code>dsa_sha256_sign_digest</code></a>: <a href="#DSA">DSA</a></li>
4474 <li><a href="#index-dsa_005fsha256_005fverify-364"><code>dsa_sha256_verify</code></a>: <a href="#DSA">DSA</a></li>
4475 <li><a href="#index-dsa_005fsha256_005fverify_005fdigest-365"><code>dsa_sha256_verify_digest</code></a>: <a href="#DSA">DSA</a></li>
4476 <li><a href="#index-dsa_005fsignature_005fclear-357"><code>dsa_signature_clear</code></a>: <a href="#DSA">DSA</a></li>
4477 <li><a href="#index-dsa_005fsignature_005finit-356"><code>dsa_signature_init</code></a>: <a href="#DSA">DSA</a></li>
4478 <li><a href="#index-ecc_005fpoint_005fclear-369"><code>ecc_point_clear</code></a>: <a href="#Elliptic-curves">Elliptic curves</a></li>
4479 <li><a href="#index-ecc_005fpoint_005fget-371"><code>ecc_point_get</code></a>: <a href="#Elliptic-curves">Elliptic curves</a></li>
4480 <li><a href="#index-ecc_005fpoint_005finit-368"><code>ecc_point_init</code></a>: <a href="#Elliptic-curves">Elliptic curves</a></li>
4481 <li><a href="#index-ecc_005fpoint_005fset-370"><code>ecc_point_set</code></a>: <a href="#Elliptic-curves">Elliptic curves</a></li>
4482 <li><a href="#index-ecc_005fscalar_005fclear-374"><code>ecc_scalar_clear</code></a>: <a href="#Elliptic-curves">Elliptic curves</a></li>
4483 <li><a href="#index-ecc_005fscalar_005fget-376"><code>ecc_scalar_get</code></a>: <a href="#Elliptic-curves">Elliptic curves</a></li>
4484 <li><a href="#index-ecc_005fscalar_005finit-373"><code>ecc_scalar_init</code></a>: <a href="#Elliptic-curves">Elliptic curves</a></li>
4485 <li><a href="#index-ecc_005fscalar_005fset-375"><code>ecc_scalar_set</code></a>: <a href="#Elliptic-curves">Elliptic curves</a></li>
4486 <li><a href="#index-ecdsa_005fgenerate_005fkeypair-379"><code>ecdsa_generate_keypair</code></a>: <a href="#Elliptic-curves">Elliptic curves</a></li>
4487 <li><a href="#index-ecdsa_005fsign-377"><code>ecdsa_sign</code></a>: <a href="#Elliptic-curves">Elliptic curves</a></li>
4488 <li><a href="#index-ecdsa_005fverify-378"><code>ecdsa_verify</code></a>: <a href="#Elliptic-curves">Elliptic curves</a></li>
4489 <li><a href="#index-Entropy-381">Entropy</a>: <a href="#Randomness">Randomness</a></li>
4490 <li><a href="#index-Galois-Counter-Mode-229">Galois Counter Mode</a>: <a href="#GCM">GCM</a></li>
4491 <li><a href="#index-GCM-230">GCM</a>: <a href="#GCM">GCM</a></li>
4492 <li><a href="#index-gcm_005faes_005fdecrypt-253"><code>gcm_aes_decrypt</code></a>: <a href="#GCM">GCM</a></li>
4493 <li><a href="#index-gcm_005faes_005fdigest-254"><code>gcm_aes_digest</code></a>: <a href="#GCM">GCM</a></li>
4494 <li><a href="#index-gcm_005faes_005fencrypt-252"><code>gcm_aes_encrypt</code></a>: <a href="#GCM">GCM</a></li>
4495 <li><a href="#index-gcm_005faes_005fset_005fiv-250"><code>gcm_aes_set_iv</code></a>: <a href="#GCM">GCM</a></li>
4496 <li><a href="#index-gcm_005faes_005fset_005fkey-249"><code>gcm_aes_set_key</code></a>: <a href="#GCM">GCM</a></li>
4497 <li><a href="#index-gcm_005faes_005fupdate-251"><code>gcm_aes_update</code></a>: <a href="#GCM">GCM</a></li>
4498 <li><a href="#index-GCM_005fCTX-241"><code>GCM_CTX</code></a>: <a href="#GCM">GCM</a></li>
4499 <li><a href="#index-GCM_005fDECRYPT-246"><code>GCM_DECRYPT</code></a>: <a href="#GCM">GCM</a></li>
4500 <li><a href="#index-gcm_005fdecrypt-239"><code>gcm_decrypt</code></a>: <a href="#GCM">GCM</a></li>
4501 <li><a href="#index-GCM_005fDIGEST-247"><code>GCM_DIGEST</code></a>: <a href="#GCM">GCM</a></li>
4502 <li><a href="#index-gcm_005fdigest-240"><code>gcm_digest</code></a>: <a href="#GCM">GCM</a></li>
4503 <li><a href="#index-GCM_005fENCRYPT-245"><code>GCM_ENCRYPT</code></a>: <a href="#GCM">GCM</a></li>
4504 <li><a href="#index-gcm_005fencrypt-238"><code>gcm_encrypt</code></a>: <a href="#GCM">GCM</a></li>
4505 <li><a href="#index-GCM_005fSET_005fIV-243"><code>GCM_SET_IV</code></a>: <a href="#GCM">GCM</a></li>
4506 <li><a href="#index-gcm_005fset_005fiv-236"><code>gcm_set_iv</code></a>: <a href="#GCM">GCM</a></li>
4507 <li><a href="#index-GCM_005fSET_005fKEY-242"><code>GCM_SET_KEY</code></a>: <a href="#GCM">GCM</a></li>
4508 <li><a href="#index-gcm_005fset_005fkey-235"><code>gcm_set_key</code></a>: <a href="#GCM">GCM</a></li>
4509 <li><a href="#index-GCM_005fUPDATE-244"><code>GCM_UPDATE</code></a>: <a href="#GCM">GCM</a></li>
4510 <li><a href="#index-gcm_005fupdate-237"><code>gcm_update</code></a>: <a href="#GCM">GCM</a></li>
4511 <li><a href="#index-gosthash94_005fdigest-87"><code>gosthash94_digest</code></a>: <a href="#Legacy-hash-functions">Legacy hash functions</a></li>
4512 <li><a href="#index-gosthash94_005finit-85"><code>gosthash94_init</code></a>: <a href="#Legacy-hash-functions">Legacy hash functions</a></li>
4513 <li><a href="#index-gosthash94_005fupdate-86"><code>gosthash94_update</code></a>: <a href="#Legacy-hash-functions">Legacy hash functions</a></li>
4514 <li><a href="#index-Hash-function-1">Hash function</a>: <a href="#Hash-functions">Hash functions</a></li>
4515 <li><a href="#index-HMAC-258">HMAC</a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4516 <li><a href="#index-HMAC_005fCTX-262"><code>HMAC_CTX</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4517 <li><a href="#index-HMAC_005fDIGEST-264"><code>HMAC_DIGEST</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4518 <li><a href="#index-hmac_005fdigest-261"><code>hmac_digest</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4519 <li><a href="#index-hmac_005fmd5_005fdigest-268"><code>hmac_md5_digest</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4520 <li><a href="#index-hmac_005fmd5_005fset_005fkey-266"><code>hmac_md5_set_key</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4521 <li><a href="#index-hmac_005fmd5_005fupdate-267"><code>hmac_md5_update</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4522 <li><a href="#index-hmac_005fripemd160_005fdigest-272"><code>hmac_ripemd160_digest</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4523 <li><a href="#index-hmac_005fripemd160_005fset_005fkey-270"><code>hmac_ripemd160_set_key</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4524 <li><a href="#index-hmac_005fripemd160_005fupdate-271"><code>hmac_ripemd160_update</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4525 <li><a href="#index-HMAC_005fSET_005fKEY-263"><code>HMAC_SET_KEY</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4526 <li><a href="#index-hmac_005fset_005fkey-259"><code>hmac_set_key</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4527 <li><a href="#index-hmac_005fsha1_005fdigest-276"><code>hmac_sha1_digest</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4528 <li><a href="#index-hmac_005fsha1_005fset_005fkey-274"><code>hmac_sha1_set_key</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4529 <li><a href="#index-hmac_005fsha1_005fupdate-275"><code>hmac_sha1_update</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4530 <li><a href="#index-hmac_005fsha256_005fdigest-280"><code>hmac_sha256_digest</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4531 <li><a href="#index-hmac_005fsha256_005fset_005fkey-278"><code>hmac_sha256_set_key</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4532 <li><a href="#index-hmac_005fsha256_005fupdate-279"><code>hmac_sha256_update</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4533 <li><a href="#index-hmac_005fsha512_005fdigest-284"><code>hmac_sha512_digest</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4534 <li><a href="#index-hmac_005fsha512_005fset_005fkey-282"><code>hmac_sha512_set_key</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4535 <li><a href="#index-hmac_005fsha512_005fupdate-283"><code>hmac_sha512_update</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4536 <li><a href="#index-hmac_005fupdate-260"><code>hmac_update</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4537 <li><a href="#index-KDF-315">KDF</a>: <a href="#Key-derivation-functions">Key derivation functions</a></li>
4538 <li><a href="#index-Key-Derivation-Function-312">Key Derivation Function</a>: <a href="#Key-derivation-functions">Key derivation functions</a></li>
4539 <li><a href="#index-Keyed-Hash-Function-255">Keyed Hash Function</a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4540 <li><a href="#index-MAC-257">MAC</a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4541 <li><a href="#index-md2_005fdigest-63"><code>md2_digest</code></a>: <a href="#Legacy-hash-functions">Legacy hash functions</a></li>
4542 <li><a href="#index-md2_005finit-61"><code>md2_init</code></a>: <a href="#Legacy-hash-functions">Legacy hash functions</a></li>
4543 <li><a href="#index-md2_005fupdate-62"><code>md2_update</code></a>: <a href="#Legacy-hash-functions">Legacy hash functions</a></li>
4544 <li><a href="#index-md4_005fdigest-69"><code>md4_digest</code></a>: <a href="#Legacy-hash-functions">Legacy hash functions</a></li>
4545 <li><a href="#index-md4_005finit-67"><code>md4_init</code></a>: <a href="#Legacy-hash-functions">Legacy hash functions</a></li>
4546 <li><a href="#index-md4_005fupdate-68"><code>md4_update</code></a>: <a href="#Legacy-hash-functions">Legacy hash functions</a></li>
4547 <li><a href="#index-md5_005fdigest-57"><code>md5_digest</code></a>: <a href="#Legacy-hash-functions">Legacy hash functions</a></li>
4548 <li><a href="#index-md5_005finit-55"><code>md5_init</code></a>: <a href="#Legacy-hash-functions">Legacy hash functions</a></li>
4549 <li><a href="#index-md5_005fupdate-56"><code>md5_update</code></a>: <a href="#Legacy-hash-functions">Legacy hash functions</a></li>
4550 <li><a href="#index-memxor-419"><code>memxor</code></a>: <a href="#Miscellaneous-functions">Miscellaneous functions</a></li>
4551 <li><a href="#index-Message-Authentication-Code-256">Message Authentication Code</a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4552 <li><a href="#index-One_002dway-2">One-way</a>: <a href="#Hash-functions">Hash functions</a></li>
4553 <li><a href="#index-One_002dway-function-322">One-way function</a>: <a href="#Public_002dkey-algorithms">Public-key algorithms</a></li>
4554 <li><a href="#index-Password-Based-Key-Derivation-Function-313">Password Based Key Derivation Function</a>: <a href="#Key-derivation-functions">Key derivation functions</a></li>
4555 <li><a href="#index-PBKDF-316">PBKDF</a>: <a href="#Key-derivation-functions">Key derivation functions</a></li>
4556 <li><a href="#index-PBKDF2-318"><code>PBKDF2</code></a>: <a href="#Key-derivation-functions">Key derivation functions</a></li>
4557 <li><a href="#index-pbkdf2-317"><code>pbkdf2</code></a>: <a href="#Key-derivation-functions">Key derivation functions</a></li>
4558 <li><a href="#index-pbkdf2_005fhmac_005fsha1-319"><code>pbkdf2_hmac_sha1</code></a>: <a href="#Key-derivation-functions">Key derivation functions</a></li>
4559 <li><a href="#index-pbkdf2_005fhmac_005fsha256-320"><code>pbkdf2_hmac_sha256</code></a>: <a href="#Key-derivation-functions">Key derivation functions</a></li>
4560 <li><a href="#index-PKCS-_00235-314">PKCS #5</a>: <a href="#Key-derivation-functions">Key derivation functions</a></li>
4561 <li><a href="#index-Public-Key-Cryptography-321">Public Key Cryptography</a>: <a href="#Public_002dkey-algorithms">Public-key algorithms</a></li>
4562 <li><a href="#index-Randomness-380">Randomness</a>: <a href="#Randomness">Randomness</a></li>
4563 <li><a href="#index-ripemd160_005fdigest-75"><code>ripemd160_digest</code></a>: <a href="#Legacy-hash-functions">Legacy hash functions</a></li>
4564 <li><a href="#index-ripemd160_005finit-73"><code>ripemd160_init</code></a>: <a href="#Legacy-hash-functions">Legacy hash functions</a></li>
4565 <li><a href="#index-ripemd160_005fupdate-74"><code>ripemd160_update</code></a>: <a href="#Legacy-hash-functions">Legacy hash functions</a></li>
4566 <li><a href="#index-rsa_005fcompute_005froot-347"><code>rsa_compute_root</code></a>: <a href="#RSA">RSA</a></li>
4567 <li><a href="#index-rsa_005fgenerate_005fkeypair-348"><code>rsa_generate_keypair</code></a>: <a href="#RSA">RSA</a></li>
4568 <li><a href="#index-rsa_005fmd5_005fsign-331"><code>rsa_md5_sign</code></a>: <a href="#RSA">RSA</a></li>
4569 <li><a href="#index-rsa_005fmd5_005fsign_005fdigest-335"><code>rsa_md5_sign_digest</code></a>: <a href="#RSA">RSA</a></li>
4570 <li><a href="#index-rsa_005fmd5_005fverify-339"><code>rsa_md5_verify</code></a>: <a href="#RSA">RSA</a></li>
4571 <li><a href="#index-rsa_005fmd5_005fverify_005fdigest-343"><code>rsa_md5_verify_digest</code></a>: <a href="#RSA">RSA</a></li>
4572 <li><a href="#index-rsa_005fprivate_005fkey_005fclear-328"><code>rsa_private_key_clear</code></a>: <a href="#RSA">RSA</a></li>
4573 <li><a href="#index-rsa_005fprivate_005fkey_005finit-326"><code>rsa_private_key_init</code></a>: <a href="#RSA">RSA</a></li>
4574 <li><a href="#index-rsa_005fprivate_005fkey_005fprepare-330"><code>rsa_private_key_prepare</code></a>: <a href="#RSA">RSA</a></li>
4575 <li><a href="#index-rsa_005fpublic_005fkey_005fclear-327"><code>rsa_public_key_clear</code></a>: <a href="#RSA">RSA</a></li>
4576 <li><a href="#index-rsa_005fpublic_005fkey_005finit-325"><code>rsa_public_key_init</code></a>: <a href="#RSA">RSA</a></li>
4577 <li><a href="#index-rsa_005fpublic_005fkey_005fprepare-329"><code>rsa_public_key_prepare</code></a>: <a href="#RSA">RSA</a></li>
4578 <li><a href="#index-rsa_005fsha1_005fsign-332"><code>rsa_sha1_sign</code></a>: <a href="#RSA">RSA</a></li>
4579 <li><a href="#index-rsa_005fsha1_005fsign_005fdigest-336"><code>rsa_sha1_sign_digest</code></a>: <a href="#RSA">RSA</a></li>
4580 <li><a href="#index-rsa_005fsha1_005fverify-340"><code>rsa_sha1_verify</code></a>: <a href="#RSA">RSA</a></li>
4581 <li><a href="#index-rsa_005fsha1_005fverify_005fdigest-344"><code>rsa_sha1_verify_digest</code></a>: <a href="#RSA">RSA</a></li>
4582 <li><a href="#index-rsa_005fsha256_005fsign-333"><code>rsa_sha256_sign</code></a>: <a href="#RSA">RSA</a></li>
4583 <li><a href="#index-rsa_005fsha256_005fsign_005fdigest-337"><code>rsa_sha256_sign_digest</code></a>: <a href="#RSA">RSA</a></li>
4584 <li><a href="#index-rsa_005fsha256_005fverify-341"><code>rsa_sha256_verify</code></a>: <a href="#RSA">RSA</a></li>
4585 <li><a href="#index-rsa_005fsha256_005fverify_005fdigest-345"><code>rsa_sha256_verify_digest</code></a>: <a href="#RSA">RSA</a></li>
4586 <li><a href="#index-rsa_005fsha512_005fsign-334"><code>rsa_sha512_sign</code></a>: <a href="#RSA">RSA</a></li>
4587 <li><a href="#index-rsa_005fsha512_005fsign_005fdigest-338"><code>rsa_sha512_sign_digest</code></a>: <a href="#RSA">RSA</a></li>
4588 <li><a href="#index-rsa_005fsha512_005fverify-342"><code>rsa_sha512_verify</code></a>: <a href="#RSA">RSA</a></li>
4589 <li><a href="#index-rsa_005fsha512_005fverify_005fdigest-346"><code>rsa_sha512_verify_digest</code></a>: <a href="#RSA">RSA</a></li>
4590 <li><a href="#index-salsa20_005fcrypt-177"><code>salsa20_crypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4591 <li><a href="#index-salsa20_005fset_005fiv-176"><code>salsa20_set_iv</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4592 <li><a href="#index-salsa20_005fset_005fkey-175"><code>salsa20_set_key</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4593 <li><a href="#index-salsa20r12_005fcrypt-178"><code>salsa20r12_crypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4594 <li><a href="#index-serpent_005fdecrypt-186"><code>serpent_decrypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4595 <li><a href="#index-serpent_005fencrypt-185"><code>serpent_encrypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4596 <li><a href="#index-serpent_005fset_005fkey-184"><code>serpent_set_key</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4597 <li><a href="#index-sha1_005fdigest-81"><code>sha1_digest</code></a>: <a href="#Legacy-hash-functions">Legacy hash functions</a></li>
4598 <li><a href="#index-sha1_005finit-79"><code>sha1_init</code></a>: <a href="#Legacy-hash-functions">Legacy hash functions</a></li>
4599 <li><a href="#index-sha1_005fupdate-80"><code>sha1_update</code></a>: <a href="#Legacy-hash-functions">Legacy hash functions</a></li>
4600 <li><a href="#index-sha224_005fdigest-15"><code>sha224_digest</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4601 <li><a href="#index-sha224_005finit-13"><code>sha224_init</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4602 <li><a href="#index-sha224_005fupdate-14"><code>sha224_update</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4603 <li><a href="#index-sha256_005fdigest-9"><code>sha256_digest</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4604 <li><a href="#index-sha256_005finit-7"><code>sha256_init</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4605 <li><a href="#index-sha256_005fupdate-8"><code>sha256_update</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4606 <li><a href="#index-sha384_005fdigest-27"><code>sha384_digest</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4607 <li><a href="#index-sha384_005finit-25"><code>sha384_init</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4608 <li><a href="#index-sha384_005fupdate-26"><code>sha384_update</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4609 <li><a href="#index-sha3_005f224_005fdigest-33"><code>sha3_224_digest</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4610 <li><a href="#index-sha3_005f224_005finit-31"><code>sha3_224_init</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4611 <li><a href="#index-sha3_005f224_005fupdate-32"><code>sha3_224_update</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4612 <li><a href="#index-sha3_005f256_005fdigest-39"><code>sha3_256_digest</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4613 <li><a href="#index-sha3_005f256_005finit-37"><code>sha3_256_init</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4614 <li><a href="#index-sha3_005f256_005fupdate-38"><code>sha3_256_update</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4615 <li><a href="#index-sha3_005f384_005fdigest-45"><code>sha3_384_digest</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4616 <li><a href="#index-sha3_005f384_005finit-43"><code>sha3_384_init</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4617 <li><a href="#index-sha3_005f384_005fupdate-44"><code>sha3_384_update</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4618 <li><a href="#index-sha3_005f512_005fdigest-51"><code>sha3_512_digest</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4619 <li><a href="#index-sha3_005f512_005finit-49"><code>sha3_512_init</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4620 <li><a href="#index-sha3_005f512_005fupdate-50"><code>sha3_512_update</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4621 <li><a href="#index-sha512_005fdigest-21"><code>sha512_digest</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4622 <li><a href="#index-sha512_005finit-19"><code>sha512_init</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4623 <li><a href="#index-sha512_005fupdate-20"><code>sha512_update</code></a>: <a href="#Recommended-hash-functions">Recommended hash functions</a></li>
4624 <li><a href="#index-Stream-Cipher-103">Stream Cipher</a>: <a href="#Cipher-functions">Cipher functions</a></li>
4625 <li><a href="#index-twofish_005fdecrypt-194"><code>twofish_decrypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4626 <li><a href="#index-twofish_005fencrypt-193"><code>twofish_encrypt</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4627 <li><a href="#index-twofish_005fset_005fkey-192"><code>twofish_set_key</code></a>: <a href="#Cipher-functions">Cipher functions</a></li>
4628 <li><a href="#index-UMAC-285">UMAC</a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4629 <li><a href="#index-umac128_005fdigest-311"><code>umac128_digest</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4630 <li><a href="#index-umac128_005fset_005fkey-299"><code>umac128_set_key</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4631 <li><a href="#index-umac128_005fset_005fnonce-303"><code>umac128_set_nonce</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4632 <li><a href="#index-umac128_005fupdate-307"><code>umac128_update</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4633 <li><a href="#index-umac32_005fdigest-308"><code>umac32_digest</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4634 <li><a href="#index-umac32_005fset_005fkey-296"><code>umac32_set_key</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4635 <li><a href="#index-umac32_005fset_005fnonce-300"><code>umac32_set_nonce</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4636 <li><a href="#index-umac32_005fupdate-304"><code>umac32_update</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4637 <li><a href="#index-umac64_005fdigest-309"><code>umac64_digest</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4638 <li><a href="#index-umac64_005fset_005fkey-297"><code>umac64_set_key</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4639 <li><a href="#index-umac64_005fset_005fnonce-301"><code>umac64_set_nonce</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4640 <li><a href="#index-umac64_005fupdate-305"><code>umac64_update</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4641 <li><a href="#index-umac96_005fdigest-310"><code>umac96_digest</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4642 <li><a href="#index-umac96_005fset_005fkey-298"><code>umac96_set_key</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4643 <li><a href="#index-umac96_005fset_005fnonce-302"><code>umac96_set_nonce</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4644 <li><a href="#index-umac96_005fupdate-306"><code>umac96_update</code></a>: <a href="#Keyed-hash-functions">Keyed hash functions</a></li>
4645 <li><a href="#index-yarrow256_005ffast_005freseed-392"><code>yarrow256_fast_reseed</code></a>: <a href="#Randomness">Randomness</a></li>
4646 <li><a href="#index-yarrow256_005finit-386"><code>yarrow256_init</code></a>: <a href="#Randomness">Randomness</a></li>
4647 <li><a href="#index-yarrow256_005fis_005fseeded-390"><code>yarrow256_is_seeded</code></a>: <a href="#Randomness">Randomness</a></li>
4648 <li><a href="#index-yarrow256_005fneeded_005fsources-391"><code>yarrow256_needed_sources</code></a>: <a href="#Randomness">Randomness</a></li>
4649 <li><a href="#index-yarrow256_005frandom-389"><code>yarrow256_random</code></a>: <a href="#Randomness">Randomness</a></li>
4650 <li><a href="#index-yarrow256_005fseed-387"><code>yarrow256_seed</code></a>: <a href="#Randomness">Randomness</a></li>
4651 <li><a href="#index-yarrow256_005fslow_005freseed-393"><code>yarrow256_slow_reseed</code></a>: <a href="#Randomness">Randomness</a></li>
4652 <li><a href="#index-yarrow256_005fupdate-388"><code>yarrow256_update</code></a>: <a href="#Randomness">Randomness</a></li>
4653 <li><a href="#index-yarrow_005fkey_005fevent_005festimate-396"><code>yarrow_key_event_estimate</code></a>: <a href="#Randomness">Randomness</a></li>
4654 <li><a href="#index-yarrow_005fkey_005fevent_005finit-395"><code>yarrow_key_event_init</code></a>: <a href="#Randomness">Randomness</a></li>
4655    </ul><div class="footnote">
4656 <hr>
4657 <a name="texinfo-footnotes-in-document"></a><h4>Fotnoter</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> Actually, the computation is not done like this, it is
4658 done more efficiently using <code>p</code>, <code>q</code> and the Chinese remainder
4659 theorem (<acronym>CRT</acronym>). But the result is the same.</p>
4660
4661    <hr></div>
4662
4663 </body></html>
4664
4665 <!--
4666 \1f
4667 Local Variables:
4668 coding: utf-8
4669 End:
4670
4671 -->