Merge bitcoin-core/secp256k1#1616: examples: do not retry generating seckey randomness in musig

5bab8f6d3c examples: make key generation doc consistent (Jonas Nick)
e8908221a4 examples: do not retry generating seckey randomness in musig (Jonas Nick)
70b6be1834 extrakeys: improve doc of keypair_create (don't suggest retry) (Jonas Nick)

Pull request description:

  Follow-up to #1570.

ACKs for top commit:
  real-or-random:
    utACK 5bab8f6d3c
  theStack:
    ACK 5bab8f6d3c

Tree-SHA512: f29ceda87b0017aa2a2324f23527467c777223c9f7cbe43d814bb1cebfc6f4453b7e11f48a6bc718ae05d7eb9227ceb074adf576e8bb8c28639b47931136ce0a

examples/ecdh.c

@@ -47,8 +47,8 @@ int main(void) {
         return 1;
     }
     /* If the secret key is zero or out of range (greater than secp256k1's
-    * order), we fail. Note that the probability of this occurring
+    * order), we fail. Note that the probability of this occurring is negligible
-    * is negligible with a properly functioning random number generator. */
+    * with a properly functioning random number generator. */
     if (!secp256k1_ec_seckey_verify(ctx, seckey1) || !secp256k1_ec_seckey_verify(ctx, seckey2)) {
         printf("Generated secret key is invalid. This indicates an issue with the random number generator.\n");
         return 1;

examples/ecdsa.c

@@ -49,13 +49,13 @@ int main(void) {
     assert(return_val);
 
     /*** Key Generation ***/
-    /* If the secret key is zero or out of range (greater than secp256k1's
-    * order), we return 1. Note that the probability of this occurring
-    * is negligible with a properly functioning random number generator. */
     if (!fill_random(seckey, sizeof(seckey))) {
         printf("Failed to generate randomness\n");
         return 1;
     }
+    /* If the secret key is zero or out of range (greater than secp256k1's
+    * order), we fail. Note that the probability of this occurring is negligible
+    * with a properly functioning random number generator. */
     if (!secp256k1_ec_seckey_verify(ctx, seckey)) {
         printf("Generated secret key is invalid. This indicates an issue with the random number generator.\n");
         return 1;

examples/ellswift.c

@@ -47,14 +47,13 @@ int main(void) {
     assert(return_val);
 
     /*** Generate secret keys ***/
-
-    /* If the secret key is zero or out of range (greater than secp256k1's
-     * order), we return 1. Note that the probability of this occurring
-     * is negligible with a properly functioning random number generator. */
     if (!fill_random(seckey1, sizeof(seckey1)) || !fill_random(seckey2, sizeof(seckey2))) {
         printf("Failed to generate randomness\n");
         return 1;
     }
+    /* If the secret key is zero or out of range (greater than secp256k1's
+    * order), we fail. Note that the probability of this occurring is negligible
+    * with a properly functioning random number generator. */
     if (!secp256k1_ec_seckey_verify(ctx, seckey1) || !secp256k1_ec_seckey_verify(ctx, seckey2)) {
         printf("Generated secret key is invalid. This indicates an issue with the random number generator.\n");
         return 1;

examples/musig.c

@@ -38,14 +38,17 @@ struct signer {
 /* Create a key pair, store it in signer_secrets->keypair and signer->pubkey */
 static int create_keypair(const secp256k1_context* ctx, struct signer_secrets *signer_secrets, struct signer *signer) {
     unsigned char seckey[32];
-    while (1) {
+
-        if (!fill_random(seckey, sizeof(seckey))) {
+    if (!fill_random(seckey, sizeof(seckey))) {
-            printf("Failed to generate randomness\n");
+        printf("Failed to generate randomness\n");
-            return 0;
+        return 0;
-        }
+    }
-        if (secp256k1_keypair_create(ctx, &signer_secrets->keypair, seckey)) {
+    /* Try to create a keypair with a valid context. This only fails if the
-            break;
+     * secret key is zero or out of range (greater than secp256k1's order). Note
-        }
+     * that the probability of this occurring is negligible with a properly
+     * functioning random number generator. */
+    if (!secp256k1_keypair_create(ctx, &signer_secrets->keypair, seckey)) {
+        return 0;
     }
     if (!secp256k1_keypair_pub(ctx, &signer->pubkey, &signer_secrets->keypair)) {
         return 0;

examples/schnorr.c

@@ -43,18 +43,17 @@ int main(void) {
     assert(return_val);
 
     /*** Key Generation ***/
-    /* If the secret key is zero or out of range (greater than secp256k1's
-    * order), we return 1. Note that the probability of this occurring
-    * is negligible with a properly functioning random number generator. */
     if (!fill_random(seckey, sizeof(seckey))) {
         printf("Failed to generate randomness\n");
         return 1;
     }
-    /* Try to create a keypair with a valid context, it should only fail if
+    /* Try to create a keypair with a valid context. This only fails if the
-     * the secret key is zero or out of range. */
+     * secret key is zero or out of range (greater than secp256k1's order). Note
+     * that the probability of this occurring is negligible with a properly
+     * functioning random number generator. */
     if (!secp256k1_keypair_create(ctx, &keypair, seckey)) {
         printf("Generated secret key is invalid. This indicates an issue with the random number generator.\n");
-	return 1;
+        return 1;
     }
 
     /* Extract the X-only public key from the keypair. We pass NULL for

include/secp256k1.h

@@ -684,7 +684,7 @@ SECP256K1_API int secp256k1_ecdsa_sign(
  *  A secret key is valid if it is not 0 and less than the secp256k1 curve order
  *  when interpreted as an integer (most significant byte first). The
  *  probability of choosing a 32-byte string uniformly at random which is an
- *  invalid secret key is negligible. However, if it does happen it should 
+ *  invalid secret key is negligible. However, if it does happen it should
  *  be assumed that the randomness source is severely broken and there should
  *  be no retry.
  *

include/secp256k1_extrakeys.h

@@ -155,10 +155,13 @@ SECP256K1_API SECP256K1_WARN_UNUSED_RESULT int secp256k1_xonly_pubkey_tweak_add_
     const unsigned char *tweak32
 ) SECP256K1_ARG_NONNULL(1) SECP256K1_ARG_NONNULL(2) SECP256K1_ARG_NONNULL(4) SECP256K1_ARG_NONNULL(5);
 
-/** Compute the keypair for a secret key.
+/** Compute the keypair for a valid secret key.
  *
- *  Returns: 1: secret was valid, keypair is ready to use
+ *  See the documentation of `secp256k1_ec_seckey_verify` for more information
- *           0: secret was invalid, try again with a different secret
+ *  about the validity of secret keys.
+ *
+ *  Returns: 1: secret key is valid
+ *           0: secret key is invalid
  *  Args:    ctx: pointer to a context object (not secp256k1_context_static).
  *  Out: keypair: pointer to the created keypair.
  *  In:   seckey: pointer to a 32-byte secret key.