KMAC as defined in NIST SP 800-185

doc/crypt.tex

@@ -3980,6 +3980,112 @@ \subsection{F9--MAC Functions}
 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().
 
+\mysection{KMAC}
+
+KMAC is a keyed message authentication code based on the Keccak permutation, standardised by NIST in
+SP 800--185. The library provides KMAC128 and KMAC256, each available in fixed--length and
+extendable--output (XOF) variants.
+
+The desired flavour is selected through the \textit{variant} argument, which must be exactly one of the
+following four named constants:
+
+\begin{center}
+\begin{tabular}{ll}
+\hline
+\textit{variant}             & resulting algorithm \\
+\hline
+\texttt{LTC\_KMAC128}        & KMAC128 \\
+\texttt{LTC\_KMAC256}        & KMAC256 \\
+\texttt{LTC\_KMAC128\_XOF}   & KMACXOF128 \\
+\texttt{LTC\_KMAC256\_XOF}   & KMACXOF256 \\
+\hline
+\end{tabular}
+\end{center}
+
+Any other value passed in \textit{variant} causes the init function to return \textbf{CRYPT\_INVALID\_ARG}.
+
+A KMAC state is initialised with the following function:
+\index{kmac\_init()}
+\begin{verbatim}
+int kmac_init(         kmac_state *st,
+                              int  variant,
+              const unsigned char *key,
+                    unsigned long  keylen,
+              const unsigned char *cust,
+                    unsigned long  custlen);
+\end{verbatim}
+This will initialise the KMAC state \textit{st} with the key in \textit{key} of length \textit{keylen} octets
+and the optional customisation string in \textit{cust} of length \textit{custlen} octets. The customisation
+string may be empty: pass \textbf{NULL} as \textit{cust} together with \textit{custlen} equal to zero.
+
+To process data through KMAC use the following function:
+\index{kmac\_process()}
+\begin{verbatim}
+int kmac_process(         kmac_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 KMAC state pointed
+to by \textit{st}.
+
+To compute the MAC tag use:
+\index{kmac\_done()}
+\begin{verbatim}
+int kmac_done(   kmac_state *st,
+              unsigned char *out,
+              unsigned long *outlen);
+\end{verbatim}
+On entry \textit{outlen} holds the requested output size in octets; on exit it holds the number of octets
+actually written to \textit{out}. For the fixed--length variants the requested length is bound into the
+authentication tag, so callers must commit to it before calling kmac\_done(). For the XOF variants the
+requested length is independent of the tag computation and any output length may be asked for.
+
+Helper functions are provided to make hashing memory buffers and files easier:
+\index{kmac\_memory()}
+\begin{verbatim}
+int kmac_memory(                int  variant,
+                const unsigned char *key,
+                      unsigned long  keylen,
+                const unsigned char *cust,
+                      unsigned long  custlen,
+                const unsigned char *in,
+                      unsigned long  inlen,
+                      unsigned char *out,
+                      unsigned long *outlen);
+\end{verbatim}
+This will compute the KMAC of \textit{inlen} bytes of \textit{in} using the key \textit{key} of length
+\textit{keylen} bytes and the customisation string \textit{cust} of length \textit{custlen} bytes. The result
+is stored in \textit{out} following the same rules as kmac\_done().
+
+\index{kmac\_memory\_multi()}
+\begin{verbatim}
+int kmac_memory_multi(                int  variant,
+                      const unsigned char *key,
+                            unsigned long  keylen,
+                      const unsigned char *cust,
+                            unsigned long  custlen,
+                            unsigned char *out,
+                            unsigned long *outlen,
+                      const unsigned char *in,
+                            unsigned long  inlen, ...);
+\end{verbatim}
+The variadic form accepts an arbitrary number of (data, length) pairs, terminated by a \textbf{NULL} pointer.
+
+To KMAC a file use:
+\index{kmac\_file()}
+\begin{verbatim}
+int kmac_file(                int  variant,
+              const unsigned char *key,
+                    unsigned long  keylen,
+              const unsigned char *cust,
+                    unsigned long  custlen,
+              const          char *fname,
+                    unsigned char *out,
+                    unsigned long *outlen);
+\end{verbatim}
+Which will KMAC the entire contents of the file named \textit{fname} and store the tag in \textit{out}
+following the same rules as kmac\_done().
+
 \chapter{Pseudo-Random Number Generators}
 \mysection{Core Functions}
 The library provides an array of core functions for Pseudo-Random Number Generators (PRNGs) as well.  A cryptographic PRNG is

libtomcrypt_VS2008.vcproj

@@ -1155,6 +1155,30 @@
 					>
 				</File>
 			</Filter>
+			<Filter
+				Name="kmac"
+				>
+				<File
+					RelativePath="src\mac\kmac\kmac.c"
+					>
+				</File>
+				<File
+					RelativePath="src\mac\kmac\kmac_file.c"
+					>
+				</File>
+				<File
+					RelativePath="src\mac\kmac\kmac_memory.c"
+					>
+				</File>
+				<File
+					RelativePath="src\mac\kmac\kmac_memory_multi.c"
+					>
+				</File>
+				<File
+					RelativePath="src\mac\kmac\kmac_test.c"
+					>
+				</File>
+			</Filter>
 			<Filter
 				Name="omac"
 				>

makefile.mingw

@@ -77,11 +77,12 @@ src/mac/blake2/blake2smac_memory_multi.o src/mac/blake2/blake2smac_test.o src/ma
 src/mac/f9/f9_file.o src/mac/f9/f9_init.o src/mac/f9/f9_memory.o src/mac/f9/f9_memory_multi.o \
 src/mac/f9/f9_process.o src/mac/f9/f9_test.o src/mac/hmac/hmac_done.o src/mac/hmac/hmac_file.o \
 src/mac/hmac/hmac_init.o src/mac/hmac/hmac_memory.o src/mac/hmac/hmac_memory_multi.o \
-src/mac/hmac/hmac_process.o src/mac/hmac/hmac_test.o src/mac/omac/omac_done.o src/mac/omac/omac_file.o \
-src/mac/omac/omac_init.o src/mac/omac/omac_memory.o src/mac/omac/omac_memory_multi.o \
-src/mac/omac/omac_process.o src/mac/omac/omac_test.o src/mac/pelican/pelican.o \
-src/mac/pelican/pelican_memory.o src/mac/pelican/pelican_test.o src/mac/pmac/pmac_done.o \
-src/mac/pmac/pmac_file.o src/mac/pmac/pmac_init.o src/mac/pmac/pmac_memory.o \
+src/mac/hmac/hmac_process.o src/mac/hmac/hmac_test.o src/mac/kmac/kmac.o src/mac/kmac/kmac_file.o \
+src/mac/kmac/kmac_memory.o src/mac/kmac/kmac_memory_multi.o src/mac/kmac/kmac_test.o \
+src/mac/omac/omac_done.o src/mac/omac/omac_file.o src/mac/omac/omac_init.o src/mac/omac/omac_memory.o \
+src/mac/omac/omac_memory_multi.o src/mac/omac/omac_process.o src/mac/omac/omac_test.o \
+src/mac/pelican/pelican.o src/mac/pelican/pelican_memory.o src/mac/pelican/pelican_test.o \
+src/mac/pmac/pmac_done.o src/mac/pmac/pmac_file.o src/mac/pmac/pmac_init.o src/mac/pmac/pmac_memory.o \
 src/mac/pmac/pmac_memory_multi.o src/mac/pmac/pmac_ntz.o src/mac/pmac/pmac_process.o \
 src/mac/pmac/pmac_shift_xor.o src/mac/pmac/pmac_test.o src/mac/poly1305/poly1305.o \
 src/mac/poly1305/poly1305_file.o src/mac/poly1305/poly1305_memory.o \

makefile.msvc

@@ -70,11 +70,12 @@ src/mac/blake2/blake2smac_memory_multi.obj src/mac/blake2/blake2smac_test.obj sr
 src/mac/f9/f9_file.obj src/mac/f9/f9_init.obj src/mac/f9/f9_memory.obj src/mac/f9/f9_memory_multi.obj \
 src/mac/f9/f9_process.obj src/mac/f9/f9_test.obj src/mac/hmac/hmac_done.obj src/mac/hmac/hmac_file.obj \
 src/mac/hmac/hmac_init.obj src/mac/hmac/hmac_memory.obj src/mac/hmac/hmac_memory_multi.obj \
-src/mac/hmac/hmac_process.obj src/mac/hmac/hmac_test.obj src/mac/omac/omac_done.obj src/mac/omac/omac_file.obj \
-src/mac/omac/omac_init.obj src/mac/omac/omac_memory.obj src/mac/omac/omac_memory_multi.obj \
-src/mac/omac/omac_process.obj src/mac/omac/omac_test.obj src/mac/pelican/pelican.obj \
-src/mac/pelican/pelican_memory.obj src/mac/pelican/pelican_test.obj src/mac/pmac/pmac_done.obj \
-src/mac/pmac/pmac_file.obj src/mac/pmac/pmac_init.obj src/mac/pmac/pmac_memory.obj \
+src/mac/hmac/hmac_process.obj src/mac/hmac/hmac_test.obj src/mac/kmac/kmac.obj src/mac/kmac/kmac_file.obj \
+src/mac/kmac/kmac_memory.obj src/mac/kmac/kmac_memory_multi.obj src/mac/kmac/kmac_test.obj \
+src/mac/omac/omac_done.obj src/mac/omac/omac_file.obj src/mac/omac/omac_init.obj src/mac/omac/omac_memory.obj \
+src/mac/omac/omac_memory_multi.obj src/mac/omac/omac_process.obj src/mac/omac/omac_test.obj \
+src/mac/pelican/pelican.obj src/mac/pelican/pelican_memory.obj src/mac/pelican/pelican_test.obj \
+src/mac/pmac/pmac_done.obj src/mac/pmac/pmac_file.obj src/mac/pmac/pmac_init.obj src/mac/pmac/pmac_memory.obj \
 src/mac/pmac/pmac_memory_multi.obj src/mac/pmac/pmac_ntz.obj src/mac/pmac/pmac_process.obj \
 src/mac/pmac/pmac_shift_xor.obj src/mac/pmac/pmac_test.obj src/mac/poly1305/poly1305.obj \
 src/mac/poly1305/poly1305_file.obj src/mac/poly1305/poly1305_memory.obj \

makefile.unix

@@ -91,11 +91,12 @@ src/mac/blake2/blake2smac_memory_multi.o src/mac/blake2/blake2smac_test.o src/ma
 src/mac/f9/f9_file.o src/mac/f9/f9_init.o src/mac/f9/f9_memory.o src/mac/f9/f9_memory_multi.o \
 src/mac/f9/f9_process.o src/mac/f9/f9_test.o src/mac/hmac/hmac_done.o src/mac/hmac/hmac_file.o \
 src/mac/hmac/hmac_init.o src/mac/hmac/hmac_memory.o src/mac/hmac/hmac_memory_multi.o \
-src/mac/hmac/hmac_process.o src/mac/hmac/hmac_test.o src/mac/omac/omac_done.o src/mac/omac/omac_file.o \
-src/mac/omac/omac_init.o src/mac/omac/omac_memory.o src/mac/omac/omac_memory_multi.o \
-src/mac/omac/omac_process.o src/mac/omac/omac_test.o src/mac/pelican/pelican.o \
-src/mac/pelican/pelican_memory.o src/mac/pelican/pelican_test.o src/mac/pmac/pmac_done.o \
-src/mac/pmac/pmac_file.o src/mac/pmac/pmac_init.o src/mac/pmac/pmac_memory.o \
+src/mac/hmac/hmac_process.o src/mac/hmac/hmac_test.o src/mac/kmac/kmac.o src/mac/kmac/kmac_file.o \
+src/mac/kmac/kmac_memory.o src/mac/kmac/kmac_memory_multi.o src/mac/kmac/kmac_test.o \
+src/mac/omac/omac_done.o src/mac/omac/omac_file.o src/mac/omac/omac_init.o src/mac/omac/omac_memory.o \
+src/mac/omac/omac_memory_multi.o src/mac/omac/omac_process.o src/mac/omac/omac_test.o \
+src/mac/pelican/pelican.o src/mac/pelican/pelican_memory.o src/mac/pelican/pelican_test.o \
+src/mac/pmac/pmac_done.o src/mac/pmac/pmac_file.o src/mac/pmac/pmac_init.o src/mac/pmac/pmac_memory.o \
 src/mac/pmac/pmac_memory_multi.o src/mac/pmac/pmac_ntz.o src/mac/pmac/pmac_process.o \
 src/mac/pmac/pmac_shift_xor.o src/mac/pmac/pmac_test.o src/mac/poly1305/poly1305.o \
 src/mac/poly1305/poly1305_file.o src/mac/poly1305/poly1305_memory.o \

makefile_include.mk

@@ -262,11 +262,12 @@ src/mac/blake2/blake2smac_memory_multi.o src/mac/blake2/blake2smac_test.o src/ma
 src/mac/f9/f9_file.o src/mac/f9/f9_init.o src/mac/f9/f9_memory.o src/mac/f9/f9_memory_multi.o \
 src/mac/f9/f9_process.o src/mac/f9/f9_test.o src/mac/hmac/hmac_done.o src/mac/hmac/hmac_file.o \
 src/mac/hmac/hmac_init.o src/mac/hmac/hmac_memory.o src/mac/hmac/hmac_memory_multi.o \
-src/mac/hmac/hmac_process.o src/mac/hmac/hmac_test.o src/mac/omac/omac_done.o src/mac/omac/omac_file.o \
-src/mac/omac/omac_init.o src/mac/omac/omac_memory.o src/mac/omac/omac_memory_multi.o \
-src/mac/omac/omac_process.o src/mac/omac/omac_test.o src/mac/pelican/pelican.o \
-src/mac/pelican/pelican_memory.o src/mac/pelican/pelican_test.o src/mac/pmac/pmac_done.o \
-src/mac/pmac/pmac_file.o src/mac/pmac/pmac_init.o src/mac/pmac/pmac_memory.o \
+src/mac/hmac/hmac_process.o src/mac/hmac/hmac_test.o src/mac/kmac/kmac.o src/mac/kmac/kmac_file.o \
+src/mac/kmac/kmac_memory.o src/mac/kmac/kmac_memory_multi.o src/mac/kmac/kmac_test.o \
+src/mac/omac/omac_done.o src/mac/omac/omac_file.o src/mac/omac/omac_init.o src/mac/omac/omac_memory.o \
+src/mac/omac/omac_memory_multi.o src/mac/omac/omac_process.o src/mac/omac/omac_test.o \
+src/mac/pelican/pelican.o src/mac/pelican/pelican_memory.o src/mac/pelican/pelican_test.o \
+src/mac/pmac/pmac_done.o src/mac/pmac/pmac_file.o src/mac/pmac/pmac_init.o src/mac/pmac/pmac_memory.o \
 src/mac/pmac/pmac_memory_multi.o src/mac/pmac/pmac_ntz.o src/mac/pmac/pmac_process.o \
 src/mac/pmac/pmac_shift_xor.o src/mac/pmac/pmac_test.o src/mac/poly1305/poly1305.o \
 src/mac/poly1305/poly1305_file.o src/mac/poly1305/poly1305_memory.o \

sources.cmake

@@ -145,6 +145,11 @@ src/mac/hmac/hmac_memory.c
 src/mac/hmac/hmac_memory_multi.c
 src/mac/hmac/hmac_process.c
 src/mac/hmac/hmac_test.c
+src/mac/kmac/kmac.c
+src/mac/kmac/kmac_file.c
+src/mac/kmac/kmac_memory.c
+src/mac/kmac/kmac_memory_multi.c
+src/mac/kmac/kmac_test.c
 src/mac/omac/omac_done.c
 src/mac/omac/omac_file.c
 src/mac/omac/omac_init.c

src/hashes/sha3.c

@@ -446,6 +446,13 @@ int sha3_shake_done(hash_state *md, unsigned char *out, unsigned long outlen)
    return s_sha3_shake_done(&md->sha3, out, outlen, 0x1f, s_keccakf);
 }
 
