From 468245ce5621e1a93a1d48404ef17f505f9e4df2 Mon Sep 17 00:00:00 2001 From: Karel Miko Date: Thu, 20 Jul 2017 23:09:28 +0200 Subject: [PATCH] doc: stream ciphers --- doc/crypt.tex | 137 ++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 99 insertions(+), 38 deletions(-) diff --git a/doc/crypt.tex b/doc/crypt.tex index 2d08344..c4cd7fd 100644 --- a/doc/crypt.tex +++ b/doc/crypt.tex @@ -1233,53 +1233,114 @@ int f8_done(symmetric_F8 *f8); \chapter{Stream Ciphers} -\mysection{RC4} +Stream ciphers are symmetric key ciphers which operate on a stream of bytes (in theory on a stream of bits +however LibTomCrypt's implementation works with bytes). -XXX-TODO +The API for all stream ciphers operates in mode: \textit{setup} -- \textit{crypt} -- \textit{crypt} -- ... -- \textit{done}. +Please note that both encryption and decryption is implemented via \textit{crypt}. -\begin{small} -\begin{verbatim} -int rc4_stream_setup(rc4_state *st, const unsigned char *key, unsigned long keylen); -int rc4_stream_crypt(rc4_state *st, const unsigned char *in, unsigned long inlen, unsigned char *out); -int rc4_stream_done(rc4_state *st); -int rc4_stream_keystream(rc4_state *st, unsigned char *out, unsigned long outlen); -\end{verbatim} -\end{small} - -\url{https://en.wikipedia.org/wiki/RC4} - -\mysection{Sober128} - -XXX-TODO - -\begin{small} -\begin{verbatim} -int sober128_stream_setup(sober128_state *st, const unsigned char *key, unsigned long keylen); -int sober128_stream_setiv(sober128_state *st, const unsigned char *iv, unsigned long ivlen); -int sober128_stream_crypt(sober128_state *st, const unsigned char *in, unsigned long inlen, unsigned char *out); -int sober128_stream_done(sober128_state *st); -int sober128_stream_keystream(sober128_state *st, unsigned char *out, unsigned long outlen); -\end{verbatim} -\end{small} - -\url{https://en.wikipedia.org/wiki/SOBER-128} +Another useful feature of stream ciphers API is generation of random stream of bytes which works like: +\textit{setup} -- \textit{keystream} -- \textit{keystream} -- ... -- \textit{done}. The random stream generation is +implemented like encryption of a stream o zero bytes. \mysection{ChaCha} -XXX-TODO +The \textit{ChaCha} is currently the most modern stream cipher included in LibTomCrypt, so use this one unless you +have a reason for using some of the older algorithms. -\begin{small} +For more information about ChaCha see \url{https://en.wikipedia.org/wiki/ChaCha_(cipher)}. + +Supported key size: 16 or 32 bytes (128 or 256 bits). + +You can initialize ChaCha with 96bit \textit{nonce} + 32bit \textit{counter}: \begin{verbatim} -int chacha_setup(chacha_state *st, const unsigned char *key, unsigned long keylen, int rounds); -int chacha_ivctr32(chacha_state *st, const unsigned char *iv, unsigned long ivlen, ulong32 counter); -int chacha_ivctr64(chacha_state *st, const unsigned char *iv, unsigned long ivlen, ulong64 counter); -int chacha_crypt(chacha_state *st, const unsigned char *in, unsigned long inlen, unsigned char *out); -int chacha_done(chacha_state *st); -int chacha_keystream(chacha_state *st, unsigned char *out, unsigned long outlen); +chacha_state st; +err = chacha_setup(&st, key, key_len, rounds); +err = chacha_ivctr32(&st, nonce, 12, initial_32bit_ctr); \end{verbatim} -\end{small} -\url{https://en.wikipedia.org/wiki/ChaCha_(cipher)} +Or with 64bit \textit{nonce} + 64bit \textit{counter}: +\begin{verbatim} +chacha_state st; +err = chacha_setup(&st, key, key_len, rounds); +err = chacha_ivctr64(&st, nonce, 8, initial_64bit_ctr); +\end{verbatim} + +The \textit{chacha\_setup} takes as a parameter the number of rounds -- choose 20 if you are not sure. +As always never ever used the same key + nonce pair more than once. + +For the actual encryption or decryption you to call: +\begin{verbatim} +err = chacha_crypt(&st, in_buffer, in_len, out_buffer); +\end{verbatim} + +If you just want a random stream of bytes initialize the cipher with truly random \textit{key} (32 bytes), +truly random \textit{nonce} (8 bytes) and zero initial counter. After that you can get a stream of pseudo--random +bytes via: +\begin{verbatim} +err = chacha_keystream(&st, out_buffer, out_len); +\end{verbatim} + +At the end you have to terminate the state: +\begin{verbatim} +err = chacha_done(&st); +\end{verbatim} + +\mysection{RC4} + +For more information about RC4 see \url{https://en.wikipedia.org/wiki/RC4}. + +Supported key size: 5--256 bytes + +You need to initialize RC with a \textit{key} (no \textit{nonce}, no \textit{IV}, no \textit{counter}). +\begin{verbatim} +rc4_state st; +err = rc4_stream_setup(&st, key, key_len); +\end{verbatim} + +For the actual encryption or decryption you to call: +\begin{verbatim} +err = rc4_stream_crypt(&st, in_buffer, in_len, out_buffer); +\end{verbatim} + + +If you just want a random stream of bytes initialize the cipher with truly random \textit{key}. +After that you can get a stream of pseudo--random bytes via: +\begin{verbatim} +err = rc4_stream_keystream(&st, out_buffer, out_len); +\end{verbatim} + +At the end you have to terminate the state: +\begin{verbatim} +err = rc4_stream_done(&st); +\end{verbatim} + +\mysection{Sober128} + +Supported key size: must be multiple of 4 bytes + +You need to initialize Sober128 with a \textit{key} and a \textit{nonce} (must be multiple of 4 bytes). +\begin{verbatim} +sober128_state st; +err = sober128_stream_setup(&st, key, 16); +err = sober128_stream_setiv(&st, nonce, 12); +\end{verbatim} + +For the actual encryption or decryption you to call: +\begin{verbatim} +err = sober128_stream_crypt(&st, in_buffer, in_len, out_buffer); +\end{verbatim} + +If you just want a random stream of bytes initialize the cipher with a truly random \textit{key} +and a truly random \textit{nonce}. After that you can get a stream of pseudo--random bytes via: +\begin{verbatim} +err = sober128_stream_keystream(&st, out_buffer, out_len); +\end{verbatim} + +At the end you have to terminate the state: +\begin{verbatim} +err = sober128_stream_done(&st); +\end{verbatim} \chapter{Authenticated Encryption}