PoS_EVM
/
mcl
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update doc

Browse Source
update-fork
MITSUNARI Shigeo 5 years ago
parent 26d9039b6c
commit 33bfcf4ac5
1 changed files with 159 additions and 141 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 300
      readme.md

300
readme.md
Unescape View File

@ -6,177 +6,113 @@ A portable and fast pairing-based cryptography library.
# Abstract
mcl is a library for pairing-based cryptography.
The current version supports the optimal Ate pairing over BN curves and BLS12-381 curves.
# News
* v0.99 add mclBnG1_mulVec, etc.
* v0.98 bugfix Ec::add(P, Q, R) when P == R
* v0.97 add some C api functions
* v0.96 improved scalar multiplication
* mclBn_setETHserialization(true) (de)serialize acoording to [ETH2.0 serialization of BLS12-381](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/bls_signature.md#point-representations) when BLS12-381 is used.
* (Break backward compatibility) libmcl_dy.a is renamed to libmcl.a
* The option SHARE_BASENAME_SUF is removed
* 2nd argument of `mclBn_init` is changed from `maxUnitSize` to `compiledTimeVar`, which must be `MCLBN_COMPILED_TIME_VAR`.
* break backward compatibility of mapToGi for BLS12. A map-to-function for BN is used.
If `MCL_USE_OLD_MAPTO_FOR_BLS12` is defined, then the old function is used, but this will be removed in the future.
mcl is a library for pairing-based cryptography,
which supports the optimal Ate pairing over BN curves and BLS12-381 curves.
# Support architecture
* x86-64 Windows + Visual Studio
* x86, x86-64 Linux + gcc/clang
* ARM Linux
* ARM64 Linux
* (maybe any platform to be supported by LLVM)
* WebAssembly
- x86-64 Windows + Visual Studio
- x86, x86-64 Linux + gcc/clang
- x86-64 macOS
- ARM / ARM64 Linux
- WebAssembly
- Android
- iPhone
- (maybe any platform to be supported by LLVM)
# Support curves
p(z) = 36z^4 + 36z^3 + 24z^2 + 6z + 1.
* BN254 ; a BN curve over the 254-bit prime p(z) where z = -(2^62 + 2^55 + 1).
* BN\_SNARK1 ; a BN curve over a 254-bit prime p such that n := p + 1 - t has high 2-adicity.
* BN381\_1 ; a BN curve over the 381-bit prime p(z) where z = -(2^94 + 2^76 + 2^72 + 1).
* BN462 ; a BN curve over the 462-bit prime p(z) where z = 2^114 + 2^101 - 2^14 - 1.
* BLS12\_381 ; [a BLS12-381 curve](https://blog.z.cash/new-snark-curve/)
# Benchmark
## The latest benchmark(2018/11/7)
### Intel Core i7-6700 3.4GHz(Skylake), Ubuntu 18.04.1 LTS
curveType | binary|clang-6.0.0|gcc-7.3.0|
----------|--------------------|-----------|---------|
BN254 | bin/bn\_test.exe| 882Kclk| 933Kclk|
BLS12-381 | bin/bls12\_test.exe| 2290Kclk| 2630Kclk|
### Intel Core i7-7700 3.6GHz(Kaby Lake), Ubuntu 18.04.1 LTS on Windows 10 Vmware
curveType | binary|clang-6.0.0|gcc-7.3.0|
----------|--------------------|-----------|---------|
BN254 | bin/bn\_test.exe| 900Kclk| 954Kclk|
BLS12-381 | bin/bls12\_test.exe| 2340Kclk| 2680Kclk|
* now investigating the reason why gcc is slower than clang.
## Higher-bit BN curve benchmark
For JavaScript(WebAssembly), see [ID based encryption demo](https://herumi.github.io/mcl-wasm/ibe-demo.html).
paramter | x64| Firefox on x64|Safari on iPhone7|
-----------|-----|---------------|-----------------|
BN254 | 0.25| 2.48| 4.78|
BN381\_1 | 0.95| 7.91| 11.74|
BN462 | 2.16| 14.73| 22.77|
* x64 : 'Kaby Lake Core i7-7700(3.6GHz)'.
* Firefox : 64-bit version 58.
* iPhone7 : iOS 11.2.1.
* BN254 is by `test/bn_test.cpp`.
* BN381\_1 and BN462 are by `test/bn512_test.cpp`.
* All the timings are given in ms(milliseconds).
The other benchmark results are [bench.txt](bench.txt).
- BN curve ; p(z) = 36z^4 + 36z^3 + 24z^2 + 6z + 1.
- BN254 ; a BN curve over the 254-bit prime p(z) where z = -(2^62 + 2^55 + 1).
- BN\_SNARK1 ; a BN curve over a 254-bit prime p such that n := p + 1 - t has high 2-adicity.
- BN381\_1 ; a BN curve over the 381-bit prime p(z) where z = -(2^94 + 2^76 + 2^72 + 1).
- BN462 ; a BN curve over the 462-bit prime p(z) where z = 2^114 + 2^101 - 2^14 - 1.
- BLS12\_381 ; [a BLS12-381 curve](https://blog.z.cash/new-snark-curve/)
## An old benchmark of a BN curve BN254(2016/12/25).
# How to build on Linux and macOS
x86-64/ARM/ARM64 Linux, macOS and mingw64 are supported.
* x64, x86 ; Inte Core i7-6700 3.4GHz(Skylake) upto 4GHz on Ubuntu 16.04.
* `sudo cpufreq-set -g performance`
* arm ; 900MHz quad-core ARM Cortex-A7 on Raspberry Pi2, Linux 4.4.11-v7+
* arm64 ; 1.2GHz ARM Cortex-A53 [HiKey](http://www.96boards.org/product/hikey/)
## Installation Requirements
software | x64| x86| arm|arm64(msec)
---------------------------------------------------------|------|-----|----|-----
[ate-pairing](https://github.com/herumi/ate-pairing) | 0.21 | - | - | -
mcl | 0.31 | 1.6 |22.6| 3.9
[TEPLA](http://www.cipher.risk.tsukuba.ac.jp/tepla/) | 1.76 | 3.7 | 37 | 17.9
[RELIC](https://github.com/relic-toolkit/relic) PRIME=254| 0.30 | 3.5 | 36 | -
[MIRACL](https://github.com/miracl/MIRACL) ake12bnx | 4.2 | - | 78 | -
[NEONabe](http://sandia.cs.cinvestav.mx/Site/NEONabe) | - | - | 16 | -
[GMP](https://gmplib.org/) and [OpenSSL](https://www.openssl.org/) are necessary (default setting).
* compile option for RELIC
```
cmake -DARITH=x64-asm-254 -DFP_PRIME=254 -DFPX_METHD="INTEG;INTEG;LAZYR" -DPP_METHD="LAZYR;OATEP"
apt install libgmp-dev libssl-dev # on Ubuntu
```
# Installation Requirements
## How to build with Makefile
* [GMP](https://gmplib.org/) and OpenSSL
```
apt install libgmp-dev libssl-dev
git clone git://github.com/herumi/mcl
cd mcl
make -j4
```
Create a working directory (e.g., work) and clone the following repositories.
- `lib/libmcl.*` ; core library
- `lib/libmclbn384_256.*` ; library to use C-API of BLS12-381 pairing
## How to test of BLS12-381 pairing
```
mkdir work
cd work
git clone git://github.com/herumi/mcl
git clone git://github.com/herumi/cybozulib_ext ; for only Windows
# C
make bin/bn_c384_256_test.exe && bin/bn_c384_256_test.exe
# C++
make bin/bls12_test.exe && bin/bls12_test.exe
```
* Cybozulib\_ext is a prerequisite for running OpenSSL and GMP on VC (Visual C++).
# (Option) Without GMP
## How to build without GMP
```
make MCL_USE_GMP=0
```
Define `MCL_USE_VINT` before including `bn.hpp`
Define `MCL_USE_VINT` if using C++ header files.
## How to build without OpenSSL
# (Option) Without Openssl
```
make MCL_USE_OPENSSL=0
```
Define `MCL_DONT_USE_OPENSSL` before including `bn.hpp`
Define `MCL_DONT_USE_OPENSSL` if using C++ header files.
# Build and test on x86-64 Linux, macOS, ARM and ARM64 Linux
To make lib/libmcl.a and test it:
```
cd work/mcl
make test
```
To benchmark a pairing:
```
bin/bn_test.exe
```
To make sample programs:
```
make sample
```
## How to build on 32-bit x86 Linux
if you want to change compiler options for optimization, then set `CFLAGS_OPT_USER`.
```
make CLFAGS_OPT_USER="-O2"
```
Build GMP and OpenSSL for 32-bit mode and install `<lib32>` at yourself.
## Build for 32-bit Linux
Build openssl and gmp for 32-bit mode and install `<lib32>`
```
make ARCH=x86 CFLAGS_USER="-I <lib32>/include" LDFLAGS_USER="-L <lib32>/lib -Wl,-rpath,<lib32>/lib"
```
## Build for 64-bit Windows
1) make static library and use it
# How to build on 64-bit Windows with Visual Studio
```
mklib
mk -s test\bn_c256_test.cpp
bin\bn_c256_test.exe
```
2) make dynamic library and use it
Clone cybozulib\_ext,
which provides compiled binaries of OpenSSL and [MPIR](http://mpir.org/).
```
mkdir work
cd work
git clone git://github.com/herumi/mcl
git clone git://github.com/herumi/cybozulib_ext
cd work
# static library
mklib
mk -s test\bls12_test.cpp && bin\bls12_test.exe
# dynamic library
mklib dll
mk -d test\bn_c256_test.cpp
bin\bn_c256_test.exe
mk -d test\bls12_test.cpp && bin\bls12_test.exe
```
open mcl.sln and build or if you have msbuild.exe
(not maintenanced)
Open mcl.sln and build or if you have msbuild.exe
```
msbuild /p:Configuration=Release
```
## Build with cmake
For Linux,
# How to build with CMake
For Linux, macOS, etc.
```
mkdir build
cd build
@ -190,7 +126,16 @@ cd build
cmake .. -A x64
msbuild mcl.sln /p:Configuration=Release /m
```
## Build for wasm(WebAssembly)
## options
```
cmake .. USE_GMP=OFF ; without GMP
cmake .. USE_OPENSSL=OFF ; without OpenSSL
```
see `cmake .. -LA`.
# How to build for wasm(WebAssembly)
mcl supports emcc (Emscripten) and `test/bn_test.cpp` runs on browers such as Firefox, Chrome and Edge.
* [IBE on browser](https://herumi.github.io/mcl-wasm/ibe-demo.html)
@ -199,13 +144,73 @@ mcl supports emcc (Emscripten) and `test/bn_test.cpp` runs on browers such as Fi
The timing of a pairing on `BN254` is 2.8msec on 64-bit Firefox with Skylake 3.4GHz.
### Node.js
# Node.js
* [mcl-wasm](https://www.npmjs.com/package/mcl-wasm) pairing library
* [bls-wasm](https://www.npmjs.com/package/bls-wasm) BLS signature library
* [she-wasm](https://www.npmjs.com/package/she-wasm) 2 Level Homomorphic Encryption library
### SELinux
# Benchmark
## The latest benchmark(2018/11/7)
### Intel Core i7-6700 3.4GHz(Skylake), Ubuntu 18.04.1 LTS
curveType | binary|clang-6.0.0|gcc-7.3.0|
----------|--------------------|-----------|---------|
BN254 | bin/bn\_test.exe| 882Kclk| 933Kclk|
BLS12-381 | bin/bls12\_test.exe| 2290Kclk| 2630Kclk|
### Intel Core i7-7700 3.6GHz(Kaby Lake), Ubuntu 18.04.1 LTS on Windows 10 Vmware
curveType | binary|clang-6.0.0|gcc-7.3.0|
----------|--------------------|-----------|---------|
BN254 | bin/bn\_test.exe| 900Kclk| 954Kclk|
BLS12-381 | bin/bls12\_test.exe| 2340Kclk| 2680Kclk|
* now investigating the reason why gcc is slower than clang.
## Higher-bit BN curve benchmark
For JavaScript(WebAssembly), see [ID based encryption demo](https://herumi.github.io/mcl-wasm/ibe-demo.html).
paramter | x64| Firefox on x64|Safari on iPhone7|
-----------|-----|---------------|-----------------|
BN254 | 0.25| 2.48| 4.78|
BN381\_1 | 0.95| 7.91| 11.74|
BN462 | 2.16| 14.73| 22.77|
* x64 : 'Kaby Lake Core i7-7700(3.6GHz)'.
* Firefox : 64-bit version 58.
* iPhone7 : iOS 11.2.1.
* BN254 is by `test/bn_test.cpp`.
* BN381\_1 and BN462 are by `test/bn512_test.cpp`.
* All the timings are given in ms(milliseconds).
The other benchmark results are [bench.txt](bench.txt).
## An old benchmark of a BN curve BN254(2016/12/25).
* x64, x86 ; Inte Core i7-6700 3.4GHz(Skylake) upto 4GHz on Ubuntu 16.04.
* `sudo cpufreq-set -g performance`
* arm ; 900MHz quad-core ARM Cortex-A7 on Raspberry Pi2, Linux 4.4.11-v7+
* arm64 ; 1.2GHz ARM Cortex-A53 [HiKey](http://www.96boards.org/product/hikey/)
software | x64| x86| arm|arm64(msec)
---------------------------------------------------------|------|-----|----|-----
[ate-pairing](https://github.com/herumi/ate-pairing) | 0.21 | - | - | -
mcl | 0.31 | 1.6 |22.6| 3.9
[TEPLA](http://www.cipher.risk.tsukuba.ac.jp/tepla/) | 1.76 | 3.7 | 37 | 17.9
[RELIC](https://github.com/relic-toolkit/relic) PRIME=254| 0.30 | 3.5 | 36 | -
[MIRACL](https://github.com/miracl/MIRACL) ake12bnx | 4.2 | - | 78 | -
[NEONabe](http://sandia.cs.cinvestav.mx/Site/NEONabe) | - | - | 16 | -
* compile option for RELIC
```
cmake -DARITH=x64-asm-254 -DFP_PRIME=254 -DFPX_METHD="INTEG;INTEG;LAZYR" -DPP_METHD="LAZYR;OATEP"
```
# SELinux
mcl uses Xbyak JIT engine if it is available on x64 architecture,
otherwise mcl uses a little slower functions generated by LLVM.
The default mode enables SELinux security policy on CentOS, then JIT is disabled.
@ -460,19 +465,32 @@ This library contains some part of the followings software licensed by BSD-3-Cla
* [_Skew Frobenius Map and Efficient Scalar Multiplication for Pairing–Based Cryptography_](https://www.researchgate.net/publication/221282560_Skew_Frobenius_Map_and_Efficient_Scalar_Multiplication_for_Pairing-Based_Cryptography),
Y. Sakemi, Y. Nogami, K. Okeya, Y. Morikawa, CANS 2008.
# compatilibity
- mclBn_setETHserialization(true) (de)serialize acoording to [ETH2.0 serialization of BLS12-381](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/bls_signature.md#point-representations) when BLS12-381 is used.
- (Break backward compatibility) libmcl_dy.a is renamed to libmcl.a
- The option SHARE_BASENAME_SUF is removed
- 2nd argument of `mclBn_init` is changed from `maxUnitSize` to `compiledTimeVar`, which must be `MCLBN_COMPILED_TIME_VAR`.
- break backward compatibility of mapToGi for BLS12. A map-to-function for BN is used.
If `MCL_USE_OLD_MAPTO_FOR_BLS12` is defined, then the old function is used, but this will be removed in the future.
# History
* 2019/Jun/03 v0.95 fix a parser of 0b10 with base = 16
* 2019/Apr/29 v0.94 mclBn_setETHserialization supports [ETH2.0 serialization of BLS12-381](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/bls_signature.md#point-representations)
* 2019/Apr/24 v0.93 support ios
* 2019/Mar/22 v0.92 shortcut for Ec::mul(Px, P, x) if P = 0
* 2019/Mar/21 python binding of she256 for Linux/Mac/Windows
* 2019/Mar/14 v0.91 modp supports mcl-wasm
* 2019/Mar/12 v0.90 fix Vint::setArray(x) for x == this
* 2019/Mar/07 add mclBnFr_setLittleEndianMod, mclBnFp_setLittleEndianMod
* 2019/Feb/20 LagrangeInterpolation sets out = yVec[0] if k = 1
* 2019/Jan/31 add mclBnFp_mapToG1, mclBnFp2_mapToG2
* 2019/Jan/31 fix crash on x64-CPU without AVX (thanks to mortdeus)
- 2019/Sep/22 v0.99 add mclBnG1_mulVec, etc.
- 2019/Sep/08 v0.98 bugfix Ec::add(P, Q, R) when P == R
- 2019/Aug/14 v0.97 add some C api functions
- 2019/Jul/26 v0.96 improved scalar multiplication
- 2019/Jun/03 v0.95 fix a parser of 0b10 with base = 16
- 2019/Apr/29 v0.94 mclBn_setETHserialization supports [ETH2.0 serialization of BLS12-381](https://github.com/ethereum/eth2.0-specs/blob/dev/specs/bls_signature.md#point-representations)
- 2019/Apr/24 v0.93 support ios
- 2019/Mar/22 v0.92 shortcut for Ec::mul(Px, P, x) if P = 0
- 2019/Mar/21 python binding of she256 for Linux/Mac/Windows
- 2019/Mar/14 v0.91 modp supports mcl-wasm
- 2019/Mar/12 v0.90 fix Vint::setArray(x) for x == this
- 2019/Mar/07 add mclBnFr_setLittleEndianMod, mclBnFp_setLittleEndianMod
- 2019/Feb/20 LagrangeInterpolation sets out = yVec[0] if k = 1
- 2019/Jan/31 add mclBnFp_mapToG1, mclBnFp2_mapToG2
- 2019/Jan/31 fix crash on x64-CPU without AVX (thanks to mortdeus)
# Author

Write Preview
Loading…
Cancel
Save