lc_dilithium.h

Go to the documentation of this file.

/*
 * Copyright (C) 2022 - 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.
 */
/*
 * This code is derived in parts from the code distribution provided with
 * https://github.com/pq-crystals/dilithium
 *
 * That code is released under Public Domain
 * (https://creativecommons.org/share-your-work/public-domain/cc0/);
 * or Apache 2.0 License (https://www.apache.org/licenses/LICENSE-2.0.html).
 */
 
#ifndef LC_DILITHIUM_H
#define LC_DILITHIUM_H
 
#include "ext_headers.h"
 
#if defined __has_include
 
#if __has_include("lc_dilithium_87.h")
#include "lc_dilithium_87.h"
#define LC_DILITHIUM_87_ENABLED
#endif
 
#if __has_include("lc_dilithium_65.h")
#include "lc_dilithium_65.h"
#define LC_DILITHIUM_65_ENABLED
#endif
 
#if __has_include("lc_dilithium_44.h")
#include "lc_dilithium_44.h"
#define LC_DILITHIUM_44_ENABLED
#endif
 
#else
#error "Compiler misses __has_include"
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
enum lc_dilithium_type {
        LC_DILITHIUM_UNKNOWN,
        LC_DILITHIUM_87,
        LC_DILITHIUM_65,
        LC_DILITHIUM_44,
};


struct lc_dilithium_sk {
        enum lc_dilithium_type dilithium_type;
        union {
#ifdef LC_DILITHIUM_87_ENABLED
                struct lc_dilithium_87_sk sk_87;
#endif
#ifdef LC_DILITHIUM_65_ENABLED
                struct lc_dilithium_65_sk sk_65;
#endif
#ifdef LC_DILITHIUM_44_ENABLED
                struct lc_dilithium_44_sk sk_44;
#endif
        } key;
};

struct lc_dilithium_pk {
        enum lc_dilithium_type dilithium_type;
        union {
#ifdef LC_DILITHIUM_87_ENABLED
                struct lc_dilithium_87_pk pk_87;
#endif
#ifdef LC_DILITHIUM_65_ENABLED
                struct lc_dilithium_65_pk pk_65;
#endif
#ifdef LC_DILITHIUM_44_ENABLED
                struct lc_dilithium_44_pk pk_44;
#endif
        } key;
};

struct lc_dilithium_sig {
        enum lc_dilithium_type dilithium_type;
        union {
#ifdef LC_DILITHIUM_87_ENABLED
                struct lc_dilithium_87_sig sig_87;
#endif
#ifdef LC_DILITHIUM_65_ENABLED
                struct lc_dilithium_65_sig sig_65;
#endif
#ifdef LC_DILITHIUM_44_ENABLED
                struct lc_dilithium_44_sig sig_44;
#endif
        } sig;
};

#ifdef LC_DILITHIUM_87_ENABLED
#define LC_DILITHIUM_CTX_ON_STACK_AHAT(name)                                   \
        LC_DILITHIUM_87_CTX_ON_STACK_AHAT(name)
#elif defined(LC_DILITHIUM_65_ENABLED)
LC_DILITHIUM_CTX_ON_STACK_AHAT(name)
LC_DILITHIUM_65_CTX_ON_STACK_AHAT(name)
#elif defined(LC_DILITHIUM_44_ENABLED)
LC_DILITHIUM_CTX_ON_STACK_AHAT(name)
LC_DILITHIUM_44_CTX_ON_STACK_AHAT(name)
#endif

int lc_dilithium_ctx_alloc(struct lc_dilithium_ctx **ctx);

int lc_dilithium_ctx_alloc_ahat(struct lc_dilithium_ctx **ctx);

void lc_dilithium_ctx_zero_free(struct lc_dilithium_ctx *ctx);

void lc_dilithium_ctx_zero(struct lc_dilithium_ctx *ctx);

void lc_dilithium_ctx_internal(struct lc_dilithium_ctx *ctx);

