Document public API conventions#1295
Open
mkannwischer wants to merge 2 commits into
Open
Conversation
|
|
||
| Functions returning `int` return `0` on success and a negative `MLD_ERR_*` constant (see `mldsa_native.h`) on failure. Return values must always be checked; the public API is annotated with `warn_unused_result` on compilers that support it. | ||
|
|
||
| For the signature verification, `MLD_ERR_FAIL` reports that the signature is invalid. This is an expected outcome, not an internal error. |
Contributor
There was a problem hiding this comment.
Suggest to elaborate a bit.
Functions returning `int` return `0` on success and a negative error code on failure.
Error codes are enumerated as `MLD_ERR_*` in `mldsa_native.h`.
Errors have different origins, and not all are fatal. For example, signature verification
routines use `MLD_ERR_FAIL` to signal an invalid signature; signing hooks use
`MLD_ERR_SIGNING_PAUSED` to signal a paused signature operation.
Other errors, such as `MLD_ERR_SIGN_ATTEMPTS_EXHAUSTED` or
`MLD_ERR_RNG_FAIL`, should never be observed in normal operation, and hint at
a deeper failure in the system.
Return values must always be checked; the public API is annotated with
`warn_unused_result` on compilers that support it.
|
|
||
| ## Pointer arguments | ||
|
|
||
| All pointer arguments are assumed to be valid and non-NULL, and every buffer is assumed to have the size implied by its parameter type and the relevant `MLDSA*_*BYTES` constant. mldsa-native does not check pointers for NULL and does not validate buffer sizes; passing a NULL or otherwise invalid pointer, or an undersized buffer, is undefined behavior. Ensuring these preconditions is the caller's responsibility. |
Contributor
There was a problem hiding this comment.
non-NULL is only required for positive lengths
Contributor
There was a problem hiding this comment.
Drop "and the relevant ... constant"?
|
|
||
| All pointer arguments are assumed to be valid and non-NULL, and every buffer is assumed to have the size implied by its parameter type and the relevant `MLDSA*_*BYTES` constant. mldsa-native does not check pointers for NULL and does not validate buffer sizes; passing a NULL or otherwise invalid pointer, or an undersized buffer, is undefined behavior. Ensuring these preconditions is the caller's responsibility. | ||
|
|
||
| The one exception is the context argument paired with a length: `ctx` may be NULL when `ctxlen == 0`. Such cases are called out in the per-function documentation. |
Contributor
There was a problem hiding this comment.
Did you deliberately omit the length checks?
Add API-CONVENTIONS.md covering return values, pointer validity (all pointers assumed valid, no NULL checks), and the state of output buffers on error (left unchanged or fully zeroized). Link it from the mldsa_native.h header comment and the README Usage section. Signed-off-by: Matthias J. Kannwischer <matthias@zerorisc.com>
Note in the mldsa_native.h docs that m may be NULL when mlen == 0, and add a test exercising it: a sign/verify round-trip with m == NULL, mlen == 0 for both the pure and SHAKE256 pre-hash paths. Signed-off-by: Matthias J. Kannwischer <matthias@zerorisc.com>
mkannwischer
force-pushed
the
api-conventions
branch
from
July 18, 2026 09:21
292c4b3 to
addab56
Compare
Contributor
CBMC Results (ML-DSA-44, REDUCE-RAM)Full Results (210 proofs)
|
Contributor
CBMC Results (ML-DSA-44)Full Results (210 proofs)
|
Contributor
CBMC Results (ML-DSA-65, REDUCE-RAM)Full Results (210 proofs)
|
Contributor
CBMC Results (ML-DSA-87, REDUCE-RAM)Full Results (210 proofs)
|
Contributor
CBMC Results (ML-DSA-65)Full Results (210 proofs)
|
Contributor
CBMC Results (ML-DSA-87)
Full Results (210 proofs)
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add API-CONVENTIONS.md covering return values, pointer validity (all pointers assumed valid, no NULL checks), and the state of output buffers on error (left unchanged or fully zeroized). Link it from the mldsa_native.h header comment and the README Usage section.