Nettle Manual
For the Nettle Library version 2.3
Niels M¨oller
This manual is for the Nettle library (version 2.3), a low-level cryptographic library.
Originally written 2001 by Niels M¨oller, updated 2011.
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 MD5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
6.1.2 MD2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6.1.3 MD4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6.1.4 RIPEMD160 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
6.1.5 SHA1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
6.1.6 SHA256 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
6.1.7 SHA224 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
6.1.8 SHA512 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
6.1.9 SHA384 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.1.10 struct nettle_hash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.2 Cipher functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
6.2.1 AES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
6.2.2 ARCFOUR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
6.2.3 ARCTWO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
6.2.4 BLOWFISH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
6.2.5 Camellia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
6.2.6 CAST128 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
6.2.7 DES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
6.2.8 DES3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
6.2.9 SERPENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
6.2.10 TWOFISH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
6.2.11 struct nettle_cipher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
6.3 Cipher modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
6.3.1 Cipher Block Chaining . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
6.3.2 Counter mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6.3.3 Galois counter mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
6.3.3.1 General GCM interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
6.3.3.2 GCM helper macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.3.3.3 GCM-AES interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
ii
6.4 Keyed Hash Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
6.4.1 HMAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
6.4.2 Concrete HMAC functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
6.4.2.1 HMAC-MD5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
6.4.2.2 HMAC-RIPEMD160 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
6.4.2.3 HMAC-SHA1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
6.4.2.4 HMAC-SHA256 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.4.2.5 HMAC-SHA512 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.5 Public-key algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.5.1 RSA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.5.2 Nettle’s RSA support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
6.5.3 Nettle’s DSA support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
6.5.4 Nettle’s DSA support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
6.6 Randomness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
6.6.1 Yarrow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
6.7 Miscellaneous functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
6.8 Compatibility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
7 Traditional Nettle Soup . . . . . . . . . . . . . . . . . . . . . . . 48
8 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Function and Concept Index . . . . . . . . . . . . . . . . . . . . . 50
Chapter 1: Introduction 1
1 Introduction
Nettle is a cry p togr aphi c library that is designed to fit easily in more or less any context:
In crypto toolkits for object-oriented languages (C++, Python, Pike, ...), in applications li ke
LSH or GNUPG, or even in kernel space. In most contexts, you need more than the basic
cryptographic algorithms, you also need some way to keep track of available algorithms, their
properties and variants. You often have some algorithm selection process, often dictated by
a protocol you want to implement.
And as the requir e me nts of applications differ in subtle and not so subtle ways, an API
that fits one application well can be a pain to use i n a different context. And that is why
there are so many different cryptographic libraries around.
Nettle tries to avoid this problem by doing one t hi ng, the low-level crypto stuff, and
providing a simple but general interface to it. In particular, Nettle doesn’t do algorithm
selection. It doesn’t do memory allocation. It doesn’t do any I/O.
The idea is that one can build several application and context specific interfaces on
top of Nettle, and share the code, test cases, benchmarks, documentation, etc. Examples
are the Nettle module for the Pike language, and LSH, which both use an object-oriented
abstraction on top of the library.
This manual explains how to use the Nettle library. It also tries to provide some back-
ground on the cryptography, and advic e on how to best put it t o use.