void lc_dilithium_ctx_hash(struct lc_dilithium_ctx *ctx,
                           const struct lc_hash *hash);

void lc_dilithium_ctx_userctx(struct lc_dilithium_ctx *ctx,
                              const uint8_t *userctx, size_t userctxlen);

void lc_dilithium_ctx_external_mu(struct lc_dilithium_ctx *ctx,
                                  const uint8_t *external_mu,
                                  size_t external_mu_len);

void lc_dilithium_ctx_drop_ahat(struct lc_dilithium_ctx *ctx);

enum lc_dilithium_type lc_dilithium_sk_type(const struct lc_dilithium_sk *sk);

enum lc_dilithium_type lc_dilithium_pk_type(const struct lc_dilithium_pk *pk);

enum lc_dilithium_type
lc_dilithium_sig_type(const struct lc_dilithium_sig *sig);

LC_PURE unsigned int
lc_dilithium_sk_size(enum lc_dilithium_type dilithium_type);

LC_PURE unsigned int
lc_dilithium_pk_size(enum lc_dilithium_type dilithium_type);

LC_PURE unsigned int
lc_dilithium_sig_size(enum lc_dilithium_type dilithium_type);

int lc_dilithium_sk_load(struct lc_dilithium_sk *sk, const uint8_t *src_key,
                         size_t src_key_len);

int lc_dilithium_pk_load(struct lc_dilithium_pk *pk, const uint8_t *src_key,
                         size_t src_key_len);

int lc_dilithium_sig_load(struct lc_dilithium_sig *sig, const uint8_t *src_sig,
                          size_t src_sig_len);

int lc_dilithium_sk_ptr(uint8_t **dilithium_key, size_t *dilithium_key_len,
                        struct lc_dilithium_sk *sk);

int lc_dilithium_pk_ptr(uint8_t **dilithium_key, size_t *dilithium_key_len,
                        struct lc_dilithium_pk *pk);

int lc_dilithium_sig_ptr(uint8_t **dilithium_sig, size_t *dilithium_sig_len,
                         struct lc_dilithium_sig *sig);

int lc_dilithium_keypair(struct lc_dilithium_pk *pk, struct lc_dilithium_sk *sk,
                         struct lc_rng_ctx *rng_ctx,
                         enum lc_dilithium_type dilithium_type);

int lc_dilithium_keypair_from_seed(struct lc_dilithium_pk *pk,
                                   struct lc_dilithium_sk *sk,
                                   const uint8_t *seed, size_t seedlen,
                                   enum lc_dilithium_type dilithium_type);

int lc_dilithium_pct(const struct lc_dilithium_pk *pk,
                     const struct lc_dilithium_sk *sk);

int lc_dilithium_sign(struct lc_dilithium_sig *sig, const uint8_t *m,
                      size_t mlen, const struct lc_dilithium_sk *sk,
                      struct lc_rng_ctx *rng_ctx);

int lc_dilithium_sign_ctx(struct lc_dilithium_sig *sig,
                          struct lc_dilithium_ctx *ctx, const uint8_t *m,
                          size_t mlen, const struct lc_dilithium_sk *sk,
                          struct lc_rng_ctx *rng_ctx);

int lc_dilithium_sign_init(struct lc_dilithium_ctx *ctx,
                           const struct lc_dilithium_sk *sk);

int lc_dilithium_sign_update(struct lc_dilithium_ctx *ctx, const uint8_t *m,
                             size_t mlen);

int lc_dilithium_sign_final(struct lc_dilithium_sig *sig,
                            struct lc_dilithium_ctx *ctx,
                            const struct lc_dilithium_sk *sk,
                            struct lc_rng_ctx *rng_ctx);

int lc_dilithium_verify(const struct lc_dilithium_sig *sig, const uint8_t *m,
                        size_t mlen, const struct lc_dilithium_pk *pk);

int lc_dilithium_verify_ctx(const struct lc_dilithium_sig *sig,
                            struct lc_dilithium_ctx *ctx, const uint8_t *m,
                            size_t mlen, const struct lc_dilithium_pk *pk);

