Clarify that a secp256k1_ecdh_hash_function must return 0 or 1

Summary:
and improve style of the ECDH docs.

This is a backport of libsecp256k1 [[bitcoin-core/secp256k1#718 | PR718]]

Depends on D5389

Test Plan:
  ninja check-secp256k1

Reviewers: #bitcoin_abc, Fabien

Reviewed By: #bitcoin_abc, Fabien

Differential Revision: https://reviews.bitcoinabc.org/D5390

src/secp256k1/include/secp256k1_ecdh.h

@@ -7,40 +7,44 @@
 extern "C" {
 #endif
 
-/** A pointer to a function that applies hash function to a point
+/** A pointer to a function that hashes an EC point to obtain an ECDH secret
  *
- *  Returns: 1 if a point was successfully hashed. 0 will cause ecdh to fail
- *  Out:    output:     pointer to an array to be filled by the function
- *  In:     x:          pointer to a 32-byte x coordinate
- *          y:          pointer to a 32-byte y coordinate
- *          data:       Arbitrary data pointer that is passed through
+ *  Returns: 1 if the point was successfully hashed.
+ *           0 will cause secp256k1_ecdh to fail and return 0.
+ *           Other return values are not allowed, and the behaviour of
+ *           secp256k1_ecdh is undefined for other return values.
+ *  Out:     output:     pointer to an array to be filled by the function
+ *  In:      x32:        pointer to a 32-byte x coordinate
+ *           y32:        pointer to a 32-byte y coordinate
+ *           data:       arbitrary data pointer that is passed through
  */
 typedef int (*secp256k1_ecdh_hash_function)(
   unsigned char *output,
-  const unsigned char *x,
-  const unsigned char *y,
+  const unsigned char *x32,
+  const unsigned char *y32,
   void *data
 );
 
 /** 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)
+ *           0: scalar was invalid (zero or overflow) or hashfp returned 0
  *  Args:    ctx:        pointer to a context object (cannot be NULL)
  *  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
  *                       (in which case, 32 bytes will be written to output)
- *           data:       Arbitrary data pointer that is passed through to hashfp
+ *           data:       arbitrary data pointer that is passed through to hashfp
  */
 SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_ecdh(
   const secp256k1_context* ctx,

src/secp256k1/src/modules/ecdh/main_impl.h

@@ -10,14 +10,14 @@
 #include "include/secp256k1_ecdh.h"
 #include "ecmult_const_impl.h"
 
-static int ecdh_hash_function_sha256(unsigned char *output, const unsigned char *x, const unsigned char *y, void *data) {
-    unsigned char version = (y[31] & 0x01) | 0x02;
+static int ecdh_hash_function_sha256(unsigned char *output, const unsigned char *x32, const unsigned char *y32, void *data) {
+    unsigned char version = (y32[31] & 0x01) | 0x02;
     secp256k1_sha256 sha;
     (void)data;
 
     secp256k1_sha256_initialize(&sha);
     secp256k1_sha256_write(&sha, &version, 1);
-    secp256k1_sha256_write(&sha, x, 32);
+    secp256k1_sha256_write(&sha, x32, 32);
     secp256k1_sha256_finalize(&sha, output);
 
     return 1;