Introduction ======================================== Botan (Japanese for peony) is a C++ cryptography library released under the permissive `Simplified BSD `_ license. It provides useful things like TLS, X.509 certificates, ECDSA, AES, GCM, ChaCha20Poly1305, and bcrypt, plus a kitchen sink of other crypto algorithms of various utility; see the full list below. Development is coordinated on `GitHub `_ and contributions are welcome. .. highlight:: none For all the details on building the library, read the `manual `_, but basically:: $ ./configure.py --help $ ./configure.py [probably some options] $ make $ ./botan-test # lots of output... Tests all ok $ ./botan # shows available commands $ make install If you need help or have questions, send a mail to the `mailing list `_ or open a ticket on `GitHub Issues `_. The `GitHub wiki `_ and `Doxygen docs `_ may also prove useful resources. In addition to C++ there are (partial, in-progress) bindings for C89, Python and OCaml included along with the library, and `Node.js `_ wrapper also exists. There is also a third party open source implementation of `SSHv2 `_ using the library. .. image:: https://travis-ci.org/randombit/botan.svg?branch=master :target: https://travis-ci.org/randombit/botan .. image:: https://ci.appveyor.com/api/projects/status/n9f94dljd03j2lce?svg=true :target: https://ci.appveyor.com/project/randombit/botan/branch/master .. image:: https://botan-ci.kullo.net/badge/build :target: https://botan-ci.kullo.net/ .. image:: https://botan-ci.kullo.net/badge/tests :target: https://botan-ci.kullo.net/ .. image:: https://coveralls.io/repos/randombit/botan/badge.svg?branch=master :target: https://coveralls.io/r/randombit/botan?branch=master Download ======================================== The 1.11 releases are highly recommended, especially for new development. All releases are signed with a `PGP key `_:: pub 2048R/EFBADFBC 2004-10-30 Key fingerprint = 621D AF64 11E1 851C 4CF9 A2E1 6211 EBF1 EFBA DFBC uid Botan Distribution Key Current Development Series (1.11) ---------------------------------------- The latest development release is `1.11.17 `_ `(sig) `_ Botan 1.11 requires a working C++11 compiler; GCC 4.8 and later, Clang 3.4 and later, and MSVC 2013 are regularly tested. Current Stable Series (1.10) ---------------------------------------- The latest stable branch release is `1.10.9 `_ `(sig) `_ 1.10 is the last version of botan written in C++98. From Your Favorite Distribution ---------------------------------------- Botan is already included in many package distributions, including `Fedora `_, `EPEL `_ (for RHEL/CentOS), `Debian `_, `Ubuntu `_, `Gentoo `_, `Arch `_, `Slackbuild `_, `FreeBSD ports `_, and `MacPorts `_. Books and other resources ======================================== It's a very good idea if you have some knowledge of cryptography *before* trying to use the library. This is an area where it is very easy to make mistakes, and where things are often subtle and/or counterintuitive. Obviously the library tries to provide things at a high level precisely to minimize the number of ways things can go wrong, but naive use will almost certainly not result in a secure system. Especially recommended are: - *Cryptography Engineering* by Niels Ferguson, Bruce Schneier, and Tadayoshi Kohno - *Security Engineering -- A Guide to Building Dependable Distributed Systems* by Ross Anderson - *Handbook of Applied Cryptography* by Alfred J. Menezes, Paul C. Van Oorschot, and Scott A. Vanstone (`available online `_) If you're doing something non-trivial or unique, you might want to at the very least ask for review/input on a mailing list such as the `metzdowd `_ or `randombit `_ crypto lists. And (if possible) pay a professional cryptographer or security company to review your design and code. Supported Algorithms/Protocols/RFCs ======================================== TLS/Public Key Infrastructure ---------------------------------------- * TLS/DTLS (v1.0 to v1.2), including using preshared keys (TLS-PSK) or passwords (TLS-SRP) and most important extensions (including secure renegotiation, session tickets, SNI, and ALPN) * X.509 certificates (including generating new self-signed and CA certs) and CRLs * PKIX certificate path validation, OCSP requests, PKCS #10 CSRs Public Key Cryptography ---------------------------------------- * Encryption algorithms RSA and ElGamal (with OAEP or PKCS #1 v1.5) * Signature algorithms RSA, DSA, ECDSA, GOST 34.10-2001, Nyberg-Rueppel, Rabin-Williams (with PSS, PKCS #1 v1.5, or X9.31) * Diffie-Hellman, ECDH using NIST/Brainpool prime groups, Curve25519 * McEliece code based encryption providing a KEM scheme Ciphers and cipher modes ---------------------------------------- * Authenticated cipher modes EAX, OCB, GCM, SIV, CCM, and ChaCha20Poly1305 * Unauthenticated cipher modes CTR, CBC, XTS, CFB, OFB, and ECB * AES (including constant time SSSE3 and AES-NI versions) * AES candidates Serpent, Twofish, MARS, CAST-256, RC6 * Stream ciphers Salsa20/XSalsa20, ChaCha20, and RC4 * DES, 3DES and DESX * National/telecom block ciphers SEED, KASUMI, MISTY1, GOST 28147 * Other block ciphers including Threefish-512, Blowfish, CAST-128, IDEA, Noekeon, TEA, XTEA, RC2, RC5, SAFER-SK * Large block cipher construction Lion Hash functions and MACs ---------------------------------------- * SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512 * SHA-3 winner Keccak-1600 * SHA-3 candidate Skein-512 * Authentication codes HMAC, CMAC, Poly1305, SipHash * RIPEMD-160, RIPEMD-128, Tiger, Whirlpool * Hash function combiners (Parallel and Comb4P) * National standard hashes HAS-160 and GOST 34.11 * Non-cryptographic checksums Adler32, CRC24, CRC32 * Obsolete algorithms MD5, MD4, MD2, CBC-MAC, X9.19 DES-MAC Other Useful Things ---------------------------------------- * Key derivation functions for passwords, including PBKDF2 * Password hashing functions, including bcrypt * General key derivation functions KDF1 and KDF2 from IEEE 1363 Recommended Algorithms ---------------------------------------- If your application is protecting network traffic, seriously consider using TLS v1.2 as a pre built, standard and well studied protocol. Otherwise, if you simply *must* do something custom, the developers currently recommend using: * Message encryption: AES or Serpent in GCM mode, or ChaCha20Poly1305 * General hash functions: SHA-256 or SHA-384 * Message authentication: HMAC with SHA-256 * Public Key Encryption: RSA, 2048+ bit keys, with OAEP and SHA-256 * Public Key Signatures: RSA, 2048+ bit keys with PSS and SHA-512, or ECDSA with P-256/SHA-256 or P-384/SHA-384 * Key Agreement: ECDH P-256 or Curve25519, with KDF2(SHA-256)