Leancrypto 1.6.0
Post-Quantum Cryptographic Library
Loading...
Searching...
No Matches
lc_dilithium_87.h File Reference
#include "ext_headers.h"
#include "lc_hash.h"
#include "lc_rng.h"
#include "lc_sha3.h"
#include "lc_sha512.h"
#include "lc_ed25519.h"
#include "lc_ed448.h"
Include dependency graph for lc_dilithium_87.h:

Go to the source code of this file.

Data Structures

struct  lc_dilithium_87_sk
 Dilithium secret key. More...
struct  lc_dilithium_87_pk
 Dilithium public key. More...
struct  lc_dilithium_87_sig
 Dilithium signature. More...
struct  lc_dilithium_ctx
struct  lc_dilithium_87_ed25519_sk
 Dilithium secret key. More...
struct  lc_dilithium_87_ed25519_pk
 Dilithium public key. More...
struct  lc_dilithium_87_ed25519_sig
 Dilithium signature. More...
struct  lc_dilithium_ed25519_ctx
 Dilithium stream context. More...
struct  lc_dilithium_87_ed448_sk
 Dilithium secret key. More...
struct  lc_dilithium_87_ed448_pk
 Dilithium public key. More...
struct  lc_dilithium_87_ed448_sig
 Dilithium signature. More...
struct  lc_dilithium_ed448_ctx
 Dilithium stream context. More...

Macros

#define LC_DILITHIUM_CTX_ON_STACK(name)
 Allocate stack memory for the Dilithium stream context or additional parameter relevant for the signature operation.
#define LC_DILITHIUM_87_CTX_ON_STACK_AHAT(name)
 Allocate stack memory for the Dilithium stream context and additional parameter relevant for the signature operation.
#define LC_DILITHIUM_ED25519_SIG
#define LC_DILITHIUM_ED25519_CTX_ON_STACK(name)
 Allocate stack memory for the Dilithium-ED25519 stream context.
#define LC_DILITHIUM_ED448_SIG
#define LC_DILITHIUM_ED448_CTX_ON_STACK(name)
 Allocate stack memory for the Dilithium-ED448 stream context.

Functions

static void lc_dilithium_87_ctx_zero (struct lc_dilithium_ctx *ctx)
 Zeroize Dilithium context allocated with LC_DILITHIUM_CTX_ON_STACK lc_dilithium_ed25519_alloc.
int lc_dilithium_87_ctx_alloc (struct lc_dilithium_ctx **ctx)
 Allocate Dilithium stream context on heap.
int lc_dilithium_87_ctx_alloc_ahat (struct lc_dilithium_ctx **ctx)
 Allocate Dilithium stream context on heap including additional parameter relevant for the signature operation.
void lc_dilithium_87_ctx_zero_free (struct lc_dilithium_ctx *ctx)
 Zeroize and free Dilithium stream context.
static LC_PURE unsigned int lc_dilithium_87_sk_size (void)
 Return the size of the Dilithium secret key.
static LC_PURE unsigned int lc_dilithium_87_pk_size (void)
 Return the size of the Dilithium public key.
static LC_PURE unsigned int lc_dilithium_87_sig_size (void)
 Return the size of the Dilithium signature.
int lc_dilithium_87_keypair (struct lc_dilithium_87_pk *pk, struct lc_dilithium_87_sk *sk, struct lc_rng_ctx *rng_ctx)
 Generates Dilithium public and private key.
int lc_dilithium_87_keypair_from_seed (struct lc_dilithium_87_pk *pk, struct lc_dilithium_87_sk *sk, const uint8_t *seed, size_t seedlen)
 Generates Dilithium public and private key from a given seed.
int lc_dilithium_87_sign (struct lc_dilithium_87_sig *sig, const uint8_t *m, size_t mlen, const struct lc_dilithium_87_sk *sk, struct lc_rng_ctx *rng_ctx)
 Computes ML-DSA signature in one shot.
int lc_dilithium_87_sign_ctx (struct lc_dilithium_87_sig *sig, struct lc_dilithium_ctx *ctx, const uint8_t *m, size_t mlen, const struct lc_dilithium_87_sk *sk, struct lc_rng_ctx *rng_ctx)
 Computes signature with Dilithium context in one shot.
int lc_dilithium_87_sign_init (struct lc_dilithium_ctx *ctx, const struct lc_dilithium_87_sk *sk)
 Initializes a signature operation.
int lc_dilithium_87_sign_update (struct lc_dilithium_ctx *ctx, const uint8_t *m, size_t mlen)
 Add more data to an already initialized signature state.
int lc_dilithium_87_sign_final (struct lc_dilithium_87_sig *sig, struct lc_dilithium_ctx *ctx, const struct lc_dilithium_87_sk *sk, struct lc_rng_ctx *rng_ctx)
 Computes signature.
int lc_dilithium_87_verify (const struct lc_dilithium_87_sig *sig, const uint8_t *m, size_t mlen, const struct lc_dilithium_87_pk *pk)
 Verifies ML-DSA signature in one shot.
int lc_dilithium_87_verify_ctx (const struct lc_dilithium_87_sig *sig, struct lc_dilithium_ctx *ctx, const uint8_t *m, size_t mlen, const struct lc_dilithium_87_pk *pk)
 Verifies signature with Dilithium context in one shot.
int lc_dilithium_87_verify_init (struct lc_dilithium_ctx *ctx, const struct lc_dilithium_87_pk *pk)
 Initializes a signature verification operation.
int lc_dilithium_87_verify_update (struct lc_dilithium_ctx *ctx, const uint8_t *m, size_t mlen)
 Add more data to an already initialized signature state.
int lc_dilithium_87_verify_final (const struct lc_dilithium_87_sig *sig, struct lc_dilithium_ctx *ctx, const struct lc_dilithium_87_pk *pk)
 Verifies signature.
