Enumerations, basic types and callback function specifications. More...

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

Include dependency graph for types.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	XmssValue256
	A generic 256-bit value, represented as a byte stream. More...

struct	XmssNativeValue256
	The internal (native) representation of a 256-bit value. More...

struct	XmssBuffer
	A pointer to a buffer with a given size. More...

Macros
#define	XMSS_TYPES_H_INCLUDED
	Include guard.

#define	XMSS_TREE_DEPTH(param_set)
	The tree depth for a given XMSS parameter set. More...

#define	XMSS_VALUE_256_WORDS 8
	The number of 32-bits words in an XmssValue256. More...

Typedefs
typedef void (	XmssReallocFunction) (void *ptr, size_t size)
	A function to reallocate memory. More...

typedef void(*	XmssFreeFunction) (void *ptr)
	A function to deallocate memory. More...

typedef void(*	XmssZeroizeFunction) (void *ptr, size_t size)
	A function to securely erase sensitive data. More...

Enumerations
enum	XmssDistantValues { XMSS_DISTANT_VALUE_0 = 0x00 , XMSS_DISTANT_VALUE_1 = 0xD2 , XMSS_DISTANT_VALUE_2 = 0x55 , XMSS_DISTANT_VALUE_3 = 0x87 , XMSS_DISTANT_VALUE_4 = 0x99 , XMSS_DISTANT_VALUE_5 = 0x4B , XMSS_DISTANT_VALUE_6 = 0xCC , XMSS_DISTANT_VALUE_7 = 0x1E , XMSS_DISTANT_VALUE_8 = 0xE1 , XMSS_DISTANT_VALUE_9 = 0x33 , XMSS_DISTANT_VALUE_A = 0xB4 , XMSS_DISTANT_VALUE_B = 0x66 , XMSS_DISTANT_VALUE_C = 0x78 , XMSS_DISTANT_VALUE_D = 0xAA , XMSS_DISTANT_VALUE_E = 0x2D , XMSS_DISTANT_VALUE_F = 0xFF }
	A list of Hamming(8,4) code words. More...

enum	XmssError { XMSS_OKAY = XMSS_DISTANT_VALUE_1 , XMSS_ERR_NULL_POINTER = XMSS_DISTANT_VALUE_2 , XMSS_ERR_INVALID_SIGNATURE = XMSS_DISTANT_VALUE_3 , XMSS_ERR_ARGUMENT_MISMATCH = XMSS_DISTANT_VALUE_4 , XMSS_ERR_ALLOC_ERROR = XMSS_DISTANT_VALUE_5 , XMSS_ERR_INVALID_BLOB = XMSS_DISTANT_VALUE_6 , XMSS_ERR_BAD_CONTEXT = XMSS_DISTANT_VALUE_7 , XMSS_ERR_INVALID_ARGUMENT = XMSS_DISTANT_VALUE_8 , XMSS_ERR_PARTITION_DONE = XMSS_DISTANT_VALUE_9 , XMSS_ERR_UNFINISHED_PARTITIONS = XMSS_DISTANT_VALUE_A , XMSS_ERR_TOO_FEW_SIGNATURES_AVAILABLE = XMSS_DISTANT_VALUE_B , XMSS_ERR_PARTITIONS_NOT_CONSECUTIVE = XMSS_DISTANT_VALUE_C , XMSS_ERR_NO_PUBLIC_KEY = XMSS_DISTANT_VALUE_D , XMSS_ERR_FAULT_DETECTED = XMSS_DISTANT_VALUE_E , XMSS_UNINITIALIZED = XMSS_DISTANT_VALUE_F }
	The return codes for the functions in the XMSS library. More...

enum	XmssParameterSetOID { XMSS_PARAM_SHA2_10_256 = 1 , XMSS_PARAM_SHA2_16_256 = 2 , XMSS_PARAM_SHA2_20_256 = 3 , XMSS_PARAM_SHAKE256_10_256 = 0x10 , XMSS_PARAM_SHAKE256_16_256 = 0x11 , XMSS_PARAM_SHAKE256_20_256 = 0x12 }
	The XMSS parameter sets that are supported by this library. More...

enum	XmssIndexObfuscationSetting { XMSS_INDEX_OBFUSCATION_OFF = XMSS_DISTANT_VALUE_1 , XMSS_INDEX_OBFUSCATION_ON = XMSS_DISTANT_VALUE_2 }
	The supported settings for index obfuscation. More...

