iqr_xmss.h

Go to the documentation of this file.

#ifndef IQR_XMSS_H
#define IQR_XMSS_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_XMSSPrivateKeyState_struct iqr_XMSSPrivateKeyState;

typedef struct iqr_XMSSParams_struct iqr_XMSSParams;

typedef struct iqr_XMSSPublicKey_struct iqr_XMSSPublicKey;

typedef struct iqr_XMSSPrivateKey_struct iqr_XMSSPrivateKey;

typedef struct iqr_XMSSTreeStrategy_struct iqr_XMSSTreeStrategy;

// ---------------------------------------------------------------------------------------------------------------------------------
// XMSS tree strategies.
// ---------------------------------------------------------------------------------------------------------------------------------

IQR_EXTERN
const iqr_XMSSTreeStrategy IQR_XMSS_BDS_STRATEGY;

IQR_EXTERN
const iqr_XMSSTreeStrategy IQR_XMSS_FULL_STRATEGY;

IQR_EXTERN
const iqr_XMSSTreeStrategy IQR_XMSS_VERIFY_ONLY_STRATEGY;

// ---------------------------------------------------------------------------------------------------------------------------------
// XMSS parameters.
// ---------------------------------------------------------------------------------------------------------------------------------

typedef enum {
    IQR_XMSS_HEIGHT_10      = 0,

    IQR_XMSS_HEIGHT_16      = 1,

    IQR_XMSS_HEIGHT_20      = 2,

    IQR_XMSS_HEIGHT_LAST
} iqr_XMSSHeight;

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

IQR_API
iqr_retval iqr_XMSSCreateParams(const iqr_Context *ctx, const iqr_XMSSTreeStrategy *strategy, iqr_XMSSHeight h,
    iqr_XMSSParams **params);

IQR_API_UNENFORCED_RETURN
iqr_retval iqr_XMSSDestroyParams(iqr_XMSSParams **params);

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

IQR_API
iqr_retval iqr_XMSSCreateKeyPair(const iqr_XMSSParams *params, const iqr_RNG *rng, iqr_XMSSPublicKey **public_key,
    iqr_XMSSPrivateKey **private_key, iqr_XMSSPrivateKeyState **state);

IQR_API
iqr_retval iqr_XMSSImportPrivateKey(const iqr_XMSSParams *params, const uint8_t *buf, size_t buf_size,
    iqr_XMSSPrivateKey **private_key);

IQR_API
iqr_retval iqr_XMSSExportPrivateKey(const iqr_XMSSPrivateKey *private_key, uint8_t *buf, size_t buf_size);

IQR_API
iqr_retval iqr_XMSSImportPublicKey(const iqr_XMSSParams *params, const uint8_t *buf, size_t buf_size,
    iqr_XMSSPublicKey **public_key);

IQR_API
iqr_retval iqr_XMSSExportPublicKey(const iqr_XMSSPublicKey *public_key, uint8_t *buf, size_t buf_size);

IQR_API
iqr_retval iqr_XMSSImportState(const iqr_XMSSParams *params, const uint8_t *buf, size_t buf_size, iqr_XMSSPrivateKeyState **state);

IQR_API
iqr_retval iqr_XMSSExportState(const iqr_XMSSPrivateKeyState *state, uint8_t *buf, size_t buf_size);

IQR_API_UNENFORCED_RETURN
iqr_retval iqr_XMSSDestroyPrivateKey(iqr_XMSSPrivateKey **private_key);

IQR_API_UNENFORCED_RETURN
iqr_retval iqr_XMSSDestroyPublicKey(iqr_XMSSPublicKey **public_key);

IQR_API_UNENFORCED_RETURN
iqr_retval iqr_XMSSDestroyState(iqr_XMSSPrivateKeyState **state);

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

IQR_API
iqr_retval iqr_XMSSDetachState(const iqr_XMSSPrivateKey *private_key, iqr_XMSSPrivateKeyState *state, uint32_t num_sigs,
    iqr_XMSSPrivateKeyState **detached_state);

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

IQR_API
iqr_retval iqr_XMSSGetPrivateKeySize(const iqr_XMSSPrivateKey *private_key, size_t *private_key_size);

IQR_API
iqr_retval iqr_XMSSGetPublicKeySize(const iqr_XMSSPublicKey *public_key, size_t *public_key_size);

IQR_API
iqr_retval iqr_XMSSGetStateSize(const iqr_XMSSPrivateKeyState *state, size_t *state_size);

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

IQR_API
iqr_retval iqr_XMSSGetSignatureSize(const iqr_XMSSParams *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_XMSSGetSignatureCount(const iqr_XMSSPrivateKeyState *state, uint32_t *max_sigs, uint32_t *remaining_sigs);

IQR_API
iqr_retval iqr_XMSSSign(const iqr_XMSSPrivateKey *private_key, const iqr_RNG *rng, const uint8_t *message,
    size_t message_size, iqr_XMSSPrivateKeyState *state,  uint8_t *sig, size_t sig_size);

IQR_API
iqr_retval iqr_XMSSVerify(const iqr_XMSSPublicKey *public_key, const uint8_t *message, size_t message_size, const uint8_t *sig,
    size_t sig_size);

#ifdef __cplusplus
}
#endif

#endif /* IQR_XMSS_H */