lc_hash.h

Go to the documentation of this file.

/*
 * Copyright (C) 2020 - 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_HASH_H
#define LC_HASH_H
 
#include "ext_headers.h"
#include "lc_memset_secure.h"
#include "lc_memory_support.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct lc_hash {
        /* SHA3 / SHAKE interface */
        void (*init)(void *state);
        void (*update)(void *state, const uint8_t *in, size_t inlen);
        void (*final)(void *state, uint8_t *digest);
        void (*set_digestsize)(void *state, size_t digestsize);
        size_t (*get_digestsize)(void *state);
 
        /* Sponge interface */
        void (*sponge_permutation)(void *state, unsigned int rounds);
        void (*sponge_add_bytes)(void *state, const uint8_t *data,
                                 size_t offset, size_t length);
        void (*sponge_extract_bytes)(const void *state, uint8_t *data,
                                     size_t offset, size_t length);
        void (*sponge_newstate)(void *state, const uint8_t *newstate,
                                size_t offset, size_t length);
 
        uint8_t sponge_rate;
        unsigned short statesize;
};
 
struct lc_hash_ctx {
        const struct lc_hash *hash;
        void *hash_state;
};
 
/*
 * Align the hash_state pointer to 8 bytes boundary irrespective where
 * it is embedded into. This is achieved by adding 7 more bytes than necessary
 * to LC_ALIGNED_BUFFER and then adjusting the pointer offset in that range
 * accordingly.
 *
 * It is permissible to set the alignment requirement with compile-time
 * arguments.
 */
#ifndef LC_HASH_COMMON_ALIGNMENT
/* Macro set during leancrypto compile time for target platform */
#define LC_HASH_COMMON_ALIGNMENT 64
#endif
 
#define LC_ALIGN_HASH_MASK(p)                                                  \
        LC_ALIGN_PTR_64(p, LC_ALIGNMENT_MASK(LC_HASH_COMMON_ALIGNMENT))
 
#define LC_SHA_MAX_SIZE_DIGEST 64
 
/*
 * This is the source of the compiler warning of using Variable-Length-Arrays
 * (VLA). It is considered to be harmless to have this VLA here. If you do not
 * want it, you have the following options:
 *
 * 1. Define a hard-coded value here, e.g. sizeof(struct lc_sha3_224_state)
 *    as the SHA3-224 has the largest structure.
 * 2. Only use the SHA-specific stack allocation functions
 *    (e.g. LC_SHA3_256_CTX_ON_STACK) instead of the generic
 *    LC_HASH_CTX_ON_STACK call.
 * 3. Do not use stack-allocation function.
 * 4. Ignore the warning by using
 * #pragma GCC diagnostic ignored "-Wvla"
 * #pragma GCC diagnostic push
 * LC_HASH_CTX_ON_STACK()
 * #pragma pop
 */
#define LC_HASH_STATE_SIZE_NONALIGNED(x) ((unsigned long)(x->statesize))
#define LC_HASH_STATE_SIZE(x)                                                  \
        (LC_HASH_STATE_SIZE_NONALIGNED(x) + LC_HASH_COMMON_ALIGNMENT)
#define LC_HASH_CTX_SIZE(x) (sizeof(struct lc_hash_ctx) + LC_HASH_STATE_SIZE(x))
 
#define _LC_HASH_SET_CTX(name, hashname, ctx, offset)                          \
        name->hash_state = LC_ALIGN_HASH_MASK(((uint8_t *)(ctx)) + (offset));  \
        name->hash = hashname
 
#define LC_HASH_SET_CTX(name, hashname)                                        \
        _LC_HASH_SET_CTX(name, hashname, name, sizeof(struct lc_hash_ctx))
 
static inline void lc_hash_init(struct lc_hash_ctx *hash_ctx)
{
        const struct lc_hash *hash;
 
        if (!hash_ctx)
                return;
 
        hash = hash_ctx->hash;
        hash->init(hash_ctx->hash_state);
}
 
static inline void lc_hash_update(struct lc_hash_ctx *hash_ctx,
                                  const uint8_t *in, size_t inlen)
{
        const struct lc_hash *hash;
 
        if (!hash_ctx)
                return;
 
        hash = hash_ctx->hash;
        hash->update(hash_ctx->hash_state, in, inlen);
}
 
