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 Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
6.1 Hash functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
6.1.1 Recommended hash functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
6.1.1.1 SHA256 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
6.1.1.2 SHA224 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6.1.1.3 SHA512 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6.1.1.4 SHA384 and other variants of SHA512 . . . . . . . . . . . . . . . . . . 10
6.1.1.5 SHA3-224 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
6.1.1.6 SHA3-256 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
6.1.1.7 SHA3-384 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
6.1.1.8 SHA3-512 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.1.2 Legacy hash functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.1.2.1 MD5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
6.1.2.2 MD2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
6.1.2.3 MD4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
6.1.2.4 RIPEMD160 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
6.1.2.5 SHA1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
6.1.2.6 GOSTHASH94 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
6.1.3 The struct nettle_hash abstraction . . . . . . . . . . . . . . . . . . . . 17
6.2 Cipher functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
6.2.1 AES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
6.2.2 ARCFOUR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
6.2.3 ARCTWO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
6.2.4 BLOWFISH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
6.2.5 Camellia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
6.2.6 CAST128 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6.2.7 ChaCha . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6.2.8 DES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
6.2.9 DES3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
6.2.10 Salsa20 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.2.11 SERPENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
ii
6.2.12 TWOFISH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
6.2.13 The struct nettle_cipher abstraction . . . . . . . . . . . . . . . . . 30
6.3 Cipher modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
6.3.1 Cipher Block Chaining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
6.3.2 Counter mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.3.3 Cipher Feedback mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.4 Authenticated encryption with associated data . . . . . . . . . . . . . . . . 35
6.4.1 EAX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
6.4.1.1 General EAX interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
6.4.1.2 EAX helper macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
6.4.1.3 EAX-AES128 interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
6.4.2 Galois counter mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
6.4.2.1 General GCM interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
6.4.2.2 GCM helper macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
6.4.2.3 GCM-AES interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
6.4.2.4 GCM-Camellia interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
6.4.3 Counter with CBC-MAC mode . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
6.4.3.1 General CCM interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
6.4.3.2 CCM message interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
6.4.3.3 CCM-AES interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
6.4.4 ChaCha-Poly1305 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
6.4.5 The struct nettle_aead abstraction . . . . . . . . . . . . . . . . . . . . 49
6.5 Keyed Hash Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
6.5.1 HMAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
6.5.2 Concrete HMAC functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
6.5.2.1 HMAC-MD5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
6.5.2.2 HMAC-RIPEMD160 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
6.5.2.3 HMAC-SHA1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
6.5.2.4 HMAC-SHA256 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
6.5.2.5 HMAC-SHA512 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
6.5.3 UMAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
6.5.4 Poly1305 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
6.6 Key derivation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
6.6.1 HKDF: HMAC-based Extract-and-Expand. . . . . . . . . . . . . . . . 57
6.6.2 PBKDF2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
6.6.3 Concrete PBKDF2 functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
6.6.3.1 PBKDF2-HMAC-SHA1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
6.6.3.2 PBKDF2-HMAC-SHA256 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.7 Public-key algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.7.1 RSA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
6.7.1.1 Nettle’s RSA support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
6.7.2 DSA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
6.7.2.1 Nettle’s DSA support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
6.7.2.2 Old, deprecated, DSA interface . . . . . . . . . . . . . . . . . . . . . . 70
6.7.3 Elliptic curves . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
6.7.3.1 Side-channel silence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
6.7.3.2 ECDSA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
6.7.3.3 Curve25519 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
iii
6.7.3.4 EdDSA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
6.8 Randomness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
6.8.1 Yarrow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
6.9 ASCII encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
6.10 Miscellaneous functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
6.11 Compatibility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
7 Traditional Nettle Soup . . . . . . . . . . . . . . . . . . . . . . . 84
8 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Function and Concept Index . . . . . . . . . . . . . . . . . . . . . 86