static void lc_dilithium_87_ed25519_ctx_zero (struct lc_dilithium_ed25519_ctx *ctx)
 Zeroize Dilithium-ED25519 context allocated with LC_DILITHIUM_ED25519_CTX_ON_STACK lc_dilithium_ed25519_alloc.
int lc_dilithium_87_ed25519_ctx_alloc (struct lc_dilithium_ed25519_ctx **ctx)
 Allocate Dilithium-ED25519 stream context on heap.
void lc_dilithium_87_ed25519_ctx_zero_free (struct lc_dilithium_ed25519_ctx *ctx)
 Zeroize and free Dilithium-ED25519 stream context.
int lc_dilithium_87_ed25519_keypair (struct lc_dilithium_87_ed25519_pk *pk, struct lc_dilithium_87_ed25519_sk *sk, struct lc_rng_ctx *rng_ctx)
 Generates Dilithium public and private key.
int lc_dilithium_87_ed25519_sign (struct lc_dilithium_87_ed25519_sig *sig, const uint8_t *m, size_t mlen, const struct lc_dilithium_87_ed25519_sk *sk, struct lc_rng_ctx *rng_ctx)
 Computes signature in one shot.
int lc_dilithium_87_ed25519_sign_ctx (struct lc_dilithium_87_ed25519_sig *sig, struct lc_dilithium_ed25519_ctx *ctx, const uint8_t *m, size_t mlen, const struct lc_dilithium_87_ed25519_sk *sk, struct lc_rng_ctx *rng_ctx)
 Computes signature with Dilithium context in one shot.
int lc_dilithium_87_ed25519_sign_init (struct lc_dilithium_ed25519_ctx *ctx, const struct lc_dilithium_87_ed25519_sk *sk)
int lc_dilithium_87_ed25519_sign_update (struct lc_dilithium_ed25519_ctx *ctx, const uint8_t *m, size_t mlen)
int lc_dilithium_87_ed25519_sign_final (struct lc_dilithium_87_ed25519_sig *sig, struct lc_dilithium_ed25519_ctx *ctx, const struct lc_dilithium_87_ed25519_sk *sk, struct lc_rng_ctx *rng_ctx)
int lc_dilithium_87_ed25519_verify (const struct lc_dilithium_87_ed25519_sig *sig, const uint8_t *m, size_t mlen, const struct lc_dilithium_87_ed25519_pk *pk)
 Verifies signature in one shot.
int lc_dilithium_87_ed25519_verify_ctx (const struct lc_dilithium_87_ed25519_sig *sig, struct lc_dilithium_ed25519_ctx *ctx, const uint8_t *m, size_t mlen, const struct lc_dilithium_87_ed25519_pk *pk)
 Verifies signature in one shot with Dilithium context.
int lc_dilithium_87_ed25519_verify_init (struct lc_dilithium_ed25519_ctx *ctx, const struct lc_dilithium_87_ed25519_pk *pk)
int lc_dilithium_87_ed25519_verify_update (struct lc_dilithium_ed25519_ctx *ctx, const uint8_t *m, size_t mlen)
int lc_dilithium_87_ed25519_verify_final (const struct lc_dilithium_87_ed25519_sig *sig, struct lc_dilithium_ed25519_ctx *ctx, const struct lc_dilithium_87_ed25519_pk *pk)
static void lc_dilithium_87_ed448_ctx_zero (struct lc_dilithium_ed448_ctx *ctx)
 Zeroize Dilithium-ED448 context allocated with LC_DILITHIUM_ED448_CTX_ON_STACK lc_dilithium_ed448_alloc.
int lc_dilithium_87_ed448_ctx_alloc (struct lc_dilithium_ed448_ctx **ctx)
 Allocate Dilithium-ED448 stream context on heap.
void lc_dilithium_87_ed448_ctx_zero_free (struct lc_dilithium_ed448_ctx *ctx)
 Zeroize and free Dilithium-ED448 stream context.
int lc_dilithium_87_ed448_keypair (struct lc_dilithium_87_ed448_pk *pk, struct lc_dilithium_87_ed448_sk *sk, struct lc_rng_ctx *rng_ctx)
 Generates Dilithium public and private key.
int lc_dilithium_87_ed448_sign (struct lc_dilithium_87_ed448_sig *sig, const uint8_t *m, size_t mlen, const struct lc_dilithium_87_ed448_sk *sk, struct lc_rng_ctx *rng_ctx)
 Computes signature in one shot.
int lc_dilithium_87_ed448_sign_ctx (struct lc_dilithium_87_ed448_sig *sig, struct lc_dilithium_ed448_ctx *ctx, const uint8_t *m, size_t mlen, const struct lc_dilithium_87_ed448_sk *sk, struct lc_rng_ctx *rng_ctx)
 Computes signature with Dilithium context in one shot.
int lc_dilithium_87_ed448_sign_init (struct lc_dilithium_ed448_ctx *ctx, const struct lc_dilithium_87_ed448_sk *sk)
int lc_dilithium_87_ed448_sign_update (struct lc_dilithium_ed448_ctx *ctx, const uint8_t *m, size_t mlen)
int lc_dilithium_87_ed448_sign_final (struct lc_dilithium_87_ed448_sig *sig, struct lc_dilithium_ed448_ctx *ctx, const struct lc_dilithium_87_ed448_sk *sk, struct lc_rng_ctx *rng_ctx)
int lc_dilithium_87_ed448_verify (const struct lc_dilithium_87_ed448_sig *sig, const uint8_t *m, size_t mlen, const struct lc_dilithium_87_ed448_pk *pk)
 Verifies signature in one shot.
