nettle.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <!-- This manual is for the Nettle library (version 3.2), a
   4 low-level cryptographic library.
   5
   6 Originally written 2001 by Niels Möller, updated 2015.
   7
   8 This manual is placed in the public domain. You may freely copy it, in
   9 whole or in part, with or without modification. Attribution is
  10 appreciated, but not required. -->
  11 <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
  12 <head>
  13 <title>Nettle: a low-level cryptographic library</title>
  14
  15 <meta name="description" content="Nettle: a low-level cryptographic library">
  16 <meta name="keywords" content="Nettle: a low-level cryptographic library">
  17 <meta name="resource-type" content="document">
  18 <meta name="distribution" content="global">
  19 <meta name="Generator" content="makeinfo">
  20 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  21 <link href="#Top" rel="start" title="Top">
  22 <link href="#Index" rel="index" title="Index">
  23 <link href="#SEC_Contents" rel="contents" title="Table of Contents">
  24 <link href="dir.html#Top" rel="up" title="(dir)">
  25 <style type="text/css">
  26 <!--
  27 a.summary-letter {text-decoration: none}
  28 blockquote.smallquotation {font-size: smaller}
  29 div.display {margin-left: 3.2em}
  30 div.example {margin-left: 3.2em}
  31 div.indentedblock {margin-left: 3.2em}
  32 div.lisp {margin-left: 3.2em}
  33 div.smalldisplay {margin-left: 3.2em}
  34 div.smallexample {margin-left: 3.2em}
  35 div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
  36 div.smalllisp {margin-left: 3.2em}
  37 kbd {font-style:oblique}
  38 pre.display {font-family: inherit}
  39 pre.format {font-family: inherit}
  40 pre.menu-comment {font-family: serif}
  41 pre.menu-preformatted {font-family: serif}
  42 pre.smalldisplay {font-family: inherit; font-size: smaller}
  43 pre.smallexample {font-size: smaller}
  44 pre.smallformat {font-family: inherit; font-size: smaller}
  45 pre.smalllisp {font-size: smaller}
  46 span.nocodebreak {white-space:nowrap}
  47 span.nolinebreak {white-space:nowrap}
  48 span.roman {font-family:serif; font-weight:normal}
  49 span.sansserif {font-family:sans-serif; font-weight:normal}
  50 ul.no-bullet {list-style: none}
  51 -->
  52 </style>
  53
  54
  55 </head>
  56
  57 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  58 <h1 class="settitle" align="center">Nettle: a low-level cryptographic library</h1>
  59
  60
  61
  62
  63
  64
  65 <a name="SEC_Contents"></a>
  66 <h2 class="contents-heading">Table of Contents</h2>
  67
  68 <div class="contents">
  69
  70 <ul class="no-bullet">
  71   <li><a name="toc-Introduction-1" href="#Introduction">1 Introduction</a></li>
  72   <li><a name="toc-Copyright-1" href="#Copyright">2 Copyright</a></li>
  73   <li><a name="toc-Conventions-1" href="#Conventions">3 Conventions</a></li>
  74   <li><a name="toc-Example-1" href="#Example">4 Example</a></li>
  75   <li><a name="toc-Linking-1" href="#Linking">5 Linking</a></li>
  76   <li><a name="toc-Reference-1" href="#Reference">6 Reference</a>
  77   <ul class="no-bullet">
  78     <li><a name="toc-Hash-functions-1" href="#Hash-functions">6.1 Hash functions</a>
  79     <ul class="no-bullet">
  80       <li><a name="toc-Recommended-hash-functions-1" href="#Recommended-hash-functions">6.1.1 Recommended hash functions</a>
  81       <ul class="no-bullet">
  82         <li><a name="toc-SHA256" href="#SHA256">6.1.1.1 <acronym>SHA256</acronym></a></li>
  83         <li><a name="toc-SHA224" href="#SHA224">6.1.1.2 <acronym>SHA224</acronym></a></li>
  84         <li><a name="toc-SHA512" href="#SHA512">6.1.1.3 <acronym>SHA512</acronym></a></li>
  85         <li><a name="toc-SHA384-and-other-variants-of-SHA512" href="#SHA384-and-other-variants-of-SHA512">6.1.1.4 <acronym>SHA384 and other variants of SHA512</acronym></a></li>
  86         <li><a name="toc-SHA3_002d224" href="#SHA3_002d224">6.1.1.5 <acronym>SHA3-224</acronym></a></li>
  87         <li><a name="toc-SHA3_002d256" href="#SHA3_002d256">6.1.1.6 <acronym>SHA3-256</acronym></a></li>
  88         <li><a name="toc-SHA3_002d384" href="#SHA3_002d384">6.1.1.7 <acronym>SHA3-384</acronym></a></li>
  89         <li><a name="toc-SHA3_002d512" href="#SHA3_002d512">6.1.1.8 <acronym>SHA3-512</acronym></a></li>
  90       </ul></li>
  91       <li><a name="toc-Legacy-hash-functions-1" href="#Legacy-hash-functions">6.1.2 Legacy hash functions</a>
  92       <ul class="no-bullet">
  93         <li><a name="toc-MD5" href="#MD5">6.1.2.1 <acronym>MD5</acronym></a></li>
  94         <li><a name="toc-MD2" href="#MD2">6.1.2.2 <acronym>MD2</acronym></a></li>
  95         <li><a name="toc-MD4" href="#MD4">6.1.2.3 <acronym>MD4</acronym></a></li>
  96         <li><a name="toc-RIPEMD160" href="#RIPEMD160">6.1.2.4 <acronym>RIPEMD160</acronym></a></li>
  97         <li><a name="toc-SHA1" href="#SHA1">6.1.2.5 <acronym>SHA1</acronym></a></li>
  98         <li><a name="toc-GOSTHASH94" href="#GOSTHASH94">6.1.2.6 <acronym>GOSTHASH94</acronym></a></li>
  99       </ul></li>
 100       <li><a name="toc-The-struct-nettle_005fhash-abstraction" href="#nettle_005fhash-abstraction">6.1.3 The <code>struct nettle_hash</code> abstraction</a></li>
 101     </ul></li>
 102     <li><a name="toc-Cipher-functions-1" href="#Cipher-functions">6.2 Cipher functions</a>
 103     <ul class="no-bullet">
 104       <li><a name="toc-AES" href="#AES">6.2.1 AES</a></li>
 105       <li><a name="toc-ARCFOUR" href="#ARCFOUR">6.2.2 ARCFOUR</a></li>
 106       <li><a name="toc-ARCTWO" href="#ARCTWO">6.2.3 ARCTWO</a></li>
 107       <li><a name="toc-BLOWFISH" href="#BLOWFISH">6.2.4 BLOWFISH</a></li>
 108       <li><a name="toc-Camellia" href="#Camellia">6.2.5 Camellia</a></li>
 109       <li><a name="toc-CAST128" href="#CAST128">6.2.6 CAST128</a></li>
 110       <li><a name="toc-ChaCha" href="#ChaCha">6.2.7 ChaCha</a></li>
 111       <li><a name="toc-DES" href="#DES">6.2.8 DES</a></li>
 112       <li><a name="toc-DES3" href="#DES3">6.2.9 DES3</a></li>
 113       <li><a name="toc-Salsa20" href="#Salsa20">6.2.10 Salsa20</a></li>
 114       <li><a name="toc-SERPENT" href="#SERPENT">6.2.11 SERPENT</a></li>
 115       <li><a name="toc-TWOFISH" href="#TWOFISH">6.2.12 TWOFISH</a></li>
 116       <li><a name="toc-The-struct-nettle_005fcipher-abstraction" href="#The-struct-nettle_005fcipher-abstraction">6.2.13 The <code>struct nettle_cipher</code> abstraction</a></li>
 117     </ul></li>
 118     <li><a name="toc-Cipher-modes-1" href="#Cipher-modes">6.3 Cipher modes</a>
 119     <ul class="no-bullet">
 120       <li><a name="toc-Cipher-Block-Chaining" href="#CBC">6.3.1 Cipher Block Chaining</a></li>
 121       <li><a name="toc-Counter-mode" href="#CTR">6.3.2 Counter mode</a></li>
 122     </ul></li>
 123     <li><a name="toc-Authenticated-encryption-with-associated-data" href="#Authenticated-encryption">6.4 Authenticated encryption with associated data</a>
 124     <ul class="no-bullet">
 125       <li><a name="toc-EAX-1" href="#EAX">6.4.1 EAX</a>
 126       <ul class="no-bullet">
 127         <li><a name="toc-General-EAX-interface" href="#General-EAX-interface">6.4.1.1 General <acronym>EAX</acronym> interface</a></li>
 128         <li><a name="toc-EAX-helper-macros" href="#EAX-helper-macros">6.4.1.2 <acronym>EAX</acronym> helper macros</a></li>
 129         <li><a name="toc-EAX_002dAES128-interface" href="#EAX_002dAES128-interface">6.4.1.3 <acronym>EAX</acronym>-<acronym>AES</acronym>128 interface</a></li>
 130       </ul></li>
 131       <li><a name="toc-Galois-counter-mode" href="#GCM">6.4.2 Galois counter mode</a>
 132       <ul class="no-bullet">
 133         <li><a name="toc-General-GCM-interface" href="#General-GCM-interface">6.4.2.1 General <acronym>GCM</acronym> interface</a></li>
 134         <li><a name="toc-GCM-helper-macros" href="#GCM-helper-macros">6.4.2.2 <acronym>GCM</acronym> helper macros</a></li>
 135         <li><a name="toc-GCM_002dAES-interface" href="#GCM_002dAES-interface">6.4.2.3 <acronym>GCM</acronym>-<acronym>AES</acronym> interface</a></li>
 136         <li><a name="toc-GCM_002dCamellia-interface" href="#GCM_002dCamellia-interface">6.4.2.4 <acronym>GCM</acronym>-Camellia interface</a></li>
 137       </ul></li>
 138       <li><a name="toc-Counter-with-CBC_002dMAC-mode" href="#CCM">6.4.3 Counter with CBC-MAC mode</a>
 139       <ul class="no-bullet">
 140         <li><a name="toc-General-CCM-interface" href="#General-CCM-interface">6.4.3.1 General <acronym>CCM</acronym> interface</a></li>
 141         <li><a name="toc-CCM-message-interface" href="#CCM-message-interface">6.4.3.2 <acronym>CCM</acronym> message interface</a></li>
 142         <li><a name="toc-CCM_002dAES-interface" href="#CCM_002dAES-interface">6.4.3.3 <acronym>CCM</acronym>-<acronym>AES</acronym> interface</a></li>
 143       </ul></li>
 144       <li><a name="toc-ChaCha_002dPoly1305-1" href="#ChaCha_002dPoly1305">6.4.4 ChaCha-Poly1305</a></li>
 145       <li><a name="toc-The-struct-nettle_005faead-abstraction" href="#nettle_005faead-abstraction">6.4.5 The <code>struct nettle_aead</code> abstraction</a></li>
 146     </ul></li>
 147     <li><a name="toc-Keyed-Hash-Functions" href="#Keyed-hash-functions">6.5 Keyed Hash Functions</a>
 148     <ul class="no-bullet">
 149       <li><a name="toc-HMAC-1" href="#HMAC">6.5.1 <acronym>HMAC</acronym></a></li>
 150       <li><a name="toc-Concrete-HMAC-functions" href="#Concrete-HMAC-functions">6.5.2 Concrete <acronym>HMAC</acronym> functions</a>
 151       <ul class="no-bullet">
 152         <li><a name="toc-HMAC_002dMD5" href="#HMAC_002dMD5">6.5.2.1 <acronym>HMAC-MD5</acronym></a></li>
 153         <li><a name="toc-HMAC_002dRIPEMD160" href="#HMAC_002dRIPEMD160">6.5.2.2 <acronym>HMAC-RIPEMD160</acronym></a></li>
 154         <li><a name="toc-HMAC_002dSHA1" href="#HMAC_002dSHA1">6.5.2.3 <acronym>HMAC-SHA1</acronym></a></li>
 155         <li><a name="toc-HMAC_002dSHA256" href="#HMAC_002dSHA256">6.5.2.4 <acronym>HMAC-SHA256</acronym></a></li>
 156         <li><a name="toc-HMAC_002dSHA512" href="#HMAC_002dSHA512">6.5.2.5 <acronym>HMAC-SHA512</acronym></a></li>
 157       </ul></li>
 158       <li><a name="toc-UMAC-1" href="#UMAC">6.5.3 <acronym>UMAC</acronym></a></li>
 159       <li><a name="toc-Poly1305-1" href="#Poly1305">6.5.4 Poly1305</a></li>
 160     </ul></li>
 161     <li><a name="toc-Key-derivation-Functions" href="#Key-derivation-functions">6.6 Key derivation Functions</a>
 162     <ul class="no-bullet">
 163       <li><a name="toc-PBKDF2" href="#PBKDF2">6.6.1 <acronym>PBKDF2</acronym></a></li>
 164       <li><a name="toc-Concrete-PBKDF2-functions" href="#Concrete-PBKDF2-functions">6.6.2 Concrete <acronym>PBKDF2</acronym> functions</a>
 165       <ul class="no-bullet">
 166         <li><a name="toc-PBKDF2_002dHMAC_002dSHA1" href="#PBKDF2_002dHMAC_002dSHA1">6.6.2.1 <acronym>PBKDF2-HMAC-SHA1</acronym></a></li>
 167         <li><a name="toc-PBKDF2_002dHMAC_002dSHA256" href="#PBKDF2_002dHMAC_002dSHA256">6.6.2.2 <acronym>PBKDF2-HMAC-SHA256</acronym></a></li>
 168       </ul></li>
 169     </ul></li>
 170     <li><a name="toc-Public_002dkey-algorithms-1" href="#Public_002dkey-algorithms">6.7 Public-key algorithms</a>
 171     <ul class="no-bullet">
 172       <li><a name="toc-RSA-1" href="#RSA">6.7.1 <acronym>RSA</acronym></a>
 173       <ul class="no-bullet">
 174         <li><a name="toc-Nettle_0027s-RSA-support" href="#Nettle_0027s-RSA-support">6.7.1.1 Nettle&rsquo;s <acronym>RSA</acronym> support</a></li>
 175       </ul></li>
 176       <li><a name="toc-DSA-1" href="#DSA">6.7.2 <acronym>DSA</acronym></a>
 177       <ul class="no-bullet">
 178         <li><a name="toc-Nettle_0027s-DSA-support" href="#Nettle_0027s-DSA-support">6.7.2.1 Nettle&rsquo;s <acronym>DSA</acronym> support</a></li>
 179         <li><a name="toc-Old_002c-deprecated_002c-DSA-interface" href="#Old_002c-deprecated_002c-DSA-interface">6.7.2.2 Old, deprecated, <acronym>DSA</acronym> interface</a></li>
 180       </ul></li>
 181       <li><a name="toc-Elliptic-curves-1" href="#Elliptic-curves">6.7.3 <acronym>Elliptic curves</acronym></a>
 182       <ul class="no-bullet">
 183         <li><a name="toc-Side_002dchannel-silence" href="#Side_002dchannel-silence">6.7.3.1 Side-channel silence</a></li>
 184         <li><a name="toc-ECDSA" href="#ECDSA">6.7.3.2 ECDSA</a></li>
 185         <li><a name="toc-Curve25519" href="#Curve25519">6.7.3.3 Curve25519</a></li>
 186         <li><a name="toc-EdDSA" href="#EdDSA">6.7.3.4 EdDSA</a></li>
 187       </ul></li>
 188     </ul></li>
 189     <li><a name="toc-Randomness-1" href="#Randomness">6.8 Randomness</a>
 190     <ul class="no-bullet">
 191       <li><a name="toc-Yarrow" href="#Yarrow">6.8.1 Yarrow</a></li>
 192     </ul></li>
 193     <li><a name="toc-ASCII-encoding-1" href="#ASCII-encoding">6.9 ASCII encoding</a></li>
 194     <li><a name="toc-Miscellaneous-functions-1" href="#Miscellaneous-functions">6.10 Miscellaneous functions</a></li>
 195     <li><a name="toc-Compatibility-functions-1" href="#Compatibility-functions">6.11 Compatibility functions</a></li>
 196   </ul></li>
 197   <li><a name="toc-Traditional-Nettle-Soup" href="#Nettle-soup">7 Traditional Nettle Soup</a></li>
 198   <li><a name="toc-Installation-1" href="#Installation">8 Installation</a></li>
 199   <li><a name="toc-Function-and-Concept-Index" href="#Index">Function and Concept Index</a></li>
 200 </ul>
 201 </div>
 202
 203
 204 <a name="Top"></a>
 205 <div class="header">
 206 <p>
 207 Next: <a href="#Introduction" accesskey="n" rel="next">Introduction</a>, Previous: <a href="dir.html#Top" accesskey="p" rel="prev">(dir)</a>, Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 208 </div>
 209 <a name="Nettle"></a>
 210 <h1 class="top">Nettle</h1>
 211
 212 <p>This document describes the Nettle low-level cryptographic library. You
 213 can use the library directly from your C programs, or write or use an
 214 object-oriented wrapper for your favorite language or application.
 215 </p>
 216 <p>This manual is for the Nettle library (version 3.2), a
 217 low-level cryptographic library.
 218 </p>
 219 <p>Originally written 2001 by Niels Möller, updated 2015.
 220 </p>
 221 <blockquote>
 222 <p>This manual is placed in the public domain. You may freely copy it, in
 223 whole or in part, with or without modification. Attribution is
 224 appreciated, but not required.
 225 </p></blockquote>
 226
 227
 228 <table class="menu" border="0" cellspacing="0">
 229 <tr><td align="left" valign="top">&bull; <a href="#Introduction" accesskey="1">Introduction</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">What is Nettle?
 230 </td></tr>
 231 <tr><td align="left" valign="top">&bull; <a href="#Copyright" accesskey="2">Copyright</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Your rights.
 232 </td></tr>
 233 <tr><td align="left" valign="top">&bull; <a href="#Conventions" accesskey="3">Conventions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">General interface conventions.
 234 </td></tr>
 235 <tr><td align="left" valign="top">&bull; <a href="#Example" accesskey="4">Example</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">An example program.
 236 </td></tr>
 237 <tr><td align="left" valign="top">&bull; <a href="#Linking" accesskey="5">Linking</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Linking with libnettle and libhogweed.
 238 </td></tr>
 239 <tr><td align="left" valign="top">&bull; <a href="#Reference" accesskey="6">Reference</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">All Nettle functions and features.
 240 </td></tr>
 241 <tr><td align="left" valign="top">&bull; <a href="#Nettle-soup" accesskey="7">Nettle soup</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">For the serious nettle hacker.
 242 </td></tr>
 243 <tr><td align="left" valign="top">&bull; <a href="#Installation" accesskey="8">Installation</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">How to install Nettle.
 244 </td></tr>
 245 <tr><td align="left" valign="top">&bull; <a href="#Index" accesskey="9">Index</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Function and concept index.
 246 </td></tr>
 247 <tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
 248 </pre></th></tr><tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> &mdash; The Detailed Node Listing &mdash;
 249
 250 Reference
 251
 252 </pre></th></tr><tr><td align="left" valign="top">&bull; <a href="#Hash-functions">Hash functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 253 </td></tr>
 254 <tr><td align="left" valign="top">&bull; <a href="#Cipher-functions">Cipher functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 255 </td></tr>
 256 <tr><td align="left" valign="top">&bull; <a href="#Cipher-modes">Cipher modes</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 257 </td></tr>
 258 <tr><td align="left" valign="top">&bull; <a href="#Keyed-hash-functions">Keyed hash functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 259 </td></tr>
 260 <tr><td align="left" valign="top">&bull; <a href="#Key-derivation-functions">Key derivation functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 261 </td></tr>
 262 <tr><td align="left" valign="top">&bull; <a href="#Public_002dkey-algorithms">Public-key algorithms</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 263 </td></tr>
 264 <tr><td align="left" valign="top">&bull; <a href="#Randomness">Randomness</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 265 </td></tr>
 266 <tr><td align="left" valign="top">&bull; <a href="#ASCII-encoding">ASCII encoding</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 267 </td></tr>
 268 <tr><td align="left" valign="top">&bull; <a href="#Miscellaneous-functions">Miscellaneous functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 269 </td></tr>
 270 <tr><td align="left" valign="top">&bull; <a href="#Compatibility-functions">Compatibility functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 271 </td></tr>
 272 <tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
 273 Hash functions
 274
 275 </pre></th></tr><tr><td align="left" valign="top">&bull; <a href="#Recommended-hash-functions">Recommended hash functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 276 </td></tr>
 277 <tr><td align="left" valign="top">&bull; <a href="#Legacy-hash-functions">Legacy hash functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 278 </td></tr>
 279 <tr><td align="left" valign="top">&bull; <a href="#nettle_005fhash-abstraction">nettle_hash abstraction</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 280 </td></tr>
 281 <tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
 282 Cipher modes
 283
 284 </pre></th></tr><tr><td align="left" valign="top">&bull; <a href="#CBC">CBC</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 285 </td></tr>
 286 <tr><td align="left" valign="top">&bull; <a href="#CTR">CTR</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 287 </td></tr>
 288 <tr><td align="left" valign="top">&bull; <a href="#GCM">GCM</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 289 </td></tr>
 290 <tr><td align="left" valign="top">&bull; <a href="#CCM">CCM</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 291 </td></tr>
 292 <tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
 293 Keyed Hash Functions
 294
 295 </pre></th></tr><tr><td align="left" valign="top">&bull; <a href="#HMAC">HMAC</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 296 </td></tr>
 297 <tr><td align="left" valign="top">&bull; <a href="#UMAC">UMAC</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 298 </td></tr>
 299 <tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
 300 Public-key algorithms
 301
 302 </pre></th></tr><tr><td align="left" valign="top">&bull; <a href="#RSA">RSA</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">The RSA public key algorithm.
 303 </td></tr>
 304 <tr><td align="left" valign="top">&bull; <a href="#DSA">DSA</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">The DSA digital signature algorithm.
 305 </td></tr>
 306 <tr><td align="left" valign="top">&bull; <a href="#Elliptic-curves">Elliptic curves</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Elliptic curves and ECDSA
 307 </td></tr>
 308 <tr><th colspan="3" align="left" valign="top"><pre class="menu-comment">
 309 </pre></th></tr></table>
 310
 311
 312 <hr>
 313 <a name="Introduction"></a>
 314 <div class="header">
 315 <p>
 316 Next: <a href="#Copyright" accesskey="n" rel="next">Copyright</a>, Previous: <a href="#Top" accesskey="p" rel="prev">Top</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 317 </div>
 318 <a name="Introduction-1"></a>
 319 <h2 class="chapter">1 Introduction</h2>
 320
 321 <p>Nettle is a cryptographic library that is designed to fit easily in more
 322 or less any context: In crypto toolkits for object-oriented languages
 323 (C++, Python, Pike, ...), in applications like LSH or GNUPG, or even in
 324 kernel space. In most contexts, you need more than the basic
 325 cryptographic algorithms, you also need some way to keep track of available
 326 algorithms, their properties and variants. You often have some algorithm
 327 selection process, often dictated by a protocol you want to implement.
 328 </p>
 329 <p>And as the requirements of applications differ in subtle and not so
 330 subtle ways, an API that fits one application well can be a pain to use
 331 in a different context. And that is why there are so many different
 332 cryptographic libraries around.
 333 </p>
 334 <p>Nettle tries to avoid this problem by doing one thing, the low-level
 335 crypto stuff, and providing a <em>simple</em> but general interface to it.
 336 In particular, Nettle doesn&rsquo;t do algorithm selection. It doesn&rsquo;t do
 337 memory allocation. It doesn&rsquo;t do any I/O.
 338 </p>
 339 <p>The idea is that one can build several application and context specific
 340 interfaces on top of Nettle, and share the code, test cases, benchmarks,
 341 documentation, etc. Examples are the Nettle module for the Pike
 342 language, and LSH, which both use an object-oriented abstraction on top
 343 of the library.
 344 </p>
 345 <p>This manual explains how to use the Nettle library. It also tries to
 346 provide some background on the cryptography, and advice on how to best
 347 put it to use.
 348 </p>
 349 <hr>
 350 <a name="Copyright"></a>
 351 <div class="header">
 352 <p>
 353 Next: <a href="#Conventions" accesskey="n" rel="next">Conventions</a>, Previous: <a href="#Introduction" accesskey="p" rel="prev">Introduction</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 354 </div>
 355 <a name="Copyright-1"></a>
 356 <h2 class="chapter">2 Copyright</h2>
 357
 358 <p>Nettle is dual licenced under the GNU General Public License version 2
 359 or later, and the GNU Lesser General Public License version 3 or later.
 360 When using Nettle, you must comply fully with all conditions of at least
 361 one of these licenses. A few of the individual files are licensed under
 362 more permissive terms, or in the public domain. To find the current
 363 status of particular files, you have to read the copyright notices at
 364 the top of the files.
 365 </p>
 366 <p>This manual is in the public domain. You may freely copy it in whole or
 367 in part, e.g., into documentation of programs that build on Nettle.
 368 Attribution, as well as contribution of improvements to the text, is of
 369 course appreciated, but it is not required.
 370 </p>
 371 <p>A list of the supported algorithms, their origins, and exceptions to the
 372 above licensing:
 373 </p>
 374 <dl compact="compact">
 375 <dt><em>AES</em></dt>
 376 <dd><p>The implementation of the AES cipher (also known as rijndael) is written
 377 by Rafael Sevilla. Assembler for x86 by Rafael Sevilla and
 378 Niels Möller, Sparc assembler by Niels Möller.
 379 </p>
 380 </dd>
 381 <dt><em>ARCFOUR</em></dt>
 382 <dd><p>The implementation of the ARCFOUR (also known as RC4) cipher is written
 383 by Niels Möller.
 384 </p>
 385 </dd>
 386 <dt><em>ARCTWO</em></dt>
 387 <dd><p>The implementation of the ARCTWO (also known as RC2) cipher is written
 388 by Nikos Mavroyanopoulos and modified by Werner Koch and Simon
 389 Josefsson.
 390 </p>
 391 </dd>
 392 <dt><em>BLOWFISH</em></dt>
 393 <dd><p>The implementation of the BLOWFISH cipher is written by Werner Koch,
 394 copyright owned by the Free Software Foundation. Also hacked by Simon
 395 Josefsson and Niels Möller.
 396 </p>
 397 </dd>
 398 <dt><em>CAMELLIA</em></dt>
 399 <dd><p>The C implementation is by Nippon Telegraph and Telephone Corporation
 400 (NTT), heavily modified by Niels Möller. Assembler for x86 and x86_64
 401 by Niels Möller.
 402 </p>
 403 </dd>
 404 <dt><em>CAST128</em></dt>
 405 <dd><p>The implementation of the CAST128 cipher is written by Steve Reid.
 406 Released into the public domain.
 407 </p>
 408 </dd>
 409 <dt><em>CHACHA</em></dt>
 410 <dd><p>Implemented by Joachim Strömbergson, based on the implementation of
 411 SALSA20 (see below). Assembly for x86_64 by Niels Möller.
 412 </p>
 413 </dd>
 414 <dt><em>DES</em></dt>
 415 <dd><p>The implementation of the DES cipher is written by Dana L. How, and
 416 released under the LGPL, version 2 or later.
 417 </p>
 418 </dd>
 419 <dt><em>GOSTHASH94</em></dt>
 420 <dd><p>The C implementation of the GOST94 message digest is written by
 421 Aleksey Kravchenko and was ported from the rhash library by Nikos
 422 Mavrogiannopoulos. It is released under the MIT license.
 423 </p>
 424 </dd>
 425 <dt><em>MD2</em></dt>
 426 <dd><p>The implementation of MD2 is written by Andrew Kuchling, and hacked
 427 some by Andreas Sigfridsson and Niels Möller. Python Cryptography
 428 Toolkit license (essentially public domain).
 429 </p>
 430 </dd>
 431 <dt><em>MD4</em></dt>
 432 <dd><p>This is almost the same code as for MD5 below, with modifications by
 433 Marcus Comstedt. Released into the public domain.
 434 </p>
 435 </dd>
 436 <dt><em>MD5</em></dt>
 437 <dd><p>The implementation of the MD5 message digest is written by Colin Plumb.
 438 It has been hacked some more by Andrew Kuchling and Niels Möller.
 439 Released into the public domain.
 440 </p>
 441 </dd>
 442 <dt><em>PBKDF2</em></dt>
 443 <dd><p>The C implementation of PBKDF2 is based on earlier work for Shishi and
 444 GnuTLS by Simon Josefsson.
 445 </p>
 446 </dd>
 447 <dt><em>RIPEMD160</em></dt>
 448 <dd><p>The implementation of RIPEMD160 message digest is based on the code in
 449 libgcrypt, copyright owned by the Free Software Foundation. Ported to
 450 Nettle by Andres Mejia.
 451 </p>
 452 </dd>
 453 <dt><em>SALSA20</em></dt>
 454 <dd><p>The C implementation of SALSA20 is based on D. J. Bernstein&rsquo;s reference
 455 implementation (in the public domain), adapted to Nettle by Simon
 456 Josefsson, and heavily modified by Niels Möller. Assembly for x86_64 and
 457 ARM by Niels Möller.
 458 </p>
 459 </dd>
 460 <dt><em>SERPENT</em></dt>
 461 <dd><p>The implementation of the SERPENT cipher is based on the code in libgcrypt,
 462 copyright owned by the Free Software Foundation. Adapted to Nettle by
 463 Simon Josefsson and heavily modified by Niels Möller. Assembly for
 464 x86_64 by Niels Möller.
 465 </p>
 466 </dd>
 467 <dt><em>POLY1305</em></dt>
 468 <dd><p>Based on the implementation by Andrew M. (floodyberry), modified by
 469 Nikos Mavrogiannopoulos and Niels Möller. Assembly for x86_64 by Niels
 470 Möller.
 471 </p>
 472 </dd>
 473 <dt><em>SHA1</em></dt>
 474 <dd><p>The C implementation of the SHA1 message digest is written by Peter
 475 Gutmann, and hacked some more by Andrew Kuchling and Niels Möller.
 476 Released into the public domain. Assembler for x86, x86_64 and ARM by
 477 Niels Möller, released under the LGPL.
 478 </p>
 479 </dd>
 480 <dt><em>SHA2</em></dt>
 481 <dd><p>Written by Niels Möller, using Peter Gutmann&rsquo;s SHA1 code as a model.
 482 </p>
 483 </dd>
 484 <dt><em>SHA3</em></dt>
 485 <dd><p>Written by Niels Möller.
 486 </p>
 487 </dd>
 488 <dt><em>TWOFISH</em></dt>
 489 <dd><p>The implementation of the TWOFISH cipher is written by Ruud de Rooij.
 490 </p>
 491 </dd>
 492 <dt><em>UMAC</em></dt>
 493 <dd><p>Written by Niels Möller.
 494 </p>
 495 </dd>
 496 <dt><em>RSA</em></dt>
 497 <dd><p>Written by Niels Möller. Uses the GMP library for bignum operations.
 498 </p>
 499 </dd>
 500 <dt><em>DSA</em></dt>
 501 <dd><p>Written by Niels Möller. Uses the GMP library for bignum operations.
 502 </p>
 503 </dd>
 504 <dt><em>ECDSA</em></dt>
 505 <dd><p>Written by Niels Möller. Uses the GMP library for bignum operations.
 506 Development of Nettle&rsquo;s ECC support was funded by the .SE Internet Fund.
 507 </p></dd>
 508 </dl>
 509
 510 <hr>
 511 <a name="Conventions"></a>
 512 <div class="header">
 513 <p>
 514 Next: <a href="#Example" accesskey="n" rel="next">Example</a>, Previous: <a href="#Copyright" accesskey="p" rel="prev">Copyright</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 515 </div>
 516 <a name="Conventions-1"></a>
 517 <h2 class="chapter">3 Conventions</h2>
 518
 519 <p>For each supported algorithm, there is an include file that defines a
 520 <em>context struct</em>, a few constants, and declares functions for
 521 operating on the context. The context struct encapsulates all information
 522 needed by the algorithm, and it can be copied or moved in memory with no
 523 unexpected effects.
 524 </p>
 525 <p>For consistency, functions for different algorithms are very similar,
 526 but there are some differences, for instance reflecting if the key setup
 527 or encryption function differ for encryption and decryption, and whether
 528 or not key setup can fail. There are also differences between algorithms
 529 that don&rsquo;t show in function prototypes, but which the application must
 530 nevertheless be aware of. There is no big difference between the
 531 functions for stream ciphers and for block ciphers, although they should
 532 be used quite differently by the application.
 533 </p>
 534 <p>If your application uses more than one algorithm of the same type, you
 535 should probably create an interface that is tailor-made for your needs,
 536 and then write a few lines of glue code on top of Nettle.
 537 </p>
 538 <p>By convention, for an algorithm named <code>foo</code>, the struct tag for the
 539 context struct is <code>foo_ctx</code>, constants and functions uses prefixes
 540 like <code>FOO_BLOCK_SIZE</code> (a constant) and <code>foo_set_key</code> (a
 541 function).
 542 </p>
 543 <p>In all functions, strings are represented with an explicit length, of
 544 type <code>size_t</code>, and a pointer of type <code>uint8_t *</code> or
 545 <code>const uint8_t *</code>. For functions that transform one string to
 546 another, the argument order is length, destination pointer and source
 547 pointer. Source and destination areas are usually of the same length.
 548 When they differ, e.g., for <code>ccm_encrypt_message</code>, the length
 549 argument specifies the size of the destination area. Source and
 550 destination pointers may be equal, so that you can process strings in
 551 place, but source and destination areas <em>must not</em> overlap in any
 552 other way.
 553 </p>
 554 <p>Many of the functions lack return value and can never fail. Those
 555 functions which can fail, return one on success and zero on failure.
 556 </p>
 557
 558 <hr>
 559 <a name="Example"></a>
 560 <div class="header">
 561 <p>
 562 Next: <a href="#Linking" accesskey="n" rel="next">Linking</a>, Previous: <a href="#Conventions" accesskey="p" rel="prev">Conventions</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 563 </div>
 564 <a name="Example-1"></a>
 565 <h2 class="chapter">4 Example</h2>
 566
 567 <p>A simple example program that reads a file from standard input and
 568 writes its SHA1 check-sum on standard output should give the flavor of
 569 Nettle.
 570 </p>
 571 <div class="example">
 572 <pre class="verbatim">#include &lt;stdio.h&gt;
 573 #include &lt;stdlib.h&gt;
 574
 575 #include &lt;nettle/sha1.h&gt;
 576
 577 #define BUF_SIZE 1000
 578
 579 static void
 580 display_hex(unsigned length, uint8_t *data)
 581 {
 582   unsigned i;
 583
 584   for (i = 0; i&lt;length; i++)
 585     printf(&quot;%02x &quot;, data[i]);
 586
 587   printf(&quot;\n&quot;);
 588 }
 589
 590 int
 591 main(int argc, char **argv)
 592 {
 593   struct sha1_ctx ctx;
 594   uint8_t buffer[BUF_SIZE];
 595   uint8_t digest[SHA1_DIGEST_SIZE];
 596
 597   sha1_init(&amp;ctx);
 598   for (;;)
 599   {
 600     int done = fread(buffer, 1, sizeof(buffer), stdin);
 601     sha1_update(&amp;ctx, done, buffer);
 602     if (done &lt; sizeof(buffer))
 603       break;
 604   }
 605   if (ferror(stdin))
 606     return EXIT_FAILURE;
 607
 608   sha1_digest(&amp;ctx, SHA1_DIGEST_SIZE, digest);
 609
 610   display_hex(SHA1_DIGEST_SIZE, digest);
 611   return EXIT_SUCCESS;
 612 }
 613 </pre></div>
 614
 615 <p>On a typical Unix system, this program can be compiled and linked with
 616 the command line
 617 </p><div class="example">
 618 <pre class="example">gcc sha-example.c -o sha-example -lnettle
 619 </pre></div>
 620
 621 <hr>
 622 <a name="Linking"></a>
 623 <div class="header">
 624 <p>
 625 Next: <a href="#Reference" accesskey="n" rel="next">Reference</a>, Previous: <a href="#Example" accesskey="p" rel="prev">Example</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 626 </div>
 627 <a name="Linking-1"></a>
 628 <h2 class="chapter">5 Linking</h2>
 629
 630 <p>Nettle actually consists of two libraries, <samp>libnettle</samp> and
 631 <samp>libhogweed</samp>. The <samp>libhogweed</samp> library contains those
 632 functions of Nettle that uses bignum operations, and depends on the GMP
 633 library. With this division, linking works the same for both static and
 634 dynamic libraries.
 635 </p>
 636 <p>If an application uses only the symmetric crypto algorithms of Nettle
 637 (i.e., block ciphers, hash functions, and the like), it&rsquo;s sufficient to
 638 link with <code>-lnettle</code>. If an application also uses public-key
 639 algorithms, the recommended linker flags are <code>-lhogweed -lnettle
 640 -lgmp</code>. If the involved libraries are installed as dynamic libraries, it
 641 may be sufficient to link with just <code>-lhogweed</code>, and the loader
 642 will resolve the dependencies automatically.
 643 </p>
 644 <hr>
 645 <a name="Reference"></a>
 646 <div class="header">
 647 <p>
 648 Next: <a href="#Nettle-soup" accesskey="n" rel="next">Nettle soup</a>, Previous: <a href="#Linking" accesskey="p" rel="prev">Linking</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 649 </div>
 650 <a name="Reference-1"></a>
 651 <h2 class="chapter">6 Reference</h2>
 652
 653 <p>This chapter describes all the Nettle functions, grouped by family.
 654 </p>
 655 <table class="menu" border="0" cellspacing="0">
 656 <tr><td align="left" valign="top">&bull; <a href="#Hash-functions" accesskey="1">Hash functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 657 </td></tr>
 658 <tr><td align="left" valign="top">&bull; <a href="#Cipher-functions" accesskey="2">Cipher functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 659 </td></tr>
 660 <tr><td align="left" valign="top">&bull; <a href="#Cipher-modes" accesskey="3">Cipher modes</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 661 </td></tr>
 662 <tr><td align="left" valign="top">&bull; <a href="#Authenticated-encryption" accesskey="4">Authenticated encryption</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 663 </td></tr>
 664 <tr><td align="left" valign="top">&bull; <a href="#Keyed-hash-functions" accesskey="5">Keyed hash functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 665 </td></tr>
 666 <tr><td align="left" valign="top">&bull; <a href="#Key-derivation-functions" accesskey="6">Key derivation functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 667 </td></tr>
 668 <tr><td align="left" valign="top">&bull; <a href="#Public_002dkey-algorithms" accesskey="7">Public-key algorithms</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 669 </td></tr>
 670 <tr><td align="left" valign="top">&bull; <a href="#Randomness" accesskey="8">Randomness</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 671 </td></tr>
 672 <tr><td align="left" valign="top">&bull; <a href="#ASCII-encoding" accesskey="9">ASCII encoding</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 673 </td></tr>
 674 <tr><td align="left" valign="top">&bull; <a href="#Miscellaneous-functions">Miscellaneous functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 675 </td></tr>
 676 <tr><td align="left" valign="top">&bull; <a href="#Compatibility-functions">Compatibility functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 677 </td></tr>
 678 </table>
 679
 680 <hr>
 681 <a name="Hash-functions"></a>
 682 <div class="header">
 683 <p>
 684 Next: <a href="#Cipher-functions" accesskey="n" rel="next">Cipher functions</a>, Previous: <a href="#Reference" accesskey="p" rel="prev">Reference</a>, Up: <a href="#Reference" accesskey="u" rel="up">Reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 685 </div>
 686
 687 <a name="Hash-functions-1"></a>
 688 <h3 class="section">6.1 Hash functions</h3>
 689 <a name="index-Hash-function"></a>
 690 <p>A cryptographic <em>hash function</em> is a function that takes variable
 691 size strings, and maps them to strings of fixed, short, length. There
 692 are naturally lots of collisions, as there are more possible 1MB files
 693 than 20 byte strings. But the function is constructed such that is hard
 694 to find the collisions. More precisely, a cryptographic hash function
 695 <code>H</code> should have the following properties:
 696 </p>
 697 <dl compact="compact">
 698 <dt><em>One-way</em></dt>
 699 <dd><a name="index-One_002dway"></a>
 700 <p>Given a hash value <code>H(x)</code> it is hard to find a string <code>x</code>
 701 that hashes to that value.
 702 </p>
 703 </dd>
 704 <dt><em>Collision-resistant</em></dt>
 705 <dd><a name="index-Collision_002dresistant"></a>
 706 <p>It is hard to find two different strings, <code>x</code> and <code>y</code>, such
 707 that <code>H(x)</code> = <code>H(y)</code>.
 708 </p>
 709 </dd>
 710 </dl>
 711
 712 <p>Hash functions are useful as building blocks for digital signatures,
 713 message authentication codes, pseudo random generators, association of
 714 unique ids to documents, and many other things.
 715 </p>
 716 <p>The most commonly used hash functions are MD5 and SHA1. Unfortunately,
 717 both these fail the collision-resistance requirement; cryptologists have
 718 found ways to construct colliding inputs. The recommended hash functions
 719 for new applications are SHA2 (with main variants SHA256 and SHA512). At
 720 the time of this writing (Autumn 2015), SHA3 has recently been
 721 standardized, and the new SHA3 and other top SHA3 candidates may also be
 722 reasonable alternatives.
 723 </p>
 724 <table class="menu" border="0" cellspacing="0">
 725 <tr><td align="left" valign="top">&bull; <a href="#Recommended-hash-functions" accesskey="1">Recommended hash functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 726 </td></tr>
 727 <tr><td align="left" valign="top">&bull; <a href="#Legacy-hash-functions" accesskey="2">Legacy hash functions</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 728 </td></tr>
 729 <tr><td align="left" valign="top">&bull; <a href="#nettle_005fhash-abstraction" accesskey="3">nettle_hash abstraction</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
 730 </td></tr>
 731 </table>
 732
 733 <hr>
 734 <a name="Recommended-hash-functions"></a>
 735 <div class="header">
 736 <p>
 737 Next: <a href="#Legacy-hash-functions" accesskey="n" rel="next">Legacy hash functions</a>, Up: <a href="#Hash-functions" accesskey="u" rel="up">Hash functions</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
 738 </div>
 739 <a name="Recommended-hash-functions-1"></a>
 740 <h4 class="subsection">6.1.1 Recommended hash functions</h4>
 741
 742 <p>The following hash functions have no known weaknesses, and are suitable
 743 for new applications. The SHA2 family of hash functions were specified
 744 by <em>NIST</em>, intended as a replacement for <acronym>SHA1</acronym>.
 745 </p>
 746 <a name="SHA256"></a>
 747 <h4 class="subsubsection">6.1.1.1 <acronym>SHA256</acronym></h4>
 748
 749 <p>SHA256 is a member of the SHA2 family. It outputs hash values of 256
 750 bits, or 32 octets. Nettle defines SHA256 in <samp>&lt;nettle/sha2.h&gt;</samp>.
 751 </p>
 752 <dl>
 753 <dt><a name="index-struct-sha256_005fctx"></a>Context struct: <strong>struct sha256_ctx</strong></dt>
 754 </dl>
 755
 756 <dl>
 757 <dt><a name="index-SHA256_005fDIGEST_005fSIZE"></a>Constant: <strong>SHA256_DIGEST_SIZE</strong></dt>
 758 <dd><p>The size of a SHA256 digest, i.e. 32.
 759 </p></dd></dl>
 760
 761 <dl>
 762 <dt><a name="index-SHA256_005fBLOCK_005fSIZE"></a>Constant: <strong>SHA256_BLOCK_SIZE</strong></dt>
 763 <dd><p>The internal block size of SHA256. Useful for some special constructions,
 764 in particular HMAC-SHA256.
 765 </p></dd></dl>
 766
 767 <dl>
 768 <dt><a name="index-sha256_005finit"></a>Function: <em>void</em> <strong>sha256_init</strong> <em>(struct sha256_ctx *<var>ctx</var>)</em></dt>
 769 <dd><p>Initialize the SHA256 state.
 770 </p></dd></dl>
 771
 772 <dl>
 773 <dt><a name="index-sha256_005fupdate"></a>Function: <em>void</em> <strong>sha256_update</strong> <em>(struct sha256_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
 774 <dd><p>Hash some more data.
 775 </p></dd></dl>
 776
 777 <dl>
 778 <dt><a name="index-sha256_005fdigest"></a>Function: <em>void</em> <strong>sha256_digest</strong> <em>(struct sha256_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
 779 <dd><p>Performs final processing and extracts the message digest, writing it
 780 to <var>digest</var>. <var>length</var> may be smaller than
 781 <code>SHA256_DIGEST_SIZE</code>, in which case only the first <var>length</var>
 782 octets of the digest are written.
 783 </p>
 784 <p>This function also resets the context in the same way as
 785 <code>sha256_init</code>.
 786 </p></dd></dl>
 787
 788 <p>Earlier versions of nettle defined SHA256 in the header file
 789 <samp>&lt;nettle/sha.h&gt;</samp>, which is now deprecated, but kept for
 790 compatibility.
 791 </p>
 792 <a name="SHA224"></a>
 793 <h4 class="subsubsection">6.1.1.2 <acronym>SHA224</acronym></h4>
 794
 795 <p>SHA224 is a variant of SHA256, with a different initial state, and with
 796 the output truncated to 224 bits, or 28 octets. Nettle defines SHA224 in
 797 <samp>&lt;nettle/sha2.h&gt;</samp> (and in <samp>&lt;nettle/sha.h&gt;</samp>, for backwards
 798 compatibility).
 799 </p>
 800 <dl>
 801 <dt><a name="index-struct-sha224_005fctx"></a>Context struct: <strong>struct sha224_ctx</strong></dt>
 802 </dl>
 803
 804 <dl>
 805 <dt><a name="index-SHA224_005fDIGEST_005fSIZE"></a>Constant: <strong>SHA224_DIGEST_SIZE</strong></dt>
 806 <dd><p>The size of a SHA224 digest, i.e. 28.
 807 </p></dd></dl>
 808
 809 <dl>
 810 <dt><a name="index-SHA224_005fBLOCK_005fSIZE"></a>Constant: <strong>SHA224_BLOCK_SIZE</strong></dt>
 811 <dd><p>The internal block size of SHA224. Useful for some special constructions,
 812 in particular HMAC-SHA224.
 813 </p></dd></dl>
 814
 815 <dl>
 816 <dt><a name="index-sha224_005finit"></a>Function: <em>void</em> <strong>sha224_init</strong> <em>(struct sha224_ctx *<var>ctx</var>)</em></dt>
 817 <dd><p>Initialize the SHA224 state.
 818 </p></dd></dl>
 819
 820 <dl>
 821 <dt><a name="index-sha224_005fupdate"></a>Function: <em>void</em> <strong>sha224_update</strong> <em>(struct sha224_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
 822 <dd><p>Hash some more data.
 823 </p></dd></dl>
 824
 825 <dl>
 826 <dt><a name="index-sha224_005fdigest"></a>Function: <em>void</em> <strong>sha224_digest</strong> <em>(struct sha224_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
 827 <dd><p>Performs final processing and extracts the message digest, writing it
 828 to <var>digest</var>. <var>length</var> may be smaller than
 829 <code>SHA224_DIGEST_SIZE</code>, in which case only the first <var>length</var>
 830 octets of the digest are written.
 831 </p>
 832 <p>This function also resets the context in the same way as
 833 <code>sha224_init</code>.
 834 </p></dd></dl>
 835
 836 <a name="SHA512"></a>
 837 <h4 class="subsubsection">6.1.1.3 <acronym>SHA512</acronym></h4>
 838
 839 <p>SHA512 is a larger sibling to SHA256, with a very similar structure but
 840 with both the output and the internal variables of twice the size. The
 841 internal variables are 64 bits rather than 32, making it significantly
 842 slower on 32-bit computers. It outputs hash values of 512 bits, or 64
 843 octets. Nettle defines SHA512 in <samp>&lt;nettle/sha2.h&gt;</samp> (and in
 844 <samp>&lt;nettle/sha.h&gt;</samp>, for backwards compatibility).
 845 </p>
 846 <dl>
 847 <dt><a name="index-struct-sha512_005fctx"></a>Context struct: <strong>struct sha512_ctx</strong></dt>
 848 </dl>
 849
 850 <dl>
 851 <dt><a name="index-SHA512_005fDIGEST_005fSIZE"></a>Constant: <strong>SHA512_DIGEST_SIZE</strong></dt>
 852 <dd><p>The size of a SHA512 digest, i.e. 64.
 853 </p></dd></dl>
 854
 855 <dl>
 856 <dt><a name="index-SHA512_005fBLOCK_005fSIZE"></a>Constant: <strong>SHA512_BLOCK_SIZE</strong></dt>
 857 <dd><p>The internal block size of SHA512, 128. Useful for some special
 858 constructions, in particular HMAC-SHA512.
 859 </p></dd></dl>
 860
 861 <dl>
 862 <dt><a name="index-sha512_005finit"></a>Function: <em>void</em> <strong>sha512_init</strong> <em>(struct sha512_ctx *<var>ctx</var>)</em></dt>
 863 <dd><p>Initialize the SHA512 state.
 864 </p></dd></dl>
 865
 866 <dl>
 867 <dt><a name="index-sha512_005fupdate"></a>Function: <em>void</em> <strong>sha512_update</strong> <em>(struct sha512_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
 868 <dd><p>Hash some more data.
 869 </p></dd></dl>
 870
 871 <dl>
 872 <dt><a name="index-sha512_005fdigest"></a>Function: <em>void</em> <strong>sha512_digest</strong> <em>(struct sha512_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
 873 <dd><p>Performs final processing and extracts the message digest, writing it
 874 to <var>digest</var>. <var>length</var> may be smaller than
 875 <code>SHA512_DIGEST_SIZE</code>, in which case only the first <var>length</var>
 876 octets of the digest are written.
 877 </p>
 878 <p>This function also resets the context in the same way as
 879 <code>sha512_init</code>.
 880 </p></dd></dl>
 881
 882 <a name="SHA384-and-other-variants-of-SHA512"></a>
 883 <h4 class="subsubsection">6.1.1.4 <acronym>SHA384 and other variants of SHA512</acronym></h4>
 884
 885 <p>Several variants of SHA512 have been defined, with a different initial
 886 state, and with the output truncated to shorter length than 512 bits.
 887 Naming is a bit confused, these algorithms are called SHA512-224,
 888 SHA512-256 and SHA384, for output sizes of 224, 256 and 384 bits,
 889 respectively. Nettle defines these in <samp>&lt;nettle/sha2.h&gt;</samp> (and in
 890 <samp>&lt;nettle/sha.h&gt;</samp>, for backwards compatibility).
 891 </p>
 892 <dl>
 893 <dt><a name="index-struct-sha512_005f224_005fctx"></a>Context struct: <strong>struct sha512_224_ctx</strong></dt>
 894 <dt><a name="index-struct-sha512_005f256_005fctx"></a>Context struct: <strong>struct sha512_256_ctx</strong></dt>
 895 <dt><a name="index-struct-sha384_005fctx"></a>Context struct: <strong>struct sha384_ctx</strong></dt>
 896 <dd><p>These context structs are all the same as sha512_ctx. They are defined as
 897 simple preprocessor aliases, which may cause some problems if used as
 898 identifiers for other purposes. So avoid doing that.
 899 </p></dd></dl>
 900
 901 <dl>
 902 <dt><a name="index-SHA512_005f224_005fDIGEST_005fSIZE"></a>Constant: <strong>SHA512_224_DIGEST_SIZE</strong></dt>
 903 <dt><a name="index-SHA512_005f256_005fDIGEST_005fSIZE"></a>Constant: <strong>SHA512_256_DIGEST_SIZE</strong></dt>
 904 <dt><a name="index-SHA384_005fDIGEST_005fSIZE"></a>Constant: <strong>SHA384_DIGEST_SIZE</strong></dt>
 905 <dd><p>The digest size for each variant, i.e., 28, 32, and 48, respectively.
 906 </p></dd></dl>
 907
 908 <dl>
 909 <dt><a name="index-SHA512_005f224_005fBLOCK_005fSIZE"></a>Constant: <strong>SHA512_224_BLOCK_SIZE</strong></dt>
 910 <dt><a name="index-SHA512_005f256_005fBLOCK_005fSIZE"></a>Constant: <strong>SHA512_256_BLOCK_SIZE</strong></dt>
 911 <dt><a name="index-SHA384_005fBLOCK_005fSIZE"></a>Constant: <strong>SHA384_BLOCK_SIZE</strong></dt>
 912 <dd><p>The internal block size, same as SHA512_BLOCK_SIZE, i.e., 128. Useful for
 913 some special constructions, in particular HMAC-SHA384.
 914 </p></dd></dl>
 915
 916 <dl>
 917 <dt><a name="index-sha512_005f224_005finit"></a>Function: <em>void</em> <strong>sha512_224_init</strong> <em>(struct sha512_224_ctx *<var>ctx</var>)</em></dt>
 918 <dt><a name="index-sha512_005f256_005finit"></a>Function: <em>void</em> <strong>sha512_256_init</strong> <em>(struct sha512_256_ctx *<var>ctx</var>)</em></dt>
 919 <dt><a name="index-sha384_005finit"></a>Function: <em>void</em> <strong>sha384_init</strong> <em>(struct sha384_ctx *<var>ctx</var>)</em></dt>
 920 <dd><p>Initialize the context struct.
 921 </p></dd></dl>
 922
 923 <dl>
 924 <dt><a name="index-sha512_005f224_005fupdate"></a>Function: <em>void</em> <strong>sha512_224_update</strong> <em>(struct sha512_224_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
 925 <dt><a name="index-sha512_005f256_005fupdate"></a>Function: <em>void</em> <strong>sha512_256_update</strong> <em>(struct sha512_256_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
 926 <dt><a name="index-sha384_005fupdate"></a>Function: <em>void</em> <strong>sha384_update</strong> <em>(struct sha384_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
 927 <dd><p>Hash some more data. These are all aliases for sha512_update, which does
 928 the same thing.
 929 </p></dd></dl>
 930
 931 <dl>
 932 <dt><a name="index-sha512_005f224_005fdigest"></a>Function: <em>void</em> <strong>sha512_224_digest</strong> <em>(struct sha512_224_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
 933 <dt><a name="index-sha512_005f256_005fdigest"></a>Function: <em>void</em> <strong>sha512_256_digest</strong> <em>(struct sha512_256_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
 934 <dt><a name="index-sha384_005fdigest"></a>Function: <em>void</em> <strong>sha384_digest</strong> <em>(struct sha384_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
 935 <dd><p>Performs final processing and extracts the message digest, writing it to
 936 <var>digest</var>. <var>length</var> may be smaller than the specified digest
 937 size, in which case only the first <var>length</var> octets of the digest are
 938 written.
 939 </p>
 940 <p>These function also reset the context in the same way as the
 941 corresponding init function.
 942 </p></dd></dl>
 943
 944 <a name="SHA3_002d224"></a>
 945 <h4 class="subsubsection">6.1.1.5 <acronym>SHA3-224</acronym></h4>
 946 <a name="index-SHA3"></a>
 947
 948 <p>The SHA3 hash functions were specified by NIST in response to weaknesses
 949 in SHA1, and doubts about SHA2 hash functions which structurally are
 950 very similar to SHA1. SHA3 is a result of a competition, where the
 951 winner, also known as Keccak, was designed by Guido Bertoni, Joan
 952 Daemen, Michaël Peeters and Gilles Van Assche. It is structurally very
 953 different from all widely used earlier hash functions. Like SHA2, there
 954 are several variants, with output sizes of 224, 256, 384 and 512 bits
 955 (28, 32, 48 and 64 octets, respectively). In August 2015, it was
 956 formally standardized by NIST, as FIPS 202,
 957 <a href="http://dx.doi.org/10.6028/NIST.FIPS.202">http://dx.doi.org/10.6028/NIST.FIPS.202</a>.
 958 </p>
 959 <p>Note that the SHA3 implementation in earlier versions of Nettle was
 960 based on the specification at the time Keccak was announced as the
 961 winner of the competition, which is incompatible with the final standard
 962 and hence with current versions of Nettle. The <samp>nette/sha3.h</samp>
 963 defines a preprocessor symbol <code>NETTLE_SHA3_FIPS202</code> to indicate
 964 conformance with the standard.
 965 </p>
 966 <dl>
 967 <dt><a name="index-NETTLE_005fSHA3_005fFIPS202"></a>Constant: <strong>NETTLE_SHA3_FIPS202</strong></dt>
 968 <dd><p>Defined to 1 in Nettle versions supporting FIPS 202. Undefined in
 969 earlier versions.
 970 </p></dd></dl>
 971
 972 <p>Nettle defines SHA3-224 in <samp>&lt;nettle/sha3.h&gt;</samp>.
 973 </p>
 974 <dl>
 975 <dt><a name="index-struct-sha3_005f224_005fctx"></a>Context struct: <strong>struct sha3_224_ctx</strong></dt>
 976 </dl>
 977
 978 <dl>
 979 <dt><a name="index-SHA3_005f224_005fDIGEST_005fSIZE"></a>Constant: <strong>SHA3_224_DIGEST_SIZE</strong></dt>
 980 <dd><p>The size of a SHA3_224 digest, i.e., 28.
 981 </p></dd></dl>
 982
 983 <dl>
 984 <dt><a name="index-SHA3_005f224_005fBLOCK_005fSIZE"></a>Constant: <strong>SHA3_224_BLOCK_SIZE</strong></dt>
 985 <dd><p>The internal block size of SHA3_224.
 986 </p></dd></dl>
 987
 988 <dl>
 989 <dt><a name="index-sha3_005f224_005finit"></a>Function: <em>void</em> <strong>sha3_224_init</strong> <em>(struct sha3_224_ctx *<var>ctx</var>)</em></dt>
 990 <dd><p>Initialize the SHA3-224 state.
 991 </p></dd></dl>
 992
 993 <dl>
 994 <dt><a name="index-sha3_005f224_005fupdate"></a>Function: <em>void</em> <strong>sha3_224_update</strong> <em>(struct sha3_224_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
 995 <dd><p>Hash some more data.
 996 </p></dd></dl>
 997
 998 <dl>
 999 <dt><a name="index-sha3_005f224_005fdigest"></a>Function: <em>void</em> <strong>sha3_224_digest</strong> <em>(struct sha3_224_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
1000 <dd><p>Performs final processing and extracts the message digest, writing it
1001 to <var>digest</var>. <var>length</var> may be smaller than
1002 <code>SHA3_224_DIGEST_SIZE</code>, in which case only the first <var>length</var>
1003 octets of the digest are written.
1004 </p>
1005 <p>This function also resets the context.
1006 </p></dd></dl>
1007
1008 <a name="SHA3_002d256"></a>
1009 <h4 class="subsubsection">6.1.1.6 <acronym>SHA3-256</acronym></h4>
1010
1011 <p>This is SHA3 with 256-bit output size, and possibly the most useful
1012 of the SHA3 hash functions.
1013 </p>
1014 <p>Nettle defines SHA3-256 in <samp>&lt;nettle/sha3.h&gt;</samp>.
1015 </p>
1016 <dl>
1017 <dt><a name="index-struct-sha3_005f256_005fctx"></a>Context struct: <strong>struct sha3_256_ctx</strong></dt>
1018 </dl>
1019
1020 <dl>
1021 <dt><a name="index-SHA3_005f256_005fDIGEST_005fSIZE"></a>Constant: <strong>SHA3_256_DIGEST_SIZE</strong></dt>
1022 <dd><p>The size of a SHA3_256 digest, i.e., 32.
1023 </p></dd></dl>
1024
1025 <dl>
1026 <dt><a name="index-SHA3_005f256_005fBLOCK_005fSIZE"></a>Constant: <strong>SHA3_256_BLOCK_SIZE</strong></dt>
1027 <dd><p>The internal block size of SHA3_256.
1028 </p></dd></dl>
1029
1030 <dl>
1031 <dt><a name="index-sha3_005f256_005finit"></a>Function: <em>void</em> <strong>sha3_256_init</strong> <em>(struct sha3_256_ctx *<var>ctx</var>)</em></dt>
1032 <dd><p>Initialize the SHA3-256 state.
1033 </p></dd></dl>
1034
1035 <dl>
1036 <dt><a name="index-sha3_005f256_005fupdate"></a>Function: <em>void</em> <strong>sha3_256_update</strong> <em>(struct sha3_256_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
1037 <dd><p>Hash some more data.
1038 </p></dd></dl>
1039
1040 <dl>
1041 <dt><a name="index-sha3_005f256_005fdigest"></a>Function: <em>void</em> <strong>sha3_256_digest</strong> <em>(struct sha3_256_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
1042 <dd><p>Performs final processing and extracts the message digest, writing it
1043 to <var>digest</var>. <var>length</var> may be smaller than
1044 <code>SHA3_256_DIGEST_SIZE</code>, in which case only the first <var>length</var>
1045 octets of the digest are written.
1046 </p>
1047 <p>This function also resets the context.
1048 </p></dd></dl>
1049
1050 <a name="SHA3_002d384"></a>
1051 <h4 class="subsubsection">6.1.1.7 <acronym>SHA3-384</acronym></h4>
1052
1053 <p>This is SHA3 with 384-bit output size.
1054 </p>
1055 <p>Nettle defines SHA3-384 in <samp>&lt;nettle/sha3.h&gt;</samp>.
1056 </p>
1057 <dl>
1058 <dt><a name="index-struct-sha3_005f384_005fctx"></a>Context struct: <strong>struct sha3_384_ctx</strong></dt>
1059 </dl>
1060
1061 <dl>
1062 <dt><a name="index-SHA3_005f384_005fDIGEST_005fSIZE"></a>Constant: <strong>SHA3_384_DIGEST_SIZE</strong></dt>
1063 <dd><p>The size of a SHA3_384 digest, i.e., 48.
1064 </p></dd></dl>
1065
1066 <dl>
1067 <dt><a name="index-SHA3_005f384_005fBLOCK_005fSIZE"></a>Constant: <strong>SHA3_384_BLOCK_SIZE</strong></dt>
1068 <dd><p>The internal block size of SHA3_384.
1069 </p></dd></dl>
1070
1071 <dl>
1072 <dt><a name="index-sha3_005f384_005finit"></a>Function: <em>void</em> <strong>sha3_384_init</strong> <em>(struct sha3_384_ctx *<var>ctx</var>)</em></dt>
1073 <dd><p>Initialize the SHA3-384 state.
1074 </p></dd></dl>
1075
1076 <dl>
1077 <dt><a name="index-sha3_005f384_005fupdate"></a>Function: <em>void</em> <strong>sha3_384_update</strong> <em>(struct sha3_384_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
1078 <dd><p>Hash some more data.
1079 </p></dd></dl>
1080
1081 <dl>
1082 <dt><a name="index-sha3_005f384_005fdigest"></a>Function: <em>void</em> <strong>sha3_384_digest</strong> <em>(struct sha3_384_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
1083 <dd><p>Performs final processing and extracts the message digest, writing it
1084 to <var>digest</var>. <var>length</var> may be smaller than
1085 <code>SHA3_384_DIGEST_SIZE</code>, in which case only the first <var>length</var>
1086 octets of the digest are written.
1087 </p>
1088 <p>This function also resets the context.
1089 </p></dd></dl>
1090
1091 <a name="SHA3_002d512"></a>
1092 <h4 class="subsubsection">6.1.1.8 <acronym>SHA3-512</acronym></h4>
1093
1094 <p>This is SHA3 with 512-bit output size.
1095 </p>
1096 <p>Nettle defines SHA3-512 in <samp>&lt;nettle/sha3.h&gt;</samp>.
1097 </p>
1098 <dl>
1099 <dt><a name="index-struct-sha3_005f512_005fctx"></a>Context struct: <strong>struct sha3_512_ctx</strong></dt>
1100 </dl>
1101
1102 <dl>
1103 <dt><a name="index-SHA3_005f512_005fDIGEST_005fSIZE"></a>Constant: <strong>SHA3_512_DIGEST_SIZE</strong></dt>
1104 <dd><p>The size of a SHA3_512 digest, i.e. 64.
1105 </p></dd></dl>
1106
1107 <dl>
1108 <dt><a name="index-SHA3_005f512_005fBLOCK_005fSIZE"></a>Constant: <strong>SHA3_512_BLOCK_SIZE</strong></dt>
1109 <dd><p>The internal block size of SHA3_512.
1110 </p></dd></dl>
1111
1112 <dl>
1113 <dt><a name="index-sha3_005f512_005finit"></a>Function: <em>void</em> <strong>sha3_512_init</strong> <em>(struct sha3_512_ctx *<var>ctx</var>)</em></dt>
1114 <dd><p>Initialize the SHA3-512 state.
1115 </p></dd></dl>
1116
1117 <dl>
1118 <dt><a name="index-sha3_005f512_005fupdate"></a>Function: <em>void</em> <strong>sha3_512_update</strong> <em>(struct sha3_512_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
1119 <dd><p>Hash some more data.
1120 </p></dd></dl>
1121
1122 <dl>
1123 <dt><a name="index-sha3_005f512_005fdigest"></a>Function: <em>void</em> <strong>sha3_512_digest</strong> <em>(struct sha3_512_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
1124 <dd><p>Performs final processing and extracts the message digest, writing it
1125 to <var>digest</var>. <var>length</var> may be smaller than
1126 <code>SHA3_512_DIGEST_SIZE</code>, in which case only the first <var>length</var>
1127 octets of the digest are written.
1128 </p>
1129 <p>This function also resets the context.
1130 </p></dd></dl>
1131
1132 <hr>
1133 <a name="Legacy-hash-functions"></a>
1134 <div class="header">
1135 <p>
1136 Next: <a href="#nettle_005fhash-abstraction" accesskey="n" rel="next">nettle_hash abstraction</a>, Previous: <a href="#Recommended-hash-functions" accesskey="p" rel="prev">Recommended hash functions</a>, Up: <a href="#Hash-functions" accesskey="u" rel="up">Hash functions</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1137 </div>
1138 <a name="Legacy-hash-functions-1"></a>
1139 <h4 class="subsection">6.1.2 Legacy hash functions</h4>
1140
1141 <p>The hash functions in this section all have some known weaknesses, and
1142 should be avoided for new applications. These hash functions are mainly
1143 useful for compatibility with old applications and protocols. Some are
1144 still considered safe as building blocks for particular constructions,
1145 e.g., there seems to be no known attacks against HMAC-SHA1 or even
1146 HMAC-MD5. In some important cases, use of a &ldquo;legacy&rdquo; hash function
1147 does not in itself make the application insecure; if a known weakness is
1148 relevant depends on how the hash function is used, and on the threat
1149 model.
1150 </p>
1151 <a name="MD5"></a>
1152 <h4 class="subsubsection">6.1.2.1 <acronym>MD5</acronym></h4>
1153
1154 <p>MD5 is a message digest function constructed by Ronald Rivest, and
1155 described in <cite>RFC 1321</cite>. It outputs message digests of 128 bits, or
1156 16 octets. Nettle defines MD5 in <samp>&lt;nettle/md5.h&gt;</samp>.
1157 </p>
1158 <dl>
1159 <dt><a name="index-struct-md5_005fctx"></a>Context struct: <strong>struct md5_ctx</strong></dt>
1160 </dl>
1161
1162 <dl>
1163 <dt><a name="index-MD5_005fDIGEST_005fSIZE"></a>Constant: <strong>MD5_DIGEST_SIZE</strong></dt>
1164 <dd><p>The size of an MD5 digest, i.e. 16.
1165 </p></dd></dl>
1166
1167 <dl>
1168 <dt><a name="index-MD5_005fBLOCK_005fSIZE"></a>Constant: <strong>MD5_BLOCK_SIZE</strong></dt>
1169 <dd><p>The internal block size of MD5. Useful for some special constructions,
1170 in particular HMAC-MD5.
1171 </p></dd></dl>
1172
1173 <dl>
1174 <dt><a name="index-md5_005finit"></a>Function: <em>void</em> <strong>md5_init</strong> <em>(struct md5_ctx *<var>ctx</var>)</em></dt>
1175 <dd><p>Initialize the MD5 state.
1176 </p></dd></dl>
1177
1178 <dl>
1179 <dt><a name="index-md5_005fupdate"></a>Function: <em>void</em> <strong>md5_update</strong> <em>(struct md5_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
1180 <dd><p>Hash some more data.
1181 </p></dd></dl>
1182
1183 <dl>
1184 <dt><a name="index-md5_005fdigest"></a>Function: <em>void</em> <strong>md5_digest</strong> <em>(struct md5_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
1185 <dd><p>Performs final processing and extracts the message digest, writing it
1186 to <var>digest</var>. <var>length</var> may be smaller than
1187 <code>MD5_DIGEST_SIZE</code>, in which case only the first <var>length</var>
1188 octets of the digest are written.
1189 </p>
1190 <p>This function also resets the context in the same way as
1191 <code>md5_init</code>.
1192 </p></dd></dl>
1193
1194 <p>The normal way to use MD5 is to call the functions in order: First
1195 <code>md5_init</code>, then <code>md5_update</code> zero or more times, and finally
1196 <code>md5_digest</code>. After <code>md5_digest</code>, the context is reset to
1197 its initial state, so you can start over calling <code>md5_update</code> to
1198 hash new data.
1199 </p>
1200 <p>To start over, you can call <code>md5_init</code> at any time.
1201 </p>
1202 <a name="MD2"></a>
1203 <h4 class="subsubsection">6.1.2.2 <acronym>MD2</acronym></h4>
1204
1205 <p>MD2 is another hash function of Ronald Rivest&rsquo;s, described in
1206 <cite>RFC 1319</cite>. It outputs message digests of 128 bits, or 16 octets.
1207 Nettle defines MD2 in <samp>&lt;nettle/md2.h&gt;</samp>.
1208 </p>
1209 <dl>
1210 <dt><a name="index-struct-md2_005fctx"></a>Context struct: <strong>struct md2_ctx</strong></dt>
1211 </dl>
1212
1213 <dl>
1214 <dt><a name="index-MD2_005fDIGEST_005fSIZE"></a>Constant: <strong>MD2_DIGEST_SIZE</strong></dt>
1215 <dd><p>The size of an MD2 digest, i.e. 16.
1216 </p></dd></dl>
1217
1218 <dl>
1219 <dt><a name="index-MD2_005fBLOCK_005fSIZE"></a>Constant: <strong>MD2_BLOCK_SIZE</strong></dt>
1220 <dd><p>The internal block size of MD2.
1221 </p></dd></dl>
1222
1223 <dl>
1224 <dt><a name="index-md2_005finit"></a>Function: <em>void</em> <strong>md2_init</strong> <em>(struct md2_ctx *<var>ctx</var>)</em></dt>
1225 <dd><p>Initialize the MD2 state.
1226 </p></dd></dl>
1227
1228 <dl>
1229 <dt><a name="index-md2_005fupdate"></a>Function: <em>void</em> <strong>md2_update</strong> <em>(struct md2_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
1230 <dd><p>Hash some more data.
1231 </p></dd></dl>
1232
1233 <dl>
1234 <dt><a name="index-md2_005fdigest"></a>Function: <em>void</em> <strong>md2_digest</strong> <em>(struct md2_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
1235 <dd><p>Performs final processing and extracts the message digest, writing it
1236 to <var>digest</var>. <var>length</var> may be smaller than
1237 <code>MD2_DIGEST_SIZE</code>, in which case only the first <var>length</var>
1238 octets of the digest are written.
1239 </p>
1240 <p>This function also resets the context in the same way as
1241 <code>md2_init</code>.
1242 </p></dd></dl>
1243
1244 <a name="MD4"></a>
1245 <h4 class="subsubsection">6.1.2.3 <acronym>MD4</acronym></h4>
1246
1247 <p>MD4 is a predecessor of MD5, described in <cite>RFC 1320</cite>. Like MD5, it
1248 is constructed by Ronald Rivest. It outputs message digests of 128 bits,
1249 or 16 octets. Nettle defines MD4 in <samp>&lt;nettle/md4.h&gt;</samp>. Use of MD4 is
1250 not recommended, but it is sometimes needed for compatibility with
1251 existing applications and protocols.
1252 </p>
1253 <dl>
1254 <dt><a name="index-struct-md4_005fctx"></a>Context struct: <strong>struct md4_ctx</strong></dt>
1255 </dl>
1256
1257 <dl>
1258 <dt><a name="index-MD4_005fDIGEST_005fSIZE"></a>Constant: <strong>MD4_DIGEST_SIZE</strong></dt>
1259 <dd><p>The size of an MD4 digest, i.e. 16.
1260 </p></dd></dl>
1261
1262 <dl>
1263 <dt><a name="index-MD4_005fBLOCK_005fSIZE"></a>Constant: <strong>MD4_BLOCK_SIZE</strong></dt>
1264 <dd><p>The internal block size of MD4.
1265 </p></dd></dl>
1266
1267 <dl>
1268 <dt><a name="index-md4_005finit"></a>Function: <em>void</em> <strong>md4_init</strong> <em>(struct md4_ctx *<var>ctx</var>)</em></dt>
1269 <dd><p>Initialize the MD4 state.
1270 </p></dd></dl>
1271
1272 <dl>
1273 <dt><a name="index-md4_005fupdate"></a>Function: <em>void</em> <strong>md4_update</strong> <em>(struct md4_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
1274 <dd><p>Hash some more data.
1275 </p></dd></dl>
1276
1277 <dl>
1278 <dt><a name="index-md4_005fdigest"></a>Function: <em>void</em> <strong>md4_digest</strong> <em>(struct md4_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
1279 <dd><p>Performs final processing and extracts the message digest, writing it
1280 to <var>digest</var>. <var>length</var> may be smaller than
1281 <code>MD4_DIGEST_SIZE</code>, in which case only the first <var>length</var>
1282 octets of the digest are written.
1283 </p>
1284 <p>This function also resets the context in the same way as
1285 <code>md4_init</code>.
1286 </p></dd></dl>
1287
1288 <a name="RIPEMD160"></a>
1289 <h4 class="subsubsection">6.1.2.4 <acronym>RIPEMD160</acronym></h4>
1290
1291 <p>RIPEMD160 is a hash function designed by Hans Dobbertin, Antoon
1292 Bosselaers, and Bart Preneel, as a strengthened version of RIPEMD
1293 (which, like MD4 and MD5, fails the collision-resistance requirement).
1294 It produces message digests of 160 bits, or 20 octets. Nettle defined
1295 RIPEMD160 in <samp>nettle/ripemd160.h</samp>.
1296 </p>
1297 <dl>
1298 <dt><a name="index-struct-ripemd160_005fctx"></a>Context struct: <strong>struct ripemd160_ctx</strong></dt>
1299 </dl>
1300
1301 <dl>
1302 <dt><a name="index-RIPEMD160_005fDIGEST_005fSIZE"></a>Constant: <strong>RIPEMD160_DIGEST_SIZE</strong></dt>
1303 <dd><p>The size of a RIPEMD160 digest, i.e. 20.
1304 </p></dd></dl>
1305
1306 <dl>
1307 <dt><a name="index-RIPEMD160_005fBLOCK_005fSIZE"></a>Constant: <strong>RIPEMD160_BLOCK_SIZE</strong></dt>
1308 <dd><p>The internal block size of RIPEMD160.
1309 </p></dd></dl>
1310
1311 <dl>
1312 <dt><a name="index-ripemd160_005finit"></a>Function: <em>void</em> <strong>ripemd160_init</strong> <em>(struct ripemd160_ctx *<var>ctx</var>)</em></dt>
1313 <dd><p>Initialize the RIPEMD160 state.
1314 </p></dd></dl>
1315
1316 <dl>
1317 <dt><a name="index-ripemd160_005fupdate"></a>Function: <em>void</em> <strong>ripemd160_update</strong> <em>(struct ripemd160_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
1318 <dd><p>Hash some more data.
1319 </p></dd></dl>
1320
1321 <dl>
1322 <dt><a name="index-ripemd160_005fdigest"></a>Function: <em>void</em> <strong>ripemd160_digest</strong> <em>(struct ripemd160_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
1323 <dd><p>Performs final processing and extracts the message digest, writing it
1324 to <var>digest</var>. <var>length</var> may be smaller than
1325 <code>RIPEMD160_DIGEST_SIZE</code>, in which case only the first <var>length</var>
1326 octets of the digest are written.
1327 </p>
1328 <p>This function also resets the context in the same way as
1329 <code>ripemd160_init</code>.
1330 </p></dd></dl>
1331
1332 <a name="SHA1"></a>
1333 <h4 class="subsubsection">6.1.2.5 <acronym>SHA1</acronym></h4>
1334
1335 <p>SHA1 is a hash function specified by <em>NIST</em> (The U.S. National
1336 Institute for Standards and Technology). It outputs hash values of 160
1337 bits, or 20 octets. Nettle defines SHA1 in <samp>&lt;nettle/sha1.h&gt;</samp> (and
1338 in <samp>&lt;nettle/sha.h&gt;</samp>, for backwards compatibility).
1339 </p>
1340 <dl>
1341 <dt><a name="index-struct-sha1_005fctx"></a>Context struct: <strong>struct sha1_ctx</strong></dt>
1342 </dl>
1343
1344 <dl>
1345 <dt><a name="index-SHA1_005fDIGEST_005fSIZE"></a>Constant: <strong>SHA1_DIGEST_SIZE</strong></dt>
1346 <dd><p>The size of a SHA1 digest, i.e. 20.
1347 </p></dd></dl>
1348
1349 <dl>
1350 <dt><a name="index-SHA1_005fBLOCK_005fSIZE"></a>Constant: <strong>SHA1_BLOCK_SIZE</strong></dt>
1351 <dd><p>The internal block size of SHA1. Useful for some special constructions,
1352 in particular HMAC-SHA1.
1353 </p></dd></dl>
1354
1355 <dl>
1356 <dt><a name="index-sha1_005finit"></a>Function: <em>void</em> <strong>sha1_init</strong> <em>(struct sha1_ctx *<var>ctx</var>)</em></dt>
1357 <dd><p>Initialize the SHA1 state.
1358 </p></dd></dl>
1359
1360 <dl>
1361 <dt><a name="index-sha1_005fupdate"></a>Function: <em>void</em> <strong>sha1_update</strong> <em>(struct sha1_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
1362 <dd><p>Hash some more data.
1363 </p></dd></dl>
1364
1365 <dl>
1366 <dt><a name="index-sha1_005fdigest"></a>Function: <em>void</em> <strong>sha1_digest</strong> <em>(struct sha1_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
1367 <dd><p>Performs final processing and extracts the message digest, writing it
1368 to <var>digest</var>. <var>length</var> may be smaller than
1369 <code>SHA1_DIGEST_SIZE</code>, in which case only the first <var>length</var>
1370 octets of the digest are written.
1371 </p>
1372 <p>This function also resets the context in the same way as
1373 <code>sha1_init</code>.
1374 </p></dd></dl>
1375
1376
1377 <a name="GOSTHASH94"></a>
1378 <h4 class="subsubsection">6.1.2.6 <acronym>GOSTHASH94</acronym></h4>
1379
1380 <p>The GOST94 or GOST R 34.11-94 hash algorithm is a Soviet-era algorithm
1381 used in Russian government standards (see <cite>RFC 4357</cite>).
1382 It outputs message digests of 256 bits, or 32 octets.
1383 Nettle defines GOSTHASH94 in <samp>&lt;nettle/gosthash94.h&gt;</samp>.
1384 </p>
1385 <dl>
1386 <dt><a name="index-struct-gosthash94_005fctx"></a>Context struct: <strong>struct gosthash94_ctx</strong></dt>
1387 </dl>
1388
1389 <dl>
1390 <dt><a name="index-GOSTHASH94_005fDIGEST_005fSIZE"></a>Constant: <strong>GOSTHASH94_DIGEST_SIZE</strong></dt>
1391 <dd><p>The size of a GOSTHASH94 digest, i.e. 32.
1392 </p></dd></dl>
1393
1394 <dl>
1395 <dt><a name="index-GOSTHASH94_005fBLOCK_005fSIZE"></a>Constant: <strong>GOSTHASH94_BLOCK_SIZE</strong></dt>
1396 <dd><p>The internal block size of GOSTHASH94, i.e., 32.
1397 </p></dd></dl>
1398
1399 <dl>
1400 <dt><a name="index-gosthash94_005finit"></a>Function: <em>void</em> <strong>gosthash94_init</strong> <em>(struct gosthash94_ctx *<var>ctx</var>)</em></dt>
1401 <dd><p>Initialize the GOSTHASH94 state.
1402 </p></dd></dl>
1403
1404 <dl>
1405 <dt><a name="index-gosthash94_005fupdate"></a>Function: <em>void</em> <strong>gosthash94_update</strong> <em>(struct gosthash94_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
1406 <dd><p>Hash some more data.
1407 </p></dd></dl>
1408
1409 <dl>
1410 <dt><a name="index-gosthash94_005fdigest"></a>Function: <em>void</em> <strong>gosthash94_digest</strong> <em>(struct gosthash94_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
1411 <dd><p>Performs final processing and extracts the message digest, writing it
1412 to <var>digest</var>. <var>length</var> may be smaller than
1413 <code>GOSTHASH94_DIGEST_SIZE</code>, in which case only the first <var>length</var>
1414 octets of the digest are written.
1415 </p>
1416 <p>This function also resets the context in the same way as
1417 <code>gosthash94_init</code>.
1418 </p></dd></dl>
1419
1420 <hr>
1421 <a name="nettle_005fhash-abstraction"></a>
1422 <div class="header">
1423 <p>
1424 Previous: <a href="#Legacy-hash-functions" accesskey="p" rel="prev">Legacy hash functions</a>, Up: <a href="#Hash-functions" accesskey="u" rel="up">Hash functions</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1425 </div>
1426 <a name="The-struct-nettle_005fhash-abstraction"></a>
1427 <h4 class="subsection">6.1.3 The <code>struct nettle_hash</code> abstraction</h4>
1428 <a name="index-nettle_005fhash"></a>
1429 <a name="index-nettle_005fhashes"></a>
1430
1431 <p>Nettle includes a struct including information about the supported hash
1432 functions. It is defined in <samp>&lt;nettle/nettle-meta.h&gt;</samp>, and is used
1433 by Nettle&rsquo;s implementation of <acronym>HMAC</acronym> (see <a href="#Keyed-hash-functions">Keyed hash functions</a>).
1434 </p>
1435 <dl>
1436 <dt><a name="index-struct-nettle_005fhash"></a>Meta struct: <strong><code>struct nettle_hash</code></strong> <em>name context_size digest_size block_size init update digest</em></dt>
1437 <dd><p>The last three attributes are function pointers, of types
1438 <code>nettle_hash_init_func *</code>, <code>nettle_hash_update_func *</code>, and
1439 <code>nettle_hash_digest_func *</code>. The first argument to these functions is
1440 <code>void *</code> pointer to a context struct, which is of size
1441 <code>context_size</code>.
1442 </p></dd></dl>
1443
1444 <dl>
1445 <dt><a name="index-nettle_005fmd2"></a>Constant Struct: <em>struct nettle_hash</em> <strong>nettle_md2</strong></dt>
1446 <dt><a name="index-nettle_005fmd4"></a>Constant Struct: <em>struct nettle_hash</em> <strong>nettle_md4</strong></dt>
1447 <dt><a name="index-nettle_005fmd5"></a>Constant Struct: <em>struct nettle_hash</em> <strong>nettle_md5</strong></dt>
1448 <dt><a name="index-nettle_005fripemd160"></a>Constant Struct: <em>struct nettle_hash</em> <strong>nettle_ripemd160</strong></dt>
1449 <dt><a name="index-nettle_005fsha1"></a>Constant Struct: <em>struct nettle_hash</em> <strong>nettle_sha1</strong></dt>
1450 <dt><a name="index-nettle_005fsha224"></a>Constant Struct: <em>struct nettle_hash</em> <strong>nettle_sha224</strong></dt>
1451 <dt><a name="index-nettle_005fsha256"></a>Constant Struct: <em>struct nettle_hash</em> <strong>nettle_sha256</strong></dt>
1452 <dt><a name="index-nettle_005fsha384"></a>Constant Struct: <em>struct nettle_hash</em> <strong>nettle_sha384</strong></dt>
1453 <dt><a name="index-nettle_005fsha512"></a>Constant Struct: <em>struct nettle_hash</em> <strong>nettle_sha512</strong></dt>
1454 <dt><a name="index-nettle_005fsha3_005f256"></a>Constant Struct: <em>struct nettle_hash</em> <strong>nettle_sha3_256</strong></dt>
1455 <dt><a name="index-nettle_005fgosthash94"></a>Constant Struct: <em>struct nettle_hash</em> <strong>nettle_gosthash94</strong></dt>
1456 <dd><p>These are all the hash functions that Nettle implements.
1457 </p></dd></dl>
1458
1459 <p>Nettle also exports a list of all these hashes.
1460 </p>
1461 <dl>
1462 <dt><a name="index-nettle_005fhashes-1"></a>Constant Array: <em>struct nettle_hash **</em> <strong>nettle_hashes</strong></dt>
1463 <dd><p>This list can be used to dynamically enumerate or search the supported
1464 algorithms. NULL-terminated.
1465 </p></dd></dl>
1466
1467 <hr>
1468 <a name="Cipher-functions"></a>
1469 <div class="header">
1470 <p>
1471 Next: <a href="#Cipher-modes" accesskey="n" rel="next">Cipher modes</a>, Previous: <a href="#Hash-functions" accesskey="p" rel="prev">Hash functions</a>, Up: <a href="#Reference" accesskey="u" rel="up">Reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
1472 </div>
1473 <a name="Cipher-functions-1"></a>
1474 <h3 class="section">6.2 Cipher functions</h3>
1475 <a name="index-Cipher"></a>
1476
1477 <p>A <em>cipher</em> is a function that takes a message or <em>plaintext</em>
1478 and a secret <em>key</em> and transforms it to a <em>ciphertext</em>. Given
1479 only the ciphertext, but not the key, it should be hard to find the
1480 plaintext. Given matching pairs of plaintext and ciphertext, it should
1481 be hard to find the key.
1482 </p>
1483 <a name="index-Block-Cipher"></a>
1484 <a name="index-Stream-Cipher"></a>
1485
1486 <p>There are two main classes of ciphers: Block ciphers and stream ciphers.
1487 </p>
1488 <p>A block cipher can process data only in fixed size chunks, called
1489 <em>blocks</em>. Typical block sizes are 8 or 16 octets. To encrypt
1490 arbitrary messages, you usually have to pad it to an integral number of
1491 blocks, split it into blocks, and then process each block. The simplest
1492 way is to process one block at a time, independent of each other. That
1493 mode of operation is called <em>ECB</em>, Electronic Code Book mode.
1494 However, using <acronym>ECB</acronym> is usually a bad idea. For a start, plaintext blocks
1495 that are equal are transformed to ciphertext blocks that are equal; that
1496 leaks information about the plaintext. Usually you should apply the
1497 cipher is some &ldquo;feedback mode&rdquo;, <em>CBC</em> (Cipher Block Chaining) and
1498 <em>CTR</em> (Counter mode) being two of
1499 of the most popular. See See <a href="#Cipher-modes">Cipher modes</a>, for information on
1500 how to apply <acronym>CBC</acronym> and <acronym>CTR</acronym> with Nettle.
1501 </p>
1502 <p>A stream cipher can be used for messages of arbitrary length. A typical
1503 stream cipher is a keyed pseudo-random generator. To encrypt a plaintext
1504 message of <var>n</var> octets, you key the generator, generate <var>n</var>
1505 octets of pseudo-random data, and XOR it with the plaintext. To decrypt,
1506 regenerate the same stream using the key, XOR it to the ciphertext, and
1507 the plaintext is recovered.
1508 </p>
1509 <p><strong>Caution:</strong> The first rule for this kind of cipher is the
1510 same as for a One Time Pad: <em>never</em> ever use the same key twice.
1511 </p>
1512 <p>A common misconception is that encryption, by itself, implies
1513 authentication. Say that you and a friend share a secret key, and you
1514 receive an encrypted message. You apply the key, and get a plaintext
1515 message that makes sense to you. Can you then be sure that it really was
1516 your friend that wrote the message you&rsquo;re reading? The answer is no. For
1517 example, if you were using a block cipher in ECB mode, an attacker may
1518 pick up the message on its way, and reorder, delete or repeat some of
1519 the blocks. Even if the attacker can&rsquo;t decrypt the message, he can
1520 change it so that you are not reading the same message as your friend
1521 wrote. If you are using a block cipher in <acronym>CBC</acronym> mode rather than
1522 ECB, or are using a stream cipher, the possibilities for this sort of
1523 attack are different, but the attacker can still make predictable
1524 changes to the message.
1525 </p>
1526 <p>It is recommended to <em>always</em> use an authentication mechanism in
1527 addition to encrypting the messages. Popular choices are Message
1528 Authentication Codes like <acronym>HMAC-SHA1</acronym> (see <a href="#Keyed-hash-functions">Keyed hash functions</a>), or digital signatures like <acronym>RSA</acronym>.
1529 </p>
1530 <p>Some ciphers have so called &ldquo;weak keys&rdquo;, keys that results in
1531 undesirable structure after the key setup processing, and should be
1532 avoided. In Nettle, most key setup functions have no return value, but
1533 for ciphers with weak keys, the return value indicates whether or not
1534 the given key is weak. For good keys, key setup returns 1, and for weak
1535 keys, it returns 0. When possible, avoid algorithms that
1536 have weak keys. There are several good ciphers that don&rsquo;t have any weak
1537 keys.
1538 </p>
1539 <p>To encrypt a message, you first initialize a cipher context for
1540 encryption or decryption with a particular key. You then use the context
1541 to process plaintext or ciphertext messages. The initialization is known
1542 as <em>key setup</em>. With Nettle, it is recommended to use each
1543 context struct for only one direction, even if some of the ciphers use a
1544 single key setup function that can be used for both encryption and
1545 decryption.
1546 </p>
1547 <a name="AES"></a>
1548 <h4 class="subsection">6.2.1 AES</h4>
1549 <p>AES is a block cipher, specified by NIST as a replacement for
1550 the older DES standard. The standard is the result of a competition
1551 between cipher designers. The winning design, also known as RIJNDAEL,
1552 was constructed by Joan Daemen and Vincent Rijnmen.
1553 </p>
1554 <p>Like all the AES candidates, the winning design uses a block size of 128
1555 bits, or 16 octets, and three possible key-size, 128, 192 and 256 bits
1556 (16, 24 and 32 octets) being the allowed key sizes. It does not have any
1557 weak keys. Nettle defines AES in <samp>&lt;nettle/aes.h&gt;</samp>, and there is one
1558 context struct for each key size. (Earlier versions of Nettle used a
1559 single context struct, <code>struct aes_ctx</code>, for all key sizes. This
1560 interface kept for backwards compatibility).
1561 </p>
1562 <dl>
1563 <dt><a name="index-struct-aes128_005fctx"></a>Context struct: <strong>struct aes128_ctx</strong></dt>
1564 <dt><a name="index-struct-aes192_005fctx"></a>Context struct: <strong>struct aes192_ctx</strong></dt>
1565 <dt><a name="index-struct-aes256_005fctx"></a>Context struct: <strong>struct aes256_ctx</strong></dt>
1566 </dl>
1567
1568 <dl>
1569 <dt><a name="index-struct-aes_005fctx"></a>Context struct: <strong>struct aes_ctx</strong></dt>
1570 <dd><p>Alternative struct, for the old AES interface.
1571 </p></dd></dl>
1572
1573 <dl>
1574 <dt><a name="index-AES_005fBLOCK_005fSIZE"></a>Constant: <strong>AES_BLOCK_SIZE</strong></dt>
1575 <dd><p>The AES block-size, 16.
1576 </p></dd></dl>
1577
1578 <dl>
1579 <dt><a name="index-AES128_005fKEY_005fSIZE"></a>Constant: <strong>AES128_KEY_SIZE</strong></dt>
1580 <dt><a name="index-AES192_005fKEY_005fSIZE"></a>Constant: <strong>AES192_KEY_SIZE</strong></dt>
1581 <dt><a name="index-AES256_005fKEY_005fSIZE"></a>Constant: <strong>AES256_KEY_SIZE</strong></dt>
1582 <dt><a name="index-AES_005fMIN_005fKEY_005fSIZE"></a>Constant: <strong>AES_MIN_KEY_SIZE</strong></dt>
1583 <dt><a name="index-AES_005fMAX_005fKEY_005fSIZE"></a>Constant: <strong>AES_MAX_KEY_SIZE</strong></dt>
1584 </dl>
1585
1586 <dl>
1587 <dt><a name="index-AES_005fKEY_005fSIZE"></a>Constant: <strong>AES_KEY_SIZE</strong></dt>
1588 <dd><p>Default AES key size, 32.
1589 </p></dd></dl>
1590
1591 <dl>
1592 <dt><a name="index-aes128_005fset_005fencrypt_005fkey"></a>Function: <em>void</em> <strong>aes128_set_encrypt_key</strong> <em>(struct aes128_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
1593 <dt><a name="index-aes128_005fset_005fdecrypt_005fkey"></a>Function: <em>void</em> <strong>aes128_set_decrypt_key</strong> <em>(struct aes128_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
1594 <dt><a name="index-aes192_005fset_005fencrypt_005fkey"></a>Function: <em>void</em> <strong>aes192_set_encrypt_key</strong> <em>(struct aes192_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
1595 <dt><a name="index-aes192_005fset_005fdecrypt_005fkey"></a>Function: <em>void</em> <strong>aes192_set_decrypt_key</strong> <em>(struct aes192_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
1596 <dt><a name="index-aes256_005fset_005fencrypt_005fkey"></a>Function: <em>void</em> <strong>aes256_set_encrypt_key</strong> <em>(struct aes256_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
1597 <dt><a name="index-aes256_005fset_005fdecrypt_005fkey"></a>Function: <em>void</em> <strong>aes256_set_decrypt_key</strong> <em>(struct aes256_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
1598 <dt><a name="index-aes_005fset_005fencrypt_005fkey"></a>Function: <em>void</em> <strong>aes_set_encrypt_key</strong> <em>(struct aes_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>key</var>)</em></dt>
1599 <dt><a name="index-aes_005fset_005fdecrypt_005fkey"></a>Function: <em>void</em> <strong>aes_set_decrypt_key</strong> <em>(struct aes_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>key</var>)</em></dt>
1600 <dd><p>Initialize the cipher, for encryption or decryption, respectively.
1601 </p></dd></dl>
1602
1603 <dl>
1604 <dt><a name="index-aes128_005finvert_005fkey"></a>Function: <em>void</em> <strong>aes128_invert_key</strong> <em>(struct aes128_ctx *<var>dst</var>, const struct aes128_ctx *<var>src</var>)</em></dt>
1605 <dt><a name="index-aes192_005finvert_005fkey"></a>Function: <em>void</em> <strong>aes192_invert_key</strong> <em>(struct aes192_ctx *<var>dst</var>, const struct aes192_ctx *<var>src</var>)</em></dt>
1606 <dt><a name="index-aes256_005finvert_005fkey"></a>Function: <em>void</em> <strong>aes256_invert_key</strong> <em>(struct aes256_ctx *<var>dst</var>, const struct aes256_ctx *<var>src</var>)</em></dt>
1607 <dt><a name="index-aes_005finvert_005fkey"></a>Function: <em>void</em> <strong>aes_invert_key</strong> <em>(struct aes_ctx *<var>dst</var>, const struct aes_ctx *<var>src</var>)</em></dt>
1608 <dd><p>Given a context <var>src</var> initialized for encryption, initializes the
1609 context struct <var>dst</var> for decryption, using the same key. If the same
1610 context struct is passed for both <code>src</code> and <code>dst</code>, it is
1611 converted in place. These functions are mainly useful for applications
1612 which needs to both encrypt and decrypt using the <em>same</em> key,
1613 because calling, e.g., <code>aes128_set_encrypt_key</code> and
1614 <code>aes128_invert_key</code>, is more efficient than calling
1615 <code>aes128_set_encrypt_key</code> and <code>aes128_set_decrypt_key</code>.
1616 </p></dd></dl>
1617
1618 <dl>
1619 <dt><a name="index-aes128_005fencrypt"></a>Function: <em>void</em> <strong>aes128_encrypt</strong> <em>(struct aes128_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1620 <dt><a name="index-aes192_005fencrypt"></a>Function: <em>void</em> <strong>aes192_encrypt</strong> <em>(struct aes192_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1621 <dt><a name="index-aes256_005fencrypt"></a>Function: <em>void</em> <strong>aes256_encrypt</strong> <em>(struct aes256_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1622 <dt><a name="index-aes_005fencrypt"></a>Function: <em>void</em> <strong>aes_encrypt</strong> <em>(struct aes_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1623 <dd><p>Encryption function. <var>length</var> must be an integral multiple of the
1624 block size. If it is more than one block, the data is processed in ECB
1625 mode. <code>src</code> and <code>dst</code> may be equal, but they must not overlap
1626 in any other way.
1627 </p></dd></dl>
1628
1629 <dl>
1630 <dt><a name="index-aes128_005fdecrypt"></a>Function: <em>void</em> <strong>aes128_decrypt</strong> <em>(struct aes128_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1631 <dt><a name="index-aes192_005fdecrypt"></a>Function: <em>void</em> <strong>aes192_decrypt</strong> <em>(struct aes192_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1632 <dt><a name="index-aes256_005fdecrypt"></a>Function: <em>void</em> <strong>aes256_decrypt</strong> <em>(struct aes256_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1633 <dt><a name="index-aes_005fdecrypt"></a>Function: <em>void</em> <strong>aes_decrypt</strong> <em>(struct aes_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1634 <dd><p>Analogous to the encryption functions above.
1635 </p></dd></dl>
1636
1637 <a name="ARCFOUR"></a>
1638 <h4 class="subsection">6.2.2 ARCFOUR</h4>
1639 <p>ARCFOUR is a stream cipher, also known under the trade marked name RC4,
1640 and it is one of the fastest ciphers around. A problem is that the key
1641 setup of ARCFOUR is quite weak, you should never use keys with
1642 structure, keys that are ordinary passwords, or sequences of keys like
1643 &ldquo;secret:1&rdquo;, &ldquo;secret:2&rdquo;, <small class="enddots">...</small>. If you have keys that don&rsquo;t look
1644 like random bit strings, and you want to use ARCFOUR, always hash the
1645 key before feeding it to ARCFOUR. Furthermore, the initial bytes of the
1646 generated key stream leak information about the key; for this reason, it
1647 is recommended to discard the first 512 bytes of the key stream.
1648 </p>
1649 <div class="example">
1650 <pre class="example">/* A more robust key setup function for ARCFOUR */
1651 void
1652 arcfour_set_key_hashed(struct arcfour_ctx *ctx,
1653                        size_t length, const uint8_t *key)
1654 {
1655   struct sha256_ctx hash;
1656   uint8_t digest[SHA256_DIGEST_SIZE];
1657   uint8_t buffer[0x200];
1658
1659   sha256_init(&amp;hash);
1660   sha256_update(&amp;hash, length, key);
1661   sha256_digest(&amp;hash, SHA256_DIGEST_SIZE, digest);
1662
1663   arcfour_set_key(ctx, SHA256_DIGEST_SIZE, digest);
1664   arcfour_crypt(ctx, sizeof(buffer), buffer, buffer);
1665 }
1666 </pre></div>
1667
1668 <p>Nettle defines ARCFOUR in <samp>&lt;nettle/arcfour.h&gt;</samp>.
1669 </p>
1670 <dl>
1671 <dt><a name="index-struct-arcfour_005fctx"></a>Context struct: <strong>struct arcfour_ctx</strong></dt>
1672 </dl>
1673
1674 <dl>
1675 <dt><a name="index-ARCFOUR_005fMIN_005fKEY_005fSIZE"></a>Constant: <strong>ARCFOUR_MIN_KEY_SIZE</strong></dt>
1676 <dd><p>Minimum key size, 1.
1677 </p></dd></dl>
1678
1679 <dl>
1680 <dt><a name="index-ARCFOUR_005fMAX_005fKEY_005fSIZE"></a>Constant: <strong>ARCFOUR_MAX_KEY_SIZE</strong></dt>
1681 <dd><p>Maximum key size, 256.
1682 </p></dd></dl>
1683
1684 <dl>
1685 <dt><a name="index-ARCFOUR_005fKEY_005fSIZE"></a>Constant: <strong>ARCFOUR_KEY_SIZE</strong></dt>
1686 <dd><p>Default ARCFOUR key size, 16.
1687 </p></dd></dl>
1688
1689 <dl>
1690 <dt><a name="index-arcfour_005fset_005fkey"></a>Function: <em>void</em> <strong>arcfour_set_key</strong> <em>(struct arcfour_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>key</var>)</em></dt>
1691 <dd><p>Initialize the cipher. The same function is used for both encryption and
1692 decryption.
1693 </p></dd></dl>
1694
1695 <dl>
1696 <dt><a name="index-arcfour_005fcrypt"></a>Function: <em>void</em> <strong>arcfour_crypt</strong> <em>(struct arcfour_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1697 <dd><p>Encrypt some data. The same function is used for both encryption and
1698 decryption. Unlike the block ciphers, this function modifies the
1699 context, so you can split the data into arbitrary chunks and encrypt
1700 them one after another. The result is the same as if you had called
1701 <code>arcfour_crypt</code> only once with all the data.
1702 </p></dd></dl>
1703
1704 <a name="ARCTWO"></a>
1705 <h4 class="subsection">6.2.3 ARCTWO</h4>
1706 <p>ARCTWO (also known as the trade marked name RC2) is a block cipher
1707 specified in RFC 2268. Nettle also include a variation of the ARCTWO
1708 set key operation that lack one step, to be compatible with the
1709 reverse engineered RC2 cipher description, as described in a Usenet
1710 post to <code>sci.crypt</code> by Peter Gutmann.
1711 </p>
1712 <p>ARCTWO uses a block size of 64 bits, and variable key-size ranging
1713 from 1 to 128 octets. Besides the key, ARCTWO also has a second
1714 parameter to key setup, the number of effective key bits, <code>ekb</code>.
1715 This parameter can be used to artificially reduce the key size. In
1716 practice, <code>ekb</code> is usually set equal to the input key size.
1717 Nettle defines ARCTWO in <samp>&lt;nettle/arctwo.h&gt;</samp>.
1718 </p>
1719 <p>We do not recommend the use of ARCTWO; the Nettle implementation is
1720 provided primarily for interoperability with existing applications and
1721 standards.
1722 </p>
1723 <dl>
1724 <dt><a name="index-struct-arctwo_005fctx"></a>Context struct: <strong>struct arctwo_ctx</strong></dt>
1725 </dl>
1726
1727 <dl>
1728 <dt><a name="index-ARCTWO_005fBLOCK_005fSIZE"></a>Constant: <strong>ARCTWO_BLOCK_SIZE</strong></dt>
1729 <dd><p>The ARCTWO block-size, 8.
1730 </p></dd></dl>
1731
1732 <dl>
1733 <dt><a name="index-ARCTWO_005fMIN_005fKEY_005fSIZE"></a>Constant: <strong>ARCTWO_MIN_KEY_SIZE</strong></dt>
1734 </dl>
1735
1736 <dl>
1737 <dt><a name="index-ARCTWO_005fMAX_005fKEY_005fSIZE"></a>Constant: <strong>ARCTWO_MAX_KEY_SIZE</strong></dt>
1738 </dl>
1739
1740 <dl>
1741 <dt><a name="index-ARCTWO_005fKEY_005fSIZE"></a>Constant: <strong>ARCTWO_KEY_SIZE</strong></dt>
1742 <dd><p>Default ARCTWO key size, 8.
1743 </p></dd></dl>
1744
1745 <dl>
1746 <dt><a name="index-arctwo_005fset_005fkey_005fekb"></a>Function: <em>void</em> <strong>arctwo_set_key_ekb</strong> <em>(struct arctwo_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>key</var>, unsigned <var>ekb</var>)</em></dt>
1747 <dt><a name="index-arctwo_005fset_005fkey"></a>Function: <em>void</em> <strong>arctwo_set_key</strong> <em>(struct arctwo_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>key</var>)</em></dt>
1748 <dt><a name="index-arctwo_005fset_005fkey_005fgutmann"></a>Function: <em>void</em> <strong>arctwo_set_key_gutmann</strong> <em>(struct arctwo_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>key</var>)</em></dt>
1749 <dd><p>Initialize the cipher. The same function is used for both encryption
1750 and decryption. The first function is the most general one, which lets
1751 you provide both the variable size key, and the desired effective key
1752 size (in bits). The maximum value for <var>ekb</var> is 1024, and for
1753 convenience, <code>ekb = 0</code> has the same effect as <code>ekb = 1024</code>.
1754 </p>
1755 <p><code>arctwo_set_key(ctx, length, key)</code> is equivalent to
1756 <code>arctwo_set_key_ekb(ctx, length, key, 8*length)</code>, and
1757 <code>arctwo_set_key_gutmann(ctx, length, key)</code> is equivalent to
1758 <code>arctwo_set_key_ekb(ctx, length, key, 1024)</code>
1759 </p></dd></dl>
1760
1761 <dl>
1762 <dt><a name="index-arctwo_005fencrypt"></a>Function: <em>void</em> <strong>arctwo_encrypt</strong> <em>(struct arctwo_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1763 <dd><p>Encryption function. <var>length</var> must be an integral multiple of the
1764 block size. If it is more than one block, the data is processed in ECB
1765 mode. <code>src</code> and <code>dst</code> may be equal, but they must not
1766 overlap in any other way.
1767 </p></dd></dl>
1768
1769 <dl>
1770 <dt><a name="index-arctwo_005fdecrypt"></a>Function: <em>void</em> <strong>arctwo_decrypt</strong> <em>(struct arctwo_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1771 <dd><p>Analogous to <code>arctwo_encrypt</code>
1772 </p></dd></dl>
1773
1774 <a name="BLOWFISH"></a>
1775 <h4 class="subsection">6.2.4 BLOWFISH</h4>
1776
1777 <p>BLOWFISH is a block cipher designed by Bruce Schneier. It uses a block
1778 size of 64 bits (8 octets), and a variable key size, up to 448 bits. It
1779 has some weak keys. Nettle defines BLOWFISH in <samp>&lt;nettle/blowfish.h&gt;</samp>.
1780 </p>
1781 <dl>
1782 <dt><a name="index-struct-blowfish_005fctx"></a>Context struct: <strong>struct blowfish_ctx</strong></dt>
1783 </dl>
1784
1785 <dl>
1786 <dt><a name="index-BLOWFISH_005fBLOCK_005fSIZE"></a>Constant: <strong>BLOWFISH_BLOCK_SIZE</strong></dt>
1787 <dd><p>The BLOWFISH block-size, 8.
1788 </p></dd></dl>
1789
1790 <dl>
1791 <dt><a name="index-BLOWFISH_005fMIN_005fKEY_005fSIZE"></a>Constant: <strong>BLOWFISH_MIN_KEY_SIZE</strong></dt>
1792 <dd><p>Minimum BLOWFISH key size, 8.
1793 </p></dd></dl>
1794
1795 <dl>
1796 <dt><a name="index-BLOWFISH_005fMAX_005fKEY_005fSIZE"></a>Constant: <strong>BLOWFISH_MAX_KEY_SIZE</strong></dt>
1797 <dd><p>Maximum BLOWFISH key size, 56.
1798 </p></dd></dl>
1799
1800 <dl>
1801 <dt><a name="index-BLOWFISH_005fKEY_005fSIZE"></a>Constant: <strong>BLOWFISH_KEY_SIZE</strong></dt>
1802 <dd><p>Default BLOWFISH key size, 16.
1803 </p></dd></dl>
1804
1805 <dl>
1806 <dt><a name="index-blowfish_005fset_005fkey"></a>Function: <em>int</em> <strong>blowfish_set_key</strong> <em>(struct blowfish_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>key</var>)</em></dt>
1807 <dd><p>Initialize the cipher. The same function is used for both encryption and
1808 decryption. Checks for weak keys, returning 1
1809 for good keys and 0 for weak keys. Applications that don&rsquo;t care about
1810 weak keys can ignore the return value.
1811 </p>
1812 <p><code>blowfish_encrypt</code> or <code>blowfish_decrypt</code> with a weak key will
1813 crash with an assert violation.
1814 </p></dd></dl>
1815
1816 <dl>
1817 <dt><a name="index-blowfish_005fencrypt"></a>Function: <em>void</em> <strong>blowfish_encrypt</strong> <em>(struct blowfish_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1818 <dd><p>Encryption function. <var>length</var> must be an integral multiple of the
1819 block size. If it is more than one block, the data is processed in ECB
1820 mode. <code>src</code> and <code>dst</code> may be equal, but they must not overlap
1821 in any other way.
1822 </p></dd></dl>
1823
1824 <dl>
1825 <dt><a name="index-blowfish_005fdecrypt"></a>Function: <em>void</em> <strong>blowfish_decrypt</strong> <em>(struct blowfish_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1826 <dd><p>Analogous to <code>blowfish_encrypt</code>
1827 </p></dd></dl>
1828
1829 <a name="Camellia"></a>
1830 <h4 class="subsection">6.2.5 Camellia</h4>
1831
1832 <p>Camellia is a block cipher developed by Mitsubishi and Nippon Telegraph
1833 and Telephone Corporation, described in <cite>RFC3713</cite>. It is
1834 recommended by some Japanese and European authorities as an alternative
1835 to AES, and it is one of the selected algorithms in the New European
1836 Schemes for Signatures, Integrity and Encryption (NESSIE) project. The
1837 algorithm is patented. The implementation in Nettle is derived from the
1838 implementation released by NTT under the GNU LGPL (v2.1 or later), and
1839 relies on the implicit patent license of the LGPL. There is also a
1840 statement of royalty-free licensing for Camellia at
1841 <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
1842 statement has some limitations which seem problematic for free software.
1843 </p>
1844 <p>Camellia uses a the same block size and key sizes as AES: The block size
1845 is 128 bits (16 octets), and the supported key sizes are 128, 192, and
1846 256 bits. The variants with 192 and 256 bit keys are identical, except
1847 for the key setup. Nettle defines Camellia in
1848 <samp>&lt;nettle/camellia.h&gt;</samp>, and there is one context struct for each key
1849 size. (Earlier versions of Nettle used a single context struct,
1850 <code>struct camellia_ctx</code>, for all key sizes. This interface kept for
1851 backwards compatibility).
1852 </p>
1853 <dl>
1854 <dt><a name="index-struct-camellia128_005fctx"></a>Context struct: <strong>struct camellia128_ctx</strong></dt>
1855 <dt><a name="index-struct-camellia192_005fctx"></a>Context struct: <strong>struct camellia192_ctx</strong></dt>
1856 <dt><a name="index-struct-camellia256_005fctx"></a>Context struct: <strong>struct camellia256_ctx</strong></dt>
1857 <dd><p>Contexts structs. Actually, <code>camellia192_ctx</code> is an alias for
1858 <code>camellia256_ctx</code>.
1859 </p></dd></dl>
1860
1861 <dl>
1862 <dt><a name="index-struct-camellia_005fctx"></a>Context struct: <strong>struct camellia_ctx</strong></dt>
1863 <dd><p>Alternative struct, for the old Camellia interface.
1864 </p></dd></dl>
1865
1866 <dl>
1867 <dt><a name="index-CAMELLIA_005fBLOCK_005fSIZE"></a>Constant: <strong>CAMELLIA_BLOCK_SIZE</strong></dt>
1868 <dd><p>The CAMELLIA block-size, 16.
1869 </p></dd></dl>
1870
1871 <dl>
1872 <dt><a name="index-CAMELLIA128_005fKEY_005fSIZE"></a>Constant: <strong>CAMELLIA128_KEY_SIZE</strong></dt>
1873 <dt><a name="index-CAMELLIA192_005fKEY_005fSIZE"></a>Constant: <strong>CAMELLIA192_KEY_SIZE</strong></dt>
1874 <dt><a name="index-CAMELLIA256_005fKEY_005fSIZE"></a>Constant: <strong>CAMELLIA256_KEY_SIZE</strong></dt>
1875 <dt><a name="index-CAMELLIA_005fMIN_005fKEY_005fSIZE"></a>Constant: <strong>CAMELLIA_MIN_KEY_SIZE</strong></dt>
1876 <dt><a name="index-CAMELLIA_005fMAX_005fKEY_005fSIZE"></a>Constant: <strong>CAMELLIA_MAX_KEY_SIZE</strong></dt>
1877 </dl>
1878
1879 <dl>
1880 <dt><a name="index-CAMELLIA_005fKEY_005fSIZE"></a>Constant: <strong>CAMELLIA_KEY_SIZE</strong></dt>
1881 <dd><p>Default CAMELLIA key size, 32.
1882 </p></dd></dl>
1883
1884 <dl>
1885 <dt><a name="index-camellia128_005fset_005fencrypt_005fkey"></a>Function: <em>void</em> <strong>camellia128_set_encrypt_key</strong> <em>(struct camellia128_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
1886 <dt><a name="index-camellia128_005fset_005fdecrypt_005fkey"></a>Function: <em>void</em> <strong>camellia128_set_decrypt_key</strong> <em>(struct camellia128_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
1887 <dt><a name="index-camellia192_005fset_005fencrypt_005fkey"></a>Function: <em>void</em> <strong>camellia192_set_encrypt_key</strong> <em>(struct camellia192_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
1888 <dt><a name="index-camellia192_005fset_005fdecrypt_005fkey"></a>Function: <em>void</em> <strong>camellia192_set_decrypt_key</strong> <em>(struct camellia192_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
1889 <dt><a name="index-camellia256_005fset_005fencrypt_005fkey"></a>Function: <em>void</em> <strong>camellia256_set_encrypt_key</strong> <em>(struct camellia256_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
1890 <dt><a name="index-camellia256_005fset_005fdecrypt_005fkey"></a>Function: <em>void</em> <strong>camellia256_set_decrypt_key</strong> <em>(struct camellia256_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
1891 <dt><a name="index-camellia_005fset_005fencrypt_005fkey"></a>Function: <em>void</em> <strong>camellia_set_encrypt_key</strong> <em>(struct camellia_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>key</var>)</em></dt>
1892 <dt><a name="index-camellia_005fset_005fdecrypt_005fkey"></a>Function: <em>void</em> <strong>camellia_set_decrypt_key</strong> <em>(struct camellia_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>key</var>)</em></dt>
1893 <dd><p>Initialize the cipher, for encryption or decryption, respectively.
1894 </p></dd></dl>
1895
1896 <dl>
1897 <dt><a name="index-camellia128_005finvert_005fkey"></a>Function: <em>void</em> <strong>camellia128_invert_key</strong> <em>(struct camellia128_ctx *<var>dst</var>, const struct camellia128_ctx *<var>src</var>)</em></dt>
1898 <dt><a name="index-camellia192_005finvert_005fkey"></a>Function: <em>void</em> <strong>camellia192_invert_key</strong> <em>(struct camellia192_ctx *<var>dst</var>, const struct camellia192_ctx *<var>src</var>)</em></dt>
1899 <dt><a name="index-camellia256_005finvert_005fkey"></a>Function: <em>void</em> <strong>camellia256_invert_key</strong> <em>(struct camellia256_ctx *<var>dst</var>, const struct camellia256_ctx *<var>src</var>)</em></dt>
1900 <dt><a name="index-camellia_005finvert_005fkey"></a>Function: <em>void</em> <strong>camellia_invert_key</strong> <em>(struct camellia_ctx *<var>dst</var>, const struct camellia_ctx *<var>src</var>)</em></dt>
1901 <dd><p>Given a context <var>src</var> initialized for encryption, initializes the
1902 context struct <var>dst</var> for decryption, using the same key. If the same
1903 context struct is passed for both <code>src</code> and <code>dst</code>, it is
1904 converted in place. These functions are mainly useful for applications
1905 which needs to both encrypt and decrypt using the <em>same</em> key.
1906 </p></dd></dl>
1907
1908 <dl>
1909 <dt><a name="index-camellia128_005fcrypt"></a>Function: <em>void</em> <strong>camellia128_crypt</strong> <em>(struct camellia128_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1910 <dt><a name="index-camellia192_005fcrypt"></a>Function: <em>void</em> <strong>camellia192_crypt</strong> <em>(struct camellia192_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1911 <dt><a name="index-camellia256_005fcrypt"></a>Function: <em>void</em> <strong>camellia256_crypt</strong> <em>(struct camellia256_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1912 <dt><a name="index-camellia_005fcrypt"></a>Function: <em>void</em> <strong>camellia_crypt</strong> <em>(struct camellia_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1913 <dd><p>The same function is used for both encryption and decryption.
1914 <var>length</var> must be an integral multiple of the block size. If it is
1915 more than one block, the data is processed in ECB mode. <code>src</code> and
1916 <code>dst</code> may be equal, but they must not overlap in any other way.
1917 </p></dd></dl>
1918
1919 <a name="CAST128"></a>
1920 <h4 class="subsection">6.2.6 CAST128</h4>
1921
1922 <p>CAST-128 is a block cipher, specified in <cite>RFC 2144</cite>. It uses a 64
1923 bit (8 octets) block size, and a variable key size of up to 128 bits.
1924 Nettle defines cast128 in <samp>&lt;nettle/cast128.h&gt;</samp>.
1925 </p>
1926 <dl>
1927 <dt><a name="index-struct-cast128_005fctx"></a>Context struct: <strong>struct cast128_ctx</strong></dt>
1928 </dl>
1929
1930 <dl>
1931 <dt><a name="index-CAST128_005fBLOCK_005fSIZE"></a>Constant: <strong>CAST128_BLOCK_SIZE</strong></dt>
1932 <dd><p>The CAST128 block-size, 8.
1933 </p></dd></dl>
1934
1935 <dl>
1936 <dt><a name="index-CAST128_005fMIN_005fKEY_005fSIZE"></a>Constant: <strong>CAST128_MIN_KEY_SIZE</strong></dt>
1937 <dd><p>Minimum CAST128 key size, 5.
1938 </p></dd></dl>
1939
1940 <dl>
1941 <dt><a name="index-CAST128_005fMAX_005fKEY_005fSIZE"></a>Constant: <strong>CAST128_MAX_KEY_SIZE</strong></dt>
1942 <dd><p>Maximum CAST128 key size, 16.
1943 </p></dd></dl>
1944
1945 <dl>
1946 <dt><a name="index-CAST128_005fKEY_005fSIZE"></a>Constant: <strong>CAST128_KEY_SIZE</strong></dt>
1947 <dd><p>Default CAST128 key size, 16.
1948 </p></dd></dl>
1949
1950 <dl>
1951 <dt><a name="index-cast128_005fset_005fkey"></a>Function: <em>void</em> <strong>cast128_set_key</strong> <em>(struct cast128_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>key</var>)</em></dt>
1952 <dd><p>Initialize the cipher. The same function is used for both encryption and
1953 decryption.
1954 </p></dd></dl>
1955
1956 <dl>
1957 <dt><a name="index-cast128_005fencrypt"></a>Function: <em>void</em> <strong>cast128_encrypt</strong> <em>(struct cast128_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1958 <dd><p>Encryption function. <var>length</var> must be an integral multiple of the
1959 block size. If it is more than one block, the data is processed in ECB
1960 mode. <code>src</code> and <code>dst</code> may be equal, but they must not overlap
1961 in any other way.
1962 </p></dd></dl>
1963
1964 <dl>
1965 <dt><a name="index-cast128_005fdecrypt"></a>Function: <em>void</em> <strong>cast128_decrypt</strong> <em>(struct cast128_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
1966 <dd><p>Analogous to <code>cast128_encrypt</code>
1967 </p></dd></dl>
1968
1969 <a name="ChaCha"></a>
1970 <h4 class="subsection">6.2.7 ChaCha</h4>
1971
1972 <p>ChaCha is a variant of the stream cipher Salsa20, also designed by D. J.
1973 Bernstein. For more information on Salsa20, see below. Nettle defines
1974 ChaCha in <samp>&lt;nettle/chacha.h&gt;</samp>.
1975 </p>
1976 <dl>
1977 <dt><a name="index-struct-chacha_005fctx"></a>Context struct: <strong>struct chacha_ctx</strong></dt>
1978 </dl>
1979
1980 <dl>
1981 <dt><a name="index-CHACHA_005fKEY_005fSIZE"></a>Constant: <strong>CHACHA_KEY_SIZE</strong></dt>
1982 <dd><p>ChaCha key size, 32.
1983 </p></dd></dl>
1984
1985 <dl>
1986 <dt><a name="index-CHACHA_005fBLOCK_005fSIZE"></a>Constant: <strong>CHACHA_BLOCK_SIZE</strong></dt>
1987 <dd><p>ChaCha block size, 64.
1988 </p></dd></dl>
1989
1990 <dl>
1991 <dt><a name="index-CHACHA_005fNONCE_005fSIZE"></a>Constant: <strong>CHACHA_NONCE_SIZE</strong></dt>
1992 <dd><p>Size of the nonce, 8.
1993 </p></dd></dl>
1994
1995 <dl>
1996 <dt><a name="index-chacha_005fset_005fkey"></a>Function: <em>void</em> <strong>chacha_set_key</strong> <em>(struct chacha_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
1997 <dd><p>Initialize the cipher. The same function is used for both encryption and
1998 decryption. Before using the cipher,
1999 you <em>must</em> also call <code>chacha_set_nonce</code>, see below.
2000 </p></dd></dl>
2001
2002 <dl>
2003 <dt><a name="index-chacha_005fset_005fnonce"></a>Function: <em>void</em> <strong>chacha_set_nonce</strong> <em>(struct chacha_ctx *<var>ctx</var>, const uint8_t *<var>nonce</var>)</em></dt>
2004 <dd><p>Sets the nonce. It is always of size <code>CHACHA_NONCE_SIZE</code>, 8
2005 octets. This function also initializes the block counter, setting it to
2006 zero.
2007 </p></dd></dl>
2008
2009 <dl>
2010 <dt><a name="index-chacha_005fcrypt"></a>Function: <em>void</em> <strong>chacha_crypt</strong> <em>(struct chacha_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2011 <dd><p>Encrypts or decrypts the data of a message, using ChaCha. When a
2012 message is encrypted using a sequence of calls to <code>chacha_crypt</code>,
2013 all but the last call <em>must</em> use a length that is a multiple of
2014 <code>CHACHA_BLOCK_SIZE</code>.
2015 </p></dd></dl>
2016
2017 <a name="DES"></a>
2018 <h4 class="subsection">6.2.8 DES</h4>
2019 <p>DES is the old Data Encryption Standard, specified by NIST. It uses a
2020 block size of 64 bits (8 octets), and a key size of 56 bits. However,
2021 the key bits are distributed over 8 octets, where the least significant
2022 bit of each octet may be used for parity. A common way to use DES is to
2023 generate 8 random octets in some way, then set the least significant bit
2024 of each octet to get odd parity, and initialize DES with the resulting
2025 key.
2026 </p>
2027 <p>The key size of DES is so small that keys can be found by brute force,
2028 using specialized hardware or lots of ordinary work stations in
2029 parallel. One shouldn&rsquo;t be using plain DES at all today, if one uses
2030 DES at all one should be using &ldquo;triple DES&rdquo;, see DES3 below.
2031 </p>
2032 <p>DES also has some weak keys. Nettle defines DES in <samp>&lt;nettle/des.h&gt;</samp>.
2033 </p>
2034 <dl>
2035 <dt><a name="index-struct-des_005fctx"></a>Context struct: <strong>struct des_ctx</strong></dt>
2036 </dl>
2037
2038 <dl>
2039 <dt><a name="index-DES_005fBLOCK_005fSIZE"></a>Constant: <strong>DES_BLOCK_SIZE</strong></dt>
2040 <dd><p>The DES block-size, 8.
2041 </p></dd></dl>
2042
2043 <dl>
2044 <dt><a name="index-DES_005fKEY_005fSIZE"></a>Constant: <strong>DES_KEY_SIZE</strong></dt>
2045 <dd><p>DES key size, 8.
2046 </p></dd></dl>
2047
2048 <dl>
2049 <dt><a name="index-des_005fset_005fkey"></a>Function: <em>int</em> <strong>des_set_key</strong> <em>(struct des_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
2050 <dd><p>Initialize the cipher. The same function is used for both encryption and
2051 decryption. Parity bits are ignored. Checks for weak keys, returning 1
2052 for good keys and 0 for weak keys. Applications that don&rsquo;t care about
2053 weak keys can ignore the return value.
2054 </p></dd></dl>
2055
2056 <dl>
2057 <dt><a name="index-des_005fencrypt"></a>Function: <em>void</em> <strong>des_encrypt</strong> <em>(struct des_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2058 <dd><p>Encryption function. <var>length</var> must be an integral multiple of the
2059 block size. If it is more than one block, the data is processed in ECB
2060 mode. <code>src</code> and <code>dst</code> may be equal, but they must not overlap
2061 in any other way.
2062 </p></dd></dl>
2063
2064 <dl>
2065 <dt><a name="index-des_005fdecrypt"></a>Function: <em>void</em> <strong>des_decrypt</strong> <em>(struct des_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2066 <dd><p>Analogous to <code>des_encrypt</code>
2067 </p></dd></dl>
2068
2069 <dl>
2070 <dt><a name="index-des_005fcheck_005fparity"></a>Function: <em>int</em> <strong>des_check_parity</strong> <em>(size_t <var>length</var>, const uint8_t *<var>key</var>);</em></dt>
2071 <dd><p>Checks that the given key has correct, odd, parity. Returns 1 for
2072 correct parity, and 0 for bad parity.
2073 </p></dd></dl>
2074
2075 <dl>
2076 <dt><a name="index-des_005ffix_005fparity"></a>Function: <em>void</em> <strong>des_fix_parity</strong> <em>(size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2077 <dd><p>Adjusts the parity bits to match DES&rsquo;s requirements. You need this
2078 function if you have created a random-looking string by a key agreement
2079 protocol, and want to use it as a DES key. <var>dst</var> and <var>src</var> may
2080 be equal.
2081 </p></dd></dl>
2082
2083 <a name="DES3"></a>
2084 <h4 class="subsection">6.2.9 DES3</h4>
2085 <p>The inadequate key size of DES has already been mentioned. One way to
2086 increase the key size is to pipe together several DES boxes with
2087 independent keys. It turns out that using two DES ciphers is not as
2088 secure as one might think, even if the key size of the combination is a
2089 respectable 112 bits.
2090 </p>
2091 <p>The standard way to increase DES&rsquo;s key size is to use three DES boxes.
2092 The mode of operation is a little peculiar: the middle DES box is wired
2093 in the reverse direction. To encrypt a block with DES3, you encrypt it
2094 using the first 56 bits of the key, then <em>decrypt</em> it using the
2095 middle 56 bits of the key, and finally encrypt it again using the last
2096 56 bits of the key. This is known as &ldquo;ede&rdquo; triple-DES, for
2097 &ldquo;encrypt-decrypt-encrypt&rdquo;.
2098 </p>
2099 <p>The &ldquo;ede&rdquo; construction provides some backward compatibility, as you get
2100 plain single DES simply by feeding the same key to all three boxes. That
2101 should help keeping down the gate count, and the price, of hardware
2102 circuits implementing both plain DES and DES3.
2103 </p>
2104 <p>DES3 has a key size of 168 bits, but just like plain DES, useless parity
2105 bits are inserted, so that keys are represented as 24 octets (192 bits).
2106 As a 112 bit key is large enough to make brute force attacks
2107 impractical, some applications uses a &ldquo;two-key&rdquo; variant of triple-DES.
2108 In this mode, the same key bits are used for the first and the last DES
2109 box in the pipe, while the middle box is keyed independently. The
2110 two-key variant is believed to be secure, i.e. there are no known
2111 attacks significantly better than brute force.
2112 </p>
2113 <p>Naturally, it&rsquo;s simple to implement triple-DES on top of Nettle&rsquo;s DES
2114 functions. Nettle includes an implementation of three-key &ldquo;ede&rdquo;
2115 triple-DES, it is defined in the same place as plain DES,
2116 <samp>&lt;nettle/des.h&gt;</samp>.
2117 </p>
2118 <dl>
2119 <dt><a name="index-struct-des3_005fctx"></a>Context struct: <strong>struct des3_ctx</strong></dt>
2120 </dl>
2121
2122 <dl>
2123 <dt><a name="index-DES3_005fBLOCK_005fSIZE"></a>Constant: <strong>DES3_BLOCK_SIZE</strong></dt>
2124 <dd><p>The DES3 block-size is the same as DES_BLOCK_SIZE, 8.
2125 </p></dd></dl>
2126
2127 <dl>
2128 <dt><a name="index-DES3_005fKEY_005fSIZE"></a>Constant: <strong>DES3_KEY_SIZE</strong></dt>
2129 <dd><p>DES key size, 24.
2130 </p></dd></dl>
2131
2132 <dl>
2133 <dt><a name="index-des3_005fset_005fkey"></a>Function: <em>int</em> <strong>des3_set_key</strong> <em>(struct des3_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
2134 <dd><p>Initialize the cipher. The same function is used for both encryption and
2135 decryption. Parity bits are ignored. Checks for weak keys, returning 1
2136 if all three keys are good keys, and 0 if one or more key is weak.
2137 Applications that don&rsquo;t care about weak keys can ignore the return
2138 value.
2139 </p></dd></dl>
2140
2141 <p>For random-looking strings, you can use <code>des_fix_parity</code> to adjust
2142 the parity bits before calling <code>des3_set_key</code>.
2143 </p>
2144 <dl>
2145 <dt><a name="index-des3_005fencrypt"></a>Function: <em>void</em> <strong>des3_encrypt</strong> <em>(struct des3_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2146 <dd><p>Encryption function. <var>length</var> must be an integral multiple of the
2147 block size. If it is more than one block, the data is processed in ECB
2148 mode. <code>src</code> and <code>dst</code> may be equal, but they must not overlap
2149 in any other way.
2150 </p></dd></dl>
2151
2152 <dl>
2153 <dt><a name="index-des3_005fdecrypt"></a>Function: <em>void</em> <strong>des3_decrypt</strong> <em>(struct des3_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2154 <dd><p>Analogous to <code>des_encrypt</code>
2155 </p></dd></dl>
2156
2157 <a name="Salsa20"></a>
2158 <h4 class="subsection">6.2.10 Salsa20</h4>
2159 <p>Salsa20 is a fairly recent stream cipher designed by D. J. Bernstein. It
2160 is built on the observation that a cryptographic hash function can be
2161 used for encryption: Form the hash input from the secret key and a
2162 counter, xor the hash output and the first block of the plaintext, then
2163 increment the counter to process the next block (similar to CTR mode, see
2164 see <a href="#CTR">CTR</a>). Bernstein defined an encryption algorithm, Snuffle,
2165 in this way to ridicule United States export restrictions which treated hash
2166 functions as nice and harmless, but ciphers as dangerous munitions.
2167 </p>
2168 <p>Salsa20 uses the same idea, but with a new specialized hash function to
2169 mix key, block counter, and a couple of constants. It&rsquo;s also designed
2170 for speed; on x86_64, it is currently the fastest cipher offered by
2171 nettle. It uses a block size of 512 bits (64 octets) and there are two
2172 specified key sizes, 128 and 256 bits (16 and 32 octets).
2173 </p>
2174 <p><strong>Caution:</strong> The hash function used in Salsa20 is <em>not</em>
2175 directly applicable for use as a general hash function. It&rsquo;s <em>not</em>
2176 collision resistant if arbitrary inputs are allowed, and furthermore,
2177 the input and output is of fixed size.
2178 </p>
2179 <p>When using Salsa20 to process a message, one specifies both a key and a
2180 <em>nonce</em>, the latter playing a similar rôle to the initialization
2181 vector (<acronym>IV</acronym>) used with <acronym>CBC</acronym> or <acronym>CTR</acronym> mode. One
2182 can use the same key for several messages, provided one uses a unique
2183 random <acronym>iv</acronym> for each message. The <acronym>iv</acronym> is 64 bits (8
2184 octets). The block counter is initialized to zero for each message, and
2185 is also 64 bits (8 octets). Nettle defines Salsa20 in
2186 <samp>&lt;nettle/salsa20.h&gt;</samp>.
2187 </p>
2188 <dl>
2189 <dt><a name="index-struct-salsa20_005fctx"></a>Context struct: <strong>struct salsa20_ctx</strong></dt>
2190 </dl>
2191
2192 <dl>
2193 <dt><a name="index-SALSA20_005f128_005fKEY_005fSIZE"></a>Constant: <strong>SALSA20_128_KEY_SIZE</strong></dt>
2194 <dt><a name="index-SALSA20_005f256_005fKEY_005fSIZE"></a>Constant: <strong>SALSA20_256_KEY_SIZE</strong></dt>
2195 <dd><p>The two supported key sizes, 16 and 32 octets.
2196 </p></dd></dl>
2197
2198 <dl>
2199 <dt><a name="index-SALSA20_005fKEY_005fSIZE"></a>Constant: <strong>SALSA20_KEY_SIZE</strong></dt>
2200 <dd><p>Recommended key size, 32.
2201 </p></dd></dl>
2202
2203 <dl>
2204 <dt><a name="index-SALSA20_005fBLOCK_005fSIZE"></a>Constant: <strong>SALSA20_BLOCK_SIZE</strong></dt>
2205 <dd><p>Salsa20 block size, 64.
2206 </p></dd></dl>
2207
2208 <dl>
2209 <dt><a name="index-SALSA20_005fNONCE_005fSIZE"></a>Constant: <strong>SALSA20_NONCE_SIZE</strong></dt>
2210 <dd><p>Size of the nonce, 8.
2211 </p></dd></dl>
2212
2213 <dl>
2214 <dt><a name="index-salsa20_005f128_005fset_005fkey"></a>Function: <em>void</em> <strong>salsa20_128_set_key</strong> <em>(struct salsa20_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
2215 <dt><a name="index-salsa20_005f256_005fset_005fkey"></a>Function: <em>void</em> <strong>salsa20_256_set_key</strong> <em>(struct salsa20_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
2216 <dt><a name="index-salsa20_005fset_005fkey"></a>Function: <em>void</em> <strong>salsa20_set_key</strong> <em>(struct salsa20_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>key</var>)</em></dt>
2217 <dd><p>Initialize the cipher. The same function is used for both encryption and
2218 decryption. <code>salsa20_128_set_key</code> and <code>salsa20_128_set_key</code>
2219 use a fix key size each, 16 and 32 octets, respectively. The function
2220 <code>salsa20_set_key</code> is provided for backwards compatibility, and the
2221 <var>length</var> argument must be either 16 or 32. Before using the cipher,
2222 you <em>must</em> also call <code>salsa20_set_nonce</code>, see below.
2223 </p></dd></dl>
2224
2225 <dl>
2226 <dt><a name="index-salsa20_005fset_005fnonce"></a>Function: <em>void</em> <strong>salsa20_set_nonce</strong> <em>(struct salsa20_ctx *<var>ctx</var>, const uint8_t *<var>nonce</var>)</em></dt>
2227 <dd><p>Sets the nonce. It is always of size <code>SALSA20_NONCE_SIZE</code>, 8
2228 octets. This function also initializes the block counter, setting it to
2229 zero.
2230 </p></dd></dl>
2231
2232 <dl>
2233 <dt><a name="index-salsa20_005fcrypt"></a>Function: <em>void</em> <strong>salsa20_crypt</strong> <em>(struct salsa20_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2234 <dd><p>Encrypts or decrypts the data of a message, using salsa20. When a
2235 message is encrypted using a sequence of calls to <code>salsa20_crypt</code>,
2236 all but the last call <em>must</em> use a length that is a multiple of
2237 <code>SALSA20_BLOCK_SIZE</code>.
2238 </p></dd></dl>
2239
2240 <p>The full salsa20 cipher uses 20 rounds of mixing. Variants of Salsa20
2241 with fewer rounds are possible, and the 12-round variant is specified by
2242 eSTREAM, see <a href="http://www.ecrypt.eu.org/stream/finallist.html">http://www.ecrypt.eu.org/stream/finallist.html</a>.
2243 Nettle calls this variant <code>salsa20r12</code>. It uses the same context
2244 struct and key setup as the full salsa20 cipher, but a separate function
2245 for encryption and decryption.
2246 </p>
2247 <dl>
2248 <dt><a name="index-salsa20r12_005fcrypt"></a>Function: <em>void</em> <strong>salsa20r12_crypt</strong> <em>(struct salsa20_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2249 <dd><p>Encrypts or decrypts the data of a message, using salsa20 reduced to 12
2250 rounds.
2251 </p></dd></dl>
2252
2253 <a name="SERPENT"></a>
2254 <h4 class="subsection">6.2.11 SERPENT</h4>
2255 <p>SERPENT is one of the AES finalists, designed by Ross Anderson, Eli
2256 Biham and Lars Knudsen. Thus, the interface and properties are similar
2257 to AES&rsquo;. One peculiarity is that it is quite pointless to use it with
2258 anything but the maximum key size, smaller keys are just padded to
2259 larger ones. Nettle defines SERPENT in <samp>&lt;nettle/serpent.h&gt;</samp>.
2260 </p>
2261 <dl>
2262 <dt><a name="index-struct-serpent_005fctx"></a>Context struct: <strong>struct serpent_ctx</strong></dt>
2263 </dl>
2264
2265 <dl>
2266 <dt><a name="index-SERPENT_005fBLOCK_005fSIZE"></a>Constant: <strong>SERPENT_BLOCK_SIZE</strong></dt>
2267 <dd><p>The SERPENT block-size, 16.
2268 </p></dd></dl>
2269
2270 <dl>
2271 <dt><a name="index-SERPENT_005fMIN_005fKEY_005fSIZE"></a>Constant: <strong>SERPENT_MIN_KEY_SIZE</strong></dt>
2272 <dd><p>Minimum SERPENT key size, 16.
2273 </p></dd></dl>
2274
2275 <dl>
2276 <dt><a name="index-SERPENT_005fMAX_005fKEY_005fSIZE"></a>Constant: <strong>SERPENT_MAX_KEY_SIZE</strong></dt>
2277 <dd><p>Maximum SERPENT key size, 32.
2278 </p></dd></dl>
2279
2280 <dl>
2281 <dt><a name="index-SERPENT_005fKEY_005fSIZE"></a>Constant: <strong>SERPENT_KEY_SIZE</strong></dt>
2282 <dd><p>Default SERPENT key size, 32.
2283 </p></dd></dl>
2284
2285 <dl>
2286 <dt><a name="index-serpent_005fset_005fkey"></a>Function: <em>void</em> <strong>serpent_set_key</strong> <em>(struct serpent_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>key</var>)</em></dt>
2287 <dd><p>Initialize the cipher. The same function is used for both encryption and
2288 decryption.
2289 </p></dd></dl>
2290
2291 <dl>
2292 <dt><a name="index-serpent_005fencrypt"></a>Function: <em>void</em> <strong>serpent_encrypt</strong> <em>(struct serpent_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2293 <dd><p>Encryption function. <var>length</var> must be an integral multiple of the
2294 block size. If it is more than one block, the data is processed in ECB
2295 mode. <code>src</code> and <code>dst</code> may be equal, but they must not overlap
2296 in any other way.
2297 </p></dd></dl>
2298
2299 <dl>
2300 <dt><a name="index-serpent_005fdecrypt"></a>Function: <em>void</em> <strong>serpent_decrypt</strong> <em>(struct serpent_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2301 <dd><p>Analogous to <code>serpent_encrypt</code>
2302 </p></dd></dl>
2303
2304
2305 <a name="TWOFISH"></a>
2306 <h4 class="subsection">6.2.12 TWOFISH</h4>
2307 <p>Another AES finalist, this one designed by Bruce Schneier and others.
2308 Nettle defines it in <samp>&lt;nettle/twofish.h&gt;</samp>.
2309 </p>
2310 <dl>
2311 <dt><a name="index-struct-twofish_005fctx"></a>Context struct: <strong>struct twofish_ctx</strong></dt>
2312 </dl>
2313
2314 <dl>
2315 <dt><a name="index-TWOFISH_005fBLOCK_005fSIZE"></a>Constant: <strong>TWOFISH_BLOCK_SIZE</strong></dt>
2316 <dd><p>The TWOFISH block-size, 16.
2317 </p></dd></dl>
2318
2319 <dl>
2320 <dt><a name="index-TWOFISH_005fMIN_005fKEY_005fSIZE"></a>Constant: <strong>TWOFISH_MIN_KEY_SIZE</strong></dt>
2321 <dd><p>Minimum TWOFISH key size, 16.
2322 </p></dd></dl>
2323
2324 <dl>
2325 <dt><a name="index-TWOFISH_005fMAX_005fKEY_005fSIZE"></a>Constant: <strong>TWOFISH_MAX_KEY_SIZE</strong></dt>
2326 <dd><p>Maximum TWOFISH key size, 32.
2327 </p></dd></dl>
2328
2329 <dl>
2330 <dt><a name="index-TWOFISH_005fKEY_005fSIZE"></a>Constant: <strong>TWOFISH_KEY_SIZE</strong></dt>
2331 <dd><p>Default TWOFISH key size, 32.
2332 </p></dd></dl>
2333
2334 <dl>
2335 <dt><a name="index-twofish_005fset_005fkey"></a>Function: <em>void</em> <strong>twofish_set_key</strong> <em>(struct twofish_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>key</var>)</em></dt>
2336 <dd><p>Initialize the cipher. The same function is used for both encryption and
2337 decryption.
2338 </p></dd></dl>
2339
2340 <dl>
2341 <dt><a name="index-twofish_005fencrypt"></a>Function: <em>void</em> <strong>twofish_encrypt</strong> <em>(struct twofish_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2342 <dd><p>Encryption function. <var>length</var> must be an integral multiple of the
2343 block size. If it is more than one block, the data is processed in ECB
2344 mode. <code>src</code> and <code>dst</code> may be equal, but they must not overlap
2345 in any other way.
2346 </p></dd></dl>
2347
2348 <dl>
2349 <dt><a name="index-twofish_005fdecrypt"></a>Function: <em>void</em> <strong>twofish_decrypt</strong> <em>(struct twofish_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2350 <dd><p>Analogous to <code>twofish_encrypt</code>
2351 </p></dd></dl>
2352
2353 <a name="The-struct-nettle_005fcipher-abstraction"></a>
2354 <h4 class="subsection">6.2.13 The <code>struct nettle_cipher</code> abstraction</h4>
2355 <a name="index-nettle_005fcipher"></a>
2356 <a name="index-nettle_005fciphers"></a>
2357
2358 <p>Nettle includes a struct including information about some of the more
2359 regular cipher functions. It can be useful for applications that need a
2360 simple way to handle various algorithms. Nettle defines these structs in
2361 <samp>&lt;nettle/nettle-meta.h&gt;</samp>.
2362 </p>
2363 <dl>
2364 <dt><a name="index-struct-nettle_005fcipher"></a>Meta struct: <strong><code>struct nettle_cipher</code></strong> <em>name context_size block_size key_size set_encrypt_key set_decrypt_key encrypt decrypt</em></dt>
2365 <dd><p>The last four attributes are function pointers, of types
2366 <code>nettle_set_key_func *</code> and <code>nettle_cipher_func *</code>. The first
2367 argument to these functions is a <code>const void *</code> pointer to a context
2368 struct, which is of size <code>context_size</code>.
2369 </p></dd></dl>
2370
2371 <dl>
2372 <dt><a name="index-nettle_005faes128"></a>Constant Struct: <em>struct nettle_cipher</em> <strong>nettle_aes128</strong></dt>
2373 <dt><a name="index-nettle_005faes192"></a>Constant Struct: <em>struct nettle_cipher</em> <strong>nettle_aes192</strong></dt>
2374 <dt><a name="index-nettle_005faes256"></a>Constant Struct: <em>struct nettle_cipher</em> <strong>nettle_aes256</strong></dt>
2375 <dt><a name="index-nettle_005farctwo40"></a>Constant Struct: <em>struct nettle_cipher</em> <strong>nettle_arctwo40</strong></dt>
2376 <dt><a name="index-nettle_005farctwo64"></a>Constant Struct: <em>struct nettle_cipher</em> <strong>nettle_arctwo64</strong></dt>
2377 <dt><a name="index-nettle_005farctwo128"></a>Constant Struct: <em>struct nettle_cipher</em> <strong>nettle_arctwo128</strong></dt>
2378 <dt><a name="index-nettle_005farctwo_005fgutmann128"></a>Constant Struct: <em>struct nettle_cipher</em> <strong>nettle_arctwo_gutmann128</strong></dt>
2379 <dt><a name="index-nettle_005farcfour128"></a>Constant Struct: <em>struct nettle_cipher</em> <strong>nettle_arcfour128</strong></dt>
2380 <dt><a name="index-nettle_005fcamellia128"></a>Constant Struct: <em>struct nettle_cipher</em> <strong>nettle_camellia128</strong></dt>
2381 <dt><a name="index-nettle_005fcamellia192"></a>Constant Struct: <em>struct nettle_cipher</em> <strong>nettle_camellia192</strong></dt>
2382 <dt><a name="index-nettle_005fcamellia256"></a>Constant Struct: <em>struct nettle_cipher</em> <strong>nettle_camellia256</strong></dt>
2383 <dt><a name="index-nettle_005fcast128"></a>Constant Struct: <em>struct nettle_cipher</em> <strong>nettle_cast128</strong></dt>
2384 <dt><a name="index-nettle_005fserpent128"></a>Constant Struct: <em>struct nettle_cipher</em> <strong>nettle_serpent128</strong></dt>
2385 <dt><a name="index-nettle_005fserpent192"></a>Constant Struct: <em>struct nettle_cipher</em> <strong>nettle_serpent192</strong></dt>
2386 <dt><a name="index-nettle_005fserpent256"></a>Constant Struct: <em>struct nettle_cipher</em> <strong>nettle_serpent256</strong></dt>
2387 <dt><a name="index-nettle_005ftwofish128"></a>Constant Struct: <em>struct nettle_cipher</em> <strong>nettle_twofish128</strong></dt>
2388 <dt><a name="index-nettle_005ftwofish192"></a>Constant Struct: <em>struct nettle_cipher</em> <strong>nettle_twofish192</strong></dt>
2389 <dt><a name="index-nettle_005ftwofish256"></a>Constant Struct: <em>struct nettle_cipher</em> <strong>nettle_twofish256</strong></dt>
2390 <dd><p>Nettle includes such structs for all the <em>regular</em> ciphers, i.e.
2391 ones without weak keys or other oddities.
2392 </p></dd></dl>
2393
2394 <p>Nettle also exports a list of all these ciphers without weak keys or
2395 other oddities.
2396 </p>
2397 <dl>
2398 <dt><a name="index-nettle_005fciphers-1"></a>Constant Array: <em>struct nettle_cipher **</em> <strong>nettle_ciphers</strong></dt>
2399 <dd><p>This list can be used to dynamically enumerate or search the supported
2400 algorithms. NULL-terminated.
2401 </p></dd></dl>
2402
2403 <hr>
2404 <a name="Cipher-modes"></a>
2405 <div class="header">
2406 <p>
2407 Next: <a href="#Authenticated-encryption" accesskey="n" rel="next">Authenticated encryption</a>, Previous: <a href="#Cipher-functions" accesskey="p" rel="prev">Cipher functions</a>, Up: <a href="#Reference" accesskey="u" rel="up">Reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
2408 </div>
2409 <a name="Cipher-modes-1"></a>
2410 <h3 class="section">6.3 Cipher modes</h3>
2411
2412 <p>Cipher modes of operation specifies the procedure to use when encrypting
2413 a message that is larger than the cipher&rsquo;s block size. As explained in
2414 See <a href="#Cipher-functions">Cipher functions</a>, splitting the message into blocks and
2415 processing them independently with the block cipher (Electronic Code
2416 Book mode, <acronym>ECB</acronym>), leaks information.
2417 </p>
2418 <p>Besides <acronym>ECB</acronym>, Nettle provides a two other modes of operation:
2419 Cipher Block Chaining (<acronym>CBC</acronym>), Counter mode (<acronym>CTR</acronym>), and
2420 a couple of <acronym>AEAD</acronym> modes (see <a href="#Authenticated-encryption">Authenticated encryption</a>).
2421 <acronym>CBC</acronym> is widely used, but there are a few subtle issues of
2422 information leakage, see, e.g.,
2423 <a href="http://www.kb.cert.org/vuls/id/958563"><acronym>SSH</acronym> <acronym>CBC</acronym>
2424 vulnerability</a>. Today, <acronym>CTR</acronym> is usually preferred over <acronym>CBC</acronym>.
2425 </p>
2426 <p>Modes like <acronym>CBC</acronym> and <acronym>CTR</acronym> provide <em>no</em> message
2427 authentication, and should always be used together with a <acronym>MAC</acronym>
2428 (see <a href="#Keyed-hash-functions">Keyed hash functions</a>) or signature to authenticate the message.
2429 </p>
2430 <table class="menu" border="0" cellspacing="0">
2431 <tr><td align="left" valign="top">&bull; <a href="#CBC" accesskey="1">CBC</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2432 </td></tr>
2433 <tr><td align="left" valign="top">&bull; <a href="#CTR" accesskey="2">CTR</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2434 </td></tr>
2435 </table>
2436
2437 <hr>
2438 <a name="CBC"></a>
2439 <div class="header">
2440 <p>
2441 Next: <a href="#CTR" accesskey="n" rel="next">CTR</a>, Previous: <a href="#Cipher-modes" accesskey="p" rel="prev">Cipher modes</a>, Up: <a href="#Cipher-modes" accesskey="u" rel="up">Cipher modes</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
2442 </div>
2443 <a name="Cipher-Block-Chaining"></a>
2444 <h4 class="subsection">6.3.1 Cipher Block Chaining</h4>
2445
2446 <a name="index-Cipher-Block-Chaining"></a>
2447 <a name="index-CBC-Mode"></a>
2448
2449 <p>When using <acronym>CBC</acronym> mode, plaintext blocks are not encrypted
2450 independently of each other, like in Electronic Cook Book mode. Instead,
2451 when encrypting a block in <acronym>CBC</acronym> mode, the previous ciphertext
2452 block is XORed with the plaintext before it is fed to the block cipher.
2453 When encrypting the first block, a random block called an <em>IV</em>, or
2454 Initialization Vector, is used as the &ldquo;previous ciphertext block&rdquo;. The
2455 IV should be chosen randomly, but it need not be kept secret, and can
2456 even be transmitted in the clear together with the encrypted data.
2457 </p>
2458 <p>In symbols, if <code>E_k</code> is the encryption function of a block cipher,
2459 and <code>IV</code> is the initialization vector, then <code>n</code> plaintext blocks
2460 <code>M_1</code>,&hellip; <code>M_n</code> are transformed into <code>n</code> ciphertext blocks
2461 <code>C_1</code>,&hellip; <code>C_n</code> as follows:
2462 </p>
2463 <div class="example">
2464 <pre class="example">C_1 = E_k(IV  XOR M_1)
2465 C_2 = E_k(C_1 XOR M_2)
2466
2467 &hellip;
2468
2469 C_n = E_k(C_(n-1) XOR M_n)
2470 </pre></div>
2471
2472 <p>Nettle&rsquo;s includes two functions for applying a block cipher in Cipher
2473 Block Chaining (<acronym>CBC</acronym>) mode, one for encryption and one for
2474 decryption. These functions uses <code>void *</code> to pass cipher contexts
2475 around.
2476 </p>
2477 <dl>
2478 <dt><a name="index-cbc_005fencrypt"></a>Function: <em>void</em> <strong>cbc_encrypt</strong> <em>(const void *<var>ctx</var>, nettle_cipher_func *<var>f</var>, size_t <var>block_size</var>, uint8_t *<var>iv</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2479 <dt><a name="index-cbc_005fdecrypt"></a>Function: <em>void</em> <strong>cbc_decrypt</strong> <em>(const void *<var>ctx</var>, nettle_cipher_func *<var>f</var>, size_t <var>block_size</var>, uint8_t *<var>iv</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2480 <dd>
2481 <p>Applies the encryption or decryption function <var>f</var> in <acronym>CBC</acronym>
2482 mode. The final ciphertext block processed is copied into <var>iv</var>
2483 before returning, so that large message be processed be a sequence of
2484 calls to <code>cbc_encrypt</code>. The function <var>f</var> is of type
2485 </p>
2486 <p><code>void f (void *<var>ctx</var>, size_t <var>length</var>, uint8_t <var>dst</var>,
2487 const uint8_t *<var>src</var>)</code>,
2488 </p>
2489 <p>and the <code>cbc_encrypt</code> and <code>cbc_decrypt</code> functions pass their
2490 argument <var>ctx</var> on to <var>f</var>.
2491 </p></dd></dl>
2492
2493 <p>There are also some macros to help use these functions correctly.
2494 </p>
2495 <dl>
2496 <dt><a name="index-CBC_005fCTX"></a>Macro: <strong>CBC_CTX</strong> <em>(<var>context_type</var>, <var>block_size</var>)</em></dt>
2497 <dd><p>Expands to
2498 </p><div class="example">
2499 <pre class="example">{
2500    context_type ctx;
2501    uint8_t iv[block_size];
2502 }
2503 </pre></div>
2504 </dd></dl>
2505
2506 <p>It can be used to define a <acronym>CBC</acronym> context struct, either directly,
2507 </p>
2508 <div class="example">
2509 <pre class="example">struct CBC_CTX(struct aes_ctx, AES_BLOCK_SIZE) ctx;
2510 </pre></div>
2511
2512 <p>or to give it a struct tag,
2513 </p>
2514 <div class="example">
2515 <pre class="example">struct aes_cbc_ctx CBC_CTX (struct aes_ctx, AES_BLOCK_SIZE);
2516 </pre></div>
2517
2518 <dl>
2519 <dt><a name="index-CBC_005fSET_005fIV"></a>Macro: <strong>CBC_SET_IV</strong> <em>(<var>ctx</var>, <var>iv</var>)</em></dt>
2520 <dd><p>First argument is a pointer to a context struct as defined by <code>CBC_CTX</code>,
2521 and the second is a pointer to an Initialization Vector (IV) that is
2522 copied into that context.
2523 </p></dd></dl>
2524
2525 <dl>
2526 <dt><a name="index-CBC_005fENCRYPT"></a>Macro: <strong>CBC_ENCRYPT</strong> <em>(<var>ctx</var>, <var>f</var>, <var>length</var>, <var>dst</var>, <var>src</var>)</em></dt>
2527 <dt><a name="index-CBC_005fDECRYPT"></a>Macro: <strong>CBC_DECRYPT</strong> <em>(<var>ctx</var>, <var>f</var>, <var>length</var>, <var>dst</var>, <var>src</var>)</em></dt>
2528 <dd><p>A simpler way to invoke <code>cbc_encrypt</code> and <code>cbc_decrypt</code>. The
2529 first argument is a pointer to a context struct as defined by
2530 <code>CBC_CTX</code>, and the second argument is an encryption or decryption
2531 function following Nettle&rsquo;s conventions. The last three arguments define
2532 the source and destination area for the operation.
2533 </p></dd></dl>
2534
2535 <p>These macros use some tricks to make the compiler display a warning if
2536 the types of <var>f</var> and <var>ctx</var> don&rsquo;t match, e.g. if you try to use
2537 an <code>struct aes_ctx</code> context with the <code>des_encrypt</code> function.
2538 </p>
2539 <hr>
2540 <a name="CTR"></a>
2541 <div class="header">
2542 <p>
2543 Previous: <a href="#CBC" accesskey="p" rel="prev">CBC</a>, Up: <a href="#Cipher-modes" accesskey="u" rel="up">Cipher modes</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
2544 </div>
2545 <a name="Counter-mode"></a>
2546 <h4 class="subsection">6.3.2 Counter mode</h4>
2547
2548 <a name="index-Counter-Mode"></a>
2549 <a name="index-CTR-Mode"></a>
2550
2551 <p>Counter mode (<acronym>CTR</acronym>) uses the block cipher as a keyed
2552 pseudo-random generator. The output of the generator is XORed with the
2553 data to be encrypted. It can be understood as a way to transform a block
2554 cipher to a stream cipher.
2555 </p>
2556 <p>The message is divided into <code>n</code> blocks <code>M_1</code>,&hellip;
2557 <code>M_n</code>, where <code>M_n</code> is of size <code>m</code> which may be smaller
2558 than the block size. Except for the last block, all the message blocks
2559 must be of size equal to the cipher&rsquo;s block size.
2560 </p>
2561 <p>If <code>E_k</code> is the encryption function of a block cipher, <code>IC</code> is
2562 the initial counter, then the <code>n</code> plaintext blocks are
2563 transformed into <code>n</code> ciphertext blocks <code>C_1</code>,&hellip;
2564 <code>C_n</code> as follows:
2565 </p>
2566 <div class="example">
2567 <pre class="example">C_1 = E_k(IC) XOR M_1
2568 C_2 = E_k(IC + 1) XOR M_2
2569
2570 &hellip;
2571
2572 C_(n-1) = E_k(IC + n - 2) XOR M_(n-1)
2573 C_n = E_k(IC + n - 1) [1..m] XOR M_n
2574 </pre></div>
2575
2576 <p>The <acronym>IC</acronym> is the initial value for the counter, it plays a
2577 similar rôle as the <acronym>IV</acronym> for <acronym>CBC</acronym>. When adding,
2578 <code>IC + x</code>, <acronym>IC</acronym> is interpreted as an integer, in network
2579 byte order. For the last block, <code>E_k(IC + n - 1) [1..m]</code> means that
2580 the cipher output is truncated to <code>m</code> bytes.
2581 </p>
2582 <dl>
2583 <dt><a name="index-ctr_005fcrypt"></a>Function: <em>void</em> <strong>ctr_crypt</strong> <em>(const void *<var>ctx</var>, nettle_cipher_func *<var>f</var>, size_t <var>block_size</var>, uint8_t *<var>ctr</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2584 <dd>
2585 <p>Applies the encryption function <var>f</var> in <acronym>CTR</acronym> mode. Note that
2586 for <acronym>CTR</acronym> mode, encryption and decryption is the same operation,
2587 and hence <var>f</var> should always be the encryption function for the
2588 underlying block cipher.
2589 </p>
2590 <p>When a message is encrypted using a sequence of calls to
2591 <code>ctr_crypt</code>, all but the last call <em>must</em> use a length that is
2592 a multiple of the block size.
2593 </p></dd></dl>
2594
2595 <p>Like for <acronym>CBC</acronym>, there are also a couple of helper macros.
2596 </p>
2597 <dl>
2598 <dt><a name="index-CTR_005fCTX"></a>Macro: <strong>CTR_CTX</strong> <em>(<var>context_type</var>, <var>block_size</var>)</em></dt>
2599 <dd><p>Expands to
2600 </p><div class="example">
2601 <pre class="example">{
2602    context_type ctx;
2603    uint8_t ctr[block_size];
2604 }
2605 </pre></div>
2606 </dd></dl>
2607
2608 <dl>
2609 <dt><a name="index-CTR_005fSET_005fCOUNTER"></a>Macro: <strong>CTR_SET_COUNTER</strong> <em>(<var>ctx</var>, <var>iv</var>)</em></dt>
2610 <dd><p>First argument is a pointer to a context struct as defined by
2611 <code>CTR_CTX</code>, and the second is a pointer to an initial counter that
2612 is copied into that context.
2613 </p></dd></dl>
2614
2615 <dl>
2616 <dt><a name="index-CTR_005fCRYPT"></a>Macro: <strong>CTR_CRYPT</strong> <em>(<var>ctx</var>, <var>f</var>, <var>length</var>, <var>dst</var>, <var>src</var>)</em></dt>
2617 <dd><p>A simpler way to invoke <code>ctr_crypt</code>. The first argument is a
2618 pointer to a context struct as defined by <code>CTR_CTX</code>, and the second
2619 argument is an encryption function following Nettle&rsquo;s conventions. The
2620 last three arguments define the source and destination area for the
2621 operation.
2622 </p></dd></dl>
2623
2624 <hr>
2625 <a name="Authenticated-encryption"></a>
2626 <div class="header">
2627 <p>
2628 Next: <a href="#Keyed-hash-functions" accesskey="n" rel="next">Keyed hash functions</a>, Previous: <a href="#Cipher-modes" accesskey="p" rel="prev">Cipher modes</a>, Up: <a href="#Reference" accesskey="u" rel="up">Reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
2629 </div>
2630
2631 <a name="Authenticated-encryption-with-associated-data"></a>
2632 <h3 class="section">6.4 Authenticated encryption with associated data</h3>
2633 <a name="index-AEAD"></a>
2634 <a name="index-Authenticated-encryption"></a>
2635
2636 <p>Since there are some subtle design choices to be made when combining a
2637 block cipher mode with out authentication with a <acronym>MAC</acronym>. In
2638 recent years, several constructions that combine encryption and
2639 authentication have been defined. These constructions typically also
2640 have an additional input, the &ldquo;associated data&rdquo;, which is
2641 authenticated but not included with the message. A simple example is an
2642 implicit message number which is available at both sender and receiver,
2643 and which needs authentication in order to detect deletions or replay of
2644 messages. This family of building blocks are therefore called
2645 <acronym>AEAD</acronym>, Authenticated encryption with associated data.
2646 </p>
2647 <p>The aim is to provide building blocks that it is easier for designers of
2648 protocols and applications to use correctly. There is also some
2649 potential for improved performance, if encryption and authentication can
2650 be done in a single step, although that potential is not realized for
2651 the constructions currently supported by Nettle.
2652 </p>
2653 <p>For encryption, the inputs are:
2654 </p>
2655 <ul>
2656 <li> The key, which can be used for many messages.
2657 </li><li> A nonce, which must be unique for each message using the same key.
2658 </li><li> Additional associated data to be authenticated, but not included in the
2659 message.
2660 </li><li> The cleartext message to be encrypted.
2661 </li></ul>
2662
2663 <p>The outputs are:
2664 </p>
2665 <ul>
2666 <li> The ciphertext, of the same size as the cleartext.
2667 </li><li> A digest or &ldquo;authentication tag&rdquo;.
2668 </li></ul>
2669
2670 <p>Decryption works the same, but with cleartext and ciphertext
2671 interchanged. All currently supported <acronym>AEAD</acronym> algorithms always
2672 use the encryption function of the underlying block cipher, for both
2673 encryption and decryption.
2674 </p>
2675 <p>Usually, the authentication tag should be appended at the end of the
2676 ciphertext, producing an encrypted message which is slightly longer than
2677 the cleartext. However, Nettle&rsquo;s low level <acronym>AEAD</acronym> functions
2678 produce the authentication tag as a separate output for both encryption
2679 and decryption.
2680 </p>
2681 <p>Both associated data and the message data (cleartext or ciphertext) can
2682 be processed incrementally. In general, all associated data must be
2683 processed before the message data, and all calls but the last one must
2684 use a length that is a multiple of the block size, although some
2685 <acronym>AEAD</acronym> may implement more liberal conventions. The <acronym>CCM</acronym>
2686 mode is a bit special in that it requires the message lengths up front,
2687 other <acronym>AEAD</acronym> constructions don&rsquo;t have this restriction.
2688 </p>
2689 <p>The supported <acronym>AEAD</acronym> constructions are Galois/Counter mode
2690 (<acronym>GCM</acronym>), <acronym>EAX</acronym>, ChaCha-Poly1305, and Counter with
2691 <acronym>CBC</acronym>-<acronym>MAC</acronym> (<acronym>CCM</acronym>). There are some weaknesses
2692 in <acronym>GCM</acronym> authentication, see
2693 <a href="http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/comments/CWC-GCM/Ferguson2.pdf">http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/comments/CWC-GCM/Ferguson2.pdf</a>.
2694 <acronym>CCM</acronym> and <acronym>EAX</acronym> use the same building blocks, but the
2695 <acronym>EAX</acronym> design is cleaner and avoids a couple of inconveniences of
2696 <acronym>CCM</acronym>. Therefore, <acronym>EAX</acronym> seems like a good conservative
2697 choice. The more recent ChaCha-Poly1305 may also be an attractive but
2698 more adventurous alternative, in particular if performance is important.
2699 </p>
2700 <table class="menu" border="0" cellspacing="0">
2701 <tr><td align="left" valign="top">&bull; <a href="#EAX" accesskey="1">EAX</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2702 </td></tr>
2703 <tr><td align="left" valign="top">&bull; <a href="#GCM" accesskey="2">GCM</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2704 </td></tr>
2705 <tr><td align="left" valign="top">&bull; <a href="#CCM" accesskey="3">CCM</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2706 </td></tr>
2707 <tr><td align="left" valign="top">&bull; <a href="#ChaCha_002dPoly1305" accesskey="4">ChaCha-Poly1305</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2708 </td></tr>
2709 <tr><td align="left" valign="top">&bull; <a href="#nettle_005faead-abstraction" accesskey="5">nettle_aead abstraction</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
2710 </td></tr>
2711 </table>
2712
2713 <hr>
2714 <a name="EAX"></a>
2715 <div class="header">
2716 <p>
2717 Next: <a href="#GCM" accesskey="n" rel="next">GCM</a>, Previous: <a href="#Authenticated-encryption" accesskey="p" rel="prev">Authenticated encryption</a>, Up: <a href="#Authenticated-encryption" accesskey="u" rel="up">Authenticated encryption</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
2718 </div>
2719 <a name="EAX-1"></a>
2720 <h4 class="subsection">6.4.1 EAX</h4>
2721
2722 <p>The <acronym>EAX</acronym> mode is an <acronym>AEAD</acronym> mode whichcombines
2723 <acronym>CTR</acronym> mode encryption, See <a href="#CTR">CTR</a>, with a message authentication
2724 based on <acronym>CBC</acronym>, See <a href="#CBC">CBC</a>. The implementation in Nettle is
2725 restricted to ciphers with a block size of 128 bits (16 octets).
2726 <acronym>EAX</acronym> was defined as a reaction to the <acronym>CCM</acronym> mode,
2727 See <a href="#CCM">CCM</a>, which uses the same primitives but has some undesirable and
2728 inelegant properties.
2729 </p>
2730 <p><acronym>EAX</acronym> supports arbitrary nonce size; it&rsquo;s even possible to use
2731 an empty nonce in case only a single message is encrypted for each key.
2732 </p>
2733 <p>Nettle&rsquo;s support for <acronym>EAX</acronym> consists of a low-level general
2734 interface, some convenience macros, and specific functions for
2735 <acronym>EAX</acronym> using <acronym>AES</acronym>-128 as the underlying cipher. These
2736 interfaces are defined in <samp>&lt;nettle/eax.h&gt;</samp>
2737 </p>
2738 <a name="General-EAX-interface"></a>
2739 <h4 class="subsubsection">6.4.1.1 General <acronym>EAX</acronym> interface</h4>
2740
2741 <dl>
2742 <dt><a name="index-struct-eax_005fkey"></a>Context struct: <strong>struct eax_key</strong></dt>
2743 <dd><p><acronym>EAX</acronym> state which depends only on the key, but not on the nonce
2744 or the message.
2745 </p></dd></dl>
2746
2747 <dl>
2748 <dt><a name="index-struct-eax_005fctx"></a>Context struct: <strong>struct eax_ctx</strong></dt>
2749 <dd><p>Holds state corresponding to a particular message.
2750 </p></dd></dl>
2751
2752 <dl>
2753 <dt><a name="index-EAX_005fBLOCK_005fSIZE"></a>Constant: <strong>EAX_BLOCK_SIZE</strong></dt>
2754 <dd><p><acronym>EAX</acronym>&rsquo;s block size, 16.
2755 </p></dd></dl>
2756
2757 <dl>
2758 <dt><a name="index-EAX_005fDIGEST_005fSIZE"></a>Constant: <strong>EAX_DIGEST_SIZE</strong></dt>
2759 <dd><p>Size of the <acronym>EAX</acronym> digest, also 16.
2760 </p></dd></dl>
2761
2762 <dl>
2763 <dt><a name="index-eax_005fset_005fkey"></a>Function: <em>void</em> <strong>eax_set_key</strong> <em>(struct eax_key *<var>key</var>, const void *<var>cipher</var>, nettle_cipher_func *<var>f</var>)</em></dt>
2764 <dd><p>Initializes <var>key</var>. <var>cipher</var> gives a context struct for the
2765 underlying cipher, which must have been previously initialized for
2766 encryption, and <var>f</var> is the encryption function.
2767 </p></dd></dl>
2768
2769 <dl>
2770 <dt><a name="index-eax_005fset_005fnonce"></a>Function: <em>void</em> <strong>eax_set_nonce</strong> <em>(struct eax_ctx *<var>eax</var>, const struct eax_key *<var>key</var>, const void *<var>cipher</var>, nettle_cipher_func *<var>f</var>, size_t <var>nonce_length</var>, const uint8_t *<var>nonce</var>)</em></dt>
2771 <dd><p>Initializes <var>ctx</var> for processing a new message, using the given
2772 nonce.
2773 </p></dd></dl>
2774
2775 <dl>
2776 <dt><a name="index-eax_005fupdate"></a>Function: <em>void</em> <strong>eax_update</strong> <em>(struct eax_ctx *<var>eax</var>, const struct eax_key *<var>key</var>, const void *<var>cipher</var>, nettle_cipher_func *<var>f</var>, size_t <var>data_length</var>, const uint8_t *<var>data</var>)</em></dt>
2777 <dd><p>Process associated data for authentication. All but the last call for
2778 each message <em>must</em> use a length that is a multiple of the block
2779 size. Unlike many other <acronym>AEAD</acronym> constructions, for <acronym>EAX</acronym>
2780 it&rsquo;s not necessary to complete the processing of all associated data
2781 before encrypting or decrypting the message data.
2782 </p></dd></dl>
2783
2784 <dl>
2785 <dt><a name="index-eax_005fencrypt"></a>Function: <em>void</em> <strong>eax_encrypt</strong> <em>(struct eax_ctx *<var>eax</var>, const struct eax_key *<var>key</var>, const void *<var>cipher</var>, nettle_cipher_func *<var>f</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2786 <dt><a name="index-eax_005fdecrypt"></a>Function: <em>void</em> <strong>eax_decrypt</strong> <em>(struct eax_ctx *<var>eax</var>, const struct eax_key *<var>key</var>, const void *<var>cipher</var>, nettle_cipher_func *<var>f</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2787 <dd><p>Encrypts or decrypts the data of a message. <var>cipher</var> is the context
2788 struct for the underlying cipher and <var>f</var> is the encryption function.
2789 All but the last call for each message <em>must</em> use a length that is
2790 a multiple of the block size.
2791 </p></dd></dl>
2792
2793 <dl>
2794 <dt><a name="index-eax_005fdigest"></a>Function: <em>void</em> <strong>eax_digest</strong> <em>(struct eax_ctx *<var>eax</var>, const struct eax_key *<var>key</var>, const void *<var>cipher</var>, nettle_cipher_func *<var>f</var>, size_t <var>length</var>, uint8_t *<var>digest</var>);</em></dt>
2795 <dd><p>Extracts the message digest (also known &ldquo;authentication tag&rdquo;). This is
2796 the final operation when processing a message. If <var>length</var> is
2797 smaller than <code>EAX_DIGEST_SIZE</code>, only the first <var>length</var> octets
2798 of the digest are written.
2799 </p></dd></dl>
2800
2801
2802 <a name="EAX-helper-macros"></a>
2803 <h4 class="subsubsection">6.4.1.2 <acronym>EAX</acronym> helper macros</h4>
2804
2805 <p>The following macros are defined.
2806 </p>
2807 <dl>
2808 <dt><a name="index-EAX_005fCTX"></a>Macro: <strong>EAX_CTX</strong> <em>(<var>context_type</var>)</em></dt>
2809 <dd><p>This defines an all-in-one context struct, including the context of the
2810 underlying cipher and all <acronym>EAX</acronym> state. It expands
2811 to
2812 </p><div class="example">
2813 <pre class="example">{
2814    struct eax_key key;
2815    struct eax_ctx eax;
2816    context_type cipher;
2817 }
2818 </pre></div>
2819 </dd></dl>
2820
2821 <p>For all these macros, <var>ctx</var>, is a context struct as defined by
2822 <code>EAX_CTX</code>, and <var>encrypt</var> is the encryption function of the
2823 underlying cipher.
2824 </p>
2825 <dl>
2826 <dt><a name="index-EAX_005fSET_005fKEY"></a>Macro: <strong>EAX_SET_KEY</strong> <em>(<var>ctx</var>, <var>set_key</var>, <var>encrypt</var>, <var>key</var>)</em></dt>
2827 <dd><p><var>set_key</var> is the function for setting the encryption key for the
2828 underlying cipher, and <var>key</var> is the key.
2829 </p></dd></dl>
2830
2831 <dl>
2832 <dt><a name="index-EAX_005fSET_005fNONCE"></a>Macro: <strong>EAX_SET_NONCE</strong> <em>(<var>ctx</var>, <var>encrypt</var>, <var>length</var>, <var>nonce</var>)</em></dt>
2833 <dd><p>Sets the nonce to be used for the message.
2834 </p></dd></dl>
2835
2836 <dl>
2837 <dt><a name="index-EAX_005fUPDATE"></a>Macro: <strong>EAX_UPDATE</strong> <em>(<var>ctx</var>, <var>encrypt</var>, <var>length</var>, <var>data</var>)</em></dt>
2838 <dd><p>Process associated data for authentication.
2839 </p></dd></dl>
2840
2841 <dl>
2842 <dt><a name="index-EAX_005fENCRYPT"></a>Macro: <strong>EAX_ENCRYPT</strong> <em>(<var>ctx</var>, <var>encrypt</var>, <var>length</var>, <var>dst</var>, <var>src</var>)</em></dt>
2843 <dt><a name="index-EAX_005fDECRYPT"></a>Macro: <strong>EAX_DECRYPT</strong> <em>(<var>ctx</var>, <var>encrypt</var>, <var>length</var>, <var>dst</var>, <var>src</var>)</em></dt>
2844 <dd><p>Process message data for encryption or decryption.
2845 </p></dd></dl>
2846
2847 <dl>
2848 <dt><a name="index-EAX_005fDIGEST"></a>Macro: <strong>EAX_DIGEST</strong> <em>(<var>ctx</var>, <var>encrypt</var>, <var>length</var>, <var>digest</var>)</em></dt>
2849 <dd><p>Extract te authentication tag for the message.
2850 </p></dd></dl>
2851
2852
2853 <a name="EAX_002dAES128-interface"></a>
2854 <h4 class="subsubsection">6.4.1.3 <acronym>EAX</acronym>-<acronym>AES</acronym>128 interface</h4>
2855
2856 <p>The following functions implement <acronym>EAX</acronym> using <acronym>AES</acronym>-128
2857 as the underlying cipher.
2858 </p>
2859 <dl>
2860 <dt><a name="index-struct-eax_005faes128_005fctx"></a>Context struct: <strong>struct eax_aes128_ctx</strong></dt>
2861 <dd><p>The context struct, defined using <code>EAX_CTX</code>.
2862 </p></dd></dl>
2863
2864 <dl>
2865 <dt><a name="index-eax_005faes128_005fset_005fkey"></a>Function: <em>void</em> <strong>eax_aes128_set_key</strong> <em>(struct eax_aes128_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
2866 <dd><p>Initializes <var>ctx</var> using the given key.
2867 </p></dd></dl>
2868
2869 <dl>
2870 <dt><a name="index-eax_005faes128_005fset_005fnonce"></a>Function: <em>void</em> <strong>eax_aes128_set_nonce</strong> <em>(struct eax_aes128_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>iv</var>)</em></dt>
2871 <dd><p>Initializes the per-message state, using the given nonce.
2872 </p></dd></dl>
2873
2874 <dl>
2875 <dt><a name="index-eax_005faes128_005fupdate"></a>Function: <em>void</em> <strong>eax_aes128_update</strong> <em>(struct eax_aes128_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
2876 <dd><p>Process associated data for authentication. All but the last call for
2877 each message <em>must</em> use a length that is a multiple of the block
2878 size.
2879 </p></dd></dl>
2880
2881 <dl>
2882 <dt><a name="index-eax_005faes128_005fencrypt"></a>Function: <em>void</em> <strong>eax_aes128_encrypt</strong> <em>(struct eax_aes128_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2883 <dt><a name="index-eax_005faes128_005fdecrypt"></a>Function: <em>void</em> <strong>eax_aes128_decrypt</strong> <em>(struct eax_aes128_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2884 <dd><p>Encrypts or decrypts the data of a message. All but the last call for
2885 each message <em>must</em> use a length that is a multiple of the block
2886 size.
2887 </p></dd></dl>
2888
2889 <dl>
2890 <dt><a name="index-eax_005faes128_005fdigest"></a>Function: <em>void</em> <strong>eax_aes128_digest</strong> <em>(struct eax_aes128_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>);</em></dt>
2891 <dd><p>Extracts the message digest (also known &ldquo;authentication tag&rdquo;). This is
2892 the final operation when processing a message. If <var>length</var> is
2893 smaller than <code>EAX_DIGEST_SIZE</code>, only the first <var>length</var> octets
2894 of the digest are written.
2895 </p></dd></dl>
2896
2897 <hr>
2898 <a name="GCM"></a>
2899 <div class="header">
2900 <p>
2901 Next: <a href="#CCM" accesskey="n" rel="next">CCM</a>, Previous: <a href="#EAX" accesskey="p" rel="prev">EAX</a>, Up: <a href="#Authenticated-encryption" accesskey="u" rel="up">Authenticated encryption</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
2902 </div>
2903 <a name="Galois-counter-mode"></a>
2904 <h4 class="subsection">6.4.2 Galois counter mode</h4>
2905
2906 <a name="index-Galois-Counter-Mode"></a>
2907 <a name="index-GCM"></a>
2908
2909 <p>Galois counter mode is an <acronym>AEAD</acronym> constructions combining counter
2910 mode with message authentication based on universal hashing. The main
2911 objective of the design is to provide high performance for hardware
2912 implementations, where other popular <acronym>MAC</acronym> algorithms
2913 (see <a href="#Keyed-hash-functions">Keyed hash functions</a>) become a bottleneck for high-speed
2914 hardware implementations. It was proposed by David A. McGrew and John
2915 Viega in 2005, and recommended by NIST in 2007,
2916 <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
2917 cipher which must have a block size of 128 bits.
2918 </p>
2919 <p>The authentication in <acronym>GCM</acronym> has some known weaknesses, see
2920 <a href="http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/comments/CWC-GCM/Ferguson2.pdf">http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/comments/CWC-GCM/Ferguson2.pdf</a>.
2921 In particular, don&rsquo;t use <acronym>GCM</acronym> with short authentication tags.
2922 </p>
2923 <p>Nettle&rsquo;s support for <acronym>GCM</acronym> consists of a low-level general
2924 interface, some convenience macros, and specific functions for
2925 <acronym>GCM</acronym> using <acronym>AES</acronym> or Camellia as the underlying cipher.
2926 These interfaces are defined in <samp>&lt;nettle/gcm.h&gt;</samp>
2927 </p>
2928 <a name="General-GCM-interface"></a>
2929 <h4 class="subsubsection">6.4.2.1 General <acronym>GCM</acronym> interface</h4>
2930
2931 <dl>
2932 <dt><a name="index-struct-gcm_005fkey"></a>Context struct: <strong>struct gcm_key</strong></dt>
2933 <dd><p>Message independent hash sub-key, and related tables.
2934 </p></dd></dl>
2935
2936 <dl>
2937 <dt><a name="index-struct-gcm_005fctx"></a>Context struct: <strong>struct gcm_ctx</strong></dt>
2938 <dd><p>Holds state corresponding to a particular message.
2939 </p></dd></dl>
2940
2941 <dl>
2942 <dt><a name="index-GCM_005fBLOCK_005fSIZE"></a>Constant: <strong>GCM_BLOCK_SIZE</strong></dt>
2943 <dd><p><acronym>GCM</acronym>&rsquo;s block size, 16.
2944 </p></dd></dl>
2945
2946 <dl>
2947 <dt><a name="index-GCM_005fDIGEST_005fSIZE"></a>Constant: <strong>GCM_DIGEST_SIZE</strong></dt>
2948 <dd><p>Size of the <acronym>GCM</acronym> digest, also 16.
2949 </p></dd></dl>
2950
2951 <dl>
2952 <dt><a name="index-GCM_005fIV_005fSIZE"></a>Constant: <strong>GCM_IV_SIZE</strong></dt>
2953 <dd><p>Recommended size of the <acronym>IV</acronym>, 12. Arbitrary sizes are allowed.
2954 </p></dd></dl>
2955
2956 <dl>
2957 <dt><a name="index-gcm_005fset_005fkey"></a>Function: <em>void</em> <strong>gcm_set_key</strong> <em>(struct gcm_key *<var>key</var>, const void *<var>cipher</var>, nettle_cipher_func *<var>f</var>)</em></dt>
2958 <dd><p>Initializes <var>key</var>. <var>cipher</var> gives a context struct for the
2959 underlying cipher, which must have been previously initialized for
2960 encryption, and <var>f</var> is the encryption function.
2961 </p></dd></dl>
2962
2963 <dl>
2964 <dt><a name="index-gcm_005fset_005fiv"></a>Function: <em>void</em> <strong>gcm_set_iv</strong> <em>(struct gcm_ctx *<var>ctx</var>, const struct gcm_key *<var>key</var>, size_t <var>length</var>, const uint8_t *<var>iv</var>)</em></dt>
2965 <dd><p>Initializes <var>ctx</var> using the given <acronym>IV</acronym>. The <var>key</var>
2966 argument is actually needed only if <var>length</var> differs from
2967 <code>GCM_IV_SIZE</code>.
2968 </p></dd></dl>
2969
2970 <dl>
2971 <dt><a name="index-gcm_005fupdate"></a>Function: <em>void</em> <strong>gcm_update</strong> <em>(struct gcm_ctx *<var>ctx</var>, const struct gcm_key *<var>key</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
2972 <dd><p>Provides associated data to be authenticated. If used, must be called
2973 before <code>gcm_encrypt</code> or <code>gcm_decrypt</code>. All but the last call
2974 for each message <em>must</em> use a length that is a multiple of the
2975 block size.
2976 </p></dd></dl>
2977
2978 <dl>
2979 <dt><a name="index-gcm_005fencrypt"></a>Function: <em>void</em> <strong>gcm_encrypt</strong> <em>(struct gcm_ctx *<var>ctx</var>, const struct gcm_key *<var>key</var>, const void *<var>cipher</var>, nettle_cipher_func *<var>f</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2980 <dt><a name="index-gcm_005fdecrypt"></a>Function: <em>void</em> <strong>gcm_decrypt</strong> <em>(struct gcm_ctx *<var>ctx</var>, const struct gcm_key *<var>key</var>, const void *<var>cipher</var>, nettle_cipher_func *<var>f</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
2981 <dd><p>Encrypts or decrypts the data of a message. <var>cipher</var> is the context
2982 struct for the underlying cipher and <var>f</var> is the encryption function.
2983 All but the last call for each message <em>must</em> use a length that is
2984 a multiple of the block size.
2985 </p></dd></dl>
2986
2987 <dl>
2988 <dt><a name="index-gcm_005fdigest"></a>Function: <em>void</em> <strong>gcm_digest</strong> <em>(struct gcm_ctx *<var>ctx</var>, const struct gcm_key *<var>key</var>, const void *<var>cipher</var>, nettle_cipher_func *<var>f</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
2989 <dd><p>Extracts the message digest (also known &ldquo;authentication tag&rdquo;). This is
2990 the final operation when processing a message. It&rsquo;s strongly recommended
2991 that <var>length</var> is <code>GCM_DIGEST_SIZE</code>, but if you provide a smaller
2992 value, only the first <var>length</var> octets of the digest are written.
2993 </p></dd></dl>
2994
2995 <p>To encrypt a message using <acronym>GCM</acronym>, first initialize a context for
2996 the underlying block cipher with a key to use for encryption. Then call
2997 the above functions in the following order: <code>gcm_set_key</code>,
2998 <code>gcm_set_iv</code>, <code>gcm_update</code>, <code>gcm_encrypt</code>,
2999 <code>gcm_digest</code>. The decryption procedure is analogous, just calling
3000 <code>gcm_decrypt</code> instead of <code>gcm_encrypt</code> (note that
3001 <acronym>GCM</acronym> decryption still uses the encryption function of the
3002 underlying block cipher). To process a new message, using the same key,
3003 call <code>gcm_set_iv</code> with a new <acronym>iv</acronym>.
3004 </p>
3005 <a name="GCM-helper-macros"></a>
3006 <h4 class="subsubsection">6.4.2.2 <acronym>GCM</acronym> helper macros</h4>
3007
3008 <p>The following macros are defined.
3009 </p>
3010 <dl>
3011 <dt><a name="index-GCM_005fCTX"></a>Macro: <strong>GCM_CTX</strong> <em>(<var>context_type</var>)</em></dt>
3012 <dd><p>This defines an all-in-one context struct, including the context of the
3013 underlying cipher, the hash sub-key, and the per-message state. It expands
3014 to
3015 </p><div class="example">
3016 <pre class="example">{
3017    struct gcm_key key;
3018    struct gcm_ctx gcm;
3019    context_type cipher;
3020 }
3021 </pre></div>
3022 </dd></dl>
3023
3024 <p>Example use:
3025 </p><div class="example">
3026 <pre class="example">struct gcm_aes128_ctx GCM_CTX(struct aes128_ctx);
3027 </pre></div>
3028
3029 <p>The following macros operate on context structs of this form.
3030 </p>
3031 <dl>
3032 <dt><a name="index-GCM_005fSET_005fKEY"></a>Macro: <strong>GCM_SET_KEY</strong> <em>(<var>ctx</var>, <var>set_key</var>, <var>encrypt</var>, <var>key</var>)</em></dt>
3033 <dd><p>First argument, <var>ctx</var>, is a context struct as defined
3034 by <code>GCM_CTX</code>. <var>set_key</var> and <var>encrypt</var> are functions for
3035 setting the encryption key and for encrypting data using the underlying
3036 cipher.
3037 </p></dd></dl>
3038
3039 <dl>
3040 <dt><a name="index-GCM_005fSET_005fIV"></a>Macro: <strong>GCM_SET_IV</strong> <em>(<var>ctx</var>, <var>length</var>, <var>data</var>)</em></dt>
3041 <dd><p>First argument is a context struct as defined by
3042 <code>GCM_CTX</code>. <var>length</var> and <var>data</var> give the initialization
3043 vector (<acronym>IV</acronym>).
3044 </p></dd></dl>
3045
3046 <dl>
3047 <dt><a name="index-GCM_005fUPDATE"></a>Macro: <strong>GCM_UPDATE</strong> <em>(<var>ctx</var>, <var>length</var>, <var>data</var>)</em></dt>
3048 <dd><p>Simpler way to call <code>gcm_update</code>. First argument is a context
3049 struct as defined by <code>GCM_CTX</code>
3050 </p></dd></dl>
3051
3052 <dl>
3053 <dt><a name="index-GCM_005fENCRYPT"></a>Macro: <strong>GCM_ENCRYPT</strong> <em>(<var>ctx</var>, <var>encrypt</var>, <var>length</var>, <var>dst</var>, <var>src</var>)</em></dt>
3054 <dt><a name="index-GCM_005fDECRYPT"></a>Macro: <strong>GCM_DECRYPT</strong> <em>(<var>ctx</var>, <var>encrypt</var>, <var>length</var>, <var>dst</var>, <var>src</var>)</em></dt>
3055 <dt><a name="index-GCM_005fDIGEST"></a>Macro: <strong>GCM_DIGEST</strong> <em>(<var>ctx</var>, <var>encrypt</var>, <var>length</var>, <var>digest</var>)</em></dt>
3056 <dd><p>Simpler way to call <code>gcm_encrypt</code>, <code>gcm_decrypt</code> or
3057 <code>gcm_digest</code>. First argument is a context struct as defined by
3058 <code>GCM_CTX</code>. Second argument, <var>encrypt</var>, is the encryption
3059 function of the underlying cipher.
3060 </p></dd></dl>
3061
3062 <a name="GCM_002dAES-interface"></a>
3063 <h4 class="subsubsection">6.4.2.3 <acronym>GCM</acronym>-<acronym>AES</acronym> interface</h4>
3064
3065 <p>The following functions implement the common case of <acronym>GCM</acronym> using
3066 <acronym>AES</acronym> as the underlying cipher. The variants with a specific
3067 <acronym>AES</acronym> flavor are recommended, while the fucntinos using
3068 <code>struct gcm_aes_ctx</code> are kept for compatibility with older versiosn
3069 of Nettle.
3070 </p>
3071 <dl>
3072 <dt><a name="index-struct-gcm_005faes128_005fctx"></a>Context struct: <strong>struct gcm_aes128_ctx</strong></dt>
3073 <dt><a name="index-struct-gcm_005faes192_005fctx"></a>Context struct: <strong>struct gcm_aes192_ctx</strong></dt>
3074 <dt><a name="index-struct-gcm_005faes256_005fctx"></a>Context struct: <strong>struct gcm_aes256_ctx</strong></dt>
3075 <dd><p>Context structs, defined using <code>GCM_CTX</code>.
3076 </p></dd></dl>
3077
3078 <dl>
3079 <dt><a name="index-struct-gcm_005faes_005fctx"></a>Context struct: <strong>struct gcm_aes_ctx</strong></dt>
3080 <dd><p>Alternative context struct, usign the old <acronym>AES</acronym> interface.
3081 </p></dd></dl>
3082
3083 <dl>
3084 <dt><a name="index-gcm_005faes128_005fset_005fkey"></a>Function: <em>void</em> <strong>gcm_aes128_set_key</strong> <em>(struct gcm_aes128_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
3085 <dt><a name="index-gcm_005faes192_005fset_005fkey"></a>Function: <em>void</em> <strong>gcm_aes192_set_key</strong> <em>(struct gcm_aes192_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
3086 <dt><a name="index-gcm_005faes256_005fset_005fkey"></a>Function: <em>void</em> <strong>gcm_aes256_set_key</strong> <em>(struct gcm_aes256_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
3087 <dd><p>Initializes <var>ctx</var> using the given key.
3088 </p></dd></dl>
3089
3090 <dl>
3091 <dt><a name="index-gcm_005faes_005fset_005fkey"></a>Function: <em>void</em> <strong>gcm_aes_set_key</strong> <em>(struct gcm_aes_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>key</var>)</em></dt>
3092 <dd><p>Corresponding function, using the old <acronym>AES</acronym> interface. All valid
3093 <acronym>AES</acronym> key sizes can be used.
3094 </p></dd></dl>
3095
3096 <dl>
3097 <dt><a name="index-gcm_005faes128_005fset_005fiv"></a>Function: <em>void</em> <strong>gcm_aes128_set_iv</strong> <em>(struct gcm_aes128_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>iv</var>)</em></dt>
3098 <dt><a name="index-gcm_005faes192_005fset_005fiv"></a>Function: <em>void</em> <strong>gcm_aes192_set_iv</strong> <em>(struct gcm_aes192_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>iv</var>)</em></dt>
3099 <dt><a name="index-gcm_005faes256_005fset_005fiv"></a>Function: <em>void</em> <strong>gcm_aes256_set_iv</strong> <em>(struct gcm_aes256_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>iv</var>)</em></dt>
3100 <dt><a name="index-gcm_005faes_005fset_005fiv"></a>Function: <em>void</em> <strong>gcm_aes_set_iv</strong> <em>(struct gcm_aes_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>iv</var>)</em></dt>
3101 <dd><p>Initializes the per-message state, using the given <acronym>IV</acronym>.
3102 </p></dd></dl>
3103
3104 <dl>
3105 <dt><a name="index-gcm_005faes128_005fupdate"></a>Function: <em>void</em> <strong>gcm_aes128_update</strong> <em>(struct gcm_aes128_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
3106 <dt><a name="index-gcm_005faes192_005fupdate"></a>Function: <em>void</em> <strong>gcm_aes192_update</strong> <em>(struct gcm_aes192_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
3107 <dt><a name="index-gcm_005faes256_005fupdate"></a>Function: <em>void</em> <strong>gcm_aes256_update</strong> <em>(struct gcm_aes256_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
3108 <dt><a name="index-gcm_005faes_005fupdate"></a>Function: <em>void</em> <strong>gcm_aes_update</strong> <em>(struct gcm_aes_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
3109 <dd><p>Provides associated data to be authenticated. If used, must be called
3110 before <code>gcm_aes_encrypt</code> or <code>gcm_aes_decrypt</code>. All but the
3111 last call for each message <em>must</em> use a length that is a multiple
3112 of the block size.
3113 </p></dd></dl>
3114
3115 <dl>
3116 <dt><a name="index-gcm_005faes128_005fencrypt"></a>Function: <em>void</em> <strong>gcm_aes128_encrypt</strong> <em>(struct gcm_aes128_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3117 <dt><a name="index-gcm_005faes192_005fencrypt"></a>Function: <em>void</em> <strong>gcm_aes192_encrypt</strong> <em>(struct gcm_aes192_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3118 <dt><a name="index-gcm_005faes256_005fencrypt"></a>Function: <em>void</em> <strong>gcm_aes256_encrypt</strong> <em>(struct gcm_aes256_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3119 <dt><a name="index-gcm_005faes_005fencrypt"></a>Function: <em>void</em> <strong>gcm_aes_encrypt</strong> <em>(struct gcm_aes_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3120 <dt><a name="index-gcm_005faes128_005fdecrypt"></a>Function: <em>void</em> <strong>gcm_aes128_decrypt</strong> <em>(struct gcm_aes128_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3121 <dt><a name="index-gcm_005faes192_005fdecrypt"></a>Function: <em>void</em> <strong>gcm_aes192_decrypt</strong> <em>(struct gcm_aes192_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3122 <dt><a name="index-gcm_005faes256_005fdecrypt"></a>Function: <em>void</em> <strong>gcm_aes256_decrypt</strong> <em>(struct gcm_aes256_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3123 <dt><a name="index-gcm_005faes_005fdecrypt"></a>Function: <em>void</em> <strong>gcm_aes_decrypt</strong> <em>(struct gcm_aes_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3124 <dd><p>Encrypts or decrypts the data of a message. All but the last call for
3125 each message <em>must</em> use a length that is a multiple of the block
3126 size.
3127 </p></dd></dl>
3128
3129 <dl>
3130 <dt><a name="index-gcm_005faes128_005fdigest"></a>Function: <em>void</em> <strong>gcm_aes128_digest</strong> <em>(struct gcm_aes128_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3131 <dt><a name="index-gcm_005faes192_005fdigest"></a>Function: <em>void</em> <strong>gcm_aes192_digest</strong> <em>(struct gcm_aes192_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3132 <dt><a name="index-gcm_005faes256_005fdigest"></a>Function: <em>void</em> <strong>gcm_aes256_digest</strong> <em>(struct gcm_aes256_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3133 <dt><a name="index-gcm_005faes_005fdigest"></a>Function: <em>void</em> <strong>gcm_aes_digest</strong> <em>(struct gcm_aes_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3134 <dd><p>Extracts the message digest (also known &ldquo;authentication tag&rdquo;). This is
3135 the final operation when processing a message. It&rsquo;s strongly recommended
3136 that <var>length</var> is <code>GCM_DIGEST_SIZE</code>, but if you provide a smaller
3137 value, only the first <var>length</var> octets of the digest are written.
3138 </p></dd></dl>
3139
3140 <a name="GCM_002dCamellia-interface"></a>
3141 <h4 class="subsubsection">6.4.2.4 <acronym>GCM</acronym>-Camellia interface</h4>
3142
3143 <p>The following functions implement the case of <acronym>GCM</acronym> using
3144 Camellia as the underlying cipher.
3145 </p>
3146 <dl>
3147 <dt><a name="index-struct-gcm_005fcamellia128_005fctx"></a>Context struct: <strong>struct gcm_camellia128_ctx</strong></dt>
3148 <dt><a name="index-struct-gcm_005fcamellia256_005fctx"></a>Context struct: <strong>struct gcm_camellia256_ctx</strong></dt>
3149 <dd><p>Context structs, defined using <code>GCM_CTX</code>.
3150 </p></dd></dl>
3151
3152 <dl>
3153 <dt><a name="index-gcm_005fcamellia128_005fset_005fkey"></a>Function: <em>void</em> <strong>gcm_camellia128_set_key</strong> <em>(struct gcm_camellia128_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
3154 <dt><a name="index-gcm_005fcamellia256_005fset_005fkey"></a>Function: <em>void</em> <strong>gcm_camellia256_set_key</strong> <em>(struct gcm_camellia256_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
3155 <dd><p>Initializes <var>ctx</var> using the given key.
3156 </p></dd></dl>
3157
3158 <dl>
3159 <dt><a name="index-gcm_005fcamellia128_005fset_005fiv"></a>Function: <em>void</em> <strong>gcm_camellia128_set_iv</strong> <em>(struct gcm_camellia128_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>iv</var>)</em></dt>
3160 <dt><a name="index-gcm_005fcamellia256_005fset_005fiv"></a>Function: <em>void</em> <strong>gcm_camellia256_set_iv</strong> <em>(struct gcm_camellia256_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>iv</var>)</em></dt>
3161 <dd><p>Initializes the per-message state, using the given <acronym>IV</acronym>.
3162 </p></dd></dl>
3163
3164 <dl>
3165 <dt><a name="index-gcm_005fcamellia128_005fupdate"></a>Function: <em>void</em> <strong>gcm_camellia128_update</strong> <em>(struct gcm_camellia128_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
3166 <dt><a name="index-gcm_005fcamellia256_005fupdate"></a>Function: <em>void</em> <strong>gcm_camellia256_update</strong> <em>(struct gcm_camellia256_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
3167 <dd><p>Provides associated data to be authenticated. If used, must be called
3168 before <code>gcm_camellia_encrypt</code> or <code>gcm_camellia_decrypt</code>. All but the
3169 last call for each message <em>must</em> use a length that is a multiple
3170 of the block size.
3171 </p></dd></dl>
3172
3173 <dl>
3174 <dt><a name="index-gcm_005fcamellia128_005fencrypt"></a>Function: <em>void</em> <strong>gcm_camellia128_encrypt</strong> <em>(struct gcm_camellia128_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3175 <dt><a name="index-gcm_005fcamellia256_005fencrypt"></a>Function: <em>void</em> <strong>gcm_camellia256_encrypt</strong> <em>(struct gcm_camellia256_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3176 <dt><a name="index-gcm_005fcamellia128_005fdecrypt"></a>Function: <em>void</em> <strong>gcm_camellia128_decrypt</strong> <em>(struct gcm_camellia128_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3177 <dt><a name="index-gcm_005fcamellia256_005fdecrypt"></a>Function: <em>void</em> <strong>gcm_camellia256_decrypt</strong> <em>(struct gcm_camellia256_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3178 <dd><p>Encrypts or decrypts the data of a message. All but the last call for
3179 each message <em>must</em> use a length that is a multiple of the block
3180 size.
3181 </p></dd></dl>
3182
3183 <dl>
3184 <dt><a name="index-gcm_005fcamellia128_005fdigest"></a>Function: <em>void</em> <strong>gcm_camellia128_digest</strong> <em>(struct gcm_camellia128_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3185 <dt><a name="index-gcm_005fcamellia192_005fdigest"></a>Function: <em>void</em> <strong>gcm_camellia192_digest</strong> <em>(struct gcm_camellia192_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3186 <dt><a name="index-gcm_005fcamellia256_005fdigest"></a>Function: <em>void</em> <strong>gcm_camellia256_digest</strong> <em>(struct gcm_camellia256_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3187 <dt><a name="index-gcm_005fcamellia_005fdigest"></a>Function: <em>void</em> <strong>gcm_camellia_digest</strong> <em>(struct gcm_camellia_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3188 <dd><p>Extracts the message digest (also known &ldquo;authentication tag&rdquo;). This is
3189 the final operation when processing a message. It&rsquo;s strongly recommended
3190 that <var>length</var> is <code>GCM_DIGEST_SIZE</code>, but if you provide a smaller
3191 value, only the first <var>length</var> octets of the digest are written.
3192 </p></dd></dl>
3193
3194 <hr>
3195 <a name="CCM"></a>
3196 <div class="header">
3197 <p>
3198 Next: <a href="#ChaCha_002dPoly1305" accesskey="n" rel="next">ChaCha-Poly1305</a>, Previous: <a href="#GCM" accesskey="p" rel="prev">GCM</a>, Up: <a href="#Authenticated-encryption" accesskey="u" rel="up">Authenticated encryption</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
3199 </div>
3200 <a name="Counter-with-CBC_002dMAC-mode"></a>
3201 <h4 class="subsection">6.4.3 Counter with CBC-MAC mode</h4>
3202
3203 <a name="index-Counter-with-CBC_002dMAC-Mode"></a>
3204 <a name="index-CCM-Mode"></a>
3205
3206 <p><acronym>CCM</acronym> mode is a combination of counter mode with message
3207 authentication based on cipher block chaining, the same building blocks
3208 as <acronym>EAX</acronym>, see <a href="#EAX">EAX</a>. It is constructed on top of a block cipher
3209 which must have a block size of 128 bits. <acronym>CCM</acronym> mode is
3210 recommended by NIST in
3211 <a href="http://csrc.nist.gov/publications/nistpubs/800-38C/SP800-38C_updated-July20_2007.pdf">NIST Special Publication 800-38C</a>. Nettle&rsquo;s support for CCM consists of
3212 a low-level general interface, a message encryption and authentication
3213 interface, and specific functions for CCM using AES as the underlying
3214 block cipher. These interfaces are defined in <samp>&lt;nettle/ccm.h&gt;</samp>.
3215 </p>
3216 <p>In <acronym>CCM</acronym>, the length of the message must be known before
3217 processing. The maximum message size depends on the size of the nonce,
3218 since the message size is encoded in a field which must fit in a single
3219 block, together with the nonce and a flag byte. E.g., with a nonce size
3220 of 12 octets, there are three octets left for encoding the message
3221 length, the maximum message length is <em>2^24 - 1</em> octets.
3222 </p>
3223 <p><acronym>CCM</acronym> mode encryption operates as follows:
3224 </p><ul>
3225 <li> The nonce and message length are concatenated to create
3226 <code>B_0 = flags | nonce | mlength</code>
3227
3228 </li><li> The authenticated data and plaintext is formatted into the string
3229 <code>B = L(adata) | adata | padding | plaintext | padding</code> with
3230 <code>padding</code> being the shortest string of zero bytes such that the
3231 length of the string is a multiple of the block size, and
3232 <code>L(adata)</code> is an encoding of the length of <code>adata</code>.
3233
3234 </li><li> The string <code>B</code> is separated into blocks <code>B_1</code> ...
3235 <code>B_n</code>
3236 </li><li> The authentication tag <code>T</code> is calculated as
3237 <code>T=0, for i=0 to n, do T = E_k(B_i XOR T)</code>
3238
3239 </li><li> An initial counter is then initialized from the nonce to create
3240 <code>IC = flags | nonce | padding</code>, where <code>padding</code> is the
3241 shortest string of zero bytes such that <code>IC</code> is exactly one block
3242 in length.
3243
3244 </li><li> The authentication tag is encrypted using using <acronym>CTR</acronym> mode:
3245 <code>MAC = E_k(IC) XOR T</code>
3246
3247 </li><li> The plaintext is then encrypted using <acronym>CTR</acronym> mode with an
3248 initial counter of <code>IC+1</code>.
3249 </li></ul>
3250
3251 <p><acronym>CCM</acronym> mode decryption operates similarly, except that the
3252 ciphertext and <acronym>MAC</acronym> are first decrypted using CTR mode to
3253 retreive the plaintext and authentication tag. The authentication tag
3254 can then be recalucated from the authenticated data and plantext, and
3255 compared to the value in the message to check for authenticity.
3256 </p>
3257 <a name="General-CCM-interface"></a>
3258 <h4 class="subsubsection">6.4.3.1 General <acronym>CCM</acronym> interface</h4>
3259
3260 <p>For all of the functions in the <acronym>CCM</acronym> interface, <var>cipher</var> is
3261 the context struct for the underlying cipher and <var>f</var> is the
3262 encryption function. The cipher&rsquo;s encryption key must be set before
3263 calling any of the <acronym>CCM</acronym> functions. The cipher&rsquo;s decryption
3264 function and key are never used.
3265 </p>
3266 <dl>
3267 <dt><a name="index-struct-ccm_005fctx"></a>Context struct: <strong>struct ccm_ctx</strong></dt>
3268 <dd><p>Holds state corresponding to a particular message.
3269 </p></dd></dl>
3270
3271 <dl>
3272 <dt><a name="index-CCM_005fBLOCK_005fSIZE"></a>Constant: <strong>CCM_BLOCK_SIZE</strong></dt>
3273 <dd><p><acronym>CCM</acronym>&rsquo;s block size, 16.
3274 </p></dd></dl>
3275
3276 <dl>
3277 <dt><a name="index-CCM_005fDIGEST_005fSIZE"></a>Constant: <strong>CCM_DIGEST_SIZE</strong></dt>
3278 <dd><p>Size of the <acronym>CCM</acronym> digest, 16.
3279 </p></dd></dl>
3280
3281 <dl>
3282 <dt><a name="index-CCM_005fMIN_005fNONCE_005fSIZE"></a>Constant: <strong>CCM_MIN_NONCE_SIZE</strong></dt>
3283 <dt><a name="index-CCM_005fMAX_005fNONCE_005fSIZE"></a>Constant: <strong>CCM_MAX_NONCE_SIZE</strong></dt>
3284 <dd><p>The the minimum and maximum sizes for an <acronym>CCM</acronym> nonce, 7 and 14,
3285 respectively.
3286 </p></dd></dl>
3287
3288 <dl>
3289 <dt><a name="index-CCM_005fMAX_005fMSG_005fSIZE"></a>Macro: <strong>CCM_MAX_MSG_SIZE</strong> <em>(<var>nonce_size</var>)</em></dt>
3290 <dd><p>The largest allowed plaintext length, when using <acronym>CCM</acronym> with a
3291 nonce of the given size.
3292 </p></dd></dl>
3293
3294 <dl>
3295 <dt><a name="index-ccm_005fset_005fnonce"></a>Function: <em>void</em> <strong>ccm_set_nonce</strong> <em>(struct ccm_ctx *<var>ctx</var>, const void *<var>cipher</var>, nettle_cipher_func *<var>f</var>, size_t <var>noncelen</var>, const uint8_t *<var>nonce</var>, size_t <var>authlen</var>, size_t <var>msglen</var>, size_t <var>taglen</var>)</em></dt>
3296 <dd><p>Initializes <var>ctx</var> using the given nonce and the sizes of the
3297 authenticated data, message, and <acronym>MAC</acronym> to be processed.
3298 </p></dd></dl>
3299
3300 <dl>
3301 <dt><a name="index-ccm_005fupdate"></a>Function: <em>void</em> <strong>ccm_update</strong> <em>(struct ccm_ctx *<var>ctx</var>, const void *<var>cipher</var>, nettle_cipher_func *<var>f</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
3302 <dd><p>Provides associated data to be authenticated. Must be called after
3303 <code>ccm_set_nonce</code>, and before <code>ccm_encrypt</code>, <code>ccm_decrypt</code>, or
3304 <code>ccm_digest</code>.
3305 </p></dd></dl>
3306
3307 <dl>
3308 <dt><a name="index-ccm_005fencrypt"></a>Function: <em>void</em> <strong>ccm_encrypt</strong> <em>(struct ccm_ctx *<var>ctx</var>, const void *<var>cipher</var>, nettle_cipher_func *<var>f</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3309 <dt><a name="index-ccm_005fdecrypt"></a>Function: <em>void</em> <strong>ccm_decrypt</strong> <em>(struct ccm_ctx *<var>ctx</var>, const void *<var>cipher</var>, nettle_cipher_func *<var>f</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3310 <dd><p>Encrypts or decrypts the message data. Must be called after
3311 <code>ccm_set_nonce</code> and before <code>ccm_digest</code>. All but the last call
3312 for each message <em>must</em> use a length that is a multiple of the
3313 block size.
3314 </p></dd></dl>
3315
3316 <dl>
3317 <dt><a name="index-ccm_005fdigest"></a>Function: <em>void</em> <strong>ccm_digest</strong> <em>(struct ccm_ctx *<var>ctx</var>, const void *<var>cipher</var>, nettle_cipher_func *<var>f</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3318 <dd><p>Extracts the message digest (also known &ldquo;authentication tag&rdquo;). This is
3319 the final operation when processing a message. <var>length</var> is usually
3320 equal to the <var>taglen</var> parameter supplied to <code>ccm_set_nonce</code>,
3321 but if you provide a smaller value, only the first <var>length</var> octets
3322 of the digest are written.
3323 </p></dd></dl>
3324
3325 <p>To encrypt a message using the general <acronym>CCM</acronym> interface, set the
3326 message nonce and length using <code>ccm_set_nonce</code> and then call
3327 <code>ccm_update</code> to generate the digest of any authenticated data.
3328 After all of the authenticated data has been digested use
3329 <code>ccm_encrypt</code> to encrypt the plaintext. Finally, use
3330 <code>ccm_digest</code> to return the encrypted <acronym>MAC</acronym>.
3331 </p>
3332 <p>To decrypt a message, use <code>ccm_set_nonce</code> and <code>ccm_update</code> the
3333 same as you would for encryption, and then call <code>ccm_decrypt</code> to
3334 decrypt the ciphertext. After decrypting the ciphertext
3335 <code>ccm_digest</code> will return the encrypted <acronym>MAC</acronym> which should
3336 be identical to the <acronym>MAC</acronym> in the received message.
3337 </p>
3338 <a name="CCM-message-interface"></a>
3339 <h4 class="subsubsection">6.4.3.2 <acronym>CCM</acronym> message interface</h4>
3340
3341 <p>The <acronym>CCM</acronym> message fuctions provides a simple interface that will
3342 perform authentication and message encryption in a single function call.
3343 The length of the cleartext is given by <var>mlength</var> and the length of
3344 the ciphertext is given by <var>clength</var>, always exactly <var>tlength</var>
3345 bytes longer than the corresponding plaintext. The length argument
3346 passed to a function is always the size for the result, <var>clength</var>
3347 for the encryption functions, and <var>mlength</var> for the decryption
3348 functions.
3349 </p>
3350 <dl>
3351 <dt><a name="index-ccm_005fencrypt_005fmessage"></a>Function: <em>void</em> <strong>ccm_encrypt_message</strong> <em>(void *<var>cipher</var>, nettle_cipher_func *<var>f</var>, size_t <var>nlength</var>, const uint8_t *<var>nonce</var>, size_t <var>alength</var>, const uint8_t *<var>adata</var>, size_t <var>tlength</var>, size_t <var>clength</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3352 <dd><p>Computes the message digest from the <var>adata</var> and <var>src</var>
3353 parameters, encrypts the plaintext from <var>src</var>, appends the encrypted
3354 <acronym>MAC</acronym> to ciphertext and outputs it to <var>dst</var>.
3355 </p></dd></dl>
3356
3357 <dl>
3358 <dt><a name="index-ccm_005fdecrypt_005fmessage"></a>Function: <em>int</em> <strong>ccm_decrypt_message</strong> <em>(void *<var>cipher</var>, nettle_cipher_func *<var>f</var>, size_t <var>nlength</var>, const uint8_t *<var>nonce</var>, size_t <var>alength</var>, const uint8_t *<var>adata</var>, size_t <var>tlength</var>, size_t <var>mlength</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3359 <dd><p>Decrypts the ciphertext from <var>src</var>, outputs the plaintext to
3360 <var>dst</var>, recalculates the <acronym>MAC</acronym> from <var>adata</var> and the
3361 plaintext, and compares it to the final <var>tlength</var> bytes of
3362 <var>src</var>. If the values of the received and calculated <acronym>MAC</acronym>s
3363 are equal, this will return 1 indicating a valid and authenticated
3364 message. Otherwise, this function will return zero.
3365 </p></dd></dl>
3366
3367 <a name="CCM_002dAES-interface"></a>
3368 <h4 class="subsubsection">6.4.3.3 <acronym>CCM</acronym>-<acronym>AES</acronym> interface</h4>
3369
3370 <p>The <acronym>AES</acronym> <acronym>CCM</acronym> functions provide an API for using
3371 <acronym>CCM</acronym> mode with the <acronym>AES</acronym> block ciphers. The parameters
3372 all have the same meaning as the general and message interfaces, except
3373 that the <var>cipher</var>, <var>f</var>, and <var>ctx</var> parameters are replaced
3374 with an <acronym>AES</acronym> context structure, and a set-key function must be
3375 called before using any of the other functions in this interface.
3376 </p>
3377 <dl>
3378 <dt><a name="index-struct-ccm_005faes128_005fctx"></a>Context struct: <strong>struct ccm_aes128_ctx</strong></dt>
3379 <dd><p>Holds state corresponding to a particular message encrypted using the
3380 AES-128 block cipher.
3381 </p></dd></dl>
3382
3383 <dl>
3384 <dt><a name="index-struct-ccm_005faes192_005fctx"></a>Context struct: <strong>struct ccm_aes192_ctx</strong></dt>
3385 <dd><p>Holds state corresponding to a particular message encrypted using the
3386 AES-192 block cipher.
3387 </p></dd></dl>
3388
3389 <dl>
3390 <dt><a name="index-struct-ccm_005faes256_005fctx"></a>Context struct: <strong>struct ccm_aes256_ctx</strong></dt>
3391 <dd><p>Holds state corresponding to a particular message encrypted using the
3392 AES-256 block cipher.
3393 </p></dd></dl>
3394
3395 <dl>
3396 <dt><a name="index-ccm_005faes128_005fset_005fkey"></a>Function: <em>void</em> <strong>ccm_aes128_set_key</strong> <em>(struct ccm_aes128_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
3397 <dt><a name="index-ccm_005faes192_005fset_005fkey"></a>Function: <em>void</em> <strong>ccm_aes192_set_key</strong> <em>(struct ccm_aes192_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
3398 <dt><a name="index-ccm_005faes256_005fset_005fkey"></a>Function: <em>void</em> <strong>ccm_aes256_set_key</strong> <em>(struct ccm_aes256_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
3399 <dd><p>Initializes the encryption key for the AES block cipher. One of these
3400 functions must be called before any of the other functions in the
3401 <acronym>AES</acronym> <acronym>CCM</acronym> interface.
3402 </p></dd></dl>
3403
3404 <dl>
3405 <dt><a name="index-ccm_005faes128_005fset_005fnonce"></a>Function: <em>void</em> <strong>ccm_aes128_set_nonce</strong> <em>(struct ccm_aes128_ctx *<var>ctx</var>, size_t <var>noncelen</var>, const uint8_t *<var>nonce</var>, size_t <var>authlen</var>, size_t <var>msglen</var>, size_t <var>taglen</var>)</em></dt>
3406 <dt><a name="index-ccm_005faes192_005fset_005fnonce"></a>Function: <em>void</em> <strong>ccm_aes192_set_nonce</strong> <em>(struct ccm_aes192_ctx *<var>ctx</var>, size_t <var>noncelen</var>, const uint8_t *<var>nonce</var>, size_t <var>authlen</var>, size_t <var>msglen</var>, size_t <var>taglen</var>)</em></dt>
3407 <dt><a name="index-ccm_005faes256_005fset_005fnonce"></a>Function: <em>void</em> <strong>ccm_aes256_set_nonce</strong> <em>(struct ccm_aes256_ctx *<var>ctx</var>, size_t <var>noncelen</var>, const uint8_t *<var>nonce</var>, size_t <var>authlen</var>, size_t <var>msglen</var>, size_t <var>taglen</var>)</em></dt>
3408 <dd><p>These are identical to <code>ccm_set_nonce</code>, except that <var>cipher</var>,
3409 <var>f</var>, and <var>ctx</var> are replaced with a context structure.
3410 </p></dd></dl>
3411
3412 <dl>
3413 <dt><a name="index-ccm_005faes128_005fupdate"></a>Function: <em>void</em> <strong>ccm_aes128_update</strong> <em>(struct ccm_aes128_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
3414 <dt><a name="index-ccm_005faes192_005fupdate"></a>Function: <em>void</em> <strong>ccm_aes192_update</strong> <em>(struct ccm_aes192_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
3415 <dt><a name="index-ccm_005faes256_005fupdate"></a>Function: <em>void</em> <strong>ccm_aes256_update</strong> <em>(struct ccm_aes256_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
3416 <dd><p>These are identical to <code>ccm_set_update</code>, except that <var>cipher</var>,
3417 <var>f</var>, and <var>ctx</var> are replaced with a context structure.
3418 </p></dd></dl>
3419
3420 <dl>
3421 <dt><a name="index-ccm_005faes128_005fencrypt"></a>Function: <em>void</em> <strong>ccm_aes128_encrypt</strong> <em>(struct ccm_aes128_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3422 <dt><a name="index-ccm_005faes192_005fencrypt"></a>Function: <em>void</em> <strong>ccm_aes192_encrypt</strong> <em>(struct ccm_aes192_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3423 <dt><a name="index-ccm_005faes256_005fencrypt"></a>Function: <em>void</em> <strong>ccm_aes256_encrypt</strong> <em>(struct ccm_aes256_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3424 <dt><a name="index-ccm_005faes128_005fdecrypt"></a>Function: <em>void</em> <strong>ccm_aes128_decrypt</strong> <em>(struct ccm_aes128_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3425 <dt><a name="index-ccm_005faes192_005fdecrypt"></a>Function: <em>void</em> <strong>ccm_aes192_decrypt</strong> <em>(struct ccm_aes192_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3426 <dt><a name="index-ccm_005faes256_005fdecrypt"></a>Function: <em>void</em> <strong>ccm_aes256_decrypt</strong> <em>(struct ccm_aes256_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3427 <dd><p>These are identical to <code>ccm_set_encrypt</code> and <code>ccm_set_decrypt</code>, except
3428 that <var>cipher</var>, <var>f</var>, and <var>ctx</var> are replaced with a context structure.
3429 </p></dd></dl>
3430
3431 <dl>
3432 <dt><a name="index-ccm_005faes128_005fdigest"></a>Function: <em>void</em> <strong>ccm_aes128_digest</strong> <em>(struct ccm_aes128_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3433 <dt><a name="index-ccm_005faes192_005fdigest"></a>Function: <em>void</em> <strong>ccm_aes192_digest</strong> <em>(struct ccm_aes192_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3434 <dt><a name="index-ccm_005faes256_005fdigest"></a>Function: <em>void</em> <strong>ccm_aes256_digest</strong> <em>(struct ccm_aes256_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3435 <dd><p>These are identical to <code>ccm_set_digest</code>, except that <var>cipher</var>,
3436 <var>f</var>, and <var>ctx</var> are replaced with a context structure.
3437 </p></dd></dl>
3438
3439 <dl>
3440 <dt><a name="index-ccm_005faes128_005fencrypt_005fmessage"></a>Function: <em>void</em> <strong>ccm_aes128_encrypt_message</strong> <em>(struct ccm_aes128_ctx *<var>ctx</var>, size_t <var>nlength</var>, const uint8_t *<var>nonce</var>, size_t <var>alength</var>, const uint8_t *<var>adata</var>, size_t <var>tlength</var>, size_t <var>clength</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3441 <dt><a name="index-ccm_005faes192_005fencrypt_005fmessage"></a>Function: <em>void</em> <strong>ccm_aes192_encrypt_message</strong> <em>(struct ccm_aes192_ctx *<var>ctx</var>, size_t <var>nlength</var>, const uint8_t *<var>nonce</var>, size_t <var>alength</var>, const uint8_t *<var>adata</var>, size_t <var>tlength</var>, size_t <var>clength</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3442 <dt><a name="index-ccm_005faes256_005fencrypt_005fmessage"></a>Function: <em>void</em> <strong>ccm_aes256_encrypt_message</strong> <em>(struct ccm_aes256_ctx *<var>ctx</var>, size_t <var>nlength</var>, const uint8_t *<var>nonce</var>, size_t <var>alength</var>, const uint8_t *<var>adata</var>, size_t <var>tlength</var>, size_t <var>clength</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3443 <dt><a name="index-ccm_005faes128_005fdecrypt_005fmessage"></a>Function: <em>int</em> <strong>ccm_aes128_decrypt_message</strong> <em>(struct ccm_aes128_ctx *<var>ctx</var>, size_t <var>nlength</var>, const uint8_t *<var>nonce</var>, size_t <var>alength</var>, const uint8_t *<var>adata</var>, size_t <var>tlength</var>, size_t <var>mlength</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3444 <dt><a name="index-ccm_005faes192_005fdecrypt_005fmessage"></a>Function: <em>int</em> <strong>ccm_aes192_decrypt_message</strong> <em>(struct ccm_aes192_ctx *<var>ctx</var>, size_t <var>nlength</var>, const uint8_t *<var>nonce</var>, size_t <var>alength</var>, const uint8_t *<var>adata</var>, size_t <var>tlength</var>, size_t <var>mlength</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3445 <dt><a name="index-ccm_005faes192_005fdecrypt_005fmessage-1"></a>Function: <em>int</em> <strong>ccm_aes192_decrypt_message</strong> <em>(struct ccm_aes256_ctx *<var>ctx</var>, size_t <var>nlength</var>, const uint8_t *<var>nonce</var>, size_t <var>alength</var>, const uint8_t *<var>adata</var>, size_t <var>tlength</var>, size_t <var>mlength</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3446 <dd><p>These are identical to <code>ccm_encrypt_message</code> and <code>ccm_decrypt_message</code>
3447 except that <var>cipher</var> and <var>f</var> are replaced with a context structure.
3448 </p></dd></dl>
3449
3450 <hr>
3451 <a name="ChaCha_002dPoly1305"></a>
3452 <div class="header">
3453 <p>
3454 Next: <a href="#nettle_005faead-abstraction" accesskey="n" rel="next">nettle_aead abstraction</a>, Previous: <a href="#CCM" accesskey="p" rel="prev">CCM</a>, Up: <a href="#Authenticated-encryption" accesskey="u" rel="up">Authenticated encryption</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
3455 </div>
3456 <a name="ChaCha_002dPoly1305-1"></a>
3457 <h4 class="subsection">6.4.4 ChaCha-Poly1305</h4>
3458
3459 <p>ChaCha-Poly1305 is a combination of the ChaCha stream cipher and the
3460 poly1305 message authentication code (see <a href="#Poly1305">Poly1305</a>). It originates
3461 from the NaCl cryptographic library by D. J. Bernstein et al, which
3462 defines a similar construction but with Salsa20 instead of ChaCha.
3463 </p>
3464 <p>Nettle&rsquo;s implementation ChaCha-Poly1305 should be considered
3465 <strong>experimental</strong>. At the time of this writing, there is no
3466 authoritative specification for ChaCha-Poly1305, and a couple of
3467 different incompatible variants. Nettle implements it using the original
3468 definition of ChaCha, with 64 bits (8 octets) each for the nonce and the
3469 block counter. Some protocols prefer to use nonces of 12 bytes, and it&rsquo;s
3470 a small change to ChaCha to use the upper 32 bits of the block counter
3471 as a nonce, instead limiting message size to <em>2^32</em> blocks or 256
3472 GBytes, but that variant is currently not supported.
3473 </p>
3474 <p>For ChaCha-Poly1305, the ChaCha cipher is initialized with a key, of 256
3475 bits, and a per-message nonce. The first block of the key stream
3476 (counter all zero) is set aside for the authentication subkeys. Of this
3477 64-octet block, the first 16 octets specify the poly1305 evaluation
3478 point, and the next 16 bytes specify the value to add in for the final
3479 digest. The final 32 bytes of this block are unused. Note that unlike
3480 poly1305-aes, the evaluation point depends on the nonce. This is
3481 preferable, because it leaks less information in case the attacker for
3482 some reason is lucky enough to forge a valid authentication tag, and
3483 observe (from the receiver&rsquo;s behaviour) that the forgery succeeded.
3484 </p>
3485 <p>The ChaCha key stream, starting with counter value 1, is then used to
3486 encrypt the message. For authentication, poly1305 is applied to the
3487 concatenation of the associated data, the cryptotext, and the lengths of
3488 the associated data and the message, each a 64-bit number (eight octets,
3489 little-endian). Nettle defines ChaCha-Poly1305 in
3490 <samp>&lt;nettle/chacha-poly1305.h&gt;</samp>.
3491 </p>
3492 <dl>
3493 <dt><a name="index-CHACHA_005fPOLY1305_005fBLOCK_005fSIZE"></a>Constant: <strong>CHACHA_POLY1305_BLOCK_SIZE</strong></dt>
3494 <dd><p>Same as the ChaCha block size, 64.
3495 </p></dd></dl>
3496
3497 <dl>
3498 <dt><a name="index-CHACHA_005fPOLY1305_005fKEY_005fSIZE"></a>Constant: <strong>CHACHA_POLY1305_KEY_SIZE</strong></dt>
3499 <dd><p>ChaCha-Poly1305 key size, 32.
3500 </p></dd></dl>
3501
3502 <dl>
3503 <dt><a name="index-CHACHA_005fPOLY1305_005fNONCE_005fSIZE"></a>Constant: <strong>CHACHA_POLY1305_NONCE_SIZE</strong></dt>
3504 <dd><p>Same as the ChaCha nonce size, 16.
3505 </p></dd></dl>
3506
3507 <dl>
3508 <dt><a name="index-CHACHA_005fPOLY1305_005fDIGEST_005fSIZE"></a>Constant: <strong>CHACHA_POLY1305_DIGEST_SIZE</strong></dt>
3509 <dd><p>Digest size, 16.
3510 </p></dd></dl>
3511
3512 <dl>
3513 <dt><a name="index-struct-chacha_005fpoly1305_005fctx"></a>Context struct: <strong>struct chacha_poly1305_ctx</strong></dt>
3514 </dl>
3515
3516 <dl>
3517 <dt><a name="index-chacha_005fpoly1305_005fset_005fkey"></a>Function: <em>void</em> <strong>chacha_poly1305_set_key</strong> <em>(struct chacha_poly1305_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
3518 <dd><p>Initializes <var>ctx</var> using the given key. Before using the context, you
3519 <em>must</em> also call <code>chacha_poly1305_set_nonce</code>, see below.
3520 </p></dd></dl>
3521
3522 <dl>
3523 <dt><a name="index-chacha_005fpoly1305_005fset_005fnonce"></a>Function: <em>void</em> <strong>chacha_poly1305_set_nonce</strong> <em>(struct chacha_poly1305_ctx *<var>ctx</var>, const uint8_t *<var>nonce</var>)</em></dt>
3524 <dd><p>Initializes the per-message state, using the given nonce.
3525 </p></dd></dl>
3526
3527 <dl>
3528 <dt><a name="index-chacha_005fpoly1305_005fupdate"></a>Function: <em>void</em> <strong>chacha_poly1305_update</strong> <em>(struct chacha_poly1305_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
3529 <dd><p>Process associated data for authentication.
3530 </p></dd></dl>
3531
3532 <dl>
3533 <dt><a name="index-chacha_005fpoly1305_005fencrypt"></a>Function: <em>void</em> <strong>chacha_poly1305_encrypt</strong> <em>(struct chacha_poly1305_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3534 <dt><a name="index-chacha_005fpoly1305_005fdecrypt"></a>Function: <em>void</em> <strong>chacha_poly1305_decrypt</strong> <em>(struct chacha_poly1305_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>, const uint8_t *<var>src</var>)</em></dt>
3535 <dd><p>Encrypts or decrypts the data of a message. All but the last call for
3536 each message <em>must</em> use a length that is a multiple of the block
3537 size.
3538 </p></dd></dl>
3539
3540 <dl>
3541 <dt><a name="index-chacha_005fpoly1305_005fdigest"></a>Function: <em>void</em> <strong>chacha_poly1305_digest</strong> <em>(struct chacha_poly1305_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3542 <dd><p>Extracts the message digest (also known &ldquo;authentication tag&rdquo;). This is
3543 the final operation when processing a message. If <var>length</var> is
3544 smaller than <code>CHACHA_POLY1305_DIGEST_SIZE</code>, only the first
3545 <var>length</var> octets of the digest are written.
3546 </p></dd></dl>
3547
3548 <hr>
3549 <a name="nettle_005faead-abstraction"></a>
3550 <div class="header">
3551 <p>
3552 Previous: <a href="#ChaCha_002dPoly1305" accesskey="p" rel="prev">ChaCha-Poly1305</a>, Up: <a href="#Authenticated-encryption" accesskey="u" rel="up">Authenticated encryption</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
3553 </div>
3554 <a name="The-struct-nettle_005faead-abstraction"></a>
3555 <h4 class="subsection">6.4.5 The <code>struct nettle_aead</code> abstraction</h4>
3556 <a name="index-nettle_005faead"></a>
3557 <a name="index-nettle_005faeads"></a>
3558
3559 <p>Nettle includes a struct including information about the supported hash
3560 functions. It is defined in <samp>&lt;nettle/nettle-meta.h&gt;</samp>.
3561 </p>
3562 <dl>
3563 <dt><a name="index-struct-nettle_005faead"></a>Meta struct: <strong><code>struct nettle_aead</code></strong> <em>name context_size block_size key_size nonce_size digest_size set_encrypt_key set_decrypt_key set_nonce update encrypt decrypt digest</em></dt>
3564 <dd><p>The last seven attributes are function pointers.
3565 </p></dd></dl>
3566
3567 <dl>
3568 <dt><a name="index-nettle_005fgcm_005faes128"></a>Constant Struct: <em>struct nettle_aead</em> <strong>nettle_gcm_aes128</strong></dt>
3569 <dt><a name="index-nettle_005fgcm_005faes192"></a>Constant Struct: <em>struct nettle_aead</em> <strong>nettle_gcm_aes192</strong></dt>
3570 <dt><a name="index-nettle_005fgcm_005faes256"></a>Constant Struct: <em>struct nettle_aead</em> <strong>nettle_gcm_aes256</strong></dt>
3571 <dt><a name="index-nettle_005fgcm_005fcamellia128"></a>Constant Struct: <em>struct nettle_aead</em> <strong>nettle_gcm_camellia128</strong></dt>
3572 <dt><a name="index-nettle_005fgcm_005fcamellia256"></a>Constant Struct: <em>struct nettle_aead</em> <strong>nettle_gcm_camellia256</strong></dt>
3573 <dt><a name="index-nettle_005feax_005faes128"></a>Constant Struct: <em>struct nettle_aead</em> <strong>nettle_eax_aes128</strong></dt>
3574 <dt><a name="index-nettle_005fchacha_005fpoly1305"></a>Constant Struct: <em>struct nettle_aead</em> <strong>nettle_chacha_poly1305</strong></dt>
3575 <dd><p>These are most of the <acronym>AEAD</acronym> constructions that Nettle
3576 implements. Note that <acronym>CCM</acronym> is missing; it requirement that the
3577 message size is specified in advance makes it incompatible with the
3578 <code>nettle_aead</code> abstraction.
3579 </p></dd></dl>
3580
3581 <p>Nettle also exports a list of all these constructions.
3582 </p>
3583 <dl>
3584 <dt><a name="index-nettle_005faeads-1"></a>Constant Array: <em>struct nettle_aead **</em> <strong>nettle_aeads</strong></dt>
3585 <dd><p>This list can be used to dynamically enumerate or search the supported
3586 algorithms. NULL-terminated.
3587 </p></dd></dl>
3588
3589 <hr>
3590 <a name="Keyed-hash-functions"></a>
3591 <div class="header">
3592 <p>
3593 Next: <a href="#Key-derivation-functions" accesskey="n" rel="next">Key derivation functions</a>, Previous: <a href="#Authenticated-encryption" accesskey="p" rel="prev">Authenticated encryption</a>, Up: <a href="#Reference" accesskey="u" rel="up">Reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
3594 </div>
3595 <a name="Keyed-Hash-Functions"></a>
3596 <h3 class="section">6.5 Keyed Hash Functions</h3>
3597
3598 <a name="index-Keyed-Hash-Function"></a>
3599 <a name="index-Message-Authentication-Code"></a>
3600 <a name="index-MAC"></a>
3601
3602 <p>A <em>keyed hash function</em>, or <em>Message Authentication Code</em>
3603 (<acronym>MAC</acronym>) is a function that takes a key and a message, and
3604 produces fixed size <acronym>MAC</acronym>. It should be hard to compute a
3605 message and a matching <acronym>MAC</acronym> without knowledge of the key. It
3606 should also be hard to compute the key given only messages and
3607 corresponding <acronym>MAC</acronym>s.
3608 </p>
3609 <p>Keyed hash functions are useful primarily for message authentication,
3610 when Alice and Bob shares a secret: The sender, Alice, computes the
3611 <acronym>MAC</acronym> and attaches it to the message. The receiver, Bob, also computes
3612 the <acronym>MAC</acronym> of the message, using the same key, and compares that
3613 to Alice&rsquo;s value. If they match, Bob can be assured that
3614 the message has not been modified on its way from Alice.
3615 </p>
3616 <p>However, unlike digital signatures, this assurance is not transferable.
3617 Bob can&rsquo;t show the message and the <acronym>MAC</acronym> to a third party and
3618 prove that Alice sent that message. Not even if he gives away the key to
3619 the third party. The reason is that the <em>same</em> key is used on both
3620 sides, and anyone knowing the key can create a correct <acronym>MAC</acronym> for
3621 any message. If Bob believes that only he and Alice knows the key, and
3622 he knows that he didn&rsquo;t attach a <acronym>MAC</acronym> to a particular message,
3623 he knows it must be Alice who did it. However, the third party can&rsquo;t
3624 distinguish between a <acronym>MAC</acronym> created by Alice and one created by
3625 Bob.
3626 </p>
3627 <p>Keyed hash functions are typically a lot faster than digital signatures
3628 as well.
3629 </p>
3630 <table class="menu" border="0" cellspacing="0">
3631 <tr><td align="left" valign="top">&bull; <a href="#HMAC" accesskey="1">HMAC</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3632 </td></tr>
3633 <tr><td align="left" valign="top">&bull; <a href="#UMAC" accesskey="2">UMAC</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3634 </td></tr>
3635 <tr><td align="left" valign="top">&bull; <a href="#Poly1305" accesskey="3">Poly1305</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">
3636 </td></tr>
3637 </table>
3638
3639 <hr>
3640 <a name="HMAC"></a>
3641 <div class="header">
3642 <p>
3643 Next: <a href="#UMAC" accesskey="n" rel="next">UMAC</a>, Previous: <a href="#Keyed-hash-functions" accesskey="p" rel="prev">Keyed hash functions</a>, Up: <a href="#Keyed-hash-functions" accesskey="u" rel="up">Keyed hash functions</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
3644 </div>
3645
3646 <a name="HMAC-1"></a>
3647 <h4 class="subsection">6.5.1 <acronym>HMAC</acronym></h4>
3648 <a name="index-HMAC"></a>
3649
3650 <p>One can build keyed hash functions from ordinary hash functions. Older
3651 constructions simply concatenate secret key and message and hashes that, but
3652 such constructions have weaknesses. A better construction is
3653 <acronym>HMAC</acronym>, described in <cite>RFC 2104</cite>.
3654 </p>
3655 <p>For an underlying hash function <code>H</code>, with digest size <code>l</code> and
3656 internal block size <code>b</code>, <acronym>HMAC-H</acronym> is constructed as
3657 follows: From a given key <code>k</code>, two distinct subkeys <code>k_i</code> and
3658 <code>k_o</code> are constructed, both of length <code>b</code>. The
3659 <acronym>HMAC-H</acronym> of a message <code>m</code> is then computed as <code>H(k_o |
3660 H(k_i | m))</code>, where <code>|</code> denotes string concatenation.
3661 </p>
3662 <p><acronym>HMAC</acronym> keys can be of any length, but it is recommended to use
3663 keys of length <code>l</code>, the digest size of the underlying hash function
3664 <code>H</code>. Keys that are longer than <code>b</code> are shortened to length
3665 <code>l</code> by hashing with <code>H</code>, so arbitrarily long keys aren&rsquo;t
3666 very useful.
3667 </p>
3668 <p>Nettle&rsquo;s <acronym>HMAC</acronym> functions are defined in <samp>&lt;nettle/hmac.h&gt;</samp>.
3669 There are abstract functions that use a pointer to a <code>struct
3670 nettle_hash</code> to represent the underlying hash function and <code>void *</code>
3671 pointers that point to three different context structs for that hash
3672 function. There are also concrete functions for <acronym>HMAC-MD5</acronym>,
3673 <acronym>HMAC-RIPEMD160</acronym> <acronym>HMAC-SHA1</acronym>, <acronym>HMAC-SHA256</acronym>, and
3674 <acronym>HMAC-SHA512</acronym>. First, the abstract functions:
3675 </p>
3676 <dl>
3677 <dt><a name="index-hmac_005fset_005fkey"></a>Function: <em>void</em> <strong>hmac_set_key</strong> <em>(void *<var>outer</var>, void *<var>inner</var>, void *<var>state</var>, const struct nettle_hash *<var>H</var>, size_t <var>length</var>, const uint8_t *<var>key</var>)</em></dt>
3678 <dd><p>Initializes the three context structs from the key. The <var>outer</var> and
3679 <var>inner</var> contexts corresponds to the subkeys <code>k_o</code> and
3680 <code>k_i</code>. <var>state</var> is used for hashing the message, and is
3681 initialized as a copy of the <var>inner</var> context.
3682 </p></dd></dl>
3683
3684 <dl>
3685 <dt><a name="index-hmac_005fupdate"></a>Function: <em>void</em> <strong>hmac_update</strong> <em>(void *<var>state</var>, const struct nettle_hash *<var>H</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
3686 <dd><p>This function is called zero or more times to process the message.
3687 Actually, <code>hmac_update(state, H, length, data)</code> is equivalent to
3688 <code>H-&gt;update(state, length, data)</code>, so if you wish you can use the
3689 ordinary update function of the underlying hash function instead.
3690 </p></dd></dl>
3691
3692 <dl>
3693 <dt><a name="index-hmac_005fdigest"></a>Function: <em>void</em> <strong>hmac_digest</strong> <em>(const void *<var>outer</var>, const void *<var>inner</var>, void *<var>state</var>, const struct nettle_hash *<var>H</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3694 <dd><p>Extracts the <acronym>MAC</acronym> of the message, writing it to <var>digest</var>.
3695 <var>outer</var> and <var>inner</var> are not modified. <var>length</var> is usually
3696 equal to <code>H-&gt;digest_size</code>, but if you provide a smaller value,
3697 only the first <var>length</var> octets of the <acronym>MAC</acronym> are written.
3698 </p>
3699 <p>This function also resets the <var>state</var> context so that you can start
3700 over processing a new message (with the same key).
3701 </p></dd></dl>
3702
3703 <p>Like for <acronym>CBC</acronym>, there are some macros to help use these
3704 functions correctly.
3705 </p>
3706 <dl>
3707 <dt><a name="index-HMAC_005fCTX"></a>Macro: <strong>HMAC_CTX</strong> <em>(<var>type</var>)</em></dt>
3708 <dd><p>Expands to
3709 </p><div class="example">
3710 <pre class="example">{
3711    type outer;
3712    type inner;
3713    type state;
3714 }
3715 </pre></div>
3716 </dd></dl>
3717
3718 <p>It can be used to define a <acronym>HMAC</acronym> context struct, either
3719 directly,
3720 </p>
3721 <div class="example">
3722 <pre class="example">struct HMAC_CTX(struct md5_ctx) ctx;
3723 </pre></div>
3724
3725 <p>or to give it a struct tag,
3726 </p>
3727 <div class="example">
3728 <pre class="example">struct hmac_md5_ctx HMAC_CTX (struct md5_ctx);
3729 </pre></div>
3730
3731 <dl>
3732 <dt><a name="index-HMAC_005fSET_005fKEY"></a>Macro: <strong>HMAC_SET_KEY</strong> <em>(<var>ctx</var>, <var>H</var>, <var>length</var>, <var>key</var>)</em></dt>
3733 <dd><p><var>ctx</var> is a pointer to a context struct as defined by
3734 <code>HMAC_CTX</code>, <var>H</var> is a pointer to a <code>const struct
3735 nettle_hash</code> describing the underlying hash function (so it must match
3736 the type of the components of <var>ctx</var>). The last two arguments specify
3737 the secret key.
3738 </p></dd></dl>
3739
3740 <dl>
3741 <dt><a name="index-HMAC_005fDIGEST"></a>Macro: <strong>HMAC_DIGEST</strong> <em>(<var>ctx</var>, <var>H</var>, <var>length</var>, <var>digest</var>)</em></dt>
3742 <dd><p><var>ctx</var> is a pointer to a context struct as defined by
3743 <code>HMAC_CTX</code>, <var>H</var> is a pointer to a <code>const struct
3744 nettle_hash</code> describing the underlying hash function. The last two
3745 arguments specify where the digest is written.
3746 </p></dd></dl>
3747
3748 <p>Note that there is no <code>HMAC_UPDATE</code> macro; simply call
3749 <code>hmac_update</code> function directly, or the update function of the
3750 underlying hash function.
3751 </p>
3752 <a name="Concrete-HMAC-functions"></a>
3753 <h4 class="subsection">6.5.2 Concrete <acronym>HMAC</acronym> functions</h4>
3754 <p>Now we come to the specialized <acronym>HMAC</acronym> functions, which are
3755 easier to use than the general <acronym>HMAC</acronym> functions.
3756 </p>
3757 <a name="HMAC_002dMD5"></a>
3758 <h4 class="subsubsection">6.5.2.1 <acronym>HMAC-MD5</acronym></h4>
3759
3760 <dl>
3761 <dt><a name="index-struct-hmac_005fmd5_005fctx"></a>Context struct: <strong>struct hmac_md5_ctx</strong></dt>
3762 </dl>
3763
3764 <dl>
3765 <dt><a name="index-hmac_005fmd5_005fset_005fkey"></a>Function: <em>void</em> <strong>hmac_md5_set_key</strong> <em>(struct hmac_md5_ctx *<var>ctx</var>, size_t <var>key_length</var>, const uint8_t *<var>key</var>)</em></dt>
3766 <dd><p>Initializes the context with the key.
3767 </p></dd></dl>
3768
3769 <dl>
3770 <dt><a name="index-hmac_005fmd5_005fupdate"></a>Function: <em>void</em> <strong>hmac_md5_update</strong> <em>(struct hmac_md5_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
3771 <dd><p>Process some more data.
3772 </p></dd></dl>
3773
3774 <dl>
3775 <dt><a name="index-hmac_005fmd5_005fdigest"></a>Function: <em>void</em> <strong>hmac_md5_digest</strong> <em>(struct hmac_md5_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3776 <dd><p>Extracts the <acronym>MAC</acronym>, writing it to <var>digest</var>. <var>length</var> may be smaller than
3777 <code>MD5_DIGEST_SIZE</code>, in which case only the first <var>length</var>
3778 octets of the <acronym>MAC</acronym> are written.
3779 </p>
3780 <p>This function also resets the context for processing new messages, with
3781 the same key.
3782 </p></dd></dl>
3783
3784 <a name="HMAC_002dRIPEMD160"></a>
3785 <h4 class="subsubsection">6.5.2.2 <acronym>HMAC-RIPEMD160</acronym></h4>
3786
3787 <dl>
3788 <dt><a name="index-struct-hmac_005fripemd160_005fctx"></a>Context struct: <strong>struct hmac_ripemd160_ctx</strong></dt>
3789 </dl>
3790
3791 <dl>
3792 <dt><a name="index-hmac_005fripemd160_005fset_005fkey"></a>Function: <em>void</em> <strong>hmac_ripemd160_set_key</strong> <em>(struct hmac_ripemd160_ctx *<var>ctx</var>, size_t <var>key_length</var>, const uint8_t *<var>key</var>)</em></dt>
3793 <dd><p>Initializes the context with the key.
3794 </p></dd></dl>
3795
3796 <dl>
3797 <dt><a name="index-hmac_005fripemd160_005fupdate"></a>Function: <em>void</em> <strong>hmac_ripemd160_update</strong> <em>(struct hmac_ripemd160_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
3798 <dd><p>Process some more data.
3799 </p></dd></dl>
3800
3801 <dl>
3802 <dt><a name="index-hmac_005fripemd160_005fdigest"></a>Function: <em>void</em> <strong>hmac_ripemd160_digest</strong> <em>(struct hmac_ripemd160_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3803 <dd><p>Extracts the <acronym>MAC</acronym>, writing it to <var>digest</var>. <var>length</var> may be smaller than
3804 <code>RIPEMD160_DIGEST_SIZE</code>, in which case only the first <var>length</var>
3805 octets of the <acronym>MAC</acronym> are written.
3806 </p>
3807 <p>This function also resets the context for processing new messages, with
3808 the same key.
3809 </p></dd></dl>
3810
3811 <a name="HMAC_002dSHA1"></a>
3812 <h4 class="subsubsection">6.5.2.3 <acronym>HMAC-SHA1</acronym></h4>
3813
3814 <dl>
3815 <dt><a name="index-struct-hmac_005fsha1_005fctx"></a>Context struct: <strong>struct hmac_sha1_ctx</strong></dt>
3816 </dl>
3817
3818 <dl>
3819 <dt><a name="index-hmac_005fsha1_005fset_005fkey"></a>Function: <em>void</em> <strong>hmac_sha1_set_key</strong> <em>(struct hmac_sha1_ctx *<var>ctx</var>, size_t <var>key_length</var>, const uint8_t *<var>key</var>)</em></dt>
3820 <dd><p>Initializes the context with the key.
3821 </p></dd></dl>
3822
3823 <dl>
3824 <dt><a name="index-hmac_005fsha1_005fupdate"></a>Function: <em>void</em> <strong>hmac_sha1_update</strong> <em>(struct hmac_sha1_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
3825 <dd><p>Process some more data.
3826 </p></dd></dl>
3827
3828 <dl>
3829 <dt><a name="index-hmac_005fsha1_005fdigest"></a>Function: <em>void</em> <strong>hmac_sha1_digest</strong> <em>(struct hmac_sha1_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3830 <dd><p>Extracts the <acronym>MAC</acronym>, writing it to <var>digest</var>. <var>length</var> may be smaller than
3831 <code>SHA1_DIGEST_SIZE</code>, in which case only the first <var>length</var>
3832 octets of the <acronym>MAC</acronym> are written.
3833 </p>
3834 <p>This function also resets the context for processing new messages, with
3835 the same key.
3836 </p></dd></dl>
3837
3838
3839 <a name="HMAC_002dSHA256"></a>
3840 <h4 class="subsubsection">6.5.2.4 <acronym>HMAC-SHA256</acronym></h4>
3841
3842 <dl>
3843 <dt><a name="index-struct-hmac_005fsha256_005fctx"></a>Context struct: <strong>struct hmac_sha256_ctx</strong></dt>
3844 </dl>
3845
3846 <dl>
3847 <dt><a name="index-hmac_005fsha256_005fset_005fkey"></a>Function: <em>void</em> <strong>hmac_sha256_set_key</strong> <em>(struct hmac_sha256_ctx *<var>ctx</var>, size_t <var>key_length</var>, const uint8_t *<var>key</var>)</em></dt>
3848 <dd><p>Initializes the context with the key.
3849 </p></dd></dl>
3850
3851 <dl>
3852 <dt><a name="index-hmac_005fsha256_005fupdate"></a>Function: <em>void</em> <strong>hmac_sha256_update</strong> <em>(struct hmac_sha256_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
3853 <dd><p>Process some more data.
3854 </p></dd></dl>
3855
3856 <dl>
3857 <dt><a name="index-hmac_005fsha256_005fdigest"></a>Function: <em>void</em> <strong>hmac_sha256_digest</strong> <em>(struct hmac_sha256_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3858 <dd><p>Extracts the <acronym>MAC</acronym>, writing it to <var>digest</var>. <var>length</var> may be smaller than
3859 <code>SHA256_DIGEST_SIZE</code>, in which case only the first <var>length</var>
3860 octets of the <acronym>MAC</acronym> are written.
3861 </p>
3862 <p>This function also resets the context for processing new messages, with
3863 the same key.
3864 </p></dd></dl>
3865
3866
3867 <a name="HMAC_002dSHA512"></a>
3868 <h4 class="subsubsection">6.5.2.5 <acronym>HMAC-SHA512</acronym></h4>
3869
3870 <dl>
3871 <dt><a name="index-struct-hmac_005fsha512_005fctx"></a>Context struct: <strong>struct hmac_sha512_ctx</strong></dt>
3872 </dl>
3873
3874 <dl>
3875 <dt><a name="index-hmac_005fsha512_005fset_005fkey"></a>Function: <em>void</em> <strong>hmac_sha512_set_key</strong> <em>(struct hmac_sha512_ctx *<var>ctx</var>, size_t <var>key_length</var>, const uint8_t *<var>key</var>)</em></dt>
3876 <dd><p>Initializes the context with the key.
3877 </p></dd></dl>
3878
3879 <dl>
3880 <dt><a name="index-hmac_005fsha512_005fupdate"></a>Function: <em>void</em> <strong>hmac_sha512_update</strong> <em>(struct hmac_sha512_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
3881 <dd><p>Process some more data.
3882 </p></dd></dl>
3883
3884 <dl>
3885 <dt><a name="index-hmac_005fsha512_005fdigest"></a>Function: <em>void</em> <strong>hmac_sha512_digest</strong> <em>(struct hmac_sha512_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
3886 <dd><p>Extracts the <acronym>MAC</acronym>, writing it to <var>digest</var>. <var>length</var> may be smaller than
3887 <code>SHA512_DIGEST_SIZE</code>, in which case only the first <var>length</var>
3888 octets of the <acronym>MAC</acronym> are written.
3889 </p>
3890 <p>This function also resets the context for processing new messages, with
3891 the same key.
3892 </p></dd></dl>
3893
3894 <hr>
3895 <a name="UMAC"></a>
3896 <div class="header">
3897 <p>
3898 Next: <a href="#Poly1305" accesskey="n" rel="next">Poly1305</a>, Previous: <a href="#HMAC" accesskey="p" rel="prev">HMAC</a>, Up: <a href="#Keyed-hash-functions" accesskey="u" rel="up">Keyed hash functions</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
3899 </div>
3900
3901 <a name="UMAC-1"></a>
3902 <h4 class="subsection">6.5.3 <acronym>UMAC</acronym></h4>
3903 <a name="index-UMAC"></a>
3904
3905 <p><acronym>UMAC</acronym> is a message authentication code based on universal
3906 hashing, and designed for high performance on modern processors (in
3907 contrast to GCM, See <a href="#GCM">GCM</a>, which is designed primarily for hardware
3908 performance). On processors with good integer multiplication
3909 performance, it can be 10 times faster than SHA256 and SHA512.
3910 <acronym>UMAC</acronym> is specified in <cite>RFC 4418</cite>.
3911 </p>
3912 <p>The secret key is always 128 bits (16 octets). The key is used as an
3913 encryption key for the <acronym>AES</acronym> block cipher. This cipher is used
3914 in counter mode to generate various internal subkeys needed in
3915 <acronym>UMAC</acronym>. Messages are of arbitrary size, and for each message,
3916 <acronym>UMAC</acronym> also needs a unique nonce. Nonce values must not be
3917 reused for two messages with the same key, but they need not be kept
3918 secret.
3919 </p>
3920 <p>The nonce must be at least one octet, and at most 16; nonces shorter
3921 than 16 octets are zero-padded. Nettle&rsquo;s implementation of
3922 <acronym>UMAC</acronym> increments the nonce automatically for each message, so
3923 explicitly setting the nonce for each message is optional. This
3924 auto-increment uses network byte order and it takes the length of the
3925 nonce into account. E.g., if the initial nonce is &ldquo;abc&rdquo; (3 octets),
3926 this value is zero-padded to 16 octets for the first message. For the
3927 next message, the nonce is incremented to &ldquo;abd&rdquo;, and this incremented
3928 value is zero-padded to 16 octets.
3929 </p>
3930 <p><acronym>UMAC</acronym> is defined in four variants, for different output sizes:
3931 32 bits (4 octets), 64 bits (8 octets), 96 bits (12 octets) and 128 bits
3932 (16 octets), corresponding to different trade-offs between speed and
3933 security. Using a shorter output size sometimes (but not always!) gives
3934 the same result as using a longer output size and truncating the result.
3935 So it is important to use the right variant. For consistency with other
3936 hash and <acronym>MAC</acronym> functions, Nettle&rsquo;s <code>_digest</code> functions for
3937 <acronym>UMAC</acronym> accept a length parameter so that the output can be
3938 truncated to any desired size, but it is recommended to stick to the
3939 specified output size and select the <acronym>umac</acronym> variant
3940 corresponding to the desired size.
3941 </p>
3942 <p>The internal block size of <acronym>UMAC</acronym> is 1024 octets, and it also
3943 generates more than 1024 bytes of subkeys. This makes the size of the
3944 context struct quite a bit larger than other hash functions and
3945 <acronym>MAC</acronym> algorithms in Nettle.
3946 </p>
3947 <p>Nettle defines <acronym>UMAC</acronym> in <samp>&lt;nettle/umac.h&gt;</samp>.
3948 </p>
3949 <dl>
3950 <dt><a name="index-struct-umac32_005fctx"></a>Context struct: <strong>struct umac32_ctx</strong></dt>
3951 <dt><a name="index-struct-umac64_005fctx"></a>Context struct: <strong>struct umac64_ctx</strong></dt>
3952 <dt><a name="index-struct-umac96_005fctx"></a>Context struct: <strong>struct umac96_ctx</strong></dt>
3953 <dt><a name="index-struct-umac128_005fctx"></a>Context struct: <strong>struct umac128_ctx</strong></dt>
3954 <dd><p>Each <acronym>UMAC</acronym> variant uses its own context struct.
3955 </p></dd></dl>
3956
3957 <dl>
3958 <dt><a name="index-UMAC_005fKEY_005fSIZE"></a>Constant: <strong>UMAC_KEY_SIZE</strong></dt>
3959 <dd><p>The UMAC key size, 16.
3960 </p></dd></dl>
3961 <dl>
3962 <dt><a name="index-UMAC_005fMIN_005fNONCE_005fSIZE"></a>Constant: <strong>UMAC_MIN_NONCE_SIZE</strong></dt>
3963 <dt><a name="index-UMAC_005fMAX_005fNONCE_005fSIZE"></a>Constant: <strong>UMAC_MAX_NONCE_SIZE</strong></dt>
3964 <dd><p>The the minimum and maximum sizes for an UMAC nonce, 1 and 16,
3965 respectively.
3966 </p></dd></dl>
3967 <dl>
3968 <dt><a name="index-UMAC32_005fDIGEST_005fSIZE"></a>Constant: <strong>UMAC32_DIGEST_SIZE</strong></dt>
3969 <dd><p>The size of an UMAC32 digest, 4.
3970 </p></dd></dl>
3971 <dl>
3972 <dt><a name="index-UMAC64_005fDIGEST_005fSIZE"></a>Constant: <strong>UMAC64_DIGEST_SIZE</strong></dt>
3973 <dd><p>The size of an UMAC64 digest, 8.
3974 </p></dd></dl>
3975 <dl>
3976 <dt><a name="index-UMAC96_005fDIGEST_005fSIZE"></a>Constant: <strong>UMAC96_DIGEST_SIZE</strong></dt>
3977 <dd><p>The size of an UMAC96 digest, 12.
3978 </p></dd></dl>
3979 <dl>
3980 <dt><a name="index-UMAC128_005fDIGEST_005fSIZE"></a>Constant: <strong>UMAC128_DIGEST_SIZE</strong></dt>
3981 <dd><p>The size of an UMAC128 digest, 16.
3982 </p></dd></dl>
3983 <dl>
3984 <dt><a name="index-UMAC_005fBLOCK_005fSIZE"></a>Constant: <strong>UMAC_BLOCK_SIZE</strong></dt>
3985 <dd><p>The internal block size of UMAC.
3986 </p></dd></dl>
3987
3988 <dl>
3989 <dt><a name="index-umac32_005fset_005fkey"></a>Function: <em>void</em> <strong>umac32_set_key</strong> <em>(struct umac32_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
3990 <dt><a name="index-umac64_005fset_005fkey"></a>Function: <em>void</em> <strong>umac64_set_key</strong> <em>(struct umac64_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
3991 <dt><a name="index-umac96_005fset_005fkey"></a>Function: <em>void</em> <strong>umac96_set_key</strong> <em>(struct umac96_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
3992 <dt><a name="index-umac128_005fset_005fkey"></a>Function: <em>void</em> <strong>umac128_set_key</strong> <em>(struct umac128_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
3993 <dd><p>These functions initialize the <acronym>UMAC</acronym> context struct. They also
3994 initialize the nonce to zero (with length 16, for auto-increment).
3995 </p></dd></dl>
3996
3997 <dl>
3998 <dt><a name="index-umac32_005fset_005fnonce"></a>Function: <em>void</em> <strong>umac32_set_nonce</strong> <em>(struct umac32_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>nonce</var>)</em></dt>
3999 <dt><a name="index-umac64_005fset_005fnonce"></a>Function: <em>void</em> <strong>umac64_set_nonce</strong> <em>(struct umac64_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>nonce</var>)</em></dt>
4000 <dt><a name="index-umac96_005fset_005fnonce"></a>Function: <em>void</em> <strong>umac96_set_nonce</strong> <em>(struct umac96_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>nonce</var>)</em></dt>
4001 <dt><a name="index-umac128_005fset_005fnonce"></a>Function: <em>void</em> <strong>umac128_set_nonce</strong> <em>(struct umac128_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>nonce</var>)</em></dt>
4002 <dd><p>Sets the nonce to be used for the next message. In general, nonces
4003 should be set before processing of the message. This is not strictly
4004 required for <acronym>UMAC</acronym> (the nonce only affects the final processing
4005 generating the digest), but it is nevertheless recommended that this
4006 function is called <em>before</em> the first <code>_update</code> call for the
4007 message.
4008 </p></dd></dl>
4009
4010 <dl>
4011 <dt><a name="index-umac32_005fupdate"></a>Function: <em>void</em> <strong>umac32_update</strong> <em>(struct umac32_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
4012 <dt><a name="index-umac64_005fupdate"></a>Function: <em>void</em> <strong>umac64_update</strong> <em>(struct umac64_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
4013 <dt><a name="index-umac96_005fupdate"></a>Function: <em>void</em> <strong>umac96_update</strong> <em>(struct umac96_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
4014 <dt><a name="index-umac128_005fupdate"></a>Function: <em>void</em> <strong>umac128_update</strong> <em>(struct umac128_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
4015 <dd><p>These functions are called zero or more times to process the message.
4016 </p></dd></dl>
4017
4018 <dl>
4019 <dt><a name="index-umac32_005fdigest"></a>Function: <em>void</em> <strong>umac32_digest</strong> <em>(struct umac32_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
4020 <dt><a name="index-umac64_005fdigest"></a>Function: <em>void</em> <strong>umac64_digest</strong> <em>(struct umac64_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
4021 <dt><a name="index-umac96_005fdigest"></a>Function: <em>void</em> <strong>umac96_digest</strong> <em>(struct umac96_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
4022 <dt><a name="index-umac128_005fdigest"></a>Function: <em>void</em> <strong>umac128_digest</strong> <em>(struct umac128_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
4023 <dd><p>Extracts the <acronym>MAC</acronym> of the message, writing it to <var>digest</var>.
4024 <var>length</var> is usually equal to the specified output size, but if you
4025 provide a smaller value, only the first <var>length</var> octets of the
4026 <acronym>MAC</acronym> are written. These functions reset the context for
4027 processing of a new message with the same key. The nonce is incremented
4028 as described above, the new value is used unless you call the
4029 <code>_set_nonce</code> function explicitly for each message.
4030 </p></dd></dl>
4031
4032 <hr>
4033 <a name="Poly1305"></a>
4034 <div class="header">
4035 <p>
4036 Previous: <a href="#UMAC" accesskey="p" rel="prev">UMAC</a>, Up: <a href="#Keyed-hash-functions" accesskey="u" rel="up">Keyed hash functions</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
4037 </div>
4038 <a name="Poly1305-1"></a>
4039 <h4 class="subsection">6.5.4 Poly1305</h4>
4040
4041 <p>Poly1305-<acronym>AES</acronym> is a message authentication code designed by D. J.
4042 Bernstein. It treats the message as a polynomial modulo the prime number
4043 <em>2^130 - 5</em>.
4044 </p>
4045 <p>The key, 256 bits, consists of two parts, where the first half is an
4046 <acronym>AES</acronym>-128 key, and the second half specifies the point where the
4047 polynomial is evaluated. Of the latter half, 22 bits are set to zero, to
4048 enable high-performance implementation, leaving 106 bits for specifying
4049 an evaluation point <code>r</code>. For each message, one must also provide a
4050 128-bit nonce. The nonce is encrypted using the <acronym>AES</acronym> key, and
4051 that&rsquo;s the only thing <acronym>AES</acronym> is used for.
4052 </p>
4053 <p>The message is split into 128-bit chunks (with final chunk possibly
4054 being shorter), each read as a little-endian integer. Each chunk has a
4055 one-bit appended at the high end. The resulting integers are treated as
4056 polynomial coefficients modulo <em>2^130 - 5</em>, and the polynomial is
4057 evaluated at the point <code>r</code>. Finally, this value is reduced modulo
4058 <em>2^128</em>, and added (also modulo <em>2^128</em>) to the encrypted
4059 nonce, to produce an 128-bit authenticator for the message. See
4060 <a href="http://cr.yp.to/mac/poly1305-20050329.pdf">http://cr.yp.to/mac/poly1305-20050329.pdf</a> for further details.
4061 </p>
4062 <p>Clearly, variants using a different cipher than <acronym>AES</acronym> could be
4063 defined. Another variant is the ChaCha-Poly1305 <acronym>AEAD</acronym>
4064 construction (see <a href="#ChaCha_002dPoly1305">ChaCha-Poly1305</a>). Nettle defines
4065 Poly1305-<acronym>AES</acronym> in <samp>nettle/poly1305.h</samp>.
4066 </p>
4067 <dl>
4068 <dt><a name="index-POLY1305_005fAES_005fKEY_005fSIZE"></a>Constant: <strong>POLY1305_AES_KEY_SIZE</strong></dt>
4069 <dd><p>Key size, 32 octets.
4070 </p></dd></dl>
4071
4072 <dl>
4073 <dt><a name="index-POLY1305_005fAES_005fDIGEST_005fSIZE"></a>Constant: <strong>POLY1305_AES_DIGEST_SIZE</strong></dt>
4074 <dd><p>Size of the digest or &ldquo;authenticator&rdquo;, 16 octets.
4075 </p></dd></dl>
4076
4077 <dl>
4078 <dt><a name="index-POLY1305_005fAES_005fNONCE_005fSIZE"></a>Constant: <strong>POLY1305_AES_NONCE_SIZE</strong></dt>
4079 <dd><p>Nonce size, 16 octets.
4080 </p></dd></dl>
4081
4082 <dl>
4083 <dt><a name="index-struct-poly1305_005faes_005fctx"></a>Context struct: <strong>struct poly1305_aes_ctx</strong></dt>
4084 <dd><p>The poly1305-aes context struct.
4085 </p></dd></dl>
4086
4087 <dl>
4088 <dt><a name="index-poly1305_005faes_005fset_005fkey"></a>Function: <em>void</em> <strong>poly1305_aes_set_key</strong> <em>(struct poly1305_aes_ctx *<var>ctx</var>, const uint8_t *<var>key</var>)</em></dt>
4089 <dd><p>Initialize the context struct. Also sets the nonce to zero.
4090 </p></dd></dl>
4091
4092 <dl>
4093 <dt><a name="index-poly1305_005faes_005fset_005fnonce"></a>Function: <em>void</em> <strong>poly1305_aes_set_nonce</strong> <em>(struct poly1305_aes_ctx *<var>ctx</var>, const uint8_t *<var>nonce</var>)</em></dt>
4094 <dd><p>Sets the nonce. Calling this function is optional, since the nonce is
4095 incremented automatically for each message.
4096 </p></dd></dl>
4097
4098 <dl>
4099 <dt><a name="index-poly1305_005faes_005fupdate"></a>Function: <em>void</em> <strong>poly1305_aes_update</strong> <em>(struct poly1305_aes_ctx *<var>ctx</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
4100 <dd><p>Process more data.
4101 </p></dd></dl>
4102
4103 <dl>
4104 <dt><a name="index-poly1305_005faes_005fdigest"></a>Function: <em>void</em> <strong>poly1305_aes_digest</strong> <em>(struct poly1305_aes_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>digest</var>)</em></dt>
4105 <dd><p>Extracts the digest. If <var>length</var> is smaller than
4106 <code>POLY1305_AES_DIGEST_SIZE</code>, only the first <var>length</var> octets are
4107 written. Also increments the nonce, and prepares the context for
4108 processing a new message.
4109 </p></dd></dl>
4110
4111
4112 <hr>
4113 <a name="Key-derivation-functions"></a>
4114 <div class="header">
4115 <p>
4116 Next: <a href="#Public_002dkey-algorithms" accesskey="n" rel="next">Public-key algorithms</a>, Previous: <a href="#Keyed-hash-functions" accesskey="p" rel="prev">Keyed hash functions</a>, Up: <a href="#Reference" accesskey="u" rel="up">Reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
4117 </div>
4118 <a name="Key-derivation-Functions"></a>
4119 <h3 class="section">6.6 Key derivation Functions</h3>
4120
4121 <a name="index-Key-Derivation-Function"></a>
4122 <a name="index-Password-Based-Key-Derivation-Function"></a>
4123 <a name="index-PKCS-_00235"></a>
4124 <a name="index-KDF"></a>
4125 <a name="index-PBKDF"></a>
4126
4127 <p>A <em>key derivation function</em> (<acronym>KDF</acronym>) is a function that from
4128 a given symmetric key derives other symmetric keys.  A sub-class of KDFs
4129 is the <em>password-based key derivation functions</em> (<acronym>PBKDFs</acronym>),
4130 which take as input a password or passphrase, and its purpose is
4131 typically to strengthen it and protect against certain pre-computation
4132 attacks by using salting and expensive computation.
4133 </p>
4134 <a name="PBKDF2"></a>
4135 <h4 class="subsection">6.6.1 <acronym>PBKDF2</acronym></h4>
4136 <p>The most well known PBKDF is the <code>PKCS #5 PBKDF2</code> described in
4137 <cite>RFC 2898</cite> which uses a pseudo-random function such as
4138 <acronym>HMAC-SHA1</acronym>.
4139 </p>
4140 <p>Nettle&rsquo;s <acronym>PBKDF2</acronym> functions are defined in
4141 <samp>&lt;nettle/pbkdf2.h&gt;</samp>.  There is an abstract function that operate on
4142 any PRF implemented via the <code>nettle_hash_update_func</code>,
4143 <code>nettle_hash_digest_func</code> interfaces.  There is also helper macros
4144 and concrete functions PBKDF2-HMAC-SHA1 and PBKDF2-HMAC-SHA256.  First,
4145 the abstract function:
4146 </p>
4147 <dl>
4148 <dt><a name="index-pbkdf2"></a>Function: <em>void</em> <strong>pbkdf2</strong> <em>(void *mac_ctx, nettle_hash_update_func *update, nettle_hash_digest_func *digest, size_t digest_size, unsigned iterations, size_t salt_length, const uint8_t *salt, size_t length, uint8_t *dst)</em></dt>
4149 <dd><p>Derive symmetric key from a password according to PKCS #5 PBKDF2.  The
4150 PRF is assumed to have been initialized and this function will call the
4151 <var>update</var> and <var>digest</var> functions passing the <var>mac_ctx</var>
4152 context parameter as an argument in order to compute digest of size
4153 <var>digest_size</var>.  Inputs are the salt <var>salt</var> of length
4154 <var>salt_length</var>, the iteration counter <var>iterations</var> (&gt; 0), and the
4155 desired derived output length <var>length</var>.  The output buffer is
4156 <var>dst</var> which must have room for at least <var>length</var> octets.
4157 </p></dd></dl>
4158
4159 <p>Like for CBC and HMAC, there is a macro to help use the function
4160 correctly.
4161 </p>
4162 <dl>
4163 <dt><a name="index-PBKDF2"></a>Macro: <strong>PBKDF2</strong> <em>(<var>ctx</var>, <var>update</var>, <var>digest</var>, <var>digest_size</var>, <var>iterations</var>, <var>salt_length</var>, <var>salt</var>, <var>length</var>, <var>dst</var>)</em></dt>
4164 <dd><p><var>ctx</var> is a pointer to a context struct passed to the <var>update</var>
4165 and <var>digest</var> functions (of the types <code>nettle_hash_update_func</code>
4166 and <code>nettle_hash_digest_func</code> respectively) to implement the
4167 underlying PRF with digest size of <var>digest_size</var>.  Inputs are the
4168 salt <var>salt</var> of length <var>salt_length</var>, the iteration counter
4169 <var>iterations</var> (&gt; 0), and the desired derived output length
4170 <var>length</var>.  The output buffer is <var>dst</var> which must have room for
4171 at least <var>length</var> octets.
4172 </p></dd></dl>
4173
4174 <a name="Concrete-PBKDF2-functions"></a>
4175 <h4 class="subsection">6.6.2 Concrete <acronym>PBKDF2</acronym> functions</h4>
4176 <p>Now we come to the specialized <acronym>PBKDF2</acronym> functions, which are
4177 easier to use than the general <acronym>PBKDF2</acronym> function.
4178 </p>
4179 <a name="PBKDF2_002dHMAC_002dSHA1"></a>
4180 <h4 class="subsubsection">6.6.2.1 <acronym>PBKDF2-HMAC-SHA1</acronym></h4>
4181
4182 <dl>
4183 <dt><a name="index-pbkdf2_005fhmac_005fsha1"></a>Function: <em>void</em> <strong>pbkdf2_hmac_sha1</strong> <em>(size_t <var>key_length</var>, const uint8_t *<var>key</var>, unsigned <var>iterations</var>, size_t <var>salt_length</var>, const uint8_t *<var>salt</var>, size_t <var>length</var>, uint8_t *<var>dst</var>)</em></dt>
4184 <dd><p>PBKDF2 with HMAC-SHA1.  Derive <var>length</var> bytes of key into buffer
4185 <var>dst</var> using the password <var>key</var> of length <var>key_length</var> and
4186 salt <var>salt</var> of length <var>salt_length</var>, with iteration counter
4187 <var>iterations</var> (&gt; 0).  The output buffer is <var>dst</var> which must have
4188 room for at least <var>length</var> octets.
4189 </p></dd></dl>
4190
4191 <a name="PBKDF2_002dHMAC_002dSHA256"></a>
4192 <h4 class="subsubsection">6.6.2.2 <acronym>PBKDF2-HMAC-SHA256</acronym></h4>
4193
4194 <dl>
4195 <dt><a name="index-pbkdf2_005fhmac_005fsha256"></a>Function: <em>void</em> <strong>pbkdf2_hmac_sha256</strong> <em>(size_t <var>key_length</var>, const uint8_t *<var>key</var>, unsigned <var>iterations</var>, size_t <var>salt_length</var>, const uint8_t *<var>salt</var>, size_t <var>length</var>, uint8_t *<var>dst</var>)</em></dt>
4196 <dd><p>PBKDF2 with HMAC-SHA256.  Derive <var>length</var> bytes of key into buffer
4197 <var>dst</var> using the password <var>key</var> of length <var>key_length</var> and
4198 salt <var>salt</var> of length <var>salt_length</var>, with iteration counter
4199 <var>iterations</var> (&gt; 0).  The output buffer is <var>dst</var> which must have
4200 room for at least <var>length</var> octets.
4201 </p></dd></dl>
4202
4203 <hr>
4204 <a name="Public_002dkey-algorithms"></a>
4205 <div class="header">
4206 <p>
4207 Next: <a href="#Randomness" accesskey="n" rel="next">Randomness</a>, Previous: <a href="#Key-derivation-functions" accesskey="p" rel="prev">Key derivation functions</a>, Up: <a href="#Reference" accesskey="u" rel="up">Reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
4208 </div>
4209 <a name="Public_002dkey-algorithms-1"></a>
4210 <h3 class="section">6.7 Public-key algorithms</h3>
4211
4212 <p>Nettle uses <acronym>GMP</acronym>, the GNU bignum library, for all calculations
4213 with large numbers. In order to use the public-key features of Nettle,
4214 you must install <acronym>GMP</acronym>, at least version 3.0, before compiling
4215 Nettle, and you need to link your programs with <code>-lhogweed -lnettle
4216 -lgmp</code>.
4217 </p>
4218 <p>The concept of <em>Public-key</em> encryption and digital signatures was
4219 discovered by Whitfield Diffie and Martin E. Hellman and described in a
4220 paper 1976. In traditional, &ldquo;symmetric&rdquo;, cryptography, sender and
4221 receiver share the same keys, and these keys must be distributed in a
4222 secure way. And if there are many users or entities that need to
4223 communicate, each <em>pair</em> needs a shared secret key known by nobody
4224 else.
4225 </p>
4226 <a name="index-Public-Key-Cryptography"></a>
4227 <a name="index-One_002dway-function"></a>
4228
4229 <p>Public-key cryptography uses trapdoor one-way functions. A
4230 <em>one-way function</em> is a function <code>F</code> such that it is easy to
4231 compute the value <code>F(x)</code> for any <code>x</code>, but given a value
4232 <code>y</code>, it is hard to compute a corresponding <code>x</code> such that
4233 <code>y = F(x)</code>. Two examples are cryptographic hash functions, and
4234 exponentiation in certain groups.
4235 </p>
4236 <p>A <em>trapdoor one-way function</em> is a function <code>F</code> that is
4237 one-way, unless one knows some secret information about <code>F</code>. If one
4238 knows the secret, it is easy to compute both <code>F</code> and it&rsquo;s inverse.
4239 If this sounds strange, look at the <acronym>RSA</acronym> example below.
4240 </p>
4241 <p>Two important uses for one-way functions with trapdoors are public-key
4242 encryption, and digital signatures. The public-key encryption functions
4243 in Nettle are not yet documented; the rest of this chapter is about
4244 digital signatures.
4245 </p>
4246 <p>To use a digital signature algorithm, one must first create a
4247 <em>key-pair</em>: A public key and a corresponding private key. The private
4248 key is used to sign messages, while the public key is used for verifying
4249 that that signatures and messages match. Some care must be taken when
4250 distributing the public key; it need not be kept secret, but if a bad
4251 guy is able to replace it (in transit, or in some user&rsquo;s list of known
4252 public keys), bad things may happen.
4253 </p>
4254 <p>There are two operations one can do with the keys. The signature
4255 operation takes a message and a private key, and creates a signature for
4256 the message. A signature is some string of bits, usually at most a few
4257 thousand bits or a few hundred octets. Unlike paper-and-ink signatures,
4258 the digital signature depends on the message, so one can&rsquo;t cut it out of
4259 context and glue it to a different message.
4260 </p>
4261 <p>The verification operation takes a public key, a message, and a string
4262 that is claimed to be a signature on the message, and returns true or
4263 false. If it returns true, that means that the three input values
4264 matched, and the verifier can be sure that someone went through with the
4265 signature operation on that very message, and that the &ldquo;someone&rdquo; also
4266 knows the private key corresponding to the public key.
4267 </p>
4268 <p>The desired properties of a digital signature algorithm are as follows:
4269 Given the public key and pairs of messages and valid signatures on them,
4270 it should be hard to compute the private key, and it should also be hard
4271 to create a new message and signature that is accepted by the
4272 verification operation.
4273 </p>
4274 <p>Besides signing meaningful messages, digital signatures can be used for
4275 authorization. A server can be configured with a public key, such that
4276 any client that connects to the service is given a random nonce message.
4277 If the server gets a reply with a correct signature matching the nonce
4278 message and the configured public key, the client is granted access. So
4279 the configuration of the server can be understood as &ldquo;grant access to
4280 whoever knows the private key corresponding to this particular public
4281 key, and to no others&rdquo;.
4282 </p>
4283
4284 <table class="menu" border="0" cellspacing="0">
4285 <tr><td align="left" valign="top">&bull; <a href="#RSA" accesskey="1">RSA</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">The RSA public key algorithm.
4286 </td></tr>
4287 <tr><td align="left" valign="top">&bull; <a href="#DSA" accesskey="2">DSA</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">The DSA digital signature algorithm.
4288 </td></tr>
4289 <tr><td align="left" valign="top">&bull; <a href="#Elliptic-curves" accesskey="3">Elliptic curves</a>:</td><td>&nbsp;&nbsp;</td><td align="left" valign="top">Elliptic curves and ECDSA
4290 </td></tr>
4291 </table>
4292
4293 <hr>
4294 <a name="RSA"></a>
4295 <div class="header">
4296 <p>
4297 Next: <a href="#DSA" accesskey="n" rel="next">DSA</a>, Previous: <a href="#Public_002dkey-algorithms" accesskey="p" rel="prev">Public-key algorithms</a>, Up: <a href="#Public_002dkey-algorithms" accesskey="u" rel="up">Public-key algorithms</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
4298 </div>
4299 <a name="RSA-1"></a>
4300 <h4 class="subsection">6.7.1 <acronym>RSA</acronym></h4>
4301
4302 <p>The <acronym>RSA</acronym> algorithm was the first practical digital signature
4303 algorithm that was constructed. It was described 1978 in a paper by
4304 Ronald Rivest, Adi Shamir and L.M. Adleman, and the technique was also
4305 patented in the <acronym>USA</acronym> in 1983. The patent expired on September 20, 2000, and since
4306 that day, <acronym>RSA</acronym> can be used freely, even in the <acronym>USA</acronym>.
4307 </p>
4308 <p>It&rsquo;s remarkably simple to describe the trapdoor function behind
4309 <acronym>RSA</acronym>. The &ldquo;one-way&rdquo;-function used is
4310 </p>
4311 <div class="example">
4312 <pre class="example">F(x) = x^e mod n
4313 </pre></div>
4314
4315 <p>I.e. raise x to the <code>e</code>&rsquo;th power, while discarding all multiples of
4316 <code>n</code>. The pair of numbers <code>n</code> and <code>e</code> is the public key.
4317 <code>e</code> can be quite small, even <code>e = 3</code> has been used, although
4318 slightly larger numbers are recommended. <code>n</code> should be about 2000
4319 bits or larger.
4320 </p>
4321 <p>If <code>n</code> is large enough, and properly chosen, the inverse of F,
4322 the computation of <code>e</code>&rsquo;th roots modulo <code>n</code>, is very difficult.
4323 But, where&rsquo;s the trapdoor?
4324 </p>
4325 <p>Let&rsquo;s first look at how <acronym>RSA</acronym> key-pairs are generated. First
4326 <code>n</code> is chosen as the product of two large prime numbers <code>p</code>
4327 and <code>q</code> of roughly the same size (so if <code>n</code> is 2000 bits,
4328 <code>p</code> and <code>q</code> are about 1000 bits each). One also computes the
4329 number <code>phi = (p-1)(q-1)</code>, in mathematical speak, <code>phi</code> is the
4330 order of the multiplicative group of integers modulo n.
4331 </p>
4332 <p>Next, <code>e</code> is chosen. It must have no factors in common with <code>phi</code> (in
4333 particular, it must be odd), but can otherwise be chosen more or less
4334 randomly. <code>e = 65537</code> is a popular choice, because it makes raising
4335 to the <code>e</code>&rsquo;th power particularly efficient, and being prime, it
4336 usually has no factors common with <code>phi</code>.
4337 </p>
4338 <p>Finally, a number <code>d</code>, <code>d &lt; n</code> is computed such that <code>e d
4339 mod phi = 1</code>. It can be shown that such a number exists (this is why
4340 <code>e</code> and <code>phi</code> must have no common factors), and that for all x,
4341 </p>
4342 <div class="example">
4343 <pre class="example">(x^e)^d mod n = x^(ed) mod n = (x^d)^e mod n = x
4344 </pre></div>
4345
4346 <p>Using Euclid&rsquo;s algorithm, <code>d</code> can be computed quite easily from
4347 <code>phi</code> and <code>e</code>. But it is still hard to get <code>d</code> without
4348 knowing <code>phi</code>, which depends on the factorization of <code>n</code>.
4349 </p>
4350 <p>So <code>d</code> is the trapdoor, if we know <code>d</code> and <code>y = F(x)</code>, we can
4351 recover x as <code>y^d mod n</code>. <code>d</code> is also the private half of
4352 the <acronym>RSA</acronym> key-pair.
4353 </p>
4354 <p>The most common signature operation for <acronym>RSA</acronym> is defined in
4355 <cite>PKCS#1</cite>, a specification by RSA Laboratories. The message to be
4356 signed is first hashed using a cryptographic hash function, e.g.
4357 <acronym>MD5</acronym> or <acronym>SHA1</acronym>. Next, some padding, the <acronym>ASN.1</acronym>
4358 &ldquo;Algorithm Identifier&rdquo; for the hash function, and the message digest
4359 itself, are concatenated and converted to a number <code>x</code>. The
4360 signature is computed from <code>x</code> and the private key as <code>s = x^d
4361 mod n</code><a name="DOCF1" href="#FOOT1"><sup>1</sup></a>. The signature, <code>s</code> is a
4362 number of about the same size of <code>n</code>, and it usually encoded as a
4363 sequence of octets, most significant octet first.
4364 </p>
4365 <p>The verification operation is straight-forward, <code>x</code> is computed
4366 from the message in the same way as above. Then <code>s^e mod n</code> is
4367 computed, the operation returns true if and only if the result equals
4368 <code>x</code>.
4369 </p>
4370 <p>The <acronym>RSA</acronym> algorithm can also be used for encryption. RSA encryption uses
4371 the public key <code>(n,e)</code> to compute the ciphertext <code>m^e mod n</code>.
4372 The <cite>PKCS#1</cite> padding scheme will use at least 8 random and non-zero
4373 octets, using <var>m</var> of the form <code>[00 02 padding 00 plaintext]</code>.
4374 It is required that <code>m &lt; n</code>, and therefor the plaintext must be
4375 smaller than the octet size of the modulo <code>n</code>, with some margin.
4376 </p>
4377 <p>To decrypt the message, one needs the private key to compute <code>m =
4378 c^e mod n</code> followed by checking and removing the padding.
4379 </p>
4380 <a name="Nettle_0027s-RSA-support"></a>
4381 <h4 class="subsubsection">6.7.1.1 Nettle&rsquo;s <acronym>RSA</acronym> support</h4>
4382
4383 <p>Nettle represents <acronym>RSA</acronym> keys using two structures that contain
4384 large numbers (of type <code>mpz_t</code>).
4385 </p>
4386 <dl>
4387 <dt><a name="index-rsa_005fpublic_005fkey"></a>Context struct: <strong>rsa_public_key</strong> <em>size n e</em></dt>
4388 <dd><p><code>size</code> is the size, in octets, of the modulo, and is used internally.
4389 <code>n</code> and <code>e</code> is the public key.
4390 </p></dd></dl>
4391
4392 <dl>
4393 <dt><a name="index-rsa_005fprivate_005fkey"></a>Context struct: <strong>rsa_private_key</strong> <em>size d p q a b c</em></dt>
4394 <dd><p><code>size</code> is the size, in octets, of the modulo, and is used internally.
4395 <code>d</code> is the secret exponent, but it is not actually used when
4396 signing. Instead, the factors <code>p</code> and <code>q</code>, and the parameters
4397 <code>a</code>, <code>b</code> and <code>c</code> are used. They are computed from <code>p</code>,
4398 <code>q</code> and <code>e</code> such that <code>a e mod (p - 1) = 1, b e mod (q -
4399 1) = 1, c q mod p = 1</code>.
4400 </p></dd></dl>
4401
4402 <p>Before use, these structs must be initialized by calling one of
4403 </p>
4404 <dl>
4405 <dt><a name="index-rsa_005fpublic_005fkey_005finit"></a>Function: <em>void</em> <strong>rsa_public_key_init</strong> <em>(struct rsa_public_key *<var>pub</var>)</em></dt>
4406 <dt><a name="index-rsa_005fprivate_005fkey_005finit"></a>Function: <em>void</em> <strong>rsa_private_key_init</strong> <em>(struct rsa_private_key *<var>key</var>)</em></dt>
4407 <dd><p>Calls <code>mpz_init</code> on all numbers in the key struct.
4408 </p></dd></dl>
4409
4410 <p>and when finished with them, the space for the numbers must be
4411 deallocated by calling one of
4412 </p>
4413 <dl>
4414 <dt><a name="index-rsa_005fpublic_005fkey_005fclear"></a>Function: <em>void</em> <strong>rsa_public_key_clear</strong> <em>(struct rsa_public_key *<var>pub</var>)</em></dt>
4415 <dt><a name="index-rsa_005fprivate_005fkey_005fclear"></a>Function: <em>void</em> <strong>rsa_private_key_clear</strong> <em>(struct rsa_private_key *<var>key</var>)</em></dt>
4416 <dd><p>Calls <code>mpz_clear</code> on all numbers in the key struct.
4417 </p></dd></dl>
4418
4419 <p>In general, Nettle&rsquo;s <acronym>RSA</acronym> functions deviates from Nettle&rsquo;s &ldquo;no
4420 memory allocation&rdquo;-policy. Space for all the numbers, both in the key structs
4421 above, and temporaries, are allocated dynamically. For information on how
4422 to customize allocation, see
4423 See <a href="http://www.gmplib.org/manual/Custom-Allocation.html#Custom-Allocation">GMP Allocation</a> in <cite>GMP Manual</cite>.
4424 </p>
4425 <p>When you have assigned values to the attributes of a key, you must call
4426 </p>
4427 <dl>
4428 <dt><a name="index-rsa_005fpublic_005fkey_005fprepare"></a>Function: <em>int</em> <strong>rsa_public_key_prepare</strong> <em>(struct rsa_public_key *<var>pub</var>)</em></dt>
4429 <dt><a name="index-rsa_005fprivate_005fkey_005fprepare"></a>Function: <em>int</em> <strong>rsa_private_key_prepare</strong> <em>(struct rsa_private_key *<var>key</var>)</em></dt>
4430 <dd><p>Computes the octet size of the key (stored in the <code>size</code> attribute,
4431 and may also do other basic sanity checks. Returns one if successful, or
4432 zero if the key can&rsquo;t be used, for instance if the modulo is smaller
4433 than the minimum size needed for <acronym>RSA</acronym> operations specified by PKCS#1.
4434 </p></dd></dl>
4435
4436 <p>For each operation using the private key, there are two variants, e.g.,
4437 <code>rsa_sha256_sign</code> and <code>rsa_sha256_sign_tr</code>. The former
4438 function is older, and it should be avoided, because it provides no
4439 defenses against side-channel attacks. The latter function use
4440 randomized <acronym>RSA</acronym> blinding, which defends against timing attacks
4441 using chosen-ciphertext, and it also checks the correctness of the
4442 private key computation using the public key, which defends against
4443 software or hardware errors which could leak the private key.
4444 </p>
4445 <p>Before signing or verifying a message, you first hash it with the
4446 appropriate hash function. You pass the hash function&rsquo;s context struct
4447 to the <acronym>RSA</acronym> signature function, and it will extract the message
4448 digest and do the rest of the work. There are also alternative functions
4449 that take the hash digest as argument.
4450 </p>
4451 <p>There is currently no support for using SHA224 or SHA384 with
4452 <acronym>RSA</acronym> signatures, since there&rsquo;s no gain in either computation
4453 time nor message size compared to using SHA256 and SHA512, respectively.
4454 </p>
4455 <p>Creating an <acronym>RSA</acronym> signature is done with one of the following
4456 functions:
4457 </p>
4458 <dl>
4459 <dt><a name="index-rsa_005fmd5_005fsign_005ftr_0028const"></a>Function: <em>int</em> <strong>rsa_md5_sign_tr(const</strong> <em>struct rsa_public_key *<var>pub</var>, const struct rsa_private_key *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func *<var>random</var>, struct md5_ctx *<var>hash</var>, mpz_t <var>signature</var>)</em></dt>
4460 <dt><a name="index-rsa_005fsha1_005fsign_005ftr_0028const"></a>Function: <em>int</em> <strong>rsa_sha1_sign_tr(const</strong> <em>struct rsa_public_key *<var>pub</var>, const struct rsa_private_key *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func *<var>random</var>, struct sha1_ctx *<var>hash</var>, mpz_t <var>signature</var>)</em></dt>
4461 <dt><a name="index-rsa_005fsha256_005fsign_005ftr_0028const"></a>Function: <em>int</em> <strong>rsa_sha256_sign_tr(const</strong> <em>struct rsa_public_key *<var>pub</var>, const struct rsa_private_key *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func *<var>random</var>, struct sha256_ctx *<var>hash</var>, mpz_t <var>signature</var>)</em></dt>
4462 <dt><a name="index-rsa_005fsha512_005fsign_005ftr_0028const"></a>Function: <em>int</em> <strong>rsa_sha512_sign_tr(const</strong> <em>struct rsa_public_key *<var>pub</var>, const struct rsa_private_key *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func *<var>random</var>, struct sha512_ctx *<var>hash</var>, mpz_t <var>signature</var>)</em></dt>
4463 <dd><p>The signature is stored in <var>signature</var> (which must have been
4464 <code>mpz_init</code>&rsquo;ed earlier). The hash context is reset so that it can be
4465 used for new messages. The <var>random_ctx</var> and <var>random</var> pointers
4466 are used to generate the <acronym>RSA</acronym> blinding. Returns one on success,
4467 or zero on failure. Signing fails if an error in the computation was
4468 detected, or if the key is too small for the given hash size, e.g., it&rsquo;s
4469 not possible to create a signature using SHA512 and a 512-bit
4470 <acronym>RSA</acronym> key.
4471 </p></dd></dl>
4472
4473 <dl>
4474 <dt><a name="index-rsa_005fmd5_005fsign_005fdigest_005ftr_0028const"></a>Function: <em>int</em> <strong>rsa_md5_sign_digest_tr(const</strong> <em>struct rsa_public_key *<var>pub</var>, const struct rsa_private_key *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func *<var>random</var>, const uint8_t *<var>digest</var>, mpz_t <var>signature</var>)</em></dt>
4475 <dt><a name="index-rsa_005fsha1_005fsign_005fdigest_005ftr_0028const"></a>Function: <em>int</em> <strong>rsa_sha1_sign_digest_tr(const</strong> <em>struct rsa_public_key *<var>pub</var>, const struct rsa_private_key *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func *<var>random</var>, const uint8_t *<var>digest</var>, mpz_t <var>signature</var>)</em></dt>
4476 <dt><a name="index-rsa_005fsha256_005fsign_005fdigest_005ftr_0028const"></a>Function: <em>int</em> <strong>rsa_sha256_sign_digest_tr(const</strong> <em>struct rsa_public_key *<var>pub</var>, const struct rsa_private_key *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func *<var>random</var>, const uint8_t *<var>digest</var>, mpz_t <var>signature</var>)</em></dt>
4477 <dt><a name="index-rsa_005fsha512_005fsign_005fdigest_005ftr_0028const"></a>Function: <em>int</em> <strong>rsa_sha512_sign_digest_tr(const</strong> <em>struct rsa_public_key *<var>pub</var>, const struct rsa_private_key *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func *<var>random</var>, const uint8_t *<var>digest</var>, mpz_t <var>signature</var>)</em></dt>
4478 <dd><p>Creates a signature from the given hash digest. <var>digest</var> should
4479 point to a digest of size <code>MD5_DIGEST_SIZE</code>,
4480 <code>SHA1_DIGEST_SIZE</code>, <code>SHA256_DIGEST_SIZE</code>, or
4481 <code>SHA512_DIGEST_SIZE</code>respectively. The signature is stored in
4482 <var>signature</var> (which must have been <code>mpz_init</code>:ed earlier).
4483 Returns one on success, or zero on failure.
4484 </p></dd></dl>
4485
4486 <dl>
4487 <dt><a name="index-rsa_005fpkcs1_005fsign_005ftr_0028const"></a>Function: <em>int</em> <strong>rsa_pkcs1_sign_tr(const</strong> <em>struct rsa_public_key *<var>pub</var>, const struct rsa_private_key *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func *<var>random</var>, size_t <var>length</var>, const uint8_t *<var>digest_info</var>, mpz_t <var>signature</var>)</em></dt>
4488 <dd><p>Similar to the above <code>_sign_digest_tr</code> functions, but the input is not the
4489 plain hash digest, but a PKCS#1 &ldquo;DigestInfo&rdquo;, an ASN.1 DER-encoding
4490 of the digest together with an object identifier for the used hash
4491 algorithm.
4492 </p></dd></dl>
4493
4494 <dl>
4495 <dt><a name="index-rsa_005fmd5_005fsign"></a>Function: <em>int</em> <strong>rsa_md5_sign</strong> <em>(const struct rsa_private_key *<var>key</var>, struct md5_ctx *<var>hash</var>, mpz_t <var>signature</var>)</em></dt>
4496 <dt><a name="index-rsa_005fsha1_005fsign"></a>Function: <em>int</em> <strong>rsa_sha1_sign</strong> <em>(const struct rsa_private_key *<var>key</var>, struct sha1_ctx *<var>hash</var>, mpz_t <var>signature</var>)</em></dt>
4497 <dt><a name="index-rsa_005fsha256_005fsign"></a>Function: <em>int</em> <strong>rsa_sha256_sign</strong> <em>(const struct rsa_private_key *<var>key</var>, struct sha256_ctx *<var>hash</var>, mpz_t <var>signature</var>)</em></dt>
4498 <dt><a name="index-rsa_005fsha512_005fsign"></a>Function: <em>int</em> <strong>rsa_sha512_sign</strong> <em>(const struct rsa_private_key *<var>key</var>, struct sha512_ctx *<var>hash</var>, mpz_t <var>signature</var>)</em></dt>
4499 <dd><p>The signature is stored in <var>signature</var> (which must have been
4500 <code>mpz_init</code>&rsquo;ed earlier). The hash context is reset so that it can be
4501 used for new messages. Returns one on success, or zero on failure.
4502 Signing fails if the key is too small for the given hash size, e.g.,
4503 it&rsquo;s not possible to create a signature using SHA512 and a 512-bit
4504 <acronym>RSA</acronym> key.
4505 </p></dd></dl>
4506
4507 <dl>
4508 <dt><a name="index-rsa_005fmd5_005fsign_005fdigest"></a>Function: <em>int</em> <strong>rsa_md5_sign_digest</strong> <em>(const struct rsa_private_key *<var>key</var>, const uint8_t *<var>digest</var>, mpz_t <var>signature</var>)</em></dt>
4509 <dt><a name="index-rsa_005fsha1_005fsign_005fdigest"></a>Function: <em>int</em> <strong>rsa_sha1_sign_digest</strong> <em>(const struct rsa_private_key *<var>key</var>, const uint8_t *<var>digest</var>, mpz_t <var>signature</var>);</em></dt>
4510 <dt><a name="index-rsa_005fsha256_005fsign_005fdigest"></a>Function: <em>int</em> <strong>rsa_sha256_sign_digest</strong> <em>(const struct rsa_private_key *<var>key</var>, const uint8_t *<var>digest</var>, mpz_t <var>signature</var>);</em></dt>
4511 <dt><a name="index-rsa_005fsha512_005fsign_005fdigest"></a>Function: <em>int</em> <strong>rsa_sha512_sign_digest</strong> <em>(const struct rsa_private_key *<var>key</var>, const uint8_t *<var>digest</var>, mpz_t <var>signature</var>);</em></dt>
4512 <dd><p>Creates a signature from the given hash digest; otherwise analoguous to
4513 the above signing functions. <var>digest</var> should point to a digest of
4514 size <code>MD5_DIGEST_SIZE</code>, <code>SHA1_DIGEST_SIZE</code>,
4515 <code>SHA256_DIGEST_SIZE</code>, or <code>SHA512_DIGEST_SIZE</code>, respectively.
4516 The signature is stored in <var>signature</var> (which must have been
4517 <code>mpz_init</code>:ed earlier). Returns one on success, or zero on failure.
4518 </p></dd></dl>
4519
4520 <dl>
4521 <dt><a name="index-rsa_005fpkcs1_005fsign_0028const"></a>Function: <em>int</em> <strong>rsa_pkcs1_sign(const</strong> <em>struct rsa_private_key *<var>key</var>, size_t <var>length</var>, const uint8_t *<var>digest_info</var>, mpz_t <var>s</var>)</em></dt>
4522 <dd><p>Similar to the above _sign_digest functions, but the input is not the
4523 plain hash digest, but a PKCS#1 &ldquo;DigestInfo&rdquo;, an ASN.1 DER-encoding
4524 of the digest together with an object identifier for the used hash
4525 algorithm.
4526 </p></dd></dl>
4527
4528 <p>Verifying an RSA signature is done with one of the following functions:
4529 </p>
4530 <dl>
4531 <dt><a name="index-rsa_005fmd5_005fverify"></a>Function: <em>int</em> <strong>rsa_md5_verify</strong> <em>(const struct rsa_public_key *<var>key</var>, struct md5_ctx *<var>hash</var>, const mpz_t <var>signature</var>)</em></dt>
4532 <dt><a name="index-rsa_005fsha1_005fverify"></a>Function: <em>int</em> <strong>rsa_sha1_verify</strong> <em>(const struct rsa_public_key *<var>key</var>, struct sha1_ctx *<var>hash</var>, const mpz_t <var>signature</var>)</em></dt>
4533 <dt><a name="index-rsa_005fsha256_005fverify"></a>Function: <em>int</em> <strong>rsa_sha256_verify</strong> <em>(const struct rsa_public_key *<var>key</var>, struct sha256_ctx *<var>hash</var>, const mpz_t <var>signature</var>)</em></dt>
4534 <dt><a name="index-rsa_005fsha512_005fverify"></a>Function: <em>int</em> <strong>rsa_sha512_verify</strong> <em>(const struct rsa_public_key *<var>key</var>, struct sha512_ctx *<var>hash</var>, const mpz_t <var>signature</var>)</em></dt>
4535 <dd><p>Returns 1 if the signature is valid, or 0 if it isn&rsquo;t. In either case,
4536 the hash context is reset so that it can be used for new messages.
4537 </p></dd></dl>
4538
4539 <dl>
4540 <dt><a name="index-rsa_005fmd5_005fverify_005fdigest"></a>Function: <em>int</em> <strong>rsa_md5_verify_digest</strong> <em>(const struct rsa_public_key *<var>key</var>, const uint8_t *<var>digest</var>, const mpz_t <var>signature</var>)</em></dt>
4541 <dt><a name="index-rsa_005fsha1_005fverify_005fdigest"></a>Function: <em>int</em> <strong>rsa_sha1_verify_digest</strong> <em>(const struct rsa_public_key *<var>key</var>, const uint8_t *<var>digest</var>, const mpz_t <var>signature</var>)</em></dt>
4542 <dt><a name="index-rsa_005fsha256_005fverify_005fdigest"></a>Function: <em>int</em> <strong>rsa_sha256_verify_digest</strong> <em>(const struct rsa_public_key *<var>key</var>, const uint8_t *<var>digest</var>, const mpz_t <var>signature</var>)</em></dt>
4543 <dt><a name="index-rsa_005fsha512_005fverify_005fdigest"></a>Function: <em>int</em> <strong>rsa_sha512_verify_digest</strong> <em>(const struct rsa_public_key *<var>key</var>, const uint8_t *<var>digest</var>, const mpz_t <var>signature</var>)</em></dt>
4544 <dd><p>Returns 1 if the signature is valid, or 0 if it isn&rsquo;t. <var>digest</var>
4545 should point to a digest of size <code>MD5_DIGEST_SIZE</code>,
4546 <code>SHA1_DIGEST_SIZE</code>, <code>SHA256_DIGEST_SIZE</code>, or
4547 <code>SHA512_DIGEST_SIZE</code> respectively.
4548 </p></dd></dl>
4549
4550 <dl>
4551 <dt><a name="index-rsa_005fpkcs1_005fverify_0028const"></a>Function: <em>int</em> <strong>rsa_pkcs1_verify(const</strong> <em>struct rsa_public_key *<var>key</var>, size_t <var>length</var>, const uint8_t *<var>digest_info</var>, const mpz_t <var>signature</var>)</em></dt>
4552 <dd><p>Similar to the above _verify_digest functions, but the input is not the
4553 plain hash digest, but a PKCS#1 &ldquo;DigestInfo&rdquo;, and ASN.1 DER-encoding
4554 of the digest together with an object identifier for the used hash
4555 algorithm.
4556 </p></dd></dl>
4557
4558 <p>The following function is used to encrypt a clear text message using RSA.
4559 </p><dl>
4560 <dt><a name="index-rsa_005fencrypt"></a>Function: <em>int</em> <strong>rsa_encrypt</strong> <em>(const struct rsa_public_key *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func *<var>random</var>, size_t <var>length</var>, const uint8_t *<var>cleartext</var>, mpz_t <var>ciphertext</var>)</em></dt>
4561 <dd><p>Returns 1 on success, 0 on failure. If the message is too long then this
4562 will lead to a failure.
4563 </p></dd></dl>
4564 <p>The following function is used to decrypt a cipher text message using RSA.
4565 </p><dl>
4566 <dt><a name="index-rsa_005fdecrypt"></a>Function: <em>int</em> <strong>rsa_decrypt</strong> <em>(const struct rsa_private_key *<var>key</var>, size_t *<var>length</var>, uint8_t *<var>cleartext</var>, const mpz_t <var>ciphertext</var>)</em></dt>
4567 <dd><p>Returns 1 on success, 0 on failure. Causes of failure include decryption
4568 failing or the resulting message being to large. The message buffer
4569 pointed to by <var>cleartext</var> must be of size *<var>length</var>. After
4570 decryption, *<var>length</var> will be updated with the size of the
4571 message.
4572 </p></dd></dl>
4573 <p>There is also a timing resistant version of decryption that utilizes
4574 randomized RSA blinding.
4575 </p><dl>
4576 <dt><a name="index-rsa_005fdecrypt_005ftr"></a>Function: <em>int</em> <strong>rsa_decrypt_tr</strong> <em>(const struct rsa_public_key *<var>pub</var>, const struct rsa_private_key *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func *<var>random</var>, size_t *<var>length</var>, uint8_t *<var>message</var>, const mpz_t <var>ciphertext</var>)</em></dt>
4577 <dd><p>Returns 1 on success, 0 on failure.
4578 </p></dd></dl>
4579
4580 <p>If you need to use the <acronym>RSA</acronym> trapdoor, the private key, in a way
4581 that isn&rsquo;t supported by the above functions Nettle also includes a
4582 function that computes <code>x^d mod n</code> and nothing more, using the
4583 <acronym>CRT</acronym> optimization.
4584 </p>
4585 <dl>
4586 <dt><a name="index-rsa_005fcompute_005froot_005ftr_0028const"></a>Function: <em>int</em> <strong>rsa_compute_root_tr(const</strong> <em>struct rsa_public_key *<var>pub</var>, const struct rsa_private_key *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func *<var>random</var>, mpz_t <var>x</var>, const mpz_t <var>m</var>)</em></dt>
4587 <dd><p>Computes <code>x = m^d</code>. Returns one on success, or zero if a failure in
4588 the computation was detected.
4589 </p></dd></dl>
4590
4591 <dl>
4592 <dt><a name="index-rsa_005fcompute_005froot"></a>Function: <em>void</em> <strong>rsa_compute_root</strong> <em>(struct rsa_private_key *<var>key</var>, mpz_t <var>x</var>, const mpz_t <var>m</var>)</em></dt>
4593 <dd><p>Computes <code>x = m^d</code>.
4594 </p></dd></dl>
4595
4596 <p>At last, how do you create new keys?
4597 </p>
4598 <dl>
4599 <dt><a name="index-rsa_005fgenerate_005fkeypair"></a>Function: <em>int</em> <strong>rsa_generate_keypair</strong> <em>(struct rsa_public_key *<var>pub</var>, struct rsa_private_key *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func <var>random</var>, void *<var>progress_ctx</var>, nettle_progress_func <var>progress</var>, unsigned <var>n_size</var>, unsigned <var>e_size</var>);</em></dt>
4600 <dd><p>There are lots of parameters. <var>pub</var> and <var>key</var> is where the
4601 resulting key pair is stored. The structs should be initialized, but you
4602 don&rsquo;t need to call <code>rsa_public_key_prepare</code> or
4603 <code>rsa_private_key_prepare</code> after key generation.
4604 </p>
4605 <p><var>random_ctx</var> and <var>random</var> is a randomness generator.
4606 <code>random(random_ctx, length, dst)</code> should generate <code>length</code>
4607 random octets and store them at <code>dst</code>. For advice, see
4608 See <a href="#Randomness">Randomness</a>.
4609 </p>
4610 <p><var>progress</var> and <var>progress_ctx</var> can be used to get callbacks
4611 during the key generation process, in order to uphold an illusion of
4612 progress. <var>progress</var> can be NULL, in that case there are no
4613 callbacks.
4614 </p>
4615 <p><var>size_n</var> is the desired size of the modulo, in bits. If <var>size_e</var>
4616 is non-zero, it is the desired size of the public exponent and a random
4617 exponent of that size is selected. But if <var>e_size</var> is zero, it is
4618 assumed that the caller has already chosen a value for <code>e</code>, and
4619 stored it in <var>pub</var>.
4620 Returns one on success, and zero on failure. The function can fail for
4621 example if if <var>n_size</var> is too small, or if <var>e_size</var> is zero and
4622 <code>pub-&gt;e</code> is an even number.
4623 </p></dd></dl>
4624
4625 <hr>
4626 <a name="DSA"></a>
4627 <div class="header">
4628 <p>
4629 Next: <a href="#Elliptic-curves" accesskey="n" rel="next">Elliptic curves</a>, Previous: <a href="#RSA" accesskey="p" rel="prev">RSA</a>, Up: <a href="#Public_002dkey-algorithms" accesskey="u" rel="up">Public-key algorithms</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
4630 </div>
4631 <a name="DSA-1"></a>
4632 <h4 class="subsection">6.7.2 <acronym>DSA</acronym></h4>
4633
4634 <p>The <acronym>DSA</acronym> digital signature algorithm is more complex than
4635 <acronym>RSA</acronym>. It was specified during the early 1990s, and in 1994 NIST
4636 published <acronym>FIPS</acronym> 186 which is the authoritative specification.
4637 Sometimes <acronym>DSA</acronym> is referred to using the acronym <acronym>DSS</acronym>,
4638 for Digital Signature Standard. The most recent revision of the
4639 specification, FIPS186-3, was issued in 2009, and it adds support for
4640 larger hash functions than <acronym>sha1</acronym>.
4641 </p>
4642 <p>For <acronym>DSA</acronym>, the underlying mathematical problem is the
4643 computation of discrete logarithms. The public key consists of a large
4644 prime <code>p</code>, a small prime <code>q</code> which is a factor of <code>p-1</code>,
4645 a number <code>g</code> which generates a subgroup of order <code>q</code> modulo
4646 <code>p</code>, and an element <code>y</code> in that subgroup.
4647 </p>
4648 <p>In the original <acronym>DSA</acronym>, the size of <code>q</code> is fixed to 160
4649 bits, to match with the <acronym>SHA1</acronym> hash algorithm. The size of
4650 <code>p</code> is in principle unlimited, but the
4651 standard specifies only nine specific sizes: <code>512 + l*64</code>, where
4652 <code>l</code> is between 0 and 8. Thus, the maximum size of <code>p</code> is 1024
4653 bits, and sizes less than 1024 bits are considered obsolete and not
4654 secure.
4655 </p>
4656 <p>The subgroup requirement means that if you compute
4657 </p>
4658 <div class="example">
4659 <pre class="example">g^t mod p
4660 </pre></div>
4661
4662 <p>for all possible integers <code>t</code>, you will get precisely <code>q</code>
4663 distinct values.
4664 </p>
4665 <p>The private key is a secret exponent <code>x</code>, such that
4666 </p>
4667 <div class="example">
4668 <pre class="example">g^x = y mod p
4669 </pre></div>
4670
4671 <p>In mathematical speak, <code>x</code> is the <em>discrete logarithm</em> of
4672 <code>y</code> mod <code>p</code>, with respect to the generator <code>g</code>. The size
4673 of <code>x</code> will also be about the same size as <code>q</code>. The security of the
4674 <acronym>DSA</acronym> algorithm relies on the difficulty of the discrete
4675 logarithm problem. Current algorithms to compute discrete logarithms in
4676 this setting, and hence crack <acronym>DSA</acronym>, are of two types. The first
4677 type works directly in the (multiplicative) group of integers mod
4678 <code>p</code>. The best known algorithm of this type is the Number Field
4679 Sieve, and it&rsquo;s complexity is similar to the complexity of factoring
4680 numbers of the same size as <code>p</code>. The other type works in the
4681 smaller <code>q</code>-sized subgroup generated by <code>g</code>, which has a more
4682 difficult group structure. One good algorithm is Pollard-rho, which has
4683 complexity <code>sqrt(q)</code>.
4684 </p>
4685 <p>The important point is that security depends on the size of <em>both</em>
4686 <code>p</code> and <code>q</code>, and they should be chosen so that the difficulty
4687 of both discrete logarithm methods are comparable. Today, the security
4688 margin of the original <acronym>DSA</acronym> may be uncomfortably small. Using a
4689 <code>p</code> of 1024 bits implies that cracking using the number field sieve
4690 is expected to take about the same time as factoring a 1024-bit
4691 <acronym>RSA</acronym> modulo, and using a <code>q</code> of size 160 bits implies
4692 that cracking using Pollard-rho will take roughly <code>2^80</code> group
4693 operations. With the size of <code>q</code> fixed, tied to the <acronym>SHA1</acronym>
4694 digest size, it may be tempting to increase the size of <code>p</code> to,
4695 say, 4096 bits. This will provide excellent resistance against attacks
4696 like the number field sieve which works in the large group. But it will
4697 do very little to defend against Pollard-rho attacking the small
4698 subgroup; the attacker is slowed down at most by a single factor of 10
4699 due to the more expensive group operation. And the attacker will surely
4700 choose the latter attack.
4701 </p>
4702 <p>The signature generation algorithm is randomized; in order to create a
4703 <acronym>DSA</acronym> signature, you need a good source for random numbers
4704 (see <a href="#Randomness">Randomness</a>). Let us describe the common case of a 160-bit
4705 <code>q</code>.
4706 </p>
4707 <p>To create a signature, one starts with the hash digest of the message,
4708 <code>h</code>, which is a 160 bit number, and a random number <code>k,
4709 0&lt;k&lt;q</code>, also 160 bits. Next, one computes
4710 </p>
4711 <div class="example">
4712 <pre class="example">r = (g^k mod p) mod q
4713 s = k^-1 (h + x r) mod q
4714 </pre></div>
4715
4716 <p>The signature is the pair <code>(r, s)</code>, two 160 bit numbers. Note the
4717 two different mod operations when computing <code>r</code>, and the use of the
4718 secret exponent <code>x</code>.
4719 </p>
4720 <p>To verify a signature, one first checks that <code>0 &lt; r,s &lt; q</code>, and
4721 then one computes backwards,
4722 </p>
4723 <div class="example">
4724 <pre class="example">w = s^-1 mod q
4725 v = (g^(w h) y^(w r) mod p) mod q
4726 </pre></div>
4727
4728 <p>The signature is valid if <code>v = r</code>. This works out because <code>w =
4729 s^-1 mod q = k (h + x r)^-1 mod q</code>, so that
4730 </p>
4731 <div class="example">
4732 <pre class="example">g^(w h) y^(w r) = g^(w h) (g^x)^(w r) = g^(w (h + x r)) = g^k
4733 </pre></div>
4734
4735 <p>When reducing mod <code>q</code> this yields <code>r</code>. Note that when
4736 verifying a signature, we don&rsquo;t know either <code>k</code> or <code>x</code>: those
4737 numbers are secret.
4738 </p>
4739 <p>If you can choose between <acronym>RSA</acronym> and <acronym>DSA</acronym>, which one is
4740 best? Both are believed to be secure. <acronym>DSA</acronym> gained popularity in
4741 the late 1990s, as a patent free alternative to <acronym>RSA</acronym>. Now that
4742 the <acronym>RSA</acronym> patents have expired, there&rsquo;s no compelling reason to
4743 want to use <acronym>DSA</acronym>. Today, the original <acronym>DSA</acronym> key size
4744 does not provide a large security margin, and it should probably be
4745 phased out together with <acronym>RSA</acronym> keys of 1024 bits. Using the
4746 revised <acronym>DSA</acronym> algorithm with a larger hash function, in
4747 particular, <acronym>SHA256</acronym>, a 256-bit <code>q</code>, and <code>p</code> of size
4748 2048 bits or more, should provide for a more comfortable security
4749 margin, but these variants are not yet in wide use.
4750 </p>
4751 <p><acronym>DSA</acronym> signatures are smaller than <acronym>RSA</acronym> signatures,
4752 which is important for some specialized applications.
4753 </p>
4754 <p>From a practical point of view, <acronym>DSA</acronym>&rsquo;s need for a good
4755 randomness source is a serious disadvantage. If you ever use the same
4756 <code>k</code> (and <code>r</code>) for two different message, you leak your private
4757 key.
4758 </p>
4759 <a name="Nettle_0027s-DSA-support"></a>
4760 <h4 class="subsubsection">6.7.2.1 Nettle&rsquo;s <acronym>DSA</acronym> support</h4>
4761
4762 <p>Like for <acronym>RSA</acronym>, Nettle represents <acronym>DSA</acronym> keys using two
4763 structures, containing values of type <code>mpz_t</code>. For information on
4764 how to customize allocation, see See <a href="http://www.gmplib.org/manual/Custom-Allocation.html#Custom-Allocation">GMP
4765 Allocation</a> in <cite>GMP Manual</cite>. Nettle&rsquo;s <acronym>DSA</acronym> interface is defined
4766 in <samp>&lt;nettle/dsa.h&gt;</samp>.
4767 </p>
4768 <p>A <acronym>DSA</acronym> group is represented using the following struct.
4769 </p>
4770 <dl>
4771 <dt><a name="index-dsa_005fparams"></a>Context struct: <strong>dsa_params</strong> <em>p q g</em></dt>
4772 <dd><p>Parameters of the <acronym>DSA</acronym> group.
4773 </p></dd></dl>
4774
4775 <dl>
4776 <dt><a name="index-dsa_005fparams_005finit"></a>Function: <em>void</em> <strong>dsa_params_init</strong> <em>(struct dsa_params *<var>params</var>)</em></dt>
4777 <dd><p>Calls <code>mpz_init</code> on all numbers in the struct.
4778 </p></dd></dl>
4779
4780 <dl>
4781 <dt><a name="index-dsa_005fparams_005fclear"></a>Function: <em>void</em> <strong>dsa_params_clear</strong> <em>(struct dsa_params *<var>params</var>params)</em></dt>
4782 <dd><p>Calls <code>mpz_clear</code> on all numbers in the struct.
4783 </p></dd></dl>
4784
4785 <dl>
4786 <dt><a name="index-dsa_005fgenerate_005fparams"></a>Function: <em>int</em> <strong>dsa_generate_params</strong> <em>(struct dsa_params *<var>params</var>, void *<var>random_ctx</var>, nettle_random_func *<var>random</var>, void *<var>progress_ctx</var>, nettle_progress_func *<var>progress</var>, unsigned <var>p_bits</var>, unsigned <var>q_bits</var>)</em></dt>
4787 <dd><p>Generates paramaters of a new group. The <var>params</var> struct should be
4788 initialized before you call this function.
4789 </p>
4790 <p><var>random_ctx</var> and <var>random</var> is a randomness generator.
4791 <code>random(random_ctx, length, dst)</code> should generate <code>length</code>
4792 random octets and store them at <code>dst</code>. For advice, see
4793 See <a href="#Randomness">Randomness</a>.
4794 </p>
4795 <p><var>progress</var> and <var>progress_ctx</var> can be used to get callbacks
4796 during the key generation process, in order to uphold an illusion of
4797 progress. <var>progress</var> can be NULL, in that case there are no
4798 callbacks.
4799 </p>
4800 <p><var>p_bits</var> and <var>q_bits</var> are the desired sizes of <code>p</code> and
4801 <code>q</code>. To generate keys that conform to the original <acronym>DSA</acronym>
4802 standard, you must use <code>q_bits = 160</code> and select <var>p_bits</var> of
4803 the form <code>p_bits = 512 + l*64</code>, for <code>0 &lt;= l &lt;= 8</code>, where the
4804 smaller sizes are no longer recommended, so you should most likely stick
4805 to <code>p_bits = 1024</code>. Non-standard sizes are possible, in particular
4806 <code>p_bits</code> larger than 1024, although <acronym>DSA</acronym> implementations
4807 can not in general be expected to support such keys. Also note that
4808 using very large <var>p_bits</var>, with <var>q_bits</var> fixed at 160, doesn&rsquo;t
4809 make much sense, because the security is also limited by the size of the
4810 smaller prime. To generate <acronym>DSA</acronym> keys for use with
4811 <acronym>SHA256</acronym>, use <code>q_bits = 256</code> and, e.g., <code>p_bits =
4812 2048</code>.
4813 </p>
4814 <p>Returns one on success, and zero on failure. The function will fail if
4815 <var>q_bits</var> is too small, or too close to <var>p_bits</var>.
4816 </p></dd></dl>
4817
4818 <p>Signatures are represented using the structure below.
4819 </p>
4820 <dl>
4821 <dt><a name="index-dsa_005fsignature"></a>Context struct: <strong>dsa_signature</strong> <em>r s</em></dt>
4822 </dl>
4823
4824 <dl>
4825 <dt><a name="index-dsa_005fsignature_005finit"></a>Function: <em>void</em> <strong>dsa_signature_init</strong> <em>(struct dsa_signature *<var>signature</var>)</em></dt>
4826 <dt><a name="index-dsa_005fsignature_005fclear"></a>Function: <em>void</em> <strong>dsa_signature_clear</strong> <em>(struct dsa_signature *<var>signature</var>)</em></dt>
4827 <dd><p>You must call <code>dsa_signature_init</code> before creating or using a
4828 signature, and call <code>dsa_signature_clear</code> when you are finished
4829 with it.
4830 </p></dd></dl>
4831
4832 <p>Keys are represented as bignums, of type <code>mpz_t</code>. A public keys
4833 represent a group element, and is of the same size as <code>p</code>, while a
4834 private key is an exponent, of the same size as <code>q</code>.
4835 </p>
4836 <dl>
4837 <dt><a name="index-dsa_005fsign"></a>Function: <em>int</em> <strong>dsa_sign</strong> <em>(const struct dsa_params *<var>params</var>, const mpz_t <var>x</var>, void *<var>random_ctx</var>, nettle_random_func *<var>random</var>, size_t <var>digest_size</var>, const uint8_t *<var>digest</var>, struct dsa_signature *<var>signature</var>)</em></dt>
4838 <dd><p>Creates a signature from the given hash digest, using the private key
4839 <var>x</var>. <var>random_ctx</var> and <var>random</var> is a randomness generator.
4840 <code>random(random_ctx, length, dst)</code> should generate <code>length</code>
4841 random octets and store them at <code>dst</code>. For advice, see
4842 See <a href="#Randomness">Randomness</a>. Returns one on success, or zero on failure. Signing
4843 can fail only if the key is invalid, so that inversion modulo <code>q</code>
4844 fails.
4845 </p></dd></dl>
4846
4847 <dl>
4848 <dt><a name="index-dsa_005fverify"></a>Function: <em>int</em> <strong>dsa_verify</strong> <em>(const struct dsa_params *<var>params</var>, const mpz_t <var>y</var>, size_t <var>digest_size</var>, const uint8_t *<var>digest</var>, const struct dsa_signature *<var>signature</var>)</em></dt>
4849 <dd><p>Verifies a signature, using the public key y. Returns 1 if the signature
4850 is valid, otherwise 0.
4851 </p></dd></dl>
4852
4853 <p>To generate a keypair, first generate a <acronym>DSA</acronym> group using
4854 <code>dsa_generate_params</code>. A keypair in this group is then created
4855 using
4856 </p>
4857 <dl>
4858 <dt><a name="index-dsa_005fgenerate_005fkeypair"></a>Function: <em>void</em> <strong>dsa_generate_keypair</strong> <em>(const struct dsa_params *<var>params</var>, mpz_t <var>pub</var>, mpz_t <var>key</var>, void *<var>random_ctx</var>, nettle_random_func *<var>random</var>)</em></dt>
4859 <dd><p>Generates a new keypair, using the group <var>params</var>. The public key is
4860 stored in <var>pub</var>, and the private key in <var>key</var>. Both variables
4861 must be initialized using <code>mpz_init</code> before this call.
4862 </p>
4863 <p><var>random_ctx</var> and <var>random</var> is a randomness generator.
4864 <code>random(random_ctx, length, dst)</code> should generate <code>length</code>
4865 random octets and store them at <code>dst</code>. For advice, see
4866 See <a href="#Randomness">Randomness</a>.
4867 </p></dd></dl>
4868
4869 <a name="Old_002c-deprecated_002c-DSA-interface"></a>
4870 <h4 class="subsubsection">6.7.2.2 Old, deprecated, <acronym>DSA</acronym> interface</h4>
4871
4872 <p>Versions before nettle-3.0 used a different interface for <acronym>DSA</acronym>
4873 signatures, where the group parameters and the public key was packed
4874 together as <code>struct dsa_public_key</code>. Most of this interface is kept
4875 for backwards compatibility, and declared in <samp>nettle/dsa-compat.h</samp>.
4876 Below is the old documentation. The old and new interface use distinct
4877 names and don&rsquo;t confict, with one exception: The key generation
4878 function. The <samp>nettle/dsa-compat.h</samp> redefines
4879 <code>dsa_generate_keypair</code> as an alias for
4880 <code>dsa_compat_generate_keypair</code>, compatible with the old interface
4881 and documented below.
4882 </p>
4883 <p>The old <acronym>DSA</acronym> functions are very similar to the corresponding
4884 <acronym>RSA</acronym> functions, but there are a few differences pointed out
4885 below. For a start, there are no functions corresponding to
4886 <code>rsa_public_key_prepare</code> and <code>rsa_private_key_prepare</code>.
4887 </p>
4888 <dl>
4889 <dt><a name="index-dsa_005fpublic_005fkey"></a>Context struct: <strong>dsa_public_key</strong> <em>p q g y</em></dt>
4890 <dd><p>The public parameters described above.
4891 </p></dd></dl>
4892
4893 <dl>
4894 <dt><a name="index-dsa_005fprivate_005fkey"></a>Context struct: <strong>dsa_private_key</strong> <em>x</em></dt>
4895 <dd><p>The private key <code>x</code>.
4896 </p></dd></dl>
4897
4898 <p>Before use, these structs must be initialized by calling one of
4899 </p>
4900 <dl>
4901 <dt><a name="index-dsa_005fpublic_005fkey_005finit"></a>Function: <em>void</em> <strong>dsa_public_key_init</strong> <em>(struct dsa_public_key *<var>pub</var>)</em></dt>
4902 <dt><a name="index-dsa_005fprivate_005fkey_005finit"></a>Function: <em>void</em> <strong>dsa_private_key_init</strong> <em>(struct dsa_private_key *<var>key</var>)</em></dt>
4903 <dd><p>Calls <code>mpz_init</code> on all numbers in the key struct.
4904 </p></dd></dl>
4905
4906 <p>When finished with them, the space for the numbers must be
4907 deallocated by calling one of
4908 </p>
4909 <dl>
4910 <dt><a name="index-dsa_005fpublic_005fkey_005fclear"></a>Function: <em>void</em> <strong>dsa_public_key_clear</strong> <em>(struct dsa_public_key *<var>pub</var>)</em></dt>
4911 <dt><a name="index-dsa_005fprivate_005fkey_005fclear"></a>Function: <em>void</em> <strong>dsa_private_key_clear</strong> <em>(struct dsa_private_key *<var>key</var>)</em></dt>
4912 <dd><p>Calls <code>mpz_clear</code> on all numbers in the key struct.
4913 </p></dd></dl>
4914
4915 <p>Signatures are represented using <code>struct dsa_signature</code>, described
4916 earlier.
4917 </p>
4918 <p>For signing, you need to provide both the public and the private key
4919 (unlike <acronym>RSA</acronym>, where the private key struct includes all
4920 information needed for signing), and a source for random numbers.
4921 Signatures can use the <acronym>SHA1</acronym> or the <acronym>SHA256</acronym> hash
4922 function, although the implementation of <acronym>DSA</acronym> with
4923 <acronym>SHA256</acronym> should be considered somewhat experimental due to lack
4924 of official test vectors and interoperability testing.
4925 </p>
4926 <dl>
4927 <dt><a name="index-dsa_005fsha1_005fsign"></a>Function: <em>int</em> <strong>dsa_sha1_sign</strong> <em>(const struct dsa_public_key *<var>pub</var>, const struct dsa_private_key *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func <var>random</var>, struct sha1_ctx *<var>hash</var>, struct dsa_signature *<var>signature</var>)</em></dt>
4928 <dt><a name="index-dsa_005fsha1_005fsign_005fdigest"></a>Function: <em>int</em> <strong>dsa_sha1_sign_digest</strong> <em>(const struct dsa_public_key *<var>pub</var>, const struct dsa_private_key *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func <var>random</var>, const uint8_t *<var>digest</var>, struct dsa_signature *<var>signature</var>)</em></dt>
4929 <dt><a name="index-dsa_005fsha256_005fsign"></a>Function: <em>int</em> <strong>dsa_sha256_sign</strong> <em>(const struct dsa_public_key *<var>pub</var>, const struct dsa_private_key *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func <var>random</var>, struct sha256_ctx *<var>hash</var>, struct dsa_signature *<var>signature</var>)</em></dt>
4930 <dt><a name="index-dsa_005fsha256_005fsign_005fdigest"></a>Function: <em>int</em> <strong>dsa_sha256_sign_digest</strong> <em>(const struct dsa_public_key *<var>pub</var>, const struct dsa_private_key *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func <var>random</var>, const uint8_t *<var>digest</var>, struct dsa_signature *<var>signature</var>)</em></dt>
4931 <dd><p>Creates a signature from the given hash context or digest.
4932 <var>random_ctx</var> and <var>random</var> is a randomness generator.
4933 <code>random(random_ctx, length, dst)</code> should generate <code>length</code>
4934 random octets and store them at <code>dst</code>. For advice, see
4935 See <a href="#Randomness">Randomness</a>. Returns one on success, or zero on failure.
4936 Signing fails if the key size and the hash size don&rsquo;t match.
4937 </p></dd></dl>
4938
4939 <p>Verifying signatures is a little easier, since no randomness generator is
4940 needed. The functions are
4941 </p>
4942 <dl>
4943 <dt><a name="index-dsa_005fsha1_005fverify"></a>Function: <em>int</em> <strong>dsa_sha1_verify</strong> <em>(const struct dsa_public_key *<var>key</var>, struct sha1_ctx *<var>hash</var>, const struct dsa_signature *<var>signature</var>)</em></dt>
4944 <dt><a name="index-dsa_005fsha1_005fverify_005fdigest"></a>Function: <em>int</em> <strong>dsa_sha1_verify_digest</strong> <em>(const struct dsa_public_key *<var>key</var>, const uint8_t *<var>digest</var>, const struct dsa_signature *<var>signature</var>)</em></dt>
4945 <dt><a name="index-dsa_005fsha256_005fverify"></a>Function: <em>int</em> <strong>dsa_sha256_verify</strong> <em>(const struct dsa_public_key *<var>key</var>, struct sha256_ctx *<var>hash</var>, const struct dsa_signature *<var>signature</var>)</em></dt>
4946 <dt><a name="index-dsa_005fsha256_005fverify_005fdigest"></a>Function: <em>int</em> <strong>dsa_sha256_verify_digest</strong> <em>(const struct dsa_public_key *<var>key</var>, const uint8_t *<var>digest</var>, const struct dsa_signature *<var>signature</var>)</em></dt>
4947 <dd><p>Verifies a signature. Returns 1 if the signature is valid, otherwise 0.
4948 </p></dd></dl>
4949
4950 <p>Key generation uses mostly the same parameters as the corresponding
4951 <acronym>RSA</acronym> function.
4952 </p>
4953 <dl>
4954 <dt><a name="index-dsa_005fcompat_005fgenerate_005fkeypair"></a>Function: <em>int</em> <strong>dsa_compat_generate_keypair</strong> <em>(struct dsa_public_key *<var>pub</var>, struct dsa_private_key *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func <var>random</var>, void *<var>progress_ctx</var>, nettle_progress_func <var>progress</var>, unsigned <var>p_bits</var>, unsigned <var>q_bits</var>)</em></dt>
4955 <dd><p><var>pub</var> and <var>key</var> is where the resulting key pair is stored. The
4956 structs should be initialized before you call this function.
4957 </p>
4958 <p><var>random_ctx</var> and <var>random</var> is a randomness generator.
4959 <code>random(random_ctx, length, dst)</code> should generate <code>length</code>
4960 random octets and store them at <code>dst</code>. For advice, see
4961 See <a href="#Randomness">Randomness</a>.
4962 </p>
4963 <p><var>progress</var> and <var>progress_ctx</var> can be used to get callbacks
4964 during the key generation process, in order to uphold an illusion of
4965 progress. <var>progress</var> can be NULL, in that case there are no
4966 callbacks.
4967 </p>
4968 <p><var>p_bits</var> and <var>q_bits</var> are the desired sizes of <code>p</code> and
4969 <code>q</code>. See <code>dsa_generate_keypair</code> for details.
4970 </p></dd></dl>
4971
4972 <hr>
4973 <a name="Elliptic-curves"></a>
4974 <div class="header">
4975 <p>
4976 Previous: <a href="#DSA" accesskey="p" rel="prev">DSA</a>, Up: <a href="#Public_002dkey-algorithms" accesskey="u" rel="up">Public-key algorithms</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
4977 </div>
4978 <a name="Elliptic-curves-1"></a>
4979 <h4 class="subsection">6.7.3 <acronym>Elliptic curves</acronym></h4>
4980
4981 <p>For cryptographic purposes, an elliptic curve is a mathematical group of
4982 points, and computing logarithms in this group is computationally
4983 difficult problem. Nettle uses additive notation for elliptic curve
4984 groups. If <em>P</em> and <em>Q</em> are two points, and <em>k</em> is an
4985 integer, the point sum, <em>P + Q</em>, and the multiple <em>k P</em> can be
4986 computed efficiently, but given only two points <em>P</em> and <em>Q</em>,
4987 finding an integer <em>k</em> such that <em>Q = k P</em> is the elliptic
4988 curve discrete logarithm problem.
4989 </p>
4990 <p>Nettle supports standard curves which are all of the form <em>y^2 =
4991 x^3 - 3 x + b (mod p)</em>, i.e., the points have coordinates <em>(x,y)</em>,
4992 both considered as integers modulo a specified prime <em>p</em>. Curves
4993 are represented as a <code>struct ecc_curve</code>. It also supports
4994 curve25519, which uses a different form of curve. Supported curves are
4995 declared in <samp>&lt;nettle/ecc-curve.h&gt;</samp>, e.g., <code>nettle_secp_256r1</code>
4996 for a standardized curve using the 256-bit prime <em>p = 2^{256} -
4997 2^{224} + 2^{192} + 2^{96} - 1</em>. The contents of these structs is not
4998 visible to nettle users. The &ldquo;bitsize of the curve&rdquo; is used as a
4999 shorthand for the bitsize of the curve&rsquo;s prime <em>p</em>, e.g., 256 bits
5000 for <code>nettle_secp_256r1</code>.
5001 </p>
5002 <a name="Side_002dchannel-silence"></a>
5003 <h4 class="subsubsection">6.7.3.1 Side-channel silence</h4>
5004 <p>Nettle&rsquo;s implementation of the elliptic curve operations is intended to
5005 be side-channel silent. The side-channel attacks considered are:
5006 </p>
5007 <ul>
5008 <li> Timing attacks
5009 If the timing of operations depends on secret values, an attacker
5010 interacting with your system can measure the response time, and infer
5011 information about your secrets, e.g., a private signature key.
5012
5013 </li><li> Attacks using memory caches
5014 Assume you have some secret data on a multi-user system, and that this
5015 data is properly protected so that other users get no direct access to
5016 it. If you have a process operating on the secret data, and this process
5017 does memory accesses depending on the data, e.g, an internal lookup
5018 table in some cryptographic algorithm, an attacker running a separate
5019 process on the same system may use behavior of internal CPU caches to
5020 get information about your secrets.
5021 </li></ul>
5022
5023 <p>Nettle&rsquo;s ECC implementation is designed to be <em>side-channel silent</em>,
5024 and not leak any information to these attacks. Timing and memory
5025 accesses depend only on the size of the input data and its location in
5026 memory, not on the actual data bits. This implies a performance penalty
5027 in several of the building blocks.
5028 </p>
5029 <a name="ECDSA"></a>
5030 <h4 class="subsubsection">6.7.3.2 ECDSA</h4>
5031
5032 <p>ECDSA is a variant of the DSA digital signature scheme (see <a href="#DSA">DSA</a>),
5033 which works over an elliptic curve group rather than over a (subgroup
5034 of) integers modulo <em>p</em>. Like DSA, creating a signature requires a unique
5035 random nonce (repeating the nonce with two different messages reveals
5036 the private key, and any leak or bias in the generation of the nonce
5037 also leaks information about the key).
5038 </p>
5039 <p>Unlike DSA, signatures are in general not tied to any particular hash
5040 function or even hash size. Any hash function can be used, and the hash
5041 value is truncated or padded as needed to get a size matching the curve
5042 being used. It is recommended to use a strong cryptographic hash
5043 function with digest size close to the bit size of the curve, e.g.,
5044 SHA256 is a reasonable choice when using ECDSA signature over the curve
5045 secp256r1. A protocol or application using ECDSA has to specify which
5046 curve and which hash function to use, or provide some mechanism for
5047 negotiating.
5048 </p>
5049 <p>Nettle defines ECDSA in <samp>&lt;nettle/ecdsa.h&gt;</samp>. We first need
5050 to define the data types used to represent public and private keys.
5051 </p>
5052 <dl>
5053 <dt><a name="index-struct-ecc_005fpoint"></a>struct: <strong>struct ecc_point</strong></dt>
5054 <dd><p>Represents a point on an elliptic curve. In particular, it is used to
5055 represent an ECDSA public key.
5056 </p></dd></dl>
5057
5058 <dl>
5059 <dt><a name="index-ecc_005fpoint_005finit"></a>Function: <em>void</em> <strong>ecc_point_init</strong> <em>(struct ecc_point *<var>p</var>, const structecc_curve *<var>ecc</var>)</em></dt>
5060 <dd><p>Initializes <var>p</var> to represent points on the given curve <var>ecc</var>.
5061 Allocates storage for the coordinates, using the same allocation
5062 functions as GMP.
5063 </p></dd></dl>
5064
5065 <dl>
5066 <dt><a name="index-ecc_005fpoint_005fclear"></a>Function: <em>void</em> <strong>ecc_point_clear</strong> <em>(struct ecc_point *<var>p</var>)</em></dt>
5067 <dd><p>Deallocate storage.
5068 </p></dd></dl>
5069
5070 <dl>
5071 <dt><a name="index-ecc_005fpoint_005fset"></a>Function: <em>int</em> <strong>ecc_point_set</strong> <em>(struct ecc_point *<var>p</var>, const mpz_t <var>x</var>, const mpz_t <var>y</var>)</em></dt>
5072 <dd><p>Check that the given coordinates represent a point on the curve. If so,
5073 the coordinates are copied and converted to internal representation, and
5074 the function returns 1. Otherwise, it returns 0. Currently, the
5075 infinity point (or zero point, with additive notation) i snot allowed.
5076 </p></dd></dl>
5077
5078 <dl>
5079 <dt><a name="index-ecc_005fpoint_005fget"></a>Function: <em>void</em> <strong>ecc_point_get</strong> <em>(const struct ecc_point *<var>p</var>, mpz_t <var>x</var>, mpz_t <var>y</var>)</em></dt>
5080 <dd><p>Extracts the coordinate of the point <var>p</var>. The output parameters
5081 <var>x</var> or <var>y</var> may be NULL if the caller doesn&rsquo;t want that
5082 coordinate.
5083 </p></dd></dl>
5084
5085 <dl>
5086 <dt><a name="index-struct-ecc_005fscalar"></a>struct: <strong>struct ecc_scalar</strong></dt>
5087 <dd><p>Represents an integer in the range <em>0 &lt; x &lt; group order</em>, where the
5088 &ldquo;group order&rdquo; refers to the order of an ECC group. In particular, it
5089 is used to represent an ECDSA private key.
5090 </p></dd></dl>
5091
5092 <dl>
5093 <dt><a name="index-ecc_005fscalar_005finit"></a>Function: <em>void</em> <strong>ecc_scalar_init</strong> <em>(struct ecc_scalar *<var>s</var>, const struct ecc_curve *<var>ecc</var>)</em></dt>
5094 <dd><p>Initializes <var>s</var> to represent a scalar suitable for the given curve
5095 <var>ecc</var>. Allocates storage using the same allocation functions as GMP.
5096 </p></dd></dl>
5097
5098 <dl>
5099 <dt><a name="index-ecc_005fscalar_005fclear"></a>Function: <em>void</em> <strong>ecc_scalar_clear</strong> <em>(struct ecc_scalar *<var>s</var>)</em></dt>
5100 <dd><p>Deallocate storage.
5101 </p></dd></dl>
5102
5103 <dl>
5104 <dt><a name="index-ecc_005fscalar_005fset"></a>Function: <em>int</em> <strong>ecc_scalar_set</strong> <em>(struct ecc_scalar *<var>s</var>, const mpz_t <var>z</var>)</em></dt>
5105 <dd><p>Check that <var>z</var> is in the correct range. If so, copies the value to
5106 <var>s</var> and returns 1, otherwise returns 0.
5107 </p></dd></dl>
5108
5109 <dl>
5110 <dt><a name="index-ecc_005fscalar_005fget"></a>Function: <em>void</em> <strong>ecc_scalar_get</strong> <em>(const struct ecc_scalar *<var>s</var>, mpz_t <var>z</var>)</em></dt>
5111 <dd><p>Extracts the scalar, in GMP <code>mpz_t</code> representation.
5112 </p></dd></dl>
5113
5114 <p>To create and verify ECDSA signatures, the following functions are used.
5115 </p>
5116 <dl>
5117 <dt><a name="index-ecdsa_005fsign"></a>Function: <em>void</em> <strong>ecdsa_sign</strong> <em>(const struct ecc_scalar *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func *<var>random</var>, size_t <var>digest_length</var>, const uint8_t *<var>digest</var>, struct dsa_signature *<var>signature</var>)</em></dt>
5118 <dd><p>Uses the private key <var>key</var> to create a signature on <var>digest</var>.
5119 <var>random_ctx</var> and <var>random</var> is a randomness generator.
5120 <code>random(random_ctx, length, dst)</code> should generate <code>length</code>
5121 random octets and store them at <code>dst</code>. The signature is stored in
5122 <var>signature</var>, in the same was as for plain DSA.
5123 </p></dd></dl>
5124
5125 <dl>
5126 <dt><a name="index-ecdsa_005fverify"></a>Function: <em>int</em> <strong>ecdsa_verify</strong> <em>(const struct ecc_point *<var>pub</var>, size_t <var>length</var>, const uint8_t *<var>digest</var>, const struct dsa_signature *<var>signature</var>)</em></dt>
5127 <dd><p>Uses the public key <var>pub</var> to verify that <var>signature</var> is a valid
5128 signature for the message digest <var>digest</var> (of <var>length</var> octets).
5129 Returns 1 if the signature is valid, otherwise 0.
5130 </p></dd></dl>
5131
5132 <p>Finally, to generation of new an ECDSA key pairs
5133 </p>
5134 <dl>
5135 <dt><a name="index-ecdsa_005fgenerate_005fkeypair"></a>Function: <em>void</em> <strong>ecdsa_generate_keypair</strong> <em>(struct ecc_point *<var>pub</var>, struct ecc_scalar *<var>key</var>, void *<var>random_ctx</var>, nettle_random_func *<var>random</var>);</em></dt>
5136 <dd><p><var>pub</var> and <var>key</var> is where the resulting key pair is stored. The
5137 structs should be initialized, for the desired ECC curve, before you call this function.
5138 </p>
5139 <p><var>random_ctx</var> and <var>random</var> is a randomness generator.
5140 <code>random(random_ctx, length, dst)</code> should generate <code>length</code>
5141 random octets and store them at <code>dst</code>. For advice, see
5142 See <a href="#Randomness">Randomness</a>.
5143 </p></dd></dl>
5144
5145 <a name="Curve25519"></a>
5146 <h4 class="subsubsection">6.7.3.3 Curve25519</h4>
5147
5148 <p>Curve25519 is an elliptic curve of Montgomery type, <em>y^2 = x^3 +
5149 486662 x^2 + x (mod p)</em>, with <em>p = 2^255 - 19</em>. Montgomery curves
5150 have the advantage of simple and efficient point addition based on the
5151 x-coordinate only. This particular curve was proposed by D.~J.~Bernstein
5152 in 2006, for fast Diffie-Hellman key exchange. The group generator is
5153 defined by <em>x = 9</em> (there are actually two points with <em>x =
5154 9</em>, differing by the sign of the y-coordinate, but that doesn&rsquo;t matter
5155 for the curve25519 operations which work with the x-coordinate only).
5156 </p>
5157 <p>The curve25519 functions are defined as operations on octet strings,
5158 which are interpreted as x-coordinates in little-endian byte order.
5159 </p>
5160 <p>Of all the possible input strings, only about half correspond to points
5161 on curve25519, i.e., a value that can be produced by
5162 <code>curve25519_mul_g</code>. The other half corresponds to points on a
5163 related &ldquo;twist curve&rdquo;. The current implementation of
5164 <code>curve25519_mul</code> uses a Montgomery ladder for the scalar
5165 multiplication, as suggested in the curve25519 literature, and produces
5166 a well defined output for all possible inputs, no matter if points are
5167 on the proper curve or on its twist. However, at the time of writing, it
5168 is not yet ruled out that other implementations could be faster, and
5169 therefore the behaviour for inputs corresponding to points on the twist
5170 curve must be considered an implementation idiosyncrasy, and may change
5171 in future versions.
5172 </p>
5173 <dl>
5174 <dt><a name="index-CURVE25519_005fSIZE"></a>Constant: <strong>CURVE25519_SIZE</strong></dt>
5175 <dd><p>The size of the strings representing curve25519 points and scalars, 32.
5176 </p></dd></dl>
5177
5178 <dl>
5179 <dt><a name="index-curve25519_005fmul_005fg"></a>Function: <em>void</em> <strong>curve25519_mul_g</strong> <em>(uint8_t *<var>q</var>, const uint8_t *<var>n</var>)</em></dt>
5180 <dd><p>Computes <em>Q = N G</em>, where <em>G</em> is the group generator and
5181 <em>N</em> is an integer. The input argument <var>n</var> and the output
5182 argument <var>q</var> use a little-endian representation of the scalar and
5183 the x-coordinate, respectively. They are both of size
5184 <code>CURVE25519_SIZE</code>.
5185 </p>
5186 <p>This function is intended to be compatible with the function
5187 <code>crypto_scalar_mult_base</code> in the NaCl library.
5188 </p></dd></dl>
5189
5190 <dl>
5191 <dt><a name="index-curve25519_005fmul"></a>Function: <em>void</em> <strong>curve25519_mul</strong> <em>(uint8_t *<var>q</var>, const uint8_t *<var>n</var>, const uint8_t *<var>p</var>)</em></dt>
5192 <dd><p>Computes <em>Q = N P</em>, where <em>P</em> is an input point and <em>N</em>
5193 is an integer. The input arguments <var>n</var> and <var>p</var> and the output
5194 argument <var>q</var> use a little-endian representation of the scalar and
5195 the x-coordinates, respectively. They are all of size
5196 <code>CURVE25519_SIZE</code>.
5197 </p>
5198 <p>The output value is defined only when the input <var>p</var> is a string
5199 produced by <code>curve25519_mul_g</code>. (See discussion above, about the
5200 twist curve).
5201 </p>
5202 <p>This function is intended to be compatible with the function
5203 <code>crypto_scalar_mult</code> in the NaCl library.
5204 </p></dd></dl>
5205
5206 <a name="EdDSA"></a>
5207 <h4 class="subsubsection">6.7.3.4 EdDSA</h4>
5208 <a name="index-eddsa"></a>
5209
5210 <p>EdDSA is a signature scheme proposed by D.~J.~Bernstein et al. in 2011.
5211 It is defined using a &ldquo;Twisted Edwards curve&rdquo;, of the form <em>-x^2
5212 + y^2 = 1 + d x^2 y^2</em>. The specific signature scheme Ed25519 uses a
5213 curve which is equivalent to curve25519: The two groups used differ only
5214 by a simple change of coordinates, so that the discrete logarithm
5215 problem is of equal difficulty in both groups.
5216 </p>
5217 <p>Unlike other signature schemes in Nettle, the input to the EdDSA sign
5218 and verify functions is the possibly large message itself, not a hash
5219 digest. EdDSA is a variant of Schnorr signatures, where the message is
5220 hashed together with other data during the signature process, providing
5221 resilience to hash-collisions: A successful attack finding collisions in
5222 the hash function does not automatically translate into an attack to
5223 forge signatures. EdDSA also avoids the use of a randomness source by
5224 generating the needed signature nonce from a hash of the private key and
5225 the message, which means that the message is actually hashed twice when
5226 creating a signature. If signing huge messages, it is possible to hash
5227 the message first and pass the short message digest as input to the sign
5228 and verify functions, however, the resilience to hash collision is then
5229 lost.
5230 </p>
5231 <dl>
5232 <dt><a name="index-ED25519_005fKEY_005fSIZE"></a>Constant: <strong>ED25519_KEY_SIZE</strong></dt>
5233 <dd><p>The size of a private or public Ed25519 key, 32 octets.
5234 </p></dd></dl>
5235
5236 <dl>
5237 <dt><a name="index-ED25519_005fSIGNATURE_005fSIZE"></a>Constant: <strong>ED25519_SIGNATURE_SIZE</strong></dt>
5238 <dd><p>The size of an Ed25519 signature, 64 octets.
5239 </p></dd></dl>
5240
5241 <dl>
5242 <dt><a name="index-ed25519_005fsha512_005fpublic_005fkey"></a>Function: <em>void</em> <strong>ed25519_sha512_public_key</strong> <em>(uint8_t *<var>pub</var>, const uint8_t *<var>priv</var>)</em></dt>
5243 <dd><p>Computes the public key corresponding to the given private key. Both
5244 input and output are of size <code>ED25519_KEY_SIZE</code>.
5245 </p></dd></dl>
5246
5247 <dl>
5248 <dt><a name="index-ed25519_005fsha512_005fsign"></a>Function: <em>void</em> <strong>ed25519_sha512_sign</strong> <em>(const uint8_t *<var>pub</var>, const uint8_t *<var>priv</var>, size_t <var>length</var>, const uint8_t *<var>msg</var>, uint8_t *<var>signature</var>)</em></dt>
5249 <dd><p>Signs a message using the provided key pair.
5250 </p></dd></dl>
5251
5252 <dl>
5253 <dt><a name="index-ed25519_005fsha512_005fverify"></a>Function: <em>int</em> <strong>ed25519_sha512_verify</strong> <em>(const uint8_t *<var>pub</var>, size_t <var>length</var>, const uint8_t *<var>msg</var>, const uint8_t *<var>signature</var>)</em></dt>
5254 <dd><p>Verifies a message using the provided public key. Returns 1 if the
5255 signature is valid, otherwise 0.
5256 </p></dd></dl>
5257
5258 <hr>
5259 <a name="Randomness"></a>
5260 <div class="header">
5261 <p>
5262 Next: <a href="#ASCII-encoding" accesskey="n" rel="next">ASCII encoding</a>, Previous: <a href="#Public_002dkey-algorithms" accesskey="p" rel="prev">Public-key algorithms</a>, Up: <a href="#Reference" accesskey="u" rel="up">Reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
5263 </div>
5264 <a name="Randomness-1"></a>
5265 <h3 class="section">6.8 Randomness</h3>
5266
5267 <a name="index-Randomness"></a>
5268
5269 <p>A crucial ingredient in many cryptographic contexts is randomness: Let
5270 <code>p</code> be a random prime, choose a random initialization vector
5271 <code>iv</code>, a random key <code>k</code> and a random exponent <code>e</code>, etc. In
5272 the theories, it is assumed that you have plenty of randomness around.
5273 If this assumption is not true in practice, systems that are otherwise
5274 perfectly secure, can be broken. Randomness has often turned out to be
5275 the weakest link in the chain.
5276 </p>
5277 <p>In non-cryptographic applications, such as games as well as scientific
5278 simulation, a good randomness generator usually means a generator that
5279 has good statistical properties, and is seeded by some simple function
5280 of things like the current time, process id, and host name.
5281 </p>
5282 <p>However, such a generator is inadequate for cryptography, for at least
5283 two reasons:
5284 </p>
5285
5286 <ul>
5287 <li> It&rsquo;s too easy for an attacker to guess the initial seed. Even if it will
5288 take some 2^32 tries before he guesses right, that&rsquo;s far too easy. For
5289 example, if the process id is 16 bits, the resolution of &ldquo;current time&rdquo;
5290 is one second, and the attacker knows what day the generator was seeded,
5291 there are only about 2^32 possibilities to try if all possible values
5292 for the process id and time-of-day are tried.
5293
5294 </li><li> The generator output reveals too much. By observing only a small segment
5295 of the generator&rsquo;s output, its internal state can be recovered, and from
5296 there, all previous output and all future output can be computed by the
5297 attacker.
5298 </li></ul>
5299
5300 <p>A randomness generator that is used for cryptographic purposes must have
5301 better properties. Let&rsquo;s first look at the seeding, as the issues here
5302 are mostly independent of the rest of the generator. The initial state
5303 of the generator (its seed) must be unguessable by the attacker. So
5304 what&rsquo;s unguessable? It depends on what the attacker already knows. The
5305 concept used in information theory to reason about such things is called
5306 &ldquo;entropy&rdquo;, or &ldquo;conditional entropy&rdquo; (not to be confused with the
5307 thermodynamic concept with the same name). A reasonable requirement is
5308 that the seed contains a conditional entropy of at least some 80-100
5309 bits. This property can be explained as follows: Allow the attacker to
5310 ask <code>n</code> yes-no-questions, of his own choice, about the seed. If
5311 the attacker, using this question-and-answer session, as well as any
5312 other information he knows about the seeding process, still can&rsquo;t guess
5313 the seed correctly, then the conditional entropy is more than <code>n</code>
5314 bits.
5315 </p>
5316 <a name="index-Entropy"></a>
5317 <a name="index-Conditional-entropy"></a>
5318
5319 <p>Let&rsquo;s look at an example. Say information about timing of received
5320 network packets is used in the seeding process. If there is some random
5321 network traffic going on, this will contribute some bits of entropy or
5322 &ldquo;unguessability&rdquo; to the seed. However, if the attacker can listen in to
5323 the local network, or if all but a small number of the packets were
5324 transmitted by machines that the attacker can monitor, this additional
5325 information makes the seed easier for the attacker to figure out. Even
5326 if the information is exactly the same, the conditional entropy, or
5327 unguessability, is smaller for an attacker that knows some of it already
5328 before the hypothetical question-and-answer session.
5329 </p>
5330 <p>Seeding of good generators is usually based on several sources. The key
5331 point here is that the amount of unguessability that each source
5332 contributes, depends on who the attacker is. Some sources that have been
5333 used are:
5334 </p>
5335 <dl compact="compact">
5336 <dt>High resolution timing of i/o activities</dt>
5337 <dd><p>Such as completed blocks from spinning hard disks, network packets, etc.
5338 Getting access to such information is quite system dependent, and not
5339 all systems include suitable hardware. If available, it&rsquo;s one of the
5340 better randomness source one can find in a digital, mostly predictable,
5341 computer.
5342 </p>
5343 </dd>
5344 <dt>User activity</dt>
5345 <dd><p>Timing and contents of user interaction events is another popular source
5346 that is available for interactive programs (even if I suspect that it is
5347 sometimes used in order to make the user feel good, not because the
5348 quality of the input is needed or used properly). Obviously, not
5349 available when a machine is unattended. Also beware of networks: User
5350 interaction that happens across a long serial cable, <acronym>TELNET</acronym>
5351 session, or even <acronym>SSH</acronym> session may be visible to an attacker, in
5352 full or partially.
5353 </p>
5354 </dd>
5355 <dt>Audio input</dt>
5356 <dd><p>Any room, or even a microphone input that&rsquo;s left unconnected, is a
5357 source of some random background noise, which can be fed into the
5358 seeding process.
5359 </p>
5360 </dd>
5361 <dt>Specialized hardware</dt>
5362 <dd><p>Hardware devices with the sole purpose of generating random data have
5363 been designed. They range from radioactive samples with an attached
5364 Geiger counter, to amplification of the inherent noise in electronic
5365 components such as diodes and resistors, to low-frequency sampling of
5366 chaotic systems. Hashing successive images of a Lava lamp is a
5367 spectacular example of the latter type.
5368 </p>
5369 </dd>
5370 <dt>Secret information</dt>
5371 <dd><p>Secret information, such as user passwords or keys, or private files
5372 stored on disk, can provide some unguessability. A problem is that if
5373 the information is revealed at a later time, the unguessability
5374 vanishes. Another problem is that this kind of information tends to be
5375 fairly constant, so if you rely on it and seed your generator regularly,
5376 you risk constructing almost similar seeds or even constructing the same
5377 seed more than once.
5378 </p></dd>
5379 </dl>
5380
5381 <p>For all practical sources, it&rsquo;s difficult but important to provide a
5382 reliable lower bound on the amount of unguessability that it provides.
5383 Two important points are to make sure that the attacker can&rsquo;t observe
5384 your sources (so if you like the Lava lamp idea, remember that you have
5385 to get your own lamp, and not put it by a window or anywhere else where
5386 strangers can see it), and that hardware failures are detected. What if
5387 the bulb in the Lava lamp, which you keep locked into a cupboard
5388 following the above advice, breaks after a few months?
5389 </p>
5390 <p>So let&rsquo;s assume that we have been able to find an unguessable seed,
5391 which contains at least 80 bits of conditional entropy, relative to all
5392 attackers that we care about (typically, we must at the very least
5393 assume that no attacker has root privileges on our machine).
5394 </p>
5395 <p>How do we generate output from this seed, and how much can we get? Some
5396 generators (notably the Linux <samp>/dev/random</samp> generator) tries to
5397 estimate available entropy and restrict the amount of output. The goal
5398 is that if you read 128 bits from <samp>/dev/random</samp>, you should get 128
5399 &ldquo;truly random&rdquo; bits. This is a property that is useful in some
5400 specialized circumstances, for instance when generating key material for
5401 a one time pad, or when working with unconditional blinding, but in most
5402 cases, it doesn&rsquo;t matter much. For most application, there&rsquo;s no limit on
5403 the amount of useful &ldquo;random&rdquo; data that we can generate from a small
5404 seed; what matters is that the seed is unguessable and that the
5405 generator has good cryptographic properties.
5406 </p>
5407 <p>At the heart of all generators lies its internal state. Future output
5408 is determined by the internal state alone. Let&rsquo;s call it the generator&rsquo;s
5409 key. The key is initialized from the unguessable seed. Important
5410 properties of a generator are:
5411 </p>
5412 <dl compact="compact">
5413 <dt><em>Key-hiding</em></dt>
5414 <dd><p>An attacker observing the output should not be able to recover the
5415 generator&rsquo;s key.
5416 </p>
5417 </dd>
5418 <dt><em>Independence of outputs</em></dt>
5419 <dd><p>Observing some of the output should not help the attacker to guess
5420 previous or future output.
5421 </p>
5422 </dd>
5423 <dt><em>Forward secrecy</em></dt>
5424 <dd><p>Even if an attacker compromises the generator&rsquo;s key, he should not be
5425 able to guess the generator output <em>before</em> the key compromise.
5426 </p>
5427 </dd>
5428 <dt><em>Recovery from key compromise</em></dt>
5429 <dd><p>If an attacker compromises the generator&rsquo;s key, he can compute
5430 <em>all</em> future output. This is inevitable if the generator is seeded
5431 only once, at startup. However, the generator can provide a reseeding
5432 mechanism, to achieve recovery from key compromise. More precisely: If
5433 the attacker compromises the key at a particular time <code>t_1</code>, there
5434 is another later time <code>t_2</code>, such that if the attacker observes all
5435 output generated between <code>t_1</code> and <code>t_2</code>, he still can&rsquo;t guess
5436 what output is generated after <code>t_2</code>.
5437 </p>
5438 </dd>
5439 </dl>
5440
5441 <p>Nettle includes one randomness generator that is believed to have all
5442 the above properties, and two simpler ones.
5443 </p>
5444 <p><acronym>ARCFOUR</acronym>, like any stream cipher, can be used as a randomness
5445 generator. Its output should be of reasonable quality, if the seed is
5446 hashed properly before it is used with <code>arcfour_set_key</code>. There&rsquo;s
5447 no single natural way to reseed it, but if you need reseeding, you
5448 should be using Yarrow instead.
5449 </p>
5450 <p>The &ldquo;lagged Fibonacci&rdquo; generator in <samp>&lt;nettle/knuth-lfib.h&gt;</samp> is a
5451 fast generator with good statistical properties, but is <strong>not</strong> for
5452 cryptographic use, and therefore not documented here. It is included
5453 mostly because the Nettle test suite needs to generate some test data
5454 from a small seed.
5455 </p>
5456 <p>The recommended generator to use is Yarrow, described below.
5457 </p>
5458 <a name="Yarrow"></a>
5459 <h4 class="subsection">6.8.1 Yarrow</h4>
5460
5461 <p>Yarrow is a family of pseudo-randomness generators, designed for
5462 cryptographic use, by John Kelsey, Bruce Schneier and Niels Ferguson.
5463 Yarrow-160 is described in a paper at
5464 <a href="http://www.counterpane.com/yarrow.html">http://www.counterpane.com/yarrow.html</a>, and it uses <acronym>SHA1</acronym>
5465 and triple-DES, and has a 160-bit internal state. Nettle implements
5466 Yarrow-256, which is similar, but uses <acronym>SHA256</acronym> and
5467 <acronym>AES</acronym> to get an internal state of 256 bits.
5468 </p>
5469 <p>Yarrow was an almost finished project, the paper mentioned above is the
5470 closest thing to a specification for it, but some smaller details are
5471 left out. There is no official reference implementation or test cases.
5472 This section includes an overview of Yarrow, but for the details of
5473 Yarrow-256, as implemented by Nettle, you have to consult the source
5474 code. Maybe a complete specification can be written later.
5475 </p>
5476 <p>Yarrow can use many sources (at least two are needed for proper
5477 reseeding), and two randomness &ldquo;pools&rdquo;, referred to as the &ldquo;slow pool&rdquo; and
5478 the &ldquo;fast pool&rdquo;. Input from the sources is fed alternatingly into the
5479 two pools. When one of the sources has contributed 100 bits of entropy
5480 to the fast pool, a &ldquo;fast reseed&rdquo; happens and the fast pool is mixed
5481 into the internal state. When at least two of the sources have
5482 contributed at least 160 bits each to the slow pool, a &ldquo;slow reseed&rdquo;
5483 takes place. The contents of both pools are mixed into the internal
5484 state. These procedures should ensure that the generator will eventually
5485 recover after a key compromise.
5486 </p>
5487 <p>The output is generated by using <acronym>AES</acronym> to encrypt a counter,
5488 using the generator&rsquo;s current key. After each request for output,
5489 another 256 bits are generated which replace the key. This ensures
5490 forward secrecy.
5491 </p>
5492 <p>Yarrow can also use a <em>seed file</em> to save state across restarts.
5493 Yarrow is seeded by either feeding it the contents of the previous seed
5494 file, or feeding it input from its sources until a slow reseed happens.
5495 </p>
5496 <p>Nettle defines Yarrow-256 in <samp>&lt;nettle/yarrow.h&gt;</samp>.
5497 </p>
5498 <dl>
5499 <dt><a name="index-struct-yarrow256_005fctx"></a>Context struct: <strong>struct yarrow256_ctx</strong></dt>
5500 </dl>
5501
5502 <dl>
5503 <dt><a name="index-struct-yarrow_005fsource"></a>Context struct: <strong>struct yarrow_source</strong></dt>
5504 <dd><p>Information about a single source.
5505 </p></dd></dl>
5506
5507 <dl>
5508 <dt><a name="index-YARROW256_005fSEED_005fFILE_005fSIZE"></a>Constant: <strong>YARROW256_SEED_FILE_SIZE</strong></dt>
5509 <dd><p>Recommended size of the Yarrow-256 seed file.
5510 </p></dd></dl>
5511
5512 <dl>
5513 <dt><a name="index-yarrow256_005finit"></a>Function: <em>void</em> <strong>yarrow256_init</strong> <em>(struct yarrow256_ctx *<var>ctx</var>, unsigned <var>nsources</var>, struct yarrow_source *<var>sources</var>)</em></dt>
5514 <dd><p>Initializes the yarrow context, and its <var>nsources</var> sources. It&rsquo;s
5515 possible to call it with <var>nsources</var>=0 and <var>sources</var>=NULL, if
5516 you don&rsquo;t need the update features.
5517 </p></dd></dl>
5518
5519 <dl>
5520 <dt><a name="index-yarrow256_005fseed"></a>Function: <em>void</em> <strong>yarrow256_seed</strong> <em>(struct yarrow256_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>seed_file</var>)</em></dt>
5521 <dd><p>Seeds Yarrow-256 from a previous seed file. <var>length</var> should be at least
5522 <code>YARROW256_SEED_FILE_SIZE</code>, but it can be larger.
5523 </p>
5524 <p>The generator will trust you that the <var>seed_file</var> data really is
5525 unguessable. After calling this function, you <em>must</em> overwrite the old
5526 seed file with newly generated data from <code>yarrow256_random</code>. If it&rsquo;s
5527 possible for several processes to read the seed file at about the same
5528 time, access must be coordinated using some locking mechanism.
5529 </p></dd></dl>
5530
5531 <dl>
5532 <dt><a name="index-yarrow256_005fupdate"></a>Function: <em>int</em> <strong>yarrow256_update</strong> <em>(struct yarrow256_ctx *<var>ctx</var>, unsigned <var>source</var>, unsigned <var>entropy</var>, size_t <var>length</var>, const uint8_t *<var>data</var>)</em></dt>
5533 <dd><p>Updates the generator with data from source <var>SOURCE</var> (an index that
5534 must be smaller than the number of sources). <var>entropy</var> is your
5535 estimated lower bound for the entropy in the data, measured in bits.
5536 Calling update with zero <var>entropy</var> is always safe, no matter if the
5537 data is random or not.
5538 </p>
5539 <p>Returns 1 if a reseed happened, in which case an application using a
5540 seed file may want to generate new seed data with
5541 <code>yarrow256_random</code> and overwrite the seed file. Otherwise, the
5542 function returns 0.
5543 </p></dd></dl>
5544
5545 <dl>
5546 <dt><a name="index-yarrow256_005frandom"></a>Function: <em>void</em> <strong>yarrow256_random</strong> <em>(struct yarrow256_ctx *<var>ctx</var>, size_t <var>length</var>, uint8_t *<var>dst</var>)</em></dt>
5547 <dd><p>Generates <var>length</var> octets of output. The generator must be seeded
5548 before you call this function.
5549 </p>
5550 <p>If you don&rsquo;t need forward secrecy, e.g. if you need non-secret
5551 randomness for initialization vectors or padding, you can gain some
5552 efficiency by buffering, calling this function for reasonably large
5553 blocks of data, say 100-1000 octets at a time.
5554 </p></dd></dl>
5555
5556 <dl>
5557 <dt><a name="index-yarrow256_005fis_005fseeded"></a>Function: <em>int</em> <strong>yarrow256_is_seeded</strong> <em>(struct yarrow256_ctx *<var>ctx</var>)</em></dt>
5558 <dd><p>Returns 1 if the generator is seeded and ready to generate output,
5559 otherwise 0.
5560 </p></dd></dl>
5561
5562 <dl>
5563 <dt><a name="index-yarrow256_005fneeded_005fsources"></a>Function: <em>unsigned</em> <strong>yarrow256_needed_sources</strong> <em>(struct yarrow256_ctx *<var>ctx</var>)</em></dt>
5564 <dd><p>Returns the number of sources that must reach the threshold before a
5565 slow reseed will happen. Useful primarily when the generator is unseeded.
5566 </p></dd></dl>
5567
5568 <dl>
5569 <dt><a name="index-yarrow256_005ffast_005freseed"></a>Function: <em>void</em> <strong>yarrow256_fast_reseed</strong> <em>(struct yarrow256_ctx *<var>ctx</var>)</em></dt>
5570 <dt><a name="index-yarrow256_005fslow_005freseed"></a>Function: <em>void</em> <strong>yarrow256_slow_reseed</strong> <em>(struct yarrow256_ctx *<var>ctx</var>)</em></dt>
5571 <dd><p>Causes a fast or slow reseed to take place immediately, regardless of the
5572 current entropy estimates of the two pools. Use with care.
5573 </p></dd></dl>
5574
5575 <p>Nettle includes an entropy estimator for one kind of input source: User
5576 keyboard input.
5577 </p>
5578 <dl>
5579 <dt><a name="index-struct-yarrow_005fkey_005fevent_005fctx"></a>Context struct: <strong>struct yarrow_key_event_ctx</strong></dt>
5580 <dd><p>Information about recent key events.
5581 </p></dd></dl>
5582
5583 <dl>
5584 <dt><a name="index-yarrow_005fkey_005fevent_005finit"></a>Function: <em>void</em> <strong>yarrow_key_event_init</strong> <em>(struct yarrow_key_event_ctx *<var>ctx</var>)</em></dt>
5585 <dd><p>Initializes the context.
5586 </p></dd></dl>
5587
5588 <dl>
5589 <dt><a name="index-yarrow_005fkey_005fevent_005festimate"></a>Function: <em>unsigned</em> <strong>yarrow_key_event_estimate</strong> <em>(struct yarrow_key_event_ctx *<var>ctx</var>, unsigned <var>key</var>, unsigned <var>time</var>)</em></dt>
5590 <dd><p><var>key</var> is the id of the key (ASCII value, hardware key code, X
5591 keysym, &hellip;, it doesn&rsquo;t matter), and <var>time</var> is the timestamp of
5592 the event. The time must be given in units matching the resolution by
5593 which you read the clock. If you read the clock with microsecond
5594 precision, <var>time</var> should be provided in units of microseconds. But
5595 if you use <code>gettimeofday</code> on a typical Unix system where the clock
5596 ticks 10 or so microseconds at a time, <var>time</var> should be given in
5597 units of 10 microseconds.
5598 </p>
5599 <p>Returns an entropy estimate, in bits, suitable for calling
5600 <code>yarrow256_update</code>. Usually, 0, 1 or 2 bits.
5601 </p></dd></dl>
5602
5603 <hr>
5604 <a name="ASCII-encoding"></a>
5605 <div class="header">
5606 <p>
5607 Next: <a href="#Miscellaneous-functions" accesskey="n" rel="next">Miscellaneous functions</a>, Previous: <a href="#Randomness" accesskey="p" rel="prev">Randomness</a>, Up: <a href="#Reference" accesskey="u" rel="up">Reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
5608 </div>
5609 <a name="ASCII-encoding-1"></a>
5610 <h3 class="section">6.9 ASCII encoding</h3>
5611
5612 <p>Encryption will transform your data from text into binary format, and that
5613 may be a problem if, for example, you want to send the data as if it was
5614 plain text in an email, or store it along with descriptive text in a
5615 file. You may then use an encoding from binary to text: each binary byte
5616 is translated into a number of bytes of plain text.
5617 </p>
5618 <p>A base-N encoding of data is one representation of data that only uses N
5619 different symbols (instead of the 256 possible values of a byte).
5620 </p>
5621 <p>The base64 encoding will always use alphanumeric (upper and lower case)
5622 characters and the &rsquo;+&rsquo;, &rsquo;/&rsquo; and &rsquo;=&rsquo; symbols to represent the data. Four
5623 output characters are generated for each three bytes of input. In case
5624 the length of the input is not a multiple of three, padding characters
5625 are added at the end. There&rsquo;s also a &ldquo;URL safe&rdquo; variant, which is
5626 useful for encoding binary data into URLs and filenames. See <cite>RFC
5627 4648</cite>.
5628 </p>
5629 <p>The base16 encoding, also known as &ldquo;hexadecimal&rdquo;, uses the decimal
5630 digits and the letters from A to F. Two hexadecimal digits are generated
5631 for each input byte.
5632 </p>
5633 <p>Nettle supports both base64 and base16 encoding and decoding.
5634 </p>
5635 <p>Encoding and decoding uses a context struct to maintain its state (with
5636 the exception of base16 encoding, which doesn&rsquo;t need any). To encode or
5637 decode the data, first initialize the context, then call the update
5638 function as many times as necessary, and complete the operation by
5639 calling the final function.
5640 </p>
5641 <p>The following functions can be used to perform base64 encoding and decoding.
5642 They are defined in <samp>&lt;nettle/base64.h&gt;</samp>.
5643 </p>
5644 <dl>
5645 <dt><a name="index-struct-base64_005fencode_005fctx"></a>Context struct: <strong>struct base64_encode_ctx</strong></dt>
5646 </dl>
5647
5648 <dl>
5649 <dt><a name="index-base64_005fencode_005finit"></a>Function: <em>void</em> <strong>base64_encode_init</strong> <em>(struct base64_encode_ctx *<var>ctx</var>)</em></dt>
5650 <dt><a name="index-base64url_005fencode_005finit"></a>Function: <em>void</em> <strong>base64url_encode_init</strong> <em>(struct base64_encode_ctx *<var>ctx</var>)</em></dt>
5651 <dd><p>Initializes a base64 context. This is necessary before starting an
5652 encoding session. <code>base64_encode_init</code> selects the standard base64
5653 alphabet, while <code>base64url_encode_init</code> selects the URL safe
5654 alphabet.
5655 </p></dd></dl>
5656
5657
5658 <dl>
5659 <dt><a name="index-base64_005fencode_005fsingle"></a>Function: <em>size_t</em> <strong>base64_encode_single</strong> <em>(struct base64_encode_ctx *<var>ctx</var>, uint8_t *<var>dst</var>, uint8_t <var>src</var>)</em></dt>
5660 <dd><p>Encodes a single byte. Returns amount of output (always 1 or 2).
5661 </p></dd></dl>
5662
5663 <dl>
5664 <dt><a name="index-BASE64_005fENCODE_005fLENGTH"></a>Macro: <strong>BASE64_ENCODE_LENGTH</strong> <em>(<var>length</var>)</em></dt>
5665 <dd><p>The maximum number of output bytes when passing <var>length</var> input bytes
5666 to <code>base64_encode_update</code>.
5667 </p></dd></dl>
5668
5669 <dl>
5670 <dt><a name="index-base64_005fencode_005fupdate"></a>Function: <em>size_t</em> <strong>base64_encode_update</strong> <em>(struct base64_encode_ctx *<var>ctx</var>, uint8_t *<var>dst</var>, size_t <var>length</var>, const uint8_t *<var>src</var>)</em></dt>
5671 <dd><p>After <var>ctx</var> is initialized, this function may be called to encode <var>length</var>
5672 bytes from <var>src</var>. The result will be placed in <var>dst</var>, and the return value
5673 will be the number of bytes generated. Note that <var>dst</var> must be at least of size
5674 BASE64_ENCODE_LENGTH(<var>length</var>).
5675 </p></dd></dl>
5676
5677 <dl>
5678 <dt><a name="index-BASE64_005fENCODE_005fFINAL_005fLENGTH"></a>Constant: <strong>BASE64_ENCODE_FINAL_LENGTH</strong></dt>
5679 <dd><p>The maximum amount of output from <code>base64_encode_final</code>.
5680 </p></dd></dl>
5681
5682 <dl>
5683 <dt><a name="index-base64_005fencode_005ffinal"></a>Function: <em>size_t</em> <strong>base64_encode_final</strong> <em>(struct base64_encode_ctx *<var>ctx</var>, uint8_t *<var>dst</var>)</em></dt>
5684 <dd><p>After calling base64_encode_update one or more times, this function
5685 should be called to generate the final output bytes, including any
5686 needed paddding. The return value is the number of output bytes
5687 generated.
5688 </p></dd></dl>
5689
5690 <dl>
5691 <dt><a name="index-struct-base64_005fdecode_005fctx"></a>Context struct: <strong>struct base64_decode_ctx</strong></dt>
5692 </dl>
5693
5694 <dl>
5695 <dt><a name="index-base64_005fdecode_005finit"></a>Function: <em>void</em> <strong>base64_decode_init</strong> <em>(struct base64_decode_ctx *<var>ctx</var>)</em></dt>
5696 <dt><a name="index-base64url_005fdecode_005finit"></a>Function: <em>void</em> <strong>base64url_decode_init</strong> <em>(struct base64_decode_ctx *<var>ctx</var>)</em></dt>
5697 <dd><p>Initializes a base64 decoding context. This is necessary before starting
5698 a decoding session. <code>base64_decode_init</code> selects the standard
5699 base64 alphabet, while <code>base64url_decode_init</code> selects the URL safe
5700 alphabet.
5701 </p></dd></dl>
5702
5703 <dl>
5704 <dt><a name="index-base64_005fdecode_005fsingle"></a>Function: <em>int</em> <strong>base64_decode_single</strong> <em>(struct base64_decode_ctx *<var>ctx</var>, uint8_t *<var>dst</var>, uint8_t <var>src</var>)</em></dt>
5705 <dd><p>Decodes a single byte (<var>src</var>) and stores the result in <var>dst</var>.
5706 Returns amount of output (0 or 1), or -1 on errors.
5707 </p></dd></dl>
5708
5709 <dl>
5710 <dt><a name="index-BASE64_005fDECODE_005fLENGTH"></a>Macro: <strong>BASE64_DECODE_LENGTH</strong> <em>(<var>length</var>)</em></dt>
5711 <dd><p>The maximum number of output bytes when passing <var>length</var> input bytes
5712 to <code>base64_decode_update</code>.
5713 </p></dd></dl>
5714
5715 <dl>
5716 <dt><a name="index-base64_005fdecode_005fupdate"></a>Function: <em>void</em> <strong>base64_decode_update</strong> <em>(struct base64_decode_ctx *<var>ctx</var>, size_t *<var>dst_length</var>, uint8_t *<var>dst</var>, size_t <var>src_length</var>, const uint8_t *<var>src</var>)</em></dt>
5717 <dd><p>After <var>ctx</var> is initialized, this function may be called to decode
5718 <var>src_length</var> bytes from <var>src</var>. <var>dst</var> should point to an area
5719 of size at least BASE64_DECODE_LENGTH(<var>src_length</var>). The amount of data
5720 generated is returned in *<var>dst_length</var>. Returns 1 on success
5721 and 0 on error.
5722 </p></dd></dl>
5723
5724 <dl>
5725 <dt><a name="index-base64_005fdecode_005ffinal"></a>Function: <em>int</em> <strong>base64_decode_final</strong> <em>(struct base64_decode_ctx *<var>ctx</var>)</em></dt>
5726 <dd><p>Check that final padding is correct. Returns 1 on success, and 0 on
5727 error.
5728 </p></dd></dl>
5729
5730 <p>Similarly to the base64 functions, the following functions perform base16 encoding,
5731 and are defined in <samp>&lt;nettle/base16.h&gt;</samp>. Note that there is no encoding context
5732 necessary for doing base16 encoding.
5733 </p>
5734 <dl>
5735 <dt><a name="index-base16_005fencode_005fsingle"></a>Function: <em>void</em> <strong>base16_encode_single</strong> <em>(uint8_t *<var>dst</var>, uint8_t <var>src</var>)</em></dt>
5736 <dd><p>Encodes a single byte. Always stores two digits in <var>dst</var>[0] and <var>dst</var>[1].
5737 </p></dd></dl>
5738
5739 <dl>
5740 <dt><a name="index-BASE16_005fENCODE_005fLENGTH"></a>Macro: <strong>BASE16_ENCODE_LENGTH</strong> <em>(<var>length</var>)</em></dt>
5741 <dd><p>The number of output bytes when passing <var>length</var> input bytes to
5742 <code>base16_encode_update</code>.
5743 </p></dd></dl>
5744
5745 <dl>
5746 <dt><a name="index-base16_005fencode_005fupdate"></a>Function: <em>void</em> <strong>base16_encode_update</strong> <em>(uint8_t *<var>dst</var>, size_t <var>length</var>, const uint8_t *<var>src</var>)</em></dt>
5747 <dd><p>Always stores BASE16_ENCODE_LENGTH(<var>length</var>) digits in <var>dst</var>.
5748 </p></dd></dl>
5749
5750 <dl>
5751 <dt><a name="index-struct-base16_005fdecode_005fctx"></a>Context struct: <strong>struct base16_decode_ctx</strong></dt>
5752 </dl>
5753
5754 <dl>
5755 <dt><a name="index-base16_005fdecode_005finit"></a>Function: <em>void</em> <strong>base16_decode_init</strong> <em>(struct base16_decode_ctx *<var>ctx</var>)</em></dt>
5756 <dd><p>Initializes a base16 decoding context. This is necessary before starting a decoding
5757 session.
5758 </p></dd></dl>
5759
5760 <dl>
5761 <dt><a name="index-base16_005fdecode_005fsingle"></a>Function: <em>int</em> <strong>base16_decode_single</strong> <em>(struct base16_decode_ctx *<var>ctx</var>, uint8_t *<var>dst</var>, uint8_t <var>src</var>)</em></dt>
5762 <dd><p>Decodes a single byte from <var>src</var> into <var>dst</var>. Returns amount of output (0 or 1), or -1 on errors.
5763 </p></dd></dl>
5764
5765 <dl>
5766 <dt><a name="index-BASE16_005fDECODE_005fLENGTH"></a>Macro: <strong>BASE16_DECODE_LENGTH</strong> <em>(<var>length</var>)</em></dt>
5767 <dd><p>The maximum number of output bytes when passing <var>length</var> input bytes
5768 to <code>base16_decode_update</code>.
5769 </p></dd></dl>
5770
5771 <dl>
5772 <dt><a name="index-base16_005fdecode_005fupdate"></a>Function: <em>int</em> <strong>base16_decode_update</strong> <em>(struct base16_decode_ctx *<var>ctx</var>, size_t *<var>dst_length</var>, uint8_t *<var>dst</var>, size_t <var>src_length</var>, const uint8_t *<var>src</var>)</em></dt>
5773 <dd><p>After <var>ctx</var> is initialized, this function may be called to decode
5774 <var>src_length</var> bytes from <var>src</var>. <var>dst</var> should point to an area
5775 of size at least BASE16_DECODE_LENGTH(<var>src_length</var>). The amount of data
5776 generated is returned in *<var>dst_length</var>. Returns 1 on success
5777 and 0 on error.
5778 </p></dd></dl>
5779
5780 <dl>
5781 <dt><a name="index-base16_005fdecode_005ffinal"></a>Function: <em>int</em> <strong>base16_decode_final</strong> <em>(struct base16_decode_ctx *<var>ctx</var>)</em></dt>
5782 <dd><p>Checks that the end of data is correct (i.e., an even number of
5783 hexadecimal digits have been seen). Returns 1 on success, and 0 on
5784 error.
5785 </p></dd></dl>
5786
5787 <hr>
5788 <a name="Miscellaneous-functions"></a>
5789 <div class="header">
5790 <p>
5791 Next: <a href="#Compatibility-functions" accesskey="n" rel="next">Compatibility functions</a>, Previous: <a href="#ASCII-encoding" accesskey="p" rel="prev">ASCII encoding</a>, Up: <a href="#Reference" accesskey="u" rel="up">Reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
5792 </div>
5793 <a name="Miscellaneous-functions-1"></a>
5794 <h3 class="section">6.10 Miscellaneous functions</h3>
5795
5796 <dl>
5797 <dt><a name="index-memxor"></a>Function: <em>void *</em> <strong>memxor</strong> <em>(void *<var>dst</var>, const void *<var>src</var>, size_t <var>n</var>)</em></dt>
5798 <dd><p>XORs the source area on top of the destination area. The interface
5799 doesn&rsquo;t follow the Nettle conventions, because it is intended to be
5800 similar to the ANSI-C <code>memcpy</code> function.
5801 </p></dd></dl>
5802
5803 <dl>
5804 <dt><a name="index-memxor3"></a>Function: <em>void *</em> <strong>memxor3</strong> <em>(void *<var>dst</var>, const void *<var>a</var>, const void *<var>b</var>, size_t <var>n</var>)</em></dt>
5805 <dd><p>Like <code>memxor</code>, but takes two source areas and separate
5806 destination area.
5807 </p></dd></dl>
5808
5809
5810 <p><code>memxor</code> is declared in <samp>&lt;nettle/memxor.h&gt;</samp>.
5811 </p>
5812 <hr>
5813 <a name="Compatibility-functions"></a>
5814 <div class="header">
5815 <p>
5816 Previous: <a href="#Miscellaneous-functions" accesskey="p" rel="prev">Miscellaneous functions</a>, Up: <a href="#Reference" accesskey="u" rel="up">Reference</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
5817 </div>
5818 <a name="Compatibility-functions-1"></a>
5819 <h3 class="section">6.11 Compatibility functions</h3>
5820
5821 <p>For convenience, Nettle includes alternative interfaces to some
5822 algorithms, for compatibility with some other popular crypto toolkits.
5823 These are not fully documented here; refer to the source or to the
5824 documentation for the original implementation.
5825 </p>
5826 <p>MD5 is defined in [RFC 1321], which includes a reference implementation.
5827 Nettle defines a compatible interface to MD5 in
5828 <samp>&lt;nettle/md5-compat.h&gt;</samp>. This file defines the typedef
5829 <code>MD5_CTX</code>, and declares the functions <code>MD5Init</code>, <code>MD5Update</code> and
5830 <code>MD5Final</code>.
5831 </p>
5832 <p>Eric Young&rsquo;s &ldquo;libdes&rdquo; (also part of OpenSSL) is a quite popular DES
5833 implementation. Nettle includes a subset if its interface in
5834 <samp>&lt;nettle/des-compat.h&gt;</samp>. This file defines the typedefs
5835 <code>des_key_schedule</code> and <code>des_cblock</code>, two constants
5836 <code>DES_ENCRYPT</code> and <code>DES_DECRYPT</code>, and declares one global
5837 variable <code>des_check_key</code>, and the functions <code>des_cbc_cksum</code>
5838 <code>des_cbc_encrypt</code>, <code>des_ecb2_encrypt</code>,
5839 <code>des_ecb3_encrypt</code>, <code>des_ecb_encrypt</code>,
5840 <code>des_ede2_cbc_encrypt</code>, <code>des_ede3_cbc_encrypt</code>,
5841 <code>des_is_weak_key</code>, <code>des_key_sched</code>, <code>des_ncbc_encrypt</code>
5842 <code>des_set_key</code>, and <code>des_set_odd_parity</code>.
5843 </p>
5844 <hr>
5845 <a name="Nettle-soup"></a>
5846 <div class="header">
5847 <p>
5848 Next: <a href="#Installation" accesskey="n" rel="next">Installation</a>, Previous: <a href="#Reference" accesskey="p" rel="prev">Reference</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
5849 </div>
5850 <a name="Traditional-Nettle-Soup"></a>
5851 <h2 class="chapter">7 Traditional Nettle Soup</h2>
5852 <p>For the serious nettle hacker, here is a recipe for nettle soup. 4 servings.
5853 </p>
5854 <ul class="no-bullet">
5855 <li><!-- /@w --> 1 liter fresh nettles (urtica dioica)
5856 </li><li><!-- /@w --> 2 tablespoons butter
5857 </li><li><!-- /@w --> 3 tablespoons flour
5858 </li><li><!-- /@w --> 1 liter stock (meat or vegetable)
5859 </li><li><!-- /@w --> 1/2 teaspoon salt
5860 </li><li><!-- /@w --> a tad white pepper
5861 </li><li><!-- /@w --> some cream or milk
5862 </li></ul>
5863
5864 <p>Gather 1 liter fresh nettles. Use gloves! Small, tender shoots are
5865 preferable but the tops of larger nettles can also be used.
5866 </p>
5867 <p>Rinse the nettles very well. Boil them for 10 minutes in lightly salted
5868 water. Strain the nettles and save the water. Hack the nettles. Melt the
5869 butter and mix in the flour. Dilute with stock and the nettle-water you
5870 saved earlier. Add the hacked nettles. If you wish you can add some milk
5871 or cream at this stage. Bring to a boil and let boil for a few minutes.
5872 Season with salt and pepper.
5873 </p>
5874 <p>Serve with boiled egg-halves.
5875 </p>
5876
5877 <hr>
5878 <a name="Installation"></a>
5879 <div class="header">
5880 <p>
5881 Next: <a href="#Index" accesskey="n" rel="next">Index</a>, Previous: <a href="#Nettle-soup" accesskey="p" rel="prev">Nettle soup</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
5882 </div>
5883 <a name="Installation-1"></a>
5884 <h2 class="chapter">8 Installation</h2>
5885
5886 <p>Nettle uses <code>autoconf</code>. To build it, unpack the source and run
5887 </p>
5888 <div class="example">
5889 <pre class="example">./configure
5890 make
5891 make check
5892 make install
5893 </pre></div>
5894
5895 <p>to install it under the default prefix, <samp>/usr/local</samp>. Using GNU
5896 make is strongly recommended. By default, both static and shared
5897 libraries are built and installed.
5898 </p>
5899 <p>To get a list of configure options, use <code>./configure --help</code>. Some
5900 of the more interesting are:
5901 </p>
5902 <dl compact="compact">
5903 <dt><samp>--enable-fat</samp></dt>
5904 <dd><p>Include multiple versions of certain functions in the library, and
5905 select the ones to use at run-time, depending on available processor
5906 features. Supported for ARM and x86_64.
5907 </p>
5908 </dd>
5909 <dt><samp>--enable-mini-gmp</samp></dt>
5910 <dd><p>Use the smaller and slower &ldquo;mini-gmp&rdquo; implementation of the bignum
5911 functions needed for public-key cryptography, instead of the real GNU
5912 GMP library. This option is intended primarily for smaller embedded
5913 systems. Note that builds using mini-gmp are <strong>not</strong> binary compatible
5914 with regular builds of Nettle, and more likely to leak side-channel
5915 information.
5916 </p>
5917 </dd>
5918 <dt><samp>--disable-shared</samp></dt>
5919 <dd><p>Omit building the shared libraries.
5920 </p>
5921 </dd>
5922 <dt><samp>--disable-dependency-tracking</samp></dt>
5923 <dd><p>Disable the automatic dependency tracking. You will likely need this
5924 option to be able to build with BSD make.
5925 </p>
5926 </dd>
5927 </dl>
5928
5929 <hr>
5930 <a name="Index"></a>
5931 <div class="header">
5932 <p>
5933 Previous: <a href="#Installation" accesskey="p" rel="prev">Installation</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
5934 </div>
5935 <a name="Function-and-Concept-Index"></a>
5936 <h2 class="unnumbered">Function and Concept Index</h2>
5937
5938 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Index_cp_letter-A"><b>A</b></a>
5939  &nbsp;
5940 <a class="summary-letter" href="#Index_cp_letter-B"><b>B</b></a>
5941  &nbsp;
5942 <a class="summary-letter" href="#Index_cp_letter-C"><b>C</b></a>
5943  &nbsp;
5944 <a class="summary-letter" href="#Index_cp_letter-D"><b>D</b></a>
5945  &nbsp;
5946 <a class="summary-letter" href="#Index_cp_letter-E"><b>E</b></a>
5947  &nbsp;
5948 <a class="summary-letter" href="#Index_cp_letter-G"><b>G</b></a>
5949  &nbsp;
5950 <a class="summary-letter" href="#Index_cp_letter-H"><b>H</b></a>
5951  &nbsp;
5952 <a class="summary-letter" href="#Index_cp_letter-K"><b>K</b></a>
5953  &nbsp;
5954 <a class="summary-letter" href="#Index_cp_letter-M"><b>M</b></a>
5955  &nbsp;
5956 <a class="summary-letter" href="#Index_cp_letter-N"><b>N</b></a>
5957  &nbsp;
5958 <a class="summary-letter" href="#Index_cp_letter-O"><b>O</b></a>
5959  &nbsp;
5960 <a class="summary-letter" href="#Index_cp_letter-P"><b>P</b></a>
5961  &nbsp;
5962 <a class="summary-letter" href="#Index_cp_letter-R"><b>R</b></a>
5963  &nbsp;
5964 <a class="summary-letter" href="#Index_cp_letter-S"><b>S</b></a>
5965  &nbsp;
5966 <a class="summary-letter" href="#Index_cp_letter-T"><b>T</b></a>
5967  &nbsp;
5968 <a class="summary-letter" href="#Index_cp_letter-U"><b>U</b></a>
5969  &nbsp;
5970 <a class="summary-letter" href="#Index_cp_letter-Y"><b>Y</b></a>
5971  &nbsp;
5972 </td></tr></table>
5973 <table class="index-cp" border="0">
5974 <tr><td></td><th align="left">Index Entry</th><td>&nbsp;</td><th align="left"> Section</th></tr>
5975 <tr><td colspan="4"> <hr></td></tr>
5976 <tr><th><a name="Index_cp_letter-A">A</a></th><td></td><td></td></tr>
5977 <tr><td></td><td valign="top"><a href="#index-AEAD">AEAD</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Authenticated-encryption">Authenticated encryption</a></td></tr>
5978 <tr><td></td><td valign="top"><a href="#index-aes128_005fdecrypt"><code>aes128_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5979 <tr><td></td><td valign="top"><a href="#index-aes128_005fencrypt"><code>aes128_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5980 <tr><td></td><td valign="top"><a href="#index-aes128_005finvert_005fkey"><code>aes128_invert_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5981 <tr><td></td><td valign="top"><a href="#index-aes128_005fset_005fdecrypt_005fkey"><code>aes128_set_decrypt_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5982 <tr><td></td><td valign="top"><a href="#index-aes128_005fset_005fencrypt_005fkey"><code>aes128_set_encrypt_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5983 <tr><td></td><td valign="top"><a href="#index-aes192_005fdecrypt"><code>aes192_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5984 <tr><td></td><td valign="top"><a href="#index-aes192_005fencrypt"><code>aes192_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5985 <tr><td></td><td valign="top"><a href="#index-aes192_005finvert_005fkey"><code>aes192_invert_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5986 <tr><td></td><td valign="top"><a href="#index-aes192_005fset_005fdecrypt_005fkey"><code>aes192_set_decrypt_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5987 <tr><td></td><td valign="top"><a href="#index-aes192_005fset_005fencrypt_005fkey"><code>aes192_set_encrypt_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5988 <tr><td></td><td valign="top"><a href="#index-aes256_005fdecrypt"><code>aes256_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5989 <tr><td></td><td valign="top"><a href="#index-aes256_005fencrypt"><code>aes256_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5990 <tr><td></td><td valign="top"><a href="#index-aes256_005finvert_005fkey"><code>aes256_invert_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5991 <tr><td></td><td valign="top"><a href="#index-aes256_005fset_005fdecrypt_005fkey"><code>aes256_set_decrypt_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5992 <tr><td></td><td valign="top"><a href="#index-aes256_005fset_005fencrypt_005fkey"><code>aes256_set_encrypt_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5993 <tr><td></td><td valign="top"><a href="#index-aes_005fdecrypt"><code>aes_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5994 <tr><td></td><td valign="top"><a href="#index-aes_005fencrypt"><code>aes_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5995 <tr><td></td><td valign="top"><a href="#index-aes_005finvert_005fkey"><code>aes_invert_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5996 <tr><td></td><td valign="top"><a href="#index-aes_005fset_005fdecrypt_005fkey"><code>aes_set_decrypt_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5997 <tr><td></td><td valign="top"><a href="#index-aes_005fset_005fencrypt_005fkey"><code>aes_set_encrypt_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5998 <tr><td></td><td valign="top"><a href="#index-arcfour_005fcrypt"><code>arcfour_crypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
5999 <tr><td></td><td valign="top"><a href="#index-arcfour_005fset_005fkey"><code>arcfour_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6000 <tr><td></td><td valign="top"><a href="#index-arctwo_005fdecrypt"><code>arctwo_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6001 <tr><td></td><td valign="top"><a href="#index-arctwo_005fencrypt"><code>arctwo_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6002 <tr><td></td><td valign="top"><a href="#index-arctwo_005fset_005fkey"><code>arctwo_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6003 <tr><td></td><td valign="top"><a href="#index-arctwo_005fset_005fkey_005fekb"><code>arctwo_set_key_ekb</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6004 <tr><td></td><td valign="top"><a href="#index-arctwo_005fset_005fkey_005fgutmann"><code>arctwo_set_key_gutmann</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6005 <tr><td></td><td valign="top"><a href="#index-Authenticated-encryption">Authenticated encryption</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Authenticated-encryption">Authenticated encryption</a></td></tr>
6006 <tr><td colspan="4"> <hr></td></tr>
6007 <tr><th><a name="Index_cp_letter-B">B</a></th><td></td><td></td></tr>
6008 <tr><td></td><td valign="top"><a href="#index-base16_005fdecode_005ffinal"><code>base16_decode_final</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6009 <tr><td></td><td valign="top"><a href="#index-base16_005fdecode_005finit"><code>base16_decode_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6010 <tr><td></td><td valign="top"><a href="#index-BASE16_005fDECODE_005fLENGTH"><code>BASE16_DECODE_LENGTH</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6011 <tr><td></td><td valign="top"><a href="#index-base16_005fdecode_005fsingle"><code>base16_decode_single</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6012 <tr><td></td><td valign="top"><a href="#index-base16_005fdecode_005fupdate"><code>base16_decode_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6013 <tr><td></td><td valign="top"><a href="#index-BASE16_005fENCODE_005fLENGTH"><code>BASE16_ENCODE_LENGTH</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6014 <tr><td></td><td valign="top"><a href="#index-base16_005fencode_005fsingle"><code>base16_encode_single</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6015 <tr><td></td><td valign="top"><a href="#index-base16_005fencode_005fupdate"><code>base16_encode_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6016 <tr><td></td><td valign="top"><a href="#index-base64url_005fdecode_005finit"><code>base64url_decode_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6017 <tr><td></td><td valign="top"><a href="#index-base64url_005fencode_005finit"><code>base64url_encode_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6018 <tr><td></td><td valign="top"><a href="#index-base64_005fdecode_005ffinal"><code>base64_decode_final</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6019 <tr><td></td><td valign="top"><a href="#index-base64_005fdecode_005finit"><code>base64_decode_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6020 <tr><td></td><td valign="top"><a href="#index-BASE64_005fDECODE_005fLENGTH"><code>BASE64_DECODE_LENGTH</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6021 <tr><td></td><td valign="top"><a href="#index-base64_005fdecode_005fsingle"><code>base64_decode_single</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6022 <tr><td></td><td valign="top"><a href="#index-base64_005fdecode_005fupdate"><code>base64_decode_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6023 <tr><td></td><td valign="top"><a href="#index-base64_005fencode_005ffinal"><code>base64_encode_final</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6024 <tr><td></td><td valign="top"><a href="#index-base64_005fencode_005finit"><code>base64_encode_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6025 <tr><td></td><td valign="top"><a href="#index-BASE64_005fENCODE_005fLENGTH"><code>BASE64_ENCODE_LENGTH</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6026 <tr><td></td><td valign="top"><a href="#index-base64_005fencode_005fsingle"><code>base64_encode_single</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6027 <tr><td></td><td valign="top"><a href="#index-base64_005fencode_005fupdate"><code>base64_encode_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ASCII-encoding">ASCII encoding</a></td></tr>
6028 <tr><td></td><td valign="top"><a href="#index-Block-Cipher">Block Cipher</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6029 <tr><td></td><td valign="top"><a href="#index-blowfish_005fdecrypt"><code>blowfish_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6030 <tr><td></td><td valign="top"><a href="#index-blowfish_005fencrypt"><code>blowfish_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6031 <tr><td></td><td valign="top"><a href="#index-blowfish_005fset_005fkey"><code>blowfish_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6032 <tr><td colspan="4"> <hr></td></tr>
6033 <tr><th><a name="Index_cp_letter-C">C</a></th><td></td><td></td></tr>
6034 <tr><td></td><td valign="top"><a href="#index-camellia128_005fcrypt"><code>camellia128_crypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6035 <tr><td></td><td valign="top"><a href="#index-camellia128_005finvert_005fkey"><code>camellia128_invert_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6036 <tr><td></td><td valign="top"><a href="#index-camellia128_005fset_005fdecrypt_005fkey"><code>camellia128_set_decrypt_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6037 <tr><td></td><td valign="top"><a href="#index-camellia128_005fset_005fencrypt_005fkey"><code>camellia128_set_encrypt_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6038 <tr><td></td><td valign="top"><a href="#index-camellia192_005fcrypt"><code>camellia192_crypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6039 <tr><td></td><td valign="top"><a href="#index-camellia192_005finvert_005fkey"><code>camellia192_invert_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6040 <tr><td></td><td valign="top"><a href="#index-camellia192_005fset_005fdecrypt_005fkey"><code>camellia192_set_decrypt_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6041 <tr><td></td><td valign="top"><a href="#index-camellia192_005fset_005fencrypt_005fkey"><code>camellia192_set_encrypt_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6042 <tr><td></td><td valign="top"><a href="#index-camellia256_005fcrypt"><code>camellia256_crypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6043 <tr><td></td><td valign="top"><a href="#index-camellia256_005finvert_005fkey"><code>camellia256_invert_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6044 <tr><td></td><td valign="top"><a href="#index-camellia256_005fset_005fdecrypt_005fkey"><code>camellia256_set_decrypt_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6045 <tr><td></td><td valign="top"><a href="#index-camellia256_005fset_005fencrypt_005fkey"><code>camellia256_set_encrypt_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6046 <tr><td></td><td valign="top"><a href="#index-camellia_005fcrypt"><code>camellia_crypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6047 <tr><td></td><td valign="top"><a href="#index-camellia_005finvert_005fkey"><code>camellia_invert_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6048 <tr><td></td><td valign="top"><a href="#index-camellia_005fset_005fdecrypt_005fkey"><code>camellia_set_decrypt_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6049 <tr><td></td><td valign="top"><a href="#index-camellia_005fset_005fencrypt_005fkey"><code>camellia_set_encrypt_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6050 <tr><td></td><td valign="top"><a href="#index-cast128_005fdecrypt"><code>cast128_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6051 <tr><td></td><td valign="top"><a href="#index-cast128_005fencrypt"><code>cast128_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6052 <tr><td></td><td valign="top"><a href="#index-cast128_005fset_005fkey"><code>cast128_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6053 <tr><td></td><td valign="top"><a href="#index-CBC-Mode">CBC Mode</a>:</td><td>&nbsp;</td><td valign="top"><a href="#CBC">CBC</a></td></tr>
6054 <tr><td></td><td valign="top"><a href="#index-CBC_005fCTX"><code>CBC_CTX</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CBC">CBC</a></td></tr>
6055 <tr><td></td><td valign="top"><a href="#index-cbc_005fdecrypt"><code>cbc_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CBC">CBC</a></td></tr>
6056 <tr><td></td><td valign="top"><a href="#index-CBC_005fDECRYPT"><code>CBC_DECRYPT</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CBC">CBC</a></td></tr>
6057 <tr><td></td><td valign="top"><a href="#index-cbc_005fencrypt"><code>cbc_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CBC">CBC</a></td></tr>
6058 <tr><td></td><td valign="top"><a href="#index-CBC_005fENCRYPT"><code>CBC_ENCRYPT</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CBC">CBC</a></td></tr>
6059 <tr><td></td><td valign="top"><a href="#index-CBC_005fSET_005fIV"><code>CBC_SET_IV</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CBC">CBC</a></td></tr>
6060 <tr><td></td><td valign="top"><a href="#index-CCM-Mode">CCM Mode</a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6061 <tr><td></td><td valign="top"><a href="#index-ccm_005faes128_005fdecrypt"><code>ccm_aes128_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6062 <tr><td></td><td valign="top"><a href="#index-ccm_005faes128_005fdecrypt_005fmessage"><code>ccm_aes128_decrypt_message</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6063 <tr><td></td><td valign="top"><a href="#index-ccm_005faes128_005fdigest"><code>ccm_aes128_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6064 <tr><td></td><td valign="top"><a href="#index-ccm_005faes128_005fencrypt"><code>ccm_aes128_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6065 <tr><td></td><td valign="top"><a href="#index-ccm_005faes128_005fencrypt_005fmessage"><code>ccm_aes128_encrypt_message</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6066 <tr><td></td><td valign="top"><a href="#index-ccm_005faes128_005fset_005fkey"><code>ccm_aes128_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6067 <tr><td></td><td valign="top"><a href="#index-ccm_005faes128_005fset_005fnonce"><code>ccm_aes128_set_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6068 <tr><td></td><td valign="top"><a href="#index-ccm_005faes128_005fupdate"><code>ccm_aes128_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6069 <tr><td></td><td valign="top"><a href="#index-ccm_005faes192_005fdecrypt"><code>ccm_aes192_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6070 <tr><td></td><td valign="top"><a href="#index-ccm_005faes192_005fdecrypt_005fmessage"><code>ccm_aes192_decrypt_message</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6071 <tr><td></td><td valign="top"><a href="#index-ccm_005faes192_005fdecrypt_005fmessage-1"><code>ccm_aes192_decrypt_message</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6072 <tr><td></td><td valign="top"><a href="#index-ccm_005faes192_005fdigest"><code>ccm_aes192_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6073 <tr><td></td><td valign="top"><a href="#index-ccm_005faes192_005fencrypt"><code>ccm_aes192_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6074 <tr><td></td><td valign="top"><a href="#index-ccm_005faes192_005fencrypt_005fmessage"><code>ccm_aes192_encrypt_message</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6075 <tr><td></td><td valign="top"><a href="#index-ccm_005faes192_005fset_005fkey"><code>ccm_aes192_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6076 <tr><td></td><td valign="top"><a href="#index-ccm_005faes192_005fset_005fnonce"><code>ccm_aes192_set_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6077 <tr><td></td><td valign="top"><a href="#index-ccm_005faes192_005fupdate"><code>ccm_aes192_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6078 <tr><td></td><td valign="top"><a href="#index-ccm_005faes256_005fdecrypt"><code>ccm_aes256_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6079 <tr><td></td><td valign="top"><a href="#index-ccm_005faes256_005fdigest"><code>ccm_aes256_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6080 <tr><td></td><td valign="top"><a href="#index-ccm_005faes256_005fencrypt"><code>ccm_aes256_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6081 <tr><td></td><td valign="top"><a href="#index-ccm_005faes256_005fencrypt_005fmessage"><code>ccm_aes256_encrypt_message</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6082 <tr><td></td><td valign="top"><a href="#index-ccm_005faes256_005fset_005fkey"><code>ccm_aes256_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6083 <tr><td></td><td valign="top"><a href="#index-ccm_005faes256_005fset_005fnonce"><code>ccm_aes256_set_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6084 <tr><td></td><td valign="top"><a href="#index-ccm_005faes256_005fupdate"><code>ccm_aes256_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6085 <tr><td></td><td valign="top"><a href="#index-ccm_005fdecrypt"><code>ccm_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6086 <tr><td></td><td valign="top"><a href="#index-ccm_005fdecrypt_005fmessage"><code>ccm_decrypt_message</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6087 <tr><td></td><td valign="top"><a href="#index-ccm_005fdigest"><code>ccm_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6088 <tr><td></td><td valign="top"><a href="#index-ccm_005fencrypt"><code>ccm_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6089 <tr><td></td><td valign="top"><a href="#index-ccm_005fencrypt_005fmessage"><code>ccm_encrypt_message</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6090 <tr><td></td><td valign="top"><a href="#index-CCM_005fMAX_005fMSG_005fSIZE"><code>CCM_MAX_MSG_SIZE</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6091 <tr><td></td><td valign="top"><a href="#index-ccm_005fset_005fnonce"><code>ccm_set_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6092 <tr><td></td><td valign="top"><a href="#index-ccm_005fupdate"><code>ccm_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6093 <tr><td></td><td valign="top"><a href="#index-chacha_005fcrypt"><code>chacha_crypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6094 <tr><td></td><td valign="top"><a href="#index-chacha_005fpoly1305_005fdecrypt"><code>chacha_poly1305_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ChaCha_002dPoly1305">ChaCha-Poly1305</a></td></tr>
6095 <tr><td></td><td valign="top"><a href="#index-chacha_005fpoly1305_005fdigest"><code>chacha_poly1305_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ChaCha_002dPoly1305">ChaCha-Poly1305</a></td></tr>
6096 <tr><td></td><td valign="top"><a href="#index-chacha_005fpoly1305_005fencrypt"><code>chacha_poly1305_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ChaCha_002dPoly1305">ChaCha-Poly1305</a></td></tr>
6097 <tr><td></td><td valign="top"><a href="#index-chacha_005fpoly1305_005fset_005fkey"><code>chacha_poly1305_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ChaCha_002dPoly1305">ChaCha-Poly1305</a></td></tr>
6098 <tr><td></td><td valign="top"><a href="#index-chacha_005fpoly1305_005fset_005fnonce"><code>chacha_poly1305_set_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ChaCha_002dPoly1305">ChaCha-Poly1305</a></td></tr>
6099 <tr><td></td><td valign="top"><a href="#index-chacha_005fpoly1305_005fupdate"><code>chacha_poly1305_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#ChaCha_002dPoly1305">ChaCha-Poly1305</a></td></tr>
6100 <tr><td></td><td valign="top"><a href="#index-chacha_005fset_005fkey"><code>chacha_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6101 <tr><td></td><td valign="top"><a href="#index-chacha_005fset_005fnonce"><code>chacha_set_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6102 <tr><td></td><td valign="top"><a href="#index-Cipher">Cipher</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6103 <tr><td></td><td valign="top"><a href="#index-Cipher-Block-Chaining">Cipher Block Chaining</a>:</td><td>&nbsp;</td><td valign="top"><a href="#CBC">CBC</a></td></tr>
6104 <tr><td></td><td valign="top"><a href="#index-Collision_002dresistant">Collision-resistant</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Hash-functions">Hash functions</a></td></tr>
6105 <tr><td></td><td valign="top"><a href="#index-Conditional-entropy">Conditional entropy</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Randomness">Randomness</a></td></tr>
6106 <tr><td></td><td valign="top"><a href="#index-Counter-Mode">Counter Mode</a>:</td><td>&nbsp;</td><td valign="top"><a href="#CTR">CTR</a></td></tr>
6107 <tr><td></td><td valign="top"><a href="#index-Counter-with-CBC_002dMAC-Mode">Counter with CBC-MAC Mode</a>:</td><td>&nbsp;</td><td valign="top"><a href="#CCM">CCM</a></td></tr>
6108 <tr><td></td><td valign="top"><a href="#index-CTR-Mode">CTR Mode</a>:</td><td>&nbsp;</td><td valign="top"><a href="#CTR">CTR</a></td></tr>
6109 <tr><td></td><td valign="top"><a href="#index-ctr_005fcrypt"><code>ctr_crypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CTR">CTR</a></td></tr>
6110 <tr><td></td><td valign="top"><a href="#index-CTR_005fCRYPT"><code>CTR_CRYPT</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CTR">CTR</a></td></tr>
6111 <tr><td></td><td valign="top"><a href="#index-CTR_005fCTX"><code>CTR_CTX</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CTR">CTR</a></td></tr>
6112 <tr><td></td><td valign="top"><a href="#index-CTR_005fSET_005fCOUNTER"><code>CTR_SET_COUNTER</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#CTR">CTR</a></td></tr>
6113 <tr><td></td><td valign="top"><a href="#index-curve25519_005fmul"><code>curve25519_mul</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Elliptic-curves">Elliptic curves</a></td></tr>
6114 <tr><td></td><td valign="top"><a href="#index-curve25519_005fmul_005fg"><code>curve25519_mul_g</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Elliptic-curves">Elliptic curves</a></td></tr>
6115 <tr><td colspan="4"> <hr></td></tr>
6116 <tr><th><a name="Index_cp_letter-D">D</a></th><td></td><td></td></tr>
6117 <tr><td></td><td valign="top"><a href="#index-des3_005fdecrypt"><code>des3_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6118 <tr><td></td><td valign="top"><a href="#index-des3_005fencrypt"><code>des3_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6119 <tr><td></td><td valign="top"><a href="#index-des3_005fset_005fkey"><code>des3_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6120 <tr><td></td><td valign="top"><a href="#index-des_005fcheck_005fparity"><code>des_check_parity</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6121 <tr><td></td><td valign="top"><a href="#index-des_005fdecrypt"><code>des_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6122 <tr><td></td><td valign="top"><a href="#index-des_005fencrypt"><code>des_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6123 <tr><td></td><td valign="top"><a href="#index-des_005ffix_005fparity"><code>des_fix_parity</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6124 <tr><td></td><td valign="top"><a href="#index-des_005fset_005fkey"><code>des_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6125 <tr><td></td><td valign="top"><a href="#index-dsa_005fcompat_005fgenerate_005fkeypair"><code>dsa_compat_generate_keypair</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6126 <tr><td></td><td valign="top"><a href="#index-dsa_005fgenerate_005fkeypair"><code>dsa_generate_keypair</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6127 <tr><td></td><td valign="top"><a href="#index-dsa_005fgenerate_005fparams"><code>dsa_generate_params</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6128 <tr><td></td><td valign="top"><a href="#index-dsa_005fparams_005fclear"><code>dsa_params_clear</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6129 <tr><td></td><td valign="top"><a href="#index-dsa_005fparams_005finit"><code>dsa_params_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6130 <tr><td></td><td valign="top"><a href="#index-dsa_005fprivate_005fkey_005fclear"><code>dsa_private_key_clear</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6131 <tr><td></td><td valign="top"><a href="#index-dsa_005fprivate_005fkey_005finit"><code>dsa_private_key_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6132 <tr><td></td><td valign="top"><a href="#index-dsa_005fpublic_005fkey_005fclear"><code>dsa_public_key_clear</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6133 <tr><td></td><td valign="top"><a href="#index-dsa_005fpublic_005fkey_005finit"><code>dsa_public_key_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6134 <tr><td></td><td valign="top"><a href="#index-dsa_005fsha1_005fsign"><code>dsa_sha1_sign</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6135 <tr><td></td><td valign="top"><a href="#index-dsa_005fsha1_005fsign_005fdigest"><code>dsa_sha1_sign_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6136 <tr><td></td><td valign="top"><a href="#index-dsa_005fsha1_005fverify"><code>dsa_sha1_verify</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6137 <tr><td></td><td valign="top"><a href="#index-dsa_005fsha1_005fverify_005fdigest"><code>dsa_sha1_verify_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6138 <tr><td></td><td valign="top"><a href="#index-dsa_005fsha256_005fsign"><code>dsa_sha256_sign</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6139 <tr><td></td><td valign="top"><a href="#index-dsa_005fsha256_005fsign_005fdigest"><code>dsa_sha256_sign_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6140 <tr><td></td><td valign="top"><a href="#index-dsa_005fsha256_005fverify"><code>dsa_sha256_verify</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6141 <tr><td></td><td valign="top"><a href="#index-dsa_005fsha256_005fverify_005fdigest"><code>dsa_sha256_verify_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6142 <tr><td></td><td valign="top"><a href="#index-dsa_005fsign"><code>dsa_sign</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6143 <tr><td></td><td valign="top"><a href="#index-dsa_005fsignature_005fclear"><code>dsa_signature_clear</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6144 <tr><td></td><td valign="top"><a href="#index-dsa_005fsignature_005finit"><code>dsa_signature_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6145 <tr><td></td><td valign="top"><a href="#index-dsa_005fverify"><code>dsa_verify</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#DSA">DSA</a></td></tr>
6146 <tr><td colspan="4"> <hr></td></tr>
6147 <tr><th><a name="Index_cp_letter-E">E</a></th><td></td><td></td></tr>
6148 <tr><td></td><td valign="top"><a href="#index-eax_005faes128_005fdecrypt"><code>eax_aes128_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6149 <tr><td></td><td valign="top"><a href="#index-eax_005faes128_005fdigest"><code>eax_aes128_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6150 <tr><td></td><td valign="top"><a href="#index-eax_005faes128_005fencrypt"><code>eax_aes128_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6151 <tr><td></td><td valign="top"><a href="#index-eax_005faes128_005fset_005fkey"><code>eax_aes128_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6152 <tr><td></td><td valign="top"><a href="#index-eax_005faes128_005fset_005fnonce"><code>eax_aes128_set_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6153 <tr><td></td><td valign="top"><a href="#index-eax_005faes128_005fupdate"><code>eax_aes128_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6154 <tr><td></td><td valign="top"><a href="#index-EAX_005fCTX"><code>EAX_CTX</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6155 <tr><td></td><td valign="top"><a href="#index-eax_005fdecrypt"><code>eax_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6156 <tr><td></td><td valign="top"><a href="#index-EAX_005fDECRYPT"><code>EAX_DECRYPT</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6157 <tr><td></td><td valign="top"><a href="#index-eax_005fdigest"><code>eax_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6158 <tr><td></td><td valign="top"><a href="#index-EAX_005fDIGEST"><code>EAX_DIGEST</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6159 <tr><td></td><td valign="top"><a href="#index-eax_005fencrypt"><code>eax_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6160 <tr><td></td><td valign="top"><a href="#index-EAX_005fENCRYPT"><code>EAX_ENCRYPT</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6161 <tr><td></td><td valign="top"><a href="#index-eax_005fset_005fkey"><code>eax_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6162 <tr><td></td><td valign="top"><a href="#index-EAX_005fSET_005fKEY"><code>EAX_SET_KEY</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6163 <tr><td></td><td valign="top"><a href="#index-eax_005fset_005fnonce"><code>eax_set_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6164 <tr><td></td><td valign="top"><a href="#index-EAX_005fSET_005fNONCE"><code>EAX_SET_NONCE</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6165 <tr><td></td><td valign="top"><a href="#index-eax_005fupdate"><code>eax_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6166 <tr><td></td><td valign="top"><a href="#index-EAX_005fUPDATE"><code>EAX_UPDATE</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#EAX">EAX</a></td></tr>
6167 <tr><td></td><td valign="top"><a href="#index-ecc_005fpoint_005fclear"><code>ecc_point_clear</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Elliptic-curves">Elliptic curves</a></td></tr>
6168 <tr><td></td><td valign="top"><a href="#index-ecc_005fpoint_005fget"><code>ecc_point_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Elliptic-curves">Elliptic curves</a></td></tr>
6169 <tr><td></td><td valign="top"><a href="#index-ecc_005fpoint_005finit"><code>ecc_point_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Elliptic-curves">Elliptic curves</a></td></tr>
6170 <tr><td></td><td valign="top"><a href="#index-ecc_005fpoint_005fset"><code>ecc_point_set</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Elliptic-curves">Elliptic curves</a></td></tr>
6171 <tr><td></td><td valign="top"><a href="#index-ecc_005fscalar_005fclear"><code>ecc_scalar_clear</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Elliptic-curves">Elliptic curves</a></td></tr>
6172 <tr><td></td><td valign="top"><a href="#index-ecc_005fscalar_005fget"><code>ecc_scalar_get</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Elliptic-curves">Elliptic curves</a></td></tr>
6173 <tr><td></td><td valign="top"><a href="#index-ecc_005fscalar_005finit"><code>ecc_scalar_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Elliptic-curves">Elliptic curves</a></td></tr>
6174 <tr><td></td><td valign="top"><a href="#index-ecc_005fscalar_005fset"><code>ecc_scalar_set</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Elliptic-curves">Elliptic curves</a></td></tr>
6175 <tr><td></td><td valign="top"><a href="#index-ecdsa_005fgenerate_005fkeypair"><code>ecdsa_generate_keypair</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Elliptic-curves">Elliptic curves</a></td></tr>
6176 <tr><td></td><td valign="top"><a href="#index-ecdsa_005fsign"><code>ecdsa_sign</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Elliptic-curves">Elliptic curves</a></td></tr>
6177 <tr><td></td><td valign="top"><a href="#index-ecdsa_005fverify"><code>ecdsa_verify</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Elliptic-curves">Elliptic curves</a></td></tr>
6178 <tr><td></td><td valign="top"><a href="#index-ed25519_005fsha512_005fpublic_005fkey"><code>ed25519_sha512_public_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Elliptic-curves">Elliptic curves</a></td></tr>
6179 <tr><td></td><td valign="top"><a href="#index-ed25519_005fsha512_005fsign"><code>ed25519_sha512_sign</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Elliptic-curves">Elliptic curves</a></td></tr>
6180 <tr><td></td><td valign="top"><a href="#index-ed25519_005fsha512_005fverify"><code>ed25519_sha512_verify</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Elliptic-curves">Elliptic curves</a></td></tr>
6181 <tr><td></td><td valign="top"><a href="#index-eddsa">eddsa</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Elliptic-curves">Elliptic curves</a></td></tr>
6182 <tr><td></td><td valign="top"><a href="#index-Entropy">Entropy</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Randomness">Randomness</a></td></tr>
6183 <tr><td colspan="4"> <hr></td></tr>
6184 <tr><th><a name="Index_cp_letter-G">G</a></th><td></td><td></td></tr>
6185 <tr><td></td><td valign="top"><a href="#index-Galois-Counter-Mode">Galois Counter Mode</a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6186 <tr><td></td><td valign="top"><a href="#index-GCM">GCM</a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6187 <tr><td></td><td valign="top"><a href="#index-gcm_005faes128_005fdecrypt"><code>gcm_aes128_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6188 <tr><td></td><td valign="top"><a href="#index-gcm_005faes128_005fdigest"><code>gcm_aes128_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6189 <tr><td></td><td valign="top"><a href="#index-gcm_005faes128_005fencrypt"><code>gcm_aes128_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6190 <tr><td></td><td valign="top"><a href="#index-gcm_005faes128_005fset_005fiv"><code>gcm_aes128_set_iv</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6191 <tr><td></td><td valign="top"><a href="#index-gcm_005faes128_005fset_005fkey"><code>gcm_aes128_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6192 <tr><td></td><td valign="top"><a href="#index-gcm_005faes128_005fupdate"><code>gcm_aes128_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6193 <tr><td></td><td valign="top"><a href="#index-gcm_005faes192_005fdecrypt"><code>gcm_aes192_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6194 <tr><td></td><td valign="top"><a href="#index-gcm_005faes192_005fdigest"><code>gcm_aes192_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6195 <tr><td></td><td valign="top"><a href="#index-gcm_005faes192_005fencrypt"><code>gcm_aes192_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6196 <tr><td></td><td valign="top"><a href="#index-gcm_005faes192_005fset_005fiv"><code>gcm_aes192_set_iv</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6197 <tr><td></td><td valign="top"><a href="#index-gcm_005faes192_005fset_005fkey"><code>gcm_aes192_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6198 <tr><td></td><td valign="top"><a href="#index-gcm_005faes192_005fupdate"><code>gcm_aes192_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6199 <tr><td></td><td valign="top"><a href="#index-gcm_005faes256_005fdecrypt"><code>gcm_aes256_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6200 <tr><td></td><td valign="top"><a href="#index-gcm_005faes256_005fdigest"><code>gcm_aes256_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6201 <tr><td></td><td valign="top"><a href="#index-gcm_005faes256_005fencrypt"><code>gcm_aes256_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6202 <tr><td></td><td valign="top"><a href="#index-gcm_005faes256_005fset_005fiv"><code>gcm_aes256_set_iv</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6203 <tr><td></td><td valign="top"><a href="#index-gcm_005faes256_005fset_005fkey"><code>gcm_aes256_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6204 <tr><td></td><td valign="top"><a href="#index-gcm_005faes256_005fupdate"><code>gcm_aes256_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6205 <tr><td></td><td valign="top"><a href="#index-gcm_005faes_005fdecrypt"><code>gcm_aes_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6206 <tr><td></td><td valign="top"><a href="#index-gcm_005faes_005fdigest"><code>gcm_aes_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6207 <tr><td></td><td valign="top"><a href="#index-gcm_005faes_005fencrypt"><code>gcm_aes_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6208 <tr><td></td><td valign="top"><a href="#index-gcm_005faes_005fset_005fiv"><code>gcm_aes_set_iv</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6209 <tr><td></td><td valign="top"><a href="#index-gcm_005faes_005fset_005fkey"><code>gcm_aes_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6210 <tr><td></td><td valign="top"><a href="#index-gcm_005faes_005fupdate"><code>gcm_aes_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6211 <tr><td></td><td valign="top"><a href="#index-gcm_005fcamellia128_005fdecrypt"><code>gcm_camellia128_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6212 <tr><td></td><td valign="top"><a href="#index-gcm_005fcamellia128_005fdigest"><code>gcm_camellia128_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6213 <tr><td></td><td valign="top"><a href="#index-gcm_005fcamellia128_005fencrypt"><code>gcm_camellia128_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6214 <tr><td></td><td valign="top"><a href="#index-gcm_005fcamellia128_005fset_005fiv"><code>gcm_camellia128_set_iv</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6215 <tr><td></td><td valign="top"><a href="#index-gcm_005fcamellia128_005fset_005fkey"><code>gcm_camellia128_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6216 <tr><td></td><td valign="top"><a href="#index-gcm_005fcamellia128_005fupdate"><code>gcm_camellia128_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6217 <tr><td></td><td valign="top"><a href="#index-gcm_005fcamellia192_005fdigest"><code>gcm_camellia192_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6218 <tr><td></td><td valign="top"><a href="#index-gcm_005fcamellia256_005fdecrypt"><code>gcm_camellia256_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6219 <tr><td></td><td valign="top"><a href="#index-gcm_005fcamellia256_005fdigest"><code>gcm_camellia256_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6220 <tr><td></td><td valign="top"><a href="#index-gcm_005fcamellia256_005fencrypt"><code>gcm_camellia256_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6221 <tr><td></td><td valign="top"><a href="#index-gcm_005fcamellia256_005fset_005fiv"><code>gcm_camellia256_set_iv</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6222 <tr><td></td><td valign="top"><a href="#index-gcm_005fcamellia256_005fset_005fkey"><code>gcm_camellia256_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6223 <tr><td></td><td valign="top"><a href="#index-gcm_005fcamellia256_005fupdate"><code>gcm_camellia256_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6224 <tr><td></td><td valign="top"><a href="#index-gcm_005fcamellia_005fdigest"><code>gcm_camellia_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6225 <tr><td></td><td valign="top"><a href="#index-GCM_005fCTX"><code>GCM_CTX</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6226 <tr><td></td><td valign="top"><a href="#index-gcm_005fdecrypt"><code>gcm_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6227 <tr><td></td><td valign="top"><a href="#index-GCM_005fDECRYPT"><code>GCM_DECRYPT</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6228 <tr><td></td><td valign="top"><a href="#index-gcm_005fdigest"><code>gcm_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6229 <tr><td></td><td valign="top"><a href="#index-GCM_005fDIGEST"><code>GCM_DIGEST</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6230 <tr><td></td><td valign="top"><a href="#index-gcm_005fencrypt"><code>gcm_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6231 <tr><td></td><td valign="top"><a href="#index-GCM_005fENCRYPT"><code>GCM_ENCRYPT</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6232 <tr><td></td><td valign="top"><a href="#index-gcm_005fset_005fiv"><code>gcm_set_iv</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6233 <tr><td></td><td valign="top"><a href="#index-GCM_005fSET_005fIV"><code>GCM_SET_IV</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6234 <tr><td></td><td valign="top"><a href="#index-gcm_005fset_005fkey"><code>gcm_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6235 <tr><td></td><td valign="top"><a href="#index-GCM_005fSET_005fKEY"><code>GCM_SET_KEY</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6236 <tr><td></td><td valign="top"><a href="#index-gcm_005fupdate"><code>gcm_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6237 <tr><td></td><td valign="top"><a href="#index-GCM_005fUPDATE"><code>GCM_UPDATE</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#GCM">GCM</a></td></tr>
6238 <tr><td></td><td valign="top"><a href="#index-gosthash94_005fdigest"><code>gosthash94_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Legacy-hash-functions">Legacy hash functions</a></td></tr>
6239 <tr><td></td><td valign="top"><a href="#index-gosthash94_005finit"><code>gosthash94_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Legacy-hash-functions">Legacy hash functions</a></td></tr>
6240 <tr><td></td><td valign="top"><a href="#index-gosthash94_005fupdate"><code>gosthash94_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Legacy-hash-functions">Legacy hash functions</a></td></tr>
6241 <tr><td colspan="4"> <hr></td></tr>
6242 <tr><th><a name="Index_cp_letter-H">H</a></th><td></td><td></td></tr>
6243 <tr><td></td><td valign="top"><a href="#index-Hash-function">Hash function</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Hash-functions">Hash functions</a></td></tr>
6244 <tr><td></td><td valign="top"><a href="#index-HMAC">HMAC</a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6245 <tr><td></td><td valign="top"><a href="#index-HMAC_005fCTX"><code>HMAC_CTX</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6246 <tr><td></td><td valign="top"><a href="#index-hmac_005fdigest"><code>hmac_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6247 <tr><td></td><td valign="top"><a href="#index-HMAC_005fDIGEST"><code>HMAC_DIGEST</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6248 <tr><td></td><td valign="top"><a href="#index-hmac_005fmd5_005fdigest"><code>hmac_md5_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6249 <tr><td></td><td valign="top"><a href="#index-hmac_005fmd5_005fset_005fkey"><code>hmac_md5_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6250 <tr><td></td><td valign="top"><a href="#index-hmac_005fmd5_005fupdate"><code>hmac_md5_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6251 <tr><td></td><td valign="top"><a href="#index-hmac_005fripemd160_005fdigest"><code>hmac_ripemd160_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6252 <tr><td></td><td valign="top"><a href="#index-hmac_005fripemd160_005fset_005fkey"><code>hmac_ripemd160_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6253 <tr><td></td><td valign="top"><a href="#index-hmac_005fripemd160_005fupdate"><code>hmac_ripemd160_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6254 <tr><td></td><td valign="top"><a href="#index-hmac_005fset_005fkey"><code>hmac_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6255 <tr><td></td><td valign="top"><a href="#index-HMAC_005fSET_005fKEY"><code>HMAC_SET_KEY</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6256 <tr><td></td><td valign="top"><a href="#index-hmac_005fsha1_005fdigest"><code>hmac_sha1_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6257 <tr><td></td><td valign="top"><a href="#index-hmac_005fsha1_005fset_005fkey"><code>hmac_sha1_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6258 <tr><td></td><td valign="top"><a href="#index-hmac_005fsha1_005fupdate"><code>hmac_sha1_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6259 <tr><td></td><td valign="top"><a href="#index-hmac_005fsha256_005fdigest"><code>hmac_sha256_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6260 <tr><td></td><td valign="top"><a href="#index-hmac_005fsha256_005fset_005fkey"><code>hmac_sha256_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6261 <tr><td></td><td valign="top"><a href="#index-hmac_005fsha256_005fupdate"><code>hmac_sha256_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6262 <tr><td></td><td valign="top"><a href="#index-hmac_005fsha512_005fdigest"><code>hmac_sha512_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6263 <tr><td></td><td valign="top"><a href="#index-hmac_005fsha512_005fset_005fkey"><code>hmac_sha512_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6264 <tr><td></td><td valign="top"><a href="#index-hmac_005fsha512_005fupdate"><code>hmac_sha512_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6265 <tr><td></td><td valign="top"><a href="#index-hmac_005fupdate"><code>hmac_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#HMAC">HMAC</a></td></tr>
6266 <tr><td colspan="4"> <hr></td></tr>
6267 <tr><th><a name="Index_cp_letter-K">K</a></th><td></td><td></td></tr>
6268 <tr><td></td><td valign="top"><a href="#index-KDF">KDF</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Key-derivation-functions">Key derivation functions</a></td></tr>
6269 <tr><td></td><td valign="top"><a href="#index-Key-Derivation-Function">Key Derivation Function</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Key-derivation-functions">Key derivation functions</a></td></tr>
6270 <tr><td></td><td valign="top"><a href="#index-Keyed-Hash-Function">Keyed Hash Function</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Keyed-hash-functions">Keyed hash functions</a></td></tr>
6271 <tr><td colspan="4"> <hr></td></tr>
6272 <tr><th><a name="Index_cp_letter-M">M</a></th><td></td><td></td></tr>
6273 <tr><td></td><td valign="top"><a href="#index-MAC">MAC</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Keyed-hash-functions">Keyed hash functions</a></td></tr>
6274 <tr><td></td><td valign="top"><a href="#index-md2_005fdigest"><code>md2_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Legacy-hash-functions">Legacy hash functions</a></td></tr>
6275 <tr><td></td><td valign="top"><a href="#index-md2_005finit"><code>md2_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Legacy-hash-functions">Legacy hash functions</a></td></tr>
6276 <tr><td></td><td valign="top"><a href="#index-md2_005fupdate"><code>md2_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Legacy-hash-functions">Legacy hash functions</a></td></tr>
6277 <tr><td></td><td valign="top"><a href="#index-md4_005fdigest"><code>md4_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Legacy-hash-functions">Legacy hash functions</a></td></tr>
6278 <tr><td></td><td valign="top"><a href="#index-md4_005finit"><code>md4_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Legacy-hash-functions">Legacy hash functions</a></td></tr>
6279 <tr><td></td><td valign="top"><a href="#index-md4_005fupdate"><code>md4_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Legacy-hash-functions">Legacy hash functions</a></td></tr>
6280 <tr><td></td><td valign="top"><a href="#index-md5_005fdigest"><code>md5_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Legacy-hash-functions">Legacy hash functions</a></td></tr>
6281 <tr><td></td><td valign="top"><a href="#index-md5_005finit"><code>md5_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Legacy-hash-functions">Legacy hash functions</a></td></tr>
6282 <tr><td></td><td valign="top"><a href="#index-md5_005fupdate"><code>md5_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Legacy-hash-functions">Legacy hash functions</a></td></tr>
6283 <tr><td></td><td valign="top"><a href="#index-memxor"><code>memxor</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-functions">Miscellaneous functions</a></td></tr>
6284 <tr><td></td><td valign="top"><a href="#index-memxor3"><code>memxor3</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Miscellaneous-functions">Miscellaneous functions</a></td></tr>
6285 <tr><td></td><td valign="top"><a href="#index-Message-Authentication-Code">Message Authentication Code</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Keyed-hash-functions">Keyed hash functions</a></td></tr>
6286 <tr><td colspan="4"> <hr></td></tr>
6287 <tr><th><a name="Index_cp_letter-N">N</a></th><td></td><td></td></tr>
6288 <tr><td></td><td valign="top"><a href="#index-nettle_005faead">nettle_aead</a>:</td><td>&nbsp;</td><td valign="top"><a href="#nettle_005faead-abstraction">nettle_aead abstraction</a></td></tr>
6289 <tr><td></td><td valign="top"><a href="#index-nettle_005faeads">nettle_aeads</a>:</td><td>&nbsp;</td><td valign="top"><a href="#nettle_005faead-abstraction">nettle_aead abstraction</a></td></tr>
6290 <tr><td></td><td valign="top"><a href="#index-nettle_005fcipher">nettle_cipher</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6291 <tr><td></td><td valign="top"><a href="#index-nettle_005fciphers">nettle_ciphers</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6292 <tr><td></td><td valign="top"><a href="#index-nettle_005fhash">nettle_hash</a>:</td><td>&nbsp;</td><td valign="top"><a href="#nettle_005fhash-abstraction">nettle_hash abstraction</a></td></tr>
6293 <tr><td></td><td valign="top"><a href="#index-nettle_005fhashes">nettle_hashes</a>:</td><td>&nbsp;</td><td valign="top"><a href="#nettle_005fhash-abstraction">nettle_hash abstraction</a></td></tr>
6294 <tr><td colspan="4"> <hr></td></tr>
6295 <tr><th><a name="Index_cp_letter-O">O</a></th><td></td><td></td></tr>
6296 <tr><td></td><td valign="top"><a href="#index-One_002dway">One-way</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Hash-functions">Hash functions</a></td></tr>
6297 <tr><td></td><td valign="top"><a href="#index-One_002dway-function">One-way function</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Public_002dkey-algorithms">Public-key algorithms</a></td></tr>
6298 <tr><td colspan="4"> <hr></td></tr>
6299 <tr><th><a name="Index_cp_letter-P">P</a></th><td></td><td></td></tr>
6300 <tr><td></td><td valign="top"><a href="#index-Password-Based-Key-Derivation-Function">Password Based Key Derivation Function</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Key-derivation-functions">Key derivation functions</a></td></tr>
6301 <tr><td></td><td valign="top"><a href="#index-PBKDF">PBKDF</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Key-derivation-functions">Key derivation functions</a></td></tr>
6302 <tr><td></td><td valign="top"><a href="#index-pbkdf2"><code>pbkdf2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Key-derivation-functions">Key derivation functions</a></td></tr>
6303 <tr><td></td><td valign="top"><a href="#index-PBKDF2"><code>PBKDF2</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Key-derivation-functions">Key derivation functions</a></td></tr>
6304 <tr><td></td><td valign="top"><a href="#index-pbkdf2_005fhmac_005fsha1"><code>pbkdf2_hmac_sha1</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Key-derivation-functions">Key derivation functions</a></td></tr>
6305 <tr><td></td><td valign="top"><a href="#index-pbkdf2_005fhmac_005fsha256"><code>pbkdf2_hmac_sha256</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Key-derivation-functions">Key derivation functions</a></td></tr>
6306 <tr><td></td><td valign="top"><a href="#index-PKCS-_00235">PKCS #5</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Key-derivation-functions">Key derivation functions</a></td></tr>
6307 <tr><td></td><td valign="top"><a href="#index-poly1305_005faes_005fdigest"><code>poly1305_aes_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Poly1305">Poly1305</a></td></tr>
6308 <tr><td></td><td valign="top"><a href="#index-poly1305_005faes_005fset_005fkey"><code>poly1305_aes_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Poly1305">Poly1305</a></td></tr>
6309 <tr><td></td><td valign="top"><a href="#index-poly1305_005faes_005fset_005fnonce"><code>poly1305_aes_set_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Poly1305">Poly1305</a></td></tr>
6310 <tr><td></td><td valign="top"><a href="#index-poly1305_005faes_005fupdate"><code>poly1305_aes_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Poly1305">Poly1305</a></td></tr>
6311 <tr><td></td><td valign="top"><a href="#index-Public-Key-Cryptography">Public Key Cryptography</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Public_002dkey-algorithms">Public-key algorithms</a></td></tr>
6312 <tr><td colspan="4"> <hr></td></tr>
6313 <tr><th><a name="Index_cp_letter-R">R</a></th><td></td><td></td></tr>
6314 <tr><td></td><td valign="top"><a href="#index-Randomness">Randomness</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Randomness">Randomness</a></td></tr>
6315 <tr><td></td><td valign="top"><a href="#index-ripemd160_005fdigest"><code>ripemd160_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Legacy-hash-functions">Legacy hash functions</a></td></tr>
6316 <tr><td></td><td valign="top"><a href="#index-ripemd160_005finit"><code>ripemd160_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Legacy-hash-functions">Legacy hash functions</a></td></tr>
6317 <tr><td></td><td valign="top"><a href="#index-ripemd160_005fupdate"><code>ripemd160_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Legacy-hash-functions">Legacy hash functions</a></td></tr>
6318 <tr><td></td><td valign="top"><a href="#index-rsa_005fcompute_005froot"><code>rsa_compute_root</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6319 <tr><td></td><td valign="top"><a href="#index-rsa_005fcompute_005froot_005ftr_0028const"><code>rsa_compute_root_tr(const</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6320 <tr><td></td><td valign="top"><a href="#index-rsa_005fdecrypt"><code>rsa_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6321 <tr><td></td><td valign="top"><a href="#index-rsa_005fdecrypt_005ftr"><code>rsa_decrypt_tr</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6322 <tr><td></td><td valign="top"><a href="#index-rsa_005fencrypt"><code>rsa_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6323 <tr><td></td><td valign="top"><a href="#index-rsa_005fgenerate_005fkeypair"><code>rsa_generate_keypair</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6324 <tr><td></td><td valign="top"><a href="#index-rsa_005fmd5_005fsign"><code>rsa_md5_sign</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6325 <tr><td></td><td valign="top"><a href="#index-rsa_005fmd5_005fsign_005fdigest"><code>rsa_md5_sign_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6326 <tr><td></td><td valign="top"><a href="#index-rsa_005fmd5_005fsign_005fdigest_005ftr_0028const"><code>rsa_md5_sign_digest_tr(const</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6327 <tr><td></td><td valign="top"><a href="#index-rsa_005fmd5_005fsign_005ftr_0028const"><code>rsa_md5_sign_tr(const</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6328 <tr><td></td><td valign="top"><a href="#index-rsa_005fmd5_005fverify"><code>rsa_md5_verify</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6329 <tr><td></td><td valign="top"><a href="#index-rsa_005fmd5_005fverify_005fdigest"><code>rsa_md5_verify_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6330 <tr><td></td><td valign="top"><a href="#index-rsa_005fpkcs1_005fsign_0028const"><code>rsa_pkcs1_sign(const</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6331 <tr><td></td><td valign="top"><a href="#index-rsa_005fpkcs1_005fsign_005ftr_0028const"><code>rsa_pkcs1_sign_tr(const</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6332 <tr><td></td><td valign="top"><a href="#index-rsa_005fpkcs1_005fverify_0028const"><code>rsa_pkcs1_verify(const</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6333 <tr><td></td><td valign="top"><a href="#index-rsa_005fprivate_005fkey_005fclear"><code>rsa_private_key_clear</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6334 <tr><td></td><td valign="top"><a href="#index-rsa_005fprivate_005fkey_005finit"><code>rsa_private_key_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6335 <tr><td></td><td valign="top"><a href="#index-rsa_005fprivate_005fkey_005fprepare"><code>rsa_private_key_prepare</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6336 <tr><td></td><td valign="top"><a href="#index-rsa_005fpublic_005fkey_005fclear"><code>rsa_public_key_clear</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6337 <tr><td></td><td valign="top"><a href="#index-rsa_005fpublic_005fkey_005finit"><code>rsa_public_key_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6338 <tr><td></td><td valign="top"><a href="#index-rsa_005fpublic_005fkey_005fprepare"><code>rsa_public_key_prepare</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6339 <tr><td></td><td valign="top"><a href="#index-rsa_005fsha1_005fsign"><code>rsa_sha1_sign</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6340 <tr><td></td><td valign="top"><a href="#index-rsa_005fsha1_005fsign_005fdigest"><code>rsa_sha1_sign_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6341 <tr><td></td><td valign="top"><a href="#index-rsa_005fsha1_005fsign_005fdigest_005ftr_0028const"><code>rsa_sha1_sign_digest_tr(const</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6342 <tr><td></td><td valign="top"><a href="#index-rsa_005fsha1_005fsign_005ftr_0028const"><code>rsa_sha1_sign_tr(const</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6343 <tr><td></td><td valign="top"><a href="#index-rsa_005fsha1_005fverify"><code>rsa_sha1_verify</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6344 <tr><td></td><td valign="top"><a href="#index-rsa_005fsha1_005fverify_005fdigest"><code>rsa_sha1_verify_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6345 <tr><td></td><td valign="top"><a href="#index-rsa_005fsha256_005fsign"><code>rsa_sha256_sign</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6346 <tr><td></td><td valign="top"><a href="#index-rsa_005fsha256_005fsign_005fdigest"><code>rsa_sha256_sign_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6347 <tr><td></td><td valign="top"><a href="#index-rsa_005fsha256_005fsign_005fdigest_005ftr_0028const"><code>rsa_sha256_sign_digest_tr(const</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6348 <tr><td></td><td valign="top"><a href="#index-rsa_005fsha256_005fsign_005ftr_0028const"><code>rsa_sha256_sign_tr(const</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6349 <tr><td></td><td valign="top"><a href="#index-rsa_005fsha256_005fverify"><code>rsa_sha256_verify</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6350 <tr><td></td><td valign="top"><a href="#index-rsa_005fsha256_005fverify_005fdigest"><code>rsa_sha256_verify_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6351 <tr><td></td><td valign="top"><a href="#index-rsa_005fsha512_005fsign"><code>rsa_sha512_sign</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6352 <tr><td></td><td valign="top"><a href="#index-rsa_005fsha512_005fsign_005fdigest"><code>rsa_sha512_sign_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6353 <tr><td></td><td valign="top"><a href="#index-rsa_005fsha512_005fsign_005fdigest_005ftr_0028const"><code>rsa_sha512_sign_digest_tr(const</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6354 <tr><td></td><td valign="top"><a href="#index-rsa_005fsha512_005fsign_005ftr_0028const"><code>rsa_sha512_sign_tr(const</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6355 <tr><td></td><td valign="top"><a href="#index-rsa_005fsha512_005fverify"><code>rsa_sha512_verify</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6356 <tr><td></td><td valign="top"><a href="#index-rsa_005fsha512_005fverify_005fdigest"><code>rsa_sha512_verify_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#RSA">RSA</a></td></tr>
6357 <tr><td colspan="4"> <hr></td></tr>
6358 <tr><th><a name="Index_cp_letter-S">S</a></th><td></td><td></td></tr>
6359 <tr><td></td><td valign="top"><a href="#index-salsa20r12_005fcrypt"><code>salsa20r12_crypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6360 <tr><td></td><td valign="top"><a href="#index-salsa20_005f128_005fset_005fkey"><code>salsa20_128_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6361 <tr><td></td><td valign="top"><a href="#index-salsa20_005f256_005fset_005fkey"><code>salsa20_256_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6362 <tr><td></td><td valign="top"><a href="#index-salsa20_005fcrypt"><code>salsa20_crypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6363 <tr><td></td><td valign="top"><a href="#index-salsa20_005fset_005fkey"><code>salsa20_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6364 <tr><td></td><td valign="top"><a href="#index-salsa20_005fset_005fnonce"><code>salsa20_set_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6365 <tr><td></td><td valign="top"><a href="#index-serpent_005fdecrypt"><code>serpent_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6366 <tr><td></td><td valign="top"><a href="#index-serpent_005fencrypt"><code>serpent_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6367 <tr><td></td><td valign="top"><a href="#index-serpent_005fset_005fkey"><code>serpent_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6368 <tr><td></td><td valign="top"><a href="#index-sha1_005fdigest"><code>sha1_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Legacy-hash-functions">Legacy hash functions</a></td></tr>
6369 <tr><td></td><td valign="top"><a href="#index-sha1_005finit"><code>sha1_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Legacy-hash-functions">Legacy hash functions</a></td></tr>
6370 <tr><td></td><td valign="top"><a href="#index-sha1_005fupdate"><code>sha1_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Legacy-hash-functions">Legacy hash functions</a></td></tr>
6371 <tr><td></td><td valign="top"><a href="#index-sha224_005fdigest"><code>sha224_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6372 <tr><td></td><td valign="top"><a href="#index-sha224_005finit"><code>sha224_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6373 <tr><td></td><td valign="top"><a href="#index-sha224_005fupdate"><code>sha224_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6374 <tr><td></td><td valign="top"><a href="#index-sha256_005fdigest"><code>sha256_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6375 <tr><td></td><td valign="top"><a href="#index-sha256_005finit"><code>sha256_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6376 <tr><td></td><td valign="top"><a href="#index-sha256_005fupdate"><code>sha256_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6377 <tr><td></td><td valign="top"><a href="#index-SHA3">SHA3</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6378 <tr><td></td><td valign="top"><a href="#index-sha384_005fdigest"><code>sha384_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6379 <tr><td></td><td valign="top"><a href="#index-sha384_005finit"><code>sha384_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6380 <tr><td></td><td valign="top"><a href="#index-sha384_005fupdate"><code>sha384_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6381 <tr><td></td><td valign="top"><a href="#index-sha3_005f224_005fdigest"><code>sha3_224_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6382 <tr><td></td><td valign="top"><a href="#index-sha3_005f224_005finit"><code>sha3_224_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6383 <tr><td></td><td valign="top"><a href="#index-sha3_005f224_005fupdate"><code>sha3_224_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6384 <tr><td></td><td valign="top"><a href="#index-sha3_005f256_005fdigest"><code>sha3_256_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6385 <tr><td></td><td valign="top"><a href="#index-sha3_005f256_005finit"><code>sha3_256_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6386 <tr><td></td><td valign="top"><a href="#index-sha3_005f256_005fupdate"><code>sha3_256_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6387 <tr><td></td><td valign="top"><a href="#index-sha3_005f384_005fdigest"><code>sha3_384_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6388 <tr><td></td><td valign="top"><a href="#index-sha3_005f384_005finit"><code>sha3_384_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6389 <tr><td></td><td valign="top"><a href="#index-sha3_005f384_005fupdate"><code>sha3_384_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6390 <tr><td></td><td valign="top"><a href="#index-sha3_005f512_005fdigest"><code>sha3_512_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6391 <tr><td></td><td valign="top"><a href="#index-sha3_005f512_005finit"><code>sha3_512_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6392 <tr><td></td><td valign="top"><a href="#index-sha3_005f512_005fupdate"><code>sha3_512_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6393 <tr><td></td><td valign="top"><a href="#index-sha512_005f224_005fdigest"><code>sha512_224_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6394 <tr><td></td><td valign="top"><a href="#index-sha512_005f224_005finit"><code>sha512_224_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6395 <tr><td></td><td valign="top"><a href="#index-sha512_005f224_005fupdate"><code>sha512_224_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6396 <tr><td></td><td valign="top"><a href="#index-sha512_005f256_005fdigest"><code>sha512_256_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6397 <tr><td></td><td valign="top"><a href="#index-sha512_005f256_005finit"><code>sha512_256_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6398 <tr><td></td><td valign="top"><a href="#index-sha512_005f256_005fupdate"><code>sha512_256_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6399 <tr><td></td><td valign="top"><a href="#index-sha512_005fdigest"><code>sha512_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6400 <tr><td></td><td valign="top"><a href="#index-sha512_005finit"><code>sha512_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6401 <tr><td></td><td valign="top"><a href="#index-sha512_005fupdate"><code>sha512_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Recommended-hash-functions">Recommended hash functions</a></td></tr>
6402 <tr><td></td><td valign="top"><a href="#index-Stream-Cipher">Stream Cipher</a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6403 <tr><td colspan="4"> <hr></td></tr>
6404 <tr><th><a name="Index_cp_letter-T">T</a></th><td></td><td></td></tr>
6405 <tr><td></td><td valign="top"><a href="#index-twofish_005fdecrypt"><code>twofish_decrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6406 <tr><td></td><td valign="top"><a href="#index-twofish_005fencrypt"><code>twofish_encrypt</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6407 <tr><td></td><td valign="top"><a href="#index-twofish_005fset_005fkey"><code>twofish_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Cipher-functions">Cipher functions</a></td></tr>
6408 <tr><td colspan="4"> <hr></td></tr>
6409 <tr><th><a name="Index_cp_letter-U">U</a></th><td></td><td></td></tr>
6410 <tr><td></td><td valign="top"><a href="#index-UMAC">UMAC</a>:</td><td>&nbsp;</td><td valign="top"><a href="#UMAC">UMAC</a></td></tr>
6411 <tr><td></td><td valign="top"><a href="#index-umac128_005fdigest"><code>umac128_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#UMAC">UMAC</a></td></tr>
6412 <tr><td></td><td valign="top"><a href="#index-umac128_005fset_005fkey"><code>umac128_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#UMAC">UMAC</a></td></tr>
6413 <tr><td></td><td valign="top"><a href="#index-umac128_005fset_005fnonce"><code>umac128_set_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#UMAC">UMAC</a></td></tr>
6414 <tr><td></td><td valign="top"><a href="#index-umac128_005fupdate"><code>umac128_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#UMAC">UMAC</a></td></tr>
6415 <tr><td></td><td valign="top"><a href="#index-umac32_005fdigest"><code>umac32_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#UMAC">UMAC</a></td></tr>
6416 <tr><td></td><td valign="top"><a href="#index-umac32_005fset_005fkey"><code>umac32_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#UMAC">UMAC</a></td></tr>
6417 <tr><td></td><td valign="top"><a href="#index-umac32_005fset_005fnonce"><code>umac32_set_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#UMAC">UMAC</a></td></tr>
6418 <tr><td></td><td valign="top"><a href="#index-umac32_005fupdate"><code>umac32_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#UMAC">UMAC</a></td></tr>
6419 <tr><td></td><td valign="top"><a href="#index-umac64_005fdigest"><code>umac64_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#UMAC">UMAC</a></td></tr>
6420 <tr><td></td><td valign="top"><a href="#index-umac64_005fset_005fkey"><code>umac64_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#UMAC">UMAC</a></td></tr>
6421 <tr><td></td><td valign="top"><a href="#index-umac64_005fset_005fnonce"><code>umac64_set_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#UMAC">UMAC</a></td></tr>
6422 <tr><td></td><td valign="top"><a href="#index-umac64_005fupdate"><code>umac64_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#UMAC">UMAC</a></td></tr>
6423 <tr><td></td><td valign="top"><a href="#index-umac96_005fdigest"><code>umac96_digest</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#UMAC">UMAC</a></td></tr>
6424 <tr><td></td><td valign="top"><a href="#index-umac96_005fset_005fkey"><code>umac96_set_key</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#UMAC">UMAC</a></td></tr>
6425 <tr><td></td><td valign="top"><a href="#index-umac96_005fset_005fnonce"><code>umac96_set_nonce</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#UMAC">UMAC</a></td></tr>
6426 <tr><td></td><td valign="top"><a href="#index-umac96_005fupdate"><code>umac96_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#UMAC">UMAC</a></td></tr>
6427 <tr><td colspan="4"> <hr></td></tr>
6428 <tr><th><a name="Index_cp_letter-Y">Y</a></th><td></td><td></td></tr>
6429 <tr><td></td><td valign="top"><a href="#index-yarrow256_005ffast_005freseed"><code>yarrow256_fast_reseed</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Randomness">Randomness</a></td></tr>
6430 <tr><td></td><td valign="top"><a href="#index-yarrow256_005finit"><code>yarrow256_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Randomness">Randomness</a></td></tr>
6431 <tr><td></td><td valign="top"><a href="#index-yarrow256_005fis_005fseeded"><code>yarrow256_is_seeded</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Randomness">Randomness</a></td></tr>
6432 <tr><td></td><td valign="top"><a href="#index-yarrow256_005fneeded_005fsources"><code>yarrow256_needed_sources</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Randomness">Randomness</a></td></tr>
6433 <tr><td></td><td valign="top"><a href="#index-yarrow256_005frandom"><code>yarrow256_random</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Randomness">Randomness</a></td></tr>
6434 <tr><td></td><td valign="top"><a href="#index-yarrow256_005fseed"><code>yarrow256_seed</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Randomness">Randomness</a></td></tr>
6435 <tr><td></td><td valign="top"><a href="#index-yarrow256_005fslow_005freseed"><code>yarrow256_slow_reseed</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Randomness">Randomness</a></td></tr>
6436 <tr><td></td><td valign="top"><a href="#index-yarrow256_005fupdate"><code>yarrow256_update</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Randomness">Randomness</a></td></tr>
6437 <tr><td></td><td valign="top"><a href="#index-yarrow_005fkey_005fevent_005festimate"><code>yarrow_key_event_estimate</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Randomness">Randomness</a></td></tr>
6438 <tr><td></td><td valign="top"><a href="#index-yarrow_005fkey_005fevent_005finit"><code>yarrow_key_event_init</code></a>:</td><td>&nbsp;</td><td valign="top"><a href="#Randomness">Randomness</a></td></tr>
6439 <tr><td colspan="4"> <hr></td></tr>
6440 </table>
6441 <table><tr><th valign="top">Jump to: &nbsp; </th><td><a class="summary-letter" href="#Index_cp_letter-A"><b>A</b></a>
6442  &nbsp;
6443 <a class="summary-letter" href="#Index_cp_letter-B"><b>B</b></a>
6444  &nbsp;
6445 <a class="summary-letter" href="#Index_cp_letter-C"><b>C</b></a>
6446  &nbsp;
6447 <a class="summary-letter" href="#Index_cp_letter-D"><b>D</b></a>
6448  &nbsp;
6449 <a class="summary-letter" href="#Index_cp_letter-E"><b>E</b></a>
6450  &nbsp;
6451 <a class="summary-letter" href="#Index_cp_letter-G"><b>G</b></a>
6452  &nbsp;
6453 <a class="summary-letter" href="#Index_cp_letter-H"><b>H</b></a>
6454  &nbsp;
6455 <a class="summary-letter" href="#Index_cp_letter-K"><b>K</b></a>
6456  &nbsp;
6457 <a class="summary-letter" href="#Index_cp_letter-M"><b>M</b></a>
6458  &nbsp;
6459 <a class="summary-letter" href="#Index_cp_letter-N"><b>N</b></a>
6460  &nbsp;
6461 <a class="summary-letter" href="#Index_cp_letter-O"><b>O</b></a>
6462  &nbsp;
6463 <a class="summary-letter" href="#Index_cp_letter-P"><b>P</b></a>
6464  &nbsp;
6465 <a class="summary-letter" href="#Index_cp_letter-R"><b>R</b></a>
6466  &nbsp;
6467 <a class="summary-letter" href="#Index_cp_letter-S"><b>S</b></a>
6468  &nbsp;
6469 <a class="summary-letter" href="#Index_cp_letter-T"><b>T</b></a>
6470  &nbsp;
6471 <a class="summary-letter" href="#Index_cp_letter-U"><b>U</b></a>
6472  &nbsp;
6473 <a class="summary-letter" href="#Index_cp_letter-Y"><b>Y</b></a>
6474  &nbsp;
6475 </td></tr></table>
6476
6477 <hr>
6478 <a name="SEC_Foot"></a>
6479 <div class="header">
6480 <p>
6481  &nbsp; [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="#Index" title="Index" rel="index">Index</a>]</p>
6482 </div>
6483 <h4 class="footnotes-heading">Footnotes</h4>
6484
6485 <h3><a name="FOOT1" href="#DOCF1">(1)</a></h3>
6486 <p>Actually, the computation is not done like this, it is
6487 done more efficiently using <code>p</code>, <code>q</code> and the Chinese remainder
6488 theorem (<acronym>CRT</acronym>). But the result is the same.</p>
6489 <hr>
6490
6491
6492
6493 </body>
6494 </html>