Release 2.0.0

Author: dorssel

.reuse/dep5

@@ -1,6 +1,6 @@
 Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
 Upstream-Name: xmss-library
-Source: https://github.com/foxcrypto/xmss-library
+Source: https://github.com/FoxCryptoNL/xmss-library
 
 Files: docs/doxygen-awesome-css/*
 Copyright: 2021-2023 jothepro

CMakeLists.txt

@@ -4,7 +4,7 @@
 # CMake 3.22.1 is the version installed with Ubuntu 22.04.1.
 cmake_minimum_required(VERSION 3.22.1 FATAL_ERROR)
 
-project(xmss-library VERSION 1.0.0 LANGUAGES C)
+project(xmss-library VERSION 2.0.0 LANGUAGES C)
 
 # All compiler options are in a separate file
 include("cmake/compiler_options.cmake")
@@ -47,6 +47,14 @@ else()
     endif()
 endif()
 
+# When set to OFF (default), static libraries are built.
+# When set to ON, shared libraries are built.
+option(BUILD_SHARED_LIBS "Build shared libraries instead of static ones." OFF)
+
+# When set to ON (default), both the full library (including signing) and a verification-only library are built.
+# When set to OFF, just the verification-only library is built.
+option(XMSS_ENABLE_SIGNING "Enable signing support in the library." ON)
+
 # The C tests are part of the early validation of the compiler/platform combination with the XMSS library and must not
 # be disabled for normal testing or production builds.
 # The full test suite contains several tests that require hash overrides that will completely fail these tests, though.
@@ -65,12 +73,24 @@ else()
     set(XMSS_ENABLE_SHA256 ON)
 endif()
 
+if(XMSS_SHA256 STREQUAL "Default")
+    set(XMSS_ENABLE_SHA256_DEFAULT ON)
+else()
+    set(XMSS_ENABLE_SHA256_DEFAULT OFF)
+endif()
+
 if(XMSS_SHAKE256_256 STREQUAL "Disabled")
     set(XMSS_ENABLE_SHAKE256_256 OFF)
 else()
     set(XMSS_ENABLE_SHAKE256_256 ON)
 endif()
 
+if(XMSS_SHAKE256_256 STREQUAL "Default")
+    set(XMSS_ENABLE_SHAKE256_256_DEFAULT ON)
+else()
+    set(XMSS_ENABLE_SHAKE256_256_DEFAULT OFF)
+endif()
+
 if(NOT XMSS_ENABLE_SHA256 AND NOT XMSS_ENABLE_SHAKE256_256)
     message(FATAL_ERROR "XMSS_SHA256 and XMSS_SHAKE256_256 cannot be both Disabled.")
 endif()
@@ -139,7 +159,14 @@ try_compile(XMSS_CAN_USE_EXTENSION_STATIC_ASSERT ${CMAKE_CURRENT_BINARY_DIR}
 configure_file(include/xmss_config.in.h include/xmss_config.h NO_SOURCE_PERMISSIONS)
 configure_file(src/config.in.h src/config.h NO_SOURCE_PERMISSIONS)
 
+add_library(config INTERFACE)
+target_include_directories(config
+    INTERFACE ${CMAKE_CURRENT_BINARY_DIR}/include
+    INTERFACE ${CMAKE_CURRENT_BINARY_DIR}/src
+)
+
 enable_testing()
+set_property(GLOBAL PROPERTY USE_FOLDERS ON)
 
 add_subdirectory(include)
 add_subdirectory(src)

README.md

@@ -9,8 +9,7 @@ eXtended Merkle Signature Scheme is a post-quantum safe signature algorithm
 ([RFC](https://datatracker.ietf.org/doc/html/rfc8391)).
 
 ![XMSS C Library License](https://img.shields.io/github/license/FoxCryptoNL/xmss-library?style=plastic)
-[![XMSS C Library Release](https://img.shields.io/github/v/release/FoxCryptoNL/xmss-library?style=plastic)](
-    https://github.com/FoxCryptoNL/xmss-library/releases)
+[![XMSS C Library Release](https://img.shields.io/github/v/release/FoxCryptoNL/xmss-library?style=plastic)](https://github.com/FoxCryptoNL/xmss-library/releases)
 
 ## XMSS C Library Source Code
 

include/CMakeLists.txt

@@ -3,6 +3,7 @@
 
 set(XMSS_HEADER_FILES
     compat.h
+    errors.h
     generic_digest.h
     opaque_structures.h
     override_sha256_generic.h
@@ -13,6 +14,7 @@ set(XMSS_HEADER_FILES
     structures.h
     types.h
     verification.h
+    version.h
     ${CMAKE_CURRENT_BINARY_DIR}/xmss_config.h
 )
 
@@ -41,6 +43,7 @@ int main(void) { return 0; }
         PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}
         PRIVATE ${CMAKE_CURRENT_BINARY_DIR}
     )
+    set_property(TARGET _verify_${HEADER_FILENAME} PROPERTY FOLDER tests/verify_headers)
     # Note that building the executable is the real test. They're added as tests, anyway, to ensure that they're built
     # as part of the test cycle.
     add_test(NAME "Verify ${HEADER_FILENAME} is standalone" COMMAND "_verify_${HEADER_FILENAME}")
@@ -50,3 +53,5 @@ add_library(xmss_headers INTERFACE ${XMSS_HEADER_FILES})
 target_include_directories(xmss_headers
     INTERFACE ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_BINARY_DIR}
 )
+
+install(FILES ${XMSS_HEADER_FILES} DESTINATION include/xmss)

include/compat.h

@@ -27,21 +27,21 @@
 
 /**
  * @brief
- * Syntactical equivalent of _Static_assert(), which is C11.
+ * Syntactical equivalent of `_Static_assert()`, which is C11.
  *
  * @details
- * C11 supports _Static_assert(). CMake can detect if it is available anyway, even if the compiler is not C11.
+ * C11 supports `_Static_assert()`. CMake can detect if it is available anyway, even if the compiler is not C11.
  * If CMake detects that static asserts are not supported, then this macro is a no-op.
  *
  * @see XMSS_CAN_USE_STATIC_ASSERT
  * @see XMSS_CAN_USE_EXTENSION_STATIC_ASSERT
  */
 #if (__STDC_VERSION__ >= 201112L) || XMSS_CAN_USE_STATIC_ASSERT || defined(DOXYGEN)
