docs: documentation of crypto algorithms

4 files changed, 193 insertions, 0 deletions

diff --git a/doc/source/crypto/ciphers.rst b/doc/source/crypto/ciphers.rst
new file mode 100644
index 0000000..0a60689
--- /dev/null
+++ b/doc/source/crypto/ciphers.rst
@@ -0,0 +1,58 @@
+Ciphers
+=======
+Generally, all ciphers used by fastd
+are `stream ciphers <http://en.wikipedia.org/wiki/Stream_cipher>`_.
+
+This means that the cipher outputs a cipher stream indistinguishable
+from a random byte stream which can be used to encrypt packets of any
+length without a need for padding the packet site to a multiple of a
+block size by just XORing the cipher stream with the packet.
+
+AES128-CTR
+~~~~~~~~~~
+The Advanced Encryption Standard is a widely used, highly regarded block cipher
+specified in [FIPS197]_.
+
+In counter mode a nonce of up to 12 bytes in concatenated with a 4 byte counter;
+this value is encrypted with the block cipher to compute 16 bytes of the cipher stream.
+
+AES128 has been chosen in contrast to the stronger variants AES192 and AES256 as
+hardware acceleration for AES128 is more widely available on embedded hardware.
+Using this acceleration hardware from userspace through the
+alg_if interface of the Linux kernel is very complex though, so support for it has
+been removed from fastd again (but may still be used through OpenSSL.
+
+One issue with the AES algorithm is that it is very hard to implement in a way
+that is safe against cache timing attacks (see [Ber05a]_ for details). Because
+of that fastd can make use of two different AES implementations: a very secure, but
+also very slow implementation from the `NaCl <http://nacl.cr.yp.to/>`_ library, and
+the implementations from OpenSSL (which can either use hardware acceleration like AES-NI,
+or a fast, but potentially insecure software implementation).
+
+Salsa20(/12)
+~~~~~~~~~~~~
+Salsa20 (see [Ber07]_) is a state-of-the-art stream cipher which is very fast and very secure. In contrast to
+AES, it is easily implementable without any timing side channels.
+
+Salsa20/12 is a variant of Salsa20 which uses only 12 instead of 20 rounds
+to improve performance. The Salsa20/12 has been chosen for the software profile on the `eSTREAM <http://www.ecrypt.eu.org/stream/>`_ portfolio in
+2011 as it has a very high throughput while providing a very comfortable security margin.
+
+The even more reduced variant Salsa20/8 has also been evaluated for fastd,
+but the performance gain has been to small to warrant the significantly
+reduced security.
+
+Bibliography
+~~~~~~~~~~~~
+.. [Ber05a]
+   D. J. Bernstein, "Cache-timing attacks on AES", 2005. [Online]
+   http://cr.yp.to/antiforgery/cachetiming-20050414.pdf
+
+.. [Ber07]
+   D. J. Bernstein, "The Salsa20 family of stream ciphers", 2007. [Online]
+   http://cr.yp.to/snuffle/salsafamily-20071225.pdf
+
+.. [FIPS197]
+   National Institute of Standards and Technology, "ADVANCED ENCRYPTION STANDARD (AES)",
+   Federal Information Processing Standard 197, 2001. [Online]
+   http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf
diff --git a/doc/source/crypto/macs.rst b/doc/source/crypto/macs.rst
new file mode 100644
index 0000000..7b8a821
--- /dev/null
+++ b/doc/source/crypto/macs.rst
@@ -0,0 +1,48 @@
+Message Authentication Codes
+============================
+
+GHASH / Galois/Counter Mode (GCM) / GMAC
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Galois/Counter Mode is a very well-known mode of operation for block ciphers which
+was specified in [MV04]_. GMAC is a authentication-only variant of the algorithm.
+
+While the original specification only considers block ciphers, GCM can also be specified
+in terms of the Counter mode (CTR) of the block cipher. The counter mode transforms a
+block cipher into a stream cipher. This allows it to replace the block cipher by any stream
+cipher while preserving all security guarantees; thereforce fastd allows to use GMAC with
+any supported stream cipher.
+
+One particular issue with GCM/GMAC is that it is hard to implement in software.
+Usually it is implemented using lookup table, which might exhibit cache timing
+side channels. This issue doesn't affect modern x86 CPUs providing the PCLMUL
+instruction, as PCLMUL allows performing carry-less multiplications without
+a lookup table.
+
+UHASH / UMAC
+~~~~~~~~~~~~
+
+The `UMAC <http://en.wikipedia.org/wiki/UMAC>`_ message authentication code
+defined in [RFC4418]_ is a strongly universal hash function, which
+is formed by defining a `universal hash function <http://en.wikipedia.org/wiki/Universal_hashing>`_
+UHASH and XORing it with a pad generated by a block cipher like AES.
+
+In fastd, the pad can be generated by any supported stream cipher, and the
+key derivation function specified in the RFC has been replaced by HKDF.
+
+The UHASH function is optimized for efficient implementation in software on
+32bit CPUs. Therefore UMAC is much more performant than GMAC, especially
+on embedded systems, and doesn't exhibit any timing side channels.
+
+Bibliography
+~~~~~~~~~~~~
+
+.. [MV04]
+   D. McGrew and J. Viega, "The Galois/counter mode of operation (GCM)", Submission
+   to NIST Modes of Operation Process, 2004.
+
+.. [RFC4418]
+   T. Krovetz, "UMAC: Message Authentication Code using Universal Hashing",
+   RFC4418 (Informational), Internet Engineering Task Force,
+   2006. [Online] http://www.ietf.org/rfc/rfc4418.txt
+
diff --git a/doc/source/crypto/methods.rst b/doc/source/crypto/methods.rst
new file mode 100644
index 0000000..bbc1690
--- /dev/null
+++ b/doc/source/crypto/methods.rst
@@ -0,0 +1,84 @@
+Method providers
+================
+
+See :doc:`/manual/methods` for details about the method
+configuration and recommendations.
+
+generic-gmac
+~~~~~~~~~~~~
+
+The *generic-gmac* provider combines the GHASH message authetication code
+with any stream cipher, which is used both to encrypt the data and the
+authentication tag.
+
+After the last encrypted data block, a block containing the length of
+the data (in bits, big endian) is passed to the GHASH function as defined
+by the GCM specification.
+
+The method names normally have the form "<cipher>+gmac", and "aes128-gcm"
+for the AES128 cipher.
+
+composed-gmac
+~~~~~~~~~~~~~
+
+The *composed-gmac* provider combines the GHASH message authetication code
+with two stream ciphers, where the first one is used to encrypt the data and the second one for the
+authentication tag. As only the authentication tag must be encrypted, "null" can be used
+as the first cipher for authenticated-only methods.
+
+After the last encrypted data block, a block with the first 8 bytes containing the length of
+the data (in bits, big endian) and the other 8 bytes set to zero is passed to the GHASH function.
+This differs from the size block used by the *generic-gmac* for historical reasons.
+
+The method names normally have the form "<cipher>+<cipher>+gmac", and "<cipher>+aes128-gmac"
+for the AES128 cipher.
+
+generic-umac
+~~~~~~~~~~~~
+
+The *generic-umac* provider combines the UHASH message authetication code
+with any stream cipher, which is used both to encrypt the data and the
+authentication tag.
+
+The method names have the form "<cipher>+umac".
+
+composed-umac
+~~~~~~~~~~~~~
+
+The *composed-umac* provider combines the UHASH message authetication code
+with two stream ciphers, where the first one is used to encrypt the data and the second one for the
+authentication tag. As only the authentication tag must be encrypted, "null" can be used
+as the first cipher for authenticated-only methods.
+
+The method names have the form "<cipher>+<cipher>+umac".
+
+generic-poly1305
+~~~~~~~~~~~~~~~~
+
+The *generic-umac* provider combines the `Poly1305 <http://cr.yp.to/mac.html>`_ message authentication code
+with any stream cipher, which is used both to encrypt the data and the
+authentication tag. This method was added to replace the deprecated *xsalsa20-poly1305*
+method, but may be removed as well in the long term as UMAC is generally more performant
+and makes the same security guarantees.
+
+The method names have the form "<cipher>+poly1305".
+
+xsalsa20-poly1305
+~~~~~~~~~~~~~~~~~
+
+The *xsalsa20-poly1305* provider only provides a single method, "xsalsa20-poly1305",
+which uses the "secret box" provided by the `NaCl <http://nacl.cr.yp.to/>`_ library.
+It is deprecated and should be used for connections with very old fastd versions only.
+
+null
+~~~~
+
+The "null" method doesn't provide any encryption or authentication.
+
+cipher-test
+~~~~~~~~~~~
+
+The *cipher-test* method can be used to run a cipher without any authentication.
+This isn't secure and should be used for tests and benchmarks only.
+
+The method names have the form "<cipher>+cipher-test".
diff --git a/doc/source/index.rst b/doc/source/index.rst
index a53c0ed..0a6defe 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -21,6 +21,9 @@ Cryptographic algorithms
 
    crypto/ec25519
    crypto/fhmqvc
+   crypto/ciphers
+   crypto/macs
+   crypto/methods
 
 
 Developer documentation