header: Add note on SHA256 override and aux functions
What the developer wrote
Authored by Tim Ruffing
header: Add note on SHA256 override and aux functions
Resolves one item in #1835.
What changed, and why it matters
This commit only adds a documentation note to a public header file. It explains that certain auxiliary functions, when called directly by user code, will not use a user-installed SHA256 override callback because they do not receive a library context object. There is no code change, no behavior change, and no security fix.
No security action required. This is a documentation-only clarification.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff modifies include/secp256k1.h to clarify the interaction between secp256k1_context_set_sha256_callback and auxiliary function pointers such as secp256k1_nonce_function_default. It documents that the callback is only effective when functions are invoked through library paths that carry a context object (e.g., secp256k1_ecdsa_sign with noncefp==NULL or noncefp==secp256k1_nonce_function_default), not when the auxiliary function pointer is called directly by user code. No implementation logic was changed.
Changed components
include/secp256k1.h documentationInspect captured patch +9 / −1
diff --git a/include/secp256k1.h b/include/secp256k1.h
index 984972c..a44a33a 100644
--- a/include/secp256k1.h
+++ b/include/secp256k1.h
@@ -417,7 +417,7 @@ typedef void (*secp256k1_sha256_compression_function)(
/**
* Set a callback function to override the internal SHA256 compression function.
*
- * This installs a function to replace the built-in block-compression
+ * This installs a callback to replace the built-in block-compression
* step used by the library's internal SHA256 implementation.
* The provided callback must exactly implement the effect of n_blocks
* repeated applications of the SHA256 compression function.
@@ -427,6 +427,14 @@ typedef void (*secp256k1_sha256_compression_function)(
* specialized implementation. It is NOT meant for replacing SHA256
* with a different hash function.
*
+ * Since auxiliary functions exposed by the library via a function
+ * pointer such as secp256k1_nonce_function_default do not take a
+ * context object, they will not use the callback when called directly
+ * from user code. (But they will use the callback when called from
+ * other library functions that do take a context object, e.g., when
+ * noncefp==NULL or noncefp==secp256k1_nonce_function_default is passed
+ * as an argument to secp256k1_ecdsa_sign.)
+ *
* Args: ctx: pointer to a context object.
* In: fn_compression: pointer to a function implementing the compression function;
* passing NULL restores the default implementation.
Why this scored 15/100
Community notes
Notes can correct, qualify, or add evidence to the AI analysis. Every note shown here has been validated by a human moderator.
The AI analysis stands alone for now. Submit a note if you can add evidence or important context.