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

BLAKE2s + BLAKE2b MAC doc

Browse Source
This commit is contained in:
Karel Miko 2017-09-19 22:53:47 +02:00 committed by Steffen Jaeckel
parent 50e52d0b4c
commit f3f839ec6c
1 changed files with 94 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

114
doc/crypt.tex
View File

@ -3287,8 +3287,6 @@ This will return \textbf{CRYPT\_OK} on success. This requires the AES or Rijnda
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 @@ length \textit{keylen} bytes. It will store the MAC in \textit{mac} with the sam
\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}