int lc_dilithium_87_ed448_verify_ctx (const struct lc_dilithium_87_ed448_sig *sig, struct lc_dilithium_ed448_ctx *ctx, const uint8_t *m, size_t mlen, const struct lc_dilithium_87_ed448_pk *pk)
 Verifies signature in one shot with Dilithium context.
int lc_dilithium_87_ed448_verify_init (struct lc_dilithium_ed448_ctx *ctx, const struct lc_dilithium_87_ed448_pk *pk)
int lc_dilithium_87_ed448_verify_update (struct lc_dilithium_ed448_ctx *ctx, const uint8_t *m, size_t mlen)
int lc_dilithium_87_ed448_verify_final (const struct lc_dilithium_87_ed448_sig *sig, struct lc_dilithium_ed448_ctx *ctx, const struct lc_dilithium_87_ed448_pk *pk)

Data Structure Documentation

◆ lc_dilithium_87_sk

struct lc_dilithium_87_sk

Dilithium secret key.

Definition at line 152 of file lc_dilithium_87.h.

Data Fields
uint8_t sk[LC_DILITHIUM_SECRETKEYBYTES]

◆ lc_dilithium_87_pk

struct lc_dilithium_87_pk

Dilithium public key.

Definition at line 159 of file lc_dilithium_87.h.

Data Fields
uint8_t pk[LC_DILITHIUM_PUBLICKEYBYTES]

◆ lc_dilithium_87_sig

struct lc_dilithium_87_sig

Dilithium signature.

Definition at line 166 of file lc_dilithium_87.h.

Data Fields
uint8_t sig[LC_DILITHIUM_CRYPTO_BYTES]

◆ lc_dilithium_ctx

struct lc_dilithium_ctx

Definition at line 171 of file lc_dilithium_44.h.

Data Fields
void * ahat Pointer to the AHat buffer. This can be provided by the caller or it must be NULL otherwise.
Note
Use LC_DILITHIUM_CTX_ON_STACK_AHAT to provide memory for storing AHat in the caller context and thus make the signature operation much faster starting with the 2nd use of the key (pair).
unsigned int ahat_expanded:1 Was aHat already filled? This is used and set internally.
unsigned short ahat_size
struct lc_hash_ctx dilithium_hash_ctx Hash context used internally to the library - it should not be touched by the user.
const struct lc_hash * dilithium_prehash_type When using HashML-DSA, set the hash reference used for the hash operation. Allowed values are lc_sha256, lc_sha512, lc_sha3_256, lc_sha3_384, lc_sha3_512, lc_shake128 and lc_shake256. Note, the actual message digest operation can be performed external to leancrypto. This parameter only shall indicate the used hash operation.
Note
Use lc_dilithium_ctx_hash or lc_dilithium_ed25519_ctx_hash to set this value.
const uint8_t * external_mu Pointer to the external mu.

If set, the signature operation will use the provided mu instead of the message. In this case, the message pointer to the signature generation or verification can be NULL.

size_t external_mu_len
unsigned int ml_dsa_internal:1 When set to true, only the ML-DSA.Sign_internal or ML-DSA.Verify_internal are performed (see FIPS 204 chapter 6). Otherwise the ML-DSA.Sign / ML-DSA.Verify (see FIPS chapter 5) is applied.
Note
Use lc_dilithium_ctx_internal or lc_dilithium_ed25519_ctx_internal to set this value.
Warning
Only set this value to true if you exactly know what you are doing!.
uint8_t nist_category NIST category required for composite signatures.

The domain separation logic depends on the selection of the right OID for the "Domain" data.

const uint8_t * randomizer Pointer to the randomizer.

This is used for the Composite signature: For the discussion of the randomizer, see https://lamps-wg.github.io/draft-composite-sigs/draft-ietf-lamps-pq-composite-sigs.html

size_t randomizerlen
uint8_t shake_state[LC_SHA3_STATE_SIZE_ALIGN(LC_SHA3_256_CTX_SIZE)] State memory of the hash context used internally to the library - it should not be touched by the user.
const uint8_t * userctx buffer with a caller-specified context string
Note
Use lc_dilithium_ctx_userctx or lc_dilithium_ed25519_ctx_userctx to set this value.
size_t userctxlen length of the user context (allowed range between 0 and 255 bytes)
Note
Use lc_dilithium_ctx_userctx or lc_dilithium_ed25519_ctx_userctx to set this value.

◆ lc_dilithium_87_ed25519_sk

struct lc_dilithium_87_ed25519_sk

Dilithium secret key.

Definition at line 685 of file lc_dilithium_87.h.

Collaboration diagram for lc_dilithium_87_ed25519_sk:
Data Fields
struct lc_dilithium_87_sk sk
struct lc_ed25519_sk sk_ed25519

◆ lc_dilithium_87_ed25519_pk

struct lc_dilithium_87_ed25519_pk

Dilithium public key.

Definition at line 693 of file lc_dilithium_87.h.

Collaboration diagram for lc_dilithium_87_ed25519_pk:
Data Fields
struct lc_dilithium_87_pk pk
struct lc_ed25519_pk pk_ed25519

◆ lc_dilithium_87_ed25519_sig

struct lc_dilithium_87_ed25519_sig

Dilithium signature.

Definition at line 701 of file lc_dilithium_87.h.

Collaboration diagram for lc_dilithium_87_ed25519_sig:
Data Fields
struct lc_dilithium_87_sig sig
struct lc_ed25519_sig sig_ed25519

◆ lc_dilithium_ed25519_ctx

struct lc_dilithium_ed25519_ctx

Dilithium stream context.

This structure is used for the init/update/final operation of the Dilithium-ED25519 hybrid.

Definition at line 713 of file lc_dilithium_44.h.

Collaboration diagram for lc_dilithium_ed25519_ctx:
Data Fields
struct lc_dilithium_ctx dilithium_ctx

