Merge pull request #22 from cryptimeleon/rework

Rework of starting page and some structuring

Author: feidens

_config.yml

@@ -6,8 +6,9 @@ relative_links:
     collections: true
 theme: minimal-mistakes-jekyll
 minimal_mistakes_skin: "air"
-title: Cryptimeleon Documentation
-subtitle: "Version 1.0.0"
+title: Cryptimeleon
+subtitle: Prototyping of Cryptographic Construction
+logo: /assets/logo.png
 repository: cryptimeleon/cryptimeleon.github.io
 locale: en
 description: Documentation page for the Cryptimeleon cryptography libraries.
@@ -25,6 +26,9 @@ kramdown:
     auto_ids: true
     hard_wrap: false
 
+cracoversion: 2.0.0
+mathversion: 2.0.0
+
 # exclude from jekyll site
 exclude:
     - vendor
@@ -33,4 +37,4 @@ exclude:
     - Gemfile.lock
     - README.md
     - Dockerfile
-    - LICENSE
+    - LICENSE

_data/navigation.yaml

@@ -1,10 +1,8 @@
 docs:
 - title: Getting Started
   children:
-    - title: "Libraries Overview"
-      url: /getting-started/libraries.html
-    - title: "Installation"
-      url: /getting-started/installation.html
+    - title: "First Steps"
+      url: /getting-started/first-steps.html
     - title: "5-minute Tutorial"
       url: /getting-started/5-minute-tutorial.html
     - title: "Pairing Tutorial"
@@ -15,6 +13,8 @@ docs:
       url: /getting-started/implement-elgamal.html
 - title: Documentation
   children:
+    - title: "How do I ...?"
+      url: /docs/how-do-I.html
     - title: "Lazy Evaluation"
       url: /docs/lazy-eval.html
     - title: "Bilinear Groups"
@@ -37,5 +37,3 @@ docs:
       url: /contributors/composite-builds.html
     - title: "Contributing"
       url: /contributors/contributing.html
-    - title: "Dependencies"
-      url: /contributors/dependencies.html

assets/cryptimeleon_overview_parts.png

@@ -17,10 +17,10 @@ To do this, every library that depends on some other Cryptimeleon library includ
 This script clones the dependency to the same directory level as the library being built and includes it as a composite build if possible.
 "If possible" means that the branches should follow some rules. Let `LB` be the name of the branch of the library being built and `DB` be the name of the branch of the dependency library. The composite build will only be enabled if either of the following hold:
 
-- The dependency has no branch called `LB` and `DB == master`. In this case, the `master` branch of the dependency is used for the composite build.
+- The dependency has no branch called `LB` and `DB == main`. In this case, the `main` branch of the dependency is used for the composite build.
 - The dependency has a branch called `LB` and `DB = LB`. In this case, the `DB` branch of the dependency is used for the composite build.
 
-To summarize, the build script will always try to use the branch with the same name as `LB` and use `master` if no such branch exists.
+To summarize, the build script will always try to use the branch with the same name as `LB` and use `main` if no such branch exists.
 Importantly, no automatic checkout of branches is done. 
 This means that if the branches don't match, the build script will complain and fail. 
 You can adjust this behaviour using the **useCurrentBranch** parameter as explained below.
@@ -35,7 +35,7 @@ These can either be set in the `gradle.properties` file in the top level folder
 
 - **useCurrentBranch**: If defined (any value) the branch selection checking will be skipped. 
     That means the composite build will be enabled no matter the dependency branches that are currently checked out.
-    This can be useful for when you need a version that is not on `master` but you also do not want to create a new branch.
+    This can be useful for when you need a version that is not on `main` but you also do not want to create a new branch.
 - **checkoutIfCloned**: If defined (any value), will automatically check out the corresponding
     dependency branch (branch with same name) given that the dependency was freshly cloned.
     Used by the Travis CI to automatically switch to the right dependency branch for the build.

assets/logo.png

@@ -11,9 +11,9 @@ If you are not sure which repository exactly the issue belongs to, just pick one
 ## What software is required to use the libraries?
 
 In general you only need Java SDK Version 8 or higher.
-To use the Cryptimeleon Mclwrap wrapper, you additionally need to install the Mcl Java bindings (more info on this [here]({% link getting-started/installation.md %})).
+To use the Cryptimeleon Mclwrap wrapper, you additionally need to install the Mcl Java bindings (more info on this [here]({% link getting-started/first-steps.md %})).
 
 ## Which operating systems do you support?
 
 Since Java is cross-platform, the libraries should run on Linux, Mac OS and Windows.