enum	XmssCacheType { XMSS_CACHE_NONE = XMSS_DISTANT_VALUE_1 , XMSS_CACHE_SINGLE_LEVEL = XMSS_DISTANT_VALUE_2 , XMSS_CACHE_TOP = XMSS_DISTANT_VALUE_3 }
	The type of caching to use. More...

Detailed Description

Enumerations, basic types and callback function specifications.

There is no need to include this header explicitly. Instead, include either verification.h or signing.h.

Macro Definition Documentation

◆ XMSS_TREE_DEPTH

#define XMSS_TREE_DEPTH ( param_set )

Value:

    (((param_set) == XMSS_PARAM_SHA2_10_256 || (param_set) == XMSS_PARAM_SHAKE256_10_256) ? 10u : \
        (((param_set) == XMSS_PARAM_SHA2_16_256 || (param_set) == XMSS_PARAM_SHAKE256_16_256) ? 16u : \
            (((param_set) == XMSS_PARAM_SHA2_20_256 || (param_set) == XMSS_PARAM_SHAKE256_20_256) ? 20u : \
                0u /* Garbage in, 0 out */ \
            ) \
        ) \
    )

The tree depth for a given XMSS parameter set.

Note: The argument to XMSS_TREE_DEPTH() will be evaluated multiple times.

Parameters

[in] param_set A valid XmssParameterSetOID.

◆ XMSS_VALUE_256_WORDS

#define XMSS_VALUE_256_WORDS 8

The number of 32-bits words in an XmssValue256.

Defined as a literal constant to allow its use in both a signed and an unsigned context.

Typedef Documentation

◆ XmssFreeFunction

typedef void(* XmssFreeFunction) (void *ptr)

A function to deallocate memory.

All memory deallocations will be done using this function.

Note that the signature for this function type is identical to that of standard C free().

See also: xmss_context_initialize() for additional information about memory management.

Parameters

[in] ptr The pointer to the allocated memory. After the memory deallocation function returns this pointer is considered to no longer be valid and will neither be used nor passed to a memory deallocation function again.

◆ XmssReallocFunction

typedef void*(* XmssReallocFunction) (void *ptr, size_t size)

A function to reallocate memory.

All memory allocations will be done using this function.

Note that the signature for this function type is identical to that of standard C realloc().

See also: xmss_context_initialize() for additional information about memory management.

Parameters

[in]	ptr	The pointer to an existing block of memory to resize, or NULL to allocate a new block of memory. If the memory reallocation function returns a non-NULL value that is different from this argument, this pointer is considered to no longer be valid and will neither be used nor passed to a memory deallocation function.
[in]	size	The requested size of the memory block.

Returns: The pointer to the memory block, which is at least size bytes large, or NULL if (re)allocation failed.

◆ XmssZeroizeFunction

typedef void(* XmssZeroizeFunction) (void *ptr, size_t size)

A function to securely erase sensitive data.

This function overwrites sensitive data in memory with zeros.

Parameters

[in]	ptr	The pointer to the object to erase.
[in]	size	The size in bytes of the object.

Enumeration Type Documentation

◆ XmssCacheType

enum XmssCacheType

The type of caching to use.

Enumerator

XMSS_CACHE_NONE

No caching.

XMSS_CACHE_SINGLE_LEVEL

Single level caching.

Single level caching saves half the cache space, but increases computation time for every signature.

XMSS_CACHE_TOP

Top caching.

Top caching caches a single level and all levels above that, up to the root. Top caching requires twice as much space as single level but saves computation time for every signature.

◆ XmssDistantValues

enum XmssDistantValues

A list of Hamming(8,4) code words.

These code words are used to provide values with high hamming distance to other enums' values.

XMSS_DISTANT_VALUE_0 is guaranteed to be 0, allowing its use for values that should automatically be set when a structure it contains is cleared to all-zeroes.

