Need help with mcl?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

herumi
226 Stars 79 Forks Other 2.1K Commits 4 Opened issues

Description

a portable and fast pairing-based cryptography library

Services available

!
?

Need anything else?

Contributors list

Build Status

mcl

A portable and fast pairing-based cryptography library.

Abstract

mcl is a library for pairing-based cryptography, which supports the optimal Ate pairing over BN curves and BLS12-381 curves.

News

  • dst for mapToG1 has changed to
    BLS_SIG_BLS12381G1_XMD:SHA-256_SSWU_RO_POP_
    .
  • mclBn_eth*
    functions are removed.
  • mcl::bn::mapToG1(G1& out, const Fp& v)
    supports
    BLS12_MAP_FP_TO_G1
    in EIP 2537.
  • mcl::bn::hashAndMapToG1(G1& out, const void *msg, size_t msgSize)
    supports (hash-to-curve-09 BLS12381G1XMD:SHA-256SSWURO)
  • MCL_MAP_TO_MODE_HASH_TO_CURVE_07
    is added for hash-to-curve-draft-07.
    • The older version will be removed in the future.
  • change DST of hash-to-curve for
    MCL_MAP_TO_MODE_HASH_TO_CURVE_06
    .
  • add new hash-to-curve function of hash-to-curve-draft-06 at March 2020.
    • call
      setETHmode(MCL_MAP_TO_MODE_HASH_TO_CURVE_06);
    • The older
      MAP_TO_MODE
      will be removed after the draft is fixed.
  • add new hash functions corresponding to python-impl of algorand/blssigref.
    • mclBn_ethMsgToFp2
      (resp.
      Hp2
      )
    • mclBn_ethFp2ToG2
      (resp.
      opt_swu2_map
      )
    • mclBn_ethMsgToG2
      (resp.
      map2curve_osswu2
      )

Support architecture

  • 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

  • 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

C-API

see api.md

How to build on Linux and macOS

x86-64/ARM/ARM64 Linux, macOS and mingw64 are supported.

Installation Requirements

GMP is necessary (default setting).

apt install libgmp-dev # on Ubuntu

How to build with Makefile

git clone git://github.com/herumi/mcl
cd mcl
make -j4
  • lib/libmcl.*
    ; core library
  • lib/libmclbn384_256.*
    ; library to use C-API of BLS12-381 pairing

How to test of BLS12-381 pairing

# C
make bin/bn_c384_256_test.exe && bin/bn_c384_256_test.exe

C++

make bin/bls12_test.exe && bin/bls12_test.exe

How to build without GMP

make MCL_USE_GMP=0

Define

MCL_USE_VINT
if using C++ header files.

How to profile on Linux

Use perf

make MCL_USE_PROF=1 bin/bls12_test.exe
env MCL_PROF=1 bin/bls12_test.exe

Use Intel VTune profiler

Supporse VTune is installed in

/opt/intel/vtune_amplifier/
.
make MCL_USE_PROF=2 bin/bls12_test.exe
env MCL_PROF=2 bin/bls12_test.exe

How to build on 32-bit x86 Linux

Build GMP for 32-bit mode (

env ABI=32 ./configure --enable-cxx ...
) and install
 at yourself.
make ARCH=x86 CFLAGS_USER="-I /include" LDFLAGS_USER="-L /lib -Wl,-rpath,/lib"

How to build on 64-bit Windows with Visual Studio

Clone cybozulib_ext, which provides compiled binaries of MPIR.

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\bls12_test.cpp && bin\bls12_test.exe

(not maintenanced) Open mcl.sln and build or if you have msbuild.exe

msbuild /p:Configuration=Release

How to build with CMake

For Linux, macOS, etc.

mkdir build
cd build
cmake ..
make
For Visual Studio,
mkdir build
cd build
cmake .. -A x64
msbuild mcl.sln /p:Configuration=Release /m

For your convenience you could use the build script

