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

139
doc/crypt.tex
View File

@ -680,9 +680,25 @@ Twofish round function.
\caption{Twofish Build Options} \caption{Twofish Build Options}
\label{fig:twofishopts} \label{fig:twofishopts}
\end{figure} \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{enumerate}
\end{small} \end{small}
To work with the cipher\_descriptor array there is a function: To work with the cipher\_descriptor array there is a function:
\index{find\_cipher()} \index{find\_cipher()}
\begin{verbatim} \begin{verbatim}
@ -1229,7 +1245,7 @@ int f8_done(symmetric_F8 *f8);
Stream ciphers are symmetric key ciphers which operate on a stream of bytes (in theory on a stream of bits 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). however LibTomCrypt's implementation works with bytes).
The API for all stream ciphers operates in mode: \textit{setup} -- \textit{crypt} -- \textit{crypt} -- ... -- \textit{done}. 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}. Please note that both encryption and decryption is implemented via \textit{crypt}.
Another useful feature of stream ciphers API is generation of random stream of bytes which works like: Another useful feature of stream ciphers API is generation of random stream of bytes which works like:
@ -1238,7 +1254,7 @@ implemented like encryption of a stream o zero bytes.
\mysection{ChaCha} \mysection{ChaCha}
The \textit{ChaCha} is currently the most modern stream cipher included in LibTomCrypt, so use this one unless you 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. have a reason for using some of the older algorithms.
For more information about ChaCha see \url{https://en.wikipedia.org/wiki/ChaCha_(cipher)}. For more information about ChaCha see \url{https://en.wikipedia.org/wiki/ChaCha_(cipher)}.
@ -1259,7 +1275,7 @@ err = chacha_setup(&st, key, key_len, rounds);
err = chacha_ivctr64(&st, nonce, 8, initial_64bit_ctr); err = chacha_ivctr64(&st, nonce, 8, initial_64bit_ctr);
\end{verbatim} \end{verbatim}
The \textit{chacha\_setup} takes as a parameter the number of rounds -- choose 20 if you are not sure. 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. As always never ever used the same key + nonce pair more than once.
For the actual encryption or decryption you to call: For the actual encryption or decryption you to call:
@ -1340,7 +1356,7 @@ err = sober128_stream_done(&st);
Authenticated Encryption - sometimes also called Authenticated Encryption with Associated Data (AEAD) - is a variant of encryption Authenticated Encryption - sometimes also called Authenticated Encryption with Associated Data (AEAD) - is a variant of encryption
that provides not only confidentiality (as other symmetric or stream ciphers) but also integrity. that provides not only confidentiality (as other symmetric or stream ciphers) but also integrity.
The inputs of Authenticated Encryption are: \textit{key}, \textit{nonce} (sometimes called initialization vector), \textit{plaintext}, The inputs of Authenticated Encryption are: \textit{key}, \textit{nonce} (sometimes called initialization vector), \textit{plaintext},
optional \textit{header} (sometimes called additional authenticated data - AAD). The outputs are: \textit{ciphertext} and \textit{tag}. optional \textit{header} (sometimes called additional authenticated data - AAD). The outputs are: \textit{ciphertext} and \textit{tag}.
\mysection{EAX Mode} \mysection{EAX Mode}
@ -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 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$. 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}.} 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()} \index{ocb\_init()}
\begin{verbatim} \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} 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. 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. 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 \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). message).
\subsection{Packet Functions} \subsubsection{Packet Functions}
To make life simpler the following two functions are provided for memory bound OCB. To make life simpler the following two functions are provided for memory bound OCB.
%\index{ocb\_encrypt\_authenticate\_memory()} %\index{ocb\_encrypt\_authenticate\_memory()}
@ -1621,27 +1648,78 @@ int ocb_decrypt_verify_memory(
\end{verbatim} \end{verbatim}
Similarly, this will OCB decrypt, and compare the internally computed tag against the tag provided. \textit{res} is set 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} \begin{verbatim}
int ocb3_init(ocb3_state *ocb, int cipher, int ocb3_init(ocb3_state *ocb, int cipher,
const unsigned char *key, unsigned long keylen, const unsigned char *key, unsigned long keylen,
const unsigned char *nonce, unsigned long noncelen); 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_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, int ocb3_encrypt_authenticate_memory(int cipher,
const unsigned char *key, unsigned long keylen, const unsigned char *key, unsigned long keylen,
const unsigned char *nonce, unsigned long noncelen, 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, const unsigned char *pt, unsigned long ptlen,
unsigned char *ct, unsigned char *ct,
unsigned char *tag, unsigned long *taglen); unsigned char *tag, unsigned long *taglen);
\end{verbatim}
\index{ocb3\_decrypt\_verify\_memory()}
\begin{verbatim}
int ocb3_decrypt_verify_memory(int cipher, int ocb3_decrypt_verify_memory(int cipher,
const unsigned char *key, unsigned long keylen, const unsigned char *key, unsigned long keylen,
const unsigned char *nonce, unsigned long noncelen, 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, const unsigned char *tag, unsigned long taglen,
int *stat); int *stat);
\end{verbatim} \end{verbatim}
\end{small}
\mysection{CCM Mode} \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. CCM is a NIST proposal for encrypt + authenticate that is centered around using AES (or any 16--byte cipher) as a primitive.
@ -4673,12 +4753,12 @@ the ECC \textit{key} provided must be a private key.
\index{ecc\_sign\_hash\_rfc7518()} \index{ecc\_sign\_hash\_rfc7518()}
\begin{verbatim} \begin{verbatim}
int ecc_sign_hash_rfc7518(const unsigned char *in, int ecc_sign_hash_rfc7518(const unsigned char *in,
unsigned long inlen, unsigned long inlen,
unsigned char *out, unsigned char *out,
unsigned long *outlen, unsigned long *outlen,
prng_state *prng, prng_state *prng,
int wprng, int wprng,
ecc_key *key); ecc_key *key);
\end{verbatim} \end{verbatim}
@ -4712,7 +4792,7 @@ int ecc_verify_hash_rfc7518(const unsigned char *sig,
ecc_key *key); ecc_key *key);
\end{verbatim} \end{verbatim}
This function validate the EC--DSA signature as \textit{ecc\_verify\_hash} only the signature input format This function validate the EC--DSA signature as \textit{ecc\_verify\_hash} only the signature input format
follows \url{https://tools.ietf.org/html/rfc7518#section-3.4}. follows \url{https://tools.ietf.org/html/rfc7518#section-3.4}.
\mysection{ECC Keysizes} \mysection{ECC Keysizes}
@ -5850,7 +5930,7 @@ Parameters are as in \textit{hkdf\_extract()} and \textit{hkdf\_expand()}.
\chapter{Miscellaneous} \chapter{Miscellaneous}
\mysection{Base64 Encoding and Decoding} \mysection{Base64 Encoding and Decoding}
The library provides functions to encode and decode a RFC 4648 Base64 coding scheme. The library provides functions to encode and decode a RFC 4648 Base64 coding scheme.
\subsection{Standard 'base64' encoding} \subsection{Standard 'base64' encoding}
The characters used in the mappings are: The characters used in the mappings are:
@ -6040,6 +6120,7 @@ math library.
\begin{verbatim} \begin{verbatim}
void init_LTM(void); void init_LTM(void);
void init_TFM(void); void init_TFM(void);
void init_GMP(void);
\end{verbatim} \end{verbatim}
Here is a Python program demonstrating how to call various LTC dynamic Here is a Python program demonstrating how to call various LTC dynamic
@ -6228,6 +6309,8 @@ libraries.
\mysection{Makefile variables} \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 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. settings can be overwritten from the command line which makes custom installation a breeze.