Merge pull request #379 from tuneinsight/dev_release_v4.2.0

Release v5

.github/workflows/ci.yml

@@ -6,13 +6,13 @@ jobs:
     name: Run static checks
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v3
       with:
         fetch-depth: 1
     - name: Setup Go
-      uses: actions/setup-go@v3
+      uses: actions/setup-go@v4
       with:
-        go-version: 1.19
+        go-version: '1.21.1'
 
     - uses: actions/cache@v3
       with:
@@ -32,13 +32,13 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        go: [ '1.19', '1.18', '1.17', '1.16', '1.15', '1.14' ]
+        go: ['1.21.1', '1.20.8', '1.19.13', '1.18.10']
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Setup Go
-        uses: actions/setup-go@v3
+        uses: actions/setup-go@v4
         with:
           go-version: ${{ matrix.go }}
 

Makefile

@@ -4,20 +4,6 @@
 test_gotest:
 	go test -timeout=0 ./...
 
-.PHONY: test_examples
-test_examples:
-	@echo Running the examples
-	go run ./examples/ring/vOLE -short > /dev/null
-	go run ./examples/rgsw > /dev/null
-	go run ./examples/bfv > /dev/null
-	go run ./examples/ckks/bootstrapping -short > /dev/null
-	go run ./examples/ckks/advanced/lut -short > /dev/null
-	go run ./examples/ckks/euler > /dev/null
-	go run ./examples/ckks/polyeval > /dev/null
-	go run ./examples/dbfv/pir &> /dev/null
-	go run ./examples/dbfv/psi &> /dev/null
-	@echo ok
-
 .PHONY: static_check
 static_check: check_tools
 	@echo Checking correct formatting of files
@@ -48,7 +34,7 @@ static_check: check_tools
 		false;\
     fi
 
-	@STATICCHECKOUT=$$(staticcheck -go 1.19 -checks all ./...); \
+	@STATICCHECKOUT=$$(staticcheck -go 1.20 -checks all ./...); \
 	if [ -z "$$STATICCHECKOUT" ]; then\
         echo "staticcheck: OK";\
 	else \
@@ -62,16 +48,16 @@ static_check: check_tools
 	out=`git status --porcelain`; echo "$$out"; [ -z "$$out" ]
 
 .PHONY: test
-test: test_gotest test_examples
+test: test_gotest
 
 .PHONY: ci_test
-ci_test: static_check test_gotest test_examples
+ci_test: static_check test_gotest
 
 EXECUTABLES = goimports staticcheck
 .PHONY: get_tools
 get_tools:
 	go install golang.org/x/tools/cmd/goimports@latest
-	go install honnef.co/go/tools/cmd/staticcheck@2022.1.1
+	go install honnef.co/go/tools/cmd/staticcheck@2023.1.5
 
 .PHONY: check_tools
 check_tools:

README.md

