21-DOT-DEV · csjones · Mar 2, 2026 · Mar 2, 2026 · Mar 2, 2026 · Mar 2, 2026
@@ -261,7 +261,7 @@ SECP256K1_DEPRECATED("Use secp256k1_context_static instead");
  *  secp256k1_context_create (or secp256k1_context_preallocated_create), which will
  *  take care of performing the self tests.
  *
- *  If the tests fail, this function will call the default error handler to abort the
+ *  If the tests fail, this function will call the default error callback to abort the
  *  program (see secp256k1_context_set_error_callback).
  */
 SECP256K1_API void secp256k1_selftest(void);
@@ -334,36 +334,37 @@ SECP256K1_API void secp256k1_context_destroy(
  *  an API call. It will only trigger for violations that are mentioned
  *  explicitly in the header.
  *
- *  The philosophy is that these shouldn't be dealt with through a
- *  specific return value, as calling code should not have branches to deal with
- *  the case that this code itself is broken.
+ *  The philosophy is that these shouldn't be dealt with through a specific
+ *  return value, as calling code should not have branches to deal with the case
+ *  that this code itself is broken.
  *
  *  On the other hand, during debug stage, one would want to be informed about
- *  such mistakes, and the default (crashing) may be inadvisable.
- *  When this callback is triggered, the API function called is guaranteed not
- *  to cause a crash, though its return value and output arguments are
- *  undefined.
- *
- *  When this function has not been called (or called with fn==NULL), then the
- *  default handler will be used. The library provides a default handler which
- *  writes the message to stderr and calls abort. This default handler can be
+ *  such mistakes, and the default (crashing) may be inadvisable. Should this
+ *  callback return instead of crashing, the return value and output arguments
+ *  of the API function call are undefined. Moreover, the same API call may
+ *  trigger the callback again in this case.
+ *
+ *  When this function has not been called (or called with fun==NULL), then the
+ *  default callback will be used. The library provides a default callback which
+ *  writes the message to stderr and calls abort. This default callback can be
  *  replaced at link time if the preprocessor macro
  *  USE_EXTERNAL_DEFAULT_CALLBACKS is defined, which is the case if the build
  *  has been configured with --enable-external-default-callbacks. Then the
  *  following two symbols must be provided to link against:
  *   - void secp256k1_default_illegal_callback_fn(const char *message, void *data);
  *   - void secp256k1_default_error_callback_fn(const char *message, void *data);
- *  The library can call these default handlers even before a proper callback data
+ *  The library may call a default callback even before a proper callback data
  *  pointer could have been set using secp256k1_context_set_illegal_callback or
  *  secp256k1_context_set_error_callback, e.g., when the creation of a context
- *  fails. In this case, the corresponding default handler will be called with
+ *  fails. In this case, the corresponding default callback will be called with
  *  the data pointer argument set to NULL.
  *
  *  Args: ctx:  pointer to a context object.
  *  In:   fun:  pointer to a function to call when an illegal argument is
  *              passed to the API, taking a message and an opaque pointer.
- *              (NULL restores the default handler.)
- *        data: the opaque pointer to pass to fun above, must be NULL for the default handler.
+ *              (NULL restores the default callback.)
+ *        data: the opaque pointer to pass to fun above, must be NULL for the
+ *              default callback.
  *
  *  See also secp256k1_context_set_error_callback.
  */
@@ -380,18 +381,19 @@ SECP256K1_API void secp256k1_context_set_illegal_callback(
  *  to abort the program.
  *
  *  This can only trigger in case of a hardware failure, miscompilation,
- *  memory corruption, serious bug in the library, or other error would can
- *  otherwise result in undefined behaviour. It will not trigger due to mere
+ *  memory corruption, serious bug in the library, or other error that would
+ *  result in undefined behaviour. It will not trigger due to mere
  *  incorrect usage of the API (see secp256k1_context_set_illegal_callback
  *  for that). After this callback returns, anything may happen, including
  *  crashing.
  *
  *  Args: ctx:  pointer to a context object.
  *  In:   fun:  pointer to a function to call when an internal error occurs,
  *              taking a message and an opaque pointer (NULL restores the
- *              default handler, see secp256k1_context_set_illegal_callback
+ *              default callback, see secp256k1_context_set_illegal_callback
  *              for details).
- *        data: the opaque pointer to pass to fun above, must be NULL for the default handler.
+ *        data: the opaque pointer to pass to fun above, must be NULL for the
+ *              default callback.
  *
  *  See also secp256k1_context_set_illegal_callback.
  */

@@ -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.

@@ -48,7 +48,17 @@
 #  if __has_feature(memory_sanitizer)
 #    include <sanitizer/msan_interface.h>
 #    define SECP256K1_CHECKMEM_ENABLED 1
-#    define SECP256K1_CHECKMEM_UNDEFINE(p, len) __msan_allocated_memory((p), (len))
+#    if defined(__clang__) && ((__clang_major__ == 21 && __clang_minor__ >= 1) || __clang_major__ >= 22)
+#      define SECP256K1_CHECKMEM_UNDEFINE(p, len) do { \
+         /* Work around https://github.com/llvm/llvm-project/issues/160094 */ \
+         _Pragma("clang diagnostic push") \
+         _Pragma("clang diagnostic ignored \"-Wuninitialized-const-pointer\"") \
+         __msan_allocated_memory((p), (len)); \
+         _Pragma("clang diagnostic pop") \
+         } while(0)
+#    else
+#      define SECP256K1_CHECKMEM_UNDEFINE(p, len) __msan_allocated_memory((p), (len))
+#    endif
 #    define SECP256K1_CHECKMEM_DEFINE(p, len) __msan_unpoison((p), (len))
 #    define SECP256K1_CHECKMEM_MSAN_DEFINE(p, len) __msan_unpoison((p), (len))
 #    define SECP256K1_CHECKMEM_CHECK(p, len) __msan_check_mem_is_initialized((p), (len))

@@ -277,8 +277,8 @@ static void secp256k1_ecmult_gen(const secp256k1_ecmult_gen_context *ctx, secp25
     /* Cleanup. */
     secp256k1_fe_clear(&neg);
     secp256k1_ge_clear(&add);
-    secp256k1_memclear(&adds, sizeof(adds));
-    secp256k1_memclear(&recoded, sizeof(recoded));
+    secp256k1_memclear_explicit(&adds, sizeof(adds));
+    secp256k1_memclear_explicit(&recoded, sizeof(recoded));
 }
 
 /* Setup blinding values for secp256k1_ecmult_gen. */
@@ -310,7 +310,7 @@ static void secp256k1_ecmult_gen_blind(secp256k1_ecmult_gen_context *ctx, const
     VERIFY_CHECK(seed32 != NULL);
     memcpy(keydata + 32, seed32, 32);
     secp256k1_rfc6979_hmac_sha256_initialize(&rng, keydata, 64);
-    secp256k1_memclear(keydata, sizeof(keydata));
+    secp256k1_memclear_explicit(keydata, sizeof(keydata));
 
     /* Compute projective blinding factor (cannot be 0). */
     secp256k1_rfc6979_hmac_sha256_generate(&rng, nonce32, 32);
@@ -331,7 +331,7 @@ static void secp256k1_ecmult_gen_blind(secp256k1_ecmult_gen_context *ctx, const
     secp256k1_ge_set_gej(&ctx->ge_offset, &gb);
 
     /* Clean up. */
-    secp256k1_memclear(nonce32, sizeof(nonce32));
+    secp256k1_memclear_explicit(nonce32, sizeof(nonce32));
     secp256k1_scalar_clear(&b);
     secp256k1_gej_clear(&gb);
     secp256k1_fe_clear(&f);

@@ -19,7 +19,7 @@
 #endif
 
 SECP256K1_INLINE static void secp256k1_fe_clear(secp256k1_fe *a) {
-    secp256k1_memclear(a, sizeof(secp256k1_fe));
+    secp256k1_memclear_explicit(a, sizeof(secp256k1_fe));
 }
 
 SECP256K1_INLINE static int secp256k1_fe_equal(const secp256k1_fe *a, const secp256k1_fe *b) {

@@ -337,11 +337,11 @@ static void secp256k1_ge_set_infinity(secp256k1_ge *r) {
 }
 
 static void secp256k1_gej_clear(secp256k1_gej *r) {
-    secp256k1_memclear(r, sizeof(secp256k1_gej));
+    secp256k1_memclear_explicit(r, sizeof(secp256k1_gej));
 }
 
 static void secp256k1_ge_clear(secp256k1_ge *r) {
-    secp256k1_memclear(r, sizeof(secp256k1_ge));
+    secp256k1_memclear_explicit(r, sizeof(secp256k1_ge));
 }
 
 static int secp256k1_ge_set_xquad(secp256k1_ge *r, const secp256k1_fe *x) {

@@ -172,7 +172,7 @@ static void secp256k1_sha256_initialize_tagged(secp256k1_sha256 *hash, const uns
 }
 
 static void secp256k1_sha256_clear(secp256k1_sha256 *hash) {
-    secp256k1_memclear(hash, sizeof(*hash));
+    secp256k1_memclear_explicit(hash, sizeof(*hash));
 }
 
 static void secp256k1_hmac_sha256_initialize(secp256k1_hmac_sha256 *hash, const unsigned char *key, size_t keylen) {
@@ -200,7 +200,7 @@ static void secp256k1_hmac_sha256_initialize(secp256k1_hmac_sha256 *hash, const
         rkey[n] ^= 0x5c ^ 0x36;
     }
     secp256k1_sha256_write(&hash->inner, rkey, sizeof(rkey));
-    secp256k1_memclear(rkey, sizeof(rkey));
+    secp256k1_memclear_explicit(rkey, sizeof(rkey));
 }
 
 static void secp256k1_hmac_sha256_write(secp256k1_hmac_sha256 *hash, const unsigned char *data, size_t size) {
@@ -211,12 +211,12 @@ static void secp256k1_hmac_sha256_finalize(secp256k1_hmac_sha256 *hash, unsigned
     unsigned char temp[32];
     secp256k1_sha256_finalize(&hash->inner, temp);
     secp256k1_sha256_write(&hash->outer, temp, 32);
-    secp256k1_memclear(temp, sizeof(temp));
+    secp256k1_memclear_explicit(temp, sizeof(temp));
     secp256k1_sha256_finalize(&hash->outer, out32);
 }
 
 static void secp256k1_hmac_sha256_clear(secp256k1_hmac_sha256 *hash) {
-    secp256k1_memclear(hash, sizeof(*hash));
+    secp256k1_memclear_explicit(hash, sizeof(*hash));
 }
 
 static void secp256k1_rfc6979_hmac_sha256_initialize(secp256k1_rfc6979_hmac_sha256 *rng, const unsigned char *key, size_t keylen) {
@@ -285,7 +285,7 @@ static void secp256k1_rfc6979_hmac_sha256_finalize(secp256k1_rfc6979_hmac_sha256
 }
 
 static void secp256k1_rfc6979_hmac_sha256_clear(secp256k1_rfc6979_hmac_sha256 *rng) {
-    secp256k1_memclear(rng, sizeof(*rng));
+    secp256k1_memclear_explicit(rng, sizeof(*rng));
 }
 
 #undef Round

@@ -62,8 +62,8 @@ int secp256k1_ecdh(const secp256k1_context* ctx, unsigned char *output, const se
 
     ret = hashfp(output, x, y, data);
 
-    secp256k1_memclear(x, sizeof(x));
-    secp256k1_memclear(y, sizeof(y));
+    secp256k1_memclear_explicit(x, sizeof(x));
+    secp256k1_memclear_explicit(y, sizeof(y));
     secp256k1_scalar_clear(&s);
     secp256k1_ge_clear(&pt);
     secp256k1_gej_clear(&res);

@@ -182,7 +182,7 @@ int secp256k1_ecdsa_anti_exfil_signer_commit(const secp256k1_context* ctx, secp2
     secp256k1_ecmult_gen(&ctx->ecmult_gen_ctx, &rj, &k);
     secp256k1_ge_set_gej(&r, &rj);
     secp256k1_ecdsa_s2c_opening_save(opening, &r);
-    secp256k1_memclear(nonce32, 32);
+    secp256k1_memclear_explicit(nonce32, 32);
     secp256k1_scalar_clear(&k);
     return 1;
 }

@@ -582,7 +582,7 @@ int secp256k1_ellswift_xdh(const secp256k1_context *ctx, unsigned char *output,
     /* Invoke hasher */
     ret = hashfp(output, sx, ell_a64, ell_b64, data);
 
-    secp256k1_memclear(sx, sizeof(sx));
+    secp256k1_memclear_explicit(sx, sizeof(sx));
     secp256k1_fe_clear(&px);
     secp256k1_scalar_clear(&s);
 

@@ -28,7 +28,7 @@ static void secp256k1_pedersen_scalar_set_u64(secp256k1_scalar *sec, uint64_t va
         value <<= 8;
     }
     secp256k1_scalar_set_b32(sec, data, NULL);
-    secp256k1_memclear(data, 32);
+    secp256k1_memclear_explicit(data, 32);
 }
 
 static void secp256k1_pedersen_ecmult_small(secp256k1_gej *r, uint64_t gn, const secp256k1_ge* genp) {

@@ -385,10 +385,10 @@ static void secp256k1_nonce_function_musig(secp256k1_scalar *k, const unsigned c
         secp256k1_scalar_set_b32(&k[i], buf, NULL);
 
         /* Attempt to erase secret data */
-        secp256k1_memclear(buf, sizeof(buf));
+        secp256k1_memclear_explicit(buf, sizeof(buf));
         secp256k1_sha256_clear(&sha_tmp);
     }
-    secp256k1_memclear(rand, sizeof(rand));
+    secp256k1_memclear_explicit(rand, sizeof(rand));
     secp256k1_sha256_clear(&sha);
 }
 
@@ -518,7 +518,7 @@ int secp256k1_musig_nonce_gen_counter(const secp256k1_context* ctx, secp256k1_mu
     if (!secp256k1_musig_nonce_gen_internal(ctx, secnonce, pubnonce, buf, seckey, &pubkey, msg32, keyagg_cache, extra_input32)) {
         return 0;
     }
-    secp256k1_memclear(seckey, sizeof(seckey));
+    secp256k1_memclear_explicit(seckey, sizeof(seckey));
     return 1;
 }
 
@@ -691,7 +691,7 @@ int secp256k1_musig_partial_sign(const secp256k1_context* ctx, secp256k1_musig_p
     ret = secp256k1_musig_secnonce_load(ctx, k, &pk, secnonce);
     /* Set nonce to zero to avoid nonce reuse. This will cause subsequent calls
      * of this function to fail */
-    memset(secnonce, 0, sizeof(*secnonce));
+    secp256k1_memzero_explicit(secnonce, sizeof(*secnonce));
     if (!ret) {
         secp256k1_musig_partial_sign_clear(&sk, k);
         return 0;

@@ -192,7 +192,7 @@ int secp256k1_borromean_sign(const secp256k1_ecmult_gen_context *ecmult_gen_ctx,
     secp256k1_scalar_clear(&ens);
     secp256k1_ge_clear(&rge);
     secp256k1_gej_clear(&rgej);
-    secp256k1_memclear(tmp, 33);
+    secp256k1_memclear_explicit(tmp, 33);
     return 1;
 }
 

@@ -107,7 +107,7 @@ SECP256K1_INLINE static int secp256k1_rangeproof_genrand(secp256k1_scalar *sec,
     secp256k1_rfc6979_hmac_sha256_finalize(&rng);
     secp256k1_rfc6979_hmac_sha256_clear(&rng);
     secp256k1_scalar_clear(&acc);
-    secp256k1_memclear(tmp, 32);
+    secp256k1_memclear_explicit(tmp, 32);
     return ret;
 }
 
@@ -270,7 +270,7 @@ SECP256K1_INLINE static int secp256k1_rangeproof_sign_impl(const secp256k1_ecmul
     if (!secp256k1_rangeproof_genrand(sec, s, prep, rsizes, rings, nonce, commit, proof, len, genp)) {
         return 0;
     }
-    secp256k1_memclear(prep, 4096);
+    secp256k1_memclear_explicit(prep, 4096);
     for (i = 0; i < rings; i++) {
         /* Sign will overwrite the non-forged signature, move that random value into the nonce. */
         k[i] = s[i * 4 + secidx[i]];
@@ -332,7 +332,7 @@ SECP256K1_INLINE static int secp256k1_rangeproof_sign_impl(const secp256k1_ecmul
     }
     VERIFY_CHECK(len <= *plen);
     *plen = len;
-    secp256k1_memclear(prep, 4096);
+    secp256k1_memclear_explicit(prep, 4096);
     return 1;
 }
 
@@ -473,7 +473,7 @@ SECP256K1_INLINE static int secp256k1_rangeproof_rewind_inner(secp256k1_scalar *
         }
     }
     *mlen = offset;
-    secp256k1_memclear(prep, 4096);
+    secp256k1_memclear_explicit(prep, 4096);
     for (i = 0; i < 128; i++) {
         secp256k1_scalar_clear(&s_orig[i]);
     }

@@ -94,7 +94,7 @@ static int nonce_function_bip340(unsigned char *nonce32, const unsigned char *ms
     secp256k1_sha256_write(&sha, msg, msglen);
     secp256k1_sha256_finalize(&sha, nonce32);
     secp256k1_sha256_clear(&sha);
-    secp256k1_memclear(masked_key, sizeof(masked_key));
+    secp256k1_memclear_explicit(masked_key, sizeof(masked_key));
 
     return 1;
 }
@@ -190,8 +190,8 @@ static int secp256k1_schnorrsig_sign_internal(const secp256k1_context* ctx, unsi
     secp256k1_memczero(sig64, 64, !ret);
     secp256k1_scalar_clear(&k);
     secp256k1_scalar_clear(&sk);
-    secp256k1_memclear(seckey, sizeof(seckey));
-    secp256k1_memclear(nonce32, sizeof(nonce32));
+    secp256k1_memclear_explicit(seckey, sizeof(seckey));
+    secp256k1_memclear_explicit(nonce32, sizeof(nonce32));
     secp256k1_gej_clear(&rj);
 
     return ret;

@@ -55,11 +55,11 @@ SECP256K1_INLINE static int secp256k1_surjection_genrand(secp256k1_scalar *s, si
         secp256k1_sha256_clear(&sha256_en);
         secp256k1_scalar_set_b32(&s[i], sec_input, &overflow);
         if (overflow == 1) {
-            secp256k1_memclear(sec_input, 32);
+            secp256k1_memclear_explicit(sec_input, 32);
             return 0;
         }
     }
-    secp256k1_memclear(sec_input, 32);
+    secp256k1_memclear_explicit(sec_input, 32);
     return 1;
 }
 

@@ -54,7 +54,7 @@ int secp256k1_whitelist_sign(const secp256k1_context* ctx, secp256k1_whitelist_s
                 break;
             }
             secp256k1_scalar_set_b32(&non, nonce32, &overflow);
-            secp256k1_memclear(nonce32, 32);
+            secp256k1_memclear_explicit(nonce32, 32);
             if (overflow || secp256k1_scalar_is_zero(&non)) {
                 count++;
                 continue;
@@ -80,7 +80,7 @@ int secp256k1_whitelist_sign(const secp256k1_context* ctx, secp256k1_whitelist_s
                 break;
             }
         }
-        secp256k1_memclear(seckey32, 32);
+        secp256k1_memclear_explicit(seckey32, 32);
     }
     /* Actually sign */
     if (ret) {

@@ -28,7 +28,7 @@ static const secp256k1_scalar secp256k1_scalar_one = SECP256K1_SCALAR_CONST(0, 0
 static const secp256k1_scalar secp256k1_scalar_zero = SECP256K1_SCALAR_CONST(0, 0, 0, 0, 0, 0, 0, 0);
 
 SECP256K1_INLINE static void secp256k1_scalar_clear(secp256k1_scalar *r) {
-    secp256k1_memclear(r, sizeof(secp256k1_scalar));
+    secp256k1_memclear_explicit(r, sizeof(secp256k1_scalar));
 }
 
 static int secp256k1_scalar_set_b32_seckey(secp256k1_scalar *r, const unsigned char *bin) {