-#   define STATIC_ASSERT(cond, msg) _Static_assert(cond, msg)
+#   define XMSS_STATIC_ASSERT(cond, msg) _Static_assert(cond, msg)
 #elif XMSS_CAN_USE_EXTENSION_STATIC_ASSERT
-#   define STATIC_ASSERT(cond, msg) __extension__ _Static_assert(cond, msg)
+#   define XMSS_STATIC_ASSERT(cond, msg) __extension__ _Static_assert(cond, msg)
 #else
-#   define STATIC_ASSERT(cond, msg) struct xmss_static_assert_unsupported
+#   define XMSS_STATIC_ASSERT(cond, msg) struct xmss_static_assert_unsupported
 #endif
 
 #endif /* !XMSS_COMPAT_H_INCLUDED */

include/errors.h

@@ -0,0 +1,50 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Fox Crypto B.V.
+ * SPDX-License-Identifier: MIT
+ *
+ * SPDX-FileContributor: Thomas Schaap
+ * SPDX-FileContributor: Frans van Dorsselaer
+ */
+
+/**
+ * @file
+ * @brief
+ * Public API for XMSS error handling.
+ */
+
+#pragma once
+
+#ifndef XMSS_ERRORS_H_INCLUDED
+/** @private @brief Include guard. */
+#define XMSS_ERRORS_H_INCLUDED
+
+#include <types.h>
+
+
+/**
+ * Translate an XMSS error to the string with the enumeration-constant name.
+ *
+ * @details
+ * As an example, `xmss_error_to_name(XMSS_OKAY)` returns `"XMSS_OKAY"`.
+ *
+ * @remark
+ * This function returns `"XmssError_Undefined"` for values of `error` that are not defined in #XmssError.
+ *
+ * @param[in]   error   The error to translate.
+ *
+ * @returns A pointer to a static string with the enumeration-constant name corresponding to `error`.
+ */
+const char *xmss_error_to_name(XmssError error);
+
+
+/**
+ * Translate an XMSS error to a human-readable message.
+ *
+ * @param[in]   error   The error to translate.
+ *
+ * @returns A pointer to a static string with a message corresponding to `error`.
+ */
+const char *xmss_error_to_description(XmssError error);
+
+
+#endif /* !XMSS_ERRORS_H_INCLUDED */

include/generic_digest.h

@@ -9,8 +9,8 @@
  * @file
  * @brief Abstract typedefs for hash function overrides using the generic interface.
  * @details
- * Do not include this file. Instead, either include `override_sha256_generic.h` or
- * `override_shake256_256_generic.h`, depending on the specific algorithm you are overriding.
+ * Do not include this file. Instead, either include override_sha256_generic.h or
+ * override_shake256_256_generic.h, depending on the specific algorithm you are overriding.
  *
  * For each digest algorithm (SHA-256 and/or SHAKE256/256), the library allows to override its internal implementation.
  * The main use case is hardware acceleration.
