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 (3771B)


      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 For a pure Haskell secp256k1 implementation, see [ppad-secp256k1][ppads].
     14 
     15 ## Documentation
     16 
     17 API documentation and examples are hosted at
     18 [docs.ppad.tech/csecp256k1][hadoc].
     19 
     20 ## Performance
     21 
     22 As we bind to libsecp256k1, the resulting functions are very fast:
     23 
     24 ```
     25   benchmarking csecp256k1/ecdsa/sign
     26   time                 13.31 μs   (13.30 μs .. 13.31 μs)
     27                        1.000 R²   (1.000 R² .. 1.000 R²)
     28   mean                 13.33 μs   (13.32 μs .. 13.33 μs)
     29   std dev              11.15 ns   (8.932 ns .. 15.01 ns)
     30 
     31   benchmarking csecp256k1/ecdsa/verify
     32   time                 12.35 μs   (12.34 μs .. 12.38 μs)
     33                        1.000 R²   (1.000 R² .. 1.000 R²)
     34   mean                 12.35 μs   (12.35 μs .. 12.36 μs)
     35   std dev              21.83 ns   (9.273 ns .. 47.76 ns)
     36 
     37   benchmarking csecp256k1/schnorr/sign
     38   time                 18.35 μs   (18.35 μs .. 18.36 μs)
     39                        1.000 R²   (1.000 R² .. 1.000 R²)
     40   mean                 18.35 μs   (18.35 μs .. 18.35 μs)
     41   std dev              5.990 ns   (4.283 ns .. 9.131 ns)
     42 
     43   benchmarking csecp256k1/schnorr/verify
     44   time                 14.15 μs   (14.14 μs .. 14.15 μs)
     45                        1.000 R²   (1.000 R² .. 1.000 R²)
     46   mean                 14.14 μs   (14.13 μs .. 14.15 μs)
     47   std dev              30.51 ns   (14.54 ns .. 57.66 ns)
     48 
     49   benchmarking csecp256k1/ecdh/ecdh
     50   time                 15.02 μs   (15.02 μs .. 15.03 μs)
     51                        1.000 R²   (1.000 R² .. 1.000 R²)
     52   mean                 15.02 μs   (15.00 μs .. 15.03 μs)
     53   std dev              34.78 ns   (10.81 ns .. 71.53 ns)
     54 ```
     55 
     56 ## Security
     57 
     58 These bindings aim at the maximum security achievable in a
     59 garbage-collected language under an optimizing compiler such as GHC, in
     60 which strict constant-timeness can be challenging to achieve.
     61 
     62 The Schnorr implementation within has been tested against the [official
     63 BIP0340 vectors][ut340] (sans those using arbitrary-size messages, which
     64 we're not at present supporting), and ECDSA has been tested against the
     65 relevant [Wycheproof vectors][wyche].
     66 
     67 If you discover any vulnerabilities, please disclose them via
     68 security@ppad.tech.
     69 
     70 ## Development
     71 
     72 You'll require [Nix][nixos] with [flake][flake] support enabled. Enter a
     73 development shell with:
     74 
     75 ```
     76 $ nix develop
     77 ```
     78 
     79 Then do e.g.:
     80 
     81 ```
     82 $ cabal repl ppad-csecp256k1
     83 ```
     84 
     85 to get a REPL for the main library, or:
     86 
     87 ```
     88 $ cabal repl secp256k1-sys-tests
     89 ```
     90 
     91 to get one for the internal test suite. You can run all tests via:
     92 
     93 ```
     94 $ cabal test
     95 ```
     96 
     97 and the benchmarks via:
     98 
     99 ```
    100 $ cabal bench
    101 ```
    102 
    103 ## Attribution
    104 
    105 This implementation has benefited greatly and uses modified versions of
    106 code from both [secp256k1-haskell][hsecp] (test cases, FFI/bytestring
    107 manipulation) and [rust-secp256k1][rsecp] (dependency vendoring).
    108 
    109 [ppads]: https://github.com/ppad-tech/secp256k1
    110 [nixos]: https://nixos.org/
    111 [flake]: https://nixos.org/manual/nix/unstable/command-ref/new-cli/nix3-flake.html
    112 [hadoc]: https://docs.ppad.tech/csecp256k1
    113 [hsecp]: https://github.com/haskoin/secp256k1-haskell
    114 [rsecp]: https://github.com/rust-bitcoin/rust-secp256k1
    115 [ut340]: https://github.com/bitcoin/bips/blob/master/bip-0340/test-vectors.csv
    116 [wyche]: https://github.com/C2SP/wycheproof