Skip to content

Latest commit

 

History

History
128 lines (98 loc) · 8.69 KB

README.md

File metadata and controls

128 lines (98 loc) · 8.69 KB
Raw

Build Status Build Status Build Status Build Status

Mclwrap

Mclwrap provides a wrapper around the BN-254 and BLS12-381 bilinear group implemented in the MCL library. As the bilinear groups implemented in the Cryptimeleon Math library are not particulary efficient, use of this wrapper is recommended for proper benchmarks. Specifically, the Mclwrap implementation's group operations are roughly 100 times as fast as our own implementation.

Security Disclaimer

WARNING: This library is meant to be used for prototyping and as a research tool only. It has not been sufficiently vetted for use in security-critical production environments. All implementations are to be considered experimental.

Table Of Contents

Quickstart

Simply add mclwrap as a dependency (see below for maven and gradle snippets) and start using the MclBilinearGroup in your code. You can pass GroupChoice.BN254 or GroupChoice.BLS12_381 to the constructor of MclBilinearGroup to choose which group to use. Note that we currently do not support instantiating both groups at the same time.

For full performance, you should compile the underlying mcl library for your system yourself (by default, a precompiled maximum-compatibility version of mcl is used, which may miss out on some modern processor features). Instructions for this can be found below.

Adding Mclwrap Dependency With Maven

To add the newest Mclwrap version as a dependency, add this to your project's POM:

<dependency>
    <groupId>org.cryptimeleon</groupId>
    <artifactId>mclwrap</artifactId>
    <version>[3.0,)</version>
</dependency>

Adding Mclwrap Dependency With Gradle

Mclwrap is published via Maven Central. Therefore, you need to add mavenCentral() to the repositories section of your project's build.gradle file. Then, add implementation group: 'org.cryptimeleon', name: 'mclwrap', version: '3.+' to the dependencies section of your build.gradle file.

For example:

repositories {
    mavenCentral()
}

dependencies {
    implementation group: 'org.cryptimeleon', name: 'mclwrap', version: '3.+'
}

Compiling mcl on Linux or macOS

This is optional, but strongly recommended for full performance on modern CPUs.

You can peform most of the installation automatically by using the scripts/install_fast_mcljava_linux_mac.sh script contained in this repository. It will compile the mcl library as well as the Java bindings, and move the shared library to the correct library folder. As a prerequisite, you need to have the libgmp-dev package (i.e. libgmp and the corresponding headers) installed. You can also run the install_mcljava_with_optimized_gmp.sh script with an arbitrary second parameter in order to download and compile gmp from source and install it to /usr/local/{include,lib} for future use. You will also need make and g++ (or clang++ if using FreeBSD or OpenBSD).

The scripts/install_fast_mcljava_linux_mac.sh script takes the include path of your Java JDK as its only argument. The path should be given without a trailing forward slash.
The created binary library is optimized for roughly the CPU model and operating system version the script was executed on and might not work on other CPUs and system versions. If you want the created library to be portable to other machines, use the scripts whose names contain "portable".

Finally, the install_mcljava_with_optimized_gmp.sh script takes the same include paramter, but tries to link against an existing or compiles an optimized libgmp to or from /usr/locale/lib. On some systems, especially older CPUs running Linux, this can achieve additional performance compared to the install_fast_mcljava_linux_mac.sh script, while on other systems the resulting library is slower.

Compiling mcl on Windows

This is optional, but strongly recommended for full performance on modern CPUs.

As prerequisites you need Visual Studio with C++ build tools and the Windows 10 SDK installed. These should be easily installable using the setup application that comes with Visual Studio, which you can access by going to the program deinstallation settings in Windows and then selecting modify under Visual Studio. Then select the C++ workload and deselect everything but the C++ build tools and the Windows 10 SDK. Furthermore, you need a Java SDK Version 8 or higher as well as the Git command line application (or some other way to clone git repos).

I did this using Visual Studio 2019 Community Edition and Oracle JDK Version 15 on Windows 10.

The below commands are executed in the Developer Command Prompt for VS 2019 since this allows using the C++ build tools without having to manipulate PATH.

Before you start with the actual installation, you need to make sure that x64 is selected as target architecure in the Command Prompt. For VS 2017 or later, this is done by executing vcvarsall.bat x64 in the C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\ folder (replace with your Visual Studio location). For VS 2015, the batch file will be in C:\Program Files (x86)\Microsoft Visual Studio 15.0\VC\ instead.

Now, we need to clone Mcl and Cybozu_ext. The repositories need to be in the same folder. Furthermore, we need to ensure that the correct version of Mcl is checked out. To set the version (vX.YZ) of mcl in the following snippet see scripts/install_fast_mcljava_linux_mac.sh.

git clone https://github.com/herumi/mcl.git
git clone https://github.com/herumi/cybozulib_ext.git
cd mcl
git checkout vX.YZ

Next, we build Mcl:

mklib
mk -s test\bls12_test.cpp && bin\bls12_test.exe

This will build Mcl as a static library and run some tests. If you get a module machine type 'X654' conflicts with target machine type 'x86' error, you probably forgot to execute vcvarsall.bat x64 during the first step. If c1 or lib cannot be found, you don't have the C++ build tools installed or they cannot be found. If the compiler complains about missing headers, you are probably missing the Windows 10 SDK.

If this succeeds, we can move on to building the java bindings. This will require you to set the JAVA_HOME variable to your Java SDK installation folder.

cd ffi\java
set JAVA_HOME=C:\PROGRA~1\Java\jdk-15
make_wrap

If you are wondering what is going with that JAVA_HOME path, the script seems to not like spaces in folder names so we are using DOS folder names which don't contain spaces. You can find out the DOS folder names by executing dir /X.

Lastly, we need to move the compiled DLL to the correct path. This is basically a path that is in your system variable PATH.
You can find the dll that you have to move under mcl\bin\mcljava.dll. One way to find one of the target paths is to run the .\gradlew test for mclwrap. Then the PATH should be printed in the console in the first warning, because mclwrap cannot find the mcljava.dll, but lists all the places where it looked for it. One example is the path: C:\Users\<User>\.jdks\openjdk-15\bin, where the jdk may vary depending on your setup. The second option is to just look at your PATH (or extend it with a path of your choice) and but the mcljava.dll in one of the included paths.

Miscellaneous Information

  • Official Documentation can be found here.
  • Mclwrap adheres to Semantic Versioning.
  • The changelog can be found here.
  • A description of how we have built the packaged precompiled mcl library can be found here.
  • Mclwrap is licensed under Apache License 2.0, see LICENSE file.