Botan: Crypto and TLS for C++11

Botan (Japanese for peony) is a C++ cryptography library
released under the permissive
Simplified BSD <http://botan.randombit.net/license.txt>_ 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 <https://github.com/randombit/botan>_
and contributions are welcome.

.. highlight:: none

For all the details on building the library, read the
users manual <http://botan.randombit.net/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 <http://lists.randombit.net/mailman/listinfo/botan-devel/>_
or open a ticket on
GitHub Issues <https://github.com/randombit/botan/issues>_.

The GitHub wiki <https://github.com/randombit/botan/wiki>_
and Doxygen docs <https://botan.randombit.net/doxygen>_
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 <https://github.com/justinfreitag/node-botan>_ wrapper also
exists.

There is also a third party open source implementation of
SSHv2 <https://github.com/cdesjardins/cppssh>_ 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
:target: https://botan-ci.kullo.net/

.. image:: https://scan.coverity.com/projects/624/badge.svg
:target: https://scan.coverity.com/projects/624

.. image:: https://coveralls.io/repos/randombit/botan/badge.svg?branch=master
:target: https://coveralls.io/r/randombit/botan?branch=master

Download
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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 <http://botan.randombit.net/pgpkey.txt>_::

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 <https://admin.fedoraproject.org/pkgdb/packages/botan>,
EPEL <http://dl.fedoraproject.org/pub/epel/7/SRPMS/repoview/botan.html> (for RHEL/CentOS),
Debian <http://packages.debian.org/search?keywords=libbotan>,
Ubuntu <http://packages.ubuntu.com/search?keywords=botan>,
Gentoo <http://packages.gentoo.org/package/botan>,
Arch <http://www.archlinux.org/packages/community/x86_64/botan/>,
Slackbuild <http://slackbuilds.org/result/?search=Botan>,
FreeBSD ports <http://www.freshports.org/security/botan110>, or
MacPorts <http://www.macports.org/ports.php?by=name&substr=botan>_.

Current Development Series (1.11)

A new development release is made on the first Monday of every month.

The latest development release is
1.11.18 <http://botan.randombit.net/releases/Botan-1.11.18.tgz>_
(sig) <http://botan.randombit.net/releases/Botan-1.11.18.tgz.asc>_
released 2015-07-05

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 <http://botan.randombit.net/releases/Botan-1.10.9.tgz>_
(sig) <http://botan.randombit.net/releases/Botan-1.10.9.tgz.asc>_
released 2014-12-13

Botan 1.10 is the last version written in C++98.

Books and other resources
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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 <http://www.cacr.math.uwaterloo.ca/hac/>_)

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 <http://www.metzdowd.com/mailman/listinfo/cryptography>_ or
randombit <http://lists.randombit.net/mailman/listinfo/cryptography>_
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 randombit#10 CSRs

Public Key Cryptography

Encryption algorithms RSA and ElGamal (with OAEP or PKCS randombit#1 v1.5)
Signature algorithms RSA, DSA, ECDSA, GOST 34.10-2001, Nyberg-Rueppel,
Rabin-Williams (with PSS, PKCS randombit#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)

alexger/botan