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, 78 insertions, 0 deletions

diff --git a/doc/algos.txt b/doc/algos.txt
new file mode 100644
index 000000000..0221405d6
--- /dev/null
+++ b/doc/algos.txt
@@ -0,0 +1,78 @@
+Algorithms
+=================================
+
+Recommended Algorithms
+---------------------------------
+
+This section is by no means the last word on selecting which
+algorithms to use.  However, Botan includes a sometimes bewildering
+array of possible algorithms, and unless you're familiar with the
+latest developments in the field, it can be hard to know what is
+secure and what is not. The following attributes of the algorithms
+were evaluated when making this list: security, standardization,
+patent status, support by other implementations, and efficiency (in
+roughly that order).
+
+It is intended as a set of simple guidelines for developers, and
+nothing more.  It's entirely possible that there are algorithms in
+Botan that will turn out to be more secure than the ones listed, but
+the algorithms listed here are (currently) thought to be safe.
+
+ - Block ciphers: AES or Serpent in CBC, CTR, or XTS mode
+
+ - Hash functions: SHA-256, SHA-512
+
+ - MACs: HMAC with any recommended hash function
+
+ - Public Key Encryption: RSA with "EME1(SHA-256)"
+
+ - Public Key Signatures: RSA with EMSA4 and any recommended
+    hash, or DSA or ECDSA with "EMSA1(SHA-256)"
+
+ - Key Agreement: Diffie-Hellman or ECDH, with "KDF2(SHA-256)"
+
+Algorithms Listing
+---------------------------------
+
+Botan includes a very sizable number of cryptographic algorithms. In
+nearly all cases, you never need to know the header file or type name
+to use them. However, you do need to know what string (or strings) are
+used to identify that algorithm. These names conform to those set out
+by SCAN (Standard Cryptographic Algorithm Naming), which is a document
+that specifies how strings are mapped onto algorithm objects, which is
+useful for a wide variety of crypto APIs (SCAN is oriented towards
+Java, but Botan and several other non-Java libraries also make at
+least some use of it). For full details, read the SCAN document, which
+can be found at
+http://www.users.zetnet.co.uk/hopwood/crypto/scan/
+
+Many of these algorithms can take options (such as the number of
+rounds in a block cipher, the output size of a hash function,
+etc). These are shown in the following list; all of them default to
+reasonable values. There are algorithm-specific limits on most of
+them. When you see something like "HASH" or "BLOCK", that means
+you should insert the name of some algorithm of that type. There are
+no defaults for those options.
+
+A few very obscure algorithms are skipped; if you need one of them,
+you'll know it, and you can look in the appropriate header to see what
+that classes' ``name`` function returns (the names tend to
+match that in SCAN, if it's defined there).
+
+ - ROUNDS: The number of rounds in a block cipher.
+ - OUTSZ: The output size of a hash function or MAC
+
+**Block Ciphers:** "AES-128", "AES-192", "AES-256", "Blowfish",
+"CAST-128", "CAST-256", "DES", "DESX", "TripleDES", "GOST-28147-89",
+"IDEA", "KASUMI", "MARS", "MISTY1(ROUNDS)", "Noekeon", "RC2",
+"RC5(ROUNDS)", "RC6", "SAFER-SK(ROUNDS)", "SEED", "Serpent",
+"Skipjack", "Square", "TEA", "Twofish", "XTEA"
+
+**Stream Ciphers:** "ARC4", "MARK4", "Salsa20", "Turing",
+"WiderWake4+1-BE"
+
+**Hash Functions:** "HAS-160", "GOST-34.11", "MD2", "MD4", "MD5",
+"RIPEMD-128", "RIPEMD-160", "SHA-160", "SHA-256", "SHA-384",
+"SHA-512", "Skein-512", "Tiger(OUTSZ)", "Whirlpool"
+
+**MACs:** "HMAC(HASH)", "CMAC(BLOCK)", "X9.19-MAC"