◆ lc_dilithium_87_ed448_sk

struct lc_dilithium_87_ed448_sk

Dilithium secret key.

Definition at line 901 of file lc_dilithium_87.h.

Collaboration diagram for lc_dilithium_87_ed448_sk:
Data Fields
struct lc_dilithium_87_sk sk
struct lc_ed448_sk sk_ed448

◆ lc_dilithium_87_ed448_pk

struct lc_dilithium_87_ed448_pk

Dilithium public key.

Definition at line 909 of file lc_dilithium_87.h.

Collaboration diagram for lc_dilithium_87_ed448_pk:
Data Fields
struct lc_dilithium_87_pk pk
struct lc_ed448_pk pk_ed448

◆ lc_dilithium_87_ed448_sig

struct lc_dilithium_87_ed448_sig

Dilithium signature.

Definition at line 917 of file lc_dilithium_87.h.

Collaboration diagram for lc_dilithium_87_ed448_sig:
Data Fields
struct lc_dilithium_87_sig sig
struct lc_ed448_sig sig_ed448

◆ lc_dilithium_ed448_ctx

struct lc_dilithium_ed448_ctx

Dilithium stream context.

This structure is used for the init/update/final operation of the Dilithium-ED448 hybrid.

Definition at line 929 of file lc_dilithium_44.h.

Collaboration diagram for lc_dilithium_ed448_ctx:
Data Fields
struct lc_dilithium_ctx dilithium_ctx

Macro Definition Documentation

◆ LC_DILITHIUM_87_CTX_ON_STACK_AHAT

#define LC_DILITHIUM_87_CTX_ON_STACK_AHAT ( name)
Value:
_Pragma("GCC diagnostic push") _Pragma( \
"GCC diagnostic ignored \"-Wdeclaration-after-statement\"") \
name##_ctx_buf, LC_DILITHIUM_CTX_SIZE + \
LC_DILITHIUM_87_AHAT_PAD + LC_DILITHIUM_87_AHAT_SIZE, \
LC_HASH_COMMON_ALIGNMENT); \
struct lc_dilithium_ctx *name = \
(struct lc_dilithium_ctx *)name##_ctx_buf; \
LC_DILITHIUM_SET_CTX(name); \
name->ahat = (uint8_t *)name + LC_DILITHIUM_CTX_SIZE + \
LC_DILITHIUM_87_AHAT_PAD; \
name->ahat_expanded = 0; \
name->ahat_size = LC_DILITHIUM_87_AHAT_SIZE; \
_Pragma("GCC diagnostic pop")
#define LC_ALIGNED_BUFFER(name, size, alignment)
Allocate aligned stack memory.

Allocate stack memory for the Dilithium stream context and additional parameter relevant for the signature operation.

In addition, the memory buffer returned by this allocation contains the space for an expanded representation of the public key which is required in both, signature generation and verification. When using this memory, the first signature operation expands the key and any subsequent operation using this context will re-use the expanded key which improves performance of the signature operation significantly.

As the same expanded structure is used for signature generation and verification and the structure can be expanded by either operation, it is perfectly legal to use one context for both operations as the expanded key can (a) be generated from either the public or the secret key and (b) it applies to both operations and (c) is identical irrespective it was generated from the public or secret key.

Note
: ML-DSA AVX2 signature operation uses a completely different algorithm which does not use a pre-pcomputed expanded key. Thus, if you know you have AVX2 support, you may not need this larger buffer and you can use LC_DILITHIUM_CTX_ON_STACK instead.
: The expanded representation only uses public key data. Even when deriving the expanded representation from a secret key, this data is only obtained from a part that is considered public. Thus, this memory does not require special protections. See FIPS 204 section 3.6.3 on the properties and handling requirements of the  matrix. Further, see the FIPS 204 ML-DSA.Sign_internal and ML-DSA.Verify_internal algorithm specification on how this  matrix is generated and that the input to the generation is public data.
Warning
: One instance of the expanded key representation can only ever apply to one given key (pair). If you want to reuse the context with multiple keys, you MUST invalidate the potentially present expanded key representation. Such invalidation is invoked with the method lc_dilithium_ctx_drop_ahat. Only after this invalidation you can use the context with a different key.
Parameters
[in]nameName of the stack variable

Definition at line 375 of file lc_dilithium_87.h.

◆ LC_DILITHIUM_CTX_ON_STACK

#define LC_DILITHIUM_CTX_ON_STACK ( name)
Value:
_Pragma("GCC diagnostic push") _Pragma( \
"GCC diagnostic ignored \"-Wdeclaration-after-statement\"") \
name##_ctx_buf, LC_DILITHIUM_CTX_SIZE, \
LC_HASH_COMMON_ALIGNMENT); \
struct lc_dilithium_ctx *name = \
(struct lc_dilithium_ctx *)name##_ctx_buf; \
LC_DILITHIUM_SET_CTX(name); \
_Pragma("GCC diagnostic pop")

Allocate stack memory for the Dilithium stream context or additional parameter relevant for the signature operation.

Parameters
[in]nameName of the stack variable

Definition at line 323 of file lc_dilithium_87.h.

◆ LC_DILITHIUM_ED25519_CTX_ON_STACK

#define LC_DILITHIUM_ED25519_CTX_ON_STACK ( name)
Value:
_Pragma("GCC diagnostic push") _Pragma( \
"GCC diagnostic ignored \"-Wdeclaration-after-statement\"") \
name##_ctx_buf, LC_DILITHIUM_ED25519_CTX_SIZE, \
LC_HASH_COMMON_ALIGNMENT); \
struct lc_dilithium_ed25519_ctx *name = \
(struct lc_dilithium_ed25519_ctx *)name##_ctx_buf; \
LC_DILITHIUM_SET_CTX(&(name)->dilithium_ctx); \
_Pragma("GCC diagnostic pop")

