aboutsummaryrefslogtreecommitdiffstats
path: root/doc/manual/goals.rst
diff options
context:
space:
mode:
authorJack Lloyd <[email protected]>2016-12-30 13:58:11 -0500
committerJack Lloyd <[email protected]>2016-12-30 13:58:11 -0500
commit2412d26865c9e6789dd4649c248af59dc13995ad (patch)
treef89e104abac2dcd95c311e8c665c602664695228 /doc/manual/goals.rst
parent3233498b1529f267eb1d76963cba25edbb3335e2 (diff)
Add a statement of project goals (and non-goals)
[ci skip]
Diffstat (limited to 'doc/manual/goals.rst')
-rw-r--r--doc/manual/goals.rst129
1 files changed, 129 insertions, 0 deletions
diff --git a/doc/manual/goals.rst b/doc/manual/goals.rst
new file mode 100644
index 000000000..710324ece
--- /dev/null
+++ b/doc/manual/goals.rst
@@ -0,0 +1,129 @@
+
+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.
+
+* 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 and specialized attack
+ tools for common protocols.
+
+* 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 does not in every case strive to be faster than every other
+ software implementation, but performance should be competitive and over time
+ new optimizations are identified and applied.
+
+* 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 OSes
+ like Windows, Linux, and BSD and also relatively new OSes such as IncludeOS.
+
+* 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 5-15
+ years ago but which never saw widespread deployment and have no compelling
+ benefit over other designs were originally implemented in the library but have
+ since 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. 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.
+
+* FIPS 140 validation. The primary developer was (long ago) a consultant with a
+ NIST approved testing lab. He does not have a positive view of the process or
+ results, at least when it comes to Level 1 software validations (a Level 4
+ validation is however the real deal). The only benefit of a Level 1 validation
+ is to allow for government sales, and the cost of validation includes enormous
+ amounts of time and money, adding 'checks' that are useless or actively
+ harmful, then freezing the software version so security updates cannot be
+ applied in the future. It does force a certain minimum standard (ie, FIPS
+ Level 1 does assure AES and RSA are probably implemented correctly) but this
+ is an issue of interop not security since Level 1 does not seriously consider
+ attacks of any kind. Any security budget would be far better spent on a review
+ from a specialized crypto consultancy, who would look for actual flaws.
+
+ That said it would be easy to add a "FIPS 140" build mode to Botan, which just
+ disabled all the builtin crypto and wrapped whatever the most recent OpenSSL
+ FIPS module exports.
+
+* 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.