lc_hash.h

Go to the documentation of this file.

/*
 * Copyright (C) 2020 - 2025, 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 */
        int (*init)(void *state);
        int (*init_nocheck)(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);
        uint64_t algorithm_type;
 
        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 8
#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 push
 * #pragma GCC diagnostic ignored "-Wvla"
 * LC_HASH_CTX_ON_STACK()
 * #pragma GCC diagnostic 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))


int lc_hash_init(struct lc_hash_ctx *hash_ctx);

void lc_hash_update(struct lc_hash_ctx *hash_ctx, const uint8_t *in,
                    size_t inlen);

void lc_hash_final(struct lc_hash_ctx *hash_ctx, uint8_t *digest);

void lc_hash_set_digestsize(struct lc_hash_ctx *hash_ctx, size_t digestsize);

size_t lc_hash_digestsize(struct lc_hash_ctx *hash_ctx);

unsigned int lc_hash_blocksize(struct lc_hash_ctx *hash_ctx);

unsigned int lc_hash_ctxsize(struct lc_hash_ctx *hash_ctx);

void lc_hash_zero(struct lc_hash_ctx *hash_ctx);

#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);                                            \
        _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);

int lc_hash(const struct lc_hash *hash, const uint8_t *in, size_t inlen,
            uint8_t *digest);

int lc_xof(const struct lc_hash *xof, const uint8_t *in, size_t inlen,
           uint8_t *digest, size_t digestlen);

int lc_sponge(const struct lc_hash *hash, void *state, unsigned int rounds);

int lc_sponge_add_bytes(const struct lc_hash *hash, void *state,
                        const uint8_t *data, size_t offset, size_t length);

int lc_sponge_extract_bytes(const struct lc_hash *hash, const void *state,
                            uint8_t *data, size_t offset, size_t length);

int lc_sponge_newstate(const struct lc_hash *hash, void *state,
                       const uint8_t *data, size_t offset, size_t length);

uint64_t lc_hash_algorithm_type(const struct lc_hash *hash);

uint64_t lc_hash_ctx_algorithm_type(const struct lc_hash_ctx *ctx);
 
 
#ifdef __cplusplus
}
#endif
 
#endif /* LC_HASH_H */