Allocate stack memory for the Dilithium-ED25519 stream context.

Parameters
[in]nameName of the stack variable

Definition at line 731 of file lc_dilithium_87.h.

◆ LC_DILITHIUM_ED25519_SIG

#define LC_DILITHIUM_ED25519_SIG

Definition at line 677 of file lc_dilithium_87.h.

◆ LC_DILITHIUM_ED448_CTX_ON_STACK

#define LC_DILITHIUM_ED448_CTX_ON_STACK ( name)
Value:
_Pragma("GCC diagnostic push") _Pragma( \
"GCC diagnostic ignored \"-Wdeclaration-after-statement\"") \
name##_ctx_buf, LC_DILITHIUM_ED448_CTX_SIZE, \
LC_HASH_COMMON_ALIGNMENT); \
struct lc_dilithium_ed448_ctx *name = \
(struct lc_dilithium_ed448_ctx *)name##_ctx_buf; \
LC_DILITHIUM_SET_CTX(&(name)->dilithium_ctx); \
_Pragma("GCC diagnostic pop")

Allocate stack memory for the Dilithium-ED448 stream context.

Parameters
[in]nameName of the stack variable

Definition at line 947 of file lc_dilithium_87.h.

◆ LC_DILITHIUM_ED448_SIG

#define LC_DILITHIUM_ED448_SIG

Definition at line 893 of file lc_dilithium_87.h.

Function Documentation

◆ lc_dilithium_87_ctx_alloc()

int lc_dilithium_87_ctx_alloc ( struct lc_dilithium_ctx ** ctx)

Allocate Dilithium stream context on heap.

Parameters
[out]ctxAllocated Dilithium stream context
Returns
: 0 on success, < 0 on error

◆ lc_dilithium_87_ctx_alloc_ahat()

int lc_dilithium_87_ctx_alloc_ahat ( struct lc_dilithium_ctx ** ctx)

Allocate Dilithium stream context on heap including additional parameter relevant for the signature operation.

Note
See LC_DILITHIUM_87_CTX_ON_STACK_AHAT for details.
Parameters
[out]ctxAllocated Dilithium stream context
Returns
: 0 on success, < 0 on error

◆ lc_dilithium_87_ctx_zero()

void lc_dilithium_87_ctx_zero ( struct lc_dilithium_ctx * ctx)
inlinestatic

Zeroize Dilithium context allocated with LC_DILITHIUM_CTX_ON_STACK lc_dilithium_ed25519_alloc.

Parameters
[in]ctxDilithium context to be zeroized

Definition at line 397 of file lc_dilithium_87.h.

◆ lc_dilithium_87_ctx_zero_free()

void lc_dilithium_87_ctx_zero_free ( struct lc_dilithium_ctx * ctx)

Zeroize and free Dilithium stream context.

Parameters
[in]ctxDilithium stream context to be zeroized and freed

◆ lc_dilithium_87_ed25519_ctx_alloc()

int lc_dilithium_87_ed25519_ctx_alloc ( struct lc_dilithium_ed25519_ctx ** ctx)

Allocate Dilithium-ED25519 stream context on heap.

Parameters
[out]ctxAllocated Dilithium-ED25519 stream context
Returns
: 0 on success, < 0 on error

◆ lc_dilithium_87_ed25519_ctx_zero()

void lc_dilithium_87_ed25519_ctx_zero ( struct lc_dilithium_ed25519_ctx * ctx)
inlinestatic

Zeroize Dilithium-ED25519 context allocated with LC_DILITHIUM_ED25519_CTX_ON_STACK lc_dilithium_ed25519_alloc.

Parameters
[in]ctxDilithium-ED25519 context to be zeroized

Definition at line 749 of file lc_dilithium_87.h.

◆ lc_dilithium_87_ed25519_ctx_zero_free()

void lc_dilithium_87_ed25519_ctx_zero_free ( struct lc_dilithium_ed25519_ctx * ctx)

Zeroize and free Dilithium-ED25519 stream context.

Parameters
[in]ctxDilithium-ED25519 stream context to be zeroized and freed

◆ lc_dilithium_87_ed25519_keypair()

int lc_dilithium_87_ed25519_keypair ( struct lc_dilithium_87_ed25519_pk * pk,
struct lc_dilithium_87_ed25519_sk * sk,
struct lc_rng_ctx * rng_ctx )

Generates Dilithium public and private key.

Parameters
[out]pkpointer to allocated output public key
[out]skpointer to allocated output private key
[in]rng_ctxpointer to seeded random number generator context
Returns
0 (success) or < 0 on error

◆ lc_dilithium_87_ed25519_sign()

int lc_dilithium_87_ed25519_sign ( struct lc_dilithium_87_ed25519_sig * sig,
const uint8_t * m,
size_t mlen,
const struct lc_dilithium_87_ed25519_sk * sk,
struct lc_rng_ctx * rng_ctx )

Computes signature in one shot.

Parameters
[out]sigpointer to output signature
[in]mpointer to message to be signed
[in]mlenlength of message
[in]skpointer to bit-packed secret key
[in]rng_ctxpointer to seeded random number generator context - when pointer is non-NULL, perform a randomized signing. Otherwise use deterministic signing.
Returns
0 (success) or < 0 on error

◆ lc_dilithium_87_ed25519_sign_ctx()

int lc_dilithium_87_ed25519_sign_ctx ( struct lc_dilithium_87_ed25519_sig * sig,
struct lc_dilithium_ed25519_ctx * ctx,
const uint8_t * m,
size_t mlen,
const struct lc_dilithium_87_ed25519_sk * sk,
struct lc_rng_ctx * rng_ctx )

