This manual is for the Nettle library (version @value{UPDATED-FOR}), a
low-level cryptographic library.
-Originally written 2001 by @value{AUTHOR}, updated 2025.
+Originally written 2001 by @value{AUTHOR}, updated 2026.
@quotation
This manual is placed in the public domain. You may freely copy it, in
message authentication codes, pseudo random generators, association of
unique ids to documents, and many other things.
-The most commonly used hash functions are MD5 and SHA1. Unfortunately,
-both these fail the collision-resistance requirement; cryptologists have
-found ways to construct colliding inputs. The recommended hash functions
-for new applications are SHA2 (with main variants SHA256 and SHA512). At
-the time of this writing (Autumn 2015), SHA3 has recently been
-standardized, and the new SHA3 and other top SHA3 candidates may also be
-reasonable alternatives.
+The SHA1 hash function is still quite commonly used, even though it
+fails the collision-resistance requirement; cryptologists have found
+ways to construct colliding inputs. The recommended hash functions for
+new applications are SHA2 (with main variants SHA256 and SHA512) and
+SHA3 (several variants, including SHA3-256, SHAKE256 and SHA3-512).
@menu
* Recommended hash functions::
SM3 is a cryptographic hash function standard adopted by the government of the
People's Republic of China, which was issued by the Cryptography Standardization
Technical Committee of China on December 17, 2010. The corresponding standard
-is GM/T 0004-2012 "SM3 Cryptographic Hash Algorithm".
+is GM/T 0004-2012 ``SM3 Cryptographic Hash Algorithm''.
SM3 algorithm is a hash algorithm in ShangMi cryptosystems. SM3 is mainly used
for digital signature and verification, message authentication code generation
SM4 is a block cipher standard adopted by the government of the People's
Republic of China, and it was issued by the State Cryptography Administration
-on March 21, 2012. The standard is GM/T 0002-2012 "SM4 block cipher algorithm".
+on March 21, 2012. The standard is GM/T 0002-2012 ``SM4 block cipher algorithm''.
Nettle defines it in @file{<nettle/sm4.h>}.
@deftp {Context struct} {struct sm4_ctx}
@cindex AEAD
@cindex Authenticated encryption
-Since there are some subtle design choices to be made when combining a
-block cipher mode with out authentication with a @acronym{MAC}. In
+There are some subtle design choices to be made when combining a
+block cipher mode without authentication with a @acronym{MAC}. In
recent years, several constructions that combine encryption and
authentication have been defined. These constructions typically also
have an additional input, the ``associated data'', which is
The aim is to provide building blocks that it is easier for designers of
protocols and applications to use correctly. There is also some
potential for improved performance, if encryption and authentication can
-be done in a single step, although that potential is not realized for
-the constructions currently supported by Nettle.
+be done in a single step.
For encryption, the inputs are:
@end itemize
Decryption works the same, but with cleartext and ciphertext
-interchanged. All currently supported @acronym{AEAD} algorithms always
+interchanged. Most of the currently supported @acronym{AEAD} algorithms
use the encryption function of the underlying block cipher, for both
-encryption and decryption.
+encryption and decryption (OCB being a notable exception).
Usually, the authentication tag should be appended at the end of the
ciphertext, producing an encrypted message which is slightly longer than
mode is a bit special in that it requires the message lengths up front,
other @acronym{AEAD} constructions don't have this restriction.
-The supported @acronym{AEAD} constructions are Galois/Counter mode
-(@acronym{GCM}), @acronym{EAX}, ChaCha-Poly1305, and Counter with
-@acronym{CBC}-@acronym{MAC} (@acronym{CCM}). There are some weaknesses
-in @acronym{GCM} authentication, see
-@url{https://csrc.nist.gov/groups/ST/toolkit/BCM/documents/comments@//CWC-GCM/Ferguson2.pdf}.
-@acronym{CCM} and @acronym{EAX} use the same building blocks, but the
+Of the supported @acronym{AEAD} constructions in Nettle, Galois/Counter
+mode (@acronym{GCM}) is widely used, and was originally designed for
+high performance in hardware implementations. Software performance is
+rather poor unless there's an efficient ``carry-less multiplication''
+instruction that can be used. Both @acronym{CCM} and @acronym{EAX} use
+the same building blocks, @acronym{CTR} and @acronym{CMAC}, but the
@acronym{EAX} design is cleaner and avoids a couple of inconveniences of
@acronym{CCM}. Therefore, @acronym{EAX} seems like a good conservative
-choice. The more recent ChaCha-Poly1305 may also be an attractive but
-more adventurous alternative, in particular if performance is important.
+choice. The ChaCha-Poly1305 scheme is designed for high performance,
+also on machines without specialized crypto acceleration instructions.
+The Synthetic Initialization Vector (@acronym{SIV}) modes are designed
+to not fail catastrophically if a nonce is reused.
@menu
* EAX::
HKDF is a key derivation function used as a building block of
higher-level protocols like TLS 1.3. It is a derivation function
based on HMAC described in @cite{RFC 5869},
-and is split into two logical modules, called 'extract' and 'expand'.
+and is split into two logical modules, called ``extract'' and ``expand''.
The extract module takes an initial secret and a random
-salt to "extract" a fixed-length pseudorandom key (PRK). The second stage
+salt to extract a fixed-length pseudorandom key (PRK). The second stage
takes as input the previous PRK and some informational data (e.g.,
text) and expands them into multiple keys.
perfectly secure, can be broken. Randomness has often turned out to be
the weakest link in the chain.
+Building a good randomness source is subtle, in particular if your
+program may run inside several layers of virtualization. Today, most
+operating system provides a good randomness source, e.g.,
+@file{/dev/random} and the @code{getrandom} syscall on GNU/Linux. Please
+use that, possibly in combination with a @acronym{KDF}! If for some
+reason that is not possible and you @emph{have} to roll your own, the
+rest of this section provides some advice.
+
In non-cryptographic applications, such as games as well as scientific
simulation, a good randomness generator usually means a generator that
has good statistical properties, and is seeded by some simple function
However, such a generator is inadequate for cryptography, for at least
two reasons:
-
@itemize
@item
assume that no attacker has root privileges on our machine).
How do we generate output from this seed, and how much can we get? Some
-generators (notably the Linux @file{/dev/random} generator) tries to
-estimate available entropy and restrict the amount of output. The goal
-is that if you read 128 bits from @file{/dev/random}, you should get 128
-``truly random'' bits. This is a property that is useful in some
-specialized circumstances, for instance when generating key material for
-a one time pad, or when working with unconditional blinding, but in most
-cases, it doesn't matter much. For most application, there's no limit on
-the amount of useful ``random'' data that we can generate from a small
-seed; what matters is that the seed is unguessable and that the
-generator has good cryptographic properties.
+generators (notably older versions of the Linux @file{/dev/random}
+generator) tries to estimate available entropy and restrict the amount
+of output. The goal was that if you read 512 bits from
+@file{/dev/random}, you should get 512 ``truly random'' bits. This is a
+property that is useful in some specialized circumstances, for instance
+when generating key material for a one time pad, or when working with
+unconditional blinding, but in most cases, it doesn't matter much. For
+most application, there's no limit on the amount of useful ``random''
+data that we can generate from a small seed; what matters is that the
+seed is unguessable and that the generator has good cryptographic
+properties.
At the heart of all generators lies its internal state. Future output
is determined by the internal state alone. Let's call it the generator's
@node Installation
@chapter Installation
-Nettle uses @command{autoconf}. To build it, unpack the source and run
+Nettle uses @command{autoconf}, and the generated Makefile requires GNU
+make. To build Nettle, unpack the source and run
@example
./configure
@end example
@noindent
-to install it under the default prefix, @file{/usr/local}. Using GNU
-make is strongly recommended. By default, both static and shared
-libraries are built and installed.
+to install it under the default prefix, @file{/usr/local}. By default,
+both static and shared libraries are built and installed.
To get a list of configure options, use @code{./configure --help}. Some
of the more interesting are:
@table @option
-@item --enable-fat
-Include multiple versions of certain functions in the library, and
-select the ones to use at run-time, depending on available processor
-features. Supported for ARM and x86_64.
+@item --prefix
+Change install location.
+
+@item --disable-fat
+Disable run-time detection of available processor features. Additional
+configure options can be used to select which features to require.
@item --enable-mini-gmp
Use the smaller and slower ``mini-gmp'' implementation of the bignum
@item --disable-shared
Omit building the shared libraries.
-@item --disable-dependency-tracking
-Disable the automatic dependency tracking. You will likely need this
-option to be able to build with BSD make.
-
@end table
@node Index
projects / thirdparty / nettle.git / commitdiff
