Botan Reference Guide Release 2.18.1
Total Page:16
File Type:pdf, Size:1020Kb
Botan Reference Guide Release 2.18.1 Jack Lloyd Daniel Neus René Korthaus Juraj Somorovsky Tobias Niemann 2021-05-09 CONTENTS 1 Getting Started 1 1.1 Examples.................................................1 1.2 Books and other references.......................................1 2 Project Goals 3 2.1 Non-Goals................................................4 3 Support Information 5 3.1 Supported Platforms...........................................5 3.2 Branch Support Status..........................................6 3.3 Getting Help...............................................6 4 Building The Library 7 4.1 Configuring the Build..........................................7 4.2 Cross Compiling.............................................8 4.3 On Unix.................................................9 4.4 On macOS................................................9 4.5 On Windows...............................................9 4.6 For iOS using XCode.......................................... 10 4.7 For Android............................................... 11 4.8 Emscripten (WebAssembly)....................................... 11 4.9 Supporting Older Distros......................................... 11 4.10 Other Build-Related Tasks........................................ 12 4.11 Building Applications.......................................... 14 4.12 Language Wrappers........................................... 15 4.13 Minimized Builds............................................ 15 4.14 Configure Script Options......................................... 15 5 API Reference 27 5.1 Versioning................................................ 27 5.2 Memory container............................................ 28 5.3 Random Number Generators....................................... 29 5.4 Hash Functions and Checksums..................................... 33 5.5 Block Ciphers.............................................. 39 5.6 Stream Ciphers.............................................. 45 5.7 Message Authentication Codes (MAC)................................. 48 5.8 Cipher Modes.............................................. 52 5.9 Public Key Cryptography........................................ 57 5.10 X.509 Certificates and CRLs....................................... 71 5.11 Transport Layer Security (TLS)..................................... 83 i 5.12 Credentials Manager........................................... 112 5.13 BigInt................................................... 114 5.14 Key Derivation Functions........................................ 117 5.15 Password Based Key Derivation..................................... 119 5.16 AES Key Wrapping........................................... 122 5.17 Password Hashing............................................ 123 5.18 Cryptobox................................................ 126 5.19 Secure Remote Password......................................... 126 5.20 PSK Database.............................................. 127 5.21 Pipe/Filter Message Processing..................................... 128 5.22 Format Preserving Encryption...................................... 138 5.23 Threshold Secret Sharing........................................ 143 5.24 Elliptic Curve Operations........................................ 144 5.25 Lossless Data Compression....................................... 147 5.26 PKCS#11................................................. 148 5.27 Trusted Platform Module (TPM)..................................... 172 5.28 One Time Passwords........................................... 174 5.29 Roughtime................................................ 175 5.30 FFI (C Binding)............................................. 175 5.31 Environment Variables.......................................... 189 5.32 Python Binding.............................................. 190 6 Command Line Interface 199 6.1 Outline.................................................. 199 6.2 Hash Function.............................................. 199 6.3 Password Hash.............................................. 199 6.4 HMAC.................................................. 200 6.5 Encryption................................................ 200 6.6 Public Key Cryptography........................................ 200 6.7 X.509................................................... 201 6.8 TLS Server/Client............................................ 202 6.9 Number Theory............................................. 202 6.10 PSK Database.............................................. 203 6.11 Secret Sharing.............................................. 203 6.12 Data Encoding/Decoding......................................... 203 6.13 Miscellaneous Commands........................................ 204 7 Deprecated Features 205 7.1 TLS Protocol Deprecations....................................... 205 7.2 Deprecated Functionality......................................... 206 7.3 Deprecated Headers........................................... 206 7.4 Other API deprecations......................................... 207 7.5 Deprecated Build Targets........................................ 207 8 Development Roadmap 209 8.1 Near Term Plans............................................. 209 8.2 Botan 3.x................................................. 209 9 Credits 211 10 ABI Stability 215 11 Notes for Distributors 217 11.1 Recommended Options......................................... 217 11.2 Set Path to the System CA bundle.................................... 217 ii 11.3 Set Distribution Info........................................... 217 11.4 Minimize Distribution Patches...................................... 218 12 Security Advisories 219 12.1 2020................................................... 219 12.2 2018................................................... 220 12.3 2017................................................... 220 12.4 2016................................................... 221 12.5 2015................................................... 222 12.6 2014................................................... 224 13 Side Channels 225 13.1 Modular Exponentiation......................................... 225 13.2 Barrett Reduction............................................. 225 13.3 RSA................................................... 225 13.4 Decryption of PKCS #1 v1.5 Ciphertexts................................ 226 13.5 Verification of PKCS #1 v1.5 Signatures................................ 226 13.6 OAEP................................................... 227 13.7 ECC point decoding........................................... 227 13.8 ECC scalar multiply........................................... 227 13.9 ECDH.................................................. 228 13.10 ECDSA.................................................. 228 13.11 x25519.................................................. 228 13.12 TLS CBC ciphersuites.......................................... 228 13.13 CBC mode padding........................................... 228 13.14 AES.................................................... 229 13.15 GCM................................................... 229 13.16 OCB................................................... 229 13.17 Poly1305................................................. 229 13.18 DES/3DES................................................ 229 13.19 Twofish.................................................. 230 13.20 ChaCha20, Serpent, Threefish, . ..................................... 230 13.21 IDEA................................................... 230 13.22 Hash Functions.............................................. 230 13.23 Memory comparisons.......................................... 230 13.24 Memory zeroizing............................................ 230 13.25 Memory allocation............................................ 231 13.26 Automated Analysis........................................... 231 13.27 References................................................ 231 14 Developer Reference 233 14.1 Notes for New Contributors....................................... 233 14.2 Understanding configure.py....................................... 237 14.3 Test Framework............................................. 245 14.4 Continuous Integration and Automated Testing............................. 249 14.5 Fuzzing The Library........................................... 250 14.6 Release Process and Checklist...................................... 251 14.7 Todo List................................................. 254 14.8 OS Features............................................... 258 14.9 Private OID Assignments........................................ 260 14.10 Reading List............................................... 261 14.11 Mistakes Were Made........................................... 262 15 Release Notes: 0.7.0 to 1.11.34 265 15.1 Version 1.10.17, 2017-10-02....................................... 265 iii 15.2 Version 1.10.16, 2017-04-04....................................... 265 15.3 Version 1.10.15, 2017-01-12....................................... 265 15.4 Version 1.11.34, 2016-11-28....................................... 266 15.5 Version 1.10.14, 2016-11-28....................................... 268 15.6 Version 1.11.33, 2016-10-26....................................... 268 15.7 Version 1.11.32, 2016-09-28....................................... 269 15.8 Version 1.11.31, 2016-08-30....................................... 270 15.9 Version 1.11.30, 2016-06-19....................................... 272 15.10 Version 1.10.13,