Computes signature with Dilithium context in one shot.

This API allows the caller to provide an arbitrary context buffer which is hashed together with the message to form the message digest to be signed.

Parameters
[out]sigpointer to output signature
[in]ctxreference to the allocated Dilithium context handle
[in]mpointer to message to be signed
[in]mlenlength of message
[in]skpointer to bit-packed secret key
[in]rng_ctxpointer to seeded random number generator context - when pointer is non-NULL, perform a randomized signing. Otherwise use deterministic signing.
Returns
0 (success) or < 0 on error

◆ lc_dilithium_87_ed25519_sign_final()

int lc_dilithium_87_ed25519_sign_final ( struct lc_dilithium_87_ed25519_sig * sig,
struct lc_dilithium_ed25519_ctx * ctx,
const struct lc_dilithium_87_ed25519_sk * sk,
struct lc_rng_ctx * rng_ctx )

◆ lc_dilithium_87_ed25519_sign_init()

int lc_dilithium_87_ed25519_sign_init ( struct lc_dilithium_ed25519_ctx * ctx,
const struct lc_dilithium_87_ed25519_sk * sk )

◆ lc_dilithium_87_ed25519_sign_update()

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

◆ lc_dilithium_87_ed25519_verify()

int lc_dilithium_87_ed25519_verify ( const struct lc_dilithium_87_ed25519_sig * sig,
const uint8_t * m,
size_t mlen,
const struct lc_dilithium_87_ed25519_pk * pk )

Verifies signature in one shot.

Parameters
[in]sigpointer to input signature
[in]mpointer to message
[in]mlenlength of message
[in]pkpointer to bit-packed public key
Returns
0 if signature could be verified correctly and -EBADMSG when signature cannot be verified, < 0 on other errors

◆ lc_dilithium_87_ed25519_verify_ctx()

int lc_dilithium_87_ed25519_verify_ctx ( const struct lc_dilithium_87_ed25519_sig * sig,
struct lc_dilithium_ed25519_ctx * ctx,
const uint8_t * m,
size_t mlen,
const struct lc_dilithium_87_ed25519_pk * pk )

Verifies signature in one shot with Dilithium context.

This API allows the caller to provide an arbitrary context buffer which is hashed together with the message to form the message digest to be signed.

Parameters
[in]sigpointer to input signature
[in]ctxreference to the allocated Dilithium context handle
[in]mpointer to message
[in]mlenlength of message
[in]pkpointer to bit-packed public key
Returns
0 if signature could be verified correctly and -EBADMSG when signature cannot be verified, < 0 on other errors

◆ lc_dilithium_87_ed25519_verify_final()

int lc_dilithium_87_ed25519_verify_final ( const struct lc_dilithium_87_ed25519_sig * sig,
struct lc_dilithium_ed25519_ctx * ctx,
const struct lc_dilithium_87_ed25519_pk * pk )

◆ lc_dilithium_87_ed25519_verify_init()

int lc_dilithium_87_ed25519_verify_init ( struct lc_dilithium_ed25519_ctx * ctx,
const struct lc_dilithium_87_ed25519_pk * pk )

◆ lc_dilithium_87_ed25519_verify_update()

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

◆ lc_dilithium_87_ed448_ctx_alloc()

int lc_dilithium_87_ed448_ctx_alloc ( struct lc_dilithium_ed448_ctx ** ctx)

Allocate Dilithium-ED448 stream context on heap.

Parameters
[out]ctxAllocated Dilithium-ED448 stream context
Returns
: 0 on success, < 0 on error

◆ lc_dilithium_87_ed448_ctx_zero()

void lc_dilithium_87_ed448_ctx_zero ( struct lc_dilithium_ed448_ctx * ctx)
inlinestatic

Zeroize Dilithium-ED448 context allocated with LC_DILITHIUM_ED448_CTX_ON_STACK lc_dilithium_ed448_alloc.

Parameters
[in]ctxDilithium-ED448 context to be zeroized

Definition at line 965 of file lc_dilithium_87.h.

◆ lc_dilithium_87_ed448_ctx_zero_free()

void lc_dilithium_87_ed448_ctx_zero_free ( struct lc_dilithium_ed448_ctx * ctx)

Zeroize and free Dilithium-ED448 stream context.

Parameters
[in]ctxDilithium-ED448 stream context to be zeroized and freed

◆ lc_dilithium_87_ed448_keypair()

int lc_dilithium_87_ed448_keypair ( struct lc_dilithium_87_ed448_pk * pk,
struct lc_dilithium_87_ed448_sk * sk,
struct lc_rng_ctx * rng_ctx )

Generates Dilithium public and private key.

Parameters
[out]pkpointer to allocated output public key
[out]skpointer to allocated output private key
[in]rng_ctxpointer to seeded random number generator context
Returns
0 (success) or < 0 on error

◆ lc_dilithium_87_ed448_sign()

int lc_dilithium_87_ed448_sign ( struct lc_dilithium_87_ed448_sig * sig,
const uint8_t * m,
size_t mlen,
const struct lc_dilithium_87_ed448_sk * sk,
struct lc_rng_ctx * rng_ctx )

Computes signature in one shot.

Parameters
[out]sigpointer to output signature
[in]mpointer to message to be signed
[in]mlenlength of message
[in]skpointer to bit-packed secret key
[in]rng_ctxpointer to seeded random number generator context - when pointer is non-NULL, perform a randomized signing. Otherwise use deterministic signing.
Returns
0 (success) or < 0 on error

◆ lc_dilithium_87_ed448_sign_ctx()

int lc_dilithium_87_ed448_sign_ctx ( struct lc_dilithium_87_ed448_sig * sig,
struct lc_dilithium_ed448_ctx * ctx,
const uint8_t * m,
size_t mlen,
const struct lc_dilithium_87_ed448_sk * sk,
struct lc_rng_ctx * rng_ctx )

