csecp256k1

Haskell FFI bindings to bitcoin-core/secp256k1 (docs.ppad.tech/csecp256k1).
git clone git://git.ppad.tech/csecp256k1.git
Log | Files | Refs | README | LICENSE

README.md (3902B)


      1 # ppad-csecp256k1
      2 
      3 ![](https://img.shields.io/badge/license-MIT-brightgreen)
      4 [![](https://img.shields.io/badge/haddock-csecp256k1-lightblue)](https://docs.ppad.tech/csecp256k1)
      5 
      6 Bindings to bitcoin-core/secp256k1, which provides digital signatures
      7 and other cryptographic primitives on the secp256k1 elliptic curve.
      8 
      9 This library exposes a minimal subset of the underlying library, mainly
     10 supporting ECDSA/Schnorr signatures and ECDH secret computation, as well
     11 as utilities for public key manipulation.
     12 
     13 ## Documentation
     14 
     15 API documentation and examples are hosted at
     16 [docs.ppad.tech/csecp256k1][hadoc].
     17 
     18 ## Performance
     19 
     20 As we bind to libsecp256k1, the resulting functions are very fast:
     21 
     22 ```
     23   benchmarking csecp256k1/ecdsa/sign
     24   time                 33.67 μs   (33.43 μs .. 34.00 μs)
     25                        1.000 R²   (0.999 R² .. 1.000 R²)
     26   mean                 33.74 μs   (33.64 μs .. 33.87 μs)
     27   std dev              378.5 ns   (259.2 ns .. 606.8 ns)
     28 
     29   benchmarking csecp256k1/ecdsa/verify
     30   time                 38.01 μs   (37.44 μs .. 38.65 μs)
     31                        0.999 R²   (0.998 R² .. 1.000 R²)
     32   mean                 37.82 μs   (37.56 μs .. 38.16 μs)
     33   std dev              912.8 ns   (657.5 ns .. 1.263 μs)
     34   variance introduced by outliers: 22% (moderately inflated)
     35 
     36   benchmarking csecp256k1/schnorr/sign
     37   time                 49.97 μs   (49.60 μs .. 50.41 μs)
     38                        0.999 R²   (0.999 R² .. 1.000 R²)
     39   mean                 49.95 μs   (49.54 μs .. 50.54 μs)
     40   std dev              1.618 μs   (1.200 μs .. 2.399 μs)
     41   variance introduced by outliers: 34% (moderately inflated)
     42 
     43   benchmarking csecp256k1/schnorr/verify
     44   time                 41.84 μs   (41.32 μs .. 42.26 μs)
     45                        0.999 R²   (0.998 R² .. 0.999 R²)
     46   mean                 41.50 μs   (41.06 μs .. 41.94 μs)
     47   std dev              1.432 μs   (1.167 μs .. 1.715 μs)
     48   variance introduced by outliers: 37% (moderately inflated)
     49 
     50   benchmarking csecp256k1/ecdh/ecdh
     51   time                 47.43 μs   (46.78 μs .. 48.19 μs)
     52                        0.998 R²   (0.997 R² .. 0.999 R²)
     53   mean                 46.86 μs   (46.33 μs .. 47.58 μs)
     54   std dev              2.075 μs   (1.609 μs .. 2.747 μs)
     55   variance introduced by outliers: 49% (moderately inflated)
     56 ```
     57 
     58 ## Security
     59 
     60 These bindings aim at the maximum security achievable in a
     61 garbage-collected language under an optimizing compiler such as GHC, in
     62 which strict constant-timeness can be challenging to achieve.
     63 
     64 The Schnorr implementation within has been tested against the [official
     65 BIP0340 vectors][ut340] (sans those using arbitrary-size messages, which
     66 we're not at present supporting), and ECDSA has been tested against the
     67 relevant [Wycheproof vectors][wyche].
     68 
     69 If you discover any vulnerabilities, please disclose them via
     70 security@ppad.tech.
     71 
     72 ## Development
     73 
     74 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
     75 development shell with:
     76 
     77 ```
     78 $ nix develop
     79 ```
     80 
     81 Then do e.g.:
     82 
     83 ```
     84 $ cabal repl ppad-csecp256k1
     85 ```
     86 
     87 to get a REPL for the main library, or:
     88 
     89 ```
     90 $ cabal repl secp256k1-sys-tests
     91 ```
     92 
     93 to get one for the internal test suite. You can run all tests via:
     94 
     95 ```
     96 $ cabal test
     97 ```
     98 
     99 and the benchmarks via:
    100 
    101 ```
    102 $ cabal bench
    103 ```
    104 
    105 ## Attribution
    106 
    107 This implementation has benefited greatly and uses modified versions of
    108 code from both [secp256k1-haskell][hsecp] (test cases, FFI/bytestring
    109 manipulation) and [rust-secp256k1][rsecp] (dependency vendoring).
    110 
    111 [nixos]: https://nixos.org/
    112 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html
    113 [hadoc]: https://docs.ppad.tech/csecp256k1
    114 [hsecp]: https://github.com/haskoin/secp256k1-haskell
    115 [rsecp]: https://github.com/rust-bitcoin/rust-secp256k1
    116 [ut340]: https://github.com/bitcoin/bips/blob/master/bip-0340/test-vectors.csv
    117 [wyche]: https://github.com/C2SP/wycheproof