README.md (3771B)
1 # ppad-csecp256k1 2 3  4 [](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