iqr_hss.h

Go to the documentation of this file.

#ifndef IQR_HSS_H
#define IQR_HSS_H

#ifdef __cplusplus
extern "C" {
#endif

#include "iqr_api.h"
#include "iqr_hash.h"
#include "iqr_retval.h"
#include "iqr_rng.h"

#include <stddef.h>
#include <stdint.h>

// ---------------------------------------------------------------------------------------------------------------------------------
// Opaque data types.
// ---------------------------------------------------------------------------------------------------------------------------------

typedef struct iqr_HSSPrivateKeyState_struct iqr_HSSPrivateKeyState;

typedef struct iqr_HSSParams_struct iqr_HSSParams;

typedef struct iqr_HSSPublicKey_struct iqr_HSSPublicKey;

typedef struct iqr_HSSPrivateKey_struct iqr_HSSPrivateKey;

typedef struct iqr_HSSTreeStrategy_struct iqr_HSSTreeStrategy;

// ---------------------------------------------------------------------------------------------------------------------------------
// HSS tree strategies.
// ---------------------------------------------------------------------------------------------------------------------------------

IQR_EXTERN
const iqr_HSSTreeStrategy IQR_HSS_BDS_STRATEGY;

IQR_EXTERN
const iqr_HSSTreeStrategy IQR_HSS_FULL_STRATEGY;

IQR_EXTERN
const iqr_HSSTreeStrategy IQR_HSS_VERIFY_ONLY_STRATEGY;

// ---------------------------------------------------------------------------------------------------------------------------------
// HSS parameters.
// ---------------------------------------------------------------------------------------------------------------------------------

typedef enum {
    IQR_HSS_WINTERNITZ_1    = 0,
    IQR_HSS_WINTERNITZ_2    = 1,
    IQR_HSS_WINTERNITZ_4    = 2,
    IQR_HSS_WINTERNITZ_8    = 3,

    IQR_HSS_WINTERNITZ_LAST
} iqr_HSSWinternitz;

typedef enum {
    IQR_HSS_HEIGHT_5    = 0,

    IQR_HSS_HEIGHT_10   = 1,

    IQR_HSS_HEIGHT_15   = 2,

    IQR_HSS_HEIGHT_20   = 3,

    IQR_HSS_HEIGHT_25   = 4,

    IQR_HSS_HEIGHT_LAST
} iqr_HSSHeight;

typedef enum {
    IQR_HSS_LEVEL_1     = 0,


    IQR_HSS_LEVEL_MAX
} iqr_HSSLevels;

// ---------------------------------------------------------------------------------------------------------------------------------
// Domain parameter functions.
// ---------------------------------------------------------------------------------------------------------------------------------

IQR_API
iqr_retval iqr_HSSCreateParams(const iqr_Context *ctx, const iqr_HSSTreeStrategy *strategy, iqr_HSSWinternitz w, iqr_HSSHeight h,
    iqr_HSSLevels l, iqr_HSSParams **params);

IQR_API_UNENFORCED_RETURN
iqr_retval iqr_HSSDestroyParams(iqr_HSSParams **params);

// ---------------------------------------------------------------------------------------------------------------------------------
// Key management functions.
// ---------------------------------------------------------------------------------------------------------------------------------

IQR_API
iqr_retval iqr_HSSCreateKeyPair(const iqr_HSSParams *params, const iqr_RNG *rng, iqr_HSSPublicKey **public_key,
    iqr_HSSPrivateKey **private_key, iqr_HSSPrivateKeyState **state);

IQR_API
iqr_retval iqr_HSSImportPrivateKey(const iqr_HSSParams *params, const uint8_t *buf, size_t buf_size,
    iqr_HSSPrivateKey **private_key);

IQR_API
iqr_retval iqr_HSSExportPrivateKey(const iqr_HSSPrivateKey *private_key, uint8_t *buf, size_t buf_size);

IQR_API
iqr_retval iqr_HSSImportPublicKey(const iqr_HSSParams *params, const uint8_t *buf, size_t buf_size,
    iqr_HSSPublicKey **public_key);

IQR_API
iqr_retval iqr_HSSExportPublicKey(const iqr_HSSPublicKey *public_key, uint8_t *buf, size_t buf_size);

IQR_API
iqr_retval iqr_HSSImportState(const iqr_HSSParams *params, const uint8_t *buf, size_t buf_size, iqr_HSSPrivateKeyState **state);

IQR_API
iqr_retval iqr_HSSExportState(const iqr_HSSPrivateKeyState *state, uint8_t *buf, size_t buf_size);

IQR_API_UNENFORCED_RETURN
iqr_retval iqr_HSSDestroyPrivateKey(iqr_HSSPrivateKey **private_key);

IQR_API_UNENFORCED_RETURN
iqr_retval iqr_HSSDestroyPublicKey(iqr_HSSPublicKey **public_key);

IQR_API_UNENFORCED_RETURN
iqr_retval iqr_HSSDestroyState(iqr_HSSPrivateKeyState **state);

// ---------------------------------------------------------------------------------------------------------------------------------
// State management functionality.
// ---------------------------------------------------------------------------------------------------------------------------------

IQR_API
iqr_retval iqr_HSSDetachState(const iqr_HSSPrivateKey *private_key, iqr_HSSPrivateKeyState *state, uint32_t num_sigs,
    iqr_HSSPrivateKeyState **detached_state);

// ---------------------------------------------------------------------------------------------------------------------------------
// Key data retrieval functions.
// ---------------------------------------------------------------------------------------------------------------------------------

IQR_API
iqr_retval iqr_HSSGetPrivateKeySize(const iqr_HSSPrivateKey *private_key, size_t *private_key_size);

IQR_API
iqr_retval iqr_HSSGetPublicKeySize(const iqr_HSSPublicKey *public_key, size_t *public_key_size);

IQR_API
iqr_retval iqr_HSSGetStateSize(const iqr_HSSPrivateKeyState *state, size_t *state_size);

// ---------------------------------------------------------------------------------------------------------------------------------
// Signature functionality.
// ---------------------------------------------------------------------------------------------------------------------------------

IQR_API
iqr_retval iqr_HSSGetSignatureSize(const iqr_HSSParams *params, size_t *sig_size);

#ifndef IQR_IGNORE_1_5_DEPRECATED
IQR_DEPRECATED_MSG("This API will change in the next toolkit release.")
#endif
IQR_API
iqr_retval iqr_HSSGetSignatureCount(const iqr_HSSPrivateKeyState *state, uint32_t *max_sigs, uint32_t *remaining_sigs);

IQR_API
iqr_retval iqr_HSSSign(const iqr_HSSPrivateKey *private_key, const iqr_RNG *rng, const uint8_t *message, size_t message_size,
    iqr_HSSPrivateKeyState *state, uint8_t *sig, size_t sig_size);

IQR_API
iqr_retval iqr_HSSVerify(const iqr_HSSPublicKey *public_key, const uint8_t *message, size_t message_size, const uint8_t *sig,
    size_t sig_size);

#ifdef __cplusplus
}
#endif

#endif /* IQR_HSS_H */