Add usage examples #748

elichai · 2020-04-30T12:12:37Z

Resolves #184

I didn't add a sign/verify/recover example yet because I'd prefer that the example included hashing a message,
but we don't provide a hash function so I decided to start only with key generation and ECDH, and get feedback.

I did not check the example on windows, but did try to implement it correctly, if anyone has access to a windows machine(and knows how to build on windows hehe) please test this :)

P.S. Should the usage examples be MIT or CC0(Public Domain)?

jonasnick

Very nice!

Alternatively the module-specific examples could be in their respective module directory. But I think either way is fine.

examples/ecdh.c

examples/random.h

examples/ecdh.c

examples/random.h

elichai · 2020-04-30T19:04:49Z

Alternatively the module-specific examples could be in their respective module directory. But I think either way is fine.

I thought about it, but I think that for newcomers it's easier to see an examples directory at the top level and start from there.

examples/ecdh.c

real-or-random · 2020-05-01T11:22:17Z

My feeling is this entire issue of secret key handling deserves a broader discussion.

We don't have a key generation function and Core won't need one. If we're now targeting different users more, maybe it's time to have one. But it's hard, see all the discussion points above. And it really depends on the user's platform. So actually I'd be happy with good examples and some references to correct methods to get randomness on different OSes.

On the other hand, nothing should stop us from exporting a cleaning function in #636, even if we don't have one for key gen.

What are other libraries doing for key generation?

real-or-random · 2020-05-01T11:29:36Z

examples/keygen.c

