Botan (Japanese for peony) is a C++ cryptography library released under the permissive Simplified BSD license.
It provides TLS, X.509 certificates, OCSP, ECDSA, AES, GCM, ChaCha20Poly1305, and bcrypt, and quite a few other things. It also provides a botan command line tool for various cryptographic operations, the source for which also helps demonstrate usage of the library.
Development is coordinated on GitHub and contributions are welcome. Read doc/hacking.rst for more about how to contribute.
For all the details on building the library, read the users 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
The library can also be built into a single-file amalgamation for easy inclusion into external build systems.
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++, botan has a C89 API specifically designed to be easy to call from other languages. A Python binding using ctypes is included, there are also bindings for Node.js and OCaml
There is also a third party open source implementation of SSHv2 using the library.
The 1.11 branch is highly recommended, especially for new development. But be warned the API is still subject to some change before the 2.0 stable release.
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
Botan may already be included in your favorite distribution, such as Fedora, EPEL (for RHEL/CentOS), Debian, Ubuntu, Gentoo, Arch, Slackbuild, FreeBSD ports, or MacPorts.
A new development release is made on the first Monday of every month.
The latest development release is 1.11.20 (sig) released 2015-09-07
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.
The latest stable branch release is 1.10.10 (sig) released 2015-08-03
Botan 1.10 is the last version written in C++98.
You should 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.
- 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
- 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
- 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
- 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
- Key derivation functions for passwords, including PBKDF2
- Password hashing functions, including bcrypt
- General key derivation functions KDF1 and KDF2 from IEEE 1363
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)