Documentation clarifications for BLST integration

README.md

@@ -6,7 +6,7 @@ The primitives and protocols can be used in other projects and are not specific
 Notes:
    - The package has been audited for security in January 2021 on [this version](https://github.com/onflow/crypto/tree/bc6bbd277994d5d50ca3b777bd6747f555629c18). The package had a major refactor to switch all the BLS12-381 curve implementation to use [BLST](https://github.com/supranational/blst/tree/master/src) starting from version `v0.25.0`. 
    - The package used to live under the [flow-go](https://github.com/onflow/flow-go) repository before being moved out as a separate repository. The move preserved all the module Git history.
-   - The module does not provide security against side channel or fault attacks.
+   - The module does not provide security against side channel or fault injection attacks.
 
 ## Module import
 

blst_src/README.md

@@ -5,7 +5,11 @@ specifically from the tagged version `v0.3.14`.
  Licensed under the Apache License, Version 2.0, see LICENSE for details.
  SPDX-License-Identifier: Apache-2.0
 
-While BLST exports multiple functions and tools, the implementation in Flow crypto requires access to low level functions. Some of these tools are not exported by BLST, others would need to be used without paying for the cgo cost, and therefore without using the Go bindings in BLST. 
+While BLST exports multiple functions and tools, the implementation in Flow crypto requires access to low level BLS12-381 curve functions. Some of these tools are not exported by BLST, others would need to be used without paying for the cgo cost, and therefore without using the Go bindings in BLST.
+
+Higher level protocols are all implemented within Flow crypto and are not using BLST source. Only the BLS12-381 curve
+implementation from BLST is used to benfit from its high performance. All code outisde of `./blst_src` and `./blst/internal` is
+not code re-used from BLST source. 
 
 The folder contains:
 - BLST LICENSE file

internal/blst/README.md

@@ -0,0 +1,15 @@
+This package simulates the BLST Go bindings https://github.com/supranational/blst/tree/master/bindings/go.
+
+Files in this folder are copied from the BLST Go binding, specifically from the BLST version supported by the Flow crypto
+(check https://github.com/onflow/crypto/blob/main/blst_src/README.md for the exact BLST version tag).
+
+ Copyright Supranational LLC
+ Licensed under the Apache License, Version 2.0, see LICENSE for details.
+ SPDX-License-Identifier: Apache-2.0
+
+The BLST Go bindings are not exported or used by the Flow crypto package. 
+Some BLS signature bindings are used only for compatibility tests in https://github.com/onflow/crypto/blob/main/bls_crossBLST_test.go.
+The BLST source code used by Flow crypto is the low level BLS12-381 arithmetic as explained in https://github.com/onflow/crypto/blob/main/blst_src/README.md. The higher level protocols using curve BLS12-381 are implemented within Flow crypto.
+
+The reason of not importing the BLST Go bindings package but rather duplicating it as an internal package is related to a cgo build limitation. When importing the BLST Go bindings, the low level C and assembly functions are also linked when the tests are run. The cgo linker detects duplications in low level symbols (the ones from the imported BLST package and the ones from Flow crypto) and errors. By avoiding the Go package import and instead copying the BLST go bindings, the tests use the same non-duplicated low level layer for both the BLST bindings and Flow crypto. The tests are still relevant because they check compatibility of the higher layers.
+