-Keep in mind that we develop on Linux/Mac OS and do not necessarily test on Windows.
+Keep in mind that we develop on Linux/Mac OS and do not necessarily test on Windows.

contributors/composite-builds.md

@@ -0,0 +1,35 @@
+---
+title: How do I ...?
+mathjax: true
+toc: true
+---
+
+This page addresses a bunch of questions of the form "how do I do xyz in Cryptimeleon?".
+Consider it Stack-Overflow-style help.
+
+# How do I do group operations and pairings?
+
+
+# How do I hash into \\(\mathbb{Z}_n\\)?
+You can use `HashIntoZn` for this.
+```java
+BigInteger n = BigInteger.valueOf(99991); //just for the sake of example
+HashIntoZn hashFunction = new HashIntoZn(n);
+Zn.ZnElement hashVal = hashFunction.hash("Preimage");
+```
+
+# How do I hash into a group \\(\mathbb{G}\\)?
+Bilinear groups provide hash functions as follows:
+```java
+GroupElement hashValue = bilinearGroup.getHashIntoG1().hash("Preimage");
+```
+
+For other groups, there may be classes like named like `HashIntoSecp256k1`.
+
+# How do I hash a list of group elements?
+
+
+# How do I send or store a group element?
+
+
+# My benchmark produces implausibly good numbers

contributors/dependencies.md

@@ -270,7 +270,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "For more information on serialization, see [our documentation regarding `Representation`s](https://cryptimeleon.github.io/docs/representations.html)."
+    "For more information on serialization, see [our documentation regarding `Representation`s](https://cryptimeleon.org/docs/representations.html)."
    ]
   },
   {

docs/faq.md

@@ -0,0 +1,77 @@
+---
+title: First Steps
+toc: true
+---
+
+# Project structure overview
+Cryptimeleon is composed of several libraries.
+![Overview of Cryptimeleon libraries](/assets/cryptimeleon_overview_parts.png)
+
+## Base libraries
+### Math
+The [Math](https://github.com/cryptimeleon/math) library contains all the basics like bilinear groups, hashing, randomness generation, and serialization. 
+It is the basis for every other Cryptimeleon library.
+
+### Craco
+[Craco](https://github.com/cryptimeleon/craco) (the name has historical reasons) implements various cryptographic primitives and low-level constructions. This includes reusable primitives such as accumulators, commitment schemes, signature and encryption schemes, Sigma protocols, and many more.
+
+The goal of Craco is to provide common cryptographic schemes for use in more high-level protocols.
+
+### Mclwrap
+[Mclwrap](https://github.com/cryptimeleon/mclwrap) provides an efficient BN-254 bilinear group implementation (powered by [MCL](https://github.com/herumi/mcl)). 
+You should definitely use this if you want to run timing benchmarks.
+
+### Predenc, Groupsig
+Implementations of various [predicate encryption schemes](https://github.com/cryptimeleon/predenc) and [group signature schemes](https://github.com/cryptimeleon/groupsig).
+
+# Starting from scratch
+If you don't have anything right now, it's easiest to get started with our template projects.
+
+- Java: [tbd]
+- Android: [tbd]
+
+If you want to use Zero-knowledge proofs, you can generate a basic project containing your protocol with [subzero](https://cptml.org/subzero).
+
+# Including our libraries into your existing project
+Our libraries are hosted on Maven Central. 
+For the sake of this, we assume you want to import Math and Craco (which is usually what you need).
+
+## Maven
+Add these dependencies to your `pom.xml`:
+
+```xml
+<dependency>
+    <groupId>org.cryptimeleon</groupId>
+    <artifactId>math</artifactId>
+    <version>{{site.mathversion}}</version>
+</dependency>
+<dependency>
+    <groupId>org.cryptimeleon</groupId>
+    <artifactId>craco</artifactId>
+    <version>{{site.cracoversion}}</version>
+</dependency>
+```
+
+## Gradle
+Add these entries to your `build.gradle`.
+
+```gradle
+plugins {
+  id 'java-library'
+}
+
+repositories {
+  mavenCentral()
+}
+
+dependencies {
+  implementation 'org.cryptimeleon:math:{{site.mathversion}}'
+  implementation 'org.cryptimeleon:craco:{{site.cracoversion}}'
+}
+```
+
+# Mclwrap Installation
+Eventually, you should probably install [mclwrap](https://github.com/herumi/mcl) because it is a _much_ more efficient bilinear group than [what is available](/docs/bilinear-groups.html) in the Math library by default.
+
+To use MCL in your project, you need to (1) compile and install MCL, and then (2) add the dependency to our the Java bindings.
+This process is explained [here](https://github.com/cryptimeleon/mclwrap/blob/main/README.md).