lc_kmac.h

Go to the documentation of this file.

/*
 * Copyright (C) 2022 - 2024, Stephan Mueller <smueller@chronox.de>
 *
 * License: see LICENSE file in root directory
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ALL OF
 * WHICH ARE HEREBY DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
 * USE OF THIS SOFTWARE, EVEN IF NOT ADVISED OF THE POSSIBILITY OF SUCH
 * DAMAGE.
 */
 
#ifndef LC_KMAC_H
#define LC_KMAC_H
 
#include "lc_hash.h"
#include "lc_rng.h"
#include "lc_sha3.h"
#include "lc_memset_secure.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct lc_kmac_ctx {
        uint8_t final_called : 1;
        uint8_t rng_initialized : 1;
        uint8_t *shadow_ctx;
        struct lc_hash_ctx hash_ctx;
};
 
#define LC_KMAC_STATE_SIZE(x) (LC_HASH_STATE_SIZE(x))
#define LC_KMAC_STATE_SIZE_REINIT(x) (2 * LC_HASH_STATE_SIZE(x))
#define LC_KMAC_CTX_SIZE(x) (LC_KMAC_STATE_SIZE(x) + sizeof(struct lc_kmac_ctx))
#define LC_KMAC_CTX_SIZE_REINIT(x)                                             \
        (LC_KMAC_STATE_SIZE_REINIT(x) + sizeof(struct lc_kmac_ctx))
 
#define _LC_KMAC_SET_CTX(name, hashname, ctx, offset)                          \
        _LC_HASH_SET_CTX((&name->hash_ctx), hashname, ctx, offset);            \
        name->shadow_ctx = NULL
 
#define LC_KMAC_SET_CTX(name, hashname)                                        \
        _LC_KMAC_SET_CTX(name, hashname, name, sizeof(struct lc_kmac_ctx))
 
#define _LC_KMAC_SET_CTX_REINIT(name, hashname, ctx, offset)                   \
        _LC_HASH_SET_CTX((&name->hash_ctx), hashname, ctx, offset);            \
        name->shadow_ctx = (uint8_t *)((uint8_t *)ctx + offset +               \
                                       LC_HASH_STATE_SIZE(hashname))
 
#define LC_KMAC_SET_CTX_REINIT(name, hashname)                                 \
        _LC_KMAC_SET_CTX_REINIT(name, hashname, name,                          \
                                sizeof(struct lc_kmac_ctx))
 
void lc_kmac_init(struct lc_kmac_ctx *kmac_ctx, const uint8_t *key, size_t klen,
                  const uint8_t *s, size_t slen);
 
void lc_kmac_reinit(struct lc_kmac_ctx *kmac_ctx);
 
void lc_kmac_update(struct lc_kmac_ctx *kmac_ctx, const uint8_t *in,
                    size_t inlen);
 
void lc_kmac_final(struct lc_kmac_ctx *kmac_ctx, uint8_t *mac, size_t maclen);
 
void lc_kmac_final_xof(struct lc_kmac_ctx *kmac_ctx, uint8_t *mac,
                       size_t maclen);
 
int lc_kmac_alloc(const struct lc_hash *hash, struct lc_kmac_ctx **kmac_ctx,
                  uint32_t flags);
 
/*
 * Support re-initialization of state. You set a key during kmac_init,
 * perform a full KMAC operation. After a kmac_final, the re-initialization
 * support allows you to call kmac_reinit and reuse the state for a new
 * operation without providing the keys again. If in doubt, initialize
 * the context with re-init support. The difference is that more memory is
 * allocated to retain the initialized state.
 */
#define LC_KMAC_FLAGS_SUPPORT_REINIT (1 << 0)
 
void lc_kmac_zero_free(struct lc_kmac_ctx *kmac_ctx);
 
static inline void lc_kmac_zero(struct lc_kmac_ctx *kmac_ctx)
{
        struct lc_hash_ctx *hash_ctx;
        const struct lc_hash *hash;
 
        if (!kmac_ctx)
                return;
        hash_ctx = &kmac_ctx->hash_ctx;
        hash = hash_ctx->hash;
 
        kmac_ctx->final_called = 0;
        kmac_ctx->rng_initialized = 0;
 
        lc_memset_secure((uint8_t *)kmac_ctx + sizeof(struct lc_kmac_ctx), 0,
                         kmac_ctx->shadow_ctx ?
                                 LC_KMAC_STATE_SIZE_REINIT(hash) :
                                 LC_KMAC_STATE_SIZE(hash));
}
 
#define LC_KMAC_CTX_ON_STACK(name, hashname)                                        \
        _Pragma("GCC diagnostic push")                                              \
                _Pragma("GCC diagnostic ignored \"-Wvla\"") _Pragma(                \
                        "GCC diagnostic ignored \"-Wdeclaration-after-statement\"") \
                        LC_ALIGNED_BUFFER(name##_ctx_buf,                           \
                                          LC_KMAC_CTX_SIZE(hashname),               \
                                          LC_HASH_COMMON_ALIGNMENT);                \
        struct lc_kmac_ctx *name = (struct lc_kmac_ctx *)name##_ctx_buf;            \
        LC_KMAC_SET_CTX(name, hashname);                                            \
        lc_kmac_zero(name);                                                         \
        _Pragma("GCC diagnostic pop")
 
