From 0dfa34ac9491754dc57d4bbc5f3b507f8d4cbb6d Mon Sep 17 00:00:00 2001 From: Matthias Schiffer Date: Wed, 5 Nov 2014 20:47:25 +0100 Subject: docs: documentation of crypto algorithms --- doc/source/crypto/ciphers.rst | 58 ++++++++++++++++++++++++++++++ doc/source/crypto/macs.rst | 48 +++++++++++++++++++++++++ doc/source/crypto/methods.rst | 84 +++++++++++++++++++++++++++++++++++++++++++ doc/source/index.rst | 3 ++ 4 files changed, 193 insertions(+) create mode 100644 doc/source/crypto/ciphers.rst create mode 100644 doc/source/crypto/macs.rst create mode 100644 doc/source/crypto/methods.rst (limited to 'doc') 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 `_. + +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 `_ 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 `_ 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 `_ message authentication code +defined in [RFC4418]_ is a strongly universal hash function, which +is formed by defining a `universal hash function `_ +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 "+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 "++gmac", and "+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 "+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 "++umac". + +generic-poly1305 +~~~~~~~~~~~~~~~~ + +The *generic-umac* provider combines the `Poly1305 `_ 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 "+poly1305". + +xsalsa20-poly1305 +~~~~~~~~~~~~~~~~~ + +The *xsalsa20-poly1305* provider only provides a single method, "xsalsa20-poly1305", +which uses the "secret box" provided by the `NaCl `_ 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-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 -- cgit v1.2.3