int lc_dilithium_verify_init(struct lc_dilithium_ctx *ctx,
                             const struct lc_dilithium_pk *pk);

int lc_dilithium_verify_update(struct lc_dilithium_ctx *ctx, const uint8_t *m,
                               size_t mlen);

int lc_dilithium_verify_final(const struct lc_dilithium_sig *sig,
                              struct lc_dilithium_ctx *ctx,
                              const struct lc_dilithium_pk *pk);
 
/****************************** Dilithium ED25510 *****************************/
 
#ifdef LC_DILITHIUM_ED25519_SIG


struct lc_dilithium_ed25519_sk {
        enum lc_dilithium_type dilithium_type;
        union {
#ifdef LC_DILITHIUM_87_ENABLED
                struct lc_dilithium_87_ed25519_sk sk_87;
#endif
#ifdef LC_DILITHIUM_65_ENABLED
                struct lc_dilithium_65_ed25519_sk sk_65;
#endif
#ifdef LC_DILITHIUM_44_ENABLED
                struct lc_dilithium_44_ed25519_sk sk_44;
#endif
        } key;
};

struct lc_dilithium_ed25519_pk {
        enum lc_dilithium_type dilithium_type;
        union {
#ifdef LC_DILITHIUM_87_ENABLED
                struct lc_dilithium_87_ed25519_pk pk_87;
#endif
#ifdef LC_DILITHIUM_65_ENABLED
                struct lc_dilithium_65_ed25519_pk pk_65;
#endif
#ifdef LC_DILITHIUM_44_ENABLED
                struct lc_dilithium_44_ed25519_pk pk_44;
#endif
        } key;
};

struct lc_dilithium_ed25519_sig {
        enum lc_dilithium_type dilithium_type;
        union {
#ifdef LC_DILITHIUM_87_ENABLED
                struct lc_dilithium_87_ed25519_sig sig_87;
#endif
#ifdef LC_DILITHIUM_65_ENABLED
                struct lc_dilithium_65_ed25519_sig sig_65;
#endif
#ifdef LC_DILITHIUM_44_ENABLED
                struct lc_dilithium_44_ed25519_sig sig_44;
#endif
        } sig;
};

int lc_dilithium_ed25519_ctx_alloc(struct lc_dilithium_ed25519_ctx **ctx);

void lc_dilithium_ed25519_ctx_zero_free(struct lc_dilithium_ed25519_ctx *ctx);

void lc_dilithium_ed25519_ctx_zero(struct lc_dilithium_ed25519_ctx *ctx);

void lc_dilithium_ed25519_ctx_hash(struct lc_dilithium_ed25519_ctx *ctx,
                                   const struct lc_hash *hash);

void lc_dilithium_ed25519_ctx_internal(struct lc_dilithium_ed25519_ctx *ctx);

void lc_dilithium_ed25519_ctx_userctx(struct lc_dilithium_ed25519_ctx *ctx,
                                      const uint8_t *userctx,
                                      size_t userctxlen);

void lc_dilithium_ed25519_ctx_randomizer(struct lc_dilithium_ed25519_ctx *ctx,
                                         const uint8_t *randomizer,
                                         size_t randomizerlen);

enum lc_dilithium_type
lc_dilithium_ed25519_sk_type(const struct lc_dilithium_ed25519_sk *sk);

enum lc_dilithium_type
lc_dilithium_ed25519_pk_type(const struct lc_dilithium_ed25519_pk *pk);

enum lc_dilithium_type
lc_dilithium_ed25519_sig_type(const struct lc_dilithium_ed25519_sig *sig);

LC_PURE unsigned int
lc_dilithium_ed25519_sk_size(enum lc_dilithium_type dilithium_type);

LC_PURE unsigned int
lc_dilithium_ed25519_pk_size(enum lc_dilithium_type dilithium_type);

LC_PURE unsigned int
lc_dilithium_ed25519_sig_size(enum lc_dilithium_type dilithium_type);

