Home

Awesome

=nil; Foundation's Cryptography Suite

Build docs Discord Telegram Twitter

Crypto3 cryptography suite's purpose is:

  1. To provide a secure, fast and architecturally clean C++ generic cryptography schemes implementation.
  2. To provide a developer-friendly, modular suite, usable for novel schemes implementation and further extension.
  3. To provide a Standard Template Library-alike C++ interface and concept-based architecture implementation.

Libraries are designed to be state of the art, highly performant and providing a one-stop solution for all cryptographic operations. They are supported on all operating systems (*nix, windows, macOS) and architectures(x86/ARM).

Developed by =nil; Crypto3 and supported by =nil; Foundation.

Rationale, tutorials and references are available here

Contents

  1. Repository Structure
  2. Installation
  3. Usage
  4. Contributing
  5. Community

Repository Structure

This repository is an umbrella-repository for the whole suite. Single-purposed libraries repositories (e.g. block or hash) are not advised to be used outside this suite or properly constructed CMake project and should be handled with great care.

root
├── cmake: cmake sub-module with helper functions/macros to build crypto3 library umbrella-repository
├── docs: documentation , tutorials and guides
├── libs: all directories added as submodules which are independent projects.
│   ├── algebra: algebraic operations and structures being used for elliptic-curve cryptography
│   ├── block: block ciphers
│   ├── blueprint: components and circuits for zk schemes
│   ├── codec: encoding/decoding algorithms
│   ├── containers: containers and generic commitment schemes for accumulating data, includes Merkle Tree
│   ├── hash: hashing algorithms
│   ├── kdf: key derivation functions 
│   ├── mac: message authentication codes
│   ├── marshalling: marshalling libraries for types in crypto3 library
│   ├── math: set of Fast Fourier Transforms evaluation algorithms and Polynomial Arithmetics
│   ├── modes: cipher modes
│   ├── multiprecision: integer, rational, floating-point, complex and interval number types. 
│   ├── passhash: password hashing operations 
│   ├── pbkdf: password based key derivation functions
│   ├── pkmodes: threshold, aggregation modes for public key schemes
│   ├── pkpad: padding module for public key schemes
│   ├── pubkey: pubkey signing APIs
│   ├── random: randomisation primitives 
│   ├── stream: stream ciphers
│   ├── vdf: verifiable delay functions 
│   ├── zk: zk cryptography schemes

Installation

Dependencies

Clone & Build

git clone --recurse-submodules https://github.com/nilfoundation/crypto3.git 
cd crypto3 && mkdir build && cd build
cmake ..
make tests

Nix support

This repository provides Nix flake, so once you have installed Nix with flake support, you can use single command to fetch all the dependencies and build:

nix build

To activate Nix development environment:

nix develop

To run all tests:

nix flake check

To run single test:

nix develop . -c cmake -B build -DCMAKE_CXX_STANDARD=17 -DCMAKE_BUILD_TYPE=Debug -DBUILD_SHARED_LIBS=FALSE -DCMAKE_ENABLE_TESTS=TRUE -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_BUILD_TYPE=Debug  -DCMAKE_CXX_FLAGS=-ggdb
nix develop -c cmake --build build -t <test_target> // for example multiprecision_modular_adaptor_fixed_test

Usage

Cryptography suite can be used as follows:

  1. Generic.
  2. Selective.

The suite is used as a header-only and is currently statically linked. Future versions will allow dynamic linking.

Generic

Generic usage of cryptography suite consists of all modules available at GitHub =nil; Crypto3 Team Repositories. This is an umbrella-repository where Modules are added as submodules emplaced in libs directory. A developer can thus add this
project as a submodule and would not need to resolve dependencies. See crypto3-scaffold as an example of usage.

The generic module can be added to your c++ project as follows

git submodule add https://github.com/NilFoundation/crypto3.git <dir>

Selective

Developer can select to include a one or more modules to reduce the sources of resulting project and dependencies tree height. This however does require the developer to manually resolve all required dependencies and stay upto date regarding compatibilities across modules.

Example of such embedding is =nil; Foundation's Actor Library. It uses only hashes so the dependency graph requires for the project to submodule block ciphers library and optional codec library for testing purposes. So, the root Actor repository has only related libraries submoduled: block, codec and hash.

Selective modules can be added to your project as follows:

git submodule add https://github.com/NilFoundation/crypto3-<lib>.git <dir>

Contributing

See contributing for contribution guidelines.

Support

This cryptography suite is authored by =nil; Crypto3 team, so you can contact it several ways:

Licence

The software is provided under MIT Licence.