https://github.com/cryptimeleon/mclwrap
A wrapper to bring the mcl pairing library into cryptimeleon
https://github.com/cryptimeleon/mclwrap
java-bindings mcl-library
Last synced: about 1 month ago
JSON representation
A wrapper to bring the mcl pairing library into cryptimeleon
- Host: GitHub
- URL: https://github.com/cryptimeleon/mclwrap
- Owner: cryptimeleon
- License: bsd-3-clause
- Created: 2018-08-25T09:38:54.000Z (over 7 years ago)
- Default Branch: develop
- Last Pushed: 2022-03-09T14:02:22.000Z (almost 4 years ago)
- Last Synced: 2025-09-10T06:27:00.415Z (5 months ago)
- Topics: java-bindings, mcl-library
- Language: Java
- Homepage:
- Size: 4.6 MB
- Stars: 3
- Watchers: 7
- Forks: 1
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Mclwrap
Mclwrap provides a wrapper around the BN-254 and BLS12-381 bilinear group implemented in the [MCL library](https://github.com/herumi/mcl). 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 Guide](#quickstart)
* [Adding Maven Dependency](#adding-mclwrap-dependency-with-maven)
* [Adding Gradle Dependency](#adding-mclwrap-dependency-with-gradle)
* [Compiling mcl on Linux/macOS](#compiling-mcl-on-linux-or-macos)
* [Compiling mcl on Windows](#compiling-mcl-on-windows)
* [Miscellaneous Information](#miscellaneous-information)
## Quickstart
Simply add mclwrap as a dependency (see below for [maven](#adding-mclwrap-dependency-with-maven) and [gradle](#adding-mclwrap-dependency-with-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:
```xml
org.cryptimeleon
mclwrap
[3.0,)
```
### 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:
```groovy
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](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](scripts/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](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](scripts/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](https://github.com/herumi/mcl) and [Cybozu_ext](https://github.com/herumi/cybozulib_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](https://github.com/cryptimeleon/mclwrap/blob/f46bfb7e8c18c9534aeabd68612071ae7642362f/scripts/install_fast_mcljava_linux_mac.sh#L2).
```
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\\.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](https://cryptimeleon.org).
- Mclwrap adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
- The changelog can be found [here](CHANGELOG.md).
- A description of how we have built the packaged precompiled mcl library can be found [here](PORTABLE.md).
- Mclwrap is licensed under Apache License 2.0, see [LICENSE file](LICENSE).