Public definitions of opaque structures and memory management calls for those. More...

#include "types.h"
#include "compat.h"

Include dependency graph for opaque_structures.h:

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

Macros
#define	XMSS_OPAQUE_STRUCTURES_H_INCLUDED
	Include guard.

#define	XMSS_SIGNING_CONTEXT_SIZE (4u + 4u + 4u + 4u + 4u * sizeof(void(*)(void)))
	The size in bytes of an XmssSigningContext.

#define	XMSS_CACHE_ENTRY_COUNT(cache_type, cache_level, param_set)
	The number of cached entries for a specific cache configuration. More...

#define	XMSS_INTERNAL_CACHE_SIZE(cache_type, cache_level, param_set) (4 + 4 + sizeof(XmssValue256) * XMSS_CACHE_ENTRY_COUNT((cache_type), (cache_level), (param_set)))
	The size in bytes of an XmssInternalCache. More...

#define	XMSS_PUBLIC_KEY_GENERATION_CACHE_SIZE(number_of_partitions) (4 + 4 + sizeof(XmssValue256) * (number_of_partitions))
	The size in bytes of the XmssInternalCache public key generation cache. More...

#define	XMSS_PRIVATE_KEY_STATEFUL_PART_SIZE (4u + 4u)
	The size in bytes of the stateful part of a private key. More...

#define	XMSS_PRIVATE_KEY_STATELESS_PART_SIZE (32u + 32u + 4u + 4u + 32u + sizeof(XmssValue256) + 32u)
	The size in bytes of the stateless part of a private key. More...

#define	XMSS_KEY_CONTEXT_SIZE(param_set, obfuscation_setting)
	The size in bytes of an XmssKeyContext. More...

#define	XMSS_KEY_GENERATION_CONTEXT_SIZE(generation_partitions)
	The size in bytes of XmssKeyGenerationContext. More...

Typedefs
typedef struct XmssSigningContext	XmssSigningContext
	The context of an instantiation of the signing library. More...

typedef struct XmssInternalCache	XmssInternalCache
	In-memory representation of a loaded cache. More...

typedef struct XmssKeyContext	XmssKeyContext
	Context for using the signature generation part of the library, with a loaded private key partition. More...

typedef struct XmssKeyGenerationContext	XmssKeyGenerationContext
	The temporary context to gather all the results of generating a public key. More...

Functions
void	xmss_free_signing_context (XmssSigningContext *signing_context)
	Deallocate an XmssSigningContext structure. More...

void	xmss_free_key_context (XmssKeyContext *key_context)
	Deallocate an XmssKeyContext structure. More...

void	xmss_free_key_generation_context (XmssKeyGenerationContext *key_generation_context)
	Deallocate an XmssKeyGenerationContext structure. More...

Detailed Description

Public definitions of opaque structures and memory management calls for those.

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

Macro Definition Documentation

◆ XMSS_CACHE_ENTRY_COUNT

#define XMSS_CACHE_ENTRY_COUNT	(	cache_type,
		cache_level,
		param_set
	)

Value:

    ((cache_type) == XMSS_CACHE_NONE ? 0u : \
        ((cache_level) >= XMSS_TREE_DEPTH(param_set) ? 0u : \
            ((cache_type) == XMSS_CACHE_SINGLE_LEVEL ? (1u << (XMSS_TREE_DEPTH(param_set) - (cache_level))) : \
                ((cache_type) == XMSS_CACHE_TOP ? ((1u << ((XMSS_TREE_DEPTH(param_set) - (cache_level)) + 1u)) - 1u) : \
                    0u /* Garbage in, 0 out. */ \
                ) \
            ) \
        ) \
    )

The number of cached entries for a specific cache configuration.

Note: The arguments to XMSS_CACHE_ENTRY_COUNT() will be evaluated multiple times.

Parameters

[in]	cache_type	The cache type that is used.
[in]	cache_level	The cache level that is to be held.
[in]	param_set	The parameter set of the key for which the cache will be used.

See also: xmss_generate_public_key() for more information about the cache type and level.

◆ XMSS_INTERNAL_CACHE_SIZE

#define XMSS_INTERNAL_CACHE_SIZE	(	cache_type,
		cache_level,
		param_set
	)	(4 + 4 + sizeof(XmssValue256) * XMSS_CACHE_ENTRY_COUNT((cache_type), (cache_level), (param_set)))

The size in bytes of an XmssInternalCache.

Note: The arguments to XMSS_INTERNAL_CACHE_SIZE() will be evaluated multiple times.

Parameters

[in]	cache_type	The cache type that is used.
[in]	cache_level	The cache level that is to be held.
[in]	param_set	The parameter set of the key for which the cache will be used.

See also: xmss_generate_public_key() for more information about the cache type and level.

◆ XMSS_KEY_CONTEXT_SIZE

#define XMSS_KEY_CONTEXT_SIZE	(	param_set,
		obfuscation_setting
	)

Value:

    (4u + 4u + XMSS_SIGNING_CONTEXT_SIZE + XMSS_PRIVATE_KEY_STATELESS_PART_SIZE + \
     2u * XMSS_PRIVATE_KEY_STATEFUL_PART_SIZE + 3 * sizeof(XmssValue256) + sizeof(void*) + 4u + 4u + \
     4u * (1u << XMSS_TREE_DEPTH(param_set)) * ((obfuscation_setting) == XMSS_INDEX_OBFUSCATION_ON ? 1u : 0u))

