Libtomcrypt Developer Manual
Total Page:16
File Type:pdf, Size:1020Kb
LibTomCrypt Developer Manual LibTom Projects This document is part of the LibTomCrypt package and is hereby released into the public domain. Open Source. Open Academia. Open Minds. LibTom Projects & originally Tom St Denis Ottawa, Ontario Canada Contents 1 Introduction 1 1.1 What is the LibTomCrypt? . .1 1.2 Why did I write it? . .1 1.2.1 Modular . .2 1.3 License . .2 1.4 Patent Disclosure . .2 1.5 Thanks . .3 2 The Application Programming Interface (API) 5 2.1 Introduction . .5 2.2 Macros . .6 2.3 Functions with Variable Length Output . .7 2.4 Functions that need a PRNG . .8 2.5 Functions that use Arrays of Octets . .9 3 Symmetric Block Ciphers 11 3.1 Core Functions . 11 3.1.1 Key Scheduling . 11 3.1.2 ECB Encryption and Decryption . 12 3.1.3 Self{Testing . 12 3.1.4 Key Sizing . 12 3.1.5 Cipher Termination . 13 3.1.6 Simple Encryption Demonstration . 13 3.2 Key Sizes and Number of Rounds . 14 3.3 The Cipher Descriptors . 14 3.3.1 Notes . 16 3.4 Symmetric Modes of Operations . 18 3.4.1 Background . 18 3.4.2 Choice of Mode . 19 3.4.3 Ciphertext Stealing . 20 3.4.4 Initialization . 20 3.4.5 Encryption and Decryption . 21 3.4.6 IV Manipulation . 22 3.4.7 Stream Termination . 22 3.4.8 Examples . 23 iii 3.4.9 LRW Mode . 24 3.4.10 XTS Mode . 25 3.4.11 F8 Mode . 26 4 Stream Ciphers 29 4.1 ChaCha . 29 4.2 Salsa20 and XSalsa20 . 30 4.3 Sosemanuk . 31 4.4 Rabbit . 32 4.5 RC4 ............................................. 32 4.6 Sober128 . 33 5 Authenticated Encryption 35 5.1 EAX Mode . 35 5.2 OCB Modes . 38 5.2.1 Preface . 38 5.2.2 OCB . 39 5.2.3 OCB3 . 41 5.3 CCM Mode . 42 5.3.1 Initialization . 43 5.3.2 Nonce Vector . 43 5.3.3 Additional Authentication Data . 43 5.3.4 Plaintext Processing . 43 5.3.5 State Termination . 44 5.3.6 State Reset . 44 5.3.7 One{Shot Packet . 44 5.3.8 Example Usage . 45 5.4 GCM Mode . 47 5.4.1 Initialization . 47 5.4.2 Initialization Vector . 47 5.4.3 Additional Authentication Data . 47 5.4.4 Plaintext Processing . 48 5.4.5 State Termination . 48 5.4.6 State Reset . 48 5.4.7 One{Shot Packet . 49 5.4.8 Example Usage . 49 5.5 ChaCha20{Poly1305 . 51 5.5.1 Initialization . 51 5.5.2 Initialization Vector . 51 5.5.3 Additional Authentication Data . 52 5.5.4 Encryption / Decryption . 52 5.5.5 State Termination . 52 5.5.6 One{Shot Packet . 53 6 One-Way Cryptographic Hash Functions 55 6.1 Core Functions . 55 6.2 Hash Descriptors . 56 6.2.1 Hash Registration . 59 6.3 Cipher Hash Construction . 61 6.4 SHA3 SHAKE . 62 6.5 Notice . 62 7 Checksum Functions 63 7.1 Preface . 63 7.2 CRC-32 { Cyclic redundancy check . 63 7.3 Adler-32 . 63 8 Message Authentication Codes 65 8.1 HMAC Protocol . 65 8.2 OMAC Support . 67 8.3 PMAC Support . 70 8.4 Pelican MAC . 71 8.4.1 Example . 72 8.5 XCBC-MAC . 73 8.6 F9{MAC . 74 8.6.1 Usage Notice . 74 8.6.2 F9{MAC Functions . 74 8.7 Poly1305{MAC . 76 8.8 BLAKE2s + BLAKE2b MAC . 77 9 Pseudo-Random Number Generators 79 9.1 Core Functions . ..