@@ -20,9 +20,9 @@
  *
  * When supplying an override using the generic interface, you will have to implement 3 functions (per algorithm, that
  * you are overriding):
- * - initialize
- * - update
- * - finalize
+ * - #XmssGenericDigestInit
+ * - #XmssGenericDigestUpdate
+ * - #XmssGenericDigestFinalize
  *
  * The library guarantees that the functions are called in the following order:
  * - exactly one call to the initialize function
@@ -31,7 +31,7 @@
  *
  * Per thread, there will be at most one digest in use at any one time. This implies that if you use the library single
  * threaded, then you could use a single statically allocated context. In that case the opaque `context` parameter does
- * not necessarily have to be provided or used (i.e., it could simply be 0).
+ * not necessarily have to be provided or used (i.e., it could simply be NULL).
  *
  * **Error handling**
  *
@@ -84,10 +84,10 @@ typedef void *(*XmssGenericDigestInit)(void);
  * @param[in] context   An opaque context, i.e., the result of the most recent call to the initialization function on
  *                      this thread.
  * @param[in] data   The byte stream of additional data to be included in the message; may be NULL if and only if
- *                   data_length is zero.
- * @param[in] data_length   The number of bytes pointed to by data.
+ *                   `data_length` is zero.
+ * @param[in] data_length   The number of bytes pointed to by `data`.
  */
-typedef void (*XmssGenericDigestUpdate)(void *restrict context, const uint8_t *restrict data, size_t data_length);
+typedef void (*XmssGenericDigestUpdate)(void *context, const uint8_t *data, size_t data_length);
 
 /**
  * @brief
@@ -98,6 +98,6 @@ typedef void (*XmssGenericDigestUpdate)(void *restrict context, const uint8_t *r
  *                      this thread.
  * @param[out] digest   The output of the hash function.
  */
-typedef void (*XmssGenericDigestFinalize)(void *restrict context, XmssValue256 *restrict digest);
+typedef void (*XmssGenericDigestFinalize)(void *context, XmssValue256 *digest);
 
 #endif /* !XMSS_GENERIC_DIGEST_H_INCLUDED */

include/opaque_structures.h

@@ -30,7 +30,7 @@
  * @details
  * 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.
+ * 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.
  */
@@ -40,7 +40,7 @@ typedef struct XmssSigningContext XmssSigningContext;
  * @brief
  * The size in bytes of an XmssSigningContext.
  */
-#define XMSS_SIGNING_CONTEXT_SIZE (4u + 4u + 4u + 4u + 11u * sizeof(void(*)()))
+#define XMSS_SIGNING_CONTEXT_SIZE (4u + 4u + 4u + 4u + 4u * sizeof(void(*)(void)))
 
 /**
  * @brief
@@ -60,7 +60,7 @@ void xmss_free_signing_context(XmssSigningContext *signing_context);
  * In-memory representation of a loaded cache.
  *
  * @details
- * When creating an XmssInternalCache, the XMSS_INTERNAL_CACHE_SIZE macro can be used to allocate the correct size.
+ * 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.
  */
@@ -70,12 +70,12 @@ typedef struct XmssInternalCache XmssInternalCache;
  * @brief
  * The number of cached entries for a specific cache configuration.
  *
- * @note The arguments to XMSS_CACHE_ENTRY_COUNT will be evaluated multiple times.
+ * @note The arguments to #XMSS_CACHE_ENTRY_COUNT() will be evaluated multiple times.
  *
  * @param[in] cache_type    The cache type that is used.
  * @param[in] cache_level   The cache level that is to be held.
  * @param[in] param_set     The parameter set of the key for which the cache will be used.
