README.md (3902B)
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 ## 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