Upstream PRs 1579, 1631, 1633, 1634, 1641, 1650, 1646, 1654

CHANGELOG.md

@@ -10,14 +10,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2024-11-04
+
 #### Added
  - New module `musig` implements the MuSig2 multisignature scheme according to the [BIP 327 specification](https://github.com/bitcoin/bips/blob/master/bip-0327.mediawiki). See:
    - Header file `include/secp256k1_musig.h` which defines the new API.
    - Document `doc/musig.md` for further notes on API usage.
    - Usage example `examples/musig.c`.
+ - New CMake variable `SECP256K1_APPEND_LDFLAGS` for appending linker flags to the build command.
+
+#### Changed
+ - API functions now use a significantly more robust method to clear secrets from the stack before returning. However, secret clearing remains a best-effort security measure and cannot guarantee complete removal.
+ - Any type `secp256k1_foo` can now be forward-declared using `typedef struct secp256k1_foo secp256k1_foo;` (or also `struct secp256k1_foo;` in C++).
+ - Organized CMake build artifacts into dedicated directories (`bin/` for executables, `lib/` for libraries) to improve build output structure and Windows shared library compatibility.
 
 #### Removed
- - Removed the `secp256k1_scratch_space` struct and its associated functions `secp256k1_scratch_space_create` `secp256k1_scratch_space_destroy` because the scratch space was unused in the API.
+ - Removed the `secp256k1_scratch_space` struct and its associated functions `secp256k1_scratch_space_create` and `secp256k1_scratch_space_destroy` because the scratch space was unused in the API.
+
+#### ABI Compatibility
+The symbols `secp256k1_scratch_space_create` and `secp256k1_scratch_space_destroy` were removed.
+Otherwise, the library maintains backward compatibility with versions 0.3.x through 0.5.x.
 
 ## [0.5.1] - 2024-08-01
 
@@ -155,7 +167,8 @@ This version was in fact never released.
 The number was given by the build system since the introduction of autotools in Jan 2014 (ea0fe5a5bf0c04f9cc955b2966b614f5f378c6f6).
 Therefore, this version number does not uniquely identify a set of source files.
 
-[unreleased]: https://github.com/bitcoin-core/secp256k1/compare/v0.5.1...HEAD
+[unreleased]: https://github.com/bitcoin-core/secp256k1/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/bitcoin-core/secp256k1/compare/v0.5.1...v0.6.0
 [0.5.1]: https://github.com/bitcoin-core/secp256k1/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/bitcoin-core/secp256k1/compare/v0.4.1...v0.5.0
 [0.4.1]: https://github.com/bitcoin-core/secp256k1/compare/v0.4.0...v0.4.1

CMakeLists.txt

@@ -7,7 +7,7 @@ project(libsecp256k1
   # The package (a.k.a. release) version is based on semantic versioning 2.0.0 of
   # the API. All changes in experimental modules are treated as
   # backwards-compatible and therefore at most increase the minor version.
-  VERSION 0.5.2
+  VERSION 0.6.1
   DESCRIPTION "Optimized C library for ECDSA signatures and secret/public key operations on curve secp256k1."
   HOMEPAGE_URL "https://github.com/bitcoin-core/secp256k1"
   LANGUAGES C
@@ -31,9 +31,9 @@ endif()
 # https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html
 # All changes in experimental modules are treated as if they don't affect the
 # interface and therefore only increase the revision.
-set(${PROJECT_NAME}_LIB_VERSION_CURRENT 4)
-set(${PROJECT_NAME}_LIB_VERSION_REVISION 2)
-set(${PROJECT_NAME}_LIB_VERSION_AGE 2)
+set(${PROJECT_NAME}_LIB_VERSION_CURRENT 5)
+set(${PROJECT_NAME}_LIB_VERSION_REVISION 1)
+set(${PROJECT_NAME}_LIB_VERSION_AGE 0)
 
 #=============================
 # Language setup
@@ -55,7 +55,7 @@ option(SECP256K1_INSTALL "Enable installation." ${PROJECT_IS_TOP_LEVEL})
 ## Modules
 
 # We declare all options before processing them, to make sure we can express
-# dependendencies while processing.
+# dependencies while processing.
 option(SECP256K1_ENABLE_MODULE_ECDH "Enable ECDH module." ON)
 option(SECP256K1_ENABLE_MODULE_RECOVERY "Enable ECDSA pubkey recovery module." OFF)
 option(SECP256K1_ENABLE_MODULE_EXTRAKEYS "Enable extrakeys module." ON)

CONTRIBUTING.md

@@ -74,6 +74,7 @@ In addition, libsecp256k1 tries to maintain the following coding conventions:
 * User-facing comment lines in headers should be limited to 80 chars if possible.
 * All identifiers in file scope should start with `secp256k1_`.
 * Avoid trailing whitespace.
+* Use the constants `EXIT_SUCCESS`/`EXIT_FAILURE` (defined in `stdlib.h`) to indicate program execution status for examples and other binaries.
 
 ### Tests
 

Makefile.am

@@ -267,6 +267,7 @@ maintainer-clean-local: clean-testvectors
 ### Additional files to distribute
 EXTRA_DIST = autogen.sh CHANGELOG.md SECURITY.md
 EXTRA_DIST += doc/release-process.md doc/safegcd_implementation.md
+EXTRA_DIST += doc/ellswift.md doc/musig.md
 EXTRA_DIST += examples/EXAMPLES_COPYING
 EXTRA_DIST += sage/gen_exhaustive_groups.sage
 EXTRA_DIST += sage/gen_split_lambda_constants.sage

README.md

@@ -17,14 +17,50 @@ Experimental features are made available for testing and review by the community
 Build steps
 -----------
 
+Obtaining and verifying
+-----------------------
+
+The git tag for each release (e.g. `v0.6.0`) is GPG-signed by one of the maintainers.
+For a fully verified build of this project, it is recommended to obtain this repository
+via git, obtain the GPG keys of the signing maintainer(s), and then verify the release
+tag's signature using git.
+
+This can be done with the following steps:
+
+1. Obtain the GPG keys listed in [SECURITY.md](./SECURITY.md).
+2. If possible, cross-reference these key IDs with another source controlled by its owner (e.g.
+   social media, personal website). This is to mitigate the unlikely case that incorrect 
+   content is being presented by this repository.
+3. Clone the repository: 
+    ```
+    git clone https://github.com/bitcoin-core/secp256k1
+    ```
+4. Check out the latest release tag, e.g. 
+    ```
+    git checkout v0.6.0
+    ```
+5. Use git to verify the GPG signature: 
+   ```
+   % git tag -v v0.6.0 | grep -C 3 'Good signature'
+
+   gpg: Signature made Mon 04 Nov 2024 12:14:44 PM EST
+   gpg:                using RSA key 4BBB845A6F5A65A69DFAEC234861DBF262123605
+   gpg: Good signature from "Jonas Nick <jonas@n-ck.net>" [unknown]
+   gpg:                 aka "Jonas Nick <jonasd.nick@gmail.com>" [unknown]
+   gpg: WARNING: This key is not certified with a trusted signature!
+   gpg:          There is no indication that the signature belongs to the owner.
+   Primary key fingerprint: 36C7 1A37 C9D9 88BD E825  08D9 B1A7 0E4F 8DCD 0366
+        Subkey fingerprint: 4BBB 845A 6F5A 65A6 9DFA  EC23 4861 DBF2 6212 3605
+   ```
+
 Building with Autotools
 -----------------------
 
-    $ ./autogen.sh
-    $ ./configure
-    $ make
-    $ make check  # run the test suite
-    $ sudo make install  # optional
+    $ ./autogen.sh       # Generate a ./configure script
+    $ ./configure        # Generate a build system
+    $ make               # Run the actual build process
+    $ make check         # Run the test suite
+    $ sudo make install  # Install the library into the system (optional)
 
 To compile optional modules (such as Schnorr signatures), you need to run `./configure` with additional flags (such as `--enable-module-schnorrsig`). Run `./configure --help` to see the full list of available flags. For experimental modules, you will also need `--enable-experimental` as well as a flag for each individual module, e.g. `--enable-module-rangeproof`.
 
@@ -35,24 +71,23 @@ To maintain a pristine source tree, CMake encourages to perform an out-of-source
 
 ### Building on POSIX systems
 
-    $ mkdir build && cd build
-    $ cmake ..
-    $ cmake --build .
-    $ ctest  # run the test suite
-    $ sudo cmake --install .  # optional
+    $ cmake -B build              # Generate a build system in subdirectory "build"
+    $ cmake --build build         # Run the actual build process
+    $ ctest --test-dir build      # Run the test suite
+    $ sudo cmake --install build  # Install the library into the system (optional)
 
-To compile optional modules (such as Schnorr signatures), you need to run `cmake` with additional flags (such as `-DSECP256K1_ENABLE_MODULE_SCHNORRSIG=ON`). Run `cmake .. -LH` to see the full list of available flags.
+To compile optional modules (such as Schnorr signatures), you need to run `cmake` with additional flags (such as `-DSECP256K1_ENABLE_MODULE_SCHNORRSIG=ON`). Run `cmake -B build -LH` or `ccmake -B build` to see the full list of available flags.
 
 ### Cross compiling
 
 To alleviate issues with cross compiling, preconfigured toolchain files are available in the `cmake` directory.
 For example, to cross compile for Windows:
 
-    $ cmake .. -DCMAKE_TOOLCHAIN_FILE=../cmake/x86_64-w64-mingw32.toolchain.cmake
+    $ cmake -B build -DCMAKE_TOOLCHAIN_FILE=cmake/x86_64-w64-mingw32.toolchain.cmake
 
 To cross compile for Android with [NDK](https://developer.android.com/ndk/guides/cmake) (using NDK's toolchain file, and assuming the `ANDROID_NDK_ROOT` environment variable has been set):
 
-    $ cmake .. -DCMAKE_TOOLCHAIN_FILE="${ANDROID_NDK_ROOT}/build/cmake/android.toolchain.cmake" -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=28
+    $ cmake -B build -DCMAKE_TOOLCHAIN_FILE="${ANDROID_NDK_ROOT}/build/cmake/android.toolchain.cmake" -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=28
 
 ### Building on Windows
 
@@ -62,7 +97,7 @@ The following example assumes using of Visual Studio 2022 and CMake v3.21+.
 
 In "Developer Command Prompt for VS 2022":
 
-    >cmake -G "Visual Studio 17 2022" -A x64 -S . -B build
+    >cmake -G "Visual Studio 17 2022" -A x64 -B build
     >cmake --build build --config RelWithDebInfo
 
 Usage examples

configure.ac

@@ -297,8 +297,8 @@ fi
 print_msan_notice=no
 if test x"$enable_ctime_tests" = x"yes"; then
   SECP_MSAN_CHECK
-  # MSan on Clang >=16 reports unitialized memory in function parameters and return values, even if
-  # the uninitalized variable is never actually "used". This is called "eager" checking, and it's
+  # MSan on Clang >=16 reports uninitialized memory in function parameters and return values, even if
+  # the uninitialized variable is never actually "used". This is called "eager" checking, and it's
   # sounds like good idea for normal use of MSan. However, it yields many false positives in the
   # ctime_tests because many return values depend on secret (i.e., "uninitialized") values, and
   # we're only interested in detecting branches (which count as "uses") on secret data.

examples/ecdh.c

@@ -8,6 +8,7 @@
  *************************************************************************/
 
 #include <stdio.h>
+#include <stdlib.h>
 #include <assert.h>
 #include <string.h>
 
@@ -33,7 +34,7 @@ int main(void) {
     secp256k1_context* ctx = secp256k1_context_create(SECP256K1_CONTEXT_NONE);
     if (!fill_random(randomize, sizeof(randomize))) {
         printf("Failed to generate randomness\n");
-        return 1;
+        return EXIT_FAILURE;
     }
     /* Randomizing the context is recommended to protect against side-channel
      * leakage See `secp256k1_context_randomize` in secp256k1.h for more
@@ -44,14 +45,14 @@ int main(void) {
     /*** Key Generation ***/
     if (!fill_random(seckey1, sizeof(seckey1)) || !fill_random(seckey2, sizeof(seckey2))) {
         printf("Failed to generate randomness\n");
-        return 1;
+        return EXIT_FAILURE;
     }
     /* 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;
+        return EXIT_FAILURE;
     }
 
     /* Public key creation using a valid context with a verified secret key should never fail */
@@ -116,5 +117,5 @@ int main(void) {
     secure_erase(shared_secret1, sizeof(shared_secret1));
     secure_erase(shared_secret2, sizeof(shared_secret2));
 
-    return 0;
+    return EXIT_SUCCESS;
 }

examples/ecdsa.c

@@ -8,6 +8,7 @@
  *************************************************************************/
 
 #include <stdio.h>
+#include <stdlib.h>
 #include <assert.h>
 #include <string.h>
 
@@ -40,7 +41,7 @@ int main(void) {
     secp256k1_context* ctx = secp256k1_context_create(SECP256K1_CONTEXT_NONE);
     if (!fill_random(randomize, sizeof(randomize))) {
         printf("Failed to generate randomness\n");
-        return 1;
+        return EXIT_FAILURE;
     }
     /* Randomizing the context is recommended to protect against side-channel
      * leakage See `secp256k1_context_randomize` in secp256k1.h for more
@@ -51,14 +52,14 @@ int main(void) {
     /*** Key Generation ***/
     if (!fill_random(seckey, sizeof(seckey))) {
         printf("Failed to generate randomness\n");
-        return 1;
+        return EXIT_FAILURE;
     }
     /* 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;
+        return EXIT_FAILURE;
     }
 
     /* Public key creation using a valid context with a verified secret key should never fail */
@@ -92,13 +93,13 @@ int main(void) {
     /* Deserialize the signature. This will return 0 if the signature can't be parsed correctly. */
     if (!secp256k1_ecdsa_signature_parse_compact(ctx, &sig, serialized_signature)) {
         printf("Failed parsing the signature\n");
-        return 1;
+        return EXIT_FAILURE;
     }
 
     /* Deserialize the public key. This will return 0 if the public key can't be parsed correctly. */
     if (!secp256k1_ec_pubkey_parse(ctx, &pubkey, compressed_pubkey, sizeof(compressed_pubkey))) {
         printf("Failed parsing the public key\n");
-        return 1;
+        return EXIT_FAILURE;
     }
 
     /* Verify a signature. This will return 1 if it's valid and 0 if it's not. */
@@ -133,5 +134,5 @@ int main(void) {
      * will remove any writes that aren't used. */
     secure_erase(seckey, sizeof(seckey));
 
-    return 0;
+    return EXIT_SUCCESS;
 }

examples/ellswift.c

@@ -13,6 +13,7 @@
  */
 
 #include <stdio.h>
+#include <stdlib.h>
 #include <assert.h>
 #include <string.h>
 
@@ -38,7 +39,7 @@ int main(void) {
     ctx = secp256k1_context_create(SECP256K1_CONTEXT_NONE);
     if (!fill_random(randomize, sizeof(randomize))) {
         printf("Failed to generate randomness\n");
-        return 1;
+        return EXIT_FAILURE;
     }
     /* Randomizing the context is recommended to protect against side-channel
      * leakage. See `secp256k1_context_randomize` in secp256k1.h for more
@@ -49,22 +50,22 @@ int main(void) {
     /*** Generate secret keys ***/
     if (!fill_random(seckey1, sizeof(seckey1)) || !fill_random(seckey2, sizeof(seckey2))) {
         printf("Failed to generate randomness\n");
-        return 1;
+        return EXIT_FAILURE;
     }
     /* 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;
+        return EXIT_FAILURE;
     }
 
     /* Generate ElligatorSwift public keys. This should never fail with valid context and
        verified secret keys. Note that providing additional randomness (fourth parameter) is
        optional, but recommended. */
     if (!fill_random(auxrand1, sizeof(auxrand1)) || !fill_random(auxrand2, sizeof(auxrand2))) {
         printf("Failed to generate randomness\n");
-        return 1;
+        return EXIT_FAILURE;
     }
     return_val = secp256k1_ellswift_create(ctx, ellswift_pubkey1, seckey1, auxrand1);
     assert(return_val);
@@ -117,5 +118,5 @@ int main(void) {
     secure_erase(shared_secret1, sizeof(shared_secret1));
     secure_erase(shared_secret2, sizeof(shared_secret2));
 
-    return 0;
+    return EXIT_SUCCESS;
 }