Computes signature with Dilithium context in one shot.

This API allows the caller to provide an arbitrary context buffer which is hashed together with the message to form the message digest to be signed.

Parameters
[out]sigpointer to output signature
[in]ctxreference to the allocated Dilithium context handle
[in]mpointer to message to be signed
[in]mlenlength of message
[in]skpointer to bit-packed secret key
[in]rng_ctxpointer to seeded random number generator context - when pointer is non-NULL, perform a randomized signing. Otherwise use deterministic signing.
Returns
0 (success) or < 0 on error

◆ lc_dilithium_87_ed448_sign_final()

int lc_dilithium_87_ed448_sign_final ( struct lc_dilithium_87_ed448_sig * sig,
struct lc_dilithium_ed448_ctx * ctx,
const struct lc_dilithium_87_ed448_sk * sk,
struct lc_rng_ctx * rng_ctx )

◆ lc_dilithium_87_ed448_sign_init()

int lc_dilithium_87_ed448_sign_init ( struct lc_dilithium_ed448_ctx * ctx,
const struct lc_dilithium_87_ed448_sk * sk )

◆ lc_dilithium_87_ed448_sign_update()

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

◆ lc_dilithium_87_ed448_verify()

int lc_dilithium_87_ed448_verify ( const struct lc_dilithium_87_ed448_sig * sig,
const uint8_t * m,
size_t mlen,
const struct lc_dilithium_87_ed448_pk * pk )

Verifies signature in one shot.

Parameters
[in]sigpointer to input signature
[in]mpointer to message
[in]mlenlength of message
[in]pkpointer to bit-packed public key
Returns
0 if signature could be verified correctly and -EBADMSG when signature cannot be verified, < 0 on other errors

◆ lc_dilithium_87_ed448_verify_ctx()

int lc_dilithium_87_ed448_verify_ctx ( const struct lc_dilithium_87_ed448_sig * sig,
struct lc_dilithium_ed448_ctx * ctx,
const uint8_t * m,
size_t mlen,
const struct lc_dilithium_87_ed448_pk * pk )

Verifies signature in one shot with Dilithium context.

This API allows the caller to provide an arbitrary context buffer which is hashed together with the message to form the message digest to be signed.

Parameters
[in]sigpointer to input signature
[in]ctxreference to the allocated Dilithium context handle
[in]mpointer to message
[in]mlenlength of message
[in]pkpointer to bit-packed public key
Returns
0 if signature could be verified correctly and -EBADMSG when signature cannot be verified, < 0 on other errors

◆ lc_dilithium_87_ed448_verify_final()

int lc_dilithium_87_ed448_verify_final ( const struct lc_dilithium_87_ed448_sig * sig,
struct lc_dilithium_ed448_ctx * ctx,
const struct lc_dilithium_87_ed448_pk * pk )

◆ lc_dilithium_87_ed448_verify_init()

int lc_dilithium_87_ed448_verify_init ( struct lc_dilithium_ed448_ctx * ctx,
const struct lc_dilithium_87_ed448_pk * pk )

◆ lc_dilithium_87_ed448_verify_update()

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

◆ lc_dilithium_87_keypair()

int lc_dilithium_87_keypair ( struct lc_dilithium_87_pk * pk,
struct lc_dilithium_87_sk * sk,
struct lc_rng_ctx * rng_ctx )

Generates Dilithium public and private key.

Parameters
[out]pkpointer to allocated output public key
[out]skpointer to allocated output private key
[in]rng_ctxpointer to seeded random number generator context
Returns
0 (success) or < 0 on error

◆ lc_dilithium_87_keypair_from_seed()

int lc_dilithium_87_keypair_from_seed ( struct lc_dilithium_87_pk * pk,
struct lc_dilithium_87_sk * sk,
const uint8_t * seed,
size_t seedlen )

Generates Dilithium public and private key from a given seed.

The idea of the function is the allowance of FIPS 204 to maintain the seed used to generate a key pair in lieu of maintaining a private key or the key pair (which used much more memory). The seed must be treated equally sensitive as a private key.

The seed is generated by simply obtaining 32 bytes from a properly seeded DRNG, i.e. the same way as a symmetric key would be generated.

Parameters
[out]pkpointer to allocated output public key
[out]skpointer to allocated output private key
[in]seedbuffer with the seed data which must be exactly 32 bytes in size
[in]seedlenlength of the seed buffer
Returns
0 (success) or < 0 on error

◆ lc_dilithium_87_pk_size()

LC_PURE unsigned int lc_dilithium_87_pk_size ( void )
inlinestatic

Return the size of the Dilithium public key.

Definition at line 449 of file lc_dilithium_87.h.

◆ lc_dilithium_87_sig_size()

LC_PURE unsigned int lc_dilithium_87_sig_size ( void )
inlinestatic

Return the size of the Dilithium signature.

Definition at line 458 of file lc_dilithium_87.h.

◆ lc_dilithium_87_sign()

int lc_dilithium_87_sign ( struct lc_dilithium_87_sig * sig,
const uint8_t * m,
size_t mlen,
const struct lc_dilithium_87_sk * sk,
struct lc_rng_ctx * rng_ctx )

Computes ML-DSA signature in one shot.

Parameters
[out]sigpointer to output signature
[in]mpointer to message to be signed
[in]mlenlength of message
[in]skpointer to bit-packed secret key
[in]rng_ctxpointer to seeded random number generator context - when pointer is non-NULL, perform a randomized signing. Otherwise use deterministic signing.
Returns
0 (success) or < 0 on error

◆ lc_dilithium_87_sign_ctx()

