diff options
Diffstat (limited to 'doc/manual')
| -rw-r--r-- | doc/manual/contents.rst | 1 | ||||
| -rw-r--r-- | doc/manual/goals.rst | 129 |
2 files changed, 130 insertions, 0 deletions
diff --git a/doc/manual/contents.rst b/doc/manual/contents.rst index cddfc4814..79e410051 100644 --- a/doc/manual/contents.rst +++ b/doc/manual/contents.rst @@ -5,6 +5,7 @@ Contents .. toctree:: index + goals building platforms python 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. |