Nettle Manual
For the Nettle Library version 3.4
Niels M¨oller
This manual is for the Nettle library (version 3.4), a low-level cryptographic library.
Originally written 2001 by Niels M¨oller, updated 2017.
This manual is placed i n the public domain. You may freely copy it, in whole
or in part, with or with out modification. Attribution is appreciated, but not
required.
i
Table of Contents
1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2 Copyright . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
3 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
4 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
5 Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
6 Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
7 Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
7.1 Hash functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
7.1.1 Recommended hash functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
7.1.1.1 SHA256 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
7.1.1.2 SHA224. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
7.1.1.3 SHA512. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
7.1.1.4 SHA384 and other variants of SHA512 . . . . . . . . . . . . . . . . . . 11
7.1.1.5 SHA3-224 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
7.1.1.6 SHA3-256 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
7.1.1.7 SHA3-384 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
7.1.1.8 SHA3-512 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
7.1.2 Legacy hash functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
7.1.2.1 MD5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
7.1.2.2 MD2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
7.1.2.3 MD4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
7.1.2.4 RIPEMD160 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
7.1.2.5 SHA1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
7.1.2.6 GOSTHASH94 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
7.1.3 The struct nettle_hash abstraction . . . . . . . . . . . . . . . . . . . . 18
7.2 Cipher functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
7.2.1 AES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
7.2.2 ARCFOUR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
7.2.3 ARCTWO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
7.2.4 BLOWFISH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
7.2.5 Camellia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
7.2.6 CAST128 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
7.2.7 ChaCha . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
7.2.8 DES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
7.2.9 DES3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
ii
7.2.10 Salsa20 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
7.2.11 SERPENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
7.2.12 TWOFISH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
7.2.13 The struct nettle_cipher abstraction . . . . . . . . . . . . . . . . . 32
7.3 Cipher modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
7.3.1 Cipher Block Chaining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
7.3.2 Counter mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
7.3.3 Cipher Feedback mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
7.3.4 XEX-based tweaked-codebook mode with ci phe r te x t st eal i n g
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
7.3.4.1 General (XTS) interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
7.3.4.2 XTS-AES interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
7.4 Authenticated encryption with associated data . . . . . . . . . . . . . . . . 40
7.4.1 EAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
7.4.1.1 General EAX interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
7.4.1.2 EAX helper macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
7.4.1.3 EAX-AES128 interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
7.4.2 Galois counter mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
7.4.2.1 General GCM interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
7.4.2.2 GCM helper macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
7.4.2.3 GCM-AES interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
7.4.2.4 GCM-Camellia interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
7.4.3 Counter with CBC-MAC mode . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
7.4.3.1 General CCM interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
7.4.3.2 CCM message interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
7.4.3.3 CCM-AES interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
7.4.4 ChaCha-Poly1305 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
7.4.5 The struct nettle_aead abstraction . . . . . . . . . . . . . . . . . . . . 54
7.5 Keyed Hash Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
7.5.1 HMAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
7.5.2 Concrete HMAC functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
7.5.2.1 HMAC-MD5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
7.5.2.2 HMAC-RIPEMD160 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
7.5.2.3 HMAC-SHA1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
7.5.2.4 HMAC-SHA256 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
7.5.2.5 HMAC-SHA512 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
7.5.3 UMAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
7.5.4 CMAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
7.5.5 Poly1305 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
7.6 Key derivation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
7.6.1 HKDF: HMAC-based Extract-and-Expand. . . . . . . . . . . . . . . . 63
7.6.2 PBKDF2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
7.6.3 Concrete PBKDF2 functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
7.6.3.1 PBKDF2-HMAC-SHA1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
7.6.3.2 PBKDF2-HMAC-SHA256 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
7.7 Public-key algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
7.7.1 RSA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
7.7.1.1 Nettle’s RSA support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
iii
7.7.2 DSA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
7.7.2.1 Nettle’s DSA support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
7.7.2.2 Old, deprecated, DSA interface . . . . . . . . . . . . . . . . . . . . . . 75
7.7.3 Elliptic curves . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
7.7.3.1 Side-channel silence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
7.7.3.2 ECDSA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
7.7.3.3 Curve25519 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
7.7.3.4 EdDSA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
7.8 Randomness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
7.8.1 Yarrow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
7.9 ASCII encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
7.10 Miscellaneous functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
7.11 Compatibility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
8 Traditional Nettle Soup . . . . . . . . . . . . . . . . . . . . . . . 90
9 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Function and Concept Index . . . . . . . . . . . . . . . . . . . . . 92
