github.com/onflow/flow-go/crypto@v0.24.8/README.md (about)

     1  # Flow Cryptography
     2  
     3  This Go package provides the cryptography tools needed by the Flow blockchain.
     4  Most of the primitives and protocols can be used in other projects and are not specific to Flow.
     5  
     6  Flow is an ongoing project, which means that new features will still be added and modifications will still be made to improve security and performance of the cryptography package.
     7  
     8  Notes:
     9     - The package has been audited for security in January 2021 on [this version](https://github.com/onflow/flow-go/tree/2707acdabb851138e298b2d186e73f47df8a14dd). The package had a few improvements since. 
    10     - The package does not provide security against side channel or fault attacks.
    11  
    12  ## Package import
    13  
    14  Cloning Flow repository and following the [installation steps](https://github.com/onflow/flow-go) builds the necessary tools to use Flow cryptography.
    15  
    16  If you wish to only import the Flow cryptography package into your Go project, please follow the following steps:
    17  
    18  - Get Flow cryptography package 
    19  ```
    20  go get github.com/onflow/flow-go/crypto
    21  ```
    22  or simply import the package to your Go project
    23   ```
    24  import "github.com/onflow/flow-go/crypto"
    25  ```
    26  
    27  This is enough to run the package code for many functionalities. However, this isn't enough if BLS signature related functionalities are used. The BLS features rely on an extrnal C library ([Relic](https://github.com/relic-toolkit/relic)) for lower level mathematical operations. Building your project at this stage including BLS functionalities would result in build errors related to missing "relic" files. For instance:
    28  ```
    29  fatal error: 'relic.h' file not found
    30  #include "relic.h"
    31           ^~~~~~~~~
    32  ```
    33  
    34   An extra step is required to compile the external dependency (Relic) locally. 
    35  
    36  - Install [CMake](https://cmake.org/install/), which is used for building the package. The build also requires [Git](http://git-scm.com/) and bash scripting.  
    37  - From the Go package directory in `$GOPATH/pkg/mod/github.com/onflow/flow-go/crypto@<version-tag>/`, build the package dependencies. `version-tag` is the imported package version. 
    38  For instance:
    39  ```
    40  cd $GOPATH/pkg/mod/github.com/onflow/flow-go/crypto@v0.25.0/
    41  go generate
    42  ```
    43  
    44  Below is a bash script example to automate the above steps. The script can be copied into your Go project root directory.
    45  It extracts the imported pacakage version from your project's go.mod file and performs the remaining steps. 
    46  ```bash
    47  #!/bin/bash
    48  
    49  # crypto package 
    50  PKG_NAME="github.com/onflow/flow-go/crypto"
    51  
    52  # go get the package
    53  go get ${PKG_NAME}
    54  
    55  # go.mod
    56  MOD_FILE="./go.mod"
    57  
    58  # the version of onflow/flow-go/crypto used in the project is read from the go.mod file
    59  if [ -f "${MOD_FILE}" ]
    60  then
    61      # extract the version from the go.mod file
    62      VERSION="$(grep ${PKG_NAME} < ${MOD_FILE} | cut -d' ' -f 2)"
    63      # using the right version, get the package directory path
    64      PKG_DIR="$(go env GOPATH)/pkg/mod/${PKG_NAME}@${VERSION}"
    65  else 
    66     { echo "couldn't find go.mod file - make sure the script is in the project root directory"; exit 1; }
    67  fi
    68  
    69  # grant permissions if not existant
    70  if [[ ! -r ${PKG_DIR}  || ! -w ${PKG_DIR} || ! -x ${PKG_DIR} ]]; then
    71     sudo chmod -R 755 "${PKG_DIR}"
    72  fi
    73  
    74  # get into the package directory and set up the external dependencies
    75  (
    76      cd "${PKG_DIR}" || { echo "cd into the GOPATH package folder failed"; exit 1; }
    77      go generate
    78  )
    79  ``` 
    80  
    81  
    82  Finally, when building your project and including any BLS functionality, adding a Go build tag to include the BLS files in the build is required.
    83  The tag is not required when the package is used without BLS functions. It was introduced to avoid build errors when BLS (and therefore Relic) is not needed.
    84  
    85  ```
    86  go build -tags=relic
    87  ```
    88  
    89  ## Algorithms
    90  
    91  ### Hashing and Message Authentication Code:
    92  
    93  `crypto/hash` provides the hashing and MAC algorithms required for Flow. All algorithm implement the generic interface `Hasher`. All digests are of the generic type `Hash`.
    94  
    95   * SHA-3: 256 and 384 output sizes
    96   * Legacy Kaccak: 256 output size
    97   * SHA-2: 256 and 384 output sizes
    98   * KMAC: 128 variant
    99  
   100  ### Signature schemes
   101  
   102  All signature schemes use the generic interfaces of `PrivateKey` and `PublicKey`. All signatures are of the generic type `Signature`.
   103  
   104   * ECDSA
   105      * public keys are compressed or uncompressed.
   106      * ephemeral key is derived from the private key, hash and an external entropy using a CSPRNG (based on https://golang.org/pkg/crypto/ecdsa/).
   107      * supports NIST P-256 (secp256r1) and secp256k1 curves.
   108  
   109   * BLS
   110      * supports [BLS 12-381](https://electriccoin.co/blog/new-snark-curve/) curve.
   111      * is implementing the minimal-signature-size variant:
   112      signatures in G1 and public keys in G2.
   113      * default set-up uses [compressed](https://www.ietf.org/archive/id/draft-irtf-cfrg-pairing-friendly-curves-08.html#name-zcash-serialization-format-) G1/G2 points, 
   114      but uncompressed format is also supported.
   115      * hashing to curve uses the [Simplified SWU map-to-curve](https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-hash-to-curve-14#section-6.6.3).
   116      * expanding the message in hash-to-curve uses a cSHAKE-based KMAC128 with a domain separation tag.
   117      KMAC128 serves as an expand_message_xof function.
   118      * this results in the full ciphersuite BLS_SIG_BLS12381G1_XOF:KMAC128_SSWU_RO_POP_ for signatures
   119      and BLS_POP_BLS12381G1_XOF:KMAC128_SSWU_RO_POP_ for proofs of possession.
   120      * signature verification includes the signature membership check in G1.
   121      * public key membership check in G2 is provided outside of the signature verification.
   122      * membership check in G1 is using [Bowe's fast check](https://eprint.iacr.org/2019/814.pdf), while membership check in G2 is using a simple scalar multiplication by the group order (both will be updated to use Scott's method)
   123      * non-interactive aggregation of signatures, public keys and private keys.
   124      * multi-signature verification of an aggregated signature of a single message under multiple public keys.
   125      * multi-signature verification of an aggregated signature of multiple messages under multiple public keys.
   126      * batch verification of multiple signatures of a single message under multiple
   127      public keys: use a binary tree of aggregations to find the invalid signatures.
   128      * SPoCK scheme based on BLS: verifies two signatures have been generated from the same message that is unknown to the verifier.
   129  
   130   * Future features:
   131      * membership checks in G1/G2 using [Scotts's method](https://eprint.iacr.org/2021/1130.pdf).
   132      * support minimal-pubkey-size variant
   133  
   134  ### PRNG
   135  
   136   * ChaCha20-based CSPRNG
   137  
   138  ## Protocols
   139  
   140  ### Threshold Signature
   141  
   142   * BLS-based threshold signature
   143      * [non interactive](https://www.iacr.org/archive/pkc2003/25670031/25670031.pdf) threshold signature reconstruction.
   144      * supports only BLS 12-381 curve with the same features above.
   145      * (t+1) signatures are required to reconstruct the threshold signature.
   146      * key generation (single dealer) to provide the set of keys.
   147      * provides a stateless api and a stateful api.
   148  
   149   * Future features:
   150      * support a partial signature reconstruction in the stateful api to avoid a long final reconstruction.
   151  
   152  
   153  ### Discrete-Log based distributed key generation
   154  
   155  All supported Distributed Key Generation protocols are [discrete log based](http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.50.2737&rep=rep1&type=pdf) and are implemented for the same BLS setup on the BLS 12-381 curve. The protocols generate key sets for the BLS-based threshold signature.
   156  
   157   * Feldman VSS
   158      * simple verifiable secret sharing with a single dealer.
   159      * the library does not implement the communication channels between participants. The caller should implement the methods `PrivateSend` (1-to-1 messaging) and `Broadcast` (1-to-n messaging)
   160      * 1-to-1 messaging must be a private channel, the caller must make sure the channel preserves confidentialiy and authenticates the sender.
   161      * 1-to-n broadcasting assume all destination participants receive the same copy of the message. The channel should also authenticate the broadcaster.
   162      * It is recommended that both communication channels are unique per protocol instance. This could be achieved by prepending the messages to send/broadcast by a unique protocol instance ID.
   163   * Feldman VSS Qual.
   164      * an extension of the simple Feldman VSS.
   165      * implements a complaint mechanism to qualify/disqualify the dealer.
   166   * Joint Feldman (Pedersen)
   167      * distributed generation.
   168      * based on multiple parallel instances of Feldman VSS Qual with multiple dealers.
   169      * same assumptions about the communication channels as in Feldman VSS.
   170  
   171  
   172  
   173  
   174