BLAKE2s + BLAKE2b MAC doc

Author: karel-m

doc/crypt.tex

@@ -3287,8 +3287,6 @@ \subsection{F9--MAC Functions}
 The Poly1305--MAC is a cryptographic message authentication code created by Daniel J. Bernstein.
 More info at \url{https://en.wikipedia.org/wiki/Poly1305}.
 
-\subsection{Poly1305--MAC Functions}
-
 A Poly1305--MAC state is initialized with the following function:
 \index{poly1305\_init()}
 \begin{verbatim}
@@ -3348,27 +3346,103 @@ \subsection{Poly1305--MAC Functions}
 
 \mysection{BLAKE2s + BLAKE2b MAC}
 
-XXX-TODO see \url{https://tools.ietf.org/html/rfc7693}
+The BLAKE2s and BLAKE2b are cryptographic message authentication code designed by Jean--Philippe Aumasson,
+Samuel Neves, Zooko Wilcox-O'Hearn, and Christian Winnerlein. More info at \url{https://tools.ietf.org/html/rfc7693}.
 
-\begin{small}
+A BLAKE2s/b--MAC state is initialized with the following function:
+\index{blake2smac\_init()}
 \begin{verbatim}
-int blake2smac_init(blake2smac_state *st, unsigned long outlen, const unsigned char *key, unsigned long keylen);
-int blake2smac_process(blake2smac_state *st, const unsigned char *in, unsigned long inlen);
-int blake2smac_done(blake2smac_state *st, unsigned char *mac, unsigned long *maclen);
-int blake2smac_test(void);
-int blake2smac_memory(const unsigned char *key, unsigned long keylen, const unsigned char *in, unsigned long inlen, unsigned char *mac, unsigned long *maclen);
-int blake2smac_memory_multi(const unsigned char *key, unsigned long keylen, unsigned char *mac, unsigned long *maclen, const unsigned char *in,  unsigned long inlen, ...);
-int blake2smac_file(const char *fname, const unsigned char *key, unsigned long keylen, unsigned char *mac, unsigned long *maclen);
-
-int blake2bmac_init(blake2bmac_state *st, unsigned long outlen, const unsigned char *key, unsigned long keylen);
-int blake2bmac_process(blake2bmac_state *st, const unsigned char *in, unsigned long inlen);
-int blake2bmac_done(blake2bmac_state *st, unsigned char *mac, unsigned long *maclen);
-int blake2bmac_test(void);
-int blake2bmac_memory(const unsigned char *key, unsigned long keylen, const unsigned char *in, unsigned long inlen, unsigned char *mac, unsigned long *maclen);
-int blake2bmac_memory_multi(const unsigned char *key, unsigned long keylen, unsigned char *mac, unsigned long *maclen, const unsigned char *in,  unsigned long inlen, ...);
-int blake2bmac_file(const char *fname, const unsigned char *key, unsigned long keylen, unsigned char *mac, unsigned long *maclen);
+int blake2smac_init(blake2smac_state *st,
+                       unsigned long  outlen,
+                 const unsigned char *key,
+                       unsigned long  keylen);
 \end{verbatim}
-\end{small}
+\index{blake2bmac\_init()}
+\begin{verbatim}
+int blake2bmac_init(blake2smac_state *st,
+                       unsigned long  outlen,
+                 const unsigned char *key,
+                       unsigned long  keylen);
+\end{verbatim}
+This will initialize the BLAKE2s/b--MAC state \textit{st}, with the key specified in \textit{key} of length \textit{keylen} octets (up to 64).
+The \textit{outlen} specifies the size of the final tag (up to 64 octets).
+
+To process data through BLAKE2s/b--MAC use the following function:
+\index{blake2smac\_process()}
+\begin{verbatim}
+int blake2smac_process(   blake2smac_state *st,
+                       const unsigned char *in,
+                             unsigned long  inlen);
+\end{verbatim}
+\index{blake2bmac\_process()}
+\begin{verbatim}
+int blake2bmac_process(   blake2bmac_state *st,
+                       const unsigned char *in,
+                             unsigned long  inlen);
+\end{verbatim}
+
+This will add the message octets pointed to by \textit{in} of length \textit{inlen} to the BLAKE2s/b--MAC state pointed to by \textit{st}.
+
+To compute the MAC tag value use the following function:
+\index{blake2smac\_done()}
+\begin{verbatim}
+int blake2smac_done(blake2smac_state *st,
+                       unsigned char *mac,
+                       unsigned long *maclen);
+\end{verbatim}
+\index{blake2bmac\_done()}
+\begin{verbatim}
+int blake2bmac_done(blake2bmac_state *st,
+                       unsigned char *mac,
+                       unsigned long *maclen);
+\end{verbatim}
+
+This will retrieve the BLAKE2s/b--MAC tag from the state pointed to by \textit{st}, and store it in the array pointed to by \textit{mac}.
+The \textit{maclen} parameter specifies the maximum size of the destination buffer, and is updated to hold the final size of the tag when
+the function returns.
+
+Helper functions are provided to make parsing memory buffers and files easier. The following functions are provided:
+\index{blake2smac\_memory()}
+\begin{verbatim}
+int blake2smac_memory(const unsigned char *key,
+                            unsigned long  keylen,
+                      const unsigned char *in,
+                            unsigned long  inlen,
+                            unsigned char *mac,
+                            unsigned long *maclen);
+\end{verbatim}
+\index{blake2bmac\_memory()}
+\begin{verbatim}
+int blake2bmac_memory(const unsigned char *key,
+                            unsigned long  keylen,
+                      const unsigned char *in,
+                            unsigned long  inlen,
+                            unsigned char *mac,
+                            unsigned long *maclen);
+\end{verbatim}
+This will compute the BLAKE2s/b--MAC of \textit{inlen} bytes of \textit{in}, using the key \textit{key} of length \textit{keylen} bytes.
+It will store the MAC in \textit{mac} with the same rules as blake2smac\_done().
+
+To BLAKE2s/b--MAC a file use
+\index{blake2smac\_file()}
+\begin{verbatim}
+int blake2smac_file(         const char *fname,
+                    const unsigned char *key,
+                          unsigned long  keylen,
+                          unsigned char *mac,
+                          unsigned long *maclen);
+\end{verbatim}
+\index{blake2bmac\_file()}
+\begin{verbatim}
+int blake2bmac_file(         const char *fname,
+                    const unsigned char *key,
+                          unsigned long  keylen,
+                          unsigned char *mac,
+                          unsigned long *maclen);
+\end{verbatim}
+
+Which will BLAKE2s/b--MAC the entire contents of the file specified by \textit{fname} using the key \textit{key} of
+length \textit{keylen} bytes. It will store the MAC in \textit{mac} with the same rules as blake2smac\_done().
 
 \chapter{Pseudo-Random Number Generators}
 \mysection{Core Functions}