selftest: Expose in public API

Author: real-or-random

doc/CHANGELOG.md

@@ -10,6 +10,9 @@ Each change falls into one of the following categories: Added, Changed, Deprecat
  - Deprecated context flags `SECP256K1_CONTEXT_VERIFY` and `SECP256K1_CONTEXT_NONE`. Use `SECP256K1_CONTEXT_SIGN` instead.
  - Renamed `secp256k1_context_no_precomp` to `secp256k1_context_static`.
 
+### Added
+ - Added `secp256k1_selftest`, to be used in conjunction with `secp256k1_context_static`.
+
 ## [MAJOR.MINOR.PATCH] - YYYY-MM-DD
 
 ### Added/Changed/Deprecated/Removed/Fixed/Security

include/secp256k1.h

@@ -214,19 +214,41 @@ typedef int (*secp256k1_nonce_function)(
 #define SECP256K1_TAG_PUBKEY_HYBRID_EVEN 0x06
 #define SECP256K1_TAG_PUBKEY_HYBRID_ODD 0x07
 
-/** A built-in constant secp256k1 context object with static storage duration.
+/** A built-in constant secp256k1 context object with static storage duration, to be
+ *  used in conjunction with secp256k1_selftest.
  *
  *  This context object is *not* "initialized for signing", i.e., it cannot be used
  *  for certain functions that operate on secret keys, e.g., signing and public key
  *  generation. See secp256k1_context_create if you need a context object initialized
  *  for signing.
+ *
+ *  It is highly recommended to call secp256k1_selftest before using this context.
  */
 SECP256K1_API extern const secp256k1_context *secp256k1_context_static;
 
 /** Deprecated alias for secp256k1_context_no_precomp. */
 SECP256K1_API extern const secp256k1_context *secp256k1_context_no_precomp
 SECP256K1_DEPRECATED("Use secp256k1_context_static instead");
 
+/** Perform basic self tests (to be used in conjunction with secp256k1_context_static)
+ *
+ *  This function performs self tests that detect some serious usage errors and
+ *  similar conditions, e.g., when the library is compiled for the wrong endianness.
+ *  This is a last resort measure to be used in production. The performed tests are
+ *  very rudimentary and are not intended as a replacement for running the test
+ *  binaries.
+ *
+ *  It is highly recommended to call this before using secp256k1_context_static.
+ *  It is not necessary to call this function before using a context created with
+ *  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
+ *  program (see secp256k1_context_set_error_callback).
+ */
+SECP256K1_API void secp256k1_selftest(void);
+
+
 /** Create a secp256k1 context object (in dynamically allocated memory).
  *
  *  This function uses malloc to allocate memory. It is guaranteed that malloc is

src/secp256k1.c

@@ -71,6 +71,12 @@ static const secp256k1_context secp256k1_context_static_ = {
 const secp256k1_context *secp256k1_context_static = &secp256k1_context_static_;
 const secp256k1_context *secp256k1_context_no_precomp = &secp256k1_context_static_;
 
+void secp256k1_selftest(void) {
+    if (!secp256k1_selftest_passes()) {
+        secp256k1_callback_call(&default_error_callback, "self test failed");
+    }
+}
+
 size_t secp256k1_context_preallocated_size(unsigned int flags) {
     size_t ret = sizeof(secp256k1_context);
     /* A return value of 0 is reserved as an indicator for errors when we call this function internally. */
@@ -95,9 +101,7 @@ secp256k1_context* secp256k1_context_preallocated_create(void* prealloc, unsigne
     size_t prealloc_size;
     secp256k1_context* ret;
 
-    if (!secp256k1_selftest_passes()) {
-        secp256k1_callback_call(&default_error_callback, "self test failed");
-    }
+    secp256k1_selftest();
 
     prealloc_size = secp256k1_context_preallocated_size(flags);
     if (prealloc_size == 0) {

src/tests.c

@@ -140,6 +140,11 @@ void random_scalar_order_b32(unsigned char *b32) {
     secp256k1_scalar_get_b32(b32, &num);
 }
 
+void run_selftest_tests(void) {
+    /* Test public API */
+    secp256k1_selftest();
+}
+
 void run_context_tests(int use_prealloc) {
     secp256k1_pubkey pubkey;
     secp256k1_pubkey zero_pubkey;
@@ -7083,6 +7088,7 @@ int main(int argc, char **argv) {
     secp256k1_testrand_init(argc > 2 ? argv[2] : NULL);
 
     /* initialize */
+    run_selftest_tests();
     run_context_tests(0);
     run_context_tests(1);
     run_scratch_tests();