ChaCha20-Poly1305 doc

doc/crypt.tex

@@ -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_init(chacha20poly1305_state *st,
-int chacha20poly1305_setiv(chacha20poly1305_state *st, const unsigned char *iv, unsigned long ivlen);
+                             const unsigned char *key,
-int chacha20poly1305_setiv_rfc7905(chacha20poly1305_state *st, const unsigned char *iv, unsigned long ivlen, ulong64 sequence_number);
+                                   unsigned long  keylen);
-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);
 \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}