Please add an example how to set "useCurrentBranch" in settings.gradle to the Composite build page.

Questions:

• in which project do I set this parameter? If my project "includeBuild-depends" on math and craco, can I turn it off in my project or do I need to modify craco's settings.gradle?
• what's the right syntax to "set" it? Add a concrete code example.

As it stands, it was easier for me to comment out the line that throws an exception rather than read into gradle syntax for setting properties (naive attempts failed). The documentation should be more helpful here.

To be able to render Jupyter notebooks on the documentation page, they need to be converted to the Markdown format supported by the Kramdown parser we use.
The conversion included in Jupyter does not do this correctly; therefore, a script to automate the process would be useful.

The script has to:

• Replace all single dollar signs $ with double dollar signs $$ as that is the default used by Kramdown
• Replace ```Java with ```java to make code highlighting work properly
• Create a valid YAML Front Matter:
  • The first header is usually used as a title. Therefore we should remove the header and use it as the Front Matter Title. Remember to wrap it in quotation marks; otherwise, things such as ":" will be interpreted as YAML
  • Enable mathjax: true and/or toc: true to render LaTex and/or a table of contents. Could use optional commandline arguments to make this configurable.
• Extract images from Notebooks, store them in the assets folder, and update the link in the Markdown file

There is already an existing Jupyter Notebook to Jekyll Markdown converter.
We could use that via a Github Actions workflow to automatically do the conversion like here. It does require adding additional metadata to the Notebook to enable YAML Front Matter (as shown on the script's page).

The installation instructions need to be rewritten once we have published it online (or ideally shortly beforehand).

The jupyter notebooks don't work anymore due to the recent Math and Craco reorganizations. This needs to be fixed.

I noticed that we sometimes use full capitalization for headers, e.g. the representation page, and sometimes regular sentence capitalization, e.g. the first steps page. We should decide on one style and then stick with that. I personally prefer the regular sentence capitalization; I think it looks better and you don't need to worry about edge cases like "Do you capitalize single letter words such as 'a'?".

Figuring out whether the libraries offer any existing tests for your schemes is currently fairly difficult without consulting our own tests.

For example, to use the standalone tests you need to add the math-tests dependency to your project and then correctly use the standalone test. Similarly for the Craco tests via craco-tests.

It would be nice if we had a page that

• tells the user what kind of testing classes we offer
• how to access them
• how to use them

I originally started on something like this and then stopped, because I wanted to make the tests more uniform first (see this issue). I still think that should be addressed first (especially the signature tests). However, since the standalone tests have been rewritten already, one could at least write something for those.

Due to the math rewrite, work on the documentation has been halted until now. Once the next release is feature-complete, we should write documentation to support the release.

Ideas

My plans for the documentation currently would be as follows:

• Update readmes to give the potential user a better idea of the purpose of this library.
• Installation guide (esp. for the mcl wrapper).
• Overview of the libraries: What does each do and which one is relevant for me?
• There should be a short tutorial that gives a basic overview of the features of math/craco and guides the user through implementing a sample construction. @JanBobolz was planning on writing this. This would be part of a "getting started" section.
  Compared to my old ElGamal tutorial, this should be much shorter and more digestible. More of a quickstart type of thing.
• A guide for contributing to the project. This could also also be part of a contributors.md file as seen in other github projects.
  This should include information on the technical details of contribution, e.g. forking and creating pull request.
  Could also include information on some relevant internals of the project. For example, how to add new pairing wrappers.
• A link to the javadocs for each of the sublibraries. We could use javadoc.io to host the java docs.
• FAQ
• A tutorial on using representations as well as serializing a representation.
• Somewhere there should be something on how to use pairings, perhaps this could be part of a longer tutorial on for example some simple pairing-based construction such as the BLS signature. This would be more akin to the old ElGamal tutorial I wrote.
  Can integrate basics of using representations here.
• For each type of scheme we could just quickly detail which interfaces are relevant. Can point to example constructions here.
• Benchmarking: Example using JMH, Group operation counting.

FAQ questions

• Is the library cross-platform?
• How do I report a bug/suggest improvements?

DONE

• Updated installation guide
• Library Overview
• Tutorials by Jan on Basics, Pairings, and Protocols
• FAQ (still short)
• Representations Tutorial
• Benchmarking Page

TODO

• Could still add an example where we use JMH for benchmarking a function to the Benchmark page
• Update readmes

Find nice way to include the ipynb stuff.

Ideas:

• Add a link to spin up a binder instance.
  • Ideally contains all the md files from the github.io site and the ipynbs where appropriate.
  • Can only be usefully done once we've deployed the project to maven central.
• Somehow get rid of the markdown versions of the files and just have github render the ipynb. It seems to do a pretty good job with that.
• If the above is not possible: Include missing pictures into the md files and fix mathjax and code/output style.

Add official reference for BBS signature scheme variant to libraries.md. We can additionally cite the thesis.

@InProceedings{SCN:AuSusMu06,
  author =       "Man Ho Au and
                  Willy Susilo and
                  Yi Mu",
  title =        "Constant-Size Dynamic k-{TAA}",
  pages =        "111--125",
  editor =       scn06ed,
  booktitle =    scn06name,
  volume =       scn06vol,
  address =      scn06addr,
  month =        scn06month,
  publisher =    scnpub,
  series =       mylncs,
  year =         2006,
  doi =          "10.1007/11832072_8",
}

The Gradle library allows for selecting which version of Gradle you use and then shows the right documentation for that version. Once we have more than just version 1.0.0, it would be nice to offer a similar functionality for our documentation page.

Since we have multiple projects in our documentation, it would probably make sense to bundle up specific version of each library in a bigger "all of upb.crypto" version, similar to how Math 1.0.0, Craco 1.0.0, etc. are designed to work together. Then the selection would just differentiate between these bundles.

see cryptimeleon/craco#76 for details.
Also the existing citation is wrong it should be eprint 2014/944 as in the class mentioned in the above issue.

(This issue has been imported from the Gitlab repository because it seems to not have been addressed yet)

Original Text (Issue 118)

Add coding guidelines to Wiki that includes stuff like

1. what are the contracts that we follow (e.g. in serialization)
2. What kind of security checks should we follow (e.g. group membership)
3. our rules for constant time arithmetic (if we have some)
4. ...

Comment by Jan Bobolz

On group membership: we should check whenever creating a (group) Element from user-supplied data. So any instantiated object should correspond to a valid Element (throw an exception otherwise).

Comment by Fabian Eidens

Can we enforce such things using findbugs rules?

Comment by Jan Bobolz

Can we enforce such things using findbugs rules?

Probably not (at least the first three points seems too complicated and diverse to check with a general rule). But it's generally a cool idea to think about adding some findbugs checks :)

Comment by Peter Günther

[at]feidens what are findbugs rules? I think we could implement a generic subgroup membership test given that the factorization of the group order is known. IEEE also proposes such checks that are basically:

1. Check that proper representation of group element (e.g. that it fulfills the Weierstrass equiation of an element) [specific to group]
2. Check that exponentiation with group order results in neutral element [generic]
3. For generators: Check that exponentiation with any factor of group order does not result in neutral element [generic]

Check 2 might be expensive for large groups. For small cofactors a check based on exponentiation with cofactors might be more efficient. How to do this without introducing vulnerabilities to small subgroup attack will be part of the wiki.

Comment by Fabian Eidens

I think the findbugs rules were shown in our last meeting through the sonarqube example (e.g. code smell) or are there further questions?

I wanted to discuss how we write the different library names in the documentation, for example upb.crypto.math. I used to write this in bold text, but I found that too distracting. Therefore, I switched over to just regular text which seems consistent with what I see in other docs. I also saw upb.crypto.math in the 5-minute tutorial, but that obviously suffers the same issue plus I would like to reserve code text for actual code such as method or class names.

More problematic I find is the necessity for writing out upb.crypto.math each time. It disrupts the readers flow a bit. Sadly, math is such a generic name that I would not just call it Math instead. We could, however, only write out upb.crypto.math on first use on each page, and then use a shortened name such as Math instead (although this may actually may be more confusing than just using Math immediately since it suggests we mean different things?). Or, if we finally find a name for our whole library collection, we could prefix Math with that name, for example "Craco.Math" which is a tad bit nicer.

Just want to make sure we are on the same page in this regard so we are using matching styles when writing the docs.

It seems like the representation page in the docs could use some improvements.

What I think could be improved:

• Improve explanation of motivation for using representations
• Make the tutorial a bit less terse, i.e. more verbose and indepth explanations
• Explain serialization and deserialization separately
• Explain how to create a custom representation restorer
• Explain how to manually create a representation instead of using ReprUtil since a few classes still use that

I'd suggest the following:

• don't tell people to use computeSync(). Instead, tell them to do a complete x.getRepresentation(); send(); x = fromRepresentation() cycle, simulating a real application.
• add (a short version of) the paper's discussion on the two benchmark types
• Add the JMH code example from the paper (but a full version of it) to the .md file.
• Maybe weave in some of the counting description from the paper, I thought that was pretty clear and concise.