int lc_dilithium_ed25519_sk_load(struct lc_dilithium_ed25519_sk *sk,
                                 const uint8_t *dilithium_src_key,
                                 size_t dilithium_src_key_len,
                                 const uint8_t *ed25519_src_key,
                                 size_t ed25519_src_key_len);

int lc_dilithium_ed25519_pk_load(struct lc_dilithium_ed25519_pk *pk,
                                 const uint8_t *dilithium_src_key,
                                 size_t dilithium_src_key_len,
                                 const uint8_t *ed25519_src_key,
                                 size_t ed25519_src_key_len);

int lc_dilithium_ed25519_sig_load(struct lc_dilithium_ed25519_sig *sig,
                                  const uint8_t *dilithium_src_sig,
                                  size_t dilithium_src_sig_len,
                                  const uint8_t *ed25519_src_sig,
                                  size_t ed25519_src_sig_len);

int lc_dilithium_ed25519_sk_ptr(uint8_t **dilithium_key,
                                size_t *dilithium_key_len,
                                uint8_t **ed25519_key, size_t *ed25519_key_len,
                                struct lc_dilithium_ed25519_sk *sk);

int lc_dilithium_ed25519_pk_ptr(uint8_t **dilithium_key,
                                size_t *dilithium_key_len,
                                uint8_t **ed25519_key, size_t *ed25519_key_len,
                                struct lc_dilithium_ed25519_pk *pk);

int lc_dilithium_ed25519_sig_ptr(uint8_t **dilithium_sig,
                                 size_t *dilithium_sig_len,
                                 uint8_t **ed25519_sig, size_t *ed25519_sig_len,
                                 struct lc_dilithium_ed25519_sig *sig);

int lc_dilithium_ed25519_keypair(struct lc_dilithium_ed25519_pk *pk,
                                 struct lc_dilithium_ed25519_sk *sk,
                                 struct lc_rng_ctx *rng_ctx,
                                 enum lc_dilithium_type dilithium_type);

int lc_dilithium_ed25519_sign(struct lc_dilithium_ed25519_sig *sig,
                              const uint8_t *m, size_t mlen,
                              const struct lc_dilithium_ed25519_sk *sk,
                              struct lc_rng_ctx *rng_ctx);

int lc_dilithium_ed25519_sign_ctx(struct lc_dilithium_ed25519_sig *sig,
                                  struct lc_dilithium_ed25519_ctx *ctx,
                                  const uint8_t *m, size_t mlen,
                                  const struct lc_dilithium_ed25519_sk *sk,
                                  struct lc_rng_ctx *rng_ctx);

int lc_dilithium_ed25519_sign_init(struct lc_dilithium_ed25519_ctx *ctx,
                                   const struct lc_dilithium_ed25519_sk *sk);

int lc_dilithium_ed25519_sign_update(struct lc_dilithium_ed25519_ctx *ctx,
                                     const uint8_t *m, size_t mlen);

int lc_dilithium_ed25519_sign_final(struct lc_dilithium_ed25519_sig *sig,
                                    struct lc_dilithium_ed25519_ctx *ctx,
                                    const struct lc_dilithium_ed25519_sk *sk,
                                    struct lc_rng_ctx *rng_ctx);

int lc_dilithium_ed25519_verify(const struct lc_dilithium_ed25519_sig *sig,
                                const uint8_t *m, size_t mlen,
                                const struct lc_dilithium_ed25519_pk *pk);

int lc_dilithium_ed25519_verify_ctx(const struct lc_dilithium_ed25519_sig *sig,
                                    struct lc_dilithium_ed25519_ctx *ctx,
                                    const uint8_t *m, size_t mlen,
                                    const struct lc_dilithium_ed25519_pk *pk);

int lc_dilithium_ed25519_verify_init(struct lc_dilithium_ed25519_ctx *ctx,
                                     const struct lc_dilithium_ed25519_pk *pk);

int lc_dilithium_ed25519_verify_update(struct lc_dilithium_ed25519_ctx *ctx,
                                       const uint8_t *m, size_t mlen);