Enumerator
XMSS_DISTANT_VALUE_0	Code word 0: $00000000_2$.
XMSS_DISTANT_VALUE_1	Code word 1: $11010010_2$.
XMSS_DISTANT_VALUE_2	Code word 2: $01010101_2$.
XMSS_DISTANT_VALUE_3	Code word 3: $10000111_2$.
XMSS_DISTANT_VALUE_4	Code word 4: $10011001_2$.
XMSS_DISTANT_VALUE_5	Code word 5: $01001011_2$.
XMSS_DISTANT_VALUE_6	Code word 6: $11001100_2$.
XMSS_DISTANT_VALUE_7	Code word 7: $00011110_2$.
XMSS_DISTANT_VALUE_8	Code word 8: $11100001_2$.
XMSS_DISTANT_VALUE_9	Code word 9: $00110011_2$.
XMSS_DISTANT_VALUE_A	Code word A: $10110100_2$.
XMSS_DISTANT_VALUE_B	Code word B: $01100110_2$.
XMSS_DISTANT_VALUE_C	Code word C: $01111000_2$.
XMSS_DISTANT_VALUE_D	Code word D: $10101010_2$.
XMSS_DISTANT_VALUE_E	Code word E: $00101101_2$.
XMSS_DISTANT_VALUE_F	Code word F: $11111111_2$.

◆ XmssError

enum XmssError

The return codes for the functions in the XMSS library.

The values of these return codes are chosen from a Hamming(8,4) code to ensure bit error resilience. Note that XMSS_DISTANT_VALUE_0 (with value 0) is unused to avoid accidentally confusing it with an uninitialized value.

See also: XmssDistantValues; xmss_error_to_description(); xmss_error_to_name()

Enumerator
XMSS_OKAY	Success.
XMSS_ERR_NULL_POINTER	An unexpected NULL pointer was passed.
XMSS_ERR_INVALID_SIGNATURE	The signature is invalid.
XMSS_ERR_ARGUMENT_MISMATCH	A mismatch was detected between arguments.
XMSS_ERR_ALLOC_ERROR	An error occurred with memory allocation.
XMSS_ERR_INVALID_BLOB	A blob structure was found to be invalid.
XMSS_ERR_BAD_CONTEXT	The passed context is in an incorrect state.
XMSS_ERR_INVALID_ARGUMENT	The value of an argument was invalid.
XMSS_ERR_PARTITION_DONE	The calculations for the key generation partition were already performed.
XMSS_ERR_UNFINISHED_PARTITIONS	Not all key generation partition calculations were completed.
XMSS_ERR_TOO_FEW_SIGNATURES_AVAILABLE	There are not enough signatures available to allow the operation.
XMSS_ERR_PARTITIONS_NOT_CONSECUTIVE	Partitions are not consecutive.
XMSS_ERR_NO_PUBLIC_KEY	The key context does not have a public key loaded.
XMSS_ERR_FAULT_DETECTED	A fault was detected. Note that faults can also cause different errors or segfaults.
XMSS_UNINITIALIZED	Function returned prematurely. Dummy value to initialize return value variables before the correct value is known.

◆ XmssIndexObfuscationSetting

enum XmssIndexObfuscationSetting

The supported settings for index obfuscation.

Enumerator
XMSS_INDEX_OBFUSCATION_OFF	No index obfuscation.
XMSS_INDEX_OBFUSCATION_ON	Index obfuscation is enabled.

◆ XmssParameterSetOID

enum XmssParameterSetOID

The XMSS parameter sets that are supported by this library.

These are the supported subset of OIDs for XMSS parameter sets as defined in:

for SHA-256: RFC 8391, Section 5.3 and NIST SP 800-208, Section 5.1.
for SHAKE256/256: NIST SP 800-208, Section 5.3.

Note: All listed OIDs are defined, even if a hash algorithm was disabled during compilation and as a result is not supported.

Enumerator
XMSS_PARAM_SHA2_10_256	SHA-256, tree height 10.
XMSS_PARAM_SHA2_16_256	SHA-256, tree height 16.
XMSS_PARAM_SHA2_20_256	SHA-256, tree height 20.
XMSS_PARAM_SHAKE256_10_256	SHAKE256/256, tree height 10.
XMSS_PARAM_SHAKE256_16_256	SHAKE256/256, tree height 16.
XMSS_PARAM_SHAKE256_20_256	SHAKE256/256, tree height 20.

Classes

Macros

Typedefs

Enumerations

Detailed Description

Macro Definition Documentation

◆ XMSS_TREE_DEPTH

◆ XMSS_VALUE_256_WORDS

Typedef Documentation

◆ XmssFreeFunction

◆ XmssReallocFunction

◆ XmssZeroizeFunction

Enumeration Type Documentation

◆ XmssCacheType

◆ XmssDistantValues

◆ XmssError

◆ XmssIndexObfuscationSetting

◆ XmssParameterSetOID