doc: stream ciphers

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}