
Project Goals
================================

Botan seeks to be a broadly applicable library that can be used to implement a
range of secure distributed systems.

The library has the following project goals guiding changes. It does not succeed
in all of these areas in every way just yet, but it describes the system that is
the desired end result. Over time further progress is made in each.

* Secure and reliable. The implementations must of course be correct and well
  tested, and attacks such as side channels and fault attacks should be
  accounted for where necessary. The library should never crash, or invoke
  undefined behavior, regardless of circumstances.

* Constant time programming. The table stakes for a modern cryptographic library
  include being immune to basic timing/cache based side channels. Botan includes
  utilities to assist in writing and testing constant time code. A test suite
  run nightly in CI verifies Botan's constant time behavior across a range of
  compilers, compiler options, and CPU architectures.

* Implement schemes important in practice. It should be practical to implement
  any real-world crypto protocol using just what the library provides. It is
  worth some (limited) additional complexity in the library, in order to expand
  the set of applications which can easily adopt Botan.

* Ease of use. It should be straightforward for an application programmer to do
  whatever it is they need to do. There should be one obvious way to perform any
  operation. The API should be predicable, and follow the "principle of least
  astonishment" in its design. This is not just a nicety; confusing APIs often
  result in errors that end up compromising security.

* Simplicity of design, clarity of code, ease of review. The code should be easy
  to read and understand by other library developers, users seeking to better
  understand the behavior of the code, and by professional reviewers looking for
  bugs. This is important because bugs in convoluted code can easily escape
  multiple expert reviews, and end up living on for years.

* Well tested. The code should be correct against the spec, with as close to
  100% test coverage as possible. All available static and dynamic analysis
  tools at our disposal should be used, including fuzzers, symbolic execution,
  and protocol specific tools. Within reason, all warnings from compilers and
  static analyzers should be addressed, even if they seem like false positives,
  because that maximizes the signal value of new warnings from the tool.

* Safe defaults. Policies should aim to be highly restrictive by default, and if
  they must be made less restrictive by certain applications, it should be
  obvious to the developer that they are doing something unsafe.

* Post quantum security. Possibly a practical quantum computer that can break
  RSA and ECC will never be built, but the future is notoriously hard to predict.
  It seems prudent to begin designing and deploying systems now which have at
  least the option of using a post-quantum scheme. Botan provides a conservative
  selection of algorithms thought to be post-quantum secure.

* Performance. Botan aims to have the fastest possible implementation of all
  algorithms it supports, subject to the constraints implicit with the other
  project goals.

* Support whatever I/O mechanism the application wants. Allow the application to
  control all aspects of how the network is contacted, and ensure the API makes
  asynchronous operations easy to handle. This both insulates Botan from
  system-specific details and allows the application to use whatever networking
  style they please.

* Portability to modern systems. Botan does not run everywhere, and we actually
  do not want it to (see non-goals below). But we do want it to run on anything
  that someone is deploying new applications on. That includes both major
  platforms like Windows, Linux, Android and iOS, and also promising new systems
  such as Fuchsia.

* Well documented. Ideally every public API would have some place in the manual
  describing its usage.

* Useful command line utility. The botan command line tool should be flexible
  and featured enough to replace similar tools such as ``openssl`` for everyday
  users.

Non-Goals
-------------------------

There are goals some crypto libraries have, but which Botan actively does not
seek to address.

* Deep embedded support. Botan requires a heap, C++ exceptions, and RTTI, and at
  least in terms of performance optimizations effectively assumes a 32 or 64 bit
  processor. It is not suitable for deploying on, say FreeRTOS running on a
  MSP430, or smartcard with an 8 bit CPU and 256 bytes RAM. A larger SoC, such
  as a Cortex-A7 running Linux, is entirely within scope.

* Implementing every crypto scheme in existence. The focus is on algorithms
  which are in practical use in systems deployed now, as well as promising
  algorithms for future deployment. Many algorithms which were of interest
  in the past but never saw widespread deployment and have no compelling
  benefit over other designs have been removed to simplify the codebase.

* Portable to obsolete systems. There is no reason for crypto software to
  support ancient OS platforms like SunOS or Windows 2000, since these unpatched
  systems are completely unsafe anyway. The additional complexity supporting
  such platforms just creates more room for bugs.

* Portable to every C++ compiler ever made. Over time Botan moves forward to
  both take advantage of new language/compiler features, and to shed workarounds
  for dealing with bugs in ancient compilers, allowing further simplifications
  in the codebase. The set of supported compilers is fixed for each new release
  branch, for example Botan 2.x will always support GCC 4.8. But a future 3.x
  release version will likely increase the required versions for all compilers.

* Educational purposes. The library code is intended to be easy to read and
  review, and so might be useful in an educational context. However it does not
  contain any toy ciphers (unless you count DES and RC4) nor any tools for
  simple cryptanalysis. Generally the manual and source comments assume previous
  knowledge on the basic concepts involved.

* User proof. Some libraries provide a very high level API in an attempt to save
  the user from themselves. Occasionally they succeed. It would be appropriate
  and useful to build such an API on top of Botan, but Botan itself wants to
  cover a broad set of uses cases and some of these involve having pointy things
  within reach.
