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

ChaCha20-Poly1305 doc

Browse Source
This commit is contained in:
Karel Miko 2017-09-19 22:23:21 +02:00 committed by Steffen Jaeckel
parent 35d920a688
commit 11827feef3
1 changed files with 99 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

117
doc/crypt.tex
View File

@ -2179,29 +2179,110 @@ int main(void)
\mysection{ChaCha20--Poly1305}
This authenticated encryption is based on ChaCha20 stream cipher and Poly1305 authenticator.
It is defined by \url{https://tools.ietf.org/html/rfc7539}.
XXX-TODO
\subsection{Initialization}
To initialize the ChaCha20--Poly1305 context with a secret key call the following function.
\begin{small}
\index{chacha20poly1305\_init()}
\begin{verbatim}
int chacha20poly1305_init(chacha20poly1305_state *st, const unsigned char *key, unsigned long keylen);
int chacha20poly1305_setiv(chacha20poly1305_state *st, const unsigned char *iv, unsigned long ivlen);
int chacha20poly1305_setiv_rfc7905(chacha20poly1305_state *st, const unsigned char *iv, unsigned long ivlen, ulong64 sequence_number);
int chacha20poly1305_add_aad(chacha20poly1305_state *st, const unsigned char *in, unsigned long inlen);
int chacha20poly1305_encrypt(chacha20poly1305_state *st, const unsigned char *in, unsigned long inlen, unsigned char *out);
int chacha20poly1305_decrypt(chacha20poly1305_state *st, const unsigned char *in, unsigned long inlen, unsigned char *out);
int chacha20poly1305_done(chacha20poly1305_state *st, unsigned char *tag, unsigned long *taglen);
int chacha20poly1305_memory(const unsigned char *key, unsigned long keylen,
const unsigned char *iv, unsigned long ivlen,
const unsigned char *aad, unsigned long aadlen,
const unsigned char *in, unsigned long inlen,
unsigned char *out,
unsigned char *tag, unsigned long *taglen,
int direction);
int chacha20poly1305_init(chacha20poly1305_state *st,
const unsigned char *key,
unsigned long keylen);
\end{verbatim}
\end{small}
This initializes the ChaCha20--Poly1305 state \textit{st} with a secret key \textit{key} of length \textit{keylen}
octets (valid lengths: 32 or 16).
\url{https://tools.ietf.org/html/rfc7539}
\subsection{Initial Vector}
After the state has been initialized the next step is to add the initial vector.
\index{chacha20poly1305\_setiv()}
\begin{verbatim}
int chacha20poly1305_setiv(chacha20poly1305_state *st,
const unsigned char *iv,
unsigned long ivlen);
\end{verbatim}
This adds the initial vector from \textit{iv} of length \textit{ivlen} octects (valid lengths: 8 or 12) to
the ChaCha20--Poly1305 state \textit{st}.
\index{chacha20poly1305\_setiv\_rfc7905()}
\begin{verbatim}
int chacha20poly1305_setiv_rfc7905(chacha20poly1305_state *st,
const unsigned char *iv,
unsigned long ivlen,
ulong64 sequence_number);
\end{verbatim}
This also adds the initial vector from \textit{iv} of length \textit{ivlen} octects (valid lengths: 8 or 12) to
the state \textit{st} but it also incorporates 64bit \textit{sequence\_number} into IV as described in RFC7905.
You can call only one of \textit{chacha20poly1305\_setiv} or \textit{chacha20poly1305\_setiv\_rfc7905}.
\subsection{Additional Authentication Data}
After the IV has been set, the additional authentication data can be processed.
\index{chacha20poly1305\_add\_aad()}
\begin{verbatim}
int chacha20poly1305_add_aad(chacha20poly1305_state *st,
const unsigned char *adata,
unsigned long adatalen);
\end{verbatim}
This adds the additional authentication data \textit{adata} of length \textit{adatalen} to the ChaCha20--Poly1305 state \textit{st}.
\subsection{Encryption / Decryption}
After the AAD has been processed, the plaintext (or ciphertext depending on the direction) can be processed.
\index{chacha20poly1305\_encrypt()}
\begin{verbatim}
int chacha20poly1305_encrypt(chacha20poly1305_state *st,
const unsigned char *in,
unsigned long inlen,
unsigned char *out);
\end{verbatim}
This encrypts the data where \textit{in} is the plaintext and \textit{out} is the ciphertext. The length of both are equal and stored in \textit{inlen}.
\index{chacha20poly1305\_decrypt()}
\begin{verbatim}
int chacha20poly1305_decrypt(chacha20poly1305_state *st,
const unsigned char *in,
unsigned long inlen,
unsigned char *out);
\end{verbatim}
This decrypts the data where \textit{in} is the ciphertext and \textit{out} is the plaintext. The length of both are equal and stored in \textit{inlen}.
\subsection{State Termination}
To terminate a ChaCha20--Poly1305 state and retrieve the message authentication tag call the following function.
\index{chacha20poly1305\_done()}
\begin{verbatim}
int chacha20poly1305_done(chacha20poly1305_state *st,
unsigned char *tag,
unsigned long *taglen);
\end{verbatim}
This terminates the ChaCha20--Poly1305 state \textit{st} and stores the tag in \textit{tag} of length \textit{taglen} octets (always 16).
\subsection{One--Shot Packet}
To process a single packet under any given key the following helper function can be used.
\index{chacha20poly1305\_memory()}
\begin{verbatim}
int chacha20poly1305_memory(const unsigned char *key,
unsigned long keylen,
const unsigned char *iv,
unsigned long ivlen,
const unsigned char *aad,
unsigned long aadlen,
const unsigned char *in,
unsigned long inlen,
unsigned char *out,
unsigned char *tag,
unsigned long *taglen,
int direction);
\end{verbatim}
This will initialize the ChaCha20--Poly1305 state with the given key, IV and AAD value then proceed to
encrypt (\textit{direction} equals \textbf{CHCHA20POLY1305\_ENCRYPT}) or decrypt (\textit{direction} equals
\textbf{CHCHA20POLY1305\_DECRYPT}) the message text and store the final message tag. The definition of the
variables is the same as it is for all the manual functions.
\chapter{One-Way Cryptographic Hash Functions}
\mysection{Core Functions}