int lc_dilithium_ed25519_verify_final(const struct lc_dilithium_ed25519_sig *sig,
                                      struct lc_dilithium_ed25519_ctx *ctx,
                                      const struct lc_dilithium_ed25519_pk *pk);
 
#endif /* LC_DILITHIUM_ED25519_SIG */
 
/****************************** Dilithium ED25510 *****************************/
 
#ifdef LC_DILITHIUM_ED448_SIG


struct lc_dilithium_ed448_sk {
        enum lc_dilithium_type dilithium_type;
        union {
#ifdef LC_DILITHIUM_87_ENABLED
                struct lc_dilithium_87_ed448_sk sk_87;
#endif
#ifdef LC_DILITHIUM_65_ENABLED
                struct lc_dilithium_65_ed448_sk sk_65;
#endif
#ifdef LC_DILITHIUM_44_ENABLED
                struct lc_dilithium_44_ed448_sk sk_44;
#endif
        } key;
};

struct lc_dilithium_ed448_pk {
        enum lc_dilithium_type dilithium_type;
        union {
#ifdef LC_DILITHIUM_87_ENABLED
                struct lc_dilithium_87_ed448_pk pk_87;
#endif
#ifdef LC_DILITHIUM_65_ENABLED
                struct lc_dilithium_65_ed448_pk pk_65;
#endif
#ifdef LC_DILITHIUM_44_ENABLED
                struct lc_dilithium_44_ed448_pk pk_44;
#endif
        } key;
};

struct lc_dilithium_ed448_sig {
        enum lc_dilithium_type dilithium_type;
        union {
#ifdef LC_DILITHIUM_87_ENABLED
                struct lc_dilithium_87_ed448_sig sig_87;
#endif
#ifdef LC_DILITHIUM_65_ENABLED
                struct lc_dilithium_65_ed448_sig sig_65;
#endif
#ifdef LC_DILITHIUM_44_ENABLED
                struct lc_dilithium_44_ed448_sig sig_44;
#endif
        } sig;
};

int lc_dilithium_ed448_ctx_alloc(struct lc_dilithium_ed448_ctx **ctx);

void lc_dilithium_ed448_ctx_zero_free(struct lc_dilithium_ed448_ctx *ctx);

void lc_dilithium_ed448_ctx_zero(struct lc_dilithium_ed448_ctx *ctx);

void lc_dilithium_ed448_ctx_hash(struct lc_dilithium_ed448_ctx *ctx,
                                 const struct lc_hash *hash);

void lc_dilithium_ed448_ctx_internal(struct lc_dilithium_ed448_ctx *ctx);

void lc_dilithium_ed448_ctx_userctx(struct lc_dilithium_ed448_ctx *ctx,
                                    const uint8_t *userctx, size_t userctxlen);

void lc_dilithium_ed448_ctx_randomizer(struct lc_dilithium_ed448_ctx *ctx,
                                       const uint8_t *randomizer,
                                       size_t randomizerlen);

enum lc_dilithium_type
lc_dilithium_ed448_sk_type(const struct lc_dilithium_ed448_sk *sk);

enum lc_dilithium_type
lc_dilithium_ed448_pk_type(const struct lc_dilithium_ed448_pk *pk);

enum lc_dilithium_type
lc_dilithium_ed448_sig_type(const struct lc_dilithium_ed448_sig *sig);

LC_PURE unsigned int
lc_dilithium_ed448_sk_size(enum lc_dilithium_type dilithium_type);

LC_PURE unsigned int
lc_dilithium_ed448_pk_size(enum lc_dilithium_type dilithium_type);

LC_PURE unsigned int
lc_dilithium_ed448_sig_size(enum lc_dilithium_type dilithium_type);

int lc_dilithium_ed448_sk_load(struct lc_dilithium_ed448_sk *sk,
                               const uint8_t *dilithium_src_key,
                               size_t dilithium_src_key_len,
                               const uint8_t *ed448_src_key,
                               size_t ed448_src_key_len);