static inline void lc_hash_final(struct lc_hash_ctx *hash_ctx, uint8_t *digest)
{
        const struct lc_hash *hash;
 
        if (!hash_ctx || !digest)
                return;
 
        hash = hash_ctx->hash;
        hash->final(hash_ctx->hash_state, digest);
}
 
static inline void lc_hash_set_digestsize(struct lc_hash_ctx *hash_ctx,
                                          size_t digestsize)
{
        const struct lc_hash *hash;
 
        if (!hash_ctx)
                return;
 
        hash = hash_ctx->hash;
        if (hash->set_digestsize)
                hash->set_digestsize(hash_ctx->hash_state, digestsize);
}
 
static inline size_t lc_hash_digestsize(struct lc_hash_ctx *hash_ctx)
{
        const struct lc_hash *hash;
 
        if (!hash_ctx)
                return 0;
 
        hash = hash_ctx->hash;
        return hash->get_digestsize(hash_ctx->hash_state);
}
 
static inline unsigned int lc_hash_blocksize(struct lc_hash_ctx *hash_ctx)
{
        const struct lc_hash *hash;
 
        if (!hash_ctx)
                return 0;
 
        hash = hash_ctx->hash;
        return hash->sponge_rate;
}
 
static inline unsigned int lc_hash_ctxsize(struct lc_hash_ctx *hash_ctx)
{
        const struct lc_hash *hash;
 
        if (!hash_ctx)
                return 0;
 
        hash = hash_ctx->hash;
        return hash->statesize;
}
 
static inline void lc_hash_zero(struct lc_hash_ctx *hash_ctx)
{
        const struct lc_hash *hash;
 
        if (!hash_ctx)
                return;
 
        hash = hash_ctx->hash;
        lc_memset_secure((uint8_t *)hash_ctx + sizeof(struct lc_hash_ctx), 0,
                         hash->statesize);
}
 
#define LC_HASH_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_HASH_CTX_SIZE(hashname),               \
                                          LC_HASH_COMMON_ALIGNMENT);                \
        struct lc_hash_ctx *name = (struct lc_hash_ctx *)name##_ctx_buf;            \
        LC_HASH_SET_CTX(name, hashname);                                            \
        lc_hash_zero(name);                                                         \
        _Pragma("GCC diagnostic pop")
 
int lc_hash_alloc(const struct lc_hash *hash, struct lc_hash_ctx **hash_ctx);
 
void lc_hash_zero_free(struct lc_hash_ctx *hash_ctx);
 
void lc_hash(const struct lc_hash *hash, const uint8_t *in, size_t inlen,
             uint8_t *digest);
 
void lc_xof(const struct lc_hash *xof, const uint8_t *in, size_t inlen,
            uint8_t *digest, size_t digestlen);
 
static inline int lc_sponge(const struct lc_hash *hash, void *state,
                            unsigned int rounds)
{
        if (!state || !hash || !hash->sponge_permutation)
                return -EOPNOTSUPP;
 
        hash->sponge_permutation(state, rounds);
 
        return 0;
}
 
static inline int lc_sponge_add_bytes(const struct lc_hash *hash, void *state,
                                      const uint8_t *data, size_t offset,
                                      size_t length)
{
        if (!state || !hash || !hash->sponge_add_bytes)
                return -EOPNOTSUPP;
 
        hash->sponge_add_bytes(state, data, offset, length);
 
        return 0;
}
 
static inline int lc_sponge_extract_bytes(const struct lc_hash *hash,
                                          const void *state, uint8_t *data,
                                          size_t offset, size_t length)
{
        if (!state || !hash || !hash->sponge_extract_bytes)
                return -EOPNOTSUPP;
 
        hash->sponge_extract_bytes(state, data, offset, length);
 
        return 0;
}
 
static inline int lc_sponge_newstate(const struct lc_hash *hash, void *state,
                                     const uint8_t *data, size_t offset,
                                     size_t length)
{
        if (!state || !hash || !hash->sponge_newstate)
                return -EOPNOTSUPP;
 
        hash->sponge_newstate(state, data, offset, length);
 
        return 0;
}
 
#ifdef __cplusplus
}
#endif
 
#endif /* LC_HASH_H */