The size in bytes of an XmssKeyContext.

Note: The param_set argument will be evaluated multiple times.

Parameters

[in]	param_set	The XmssParameterSetOID that is to be used for the private key.
[in]	obfuscation_setting	The XmssIndexObfuscationSetting that is to be used with the private key.

◆ XMSS_KEY_GENERATION_CONTEXT_SIZE

#define XMSS_KEY_GENERATION_CONTEXT_SIZE ( generation_partitions )

Value:

(sizeof(void*) + sizeof(uint32_t) + sizeof(uint32_t) + sizeof(void*) + sizeof(void*) + \

sizeof(uint32_t) * (generation_partitions))

The size in bytes of XmssKeyGenerationContext.

Parameters

[in] generation_partitions The number of calculation partitions that will divide the work.

See also: xmss_generate_public_key() for more information about generation_partitions.

◆ XMSS_PRIVATE_KEY_STATEFUL_PART_SIZE

#define XMSS_PRIVATE_KEY_STATEFUL_PART_SIZE (4u + 4u)

The size in bytes of the stateful part of a private key.

For internal library use only.

◆ XMSS_PRIVATE_KEY_STATELESS_PART_SIZE

#define XMSS_PRIVATE_KEY_STATELESS_PART_SIZE (32u + 32u + 4u + 4u + 32u + sizeof(XmssValue256) + 32u)

The size in bytes of the stateless part of a private key.

For internal library use only.

◆ XMSS_PUBLIC_KEY_GENERATION_CACHE_SIZE

#define XMSS_PUBLIC_KEY_GENERATION_CACHE_SIZE ( number_of_partitions ) (4 + 4 + sizeof(XmssValue256) * (number_of_partitions))

The size in bytes of the XmssInternalCache public key generation cache.

Parameters

[in] number_of_partitions The number of partitions in which to perform the public key generation.

Typedef Documentation

◆ XmssInternalCache

typedef struct XmssInternalCache XmssInternalCache

In-memory representation of a loaded cache.

When creating an XmssInternalCache, the XMSS_INTERNAL_CACHE_SIZE() macro can be used to allocate the correct size.

XmssInternalCache is an opaque type, do not access its members.

◆ XmssKeyContext

typedef struct XmssKeyContext XmssKeyContext

Context for using the signature generation part of the library, with a loaded private key partition.

When creating an XmssKeyContext, the XMSS_KEY_CONTEXT_SIZE macro can be used to allocate the correct size.

XmssKeyContext is an opaque type, do not access its members.

◆ XmssKeyGenerationContext

typedef struct XmssKeyGenerationContext XmssKeyGenerationContext

The temporary context to gather all the results of generating a public key.

When creating an XmssKeyGenerationContext, the XMSS_KEY_GENERATION_CONTEXT_SIZE macro may be used to allocate the correct size.

The elements of an XmssKeyGenerationContext are generally to be considered invalid outside of their specific use in the public key generation process.

XmssKeyGenerationContext is an opaque type, do not access its members.

◆ XmssSigningContext

typedef struct XmssSigningContext XmssSigningContext

The context of an instantiation of the signing library.

The signing context defines the parameter set and the hash functions to use.

When creating an XmssSigningContext, the XMSS_SIGNING_CONTEXT_SIZE macro can be used to allocate the correct size.

XmssSigningContext is an opaque type, do not access its members.

Function Documentation

◆ xmss_free_key_context()

void xmss_free_key_context ( XmssKeyContext * key_context )

Deallocate an XmssKeyContext structure.

All secret data is securely erased.

Parameters

[in] key_context The structure to deallocate. May be NULL.

◆ xmss_free_key_generation_context()

void xmss_free_key_generation_context ( XmssKeyGenerationContext * key_generation_context )

Deallocate an XmssKeyGenerationContext structure.

Deallocate the key generation context structure and the associated caches that have not been transferred to other structures.

Parameters

[in] key_generation_context The structure the deallocate. May be NULL.

◆ xmss_free_signing_context()

void xmss_free_signing_context ( XmssSigningContext * signing_context )

Deallocate an XmssSigningContext structure.

Note that the signing context will be deallocated using the memory deallocation function that is contained inside the initialized structure itself. Deallocating a partially initialized signing context, which is impossible to obtain, would not work.

Parameters

[in] signing_context The structure to deallocate. May be NULL.

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ XMSS_CACHE_ENTRY_COUNT

◆ XMSS_INTERNAL_CACHE_SIZE

◆ XMSS_KEY_CONTEXT_SIZE

◆ XMSS_KEY_GENERATION_CONTEXT_SIZE

◆ XMSS_PRIVATE_KEY_STATEFUL_PART_SIZE

◆ XMSS_PRIVATE_KEY_STATELESS_PART_SIZE

◆ XMSS_PUBLIC_KEY_GENERATION_CACHE_SIZE

Typedef Documentation

◆ XmssInternalCache

◆ XmssKeyContext

◆ XmssKeyGenerationContext

◆ XmssSigningContext

Function Documentation

◆ xmss_free_key_context()

◆ xmss_free_key_generation_context()

◆ xmss_free_signing_context()