doc: clarify API doc of `secp256k1_ecdsa_recover` return value
What the developer wrote
Authored by Jonas Nick
doc: clarify API doc of `secp256k1_ecdsa_recover` return value
Co-authored-by: Tim Ruffing <me@real-or-random.org>
What changed, and why it matters
This commit only updates the documentation comments for a function in a header file. It clarifies what the return value of secp256k1_ecdsa_recover means and explains a subtle detail about signature normalization after converting a recoverable signature. No code logic was changed, so there is no security vulnerability or fix here.
No action needed. Review the clarified documentation to ensure it accurately reflects intended API behavior.
Security signals we found
No strong security signals were identified.
Evidence from the diff
The diff modifies include/secp256k1_recovery.h, replacing a one-line return-value description with a more detailed explanation. It states that successful public-key recovery implies the normalized signature would verify, but that converting a recoverable signature to a non-recoverable one does not guarantee normalization. This is purely a documentation clarification; no implementation, API contract, or behavior changed.
Changed components
include/secp256k1_recovery.h documentationInspect captured patch +11 / −1
diff --git a/include/secp256k1_recovery.h b/include/secp256k1_recovery.h
index 93a2e4c..2430f99 100644
--- a/include/secp256k1_recovery.h
+++ b/include/secp256k1_recovery.h
@@ -92,7 +92,17 @@ SECP256K1_API int secp256k1_ecdsa_sign_recoverable(
/** Recover an ECDSA public key from a signature.
*
- * Returns: 1: public key successfully recovered (which guarantees a correct signature).
+ * Successful public key recovery guarantees that the signature, after normalization,
+ * passes `secp256k1_ecdsa_verify`. Thus, explicit verification is not necessary.
+ *
+ * However, a recoverable signature that successfully passes `secp256k1_ecdsa_recover`,
+ * when converted to a non-recoverable signature (using
+ * `secp256k1_ecdsa_recoverable_signature_convert`), is not guaranteed to be
+ * normalized and thus not guaranteed to pass `secp256k1_ecdsa_verify`. If a
+ * normalized signature is required, call `secp256k1_ecdsa_signature_normalize`
+ * after `secp256k1_ecdsa_recoverable_signature_convert`.
+ *
+ * Returns: 1: public key successfully recovered
* 0: otherwise.
* Args: ctx: pointer to a context object.
* Out: pubkey: pointer to the recovered public key.
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.