From 314613db8dd007c4d3b2b20e3e7410699ec6d1e9 Mon Sep 17 00:00:00 2001 From: "Matthias J. Kannwischer" Date: Mon, 17 Aug 2026 14:49:20 +0800 Subject: [PATCH 1/4] Doxygen: Render the documentation as HTML Turn the Doxygen lint config into one that renders the documentation in mldsa/ to HTML. Rendering reports the same errors the previous XML-only run did, and nothing consumed that XML, so lint now checks the documentation by building it. Signed-off-by: Matthias J. Kannwischer --- .gitignore | 2 ++ scripts/Doxyfile | 52 +++++++++++++++++++++++++++++++++++++ scripts/Doxyfile.lint | 36 ------------------------- scripts/doxygen-mainpage.md | 21 +++++++++++++++ scripts/lint | 20 +++++++------- 5 files changed, 85 insertions(+), 46 deletions(-) create mode 100644 scripts/Doxyfile delete mode 100644 scripts/Doxyfile.lint create mode 100644 scripts/doxygen-mainpage.md diff --git a/.gitignore b/.gitignore index 82ac15e8ed..fd24015dd5 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,5 @@ test/build test/acvp/.acvp-data/ # Downloaded Wycheproof test data test/wycheproof/.wycheproof-data/ +# Rendered Doxygen documentation +.doxygen-html/ diff --git a/scripts/Doxyfile b/scripts/Doxyfile new file mode 100644 index 0000000000..a5bad0ba43 --- /dev/null +++ b/scripts/Doxyfile @@ -0,0 +1,52 @@ +# Copyright (c) The mldsa-native project authors +# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT +# +# Doxygen config for mldsa-native. Run doxygen from the repository root. + +PROJECT_NAME = "mldsa-native" +PROJECT_BRIEF = "Secure, fast and portable C90 implementation of ML-DSA" + +INPUT = mldsa scripts/doxygen-mainpage.md +USE_MDFILE_AS_MAINPAGE = scripts/doxygen-mainpage.md +RECURSIVE = YES +FILE_PATTERNS = *.h *.c +OPTIMIZE_OUTPUT_FOR_C = YES +JAVADOC_AUTOBRIEF = YES + +# Document all files and their global entities. The sources have no file-level +# documentation blocks, which Doxygen would otherwise require before it picks +# up any of the macros and functions they define. +EXTRACT_ALL = YES + +GENERATE_HTML = YES +HTML_OUTPUT = .doxygen-html +GENERATE_TREEVIEW = YES +HTML_COLORSTYLE = TOGGLE +# Document members in declaration order +SORT_MEMBER_DOCS = NO +# Skip the annotated source listings; they dominate the size of the published +# site, and the sources are on GitHub. +VERBATIM_HEADERS = NO +GENERATE_LATEX = NO + +QUIET = YES + +ALIASES = "spec{1}=@par Specification^^\1" \ + "reference{1}=@par Reference^^\1" + +# Suppress false positives from project macros. The qualifiers and the +# namespace prefix are dropped from the rendered signatures, and the type of +# the context parameter is left as the configuration option that sets it. +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES +PREDEFINED = MLD_ALIGN= \ + __contract__(x)= \ + MLD_API_QUALIFIER= \ + MLD_API_MUST_CHECK_RETURN_VALUE= \ + MLD_API_NAMESPACE(sym)=sym \ + MLD_CONFIG_CONTEXT_PARAMETER + +WARN_IF_DOC_ERROR = YES +WARN_NO_PARAMDOC = YES +STRICT_PROTO_MATCHING = YES +WARN_AS_ERROR = FAIL_ON_WARNINGS diff --git a/scripts/Doxyfile.lint b/scripts/Doxyfile.lint deleted file mode 100644 index c1b882f3e5..0000000000 --- a/scripts/Doxyfile.lint +++ /dev/null @@ -1,36 +0,0 @@ -# Copyright (c) The mldsa-native project authors -# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT -# -# Doxygen lint config for mldsa-native. - -PROJECT_NAME = "mldsa-native lint" -INPUT = mldsa -RECURSIVE = YES -FILE_PATTERNS = *.h *.c -OPTIMIZE_OUTPUT_FOR_C = YES -JAVADOC_AUTOBRIEF = YES - -# Doxygen requires at least one GENERATE_* to be enabled. -GENERATE_HTML = NO -GENERATE_LATEX = NO -GENERATE_XML = YES -XML_OUTPUT = .doxylint-xml - -QUIET = YES - -ALIASES = "spec{1}=@par Specification^^\1" \ - "reference{1}=@par Reference^^\1" - -WARN_IF_DOC_ERROR = YES -WARN_IF_UNDOCUMENTED = YES -WARN_NO_PARAMDOC = YES -STRICT_PROTO_MATCHING = YES -WARN_AS_ERROR = FAIL_ON_WARNINGS - -# Suppress false positives from project macros -MACRO_EXPANSION = YES -EXPAND_ONLY_PREDEF = YES -PREDEFINED = MLD_ALIGN= \ - __contract__(x)= \ - MLD_CONFIG_CONTEXT_PARAMETER \ - MLD_CONFIG_CONTEXT_PARAMETER_TYPE=void* diff --git a/scripts/doxygen-mainpage.md b/scripts/doxygen-mainpage.md new file mode 100644 index 0000000000..dfaeee8615 --- /dev/null +++ b/scripts/doxygen-mainpage.md @@ -0,0 +1,21 @@ +[//]: # (SPDX-License-Identifier: CC-BY-4.0) + +# mldsa-native + +mldsa-native is a secure, fast and portable C90 implementation of the ML-DSA +post-quantum signature standard (FIPS 204). + +These pages are rendered from the documentation in the mldsa-native sources: + +* mldsa/mldsa_native.h declares the public API and the sizes of the + cryptographic material. +* mldsa/mldsa_native_config.h documents the build-time configuration options. +* The remaining files are internal to mldsa-native and are documented here for + the benefit of contributors and reviewers; they are not part of the public + API and may change at any time. + +Conventions shared by all public functions, such as return values, pointer +validity and the state of output buffers on error, are described in +[API-CONVENTIONS.md](https://github.com/pq-code-package/mldsa-native/blob/main/API-CONVENTIONS.md). +For everything else, including build instructions and examples, see the +[mldsa-native repository](https://github.com/pq-code-package/mldsa-native). diff --git a/scripts/lint b/scripts/lint index 27d4a91e34..48c35fdac4 100755 --- a/scripts/lint +++ b/scripts/lint @@ -359,27 +359,27 @@ check-doxygen() { if ! command -v doxygen >/dev/null; then gh_error_simple "doxygen missing" "doxygen is not installed" - error "Lint Doxygen comments" + error "Render Doxygen documentation" SUCCESS=false - gh_summary_failure "Lint Doxygen comments" + gh_summary_failure "Render Doxygen documentation" return 0 fi local out - if out=$(cd "$ROOT" && doxygen scripts/Doxyfile.lint 2>&1) && [[ -z $out ]]; then - info "Lint Doxygen comments" - gh_summary_success "Lint Doxygen comments" + if out=$(cd "$ROOT" && doxygen scripts/Doxyfile 2>&1) && [[ -z $out ]]; then + info "Render Doxygen documentation" + gh_summary_success "Render Doxygen documentation" else echo "$out" - gh_error_simple "Doxygen lint error" "$out" - error "Lint Doxygen comments" + gh_error_simple "Doxygen error" "$out" + error "Render Doxygen documentation" SUCCESS=false - gh_summary_failure "Lint Doxygen comments" + gh_summary_failure "Render Doxygen documentation" fi - rm -rf "$ROOT"/.doxylint-xml + rm -rf "$ROOT"/.doxygen-html } -gh_group_start "Linting Doxygen comments" +gh_group_start "Rendering Doxygen documentation" check-doxygen gh_group_end From f38658647b318bfb0635dbbfdc743d1455e39c6d Mon Sep 17 00:00:00 2001 From: "Matthias J. Kannwischer" Date: Mon, 17 Aug 2026 14:49:20 +0800 Subject: [PATCH 2/4] CI: Publish the Doxygen documentation to GitHub Pages Render the documentation on every change to main and commit it to the doxygen/ directory of the gh-pages branch, next to the benchmark results. The publishing step starts over on top of the branch tip should it race with the benchmark job, which writes to the same branch. Signed-off-by: Matthias J. Kannwischer --- .github/workflows/doxygen.yml | 58 +++++++++++++++++++++++++++++++++++ README.md | 2 ++ 2 files changed, 60 insertions(+) create mode 100644 .github/workflows/doxygen.yml diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml new file mode 100644 index 0000000000..d4e2c184cc --- /dev/null +++ b/.github/workflows/doxygen.yml @@ -0,0 +1,58 @@ +# Copyright (c) The mldsa-native project authors +# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT + +name: Doxygen +permissions: + contents: read +on: + workflow_dispatch: + push: + branches: ["main"] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + publish: + name: Publish documentation + if: ${{ github.repository_owner == 'pq-code-package' }} + permissions: + contents: write + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - name: Render documentation + uses: ./.github/actions/setup-shell + with: + nix-shell: ci + gh_token: ${{ secrets.GITHUB_TOKEN }} + script: | + doxygen scripts/Doxyfile + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: gh-pages + path: .gh-pages + - name: Publish to GitHub Pages + working-directory: .gh-pages + run: | + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + # The benchmark results are published to the same branch, so start + # over on top of its tip should a push race with them. + for _ in 1 2 3; do + git fetch --depth 1 origin gh-pages + git reset --quiet --hard FETCH_HEAD + rm -rf doxygen + cp -r ../.doxygen-html doxygen + git add -A doxygen + if git diff --quiet --cached; then + echo "Documentation is up to date" + exit 0 + fi + git commit --quiet -m "Update Doxygen documentation for ${GITHUB_SHA}" + if git push; then + exit 0 + fi + done + exit 1 diff --git a/README.md b/README.md index 47892ce0bc..bf3853ba9f 100644 --- a/README.md +++ b/README.md @@ -165,6 +165,8 @@ If you want to use mldsa-native, import [mldsa](mldsa) into your project's sourc See [API-CONVENTIONS.md](API-CONVENTIONS.md) for conventions that apply to all public functions, such as return values, pointer validity, and the state of output buffers on error. +The public API and the build-time configuration options are documented in the sources; for the rendered version, see the [API documentation](https://pq-code-package.github.io/mldsa-native/doxygen/). + ### Can I bring my own FIPS-202? mldsa-native relies on and comes with an implementation of FIPS-202[^FIPS202]. If your library has its own FIPS-202 implementation, you From 5b5a3d6d215c76b02eefdf52caa8ac54787c77d1 Mon Sep 17 00:00:00 2001 From: "Matthias J. Kannwischer" Date: Mon, 17 Aug 2026 14:49:20 +0800 Subject: [PATCH 3/4] Doxygen: Reference macros with # Doxygen does not link macro names that appear in a documentation block. Prefix them with '#' so that the rendered documentation links to their definition, and turn the comments on the error codes into documentation blocks, which the @retval references now point to. The configuration options are not linked: they are commented out in the default configuration, so Doxygen does not see them. - Resolves https://github.com/pq-code-package/mldsa-native/issues/1313 Signed-off-by: Matthias J. Kannwischer --- mldsa/mldsa_native.h | 316 +++++++++++++++++++++---------------------- 1 file changed, 158 insertions(+), 158 deletions(-) diff --git a/mldsa/mldsa_native.h b/mldsa/mldsa_native.h index a38a2c4154..1b24bd0a67 100644 --- a/mldsa/mldsa_native.h +++ b/mldsa/mldsa_native.h @@ -95,36 +95,36 @@ /****************************** Error codes ***********************************/ -/* Generic failure condition, reserved for failures not covered by a more +/** Generic failure condition, reserved for failures not covered by a more * specific error code. */ #define MLD_ERR_FAIL (-1) -/* An allocation failed. This can only happen if MLD_CONFIG_CUSTOM_ALLOC_FREE +/** An allocation failed. This can only happen if MLD_CONFIG_CUSTOM_ALLOC_FREE * is defined and the provided MLD_CUSTOM_ALLOC can fail. */ #define MLD_ERR_OUT_OF_MEMORY (-2) -/* An RNG failure occurred. Might be due to insufficient entropy or +/** An RNG failure occurred. Might be due to insufficient entropy or * system misconfiguration. */ #define MLD_ERR_RNG_FAIL (-3) -/* The signing rejection-sampling loop exceeded +/** The signing rejection-sampling loop exceeded * MLD_CONFIG_MAX_SIGNING_ATTEMPTS iterations without producing a valid * signature. With a FIPS 204 Appendix C compliant bound (>= 821) this * has probability < 2^-256. */ #define MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED (-4) -/* Signing was paused before completing, at the request of a caller-provided +/** Signing was paused before completing, at the request of a caller-provided * MLD_CONFIG_SIGN_HOOK_ATTEMPT hook (see mldsa_native_config.h). The caller * resumes by re-invoking signing with the same inputs; the attempt hook, * together with MLD_CONFIG_SIGN_HOOK_RESUME, decides where to continue. */ #define MLD_ERR_SIGNING_PAUSED (-5) -/* Signature verification failed: the signature is not valid for the given +/** Signature verification failed: the signature is not valid for the given * message and public key. Returned by the verification API. */ #define MLD_ERR_INVALID_SIGNATURE (-6) -/* Secret key validation failed: the secret key is malformed or internally +/** Secret key validation failed: the secret key is malformed or internally * inconsistent. Returned by pk_from_sk. */ #define MLD_ERR_INVALID_KEY (-7) -/* The Pairwise Consistency Test failed. Only possible when +/** The Pairwise Consistency Test failed. Only possible when * MLD_CONFIG_KEYGEN_PCT is enabled; signals that the freshly generated key * pair failed its sign/verify self-test. */ #define MLD_ERR_PCT_FAIL (-8) -/* An argument was invalid, e.g. an unsupported pre-hash algorithm or a context +/** An argument was invalid, e.g. an unsupported pre-hash algorithm or a context * string longer than 255 bytes. */ #define MLD_ERR_INVALID_ARG (-9) @@ -214,23 +214,23 @@ extern "C" * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * - * @retval 0 Success. - * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was - * used and an allocation via - * MLD_CUSTOM_ALLOC returned NULL. - * @retval MLD_ERR_RNG_FAIL Random number generation failed - * during the PCT. Only possible when - * MLD_CONFIG_KEYGEN_PCT is enabled. - * @retval MLD_ERR_SIGNING_PAUSED The PCT's signing step was paused by - * a MLD_CONFIG_SIGN_HOOK_ATTEMPT hook. - * This should currently never happen: - * signing hooks require - * MLD_CONFIG_NO_RANDOMIZED_API, which - * is incompatible with - * MLD_CONFIG_KEYGEN_PCT, so the two - * cannot be enabled simultaneously. - * @retval MLD_ERR_PCT_FAIL MLD_CONFIG_KEYGEN_PCT is enabled and - * the PCT check failed. + * @retval 0 Success. + * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * used and an allocation via + * MLD_CUSTOM_ALLOC returned NULL. + * @retval #MLD_ERR_RNG_FAIL Random number generation failed + * during the PCT. Only possible when + * MLD_CONFIG_KEYGEN_PCT is enabled. + * @retval #MLD_ERR_SIGNING_PAUSED The PCT's signing step was paused by + * a MLD_CONFIG_SIGN_HOOK_ATTEMPT hook. + * This should currently never happen: + * signing hooks require + * MLD_CONFIG_NO_RANDOMIZED_API, which + * is incompatible with + * MLD_CONFIG_KEYGEN_PCT, so the two + * cannot be enabled simultaneously. + * @retval #MLD_ERR_PCT_FAIL MLD_CONFIG_KEYGEN_PCT is enabled and + * the PCT check failed. */ MLD_API_QUALIFIER MLD_API_MUST_CHECK_RETURN_VALUE @@ -260,21 +260,21 @@ int MLD_API_NAMESPACE(keypair_internal)( * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * - * @retval 0 Success. - * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was - * used and an allocation via - * MLD_CUSTOM_ALLOC returned NULL. - * @retval MLD_ERR_RNG_FAIL Random number generation failed. - * @retval MLD_ERR_SIGNING_PAUSED The PCT's signing step was paused by - * a MLD_CONFIG_SIGN_HOOK_ATTEMPT hook. - * This should currently never happen: - * signing hooks require - * MLD_CONFIG_NO_RANDOMIZED_API, which - * is incompatible with - * MLD_CONFIG_KEYGEN_PCT, so the two - * cannot be enabled simultaneously. - * @retval MLD_ERR_PCT_FAIL MLD_CONFIG_KEYGEN_PCT is enabled and - * the PCT check failed. + * @retval 0 Success. + * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * used and an allocation via + * MLD_CUSTOM_ALLOC returned NULL. + * @retval #MLD_ERR_RNG_FAIL Random number generation failed. + * @retval #MLD_ERR_SIGNING_PAUSED The PCT's signing step was paused by + * a MLD_CONFIG_SIGN_HOOK_ATTEMPT hook. + * This should currently never happen: + * signing hooks require + * MLD_CONFIG_NO_RANDOMIZED_API, which + * is incompatible with + * MLD_CONFIG_KEYGEN_PCT, so the two + * cannot be enabled simultaneously. + * @retval #MLD_ERR_PCT_FAIL MLD_CONFIG_KEYGEN_PCT is enabled and + * the PCT check failed. */ MLD_API_QUALIFIER MLD_API_MUST_CHECK_RETURN_VALUE @@ -303,11 +303,11 @@ int MLD_API_NAMESPACE(keypair)( * to validate them before signing. * * @param[out] sig Pointer to buffer to hold the generated signature of - * MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] m Pointer to message to be signed (when * externalmu == 0), or to a precomputed * message representative mu (when externalmu != 0). - * @param mlen Length of m. Must equal MLDSA_CRHBYTES when + * @param mlen Length of m. Must equal #MLDSA_CRHBYTES when * externalmu != 0. * @param[in] pre Pointer to prefix string. Ignored when * externalmu != 0. @@ -318,20 +318,20 @@ int MLD_API_NAMESPACE(keypair)( * @param externalmu 0: m/mlen is the raw message; mu = H(tr, pre, m) is * computed internally. * non-zero: m points to a precomputed mu of - * MLDSA_CRHBYTES bytes; pre/prelen unused. + * #MLDSA_CRHBYTES bytes; pre/prelen unused. * @param context Application context. Only present when * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * - * @retval 0 Success. - * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was - * used and an allocation via - * MLD_CUSTOM_ALLOC returned NULL. - * @retval MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded - * MLD_CONFIG_MAX_SIGNING_ATTEMPTS - * iterations. - * @retval MLD_ERR_SIGNING_PAUSED A MLD_CONFIG_SIGN_HOOK_ATTEMPT hook - * paused signing; re-invoke to resume. + * @retval 0 Success. + * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * used and an allocation via + * MLD_CUSTOM_ALLOC returned NULL. + * @retval #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded + * MLD_CONFIG_MAX_SIGNING_ATTEMPTS + * iterations. + * @retval #MLD_ERR_SIGNING_PAUSED A MLD_CONFIG_SIGN_HOOK_ATTEMPT hook + * paused signing; re-invoke to resume. */ MLD_API_QUALIFIER MLD_API_MUST_CHECK_RETURN_VALUE @@ -361,7 +361,7 @@ int MLD_API_NAMESPACE(signature_internal)( * to validate them before signing. * * @param[out] sig Pointer to buffer to hold the generated signature of - * MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] m Pointer to message to be signed. May be NULL if * mlen == 0. * @param mlen Length of message. @@ -372,18 +372,18 @@ int MLD_API_NAMESPACE(signature_internal)( * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * - * @retval 0 Success. - * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was - * used and an allocation via - * MLD_CUSTOM_ALLOC returned NULL. - * @retval MLD_ERR_RNG_FAIL Random number generation failed. - * @retval MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded - * MLD_CONFIG_MAX_SIGNING_ATTEMPTS - * iterations. - * @retval MLD_ERR_SIGNING_PAUSED A MLD_CONFIG_SIGN_HOOK_ATTEMPT hook - * paused signing; re-invoke to resume. - * @retval MLD_ERR_INVALID_ARG The context string exceeded 255 - * bytes. + * @retval 0 Success. + * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * used and an allocation via + * MLD_CUSTOM_ALLOC returned NULL. + * @retval #MLD_ERR_RNG_FAIL Random number generation failed. + * @retval #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded + * MLD_CONFIG_MAX_SIGNING_ATTEMPTS + * iterations. + * @retval #MLD_ERR_SIGNING_PAUSED A MLD_CONFIG_SIGN_HOOK_ATTEMPT hook + * paused signing; re-invoke to resume. + * @retval #MLD_ERR_INVALID_ARG The context string exceeded 255 + * bytes. */ MLD_API_QUALIFIER MLD_API_MUST_CHECK_RETURN_VALUE @@ -411,23 +411,23 @@ int MLD_API_NAMESPACE(signature)( * to validate them before signing. * * @param[out] sig Pointer to buffer to hold the generated signature of - * MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] mu Precomputed message representative. * @param[in] sk Bit-packed secret key; assumed to be valid. * @param context Application context. Only present when * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * - * @retval 0 Success. - * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was - * used and an allocation via - * MLD_CUSTOM_ALLOC returned NULL. - * @retval MLD_ERR_RNG_FAIL Random number generation failed. - * @retval MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded - * MLD_CONFIG_MAX_SIGNING_ATTEMPTS - * iterations. - * @retval MLD_ERR_SIGNING_PAUSED A MLD_CONFIG_SIGN_HOOK_ATTEMPT hook - * paused signing; re-invoke to resume. + * @retval 0 Success. + * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * used and an allocation via + * MLD_CUSTOM_ALLOC returned NULL. + * @retval #MLD_ERR_RNG_FAIL Random number generation failed. + * @retval #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded + * MLD_CONFIG_MAX_SIGNING_ATTEMPTS + * iterations. + * @retval #MLD_ERR_SIGNING_PAUSED A MLD_CONFIG_SIGN_HOOK_ATTEMPT hook + * paused signing; re-invoke to resume. */ MLD_API_QUALIFIER MLD_API_MUST_CHECK_RETURN_VALUE @@ -452,11 +452,11 @@ int MLD_API_NAMESPACE(signature_extmu)( * @spec{Implements @[FIPS204, Algorithm 8, ML-DSA.Verify_internal].} * * @param[in] sig Pointer to input signature of - * MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] m Pointer to message (when externalmu == 0), or to a * precomputed message representative mu (when * externalmu != 0). - * @param mlen Length of m. Must equal MLDSA_CRHBYTES when + * @param mlen Length of m. Must equal #MLDSA_CRHBYTES when * externalmu != 0. * @param[in] pre Pointer to prefix string. Ignored when externalmu != 0. * @param prelen Length of prefix string. Ignored when externalmu != 0. @@ -464,16 +464,16 @@ int MLD_API_NAMESPACE(signature_extmu)( * @param externalmu 0: m/mlen is the raw message; mu = H(H(pk), pre, m) is * computed internally. * non-zero: m points to a precomputed mu of - * MLDSA_CRHBYTES bytes; pre/prelen unused. + * #MLDSA_CRHBYTES bytes; pre/prelen unused. * @param context Application context. Only present when * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * - * @retval 0 Success. - * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was - * used and an allocation via - * MLD_CUSTOM_ALLOC returned NULL. - * @retval MLD_ERR_INVALID_SIGNATURE Signature verification failed. + * @retval 0 Success. + * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * used and an allocation via + * MLD_CUSTOM_ALLOC returned NULL. + * @retval #MLD_ERR_INVALID_SIGNATURE Signature verification failed. */ MLD_API_QUALIFIER MLD_API_MUST_CHECK_RETURN_VALUE @@ -495,7 +495,7 @@ int MLD_API_NAMESPACE(verify_internal)( * @spec{Implements @[FIPS204, Algorithm 3, ML-DSA.Verify].} * * @param[in] sig Pointer to input signature of - * MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] m Pointer to message. May be NULL if mlen == 0. * @param mlen Length of message. * @param[in] ctx Pointer to context string. May be NULL if ctxlen == 0. @@ -505,12 +505,12 @@ int MLD_API_NAMESPACE(verify_internal)( * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * - * @retval 0 Success. - * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was - * used and an allocation via - * MLD_CUSTOM_ALLOC returned NULL. - * @retval MLD_ERR_INVALID_SIGNATURE Signature verification failed. - * @retval MLD_ERR_INVALID_ARG The context string exceeded 255 bytes. + * @retval 0 Success. + * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * used and an allocation via + * MLD_CUSTOM_ALLOC returned NULL. + * @retval #MLD_ERR_INVALID_SIGNATURE Signature verification failed. + * @retval #MLD_ERR_INVALID_ARG The context string exceeded 255 bytes. */ MLD_API_QUALIFIER MLD_API_MUST_CHECK_RETURN_VALUE @@ -534,18 +534,18 @@ int MLD_API_NAMESPACE(verify)( * @spec{Implements @[FIPS204, Algorithm 3, ML-DSA.Verify external mu variant].} * * @param[in] sig Pointer to input signature of - * MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] mu Precomputed message representative. * @param[in] pk Bit-packed public key. * @param context Application context. Only present when * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * - * @retval 0 Success. - * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was - * used and an allocation via - * MLD_CUSTOM_ALLOC returned NULL. - * @retval MLD_ERR_INVALID_SIGNATURE Signature verification failed. + * @retval 0 Success. + * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * used and an allocation via + * MLD_CUSTOM_ALLOC returned NULL. + * @retval #MLD_ERR_INVALID_SIGNATURE Signature verification failed. */ MLD_API_QUALIFIER MLD_API_MUST_CHECK_RETURN_VALUE @@ -575,7 +575,7 @@ int MLD_API_NAMESPACE(verify_extmu)( * MLD_PREHASH_SHA3_224, MLD_PREHASH_SHA3_256, MLD_PREHASH_SHA3_384, * MLD_PREHASH_SHA3_512, MLD_PREHASH_SHAKE_128, MLD_PREHASH_SHAKE_256. * - * MLD_PREHASH_NONE is rejected by this API. + * #MLD_PREHASH_NONE is rejected by this API. * * @warning This is an unstable API that may change in the future. If you need * a stable API use signature_pre_hash_shake256. @@ -585,12 +585,12 @@ int MLD_API_NAMESPACE(verify_extmu)( * to validate them before signing. * * @param[out] sig Pointer to buffer to hold the generated signature of - * MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] ph Pointer to pre-hashed message. * @param phlen Length of pre-hashed message. Must match the output * length of hashalg (the digest size for SHA-2/SHA-3, - * 32 bytes for MLD_PREHASH_SHAKE_128, 64 bytes for - * MLD_PREHASH_SHAKE_256). + * 32 bytes for #MLD_PREHASH_SHAKE_128, 64 bytes for + * #MLD_PREHASH_SHAKE_256). * @param[in] ctx Pointer to context string. May be NULL if ctxlen == 0. * @param ctxlen Length of context string. * @param[in] rnd Random seed. @@ -600,20 +600,20 @@ int MLD_API_NAMESPACE(verify_extmu)( * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * - * @retval 0 Success. - * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was - * used and an allocation via - * MLD_CUSTOM_ALLOC returned NULL. - * @retval MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded - * MLD_CONFIG_MAX_SIGNING_ATTEMPTS - * iterations. - * @retval MLD_ERR_SIGNING_PAUSED A MLD_CONFIG_SIGN_HOOK_ATTEMPT hook - * paused signing; re-invoke to resume. - * @retval MLD_ERR_INVALID_ARG The pre-hash algorithm was - * MLD_PREHASH_NONE or unsupported, - * phlen did not match the output - * length of hashalg, or the context - * string exceeded 255 bytes. + * @retval 0 Success. + * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * used and an allocation via + * MLD_CUSTOM_ALLOC returned NULL. + * @retval #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded + * MLD_CONFIG_MAX_SIGNING_ATTEMPTS + * iterations. + * @retval #MLD_ERR_SIGNING_PAUSED A MLD_CONFIG_SIGN_HOOK_ATTEMPT hook + * paused signing; re-invoke to resume. + * @retval #MLD_ERR_INVALID_ARG The pre-hash algorithm was + * #MLD_PREHASH_NONE or unsupported, + * phlen did not match the output + * length of hashalg, or the context + * string exceeded 255 bytes. */ MLD_API_QUALIFIER MLD_API_MUST_CHECK_RETURN_VALUE @@ -642,18 +642,18 @@ int MLD_API_NAMESPACE(signature_pre_hash_internal)( * MLD_PREHASH_SHA3_224, MLD_PREHASH_SHA3_256, MLD_PREHASH_SHA3_384, * MLD_PREHASH_SHA3_512, MLD_PREHASH_SHAKE_128, MLD_PREHASH_SHAKE_256. * - * MLD_PREHASH_NONE is rejected by this API. + * #MLD_PREHASH_NONE is rejected by this API. * * @warning This is an unstable API that may change in the future. If you need * a stable API use verify_pre_hash_shake256. * * @param[in] sig Pointer to input signature of - * MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] ph Pointer to pre-hashed message. * @param phlen Length of pre-hashed message. Must match the output * length of hashalg (the digest size for SHA-2/SHA-3, - * 32 bytes for MLD_PREHASH_SHAKE_128, 64 bytes for - * MLD_PREHASH_SHAKE_256). + * 32 bytes for #MLD_PREHASH_SHAKE_128, 64 bytes for + * #MLD_PREHASH_SHAKE_256). * @param[in] ctx Pointer to context string. May be NULL if ctxlen == 0. * @param ctxlen Length of context string. * @param[in] pk Bit-packed public key. @@ -662,16 +662,16 @@ int MLD_API_NAMESPACE(signature_pre_hash_internal)( * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * - * @retval 0 Success. - * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was - * used and an allocation via - * MLD_CUSTOM_ALLOC returned NULL. - * @retval MLD_ERR_INVALID_SIGNATURE Signature verification failed. - * @retval MLD_ERR_INVALID_ARG The pre-hash algorithm was - * MLD_PREHASH_NONE or unsupported, phlen - * did not match the output length of - * hashalg, or the context string exceeded - * 255 bytes. + * @retval 0 Success. + * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * used and an allocation via + * MLD_CUSTOM_ALLOC returned NULL. + * @retval #MLD_ERR_INVALID_SIGNATURE Signature verification failed. + * @retval #MLD_ERR_INVALID_ARG The pre-hash algorithm was + * #MLD_PREHASH_NONE or unsupported, phlen + * did not match the output length of + * hashalg, or the context string exceeded + * 255 bytes. */ MLD_API_QUALIFIER MLD_API_MUST_CHECK_RETURN_VALUE @@ -700,7 +700,7 @@ int MLD_API_NAMESPACE(verify_pre_hash_internal)( * to validate them before signing. * * @param[out] sig Pointer to buffer to hold the generated signature of - * MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] m Pointer to message to be hashed and signed. May be * NULL if mlen == 0. * @param mlen Length of message. @@ -712,17 +712,17 @@ int MLD_API_NAMESPACE(verify_pre_hash_internal)( * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * - * @retval 0 Success. - * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was - * used and an allocation via - * MLD_CUSTOM_ALLOC returned NULL. - * @retval MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded - * MLD_CONFIG_MAX_SIGNING_ATTEMPTS - * iterations. - * @retval MLD_ERR_SIGNING_PAUSED A MLD_CONFIG_SIGN_HOOK_ATTEMPT hook - * paused signing; re-invoke to resume. - * @retval MLD_ERR_INVALID_ARG The context string exceeded 255 - * bytes. + * @retval 0 Success. + * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * used and an allocation via + * MLD_CUSTOM_ALLOC returned NULL. + * @retval #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded + * MLD_CONFIG_MAX_SIGNING_ATTEMPTS + * iterations. + * @retval #MLD_ERR_SIGNING_PAUSED A MLD_CONFIG_SIGN_HOOK_ATTEMPT hook + * paused signing; re-invoke to resume. + * @retval #MLD_ERR_INVALID_ARG The context string exceeded 255 + * bytes. */ MLD_API_QUALIFIER MLD_API_MUST_CHECK_RETURN_VALUE @@ -747,7 +747,7 @@ int MLD_API_NAMESPACE(signature_pre_hash_shake256)( * the pre-hash.} * * @param[in] sig Pointer to input signature of - * MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] m Pointer to message to be hashed and verified. May be * NULL if mlen == 0. * @param mlen Length of message. @@ -758,12 +758,12 @@ int MLD_API_NAMESPACE(signature_pre_hash_shake256)( * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * - * @retval 0 Success. - * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was - * used and an allocation via - * MLD_CUSTOM_ALLOC returned NULL. - * @retval MLD_ERR_INVALID_SIGNATURE Signature verification failed. - * @retval MLD_ERR_INVALID_ARG The context string exceeded 255 bytes. + * @retval 0 Success. + * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * used and an allocation via + * MLD_CUSTOM_ALLOC returned NULL. + * @retval #MLD_ERR_INVALID_SIGNATURE Signature verification failed. + * @retval #MLD_ERR_INVALID_ARG The context string exceeded 255 bytes. */ MLD_API_QUALIFIER MLD_API_MUST_CHECK_RETURN_VALUE @@ -783,17 +783,17 @@ int MLD_API_NAMESPACE(verify_pre_hash_shake256)( /** * Prepare domain separation prefix for ML-DSA signing. * - * For pure ML-DSA (hashalg == MLD_PREHASH_NONE): + * For pure ML-DSA (hashalg == #MLD_PREHASH_NONE): * Format: 0x00 || ctxlen (1 byte) || ctx. * - * For HashML-DSA (hashalg != MLD_PREHASH_NONE): + * For HashML-DSA (hashalg != #MLD_PREHASH_NONE): * Format: 0x01 || ctxlen (1 byte) || ctx || oid (11 bytes) || ph. * * This function is useful for building incremental signing APIs. * - * @spec{For HashML-DSA (hashalg != MLD_PREHASH_NONE), implements + * @spec{For HashML-DSA (hashalg != #MLD_PREHASH_NONE), implements * @[FIPS204, Algorithm 4, line 23]. For Pure ML-DSA - * (hashalg == MLD_PREHASH_NONE), implements + * (hashalg == #MLD_PREHASH_NONE), implements * ``` * M' <- BytesToBits(IntegerToBytes(0, 1) * || IntegerToBytes(|ctx|, 1) @@ -809,7 +809,7 @@ int MLD_API_NAMESPACE(verify_pre_hash_shake256)( * length of hashalg (ignored for pure ML-DSA). * @param[in] ctx Pointer to context string. May be NULL if ctxlen == 0. * @param ctxlen Length of context string. - * @param hashalg Hash algorithm constant (MLD_PREHASH_NONE for pure + * @param hashalg Hash algorithm constant (#MLD_PREHASH_NONE for pure * ML-DSA, or MLD_PREHASH_* for HashML-DSA). * * @return The total length of the formatted prefix, or 0 on error. @@ -843,10 +843,10 @@ size_t MLD_API_NAMESPACE(prepare_domain_separation_prefix)( * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * - * @retval 0 Success. - * @retval MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was used and an - * allocation via MLD_CUSTOM_ALLOC returned NULL. - * @retval MLD_ERR_INVALID_KEY Secret key validation failed. + * @retval 0 Success. + * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was used and an + * allocation via MLD_CUSTOM_ALLOC returned NULL. + * @retval #MLD_ERR_INVALID_KEY Secret key validation failed. */ MLD_API_QUALIFIER MLD_API_MUST_CHECK_RETURN_VALUE From 3a7cb39feee035bdd5703b7d9f3d7b39df151479 Mon Sep 17 00:00:00 2001 From: "Matthias J. Kannwischer" Date: Mon, 17 Aug 2026 15:25:59 +0800 Subject: [PATCH 4/4] Doxygen: Document and link the configuration options Configuration options that are off by default are commented-out #define directives, which Doxygen does not see: their documentation blocks were attached to whichever option happened to be enabled next, leaving all but two options undocumented and MLD_CONFIG_NAMESPACE_PREFIX carrying the documentation of MLD_CONFIG_FILE. scripts/doxygen-config-filter uncomments the directives on the way into the parser and undefines them again at the end of the file, so that each option is documented in its own right while headers including the configuration file keep documenting the default configuration. With the options visible, references to them can be prefixed with '#' as well. Predefining MLD_BUILD_INTERNAL exposes the build-only options, whose documentation had never been parsed; escape the '#' in the MLD_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS block, which Doxygen reads as a request to link to a symbol named 'undef'. Signed-off-by: Matthias J. Kannwischer --- .../mldsa_native/mldsa_native_config.h | 98 +++++++------- .../mldsa_native/mldsa_native_config.h | 98 +++++++------- .../mldsa_native/mldsa_native_config.h | 98 +++++++------- .../mldsa_native/mldsa_native_config.h | 98 +++++++------- .../mldsa_native/mldsa_native_config.h | 98 +++++++------- .../mldsa_native/mldsa_native_config.h | 98 +++++++------- .../mldsa_native/mldsa_native_config.h | 98 +++++++------- .../mldsa_native/mldsa_native_config.h | 98 +++++++------- .../mldsa_native/mldsa_native_config.h | 98 +++++++------- .../mldsa_native/mldsa_native_config.h | 98 +++++++------- .../mldsa_native/mldsa_native_config.h | 98 +++++++------- .../mldsa_native/mldsa_native_config.h | 98 +++++++------- mldsa/mldsa_native.h | 120 +++++++++--------- mldsa/mldsa_native_config.h | 98 +++++++------- proofs/cbmc/mldsa_native_config_cbmc.h | 98 +++++++------- ruff.toml | 1 + scripts/Doxyfile | 7 + scripts/doxygen-config-filter | 50 ++++++++ test/configs/break_pct_config.h | 98 +++++++------- test/configs/custom_heap_alloc_config.h | 98 +++++++------- test/configs/custom_memcpy_config.h | 98 +++++++------- test/configs/custom_memset_config.h | 98 +++++++------- .../custom_native_capability_config_0.h | 98 +++++++------- .../custom_native_capability_config_1.h | 98 +++++++------- ...stom_native_capability_config_CPUID_AVX2.h | 98 +++++++------- ...native_capability_config_ID_AA64PFR1_EL1.h | 98 +++++++------- test/configs/custom_randombytes_config.h | 98 +++++++------- test/configs/custom_stdlib_config.h | 98 +++++++------- test/configs/custom_zeroize_config.h | 98 +++++++------- test/configs/low_signing_bound_config.h | 98 +++++++------- test/configs/no_asm_config.h | 98 +++++++------- test/configs/serial_fips202_config.h | 98 +++++++------- test/configs/test_alloc_config.h | 98 +++++++------- test/configs/test_sign_hook_config.h | 98 +++++++------- 34 files changed, 1588 insertions(+), 1530 deletions(-) create mode 100755 scripts/doxygen-config-filter diff --git a/examples/basic_deterministic/mldsa_native/mldsa_native_config.h b/examples/basic_deterministic/mldsa_native/mldsa_native_config.h index c8ba9d2835..9f99280ab3 100644 --- a/examples/basic_deterministic/mldsa_native/mldsa_native_config.h +++ b/examples/basic_deterministic/mldsa_native/mldsa_native_config.h @@ -47,13 +47,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -70,10 +70,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -103,9 +103,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -131,7 +131,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -142,7 +142,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -156,7 +156,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -184,7 +184,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -193,8 +193,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -221,14 +221,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -247,9 +247,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -263,7 +263,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -283,7 +283,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -299,10 +299,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -324,7 +324,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -340,7 +340,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -386,7 +386,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -400,7 +400,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -606,11 +606,11 @@ * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -637,14 +637,14 @@ * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -656,7 +656,7 @@ * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -675,7 +675,7 @@ * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -726,7 +726,7 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -736,7 +736,7 @@ * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -746,11 +746,11 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -761,13 +761,13 @@ * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -799,8 +799,8 @@ * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/examples/basic_lowram/mldsa_native/mldsa_native_config.h b/examples/basic_lowram/mldsa_native/mldsa_native_config.h index 74ecd5c654..f6bb148efc 100644 --- a/examples/basic_lowram/mldsa_native/mldsa_native_config.h +++ b/examples/basic_lowram/mldsa_native/mldsa_native_config.h @@ -46,13 +46,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -69,10 +69,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -102,9 +102,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -130,7 +130,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -141,7 +141,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -155,7 +155,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -183,7 +183,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -192,8 +192,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -220,14 +220,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -246,9 +246,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -262,7 +262,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -282,7 +282,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -298,10 +298,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -323,7 +323,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -339,7 +339,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -385,7 +385,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -399,7 +399,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -605,11 +605,11 @@ * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -636,14 +636,14 @@ * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -655,7 +655,7 @@ * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -674,7 +674,7 @@ * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -725,7 +725,7 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -735,7 +735,7 @@ * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -745,11 +745,11 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -760,13 +760,13 @@ * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -798,8 +798,8 @@ * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h b/examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h index 5dfc7a44ba..eb61222020 100644 --- a/examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h +++ b/examples/bring_your_own_fips202/mldsa_native/mldsa_native_config.h @@ -47,13 +47,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -70,10 +70,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -103,9 +103,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -131,7 +131,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -142,7 +142,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -156,7 +156,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -184,7 +184,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -193,8 +193,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -221,14 +221,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -247,9 +247,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -263,7 +263,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -283,7 +283,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -299,10 +299,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -324,7 +324,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -340,7 +340,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -386,7 +386,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -400,7 +400,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -606,11 +606,11 @@ * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -637,14 +637,14 @@ * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -656,7 +656,7 @@ * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -675,7 +675,7 @@ * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -726,7 +726,7 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -736,7 +736,7 @@ * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -746,11 +746,11 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -761,13 +761,13 @@ * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -799,8 +799,8 @@ * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/examples/bring_your_own_fips202_static/mldsa_native/mldsa_native_config.h b/examples/bring_your_own_fips202_static/mldsa_native/mldsa_native_config.h index 58823d7819..9bbedf30ec 100644 --- a/examples/bring_your_own_fips202_static/mldsa_native/mldsa_native_config.h +++ b/examples/bring_your_own_fips202_static/mldsa_native/mldsa_native_config.h @@ -48,13 +48,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -71,10 +71,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -104,9 +104,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -132,7 +132,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -143,7 +143,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -157,7 +157,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -185,7 +185,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -194,8 +194,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -222,14 +222,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -248,9 +248,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -264,7 +264,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -284,7 +284,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -300,10 +300,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -325,7 +325,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -341,7 +341,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -387,7 +387,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -401,7 +401,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -607,11 +607,11 @@ * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -638,14 +638,14 @@ * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -657,7 +657,7 @@ * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -676,7 +676,7 @@ * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -727,7 +727,7 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -737,7 +737,7 @@ * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -747,11 +747,11 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -762,13 +762,13 @@ * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -800,8 +800,8 @@ * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/examples/custom_backend/mldsa_native/mldsa_native_config.h b/examples/custom_backend/mldsa_native/mldsa_native_config.h index 30143bc27e..800523ee64 100644 --- a/examples/custom_backend/mldsa_native/mldsa_native_config.h +++ b/examples/custom_backend/mldsa_native/mldsa_native_config.h @@ -48,13 +48,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -72,10 +72,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -105,9 +105,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -133,7 +133,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -144,7 +144,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -158,7 +158,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -186,7 +186,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -195,8 +195,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -223,14 +223,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -249,9 +249,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -265,7 +265,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -285,7 +285,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -300,10 +300,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -325,7 +325,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -339,7 +339,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -382,7 +382,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -396,7 +396,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -602,11 +602,11 @@ * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -633,14 +633,14 @@ * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -652,7 +652,7 @@ * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -671,7 +671,7 @@ * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -722,7 +722,7 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -732,7 +732,7 @@ * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -742,11 +742,11 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -757,13 +757,13 @@ * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -795,8 +795,8 @@ * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/examples/monolithic_build/mldsa_native/mldsa_native_config.h b/examples/monolithic_build/mldsa_native/mldsa_native_config.h index 37e10ee576..ad1d5c66a1 100644 --- a/examples/monolithic_build/mldsa_native/mldsa_native_config.h +++ b/examples/monolithic_build/mldsa_native/mldsa_native_config.h @@ -46,13 +46,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -69,10 +69,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -102,9 +102,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -130,7 +130,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -141,7 +141,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -155,7 +155,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -183,7 +183,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -192,8 +192,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -220,14 +220,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -246,9 +246,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -262,7 +262,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -282,7 +282,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -298,10 +298,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -323,7 +323,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -339,7 +339,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -385,7 +385,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -399,7 +399,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -605,11 +605,11 @@ * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -636,14 +636,14 @@ * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -655,7 +655,7 @@ * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -674,7 +674,7 @@ * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -725,7 +725,7 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -735,7 +735,7 @@ * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -745,11 +745,11 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -760,13 +760,13 @@ * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -798,8 +798,8 @@ * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/examples/monolithic_build_multilevel/mldsa_native/mldsa_native_config.h b/examples/monolithic_build_multilevel/mldsa_native/mldsa_native_config.h index 6cfbe0a651..8d294903b6 100644 --- a/examples/monolithic_build_multilevel/mldsa_native/mldsa_native_config.h +++ b/examples/monolithic_build_multilevel/mldsa_native/mldsa_native_config.h @@ -47,13 +47,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -70,10 +70,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -103,9 +103,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -131,7 +131,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -142,7 +142,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -156,7 +156,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -184,7 +184,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -193,8 +193,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -221,14 +221,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -247,9 +247,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -263,7 +263,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -283,7 +283,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -299,10 +299,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -324,7 +324,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -340,7 +340,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -386,7 +386,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -400,7 +400,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -606,11 +606,11 @@ * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -637,14 +637,14 @@ * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -656,7 +656,7 @@ * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -675,7 +675,7 @@ * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -726,7 +726,7 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -736,7 +736,7 @@ * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -746,11 +746,11 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -761,13 +761,13 @@ * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -799,8 +799,8 @@ * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/examples/monolithic_build_multilevel_native/mldsa_native/mldsa_native_config.h b/examples/monolithic_build_multilevel_native/mldsa_native/mldsa_native_config.h index 75a39a573c..f4b6a31f6e 100644 --- a/examples/monolithic_build_multilevel_native/mldsa_native/mldsa_native_config.h +++ b/examples/monolithic_build_multilevel_native/mldsa_native/mldsa_native_config.h @@ -51,13 +51,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -74,10 +74,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -107,9 +107,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -135,7 +135,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -146,7 +146,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -160,7 +160,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -188,7 +188,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -197,8 +197,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -225,14 +225,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -251,9 +251,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -267,7 +267,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -287,7 +287,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -301,10 +301,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -326,7 +326,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -340,7 +340,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -386,7 +386,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -400,7 +400,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -612,11 +612,11 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -643,14 +643,14 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -662,7 +662,7 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -681,7 +681,7 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -732,7 +732,7 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -742,7 +742,7 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -752,11 +752,11 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -767,13 +767,13 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -805,8 +805,8 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/examples/monolithic_build_native/mldsa_native/mldsa_native_config.h b/examples/monolithic_build_native/mldsa_native/mldsa_native_config.h index 407768cfc9..6bd0276ce9 100644 --- a/examples/monolithic_build_native/mldsa_native/mldsa_native_config.h +++ b/examples/monolithic_build_native/mldsa_native/mldsa_native_config.h @@ -46,13 +46,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -69,10 +69,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -102,9 +102,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -130,7 +130,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -141,7 +141,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -155,7 +155,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -183,7 +183,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -192,8 +192,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -220,14 +220,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -246,9 +246,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -262,7 +262,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -282,7 +282,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -298,10 +298,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -323,7 +323,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -339,7 +339,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -385,7 +385,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -399,7 +399,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -605,11 +605,11 @@ * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -636,14 +636,14 @@ * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -655,7 +655,7 @@ * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -674,7 +674,7 @@ * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -725,7 +725,7 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -735,7 +735,7 @@ * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -745,11 +745,11 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -760,13 +760,13 @@ * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -798,8 +798,8 @@ * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/examples/multilevel_build/mldsa_native/mldsa_native_config.h b/examples/multilevel_build/mldsa_native/mldsa_native_config.h index 6b37f22bbb..fedfb4a3c7 100644 --- a/examples/multilevel_build/mldsa_native/mldsa_native_config.h +++ b/examples/multilevel_build/mldsa_native/mldsa_native_config.h @@ -46,13 +46,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -69,10 +69,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -102,9 +102,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -130,7 +130,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -141,7 +141,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -155,7 +155,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -183,7 +183,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -192,8 +192,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -220,14 +220,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -246,9 +246,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -262,7 +262,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -282,7 +282,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -298,10 +298,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -323,7 +323,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -339,7 +339,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -385,7 +385,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -399,7 +399,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -605,11 +605,11 @@ * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -636,14 +636,14 @@ * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -655,7 +655,7 @@ * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -674,7 +674,7 @@ * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -725,7 +725,7 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -735,7 +735,7 @@ * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -745,11 +745,11 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -760,13 +760,13 @@ * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -798,8 +798,8 @@ * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/examples/multilevel_build_native/mldsa_native/mldsa_native_config.h b/examples/multilevel_build_native/mldsa_native/mldsa_native_config.h index 17c704448a..59b5163e82 100644 --- a/examples/multilevel_build_native/mldsa_native/mldsa_native_config.h +++ b/examples/multilevel_build_native/mldsa_native/mldsa_native_config.h @@ -48,13 +48,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -71,10 +71,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -104,9 +104,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -132,7 +132,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -143,7 +143,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -157,7 +157,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -185,7 +185,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -194,8 +194,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -222,14 +222,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -248,9 +248,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -264,7 +264,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -284,7 +284,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -298,10 +298,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -323,7 +323,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -337,7 +337,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -383,7 +383,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -397,7 +397,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -603,11 +603,11 @@ * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -634,14 +634,14 @@ * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -653,7 +653,7 @@ * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -672,7 +672,7 @@ * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -723,7 +723,7 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -733,7 +733,7 @@ * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -743,11 +743,11 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -758,13 +758,13 @@ * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -796,8 +796,8 @@ * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/examples/restartable_sign/mldsa_native/mldsa_native_config.h b/examples/restartable_sign/mldsa_native/mldsa_native_config.h index fc7237527d..888ce7dedb 100644 --- a/examples/restartable_sign/mldsa_native/mldsa_native_config.h +++ b/examples/restartable_sign/mldsa_native/mldsa_native_config.h @@ -48,13 +48,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -71,10 +71,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -104,9 +104,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -132,7 +132,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -143,7 +143,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -157,7 +157,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -185,7 +185,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -194,8 +194,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -222,14 +222,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -248,9 +248,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -264,7 +264,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -284,7 +284,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -300,10 +300,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -325,7 +325,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -341,7 +341,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -387,7 +387,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -401,7 +401,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -607,11 +607,11 @@ * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -638,14 +638,14 @@ * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -657,7 +657,7 @@ * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -676,7 +676,7 @@ * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -727,7 +727,7 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -737,7 +737,7 @@ * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -747,11 +747,11 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -762,13 +762,13 @@ * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -800,8 +800,8 @@ * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/mldsa/mldsa_native.h b/mldsa/mldsa_native.h index 1b24bd0a67..59c6577400 100644 --- a/mldsa/mldsa_native.h +++ b/mldsa/mldsa_native.h @@ -105,7 +105,7 @@ * system misconfiguration. */ #define MLD_ERR_RNG_FAIL (-3) /** The signing rejection-sampling loop exceeded - * MLD_CONFIG_MAX_SIGNING_ATTEMPTS iterations without producing a valid + * #MLD_CONFIG_MAX_SIGNING_ATTEMPTS iterations without producing a valid * signature. With a FIPS 204 Appendix C compliant bound (>= 821) this * has probability < 2^-256. */ #define MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED (-4) @@ -121,7 +121,7 @@ * inconsistent. Returned by pk_from_sk. */ #define MLD_ERR_INVALID_KEY (-7) /** The Pairwise Consistency Test failed. Only possible when - * MLD_CONFIG_KEYGEN_PCT is enabled; signals that the freshly generated key + * #MLD_CONFIG_KEYGEN_PCT is enabled; signals that the freshly generated key * pair failed its sign/verify self-test. */ #define MLD_ERR_PCT_FAIL (-8) /** An argument was invalid, e.g. an unsupported pre-hash algorithm or a context @@ -199,7 +199,7 @@ extern "C" /** * Generate a public-private key pair from a seed. * - * When MLD_CONFIG_KEYGEN_PCT is set, performs a Pairwise Consistency Test + * When #MLD_CONFIG_KEYGEN_PCT is set, performs a Pairwise Consistency Test * (PCT) as required by FIPS 140-3 IG. * * @warning The seed must be generated by a cryptographically secure random @@ -211,25 +211,25 @@ extern "C" * @param[out] sk Output private key. * @param[in] seed Input random seed. * @param context Application context. Only present when - * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. + * #MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * * @retval 0 Success. - * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * @retval #MLD_ERR_OUT_OF_MEMORY #MLD_CONFIG_CUSTOM_ALLOC_FREE was * used and an allocation via * MLD_CUSTOM_ALLOC returned NULL. * @retval #MLD_ERR_RNG_FAIL Random number generation failed * during the PCT. Only possible when - * MLD_CONFIG_KEYGEN_PCT is enabled. + * #MLD_CONFIG_KEYGEN_PCT is enabled. * @retval #MLD_ERR_SIGNING_PAUSED The PCT's signing step was paused by * a MLD_CONFIG_SIGN_HOOK_ATTEMPT hook. * This should currently never happen: * signing hooks require - * MLD_CONFIG_NO_RANDOMIZED_API, which + * #MLD_CONFIG_NO_RANDOMIZED_API, which * is incompatible with - * MLD_CONFIG_KEYGEN_PCT, so the two + * #MLD_CONFIG_KEYGEN_PCT, so the two * cannot be enabled simultaneously. - * @retval #MLD_ERR_PCT_FAIL MLD_CONFIG_KEYGEN_PCT is enabled and + * @retval #MLD_ERR_PCT_FAIL #MLD_CONFIG_KEYGEN_PCT is enabled and * the PCT check failed. */ MLD_API_QUALIFIER @@ -249,7 +249,7 @@ int MLD_API_NAMESPACE(keypair_internal)( /** * Generate a public-private key pair. * - * When MLD_CONFIG_KEYGEN_PCT is set, performs a Pairwise Consistency Test + * When #MLD_CONFIG_KEYGEN_PCT is set, performs a Pairwise Consistency Test * (PCT) as required by FIPS 140-3 IG. * * @spec{Implements @[FIPS204, Algorithm 1, ML-DSA.KeyGen].} @@ -257,11 +257,11 @@ int MLD_API_NAMESPACE(keypair_internal)( * @param[out] pk Output public key. * @param[out] sk Output private key. * @param context Application context. Only present when - * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. + * #MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * * @retval 0 Success. - * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * @retval #MLD_ERR_OUT_OF_MEMORY #MLD_CONFIG_CUSTOM_ALLOC_FREE was * used and an allocation via * MLD_CUSTOM_ALLOC returned NULL. * @retval #MLD_ERR_RNG_FAIL Random number generation failed. @@ -269,11 +269,11 @@ int MLD_API_NAMESPACE(keypair_internal)( * a MLD_CONFIG_SIGN_HOOK_ATTEMPT hook. * This should currently never happen: * signing hooks require - * MLD_CONFIG_NO_RANDOMIZED_API, which + * #MLD_CONFIG_NO_RANDOMIZED_API, which * is incompatible with - * MLD_CONFIG_KEYGEN_PCT, so the two + * #MLD_CONFIG_KEYGEN_PCT, so the two * cannot be enabled simultaneously. - * @retval #MLD_ERR_PCT_FAIL MLD_CONFIG_KEYGEN_PCT is enabled and + * @retval #MLD_ERR_PCT_FAIL #MLD_CONFIG_KEYGEN_PCT is enabled and * the PCT check failed. */ MLD_API_QUALIFIER @@ -303,7 +303,7 @@ int MLD_API_NAMESPACE(keypair)( * to validate them before signing. * * @param[out] sig Pointer to buffer to hold the generated signature of - * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(#MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] m Pointer to message to be signed (when * externalmu == 0), or to a precomputed * message representative mu (when externalmu != 0). @@ -320,11 +320,11 @@ int MLD_API_NAMESPACE(keypair)( * non-zero: m points to a precomputed mu of * #MLDSA_CRHBYTES bytes; pre/prelen unused. * @param context Application context. Only present when - * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. + * #MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * * @retval 0 Success. - * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * @retval #MLD_ERR_OUT_OF_MEMORY #MLD_CONFIG_CUSTOM_ALLOC_FREE was * used and an allocation via * MLD_CUSTOM_ALLOC returned NULL. * @retval #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded @@ -361,7 +361,7 @@ int MLD_API_NAMESPACE(signature_internal)( * to validate them before signing. * * @param[out] sig Pointer to buffer to hold the generated signature of - * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(#MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] m Pointer to message to be signed. May be NULL if * mlen == 0. * @param mlen Length of message. @@ -369,11 +369,11 @@ int MLD_API_NAMESPACE(signature_internal)( * @param ctxlen Length of context string. Should be <= 255. * @param[in] sk Bit-packed secret key; assumed to be valid. * @param context Application context. Only present when - * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. + * #MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * * @retval 0 Success. - * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * @retval #MLD_ERR_OUT_OF_MEMORY #MLD_CONFIG_CUSTOM_ALLOC_FREE was * used and an allocation via * MLD_CUSTOM_ALLOC returned NULL. * @retval #MLD_ERR_RNG_FAIL Random number generation failed. @@ -411,15 +411,15 @@ int MLD_API_NAMESPACE(signature)( * to validate them before signing. * * @param[out] sig Pointer to buffer to hold the generated signature of - * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(#MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] mu Precomputed message representative. * @param[in] sk Bit-packed secret key; assumed to be valid. * @param context Application context. Only present when - * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. + * #MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * * @retval 0 Success. - * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * @retval #MLD_ERR_OUT_OF_MEMORY #MLD_CONFIG_CUSTOM_ALLOC_FREE was * used and an allocation via * MLD_CUSTOM_ALLOC returned NULL. * @retval #MLD_ERR_RNG_FAIL Random number generation failed. @@ -452,7 +452,7 @@ int MLD_API_NAMESPACE(signature_extmu)( * @spec{Implements @[FIPS204, Algorithm 8, ML-DSA.Verify_internal].} * * @param[in] sig Pointer to input signature of - * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(#MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] m Pointer to message (when externalmu == 0), or to a * precomputed message representative mu (when * externalmu != 0). @@ -466,11 +466,11 @@ int MLD_API_NAMESPACE(signature_extmu)( * non-zero: m points to a precomputed mu of * #MLDSA_CRHBYTES bytes; pre/prelen unused. * @param context Application context. Only present when - * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. + * #MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * * @retval 0 Success. - * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * @retval #MLD_ERR_OUT_OF_MEMORY #MLD_CONFIG_CUSTOM_ALLOC_FREE was * used and an allocation via * MLD_CUSTOM_ALLOC returned NULL. * @retval #MLD_ERR_INVALID_SIGNATURE Signature verification failed. @@ -495,18 +495,18 @@ int MLD_API_NAMESPACE(verify_internal)( * @spec{Implements @[FIPS204, Algorithm 3, ML-DSA.Verify].} * * @param[in] sig Pointer to input signature of - * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(#MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] m Pointer to message. May be NULL if mlen == 0. * @param mlen Length of message. * @param[in] ctx Pointer to context string. May be NULL if ctxlen == 0. * @param ctxlen Length of context string. * @param[in] pk Bit-packed public key. * @param context Application context. Only present when - * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. + * #MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * * @retval 0 Success. - * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * @retval #MLD_ERR_OUT_OF_MEMORY #MLD_CONFIG_CUSTOM_ALLOC_FREE was * used and an allocation via * MLD_CUSTOM_ALLOC returned NULL. * @retval #MLD_ERR_INVALID_SIGNATURE Signature verification failed. @@ -534,15 +534,15 @@ int MLD_API_NAMESPACE(verify)( * @spec{Implements @[FIPS204, Algorithm 3, ML-DSA.Verify external mu variant].} * * @param[in] sig Pointer to input signature of - * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(#MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] mu Precomputed message representative. * @param[in] pk Bit-packed public key. * @param context Application context. Only present when - * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. + * #MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * * @retval 0 Success. - * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * @retval #MLD_ERR_OUT_OF_MEMORY #MLD_CONFIG_CUSTOM_ALLOC_FREE was * used and an allocation via * MLD_CUSTOM_ALLOC returned NULL. * @retval #MLD_ERR_INVALID_SIGNATURE Signature verification failed. @@ -585,7 +585,7 @@ int MLD_API_NAMESPACE(verify_extmu)( * to validate them before signing. * * @param[out] sig Pointer to buffer to hold the generated signature of - * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(#MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] ph Pointer to pre-hashed message. * @param phlen Length of pre-hashed message. Must match the output * length of hashalg (the digest size for SHA-2/SHA-3, @@ -597,11 +597,11 @@ int MLD_API_NAMESPACE(verify_extmu)( * @param[in] sk Bit-packed secret key; assumed to be valid. * @param hashalg Hash algorithm constant (one of MLD_PREHASH_*). * @param context Application context. Only present when - * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. + * #MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * * @retval 0 Success. - * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * @retval #MLD_ERR_OUT_OF_MEMORY #MLD_CONFIG_CUSTOM_ALLOC_FREE was * used and an allocation via * MLD_CUSTOM_ALLOC returned NULL. * @retval #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded @@ -648,7 +648,7 @@ int MLD_API_NAMESPACE(signature_pre_hash_internal)( * a stable API use verify_pre_hash_shake256. * * @param[in] sig Pointer to input signature of - * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(#MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] ph Pointer to pre-hashed message. * @param phlen Length of pre-hashed message. Must match the output * length of hashalg (the digest size for SHA-2/SHA-3, @@ -659,11 +659,11 @@ int MLD_API_NAMESPACE(signature_pre_hash_internal)( * @param[in] pk Bit-packed public key. * @param hashalg Hash algorithm constant (one of MLD_PREHASH_*). * @param context Application context. Only present when - * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. + * #MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * * @retval 0 Success. - * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * @retval #MLD_ERR_OUT_OF_MEMORY #MLD_CONFIG_CUSTOM_ALLOC_FREE was * used and an allocation via * MLD_CUSTOM_ALLOC returned NULL. * @retval #MLD_ERR_INVALID_SIGNATURE Signature verification failed. @@ -700,7 +700,7 @@ int MLD_API_NAMESPACE(verify_pre_hash_internal)( * to validate them before signing. * * @param[out] sig Pointer to buffer to hold the generated signature of - * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(#MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] m Pointer to message to be hashed and signed. May be * NULL if mlen == 0. * @param mlen Length of message. @@ -709,11 +709,11 @@ int MLD_API_NAMESPACE(verify_pre_hash_internal)( * @param[in] rnd Random seed. * @param[in] sk Bit-packed secret key; assumed to be valid. * @param context Application context. Only present when - * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. + * #MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * * @retval 0 Success. - * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * @retval #MLD_ERR_OUT_OF_MEMORY #MLD_CONFIG_CUSTOM_ALLOC_FREE was * used and an allocation via * MLD_CUSTOM_ALLOC returned NULL. * @retval #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED The rejection-sampling loop exceeded @@ -747,7 +747,7 @@ int MLD_API_NAMESPACE(signature_pre_hash_shake256)( * the pre-hash.} * * @param[in] sig Pointer to input signature of - * #MLDSA_BYTES(MLD_CONFIG_PARAMETER_SET) bytes. + * #MLDSA_BYTES(#MLD_CONFIG_PARAMETER_SET) bytes. * @param[in] m Pointer to message to be hashed and verified. May be * NULL if mlen == 0. * @param mlen Length of message. @@ -755,11 +755,11 @@ int MLD_API_NAMESPACE(signature_pre_hash_shake256)( * @param ctxlen Length of context string. * @param[in] pk Bit-packed public key. * @param context Application context. Only present when - * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. + * #MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * * @retval 0 Success. - * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was + * @retval #MLD_ERR_OUT_OF_MEMORY #MLD_CONFIG_CUSTOM_ALLOC_FREE was * used and an allocation via * MLD_CUSTOM_ALLOC returned NULL. * @retval #MLD_ERR_INVALID_SIGNATURE Signature verification failed. @@ -840,11 +840,11 @@ size_t MLD_API_NAMESPACE(prepare_domain_separation_prefix)( * @param[out] pk Output public key. * @param[in] sk Input secret key. * @param context Application context. Only present when - * MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE. + * #MLD_CONFIG_CONTEXT_PARAMETER is defined; type set by + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE. * * @retval 0 Success. - * @retval #MLD_ERR_OUT_OF_MEMORY MLD_CONFIG_CUSTOM_ALLOC_FREE was used and an + * @retval #MLD_ERR_OUT_OF_MEMORY #MLD_CONFIG_CUSTOM_ALLOC_FREE was used and an * allocation via MLD_CUSTOM_ALLOC returned NULL. * @retval #MLD_ERR_INVALID_KEY Secret key validation failed. */ diff --git a/mldsa/mldsa_native_config.h b/mldsa/mldsa_native_config.h index 43803dee5a..425d747831 100644 --- a/mldsa/mldsa_native_config.h +++ b/mldsa/mldsa_native_config.h @@ -30,13 +30,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -53,10 +53,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -87,9 +87,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -115,7 +115,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -126,7 +126,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -140,7 +140,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -168,7 +168,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -177,8 +177,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -205,14 +205,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -231,9 +231,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -247,7 +247,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -267,7 +267,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -283,10 +283,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -308,7 +308,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -324,7 +324,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -370,7 +370,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -384,7 +384,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -590,11 +590,11 @@ * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -621,14 +621,14 @@ * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -640,7 +640,7 @@ * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -659,7 +659,7 @@ * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -710,7 +710,7 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -720,7 +720,7 @@ * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -730,11 +730,11 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -745,13 +745,13 @@ * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -783,8 +783,8 @@ * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/proofs/cbmc/mldsa_native_config_cbmc.h b/proofs/cbmc/mldsa_native_config_cbmc.h index dbb0035d92..5bf5e6cb78 100644 --- a/proofs/cbmc/mldsa_native_config_cbmc.h +++ b/proofs/cbmc/mldsa_native_config_cbmc.h @@ -49,13 +49,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -72,10 +72,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -105,9 +105,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -133,7 +133,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -144,7 +144,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -158,7 +158,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -186,7 +186,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -195,8 +195,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -223,14 +223,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -249,9 +249,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -265,7 +265,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -285,7 +285,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -301,10 +301,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -326,7 +326,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -342,7 +342,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -388,7 +388,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -402,7 +402,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -614,11 +614,11 @@ __contract__( * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -645,14 +645,14 @@ __contract__( * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ #define MLD_CONFIG_KEYGEN_PCT @@ -664,7 +664,7 @@ __contract__( * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -683,7 +683,7 @@ __contract__( * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -734,7 +734,7 @@ __contract__( * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -744,7 +744,7 @@ __contract__( * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -754,11 +754,11 @@ __contract__( * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -769,13 +769,13 @@ __contract__( * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -807,8 +807,8 @@ __contract__( * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/ruff.toml b/ruff.toml index b4c7ede520..2095aedc73 100644 --- a/ruff.toml +++ b/ruff.toml @@ -10,6 +10,7 @@ extend-include = [ "scripts/check-contracts", "scripts/check-magic", "scripts/check-namespace", + "scripts/doxygen-config-filter", "scripts/simpasm", "scripts/stack", "scripts/tests", diff --git a/scripts/Doxyfile b/scripts/Doxyfile index a5bad0ba43..dd1c65fc0c 100644 --- a/scripts/Doxyfile +++ b/scripts/Doxyfile @@ -34,6 +34,12 @@ QUIET = YES ALIASES = "spec{1}=@par Specification^^\1" \ "reference{1}=@par Reference^^\1" +# Configuration options that are off by default are commented out; uncomment +# them so that each option is documented in its own right. The source browser +# is exempt and keeps showing the file as it is. +FILTER_PATTERNS = *mldsa_native_config.h=scripts/doxygen-config-filter +FILTER_SOURCE_FILES = NO + # Suppress false positives from project macros. The qualifiers and the # namespace prefix are dropped from the rendered signatures, and the type of # the context parameter is left as the configuration option that sets it. @@ -44,6 +50,7 @@ PREDEFINED = MLD_ALIGN= \ MLD_API_QUALIFIER= \ MLD_API_MUST_CHECK_RETURN_VALUE= \ MLD_API_NAMESPACE(sym)=sym \ + MLD_BUILD_INTERNAL \ MLD_CONFIG_CONTEXT_PARAMETER WARN_IF_DOC_ERROR = YES diff --git a/scripts/doxygen-config-filter b/scripts/doxygen-config-filter new file mode 100755 index 0000000000..f7b8fc28b9 --- /dev/null +++ b/scripts/doxygen-config-filter @@ -0,0 +1,50 @@ +#!/usr/bin/env python3 +# Copyright (c) The mldsa-native project authors +# SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT + +# +# Doxygen input filter for mldsa/mldsa_native_config.h +# +# Configuration options that are off by default are written as commented-out +# #define directives. Doxygen only binds a documentation block to a macro it +# can see, so without this filter the block of a disabled option is attached +# to whichever option happens to be enabled next. Uncomment the directives so +# that every option is documented in its own right; any example code following +# the directive stays commented out. +# +# The options are undefined again at the end of the file: Doxygen documents +# them either way, and headers including the configuration file keep +# documenting the default configuration rather than one with every option +# enabled. +# + +import re +import sys + +_RE_DEFINE = re.compile(r"^/\* (#define (MLD_CONFIG_\w+).*?)( \*/)?$") + + +def unhide_config_options(lines): + options = [] + for line in lines: + m = _RE_DEFINE.match(line) + if m is None: + yield line + continue + options.append(m.group(2)) + yield m.group(1) + # Reopen the comment if the directive started a multi-line block. + if m.group(3) is None: + yield "/*" + for option in options: + yield "#undef " + option + + +def main(): + with open(sys.argv[1], encoding="utf-8") as f: + lines = f.read().splitlines() + print("\n".join(unhide_config_options(lines))) + + +if __name__ == "__main__": + main() diff --git a/test/configs/break_pct_config.h b/test/configs/break_pct_config.h index 7f7214b901..c6897fb210 100644 --- a/test/configs/break_pct_config.h +++ b/test/configs/break_pct_config.h @@ -46,13 +46,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -69,10 +69,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -103,9 +103,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -131,7 +131,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -142,7 +142,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -156,7 +156,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -184,7 +184,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -193,8 +193,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -221,14 +221,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -247,9 +247,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -263,7 +263,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -283,7 +283,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -299,10 +299,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -324,7 +324,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -340,7 +340,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -386,7 +386,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -400,7 +400,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -606,11 +606,11 @@ * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -637,14 +637,14 @@ * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ #define MLD_CONFIG_KEYGEN_PCT @@ -656,7 +656,7 @@ * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -679,7 +679,7 @@ static MLD_INLINE int mld_break_pct(void) * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -730,7 +730,7 @@ static MLD_INLINE int mld_break_pct(void) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -740,7 +740,7 @@ static MLD_INLINE int mld_break_pct(void) * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -750,11 +750,11 @@ static MLD_INLINE int mld_break_pct(void) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -765,13 +765,13 @@ static MLD_INLINE int mld_break_pct(void) * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -803,8 +803,8 @@ static MLD_INLINE int mld_break_pct(void) * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/test/configs/custom_heap_alloc_config.h b/test/configs/custom_heap_alloc_config.h index 1890789180..8a152af15a 100644 --- a/test/configs/custom_heap_alloc_config.h +++ b/test/configs/custom_heap_alloc_config.h @@ -45,13 +45,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -68,10 +68,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -102,9 +102,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -130,7 +130,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -141,7 +141,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -155,7 +155,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -183,7 +183,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -192,8 +192,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -220,14 +220,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -246,9 +246,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -262,7 +262,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -282,7 +282,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -298,10 +298,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -323,7 +323,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -339,7 +339,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -385,7 +385,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -399,7 +399,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -623,11 +623,11 @@ static inline void *mld_posix_memalign(size_t align, size_t sz) * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -654,14 +654,14 @@ static inline void *mld_posix_memalign(size_t align, size_t sz) * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -673,7 +673,7 @@ static inline void *mld_posix_memalign(size_t align, size_t sz) * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -692,7 +692,7 @@ static inline void *mld_posix_memalign(size_t align, size_t sz) * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -743,7 +743,7 @@ static inline void *mld_posix_memalign(size_t align, size_t sz) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -753,7 +753,7 @@ static inline void *mld_posix_memalign(size_t align, size_t sz) * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -763,11 +763,11 @@ static inline void *mld_posix_memalign(size_t align, size_t sz) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -778,13 +778,13 @@ static inline void *mld_posix_memalign(size_t align, size_t sz) * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -816,8 +816,8 @@ static inline void *mld_posix_memalign(size_t align, size_t sz) * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/test/configs/custom_memcpy_config.h b/test/configs/custom_memcpy_config.h index 2422680e1d..5b777e6d53 100644 --- a/test/configs/custom_memcpy_config.h +++ b/test/configs/custom_memcpy_config.h @@ -45,13 +45,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -68,10 +68,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -102,9 +102,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -130,7 +130,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -141,7 +141,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -155,7 +155,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -183,7 +183,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -192,8 +192,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -220,14 +220,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -246,9 +246,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -262,7 +262,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -282,7 +282,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -298,10 +298,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -323,7 +323,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -339,7 +339,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -385,7 +385,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -399,7 +399,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -613,11 +613,11 @@ static MLD_INLINE void *mld_memcpy(void *dest, const void *src, size_t n) * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -644,14 +644,14 @@ static MLD_INLINE void *mld_memcpy(void *dest, const void *src, size_t n) * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -663,7 +663,7 @@ static MLD_INLINE void *mld_memcpy(void *dest, const void *src, size_t n) * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -682,7 +682,7 @@ static MLD_INLINE void *mld_memcpy(void *dest, const void *src, size_t n) * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -733,7 +733,7 @@ static MLD_INLINE void *mld_memcpy(void *dest, const void *src, size_t n) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -743,7 +743,7 @@ static MLD_INLINE void *mld_memcpy(void *dest, const void *src, size_t n) * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -753,11 +753,11 @@ static MLD_INLINE void *mld_memcpy(void *dest, const void *src, size_t n) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -768,13 +768,13 @@ static MLD_INLINE void *mld_memcpy(void *dest, const void *src, size_t n) * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -806,8 +806,8 @@ static MLD_INLINE void *mld_memcpy(void *dest, const void *src, size_t n) * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/test/configs/custom_memset_config.h b/test/configs/custom_memset_config.h index 6f876fb6d2..3bde35683c 100644 --- a/test/configs/custom_memset_config.h +++ b/test/configs/custom_memset_config.h @@ -45,13 +45,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -68,10 +68,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -102,9 +102,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -130,7 +130,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -141,7 +141,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -155,7 +155,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -183,7 +183,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -192,8 +192,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -220,14 +220,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -246,9 +246,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -262,7 +262,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -282,7 +282,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -298,10 +298,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -323,7 +323,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -339,7 +339,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -385,7 +385,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -399,7 +399,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -612,11 +612,11 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -643,14 +643,14 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -662,7 +662,7 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -681,7 +681,7 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -732,7 +732,7 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -742,7 +742,7 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -752,11 +752,11 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -767,13 +767,13 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -805,8 +805,8 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/test/configs/custom_native_capability_config_0.h b/test/configs/custom_native_capability_config_0.h index 29da7faa3c..12b59acc48 100644 --- a/test/configs/custom_native_capability_config_0.h +++ b/test/configs/custom_native_capability_config_0.h @@ -46,13 +46,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -69,10 +69,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -103,9 +103,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -131,7 +131,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -142,7 +142,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -156,7 +156,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -184,7 +184,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -193,8 +193,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -221,14 +221,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -247,9 +247,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -263,7 +263,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -283,7 +283,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -299,10 +299,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -324,7 +324,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -340,7 +340,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -386,7 +386,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -400,7 +400,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -612,11 +612,11 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -643,14 +643,14 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -662,7 +662,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -681,7 +681,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -732,7 +732,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -742,7 +742,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -752,11 +752,11 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -767,13 +767,13 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -805,8 +805,8 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/test/configs/custom_native_capability_config_1.h b/test/configs/custom_native_capability_config_1.h index 111ffff1ec..2602abd5b3 100644 --- a/test/configs/custom_native_capability_config_1.h +++ b/test/configs/custom_native_capability_config_1.h @@ -46,13 +46,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -69,10 +69,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -103,9 +103,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -131,7 +131,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -142,7 +142,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -156,7 +156,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -184,7 +184,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -193,8 +193,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -221,14 +221,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -247,9 +247,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -263,7 +263,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -283,7 +283,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -299,10 +299,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -324,7 +324,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -340,7 +340,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -386,7 +386,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -400,7 +400,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -611,11 +611,11 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -642,14 +642,14 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -661,7 +661,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -680,7 +680,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -731,7 +731,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -741,7 +741,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -751,11 +751,11 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -766,13 +766,13 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -804,8 +804,8 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/test/configs/custom_native_capability_config_CPUID_AVX2.h b/test/configs/custom_native_capability_config_CPUID_AVX2.h index 94f0643508..6d0b1ef556 100644 --- a/test/configs/custom_native_capability_config_CPUID_AVX2.h +++ b/test/configs/custom_native_capability_config_CPUID_AVX2.h @@ -46,13 +46,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -69,10 +69,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -103,9 +103,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -131,7 +131,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -142,7 +142,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -156,7 +156,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -184,7 +184,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -193,8 +193,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -221,14 +221,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -247,9 +247,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -263,7 +263,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -283,7 +283,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -299,10 +299,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -324,7 +324,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -340,7 +340,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -386,7 +386,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -400,7 +400,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -643,11 +643,11 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -674,14 +674,14 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -693,7 +693,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -712,7 +712,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -763,7 +763,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -773,7 +773,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -783,11 +783,11 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -798,13 +798,13 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -836,8 +836,8 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/test/configs/custom_native_capability_config_ID_AA64PFR1_EL1.h b/test/configs/custom_native_capability_config_ID_AA64PFR1_EL1.h index d96f35b440..1d0dc69bae 100644 --- a/test/configs/custom_native_capability_config_ID_AA64PFR1_EL1.h +++ b/test/configs/custom_native_capability_config_ID_AA64PFR1_EL1.h @@ -46,13 +46,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -69,10 +69,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -103,9 +103,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -131,7 +131,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -142,7 +142,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -156,7 +156,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -184,7 +184,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -193,8 +193,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -221,14 +221,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -247,9 +247,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -263,7 +263,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -283,7 +283,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -299,10 +299,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -324,7 +324,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -340,7 +340,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -386,7 +386,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -400,7 +400,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -643,11 +643,11 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -674,14 +674,14 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -693,7 +693,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -712,7 +712,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -763,7 +763,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -773,7 +773,7 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -783,11 +783,11 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -798,13 +798,13 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -836,8 +836,8 @@ static MLD_INLINE int mld_sys_check_capability(mld_sys_cap cap) * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/test/configs/custom_randombytes_config.h b/test/configs/custom_randombytes_config.h index e6d0e3f5ca..7d8077b40b 100644 --- a/test/configs/custom_randombytes_config.h +++ b/test/configs/custom_randombytes_config.h @@ -45,13 +45,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -68,10 +68,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -102,9 +102,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -130,7 +130,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -141,7 +141,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -155,7 +155,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -183,7 +183,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -192,8 +192,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -220,14 +220,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -246,9 +246,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -262,7 +262,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -282,7 +282,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -298,10 +298,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -323,7 +323,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -339,7 +339,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -385,7 +385,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -399,7 +399,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -605,11 +605,11 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -636,14 +636,14 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -655,7 +655,7 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -674,7 +674,7 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -725,7 +725,7 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -735,7 +735,7 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -745,11 +745,11 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -760,13 +760,13 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -798,8 +798,8 @@ static MLD_INLINE int mld_randombytes(uint8_t *ptr, size_t len) * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/test/configs/custom_stdlib_config.h b/test/configs/custom_stdlib_config.h index d8678fbe71..f5d9895f12 100644 --- a/test/configs/custom_stdlib_config.h +++ b/test/configs/custom_stdlib_config.h @@ -46,13 +46,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -69,10 +69,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -103,9 +103,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -131,7 +131,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -142,7 +142,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -156,7 +156,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -184,7 +184,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -193,8 +193,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -221,14 +221,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -247,9 +247,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -263,7 +263,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -283,7 +283,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -299,10 +299,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -324,7 +324,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -340,7 +340,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -386,7 +386,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -400,7 +400,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -621,11 +621,11 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -652,14 +652,14 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -671,7 +671,7 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -690,7 +690,7 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -741,7 +741,7 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -751,7 +751,7 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -761,11 +761,11 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -776,13 +776,13 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -814,8 +814,8 @@ static MLD_INLINE void *mld_memset(void *s, int c, size_t n) * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/test/configs/custom_zeroize_config.h b/test/configs/custom_zeroize_config.h index d89f1245bd..045e5c7898 100644 --- a/test/configs/custom_zeroize_config.h +++ b/test/configs/custom_zeroize_config.h @@ -45,13 +45,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -68,10 +68,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -102,9 +102,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -130,7 +130,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -141,7 +141,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -155,7 +155,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -183,7 +183,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -192,8 +192,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -220,14 +220,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -246,9 +246,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -262,7 +262,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -282,7 +282,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -298,10 +298,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -323,7 +323,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -339,7 +339,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -385,7 +385,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -399,7 +399,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -606,11 +606,11 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -637,14 +637,14 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -656,7 +656,7 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -675,7 +675,7 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -726,7 +726,7 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -736,7 +736,7 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -746,11 +746,11 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -761,13 +761,13 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -799,8 +799,8 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/test/configs/low_signing_bound_config.h b/test/configs/low_signing_bound_config.h index d273a5274f..220ce8e42d 100644 --- a/test/configs/low_signing_bound_config.h +++ b/test/configs/low_signing_bound_config.h @@ -46,13 +46,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -69,10 +69,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -103,9 +103,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -131,7 +131,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -142,7 +142,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -156,7 +156,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -184,7 +184,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -193,8 +193,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -221,14 +221,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -247,9 +247,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -263,7 +263,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -283,7 +283,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -299,10 +299,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -324,7 +324,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -340,7 +340,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -386,7 +386,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -400,7 +400,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -606,11 +606,11 @@ * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -637,14 +637,14 @@ * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -656,7 +656,7 @@ * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -675,7 +675,7 @@ * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -728,7 +728,7 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -738,7 +738,7 @@ * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -748,11 +748,11 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -763,13 +763,13 @@ * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -801,8 +801,8 @@ * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/test/configs/no_asm_config.h b/test/configs/no_asm_config.h index b05e321403..eb15fee592 100644 --- a/test/configs/no_asm_config.h +++ b/test/configs/no_asm_config.h @@ -46,13 +46,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -69,10 +69,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -103,9 +103,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -131,7 +131,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -142,7 +142,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -156,7 +156,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -184,7 +184,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -193,8 +193,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -221,14 +221,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -247,9 +247,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -263,7 +263,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -283,7 +283,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -299,10 +299,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -324,7 +324,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -340,7 +340,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -386,7 +386,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -400,7 +400,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -607,11 +607,11 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ #define MLD_CONFIG_NO_ASM @@ -638,14 +638,14 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -657,7 +657,7 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -676,7 +676,7 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -727,7 +727,7 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -737,7 +737,7 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -747,11 +747,11 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -762,13 +762,13 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -800,8 +800,8 @@ static MLD_INLINE void mld_zeroize(void *ptr, size_t len) * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/test/configs/serial_fips202_config.h b/test/configs/serial_fips202_config.h index 826a193669..17785a39b2 100644 --- a/test/configs/serial_fips202_config.h +++ b/test/configs/serial_fips202_config.h @@ -45,13 +45,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -68,10 +68,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -102,9 +102,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -130,7 +130,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -141,7 +141,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -155,7 +155,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -183,7 +183,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -192,8 +192,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -220,14 +220,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -246,9 +246,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -262,7 +262,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -282,7 +282,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -298,10 +298,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -323,7 +323,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -339,7 +339,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -385,7 +385,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -399,7 +399,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -605,11 +605,11 @@ * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -636,14 +636,14 @@ * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -655,7 +655,7 @@ * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -674,7 +674,7 @@ * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -725,7 +725,7 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -735,7 +735,7 @@ * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -745,11 +745,11 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ /* #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE void* */ @@ -760,13 +760,13 @@ * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -798,8 +798,8 @@ * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/test/configs/test_alloc_config.h b/test/configs/test_alloc_config.h index e6be5d96a7..5783bc0949 100644 --- a/test/configs/test_alloc_config.h +++ b/test/configs/test_alloc_config.h @@ -49,13 +49,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -72,10 +72,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -105,9 +105,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -133,7 +133,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -144,7 +144,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -158,7 +158,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -186,7 +186,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -195,8 +195,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -223,14 +223,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -249,9 +249,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -265,7 +265,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -285,7 +285,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -301,10 +301,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -326,7 +326,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -342,7 +342,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -388,7 +388,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -402,7 +402,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -613,11 +613,11 @@ void custom_free(struct test_ctx_t *ctx, void *p, size_t sz, const char *file, * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -644,14 +644,14 @@ void custom_free(struct test_ctx_t *ctx, void *p, size_t sz, const char *file, * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -663,7 +663,7 @@ void custom_free(struct test_ctx_t *ctx, void *p, size_t sz, const char *file, * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -682,7 +682,7 @@ void custom_free(struct test_ctx_t *ctx, void *p, size_t sz, const char *file, * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -733,7 +733,7 @@ void custom_free(struct test_ctx_t *ctx, void *p, size_t sz, const char *file, * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -743,7 +743,7 @@ void custom_free(struct test_ctx_t *ctx, void *p, size_t sz, const char *file, * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -753,11 +753,11 @@ void custom_free(struct test_ctx_t *ctx, void *p, size_t sz, const char *file, * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ #define MLD_CONFIG_CONTEXT_PARAMETER_TYPE struct test_ctx_t * @@ -768,13 +768,13 @@ void custom_free(struct test_ctx_t *ctx, void *p, size_t sz, const char *file, * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -806,8 +806,8 @@ void custom_free(struct test_ctx_t *ctx, void *p, size_t sz, const char *file, * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */ diff --git a/test/configs/test_sign_hook_config.h b/test/configs/test_sign_hook_config.h index dd13988f0e..8ceea45af3 100644 --- a/test/configs/test_sign_hook_config.h +++ b/test/configs/test_sign_hook_config.h @@ -50,13 +50,13 @@ * MLD_CONFIG_PARAMETER_SET * * Specifies the parameter set for ML-DSA - * - MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 - * - MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 - * - MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 + * - #MLD_CONFIG_PARAMETER_SET=44 corresponds to ML-DSA-44 + * - #MLD_CONFIG_PARAMETER_SET=65 corresponds to ML-DSA-65 + * - #MLD_CONFIG_PARAMETER_SET=87 corresponds to ML-DSA-87 * * If you want to support multiple parameter sets, build the - * library multiple times and set MLD_CONFIG_MULTILEVEL_BUILD. - * See MLD_CONFIG_MULTILEVEL_BUILD for how to do this while + * library multiple times and set #MLD_CONFIG_MULTILEVEL_BUILD. + * See #MLD_CONFIG_MULTILEVEL_BUILD for how to do this while * minimizing code duplication. * * This can also be set using CFLAGS. @@ -73,10 +73,10 @@ * of the default configuration file mldsa/mldsa_native_config.h. * * When you need to build mldsa-native in multiple configurations, - * using varying MLD_CONFIG_FILE can be more convenient + * using varying #MLD_CONFIG_FILE can be more convenient * than configuring everything through CFLAGS. * - * To use, MLD_CONFIG_FILE _must_ be defined prior + * To use, #MLD_CONFIG_FILE _must_ be defined prior * to the inclusion of any mldsa-native headers. For example, * it can be set by passing `-DMLD_CONFIG_FILE="..."` * on the command line. @@ -106,9 +106,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -134,7 +134,7 @@ * MLD_CONFIG_NO_KEYPAIR_API * * By default, mldsa-native includes support for generating key - * pairs. If you don't need this, set MLD_CONFIG_NO_KEYPAIR_API + * pairs. If you don't need this, set #MLD_CONFIG_NO_KEYPAIR_API * to exclude keypair, keypair_internal, * pk_from_sk, and all internal APIs only needed by * those functions. @@ -145,7 +145,7 @@ * MLD_CONFIG_NO_SIGN_API * * By default, mldsa-native includes support for creating - * signatures. If you don't need this, set MLD_CONFIG_NO_SIGN_API + * signatures. If you don't need this, set #MLD_CONFIG_NO_SIGN_API * to exclude signature, * signature_extmu, signature_internal, * signature_pre_hash_internal, @@ -159,7 +159,7 @@ * * By default, mldsa-native includes support for verifying * signatures. If you don't need this, set - * MLD_CONFIG_NO_VERIFY_API to exclude verify, + * #MLD_CONFIG_NO_VERIFY_API to exclude verify, * verify_extmu, verify_internal, * verify_pre_hash_internal, * verify_pre_hash_shake256, and all internal APIs @@ -187,7 +187,7 @@ * internal deterministic API * (keypair_internal, signature_internal). * - * @note This option is incompatible with MLD_CONFIG_KEYGEN_PCT + * @note This option is incompatible with #MLD_CONFIG_KEYGEN_PCT * as the current PCT implementation requires * signature(). */ @@ -196,8 +196,8 @@ /** * MLD_CONFIG_CONSTANTS_ONLY * - * If you only need the size constants (MLDSA_PUBLICKEYBYTES, etc.) - * but no function declarations, set MLD_CONFIG_CONSTANTS_ONLY. + * If you only need the size constants (#MLDSA_PUBLICKEYBYTES, etc.) + * but no function declarations, set #MLD_CONFIG_CONSTANTS_ONLY. * * This only affects the public header mldsa_native.h, not * the implementation. @@ -224,14 +224,14 @@ * for other parameter sets. * * Example: mld_polyw1_pack_88 is only needed for - * MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a - * build with MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. + * #MLD_CONFIG_PARAMETER_SET == 44. Yet, if this option is set for a + * build with #MLD_CONFIG_PARAMETER_SET == 65/87, it would be included. * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -250,9 +250,9 @@ * * To build mldsa-native with support for all parameter sets, * build it three times -- once per parameter set -- and set the - * option MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of - * them, and MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. - * MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. + * option #MLD_CONFIG_MULTILEVEL_WITH_SHARED for exactly one of + * them, and #MLD_CONFIG_MULTILEVEL_NO_SHARED for the others. + * #MLD_CONFIG_MULTILEVEL_BUILD should be set for all of them. * * See examples/multilevel_build for an example. * @@ -266,7 +266,7 @@ * This is only relevant for single compilation unit (SCU) * builds of mldsa-native. In this case, it determines whether * directives defined in parameter-set-independent headers should - * be #undef'ined or not at the end of the SCU file. This is + * be \#undef'ined or not at the end of the SCU file. This is * needed in multilevel builds. * * See examples/multilevel_build_native for an example. @@ -286,7 +286,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the arithmetic backend to be used is - * determined by MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_ARITH_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -302,10 +302,10 @@ * * The arithmetic backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is unset, this option * is ignored. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must + * If #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH is set, this option must * either be undefined or the filename of an arithmetic backend. * If unset, the default backend will be used. * @@ -327,7 +327,7 @@ * If this option is unset, the C backend will be used. * * If this option is set, the FIPS202 backend to be used is - * determined by MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is + * determined by #MLD_CONFIG_FIPS202_BACKEND_FILE: If the latter is * unset, the default backend for your target architecture * will be used. If set, it must be the name of a backend metadata * file. @@ -343,7 +343,7 @@ * * The FIPS-202 backend to use. * - * If MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option + * If #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 is set, this option * must either be undefined or the filename of a FIPS202 backend. * If unset, the default backend will be used. * @@ -389,7 +389,7 @@ * * In compliance with @[FIPS204, Section 3.6.3], mldsa-native zeroizes * intermediate buffers before returning from function calls. By default, - * those buffers are allocated from the stack; if MLD_CONFIG_CUSTOM_ALLOC_FREE + * those buffers are allocated from the stack; if #MLD_CONFIG_CUSTOM_ALLOC_FREE * is set, they are (mostly -- few exceptions remain at present) allocated from * the configured custom allocator. * @@ -403,7 +403,7 @@ * The default implementation uses SecureZeroMemory on Windows and a * memset + compiler barrier otherwise. If neither of those is available on * the target platform, compilation will fail, and you will need to use - * MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of + * #MLD_CONFIG_CUSTOM_ZEROIZE to provide a custom implementation of * `mld_zeroize()`. * * @warning @@ -609,11 +609,11 @@ * Inline assembly is also used to implement a secure zeroization * function on non-Windows platforms. If this option is set and * the target platform is not Windows, you MUST set - * MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization + * #MLD_CONFIG_CUSTOM_ZEROIZE and provide a custom zeroization * function. * - * If this option is set, MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and - * MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no + * If this option is set, #MLD_CONFIG_USE_NATIVE_BACKEND_FIPS202 and + * #MLD_CONFIG_USE_NATIVE_BACKEND_ARITH will be ignored, and no * native backends will be used. */ /* #define MLD_CONFIG_NO_ASM */ @@ -640,14 +640,14 @@ * * Set this option if such a check should be implemented. * In this case, keypair_internal and - * keypair will return MLD_ERR_PCT_FAIL if the + * keypair will return #MLD_ERR_PCT_FAIL if the * PCT failed. * * @note This feature will drastically lower the performance of * key generation. * - * @note This option is incompatible with MLD_CONFIG_NO_SIGN_API - * and MLD_CONFIG_NO_VERIFY_API as the current PCT implementation + * @note This option is incompatible with #MLD_CONFIG_NO_SIGN_API + * and #MLD_CONFIG_NO_VERIFY_API as the current PCT implementation * requires signature() and verify(). */ /* #define MLD_CONFIG_KEYGEN_PCT */ @@ -659,7 +659,7 @@ * function `static inline int mld_break_pct() { ... }` to * indicate whether the PCT should be made fail. * - * This option only has an effect if MLD_CONFIG_KEYGEN_PCT is set. + * This option only has an effect if #MLD_CONFIG_KEYGEN_PCT is set. */ /* #define MLD_CONFIG_KEYGEN_PCT_BREAKAGE_TEST #if !defined(__ASSEMBLER__) @@ -678,7 +678,7 @@ * performed by ML-DSA signing (@[FIPS204, Algorithm 7]). * * If a valid signature is not produced within this many - * attempts, signing returns MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. + * attempts, signing returns #MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED. * This is useful in timing-sensitive environments that * require a deterministic worst-case bound on signing time. * @@ -729,7 +729,7 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE context * * as its last argument; its type is configured via - * MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this + * #MLD_CONFIG_CONTEXT_PARAMETER_TYPE (see below). mldsa-native treats this * value as opaque: it never dereferences it and only passes it on to the * configurable hook macros. It is meant to carry per-caller state -- e.g. a * pointer to a memory pool for the allocation hooks, or the resume state for @@ -739,7 +739,7 @@ * the hook macros never receive a context argument. * * The hooks that receive the context are the allocation hooks (see - * MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see + * #MLD_CONFIG_CUSTOM_ALLOC_FREE) and the signing hooks (see * MLD_CONFIG_SIGN_HOOK_RESUME / _ATTEMPT / _FINISH); each is documented with * its own option below. */ @@ -749,11 +749,11 @@ * MLD_CONFIG_CONTEXT_PARAMETER_TYPE * * Set this to define the type of the context parameter added by - * MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function + * #MLD_CONFIG_CONTEXT_PARAMETER. It can be any C type usable as a function * parameter, e.g. `void *` or a pointer to a caller-defined struct such as * `struct my_ctx *`. * - * This option must be defined if and only if MLD_CONFIG_CONTEXT_PARAMETER is + * This option must be defined if and only if #MLD_CONFIG_CONTEXT_PARAMETER is * defined; defining one without the other is a compile-time error. */ #if !defined(__ASSEMBLER__) @@ -771,13 +771,13 @@ struct test_sign_hook_ctx; /* Forward declaration */ * Three optional, independent hooks into the ML-DSA signing rejection-sampling * loop. Each is enabled by defining the matching option, in which case the * integration must provide the corresponding function. If a hook needs - * per-operation state, enable MLD_CONFIG_CONTEXT_PARAMETER; the context is then - * appended as the last argument. + * per-operation state, enable #MLD_CONFIG_CONTEXT_PARAMETER; the context is + * then appended as the last argument. * * @warning This feature is experimental. Its scope, configuration and * function signatures may change at any time, including after v2. * - * Enabling any of the hooks requires MLD_CONFIG_NO_RANDOMIZED_API (restricting + * Enabling any of the hooks requires #MLD_CONFIG_NO_RANDOMIZED_API (restricting * the public API to deterministic operations). This is because the restartable * signing as enabled by the signing hooks only produces the uninterrupted * signature when the randomness is fixed across calls. A logging-only use @@ -809,8 +809,8 @@ struct test_sign_hook_ctx; /* Forward declaration */ * When an option is unset, the hook is a no-op (resume to 0, attempt proceeds), * i.e. ordinary one-shot signing. * - * Independent of MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper bound - * on the number of signing attempts. + * Independent of #MLD_CONFIG_MAX_SIGNING_ATTEMPTS, which is a static upper + * bound on the number of signing attempts. * * See test/src/test_sign_hook.c for a worked example using all three. */