some more doc updates

doc/crypt.tex

@@ -680,9 +680,25 @@ Twofish round function.
 \caption{Twofish Build Options}
 \label{fig:twofishopts}
 \end{figure}
+
+\item
+As of v1.18.0 of the library RC2 got an extended setup function (which didn't fit in the regular API):
+
+\index{rc2\_setup\_ex()}
+\begin{verbatim}
+int rc2_setup_ex(const unsigned char *key,
+                                 int keylen,
+                                 int bits,
+                                 int num_rounds,
+                       symmetric_key *skey);
+\end{verbatim}
+
+This setup function also allows to configure the effective key length in bits of the RC2 cipher as in its original specification.
+
 \end{enumerate}
 \end{small}
 
+
 To work with the cipher\_descriptor array there is a function:
 \index{find\_cipher()}
 \begin{verbatim}
@@ -1515,11 +1531,22 @@ have the same meaning as with those respective functions.
 The only difference is eax\_decrypt\_verify\_memory() does not emit a tag.  Instead you pass it a tag as input and it compares it against
 the tag it computed while decrypting the message.  If the tags match then it stores a $1$ in \textit{res}, otherwise it stores a $0$.
 
-\mysection{OCB Mode}
+\mysection{OCB Modes}
-LibTomCrypt provides support for a mode called OCB\footnote{See
+\subsection{Preface}
+
+LibTomCrypt provides support for a mode called OCB in version 1 ''OCB''\footnote{See
 P. Rogaway, M. Bellare, J. Black, T. Krovetz, \textit{OCB: A Block Cipher Mode of Operation for Efficient Authenticated Encryption}.}
-.  OCB is an encryption protocol that simultaneously provides authentication.  It is slightly faster to use than EAX mode
+and version 3 ''OCB3''\footnote{See RFC7253, T. Krovetz, P. Rogaway, \textit{The OCB Authenticated-Encryption Algorithm}.}.
-but is less flexible.  Let's review how to initialize an OCB context.
+OCB is an encryption protocol that simultaneously provides authentication.  It is slightly faster to use than EAX mode
+but is less flexible.
+
+Please be aware that all versions of OCB are patented and there are several licensing models provided by P. Rogaway, the patent holder
+-- see \url{http://web.cs.ucdavis.edu/~rogaway/ocb/license.htm}.
+
+\subsection{OCB}
+\subsubsection{Initialization and processing}
+
+Let's review how to initialize an OCB context.
 
 \index{ocb\_init()}
 \begin{verbatim}
@@ -1553,7 +1580,7 @@ They assume that \textit{pt} and \textit{ct} are the same size as the block ciph
 both functions given a single \textit{ocb} state.  For bi-directional communication you will have to initialize two \textit{ocb}
 states (with different nonces).  Also \textit{pt} and \textit{ct} may point to the same location in memory.
 
-\subsection{State Termination}
+\subsubsection{State Termination}
 
 When you are finished encrypting the message you call the following function to compute the tag.
 
@@ -1591,7 +1618,7 @@ tag of the message (internally) and then compare it against the \textit{taglen}
 \textit{res} is set to zero.  If all \textit{taglen} bytes of \textit{tag} can be verified then \textit{res} is set to one (authenticated
 message).
 
-\subsection{Packet Functions}
+\subsubsection{Packet Functions}
 To make life simpler the following two functions are provided for memory bound OCB.
 
 %\index{ocb\_encrypt\_authenticate\_memory()}
@@ -1621,27 +1648,78 @@ int ocb_decrypt_verify_memory(
 \end{verbatim}
 
 Similarly, this will OCB decrypt, and compare the internally computed tag against the tag provided. \textit{res} is set
-appropriately.
+appropriately to \textit{1} if the tag matches or to \textit{0} if it doesn't match.
 
-\mysection{OCB3 Mode}
+\subsection{OCB3}
+\subsubsection{Initialization and processing}
 
-OCB3 is a successor of OCB as defined in RFC7253 -- see \url{https://tools.ietf.org/html/rfc7253}.
+\index{ocb3\_init()}
-
-XXX-TODO
-
-\begin{small}
 \begin{verbatim}
 int ocb3_init(ocb3_state *ocb, int cipher,
              const unsigned char *key, unsigned long keylen,
              const unsigned char *nonce, unsigned long noncelen);
+\end{verbatim}
 
-int ocb3_encrypt(ocb3_state *ocb, const unsigned char *pt, unsigned long ptlen, unsigned char *ct);
+This will initialize the \textit{ocb} context using cipher descriptor \textit{cipher}.  It will use a \textit{key} of length \textit{keylen}
-int ocb3_decrypt(ocb3_state *ocb, const unsigned char *ct, unsigned long ctlen, unsigned char *pt);
+and the random \textit{nonce} of length \textit{noncelen}.  Note that \textit{nonce} must be a random (public) string of an arbitrary length
-int ocb3_encrypt_last(ocb3_state *ocb, const unsigned char *pt, unsigned long ptlen, unsigned char *ct);
+between 1 and 15 octets.
-int ocb3_decrypt_last(ocb3_state *ocb, const unsigned char *ct, unsigned long ctlen, unsigned char *pt);
+
+\subsubsection{Additional Authenticated Data}
+
+OCB3 has, in contrary to OCB, the possibility to add "Additional Authenticated Data" (AAD) when performing cryptographic operations.
+
+\index{ocb3\_add\_aad()}
+\begin{verbatim}
 int ocb3_add_aad(ocb3_state *ocb, const unsigned char *aad, unsigned long aadlen);
-int ocb3_done(ocb3_state *ocb, unsigned char *tag, unsigned long *taglen);
+\end{verbatim}
 
+This will add the AAD at \textit{aad} of the arbitrary length \textit{aadlen} to be authenticated within the context \textit{ocb}.
+
+\index{ocb3\_encrypt()} \index{ocb3\_decrypt()}
+\begin{verbatim}
+int ocb3_encrypt(         ocb3_state *ocb,
+                 const unsigned char *pt,
+                       unsigned long ptlen,
+                       unsigned char *ct);
+
+int ocb3_decrypt(         ocb3_state *ocb,
+                 const unsigned char *ct,
+                       unsigned long ctlen,
+                       unsigned char *pt);
+\end{verbatim}
+
+This will encrypt (or decrypt for the latter) a fixed length of data from \textit{pt} to \textit{ct} (vice versa for the latter).
+They assume that \textit{pt} and \textit{ct} are the same size as the block cipher's block size.  Note that you cannot call
+both functions given a single \textit{ocb} state.  For bi-directional communication you will have to initialize two \textit{ocb}
+states (with different nonces).  Also \textit{pt} and \textit{ct} may point to the same location in memory.
+
+\subsubsection{State Termination}
+
+\index{ocb3\_encrypt\_last()} \index{ocb3\_decrypt\_last()}
+\begin{verbatim}
+int ocb3_encrypt_last(ocb3_state *ocb, const unsigned char *pt, unsigned long ptlen, unsigned char *ct);
+
+int ocb3_decrypt_last(ocb3_state *ocb, const unsigned char *ct, unsigned long ctlen, unsigned char *pt);
+\end{verbatim}
+
+XXX-TODO
+
+When you are finished encrypting the message you call the following function to compute the tag.
+
+\index{ocb3\_done()}
+\begin{verbatim}
+int ocb3_done(ocb3_state *ocb, unsigned char *tag, unsigned long *taglen);
+\end{verbatim}
+
+This stores the tag of the \textit{ocb} state in \textit{tag}.
+The \textit{taglen} parameter defines on input the length of the tag to output and will be set to the actual length written, which
+is at most the block length of the cipher in use.
+
+\subsubsection{Packet Functions}
+To make life simpler the following two functions are provided for memory bound OCB3.
+
+\index{ocb3\_encrypt\_authenticate\_memory()}
+\begin{verbatim}
 int ocb3_encrypt_authenticate_memory(int cipher,
     const unsigned char *key,    unsigned long keylen,
     const unsigned char *nonce,  unsigned long noncelen,
@@ -1649,7 +1727,10 @@ int ocb3_encrypt_authenticate_memory(int cipher,
     const unsigned char *pt,     unsigned long ptlen,
           unsigned char *ct,
           unsigned char *tag,    unsigned long *taglen);
+\end{verbatim}
 
+\index{ocb3\_decrypt\_verify\_memory()}
+\begin{verbatim}
 int ocb3_decrypt_verify_memory(int cipher,
     const unsigned char *key,    unsigned long keylen,
     const unsigned char *nonce,  unsigned long noncelen,
@@ -1659,7 +1740,6 @@ int ocb3_decrypt_verify_memory(int cipher,
     const unsigned char *tag,    unsigned long taglen,
           int           *stat);
 \end{verbatim}
-\end{small}
 
 \mysection{CCM Mode}
 CCM is a NIST proposal for encrypt + authenticate that is centered around using AES (or any 16--byte cipher) as a primitive.
@@ -6040,6 +6120,7 @@ math library.
 \begin{verbatim}
 void init_LTM(void);
 void init_TFM(void);
+void init_GMP(void);
 \end{verbatim}
 
 Here is a Python program demonstrating how to call various LTC dynamic
@@ -6228,6 +6309,8 @@ libraries.
 
 \mysection{Makefile variables}
 
+XXX-TODO review
+
 All GNU driven makefiles (including the makefile for ICC) use a set of common variables to control the build and install process.  Most of the
 settings can be overwritten from the command line which makes custom installation a breeze.