mirror of
https://github.com/bitcoin/bitcoin.git
synced 2025-01-13 05:12:34 -03:00
9d47e7b71b
21ffe4b22a Merge bitcoin-core/secp256k1#1055: Prepare initial release e025ccdf74 release: prepare for initial release 0.2.0 6d1784a2e2 build: add missing files to EXTRA_DIST 8c949f56da Merge bitcoin-core/secp256k1#1173: Don't use compute credits for now 13bf1b6b32 changelog: make order of change types match keepachangelog.com b1f992a552 doc: improve release process 7e5b22684f Don't use compute credits for now ad39e2dc41 build: change package version to 0.1.0-dev 5c789dcd73 Merge bitcoin-core/secp256k1#1168: Replace deprecated context flags with NONE in benchmarks and tests d6dc0f4ae3 tests: Switch to NONE contexts in module tests 0c8a5caddd tests: Switch to NONE contexts in tests.c 86540e9e1f tests: add test for deprecated flags and rm them from run_context caa0ad631e group: add gej_eq_var 37ba744f5b tests: Switch to NONE contexts in exhaustive and ctime tests 8d7a9a8eda benchmarks: Switch to NONE contexts 90618e9263 doc: move CHANGELOG from doc/ to root directory e3f84777eb Merge bitcoin-core/secp256k1#1126: API cleanup with respect to contexts 4386a2306c examples: Switch to NONE contexts 7289b51d31 docs: Use doxygen style if and only if comment is user-facing e7d0185c90 docs: Get rid of "initialized for signing" terminology 06126364ad docs: Tidy and improve docs about contexts and randomization e02d6862bd selftest: Expose in public API e383fbfa66 selftest: Rename internal function to make name available for API d2c6d48de3 tests: Use new name of static context 53796d2b24 contexts: Rename static context 72fedf8a6c docs: Improve docs for static context 316ac7625a contexts: Deprecate all context flags except SECP256K1_CONTEXT_NONE 477f02c4de Merge bitcoin-core/secp256k1#1165: gitignore: Add *.sage.py files autogenerated by sage [skip ci] 092be61c5e gitignore: Add *.sage.py files autogenerated by sage 1a553ee8be docs: Change signature "validation" to "verification" ee7341fbac docs: Never require a verification context 751c4354d5 Merge bitcoin-core/secp256k1#1152: Update macOS image for CI 2286f80902 Merge bitcoin-core/secp256k1#993: Enable non-experimental modules by default e40fd277b7 Merge bitcoin-core/secp256k1#1156: Followups to int128_struct arithmetic 99bd335599 Make int128 overflow test use secp256k1_[ui]128_mul a8494b02bf Use compute credits for macOS jobs 3afce0af7c Avoid signed overflow in MSVC AMR64 secp256k1_mul128 c0ae48c995 Update macOS image for CI 9b5f589d30 Heuristically decide whether to use int128_struct 63ff064d2f int128: Add test override for testing __(u)mulh on MSVC X64 f2b7e88768 Add int128 randomized tests 6138d73be4 Merge bitcoin-core/secp256k1#1155: Add MSan CI jobs ddf2b2910e Merge bitcoin-core/secp256k1#1000: Synthetic int128 type. 86e3b38a4a Merge bitcoin-core/secp256k1#1149: Remove usage of CHECK from non-test file 00a42b91b3 Add MSan CI job 44916ae915 Merge bitcoin-core/secp256k1#1147: ci: print env to allow reproducing the job outside of CI c2ee9175e9 Merge bitcoin-core/secp256k1#1146: ci: prevent "-v/--version: not found" irrelevant error e13fae487e Merge bitcoin-core/secp256k1#1150: ci: always cat test_env.log a340d9500a ci: add int128_struct tests dceaa1f579 int128: Tidy #includes of int128.h and int128_impl.h 2914bccbc0 Simulated int128 type. 6a965b6b98 Remove usage of CHECK from non-test file 5c9f1a5c37 ci: always cat all logs_snippets 49ae843592 ci: mostly prevent "-v/--version: not found" irrelevant error 4e54c03153 ci: print env to allow reproducing the job outside of CI a43e982bca Merge bitcoin-core/secp256k1#1144: Cleanup `.gitignore` file f5039cb66c Cleanup `.gitignore` file 798727ae1e Revert "Add test logs to gitignore" 41e8704b48 build: Enable some modules by default 694ce8fb2d Merge bitcoin-core/secp256k1#1131: readme: Misc improvements 88b00897e7 readme: Fix line break 78f5296da4 readme: Sell "no runtime dependencies" ef48f088ad readme: Add IRC channel 9f8a13dc8e Merge bitcoin-core/secp256k1#1128: configure: Remove pkgconfig macros again (reintroduced by mismerge) cabe085bb4 configure: Remove pkgconfig macros again (reintroduced by mismerge) 3efeb9da21 Merge bitcoin-core/secp256k1#1121: config: Set preprocessor defaults for ECMULT_* config values 6a873cc4a9 Merge bitcoin-core/secp256k1#1122: tests: Randomize the context with probability 15/16 instead of 1/4 17065f48ae tests: Randomize the context with probability 15/16 instead of 1/4 c27ae45144 config: Remove basic-config.h da6514a04a config: Introduce DEBUG_CONFIG macro for debug output of config 63a3565e97 Merge bitcoin-core/secp256k1#1120: ecmult_gen: Skip RNG when creating blinding if no seed is available d0cf55e13a config: Set preprocessor defaults for ECMULT_* config values 55f8bc99dc ecmult_gen: Improve comments about projective blinding 7a86955800 ecmult_gen: Simplify code (no observable change) 4cc0b1b669 ecmult_gen: Skip RNG when creating blinding if no seed is available af65d30cc8 Merge bitcoin-core/secp256k1#1116: build: Fix #include "..." paths to get rid of further -I arguments 40a3473a9d build: Fix #include "..." paths to get rid of further -I arguments 43756da819 Merge bitcoin-core/secp256k1#1115: Fix sepc256k1 -> secp256k1 typo in group.h 069aba8125 Fix sepc256k1 -> secp256k1 typo in group.h accadc94df Merge bitcoin-core/secp256k1#1114: `_scratch_destroy`: move `VERIFY_CHECK` after invalid scrach space check cd47033335 Merge bitcoin-core/secp256k1#1084: ci: Add MSVC builds 1827c9bf2b scratch_destroy: move VERIFY_CHECK after invalid scrach space check 49e2acd927 configure: Improve rationale for WERROR_CFLAGS 8dc4b03341 ci: Add a C++ job that compiles the public headers without -fpermissive 51f296a46c ci: Run persistent wineserver to speed up wine 3fb3269c22 ci: Add 32-bit MinGW64 build 9efc2e5221 ci: Add MSVC builds 2be6ba0fed configure: Convince autotools to work with MSVC's archiver lib.exe bd81f4140a schnorrsig bench: Suppress a stupid warning in MSVC 09f3d71c51 configure: Add a few CFLAGS for MSVC 3b4f3d0d46 build: Reject C++ compilers in the preprocessor 1cc0941414 configure: Don't abort if the compiler does not define __STDC__ cca8cbbac8 configure: Output message when checking for valgrind 1a6be5745f bench: Make benchmarks compile on MSVC git-subtree-dir: src/secp256k1 git-subtree-split: 21ffe4b22a9683cf24ae0763359e401d1284cc7a
122 lines
6.1 KiB
Markdown
122 lines
6.1 KiB
Markdown
libsecp256k1
|
|
============
|
|
|
|
[](https://cirrus-ci.com/github/bitcoin-core/secp256k1)
|
|
|
|
[](https://web.libera.chat/#secp256k1)
|
|
|
|
Optimized C library for ECDSA signatures and secret/public key operations on curve secp256k1.
|
|
|
|
This library is intended to be the highest quality publicly available library for cryptography on the secp256k1 curve. However, the primary focus of its development has been for usage in the Bitcoin system and usage unlike Bitcoin's may be less well tested, verified, or suffer from a less well thought out interface. Correct usage requires some care and consideration that the library is fit for your application's purpose.
|
|
|
|
Features:
|
|
* secp256k1 ECDSA signing/verification and key generation.
|
|
* Additive and multiplicative tweaking of secret/public keys.
|
|
* Serialization/parsing of secret keys, public keys, signatures.
|
|
* Constant time, constant memory access signing and public key generation.
|
|
* Derandomized ECDSA (via RFC6979 or with a caller provided function.)
|
|
* Very efficient implementation.
|
|
* Suitable for embedded systems.
|
|
* No runtime dependencies.
|
|
* Optional module for public key recovery.
|
|
* Optional module for ECDH key exchange.
|
|
* Optional module for Schnorr signatures according to [BIP-340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki).
|
|
|
|
Implementation details
|
|
----------------------
|
|
|
|
* General
|
|
* No runtime heap allocation.
|
|
* Extensive testing infrastructure.
|
|
* Structured to facilitate review and analysis.
|
|
* Intended to be portable to any system with a C89 compiler and uint64_t support.
|
|
* No use of floating types.
|
|
* Expose only higher level interfaces to minimize the API surface and improve application security. ("Be difficult to use insecurely.")
|
|
* Field operations
|
|
* Optimized implementation of arithmetic modulo the curve's field size (2^256 - 0x1000003D1).
|
|
* Using 5 52-bit limbs (including hand-optimized assembly for x86_64, by Diederik Huys).
|
|
* Using 10 26-bit limbs (including hand-optimized assembly for 32-bit ARM, by Wladimir J. van der Laan).
|
|
* This is an experimental feature that has not received enough scrutiny to satisfy the standard of quality of this library but is made available for testing and review by the community.
|
|
* Scalar operations
|
|
* Optimized implementation without data-dependent branches of arithmetic modulo the curve's order.
|
|
* Using 4 64-bit limbs (relying on __int128 support in the compiler).
|
|
* Using 8 32-bit limbs.
|
|
* Modular inverses (both field elements and scalars) based on [safegcd](https://gcd.cr.yp.to/index.html) with some modifications, and a variable-time variant (by Peter Dettman).
|
|
* Group operations
|
|
* Point addition formula specifically simplified for the curve equation (y^2 = x^3 + 7).
|
|
* Use addition between points in Jacobian and affine coordinates where possible.
|
|
* Use a unified addition/doubling formula where necessary to avoid data-dependent branches.
|
|
* Point/x comparison without a field inversion by comparison in the Jacobian coordinate space.
|
|
* Point multiplication for verification (a*P + b*G).
|
|
* Use wNAF notation for point multiplicands.
|
|
* Use a much larger window for multiples of G, using precomputed multiples.
|
|
* Use Shamir's trick to do the multiplication with the public key and the generator simultaneously.
|
|
* Use secp256k1's efficiently-computable endomorphism to split the P multiplicand into 2 half-sized ones.
|
|
* Point multiplication for signing
|
|
* Use a precomputed table of multiples of powers of 16 multiplied with the generator, so general multiplication becomes a series of additions.
|
|
* Intended to be completely free of timing sidechannels for secret-key operations (on reasonable hardware/toolchains)
|
|
* Access the table with branch-free conditional moves so memory access is uniform.
|
|
* No data-dependent branches
|
|
* Optional runtime blinding which attempts to frustrate differential power analysis.
|
|
* The precomputed tables add and eventually subtract points for which no known scalar (secret key) is known, preventing even an attacker with control over the secret key used to control the data internally.
|
|
|
|
Build steps
|
|
-----------
|
|
|
|
libsecp256k1 is built using autotools:
|
|
|
|
$ ./autogen.sh
|
|
$ ./configure
|
|
$ make
|
|
$ make check # run the test suite
|
|
$ sudo make install # optional
|
|
|
|
To compile optional modules (such as Schnorr signatures), you need to run `./configure` with additional flags (such as `--enable-module-schnorrsig`). Run `./configure --help` to see the full list of available flags.
|
|
|
|
Usage examples
|
|
-----------
|
|
Usage examples can be found in the [examples](examples) directory. To compile them you need to configure with `--enable-examples`.
|
|
* [ECDSA example](examples/ecdsa.c)
|
|
* [Schnorr signatures example](examples/schnorr.c)
|
|
* [Deriving a shared secret (ECDH) example](examples/ecdh.c)
|
|
|
|
To compile the Schnorr signature and ECDH examples, you also need to configure with `--enable-module-schnorrsig` and `--enable-module-ecdh`.
|
|
|
|
Test coverage
|
|
-----------
|
|
|
|
This library aims to have full coverage of the reachable lines and branches.
|
|
|
|
To create a test coverage report, configure with `--enable-coverage` (use of GCC is necessary):
|
|
|
|
$ ./configure --enable-coverage
|
|
|
|
Run the tests:
|
|
|
|
$ make check
|
|
|
|
To create a report, `gcovr` is recommended, as it includes branch coverage reporting:
|
|
|
|
$ gcovr --exclude 'src/bench*' --print-summary
|
|
|
|
To create a HTML report with coloured and annotated source code:
|
|
|
|
$ mkdir -p coverage
|
|
$ gcovr --exclude 'src/bench*' --html --html-details -o coverage/coverage.html
|
|
|
|
Benchmark
|
|
------------
|
|
If configured with `--enable-benchmark` (which is the default), binaries for benchmarking the libsecp256k1 functions will be present in the root directory after the build.
|
|
|
|
To print the benchmark result to the command line:
|
|
|
|
$ ./bench_name
|
|
|
|
To create a CSV file for the benchmark result :
|
|
|
|
$ ./bench_name | sed '2d;s/ \{1,\}//g' > bench_name.csv
|
|
|
|
Reporting a vulnerability
|
|
------------
|
|
|
|
See [SECURITY.md](SECURITY.md)
|