version.h File Reference

Public API for XMSS library version control. More...

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

Include dependency graph for version.h:

Go to the source code of this file.

Macros
#define	XMSS_VERSION_H_INCLUDED
	Include guard.
#define	XMSS_LIBRARY_VERSION_CONSTRUCT(major, minor, patch)
	Construct an amalgamated semantic version from parts. More...
#define	XMSS_LIBRARY_VERSION
	The amalgamated semantic version (SemVer 2.0) of the library headers. More...
#define	XMSS_LIBRARY_GET_VERSION_MAJOR(version)   ((uint8_t)((((uint32_t)(version)) >> 16) & UINT8_MAX))
	Retrieve the major version from an amalgamated semantic version. More...
#define	XMSS_LIBRARY_GET_VERSION_MINOR(version)   ((uint8_t)((((uint32_t)(version)) >> 8) & UINT8_MAX))
	Retrieve the minor version from an amalgamated semantic version. More...
#define	XMSS_LIBRARY_GET_VERSION_PATCH(version)   ((uint8_t)(((uint32_t)(version)) & UINT8_MAX))
	Retrieve the patch version from an amalgamated semantic version. More...

Functions
uint32_t	xmss_library_get_version (void)
	Retrieve, at application runtime, the amalgamated semantic version (SemVer 2.0) of the library at build-time of the library. More...

Detailed Description

Public API for XMSS library version control.

The macros and functions are currently all prefixed with XMSS_LIBRARY_ and xmss_library_ as currently only the library implementation is versioned, not the XMSS algorithm itself.

Macro Definition Documentation

XMSS_LIBRARY_GET_VERSION_MAJOR

#define XMSS_LIBRARY_GET_VERSION_MAJOR

(

version

)

((uint8_t)((((uint32_t)(version)) >> 16) & UINT8_MAX))

Retrieve the major version from an amalgamated semantic version.

See also

XMSS_LIBRARY_VERSION

xmss_library_get_version()

Parameters

[in]

version

An amalgamated semantic version.

Returns

The major version, as an uint8_t.

XMSS_LIBRARY_GET_VERSION_MINOR

#define XMSS_LIBRARY_GET_VERSION_MINOR

(

version

)

((uint8_t)((((uint32_t)(version)) >> 8) & UINT8_MAX))

Retrieve the minor version from an amalgamated semantic version.

See also

XMSS_LIBRARY_VERSION

xmss_library_get_version()

Parameters

[in]

version

An amalgamated semantic version.

Returns

The minor version, as an uint8_t.

XMSS_LIBRARY_GET_VERSION_PATCH

#define XMSS_LIBRARY_GET_VERSION_PATCH

(

version

)

((uint8_t)(((uint32_t)(version)) & UINT8_MAX))

Retrieve the patch version from an amalgamated semantic version.

See also

XMSS_LIBRARY_VERSION

xmss_library_get_version()

Parameters

[in]

version

An amalgamated semantic version.

Returns

The patch version, as an uint8_t.

XMSS_LIBRARY_VERSION

#define XMSS_LIBRARY_VERSION

Value:

    (XMSS_LIBRARY_VERSION_CONSTRUCT(XMSS_LIBRARY_VERSION_MAJOR, XMSS_LIBRARY_VERSION_MINOR, \
    XMSS_LIBRARY_VERSION_PATCH))

The amalgamated semantic version (SemVer 2.0) of the library headers.

To verify at compile-time that you are compiling against the expected library version, compare this value against the expected value constructed with XMSS_LIBRARY_VERSION_CONSTRUCT(). For example:

static_assert(XMSS_LIBRARY_VERSION == XMSS_LIBRARY_VERSION_CONSTRUCT(1,2,3), "Unexpected library version");

Alternatively, compare the values of the individual parts. For example:

static_assert(XMSS_LIBRARY_VERSION_MAJOR == 2, "Unexpected library version");

See also

xmss_library_get_version()

XMSS_LIBRARY_VERSION_CONSTRUCT

#define XMSS_LIBRARY_VERSION_CONSTRUCT	(		major,
			minor,
			patch
	)

Value:

    ((((uint32_t)(uint8_t)(major)) << 16) \
    | (((uint32_t)(uint8_t)(minor)) << 8) \
    | ((uint32_t)(uint8_t)(patch)))

Construct an amalgamated semantic version from parts.

The resulting value may be compared directly against XMSS_LIBRARY_VERSION (intended for compile-time checks) and/or xmss_library_get_version() (intended for run time checks).

Remarks

The individual parts will be silently truncated to uint8_t; i.e., their values must be between 0 and 255 (inclusive).

Parameters

[in]	major	The major version.
[in]	minor	The minor version.
[in]	patch	The patch version.

Returns

The amalgamated semantic version, as an uint32_t.

Function Documentation

xmss_library_get_version()

uint32_t xmss_library_get_version

(

void

)

Retrieve, at application runtime, the amalgamated semantic version (SemVer 2.0) of the library at build-time of the library.

To verify at runtime that you are using the expected (binary) library version, compare this value against the expected value constructed with XMSS_LIBRARY_VERSION_CONSTRUCT(), or against XMSS_LIBRARY_VERSION. For example:

if (xmss_library_get_version() != XMSS_LIBRARY_VERSION) {
    // handle library version mismatch
}

Alternatively, compare individual parts using XMSS_LIBRARY_GET_VERSION_MAJOR(), XMSS_LIBRARY_GET_VERSION_MINOR(), and/or XMSS_LIBRARY_GET_VERSION_MINOR(). For example:

if (XMSS_LIBRARY_GET_VERSION_MAJOR(xmss_library_get_version()) != XMSS_LIBRARY_VERSION_MAJOR)
{
    // handle library version mismatch
}

Returns

The library version.