- * @see xmss_generate_public_key for more information about the cache type and level.
+ * @see xmss_generate_public_key() for more information about the cache type and level.
  */
 #define XMSS_CACHE_ENTRY_COUNT(cache_type, cache_level, param_set) \
     ((cache_type) == XMSS_CACHE_NONE ? 0u : \
@@ -92,12 +92,12 @@ typedef struct XmssInternalCache XmssInternalCache;
  * @brief
  * The size in bytes of an XmssInternalCache.
  *
- * @note The arguments to XMSS_INTERNAL_CACHE_SIZE will be evaluated multiple times.
+ * @note The arguments to #XMSS_INTERNAL_CACHE_SIZE() will be evaluated multiple times.
  *
  * @param[in] cache_type    The cache type that is used.
  * @param[in] cache_level   The cache level that is to be held.
  * @param[in] param_set     The parameter set of the key for which the cache will be used.
- * @see xmss_generate_public_key for more information about the cache type and level.
+ * @see xmss_generate_public_key() for more information about the cache type and level.
  */
 #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)))
@@ -116,7 +116,7 @@ typedef struct XmssInternalCache XmssInternalCache;
  * Context for using the signature generation part of the library, with a loaded private key partition.
  *
  * @details
- * When creating an XmssKeyContext, the XMSS_KEY_CONTEXT_SIZE macro can be used to allocate the correct size.
+ * 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.
  */
@@ -144,10 +144,10 @@ typedef struct XmssKeyContext XmssKeyContext;
  * @brief
  * The size in bytes of an XmssKeyContext.
  *
- * @note The param_set argument will be evaluated multiple times.
+ * @note The `param_set` argument will be evaluated multiple times.
  *
- * @param[in] param_set             The XmssParameterSetOID that is to be used for the private key.
- * @param[in] obfuscation_setting   The XmssIndexObfuscationSetting that is to be used with the private key.
+ * @param[in] param_set             The #XmssParameterSetOID that is to be used for the private key.
+ * @param[in] obfuscation_setting   The #XmssIndexObfuscationSetting that is to be used with the private key.
  */
 #define XMSS_KEY_CONTEXT_SIZE(param_set, obfuscation_setting) \
     (4u + 4u + XMSS_SIGNING_CONTEXT_SIZE + XMSS_PRIVATE_KEY_STATELESS_PART_SIZE + \
@@ -170,7 +170,7 @@ void xmss_free_key_context(XmssKeyContext *key_context);
  * The temporary context to gather all the results of generating a public key.
  *
  * @details
- * When creating an XmssKeyGenerationContext, the XMSS_KEY_GENERATION_CONTEXT_SIZE macro may be used to allocate the
+ * 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
@@ -185,7 +185,7 @@ typedef struct XmssKeyGenerationContext XmssKeyGenerationContext;
  * The size in bytes of XmssKeyGenerationContext.
  *
  * @param[in] generation_partitions The number of calculation partitions that will divide the work.
- * @see xmss_generate_public_key for more information about generation_partitions
+ * @see xmss_generate_public_key() for more information about generation_partitions.
  */
 #define XMSS_KEY_GENERATION_CONTEXT_SIZE(generation_partitions) \
     (sizeof(void*) + sizeof(uint32_t) + sizeof(uint32_t) + sizeof(void*) + sizeof(void*) + \

include/override_sha256_generic.h

@@ -37,22 +37,22 @@
  * @details
  * This is the specialization for the SHA-256 algorithm.
  */
-void *sha256_init(void);
+void *xmss_sha256_init(void);
 
 /**
  * @copydoc XmssGenericDigestUpdate
  * @see XmssGenericDigestUpdate
  * @details
  * This is the specialization for the SHA-256 algorithm.
  */
-void sha256_update(void *restrict context, const uint8_t *restrict data, size_t data_length);
+void xmss_sha256_update(void *context, const uint8_t *data, size_t data_length);
 
 /**
  * @copydoc XmssGenericDigestFinalize
  * @see XmssGenericDigestFinalize
  * @details
  * This is the specialization for the SHA-256 algorithm.
  */
-void sha256_finalize(void *restrict context, XmssValue256 *restrict digest);
+void xmss_sha256_finalize(void *context, XmssValue256 *digest);
 
 #endif /* !XMSS_OVERRIDE_SHA256_GENERIC_H_INCLUDED */

include/override_sha256_internal.h

@@ -52,9 +52,12 @@
  * This function implements the loop body of the SHA-256($M$) function as defined by NIST FIPS 180-4, Section 6.2.2,
  * Steps 1, 2, 3, and 4.
  *
+ * For performance reasons, it is recommended not to validate the input. This function is guaranteed to be called by the
+ * library with valid input.
+ *
  * @param[in,out] Hi   Intermediate hash value $H_i$ in native form.
  * @param[in] Mi       Message block $M_i$ in native form (uint32_t[16] == 64 bytes).
  */
-void sha256_process_block(XmssNativeValue256 *restrict Hi, const uint32_t *restrict Mi);
+void xmss_sha256_process_block(XmssNativeValue256 *Hi, const uint32_t *Mi);
 
 #endif /* !XMSS_OVERRIDE_SHA256_INTERNAL_H_INCLUDED */