+#ifdef LTC_KMAC
+int sha3_shake_done_ex(hash_state *md, unsigned char *out, unsigned long outlen, unsigned char domain)
+{
+   return s_sha3_shake_done(&md->sha3, out, outlen, domain, s_keccakf);
+}
+#endif
+
 int sha3_shake128_done(hash_state *md, unsigned char *out)
 {
    return sha3_shake_done(md, out, 32);

src/headers/tomcrypt_custom.h

@@ -300,6 +300,7 @@
 #define LTC_POLY1305
 #define LTC_BLAKE2SMAC
 #define LTC_BLAKE2BMAC
+#define LTC_KMAC
 
 /* ---> Encrypt + Authenticate Modes <--- */
 
@@ -734,6 +735,10 @@
    #error LTC_BLAKE2BMAC requires LTC_BLAKE2B
 #endif
 
+#if defined(LTC_KMAC) && !defined(LTC_SHA3)
+   #error LTC_KMAC requires LTC_SHA3
+#endif
+
 #if defined(LTC_SPRNG) && !defined(LTC_RNG_GET_BYTES)
    #error LTC_SPRNG requires LTC_RNG_GET_BYTES
 #endif

src/headers/tomcrypt_mac.h

@@ -135,6 +135,42 @@ int blake2smac_file(const char *fname, const unsigned char *key, unsigned long k
 int blake2smac_test(void);
 #endif /* LTC_BLAKE2SMAC */
 
+#ifdef LTC_KMAC
+/* values for the `variant` argument of kmac_init() and friends */
+#define LTC_KMAC128       1
+#define LTC_KMAC256       2
+#define LTC_KMAC128_XOF   3
+#define LTC_KMAC256_XOF   4
+
+typedef struct Kmac_state {
+   hash_state sha3;
+   int        xof;
+} kmac_state;
+
+int kmac_init(kmac_state *st, int variant,
+              const unsigned char *key,  unsigned long keylen,
+              const unsigned char *cust, unsigned long custlen);
+int kmac_process(kmac_state *st, const unsigned char *in, unsigned long inlen);
+int kmac_done(kmac_state *st, unsigned char *out, unsigned long *outlen);
+int kmac_memory(int variant,
+                const unsigned char *key,  unsigned long keylen,
+                const unsigned char *cust, unsigned long custlen,
+                const unsigned char *in,   unsigned long inlen,
+                      unsigned char *out,  unsigned long *outlen);
+int kmac_memory_multi(int variant,
+                      const unsigned char *key,  unsigned long keylen,
+                      const unsigned char *cust, unsigned long custlen,
+                            unsigned char *out,  unsigned long *outlen,
+                      const unsigned char *in,   unsigned long inlen, ...)
+                      LTC_NULL_TERMINATED;
+int kmac_file(int variant,
+              const unsigned char *key,  unsigned long keylen,
+              const unsigned char *cust, unsigned long custlen,
+                       const char *fname,
+                    unsigned char *out,  unsigned long *outlen);
+int kmac_test(void);
+#endif /* LTC_KMAC */
+
 #ifdef LTC_BLAKE2BMAC
 typedef hash_state blake2bmac_state;
 int blake2bmac_init(blake2bmac_state *st, unsigned long outlen, const unsigned char *key, unsigned long keylen);

src/headers/tomcrypt_private.h

@@ -197,6 +197,10 @@ int sha224_test_desc(const struct ltc_hash_descriptor *desc, const char *name);
 int sha256_test_desc(const struct ltc_hash_descriptor *desc, const char *name);
 #endif
 
+#ifdef LTC_KMAC
+int sha3_shake_done_ex(hash_state *md, unsigned char *out, unsigned long outlen, unsigned char domain);
+#endif
+
 /* tomcrypt_mac.h */
 
 int ocb3_int_ntz(unsigned long x);