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