TeaSpeak/tomcrypt
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

some more doc updates

Browse Source
This commit is contained in:
Steffen Jaeckel 2017-08-07 12:06:58 +02:00
parent 5d74fee9dc
commit 56d17c8e55
1 changed files with 111 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
doc/crypt.tex
View File

@ -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}
LibTomCrypt provides support for a mode called OCB\footnote{See
\mysection{OCB Modes}
\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
but is less flexible. Let's review how to initialize an OCB context.
and version 3 ''OCB3''\footnote{See RFC7253, T. Krovetz, P. Rogaway, \textit{The OCB Authenticated-Encryption Algorithm}.}.
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}.
XXX-TODO
\begin{small}
\index{ocb3\_init()}
\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);
int ocb3_decrypt(ocb3_state *ocb, const unsigned char *ct, unsigned long ctlen, unsigned char *pt);
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);
This will initialize the \textit{ocb} context using cipher descriptor \textit{cipher}. It will use a \textit{key} of length \textit{keylen}
and the random \textit{nonce} of length \textit{noncelen}. Note that \textit{nonce} must be a random (public) string of an arbitrary length
between 1 and 15 octets.
\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.