Add a new README

CHANGELOG.md

@@ -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).

README.md

@@ -1,63 +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
-
-**WARNING: this library is meant to be used for prototyping and as a research tool *only*. It has not been sufficiently vetted to use in production.**
-
-upb.crypto.math is a library providing a number of mathematical tools needed to prototype 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
-
-## Hints
-* The included java pairing is not optimized for performance
-* Please use your own or one of our provided wrappers to a more performant pairing library (see [below](#bilinear_group)).
-
-## 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 <a name="bilinear_group"></a>
+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/).