Merge branch 'release/v1.0.0' into main

Author: feidens

.github/workflows/ci.yaml

@@ -0,0 +1,15 @@
+name: Java CI
+
+on: push
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up JDK 1.8
+        uses: actions/setup-java@v1
+        with:
+          java-version: 1.8
+      - name: Build with Gradle
+        run: ./gradlew build -PcheckoutIfCloned=true

.github/workflows/pub.yaml

@@ -0,0 +1,24 @@
+name: Maven publishing
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - v[1-9]+.[0-9]+.[0-9]+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up JDK 1.8
+        uses: actions/setup-java@v1
+        with:
+          java-version: 1.8
+      - name: Publish to the Maven Central Repository
+        run: ./gradlew publish -PcheckoutIfCloned -Prelease
+        env:
+          OSSRH_USERNAME: ${{ secrets.OSSRH_USERNAME }}
+          OSSRH_TOKEN: ${{ secrets.OSSRH_TOKEN }}
+          ORG_GRADLE_PROJECT_signingKey: ${{ secrets.GPG_PRIVATE_KEY }}
+          ORG_GRADLE_PROJECT_signingPassword: ${{ secrets.GPG_PASSPHRASE }}

.gitignore

@@ -1,2 +1,6 @@
 build/**
-.gradle/**
+.gradle/**
+out/**
+.idea/**
+.composite-enable
+gradle.properties

.travis.yml

@@ -0,0 +1,5 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

CHANGELOG.md

@@ -1,57 +1,111 @@
-[![Build Status](https://travis-ci.com/upbcuk/upb.crypto.math.svg?branch=master)](https://travis-ci.com/upbcuk/upb.crypto.math)
-## upb.crypto.math
-
-upb.crypto.math is a library providing a number of mathematical tools needed in many cryptographic applications.
-
-These include:
-
-* Elliptic curve groups with pairings
-    * Type 1:
-        * Supersingular Curve with Tate pairing
-    * Type 3: 
-        * Barreto-Naehrig
-* Hashing
-    * SHA-256
-    * SHA-512
-* Mathematical structures:
-    * Ring of integers modulo n
-    * Ring of polynomials
-    
-## Example Code
-    
-As a starting point, we provide exemplary code of common tasks.
+![Build Status](https://github.com/upbcuk/upb.crypto.craco/workflows/Java%20CI/badge.svg)
+## Math
+
+The Cryptimeleon Math library provides the mathematical foundation for the other Cryptimeleon libraries.
+It provides basics such as mathematical groups, rings and fields, e.g. Zn, as well as implementations of cryptographic pairings.
+Furthermore, it provides serialization support for the implemented structures.
+
+## 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
+
+* [Features Overview](#features)
+* [Quickstart Guide](#quickstart)
+    * [Maven Installation](#installation-with-maven)
+    * [Gradle Installation](#installation-with-gradle)
+    * [Tutorials](#tutorials)
+* [Pairing Performance](#note-regarding-pairing-performance)
+* [Miscellaneous Information](#miscellaneous-information)
+* [Authors](#authors)
+
+## Features
+
+Below we give a more detailed list of features.
+
+### Groups
+
+Math offers the following algebraic groups:
+
+* Bilinear groups:
+    * Type 1 and type 3 pairings
+* Elliptic curves without pairings:
+    * `Secp256k1`
+* Symmetric group Sn
+* Cartesian product group
+
+### Rings
 
-##### Setting up a Type 3 Bilinear Group
+Math offers the following algebraic rings and fields:
 
-Given a security parameter `securityParameter`, we can set up a type 3 bilinear group using this library as follows:
+* Boolean ring
+* Cartesian product ring
+* Field extension class for polynomials of the form x^d + c
+* Integer ring
+* Polynomial ring
+* Ring Zn and Field Zp for prime p
 
-```java
-BilinearGroupFactory fac = new BilinearGroupFactory(securityParameter);
-fac.setRequirements(BilinearGroup.Type.TYPE_3);
-BilinearGroup group = fac.createBilinearGroup();
-``` 
+### Other Features
 
-This chooses a type 3 bilinear group from predefined ones. Alternatively, the library enables it to register new groups by defining a `BilinearGroupProvider`.
+Math also implements a number of other features:
 
-##### Register your own Bilinear Group Implementation
+* Multi-exponentiation algorithms
+* Deferred evaluation of group operations for automatic application of those multi-exponentiation algorithms
+* Serialization features that integrate with the implemented algebraic structures
+* Group operation counting capabilities
+* A random generator
+* Hash function implementations such as SHA256 and SHA512
 
-Suppose you have your own implementation of a type 3 bilinear group and you want to use it in our library. To do so, you only need write a `MyBilinearGroupProvider` that implements the interface `BilinearGroupProvider`.
-Then, your group can be registered in the `BilinearGroupFactory` as follows:
+## Quickstart
 
-```java
-BilinearGroupFactory fac = new BilinearGroupFactory(securityParameter);
-fac.registerProvider(Arrays.asList(new BarretoNaehrigProvider(), new MyBilinearGroupProvider()));
-fac.setRequirements(BilinearGroup.Type.TYPE_3);
-BilinearGroup group = fac.createBilinearGroup();
+### Installation With Maven
+To add the newest Math version as a dependency, add this to your project's POM:
+
+```xml
+<dependency>
+    <groupId>org.cryptimeleon</groupId>
+    <artifactId>math</artifactId>
+    <version>1.0.0</version>
+</dependency>
 ```
 
-As an example have a look at our module [upb.crypto.mclwrap](https://github.com/upbcuk/upb.crypto.mclwrap), which includes the pairing library [mcl](https://github.com/herumi/mcl) in our environment.
+### Installation With Gradle
 
-## Notes
+Math 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: 'math', version: '1.0.0'` to the `dependencies` section of your `build.gradle` file.
 
-The library was implemented at Paderborn University in the research group ["Codes und Cryptography"](https://cs.uni-paderborn.de/en/cuk/).
+For example:
+
+```groovy
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    implementation group: 'org.cryptimeleon', name: 'math', version: '1.0.0'
+}
+```
+
+### Tutorials
 
-This module is the base of [CRACO](https://github.com/upbcuk/upb.crypto.craco) and [CLARC](https://github.com/upbcuk/upb.crypto.clarc) providing cryptographic constructions, and an anonymous credential and reputation system, respectively. 
+We recommend you go through our [short Math tutorial](https://cryptimeleon.github.io/getting-started/5-minute-tutorial.html) to get started.
 
-## Licence
-Apache License 2.0, see LICENCE file.
+We also provide a walkthrough where we show you how to implement a pairing-based signature scheme [here](https://cryptimeleon.github.io/getting-started/pairing-tutorial.html).
+    
+## Note Regarding Pairing Performance
+
+The included java pairings are not optimized for performance.
+We recommend you use our [Mcl wrapper library](https://github.com/cryptimeleon/mclwrap) if you care about pairing performance. 
+It includes an optimized type 3 pairing.
+
+## Miscellaneous Information
+
+- Official Documentation can be found [here](https://cryptimeleon.github.io/).
+    - The *For Contributors* area includes information on how to contribute.
+- Math adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+- The changelog can be found [here](CHANGELOG.md).
+- Math is licensed under Apache License 2.0, see [LICENSE file](LICENSE).
+
+## Authors
+The library was implemented at Paderborn University in the research group ["Codes und Cryptography"](https://cs.uni-paderborn.de/en/cuk/).