int lc_dilithium_ed448_pk_load(struct lc_dilithium_ed448_pk *pk,
                               const uint8_t *dilithium_src_key,
                               size_t dilithium_src_key_len,
                               const uint8_t *ed448_src_key,
                               size_t ed448_src_key_len);

int lc_dilithium_ed448_sig_load(struct lc_dilithium_ed448_sig *sig,
                                const uint8_t *dilithium_src_sig,
                                size_t dilithium_src_sig_len,
                                const uint8_t *ed448_src_sig,
                                size_t ed448_src_sig_len);

int lc_dilithium_ed448_sk_ptr(uint8_t **dilithium_key,
                              size_t *dilithium_key_len, uint8_t **ed448_key,
                              size_t *ed448_key_len,
                              struct lc_dilithium_ed448_sk *sk);

int lc_dilithium_ed448_pk_ptr(uint8_t **dilithium_key,
                              size_t *dilithium_key_len, uint8_t **ed448_key,
                              size_t *ed448_key_len,
                              struct lc_dilithium_ed448_pk *pk);

int lc_dilithium_ed448_sig_ptr(uint8_t **dilithium_sig,
                               size_t *dilithium_sig_len, uint8_t **ed448_sig,
                               size_t *ed448_sig_len,
                               struct lc_dilithium_ed448_sig *sig);

int lc_dilithium_ed448_keypair(struct lc_dilithium_ed448_pk *pk,
                               struct lc_dilithium_ed448_sk *sk,
                               struct lc_rng_ctx *rng_ctx,
                               enum lc_dilithium_type dilithium_type);

int lc_dilithium_ed448_sign(struct lc_dilithium_ed448_sig *sig,
                            const uint8_t *m, size_t mlen,
                            const struct lc_dilithium_ed448_sk *sk,
                            struct lc_rng_ctx *rng_ctx);

int lc_dilithium_ed448_sign_ctx(struct lc_dilithium_ed448_sig *sig,
                                struct lc_dilithium_ed448_ctx *ctx,
                                const uint8_t *m, size_t mlen,
                                const struct lc_dilithium_ed448_sk *sk,
                                struct lc_rng_ctx *rng_ctx);

int lc_dilithium_ed448_sign_init(struct lc_dilithium_ed448_ctx *ctx,
                                 const struct lc_dilithium_ed448_sk *sk);

int lc_dilithium_ed448_sign_update(struct lc_dilithium_ed448_ctx *ctx,
                                   const uint8_t *m, size_t mlen);

int lc_dilithium_ed448_sign_final(struct lc_dilithium_ed448_sig *sig,
                                  struct lc_dilithium_ed448_ctx *ctx,
                                  const struct lc_dilithium_ed448_sk *sk,
                                  struct lc_rng_ctx *rng_ctx);

int lc_dilithium_ed448_verify(const struct lc_dilithium_ed448_sig *sig,
                              const uint8_t *m, size_t mlen,
                              const struct lc_dilithium_ed448_pk *pk);

int lc_dilithium_ed448_verify_ctx(const struct lc_dilithium_ed448_sig *sig,
                                  struct lc_dilithium_ed448_ctx *ctx,
                                  const uint8_t *m, size_t mlen,
                                  const struct lc_dilithium_ed448_pk *pk);

int lc_dilithium_ed448_verify_init(struct lc_dilithium_ed448_ctx *ctx,
                                   const struct lc_dilithium_ed448_pk *pk);

int lc_dilithium_ed448_verify_update(struct lc_dilithium_ed448_ctx *ctx,
                                     const uint8_t *m, size_t mlen);

int lc_dilithium_ed448_verify_final(const struct lc_dilithium_ed448_sig *sig,
                                    struct lc_dilithium_ed448_ctx *ctx,
                                    const struct lc_dilithium_ed448_pk *pk);
 
#endif /* LC_DILITHIUM_ED448_SIG */
 
#ifdef __cplusplus
}
#endif
 
#endif /* LC_DILITHIUM_H */