+    size_t len;
+    secp256k1_pubkey pubkey;
+    secp256k1_context* ctx = secp256k1_context_create(SECP256K1_CONTEXT_SIGN);
+    while (1) {


I'd prefer not to loop here and instead bail out if we hit an invalid key.

The probability of hitting an invalid key is negligible if your randomness is good.
So this loop is only relevant if your randomness is broken. And then it hides the fact that your randomness is broken.

FWIW:
https://github.com/bitcoin/bitcoin/blob/master/src/key.cpp#L157
https://github.com/rust-bitcoin/rust-secp256k1/blob/master/src/key.rs#L118
https://github.com/bitcoin-core/secp256k1/blob/f39f99be0e6add959f534c03b93044cef066fe09/src/tests.c#L130:L141

Hm, I see. I still think that my argument holds up. Maybe @sipa can chime in for the code in Core.

While the probability of an invalid key is negligible (something like 1/2^128?), I feel that if the verify function is provided in the library then it could still be informative to include in the examples.

if (!secp256k1_ec_seckey_verify(ctx, seckey)) { printf("Invalid secret key\n"); return 1; }

real-or-random · 2020-07-29T09:55:27Z

examples/ecdh.c

+     * Which is why we create a context for signing(SECP256K1_CONTEXT_SIGN).
+     * (The docs for `secp256k1_ecdh` don't require any special context, just some context) */
+
+    secp256k1_context* ctx = secp256k1_context_create(SECP256K1_CONTEXT_SIGN);


The context should be randomized here.

jonasnick · 2020-11-05T22:44:14Z

Would be cool to revive this PR since it's really helpful, well-documented and provides best practices for getting randomness on different platforms. In particular, I don't think this PR should be blocked on the result of the key generation discussion. @elichai if you want to add examples for the schnorrsig module, feel free to do it, but we can also add this in a different PR.

elichai · 2020-11-09T16:14:28Z

Rebased, and replaced the keygen example with a schnorr and ecdsa examples.
Please review and comment if you think something I've done isn't best practice or some comment's wording isn't good enough

examples/ecdsa.c

README.md

.gitignore

Makefile.am

examples/random.h

examples/schnorr.c

examples/ecdh.c

examples/ecdsa.c

Makefile.am

examples/random.h

real-or-random · 2020-11-17T10:34:22Z

P.S. Should the usage examples be MIT or CC0(Public Domain)?

I think we should make them CC0 to avoid any doubt.

ssocolow · 2021-04-30T17:19:58Z

As a new user, simple example programs are really great. Thanks!

elichai · 2021-07-04T14:45:25Z

Rebased and fixed review comments,
Feel free to suggest alternative phrasings to the comments I wrote (English is my 2nd language)

elichai · 2021-07-07T10:20:50Z

Rebasing on master again so the CI will work

examples/random.h

scgbckbone · 2022-02-12T10:43:51Z

Tested ACK

ubuntu 20.04 Linux workstation 5.13.0-28-generic #31~20.04.1-Ubuntu SMP Wed Jan 19 14:08:10 UTC 2022 x86_64 x86_64 x86_64 GNU/Linux
windows 10 MINGW64_NT-10.0-19044 DESKTOP-UV75MOO 3.3.3-341.x86_64 2022-01-18 13:00 UTC x86_64 Msys

elichai · 2022-02-22T11:15:47Z

Fixed comments, and squashed

jonasnick

ACK beecb9a

real-or-random

@elichai Can you quickly fix the copyright and the msg_hash comment?

I think then this is good to go. We had many eyes on it and I can address the other two comments in another PR.

real-or-random · 2022-02-23T09:46:42Z

examples/ecdh.c

+/*************************************************************************
+ * Copyright (c) 2020-2021 Elichai Turkel                                *
+ * Distributed under the CC0 software license, see the accompanying file *
+ * EXAMPLES_COPYING or https://creativecommons.org/publicdomain/zero/1.0 *
+ *************************************************************************/


Sorry interrupting with legal stuff and not noticing earlier... I think it's weird to say "Copyright" and CC0 at the same time. And CC0 is strictly speaking not a software license. https://wiki.creativecommons.org/wiki/CC0_FAQ#May_I_apply_CC0_to_computer_software.3F_If_so.2C_is_there_a_recommended_implementation.3F provides some boilerplate.

Here's a suggestion, slightly adopted from the above to make sure it applies only to a single file.

Suggested change

/*************************************************************************

* Copyright (c) 2020-2021 Elichai Turkel *

* Distributed under the CC0 software license, see the accompanying file *

* EXAMPLES_COPYING or https://creativecommons.org/publicdomain/zero/1.0 *

*************************************************************************/

/*************************************************************************

* Written in 2020-2022 by Elichai Turkel *

* 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 *

*************************************************************************/

Yeah, I hate dealing with licenses. fixed

real-or-random · 2022-02-23T10:33:18Z

examples/ecdsa.c

+    /* Generate an ECDSA signature, note that even though here `msg_hash` is set
+    * to zeros, it MUST contain a hash, otherwise ECDSA is easily broken.


msg_hash is not set to zeros.

Thanks! fixed

real-or-random · 2022-02-23T10:43:03Z

examples/ecdsa.c

+    /* 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.
+     *
+     * TODO: Prevent these writes from being optimized out, as any good compiler
+     * will remove any writes that aren't used. */
+    memset(seckey, 0, sizeof(seckey));


I don't like the idea of having a TODO here. I mean we spent days getting the randomness right, then this feels wrong.

We could copy https://github.com/bitcoin/bitcoin/blob/7fcf53f7b4524572d1d0c9a5fdc388e87eb02416/src/support/cleanse.cpp#L14 and then really call the file util.h or refer to it...

In the interest of moving this forward, we suggest to leave this as is and I'm happy to open a further PR that fixes it.

real-or-random · 2022-02-23T11:00:30Z

examples/ecdh.c

+    return_val = secp256k1_context_randomize(ctx, randomize);
+    assert(return_val);
+
+    /*** Key Generation ***/


It may be good to add a header to every code section in this part, e.g., "Party 1: " and "Party 2:" or similar, to make sure.

This would require splitting the key generation loop but I think that's really better than. Real code wouldn't work like this, so I think we should avoid it in example code.

This is also something I can do in a follow-up PR.

Co-authored-by: Jonas Nick <jonasd.nick@gmail.com>

real-or-random

ACK 7c9502c

As I said, I can create a follow-up PR.

The one CI failure for the sage prover is harmless and only because just sage on CI was introduced after the last rebase of this PR. It will work on master.

jonasnick

ACK 7c9502c

elichai force-pushed the 2020-04-examples branch from 5365586 to 2e7decf Compare April 30, 2020 13:04

elichai changed the title ~~Add usage example~~ Add usage examples Apr 30, 2020

jonasnick reviewed Apr 30, 2020

View reviewed changes

examples/ecdh.c Outdated Show resolved Hide resolved

examples/random.h Outdated Show resolved Hide resolved

examples/ecdh.c Show resolved Hide resolved

examples/random.h Outdated Show resolved Hide resolved

examples/random.h Show resolved Hide resolved

jonasnick reviewed Apr 30, 2020

View reviewed changes

examples/ecdh.c Show resolved Hide resolved

real-or-random reviewed May 1, 2020

View reviewed changes

real-or-random mentioned this pull request May 1, 2020

Secret key generation and cleaning #749

Open

elichai force-pushed the 2020-04-examples branch from 2e7decf to c39074f Compare May 2, 2020 19:29

elichai mentioned this pull request May 3, 2020

Add macOS to the CI #750

Merged

real-or-random mentioned this pull request May 8, 2020

Add basic usage information on README [skip ci] #673

Closed

elichai force-pushed the 2020-04-examples branch from c39074f to 485c68b Compare May 19, 2020 06:46

jonasnick mentioned this pull request Jul 17, 2020

Add schnorrsig module which implements BIP-340 compliant signatures #558

Merged

real-or-random reviewed Jul 29, 2020

View reviewed changes

elichai force-pushed the 2020-04-examples branch from 485c68b to b7077be Compare July 30, 2020 08:53

elichai force-pushed the 2020-04-examples branch 2 times, most recently from 7e16921 to 0be44b4 Compare November 9, 2020 16:12

jonasnick reviewed Nov 16, 2020

View reviewed changes

elichai force-pushed the 2020-04-examples branch from 0be44b4 to a00271b Compare July 4, 2021 14:42

elichai force-pushed the 2020-04-examples branch from a00271b to 4cc6984 Compare July 7, 2021 10:19

elichai force-pushed the 2020-04-examples branch from 4cc6984 to 99fbf68 Compare July 7, 2021 10:20

jonasnick reviewed Jul 7, 2021

View reviewed changes

examples/random.h Outdated Show resolved Hide resolved

elichai mentioned this pull request Sep 23, 2021

Manual to use the API #978

Closed

real-or-random mentioned this pull request Dec 8, 2021

Replace MuSig(1) module with MuSig2 BlockstreamResearch/secp256k1-zkp#131

Merged

8 tasks

elichai force-pushed the 2020-04-examples branch from 4c43382 to beecb9a Compare February 22, 2022 11:15

jonasnick reviewed Feb 22, 2022

View reviewed changes

real-or-random reviewed Feb 23, 2022

View reviewed changes

elichai and others added 6 commits February 23, 2022 16:14

Add an ECDSA signing and verifying example

fee7d4b

Co-authored-by: Jonas Nick <jonasd.nick@gmail.com>

Add a Schnorr signing and verifying example

b0cfbcc

Co-authored-by: Jonas Nick <jonasd.nick@gmail.com>

Add a ecdh shared secret example

422a7cc

Co-authored-by: Jonas Nick <jonasd.nick@gmail.com>

Optionally compile the examples in autotools, compile+run in travis

517644e

Add usage examples to the readme

42e0343

Add a copy of the CC0 license to the examples

7c9502c

elichai force-pushed the 2020-04-examples branch from beecb9a to 7c9502c Compare February 23, 2022 14:15

real-or-random approved these changes Feb 23, 2022

View reviewed changes

jonasnick reviewed Feb 23, 2022

View reviewed changes

jonasnick merged commit 64b3497 into bitcoin-core:master Feb 23, 2022

jonasnick mentioned this pull request Mar 30, 2022

Upstream PRs 1064, 1049, 899, 1068, 1072, 1069, 1074, 1026, 1033, 748, 1079, 1088, 1090, 731, 1089, 995, 1094, 1093 BlockstreamResearch/secp256k1-zkp#174

Merged

hebasto mentioned this pull request Oct 28, 2022

Cleanup .gitignore file #1144

Merged

real-or-random mentioned this pull request Feb 27, 2023

Use arc4random_buf() as the best practice method for obtaining randomness on OpenBSD (examples) #1215

Open

		/* Generate an ECDSA signature, note that even though here `msg_hash` is set
		* to zeros, it MUST contain a hash, otherwise ECDSA is easily broken.

Add usage examples #748

Add usage examples #748

Uh oh!

Conversation

elichai commented Apr 30, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jonasnick left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

elichai commented Apr 30, 2020

Uh oh!

Uh oh!

real-or-random commented May 1, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jonasnick commented Nov 5, 2020

Uh oh!

elichai commented Nov 9, 2020

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

real-or-random commented Nov 17, 2020

Uh oh!

ssocolow commented Apr 30, 2021

Uh oh!

elichai commented Jul 4, 2021

Uh oh!

elichai commented Jul 7, 2021

Uh oh!

Uh oh!

scgbckbone commented Feb 12, 2022

Uh oh!

elichai commented Feb 22, 2022

Uh oh!

jonasnick left a comment

Choose a reason for hiding this comment

Uh oh!

real-or-random left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elichai Feb 23, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elichai commented Apr 30, 2020 •

edited

Loading

real-or-random commented May 1, 2020 •

edited

Loading

elichai Feb 23, 2022 •

edited

Loading