build.sh
on Linux, macOS and Windows (requires Git Bash).

On Windows,

build.sh
expects cybozulib_ext to be within the same parent directory, otherwise, it will be downloaded into
external\cybozulib_ext
directory.

options

cmake .. MCL_USE_GMP=OFF ; without GMP

see

cmake .. -LA
.

tests

make test binaries in

./bin
.
cmake .. -DBUILD_TESTING=ON
make -j4

How to build for wasm(WebAssembly)

mcl supports emcc (Emscripten) and

test/bn_test.cpp
runs on browers such as Firefox, Chrome and Edge.

The timing of a pairing on

BN254
is 2.8msec on 64-bit Firefox with Skylake 3.4GHz.

Node.js

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.

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.

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

software

x64 x86 arm arm64(msec)
ate-pairing 0.21 - - -
mcl 0.31 1.6 22.6 3.9
TEPLA 1.76 3.7 37 17.9
RELIC PRIME=254 0.30 3.5 36 -
MIRACL ake12bnx 4.2 - 78 -
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. ``` % sudo setenforce 1 % getenforce Enforcing % bin/bn_test.exe JIT 0 pairing 1.496Mclk finalExp 581.081Kclk

% sudo setenforce 0 % getenforce Permissive % bin/bn_test.exe JIT 1 pairing 1.394Mclk finalExp 546.259Kclk ```

How to make asm files (optional)

The asm files generated by this way are already put in

src/asm
, then it is not necessary to do this.

Install LLVM.

make MCL_USE_LLVM=1 LLVM_VER= UPDATE_ASM=1
For example, specify
-3.8
for
 if 
opt-3.8
and
llc-3.8
are installed.

If you want to use Fp with 1024-bit prime on x86-64, then

make MCL_USE_LLVM=1 LLVM_VER= UPDATE_ASM=1 MCL_MAX_BIT_SIZE=1024

API for Two level homomorphic encryption

Java API

See java.md

License

modified new BSD License http://opensource.org/licenses/BSD-3-Clause

This library contains some part of the followings software licensed by BSD-3-Clause. * xbyak * cybozulib * Lifted-ElGamal

References

compatilibity

  • mclBnGT_inv returns a - b w, a conjugate of x for x = a + b w in Fp12 = Fp6[w]
    • use mclBnGT_invGeneric if x is not in GT
  • mclBn_setETHserialization(true) (de)serialize acoording to ETH2.0 serialization of BLS12-381 when BLS12-381 is used.
  • (Break backward compatibility) libmcl_dy.a is renamed to libmcl.a
    • The option SHAREBASENAMESUF 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

  • 2020/Jun/07 v1.22 remove old hash-to-curve functions
  • 2020/Jun/04 v1.21 mapToG1 and hashAndMapToG1 are compatible to irtf/eip-2537
  • 2020/May/13 v1.09 support draft-irtf-cfrg-hash-to-curve-07
  • 2020/Mar/26 v1.07 change DST for hash-to-curve-06
  • 2020/Mar/15 v1.06 support hash-to-curve-06
  • 2020/Jan/31 v1.05 mclBn_ethMsgToFp2 has changed to append zero byte at the end of msg
  • 2020/Jan/25 v1.04 add new hash functions
  • 2019/Dec/05 v1.03 disable to check the order in setStr
  • 2019/Sep/30 v1.00 add some functions to bn.h ; api.md.
  • 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
  • 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 mclBnFrsetLittleEndianMod, mclBnFpsetLittleEndianMod
  • 2019/Feb/20 LagrangeInterpolation sets out = yVec[0] if k = 1
  • 2019/Jan/31 add mclBnFpmapToG1, mclBnFp2mapToG2
  • 2019/Jan/31 fix crash on x64-CPU without AVX (thanks to mortdeus)

Author

MITSUNARI Shigeo([email protected])

Sponsors welcome

GitHub Sponsor

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.