Resurrect algos.rst

3 files changed, 111 insertions, 7 deletions

diff --git a/doc/website/algos.rst b/doc/website/algos.rst
new file mode 100644
index 000000000..37285b6e6
--- /dev/null
+++ b/doc/website/algos.rst
@@ -0,0 +1,104 @@
+
+Supported Algorithms
+---------------------------------
+
+Botan supports a range of cryptographic algorithms and protocols,
+including:
+
+TLS/Public Key Infrastructure
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * SSL/TLS (from SSL v3 to TLS v1.2), including using preshared
+    keys (TLS-PSK) or passwords (TLS-SRP)
+  * X.509 certificates (including generating new self-signed and CA
+    certs) and CRLs
+  * Certificate path validation and OCSP
+  * PKCS #10 certificate requests (creation and certificate issue)
+
+Public Key Cryptography
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Encryption algorithms RSA, ElGamal, DLIES
+    (padding schemes OAEP or PKCS #1 v1.5)
+  * Signature algorithms RSA, DSA, ECDSA, GOST 34.10-2001, Nyberg-Rueppel,
+    Rabin-Williams (padding schemes PSS, PKCS #1 v1.5, X9.31)
+  * Key agreement techniques Diffie-Hellman and ECDH
+
+Hash functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512
+  * RIPEMD-160, RIPEMD-128, Tiger, Whirlpool
+  * SHA-3 winner Keccak-1600
+  * SHA-3 candidate Skein-512
+  * Hash function combiners (Parallel and Comb4P)
+  * National standard hashes HAS-160 and GOST 34.11
+  * Obsolete or insecure hashes MD5, MD4, MD2
+  * Non-cryptographic checksums Adler32, CRC24, CRC32
+
+Block ciphers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Authenticated cipher modes EAX, OCB, GCM, SIV, and CCM
+  * Unauthenticated cipher modes CTR, CBC, XTS, CFB, OFB, and ECB
+  * AES (including constant time SSSE3 and AES-NI versions)
+  * AES candidates Serpent, Twofish, MARS, CAST-256, RC6
+  * DES, and variants 3DES and DESX
+  * Other block ciphers including Threefish-512, Blowfish, CAST-128, IDEA,
+    Noekeon, TEA, XTEA, RC2, RC5, SAFER-SK, and Square
+  * National/telecom block ciphers SEED, KASUMI, MISTY1, GOST 28147, Skipjack
+  * Block cipher constructions Luby-Rackoff and Lion
+
+Stream Ciphers
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ * RC4
+ * Salsa20/XSalsa20
+ * ChaCha20
+ * CTR and OFB modes also present a stream cipher interface
+
+Authentication Codes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ * HMAC
+ * CMAC (aka OMAC1)
+ * Obsolete designs CBC-MAC, ANSI X9.19 DES-MAC, and the
+   protocol-specific SSLv3 authentication code
+
+Other Useful Things
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+  * Key derivation functions for passwords, including PBKDF2
+  * Password hashing functions, including bcrypt
+  * General key derivation functions KDF1 and KDF2 from IEEE 1363
+  * PRFs from ANSI X9.42, SSL v3.0, TLS v1.0
+
+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,
+support by other implementations, patent/IP status, and efficiency (in
+roughly that order).
+
+If your data is in motion, strongly consider using TLS v1.2 as a pre built,
+already standard and well studied protocol.
+
+Otherwise, if you simply *must* do something custom, use:
+
+* Message encryption: AES or Serpent in EAX or GCM mode
+
+* General hash functions: SHA-256 or SHA-512
+
+* Message authentication: HMAC with SHA-256
+
+* Public Key Encryption: RSA, 2048+ bit keys, with OAEP and SHA-256
+  ("EME1(SHA-256)")
+
+* Public Key Signatures: RSA, 2048+ bit keys with PSS and SHA-512
+  ("EMSA4(SHA-512)"), or ECDSA with SHA-256 or SHA-512
+
+* Key Agreement: Diffie-Hellman or ECDH, with "KDF2(SHA-256)"
diff --git a/doc/website/contents.rst b/doc/website/contents.rst
index 56454e990..2e7214577 100644
--- a/doc/website/contents.rst
+++ b/doc/website/contents.rst
@@ -13,4 +13,5 @@ Contents
    pgpkey
    credits
    users
+   algos
    relnotes/contents
diff --git a/doc/website/index.rst b/doc/website/index.rst
index 62d322c52..ef05d41d4 100644
--- a/doc/website/index.rst
+++ b/doc/website/index.rst
@@ -6,12 +6,12 @@ Botan is a crypto library for C++ released under the permissive
 :doc:`BSD-2 license <license>`.
 
 It provides useful things like SSL/TLS, X.509 certificates, ECDSA,
-AES, GCM, and bcrypt, plus a kitchen sink of crypto algorithms of
-various utility. A third party open source implementation of `SSHv2
-<http://www.netsieben.com/products/ssh/>`_ that uses botan is also
-available. In addition to C++ you can use botan from Python or Perl
-(both included in tree), or with `Node.js
-<https://github.com/justinfreitag/node-botan>`_.
+AES, GCM, and bcrypt, plus a :doc:`kitchen sink <algos>` of crypto
+algorithms of various utility. A third party open source
+implementation of `SSHv2 <http://www.netsieben.com/products/ssh/>`_
+that uses botan is also available. In addition to C++ you can use
+(parts of) botan from Python or Perl (both included in tree), or with
+`Node.js <https://github.com/justinfreitag/node-botan>`_.
 
 See the :doc:`faq` for a list of common questions and answers,
 :doc:`download` for information about getting the latest release,
@@ -24,4 +24,3 @@ Patches, "philosophical" bug reports, announcements of programs using
 the library, and related topics are also welcome. If you find what you
 believe to be a bug, please file a ticket in `Bugzilla
 <http://bugs.randombit.net/>`_.
-