Add ellswift usage example #1551

1. 
   theStack commented at 2:17 pm on June 25, 2024: contributor

   This should hopefully be useful as orientation for users implementing the shared secret derivation 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).
2. in CHANGELOG.md:11 in 78fe9f495f outdated

    6@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
    7 
    8 ## [Unreleased]
    9 
   10+#### Added
   11+ - Added usage example for a ElligatorSwift key exchange.
   

   ---

   ---

   

   real-or-random commented at 2:43 pm on June 25, 2024:

   0 - Added usage example for an ElligatorSwift key exchange.
   

3. in examples/ellswift.c:81 in 78fe9f495f outdated

   76+    /*** Create the shared secret on each side ***/
   77+
   78+    /* Perform x-only ECDH with seckey1 and ellswift_pubkey2. Should never fail
   79+     * with a verified seckey and valid pubkey. Note that both parties pass both
   80+     * EllSwift pubkeys in the same order; the pubkey to be actually used for the
   81+     * shared secret derivation is determined by the "party" boolean (sixth parameter). */
   

   ---

   ---

   

   real-or-random commented at 2:46 pm on June 25, 2024:

   0     * EllSwift pubkeys in the same order; the pubkey of the calling party
   1     * is determined by the "party" boolean (sixth parameter). */
   

   I think this is a bit cleaner (still need to reformat the paragraph)

4. in examples/ellswift.c:112 in 78fe9f495f outdated

   107+    /* This will clear everything from the context and free the memory */
   108+    secp256k1_context_destroy(ctx);
   109+
   110+    /* It's best practice to try to clear secrets from memory after using them.
   111+     * This is done because some bugs can allow an attacker to leak memory, for
   112+     * example through "out of bounds" array access (see Heartbleed), Or the OS
   

   ---

   ---

   

   real-or-random commented at 2:47 pm on June 25, 2024:

   0     * example through "out of bounds" array access (see Heartbleed), or the OS
   

   is this copied from the other example? Then fix it there too.

5. 
   real-or-random commented at 2:47 pm on June 25, 2024: contributor

   Concept ACK
6. real-or-random added the label user-documentation on Jun 25, 2024
7. examples: fix case typos in secret clearing paragraphs (s/, Or/, or/) fe4fbaa7f3
8. 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).

   31f84595c4
9. theStack force-pushed on Jun 25, 2024
10. 
    theStack commented at 3:24 pm on June 25, 2024: contributor

    @real-or-random: Thanks for the quick review, force-pushed with all the suggestions taken.
11. in .gitignore:13 in 31f84595c4

     9@@ -10,6 +10,7 @@ ctime_tests
    10 ecdh_example
    11 ecdsa_example
    12 schnorr_example
    13+ellswift_example
    

    ---

    ---

    

    hebasto commented at 10:12 pm on June 25, 2024:

    nit: I understand that this doesn’t adhere to the surrounding code, but, strictly speaking, it should be

    0/ellswift_example
    

    ---

    

    real-or-random commented at 9:32 am on June 26, 2024:

    Yeah, feel free to adjust this for the binaries, but I guess either variant is fine (we also have the pattern *.exe, which may in rare cases a bit too coarse`…)
12. 
    hebasto commented at 10:12 pm on June 25, 2024: member

    31f84595c4fa8fcc89021790257b85416aae44f6

    I have reviewed both build systems changes and they look OK.

13. real-or-random approved
14. 
    real-or-random commented at 9:30 am on June 26, 2024: contributor

    utACK 31f84595c4fa8fcc89021790257b85416aae44f6
15. jonasnick approved
16. 
    jonasnick commented at 6:15 pm on July 10, 2024: contributor

    ACK 31f84595c4fa8fcc89021790257b85416aae44f6
17. jonasnick merged this on Jul 10, 2024
18. jonasnick closed this on Jul 10, 2024

    ---

19. theStack deleted the branch on Jul 10, 2024

Contributors
theStack real-or-random hebasto jonasnick

Labels
user-documentation