diff options
Diffstat (limited to 'doc/source/manual/methods.rst')
| -rw-r--r-- | doc/source/manual/methods.rst | 100 |
1 files changed, 100 insertions, 0 deletions
diff --git a/doc/source/manual/methods.rst b/doc/source/manual/methods.rst new file mode 100644 index 0000000..e4ea962 --- /dev/null +++ b/doc/source/manual/methods.rst @@ -0,0 +1,100 @@ +Encryption & authentication methods +=================================== +fastd supports various combinations of ciphers and authentication schemes using +different method providers. All ciphers, message authentication codes (MACs) and +method providers can be disabled during compilation to reduce the binary size. + +See `Benchmarks <https://projects.universe-factory.net/projects/fastd/wiki/Benchmarks>`_ for an +overview of the performance of the different methods. + +Recommended methods +~~~~~~~~~~~~~~~~~~~ +The method ``salsa2012+umac`` is recommended for authenticated encyption. ``null+salsa2012+umac`` is the +recommended method for authenticated-only operation. + +Salsa20/12 is a stream cipher with very high speed and a very comfortable security margin. +It has been chosed for the software profile in the `eSTREAM <http://en.wikipedia.org/wiki/ESTREAM>`_ project in 2008. + +`UMAC <http://en.wikipedia.org/wiki/UMAC>`_ is an extremely fast message authentication code which is provably +secure and optimized for software implementations. + +OpenWrt +------- +Too keep the binary as small as possible, only the following methods are enabled on OpenWrt +by default: + +* ``salsa2012+gmac`` +* ``salsa2012+umac`` +* ``null+salsa2012+gmac`` +* ``null+salsa2012+umac`` +* ``null`` + +Of these, the GMAC-based methods may be dropped in the future to further reduce the binary size, as UMAC is +the superior authentication scheme (it is faster than GMAC, provably secure and its software implementation +isn't suspect to timing side channels). + +List of methods +~~~~~~~~~~~~~~~ + +Encrypted methods +----------------- +======================= ================ ========== ========= ====== +Method Method provider Cipher MAC Notes +======================= ================ ========== ========= ====== +``aes128-gcm`` generic-gmac aes128-ctr ghash [2]_ +``salsa20+gmac`` generic-gmac salsa20 ghash +``salsa2012+gmac`` generic-gmac salsa2012 ghash +``aes128-ctr+umac`` generic-umac aes128-ctr uhash [2]_ +``salsa20+umac`` generic-umac salsa20 uhash +``salsa2012+umac`` generic-umac salsa2012 uhash +``aes128-ctr+poly1305`` generic-poly1305 aes128-ctr none [1]_ [2]_, [3]_ +``salsa20+poly1305`` generic-poly1305 salsa20 none [1]_ [3]_ +``salsa2012+poly1305`` generic-poly1305 salsa2012 none [1]_ [3]_ +======================= ================ ========== ========= ====== + +This list is not exhaustive. It is possible to combine different ciphers for +data and authentication tag encryption using the *composed-gmac* and *composed-umac* +method providers; these methods aren't listed here as this is not very useful. + +Authenticated-only methods +-------------------------- +======================== ================ ========== ===== ====== +Method Method provider Cipher MAC Notes +======================== ================ ========== ===== ====== +``null+aes128-gmac`` composed-gmac aes128-ctr ghash [2]_, [4]_ +``null+salsa20+gmac`` composed-gmac salsa20 ghash [4]_ +``null+salsa2012+gmac`` composed-gmac salsa2012 ghash [4]_ +``null+aes128-ctr+umac`` composed-umac aes128-ctr uhash [2]_, [4]_ +``null+salsa20+umac`` composed-umac salsa20 uhash [4]_ +``null+salsa2012+umac`` composed-umac salsa2012 uhash [4]_ +======================== ================ ========== ===== ====== + +Methods without security +------------------------ +======== =============== ====== ==== ===== +Method Method provider Cipher MAC Notes +======== =============== ====== ==== ===== +``null`` null none none [5]_ +======== =============== ====== ==== ===== + + +Deprecated methods +------------------ + +======================== ================= ========== ===== ====== +Method Method provider Cipher MAC Notes +======================== ================= ========== ===== ====== +``xsalsa20-poly1305`` xsalsa20-poly1305 none none [6]_ +======================== ================= ========== ===== ====== + + Since fastd v11 ``salsa20+poly1305`` should be used instead (or even better a more performant + method like salsa2012+gmac); ``xsalsa20-poly1305`` will be removed eventually. + + +.. [1] The MAC is integrated in the method provider. +.. [2] AES is very slow without OpenSSL support. OpenSSL's AES implementation may be suspect to cache timing side channels when no hardware support like AES-NI is available. +.. [3] Poly1305 is very slow on embedded systems. +.. [4] The cipher is used to encrypt the authentication tag only, the actual data is transmitted unencrypted. +.. [5] Only authentication of peers' IP addresses, but no encryption or authentication of any data is provided. +.. [6] Both the cipher and the MAC are integrated in the method provider. + |