1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename nettle.info 4@settitle Nettle: a low-level cryptographic library 5@documentencoding UTF-8 6@footnotestyle separate 7@syncodeindex fn cp 8@c %**end of header 9 10@set UPDATED-FOR 3.4 11@set AUTHOR Niels Möller 12 13@copying 14This manual is for the Nettle library (version @value{UPDATED-FOR}), a 15low-level cryptographic library. 16 17Originally written 2001 by @value{AUTHOR}, updated 2017. 18 19@quotation 20This manual is placed in the public domain. You may freely copy it, in 21whole or in part, with or without modification. Attribution is 22appreciated, but not required. 23@end quotation 24@end copying 25 26@ifnottex 27@macro pmod {m} 28(mod \m\) 29@end macro 30@end ifnottex 31 32@titlepage 33@title Nettle Manual 34@subtitle For the Nettle Library version @value{UPDATED-FOR} 35@author @value{AUTHOR} 36@page 37@vskip 0pt plus 1filll 38@insertcopying 39@end titlepage 40 41@dircategory Encryption 42@direntry 43* Nettle: (nettle). A low-level cryptographic library. 44@end direntry 45 46@contents 47 48@ifnottex 49@node Top, Introduction, (dir), (dir) 50@comment node-name, next, previous, up 51@top Nettle 52 53This document describes the Nettle low-level cryptographic library. You 54can use the library directly from your C programs, or write or use an 55object-oriented wrapper for your favorite language or application. 56 57@insertcopying 58 59@menu 60* Introduction:: What is Nettle? 61* Copyright:: Your rights. 62* Conventions:: General interface conventions. 63* Example:: An example program. 64* Linking:: Linking with libnettle and libhogweed. 65* Compatibility:: On API and ABI compatibility between versions. 66* Reference:: All Nettle functions and features. 67* Nettle soup:: For the serious nettle hacker. 68* Installation:: How to install Nettle. 69* Index:: Function and concept index. 70 71@detailmenu 72 --- The Detailed Node Listing --- 73 74Reference 75 76* Hash functions:: 77* Cipher functions:: 78* Cipher modes:: 79* Keyed hash functions:: 80* Key derivation functions:: 81* Public-key algorithms:: 82* Randomness:: 83* ASCII encoding:: 84* Miscellaneous functions:: 85* Compatibility functions:: 86 87Hash functions 88 89* Recommended hash functions:: 90* Miscellaneous hash functions:: 91* Legacy hash functions:: 92* nettle_hash abstraction:: 93 94Cipher modes 95 96* CBC:: 97* CTR:: 98* CFB and CFB8:: 99* XTS:: 100 101Authenticated encryption with associated data 102 103* EAX:: 104* GCM:: 105* CCM:: 106* ChaCha-Poly1305:: 107* SIV-CMAC:: 108* nettle_aead abstraction:: 109 110Keyed Hash Functions 111 112* HMAC:: 113* UMAC:: 114* CMAC:: 115* Poly1305:: 116 117Public-key algorithms 118 119* RSA:: The RSA public key algorithm. 120* DSA:: The DSA digital signature algorithm. 121* Elliptic curves:: Elliptic curves and ECDSA 122 123@acronym{Elliptic curves} 124 125* Side-channel silence:: 126* ECDSA:: 127* GOSTDSA:: 128* Curve 25519 and Curve 448:: 129 130@end detailmenu 131@end menu 132 133@end ifnottex 134 135@node Introduction, Copyright, Top, Top 136@comment node-name, next, previous, up 137@chapter Introduction 138 139Nettle is a cryptographic library that is designed to fit easily in more 140or less any context: In crypto toolkits for object-oriented languages 141(C++, Python, Pike, ...), in applications like LSH or GNUPG, or even in 142kernel space. In most contexts, you need more than the basic 143cryptographic algorithms, you also need some way to keep track of available 144algorithms, their properties and variants. You often have some algorithm 145selection process, often dictated by a protocol you want to implement. 146 147And as the requirements of applications differ in subtle and not so 148subtle ways, an API that fits one application well can be a pain to use 149in a different context. And that is why there are so many different 150cryptographic libraries around. 151 152Nettle tries to avoid this problem by doing one thing, the low-level 153crypto stuff, and providing a @emph{simple} but general interface to it. 154In particular, Nettle doesn't do algorithm selection. It doesn't do 155memory allocation. It doesn't do any I/O. 156 157The idea is that one can build several application and context specific 158interfaces on top of Nettle, and share the code, test cases, benchmarks, 159documentation, etc. Examples are the Nettle module for the Pike 160language, and LSH, which both use an object-oriented abstraction on top 161of the library. 162 163This manual explains how to use the Nettle library. It also tries to 164provide some background on the cryptography, and advice on how to best 165put it to use. 166 167@node Copyright, Conventions, Introduction, Top 168@comment node-name, next, previous, up 169@chapter Copyright 170 171Nettle is dual licenced under the GNU General Public License version 2 172or later, and the GNU Lesser General Public License version 3 or later. 173When using Nettle, you must comply fully with all conditions of at least 174one of these licenses. A few of the individual files are licensed under 175more permissive terms, or in the public domain. To find the current 176status of particular files, you have to read the copyright notices at 177the top of the files. 178 179This manual is in the public domain. You may freely copy it in whole or 180in part, e.g., into documentation of programs that build on Nettle. 181Attribution, as well as contribution of improvements to the text, is of 182course appreciated, but it is not required. 183 184A list of the supported algorithms, their origins, and exceptions to the 185above licensing: 186 187@table @emph 188@item AES 189The implementation of the AES cipher (also known as rijndael) is written 190by Rafael Sevilla. Assembler for x86 by Rafael Sevilla and 191@value{AUTHOR}, Sparc assembler by @value{AUTHOR}. 192 193@item ARCFOUR 194The implementation of the ARCFOUR (also known as RC4) cipher is written 195by @value{AUTHOR}. 196 197@item ARCTWO 198The implementation of the ARCTWO (also known as RC2) cipher is written 199by Nikos Mavroyanopoulos and modified by Werner Koch and Simon 200Josefsson. 201 202@item BLOWFISH 203The implementation of the BLOWFISH cipher is written by Werner Koch, 204copyright owned by the Free Software Foundation. Also hacked by Simon 205Josefsson and Niels Möller. 206 207@item CAMELLIA 208The C implementation is by Nippon Telegraph and Telephone Corporation 209(NTT), heavily modified by @value{AUTHOR}. Assembler for x86 and x86_64 210by @value{AUTHOR}. 211 212@item CAST128 213The implementation of the CAST128 cipher is written by Steve Reid. 214Released into the public domain. 215 216@item CHACHA 217Implemented by Joachim Strömbergson, based on the implementation of 218SALSA20 (see below). Assembly for x86_64 by Niels Möller. 219 220@item DES 221The implementation of the DES cipher is written by Dana L. How, and 222released under the LGPL, version 2 or later. 223 224@item GOSTHASH94 225The C implementation of the GOST94 message digest is written by 226Aleksey Kravchenko and was ported from the rhash library by Nikos 227Mavrogiannopoulos. It is released under the MIT license. 228 229@item MD2 230The implementation of MD2 is written by Andrew Kuchling, and hacked 231some by Andreas Sigfridsson and @value{AUTHOR}. Python Cryptography 232Toolkit license (essentially public domain). 233 234@item MD4 235This is almost the same code as for MD5 below, with modifications by 236Marcus Comstedt. Released into the public domain. 237 238@item MD5 239The implementation of the MD5 message digest is written by Colin Plumb. 240It has been hacked some more by Andrew Kuchling and @value{AUTHOR}. 241Released into the public domain. 242 243@item PBKDF2 244The C implementation of PBKDF2 is based on earlier work for Shishi and 245GnuTLS by Simon Josefsson. 246 247@item RIPEMD160 248The implementation of RIPEMD160 message digest is based on the code in 249libgcrypt, copyright owned by the Free Software Foundation. Ported to 250Nettle by Andres Mejia. 251 252@item SALSA20 253The C implementation of SALSA20 is based on D. J. Bernstein's reference 254implementation (in the public domain), adapted to Nettle by Simon 255Josefsson, and heavily modified by Niels Möller. Assembly for x86_64 and 256ARM by Niels Möller. 257 258@item SERPENT 259The implementation of the SERPENT cipher is based on the code in libgcrypt, 260copyright owned by the Free Software Foundation. Adapted to Nettle by 261Simon Josefsson and heavily modified by Niels Möller. Assembly for 262x86_64 by Niels Möller. 263 264@item POLY1305 265Based on the implementation by Andrew M. (floodyberry), modified by 266Nikos Mavrogiannopoulos and Niels Möller. Assembly for x86_64 by Niels 267Möller. 268 269@item SHA1 270The C implementation of the SHA1 message digest is written by Peter 271Gutmann, and hacked some more by Andrew Kuchling and @value{AUTHOR}. 272Released into the public domain. Assembler for x86, x86_64 and ARM by 273@value{AUTHOR}, released under the LGPL. 274 275@item SHA2 276Written by @value{AUTHOR}, using Peter Gutmann's SHA1 code as a model. 277 278@item SHA3 279Written by @value{AUTHOR}. 280 281@item TWOFISH 282The implementation of the TWOFISH cipher is written by Ruud de Rooij. 283 284@item UMAC 285Written by @value{AUTHOR}. 286 287@item CMAC 288Written by Nikos Mavrogiannopoulos, @value{AUTHOR}, Jeremy Allison, Michael Adam and Stefan Metzmacher. 289 290@item RSA 291Written by @value{AUTHOR}. Uses the GMP library for bignum operations. 292 293@item DSA 294Written by @value{AUTHOR}. Uses the GMP library for bignum operations. 295 296@item ECDSA 297Written by @value{AUTHOR}. Uses the GMP library for bignum operations. 298Development of Nettle's ECC support was funded by the .SE Internet Fund. 299@end table 300 301@node Conventions, Example, Copyright, Top 302@comment node-name, next, previous, up 303@chapter Conventions 304 305For each supported algorithm, there is an include file that defines a 306@emph{context struct}, a few constants, and declares functions for 307operating on the context. The context struct encapsulates all information 308needed by the algorithm, and it can be copied or moved in memory with no 309unexpected effects. 310 311For consistency, functions for different algorithms are very similar, 312but there are some differences, for instance reflecting if the key setup 313or encryption function differ for encryption and decryption, and whether 314or not key setup can fail. There are also differences between algorithms 315that don't show in function prototypes, but which the application must 316nevertheless be aware of. There is no big difference between the 317functions for stream ciphers and for block ciphers, although they should 318be used quite differently by the application. 319 320If your application uses more than one algorithm of the same type, you 321should probably create an interface that is tailor-made for your needs, 322and then write a few lines of glue code on top of Nettle. 323 324By convention, for an algorithm named @code{foo}, the struct tag for the 325context struct is @code{foo_ctx}, constants and functions uses prefixes 326like @code{FOO_BLOCK_SIZE} (a constant) and @code{foo_set_key} (a 327function). 328 329In all functions, strings are represented with an explicit length, of 330type @code{size_t}, and a pointer of type @code{uint8_t *} or 331@code{const uint8_t *}. For functions that transform one string to 332another, the argument order is length, destination pointer and source 333pointer. Source and destination areas are usually of the same length. 334When they differ, e.g., for @code{ccm_encrypt_message}, the length 335argument specifies the size of the destination area. Source and 336destination pointers may be equal, so that you can process strings in 337place, but source and destination areas @emph{must not} overlap in any 338other way. 339 340Many of the functions lack return value and can never fail. Those 341functions which can fail, return one on success and zero on failure. 342 343@c FIXME: Say something about the name mangling. 344 345@node Example, Linking, Conventions, Top 346@comment node-name, next, previous, up 347@chapter Example 348 349A simple example program that reads a file from standard input and 350writes its SHA1 check-sum on standard output should give the flavor of 351Nettle. 352 353@example 354@verbatiminclude sha-example.c 355@end example 356 357On a typical Unix system, this program can be compiled and linked with 358the command line 359@example 360gcc sha-example.c -o sha-example -lnettle 361@end example 362 363@node Linking, Compatibility, Example, Top 364@comment node-name, next, previous, up 365@chapter Linking 366 367Nettle actually consists of two libraries, @file{libnettle} and 368@file{libhogweed}. The @file{libhogweed} library contains those 369functions of Nettle that uses bignum operations, and depends on the GMP 370library. With this division, linking works the same for both static and 371dynamic libraries. 372 373If an application uses only the symmetric crypto algorithms of Nettle 374(i.e., block ciphers, hash functions, and the like), it's sufficient to 375link with @code{-lnettle}. If an application also uses public-key 376algorithms, the recommended linker flags are @code{-lhogweed -lnettle 377-lgmp}. If the involved libraries are installed as dynamic libraries, it 378may be sufficient to link with just @code{-lhogweed}, and the loader 379will resolve the dependencies automatically. 380 381@node Compatibility, Reference, Linking, Top 382@comment node-name, next, previous, up 383@chapter Compatibility 384@cindex ABI compatibility 385@cindex API compatibility 386@cindex Binary compatibility 387 388When you write a program using the Nettle library, it's desirable to 389have it work together not only with exactly the same version of Nettle 390you had at hand, but with other current and future versions. If a 391different version of Nettle is used at compile time, i.e., you recompile 392it using the header and library files belonging to a different version, 393we talk about API compatibility (for Application Programming Interface). 394If a different version of Nettle isn't used until link time, we talk 395about ABI compatibility (Application Binary Interface) or binary 396compatibility. ABI compatibility matters mainly when using dynamic 397linking with a shared library. E.g., a user has an executable linking at 398run-time with @file{libnettle.so}, and then updates to a later version 399of the shared library, without updating or recompiling the executable. 400 401Nettle aims to provide backwards compatibility, i.e., a program written 402for a particular version of the Nettle library should usually work fine 403with later version of the library. Note that the opposite is not 404supported: The program should @emph{not} be expected to work with older 405versions of the Nettle library; and ABI breakage can be unobvious. E.g, 406the later version may define a new library symbol, and let header files 407redefine an old API name as an alias for the new symbol. If the later 408version ensures that the old symbol is still defined in the library, 409this change is backwards compatible: A program compiled using headers 410from the older version can be successfully linked with either version of 411the library. But if you compile the same program using headers from the 412later version of the library, and attempt to link with the older 413version, you'll get an undefined reference to the new symbol. 414 415API compatibility is rarely broken; exceptions are noted in the NEWS 416file. For example, the key size argument to the function 417@code{cast128_set_key} was dropped in the Nettle-3.0 release, and all 418programs using that function had to be updated to work with the new 419version. 420 421ABI compatibility is broken occasionally. This is also noted in the NEWS 422file, and the name of the shared library is updated to prevent 423accidental run-time linking with the wrong version. All programs have to 424be recompiled before they can link with the new version. Since names are 425different, multiple versions can be installed on the same system, with a 426mix of programs linking to one version or the other. 427 428Under some circumstances, it is possible to have a single program 429linking dynamically with two binary incompatible versions of the Nettle 430library, thanks to the use of symbol versioning. Consider a program 431calling functions in both Nettle and GnuTLS. For the direct dependency 432on Nettle, the program is linked with a particular version of the Nettle 433shared library. GnuTLS uses Nettle internally, but does not expose any 434Nettle data structures or the like in its own ABI. In this situation, 435the GnuTLS shared library may link with a different version of the 436Nettle library. Then both versions of the Nettle library will be loaded 437into the program's address space, and each reference to a symbol will be 438resolved to the correct version. 439 440Finally, some of Nettle's symbols are internal. They carry a leading 441underscore, and are not declared in installed header files. They can be 442used for local or experimental purposes, but programs referring directly 443to those symbols get neither API nor ABI compatibility, not even between 444minor versions. 445 446@node Reference, Nettle soup, Compatibility, Top 447@comment node-name, next, previous, up 448@chapter Reference 449 450This chapter describes all the Nettle functions, grouped by family. 451 452@menu 453* Hash functions:: 454* Cipher functions:: 455* Cipher modes:: 456* Authenticated encryption:: 457* Keyed hash functions:: 458* Key derivation functions:: 459* Public-key algorithms:: 460* Randomness:: 461* ASCII encoding:: 462* Miscellaneous functions:: 463* Compatibility functions:: 464@end menu 465 466@node Hash functions, Cipher functions, Reference, Reference 467@comment node-name, next, previous, up 468 469@section Hash functions 470@cindex Hash function 471A cryptographic @dfn{hash function} is a function that takes variable 472size strings, and maps them to strings of fixed, short, length. There 473are naturally lots of collisions, as there are more possible 1MB files 474than 20 byte strings. But the function is constructed such that is hard 475to find the collisions. More precisely, a cryptographic hash function 476@code{H} should have the following properties: 477 478@table @emph 479 480@item One-way 481@cindex One-way 482Given a hash value @code{H(x)} it is hard to find a string @code{x} 483that hashes to that value. 484 485@item Collision-resistant 486@cindex Collision-resistant 487It is hard to find two different strings, @code{x} and @code{y}, such 488that @code{H(x)} = @code{H(y)}. 489 490@end table 491 492Hash functions are useful as building blocks for digital signatures, 493message authentication codes, pseudo random generators, association of 494unique ids to documents, and many other things. 495 496The most commonly used hash functions are MD5 and SHA1. Unfortunately, 497both these fail the collision-resistance requirement; cryptologists have 498found ways to construct colliding inputs. The recommended hash functions 499for new applications are SHA2 (with main variants SHA256 and SHA512). At 500the time of this writing (Autumn 2015), SHA3 has recently been 501standardized, and the new SHA3 and other top SHA3 candidates may also be 502reasonable alternatives. 503 504@menu 505* Recommended hash functions:: 506* Miscellaneous hash functions:: 507* Legacy hash functions:: 508* nettle_hash abstraction:: 509@end menu 510 511@node Recommended hash functions, Miscellaneous hash functions,, Hash functions 512@comment node-name, next, previous, up 513@subsection Recommended hash functions 514 515The following hash functions have no known weaknesses, and are suitable 516for new applications. The SHA2 family of hash functions were specified 517by @dfn{NIST}, intended as a replacement for @acronym{SHA1}. 518 519@subsubsection @acronym{SHA256} 520 521SHA256 is a member of the SHA2 family. It outputs hash values of 256 522bits, or 32 octets. Nettle defines SHA256 in @file{<nettle/sha2.h>}. 523 524@deftp {Context struct} {struct sha256_ctx} 525@end deftp 526 527@defvr Constant SHA256_DIGEST_SIZE 528The size of a SHA256 digest, i.e. 32. 529@end defvr 530 531@defvr Constant SHA256_BLOCK_SIZE 532The internal block size of SHA256. Useful for some special constructions, 533in particular HMAC-SHA256. 534@end defvr 535 536@deftypefun void sha256_init (struct sha256_ctx *@var{ctx}) 537Initialize the SHA256 state. 538@end deftypefun 539 540@deftypefun void sha256_update (struct sha256_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 541Hash some more data. 542@end deftypefun 543 544@deftypefun void sha256_digest (struct sha256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 545Performs final processing and extracts the message digest, writing it 546to @var{digest}. @var{length} may be smaller than 547@code{SHA256_DIGEST_SIZE}, in which case only the first @var{length} 548octets of the digest are written. 549 550This function also resets the context in the same way as 551@code{sha256_init}. 552@end deftypefun 553 554Earlier versions of nettle defined SHA256 in the header file 555@file{<nettle/sha.h>}, which is now deprecated, but kept for 556compatibility. 557 558@subsubsection @acronym{SHA224} 559 560SHA224 is a variant of SHA256, with a different initial state, and with 561the output truncated to 224 bits, or 28 octets. Nettle defines SHA224 in 562@file{<nettle/sha2.h>} (and in @file{<nettle/sha.h>}, for backwards 563compatibility). 564 565@deftp {Context struct} {struct sha224_ctx} 566@end deftp 567 568@defvr Constant SHA224_DIGEST_SIZE 569The size of a SHA224 digest, i.e. 28. 570@end defvr 571 572@defvr Constant SHA224_BLOCK_SIZE 573The internal block size of SHA224. Useful for some special constructions, 574in particular HMAC-SHA224. 575@end defvr 576 577@deftypefun void sha224_init (struct sha224_ctx *@var{ctx}) 578Initialize the SHA224 state. 579@end deftypefun 580 581@deftypefun void sha224_update (struct sha224_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 582Hash some more data. 583@end deftypefun 584 585@deftypefun void sha224_digest (struct sha224_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 586Performs final processing and extracts the message digest, writing it 587to @var{digest}. @var{length} may be smaller than 588@code{SHA224_DIGEST_SIZE}, in which case only the first @var{length} 589octets of the digest are written. 590 591This function also resets the context in the same way as 592@code{sha224_init}. 593@end deftypefun 594 595@subsubsection @acronym{SHA512} 596 597SHA512 is a larger sibling to SHA256, with a very similar structure but 598with both the output and the internal variables of twice the size. The 599internal variables are 64 bits rather than 32, making it significantly 600slower on 32-bit computers. It outputs hash values of 512 bits, or 64 601octets. Nettle defines SHA512 in @file{<nettle/sha2.h>} (and in 602@file{<nettle/sha.h>}, for backwards compatibility). 603 604@deftp {Context struct} {struct sha512_ctx} 605@end deftp 606 607@defvr Constant SHA512_DIGEST_SIZE 608The size of a SHA512 digest, i.e. 64. 609@end defvr 610 611@defvr Constant SHA512_BLOCK_SIZE 612The internal block size of SHA512, 128. Useful for some special 613constructions, in particular HMAC-SHA512. 614@end defvr 615 616@deftypefun void sha512_init (struct sha512_ctx *@var{ctx}) 617Initialize the SHA512 state. 618@end deftypefun 619 620@deftypefun void sha512_update (struct sha512_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 621Hash some more data. 622@end deftypefun 623 624@deftypefun void sha512_digest (struct sha512_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 625Performs final processing and extracts the message digest, writing it 626to @var{digest}. @var{length} may be smaller than 627@code{SHA512_DIGEST_SIZE}, in which case only the first @var{length} 628octets of the digest are written. 629 630This function also resets the context in the same way as 631@code{sha512_init}. 632@end deftypefun 633 634@subsubsection @acronym{SHA384 and other variants of SHA512} 635 636Several variants of SHA512 have been defined, with a different initial 637state, and with the output truncated to shorter length than 512 bits. 638Naming is a bit confused, these algorithms are called SHA512-224, 639SHA512-256 and SHA384, for output sizes of 224, 256 and 384 bits, 640respectively. Nettle defines these in @file{<nettle/sha2.h>} (and in 641@file{<nettle/sha.h>}, for backwards compatibility). 642 643@deftp {Context struct} {struct sha512_224_ctx} 644@deftpx {Context struct} {struct sha512_256_ctx} 645@deftpx {Context struct} {struct sha384_ctx} 646These context structs are all the same as sha512_ctx. They are defined as 647simple preprocessor aliases, which may cause some problems if used as 648identifiers for other purposes. So avoid doing that. 649@end deftp 650 651@defvr Constant SHA512_224_DIGEST_SIZE 652@defvrx Constant SHA512_256_DIGEST_SIZE 653@defvrx Constant SHA384_DIGEST_SIZE 654The digest size for each variant, i.e., 28, 32, and 48, respectively. 655@end defvr 656 657@defvr Constant SHA512_224_BLOCK_SIZE 658@defvrx Constant SHA512_256_BLOCK_SIZE 659@defvrx Constant SHA384_BLOCK_SIZE 660The internal block size, same as SHA512_BLOCK_SIZE, i.e., 128. Useful for 661some special constructions, in particular HMAC-SHA384. 662@end defvr 663 664@deftypefun void sha512_224_init (struct sha512_224_ctx *@var{ctx}) 665@deftypefunx void sha512_256_init (struct sha512_256_ctx *@var{ctx}) 666@deftypefunx void sha384_init (struct sha384_ctx *@var{ctx}) 667Initialize the context struct. 668@end deftypefun 669 670@deftypefun void sha512_224_update (struct sha512_224_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 671@deftypefunx void sha512_256_update (struct sha512_256_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 672@deftypefunx void sha384_update (struct sha384_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 673Hash some more data. These are all aliases for sha512_update, which does 674the same thing. 675@end deftypefun 676 677@deftypefun void sha512_224_digest (struct sha512_224_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 678@deftypefunx void sha512_256_digest (struct sha512_256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 679@deftypefunx void sha384_digest (struct sha384_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 680Performs final processing and extracts the message digest, writing it to 681@var{digest}. @var{length} may be smaller than the specified digest 682size, in which case only the first @var{length} octets of the digest are 683written. 684 685These function also reset the context in the same way as the 686corresponding init function. 687@end deftypefun 688 689@subsubsection @acronym{SHA3-224} 690@cindex SHA3 691 692The SHA3 hash functions were specified by NIST in response to weaknesses 693in SHA1, and doubts about SHA2 hash functions which structurally are 694very similar to SHA1. SHA3 is a result of a competition, where the 695winner, also known as Keccak, was designed by Guido Bertoni, Joan 696Daemen, Michaël Peeters and Gilles Van Assche. It is structurally very 697different from all widely used earlier hash functions. Like SHA2, there 698are several variants, with output sizes of 224, 256, 384 and 512 bits 699(28, 32, 48 and 64 octets, respectively). In August 2015, it was 700formally standardized by NIST, as FIPS 202, 701@uref{http://dx.doi.org/10.6028/NIST.FIPS.202}. 702 703Note that the SHA3 implementation in earlier versions of Nettle was 704based on the specification at the time Keccak was announced as the 705winner of the competition, which is incompatible with the final standard 706and hence with current versions of Nettle. The @file{nette/sha3.h} 707defines a preprocessor symbol @code{NETTLE_SHA3_FIPS202} to indicate 708conformance with the standard. 709 710@defvr Constant NETTLE_SHA3_FIPS202 711Defined to 1 in Nettle versions supporting FIPS 202. Undefined in 712earlier versions. 713@end defvr 714 715Nettle defines SHA3-224 in @file{<nettle/sha3.h>}. 716 717@deftp {Context struct} {struct sha3_224_ctx} 718@end deftp 719 720@defvr Constant SHA3_224_DIGEST_SIZE 721The size of a SHA3_224 digest, i.e., 28. 722@end defvr 723 724@defvr Constant SHA3_224_BLOCK_SIZE 725The internal block size of SHA3_224. 726@end defvr 727 728@deftypefun void sha3_224_init (struct sha3_224_ctx *@var{ctx}) 729Initialize the SHA3-224 state. 730@end deftypefun 731 732@deftypefun void sha3_224_update (struct sha3_224_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 733Hash some more data. 734@end deftypefun 735 736@deftypefun void sha3_224_digest (struct sha3_224_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 737Performs final processing and extracts the message digest, writing it 738to @var{digest}. @var{length} may be smaller than 739@code{SHA3_224_DIGEST_SIZE}, in which case only the first @var{length} 740octets of the digest are written. 741 742This function also resets the context. 743@end deftypefun 744 745@subsubsection @acronym{SHA3-256} 746 747This is SHA3 with 256-bit output size, and possibly the most useful 748of the SHA3 hash functions. 749 750Nettle defines SHA3-256 in @file{<nettle/sha3.h>}. 751 752@deftp {Context struct} {struct sha3_256_ctx} 753@end deftp 754 755@defvr Constant SHA3_256_DIGEST_SIZE 756The size of a SHA3_256 digest, i.e., 32. 757@end defvr 758 759@defvr Constant SHA3_256_BLOCK_SIZE 760The internal block size of SHA3_256. 761@end defvr 762 763@deftypefun void sha3_256_init (struct sha3_256_ctx *@var{ctx}) 764Initialize the SHA3-256 state. 765@end deftypefun 766 767@deftypefun void sha3_256_update (struct sha3_256_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 768Hash some more data. 769@end deftypefun 770 771@deftypefun void sha3_256_digest (struct sha3_256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 772Performs final processing and extracts the message digest, writing it 773to @var{digest}. @var{length} may be smaller than 774@code{SHA3_256_DIGEST_SIZE}, in which case only the first @var{length} 775octets of the digest are written. 776 777This function also resets the context. 778@end deftypefun 779 780@subsubsection @acronym{SHA3-384} 781 782This is SHA3 with 384-bit output size. 783 784Nettle defines SHA3-384 in @file{<nettle/sha3.h>}. 785 786@deftp {Context struct} {struct sha3_384_ctx} 787@end deftp 788 789@defvr Constant SHA3_384_DIGEST_SIZE 790The size of a SHA3_384 digest, i.e., 48. 791@end defvr 792 793@defvr Constant SHA3_384_BLOCK_SIZE 794The internal block size of SHA3_384. 795@end defvr 796 797@deftypefun void sha3_384_init (struct sha3_384_ctx *@var{ctx}) 798Initialize the SHA3-384 state. 799@end deftypefun 800 801@deftypefun void sha3_384_update (struct sha3_384_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 802Hash some more data. 803@end deftypefun 804 805@deftypefun void sha3_384_digest (struct sha3_384_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 806Performs final processing and extracts the message digest, writing it 807to @var{digest}. @var{length} may be smaller than 808@code{SHA3_384_DIGEST_SIZE}, in which case only the first @var{length} 809octets of the digest are written. 810 811This function also resets the context. 812@end deftypefun 813 814@subsubsection @acronym{SHA3-512} 815 816This is SHA3 with 512-bit output size. 817 818Nettle defines SHA3-512 in @file{<nettle/sha3.h>}. 819 820@deftp {Context struct} {struct sha3_512_ctx} 821@end deftp 822 823@defvr Constant SHA3_512_DIGEST_SIZE 824The size of a SHA3_512 digest, i.e. 64. 825@end defvr 826 827@defvr Constant SHA3_512_BLOCK_SIZE 828The internal block size of SHA3_512. 829@end defvr 830 831@deftypefun void sha3_512_init (struct sha3_512_ctx *@var{ctx}) 832Initialize the SHA3-512 state. 833@end deftypefun 834 835@deftypefun void sha3_512_update (struct sha3_512_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 836Hash some more data. 837@end deftypefun 838 839@deftypefun void sha3_512_digest (struct sha3_512_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 840Performs final processing and extracts the message digest, writing it 841to @var{digest}. @var{length} may be smaller than 842@code{SHA3_512_DIGEST_SIZE}, in which case only the first @var{length} 843octets of the digest are written. 844 845This function also resets the context. 846@end deftypefun 847 848@subsubsection @acronym{SHAKE-256} 849@cindex SHAKE 850 851In addition to those SHA-3 hash functions, Nettle also provides a SHA-3 852extendable-output function (XOF), SHAKE-256. Unlike SHA-3 hash functions, 853SHAKE can produce an output digest of any desired length. 854 855To use SHAKE256, the context struct, init and update functions are the 856same as for SHA3-256. To get a SHAKE256 digest, the following function 857is used instead of @code{sha3_256_digest}. For an output size of 858@code{SHA3_256_DIGEST_SIZE}, security is equivalent to SHA3-256 (but the 859digest is different). Increasing output size further does not increase 860security in terms of collision or preimage resistance. It can be seen as 861a built in pseudorandomness generator. 862 863@deftypefun void sha3_256_shake (struct shake256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 864Performs final processing and produces a SHAKE256 digest, writing it 865to @var{digest}. @var{length} can be of arbitrary size. 866 867This function also resets the context. 868@end deftypefun 869 870@node Miscellaneous hash functions, Legacy hash functions, Recommended hash functions, Hash functions 871@comment node-name, next, previous, up 872@subsection Miscellaneous hash functions 873 874@subsubsection @acronym{STREEBOG512} 875 876STREEBOG512 is a member of the Streebog (GOST R 34.11-2012) family. It outputs 877hash values of 512 bits, or 64 octets. Nettle defines STREEBOG512 in 878@file{<nettle/streebog.h>}. 879 880@deftp {Context struct} {struct streebog512_ctx} 881@end deftp 882 883@defvr Constant STREEBOG512_DIGEST_SIZE 884The size of a STREEBOG512 digest, i.e. 64. 885@end defvr 886 887@defvr Constant STREEBOG512_BLOCK_SIZE 888The internal block size of STREEBOG512. Useful for some special constructions, 889in particular HMAC-STREEBOG512. 890@end defvr 891 892@deftypefun void streebog512_init (struct streebog512_ctx *@var{ctx}) 893Initialize the STREEBOG512 state. 894@end deftypefun 895 896@deftypefun void streebog512_update (struct streebog512_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 897Hash some more data. 898@end deftypefun 899 900@deftypefun void streebog512_digest (struct streebog512_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 901Performs final processing and extracts the message digest, writing it 902to @var{digest}. @var{length} may be smaller than 903@code{STREEBOG512_DIGEST_SIZE}, in which case only the first @var{length} 904octets of the digest are written. 905 906This function also resets the context in the same way as 907@code{streebog512_init}. 908@end deftypefun 909 910@subsubsection @acronym{STREEBOG256} 911 912STREEBOG256 is a variant of STREEBOG512, with a different initial state, and with 913the output truncated to 256 bits, or 32 octets. Nettle defines STREEBOG256 in 914@file{<nettle/streebog.h>}. 915 916@deftp {Context struct} {struct streebog256_ctx} 917@end deftp 918 919@defvr Constant STREEBOG256_DIGEST_SIZE 920The size of a STREEBOG256 digest, i.e. 32. 921@end defvr 922 923@defvr Constant STREEBOG256_BLOCK_SIZE 924The internal block size of STREEBOG256. Useful for some special constructions, 925in particular HMAC-STREEBOG256. 926@end defvr 927 928@deftypefun void streebog256_init (struct streebog256_ctx *@var{ctx}) 929Initialize the STREEBOG256 state. 930@end deftypefun 931 932@deftypefun void streebog256_update (struct streebog256_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 933Hash some more data. 934@end deftypefun 935 936@deftypefun void streebog256_digest (struct streebog256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 937Performs final processing and extracts the message digest, writing it 938to @var{digest}. @var{length} may be smaller than 939@code{STREEBOG256_DIGEST_SIZE}, in which case only the first @var{length} 940octets of the digest are written. 941 942This function also resets the context in the same way as 943@code{streebog256_init}. 944@end deftypefun 945 946 947@node Legacy hash functions, nettle_hash abstraction, Miscellaneous hash functions, Hash functions 948@comment node-name, next, previous, up 949@subsection Legacy hash functions 950 951The hash functions in this section all have some known weaknesses, and 952should be avoided for new applications. These hash functions are mainly 953useful for compatibility with old applications and protocols. Some are 954still considered safe as building blocks for particular constructions, 955e.g., there seems to be no known attacks against HMAC-SHA1 or even 956HMAC-MD5. In some important cases, use of a ``legacy'' hash function 957does not in itself make the application insecure; if a known weakness is 958relevant depends on how the hash function is used, and on the threat 959model. 960 961@subsubsection @acronym{MD5} 962 963MD5 is a message digest function constructed by Ronald Rivest, and 964described in @cite{RFC 1321}. It outputs message digests of 128 bits, or 96516 octets. Nettle defines MD5 in @file{<nettle/md5.h>}. 966 967@deftp {Context struct} {struct md5_ctx} 968@end deftp 969 970@defvr Constant MD5_DIGEST_SIZE 971The size of an MD5 digest, i.e. 16. 972@end defvr 973 974@defvr Constant MD5_BLOCK_SIZE 975The internal block size of MD5. Useful for some special constructions, 976in particular HMAC-MD5. 977@end defvr 978 979@deftypefun void md5_init (struct md5_ctx *@var{ctx}) 980Initialize the MD5 state. 981@end deftypefun 982 983@deftypefun void md5_update (struct md5_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 984Hash some more data. 985@end deftypefun 986 987@deftypefun void md5_digest (struct md5_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 988Performs final processing and extracts the message digest, writing it 989to @var{digest}. @var{length} may be smaller than 990@code{MD5_DIGEST_SIZE}, in which case only the first @var{length} 991octets of the digest are written. 992 993This function also resets the context in the same way as 994@code{md5_init}. 995@end deftypefun 996 997The normal way to use MD5 is to call the functions in order: First 998@code{md5_init}, then @code{md5_update} zero or more times, and finally 999@code{md5_digest}. After @code{md5_digest}, the context is reset to 1000its initial state, so you can start over calling @code{md5_update} to 1001hash new data. 1002 1003To start over, you can call @code{md5_init} at any time. 1004 1005@subsubsection @acronym{MD2} 1006 1007MD2 is another hash function of Ronald Rivest's, described in 1008@cite{RFC 1319}. It outputs message digests of 128 bits, or 16 octets. 1009Nettle defines MD2 in @file{<nettle/md2.h>}. 1010 1011@deftp {Context struct} {struct md2_ctx} 1012@end deftp 1013 1014@defvr Constant MD2_DIGEST_SIZE 1015The size of an MD2 digest, i.e. 16. 1016@end defvr 1017 1018@defvr Constant MD2_BLOCK_SIZE 1019The internal block size of MD2. 1020@end defvr 1021 1022@deftypefun void md2_init (struct md2_ctx *@var{ctx}) 1023Initialize the MD2 state. 1024@end deftypefun 1025 1026@deftypefun void md2_update (struct md2_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 1027Hash some more data. 1028@end deftypefun 1029 1030@deftypefun void md2_digest (struct md2_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 1031Performs final processing and extracts the message digest, writing it 1032to @var{digest}. @var{length} may be smaller than 1033@code{MD2_DIGEST_SIZE}, in which case only the first @var{length} 1034octets of the digest are written. 1035 1036This function also resets the context in the same way as 1037@code{md2_init}. 1038@end deftypefun 1039 1040@subsubsection @acronym{MD4} 1041 1042MD4 is a predecessor of MD5, described in @cite{RFC 1320}. Like MD5, it 1043is constructed by Ronald Rivest. It outputs message digests of 128 bits, 1044or 16 octets. Nettle defines MD4 in @file{<nettle/md4.h>}. Use of MD4 is 1045not recommended, but it is sometimes needed for compatibility with 1046existing applications and protocols. 1047 1048@deftp {Context struct} {struct md4_ctx} 1049@end deftp 1050 1051@defvr Constant MD4_DIGEST_SIZE 1052The size of an MD4 digest, i.e. 16. 1053@end defvr 1054 1055@defvr Constant MD4_BLOCK_SIZE 1056The internal block size of MD4. 1057@end defvr 1058 1059@deftypefun void md4_init (struct md4_ctx *@var{ctx}) 1060Initialize the MD4 state. 1061@end deftypefun 1062 1063@deftypefun void md4_update (struct md4_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 1064Hash some more data. 1065@end deftypefun 1066 1067@deftypefun void md4_digest (struct md4_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 1068Performs final processing and extracts the message digest, writing it 1069to @var{digest}. @var{length} may be smaller than 1070@code{MD4_DIGEST_SIZE}, in which case only the first @var{length} 1071octets of the digest are written. 1072 1073This function also resets the context in the same way as 1074@code{md4_init}. 1075@end deftypefun 1076 1077@subsubsection @acronym{RIPEMD160} 1078 1079RIPEMD160 is a hash function designed by Hans Dobbertin, Antoon 1080Bosselaers, and Bart Preneel, as a strengthened version of RIPEMD 1081(which, like MD4 and MD5, fails the collision-resistance requirement). 1082It produces message digests of 160 bits, or 20 octets. Nettle defined 1083RIPEMD160 in @file{nettle/ripemd160.h}. 1084 1085@deftp {Context struct} {struct ripemd160_ctx} 1086@end deftp 1087 1088@defvr Constant RIPEMD160_DIGEST_SIZE 1089The size of a RIPEMD160 digest, i.e. 20. 1090@end defvr 1091 1092@defvr Constant RIPEMD160_BLOCK_SIZE 1093The internal block size of RIPEMD160. 1094@end defvr 1095 1096@deftypefun void ripemd160_init (struct ripemd160_ctx *@var{ctx}) 1097Initialize the RIPEMD160 state. 1098@end deftypefun 1099 1100@deftypefun void ripemd160_update (struct ripemd160_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 1101Hash some more data. 1102@end deftypefun 1103 1104@deftypefun void ripemd160_digest (struct ripemd160_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 1105Performs final processing and extracts the message digest, writing it 1106to @var{digest}. @var{length} may be smaller than 1107@code{RIPEMD160_DIGEST_SIZE}, in which case only the first @var{length} 1108octets of the digest are written. 1109 1110This function also resets the context in the same way as 1111@code{ripemd160_init}. 1112@end deftypefun 1113 1114@subsubsection @acronym{SHA1} 1115 1116SHA1 is a hash function specified by @dfn{NIST} (The U.S. National 1117Institute for Standards and Technology). It outputs hash values of 160 1118bits, or 20 octets. Nettle defines SHA1 in @file{<nettle/sha1.h>} (and 1119in @file{<nettle/sha.h>}, for backwards compatibility). 1120 1121@deftp {Context struct} {struct sha1_ctx} 1122@end deftp 1123 1124@defvr Constant SHA1_DIGEST_SIZE 1125The size of a SHA1 digest, i.e. 20. 1126@end defvr 1127 1128@defvr Constant SHA1_BLOCK_SIZE 1129The internal block size of SHA1. Useful for some special constructions, 1130in particular HMAC-SHA1. 1131@end defvr 1132 1133@deftypefun void sha1_init (struct sha1_ctx *@var{ctx}) 1134Initialize the SHA1 state. 1135@end deftypefun 1136 1137@deftypefun void sha1_update (struct sha1_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 1138Hash some more data. 1139@end deftypefun 1140 1141@deftypefun void sha1_digest (struct sha1_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 1142Performs final processing and extracts the message digest, writing it 1143to @var{digest}. @var{length} may be smaller than 1144@code{SHA1_DIGEST_SIZE}, in which case only the first @var{length} 1145octets of the digest are written. 1146 1147This function also resets the context in the same way as 1148@code{sha1_init}. 1149@end deftypefun 1150 1151 1152@subsubsection @acronym{GOSTHASH94 and GOSTHASH94CP} 1153@cindex GOST hash 1154 1155@anchor{GOSTHASH94CP} 1156The GOST94 or GOST R 34.11-94 hash algorithm is a Soviet-era algorithm 1157used in Russian government standards (see @cite{RFC 4357}). 1158It outputs message digests of 256 bits, or 32 octets. The standard itself 1159does not fix the S-box used by the hash algorith, so there are two popular 1160variants (the testing S-box from the standard itself and the S-box defined 1161by CryptoPro company, see RFC 4357). Nettle provides support for the former 1162S-box in the form of GOSTHASH94 hash algorithm and for the latter in the 1163form of GOSTHASH94CP hash algorithm. 1164Nettle defines GOSTHASH94 and GOSTHASH94CP in @file{<nettle/gosthash94.h>}. 1165 1166@deftp {Context struct} {struct gosthash94_ctx} 1167@end deftp 1168 1169@defvr Constant GOSTHASH94_DIGEST_SIZE 1170The size of a GOSTHASH94 digest, i.e. 32. 1171@end defvr 1172 1173@defvr Constant GOSTHASH94_BLOCK_SIZE 1174The internal block size of GOSTHASH94, i.e., 32. 1175@end defvr 1176 1177@deftypefun void gosthash94_init (struct gosthash94_ctx *@var{ctx}) 1178Initialize the GOSTHASH94 state. 1179@end deftypefun 1180 1181@deftypefun void gosthash94_update (struct gosthash94_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 1182Hash some more data. 1183@end deftypefun 1184 1185@deftypefun void gosthash94_digest (struct gosthash94_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 1186Performs final processing and extracts the message digest, writing it 1187to @var{digest}. @var{length} may be smaller than 1188@code{GOSTHASH94_DIGEST_SIZE}, in which case only the first @var{length} 1189octets of the digest are written. 1190 1191This function also resets the context in the same way as 1192@code{gosthash94_init}. 1193@end deftypefun 1194 1195@deftp {Context struct} {struct gosthash94cp_ctx} 1196@end deftp 1197 1198@defvr Constant GOSTHASH94CP_DIGEST_SIZE 1199The size of a GOSTHASH94CP digest, i.e. 32. 1200@end defvr 1201 1202@defvr Constant GOSTHASH94CP_BLOCK_SIZE 1203The internal block size of GOSTHASH94CP, i.e., 32. 1204@end defvr 1205 1206@deftypefun void gosthash94cp_init (struct gosthash94cp_ctx *@var{ctx}) 1207Initialize the GOSTHASH94CP state. 1208@end deftypefun 1209 1210@deftypefun void gosthash94cp_update (struct gosthash94cp_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 1211Hash some more data. 1212@end deftypefun 1213 1214@deftypefun void gosthash94cp_digest (struct gosthash94cp_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 1215Performs final processing and extracts the message digest, writing it 1216to @var{digest}. @var{length} may be smaller than 1217@code{GOSTHASH94CP_DIGEST_SIZE}, in which case only the first @var{length} 1218octets of the digest are written. 1219 1220This function also resets the context in the same way as 1221@code{gosthash94cp_init}. 1222@end deftypefun 1223 1224@node nettle_hash abstraction,, Legacy hash functions, Hash functions 1225@comment node-name, next, previous, up 1226@subsection The @code{struct nettle_hash} abstraction 1227@cindex nettle_hash 1228 1229Nettle includes a struct including information about the supported hash 1230functions. It is defined in @file{<nettle/nettle-meta.h>}, and is used 1231by Nettle's implementation of @acronym{HMAC} (@pxref{Keyed hash 1232functions}). 1233 1234@deftp {Meta struct} @code{struct nettle_hash} name context_size digest_size block_size init update digest 1235The last three attributes are function pointers, of types 1236@code{nettle_hash_init_func *}, @code{nettle_hash_update_func *}, and 1237@code{nettle_hash_digest_func *}. The first argument to these functions is 1238@code{void *} pointer to a context struct, which is of size 1239@code{context_size}. 1240@end deftp 1241 1242@deftypevr {Constant Struct} {struct nettle_hash} nettle_md2 1243@deftypevrx {Constant Struct} {struct nettle_hash} nettle_md4 1244@deftypevrx {Constant Struct} {struct nettle_hash} nettle_md5 1245@deftypevrx {Constant Struct} {struct nettle_hash} nettle_ripemd160 1246@deftypevrx {Constant Struct} {struct nettle_hash} nettle_sha1 1247@deftypevrx {Constant Struct} {struct nettle_hash} nettle_sha224 1248@deftypevrx {Constant Struct} {struct nettle_hash} nettle_sha256 1249@deftypevrx {Constant Struct} {struct nettle_hash} nettle_sha384 1250@deftypevrx {Constant Struct} {struct nettle_hash} nettle_sha512 1251@deftypevrx {Constant Struct} {struct nettle_hash} nettle_sha3_256 1252@deftypevrx {Constant Struct} {struct nettle_hash} nettle_gosthash94 1253@deftypevrx {Constant Struct} {struct nettle_hash} nettle_gosthash94cp 1254These are all the hash functions that Nettle implements. 1255@end deftypevr 1256 1257Nettle also exports a list of all these hashes. 1258 1259@deftypefun {const struct nettle_hash **} nettle_get_hashes (void) 1260Returns a NULL-terminated list of pointers to supported hash functions. 1261This list can be used to dynamically enumerate or search the supported 1262algorithms. 1263@end deftypefun 1264 1265@deffn Macro nettle_hashes 1266A macro expanding to a call to nettle_get_hashes, so that one could 1267write, e.g., @code{nettle_hashes[0]->name} for the name of the first 1268hash function on the list. In earlier versions, this was not a macro but 1269the actual array of pointers. However, referring directly to the array 1270makes the array size leak into the ABI in some cases. 1271@end deffn 1272 1273@node Cipher functions, Cipher modes, Hash functions, Reference 1274@comment node-name, next, previous, up 1275@section Cipher functions 1276@cindex Cipher 1277 1278A @dfn{cipher} is a function that takes a message or @dfn{plaintext} 1279and a secret @dfn{key} and transforms it to a @dfn{ciphertext}. Given 1280only the ciphertext, but not the key, it should be hard to find the 1281plaintext. Given matching pairs of plaintext and ciphertext, it should 1282be hard to find the key. 1283 1284@cindex Block Cipher 1285@cindex Stream Cipher 1286 1287There are two main classes of ciphers: Block ciphers and stream ciphers. 1288 1289A block cipher can process data only in fixed size chunks, called 1290@dfn{blocks}. Typical block sizes are 8 or 16 octets. To encrypt 1291arbitrary messages, you usually have to pad it to an integral number of 1292blocks, split it into blocks, and then process each block. The simplest 1293way is to process one block at a time, independent of each other. That 1294mode of operation is called @dfn{ECB}, Electronic Code Book mode. 1295However, using @acronym{ECB} is usually a bad idea. For a start, plaintext blocks 1296that are equal are transformed to ciphertext blocks that are equal; that 1297leaks information about the plaintext. Usually you should apply the 1298cipher is some ``feedback mode'', @dfn{CBC} (Cipher Block Chaining) and 1299@dfn{CTR} (Counter mode) being two of 1300of the most popular. See @xref{Cipher modes}, for information on 1301how to apply @acronym{CBC} and @acronym{CTR} with Nettle. 1302 1303A stream cipher can be used for messages of arbitrary length. A typical 1304stream cipher is a keyed pseudo-random generator. To encrypt a plaintext 1305message of @var{n} octets, you key the generator, generate @var{n} 1306octets of pseudo-random data, and XOR it with the plaintext. To decrypt, 1307regenerate the same stream using the key, XOR it to the ciphertext, and 1308the plaintext is recovered. 1309 1310@strong{Caution:} The first rule for this kind of cipher is the 1311same as for a One Time Pad: @emph{never} ever use the same key twice. 1312 1313A common misconception is that encryption, by itself, implies 1314authentication. Say that you and a friend share a secret key, and you 1315receive an encrypted message. You apply the key, and get a plaintext 1316message that makes sense to you. Can you then be sure that it really was 1317your friend that wrote the message you're reading? The answer is no. For 1318example, if you were using a block cipher in ECB mode, an attacker may 1319pick up the message on its way, and reorder, delete or repeat some of 1320the blocks. Even if the attacker can't decrypt the message, he can 1321change it so that you are not reading the same message as your friend 1322wrote. If you are using a block cipher in @acronym{CBC} mode rather than 1323ECB, or are using a stream cipher, the possibilities for this sort of 1324attack are different, but the attacker can still make predictable 1325changes to the message. 1326 1327It is recommended to @emph{always} use an authentication mechanism in 1328addition to encrypting the messages. Popular choices are Message 1329Authentication Codes like @acronym{HMAC-SHA1} (@pxref{Keyed hash 1330functions}), or digital signatures like @acronym{RSA}. 1331 1332Some ciphers have so called ``weak keys'', keys that results in 1333undesirable structure after the key setup processing, and should be 1334avoided. In Nettle, most key setup functions have no return value, but 1335for ciphers with weak keys, the return value indicates whether or not 1336the given key is weak. For good keys, key setup returns 1, and for weak 1337keys, it returns 0. When possible, avoid algorithms that 1338have weak keys. There are several good ciphers that don't have any weak 1339keys. 1340 1341To encrypt a message, you first initialize a cipher context for 1342encryption or decryption with a particular key. You then use the context 1343to process plaintext or ciphertext messages. The initialization is known 1344as @dfn{key setup}. With Nettle, it is recommended to use each 1345context struct for only one direction, even if some of the ciphers use a 1346single key setup function that can be used for both encryption and 1347decryption. 1348 1349@subsection AES 1350@cindex AES 1351 1352AES is a block cipher, specified by NIST as a replacement for 1353the older DES standard. The standard is the result of a competition 1354between cipher designers. The winning design, also known as RIJNDAEL, 1355was constructed by Joan Daemen and Vincent Rijnmen. 1356 1357Like all the AES candidates, the winning design uses a block size of 128 1358bits, or 16 octets, and three possible key-size, 128, 192 and 256 bits 1359(16, 24 and 32 octets) being the allowed key sizes. It does not have any 1360weak keys. Nettle defines AES in @file{<nettle/aes.h>}, and there is one 1361context struct for each key size. (Earlier versions of Nettle used a 1362single context struct, @code{struct aes_ctx}, for all key sizes. This 1363interface kept for backwards compatibility). 1364 1365@deftp {Context struct} {struct aes128_ctx} 1366@deftpx {Context struct} {struct aes192_ctx} 1367@deftpx {Context struct} {struct aes256_ctx} 1368@end deftp 1369 1370@deftp {Context struct} {struct aes_ctx} 1371Alternative struct, for the old AES interface. 1372@end deftp 1373 1374@defvr Constant AES_BLOCK_SIZE 1375The AES block-size, 16. 1376@end defvr 1377 1378@defvr Constant AES128_KEY_SIZE 1379@defvrx Constant AES192_KEY_SIZE 1380@defvrx Constant AES256_KEY_SIZE 1381@defvrx Constant AES_MIN_KEY_SIZE 1382@defvrx Constant AES_MAX_KEY_SIZE 1383@end defvr 1384 1385@defvr Constant AES_KEY_SIZE 1386Default AES key size, 32. 1387@end defvr 1388 1389@deftypefun void aes128_set_encrypt_key (struct aes128_ctx *@var{ctx}, const uint8_t *@var{key}) 1390@deftypefunx void aes128_set_decrypt_key (struct aes128_ctx *@var{ctx}, const uint8_t *@var{key}) 1391@deftypefunx void aes192_set_encrypt_key (struct aes192_ctx *@var{ctx}, const uint8_t *@var{key}) 1392@deftypefunx void aes192_set_decrypt_key (struct aes192_ctx *@var{ctx}, const uint8_t *@var{key}) 1393@deftypefunx void aes256_set_encrypt_key (struct aes256_ctx *@var{ctx}, const uint8_t *@var{key}) 1394@deftypefunx void aes256_set_decrypt_key (struct aes256_ctx *@var{ctx}, const uint8_t *@var{key}) 1395@deftypefunx void aes_set_encrypt_key (struct aes_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{key}) 1396@deftypefunx void aes_set_decrypt_key (struct aes_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{key}) 1397Initialize the cipher, for encryption or decryption, respectively. 1398@end deftypefun 1399 1400@deftypefun void aes128_invert_key (struct aes128_ctx *@var{dst}, const struct aes128_ctx *@var{src}) 1401@deftypefunx void aes192_invert_key (struct aes192_ctx *@var{dst}, const struct aes192_ctx *@var{src}) 1402@deftypefunx void aes256_invert_key (struct aes256_ctx *@var{dst}, const struct aes256_ctx *@var{src}) 1403@deftypefunx void aes_invert_key (struct aes_ctx *@var{dst}, const struct aes_ctx *@var{src}) 1404Given a context @var{src} initialized for encryption, initializes the 1405context struct @var{dst} for decryption, using the same key. If the same 1406context struct is passed for both @code{src} and @code{dst}, it is 1407converted in place. These functions are mainly useful for applications 1408which needs to both encrypt and decrypt using the @emph{same} key, 1409because calling, e.g., @code{aes128_set_encrypt_key} and 1410@code{aes128_invert_key}, is more efficient than calling 1411@code{aes128_set_encrypt_key} and @code{aes128_set_decrypt_key}. 1412@end deftypefun 1413 1414@deftypefun void aes128_encrypt (struct aes128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1415@deftypefunx void aes192_encrypt (struct aes192_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1416@deftypefunx void aes256_encrypt (struct aes256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1417@deftypefunx void aes_encrypt (struct aes_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1418Encryption function. @var{length} must be an integral multiple of the 1419block size. If it is more than one block, the data is processed in ECB 1420mode. @code{src} and @code{dst} may be equal, but they must not overlap 1421in any other way. 1422@end deftypefun 1423 1424@deftypefun void aes128_decrypt (struct aes128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1425@deftypefunx void aes192_decrypt (struct aes192_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1426@deftypefunx void aes256_decrypt (struct aes256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1427@deftypefunx void aes_decrypt (struct aes_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1428Analogous to the encryption functions above. 1429@end deftypefun 1430 1431@subsection ARCFOUR 1432@cindex Arcfour 1433@cindex RC4 1434ARCFOUR is a stream cipher, also known under the trade marked name RC4, 1435and it is one of the fastest ciphers around. A problem is that the key 1436setup of ARCFOUR is quite weak, you should never use keys with 1437structure, keys that are ordinary passwords, or sequences of keys like 1438``secret:1'', ``secret:2'', @enddots{}. If you have keys that don't look 1439like random bit strings, and you want to use ARCFOUR, always hash the 1440key before feeding it to ARCFOUR. Furthermore, the initial bytes of the 1441generated key stream leak information about the key; for this reason, it 1442is recommended to discard the first 512 bytes of the key stream. 1443 1444@example 1445/* A more robust key setup function for ARCFOUR */ 1446void 1447arcfour_set_key_hashed(struct arcfour_ctx *ctx, 1448 size_t length, const uint8_t *key) 1449@{ 1450 struct sha256_ctx hash; 1451 uint8_t digest[SHA256_DIGEST_SIZE]; 1452 uint8_t buffer[0x200]; 1453 1454 sha256_init(&hash); 1455 sha256_update(&hash, length, key); 1456 sha256_digest(&hash, SHA256_DIGEST_SIZE, digest); 1457 1458 arcfour_set_key(ctx, SHA256_DIGEST_SIZE, digest); 1459 arcfour_crypt(ctx, sizeof(buffer), buffer, buffer); 1460@} 1461@end example 1462 1463Nettle defines ARCFOUR in @file{<nettle/arcfour.h>}. 1464 1465@deftp {Context struct} {struct arcfour_ctx} 1466@end deftp 1467 1468@defvr Constant ARCFOUR_MIN_KEY_SIZE 1469Minimum key size, 1. 1470@end defvr 1471 1472@defvr Constant ARCFOUR_MAX_KEY_SIZE 1473Maximum key size, 256. 1474@end defvr 1475 1476@defvr Constant ARCFOUR_KEY_SIZE 1477Default ARCFOUR key size, 16. 1478@end defvr 1479 1480@deftypefun void arcfour_set_key (struct arcfour_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{key}) 1481Initialize the cipher. The same function is used for both encryption and 1482decryption. 1483@end deftypefun 1484 1485@deftypefun void arcfour_crypt (struct arcfour_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1486Encrypt some data. The same function is used for both encryption and 1487decryption. Unlike the block ciphers, this function modifies the 1488context, so you can split the data into arbitrary chunks and encrypt 1489them one after another. The result is the same as if you had called 1490@code{arcfour_crypt} only once with all the data. 1491@end deftypefun 1492 1493@subsection ARCTWO 1494@cindex Arctwo 1495@cindex RC2 1496ARCTWO (also known as the trade marked name RC2) is a block cipher 1497specified in RFC 2268. Nettle also include a variation of the ARCTWO 1498set key operation that lack one step, to be compatible with the 1499reverse engineered RC2 cipher description, as described in a Usenet 1500post to @code{sci.crypt} by Peter Gutmann. 1501 1502ARCTWO uses a block size of 64 bits, and variable key-size ranging 1503from 1 to 128 octets. Besides the key, ARCTWO also has a second 1504parameter to key setup, the number of effective key bits, @code{ekb}. 1505This parameter can be used to artificially reduce the key size. In 1506practice, @code{ekb} is usually set equal to the input key size. 1507Nettle defines ARCTWO in @file{<nettle/arctwo.h>}. 1508 1509We do not recommend the use of ARCTWO; the Nettle implementation is 1510provided primarily for interoperability with existing applications and 1511standards. 1512 1513@deftp {Context struct} {struct arctwo_ctx} 1514@end deftp 1515 1516@defvr Constant ARCTWO_BLOCK_SIZE 1517The ARCTWO block-size, 8. 1518@end defvr 1519 1520@defvr Constant ARCTWO_MIN_KEY_SIZE 1521@end defvr 1522 1523@defvr Constant ARCTWO_MAX_KEY_SIZE 1524@end defvr 1525 1526@defvr Constant ARCTWO_KEY_SIZE 1527Default ARCTWO key size, 8. 1528@end defvr 1529 1530@deftypefun void arctwo_set_key_ekb (struct arctwo_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{key}, unsigned @var{ekb}) 1531@deftypefunx void arctwo_set_key (struct arctwo_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{key}) 1532@deftypefunx void arctwo_set_key_gutmann (struct arctwo_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{key}) 1533Initialize the cipher. The same function is used for both encryption 1534and decryption. The first function is the most general one, which lets 1535you provide both the variable size key, and the desired effective key 1536size (in bits). The maximum value for @var{ekb} is 1024, and for 1537convenience, @code{ekb = 0} has the same effect as @code{ekb = 1024}. 1538 1539@code{arctwo_set_key(ctx, length, key)} is equivalent to 1540@code{arctwo_set_key_ekb(ctx, length, key, 8*length)}, and 1541@code{arctwo_set_key_gutmann(ctx, length, key)} is equivalent to 1542@code{arctwo_set_key_ekb(ctx, length, key, 1024)} 1543@end deftypefun 1544 1545@deftypefun void arctwo_encrypt (struct arctwo_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1546Encryption function. @var{length} must be an integral multiple of the 1547block size. If it is more than one block, the data is processed in ECB 1548mode. @code{src} and @code{dst} may be equal, but they must not 1549overlap in any other way. 1550@end deftypefun 1551 1552@deftypefun void arctwo_decrypt (struct arctwo_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1553Analogous to @code{arctwo_encrypt} 1554@end deftypefun 1555 1556@subsection BLOWFISH 1557@cindex Blowfish 1558 1559BLOWFISH is a block cipher designed by Bruce Schneier. It uses a block 1560size of 64 bits (8 octets), and a variable key size, up to 448 bits. It 1561has some weak keys. Nettle defines BLOWFISH in @file{<nettle/blowfish.h>}. 1562 1563@deftp {Context struct} {struct blowfish_ctx} 1564@end deftp 1565 1566@defvr Constant BLOWFISH_BLOCK_SIZE 1567The BLOWFISH block-size, 8. 1568@end defvr 1569 1570@defvr Constant BLOWFISH_MIN_KEY_SIZE 1571Minimum BLOWFISH key size, 8. 1572@end defvr 1573 1574@defvr Constant BLOWFISH_MAX_KEY_SIZE 1575Maximum BLOWFISH key size, 56. 1576@end defvr 1577 1578@defvr Constant BLOWFISH_KEY_SIZE 1579Default BLOWFISH key size, 16. 1580@end defvr 1581 1582@deftypefun int blowfish_set_key (struct blowfish_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{key}) 1583Initialize the cipher. The same function is used for both encryption and 1584decryption. Checks for weak keys, returning 1 1585for good keys and 0 for weak keys. Applications that don't care about 1586weak keys can ignore the return value. 1587 1588@code{blowfish_encrypt} or @code{blowfish_decrypt} with a weak key will 1589crash with an assert violation. 1590@end deftypefun 1591 1592@deftypefun void blowfish_encrypt (struct blowfish_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1593Encryption function. @var{length} must be an integral multiple of the 1594block size. If it is more than one block, the data is processed in ECB 1595mode. @code{src} and @code{dst} may be equal, but they must not overlap 1596in any other way. 1597@end deftypefun 1598 1599@deftypefun void blowfish_decrypt (struct blowfish_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1600Analogous to @code{blowfish_encrypt} 1601@end deftypefun 1602 1603@deftypefun int blowfish_bcrypt_hash (char *@var{dst}, size_t @var{lenkey}, const char *@var{key}, size_t @var{lenscheme}, const char *@var{scheme}, int @var{log2rounds}, const uint8_t *@var{salt}) 1604Compute the bcrypt password hash. 1605The function will return @code{0} if the hash cannot be computed 1606due to invalid input. 1607The function will return @code{1} and store the computed hash 1608in the array pointed to by @var{dst}. The hash is computed based 1609on the chosen @var{scheme}, number of rounds @var{log2rounds} and 1610specified @var{salt}. 1611 1612@var{dst} must point to a character array of at least 1613 @code{BLOWFISH_BCRYPT_HASH_SIZE} bytes. 1614 1615@var{key} contains the plaintext password string of size @var{lenkey}. 1616 1617@var{scheme} is of size @var{lenscheme} and contains either just the 1618chosen scheme (valid schemes 1619are: @code{2a}, @code{2b}, @code{2x} or @code{2y}), or 1620(the prefix of) an existing hashed password (typically @code{$2b$10$...}). 1621 1622@var{log2rounds} contains the log2 of the number of encryption rounds 1623that must be used to compute the hash. If it is @code{-1} the value 1624will be extracted from @var{scheme}. 1625 1626@var{salt} should point to an array of @code{BLOWFISH_BCRYPT_BINSALT_SIZE} 1627random bytes to be used to perturb the hash computation. If it is @code{NULL} 1628the salt will be extracted from @var{scheme}. 1629 1630Sample code to generate a bcrypt hash: 1631@example 1632char cleartxtpassword[] = "ExamplePassword"; 1633char scheme[] = "2b"; 1634uint8_t salt[BLOWFISH_BCRYPT_BINSALT_SIZE]; 1635@dots{} 1636/* Make sure that salt is filled with random bytes */ 1637@dots{} 1638char hashedresult[BLOWFISH_BCRYPT_HASH_SIZE]; 1639int result = blowfish_bcrypt(hashedresult, 1640 sizeof(cleartxtpassword) - 1, cleartxtpassword, 1641 sizeof(scheme) - 1, scheme, 10, salt); 1642if (result) 1643 printf("%s\n", hashedresult); 1644@end example 1645@end deftypefun 1646 1647@deftypefun int blowfish_bcrypt_verify (size_t @var{lenkey}, const char *@var{key}, size_t @var{lenhashed}, const char *@var{hashed}) 1648Verifies the bcrypt password hash against the supplied plaintext password. 1649The function will return @code{0} if the password does not match. 1650The function will return @code{1} if the password matches. 1651 1652@var{key} contains the plaintext password string of size @var{lenkey}. 1653 1654@var{hashed} contains the hashed string of size @var{lenhashed} to compare with. 1655 1656Sample code to verify a bcrypt hash: 1657@example 1658char cleartxtpassword[] = "ExamplePassword"; 1659char existinghashed[] = 1660 "$2y$" /* Hash algorithm version */ 1661 "10" /* 2^10 hash rounds (strength) */ 1662 "$" /* separator */ 1663 "1b2lPgo4XumibnJGN3r3sO" /* base64 encoded 16-byte salt */ 1664 "u7wE7xNfYDKlAxZffJDCJdVfFTAyevu"; /* Hashedpart */ 1665if (blowfish_bcrypt_verify(sizeof(cleartxtpassword) - 1, cleartxtpassword, 1666 sizeof(existinghashed) - 1, existinghashed)) 1667 printf("Password is correct."); 1668else 1669 printf("Password is incorrect."); 1670@end example 1671@end deftypefun 1672 1673@subsection Camellia 1674@cindex Camellia 1675 1676Camellia is a block cipher developed by Mitsubishi and Nippon Telegraph 1677and Telephone Corporation, described in @cite{RFC3713}. It is 1678recommended by some Japanese and European authorities as an alternative 1679to AES, and it is one of the selected algorithms in the New European 1680Schemes for Signatures, Integrity and Encryption (NESSIE) project. The 1681algorithm is patented. The implementation in Nettle is derived from the 1682implementation released by NTT under the GNU LGPL (v2.1 or later), and 1683relies on the implicit patent license of the LGPL. There is also a 1684statement of royalty-free licensing for Camellia at 1685@url{http://www.ntt.co.jp/news/news01e/0104/010417.html}, but this 1686statement has some limitations which seem problematic for free software. 1687 1688Camellia uses a the same block size and key sizes as AES: The block size 1689is 128 bits (16 octets), and the supported key sizes are 128, 192, and 1690256 bits. The variants with 192 and 256 bit keys are identical, except 1691for the key setup. Nettle defines Camellia in 1692@file{<nettle/camellia.h>}, and there is one context struct for each key 1693size. (Earlier versions of Nettle used a single context struct, 1694@code{struct camellia_ctx}, for all key sizes. This interface kept for 1695backwards compatibility). 1696 1697@deftp {Context struct} {struct camellia128_ctx} 1698@deftpx {Context struct} {struct camellia192_ctx} 1699@deftpx {Context struct} {struct camellia256_ctx} 1700Contexts structs. Actually, @code{camellia192_ctx} is an alias for 1701@code{camellia256_ctx}. 1702@end deftp 1703 1704@deftp {Context struct} {struct camellia_ctx} 1705Alternative struct, for the old Camellia interface. 1706@end deftp 1707 1708@defvr Constant CAMELLIA_BLOCK_SIZE 1709The CAMELLIA block-size, 16. 1710@end defvr 1711 1712@defvr Constant CAMELLIA128_KEY_SIZE 1713@defvrx Constant CAMELLIA192_KEY_SIZE 1714@defvrx Constant CAMELLIA256_KEY_SIZE 1715@defvrx Constant CAMELLIA_MIN_KEY_SIZE 1716@defvrx Constant CAMELLIA_MAX_KEY_SIZE 1717@end defvr 1718 1719@defvr Constant CAMELLIA_KEY_SIZE 1720Default CAMELLIA key size, 32. 1721@end defvr 1722 1723@deftypefun void camellia128_set_encrypt_key (struct camellia128_ctx *@var{ctx}, const uint8_t *@var{key}) 1724@deftypefunx void camellia128_set_decrypt_key (struct camellia128_ctx *@var{ctx}, const uint8_t *@var{key}) 1725@deftypefunx void camellia192_set_encrypt_key (struct camellia192_ctx *@var{ctx}, const uint8_t *@var{key}) 1726@deftypefunx void camellia192_set_decrypt_key (struct camellia192_ctx *@var{ctx}, const uint8_t *@var{key}) 1727@deftypefunx void camellia256_set_encrypt_key (struct camellia256_ctx *@var{ctx}, const uint8_t *@var{key}) 1728@deftypefunx void camellia256_set_decrypt_key (struct camellia256_ctx *@var{ctx}, const uint8_t *@var{key}) 1729@deftypefunx void camellia_set_encrypt_key (struct camellia_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{key}) 1730@deftypefunx void camellia_set_decrypt_key (struct camellia_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{key}) 1731Initialize the cipher, for encryption or decryption, respectively. 1732@end deftypefun 1733 1734@deftypefun void camellia128_invert_key (struct camellia128_ctx *@var{dst}, const struct camellia128_ctx *@var{src}) 1735@deftypefunx void camellia192_invert_key (struct camellia192_ctx *@var{dst}, const struct camellia192_ctx *@var{src}) 1736@deftypefunx void camellia256_invert_key (struct camellia256_ctx *@var{dst}, const struct camellia256_ctx *@var{src}) 1737@deftypefunx void camellia_invert_key (struct camellia_ctx *@var{dst}, const struct camellia_ctx *@var{src}) 1738Given a context @var{src} initialized for encryption, initializes the 1739context struct @var{dst} for decryption, using the same key. If the same 1740context struct is passed for both @code{src} and @code{dst}, it is 1741converted in place. These functions are mainly useful for applications 1742which needs to both encrypt and decrypt using the @emph{same} key. 1743@end deftypefun 1744 1745@deftypefun void camellia128_crypt (struct camellia128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1746@deftypefunx void camellia192_crypt (struct camellia192_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1747@deftypefunx void camellia256_crypt (struct camellia256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1748@deftypefunx void camellia_crypt (struct camellia_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1749The same function is used for both encryption and decryption. 1750@var{length} must be an integral multiple of the block size. If it is 1751more than one block, the data is processed in ECB mode. @code{src} and 1752@code{dst} may be equal, but they must not overlap in any other way. 1753@end deftypefun 1754 1755@subsection CAST128 1756@cindex CAST 1757 1758CAST-128 is a block cipher, specified in @cite{RFC 2144}. It uses a 64 1759bit (8 octets) block size, and a key size of 128 bits. It is possible, 1760but discouraged, to use the same algorithm with shorter keys. Nettle 1761refers to the variant with variable key size as CAST-5. Keys for CAST-5 1762are zero padded to 128 bits, and with very short keys, less than 80 1763bits, encryption also uses fewer rounds than CAST128. Nettle defines 1764cast128 in @file{<nettle/cast128.h>}. 1765 1766@deftp {Context struct} {struct cast128_ctx} 1767@end deftp 1768 1769@defvr Constant CAST128_BLOCK_SIZE 1770The CAST128 block-size, 8. 1771@end defvr 1772 1773@defvr Constant CAST128_KEY_SIZE 1774The CAST128 key size, 16. 1775@end defvr 1776 1777@defvr Constant CAST5_MIN_KEY_SIZE 1778Minimum CAST5 key size, 5. 1779@end defvr 1780 1781@defvr Constant CAST5_MAX_KEY_SIZE 1782Maximum CAST5 key size, 16. With 16 octets key (128 bits), CAST-5 is the 1783same as CAST-128. 1784@end defvr 1785 1786@deftypefun void cast128_set_key (struct cast128_ctx *@var{ctx}, const uint8_t *@var{key}) 1787Initialize the cipher. The same function is used for both encryption and 1788decryption. 1789@end deftypefun 1790 1791@deftypefun void cast128_encrypt (struct cast128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1792Encryption function. @var{length} must be an integral multiple of the 1793block size. If it is more than one block, the data is processed in ECB 1794mode. @code{src} and @code{dst} may be equal, but they must not overlap 1795in any other way. 1796@end deftypefun 1797 1798@deftypefun void cast128_decrypt (struct cast128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1799Analogous to @code{cast128_encrypt} 1800@end deftypefun 1801 1802@deftypefun void cast5_set_key (struct cast128_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{key}) 1803Initialize the cipher. This variant of the key setup takes the key size 1804as argument. The same function is used for both encryption and 1805decryption. 1806@end deftypefun 1807 1808@subsection ChaCha 1809@cindex ChaCha 1810 1811ChaCha is a variant of the stream cipher Salsa20, also designed by D. J. 1812Bernstein. For more information on Salsa20, see below. Nettle defines 1813ChaCha in @file{<nettle/chacha.h>}. 1814 1815@deftp {Context struct} {struct chacha_ctx} 1816@end deftp 1817 1818@defvr Constant CHACHA_KEY_SIZE 1819ChaCha key size, 32. 1820@end defvr 1821 1822@defvr Constant CHACHA_BLOCK_SIZE 1823ChaCha block size, 64. 1824@end defvr 1825 1826@defvr Constant CHACHA_NONCE_SIZE 1827Size of the nonce, 8. 1828@end defvr 1829 1830@defvr Constant CHACHA_COUNTER_SIZE 1831Size of the counter, 8. 1832@end defvr 1833 1834@deftypefun void chacha_set_key (struct chacha_ctx *@var{ctx}, const uint8_t *@var{key}) 1835Initialize the cipher. The same function is used for both encryption and 1836decryption. Before using the cipher, 1837you @emph{must} also call @code{chacha_set_nonce}, see below. 1838@end deftypefun 1839 1840@deftypefun void chacha_set_nonce (struct chacha_ctx *@var{ctx}, const uint8_t *@var{nonce}) 1841Sets the nonce. It is always of size @code{CHACHA_NONCE_SIZE}, 8 1842octets. This function also initializes the block counter, setting it to 1843zero. 1844@end deftypefun 1845 1846@deftypefun void chacha_set_counter (struct chacha_ctx *@var{ctx}, const uint8_t *@var{counter}) 1847Sets the block counter. It is always of size @code{CHACHA_COUNTER_SIZE}, 18488 octets. This is rarely needed since @code{chacha_set_nonce} 1849initializes the block counter to zero. When it is still necessary, this 1850function must be called after @code{chacha_set_nonce}. 1851 1852@end deftypefun 1853 1854@deftypefun void chacha_crypt (struct chacha_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1855Encrypts or decrypts the data of a message, using ChaCha. When a 1856message is encrypted using a sequence of calls to @code{chacha_crypt}, 1857all but the last call @emph{must} use a length that is a multiple of 1858@code{CHACHA_BLOCK_SIZE}. 1859@end deftypefun 1860 1861@subsubsection 32-bit counter variant 1862 1863While the original paper uses 64-bit counter value, the variant defined 1864in @cite{RFC 8439} uses 32-bit counter value. This variant is 1865particularly useful for @pxref{ChaCha-Poly1305} AEAD construction, which 1866supports 12-octet nonces. 1867 1868@defvr Constant CHACHA_NONCE96_SIZE 1869Size of the nonce, 12. 1870@end defvr 1871 1872@defvr Constant CHACHA_COUNTER32_SIZE 1873Size of the counter, 4. 1874@end defvr 1875 1876@deftypefun void chacha_set_nonce96 (struct chacha_ctx *@var{ctx}, const uint8_t *@var{nonce}) 1877Sets the nonce. This is similar to the above @code{chacha_set_nonce}, 1878but the input is always of size @code{CHACHA_NONCE96_SIZE}, 12 octets. 1879@end deftypefun 1880 1881@deftypefun void chacha_set_counter32 (struct chacha_ctx *@var{ctx}, const uint8_t *@var{counter}) 1882Sets the block counter. This is similar to the above @code{chacha_set_counter}, 1883but the input is always of size @code{CHACHA_COUNTER32_SIZE}, 4 octets. 1884@end deftypefun 1885 1886@deftypefun void chacha_crypt32 (struct chacha_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1887Encrypts or decrypts the data of a message, using ChaCha. This is similar to the 1888above @code{chacha_crypt}, but it assumes the internal counter value is 32-bit 1889long and the nonce is 96-bit long. 1890@end deftypefun 1891 1892@subsection DES 1893@cindex DES 1894DES is the old Data Encryption Standard, specified by NIST. It uses a 1895block size of 64 bits (8 octets), and a key size of 56 bits. However, 1896the key bits are distributed over 8 octets, where the least significant 1897bit of each octet may be used for parity. A common way to use DES is to 1898generate 8 random octets in some way, then set the least significant bit 1899of each octet to get odd parity, and initialize DES with the resulting 1900key. 1901 1902The key size of DES is so small that keys can be found by brute force, 1903using specialized hardware or lots of ordinary work stations in 1904parallel. One shouldn't be using plain DES at all today, if one uses 1905DES at all one should be using ``triple DES'', see DES3 below. 1906 1907DES also has some weak keys. Nettle defines DES in @file{<nettle/des.h>}. 1908 1909@deftp {Context struct} {struct des_ctx} 1910@end deftp 1911 1912@defvr Constant DES_BLOCK_SIZE 1913The DES block-size, 8. 1914@end defvr 1915 1916@defvr Constant DES_KEY_SIZE 1917DES key size, 8. 1918@end defvr 1919 1920@deftypefun int des_set_key (struct des_ctx *@var{ctx}, const uint8_t *@var{key}) 1921Initialize the cipher. The same function is used for both encryption and 1922decryption. Parity bits are ignored. Checks for weak keys, returning 1 1923for good keys and 0 for weak keys. Applications that don't care about 1924weak keys can ignore the return value. 1925@end deftypefun 1926 1927@deftypefun void des_encrypt (struct des_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1928Encryption function. @var{length} must be an integral multiple of the 1929block size. If it is more than one block, the data is processed in ECB 1930mode. @code{src} and @code{dst} may be equal, but they must not overlap 1931in any other way. 1932@end deftypefun 1933 1934@deftypefun void des_decrypt (struct des_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1935Analogous to @code{des_encrypt} 1936@end deftypefun 1937 1938@deftypefun int des_check_parity (size_t @var{length}, const uint8_t *@var{key}); 1939Checks that the given key has correct, odd, parity. Returns 1 for 1940correct parity, and 0 for bad parity. 1941@end deftypefun 1942 1943@deftypefun void des_fix_parity (size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 1944Adjusts the parity bits to match DES's requirements. You need this 1945function if you have created a random-looking string by a key agreement 1946protocol, and want to use it as a DES key. @var{dst} and @var{src} may 1947be equal. 1948@end deftypefun 1949 1950@subsection DES3 1951@cindex DES3 1952@cindex 3DES 1953@cindex Triple-DES 1954 1955The inadequate key size of DES has already been mentioned. One way to 1956increase the key size is to pipe together several DES boxes with 1957independent keys. It turns out that using two DES ciphers is not as 1958secure as one might think, even if the key size of the combination is a 1959respectable 112 bits. 1960 1961The standard way to increase DES's key size is to use three DES boxes. 1962The mode of operation is a little peculiar: the middle DES box is wired 1963in the reverse direction. To encrypt a block with DES3, you encrypt it 1964using the first 56 bits of the key, then @emph{decrypt} it using the 1965middle 56 bits of the key, and finally encrypt it again using the last 196656 bits of the key. This is known as ``ede'' triple-DES, for 1967``encrypt-decrypt-encrypt''. 1968 1969The ``ede'' construction provides some backward compatibility, as you get 1970plain single DES simply by feeding the same key to all three boxes. That 1971should help keeping down the gate count, and the price, of hardware 1972circuits implementing both plain DES and DES3. 1973 1974DES3 has a key size of 168 bits, but just like plain DES, useless parity 1975bits are inserted, so that keys are represented as 24 octets (192 bits). 1976As a 112 bit key is large enough to make brute force attacks 1977impractical, some applications uses a ``two-key'' variant of triple-DES. 1978In this mode, the same key bits are used for the first and the last DES 1979box in the pipe, while the middle box is keyed independently. The 1980two-key variant is believed to be secure, i.e. there are no known 1981attacks significantly better than brute force. 1982 1983Naturally, it's simple to implement triple-DES on top of Nettle's DES 1984functions. Nettle includes an implementation of three-key ``ede'' 1985triple-DES, it is defined in the same place as plain DES, 1986@file{<nettle/des.h>}. 1987 1988@deftp {Context struct} {struct des3_ctx} 1989@end deftp 1990 1991@defvr Constant DES3_BLOCK_SIZE 1992The DES3 block-size is the same as DES_BLOCK_SIZE, 8. 1993@end defvr 1994 1995@defvr Constant DES3_KEY_SIZE 1996DES key size, 24. 1997@end defvr 1998 1999@deftypefun int des3_set_key (struct des3_ctx *@var{ctx}, const uint8_t *@var{key}) 2000Initialize the cipher. The same function is used for both encryption and 2001decryption. Parity bits are ignored. Checks for weak keys, returning 1 2002if all three keys are good keys, and 0 if one or more key is weak. 2003Applications that don't care about weak keys can ignore the return 2004value. 2005@end deftypefun 2006 2007For random-looking strings, you can use @code{des_fix_parity} to adjust 2008the parity bits before calling @code{des3_set_key}. 2009 2010@deftypefun void des3_encrypt (struct des3_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2011Encryption function. @var{length} must be an integral multiple of the 2012block size. If it is more than one block, the data is processed in ECB 2013mode. @code{src} and @code{dst} may be equal, but they must not overlap 2014in any other way. 2015@end deftypefun 2016 2017@deftypefun void des3_decrypt (struct des3_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2018Analogous to @code{des_encrypt} 2019@end deftypefun 2020 2021@subsection Salsa20 2022@cindex Salsa20 2023Salsa20 is a fairly recent stream cipher designed by D. J. Bernstein. It 2024is built on the observation that a cryptographic hash function can be 2025used for encryption: Form the hash input from the secret key and a 2026counter, xor the hash output and the first block of the plaintext, then 2027increment the counter to process the next block (similar to CTR mode, see 2028@pxref{CTR}). Bernstein defined an encryption algorithm, Snuffle, 2029in this way to ridicule United States export restrictions which treated hash 2030functions as nice and harmless, but ciphers as dangerous munitions. 2031 2032Salsa20 uses the same idea, but with a new specialized hash function to 2033mix key, block counter, and a couple of constants. It's also designed 2034for speed; on x86_64, it is currently the fastest cipher offered by 2035nettle. It uses a block size of 512 bits (64 octets) and there are two 2036specified key sizes, 128 and 256 bits (16 and 32 octets). 2037 2038@strong{Caution:} The hash function used in Salsa20 is @emph{not} 2039directly applicable for use as a general hash function. It's @emph{not} 2040collision resistant if arbitrary inputs are allowed, and furthermore, 2041the input and output is of fixed size. 2042 2043When using Salsa20 to process a message, one specifies both a key and a 2044@dfn{nonce}, the latter playing a similar rôle to the initialization 2045vector (@acronym{IV}) used with @acronym{CBC} or @acronym{CTR} mode. One 2046can use the same key for several messages, provided one uses a unique 2047random @acronym{iv} for each message. The @acronym{iv} is 64 bits (8 2048octets). The block counter is initialized to zero for each message, and 2049is also 64 bits (8 octets). Nettle defines Salsa20 in 2050@file{<nettle/salsa20.h>}. 2051 2052@deftp {Context struct} {struct salsa20_ctx} 2053@end deftp 2054 2055@defvr Constant SALSA20_128_KEY_SIZE 2056@defvrx Constant SALSA20_256_KEY_SIZE 2057The two supported key sizes, 16 and 32 octets. 2058@end defvr 2059 2060@defvr Constant SALSA20_KEY_SIZE 2061Recommended key size, 32. 2062@end defvr 2063 2064@defvr Constant SALSA20_BLOCK_SIZE 2065Salsa20 block size, 64. 2066@end defvr 2067 2068@defvr Constant SALSA20_NONCE_SIZE 2069Size of the nonce, 8. 2070@end defvr 2071 2072@deftypefun void salsa20_128_set_key (struct salsa20_ctx *@var{ctx}, const uint8_t *@var{key}) 2073@deftypefunx void salsa20_256_set_key (struct salsa20_ctx *@var{ctx}, const uint8_t *@var{key}) 2074@deftypefunx void salsa20_set_key (struct salsa20_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{key}) 2075Initialize the cipher. The same function is used for both encryption and 2076decryption. @code{salsa20_128_set_key} and @code{salsa20_128_set_key} 2077use a fix key size each, 16 and 32 octets, respectively. The function 2078@code{salsa20_set_key} is provided for backwards compatibility, and the 2079@var{length} argument must be either 16 or 32. Before using the cipher, 2080you @emph{must} also call @code{salsa20_set_nonce}, see below. 2081@end deftypefun 2082 2083@deftypefun void salsa20_set_nonce (struct salsa20_ctx *@var{ctx}, const uint8_t *@var{nonce}) 2084Sets the nonce. It is always of size @code{SALSA20_NONCE_SIZE}, 8 2085octets. This function also initializes the block counter, setting it to 2086zero. 2087@end deftypefun 2088 2089@deftypefun void salsa20_crypt (struct salsa20_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2090Encrypts or decrypts the data of a message, using salsa20. When a 2091message is encrypted using a sequence of calls to @code{salsa20_crypt}, 2092all but the last call @emph{must} use a length that is a multiple of 2093@code{SALSA20_BLOCK_SIZE}. 2094@end deftypefun 2095 2096The full salsa20 cipher uses 20 rounds of mixing. Variants of Salsa20 2097with fewer rounds are possible, and the 12-round variant is specified by 2098eSTREAM, see @url{http://www.ecrypt.eu.org/stream/finallist.html}. 2099Nettle calls this variant @code{salsa20r12}. It uses the same context 2100struct and key setup as the full salsa20 cipher, but a separate function 2101for encryption and decryption. 2102 2103@deftypefun void salsa20r12_crypt (struct salsa20_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2104Encrypts or decrypts the data of a message, using salsa20 reduced to 12 2105rounds. 2106@end deftypefun 2107 2108@subsection SERPENT 2109@cindex Serpent 2110 2111SERPENT is one of the AES finalists, designed by Ross Anderson, Eli 2112Biham and Lars Knudsen. Thus, the interface and properties are similar 2113to AES'. One peculiarity is that it is quite pointless to use it with 2114anything but the maximum key size, smaller keys are just padded to 2115larger ones. Nettle defines SERPENT in @file{<nettle/serpent.h>}. 2116 2117@deftp {Context struct} {struct serpent_ctx} 2118@end deftp 2119 2120@defvr Constant SERPENT_BLOCK_SIZE 2121The SERPENT block-size, 16. 2122@end defvr 2123 2124@defvr Constant SERPENT_MIN_KEY_SIZE 2125Minimum SERPENT key size, 16. 2126@end defvr 2127 2128@defvr Constant SERPENT_MAX_KEY_SIZE 2129Maximum SERPENT key size, 32. 2130@end defvr 2131 2132@defvr Constant SERPENT_KEY_SIZE 2133Default SERPENT key size, 32. 2134@end defvr 2135 2136@deftypefun void serpent_set_key (struct serpent_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{key}) 2137Initialize the cipher. The same function is used for both encryption and 2138decryption. 2139@end deftypefun 2140 2141@deftypefun void serpent_encrypt (struct serpent_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2142Encryption function. @var{length} must be an integral multiple of the 2143block size. If it is more than one block, the data is processed in ECB 2144mode. @code{src} and @code{dst} may be equal, but they must not overlap 2145in any other way. 2146@end deftypefun 2147 2148@deftypefun void serpent_decrypt (struct serpent_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2149Analogous to @code{serpent_encrypt} 2150@end deftypefun 2151 2152 2153@subsection TWOFISH 2154@cindex Twofish 2155 2156Another AES finalist, this one designed by Bruce Schneier and others. 2157Nettle defines it in @file{<nettle/twofish.h>}. 2158 2159@deftp {Context struct} {struct twofish_ctx} 2160@end deftp 2161 2162@defvr Constant TWOFISH_BLOCK_SIZE 2163The TWOFISH block-size, 16. 2164@end defvr 2165 2166@defvr Constant TWOFISH_MIN_KEY_SIZE 2167Minimum TWOFISH key size, 16. 2168@end defvr 2169 2170@defvr Constant TWOFISH_MAX_KEY_SIZE 2171Maximum TWOFISH key size, 32. 2172@end defvr 2173 2174@defvr Constant TWOFISH_KEY_SIZE 2175Default TWOFISH key size, 32. 2176@end defvr 2177 2178@deftypefun void twofish_set_key (struct twofish_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{key}) 2179Initialize the cipher. The same function is used for both encryption and 2180decryption. 2181@end deftypefun 2182 2183@deftypefun void twofish_encrypt (struct twofish_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2184Encryption function. @var{length} must be an integral multiple of the 2185block size. If it is more than one block, the data is processed in ECB 2186mode. @code{src} and @code{dst} may be equal, but they must not overlap 2187in any other way. 2188@end deftypefun 2189 2190@deftypefun void twofish_decrypt (struct twofish_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2191Analogous to @code{twofish_encrypt} 2192@end deftypefun 2193 2194@c @node nettle_cipher abstraction, , Cipher functions, Cipher functions 2195@c @comment node-name, next, previous, up 2196@subsection The @code{struct nettle_cipher} abstraction 2197@cindex nettle_cipher 2198 2199Nettle includes a struct including information about some of the more 2200regular cipher functions. It can be useful for applications that need a 2201simple way to handle various algorithms. Nettle defines these structs in 2202@file{<nettle/nettle-meta.h>}. 2203 2204@deftp {Meta struct} @code{struct nettle_cipher} name context_size block_size key_size set_encrypt_key set_decrypt_key encrypt decrypt 2205The last four attributes are function pointers, of types 2206@code{nettle_set_key_func *} and @code{nettle_cipher_func *}. The first 2207argument to these functions is a @code{const void *} pointer to a context 2208struct, which is of size @code{context_size}. 2209@end deftp 2210 2211@deftypevr {Constant Struct} {struct nettle_cipher} nettle_aes128 2212@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_aes192 2213@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_aes256 2214 2215@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_arctwo40 2216@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_arctwo64 2217@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_arctwo128 2218@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_arctwo_gutmann128 2219 2220@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_arcfour128 2221 2222@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_camellia128 2223@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_camellia192 2224@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_camellia256 2225 2226@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_cast128 2227 2228@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_serpent128 2229@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_serpent192 2230@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_serpent256 2231 2232@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_twofish128 2233@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_twofish192 2234@deftypevrx {Constant Struct} {struct nettle_cipher} nettle_twofish256 2235Nettle includes such structs for all the @emph{regular} ciphers, i.e. 2236ones without weak keys or other oddities. 2237@end deftypevr 2238 2239Nettle also exports a list of all these ciphers without weak keys or 2240other oddities. 2241 2242@deftypefun {const struct nettle_cipher **} nettle_get_ciphers (void) 2243Returns a NULL-terminated list of pointers to supported block ciphers. 2244This list can be used to dynamically enumerate or search the supported 2245algorithms. 2246@end deftypefun 2247 2248@deffn Macro nettle_ciphers 2249A macro expanding to a call to nettle_get_ciphers. In earlier versions, 2250this was not a macro but the actual array of pointers. 2251@end deffn 2252 2253@node Cipher modes, Authenticated encryption, Cipher functions, Reference 2254@comment node-name, next, previous, up 2255@section Cipher modes 2256 2257Cipher modes of operation specifies the procedure to use when encrypting 2258a message that is larger than the cipher's block size. As explained in 2259@xref{Cipher functions}, splitting the message into blocks and 2260processing them independently with the block cipher (Electronic Code 2261Book mode, @acronym{ECB}), leaks information. 2262 2263Besides @acronym{ECB}, Nettle provides several other modes of operation: 2264Cipher Block Chaining (@acronym{CBC}), Counter mode (@acronym{CTR}), Cipher 2265Feedback (@acronym{CFB} and @acronym{CFB8}), XEX-based tweaked-codebook mode 2266with ciphertext stealing (@acronym{XTS}) and a couple of @acronym{AEAD} 2267modes (@pxref{Authenticated encryption}). @acronym{CBC} is widely used, but 2268there are a few subtle issues of information leakage, see, e.g., 2269@uref{http://www.kb.cert.org/vuls/id/958563, @acronym{SSH} @acronym{CBC} 2270vulnerability}. Today, @acronym{CTR} is usually preferred over @acronym{CBC}. 2271 2272Modes like @acronym{CBC}, @acronym{CTR}, @acronym{CFB} and @acronym{CFB8} 2273provide @emph{no} message authentication, and should always be used together 2274with a @acronym{MAC} (@pxref{Keyed hash functions}) or signature to 2275authenticate the message. 2276 2277@menu 2278* CBC:: 2279* CTR:: 2280* CFB and CFB8:: 2281* XTS:: 2282@end menu 2283 2284@node CBC, CTR, Cipher modes, Cipher modes 2285@comment node-name, next, previous, up 2286@subsection Cipher Block Chaining 2287 2288@cindex Cipher Block Chaining 2289@cindex CBC Mode 2290 2291When using @acronym{CBC} mode, plaintext blocks are not encrypted 2292independently of each other, like in Electronic Cook Book mode. Instead, 2293when encrypting a block in @acronym{CBC} mode, the previous ciphertext 2294block is XORed with the plaintext before it is fed to the block cipher. 2295When encrypting the first block, a random block called an @dfn{IV}, or 2296Initialization Vector, is used as the ``previous ciphertext block''. The 2297IV should be chosen randomly, but it need not be kept secret, and can 2298even be transmitted in the clear together with the encrypted data. 2299 2300In symbols, if @code{E_k} is the encryption function of a block cipher, 2301and @code{IV} is the initialization vector, then @code{n} plaintext blocks 2302@code{M_1},@dots{} @code{M_n} are transformed into @code{n} ciphertext blocks 2303@code{C_1},@dots{} @code{C_n} as follows: 2304 2305@example 2306C_1 = E_k(IV XOR M_1) 2307C_2 = E_k(C_1 XOR M_2) 2308 2309@dots{} 2310 2311C_n = E_k(C_(n-1) XOR M_n) 2312@end example 2313 2314Nettle's includes two functions for applying a block cipher in Cipher 2315Block Chaining (@acronym{CBC}) mode, one for encryption and one for 2316decryption. These functions uses @code{void *} to pass cipher contexts 2317around. 2318 2319@deftypefun {void} cbc_encrypt (const void *@var{ctx}, nettle_cipher_func *@var{f}, size_t @var{block_size}, uint8_t *@var{iv}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2320@deftypefunx {void} cbc_decrypt (const void *@var{ctx}, nettle_cipher_func *@var{f}, size_t @var{block_size}, uint8_t *@var{iv}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2321 2322Applies the encryption or decryption function @var{f} in @acronym{CBC} 2323mode. The final ciphertext block processed is copied into @var{iv} 2324before returning, so that a large message can be processed by a sequence of 2325calls to @code{cbc_encrypt}. The function @var{f} is of type 2326 2327@code{void f (void *@var{ctx}, size_t @var{length}, uint8_t @var{dst}, 2328const uint8_t *@var{src})}, 2329 2330@noindent and the @code{cbc_encrypt} and @code{cbc_decrypt} functions pass their 2331argument @var{ctx} on to @var{f}. 2332@end deftypefun 2333 2334There are also some macros to help use these functions correctly. 2335 2336@deffn Macro CBC_CTX (@var{context_type}, @var{block_size}) 2337Expands to 2338@example 2339@{ 2340 context_type ctx; 2341 uint8_t iv[block_size]; 2342@} 2343@end example 2344@end deffn 2345 2346It can be used to define a @acronym{CBC} context struct, either directly, 2347 2348@example 2349struct CBC_CTX(struct aes_ctx, AES_BLOCK_SIZE) ctx; 2350@end example 2351 2352or to give it a struct tag, 2353 2354@example 2355struct aes_cbc_ctx CBC_CTX (struct aes_ctx, AES_BLOCK_SIZE); 2356@end example 2357 2358@deffn Macro CBC_SET_IV (@var{ctx}, @var{iv}) 2359First argument is a pointer to a context struct as defined by @code{CBC_CTX}, 2360and the second is a pointer to an Initialization Vector (IV) that is 2361copied into that context. 2362@end deffn 2363 2364@deffn Macro CBC_ENCRYPT (@var{ctx}, @var{f}, @var{length}, @var{dst}, @var{src}) 2365@deffnx Macro CBC_DECRYPT (@var{ctx}, @var{f}, @var{length}, @var{dst}, @var{src}) 2366A simpler way to invoke @code{cbc_encrypt} and @code{cbc_decrypt}. The 2367first argument is a pointer to a context struct as defined by 2368@code{CBC_CTX}, and the second argument is an encryption or decryption 2369function following Nettle's conventions. The last three arguments define 2370the source and destination area for the operation. 2371@end deffn 2372 2373These macros use some tricks to make the compiler display a warning if 2374the types of @var{f} and @var{ctx} don't match, e.g. if you try to use 2375an @code{struct aes_ctx} context with the @code{des_encrypt} function. 2376 2377@node CTR, CFB and CFB8, CBC, Cipher modes 2378@comment node-name, next, previous, up 2379@subsection Counter mode 2380 2381@cindex Counter Mode 2382@cindex CTR Mode 2383 2384Counter mode (@acronym{CTR}) uses the block cipher as a keyed 2385pseudo-random generator. The output of the generator is XORed with the 2386data to be encrypted. It can be understood as a way to transform a block 2387cipher to a stream cipher. 2388 2389The message is divided into @code{n} blocks @code{M_1},@dots{} 2390@code{M_n}, where @code{M_n} is of size @code{m} which may be smaller 2391than the block size. Except for the last block, all the message blocks 2392must be of size equal to the cipher's block size. 2393 2394If @code{E_k} is the encryption function of a block cipher, @code{IC} is 2395the initial counter, then the @code{n} plaintext blocks are 2396transformed into @code{n} ciphertext blocks @code{C_1},@dots{} 2397@code{C_n} as follows: 2398 2399@example 2400C_1 = E_k(IC) XOR M_1 2401C_2 = E_k(IC + 1) XOR M_2 2402 2403@dots{} 2404 2405C_(n-1) = E_k(IC + n - 2) XOR M_(n-1) 2406C_n = E_k(IC + n - 1) [1..m] XOR M_n 2407@end example 2408 2409The @acronym{IC} is the initial value for the counter, it plays a 2410similar rôle as the @acronym{IV} for @acronym{CBC}. When adding, 2411@code{IC + x}, @acronym{IC} is interpreted as an integer, in network 2412byte order. For the last block, @code{E_k(IC + n - 1) [1..m]} means that 2413the cipher output is truncated to @code{m} bytes. 2414 2415@deftypefun {void} ctr_crypt (const void *@var{ctx}, nettle_cipher_func *@var{f}, size_t @var{block_size}, uint8_t *@var{ctr}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2416 2417Applies the encryption function @var{f} in @acronym{CTR} mode. Note that 2418for @acronym{CTR} mode, encryption and decryption is the same operation, 2419and hence @var{f} should always be the encryption function for the 2420underlying block cipher. 2421 2422When a message is encrypted using a sequence of calls to 2423@code{ctr_crypt}, all but the last call @emph{must} use a length that is 2424a multiple of the block size. 2425@end deftypefun 2426 2427Like for @acronym{CBC}, there are also a couple of helper macros. 2428 2429@deffn Macro CTR_CTX (@var{context_type}, @var{block_size}) 2430Expands to 2431@example 2432@{ 2433 context_type ctx; 2434 uint8_t ctr[block_size]; 2435@} 2436@end example 2437@end deffn 2438 2439@deffn Macro CTR_SET_COUNTER (@var{ctx}, @var{iv}) 2440First argument is a pointer to a context struct as defined by 2441@code{CTR_CTX}, and the second is a pointer to an initial counter that 2442is copied into that context. 2443@end deffn 2444 2445@deffn Macro CTR_CRYPT (@var{ctx}, @var{f}, @var{length}, @var{dst}, @var{src}) 2446A simpler way to invoke @code{ctr_crypt}. The first argument is a 2447pointer to a context struct as defined by @code{CTR_CTX}, and the second 2448argument is an encryption function following Nettle's conventions. The 2449last three arguments define the source and destination area for the 2450operation. 2451@end deffn 2452 2453@node CFB and CFB8, XTS, CTR, Cipher modes 2454@comment node-name, next, previous, up 2455@subsection Cipher Feedback mode 2456 2457@cindex Cipher Feedback Mode 2458@cindex Cipher Feedback 8-bit Mode 2459@cindex CFB Modes 2460@cindex CFB8 Mode 2461 2462 2463Cipher Feedback mode (@acronym{CFB}) and Cipher Feedback 8-bit mode 2464(@acronym{CFB8}) being close relatives to both @acronym{CBC} mode and 2465@acronym{CTR} mode borrow some characteristics from stream ciphers. 2466 2467For CFB the message is divided into @code{n} blocks @code{M_1},@dots{} 2468@code{M_n}, where @code{M_n} is of size @code{m} which may be smaller 2469than the block size. Except for the last block, all the message blocks 2470must be of size equal to the cipher's block size. 2471 2472If @code{E_k} is the encryption function of a block cipher, @code{IV} is 2473the initialization vector, then the @code{n} plaintext blocks are 2474transformed into @code{n} ciphertext blocks @code{C_1},@dots{} 2475@code{C_n} as follows: 2476 2477@example 2478C_1 = E_k(IV) XOR M_1 2479C_2 = E_k(C_1) XOR M_2 2480 2481@dots{} 2482 2483C_(n-1) = E_k(C_(n - 2)) XOR M_(n-1) 2484C_n = E_k(C_(n - 1)) [1..m] XOR M_n 2485@end example 2486 2487Cipher Feedback 8-bit mode (@acronym{CFB8}) transforms block cipher into a stream 2488cipher. The message is encrypted byte after byte, not requiring any padding. 2489 2490If @code{E_k} is the encryption function of a block cipher, @code{b} is 2491@code{E_k} block size, @code{IV} is the initialization vector, then the 2492@code{n} plaintext bytes are transformed into @code{n} ciphertext bytes 2493@code{C_1},@dots{} @code{C_n} as follows: 2494 2495@example 2496I_1 = IV 2497C_1 = E_k(I_1) [1..8] XOR M_1 2498I_2 = I_1 [9..b] << 8 | C_1 2499C_2 = E_k(I_2) [1..8] XOR M_2 2500 2501@dots{} 2502 2503I_(n-1) = I_(n-2) [9..b] << 8 | C_(n-2) 2504C_(n-1) = E_k(I_(n-1)) [1..8] XOR M_(n-1) 2505I_n = I_(n-1) [9..b] << 8 | C_(n-1) 2506C_n = E_k(I_n) [1..8] XOR M_n 2507@end example 2508 2509Nettle's includes functions for applying a block cipher in Cipher 2510Feedback (@acronym{CFB}) and Cipher Feedback 8-bit (@acronym{CFB8}) 2511modes. These functions uses @code{void *} to pass cipher contexts around. 2512 2513@deftypefun {void} cfb_encrypt (const void *@var{ctx}, nettle_cipher_func *@var{f}, size_t @var{block_size}, uint8_t *@var{iv}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2514@deftypefunx {void} cfb_decrypt (const void *@var{ctx}, nettle_cipher_func *@var{f}, size_t @var{block_size}, uint8_t *@var{iv}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2515 2516Applies the encryption or decryption function @var{f} in @acronym{CFB} 2517mode. The final ciphertext block processed is copied into @var{iv} 2518before returning, so that a large message can be processed by a sequence 2519of calls to @code{cfb_encrypt}. Note that for @acronym{CFB} mode 2520internally uses encryption only function and hence @var{f} should always 2521be the encryption function for the underlying block cipher. 2522 2523When a message is encrypted using a sequence of calls to 2524@code{cfb_encrypt}, all but the last call @emph{must} use a length that 2525is a multiple of the block size. 2526@end deftypefun 2527 2528@deftypefun {void} cfb8_encrypt (const void *@var{ctx}, nettle_cipher_func *@var{f}, size_t @var{block_size}, uint8_t *@var{iv}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2529@deftypefunx {void} cfb8_decrypt (const void *@var{ctx}, nettle_cipher_func *@var{f}, size_t @var{block_size}, uint8_t *@var{iv}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2530 2531Applies the encryption or decryption function @var{f} in @acronym{CFB8} 2532mode. The final IV block processed is copied into @var{iv} 2533before returning, so that a large message can be processed by a sequence of 2534calls to @code{cfb8_encrypt}. Note that for @acronym{CFB8} mode internally 2535uses encryption only function and hence @var{f} should always be the 2536encryption function for the underlying block cipher. 2537 2538@end deftypefun 2539 2540Like for @acronym{CBC}, there are also a couple of helper macros. 2541 2542@deffn Macro CFB_CTX (@var{context_type}, @var{block_size}) 2543Expands to 2544@example 2545@{ 2546 context_type ctx; 2547 uint8_t iv[block_size]; 2548@} 2549@end example 2550@end deffn 2551 2552@deffn Macro CFB_SET_IV(@var{ctx}, @var{iv}) 2553First argument is a pointer to a context struct as defined by 2554@code{CFB_CTX}, and the second is a pointer to an initialization vector 2555that is copied into that context. 2556@end deffn 2557 2558@deffn Macro CFB_ENCRYPT (@var{ctx}, @var{f}, @var{length}, @var{dst}, @var{src}) 2559A simpler way to invoke @code{cfb_encrypt}. The first argument is a 2560pointer to a context struct as defined by @code{CFB_CTX}, and the second 2561argument is an encryption function following Nettle's conventions. The 2562last three arguments define the source and destination area for the 2563operation. 2564@end deffn 2565 2566@deffn Macro CFB_DECRYPT (@var{ctx}, @var{f}, @var{length}, @var{dst}, @var{src}) 2567A simpler way to invoke @code{cfb_decrypt}. The first argument is a 2568pointer to a context struct as defined by @code{CFB_CTX}, and the second 2569argument is an encryption function following Nettle's conventions. The 2570last three arguments define the source and destination area for the 2571operation. 2572@end deffn 2573 2574@deffn Macro CFB8_CTX (@var{context_type}, @var{block_size}) 2575Expands to 2576@example 2577@{ 2578 context_type ctx; 2579 uint8_t iv[block_size]; 2580@} 2581@end example 2582@end deffn 2583 2584@deffn Macro CFB8_SET_IV (@var{ctx}, @var{iv}) 2585First argument is a pointer to a context struct as defined by 2586@code{CFB8_CTX}, and the second is a pointer to an initialization vector 2587that is copied into that context. 2588@end deffn 2589 2590@deffn Macro CFB8_ENCRYPT (@var{ctx}, @var{f}, @var{length}, @var{dst}, @var{src}) 2591A simpler way to invoke @code{cfb8_encrypt}. The first argument is a 2592pointer to a context struct as defined by @code{CFB8_CTX}, and the 2593second argument is an encryption function following Nettle's 2594conventions. The last three arguments define the source and destination 2595area for the operation. 2596@end deffn 2597 2598@deffn Macro CFB8_DECRYPT (@var{ctx}, @var{f}, @var{length}, @var{dst}, @var{src}) 2599A simpler way to invoke @code{cfb8_decrypt}. The first argument is a 2600pointer to a context struct as defined by @code{CFB8_CTX}, and the 2601second argument is an encryption function following Nettle's 2602conventions. The last three arguments define the source and destination 2603area for the operation. 2604@end deffn 2605 2606@node XTS, , CFB and CFB8, Cipher modes 2607@comment node-name, next, previous, up 2608@subsection XEX-based tweaked-codebook mode with ciphertext stealing 2609 2610@cindex XEX-based tweaked-codebook mode with ciphertext stealing 2611@cindex XTS Mode 2612 2613 2614XEX-based tweaked-codebook mode with ciphertext stealing (@acronym{XTS}) is 2615a block mode like (@acronym{CBC}) but tweaked to be able to encrypt partial 2616blocks via a technique called ciphertext stealing, where the last complete 2617block of ciphertext is split and part returned as the last block and part 2618used as plaintext for the second to last block. 2619This mode is principally used to encrypt data at rest where it is not possible 2620to store additional metadata or blocks larger than the plain text. The most 2621common usage is for disk encryption. Due to the fact that ciphertext expansion 2622is not possible, data is not authenticated. This mode should not be used where 2623authentication is critical. 2624 2625The message is divided into @code{n} blocks @code{M_1},@dots{} @code{M_n}, 2626where @code{M_n} is of size @code{m} which may be smaller than the block size. 2627XTS always uses a fixed blocksize of 128 bit (16 bytes) length. 2628 2629Unlike other modes, the key is double the size of that for the used cipher mode 2630(for example 256bit for AES-128 and 512bit for AES-256). 2631 2632@acronym{XTS} encryption mode operates given: 2633@itemize 2634@item A multiplication by a primitive element alpha. 2635@code{MUL a^j} here represents the multiplication, where @code{j} is the power 2636of alpha, and the input value is converted into a 16 bytes array 2637@code{a_0[k], k = 0,1,..,15}. The multiplication is calculated as 2638@code{a_(j+1)[0] = (2(a_j[0] mod 128)) XOR (135 * floor(a_j[15]/128)} 2639@code{a_(j+1)[k] = (2(a_j[k] mod 128)) XOR (floor(a_j[k-1]/128), k = 1,2,..15} 2640Note that this operation is practically a 1 bit left shift operation with carry 2641propagating from one byte to the next, and if the last bit shift results in a 2642carry the decimal value 135 is XORed into the first byte. 2643 2644@item The encryption key is provided as the @code{Key = K1 | K2}, where @code{|} 2645denotes string concatenation. 2646@code{E_k1} is the encryption function of the block cipher using @code{K1} as 2647the key, and @code{E_k2} is the same encryption function using @code{K2} 2648 2649@item A 128 bit tweak value is provided as input and is denoted as @code{IV} 2650@end itemize 2651 2652The @code{n} plaintext blocks are transformed into @code{n} ciphertext blocks 2653@code{C_1},@dots{} @code{C_n} as follows. 2654 2655For a plaintext length that is a perfect multiple of the XTS block size: 2656@example 2657T_1 = E_k2(IV) 2658C_1 = E_k1(P_1 XOR T_1) XOR T_1 2659 2660@dots{} 2661 2662T_n = T_(n-1) MUL a 2663C_n = E_k1(P_n XOR T_n) XOR T_n 2664@end example 2665 2666For any other plaintext lengths: 2667@example 2668T_1 = E_k2(IV) 2669C_1 = E_k1(P_1 XOR T_1) XOR T_1 2670 2671@dots{} 2672 2673T_(n-2) = T_(n-3) MUL a 2674C_(n-2) = E_k1(P_(n-2) XOR T_(n-2)) XOR T_(n-2) 2675 2676T_(n-1) = T_(n-2) MUL a 2677CC_(n-1) = E_k1(P_(n-1) XOR T_(n-1)) XOR T_(n-1) 2678 2679T_n = T_(n-1) MUL a 2680PP = [1..m]Pn | [m+1..128]CC_(n-1) 2681C_(n-1) = E_k1(PP XOR T_n) XOR T_n 2682 2683C_n = [1..m]CC_(n-1) 2684@end example 2685 2686@subsubsection General (@acronym{XTS}) interface. 2687 2688The two general functions to encrypt and decrypt using the @acronym{XTS} block 2689cipher mode are the following: 2690 2691@deftypefun void xts_encrypt_message (const void *@var{enc_ctx}, const void *@var{twk_ctx}, nettle_cipher_func *@var{encf}, const uint8_t *@var{tweak}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2692@deftypefunx void xts_decrypt_message (const void *@var{dec_ctx}, const void *@var{twk_ctx}, nettle_cipher_func *@var{decf}, nettle_cipher_func *@var{encf}, const uint8_t *@var{tweak}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2693 2694Applies the encryption function @var{encf} or the decryption function 2695@var{decf} in @acronym{XTS} mode. At least one block (16 bytes) worth 2696of data must be available therefore specifying a length less than 16 2697bytes is illegal. 2698 2699The functions @var{encf} @var{decf} are of type 2700 2701@code{void f (const void *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, 2702const uint8_t *@var{src})}, 2703 2704@noindent and the @code{xts_encrypt_message} and @code{xts_decrypt_message} 2705functions pass their arguments @var{enc_ctx}, @var{twk_ctx} and @var{dec_ctx} 2706to the functions @var{encf}, @var{decf} as @var{ctx}. 2707@end deftypefun 2708 2709@subsubsection @acronym{XTS}-@acronym{AES} interface 2710 2711The @acronym{AES} @acronym{XTS} functions provide an API for using the 2712@acronym{XTS} mode with the @acronym{AES} block ciphers. The parameters 2713all have the same meaning as the general interface, except that the 2714@var{enc_ctx}, @var{dec_ctx}, @var{twk_ctx}, @var{encf} and @var{decf} are 2715replaced with an @acronym{AES} context structure called @var{ctx}, and a 2716appropriate set-key function must be called before using any of the encryption 2717or decryption functions in this interface. 2718 2719@deftp {Context struct} {struct xts_aes128_key} 2720Holds state corresponding to the AES-128 block cipher. 2721@end deftp 2722 2723@deftp {Context struct} {struct xts_aes256_key} 2724Holds state corresponding to the AES-256 block cipher. 2725@end deftp 2726 2727@deftypefun void xts_aes128_set_encrypt_key (struct xts_aes128_key *@var{ctx}, const uint8_t *@var{key}) 2728@deftypefunx void xts_aes256_set_encrypt_key (struct xts_aes256_key *@var{ctx}, const uint8_t *@var{key}) 2729@deftypefunx void xts_aes128_set_decrypt_key (struct xts_aes128_key *@var{ctx}, const uint8_t *@var{key}) 2730@deftypefunx void xts_aes256_set_decrypt_key (struct xts_aes256_key *@var{ctx}, const uint8_t *@var{key}) 2731Initializes the encryption or decryption key for the AES block cipher. The 2732length of the key must be double the size of the key for the corresponding 2733cipher (256 bits for AES-128 and 512 bits for AES-256). One of 2734these functions must be called before any of the other functions. 2735@end deftypefun 2736 2737@deftypefun void xts_aes128_encrypt_message(struct xts_aes128_key *@var{ctx}, uint8_t *@var{tweak}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2738@deftypefunx void xts_aes256_encrypt_message(struct xts_aes256_key *@var{ctx}, uint8_t *@var{tweak}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2739@deftypefunx void xts_aes128_decrypt_message(struct xts_aes128_key *@var{ctx}, uint8_t *@var{tweak}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2740@deftypefunx void xts_aes256_decrypt_message(struct xts_aes256_key *@var{ctx}, uint8_t *@var{tweak}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2741These are identical to @code{xts_encrypt_message} and 2742@code{xts_decrypt_message}, except that @var{enc_ctx}, @var{dec_ctx}, 2743@var{twk_ctx}, @var{encf} and @var{decf} are replaced by the @var{ctx} context 2744structure. 2745@end deftypefun 2746 2747@node Authenticated encryption, Keyed hash functions, Cipher modes, Reference 2748@comment node-name, next, previous, up 2749 2750@section Authenticated encryption with associated data 2751@cindex AEAD 2752@cindex Authenticated encryption 2753 2754Since there are some subtle design choices to be made when combining a 2755block cipher mode with out authentication with a @acronym{MAC}. In 2756recent years, several constructions that combine encryption and 2757authentication have been defined. These constructions typically also 2758have an additional input, the ``associated data'', which is 2759authenticated but not included with the message. A simple example is an 2760implicit message number which is available at both sender and receiver, 2761and which needs authentication in order to detect deletions or replay of 2762messages. This family of building blocks are therefore called 2763@acronym{AEAD}, Authenticated encryption with associated data. 2764 2765The aim is to provide building blocks that it is easier for designers of 2766protocols and applications to use correctly. There is also some 2767potential for improved performance, if encryption and authentication can 2768be done in a single step, although that potential is not realized for 2769the constructions currently supported by Nettle. 2770 2771For encryption, the inputs are: 2772 2773@itemize 2774@item 2775The key, which can be used for many messages. 2776@item 2777A nonce, which must be unique for each message using the same key. 2778@item 2779Additional associated data to be authenticated, but not included in the 2780message. 2781@item 2782The cleartext message to be encrypted. 2783@end itemize 2784 2785The outputs are: 2786 2787@itemize 2788@item 2789The ciphertext, of the same size as the cleartext. 2790@item 2791A digest or ``authentication tag''. 2792@end itemize 2793 2794Decryption works the same, but with cleartext and ciphertext 2795interchanged. All currently supported @acronym{AEAD} algorithms always 2796use the encryption function of the underlying block cipher, for both 2797encryption and decryption. 2798 2799Usually, the authentication tag should be appended at the end of the 2800ciphertext, producing an encrypted message which is slightly longer than 2801the cleartext. However, Nettle's low level @acronym{AEAD} functions 2802produce the authentication tag as a separate output for both encryption 2803and decryption. 2804 2805Both associated data and the message data (cleartext or ciphertext) can 2806be processed incrementally. In general, all associated data must be 2807processed before the message data, and all calls but the last one must 2808use a length that is a multiple of the block size, although some 2809@acronym{AEAD} may implement more liberal conventions. The @acronym{CCM} 2810mode is a bit special in that it requires the message lengths up front, 2811other @acronym{AEAD} constructions don't have this restriction. 2812 2813The supported @acronym{AEAD} constructions are Galois/Counter mode 2814(@acronym{GCM}), @acronym{EAX}, ChaCha-Poly1305, and Counter with 2815@acronym{CBC}-@acronym{MAC} (@acronym{CCM}). There are some weaknesses 2816in @acronym{GCM} authentication, see 2817@uref{http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/comments/CWC-GCM/Ferguson2.pdf}. 2818@acronym{CCM} and @acronym{EAX} use the same building blocks, but the 2819@acronym{EAX} design is cleaner and avoids a couple of inconveniences of 2820@acronym{CCM}. Therefore, @acronym{EAX} seems like a good conservative 2821choice. The more recent ChaCha-Poly1305 may also be an attractive but 2822more adventurous alternative, in particular if performance is important. 2823 2824@menu 2825* EAX:: 2826* GCM:: 2827* CCM:: 2828* ChaCha-Poly1305:: 2829* SIV-CMAC:: 2830* nettle_aead abstraction:: 2831@end menu 2832 2833@node EAX, GCM, Authenticated encryption, Authenticated encryption 2834@comment node-name, next, previous, up 2835@subsection EAX 2836 2837The @acronym{EAX} mode is an @acronym{AEAD} mode which combines 2838@acronym{CTR} mode encryption, @xref{CTR}, with a message authentication 2839based on @acronym{CBC}, @xref{CBC}. The implementation in Nettle is 2840restricted to ciphers with a block size of 128 bits (16 octets). 2841@acronym{EAX} was defined as a reaction to the @acronym{CCM} mode, 2842@xref{CCM}, which uses the same primitives but has some undesirable and 2843inelegant properties. 2844 2845@acronym{EAX} supports arbitrary nonce size; it's even possible to use 2846an empty nonce in case only a single message is encrypted for each key. 2847 2848Nettle's support for @acronym{EAX} consists of a low-level general 2849interface, some convenience macros, and specific functions for 2850@acronym{EAX} using @acronym{AES}-128 as the underlying cipher. These 2851interfaces are defined in @file{<nettle/eax.h>} 2852 2853@subsubsection General @acronym{EAX} interface 2854 2855@deftp {Context struct} {struct eax_key} 2856@acronym{EAX} state which depends only on the key, but not on the nonce 2857or the message. 2858@end deftp 2859 2860@deftp {Context struct} {struct eax_ctx} 2861Holds state corresponding to a particular message. 2862@end deftp 2863 2864@defvr Constant EAX_BLOCK_SIZE 2865@acronym{EAX}'s block size, 16. 2866@end defvr 2867 2868@defvr Constant EAX_DIGEST_SIZE 2869Size of the @acronym{EAX} digest, also 16. 2870@end defvr 2871 2872@deftypefun void eax_set_key (struct eax_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}) 2873Initializes @var{key}. @var{cipher} gives a context struct for the 2874underlying cipher, which must have been previously initialized for 2875encryption, and @var{f} is the encryption function. 2876@end deftypefun 2877 2878@deftypefun void eax_set_nonce (struct eax_ctx *@var{eax}, const struct eax_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{nonce_length}, const uint8_t *@var{nonce}) 2879Initializes @var{ctx} for processing a new message, using the given 2880nonce. 2881@end deftypefun 2882 2883@deftypefun void eax_update (struct eax_ctx *@var{eax}, const struct eax_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{data_length}, const uint8_t *@var{data}) 2884Process associated data for authentication. All but the last call for 2885each message @emph{must} use a length that is a multiple of the block 2886size. Unlike many other @acronym{AEAD} constructions, for @acronym{EAX} 2887it's not necessary to complete the processing of all associated data 2888before encrypting or decrypting the message data. 2889@end deftypefun 2890 2891@deftypefun void eax_encrypt (struct eax_ctx *@var{eax}, const struct eax_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2892@deftypefunx void eax_decrypt (struct eax_ctx *@var{eax}, const struct eax_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2893Encrypts or decrypts the data of a message. @var{cipher} is the context 2894struct for the underlying cipher and @var{f} is the encryption function. 2895All but the last call for each message @emph{must} use a length that is 2896a multiple of the block size. 2897@end deftypefun 2898 2899@deftypefun void eax_digest (struct eax_ctx *@var{eax}, const struct eax_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{digest}); 2900Extracts the message digest (also known ``authentication tag''). This is 2901the final operation when processing a message. If @var{length} is 2902smaller than @code{EAX_DIGEST_SIZE}, only the first @var{length} octets 2903of the digest are written. 2904@end deftypefun 2905 2906 2907@subsubsection @acronym{EAX} helper macros 2908 2909The following macros are defined. 2910 2911@deffn Macro EAX_CTX (@var{context_type}) 2912This defines an all-in-one context struct, including the context of the 2913underlying cipher and all @acronym{EAX} state. It expands 2914to 2915@example 2916@{ 2917 struct eax_key key; 2918 struct eax_ctx eax; 2919 context_type cipher; 2920@} 2921@end example 2922@end deffn 2923 2924For all these macros, @var{ctx}, is a context struct as defined by 2925@code{EAX_CTX}, and @var{encrypt} is the encryption function of the 2926underlying cipher. 2927 2928@deffn Macro EAX_SET_KEY (@var{ctx}, @var{set_key}, @var{encrypt}, @var{key}) 2929@var{set_key} is the function for setting the encryption key for the 2930underlying cipher, and @var{key} is the key. 2931@end deffn 2932 2933@deffn Macro EAX_SET_NONCE (@var{ctx}, @var{encrypt}, @var{length}, @var{nonce}) 2934Sets the nonce to be used for the message. 2935@end deffn 2936 2937@deffn Macro EAX_UPDATE (@var{ctx}, @var{encrypt}, @var{length}, @var{data}) 2938Process associated data for authentication. 2939@end deffn 2940 2941@deffn Macro EAX_ENCRYPT (@var{ctx}, @var{encrypt}, @var{length}, @var{dst}, @var{src}) 2942@deffnx Macro EAX_DECRYPT (@var{ctx}, @var{encrypt}, @var{length}, @var{dst}, @var{src}) 2943Process message data for encryption or decryption. 2944@end deffn 2945 2946@deffn Macro EAX_DIGEST (@var{ctx}, @var{encrypt}, @var{length}, @var{digest}) 2947Extract the authentication tag for the message. 2948@end deffn 2949 2950 2951@subsubsection @acronym{EAX}-@acronym{AES}128 interface 2952 2953The following functions implement @acronym{EAX} using @acronym{AES}-128 2954as the underlying cipher. 2955 2956@deftp {Context struct} {struct eax_aes128_ctx} 2957The context struct, defined using @code{EAX_CTX}. 2958@end deftp 2959 2960@deftypefun void eax_aes128_set_key (struct eax_aes128_ctx *@var{ctx}, const uint8_t *@var{key}) 2961Initializes @var{ctx} using the given key. 2962@end deftypefun 2963 2964@deftypefun void eax_aes128_set_nonce (struct eax_aes128_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{iv}) 2965Initializes the per-message state, using the given nonce. 2966@end deftypefun 2967 2968@deftypefun void eax_aes128_update (struct eax_aes128_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 2969Process associated data for authentication. All but the last call for 2970each message @emph{must} use a length that is a multiple of the block 2971size. 2972@end deftypefun 2973 2974@deftypefun void eax_aes128_encrypt (struct eax_aes128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2975@deftypefunx void eax_aes128_decrypt (struct eax_aes128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 2976Encrypts or decrypts the data of a message. All but the last call for 2977each message @emph{must} use a length that is a multiple of the block 2978size. 2979@end deftypefun 2980 2981@deftypefun void eax_aes128_digest (struct eax_aes128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}); 2982Extracts the message digest (also known ``authentication tag''). This is 2983the final operation when processing a message. If @var{length} is 2984smaller than @code{EAX_DIGEST_SIZE}, only the first @var{length} octets 2985of the digest are written. 2986@end deftypefun 2987 2988@node GCM, CCM, EAX, Authenticated encryption 2989@comment node-name, next, previous, up 2990@subsection Galois counter mode 2991 2992@cindex Galois Counter Mode 2993@cindex GCM 2994 2995Galois counter mode is an @acronym{AEAD} constructions combining counter 2996mode with message authentication based on universal hashing. The main 2997objective of the design is to provide high performance for hardware 2998implementations, where other popular @acronym{MAC} algorithms 2999(@pxref{Keyed hash functions}) become a bottleneck for high-speed 3000hardware implementations. It was proposed by David A. McGrew and John 3001Viega in 2005, and recommended by NIST in 2007, 3002@uref{http://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf, 3003NIST Special Publication 800-38D}. It is constructed on top of a block 3004cipher which must have a block size of 128 bits. 3005 3006The authentication in @acronym{GCM} has some known weaknesses, see 3007@uref{http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/comments/CWC-GCM/Ferguson2.pdf}. 3008In particular, don't use @acronym{GCM} with short authentication tags. 3009 3010Nettle's support for @acronym{GCM} consists of a low-level general 3011interface, some convenience macros, and specific functions for 3012@acronym{GCM} using @acronym{AES} or Camellia as the underlying cipher. 3013These interfaces are defined in @file{<nettle/gcm.h>} 3014 3015@subsubsection General @acronym{GCM} interface 3016 3017@deftp {Context struct} {struct gcm_key} 3018Message independent hash sub-key, and related tables. 3019@end deftp 3020 3021@deftp {Context struct} {struct gcm_ctx} 3022Holds state corresponding to a particular message. 3023@end deftp 3024 3025@defvr Constant GCM_BLOCK_SIZE 3026@acronym{GCM}'s block size, 16. 3027@end defvr 3028 3029@defvr Constant GCM_DIGEST_SIZE 3030Size of the @acronym{GCM} digest, also 16. 3031@end defvr 3032 3033@defvr Constant GCM_IV_SIZE 3034Recommended size of the @acronym{IV}, 12. Arbitrary sizes are allowed. 3035@end defvr 3036 3037@deftypefun void gcm_set_key (struct gcm_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}) 3038Initializes @var{key}. @var{cipher} gives a context struct for the 3039underlying cipher, which must have been previously initialized for 3040encryption, and @var{f} is the encryption function. 3041@end deftypefun 3042 3043@deftypefun void gcm_set_iv (struct gcm_ctx *@var{ctx}, const struct gcm_key *@var{key}, size_t @var{length}, const uint8_t *@var{iv}) 3044Initializes @var{ctx} using the given @acronym{IV}. The @var{key} 3045argument is actually needed only if @var{length} differs from 3046@code{GCM_IV_SIZE}. 3047@end deftypefun 3048 3049@deftypefun void gcm_update (struct gcm_ctx *@var{ctx}, const struct gcm_key *@var{key}, size_t @var{length}, const uint8_t *@var{data}) 3050Provides associated data to be authenticated. If used, must be called 3051before @code{gcm_encrypt} or @code{gcm_decrypt}. All but the last call 3052for each message @emph{must} use a length that is a multiple of the 3053block size. 3054@end deftypefun 3055 3056@deftypefun void gcm_encrypt (struct gcm_ctx *@var{ctx}, const struct gcm_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3057@deftypefunx void gcm_decrypt (struct gcm_ctx *@var{ctx}, const struct gcm_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3058Encrypts or decrypts the data of a message. @var{cipher} is the context 3059struct for the underlying cipher and @var{f} is the encryption function. 3060All but the last call for each message @emph{must} use a length that is 3061a multiple of the block size. 3062@end deftypefun 3063 3064@deftypefun void gcm_digest (struct gcm_ctx *@var{ctx}, const struct gcm_key *@var{key}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{digest}) 3065Extracts the message digest (also known ``authentication tag''). This is 3066the final operation when processing a message. It's strongly recommended 3067that @var{length} is @code{GCM_DIGEST_SIZE}, but if you provide a smaller 3068value, only the first @var{length} octets of the digest are written. 3069@end deftypefun 3070 3071To encrypt a message using @acronym{GCM}, first initialize a context for 3072the underlying block cipher with a key to use for encryption. Then call 3073the above functions in the following order: @code{gcm_set_key}, 3074@code{gcm_set_iv}, @code{gcm_update}, @code{gcm_encrypt}, 3075@code{gcm_digest}. The decryption procedure is analogous, just calling 3076@code{gcm_decrypt} instead of @code{gcm_encrypt} (note that 3077@acronym{GCM} decryption still uses the encryption function of the 3078underlying block cipher). To process a new message, using the same key, 3079call @code{gcm_set_iv} with a new @acronym{iv}. 3080 3081@subsubsection @acronym{GCM} helper macros 3082 3083The following macros are defined. 3084 3085@deffn Macro GCM_CTX (@var{context_type}) 3086This defines an all-in-one context struct, including the context of the 3087underlying cipher, the hash sub-key, and the per-message state. It expands 3088to 3089@example 3090@{ 3091 struct gcm_key key; 3092 struct gcm_ctx gcm; 3093 context_type cipher; 3094@} 3095@end example 3096@end deffn 3097 3098Example use: 3099@example 3100struct gcm_aes128_ctx GCM_CTX(struct aes128_ctx); 3101@end example 3102 3103The following macros operate on context structs of this form. 3104 3105@deffn Macro GCM_SET_KEY (@var{ctx}, @var{set_key}, @var{encrypt}, @var{key}) 3106First argument, @var{ctx}, is a context struct as defined 3107by @code{GCM_CTX}. @var{set_key} and @var{encrypt} are functions for 3108setting the encryption key and for encrypting data using the underlying 3109cipher. 3110@end deffn 3111 3112@deffn Macro GCM_SET_IV (@var{ctx}, @var{length}, @var{data}) 3113First argument is a context struct as defined by 3114@code{GCM_CTX}. @var{length} and @var{data} give the initialization 3115vector (@acronym{IV}). 3116@end deffn 3117 3118@deffn Macro GCM_UPDATE (@var{ctx}, @var{length}, @var{data}) 3119Simpler way to call @code{gcm_update}. First argument is a context 3120struct as defined by @code{GCM_CTX} 3121@end deffn 3122 3123@deffn Macro GCM_ENCRYPT (@var{ctx}, @var{encrypt}, @var{length}, @var{dst}, @var{src}) 3124@deffnx Macro GCM_DECRYPT (@var{ctx}, @var{encrypt}, @var{length}, @var{dst}, @var{src}) 3125@deffnx Macro GCM_DIGEST (@var{ctx}, @var{encrypt}, @var{length}, @var{digest}) 3126Simpler way to call @code{gcm_encrypt}, @code{gcm_decrypt} or 3127@code{gcm_digest}. First argument is a context struct as defined by 3128@code{GCM_CTX}. Second argument, @var{encrypt}, is the encryption 3129function of the underlying cipher. 3130@end deffn 3131 3132@subsubsection @acronym{GCM}-@acronym{AES} interface 3133 3134The following functions implement the common case of @acronym{GCM} using 3135@acronym{AES} as the underlying cipher. The variants with a specific 3136@acronym{AES} flavor are recommended, while the fucntinos using 3137@code{struct gcm_aes_ctx} are kept for compatibility with older versiosn 3138of Nettle. 3139 3140@deftp {Context struct} {struct gcm_aes128_ctx} 3141@deftpx {Context struct} {struct gcm_aes192_ctx} 3142@deftpx {Context struct} {struct gcm_aes256_ctx} 3143Context structs, defined using @code{GCM_CTX}. 3144@end deftp 3145 3146@deftp {Context struct} {struct gcm_aes_ctx} 3147Alternative context struct, using the old @acronym{AES} interface. 3148@end deftp 3149 3150@deftypefun void gcm_aes128_set_key (struct gcm_aes128_ctx *@var{ctx}, const uint8_t *@var{key}) 3151@deftypefunx void gcm_aes192_set_key (struct gcm_aes192_ctx *@var{ctx}, const uint8_t *@var{key}) 3152@deftypefunx void gcm_aes256_set_key (struct gcm_aes256_ctx *@var{ctx}, const uint8_t *@var{key}) 3153Initializes @var{ctx} using the given key. 3154@end deftypefun 3155 3156@deftypefun void gcm_aes_set_key (struct gcm_aes_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{key}) 3157Corresponding function, using the old @acronym{AES} interface. All valid 3158@acronym{AES} key sizes can be used. 3159@end deftypefun 3160 3161@deftypefun void gcm_aes128_set_iv (struct gcm_aes128_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{iv}) 3162@deftypefunx void gcm_aes192_set_iv (struct gcm_aes192_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{iv}) 3163@deftypefunx void gcm_aes256_set_iv (struct gcm_aes256_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{iv}) 3164@deftypefunx void gcm_aes_set_iv (struct gcm_aes_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{iv}) 3165Initializes the per-message state, using the given @acronym{IV}. 3166@end deftypefun 3167 3168@deftypefun void gcm_aes128_update (struct gcm_aes128_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 3169@deftypefunx void gcm_aes192_update (struct gcm_aes192_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 3170@deftypefunx void gcm_aes256_update (struct gcm_aes256_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 3171@deftypefunx void gcm_aes_update (struct gcm_aes_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 3172Provides associated data to be authenticated. If used, must be called 3173before @code{gcm_aes_encrypt} or @code{gcm_aes_decrypt}. All but the 3174last call for each message @emph{must} use a length that is a multiple 3175of the block size. 3176@end deftypefun 3177 3178@deftypefun void gcm_aes128_encrypt (struct gcm_aes128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3179@deftypefunx void gcm_aes192_encrypt (struct gcm_aes192_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3180@deftypefunx void gcm_aes256_encrypt (struct gcm_aes256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3181@deftypefunx void gcm_aes_encrypt (struct gcm_aes_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3182@deftypefunx void gcm_aes128_decrypt (struct gcm_aes128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3183@deftypefunx void gcm_aes192_decrypt (struct gcm_aes192_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3184@deftypefunx void gcm_aes256_decrypt (struct gcm_aes256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3185@deftypefunx void gcm_aes_decrypt (struct gcm_aes_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3186Encrypts or decrypts the data of a message. All but the last call for 3187each message @emph{must} use a length that is a multiple of the block 3188size. 3189@end deftypefun 3190 3191@deftypefun void gcm_aes128_digest (struct gcm_aes128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 3192@deftypefunx void gcm_aes192_digest (struct gcm_aes192_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 3193@deftypefunx void gcm_aes256_digest (struct gcm_aes256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 3194@deftypefunx void gcm_aes_digest (struct gcm_aes_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 3195Extracts the message digest (also known ``authentication tag''). This is 3196the final operation when processing a message. It's strongly recommended 3197that @var{length} is @code{GCM_DIGEST_SIZE}, but if you provide a smaller 3198value, only the first @var{length} octets of the digest are written. 3199@end deftypefun 3200 3201@subsubsection @acronym{GCM}-Camellia interface 3202 3203The following functions implement the case of @acronym{GCM} using 3204Camellia as the underlying cipher. 3205 3206@deftp {Context struct} {struct gcm_camellia128_ctx} 3207@deftpx {Context struct} {struct gcm_camellia256_ctx} 3208Context structs, defined using @code{GCM_CTX}. 3209@end deftp 3210 3211@deftypefun void gcm_camellia128_set_key (struct gcm_camellia128_ctx *@var{ctx}, const uint8_t *@var{key}) 3212@deftypefunx void gcm_camellia256_set_key (struct gcm_camellia256_ctx *@var{ctx}, const uint8_t *@var{key}) 3213Initializes @var{ctx} using the given key. 3214@end deftypefun 3215 3216@deftypefun void gcm_camellia128_set_iv (struct gcm_camellia128_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{iv}) 3217@deftypefunx void gcm_camellia256_set_iv (struct gcm_camellia256_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{iv}) 3218Initializes the per-message state, using the given @acronym{IV}. 3219@end deftypefun 3220 3221@deftypefun void gcm_camellia128_update (struct gcm_camellia128_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 3222@deftypefunx void gcm_camellia256_update (struct gcm_camellia256_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 3223Provides associated data to be authenticated. If used, must be called 3224before @code{gcm_camellia_encrypt} or @code{gcm_camellia_decrypt}. All but the 3225last call for each message @emph{must} use a length that is a multiple 3226of the block size. 3227@end deftypefun 3228 3229@deftypefun void gcm_camellia128_encrypt (struct gcm_camellia128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3230@deftypefunx void gcm_camellia256_encrypt (struct gcm_camellia256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3231@deftypefunx void gcm_camellia128_decrypt (struct gcm_camellia128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3232@deftypefunx void gcm_camellia256_decrypt (struct gcm_camellia256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3233Encrypts or decrypts the data of a message. All but the last call for 3234each message @emph{must} use a length that is a multiple of the block 3235size. 3236@end deftypefun 3237 3238@deftypefun void gcm_camellia128_digest (struct gcm_camellia128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 3239@deftypefunx void gcm_camellia192_digest (struct gcm_camellia192_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 3240@deftypefunx void gcm_camellia256_digest (struct gcm_camellia256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 3241@deftypefunx void gcm_camellia_digest (struct gcm_camellia_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 3242Extracts the message digest (also known ``authentication tag''). This is 3243the final operation when processing a message. It's strongly recommended 3244that @var{length} is @code{GCM_DIGEST_SIZE}, but if you provide a smaller 3245value, only the first @var{length} octets of the digest are written. 3246@end deftypefun 3247 3248@node CCM, ChaCha-Poly1305, GCM, Authenticated encryption 3249@comment node-name, next, previous, up 3250@subsection Counter with CBC-MAC mode 3251 3252@cindex Counter with CBC-MAC Mode 3253@cindex CCM Mode 3254 3255@acronym{CCM} mode is a combination of counter mode with message 3256authentication based on cipher block chaining, the same building blocks 3257as @acronym{EAX}, @pxref{EAX}. It is constructed on top of a block cipher 3258which must have a block size of 128 bits. @acronym{CCM} mode is 3259recommended by NIST in 3260@uref{http://csrc.nist.gov/publications/nistpubs/800-38C/SP800-38C_updated-July20_2007.pdf, 3261NIST Special Publication 800-38C}. Nettle's support for CCM consists of 3262a low-level general interface, a message encryption and authentication 3263interface, and specific functions for CCM using AES as the underlying 3264block cipher. These interfaces are defined in @file{<nettle/ccm.h>}. 3265 3266In @acronym{CCM}, the length of the message must be known before 3267processing. The maximum message size depends on the size of the nonce, 3268since the message size is encoded in a field which must fit in a single 3269block, together with the nonce and a flag byte. E.g., with a nonce size 3270of 12 octets, there are three octets left for encoding the message 3271length, the maximum message length is @math{2^24 - 1} octets. 3272 3273@acronym{CCM} mode encryption operates as follows: 3274@itemize 3275@item The nonce and message length are concatenated to create 3276@code{B_0 = flags | nonce | mlength} 3277 3278@item The authenticated data and plaintext is formatted into the string 3279@code{B = L(adata) | adata | padding | plaintext | padding} with 3280@code{padding} being the shortest string of zero bytes such that the 3281length of the string is a multiple of the block size, and 3282@code{L(adata)} is an encoding of the length of @code{adata}. 3283 3284@item The string @code{B} is separated into blocks @code{B_1} ... 3285@code{B_n} 3286@item The authentication tag @code{T} is calculated as 3287@code{T=0, for i=0 to n, do T = E_k(B_i XOR T)} 3288 3289@item An initial counter is then initialized from the nonce to create 3290@code{IC = flags | nonce | padding}, where @code{padding} is the 3291shortest string of zero bytes such that @code{IC} is exactly one block 3292in length. 3293 3294@item The authentication tag is encrypted using using @acronym{CTR} mode: 3295@code{MAC = E_k(IC) XOR T} 3296 3297@item The plaintext is then encrypted using @acronym{CTR} mode with an 3298initial counter of @code{IC+1}. 3299@end itemize 3300 3301@acronym{CCM} mode decryption operates similarly, except that the 3302ciphertext and @acronym{MAC} are first decrypted using CTR mode to 3303retrieve the plaintext and authentication tag. The authentication tag 3304can then be recalculated from the authenticated data and plaintext, and 3305compared to the value in the message to check for authenticity. 3306 3307@subsubsection General @acronym{CCM} interface 3308 3309For all of the functions in the @acronym{CCM} interface, @var{cipher} is 3310the context struct for the underlying cipher and @var{f} is the 3311encryption function. The cipher's encryption key must be set before 3312calling any of the @acronym{CCM} functions. The cipher's decryption 3313function and key are never used. 3314 3315@deftp {Context struct} {struct ccm_ctx} 3316Holds state corresponding to a particular message. 3317@end deftp 3318 3319@defvr Constant CCM_BLOCK_SIZE 3320@acronym{CCM}'s block size, 16. 3321@end defvr 3322 3323@defvr Constant CCM_DIGEST_SIZE 3324Size of the @acronym{CCM} digest, 16. 3325@end defvr 3326 3327@defvr Constant CCM_MIN_NONCE_SIZE 3328@defvrx Constant CCM_MAX_NONCE_SIZE 3329The the minimum and maximum sizes for an @acronym{CCM} nonce, 7 and 14, 3330respectively. 3331@end defvr 3332 3333@deffn Macro CCM_MAX_MSG_SIZE (@var{nonce_size}) 3334The largest allowed plaintext length, when using @acronym{CCM} with a 3335nonce of the given size. 3336@end deffn 3337 3338@deftypefun void ccm_set_nonce (struct ccm_ctx *@var{ctx}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{noncelen}, const uint8_t *@var{nonce}, size_t @var{authlen}, size_t @var{msglen}, size_t @var{taglen}) 3339Initializes @var{ctx} using the given nonce and the sizes of the 3340authenticated data, message, and @acronym{MAC} to be processed. 3341@end deftypefun 3342 3343@deftypefun void ccm_update (struct ccm_ctx *@var{ctx}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, const uint8_t *@var{data}) 3344Provides associated data to be authenticated. Must be called after 3345@code{ccm_set_nonce}, and before @code{ccm_encrypt}, @code{ccm_decrypt}, or 3346@code{ccm_digest}. 3347@end deftypefun 3348 3349@deftypefun void ccm_encrypt (struct ccm_ctx *@var{ctx}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3350@deftypefunx void ccm_decrypt (struct ccm_ctx *@var{ctx}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3351Encrypts or decrypts the message data. Must be called after 3352@code{ccm_set_nonce} and before @code{ccm_digest}. All but the last call 3353for each message @emph{must} use a length that is a multiple of the 3354block size. 3355@end deftypefun 3356 3357@deftypefun void ccm_digest (struct ccm_ctx *@var{ctx}, const void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{length}, uint8_t *@var{digest}) 3358Extracts the message digest (also known ``authentication tag''). This is 3359the final operation when processing a message. @var{length} is usually 3360equal to the @var{taglen} parameter supplied to @code{ccm_set_nonce}, 3361but if you provide a smaller value, only the first @var{length} octets 3362of the digest are written. 3363@end deftypefun 3364 3365To encrypt a message using the general @acronym{CCM} interface, set the 3366message nonce and length using @code{ccm_set_nonce} and then call 3367@code{ccm_update} to generate the digest of any authenticated data. 3368After all of the authenticated data has been digested use 3369@code{ccm_encrypt} to encrypt the plaintext. Finally, use 3370@code{ccm_digest} to return the encrypted @acronym{MAC}. 3371 3372To decrypt a message, use @code{ccm_set_nonce} and @code{ccm_update} the 3373same as you would for encryption, and then call @code{ccm_decrypt} to 3374decrypt the ciphertext. After decrypting the ciphertext 3375@code{ccm_digest} will return the encrypted @acronym{MAC} which should 3376be identical to the @acronym{MAC} in the received message. 3377 3378@subsubsection @acronym{CCM} message interface 3379 3380The @acronym{CCM} message fuctions provides a simple interface that will 3381perform authentication and message encryption in a single function call. 3382The length of the cleartext is given by @var{mlength} and the length of 3383the ciphertext is given by @var{clength}, always exactly @var{tlength} 3384bytes longer than the corresponding plaintext. The length argument 3385passed to a function is always the size for the result, @var{clength} 3386for the encryption functions, and @var{mlength} for the decryption 3387functions. 3388 3389@deftypefun void ccm_encrypt_message (void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{tlength}, size_t @var{clength}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3390Computes the message digest from the @var{adata} and @var{src} 3391parameters, encrypts the plaintext from @var{src}, appends the encrypted 3392@acronym{MAC} to ciphertext and outputs it to @var{dst}. 3393@end deftypefun 3394 3395@deftypefun int ccm_decrypt_message (void *@var{cipher}, nettle_cipher_func *@var{f}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{tlength}, size_t @var{mlength}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3396Decrypts the ciphertext from @var{src}, outputs the plaintext to 3397@var{dst}, recalculates the @acronym{MAC} from @var{adata} and the 3398plaintext, and compares it to the final @var{tlength} bytes of 3399@var{src}. If the values of the received and calculated @acronym{MAC}s 3400are equal, this will return 1 indicating a valid and authenticated 3401message. Otherwise, this function will return zero. 3402@end deftypefun 3403 3404@subsubsection @acronym{CCM}-@acronym{AES} interface 3405 3406The @acronym{AES} @acronym{CCM} functions provide an API for using 3407@acronym{CCM} mode with the @acronym{AES} block ciphers. The parameters 3408all have the same meaning as the general and message interfaces, except 3409that the @var{cipher}, @var{f}, and @var{ctx} parameters are replaced 3410with an @acronym{AES} context structure, and a set-key function must be 3411called before using any of the other functions in this interface. 3412 3413@deftp {Context struct} {struct ccm_aes128_ctx} 3414Holds state corresponding to a particular message encrypted using the 3415AES-128 block cipher. 3416@end deftp 3417 3418@deftp {Context struct} {struct ccm_aes192_ctx} 3419Holds state corresponding to a particular message encrypted using the 3420AES-192 block cipher. 3421@end deftp 3422 3423@deftp {Context struct} {struct ccm_aes256_ctx} 3424Holds state corresponding to a particular message encrypted using the 3425AES-256 block cipher. 3426@end deftp 3427 3428@deftypefun void ccm_aes128_set_key (struct ccm_aes128_ctx *@var{ctx}, const uint8_t *@var{key}) 3429@deftypefunx void ccm_aes192_set_key (struct ccm_aes192_ctx *@var{ctx}, const uint8_t *@var{key}) 3430@deftypefunx void ccm_aes256_set_key (struct ccm_aes256_ctx *@var{ctx}, const uint8_t *@var{key}) 3431Initializes the encryption key for the AES block cipher. One of these 3432functions must be called before any of the other functions in the 3433@acronym{AES} @acronym{CCM} interface. 3434@end deftypefun 3435 3436@deftypefun void ccm_aes128_set_nonce (struct ccm_aes128_ctx *@var{ctx}, size_t @var{noncelen}, const uint8_t *@var{nonce}, size_t @var{authlen}, size_t @var{msglen}, size_t @var{taglen}) 3437@deftypefunx void ccm_aes192_set_nonce (struct ccm_aes192_ctx *@var{ctx}, size_t @var{noncelen}, const uint8_t *@var{nonce}, size_t @var{authlen}, size_t @var{msglen}, size_t @var{taglen}) 3438@deftypefunx void ccm_aes256_set_nonce (struct ccm_aes256_ctx *@var{ctx}, size_t @var{noncelen}, const uint8_t *@var{nonce}, size_t @var{authlen}, size_t @var{msglen}, size_t @var{taglen}) 3439These are identical to @code{ccm_set_nonce}, except that @var{cipher}, 3440@var{f}, and @var{ctx} are replaced with a context structure. 3441@end deftypefun 3442 3443@deftypefun void ccm_aes128_update (struct ccm_aes128_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 3444@deftypefunx void ccm_aes192_update (struct ccm_aes192_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 3445@deftypefunx void ccm_aes256_update (struct ccm_aes256_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 3446These are identical to @code{ccm_set_update}, except that @var{cipher}, 3447@var{f}, and @var{ctx} are replaced with a context structure. 3448@end deftypefun 3449 3450@deftypefun void ccm_aes128_encrypt (struct ccm_aes128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3451@deftypefunx void ccm_aes192_encrypt (struct ccm_aes192_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3452@deftypefunx void ccm_aes256_encrypt (struct ccm_aes256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3453@deftypefunx void ccm_aes128_decrypt (struct ccm_aes128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3454@deftypefunx void ccm_aes192_decrypt (struct ccm_aes192_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3455@deftypefunx void ccm_aes256_decrypt (struct ccm_aes256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3456These are identical to @code{ccm_set_encrypt} and @code{ccm_set_decrypt}, except 3457that @var{cipher}, @var{f}, and @var{ctx} are replaced with a context structure. 3458@end deftypefun 3459 3460@deftypefun void ccm_aes128_digest (struct ccm_aes128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 3461@deftypefunx void ccm_aes192_digest (struct ccm_aes192_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 3462@deftypefunx void ccm_aes256_digest (struct ccm_aes256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 3463These are identical to @code{ccm_set_digest}, except that @var{cipher}, 3464@var{f}, and @var{ctx} are replaced with a context structure. 3465@end deftypefun 3466 3467@deftypefun void ccm_aes128_encrypt_message (struct ccm_aes128_ctx *@var{ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{tlength}, size_t @var{clength}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3468@deftypefunx void ccm_aes192_encrypt_message (struct ccm_aes192_ctx *@var{ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{tlength}, size_t @var{clength}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3469@deftypefunx void ccm_aes256_encrypt_message (struct ccm_aes256_ctx *@var{ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{tlength}, size_t @var{clength}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3470@deftypefunx int ccm_aes128_decrypt_message (struct ccm_aes128_ctx *@var{ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{tlength}, size_t @var{mlength}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3471@deftypefunx int ccm_aes192_decrypt_message (struct ccm_aes192_ctx *@var{ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{tlength}, size_t @var{mlength}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3472@deftypefunx int ccm_aes192_decrypt_message (struct ccm_aes256_ctx *@var{ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{tlength}, size_t @var{mlength}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3473These are identical to @code{ccm_encrypt_message} and @code{ccm_decrypt_message} 3474except that @var{cipher} and @var{f} are replaced with a context structure. 3475@end deftypefun 3476 3477@node ChaCha-Poly1305, SIV-CMAC, CCM, Authenticated encryption 3478@comment node-name, next, previous, up 3479@subsection ChaCha-Poly1305 3480 3481ChaCha-Poly1305 is a combination of the ChaCha stream cipher and the 3482poly1305 message authentication code (@pxref{Poly1305}). It originates 3483from the NaCl cryptographic library by D. J. Bernstein et al, which 3484defines a similar construction but with Salsa20 instead of ChaCha. 3485 3486Nettle's implementation of ChaCha-Poly1305 follows @cite{RFC 8439}, 3487where the ChaCha cipher is initialized with a 12-byte nonce and a 4-byte 3488block counter. This allows up to 256 gigabytes of data to be encrypted 3489using the same key and nonce. 3490 3491For ChaCha-Poly1305, the ChaCha cipher is initialized with a key, of 256 3492bits, and a per-message nonce. The first block of the key stream 3493(counter all zero) is set aside for the authentication subkeys. Of this 349464-octet block, the first 16 octets specify the poly1305 evaluation 3495point, and the next 16 bytes specify the value to add in for the final 3496digest. The final 32 bytes of this block are unused. Note that unlike 3497poly1305-aes, the evaluation point depends on the nonce. This is 3498preferable, because it leaks less information in case the attacker for 3499some reason is lucky enough to forge a valid authentication tag, and 3500observe (from the receiver's behaviour) that the forgery succeeded. 3501 3502The ChaCha key stream, starting with counter value 1, is then used to 3503encrypt the message. For authentication, poly1305 is applied to the 3504concatenation of the associated data, the cryptotext, and the lengths of 3505the associated data and the message, each a 64-bit number (eight octets, 3506little-endian). Nettle defines ChaCha-Poly1305 in 3507@file{<nettle/chacha-poly1305.h>}. 3508 3509@defvr Constant CHACHA_POLY1305_BLOCK_SIZE 3510Same as the ChaCha block size, 64. 3511@end defvr 3512 3513@defvr Constant CHACHA_POLY1305_KEY_SIZE 3514ChaCha-Poly1305 key size, 32. 3515@end defvr 3516 3517@defvr Constant CHACHA_POLY1305_NONCE_SIZE 3518ChaCha-Poly1305 nonce size, 12. 3519@end defvr 3520 3521@defvr Constant CHACHA_POLY1305_DIGEST_SIZE 3522Digest size, 16. 3523@end defvr 3524 3525@deftp {Context struct} {struct chacha_poly1305_ctx} 3526@end deftp 3527 3528@deftypefun void chacha_poly1305_set_key (struct chacha_poly1305_ctx *@var{ctx}, const uint8_t *@var{key}) 3529Initializes @var{ctx} using the given key. Before using the context, you 3530@emph{must} also call @code{chacha_poly1305_set_nonce}, see below. 3531@end deftypefun 3532 3533@deftypefun void chacha_poly1305_set_nonce (struct chacha_poly1305_ctx *@var{ctx}, const uint8_t *@var{nonce}) 3534Initializes the per-message state, using the given nonce. 3535@end deftypefun 3536 3537@deftypefun void chacha_poly1305_update (struct chacha_poly1305_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 3538Process associated data for authentication. 3539@end deftypefun 3540 3541@deftypefun void chacha_poly1305_encrypt (struct chacha_poly1305_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3542@deftypefunx void chacha_poly1305_decrypt (struct chacha_poly1305_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3543Encrypts or decrypts the data of a message. All but the last call for 3544each message @emph{must} use a length that is a multiple of the block 3545size. 3546@end deftypefun 3547 3548@deftypefun void chacha_poly1305_digest (struct chacha_poly1305_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 3549Extracts the message digest (also known ``authentication tag''). This is 3550the final operation when processing a message. If @var{length} is 3551smaller than @code{CHACHA_POLY1305_DIGEST_SIZE}, only the first 3552@var{length} octets of the digest are written. 3553@end deftypefun 3554 3555@node SIV-CMAC, nettle_aead abstraction, ChaCha-Poly1305, Authenticated encryption 3556@comment node-name, next, previous, up 3557@subsection Synthetic Initialization Vector AEAD 3558 3559@cindex SIV mode 3560@cindex SIV-CMAC mode 3561 3562@acronym{SIV-CMAC} mode is a combination of counter mode with message 3563authentication based on @acronym{CMAC}. Unlike other counter @acronym{AEAD} 3564modes, it provides protection against accidental nonce misuse, making it 3565a good choice for stateless-servers that cannot ensure nonce uniqueness. 3566It is constructed on top of a block cipher which must have a block size of 3567128 bits. Nettle's support for @acronym{SIV-CMAC} consists of 3568a message encryption and authentication interface, for 3569@acronym{SIV-CMAC} using AES as the underlying block cipher. 3570When a nonce is re-used with this mode, message authenticity is retained 3571however an attacker can determine whether the same plaintext was protected 3572with the two messages sharing the nonce. 3573These interfaces are defined in @file{<nettle/siv-cmac.h>}. 3574 3575Unlike other @acronym{AEAD} mode in @acronym{SIV-CMAC} the initialization 3576vector serves as the tag. That means that in the generated ciphertext 3577the tag precedes the ciphertext. 3578 3579Note also, that the @acronym{SIV-CMAC} algorithm, as specified in 3580@cite{RFC 5297}, introduces the notion of authenticated data which 3581consist of multiple components. For example with @acronym{SIV-CMAC} the 3582authentication tag of data @code{X} followed by @code{Y}, is different 3583than the concatenated data @code{X || Y}. The interfaces described below 3584follow the @acronym{AEAD} paradigm and do not allow access to this 3585feature and also require the use of a non-empty nonce. In the 3586terminology of the RFC, the input to the S2V function is always a vector 3587of three elements, where S1 is the authenticated data, S2 is the nonce, 3588and S3 is the plaintext. 3589 3590 3591@subsubsection General interface 3592 3593@defvr Constant SIV_BLOCK_SIZE 3594@acronym{SIV-CMAC}'s block size, 16. 3595@end defvr 3596 3597@defvr Constant SIV_DIGEST_SIZE 3598Size of the @acronym{SIV-CMAC} digest or initialization vector, 16. 3599@end defvr 3600 3601@defvr Constant SIV_MIN_NONCE_SIZE 3602The the minimum size for an @acronym{SIV-CMAC} nonce, 1. 3603@end defvr 3604 3605@subsubsection @acronym{SIV-CMAC}-@acronym{AES} interface 3606 3607The @acronym{AES} @acronym{SIV-CMAC} functions provide an API for using 3608@acronym{SIV-CMAC} mode with the @acronym{AES} block ciphers. The parameters 3609all have the same meaning as the general and message interfaces, except 3610that the @var{cipher}, @var{f}, and @var{ctx} parameters are replaced 3611with an @acronym{AES} context structure, and a set-key function must be 3612called before using any of the other functions in this interface. 3613 3614@deftp {Context struct} {struct siv_cmac_aes128_ctx} 3615Holds state corresponding to a particular message encrypted using the 3616AES-128 block cipher. 3617@end deftp 3618 3619@deftp {Context struct} {struct siv_cmac_aes256_ctx} 3620Holds state corresponding to a particular message encrypted using the 3621AES-256 block cipher. 3622@end deftp 3623 3624@deftypefun void siv_cmac_aes128_set_key (struct siv_cmac_aes128_ctx *@var{ctx}, const uint8_t *@var{key}) 3625@deftypefunx void siv_cmac_aes256_set_key (struct siv_cmac_aes256_ctx *@var{ctx}, const uint8_t *@var{key}) 3626Initializes the encryption key for the AES block cipher. One of these 3627functions must be called before any of the other functions in the 3628@acronym{AES} @acronym{SIV-CMAC} interface. 3629@end deftypefun 3630 3631@deftypefun void siv_cmac_aes128_encrypt_message (struct siv_cmac_aes128_ctx *@var{ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{clength}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3632@deftypefunx void siv_cmac_aes256_encrypt_message (struct siv_cmac_aes256_ctx *@var{ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{clength}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3633Computes the message digest from the @var{adata} and @var{src} 3634parameters, encrypts the plaintext from @var{src}, prepends the 3635initialization vector to the ciphertext and outputs it to @var{dst}. 3636The @var{clength} variable must be equal to the length of @var{src} 3637plus @code{SIV_DIGEST_SIZE}. 3638 3639@end deftypefun 3640 3641@deftypefun int siv_cmac_aes128_decrypt_message (struct siv_cmac_aes128_ctx *@var{ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{mlength}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3642@deftypefunx int siv_cmac_aes256_decrypt_message (struct siv_cmac_aes128_ctx *@var{ctx}, size_t @var{nlength}, const uint8_t *@var{nonce}, size_t @var{alength}, const uint8_t *@var{adata}, size_t @var{mlength}, uint8_t *@var{dst}, const uint8_t *@var{src}) 3643Decrypts the ciphertext from @var{src}, outputs the plaintext to 3644@var{dst}, recalculates the initialization vector from @var{adata} and the 3645plaintext. If the values of the received and calculated initialization vector 3646are equal, this will return 1 indicating a valid and authenticated 3647message. Otherwise, this function will return zero. 3648@end deftypefun 3649 3650@node nettle_aead abstraction, , ChaCha-Poly1305, Authenticated encryption 3651@comment node-name, next, previous, up 3652@subsection The @code{struct nettle_aead} abstraction 3653@cindex nettle_aead 3654 3655Nettle includes a struct including information about the supported hash 3656functions. It is defined in @file{<nettle/nettle-meta.h>}. 3657 3658@deftp {Meta struct} @code{struct nettle_aead} name context_size block_size key_size nonce_size digest_size set_encrypt_key set_decrypt_key set_nonce update encrypt decrypt digest 3659The last seven attributes are function pointers. 3660@end deftp 3661 3662@deftypevr {Constant Struct} {struct nettle_aead} nettle_gcm_aes128 3663@deftypevrx {Constant Struct} {struct nettle_aead} nettle_gcm_aes192 3664@deftypevrx {Constant Struct} {struct nettle_aead} nettle_gcm_aes256 3665@deftypevrx {Constant Struct} {struct nettle_aead} nettle_gcm_camellia128 3666@deftypevrx {Constant Struct} {struct nettle_aead} nettle_gcm_camellia256 3667@deftypevrx {Constant Struct} {struct nettle_aead} nettle_eax_aes128 3668@deftypevrx {Constant Struct} {struct nettle_aead} nettle_chacha_poly1305 3669These are most of the @acronym{AEAD} constructions that Nettle 3670implements. Note that @acronym{CCM} is missing; it requirement that the 3671message size is specified in advance makes it incompatible with the 3672@code{nettle_aead} abstraction. 3673@end deftypevr 3674 3675Nettle also exports a list of all these constructions. 3676 3677@deftypefun {const struct nettle_aead **} nettle_get_aeads (void) 3678Returns a NULL-terminated list of pointers to supported algorithms.This 3679list can be used to dynamically enumerate or search the supported 3680algorithms. 3681@end deftypefun 3682 3683@deffn Macro nettle_aeads 3684A macro expanding to a call to nettle_get_aeads. In earlier versions, 3685this was not a macro but the actual array of pointers. 3686@end deffn 3687 3688@node Keyed hash functions, Key derivation functions, Authenticated encryption, Reference 3689@comment node-name, next, previous, up 3690@section Keyed Hash Functions 3691 3692@cindex Keyed Hash Function 3693@cindex Message Authentication Code 3694@cindex MAC 3695 3696A @dfn{keyed hash function}, or @dfn{Message Authentication Code} 3697(@acronym{MAC}) is a function that takes a key and a message, and 3698produces fixed size @acronym{MAC}. It should be hard to compute a 3699message and a matching @acronym{MAC} without knowledge of the key. It 3700should also be hard to compute the key given only messages and 3701corresponding @acronym{MAC}s. 3702 3703Keyed hash functions are useful primarily for message authentication, 3704when Alice and Bob shares a secret: The sender, Alice, computes the 3705@acronym{MAC} and attaches it to the message. The receiver, Bob, also computes 3706the @acronym{MAC} of the message, using the same key, and compares that 3707to Alice's value. If they match, Bob can be assured that 3708the message has not been modified on its way from Alice. 3709 3710However, unlike digital signatures, this assurance is not transferable. 3711Bob can't show the message and the @acronym{MAC} to a third party and 3712prove that Alice sent that message. Not even if he gives away the key to 3713the third party. The reason is that the @emph{same} key is used on both 3714sides, and anyone knowing the key can create a correct @acronym{MAC} for 3715any message. If Bob believes that only he and Alice knows the key, and 3716he knows that he didn't attach a @acronym{MAC} to a particular message, 3717he knows it must be Alice who did it. However, the third party can't 3718distinguish between a @acronym{MAC} created by Alice and one created by 3719Bob. 3720 3721Keyed hash functions are typically a lot faster than digital signatures 3722as well. 3723 3724@menu 3725* HMAC:: 3726* UMAC:: 3727* CMAC:: 3728* Poly1305:: 3729@end menu 3730 3731@node HMAC, UMAC, Keyed hash functions, Keyed hash functions 3732@comment node-name, next, previous, up 3733 3734@subsection @acronym{HMAC} 3735@cindex HMAC 3736 3737One can build keyed hash functions from ordinary hash functions. Older 3738constructions simply concatenate secret key and message and hashes that, but 3739such constructions have weaknesses. A better construction is 3740@acronym{HMAC}, described in @cite{RFC 2104}. 3741 3742For an underlying hash function @code{H}, with digest size @code{l} and 3743internal block size @code{b}, @acronym{HMAC-H} is constructed as 3744follows: From a given key @code{k}, two distinct subkeys @code{k_i} and 3745@code{k_o} are constructed, both of length @code{b}. The 3746@acronym{HMAC-H} of a message @code{m} is then computed as @code{H(k_o | 3747H(k_i | m))}, where @code{|} denotes string concatenation. 3748 3749@acronym{HMAC} keys can be of any length, but it is recommended to use 3750keys of length @code{l}, the digest size of the underlying hash function 3751@code{H}. Keys that are longer than @code{b} are shortened to length 3752@code{l} by hashing with @code{H}, so arbitrarily long keys aren't 3753very useful. 3754 3755Nettle's @acronym{HMAC} functions are defined in @file{<nettle/hmac.h>}. 3756There are abstract functions that use a pointer to a @code{struct 3757nettle_hash} to represent the underlying hash function and @code{void *} 3758pointers that point to three different context structs for that hash 3759function. There are also concrete functions for @acronym{HMAC-MD5}, 3760@acronym{HMAC-RIPEMD160} @acronym{HMAC-SHA1}, @acronym{HMAC-SHA256}, and 3761@acronym{HMAC-SHA512}. First, the abstract functions: 3762 3763@deftypefun void hmac_set_key (void *@var{outer}, void *@var{inner}, void *@var{state}, const struct nettle_hash *@var{H}, size_t @var{length}, const uint8_t *@var{key}) 3764Initializes the three context structs from the key. The @var{outer} and 3765@var{inner} contexts corresponds to the subkeys @code{k_o} and 3766@code{k_i}. @var{state} is used for hashing the message, and is 3767initialized as a copy of the @var{inner} context. 3768@end deftypefun 3769 3770@deftypefun void hmac_update (void *@var{state}, const struct nettle_hash *@var{H}, size_t @var{length}, const uint8_t *@var{data}) 3771This function is called zero or more times to process the message. 3772Actually, @code{hmac_update(state, H, length, data)} is equivalent to 3773@code{H->update(state, length, data)}, so if you wish you can use the 3774ordinary update function of the underlying hash function instead. 3775@end deftypefun 3776 3777@deftypefun void hmac_digest (const void *@var{outer}, const void *@var{inner}, void *@var{state}, const struct nettle_hash *@var{H}, size_t @var{length}, uint8_t *@var{digest}) 3778Extracts the @acronym{MAC} of the message, writing it to @var{digest}. 3779@var{outer} and @var{inner} are not modified. @var{length} is usually 3780equal to @code{H->digest_size}, but if you provide a smaller value, 3781only the first @var{length} octets of the @acronym{MAC} are written. 3782 3783This function also resets the @var{state} context so that you can start 3784over processing a new message (with the same key). 3785@end deftypefun 3786 3787Like for @acronym{CBC}, there are some macros to help use these 3788functions correctly. 3789 3790@deffn Macro HMAC_CTX (@var{type}) 3791Expands to 3792@example 3793@{ 3794 type outer; 3795 type inner; 3796 type state; 3797@} 3798@end example 3799@end deffn 3800 3801It can be used to define a @acronym{HMAC} context struct, either 3802directly, 3803 3804@example 3805struct HMAC_CTX(struct md5_ctx) ctx; 3806@end example 3807 3808or to give it a struct tag, 3809 3810@example 3811struct hmac_md5_ctx HMAC_CTX (struct md5_ctx); 3812@end example 3813 3814@deffn Macro HMAC_SET_KEY (@var{ctx}, @var{H}, @var{length}, @var{key}) 3815@var{ctx} is a pointer to a context struct as defined by 3816@code{HMAC_CTX}, @var{H} is a pointer to a @code{const struct 3817nettle_hash} describing the underlying hash function (so it must match 3818the type of the components of @var{ctx}). The last two arguments specify 3819the secret key. 3820@end deffn 3821 3822@deffn Macro HMAC_DIGEST (@var{ctx}, @var{H}, @var{length}, @var{digest}) 3823@var{ctx} is a pointer to a context struct as defined by 3824@code{HMAC_CTX}, @var{H} is a pointer to a @code{const struct 3825nettle_hash} describing the underlying hash function. The last two 3826arguments specify where the digest is written. 3827@end deffn 3828 3829Note that there is no @code{HMAC_UPDATE} macro; simply call 3830@code{hmac_update} function directly, or the update function of the 3831underlying hash function. 3832 3833@subsection Concrete @acronym{HMAC} functions 3834Now we come to the specialized @acronym{HMAC} functions, which are 3835easier to use than the general @acronym{HMAC} functions. 3836 3837@subsubsection @acronym{HMAC-MD5} 3838 3839@deftp {Context struct} {struct hmac_md5_ctx} 3840@end deftp 3841 3842@deftypefun void hmac_md5_set_key (struct hmac_md5_ctx *@var{ctx}, size_t @var{key_length}, const uint8_t *@var{key}) 3843Initializes the context with the key. 3844@end deftypefun 3845 3846@deftypefun void hmac_md5_update (struct hmac_md5_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 3847Process some more data. 3848@end deftypefun 3849 3850@deftypefun void hmac_md5_digest (struct hmac_md5_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 3851Extracts the @acronym{MAC}, writing it to @var{digest}. @var{length} may be smaller than 3852@code{MD5_DIGEST_SIZE}, in which case only the first @var{length} 3853octets of the @acronym{MAC} are written. 3854 3855This function also resets the context for processing new messages, with 3856the same key. 3857@end deftypefun 3858 3859@subsubsection @acronym{HMAC-RIPEMD160} 3860 3861@deftp {Context struct} {struct hmac_ripemd160_ctx} 3862@end deftp 3863 3864@deftypefun void hmac_ripemd160_set_key (struct hmac_ripemd160_ctx *@var{ctx}, size_t @var{key_length}, const uint8_t *@var{key}) 3865Initializes the context with the key. 3866@end deftypefun 3867 3868@deftypefun void hmac_ripemd160_update (struct hmac_ripemd160_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 3869Process some more data. 3870@end deftypefun 3871 3872@deftypefun void hmac_ripemd160_digest (struct hmac_ripemd160_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 3873Extracts the @acronym{MAC}, writing it to @var{digest}. @var{length} may be smaller than 3874@code{RIPEMD160_DIGEST_SIZE}, in which case only the first @var{length} 3875octets of the @acronym{MAC} are written. 3876 3877This function also resets the context for processing new messages, with 3878the same key. 3879@end deftypefun 3880 3881@subsubsection @acronym{HMAC-SHA1} 3882 3883@deftp {Context struct} {struct hmac_sha1_ctx} 3884@end deftp 3885 3886@deftypefun void hmac_sha1_set_key (struct hmac_sha1_ctx *@var{ctx}, size_t @var{key_length}, const uint8_t *@var{key}) 3887Initializes the context with the key. 3888@end deftypefun 3889 3890@deftypefun void hmac_sha1_update (struct hmac_sha1_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 3891Process some more data. 3892@end deftypefun 3893 3894@deftypefun void hmac_sha1_digest (struct hmac_sha1_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 3895Extracts the @acronym{MAC}, writing it to @var{digest}. @var{length} may be smaller than 3896@code{SHA1_DIGEST_SIZE}, in which case only the first @var{length} 3897octets of the @acronym{MAC} are written. 3898 3899This function also resets the context for processing new messages, with 3900the same key. 3901@end deftypefun 3902 3903 3904@subsubsection @acronym{HMAC-SHA256} 3905 3906@deftp {Context struct} {struct hmac_sha256_ctx} 3907@end deftp 3908 3909@deftypefun void hmac_sha256_set_key (struct hmac_sha256_ctx *@var{ctx}, size_t @var{key_length}, const uint8_t *@var{key}) 3910Initializes the context with the key. 3911@end deftypefun 3912 3913@deftypefun void hmac_sha256_update (struct hmac_sha256_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 3914Process some more data. 3915@end deftypefun 3916 3917@deftypefun void hmac_sha256_digest (struct hmac_sha256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 3918Extracts the @acronym{MAC}, writing it to @var{digest}. @var{length} may be smaller than 3919@code{SHA256_DIGEST_SIZE}, in which case only the first @var{length} 3920octets of the @acronym{MAC} are written. 3921 3922This function also resets the context for processing new messages, with 3923the same key. 3924@end deftypefun 3925 3926 3927@subsubsection @acronym{HMAC-SHA512} 3928 3929@deftp {Context struct} {struct hmac_sha512_ctx} 3930@end deftp 3931 3932@deftypefun void hmac_sha512_set_key (struct hmac_sha512_ctx *@var{ctx}, size_t @var{key_length}, const uint8_t *@var{key}) 3933Initializes the context with the key. 3934@end deftypefun 3935 3936@deftypefun void hmac_sha512_update (struct hmac_sha512_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 3937Process some more data. 3938@end deftypefun 3939 3940@deftypefun void hmac_sha512_digest (struct hmac_sha512_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 3941Extracts the @acronym{MAC}, writing it to @var{digest}. @var{length} may be smaller than 3942@code{SHA512_DIGEST_SIZE}, in which case only the first @var{length} 3943octets of the @acronym{MAC} are written. 3944 3945This function also resets the context for processing new messages, with 3946the same key. 3947@end deftypefun 3948 3949@node UMAC, Poly1305 , HMAC, Keyed hash functions 3950@comment node-name, next, previous, up 3951 3952@subsection @acronym{UMAC} 3953@cindex UMAC 3954 3955@acronym{UMAC} is a message authentication code based on universal 3956hashing, and designed for high performance on modern processors (in 3957contrast to GCM, @xref{GCM}, which is designed primarily for hardware 3958performance). On processors with good integer multiplication 3959performance, it can be 10 times faster than SHA256 and SHA512. 3960@acronym{UMAC} is specified in @cite{RFC 4418}. 3961 3962The secret key is always 128 bits (16 octets). The key is used as an 3963encryption key for the @acronym{AES} block cipher. This cipher is used 3964in counter mode to generate various internal subkeys needed in 3965@acronym{UMAC}. Messages are of arbitrary size, and for each message, 3966@acronym{UMAC} also needs a unique nonce. Nonce values must not be 3967reused for two messages with the same key, but they need not be kept 3968secret. 3969 3970The nonce must be at least one octet, and at most 16; nonces shorter 3971than 16 octets are zero-padded. Nettle's implementation of 3972@acronym{UMAC} increments the nonce automatically for each message, so 3973explicitly setting the nonce for each message is optional. This 3974auto-increment uses network byte order and it takes the length of the 3975nonce into account. E.g., if the initial nonce is ``abc'' (3 octets), 3976this value is zero-padded to 16 octets for the first message. For the 3977next message, the nonce is incremented to ``abd'', and this incremented 3978value is zero-padded to 16 octets. 3979 3980@acronym{UMAC} is defined in four variants, for different output sizes: 398132 bits (4 octets), 64 bits (8 octets), 96 bits (12 octets) and 128 bits 3982(16 octets), corresponding to different trade-offs between speed and 3983security. Using a shorter output size sometimes (but not always!) gives 3984the same result as using a longer output size and truncating the result. 3985So it is important to use the right variant. For consistency with other 3986hash and @acronym{MAC} functions, Nettle's @code{_digest} functions for 3987@acronym{UMAC} accept a length parameter so that the output can be 3988truncated to any desired size, but it is recommended to stick to the 3989specified output size and select the @acronym{umac} variant 3990corresponding to the desired size. 3991 3992The internal block size of @acronym{UMAC} is 1024 octets, and it also 3993generates more than 1024 bytes of subkeys. This makes the size of the 3994context struct quite a bit larger than other hash functions and 3995@acronym{MAC} algorithms in Nettle. 3996 3997Nettle defines @acronym{UMAC} in @file{<nettle/umac.h>}. 3998 3999@deftp {Context struct} {struct umac32_ctx} 4000@deftpx {Context struct} {struct umac64_ctx} 4001@deftpx {Context struct} {struct umac96_ctx} 4002@deftpx {Context struct} {struct umac128_ctx} 4003Each @acronym{UMAC} variant uses its own context struct. 4004@end deftp 4005 4006@defvr Constant UMAC_KEY_SIZE 4007The UMAC key size, 16. 4008@end defvr 4009@defvr Constant UMAC_MIN_NONCE_SIZE 4010@defvrx Constant UMAC_MAX_NONCE_SIZE 4011The the minimum and maximum sizes for an UMAC nonce, 1 and 16, 4012respectively. 4013@end defvr 4014@defvr Constant UMAC32_DIGEST_SIZE 4015The size of an UMAC32 digest, 4. 4016@end defvr 4017@defvr Constant UMAC64_DIGEST_SIZE 4018The size of an UMAC64 digest, 8. 4019@end defvr 4020@defvr Constant UMAC96_DIGEST_SIZE 4021The size of an UMAC96 digest, 12. 4022@end defvr 4023@defvr Constant UMAC128_DIGEST_SIZE 4024The size of an UMAC128 digest, 16. 4025@end defvr 4026@defvr Constant UMAC_BLOCK_SIZE 4027The internal block size of UMAC. 4028@end defvr 4029 4030@deftypefun void umac32_set_key (struct umac32_ctx *@var{ctx}, const uint8_t *@var{key}) 4031@deftypefunx void umac64_set_key (struct umac64_ctx *@var{ctx}, const uint8_t *@var{key}) 4032@deftypefunx void umac96_set_key (struct umac96_ctx *@var{ctx}, const uint8_t *@var{key}) 4033@deftypefunx void umac128_set_key (struct umac128_ctx *@var{ctx}, const uint8_t *@var{key}) 4034These functions initialize the @acronym{UMAC} context struct. They also 4035initialize the nonce to zero (with length 16, for auto-increment). 4036@end deftypefun 4037 4038@deftypefun void umac32_set_nonce (struct umac32_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{nonce}) 4039@deftypefunx void umac64_set_nonce (struct umac64_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{nonce}) 4040@deftypefunx void umac96_set_nonce (struct umac96_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{nonce}) 4041@deftypefunx void umac128_set_nonce (struct umac128_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{nonce}) 4042Sets the nonce to be used for the next message. In general, nonces 4043should be set before processing of the message. This is not strictly 4044required for @acronym{UMAC} (the nonce only affects the final processing 4045generating the digest), but it is nevertheless recommended that this 4046function is called @emph{before} the first @code{_update} call for the 4047message. 4048@end deftypefun 4049 4050@deftypefun void umac32_update (struct umac32_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 4051@deftypefunx void umac64_update (struct umac64_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 4052@deftypefunx void umac96_update (struct umac96_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 4053@deftypefunx void umac128_update (struct umac128_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 4054These functions are called zero or more times to process the message. 4055@end deftypefun 4056 4057@deftypefun void umac32_digest (struct umac32_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 4058@deftypefunx void umac64_digest (struct umac64_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 4059@deftypefunx void umac96_digest (struct umac96_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 4060@deftypefunx void umac128_digest (struct umac128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 4061Extracts the @acronym{MAC} of the message, writing it to @var{digest}. 4062@var{length} is usually equal to the specified output size, but if you 4063provide a smaller value, only the first @var{length} octets of the 4064@acronym{MAC} are written. These functions reset the context for 4065processing of a new message with the same key. The nonce is incremented 4066as described above, the new value is used unless you call the 4067@code{_set_nonce} function explicitly for each message. 4068@end deftypefun 4069 4070@node CMAC,, UMAC, Keyed hash functions 4071@subsection @acronym{CMAC} 4072@cindex CMAC 4073@cindex CMAC-128 4074@cindex CMAC-64 4075 4076@acronym{CMAC} is a message authentication code based on CBC encryption 4077mode. It is suitable for systems where block ciphers are preferrable 4078and perform better than hash functions. @acronym{CMAC-128} is specified in 4079@cite{RFC4493}. The block size is always 128 bits (16 octets). 4080@acronym{CMAC-64} is specified by 4081@uref{https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38B.pdf, 4082NIST Special Publication 800-38B}. The block size is always 64 bits 4083(8 octets). 4084 4085Nettle provides helper functions for @acronym{CMAC-128} with 4086the @acronym{AES} block cipher and for @acronym{CMAC-64} with 4087the @acronym{Tripple-DES} block cipher. 4088 4089Nettle defines @acronym{CMAC} in @file{<nettle/cmac.h>}. 4090 4091@deftp {Context struct} {struct cmac_aes128_ctx} 4092@deftpx {Context struct} {struct cmac_aes256_ctx} 4093@end deftp 4094 4095@defvr Constant CMAC128_DIGEST_SIZE 4096The size of an CMAC-128 digest, 16. 4097@end defvr 4098 4099@deftypefun void cmac_aes128_set_key (struct cmac_aes128_ctx *@var{ctx}, const uint8_t *@var{key}) 4100This function initializes the @acronym{CMAC} context struct for AES-128. 4101@end deftypefun 4102 4103@deftypefun void cmac_aes128_update (struct cmac_aes128_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 4104This function is called zero or more times to process the message. 4105@end deftypefun 4106 4107@deftypefun void cmac_aes128_digest (struct cmac_aes128_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 4108Extracts the @acronym{MAC} of the message, writing it to @var{digest}. 4109@var{length} is usually equal to the specified output size, but if you 4110provide a smaller value, only the first @var{length} octets of the 4111@acronym{MAC} are written. This function resets the context for 4112processing of a new message with the same key. 4113@end deftypefun 4114 4115@deftypefun void cmac_aes256_set_key (struct cmac_aes256_ctx *@var{ctx}, const uint8_t *@var{key}) 4116This function initializes the @acronym{CMAC} context struct for AES-256. 4117@end deftypefun 4118 4119@deftypefun void cmac_aes256_update (struct cmac_aes256_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 4120This function is called zero or more times to process the message. 4121@end deftypefun 4122 4123@deftypefun void cmac_aes256_digest (struct cmac_aes256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 4124Extracts the @acronym{MAC} of the message, writing it to @var{digest}. 4125@var{length} is usually equal to the specified output size, but if you 4126provide a smaller value, only the first @var{length} octets of the 4127@acronym{MAC} are written. This function resets the context for 4128processing of a new message with the same key. 4129@end deftypefun 4130 4131@deftp {Context struct} {struct cmac_des3_ctx} 4132@end deftp 4133 4134@defvr Constant CMAC64_DIGEST_SIZE 4135The size of an CMAC-64 digest, 8. 4136@end defvr 4137 4138@deftypefun void cmac_des3_set_key (struct cmac_des3_ctx *@var{ctx}, const uint8_t *@var{key}) 4139This function initializes the @acronym{CMAC} context struct for @acronym{Tripple-DES}. 4140@end deftypefun 4141 4142@deftypefun void cmac_des3_update (struct cmac_des3_ctx *@var{ctx},size_t @var{length}, const uint8_t *@var{data}) 4143This function is called zero or more times to process the message. 4144@end deftypefun 4145 4146@deftypefun void cmac_des3_digest (struct cmac_des3_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 4147Extracts the @acronym{MAC} of the message, writing it to @var{digest}. 4148@var{length} is usually equal to the specified output size, but if you 4149provide a smaller value, only the first @var{length} octets of the 4150@acronym{MAC} are written. This function resets the context for 4151processing of a new message with the same key. 4152@end deftypefun 4153 4154@node Poly1305,, CMAC, Keyed hash functions 4155@comment node-name, next, previous, up 4156@subsection Poly1305 4157 4158Poly1305-@acronym{AES} is a message authentication code designed by D. J. 4159Bernstein. It treats the message as a polynomial modulo the prime number 4160@math{2^130 - 5}. 4161 4162The key, 256 bits, consists of two parts, where the first half is an 4163@acronym{AES}-128 key, and the second half specifies the point where the 4164polynomial is evaluated. Of the latter half, 22 bits are set to zero, to 4165enable high-performance implementation, leaving 106 bits for specifying 4166an evaluation point @code{r}. For each message, one must also provide a 4167128-bit nonce. The nonce is encrypted using the @acronym{AES} key, and 4168that's the only thing @acronym{AES} is used for. 4169 4170The message is split into 128-bit chunks (with final chunk possibly 4171being shorter), each read as a little-endian integer. Each chunk has a 4172one-bit appended at the high end. The resulting integers are treated as 4173polynomial coefficients modulo @math{2^130 - 5}, and the polynomial is 4174evaluated at the point @code{r}. Finally, this value is reduced modulo 4175@math{2^128}, and added (also modulo @math{2^128}) to the encrypted 4176nonce, to produce an 128-bit authenticator for the message. See 4177@uref{http://cr.yp.to/mac/poly1305-20050329.pdf} for further details. 4178 4179Clearly, variants using a different cipher than @acronym{AES} could be 4180defined. Another variant is the ChaCha-Poly1305 @acronym{AEAD} 4181construction (@pxref{ChaCha-Poly1305}). Nettle defines 4182Poly1305-@acronym{AES} in @file{nettle/poly1305.h}. 4183 4184@defvr Constant POLY1305_AES_KEY_SIZE 4185Key size, 32 octets. 4186@end defvr 4187 4188@defvr Constant POLY1305_AES_DIGEST_SIZE 4189Size of the digest or ``authenticator'', 16 octets. 4190@end defvr 4191 4192@defvr Constant POLY1305_AES_NONCE_SIZE 4193Nonce size, 16 octets. 4194@end defvr 4195 4196@deftp {Context struct} {struct poly1305_aes_ctx} 4197The poly1305-aes context struct. 4198@end deftp 4199 4200@deftypefun void poly1305_aes_set_key (struct poly1305_aes_ctx *@var{ctx}, const uint8_t *@var{key}) 4201Initialize the context struct. Also sets the nonce to zero. 4202@end deftypefun 4203 4204@deftypefun void poly1305_aes_set_nonce (struct poly1305_aes_ctx *@var{ctx}, const uint8_t *@var{nonce}) 4205Sets the nonce. Calling this function is optional, since the nonce is 4206incremented automatically for each message. 4207@end deftypefun 4208 4209@deftypefun void poly1305_aes_update (struct poly1305_aes_ctx *@var{ctx}, size_t @var{length}, const uint8_t *@var{data}) 4210Process more data. 4211@end deftypefun 4212 4213@deftypefun void poly1305_aes_digest (struct poly1305_aes_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{digest}) 4214Extracts the digest. If @var{length} is smaller than 4215@code{POLY1305_AES_DIGEST_SIZE}, only the first @var{length} octets are 4216written. Also increments the nonce, and prepares the context for 4217processing a new message. 4218@end deftypefun 4219 4220 4221@node Key derivation functions, Public-key algorithms, Keyed hash functions, Reference 4222@comment node-name, next, previous, up 4223@section Key derivation Functions 4224@cindex Key Derivation Function 4225 4226A @dfn{key derivation function} (@acronym{KDF}) is a function that from 4227a given symmetric key derives other symmetric keys. A sub-class of KDFs 4228is the @dfn{password-based key derivation functions} (@acronym{PBKDFs}), 4229which take as input a password or passphrase, and its purpose is 4230typically to strengthen it and protect against certain pre-computation 4231attacks by using salting and expensive computation. 4232 4233@subsection HKDF: HMAC-based Extract-and-Expand 4234@cindex HKDF 4235 4236HKDF is a key derivation function used as a building block of 4237higher-level protocols like TLS 1.3. It is a derivation function 4238based on HMAC described in @cite{RFC 5869}, 4239and is split into two logical modules, called 'extract' and 'expand'. 4240The extract module takes an initial secret and a random 4241salt to "extract" a fixed-length pseudorandom key (PRK). The second stage 4242takes as input the previous PRK and some informational data (e.g., 4243text) and expands them into multiple keys. 4244 4245Nettle's @acronym{HKDF} functions are defined in 4246@file{<nettle/hkdf.h>}. There are two abstract functions for the extract 4247and expand operations that operate on any HMAC implemented via the @code{nettle_hash_update_func}, 4248and @code{nettle_hash_digest_func} interfaces. 4249 4250@deftypefun void hkdf_extract (void *mac_ctx, nettle_hash_update_func *update, nettle_hash_digest_func *digest, size_t digest_size,size_t secret_size, const uint8_t *secret, uint8_t *dst) 4251Extract a Pseudorandom Key (PRK) from a secret and a salt according 4252to HKDF. The HMAC must have been initialized, with its key being the 4253salt for the Extract operation. This function will call the 4254@var{update} and @var{digest} functions passing the @var{mac_ctx} 4255context parameter as an argument in order to compute digest of size 4256@var{digest_size}. Inputs are the secret @var{secret} of length 4257@var{secret_length}. The output length is fixed to @var{digest_size} octets, 4258thus the output buffer @var{dst} must have room for at least @var{digest_size} octets. 4259@end deftypefun 4260 4261@deftypefun void hkdf_expand (void *mac_ctx, nettle_hash_update_func *update, nettle_hash_digest_func *digest, size_t digest_size, size_t info_size, const uint8_t *info, size_t length, uint8_t *dst) 4262Expand a Pseudorandom Key (PRK) to an arbitrary size according to HKDF. 4263The HMAC must have been initialized, with its key being the 4264PRK from the Extract operation. This function will call the 4265@var{update} and @var{digest} functions passing the @var{mac_ctx} 4266context parameter as an argument in order to compute digest of size 4267@var{digest_size}. Inputs are the info @var{info} of length 4268@var{info_length}, and the desired derived output length @var{length}. 4269The output buffer is @var{dst} which must have room for at least @var{length} octets. 4270@end deftypefun 4271 4272 4273@subsection @acronym{PBKDF2} 4274@cindex Password Based Key Derivation Function 4275@cindex PKCS #5 4276@cindex KDF 4277@cindex PBKDF 4278The most well known PBKDF is the @code{PKCS #5 PBKDF2} described in 4279@cite{RFC 2898} which uses a pseudo-random function such as 4280@acronym{HMAC-SHA1}. 4281 4282Nettle's @acronym{PBKDF2} functions are defined in 4283@file{<nettle/pbkdf2.h>}. There is an abstract function that operate on 4284any PRF implemented via the @code{nettle_hash_update_func}, 4285@code{nettle_hash_digest_func} interfaces. There is also helper macros 4286and concrete functions PBKDF2-HMAC-SHA1, PBKDF2-HMAC-SHA256, PBKDF2-HMAC-SHA384 4287and PBKDF2-HMAC-SHA512. First, the abstract function: 4288 4289@deftypefun void pbkdf2 (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) 4290Derive symmetric key from a password according to PKCS #5 PBKDF2. The 4291PRF is assumed to have been initialized and this function will call the 4292@var{update} and @var{digest} functions passing the @var{mac_ctx} 4293context parameter as an argument in order to compute digest of size 4294@var{digest_size}. Inputs are the salt @var{salt} of length 4295@var{salt_length}, the iteration counter @var{iterations} (> 0), and the 4296desired derived output length @var{length}. The output buffer is 4297@var{dst} which must have room for at least @var{length} octets. 4298@end deftypefun 4299 4300Like for CBC and HMAC, there is a macro to help use the function 4301correctly. 4302 4303@deffn Macro PBKDF2 (@var{ctx}, @var{update}, @var{digest}, @var{digest_size}, @var{iterations}, @var{salt_length}, @var{salt}, @var{length}, @var{dst}) 4304@var{ctx} is a pointer to a context struct passed to the @var{update} 4305and @var{digest} functions (of the types @code{nettle_hash_update_func} 4306and @code{nettle_hash_digest_func} respectively) to implement the 4307underlying PRF with digest size of @var{digest_size}. Inputs are the 4308salt @var{salt} of length @var{salt_length}, the iteration counter 4309@var{iterations} (> 0), and the desired derived output length 4310@var{length}. The output buffer is @var{dst} which must have room for 4311at least @var{length} octets. 4312@end deffn 4313 4314@subsection Concrete @acronym{PBKDF2} functions 4315Now we come to the specialized @acronym{PBKDF2} functions, which are 4316easier to use than the general @acronym{PBKDF2} function. 4317 4318@subsubsection @acronym{PBKDF2-HMAC-SHA1} 4319 4320@deftypefun void pbkdf2_hmac_sha1 (size_t @var{key_length}, const uint8_t *@var{key}, unsigned @var{iterations}, size_t @var{salt_length}, const uint8_t *@var{salt}, size_t @var{length}, uint8_t *@var{dst}) 4321PBKDF2 with HMAC-SHA1. Derive @var{length} bytes of key into buffer 4322@var{dst} using the password @var{key} of length @var{key_length} and 4323salt @var{salt} of length @var{salt_length}, with iteration counter 4324@var{iterations} (> 0). The output buffer is @var{dst} which must have 4325room for at least @var{length} octets. 4326@end deftypefun 4327 4328@subsubsection @acronym{PBKDF2-HMAC-SHA256} 4329 4330@deftypefun void pbkdf2_hmac_sha256 (size_t @var{key_length}, const uint8_t *@var{key}, unsigned @var{iterations}, size_t @var{salt_length}, const uint8_t *@var{salt}, size_t @var{length}, uint8_t *@var{dst}) 4331PBKDF2 with HMAC-SHA256. Derive @var{length} bytes of key into buffer 4332@var{dst} using the password @var{key} of length @var{key_length} and 4333salt @var{salt} of length @var{salt_length}, with iteration counter 4334@var{iterations} (> 0). The output buffer is @var{dst} which must have 4335room for at least @var{length} octets. 4336@end deftypefun 4337 4338@subsubsection @acronym{PBKDF2-HMAC-SHA384} 4339 4340@deftypefun void pbkdf2_hmac_sha384 (size_t @var{key_length}, const uint8_t *@var{key}, unsigned @var{iterations}, size_t @var{salt_length}, const uint8_t *@var{salt}, size_t @var{length}, uint8_t *@var{dst}) 4341PBKDF2 with HMAC-SHA384. Derive @var{length} bytes of key into buffer 4342@var{dst} using the password @var{key} of length @var{key_length} and 4343salt @var{salt} of length @var{salt_length}, with iteration counter 4344@var{iterations} (> 0). The output buffer is @var{dst} which must have 4345room for at least @var{length} octets. 4346@end deftypefun 4347 4348@subsubsection @acronym{PBKDF2-HMAC-SHA512} 4349 4350@deftypefun void pbkdf2_hmac_sha512 (size_t @var{key_length}, const uint8_t *@var{key}, unsigned @var{iterations}, size_t @var{salt_length}, const uint8_t *@var{salt}, size_t @var{length}, uint8_t *@var{dst}) 4351PBKDF2 with HMAC-SHA512. Derive @var{length} bytes of key into buffer 4352@var{dst} using the password @var{key} of length @var{key_length} and 4353salt @var{salt} of length @var{salt_length}, with iteration counter 4354@var{iterations} (> 0). The output buffer is @var{dst} which must have 4355room for at least @var{length} octets. 4356@end deftypefun 4357 4358@node Public-key algorithms, Randomness, Key derivation functions, Reference 4359@comment node-name, next, previous, up 4360@section Public-key algorithms 4361 4362Nettle uses @acronym{GMP}, the GNU bignum library, for all calculations 4363with large numbers. In order to use the public-key features of Nettle, 4364you must install @acronym{GMP}, at least version 3.0, before compiling 4365Nettle, and you need to link your programs with @code{-lhogweed -lnettle 4366-lgmp}. 4367 4368The concept of @dfn{Public-key} encryption and digital signatures was 4369discovered by Whitfield Diffie and Martin E. Hellman and described in a 4370paper 1976. In traditional, ``symmetric'', cryptography, sender and 4371receiver share the same keys, and these keys must be distributed in a 4372secure way. And if there are many users or entities that need to 4373communicate, each @emph{pair} needs a shared secret key known by nobody 4374else. 4375 4376@cindex Public Key Cryptography 4377@cindex One-way function 4378 4379Public-key cryptography uses trapdoor one-way functions. A 4380@dfn{one-way function} is a function @code{F} such that it is easy to 4381compute the value @code{F(x)} for any @code{x}, but given a value 4382@code{y}, it is hard to compute a corresponding @code{x} such that 4383@code{y = F(x)}. Two examples are cryptographic hash functions, and 4384exponentiation in certain groups. 4385 4386A @dfn{trapdoor one-way function} is a function @code{F} that is 4387one-way, unless one knows some secret information about @code{F}. If one 4388knows the secret, it is easy to compute both @code{F} and it's inverse. 4389If this sounds strange, look at the @acronym{RSA} example below. 4390 4391Two important uses for one-way functions with trapdoors are public-key 4392encryption, and digital signatures. The public-key encryption functions 4393in Nettle are not yet documented; the rest of this chapter is about 4394digital signatures. 4395 4396To use a digital signature algorithm, one must first create a 4397@dfn{key-pair}: A public key and a corresponding private key. The private 4398key is used to sign messages, while the public key is used for verifying 4399that that signatures and messages match. Some care must be taken when 4400distributing the public key; it need not be kept secret, but if a bad 4401guy is able to replace it (in transit, or in some user's list of known 4402public keys), bad things may happen. 4403 4404There are two operations one can do with the keys. The signature 4405operation takes a message and a private key, and creates a signature for 4406the message. A signature is some string of bits, usually at most a few 4407thousand bits or a few hundred octets. Unlike paper-and-ink signatures, 4408the digital signature depends on the message, so one can't cut it out of 4409context and glue it to a different message. 4410 4411The verification operation takes a public key, a message, and a string 4412that is claimed to be a signature on the message, and returns true or 4413false. If it returns true, that means that the three input values 4414matched, and the verifier can be sure that someone went through with the 4415signature operation on that very message, and that the ``someone'' also 4416knows the private key corresponding to the public key. 4417 4418The desired properties of a digital signature algorithm are as follows: 4419Given the public key and pairs of messages and valid signatures on them, 4420it should be hard to compute the private key, and it should also be hard 4421to create a new message and signature that is accepted by the 4422verification operation. 4423 4424Besides signing meaningful messages, digital signatures can be used for 4425authorization. A server can be configured with a public key, such that 4426any client that connects to the service is given a random nonce message. 4427If the server gets a reply with a correct signature matching the nonce 4428message and the configured public key, the client is granted access. So 4429the configuration of the server can be understood as ``grant access to 4430whoever knows the private key corresponding to this particular public 4431key, and to no others''. 4432 4433 4434@menu 4435* RSA:: The RSA public key algorithm. 4436* DSA:: The DSA digital signature algorithm. 4437* Elliptic curves:: Elliptic curves and ECDSA 4438@end menu 4439 4440@node RSA, DSA, Public-key algorithms, Public-key algorithms 4441@comment node-name, next, previous, up 4442@subsection @acronym{RSA} 4443 4444The @acronym{RSA} algorithm was the first practical digital signature 4445algorithm that was constructed. It was described 1978 in a paper by 4446Ronald Rivest, Adi Shamir and L.M. Adleman, and the technique was also 4447patented in the @acronym{USA} in 1983. The patent expired on September 20, 2000, and since 4448that day, @acronym{RSA} can be used freely, even in the @acronym{USA}. 4449 4450It's remarkably simple to describe the trapdoor function behind 4451@acronym{RSA}. The ``one-way''-function used is 4452 4453@example 4454F(x) = x^e mod n 4455@end example 4456 4457I.e. raise x to the @code{e}'th power, while discarding all multiples of 4458@code{n}. The pair of numbers @code{n} and @code{e} is the public key. 4459@code{e} can be quite small, even @code{e = 3} has been used, although 4460slightly larger numbers are recommended. @code{n} should be about 2000 4461bits or larger. 4462 4463If @code{n} is large enough, and properly chosen, the inverse of F, 4464the computation of @code{e}'th roots modulo @code{n}, is very difficult. 4465But, where's the trapdoor? 4466 4467Let's first look at how @acronym{RSA} key-pairs are generated. First 4468@code{n} is chosen as the product of two large prime numbers @code{p} 4469and @code{q} of roughly the same size (so if @code{n} is 2000 bits, 4470@code{p} and @code{q} are about 1000 bits each). One also computes the 4471number @code{phi = (p-1)(q-1)}, in mathematical speak, @code{phi} is the 4472order of the multiplicative group of integers modulo n. 4473 4474Next, @code{e} is chosen. It must have no factors in common with @code{phi} (in 4475particular, it must be odd), but can otherwise be chosen more or less 4476randomly. @code{e = 65537} is a popular choice, because it makes raising 4477to the @code{e}'th power particularly efficient, and being prime, it 4478usually has no factors common with @code{phi}. 4479 4480Finally, a number @code{d}, @code{d < n} is computed such that @code{e d 4481mod phi = 1}. It can be shown that such a number exists (this is why 4482@code{e} and @code{phi} must have no common factors), and that for all x, 4483 4484@example 4485(x^e)^d mod n = x^(ed) mod n = (x^d)^e mod n = x 4486@end example 4487 4488Using Euclid's algorithm, @code{d} can be computed quite easily from 4489@code{phi} and @code{e}. But it is still hard to get @code{d} without 4490knowing @code{phi}, which depends on the factorization of @code{n}. 4491 4492So @code{d} is the trapdoor, if we know @code{d} and @code{y = F(x)}, we can 4493recover x as @code{y^d mod n}. @code{d} is also the private half of 4494the @acronym{RSA} key-pair. 4495 4496The most common signature operation for @acronym{RSA} is defined in 4497@cite{PKCS#1}, a specification by RSA Laboratories. The message to be 4498signed is first hashed using a cryptographic hash function, e.g. 4499@acronym{MD5} or @acronym{SHA1}. Next, some padding, the @acronym{ASN.1} 4500``Algorithm Identifier'' for the hash function, and the message digest 4501itself, are concatenated and converted to a number @code{x}. The 4502signature is computed from @code{x} and the private key as @code{s = x^d 4503mod n}@footnote{Actually, the computation is not done like this, it is 4504done more efficiently using @code{p}, @code{q} and the Chinese remainder 4505theorem (@acronym{CRT}). But the result is the same.}. The signature, @code{s} is a 4506number of about the same size of @code{n}, and it usually encoded as a 4507sequence of octets, most significant octet first. 4508 4509The verification operation is straight-forward, @code{x} is computed 4510from the message in the same way as above. Then @code{s^e mod n} is 4511computed, the operation returns true if and only if the result equals 4512@code{x}. 4513 4514The @acronym{RSA} algorithm can also be used for encryption. RSA encryption uses 4515the public key @code{(n,e)} to compute the ciphertext @code{m^e mod n}. 4516The @cite{PKCS#1} padding scheme will use at least 8 random and non-zero 4517octets, using @var{m} of the form @code{[00 02 padding 00 plaintext]}. 4518It is required that @code{m < n}, and therefor the plaintext must be 4519smaller than the octet size of the modulo @code{n}, with some margin. 4520 4521To decrypt the message, one needs the private key to compute @code{m = 4522c^e mod n} followed by checking and removing the padding. 4523 4524@subsubsection Nettle's @acronym{RSA} support 4525 4526Nettle represents @acronym{RSA} keys using two structures that contain 4527large numbers (of type @code{mpz_t}). 4528 4529@deftp {Context struct} {rsa_public_key} size n e 4530@code{size} is the size, in octets, of the modulo, and is used internally. 4531@code{n} and @code{e} is the public key. 4532@end deftp 4533 4534@deftp {Context struct} {rsa_private_key} size d p q a b c 4535@code{size} is the size, in octets, of the modulo, and is used internally. 4536@code{d} is the secret exponent, but it is not actually used when 4537signing. Instead, the factors @code{p} and @code{q}, and the parameters 4538@code{a}, @code{b} and @code{c} are used. They are computed from @code{p}, 4539@code{q} and @code{e} such that @code{a e mod (p - 1) = 1, b e mod (q - 45401) = 1, c q mod p = 1}. 4541@end deftp 4542 4543Before use, these structs must be initialized by calling one of 4544 4545@deftypefun void rsa_public_key_init (struct rsa_public_key *@var{pub}) 4546@deftypefunx void rsa_private_key_init (struct rsa_private_key *@var{key}) 4547Calls @code{mpz_init} on all numbers in the key struct. 4548@end deftypefun 4549 4550and when finished with them, the space for the numbers must be 4551deallocated by calling one of 4552 4553@deftypefun void rsa_public_key_clear (struct rsa_public_key *@var{pub}) 4554@deftypefunx void rsa_private_key_clear (struct rsa_private_key *@var{key}) 4555Calls @code{mpz_clear} on all numbers in the key struct. 4556@end deftypefun 4557 4558In general, Nettle's @acronym{RSA} functions deviates from Nettle's ``no 4559memory allocation''-policy. Space for all the numbers, both in the key structs 4560above, and temporaries, are allocated dynamically. For information on how 4561to customize allocation, see 4562@xref{Custom Allocation,,GMP Allocation,gmp, GMP Manual}. 4563 4564When you have assigned values to the attributes of a key, you must call 4565 4566@deftypefun int rsa_public_key_prepare (struct rsa_public_key *@var{pub}) 4567@deftypefunx int rsa_private_key_prepare (struct rsa_private_key *@var{key}) 4568Computes the octet size of the key (stored in the @code{size} attribute, 4569and may also do other basic sanity checks. Returns one if successful, or 4570zero if the key can't be used, for instance if the modulo is smaller 4571than the minimum size needed for @acronym{RSA} operations specified by PKCS#1. 4572@end deftypefun 4573 4574For each operation using the private key, there are two variants, e.g., 4575@code{rsa_sha256_sign} and @code{rsa_sha256_sign_tr}. The former 4576function is older, and it should be avoided, because it provides no 4577defenses against side-channel attacks. The latter function use 4578randomized @acronym{RSA} blinding, which defends against timing attacks 4579using chosen-ciphertext, and it also checks the correctness of the 4580private key computation using the public key, which defends against 4581software or hardware errors which could leak the private key. 4582 4583Before signing or verifying a message, you first hash it with the 4584appropriate hash function. You pass the hash function's context struct 4585to the @acronym{RSA} signature function, and it will extract the message 4586digest and do the rest of the work. There are also alternative functions 4587that take the hash digest as argument. 4588 4589There is currently no support for using SHA224 or SHA384 with 4590@acronym{RSA} signatures, since there's no gain in either computation 4591time nor message size compared to using SHA256 and SHA512, respectively. 4592 4593Creating an @acronym{RSA} signature is done with one of the following 4594functions: 4595 4596@deftypefun int rsa_md5_sign_tr(const struct rsa_public_key *@var{pub}, const struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, struct md5_ctx *@var{hash}, mpz_t @var{signature}) 4597@deftypefunx int rsa_sha1_sign_tr(const struct rsa_public_key *@var{pub}, const struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, struct sha1_ctx *@var{hash}, mpz_t @var{signature}) 4598@deftypefunx int rsa_sha256_sign_tr(const struct rsa_public_key *@var{pub}, const struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, struct sha256_ctx *@var{hash}, mpz_t @var{signature}) 4599@deftypefunx int rsa_sha512_sign_tr(const struct rsa_public_key *@var{pub}, const struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, struct sha512_ctx *@var{hash}, mpz_t @var{signature}) 4600The signature is stored in @var{signature} (which must have been 4601@code{mpz_init}'ed earlier). The hash context is reset so that it can be 4602used for new messages. The @var{random_ctx} and @var{random} pointers 4603are used to generate the @acronym{RSA} blinding. Returns one on success, 4604or zero on failure. Signing fails if an error in the computation was 4605detected, or if the key is too small for the given hash size, e.g., it's 4606not possible to create a signature using SHA512 and a 512-bit 4607@acronym{RSA} key. 4608@end deftypefun 4609 4610@deftypefun int rsa_md5_sign_digest_tr(const struct rsa_public_key *@var{pub}, const struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, const uint8_t *@var{digest}, mpz_t @var{signature}) 4611@deftypefunx int rsa_sha1_sign_digest_tr(const struct rsa_public_key *@var{pub}, const struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, const uint8_t *@var{digest}, mpz_t @var{signature}) 4612@deftypefunx int rsa_sha256_sign_digest_tr(const struct rsa_public_key *@var{pub}, const struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, const uint8_t *@var{digest}, mpz_t @var{signature}) 4613@deftypefunx int rsa_sha512_sign_digest_tr(const struct rsa_public_key *@var{pub}, const struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, const uint8_t *@var{digest}, mpz_t @var{signature}) 4614Creates a signature from the given hash digest. @var{digest} should 4615point to a digest of size @code{MD5_DIGEST_SIZE}, 4616@code{SHA1_DIGEST_SIZE}, @code{SHA256_DIGEST_SIZE}, or 4617@code{SHA512_DIGEST_SIZE}respectively. The signature is stored in 4618@var{signature} (which must have been @code{mpz_init}:ed earlier). 4619Returns one on success, or zero on failure. 4620@end deftypefun 4621 4622@deftypefun int rsa_pkcs1_sign_tr(const struct rsa_public_key *@var{pub}, const struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, size_t @var{length}, const uint8_t *@var{digest_info}, mpz_t @var{signature}) 4623Similar to the above @code{_sign_digest_tr} functions, but the input is not the 4624plain hash digest, but a PKCS#1 ``DigestInfo'', an ASN.1 DER-encoding 4625of the digest together with an object identifier for the used hash 4626algorithm. 4627@end deftypefun 4628 4629@deftypefun int rsa_md5_sign (const struct rsa_private_key *@var{key}, struct md5_ctx *@var{hash}, mpz_t @var{signature}) 4630@deftypefunx int rsa_sha1_sign (const struct rsa_private_key *@var{key}, struct sha1_ctx *@var{hash}, mpz_t @var{signature}) 4631@deftypefunx int rsa_sha256_sign (const struct rsa_private_key *@var{key}, struct sha256_ctx *@var{hash}, mpz_t @var{signature}) 4632@deftypefunx int rsa_sha512_sign (const struct rsa_private_key *@var{key}, struct sha512_ctx *@var{hash}, mpz_t @var{signature}) 4633The signature is stored in @var{signature} (which must have been 4634@code{mpz_init}'ed earlier). The hash context is reset so that it can be 4635used for new messages. Returns one on success, or zero on failure. 4636Signing fails if the key is too small for the given hash size, e.g., 4637it's not possible to create a signature using SHA512 and a 512-bit 4638@acronym{RSA} key. 4639@end deftypefun 4640 4641@deftypefun int rsa_md5_sign_digest (const struct rsa_private_key *@var{key}, const uint8_t *@var{digest}, mpz_t @var{signature}) 4642@deftypefunx int rsa_sha1_sign_digest (const struct rsa_private_key *@var{key}, const uint8_t *@var{digest}, mpz_t @var{signature}); 4643@deftypefunx int rsa_sha256_sign_digest (const struct rsa_private_key *@var{key}, const uint8_t *@var{digest}, mpz_t @var{signature}); 4644@deftypefunx int rsa_sha512_sign_digest (const struct rsa_private_key *@var{key}, const uint8_t *@var{digest}, mpz_t @var{signature}); 4645Creates a signature from the given hash digest; otherwise analoguous to 4646the above signing functions. @var{digest} should point to a digest of 4647size @code{MD5_DIGEST_SIZE}, @code{SHA1_DIGEST_SIZE}, 4648@code{SHA256_DIGEST_SIZE}, or @code{SHA512_DIGEST_SIZE}, respectively. 4649The signature is stored in @var{signature} (which must have been 4650@code{mpz_init}:ed earlier). Returns one on success, or zero on failure. 4651@end deftypefun 4652 4653@deftypefun int rsa_pkcs1_sign(const struct rsa_private_key *@var{key}, size_t @var{length}, const uint8_t *@var{digest_info}, mpz_t @var{s}) 4654Similar to the above _sign_digest functions, but the input is not the 4655plain hash digest, but a PKCS#1 ``DigestInfo'', an ASN.1 DER-encoding 4656of the digest together with an object identifier for the used hash 4657algorithm. 4658@end deftypefun 4659 4660Verifying an RSA signature is done with one of the following functions: 4661 4662@deftypefun int rsa_md5_verify (const struct rsa_public_key *@var{key}, struct md5_ctx *@var{hash}, const mpz_t @var{signature}) 4663@deftypefunx int rsa_sha1_verify (const struct rsa_public_key *@var{key}, struct sha1_ctx *@var{hash}, const mpz_t @var{signature}) 4664@deftypefunx int rsa_sha256_verify (const struct rsa_public_key *@var{key}, struct sha256_ctx *@var{hash}, const mpz_t @var{signature}) 4665@deftypefunx int rsa_sha512_verify (const struct rsa_public_key *@var{key}, struct sha512_ctx *@var{hash}, const mpz_t @var{signature}) 4666Returns 1 if the signature is valid, or 0 if it isn't. In either case, 4667the hash context is reset so that it can be used for new messages. 4668@end deftypefun 4669 4670@deftypefun int rsa_md5_verify_digest (const struct rsa_public_key *@var{key}, const uint8_t *@var{digest}, const mpz_t @var{signature}) 4671@deftypefunx int rsa_sha1_verify_digest (const struct rsa_public_key *@var{key}, const uint8_t *@var{digest}, const mpz_t @var{signature}) 4672@deftypefunx int rsa_sha256_verify_digest (const struct rsa_public_key *@var{key}, const uint8_t *@var{digest}, const mpz_t @var{signature}) 4673@deftypefunx int rsa_sha512_verify_digest (const struct rsa_public_key *@var{key}, const uint8_t *@var{digest}, const mpz_t @var{signature}) 4674Returns 1 if the signature is valid, or 0 if it isn't. @var{digest} 4675should point to a digest of size @code{MD5_DIGEST_SIZE}, 4676@code{SHA1_DIGEST_SIZE}, @code{SHA256_DIGEST_SIZE}, or 4677@code{SHA512_DIGEST_SIZE} respectively. 4678@end deftypefun 4679 4680@deftypefun int rsa_pkcs1_verify(const struct rsa_public_key *@var{key}, size_t @var{length}, const uint8_t *@var{digest_info}, const mpz_t @var{signature}) 4681Similar to the above _verify_digest functions, but the input is not the 4682plain hash digest, but a PKCS#1 ``DigestInfo'', and ASN.1 DER-encoding 4683of the digest together with an object identifier for the used hash 4684algorithm. 4685@end deftypefun 4686 4687While the above functions for the RSA signature operations use the 4688@cite{PKCS#1} padding scheme, Nettle also provides the variants based on 4689the PSS padding scheme, specified in @cite{RFC 3447}. These variants 4690take advantage of a randomly choosen salt value, which could enhance the 4691security by causing output to be different for equivalent inputs. 4692However, assuming the same security level as inverting the @acronym{RSA} 4693algorithm, a longer salt value does not always mean a better security 4694@uref{http://www.iacr.org/archive/eurocrypt2002/23320268/coron.pdf}. 4695The typical choices of the length are between 0 and the digest size of 4696the underlying hash function. 4697 4698Creating an RSA signature with the PSS padding scheme is done with one 4699of the following functions: 4700 4701@deftypefun int rsa_pss_sha256_sign_digest_tr(const struct rsa_public_key *@var{pub}, const struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, size_t @var{salt_length}, const uint8_t *@var{salt}, const uint8_t *@var{digest}, mpz_t @var{signature}) 4702@deftypefunx int rsa_pss_sha384_sign_digest_tr(const struct rsa_public_key *@var{pub}, const struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, size_t @var{salt_length}, const uint8_t *@var{salt}, const uint8_t *@var{digest}, mpz_t @var{signature}) 4703@deftypefunx int rsa_pss_sha512_sign_digest_tr(const struct rsa_public_key *@var{pub}, const struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, size_t @var{salt_length}, const uint8_t *@var{salt}, const uint8_t *@var{digest}, mpz_t @var{signature}) 4704Creates a signature using the PSS padding scheme. @var{salt} should 4705point to a salt string of size @var{salt_length}. @var{digest} should 4706point to a digest of size @code{SHA256_DIGEST_SIZE}, 4707@code{SHA384_DIGEST_SIZE}, or @code{SHA512_DIGEST_SIZE}respectively. The 4708signature is stored in @var{signature} (which must have been 4709@code{mpz_init}:ed earlier). 4710Returns one on success, or zero on failure. 4711@end deftypefun 4712 4713Verifying an RSA signature with the PSS padding scheme is done with one 4714of the following functions: 4715 4716@deftypefun int rsa_pss_sha256_verify_digest (const struct rsa_public_key *@var{key}, size_t @var{salt_length}, const uint8_t *@var{digest}, const mpz_t @var{signature}) 4717@deftypefunx int rsa_pss_sha384_verify_digest (const struct rsa_public_key *@var{key}, size_t @var{salt_length}, const uint8_t *@var{digest}, const mpz_t @var{signature}) 4718@deftypefunx int rsa_pss_sha512_verify_digest (const struct rsa_public_key *@var{key}, size_t @var{salt_length}, const uint8_t *@var{digest}, const mpz_t @var{signature}) 4719Returns 1 if the signature is valid, or 0 if it isn't. @var{digest} 4720should point to a digest of size @code{SHA256_DIGEST_SIZE}, 4721@code{SHA384_DIGEST_SIZE}, or @code{SHA512_DIGEST_SIZE} respectively. 4722@end deftypefun 4723 4724The following function is used to encrypt a clear text message using RSA. 4725@deftypefun int rsa_encrypt (const struct rsa_public_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, size_t @var{length}, const uint8_t *@var{cleartext}, mpz_t @var{ciphertext}) 4726Returns 1 on success, 0 on failure. If the message is too long then this 4727will lead to a failure. 4728@end deftypefun 4729The following function is used to decrypt a cipher text message using RSA. 4730@deftypefun int rsa_decrypt (const struct rsa_private_key *@var{key}, size_t *@var{length}, uint8_t *@var{cleartext}, const mpz_t @var{ciphertext}) 4731Returns 1 on success, 0 on failure. Causes of failure include decryption 4732failing or the resulting message being to large. The message buffer 4733pointed to by @var{cleartext} must be of size *@var{length}. After 4734decryption, *@var{length} will be updated with the size of the 4735message. 4736@end deftypefun 4737There is also a timing resistant version of decryption that utilizes 4738randomized RSA blinding. 4739@deftypefun int rsa_decrypt_tr (const struct rsa_public_key *@var{pub}, const struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, size_t *@var{length}, uint8_t *@var{message}, const mpz_t @var{ciphertext}) 4740Returns 1 on success, 0 on failure. 4741@end deftypefun 4742 4743If you need to use the @acronym{RSA} trapdoor, the private key, in a way 4744that isn't supported by the above functions Nettle also includes a 4745function that computes @code{x^d mod n} and nothing more, using the 4746@acronym{CRT} optimization. 4747 4748@deftypefun int rsa_compute_root_tr(const struct rsa_public_key *@var{pub}, const struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, mpz_t @var{x}, const mpz_t @var{m}) 4749Computes @code{x = m^d}. Returns one on success, or zero if a failure in 4750the computation was detected. 4751@end deftypefun 4752 4753@deftypefun void rsa_compute_root (struct rsa_private_key *@var{key}, mpz_t @var{x}, const mpz_t @var{m}) 4754Computes @code{x = m^d}. 4755@end deftypefun 4756 4757At last, how do you create new keys? 4758 4759@deftypefun int rsa_generate_keypair (struct rsa_public_key *@var{pub}, struct rsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func @var{random}, void *@var{progress_ctx}, nettle_progress_func @var{progress}, unsigned @var{n_size}, unsigned @var{e_size}); 4760There are lots of parameters. @var{pub} and @var{key} is where the 4761resulting key pair is stored. The structs should be initialized, but you 4762don't need to call @code{rsa_public_key_prepare} or 4763@code{rsa_private_key_prepare} after key generation. 4764 4765@var{random_ctx} and @var{random} is a randomness generator. 4766@code{random(random_ctx, length, dst)} should generate @code{length} 4767random octets and store them at @code{dst}. For advice, see 4768@xref{Randomness}. 4769 4770@var{progress} and @var{progress_ctx} can be used to get callbacks 4771during the key generation process, in order to uphold an illusion of 4772progress. @var{progress} can be NULL, in that case there are no 4773callbacks. 4774 4775@var{size_n} is the desired size of the modulo, in bits. If @var{size_e} 4776is non-zero, it is the desired size of the public exponent and a random 4777exponent of that size is selected. But if @var{e_size} is zero, it is 4778assumed that the caller has already chosen a value for @code{e}, and 4779stored it in @var{pub}. 4780Returns one on success, and zero on failure. The function can fail for 4781example if if @var{n_size} is too small, or if @var{e_size} is zero and 4782@code{pub->e} is an even number. 4783@end deftypefun 4784 4785@node DSA, Elliptic curves, RSA, Public-key algorithms 4786@comment node-name, next, previous, up 4787@subsection @acronym{DSA} 4788 4789The @acronym{DSA} digital signature algorithm is more complex than 4790@acronym{RSA}. It was specified during the early 1990s, and in 1994 NIST 4791published @acronym{FIPS} 186 which is the authoritative specification. 4792Sometimes @acronym{DSA} is referred to using the acronym @acronym{DSS}, 4793for Digital Signature Standard. The most recent revision of the 4794specification, FIPS186-3, was issued in 2009, and it adds support for 4795larger hash functions than @acronym{sha1}. 4796 4797For @acronym{DSA}, the underlying mathematical problem is the 4798computation of discrete logarithms. The public key consists of a large 4799prime @code{p}, a small prime @code{q} which is a factor of @code{p-1}, 4800a number @code{g} which generates a subgroup of order @code{q} modulo 4801@code{p}, and an element @code{y} in that subgroup. 4802 4803In the original @acronym{DSA}, the size of @code{q} is fixed to 160 4804bits, to match with the @acronym{SHA1} hash algorithm. The size of 4805@code{p} is in principle unlimited, but the 4806standard specifies only nine specific sizes: @code{512 + l*64}, where 4807@code{l} is between 0 and 8. Thus, the maximum size of @code{p} is 1024 4808bits, and sizes less than 1024 bits are considered obsolete and not 4809secure. 4810 4811The subgroup requirement means that if you compute 4812 4813@example 4814g^t mod p 4815@end example 4816 4817for all possible integers @code{t}, you will get precisely @code{q} 4818distinct values. 4819 4820The private key is a secret exponent @code{x}, such that 4821 4822@example 4823g^x = y mod p 4824@end example 4825 4826In mathematical speak, @code{x} is the @dfn{discrete logarithm} of 4827@code{y} mod @code{p}, with respect to the generator @code{g}. The size 4828of @code{x} will also be about the same size as @code{q}. The security of the 4829@acronym{DSA} algorithm relies on the difficulty of the discrete 4830logarithm problem. Current algorithms to compute discrete logarithms in 4831this setting, and hence crack @acronym{DSA}, are of two types. The first 4832type works directly in the (multiplicative) group of integers mod 4833@code{p}. The best known algorithm of this type is the Number Field 4834Sieve, and it's complexity is similar to the complexity of factoring 4835numbers of the same size as @code{p}. The other type works in the 4836smaller @code{q}-sized subgroup generated by @code{g}, which has a more 4837difficult group structure. One good algorithm is Pollard-rho, which has 4838complexity @code{sqrt(q)}. 4839 4840The important point is that security depends on the size of @emph{both} 4841@code{p} and @code{q}, and they should be chosen so that the difficulty 4842of both discrete logarithm methods are comparable. Today, the security 4843margin of the original @acronym{DSA} may be uncomfortably small. Using a 4844@code{p} of 1024 bits implies that cracking using the number field sieve 4845is expected to take about the same time as factoring a 1024-bit 4846@acronym{RSA} modulo, and using a @code{q} of size 160 bits implies 4847that cracking using Pollard-rho will take roughly @code{2^80} group 4848operations. With the size of @code{q} fixed, tied to the @acronym{SHA1} 4849digest size, it may be tempting to increase the size of @code{p} to, 4850say, 4096 bits. This will provide excellent resistance against attacks 4851like the number field sieve which works in the large group. But it will 4852do very little to defend against Pollard-rho attacking the small 4853subgroup; the attacker is slowed down at most by a single factor of 10 4854due to the more expensive group operation. And the attacker will surely 4855choose the latter attack. 4856 4857The signature generation algorithm is randomized; in order to create a 4858@acronym{DSA} signature, you need a good source for random numbers 4859(@pxref{Randomness}). Let us describe the common case of a 160-bit 4860@code{q}. 4861 4862To create a signature, one starts with the hash digest of the message, 4863@code{h}, which is a 160 bit number, and a random number @code{k, 48640<k<q}, also 160 bits. Next, one computes 4865 4866@example 4867r = (g^k mod p) mod q 4868s = k^-1 (h + x r) mod q 4869@end example 4870 4871The signature is the pair @code{(r, s)}, two 160 bit numbers. Note the 4872two different mod operations when computing @code{r}, and the use of the 4873secret exponent @code{x}. 4874 4875To verify a signature, one first checks that @code{0 < r,s < q}, and 4876then one computes backwards, 4877 4878@example 4879w = s^-1 mod q 4880v = (g^(w h) y^(w r) mod p) mod q 4881@end example 4882 4883The signature is valid if @code{v = r}. This works out because @code{w = 4884s^-1 mod q = k (h + x r)^-1 mod q}, so that 4885 4886@example 4887g^(w h) y^(w r) = g^(w h) (g^x)^(w r) = g^(w (h + x r)) = g^k 4888@end example 4889 4890When reducing mod @code{q} this yields @code{r}. Note that when 4891verifying a signature, we don't know either @code{k} or @code{x}: those 4892numbers are secret. 4893 4894If you can choose between @acronym{RSA} and @acronym{DSA}, which one is 4895best? Both are believed to be secure. @acronym{DSA} gained popularity in 4896the late 1990s, as a patent free alternative to @acronym{RSA}. Now that 4897the @acronym{RSA} patents have expired, there's no compelling reason to 4898want to use @acronym{DSA}. Today, the original @acronym{DSA} key size 4899does not provide a large security margin, and it should probably be 4900phased out together with @acronym{RSA} keys of 1024 bits. Using the 4901revised @acronym{DSA} algorithm with a larger hash function, in 4902particular, @acronym{SHA256}, a 256-bit @code{q}, and @code{p} of size 49032048 bits or more, should provide for a more comfortable security 4904margin, but these variants are not yet in wide use. 4905 4906@acronym{DSA} signatures are smaller than @acronym{RSA} signatures, 4907which is important for some specialized applications. 4908 4909From a practical point of view, @acronym{DSA}'s need for a good 4910randomness source is a serious disadvantage. If you ever use the same 4911@code{k} (and @code{r}) for two different message, you leak your private 4912key. 4913 4914@subsubsection Nettle's @acronym{DSA} support 4915 4916Like for @acronym{RSA}, Nettle represents @acronym{DSA} keys using two 4917structures, containing values of type @code{mpz_t}. For information on 4918how to customize allocation, see @xref{Custom Allocation,,GMP 4919Allocation,gmp, GMP Manual}. Nettle's @acronym{DSA} interface is defined 4920in @file{<nettle/dsa.h>}. 4921 4922A @acronym{DSA} group is represented using the following struct. 4923 4924@deftp {Context struct} {dsa_params} p q g 4925Parameters of the @acronym{DSA} group. 4926@end deftp 4927 4928@deftypefun void dsa_params_init (struct dsa_params *@var{params}) 4929Calls @code{mpz_init} on all numbers in the struct. 4930@end deftypefun 4931 4932@deftypefun void dsa_params_clear (struct dsa_params *@var{params}params) 4933Calls @code{mpz_clear} on all numbers in the struct. 4934@end deftypefun 4935 4936@deftypefun int dsa_generate_params (struct dsa_params *@var{params}, void *@var{random_ctx}, nettle_random_func *@var{random}, void *@var{progress_ctx}, nettle_progress_func *@var{progress}, unsigned @var{p_bits}, unsigned @var{q_bits}) 4937Generates parameters of a new group. The @var{params} struct should be 4938initialized before you call this function. 4939 4940@var{random_ctx} and @var{random} is a randomness generator. 4941@code{random(random_ctx, length, dst)} should generate @code{length} 4942random octets and store them at @code{dst}. For advice, see 4943@xref{Randomness}. 4944 4945@var{progress} and @var{progress_ctx} can be used to get callbacks 4946during the key generation process, in order to uphold an illusion of 4947progress. @var{progress} can be NULL, in that case there are no 4948callbacks. 4949 4950@var{p_bits} and @var{q_bits} are the desired sizes of @code{p} and 4951@code{q}. To generate keys that conform to the original @acronym{DSA} 4952standard, you must use @code{q_bits = 160} and select @var{p_bits} of 4953the form @code{p_bits = 512 + l*64}, for @code{0 <= l <= 8}, where the 4954smaller sizes are no longer recommended, so you should most likely stick 4955to @code{p_bits = 1024}. Non-standard sizes are possible, in particular 4956@code{p_bits} larger than 1024, although @acronym{DSA} implementations 4957can not in general be expected to support such keys. Also note that 4958using very large @var{p_bits}, with @var{q_bits} fixed at 160, doesn't 4959make much sense, because the security is also limited by the size of the 4960smaller prime. To generate @acronym{DSA} keys for use with 4961@acronym{SHA256}, use @code{q_bits = 256} and, e.g., @code{p_bits = 49622048}. 4963 4964Returns one on success, and zero on failure. The function will fail if 4965@var{q_bits} is too small, or too close to @var{p_bits}. 4966@end deftypefun 4967 4968Signatures are represented using the structure below. 4969 4970@deftp {Context struct} {dsa_signature} r s 4971@end deftp 4972 4973@deftypefun void dsa_signature_init (struct dsa_signature *@var{signature}) 4974@deftypefunx void dsa_signature_clear (struct dsa_signature *@var{signature}) 4975You must call @code{dsa_signature_init} before creating or using a 4976signature, and call @code{dsa_signature_clear} when you are finished 4977with it. 4978@end deftypefun 4979 4980Keys are represented as bignums, of type @code{mpz_t}. A public key 4981represents a group element, and is of the same size as @code{p}, while a 4982private key is an exponent, of the same size as @code{q}. 4983 4984@deftypefun int dsa_sign (const struct dsa_params *@var{params}, const mpz_t @var{x}, void *@var{random_ctx}, nettle_random_func *@var{random}, size_t @var{digest_size}, const uint8_t *@var{digest}, struct dsa_signature *@var{signature}) 4985Creates a signature from the given hash digest, using the private key 4986@var{x}. @var{random_ctx} and @var{random} is a randomness generator. 4987@code{random(random_ctx, length, dst)} should generate @code{length} 4988random octets and store them at @code{dst}. For advice, see 4989@xref{Randomness}. Returns one on success, or zero on failure. Signing 4990can fail only if the key is invalid, so that inversion modulo @code{q} 4991fails. 4992@end deftypefun 4993 4994@deftypefun int dsa_verify (const struct dsa_params *@var{params}, const mpz_t @var{y}, size_t @var{digest_size}, const uint8_t *@var{digest}, const struct dsa_signature *@var{signature}) 4995Verifies a signature, using the public key y. Returns 1 if the signature 4996is valid, otherwise 0. 4997@end deftypefun 4998 4999To generate a keypair, first generate a @acronym{DSA} group using 5000@code{dsa_generate_params}. A keypair in this group is then created 5001using 5002 5003@deftypefun void dsa_generate_keypair (const struct dsa_params *@var{params}, mpz_t @var{pub}, mpz_t @var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}) 5004Generates a new keypair, using the group @var{params}. The public key is 5005stored in @var{pub}, and the private key in @var{key}. Both variables 5006must be initialized using @code{mpz_init} before this call. 5007 5008@var{random_ctx} and @var{random} is a randomness generator. 5009@code{random(random_ctx, length, dst)} should generate @code{length} 5010random octets and store them at @code{dst}. For advice, see 5011@xref{Randomness}. 5012@end deftypefun 5013 5014@subsubsection Old, deprecated, @acronym{DSA} interface 5015 5016Versions before nettle-3.0 used a different interface for @acronym{DSA} 5017signatures, where the group parameters and the public key was packed 5018together as @code{struct dsa_public_key}. Most of this interface is kept 5019for backwards compatibility, and declared in @file{nettle/dsa-compat.h}. 5020Below is the old documentation. The old and new interface use distinct 5021names and don't confict, with one exception: The key generation 5022function. The @file{nettle/dsa-compat.h} redefines 5023@code{dsa_generate_keypair} as an alias for 5024@code{dsa_compat_generate_keypair}, compatible with the old interface 5025and documented below. 5026 5027The old @acronym{DSA} functions are very similar to the corresponding 5028@acronym{RSA} functions, but there are a few differences pointed out 5029below. For a start, there are no functions corresponding to 5030@code{rsa_public_key_prepare} and @code{rsa_private_key_prepare}. 5031 5032@deftp {Context struct} {dsa_public_key} p q g y 5033The public parameters described above. 5034@end deftp 5035 5036@deftp {Context struct} {dsa_private_key} x 5037The private key @code{x}. 5038@end deftp 5039 5040Before use, these structs must be initialized by calling one of 5041 5042@deftypefun void dsa_public_key_init (struct dsa_public_key *@var{pub}) 5043@deftypefunx void dsa_private_key_init (struct dsa_private_key *@var{key}) 5044Calls @code{mpz_init} on all numbers in the key struct. 5045@end deftypefun 5046 5047When finished with them, the space for the numbers must be 5048deallocated by calling one of 5049 5050@deftypefun void dsa_public_key_clear (struct dsa_public_key *@var{pub}) 5051@deftypefunx void dsa_private_key_clear (struct dsa_private_key *@var{key}) 5052Calls @code{mpz_clear} on all numbers in the key struct. 5053@end deftypefun 5054 5055Signatures are represented using @code{struct dsa_signature}, described 5056earlier. 5057 5058For signing, you need to provide both the public and the private key 5059(unlike @acronym{RSA}, where the private key struct includes all 5060information needed for signing), and a source for random numbers. 5061Signatures can use the @acronym{SHA1} or the @acronym{SHA256} hash 5062function, although the implementation of @acronym{DSA} with 5063@acronym{SHA256} should be considered somewhat experimental due to lack 5064of official test vectors and interoperability testing. 5065 5066@deftypefun int dsa_sha1_sign (const struct dsa_public_key *@var{pub}, const struct dsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func @var{random}, struct sha1_ctx *@var{hash}, struct dsa_signature *@var{signature}) 5067@deftypefunx int dsa_sha1_sign_digest (const struct dsa_public_key *@var{pub}, const struct dsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func @var{random}, const uint8_t *@var{digest}, struct dsa_signature *@var{signature}) 5068@deftypefunx int dsa_sha256_sign (const struct dsa_public_key *@var{pub}, const struct dsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func @var{random}, struct sha256_ctx *@var{hash}, struct dsa_signature *@var{signature}) 5069@deftypefunx int dsa_sha256_sign_digest (const struct dsa_public_key *@var{pub}, const struct dsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func @var{random}, const uint8_t *@var{digest}, struct dsa_signature *@var{signature}) 5070Creates a signature from the given hash context or digest. 5071@var{random_ctx} and @var{random} is a randomness generator. 5072@code{random(random_ctx, length, dst)} should generate @code{length} 5073random octets and store them at @code{dst}. For advice, see 5074@xref{Randomness}. Returns one on success, or zero on failure. 5075Signing fails if the key size and the hash size don't match. 5076@end deftypefun 5077 5078Verifying signatures is a little easier, since no randomness generator is 5079needed. The functions are 5080 5081@deftypefun int dsa_sha1_verify (const struct dsa_public_key *@var{key}, struct sha1_ctx *@var{hash}, const struct dsa_signature *@var{signature}) 5082@deftypefunx int dsa_sha1_verify_digest (const struct dsa_public_key *@var{key}, const uint8_t *@var{digest}, const struct dsa_signature *@var{signature}) 5083@deftypefunx int dsa_sha256_verify (const struct dsa_public_key *@var{key}, struct sha256_ctx *@var{hash}, const struct dsa_signature *@var{signature}) 5084@deftypefunx int dsa_sha256_verify_digest (const struct dsa_public_key *@var{key}, const uint8_t *@var{digest}, const struct dsa_signature *@var{signature}) 5085Verifies a signature. Returns 1 if the signature is valid, otherwise 0. 5086@end deftypefun 5087 5088Key generation uses mostly the same parameters as the corresponding 5089@acronym{RSA} function. 5090 5091@deftypefun int dsa_compat_generate_keypair (struct dsa_public_key *@var{pub}, struct dsa_private_key *@var{key}, void *@var{random_ctx}, nettle_random_func @var{random}, void *@var{progress_ctx}, nettle_progress_func @var{progress}, unsigned @var{p_bits}, unsigned @var{q_bits}) 5092@var{pub} and @var{key} is where the resulting key pair is stored. The 5093structs should be initialized before you call this function. 5094 5095@var{random_ctx} and @var{random} is a randomness generator. 5096@code{random(random_ctx, length, dst)} should generate @code{length} 5097random octets and store them at @code{dst}. For advice, see 5098@xref{Randomness}. 5099 5100@var{progress} and @var{progress_ctx} can be used to get callbacks 5101during the key generation process, in order to uphold an illusion of 5102progress. @var{progress} can be NULL, in that case there are no 5103callbacks. 5104 5105@var{p_bits} and @var{q_bits} are the desired sizes of @code{p} and 5106@code{q}. See @code{dsa_generate_keypair} for details. 5107@end deftypefun 5108 5109@node Elliptic curves,, DSA, Public-key algorithms 5110@comment node-name, next, previous, up 5111@subsection @acronym{Elliptic curves} 5112 5113For cryptographic purposes, an elliptic curve is a mathematical group of 5114points, and computing logarithms in this group is computationally 5115difficult problem. Nettle uses additive notation for elliptic curve 5116groups. If @math{P} and @math{Q} are two points, and @math{k} is an 5117integer, the point sum, @math{P + Q}, and the multiple @math{k P} can be 5118computed efficiently, but given only two points @math{P} and @math{Q}, 5119finding an integer @math{k} such that @math{Q = k P} is the elliptic 5120curve discrete logarithm problem. 5121 5122Nettle supports standard curves which are all of the form @math{y^2 = 5123x^3 - 3 x + b @pmod{p}}, i.e., the points have coordinates @math{(x,y)}, 5124both considered as integers modulo a specified prime @math{p}. Curves 5125are represented as a @code{struct ecc_curve}. It also supports 5126curve25519, which uses a different form of curve. Supported curves are 5127declared in @file{<nettle/ecc-curve.h>}, e.g., call 5128@code{nettle_get_secp_256r1} for a standardized curve using the 256-bit 5129prime @math{p = 2^{256} - 2^{224} + 2^{192} + 2^{96} - 1}. The contents 5130of these structs is not visible to nettle users. The ``bitsize of the 5131curve'' is used as a shorthand for the bitsize of the curve's prime 5132@math{p}, e.g., 256 bits for the SECP 256R1 curve. 5133 5134@menu 5135* Side-channel silence:: 5136* ECDSA:: 5137* GOSTDSA:: 5138* Curve 25519 and Curve 448:: 5139@end menu 5140 5141@node Side-channel silence, ECDSA, , Elliptic curves 5142@comment node-name, next, previous, up 5143@subsubsection Side-channel silence 5144@cindex Side-channel attack 5145 5146Nettle's implementation of the elliptic curve operations is intended to 5147be side-channel silent. The side-channel attacks considered are: 5148 5149@itemize 5150@item Timing attacks 5151If the timing of operations depends on secret values, an attacker 5152interacting with your system can measure the response time, and infer 5153information about your secrets, e.g., a private signature key. 5154 5155@item Attacks using memory caches 5156Assume you have some secret data on a multi-user system, and that this 5157data is properly protected so that other users get no direct access to 5158it. If you have a process operating on the secret data, and this process 5159does memory accesses depending on the data, e.g, an internal lookup 5160table in some cryptographic algorithm, an attacker running a separate 5161process on the same system may use behavior of internal CPU caches to 5162get information about your secrets. This type of attack can even cross 5163virtual machine boundaries. 5164@end itemize 5165 5166Nettle's ECC implementation is designed to be @dfn{side-channel silent}, 5167and not leak any information to these attacks. Timing and memory 5168accesses depend only on the size of the input data and its location in 5169memory, not on the actual data bits. This implies a performance penalty 5170in several of the building blocks. 5171 5172@node ECDSA, GOSTDSA, Side-channel silence, Elliptic curves 5173@comment node-name, next, previous, up 5174@subsubsection ECDSA 5175 5176ECDSA is a variant of the DSA digital signature scheme (@pxref{DSA}), 5177which works over an elliptic curve group rather than over a (subgroup 5178of) integers modulo @math{p}. Like DSA, creating a signature requires a unique 5179random nonce (repeating the nonce with two different messages reveals 5180the private key, and any leak or bias in the generation of the nonce 5181also leaks information about the key). 5182 5183Unlike DSA, signatures are in general not tied to any particular hash 5184function or even hash size. Any hash function can be used, and the hash 5185value is truncated or padded as needed to get a size matching the curve 5186being used. It is recommended to use a strong cryptographic hash 5187function with digest size close to the bit size of the curve, e.g., 5188SHA256 is a reasonable choice when using ECDSA signature over the curve 5189secp256r1. A protocol or application using ECDSA has to specify which 5190curve and which hash function to use, or provide some mechanism for 5191negotiating. 5192 5193Nettle defines ECDSA in @file{<nettle/ecdsa.h>}. We first need 5194to define the data types used to represent public and private keys. 5195 5196@deftp {struct} {struct ecc_point} 5197Represents a point on an elliptic curve. In particular, it is used to 5198represent an ECDSA public key. 5199@end deftp 5200 5201@deftypefun void ecc_point_init (struct ecc_point *@var{p}, const struct ecc_curve *@var{ecc}) 5202Initializes @var{p} to represent points on the given curve @var{ecc}. 5203Allocates storage for the coordinates, using the same allocation 5204functions as GMP. 5205@end deftypefun 5206 5207@deftypefun void ecc_point_clear (struct ecc_point *@var{p}) 5208Deallocate storage. 5209@end deftypefun 5210 5211@deftypefun int ecc_point_set (struct ecc_point *@var{p}, const mpz_t @var{x}, const mpz_t @var{y}) 5212Check that the given coordinates represent a point on the curve. If so, 5213the coordinates are copied and converted to internal representation, and 5214the function returns 1. Otherwise, it returns 0. Currently, the 5215infinity point (or zero point, with additive notation) is not allowed. 5216@end deftypefun 5217 5218@deftypefun void ecc_point_get (const struct ecc_point *@var{p}, mpz_t @var{x}, mpz_t @var{y}) 5219Extracts the coordinate of the point @var{p}. The output parameters 5220@var{x} or @var{y} may be NULL if the caller doesn't want that 5221coordinate. 5222@end deftypefun 5223 5224@deftp {struct} {struct ecc_scalar} 5225Represents an integer in the range @math{0 < x < group order}, where the 5226``group order'' refers to the order of an ECC group. In particular, it 5227is used to represent an ECDSA private key. 5228@end deftp 5229 5230@deftypefun void ecc_scalar_init (struct ecc_scalar *@var{s}, const struct ecc_curve *@var{ecc}) 5231Initializes @var{s} to represent a scalar suitable for the given curve 5232@var{ecc}. Allocates storage using the same allocation functions as GMP. 5233@end deftypefun 5234 5235@deftypefun void ecc_scalar_clear (struct ecc_scalar *@var{s}) 5236Deallocate storage. 5237@end deftypefun 5238 5239@deftypefun int ecc_scalar_set (struct ecc_scalar *@var{s}, const mpz_t @var{z}) 5240Check that @var{z} is in the correct range. If so, copies the value to 5241@var{s} and returns 1, otherwise returns 0. 5242@end deftypefun 5243 5244@deftypefun void ecc_scalar_get (const struct ecc_scalar *@var{s}, mpz_t @var{z}) 5245Extracts the scalar, in GMP @code{mpz_t} representation. 5246@end deftypefun 5247 5248To create and verify ECDSA signatures, the following functions are used. 5249 5250@deftypefun void ecdsa_sign (const struct ecc_scalar *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, size_t @var{digest_length}, const uint8_t *@var{digest}, struct dsa_signature *@var{signature}) 5251Uses the private key @var{key} to create a signature on @var{digest}. 5252@var{random_ctx} and @var{random} is a randomness generator. 5253@code{random(random_ctx, length, dst)} should generate @code{length} 5254random octets and store them at @code{dst}. The signature is stored in 5255@var{signature}, in the same was as for plain DSA. 5256@end deftypefun 5257 5258@deftypefun int ecdsa_verify (const struct ecc_point *@var{pub}, size_t @var{length}, const uint8_t *@var{digest}, const struct dsa_signature *@var{signature}) 5259Uses the public key @var{pub} to verify that @var{signature} is a valid 5260signature for the message digest @var{digest} (of @var{length} octets). 5261Returns 1 if the signature is valid, otherwise 0. 5262@end deftypefun 5263 5264Finally, generating a new ECDSA key pair: 5265 5266@deftypefun void ecdsa_generate_keypair (struct ecc_point *@var{pub}, struct ecc_scalar *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}); 5267@var{pub} and @var{key} is where the resulting key pair is stored. The 5268structs should be initialized, for the desired ECC curve, before you call this function. 5269 5270@var{random_ctx} and @var{random} is a randomness generator. 5271@code{random(random_ctx, length, dst)} should generate @code{length} 5272random octets and store them at @code{dst}. For advice, see 5273@xref{Randomness}. 5274@end deftypefun 5275 5276@node GOSTDSA, Curve 25519 and Curve 448, ECDSA, Elliptic curves 5277@comment node-name, next, previous, up 5278@subsubsection GOSTDSA 5279@cindex GOST DSA 5280 5281GOSTDSA (GOST R 34.10-2001, GOST R 34.10-2012) is a variant of the DSA 5282(@pxref{DSA}) and ECDSA (@pxref{ECDSA}) digital signature schemes, which works 5283over an elliptic curve group. Original documents are written in Russian. 5284English translations are provided in @cite{RFC 5832} and @cite{RFC 7091}. 5285While technically nothing stops one from using GOSTDSA over any curve, it 5286is defined only over several 256 and 512-bit curves. Like DSA and ECDSA, 5287creating a signature requires a unique random nonce (repeating the nonce 5288with two different messages reveals the private key, and any leak or bias 5289in the generation of the nonce also leaks information about the key). 5290 5291GOST R 34.10-2001 was defined to use GOST R 34.11-94 hash function 5292(GOSTHASH94 and GOSTHASH94CP, @cite{RFC 5831}). GOST R 34.10-2012 is 5293defined to use GOST R 34.11-2012 hash function (Streebog, @cite{RFC 52946986}) of corresponding size (256 or 512) depending on curve size. 5295 5296Nettle defines GOSTDSA in @file{<nettle/gostdsa.h>}. GOSTDSA reuses ECDSA 5297data types (@code{struct ecc_point}, @code{struct ecc_scalar}) to 5298represent public and private keys. Also to generate a new GOSTDSA key 5299pair one has to use @code{ecdsa_generate_keypair()} function. 5300 5301To create and verify GOSTDSA signatures, the following functions are used. 5302 5303@deftypefun void gostdsa_sign (const struct ecc_scalar *@var{key}, void *@var{random_ctx}, nettle_random_func *@var{random}, size_t @var{digest_length}, const uint8_t *@var{digest}, struct dsa_signature *@var{signature}) 5304Uses the private key @var{key} to create a signature on @var{digest}. 5305@var{random_ctx} and @var{random} is a randomness generator. 5306@code{random(random_ctx, length, dst)} should generate @code{length} 5307random octets and store them at @code{dst}. The signature is stored in 5308@var{signature}, in the same was as for plain DSA. 5309@end deftypefun 5310 5311@deftypefun int gostdsa_verify (const struct ecc_point *@var{pub}, size_t @var{length}, const uint8_t *@var{digest}, const struct dsa_signature *@var{signature}) 5312Uses the public key @var{pub} to verify that @var{signature} is a valid 5313signature for the message digest @var{digest} (of @var{length} octets). 5314Returns 1 if the signature is valid, otherwise 0. 5315@end deftypefun 5316 5317For historical reason several curve IDs (OIDs) may correspond to a single 5318curve/generator combination. Following list defines correspondence 5319between nettle's view on curves and actual identifiers defined in @cite{RFC 53204357} and @cite{RFC 7836}. 5321 5322@deftypefun {const struct ecc_curve} nettle_get_gost_gc256b(void) 5323Returns curve corresponding to following identifiers: 5324@itemize 5325@item id-GostR3410-2001-CryptoPro-A-ParamSet (@cite{RFC 4357}) 5326@item id-GostR3410-2001-CryptoPro-XchA-ParamSet (@cite{RFC 4357}) 5327@item id-tc26-gost-3410-12-256-paramSetB 5328@end itemize 5329@end deftypefun 5330 5331@deftypefun {const struct ecc_curve} nettle_get_gost_gc512a(void) 5332Returns curve corresponding to following identifiers: 5333@itemize 5334@item id-tc26-gost-3410-12-512-paramSetA (@cite{RFC 7836}) 5335@end itemize 5336@end deftypefun 5337 5338For GOST key pairs key derivation/key agreement function (VKO) is defined in 5339@cite{RFC 4357} and @cite{RFC 7836}. Basically shared key is equal to 5340hash(cofactor * ukm * priv * pub). Nettle library provides a function that does 5341multiplication. Caller should do hashing on his own (it will be either 5342GOST R 34.11-94 (@pxref{GOSTHASH94CP}) or GOST R 34.11-2012, Streebog, which nor part of the library yet). 5343 5344@deftypefun void gostdsa_vko (const struct ecc_scalar *@var{priv}, const struct ecc_point *@var{pub}, size_t @var{ukm_length}, const uint8_t *@var{ukm}, uint8_t *@var{out}) 5345Uses private key @var{priv}, public ket @var{pub} and shared key material 5346@var{ukm} to generate shared secret, written to buffer @var{out}. The buffer 5347should be of the size equal to 2 private key lengths: 64 bytes for 256 bit 5348curves and 128 bytes for 512 bit ones. UKM is a shared key material, usually 5349transferred in cleartext. It does not have to be secret. 5350@end deftypefun 5351 5352@node Curve 25519 and Curve 448, , ECDSA, Elliptic curves 5353@comment node-name, next, previous, up 5354@subsubsection Curve25519 and Curve448 5355@cindex Curve 25519 5356@cindex Curve 448 5357 5358@c FIXME: Make 2^255 pretty in all output formats. Use @sup? 5359@c There are other places too (2^32, 2^130). 5360 5361Curve25519 is an elliptic curve of Montgomery type, @math{y^2 = x^3 + 5362486662 x^2 + x @pmod{p}}, with @math{p = 2^255 - 19}. Montgomery curves 5363have the advantage of simple and efficient point addition based on the 5364x-coordinate only. This particular curve was proposed by D. J. Bernstein 5365in 2006, for fast Diffie-Hellman key exchange, and is also described in 5366@cite{RFC 7748}. The group generator is defined by @math{x = 9} (there 5367are actually two points with @math{x = 9}, differing by the sign of the 5368y-coordinate, but that doesn't matter for the curve25519 operations 5369which work with the x-coordinate only). 5370 5371The curve25519 functions are defined as operations on octet strings, 5372representing 255-bit scalars or x-coordinates, in little-endian byte 5373order. The most significant input bit, i.e, the most significant bit of 5374the last octet, is always ignored. 5375 5376For scalars, in addition, the least significant three bits are ignored, 5377and treated as zero, and the second most significant bit is ignored too, 5378and treated as one. Then the scalar input string always represents 8 5379times a number in the range @math{2^251 <= s < 2^252}. 5380 5381Of all the possible input strings, only about half correspond to 5382x-coordinates of points on curve25519, i.e., a value @math{x} for which 5383the the curve equation can be solved for @math{y}. The other half 5384correspond to points on a related ``twist curve''. The function 5385@code{curve25519_mul} uses a Montgomery ladder for the scalar 5386multiplication, as suggested in the curve25519 literature, and required 5387by @cite{RFC 7748}. The output is therefore well defined for 5388@emph{all} possible inputs, no matter if the input string represents a 5389valid point on the curve or not. 5390 5391Note that the curve25519 implementation in earlier versions of Nettle 5392deviates slightly from @cite{RFC 7748}, in that bit 255 of the @math{x} 5393coordinate of the point input to curve25519_mul was not ignored. The 5394@file{nette/curve25519.h} defines a preprocessor symbol 5395@code{NETTLE_CURVE25519_RFC7748} to indicate conformance with the 5396standard. 5397 5398Nettle defines Curve 25519 in @file{<nettle/curve25519.h>}. 5399 5400@defvr Constant NETTLE_CURVE25519_RFC7748 5401Defined to 1 in Nettle versions conforming to RFC 7748. Undefined in 5402earlier versions. 5403@end defvr 5404 5405@defvr Constant CURVE25519_SIZE 5406The size of the strings representing curve25519 points and scalars, 32. 5407@end defvr 5408 5409@deftypefun void curve25519_mul_g (uint8_t *@var{q}, const uint8_t *@var{n}) 5410Computes @math{Q = N G}, where @math{G} is the group generator and 5411@math{N} is an integer. The input argument @var{n} and the output 5412argument @var{q} use a little-endian representation of the scalar and 5413the x-coordinate, respectively. They are both of size 5414@code{CURVE25519_SIZE}. 5415 5416This function is intended to be compatible with the function 5417@code{crypto_scalar_mult_base} in the NaCl library. 5418@end deftypefun 5419 5420@deftypefun void curve25519_mul (uint8_t *@var{q}, const uint8_t *@var{n}, const uint8_t *@var{p}) 5421Computes @math{Q = N P}, where @math{P} is an input point and @math{N} 5422is an integer. The input arguments @var{n} and @var{p} and the output 5423argument @var{q} use a little-endian representation of the scalar and 5424the x-coordinates, respectively. They are all of size 5425@code{CURVE25519_SIZE}. 5426 5427This function is intended to be compatible with the function 5428@code{crypto_scalar_mult} in the NaCl library. 5429@end deftypefun 5430 5431Similarly, Nettle also implements Curve448, an elliptic curve of 5432Montgomery type, @math{y^2 = x^3 + 156326 x^2 + x @pmod{p}}, with 5433@math{p = 2^448 - 2^224 - 1}. This particular curve was proposed by 5434Mike Hamburg in 2015, for fast Diffie-Hellman key exchange, and is also 5435described in @cite{RFC 7748}. 5436 5437Nettle defines Curve 448 in @file{<nettle/curve448.h>}. 5438 5439@defvr Constant CURVE448_SIZE 5440The octet length of the strings representing curve448 points and scalars, 56. 5441@end defvr 5442 5443@deftypefun void curve448_mul_g (uint8_t *@var{q}, const uint8_t *@var{n}) 5444Computes @math{Q = N G}, where @math{G} is the group generator and 5445@math{N} is an integer. The input argument @var{n} and the output 5446argument @var{q} use a little-endian representation of the scalar and 5447the x-coordinate, respectively. They are both of size 5448@code{CURVE448_SIZE}. 5449 5450This function is intended to be compatible with the function 5451@code{crypto_scalar_mult_base} in the NaCl library. 5452@end deftypefun 5453 5454@deftypefun void curve448_mul (uint8_t *@var{q}, const uint8_t *@var{n}, const uint8_t *@var{p}) 5455Computes @math{Q = N P}, where @math{P} is an input point and @math{N} 5456is an integer. The input arguments @var{n} and @var{p} and the output 5457argument @var{q} use a little-endian representation of the scalar and 5458the x-coordinates, respectively. They are all of size 5459@code{CURVE448_SIZE}. 5460 5461This function is intended to be compatible with the function 5462@code{crypto_scalar_mult} in the NaCl library. 5463@end deftypefun 5464 5465@subsubsection EdDSA 5466@cindex eddsa 5467 5468EdDSA is a signature scheme proposed by D. J. Bernstein et al. in 2011. 5469It is defined using a ``Twisted Edwards curve'', of the form @math{-x^2 5470+ y^2 = 1 + d x^2 y^2}. The specific signature scheme Ed25519 uses a 5471curve which is equivalent to curve25519: The two groups used differ only 5472by a simple change of coordinates, so that the discrete logarithm 5473problem is of equal difficulty in both groups. 5474 5475Unlike other signature schemes in Nettle, the input to the EdDSA sign 5476and verify functions is the possibly large message itself, not a hash 5477digest. EdDSA is a variant of Schnorr signatures, where the message is 5478hashed together with other data during the signature process, providing 5479resilience to hash-collisions: A successful attack finding collisions in 5480the hash function does not automatically translate into an attack to 5481forge signatures. EdDSA also avoids the use of a randomness source by 5482generating the needed signature nonce from a hash of the private key and 5483the message, which means that the message is actually hashed twice when 5484creating a signature. If signing huge messages, it is possible to hash 5485the message first and pass the short message digest as input to the sign 5486and verify functions, however, the resilience to hash collision is then 5487lost. 5488 5489@defvr Constant ED25519_KEY_SIZE 5490The size of a private or public Ed25519 key, 32 octets. 5491@end defvr 5492 5493@defvr Constant ED25519_SIGNATURE_SIZE 5494The size of an Ed25519 signature, 64 octets. 5495@end defvr 5496 5497@deftypefun void ed25519_sha512_public_key (uint8_t *@var{pub}, const uint8_t *@var{priv}) 5498Computes the public key corresponding to the given private key. Both 5499input and output are of size @code{ED25519_KEY_SIZE}. 5500@end deftypefun 5501 5502@deftypefun void ed25519_sha512_sign (const uint8_t *@var{pub}, const uint8_t *@var{priv}, size_t @var{length}, const uint8_t *@var{msg}, uint8_t *@var{signature}) 5503Signs a message using the provided key pair. 5504@end deftypefun 5505 5506@deftypefun int ed25519_sha512_verify (const uint8_t *@var{pub}, size_t @var{length}, const uint8_t *@var{msg}, const uint8_t *@var{signature}) 5507Verifies a message using the provided public key. Returns 1 if the 5508signature is valid, otherwise 0. 5509@end deftypefun 5510 5511Nettle also provides Ed448, an EdDSA signature scheme based on an 5512Edwards curve equivalent to curve448. 5513 5514@defvr Constant ED448_KEY_SIZE 5515The size of a private or public Ed448 key, 57 octets. 5516@end defvr 5517 5518@defvr Constant ED448_SIGNATURE_SIZE 5519The size of an Ed448 signature, 114 octets. 5520@end defvr 5521 5522@deftypefun void ed448_shake256_public_key (uint8_t *@var{pub}, const uint8_t *@var{priv}) 5523Computes the public key corresponding to the given private key. Both 5524input and output are of size @code{ED448_KEY_SIZE}. 5525@end deftypefun 5526 5527@deftypefun void ed448_shake256_sign (const uint8_t *@var{pub}, const uint8_t *@var{priv}, size_t @var{length}, const uint8_t *@var{msg}, uint8_t *@var{signature}) 5528Signs a message using the provided key pair. 5529@end deftypefun 5530 5531@deftypefun int ed448_shake256_verify (const uint8_t *@var{pub}, size_t @var{length}, const uint8_t *@var{msg}, const uint8_t *@var{signature}) 5532Verifies a message using the provided public key. Returns 1 if the 5533signature is valid, otherwise 0. 5534@end deftypefun 5535 5536@node Randomness, ASCII encoding, Public-key algorithms, Reference 5537@comment node-name, next, previous, up 5538@section Randomness 5539 5540@cindex Randomness 5541 5542A crucial ingredient in many cryptographic contexts is randomness: Let 5543@code{p} be a random prime, choose a random initialization vector 5544@code{iv}, a random key @code{k} and a random exponent @code{e}, etc. In 5545the theories, it is assumed that you have plenty of randomness around. 5546If this assumption is not true in practice, systems that are otherwise 5547perfectly secure, can be broken. Randomness has often turned out to be 5548the weakest link in the chain. 5549 5550In non-cryptographic applications, such as games as well as scientific 5551simulation, a good randomness generator usually means a generator that 5552has good statistical properties, and is seeded by some simple function 5553of things like the current time, process id, and host name. 5554 5555However, such a generator is inadequate for cryptography, for at least 5556two reasons: 5557 5558 5559@itemize 5560 5561@item 5562It's too easy for an attacker to guess the initial seed. Even if it will 5563take some 2^32 tries before he guesses right, that's far too easy. For 5564example, if the process id is 16 bits, the resolution of ``current time'' 5565is one second, and the attacker knows what day the generator was seeded, 5566there are only about 2^32 possibilities to try if all possible values 5567for the process id and time-of-day are tried. 5568 5569@item 5570The generator output reveals too much. By observing only a small segment 5571of the generator's output, its internal state can be recovered, and from 5572there, all previous output and all future output can be computed by the 5573attacker. 5574@end itemize 5575 5576A randomness generator that is used for cryptographic purposes must have 5577better properties. Let's first look at the seeding, as the issues here 5578are mostly independent of the rest of the generator. The initial state 5579of the generator (its seed) must be unguessable by the attacker. So 5580what's unguessable? It depends on what the attacker already knows. The 5581concept used in information theory to reason about such things is called 5582``entropy'', or ``conditional entropy'' (not to be confused with the 5583thermodynamic concept with the same name). A reasonable requirement is 5584that the seed contains a conditional entropy of at least some 80-100 5585bits. This property can be explained as follows: Allow the attacker to 5586ask @code{n} yes-no-questions, of his own choice, about the seed. If 5587the attacker, using this question-and-answer session, as well as any 5588other information he knows about the seeding process, still can't guess 5589the seed correctly, then the conditional entropy is more than @code{n} 5590bits. 5591 5592@cindex Entropy 5593@cindex Conditional entropy 5594 5595Let's look at an example. Say information about timing of received 5596network packets is used in the seeding process. If there is some random 5597network traffic going on, this will contribute some bits of entropy or 5598``unguessability'' to the seed. However, if the attacker can listen in to 5599the local network, or if all but a small number of the packets were 5600transmitted by machines that the attacker can monitor, this additional 5601information makes the seed easier for the attacker to figure out. Even 5602if the information is exactly the same, the conditional entropy, or 5603unguessability, is smaller for an attacker that knows some of it already 5604before the hypothetical question-and-answer session. 5605 5606Seeding of good generators is usually based on several sources. The key 5607point here is that the amount of unguessability that each source 5608contributes, depends on who the attacker is. Some sources that have been 5609used are: 5610 5611@table @asis 5612@item High resolution timing of i/o activities 5613Such as completed blocks from spinning hard disks, network packets, etc. 5614Getting access to such information is quite system dependent, and not 5615all systems include suitable hardware. If available, it's one of the 5616better randomness source one can find in a digital, mostly predictable, 5617computer. 5618 5619@item User activity 5620Timing and contents of user interaction events is another popular source 5621that is available for interactive programs (even if I suspect that it is 5622sometimes used in order to make the user feel good, not because the 5623quality of the input is needed or used properly). Obviously, not 5624available when a machine is unattended. Also beware of networks: User 5625interaction that happens across a long serial cable, @acronym{TELNET} 5626session, or even @acronym{SSH} session may be visible to an attacker, in 5627full or partially. 5628 5629@item Audio input 5630Any room, or even a microphone input that's left unconnected, is a 5631source of some random background noise, which can be fed into the 5632seeding process. 5633 5634@item Specialized hardware 5635Hardware devices with the sole purpose of generating random data have 5636been designed. They range from radioactive samples with an attached 5637Geiger counter, to amplification of the inherent noise in electronic 5638components such as diodes and resistors, to low-frequency sampling of 5639chaotic systems. Hashing successive images of a Lava lamp is a 5640spectacular example of the latter type. 5641 5642@item Secret information 5643Secret information, such as user passwords or keys, or private files 5644stored on disk, can provide some unguessability. A problem is that if 5645the information is revealed at a later time, the unguessability 5646vanishes. Another problem is that this kind of information tends to be 5647fairly constant, so if you rely on it and seed your generator regularly, 5648you risk constructing almost similar seeds or even constructing the same 5649seed more than once. 5650@end table 5651 5652For all practical sources, it's difficult but important to provide a 5653reliable lower bound on the amount of unguessability that it provides. 5654Two important points are to make sure that the attacker can't observe 5655your sources (so if you like the Lava lamp idea, remember that you have 5656to get your own lamp, and not put it by a window or anywhere else where 5657strangers can see it), and that hardware failures are detected. What if 5658the bulb in the Lava lamp, which you keep locked into a cupboard 5659following the above advice, breaks after a few months? 5660 5661So let's assume that we have been able to find an unguessable seed, 5662which contains at least 80 bits of conditional entropy, relative to all 5663attackers that we care about (typically, we must at the very least 5664assume that no attacker has root privileges on our machine). 5665 5666How do we generate output from this seed, and how much can we get? Some 5667generators (notably the Linux @file{/dev/random} generator) tries to 5668estimate available entropy and restrict the amount of output. The goal 5669is that if you read 128 bits from @file{/dev/random}, you should get 128 5670``truly random'' bits. This is a property that is useful in some 5671specialized circumstances, for instance when generating key material for 5672a one time pad, or when working with unconditional blinding, but in most 5673cases, it doesn't matter much. For most application, there's no limit on 5674the amount of useful ``random'' data that we can generate from a small 5675seed; what matters is that the seed is unguessable and that the 5676generator has good cryptographic properties. 5677 5678At the heart of all generators lies its internal state. Future output 5679is determined by the internal state alone. Let's call it the generator's 5680key. The key is initialized from the unguessable seed. Important 5681properties of a generator are: 5682 5683@table @dfn 5684 5685@item Key-hiding 5686An attacker observing the output should not be able to recover the 5687generator's key. 5688 5689@item Independence of outputs 5690Observing some of the output should not help the attacker to guess 5691previous or future output. 5692 5693@item Forward secrecy 5694Even if an attacker compromises the generator's key, he should not be 5695able to guess the generator output @emph{before} the key compromise. 5696 5697@item Recovery from key compromise 5698If an attacker compromises the generator's key, he can compute 5699@emph{all} future output. This is inevitable if the generator is seeded 5700only once, at startup. However, the generator can provide a reseeding 5701mechanism, to achieve recovery from key compromise. More precisely: If 5702the attacker compromises the key at a particular time @code{t_1}, there 5703is another later time @code{t_2}, such that if the attacker observes all 5704output generated between @code{t_1} and @code{t_2}, he still can't guess 5705what output is generated after @code{t_2}. 5706 5707@end table 5708 5709Nettle includes one randomness generator that is believed to have all 5710the above properties, and two simpler ones. 5711 5712@acronym{ARCFOUR}, like any stream cipher, can be used as a randomness 5713generator. Its output should be of reasonable quality, if the seed is 5714hashed properly before it is used with @code{arcfour_set_key}. There's 5715no single natural way to reseed it, but if you need reseeding, you 5716should be using Yarrow instead. 5717 5718The ``lagged Fibonacci'' generator in @file{<nettle/knuth-lfib.h>} is a 5719fast generator with good statistical properties, but is @strong{not} for 5720cryptographic use, and therefore not documented here. It is included 5721mostly because the Nettle test suite needs to generate some test data 5722from a small seed. 5723 5724The recommended generator to use is Yarrow, described below. 5725 5726@subsection Yarrow 5727 5728Yarrow is a family of pseudo-randomness generators, designed for 5729cryptographic use, by John Kelsey, Bruce Schneier and Niels Ferguson. 5730Yarrow-160 is described in a paper at 5731@url{http://www.counterpane.com/yarrow.html}, and it uses @acronym{SHA1} 5732and triple-DES, and has a 160-bit internal state. Nettle implements 5733Yarrow-256, which is similar, but uses @acronym{SHA256} and 5734@acronym{AES} to get an internal state of 256 bits. 5735 5736Yarrow was an almost finished project, the paper mentioned above is the 5737closest thing to a specification for it, but some smaller details are 5738left out. There is no official reference implementation or test cases. 5739This section includes an overview of Yarrow, but for the details of 5740Yarrow-256, as implemented by Nettle, you have to consult the source 5741code. Maybe a complete specification can be written later. 5742 5743Yarrow can use many sources (at least two are needed for proper 5744reseeding), and two randomness ``pools'', referred to as the ``slow pool'' and 5745the ``fast pool''. Input from the sources is fed alternatingly into the 5746two pools. When one of the sources has contributed 100 bits of entropy 5747to the fast pool, a ``fast reseed'' happens and the fast pool is mixed 5748into the internal state. When at least two of the sources have 5749contributed at least 160 bits each to the slow pool, a ``slow reseed'' 5750takes place. The contents of both pools are mixed into the internal 5751state. These procedures should ensure that the generator will eventually 5752recover after a key compromise. 5753 5754The output is generated by using @acronym{AES} to encrypt a counter, 5755using the generator's current key. After each request for output, 5756another 256 bits are generated which replace the key. This ensures 5757forward secrecy. 5758 5759Yarrow can also use a @dfn{seed file} to save state across restarts. 5760Yarrow is seeded by either feeding it the contents of the previous seed 5761file, or feeding it input from its sources until a slow reseed happens. 5762 5763Nettle defines Yarrow-256 in @file{<nettle/yarrow.h>}. 5764 5765@deftp {Context struct} {struct yarrow256_ctx} 5766@end deftp 5767 5768@deftp {Context struct} {struct yarrow_source} 5769Information about a single source. 5770@end deftp 5771 5772@defvr Constant YARROW256_SEED_FILE_SIZE 5773Recommended size of the Yarrow-256 seed file. 5774@end defvr 5775 5776@deftypefun void yarrow256_init (struct yarrow256_ctx *@var{ctx}, unsigned @var{nsources}, struct yarrow_source *@var{sources}) 5777Initializes the yarrow context, and its @var{nsources} sources. It's 5778possible to call it with @var{nsources}=0 and @var{sources}=NULL, if 5779you don't need the update features. 5780@end deftypefun 5781 5782@deftypefun void yarrow256_seed (struct yarrow256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{seed_file}) 5783Seeds Yarrow-256 from a previous seed file. @var{length} should be at least 5784@code{YARROW256_SEED_FILE_SIZE}, but it can be larger. 5785 5786The generator will trust you that the @var{seed_file} data really is 5787unguessable. After calling this function, you @emph{must} overwrite the old 5788seed file with newly generated data from @code{yarrow256_random}. If it's 5789possible for several processes to read the seed file at about the same 5790time, access must be coordinated using some locking mechanism. 5791@end deftypefun 5792 5793@deftypefun int yarrow256_update (struct yarrow256_ctx *@var{ctx}, unsigned @var{source}, unsigned @var{entropy}, size_t @var{length}, const uint8_t *@var{data}) 5794Updates the generator with data from source @var{SOURCE} (an index that 5795must be smaller than the number of sources). @var{entropy} is your 5796estimated lower bound for the entropy in the data, measured in bits. 5797Calling update with zero @var{entropy} is always safe, no matter if the 5798data is random or not. 5799 5800Returns 1 if a reseed happened, in which case an application using a 5801seed file may want to generate new seed data with 5802@code{yarrow256_random} and overwrite the seed file. Otherwise, the 5803function returns 0. 5804@end deftypefun 5805 5806@deftypefun void yarrow256_random (struct yarrow256_ctx *@var{ctx}, size_t @var{length}, uint8_t *@var{dst}) 5807Generates @var{length} octets of output. The generator must be seeded 5808before you call this function. 5809 5810If you don't need forward secrecy, e.g. if you need non-secret 5811randomness for initialization vectors or padding, you can gain some 5812efficiency by buffering, calling this function for reasonably large 5813blocks of data, say 100-1000 octets at a time. 5814@end deftypefun 5815 5816@deftypefun int yarrow256_is_seeded (struct yarrow256_ctx *@var{ctx}) 5817Returns 1 if the generator is seeded and ready to generate output, 5818otherwise 0. 5819@end deftypefun 5820 5821@deftypefun unsigned yarrow256_needed_sources (struct yarrow256_ctx *@var{ctx}) 5822Returns the number of sources that must reach the threshold before a 5823slow reseed will happen. Useful primarily when the generator is unseeded. 5824@end deftypefun 5825 5826@deftypefun void yarrow256_fast_reseed (struct yarrow256_ctx *@var{ctx}) 5827@deftypefunx void yarrow256_slow_reseed (struct yarrow256_ctx *@var{ctx}) 5828Causes a fast or slow reseed to take place immediately, regardless of the 5829current entropy estimates of the two pools. Use with care. 5830@end deftypefun 5831 5832Nettle includes an entropy estimator for one kind of input source: User 5833keyboard input. 5834 5835@deftp {Context struct} {struct yarrow_key_event_ctx} 5836Information about recent key events. 5837@end deftp 5838 5839@deftypefun void yarrow_key_event_init (struct yarrow_key_event_ctx *@var{ctx}) 5840Initializes the context. 5841@end deftypefun 5842 5843@deftypefun unsigned yarrow_key_event_estimate (struct yarrow_key_event_ctx *@var{ctx}, unsigned @var{key}, unsigned @var{time}) 5844@var{key} is the id of the key (ASCII value, hardware key code, X 5845keysym, @dots{}, it doesn't matter), and @var{time} is the timestamp of 5846the event. The time must be given in units matching the resolution by 5847which you read the clock. If you read the clock with microsecond 5848precision, @var{time} should be provided in units of microseconds. But 5849if you use @code{gettimeofday} on a typical Unix system where the clock 5850ticks 10 or so microseconds at a time, @var{time} should be given in 5851units of 10 microseconds. 5852 5853Returns an entropy estimate, in bits, suitable for calling 5854@code{yarrow256_update}. Usually, 0, 1 or 2 bits. 5855@end deftypefun 5856 5857@node ASCII encoding, Miscellaneous functions, Randomness, Reference 5858@comment node-name, next, previous, up 5859@section ASCII encoding 5860 5861Encryption will transform your data from text into binary format, and that 5862may be a problem if, for example, you want to send the data as if it was 5863plain text in an email, or store it along with descriptive text in a 5864file. You may then use an encoding from binary to text: each binary byte 5865is translated into a number of bytes of plain text. 5866 5867A base-N encoding of data is one representation of data that only uses N 5868different symbols (instead of the 256 possible values of a byte). 5869 5870The base64 encoding will always use alphanumeric (upper and lower case) 5871characters and the '+', '/' and '=' symbols to represent the data. Four 5872output characters are generated for each three bytes of input. In case 5873the length of the input is not a multiple of three, padding characters 5874are added at the end. There's also a ``URL safe'' variant, which is 5875useful for encoding binary data into URLs and filenames. See @cite{RFC 58764648}. 5877 5878The base16 encoding, also known as ``hexadecimal'', uses the decimal 5879digits and the letters from A to F. Two hexadecimal digits are generated 5880for each input byte. 5881 5882Nettle supports both base64 and base16 encoding and decoding. 5883 5884Encoding and decoding uses a context struct to maintain its state (with 5885the exception of base16 encoding, which doesn't need any). To encode or 5886decode the data, first initialize the context, then call the update 5887function as many times as necessary, and complete the operation by 5888calling the final function. 5889 5890The following functions can be used to perform base64 encoding and decoding. 5891They are defined in @file{<nettle/base64.h>}. 5892 5893@deftp {Context struct} {struct base64_encode_ctx} 5894@end deftp 5895 5896@deftypefun {void} base64_encode_init (struct base64_encode_ctx *@var{ctx}) 5897@deftypefunx {void} base64url_encode_init (struct base64_encode_ctx *@var{ctx}) 5898Initializes a base64 context. This is necessary before starting an 5899encoding session. @code{base64_encode_init} selects the standard base64 5900alphabet, while @code{base64url_encode_init} selects the URL safe 5901alphabet. 5902@end deftypefun 5903 5904 5905@deftypefun {size_t} base64_encode_single (struct base64_encode_ctx *@var{ctx}, uint8_t *@var{dst}, uint8_t @var{src}) 5906Encodes a single byte. Returns amount of output (always 1 or 2). 5907@end deftypefun 5908 5909@deffn Macro BASE64_ENCODE_LENGTH (@var{length}) 5910The maximum number of output bytes when passing @var{length} input bytes 5911to @code{base64_encode_update}. 5912@end deffn 5913 5914@deftypefun {size_t} base64_encode_update (struct base64_encode_ctx *@var{ctx}, uint8_t *@var{dst}, size_t @var{length}, const uint8_t *@var{src}) 5915After @var{ctx} is initialized, this function may be called to encode @var{length} 5916bytes from @var{src}. The result will be placed in @var{dst}, and the return value 5917will be the number of bytes generated. Note that @var{dst} must be at least of size 5918BASE64_ENCODE_LENGTH(@var{length}). 5919@end deftypefun 5920 5921@defvr Constant BASE64_ENCODE_FINAL_LENGTH 5922The maximum amount of output from @code{base64_encode_final}. 5923@end defvr 5924 5925@deftypefun {size_t} base64_encode_final (struct base64_encode_ctx *@var{ctx}, uint8_t *@var{dst}) 5926After calling base64_encode_update one or more times, this function 5927should be called to generate the final output bytes, including any 5928needed paddding. The return value is the number of output bytes 5929generated. 5930@end deftypefun 5931 5932@deftp {Context struct} {struct base64_decode_ctx} 5933@end deftp 5934 5935@deftypefun {void} base64_decode_init (struct base64_decode_ctx *@var{ctx}) 5936@deftypefunx {void} base64url_decode_init (struct base64_decode_ctx *@var{ctx}) 5937Initializes a base64 decoding context. This is necessary before starting 5938a decoding session. @code{base64_decode_init} selects the standard 5939base64 alphabet, while @code{base64url_decode_init} selects the URL safe 5940alphabet. 5941@end deftypefun 5942 5943@deftypefun {int} base64_decode_single (struct base64_decode_ctx *@var{ctx}, uint8_t *@var{dst}, uint8_t @var{src}) 5944Decodes a single byte (@var{src}) and stores the result in @var{dst}. 5945Returns amount of output (0 or 1), or -1 on errors. 5946@end deftypefun 5947 5948@deffn Macro BASE64_DECODE_LENGTH (@var{length}) 5949The maximum number of output bytes when passing @var{length} input bytes 5950to @code{base64_decode_update}. 5951@end deffn 5952 5953@deftypefun {void} base64_decode_update (struct base64_decode_ctx *@var{ctx}, size_t *@var{dst_length}, uint8_t *@var{dst}, size_t @var{src_length}, const uint8_t *@var{src}) 5954After @var{ctx} is initialized, this function may be called to decode 5955@var{src_length} bytes from @var{src}. @var{dst} should point to an area 5956of size at least BASE64_DECODE_LENGTH(@var{src_length}). The amount of data 5957generated is returned in *@var{dst_length}. Returns 1 on success 5958and 0 on error. 5959@end deftypefun 5960 5961@deftypefun {int} base64_decode_final (struct base64_decode_ctx *@var{ctx}) 5962Check that final padding is correct. Returns 1 on success, and 0 on 5963error. 5964@end deftypefun 5965 5966Similarly to the base64 functions, the following functions perform base16 encoding, 5967and are defined in @file{<nettle/base16.h>}. Note that there is no encoding context 5968necessary for doing base16 encoding. 5969 5970@deftypefun {void} base16_encode_single (uint8_t *@var{dst}, uint8_t @var{src}) 5971Encodes a single byte. Always stores two digits in @var{dst}[0] and @var{dst}[1]. 5972@end deftypefun 5973 5974@deffn Macro BASE16_ENCODE_LENGTH (@var{length}) 5975The number of output bytes when passing @var{length} input bytes to 5976@code{base16_encode_update}. 5977@end deffn 5978 5979@deftypefun {void} base16_encode_update (uint8_t *@var{dst}, size_t @var{length}, const uint8_t *@var{src}) 5980Always stores BASE16_ENCODE_LENGTH(@var{length}) digits in @var{dst}. 5981@end deftypefun 5982 5983@deftp {Context struct} {struct base16_decode_ctx} 5984@end deftp 5985 5986@deftypefun {void} base16_decode_init (struct base16_decode_ctx *@var{ctx}) 5987Initializes a base16 decoding context. This is necessary before starting a decoding 5988session. 5989@end deftypefun 5990 5991@deftypefun {int} base16_decode_single (struct base16_decode_ctx *@var{ctx}, uint8_t *@var{dst}, uint8_t @var{src}) 5992Decodes a single byte from @var{src} into @var{dst}. Returns amount of output (0 or 1), or -1 on errors. 5993@end deftypefun 5994 5995@deffn Macro BASE16_DECODE_LENGTH (@var{length}) 5996The maximum number of output bytes when passing @var{length} input bytes 5997to @code{base16_decode_update}. 5998@end deffn 5999 6000@deftypefun {int} base16_decode_update (struct base16_decode_ctx *@var{ctx}, size_t *@var{dst_length}, uint8_t *@var{dst}, size_t @var{src_length}, const uint8_t *@var{src}) 6001After @var{ctx} is initialized, this function may be called to decode 6002@var{src_length} bytes from @var{src}. @var{dst} should point to an area 6003of size at least BASE16_DECODE_LENGTH(@var{src_length}). The amount of data 6004generated is returned in *@var{dst_length}. Returns 1 on success 6005and 0 on error. 6006@end deftypefun 6007 6008@deftypefun {int} base16_decode_final (struct base16_decode_ctx *@var{ctx}) 6009Checks that the end of data is correct (i.e., an even number of 6010hexadecimal digits have been seen). Returns 1 on success, and 0 on 6011error. 6012@end deftypefun 6013 6014@node Miscellaneous functions, Compatibility functions, ASCII encoding, Reference 6015@comment node-name, next, previous, up 6016@section Miscellaneous functions 6017 6018@deftypefun {void *} memxor (void *@var{dst}, const void *@var{src}, size_t @var{n}) 6019XORs the source area on top of the destination area. The interface 6020doesn't follow the Nettle conventions, because it is intended to be 6021similar to the ANSI-C @code{memcpy} function. 6022@end deftypefun 6023 6024@deftypefun {void *} memxor3 (void *@var{dst}, const void *@var{a}, const void *@var{b}, size_t @var{n}) 6025Like @code{memxor}, but takes two source areas and separate 6026destination area. 6027@end deftypefun 6028 6029@deftypefun int memeql_sec (const void *@var{a}, const void *@var{b}, size_t @var{n}) 6030Side-channel silent comparison of the @var{n} bytes at @var{a} and 6031@var{b}. I.e., instructions executed and memory accesses are identical 6032no matter where the areas differ, @pxref{Side-channel silence}. Return 6033non-zero if the areas are equal, and zero if they differ. 6034@end deftypefun 6035 6036These functions are declared in @file{<nettle/memops.h>}. For 6037compatibility with earlier versions of Nettle, @code{memxor} and 6038@code{memxor3} are also declared in @file{<nettle/memxor.h>}. 6039 6040@node Compatibility functions, , Miscellaneous functions, Reference 6041@comment node-name, next, previous, up 6042@section Compatibility functions 6043 6044For convenience, Nettle includes alternative interfaces to some 6045algorithms, for compatibility with some other popular crypto toolkits. 6046These are not fully documented here; refer to the source or to the 6047documentation for the original implementation. 6048 6049MD5 is defined in [RFC 1321], which includes a reference implementation. 6050Nettle defines a compatible interface to MD5 in 6051@file{<nettle/md5-compat.h>}. This file defines the typedef 6052@code{MD5_CTX}, and declares the functions @code{MD5Init}, @code{MD5Update} and 6053@code{MD5Final}. 6054 6055@node Nettle soup, Installation, Reference, Top 6056@comment node-name, next, previous, up 6057@chapter Traditional Nettle Soup 6058For the serious nettle hacker, here is a recipe for nettle soup. 4 servings. 6059 6060@itemize @w{} 6061@item 60621 liter fresh nettles (urtica dioica) 6063@item 60642 tablespoons butter 6065@item 60663 tablespoons flour 6067@item 60681 liter stock (meat or vegetable) 6069@item 60701/2 teaspoon salt 6071@item 6072a tad white pepper 6073@item 6074some cream or milk 6075@end itemize 6076 6077Gather 1 liter fresh nettles. Use gloves! Small, tender shoots are 6078preferable but the tops of larger nettles can also be used. 6079 6080Rinse the nettles very well. Boil them for 10 minutes in lightly salted 6081water. Strain the nettles and save the water. Hack the nettles. Melt the 6082butter and mix in the flour. Dilute with stock and the nettle-water you 6083saved earlier. Add the hacked nettles. If you wish you can add some milk 6084or cream at this stage. Bring to a boil and let boil for a few minutes. 6085Season with salt and pepper. 6086 6087Serve with boiled egg-halves. 6088 6089@c And the original Swedish version. 6090@ignore 6091 6092Recept på nässelsoppa 60934 portioner 6094 60951 l färska nässlor 60962 msk smör 60973 msk vetemjöl 60981 l kött- eller grönsaksbuljong 60991/2 tsk salt 61001-2 krm peppar 6101(lite grädde eller mjölk) 6102 6103Plocka 1 liter färska nässlor. Använd handskar! Helst små och späda 6104skott, men topparna av större nässlor går också bra. 6105 6106Skölj nässlorna väl. Förväll dem ca 10 minuter i lätt saltat vatten. 6107Häll av och spara spadet. Hacka nässlorna. Smält smöret, rör i mjöl och 6108späd med buljong och nässelspad. Lägg i de hackade nässlorna. Om så 6109önskas, häll i en skvätt mjölk eller grädde. Koka några minuter, och 6110smaksätt med salt och peppar. 6111 6112Servera med kokta ägghalvor. 6113@end ignore 6114 6115@node Installation, Index, Nettle soup, Top 6116@comment node-name, next, previous, up 6117@chapter Installation 6118 6119Nettle uses @command{autoconf}. To build it, unpack the source and run 6120 6121@example 6122./configure 6123make 6124make check 6125make install 6126@end example 6127 6128@noindent 6129to install it under the default prefix, @file{/usr/local}. Using GNU 6130make is strongly recommended. By default, both static and shared 6131libraries are built and installed. 6132 6133To get a list of configure options, use @code{./configure --help}. Some 6134of the more interesting are: 6135 6136@table @option 6137@item --enable-fat 6138Include multiple versions of certain functions in the library, and 6139select the ones to use at run-time, depending on available processor 6140features. Supported for ARM and x86_64. 6141 6142@item --enable-mini-gmp 6143Use the smaller and slower ``mini-gmp'' implementation of the bignum 6144functions needed for public-key cryptography, instead of the real GNU 6145GMP library. This option is intended primarily for smaller embedded 6146systems. Note that builds using mini-gmp are @strong{not} binary compatible 6147with regular builds of Nettle, and more likely to leak side-channel 6148information. 6149 6150@item --disable-shared 6151Omit building the shared libraries. 6152 6153@item --disable-dependency-tracking 6154Disable the automatic dependency tracking. You will likely need this 6155option to be able to build with BSD make. 6156 6157@end table 6158 6159@node Index, , Installation, Top 6160@comment node-name, next, previous, up 6161@unnumbered Function and Concept Index 6162 6163@printindex cp 6164 6165@bye 6166 6167Local Variables: 6168ispell-local-dictionary: "american" 6169End: 6170 6171@c LocalWords: cryptographics crypto LSH GNUPG API GPL LGPL aes rijndael ller 6172@c LocalWords: Sevilla arcfour RC Niels Dassen Colin Kuchling Biham sha Ruud 6173@c LocalWords: Gutmann twofish de Rooij struct MB Rivest RFC Nettle's ECB CBC 6174@c LocalWords: RSA Daemen Rijnmen Schneier DES's ede structs oddnesses HMAC 6175@c LocalWords: NIST Alice's GMP bignum Diffie Adi Shamir Adleman Euclid's ASN 6176@c LocalWords: PKCS callbacks Young's urtica dioica autoconf SSH tad 6177@c LocalWords: unguessability reseeding reseed alternatingly keysym subkeys 6178@c LocalWords: DSA gmp FIPS DSS libdes OpenSSL ARCTWO Josefsson Nikos Andreas 6179@c LocalWords: Mavroyanopoulos Sigfridsson Comstedt interoperability Sparc IC 6180@c LocalWords: DES FIXME Rivest's plaintext ciphertext CTR XORed timestamp 6181@c LocalWords: XORs cryptologists libnettle libhogweed GCM ECDSA NTT 6182@c LocalWords: toolkits BLOWFISH Möller RIPEMD libgcrypt PBKDF Shishi 6183@c LocalWords: GnuTLS Gutmann's GOSTHASH GOST Aleksey Kravchenko ECC 6184@c LocalWords: rhash Mavrogiannopoulos Keccak Bertoni 6185@c LocalWords: Michaël Peeters Assche Dobbertin Antoon Bosselaers KDF 6186@c LocalWords: Preneel rôle McGrew Viega KDFs PBKDFs passphrase PRF 6187@c LocalWords: th deallocate pre bitsize multi lookup secp startup 6188@c LocalWords: typedef typedef 6189