#define LC_KMAC_CTX_ON_STACK_REINIT(name, hashname)                                 \
        _Pragma("GCC diagnostic push")                                              \
                _Pragma("GCC diagnostic ignored \"-Wvla\"") _Pragma(                \
                        "GCC diagnostic ignored \"-Wdeclaration-after-statement\"") \
                        LC_ALIGNED_BUFFER(name##_ctx_buf,                           \
                                          LC_KMAC_CTX_SIZE_REINIT(hashname),        \
                                          LC_HASH_COMMON_ALIGNMENT);                \
        struct lc_kmac_ctx *name = (struct lc_kmac_ctx *)name##_ctx_buf;            \
        LC_KMAC_SET_CTX_REINIT(name, hashname);                                     \
        lc_kmac_zero(name);                                                         \
        _Pragma("GCC diagnostic pop")
 
static inline size_t lc_kmac_macsize(struct lc_kmac_ctx *kmac_ctx)
{
        struct lc_hash_ctx *hash_ctx;
 
        if (!kmac_ctx)
                return 0;
 
        hash_ctx = &kmac_ctx->hash_ctx;
        return lc_hash_digestsize(hash_ctx);
}
 
static inline void lc_kmac(const struct lc_hash *hash, const uint8_t *key,
                           size_t keylen, const uint8_t *s, size_t slen,
                           const uint8_t *in, size_t inlen, uint8_t *mac,
                           size_t maclen)
{
        LC_KMAC_CTX_ON_STACK(kmac_ctx, hash);
 
        lc_kmac_init(kmac_ctx, key, keylen, s, slen);
        lc_kmac_update(kmac_ctx, in, inlen);
        lc_kmac_final(kmac_ctx, mac, maclen);
 
        lc_kmac_zero(kmac_ctx);
}
 
static inline void lc_kmac_xof(const struct lc_hash *hash, const uint8_t *key,
                               size_t keylen, const uint8_t *s, size_t slen,
                               const uint8_t *in, size_t inlen, uint8_t *mac,
                               size_t maclen)
{
        LC_KMAC_CTX_ON_STACK(kmac_ctx, hash);
 
        lc_kmac_init(kmac_ctx, key, keylen, s, slen);
        lc_kmac_update(kmac_ctx, in, inlen);
        lc_kmac_final_xof(kmac_ctx, mac, maclen);
 
        lc_kmac_zero(kmac_ctx);
}
 
/******************************** KMAC as RNG *********************************/
 
/*
 * The KMAC can be used as an RNG context for aggregated algorithms like
 * Kyber or Dilithium. The idea is that KMAC acts as a key derivation function
 * whose state can be initialized from an input data to deterministically derive
 * the values required for the algorithms the RNG context is used with.
 *
 * This RNG state is NOT intended to serve as a general-purpose deterministic
 * random number generator. For using KMAC as a such general-purpose DRNG, see
 * the API provided with lc_kmac256_drng.h.
 */
 
/* KMAC DRNG implementation */
extern const struct lc_rng *lc_kmac_rng;
 
#define LC_KMAC_KDF_DRNG_CTX_SIZE(hashname)                                    \
        (sizeof(struct lc_rng_ctx) + LC_KMAC_CTX_SIZE(hashname))
 
#define LC_KMAC_KDF_DRNG_SET_CTX(name, hashname) LC_KMAC_SET_CTX(name, hashname)
 
#define LC_KMAC_KDF_RNG_CTX(name, hashname)                                    \
        LC_RNG_CTX(name, lc_kmac_rng);                                         \
        LC_KMAC_KDF_DRNG_SET_CTX(((struct lc_kmac_ctx *)(name->rng_state)),    \
                                 hashname);                                    \
        lc_rng_zero(name)
 
#define LC_KMAC_KDF_DRNG_CTX_ON_STACK(name, hashname)                               \
        _Pragma("GCC diagnostic push")                                              \
                _Pragma("GCC diagnostic ignored \"-Wvla\"") _Pragma(                \
                        "GCC diagnostic ignored \"-Wdeclaration-after-statement\"") \
                        LC_ALIGNED_BUFFER(name##_ctx_buf,                           \
                                          LC_KMAC_KDF_DRNG_CTX_SIZE(hashname),      \
                                          LC_HASH_COMMON_ALIGNMENT);                \
        struct lc_rng_ctx *name = (struct lc_rng_ctx *)name##_ctx_buf;              \
        LC_KMAC_KDF_RNG_CTX(name, hashname);                                        \
        _Pragma("GCC diagnostic pop")
 
int lc_kmac_rng_alloc(struct lc_rng_ctx **state, const struct lc_hash *hash);
 
#ifdef __cplusplus
}
#endif
 
#endif /* LC_KMAC_H */