From fe4fbaa7f3eaa404f7ded669e611e28260839f9c Mon Sep 17 00:00:00 2001 From: Sebastian Falbesoner Date: Tue, 25 Jun 2024 16:52:38 +0200 Subject: [PATCH 1/2] examples: fix case typos in secret clearing paragraphs (s/, Or/, or/) --- examples/ecdh.c | 2 +- examples/ecdsa.c | 2 +- examples/schnorr.c | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/examples/ecdh.c b/examples/ecdh.c index 4b7b7d6154..d71fd2f604 100644 --- a/examples/ecdh.c +++ b/examples/ecdh.c @@ -108,7 +108,7 @@ int main(void) { /* It's best practice to try to clear secrets from memory after using them. * This is done because some bugs can allow an attacker to leak memory, for - * example through "out of bounds" array access (see Heartbleed), Or the OS + * example through "out of bounds" array access (see Heartbleed), or the OS * swapping them to disk. Hence, we overwrite the secret key buffer with zeros. * * Here we are preventing these writes from being optimized out, as any good compiler diff --git a/examples/ecdsa.c b/examples/ecdsa.c index d1d2b0e365..d5c4613d9c 100644 --- a/examples/ecdsa.c +++ b/examples/ecdsa.c @@ -128,7 +128,7 @@ int main(void) { /* It's best practice to try to clear secrets from memory after using them. * This is done because some bugs can allow an attacker to leak memory, for - * example through "out of bounds" array access (see Heartbleed), Or the OS + * example through "out of bounds" array access (see Heartbleed), or the OS * swapping them to disk. Hence, we overwrite the secret key buffer with zeros. * * Here we are preventing these writes from being optimized out, as any good compiler diff --git a/examples/schnorr.c b/examples/schnorr.c index 4c0dd1c1a9..b0409b986b 100644 --- a/examples/schnorr.c +++ b/examples/schnorr.c @@ -146,7 +146,7 @@ int main(void) { /* It's best practice to try to clear secrets from memory after using them. * This is done because some bugs can allow an attacker to leak memory, for - * example through "out of bounds" array access (see Heartbleed), Or the OS + * example through "out of bounds" array access (see Heartbleed), or the OS * swapping them to disk. Hence, we overwrite the secret key buffer with zeros. * * Here we are preventing these writes from being optimized out, as any good compiler From 31f84595c4fa8fcc89021790257b85416aae44f6 Mon Sep 17 00:00:00 2001 From: Sebastian Falbesoner Date: Tue, 25 Jun 2024 03:11:21 +0200 Subject: [PATCH 2/2] Add ellswift usage example This should hopefully be useful as orientation for users implementing the key exchange part of BIP324. Conceptually the example is not very different to the ECDH one, so a lot of code/comments are just copied (e.g. context creation, secret key generation, shared secret comparison, console output, cleanup with secret key clearing). --- .gitignore | 1 + CHANGELOG.md | 3 + Makefile.am | 11 ++++ README.md | 1 + examples/CMakeLists.txt | 4 ++ examples/ellswift.c | 123 ++++++++++++++++++++++++++++++++++++++++ 6 files changed, 143 insertions(+) create mode 100644 examples/ellswift.c diff --git a/.gitignore b/.gitignore index 574902b8b5..18e3259f59 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,7 @@ ctime_tests ecdh_example ecdsa_example schnorr_example +ellswift_example *.exe *.so *.a diff --git a/CHANGELOG.md b/CHANGELOG.md index a2855912fd..200653eba5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +#### Added + - Added usage example for an ElligatorSwift key exchange. + ## [0.5.0] - 2024-05-06 #### Added diff --git a/Makefile.am b/Makefile.am index 322e44eaab..8723b53b2c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -184,6 +184,17 @@ schnorr_example_LDFLAGS += -lbcrypt endif TESTS += schnorr_example endif +if ENABLE_MODULE_ELLSWIFT +noinst_PROGRAMS += ellswift_example +ellswift_example_SOURCES = examples/ellswift.c +ellswift_example_CPPFLAGS = -I$(top_srcdir)/include -DSECP256K1_STATIC +ellswift_example_LDADD = libsecp256k1.la +ellswift_example_LDFLAGS = -static +if BUILD_WINDOWS +ellswift_example_LDFLAGS += -lbcrypt +endif +TESTS += ellswift_example +endif endif ### Precomputed tables diff --git a/README.md b/README.md index e8d4123ab9..9b20dd79b8 100644 --- a/README.md +++ b/README.md @@ -114,6 +114,7 @@ Usage examples can be found in the [examples](examples) directory. To compile th * [ECDSA example](examples/ecdsa.c) * [Schnorr signatures example](examples/schnorr.c) * [Deriving a shared secret (ECDH) example](examples/ecdh.c) + * [ElligatorSwift key exchange example](examples/ellswift.c) To compile the Schnorr signature and ECDH examples, you also need to configure with `--enable-module-schnorrsig` and `--enable-module-ecdh`. diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt index 607bb67770..fd1ebce395 100644 --- a/examples/CMakeLists.txt +++ b/examples/CMakeLists.txt @@ -28,3 +28,7 @@ endif() if(SECP256K1_ENABLE_MODULE_SCHNORRSIG) add_example(schnorr) endif() + +if(SECP256K1_ENABLE_MODULE_ELLSWIFT) + add_example(ellswift) +endif() diff --git a/examples/ellswift.c b/examples/ellswift.c new file mode 100644 index 0000000000..52be7eebfb --- /dev/null +++ b/examples/ellswift.c @@ -0,0 +1,123 @@ +/************************************************************************* + * Written in 2024 by Sebastian Falbesoner * + * To the extent possible under law, the author(s) have dedicated all * + * copyright and related and neighboring rights to the software in this * + * file to the public domain worldwide. This software is distributed * + * without any warranty. For the CC0 Public Domain Dedication, see * + * EXAMPLES_COPYING or https://creativecommons.org/publicdomain/zero/1.0 * + *************************************************************************/ + +/** This file demonstrates how to use the ElligatorSwift module to perform + * a key exchange according to BIP 324. Additionally, see the documentation + * in include/secp256k1_ellswift.h and doc/ellswift.md. + */ + +#include +#include +#include + +#include +#include + +#include "examples_util.h" + +int main(void) { + secp256k1_context* ctx; + unsigned char randomize[32]; + unsigned char auxrand1[32]; + unsigned char auxrand2[32]; + unsigned char seckey1[32]; + unsigned char seckey2[32]; + unsigned char ellswift_pubkey1[64]; + unsigned char ellswift_pubkey2[64]; + unsigned char shared_secret1[32]; + unsigned char shared_secret2[32]; + int return_val; + + /* Create a secp256k1 context */ + ctx = secp256k1_context_create(SECP256K1_CONTEXT_NONE); + if (!fill_random(randomize, sizeof(randomize))) { + printf("Failed to generate randomness\n"); + return 1; + } + /* Randomizing the context is recommended to protect against side-channel + * leakage. See `secp256k1_context_randomize` in secp256k1.h for more + * information about it. This should never fail. */ + return_val = secp256k1_context_randomize(ctx, randomize); + assert(return_val); + + /*** Generate secret keys ***/ + + /* If the secret key is zero or out of range (bigger than secp256k1's + * order), we try to sample a new key. Note that the probability of this + * happening is negligible. */ + while (1) { + if (!fill_random(seckey1, sizeof(seckey1)) || !fill_random(seckey2, sizeof(seckey2))) { + printf("Failed to generate randomness\n"); + return 1; + } + if (secp256k1_ec_seckey_verify(ctx, seckey1) && secp256k1_ec_seckey_verify(ctx, seckey2)) { + break; + } + } + + /* 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_val = secp256k1_ellswift_create(ctx, ellswift_pubkey1, seckey1, auxrand1); + assert(return_val); + return_val = secp256k1_ellswift_create(ctx, ellswift_pubkey2, seckey2, auxrand2); + assert(return_val); + + /*** Create the shared secret on each side ***/ + + /* Perform x-only ECDH with seckey1 and ellswift_pubkey2. Should never fail + * with a verified seckey and valid pubkey. Note that both parties pass both + * EllSwift pubkeys in the same order; the pubkey of the calling party is + * determined by the "party" boolean (sixth parameter). */ + return_val = secp256k1_ellswift_xdh(ctx, shared_secret1, ellswift_pubkey1, ellswift_pubkey2, + seckey1, 0, secp256k1_ellswift_xdh_hash_function_bip324, NULL); + assert(return_val); + + /* Perform x-only ECDH with seckey2 and ellswift_pubkey1. Should never fail + * with a verified seckey and valid pubkey. */ + return_val = secp256k1_ellswift_xdh(ctx, shared_secret2, ellswift_pubkey1, ellswift_pubkey2, + seckey2, 1, secp256k1_ellswift_xdh_hash_function_bip324, NULL); + assert(return_val); + + /* Both parties should end up with the same shared secret */ + return_val = memcmp(shared_secret1, shared_secret2, sizeof(shared_secret1)); + assert(return_val == 0); + + printf( " Secret Key1: "); + print_hex(seckey1, sizeof(seckey1)); + printf( "EllSwift Pubkey1: "); + print_hex(ellswift_pubkey1, sizeof(ellswift_pubkey1)); + printf("\n Secret Key2: "); + print_hex(seckey2, sizeof(seckey2)); + printf( "EllSwift Pubkey2: "); + print_hex(ellswift_pubkey2, sizeof(ellswift_pubkey2)); + printf("\n Shared Secret: "); + print_hex(shared_secret1, sizeof(shared_secret1)); + + /* This will clear everything from the context and free the memory */ + secp256k1_context_destroy(ctx); + + /* It's best practice to try to clear secrets from memory after using them. + * This is done because some bugs can allow an attacker to leak memory, for + * example through "out of bounds" array access (see Heartbleed), or the OS + * swapping them to disk. Hence, we overwrite the secret key buffer with zeros. + * + * Here we are preventing these writes from being optimized out, as any good compiler + * will remove any writes that aren't used. */ + secure_erase(seckey1, sizeof(seckey1)); + secure_erase(seckey2, sizeof(seckey2)); + secure_erase(shared_secret1, sizeof(shared_secret1)); + secure_erase(shared_secret2, sizeof(shared_secret2)); + + return 0; +}