@@ -6,13 +6,15 @@
 
 ![Go tests](https://github.com/tuneinsight/lattigo/actions/workflows/ci.yml/badge.svg)
 
-Lattigo is a Go module that implements Ring-Learning-With-Errors-based homomorphic-encryption
+Lattigo is a Go module that implements full-RNS Ring-Learning-With-Errors-based homomorphic-encryption
 primitives and Multiparty-Homomorphic-Encryption-based secure protocols. The library features:
-- An implementation of the full-RNS BFV, BGV and CKKS schemes and their respective multiparty versions.
-- Comparable performance to state-of-the-art C++ libraries.
-- Dense-key and sparse-key efficient and high-precision bootstrapping procedures for full-RNS CKKS.
-- A pure Go implementation that enables cross-platform builds, including WASM compilation for
-  browser clients.
+
+- Optimized arithmetic for power-of-two cyclotomic rings.
+- Advanced and scheme-agnostic implementation of RLWE-based primitives, key-generation, and their multiparty version.
+- Implementation of the BFV/BGV and CKKS schemes and their multiparty version.
+- Support for RGSW, external product and LMKCDEY blind rotations.
+- A pure Go implementation, enabling cross-platform builds, including WASM compilation for
+browser clients, with comparable performance to state-of-the-art C++ libraries.
 
 Lattigo is meant to support HE in distributed systems and microservices architectures, for which Go
 is a common choice thanks to its natural concurrency model and portability.
@@ -21,32 +23,89 @@ is a common choice thanks to its natural concurrency model and portability.
 
 The library exposes the following packages:
 
-- `lattigo/ring`: Modular arithmetic operations for polynomials in the RNS basis, including: RNS
-  basis extension; RNS rescaling; number theoretic transform (NTT); uniform, Gaussian and ternary
-  sampling.
+- `lattigo/he`: The main package of the library which provides scheme-agnostic interfaces
+  and Homomorphic Encryption for different plaintext domains.
+
+  - `hebin`: Homomorphic Encryption for binary arithmetic. It comprises blind rotations (a.k.a Lookup Tables) over RLWE ciphertexts.
+
+  - `hefloat`: Homomorphic Encryption for fixed-point approximate arithmetic over the complex or real numbers.
+
+    - `bootstrapper`: Bootstrapping for fixed-point approximate arithmetic over the real
+      and complex numbers, with support for the Conjugate Invariant ring, batch bootstrapping with automatic
+      packing/unpacking of sparsely packed/smaller ring degree ciphertexts, arbitrary precision bootstrapping,
+      and advanced circuit customization/parameterization.
+
+  - `heint`: Homomorphic Encryption for modular arithmetic over the integers.
+
+- `lattigo/mhe`: Package for multiparty (a.k.a. distributed or threshold) key-generation and 
+  interactive ciphertext bootstrapping with secret-shared secret keys.
+
+  - `mhefloat`: Homomorphic decryption and re-encryption from and to Linear-Secret-Sharing-Shares, 
+    as well as interactive ciphertext bootstrapping for the package `he/hefloat`.
 
-- `lattigo/bfv`: The Full-RNS variant of the Brakerski-Fan-Vercauteren scale-invariant homomorphic
-  encryption scheme. It provides modular arithmetic over the integers.
+  - `mheint`: Homomorphic decryption and re-encryption from and to Linear-Secret-Sharing-Shares, 
+    as well as interactive ciphertext bootstrapping for the package `he/heint`.
 
-- `lattigo/bgv`: The Full-RNS variant of the Brakerski-Gentry-Vaikuntanathan homomorphic
-  encryption scheme. It provides modular arithmetic over the integers.
-
-- `lattigo/ckks`: The Full-RNS Homomorphic Encryption for Arithmetic for Approximate Numbers (HEAAN,
-  a.k.a. CKKS) scheme. It provides approximate arithmetic over the complex numbers (in its classic
-  variant) and over the real numbers (in its conjugate-invariant variant).
+- `lattigo/schemes`: A package implementing RLWE-based homomorphic encryption schemes.
 
-- `lattigo/dbfv`, `lattigo/dbgv` and `lattigo/dckks`: Multiparty (a.k.a. distributed or threshold) 
-  versions of the BFV, BGV and CKKS schemes that enable secure multiparty computation solutions with 
-  secret-shared secret keys.
+  - `bfv`: A Full-RNS variant of the Brakerski-Fan-Vercauteren scale-invariant homomorphic
+    encryption scheme. This scheme is instantiated via a wrapper of the `bgv` scheme. 
+    It provides modular arithmetic over the integers.
 
-- `lattigo/rlwe` and `lattigo/drlwe`: common base for generic RLWE-based multiparty homomorphic
-  encryption. It is imported by the `lattigo/bfv`, `lattigo/bgv` and `lattigo/ckks` packages.
+  - `bgv`: A Full-RNS generalization of the Brakerski-Fan-Vercauteren scale-invariant (BFV) and 
+    Brakerski-Gentry-Vaikuntanathan (BGV) homomorphic encryption schemes. 
+    It provides modular arithmetic over the integers.
+
+  - `ckks`: A Full-RNS Homomorphic Encryption for Arithmetic for Approximate Numbers (HEAAN,
+    a.k.a. CKKS) scheme. It provides fixed-point approximate arithmetic over the complex numbers (in its classic
+    variant) and over the real numbers (in its conjugate-invariant variant).
+
+- `lattigo/core`: A package implementing the core cryptographic functionalities of the library.
+
+  - `rlwe`: Common base for generic RLWE-based homomorphic encryption.
+  It provides all homomorphic functionalities and defines all structs that are not scheme-specific.
+  This includes plaintext, ciphertext, key-generation, encryption, decryption and key-switching, as
+  well as other more advanced primitives such as RLWE-repacking.
+
+  - `rgsw`: A Full-RNS variant of Ring-GSW ciphertexts and the external product.
+
+- `lattigo/ring`: Modular arithmetic operations for polynomials in the RNS basis, including: RNS
+  basis extension; RNS rescaling; number theoretic transform (NTT); uniform, Gaussian and ternary
+  sampling.
 
 - `lattigo/examples`: Executable Go programs that demonstrate the use of the Lattigo library. Each
                       subpackage includes test files that further demonstrate the use of Lattigo
                       primitives.
 
-- `lattigo/utils`: Supporting structures and functions.
+- `lattigo/utils`: Generic utility methods. This package also contains the following sub-pacakges:
+  - `bignum`: Arbitrary precision linear algebra and polynomial approximation.
+  - `buffer`: Efficient methods to write/read on `io.Writer` and `io.Reader`.
+  - `factorization`: Various factorization algorithms for medium-sized integers.
+  - `sampling`: Secure bytes sampling.
+  - `structs`: Generic structs for maps, vectors and matrices, including serialization.
+
+```mermaid
+---
+title: Packages Dependency & Organization
+---
+flowchart LR
+RING(RING) --> RLWE(RLWE)
+RLWE --> RGSW(RGSW)
+RLWE --> HE([HE])
+RLWE --> CKKS{{CKKS}}
+RGSW --> HEBin{HEBin}
+HE --> HEFloat{HEFloat}
+HE --> HEInt{HEInt}
+BFV/BGV --> HEInt
+CKKS --> HEFloat
+RLWE --> BFV/BGV{{BFV/BGV}}
+MHE --> MHEFloat
+HEFloat --> MHEFloat((MHEFloat))
+HEFloat --> Bootstrapping
+HEInt --> MHEInt((MHEInt))
+RLWE --> MHE([MHE])
+MHE --> MHEInt
+```
 
 ## Versions and Roadmap
 
@@ -86,61 +145,28 @@ us before doing so to make sure that the proposed changes are aligned with our d
 
 External pull requests only proposing small or trivial changes will be converted to an issue and closed.
 
-## Support and Issues
-
-The GitHub issues should only be used for bug reports and questions directly related to the use or the implementation of the library.
-Any other issue will be closed, and for this we recommend the use of [GitHub discussions](https://github.com/tuneinsight/lattigo/discussions) or other topic-specific forums instead.
-Any new issue regarding an unexpected behavior of the library or one of its packages must be accompanied 
-by a self-contained `main.go` reproducing the unwanted behavior.
-
 ## License
 
 Lattigo is licensed under the Apache 2.0 License. See [LICENSE](https://github.com/tuneinsight/lattigo/blob/master/LICENSE).
 
 ## Contact
 
-If you want to contribute to Lattigo, to contact us directly or to report a security issue, please do so using the following email: [[email protected]](mailto:[email protected]).
+Before contacting us directly, please make sure that your request cannot be handled through an issue.
+
+If you want to contribute to Lattigo, have a feature proposal or request, to report a security issue or simply want to contact us directly, please do so using the following email: [[email protected]](mailto:[email protected]).
 
 ## Citing
 
 Please use the following BibTex entry for citing Lattigo:
 
     @misc{lattigo,
-	    title = {Lattigo v4},
+	    title = {Lattigo v5},
 	    howpublished = {Online: \url{https://github.com/tuneinsight/lattigo}},
-	    month = Aug,
-	    year = 2022,
+	    month = Nov,
+	    year = 2023,
 	    note = {EPFL-LDS, Tune Insight SA}
     }
 
-## References
-
-1. Efficient Bootstrapping for Approximate Homomorphic Encryption with Non-Sparse Keys
-   (<https://eprint.iacr.org/2020/1203>)
-1. Bootstrapping for Approximate Homomorphic Encryption with Negligible Failure-Probability by Using Sparse-Secret Encapsulation
-   (<https://eprint.iacr.org/2022/024>)
-1. Somewhat Practical Fully Homomorphic Encryption (<https://eprint.iacr.org/2012/144>)
-1. Multiparty Homomorphic Encryption from Ring-Learning-With-Errors (<https://eprint.iacr.org/2020/304>)
-2. An Efficient Threshold Access-Structure for RLWE-Based Multiparty Homomorphic Encryption (<https://eprint.iacr.org/2022/780>)
-3. A Full RNS Variant of FV Like Somewhat Homomorphic Encryption Schemes
-   (<https://eprint.iacr.org/2016/510>)
-4. An Improved RNS Variant of the BFV Homomorphic Encryption Scheme
-   (<https://eprint.iacr.org/2018/117>)
-5. Homomorphic Encryption for Arithmetic of Approximate Numbers (<https://eprint.iacr.org/2016/421>)
-6. A Full RNS Variant of Approximate Homomorphic Encryption (<https://eprint.iacr.org/2018/931>)
-7. Improved Bootstrapping for Approximate Homomorphic Encryption
-1. Fully Homomorphic Encryption without Bootstrapping (<https://eprint.iacr.org/2011/277>)     
-1. Homomorphic Encryption for Arithmetic of Approximate Numbers (<https://eprint.iacr.org/2016/421>)
-1. A Full RNS Variant of Approximate Homomorphic Encryption (<https://eprint.iacr.org/2018/931>)
-1. Improved Bootstrapping for Approximate Homomorphic Encryption
-   (<https://eprint.iacr.org/2018/1043>)
-8. Better Bootstrapping for Approximate Homomorphic Encryption (<https://eprint.iacr.org/2019/688>)
-9.  Post-quantum key exchange - a new hope (<https://eprint.iacr.org/2015/1092>)
-10. Faster arithmetic for number-theoretic transforms (<https://arxiv.org/abs/1205.2926>)
-11. Speeding up the Number Theoretic Transform for Faster Ideal Lattice-Based Cryptography
-   (<https://eprint.iacr.org/2016/504>)
-12. Gaussian sampling in lattice-based cryptography
-   (<https://tel.archives-ouvertes.fr/tel-01245066v2>)
 
 The Lattigo logo is a lattice-based version of the original Golang mascot by [Renee
 French](http://reneefrench.blogspot.com/).

SECURITY.md

@@ -11,12 +11,17 @@ Classified as an _approximate decryption_ scheme, the CKKS scheme is secure as l
 
 This attack demonstrates that, when using an approximate homomorphic encryption scheme, the usual CPA security may not sufficient depending on the application setting. Many applications do not require to share the result with external parties and are not affected by this attack, but the ones that do must take the appropriate steps to ensure that no key-dependent information is leaked. A homomorphic encryption scheme that provides such functionality and that can be secure when releasing decrypted plaintext to external parties is defined to be CPA<sup>D</sup> secure. The corresponding indistinguishability notion (IND-CPA<sup>D</sup>) is defined as "indistinguishability under chosen plaintext attacks with decryption oracles."
 
-# CPA<sup>D</sup> Security for CKKS
-Lattigo implements tools to mitigate _Li and Micciancio_'s attack. In particular, the decoding step of CKKS (and its real-number variant R-CKKS) allows the user to add a key-independent error $e$ of standard deviation $\sigma$ to the decrypted plaintext before decoding.
+# CPA<sup>D</sup> Security for Approximate Homomorphic Encryption
+Lattigo implements tools to mitigate _Li and Micciancio_'s attack. In particular, the decoding step of CKKS (and its real-number variant R-CKKS) allows the user to specify the desired fixed-point bit-precision.
 
-If at any point of an application, decrypted values have to be shared with external parties, then the user must ensure that each shared plaintext is first _sanitized_ before being shared. To do so, the user must use the $\textsf{DecodePublic}$ method instead of the usual $\textsf{Decode}$. $\textsf{DecodePublic}$ takes as additional input $\sigma$, and samples a key-independent error $e$ with standard deviation $\sigma$, that is added to the plaintext before decoding.
+Let $\epsilon$ be the scheme error after the decoding step. We compute the bit precision of the output as $\log_{2}(1/\epsilon)$.
 
-Estimating $\sigma$ must be done carefully and we suggest the following iterative process to do so:
- 1. Given a security parameter $\lambda$ and a circuit $C$ that takes as inputs length-_n_ vectors $\omega$ following a distribution $\chi$, select the appropriate parameters enabling the homomorphic evaluation of $C(\omega)$, denoted by $H(C(\omega))$, which includes the encoding, encryption, evaluation, decryption and decoding.
- 2. Sample input vectors $\omega$ from the distribution $\chi$ and compute the standard deviation $\sigma$ in the time domain (coefficient domain) of $e=C(\omega) - H(C(\omega))$. This can be done using the encoder method $\textsf{GetErrSTDTimeDom}(C(\omega), H(C(\omega)), \Delta)$, where $\Delta$ is the scale of the plaintext after the decryption. The user should make sure that the underlying circuit computed by $H(C(\cdot))$ is identical to $C(\cdot)$; i.e., if the homomorphic implementation $H(C(\cdot))$ uses polynomial approximations, then $C(\cdot)$ should use them too, instead of using the original exact function. This will ensure that $e$, and therefore $\sigma$, are as close as possible to the actual underlying scheme error, and not influenced by function-approximation errors.
- 3. Use the encoder method $\textsf{DecodePublic}$ with the parameter $\sigma$ to decode plaintexts that will be published. $\textsf{DecodePublic}$ adds an error $e$ with standard deviation $\sigma$ bounded by $B = \sigma\sqrt{2\pi}$. The precision loss, compared to a private decoding, should be less than half a bit on average.
+If at any point of an application, decrypted values have to be shared with external parties, then the user must ensure that each shared plaintext is first _sanitized_ before being shared. To do so, the user must use the $\textsf{DecodePublic}$ method instead of the usual $\textsf{Decode}$. $\textsf{DecodePublic}$ takes as additional input the desired $\log_{2}(1/\epsilon)$-bit precision and rounds the value by evaluating $y = \lfloor x / \epsilon \rceil \cdot \epsilon$.
+
+Estimating $\text{Pr}[\epsilon < x] \leq 2^{-s}$ of the circuit must be done carefully and we suggest the following process to do so:
+ 1. Given a security parameter $\lambda$ and a circuit $C$ that takes as inputs length-$n$ vectors $\omega$ following a distribution $\chi$, select the appropriate parameters enabling the homomorphic evaluation of $C(\omega)$, denoted by $H(C(\omega))$, which includes the encoding, encryption, evaluation, decryption and decoding.
+ 2. Sample input vectors $\omega$ from the distribution $\chi$ and record $\epsilon = C(\omega) - H(C(\omega))$ for each slots. The user should make sure that the underlying circuit computed by $H(C(\cdot))$ is identical to $C(\cdot)$; i.e., if the homomorphic implementation $H(C(\cdot))$ uses polynomial approximations, then $C(\cdot)$ should use them too, instead of using the original exact function. Repeat until enough data points are collected to construct a CDF of $\textsf{Pr}[\epsilon > x]$.
+ 3. Use the CDF to select the value $\text{E}[\epsilon]$ such that any given slot will fail with probability $2^{-\varepsilon}$ (where $\varepsilon$ is a user-defined security parameter) to reach $\log_{2}(1/\epsilon)$ bits of precision. 
+ 4. Use the encoder method $\textsf{DecodePublic}$ with the parameter $\log_{2}(1/\epsilon)$ to decode plaintexts that will be published.
+
+Note that, for composability with differential privacy, the variance of the error introduced by the rounding is $\text{Var}[x - \lfloor x \cdot \epsilon \rceil / \epsilon] = \tfrac{\epsilon^2}{12}$ and therefore $\text{Var}[x -  \lfloor x/(\sigma\sqrt{12})\rceil\cdot(\sigma\sqrt{12})] = \sigma^2$.