Convert most of the documentation to reStructured Text, adding

a makefile to build it with Sphinx (http://sphinx.pocoo.org/).

Previously credits.txt listed public domain code sources; instead
directly credit the authors in the relevant files and delete that
file.

Drop the draft FIPS 140 security policy; I can't imagine FIPS 140
validation will ever happen, and if it does, I don't want
anything to do with it.

Also drop the internals doc, which was so out of date (and
incomplete) as to be worthless.

Move the tutorials and InSiTo pdfs into old/ for the time being,
until anything relevant from them can be filtered out and
converted into RST.

1 files changed, 169 insertions, 0 deletions

diff --git a/doc/intro.txt b/doc/intro.txt
new file mode 100644
index 000000000..c9a153563
--- /dev/null
+++ b/doc/intro.txt
@@ -0,0 +1,169 @@
+
+Introduction
+=================================
+
+Botan is a C++ library that attempts to provide the most common
+cryptographic algorithms and operations in an easy to use, efficient,
+and portable way. It runs on a wide variety of systems, and can be
+used with most modern C++ compilers.
+
+It is released under the 2 clause BSD license and can be used by
+commercial and open source software; see :ref:`license` for the
+specifics.
+
+The base library is written in ISO C++, so it can be ported with
+minimal fuss, but a modules system is also used. This system exposes
+system dependent code to the library through portable interfaces,
+extending the set of services available to users.
+
+The primary system targets are 32 and 64 bit CPUs, with a flat memory
+address space of at least 32 bits. Given the choice between optimizing
+for 32 bit systems and 64 bit systems, 64 bit is preferred, on the
+general theory that where performance is a real concern, modern 64 bit
+processors are the obvious choice. Smaller devices like handhelds,
+settop boxes, and smart phones are also capable of using Botan.
+
+The design makes it quite easy to remove unused algorithms in such a
+way that applications do not need to be recompiled to work, even
+applications that use the algorithm in question. They can ask the
+library if the algorithm exists, and if so, retrieve an object
+implementing that algorithm.
+
+Recommended Reading
+---------------------------------
+
+It's a very good idea if you 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*
+   Niels Ferguson, Bruce Schneier, and Tadayoshi Kohno
+
+ - *Security Engineering -- A Guide to Building Dependable Distributed Systems*
+   Ross Anderson
+
+ - *Handbook of Applied Cryptography* Alfred J. Menezes, Paul C. Van
+   Oorschot, and Scott A. Vanstone (available online at
+   http://www.cacr.math.uwaterloo.ca/hac/)
+
+Getting Help
+----------------------------------------
+
+Questions or problems you have with Botan can be directed to the
+`development mailing list
+<http://lists.randombit.net/mailman/listinfo/botan-devel/>`_.
+"Philosophical" bug reports, announcements of programs using Botan,
+and anything else having to do with Botan are also welcome.
+
+If you find what you believe to be a bug, please file a ticket in
+`Bugzilla <http://bugs.randombit.net/>`_.
+
+Getting Started
+---------------------------------
+
+All declarations in the library are contained within the namespace
+``Botan``, so you need to either prefix types with ``Botan::`` or add
+a ``using`` declaration in your code. All examples will assume a
+``using`` declaration.
+
+All library headers are included like so::
+
+  #include <botan/botan.h>
+
+Initializing the Library
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There is a set of core services that the library needs access to while
+it is performing requests. To ensure these are set up, you must create
+a ``LibraryInitializer`` object (usually called 'init' in Botan
+example code; 'botan\_library' or 'botan\_init' may make more sense in
+real applications) prior to making any calls to Botan. This object's
+lifetime must exceed that of all other Botan objects your application
+creates; for this reason the best place to create the
+``LibraryInitializer`` is at the start of your ``main``
+function, since this guarantees that it will be created first and
+destroyed last (via standard C++ RAII rules). The initializer does
+things like setting up the memory allocation system and algorithm
+lookup tables, finding out if there is a high resolution timer
+available to use, and similar such matters. With no arguments, the
+library is initialized with various default settings. So (unless you
+are writing threaded code; see below), all you need is::
+
+   Botan::LibraryInitializer init;
+
+at the start of your ``main``.
+
+The constructor takes an optional string that specifies arguments.
+Currently the only possible argument is "thread_safe", which must have
+an boolean argument (for instance "thread_safe=false" or
+"thread_safe=true"). If "thread_safe" is specified as true the library
+will attempt to register a mutex type to properly guard access to
+shared resources. However these locks do not protect individual Botan
+objects: explicit locking must be used if you wish to share a single
+object between threads.
+
+If you do not create a ``LibraryInitializer`` object, all library
+operations will fail, because it will be unable to do basic things
+like allocate memory or get random bits. You should never create more
+than one ``LibraryInitializer``.
+
+Pitfalls
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are a few things to watch out for to prevent problems when using
+the library.
+
+Never allocate any kind of Botan object globally. The problem with
+doing this is that the constructor for such an object will be called
+before the library is initialized. Many Botan objects will, in their
+constructor, make one or more calls into the library global state
+object. Access to this object is checked, so an exception should be
+thrown (rather than a memory access violation or undetected
+uninitialized object access). A rough equivalent that will work is to
+keep a global pointer to the object, initializing it after creating
+your ``LibraryInitializer``. Merely making the
+``LibraryInitializer`` also global will probably not help, because
+C++ does not make very strong guarantees about the order that such
+objects will be created.
+
+The same rule applies for making sure the destructors of all your
+Botan objects are called before the ``LibraryInitializer`` is
+destroyed. This implies you can't have static variables that are Botan
+objects inside functions or classes; in many C++ runtimes, these
+objects will be destroyed after main has returned.
+
+The memory object classes (``MemoryRegion``, ``MemoryVector``,
+``SecureVector``) are extremely primitive, and meant only for
+secure storage of potentially sensitive data like keys. They do not
+meet the requirements for an STL container object and you should not
+try to use them with STL algorithms. For a general-purpose container,
+use ``std::vector``.
+
+Use a ``try``/``catch`` block inside your ``main`` function, and catch
+any ``std::exception`` throws (remember to catch by reference, as
+``std::exception::what`` is polymorphic)::
+
+  int main()
+     {
+     try
+        {
+        LibraryInitializer init;
+
+        // ...
+        }
+     catch(std::exception& e)
+        {
+        std::cerr << e.what() << "\n";
+        }
+     }
+
+This is not strictly required, but if you don't, and Botan throws an
+exception, the runtime will call ``std::terminate``, which usually
+calls ``abort`` or something like it, leaving you (or worse, a user of
+your application) wondering what went wrong.