int lc_dilithium_87_sign_ctx ( struct lc_dilithium_87_sig * sig,
struct lc_dilithium_ctx * ctx,
const uint8_t * m,
size_t mlen,
const struct lc_dilithium_87_sk * sk,
struct lc_rng_ctx * rng_ctx )

Computes signature with Dilithium context in one shot.

This API allows the caller to provide an arbitrary context buffer which is hashed together with the message to form the message digest to be signed.

Parameters
[out]sigpointer to output signature
[in]ctxreference to the allocated Dilithium context handle
[in]mpointer to message to be signed
[in]mlenlength of message
[in]skpointer to bit-packed secret key
[in]rng_ctxpointer to seeded random number generator context - when pointer is non-NULL, perform a randomized signing. Otherwise use deterministic signing.
Returns
0 (success) or < 0 on error

◆ lc_dilithium_87_sign_final()

int lc_dilithium_87_sign_final ( struct lc_dilithium_87_sig * sig,
struct lc_dilithium_ctx * ctx,
const struct lc_dilithium_87_sk * sk,
struct lc_rng_ctx * rng_ctx )

Computes signature.

Parameters
[out]sigpointer to output signature
[in]ctxpointer to Dilithium context that was initialized with lc_dilithium_sign_init and filled with lc_dilithium_sign_update
[in]skpointer to bit-packed secret key
[in]rng_ctxpointer to seeded random number generator context - when pointer is non-NULL, perform a randomized signing. Otherwise use deterministic signing.
Returns
0 (success) or < 0 on error

◆ lc_dilithium_87_sign_init()

int lc_dilithium_87_sign_init ( struct lc_dilithium_ctx * ctx,
const struct lc_dilithium_87_sk * sk )

Initializes a signature operation.

This call is intended to support messages that are located in non-contiguous places and even becomes available at different times. This call is to be used together with the lc_dilithium_sign_update and lc_dilithium_sign_final.

Parameters
[in,out]ctxpointer to an allocated Dilithium context
[in]skpointer to bit-packed secret key
Returns
0 (success) or < 0 on error; -EOPNOTSUPP is returned if a different hash than lc_shake256 is used.

◆ lc_dilithium_87_sign_update()

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

Add more data to an already initialized signature state.

This call is intended to support messages that are located in non-contiguous places and even becomes available at different times. This call is to be used together with the lc_dilithium_sign_init and lc_dilithium_sign_final.

Parameters
[in]ctxpointer to Dilithium context that was initialized with lc_dilithium_sign_init
[in]mpointer to message to be signed
[in]mlenlength of message
Returns
0 (success) or < 0 on error

◆ lc_dilithium_87_sk_size()

LC_PURE unsigned int lc_dilithium_87_sk_size ( void )
inlinestatic

Return the size of the Dilithium secret key.

Definition at line 440 of file lc_dilithium_87.h.

◆ lc_dilithium_87_verify()

int lc_dilithium_87_verify ( const struct lc_dilithium_87_sig * sig,
const uint8_t * m,
size_t mlen,
const struct lc_dilithium_87_pk * pk )

Verifies ML-DSA signature in one shot.

Parameters
[in]sigpointer to input signature
[in]mpointer to message
[in]mlenlength of message
[in]pkpointer to bit-packed public key
Returns
0 if signature could be verified correctly and -EBADMSG when signature cannot be verified, < 0 on other errors

◆ lc_dilithium_87_verify_ctx()

int lc_dilithium_87_verify_ctx ( const struct lc_dilithium_87_sig * sig,
struct lc_dilithium_ctx * ctx,
const uint8_t * m,
size_t mlen,
const struct lc_dilithium_87_pk * pk )

Verifies signature with Dilithium context in one shot.

This API allows the caller to provide an arbitrary context buffer which is hashed together with the message to form the message digest to be signed.

Parameters
[in]sigpointer to input signature
[in]ctxreference to the allocated Dilithium context handle
[in]mpointer to message
[in]mlenlength of message
[in]pkpointer to bit-packed public key
Returns
0 if signature could be verified correctly and -EBADMSG when signature cannot be verified, < 0 on other errors

◆ lc_dilithium_87_verify_final()

int lc_dilithium_87_verify_final ( const struct lc_dilithium_87_sig * sig,
struct lc_dilithium_ctx * ctx,
const struct lc_dilithium_87_pk * pk )

Verifies signature.

Parameters
[in]sigpointer to output signature
[in]ctxpointer to Dilithium context that was initialized with lc_dilithium_sign_init and filled with lc_dilithium_sign_update
[in]pkpointer to bit-packed public key
Returns
0 if signature could be verified correctly and -EBADMSG when signature cannot be verified, < 0 on other errors

◆ lc_dilithium_87_verify_init()

int lc_dilithium_87_verify_init ( struct lc_dilithium_ctx * ctx,
const struct lc_dilithium_87_pk * pk )

Initializes a signature verification operation.

This call is intended to support messages that are located in non-contiguous places and even becomes available at different times. This call is to be used together with the lc_dilithium_verify_update and lc_dilithium_verify_final.

Parameters
[in,out]ctxpointer to an allocated Dilithium context
[in]pkpointer to bit-packed public key
Returns
0 (success) or < 0 on error; -EOPNOTSUPP is returned if a different hash than lc_shake256 is used.

◆ lc_dilithium_87_verify_update()

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

Add more data to an already initialized signature state.

This call is intended to support messages that are located in non-contiguous places and even becomes available at different times. This call is to be used together with the lc_dilithium_verify_init and lc_dilithium_verify_final.

Parameters
[in,out]ctxpointer to Dilithium context that was initialized with lc_dilithium_sign_init
[in]mpointer to message to be signed
[in]mlenlength of message
Returns
0 (success) or < 0 on error