Merge bitcoin#714: doc: document the length requirements of output pa…

…rameter. 4b48a43 doc: document the length requirements of output parameter. (Rusty Russell) Pull request description: It's subtle, since it is actually only touched by hashfp (though we assert it's non-NULL), but give explicit advice in the default case. Signed-off-by: Rusty Russell <[email protected]> ACKs for top commit: jonasnick: ACK 4b48a43 real-or-random: ACK 4b48a43 diff inspection Tree-SHA512: d6bedb495e46b27ac9b558e77d814884d782ea78569a2296688eccf374bc880d13846546ad449c2a677865cf6ed56fcbc8be58c21f9daca5084831074e20d769
sipa · Feb 10, 2020 · 856a01d · 856a01d
2 parents d72b9e2 + 4b48a43
commit 856a01d
Showing 1 changed file with 7 additions and 4 deletions.
diff --git a/include/secp256k1_ecdh.h b/include/secp256k1_ecdh.h
@@ -22,22 +22,25 @@ typedef int (*secp256k1_ecdh_hash_function)(
   void *data
 );
 
-/** An implementation of SHA256 hash function that applies to compressed public key. */
+/** An implementation of SHA256 hash function that applies to compressed public key.
+ * Populates the output parameter with 32 bytes. */
 SECP256K1_API extern const secp256k1_ecdh_hash_function secp256k1_ecdh_hash_function_sha256;
 
-/** A default ecdh hash function (currently equal to secp256k1_ecdh_hash_function_sha256). */
+/** A default ecdh hash function (currently equal to secp256k1_ecdh_hash_function_sha256).
+ * Populates the output parameter with 32 bytes. */
 SECP256K1_API extern const secp256k1_ecdh_hash_function secp256k1_ecdh_hash_function_default;
 
 /** Compute an EC Diffie-Hellman secret in constant time
  *  Returns: 1: exponentiation was successful
  *           0: scalar was invalid (zero or overflow)
  *  Args:    ctx:        pointer to a context object (cannot be NULL)
- *  Out:     output:     pointer to an array to be filled by the function
+ *  Out:     output:     pointer to an array to be filled by hashfp
  *  In:      pubkey:     a pointer to a secp256k1_pubkey containing an
  *                       initialized public key
  *           privkey:    a 32-byte scalar with which to multiply the point
  *           hashfp:     pointer to a hash function. If NULL, secp256k1_ecdh_hash_function_sha256 is used
- *           data:       Arbitrary data pointer that is passed through
+ *                       (in which case, 32 bytes will be written to output)
+ *           data:       Arbitrary data pointer that is passed through to hashfp
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdh(
   const secp256k1_context* ctx,