Skip to content

Commit

Permalink
chore: add paragraph about the security model (#623)
Browse files Browse the repository at this point in the history
  • Loading branch information
andrei-stoian-zama authored Apr 19, 2024
1 parent c6917a3 commit 18628fd
Show file tree
Hide file tree
Showing 7 changed files with 38 additions and 10 deletions.
Binary file removed docs/.gitbook/assets/jupyter_logo.png
Binary file not shown.
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ Access to additional resources and join the Zama community.

Refer to the API, review product architecture, and access additional resources for in-depth explanations while working with Concrete ML.

- [Security and correctness](explanations/security_and_correctness.md)
- [API](references/api/README.md)
- [Quantization](explanations/quantization.md)
- [Pruning](explanations/pruning.md)
Expand Down
1 change: 1 addition & 0 deletions docs/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@

## Explanations

- [Security and correctness](explanations/security_and_correctness.md)
- [Quantization](explanations/quantization.md)
- [Pruning](explanations/pruning.md)
- [Compilation](explanations/compilation.md)
Expand Down
19 changes: 19 additions & 0 deletions docs/explanations/security_and_correctness.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Security and correctness

## Security model

The default parameters for Concrete ML are chosen considering the [IND-CPA](https://en.wikipedia.org/wiki/Ciphertext_indistinguishability) security model, and are selected with a [bootstrapping off-by-one error probability](../explanations/advanced_features.md#tolerance-to-off-by-one-error-for-an-individual-tlu) of $$2^-40$$. In particular, it is assumed that the results of decrypted computations are not shared by the secret key owner with any third parties, as such an action can lead to leakage of the secret encryption key. If you are designing an application where decryptions must be shared, you will need to craft custom encryption parameters which are chosen in consideration of the IND-CPA^D security model \[1\].

## Correctness of computations

The [cryptography concepts](../getting-started/concepts.md#cryptography-concepts) section explains how Concrete ML can ensure **guaranteed correctness of encrypted computations**. In this approach, a quantized machine learning model will be converted to an FHE circuit that produces the same result on encrypted data as the original model on clear data.

However, the [bootstrapping off-by-one error probability](../explanations/advanced_features.md#tolerance-to-off-by-one-error-for-an-individual-tlu) can be configured by the user. Raising this probability results in lower latency when executing on encrypted data, but higher values cancel the correctness guarantee of the default setting. In practice this may not be an issue, as the accuracy of the model may be maintained, even though slight differences are observed in the model outputs. Moreover, as noted in the [paragraph above](#security-model), raising the off-by-one error probability may negatively impact the security model.

Furthermore, a second approach to reduce latency at the expense of correctness is approximate computation of univariate functions. This mode is enabled by using the [rounding setting](../explanations/advanced_features.md#rounded-activations-and-quantizers). When using the [`fhe.Exactness.APPROXIMATE`](../references/api/concrete.ml.torch.compile.md#function-compile_torch_model) rounding method, off-by-one errors are always induced in the computation of activation functions, irrespective of the bootstrapping off-by-one error probability.

When trading-off better latency for correctness, it is highly recommended to use the [FHE simulation feature](../getting-started/concepts.md#i-model-development) to measure accuracy on a drawn-out test-set. In many cases the accuracy of the model is only slightly impacted by approximate computations.

## References

\[1\] Li, Baiyu, et al. “Securing approximate homomorphic encryption using differential privacy.” Annual International Cryptology Conference. Cham: Springer Nature Switzerland, 2022. https://eprint.iacr.org/2022/816.pdf
1 change: 1 addition & 0 deletions docs/index.toc.txt
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@
:hidden:
:caption: Explanations

explanations/security_and_correctness.md
explanations/quantization.md
explanations/pruning.md
explanations/compilation.md
Expand Down
4 changes: 2 additions & 2 deletions docs/tutorials/dl_examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,12 +12,12 @@ Some examples constrain accumulators to 7-8 bits, which can be sufficient for si

### 1. Step-by-step guide to building a custom NN

[![](../.gitbook/assets/jupyter_logo.png) Quantization aware training example](../advanced_examples/QuantizationAwareTraining.ipynb)
- [Quantization aware training example](../advanced_examples/QuantizationAwareTraining.ipynb)

This shows how to use Quantization Aware Training and pruning when starting out from a classical PyTorch network. This example uses a simple data-set and a small NN, which achieves good accuracy with low accumulator size.

### 2. Custom convolutional NN on the [Digits](https://scikit-learn.org/stable/modules/generated/sklearn.datasets.load_digits.html) data-set

[![](../.gitbook/assets/jupyter_logo.png) Convolutional Neural Network](../advanced_examples/ConvolutionalNeuralNetwork.ipynb)
- [Convolutional Neural Network](../advanced_examples/ConvolutionalNeuralNetwork.ipynb)

Following the [Step-by-step guide](../deep-learning/fhe_friendly_models.md), this notebook implements a Quantization Aware Training convolutional neural network on the MNIST data-set. It uses 3-bit weights and activations, giving a 7-bit accumulator.
22 changes: 14 additions & 8 deletions docs/tutorials/ml_examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,46 +18,52 @@ It is recommended to use [simulation](../explanations/compilation.md#fhe-simulat

### 1. Linear models

[![](../.gitbook/assets/jupyter_logo.png) Linear Regression example](../advanced_examples/LinearRegression.ipynb) [![](../.gitbook/assets/jupyter_logo.png) Logistic Regression example](../advanced_examples/LogisticRegression.ipynb) [![](../.gitbook/assets/jupyter_logo.png) Linear Support Vector Regression example](../advanced_examples/LinearSVR.ipynb) [![](../.gitbook/assets/jupyter_logo.png) Linear SVM classification](../advanced_examples/SVMClassifier.ipynb)
- [Linear Regression example](../advanced_examples/LinearRegression.ipynb)
- [Logistic Regression example](../advanced_examples/LogisticRegression.ipynb)
- [Linear Support Vector Regression example](../advanced_examples/LinearSVR.ipynb)
- [Linear SVM classification](../advanced_examples/SVMClassifier.ipynb)

These examples show how to use the built-in linear models on synthetic data, which allows for easy visualization of the decision boundaries or trend lines. Executing these 1D and 2D models in FHE takes around 1 millisecond.

### 2. Generalized linear models

[![](../.gitbook/assets/jupyter_logo.png) Poisson Regression example](../advanced_examples/PoissonRegression.ipynb) [![](../.gitbook/assets/jupyter_logo.png) Generalized Linear Models comparison](../advanced_examples/GLMComparison.ipynb)
- [Poisson Regression example](../advanced_examples/PoissonRegression.ipynb)
- [Generalized Linear Models comparison](../advanced_examples/GLMComparison.ipynb)

These two examples show generalized linear models (GLM) on the real-world [OpenML insurance](https://www.openml.org/d/41214) data-set. As the non-linear, inverse-link functions are computed, these models do not use [PBS](../getting-started/concepts.md#cryptography-concepts), and are, thus, very fast (~1ms execution time).

### 3. Decision tree

[![](../.gitbook/assets/jupyter_logo.png) Decision Tree Classifier](../advanced_examples/DecisionTreeClassifier.ipynb)
- [Decision Tree Classifier](../advanced_examples/DecisionTreeClassifier.ipynb)

Using the [OpenML spams](https://www.openml.org/d/44) data-set, this example shows how to train a classifier that detects spam, based on features extracted from email messages. A grid-search is performed over decision-tree hyper-parameters to find the best ones.

[![](../.gitbook/assets/jupyter_logo.png) Decision Tree Regressor](../advanced_examples/DecisionTreeRegressor.ipynb)
- [Decision Tree Regressor](../advanced_examples/DecisionTreeRegressor.ipynb)

Using the [House Price prediction](https://www.openml.org/search?type=data&sort=runs&id=537) data-set, this example shows how to train regressor that predicts house prices.

### 4. XGBoost and Random Forest classifier

[![](../.gitbook/assets/jupyter_logo.png) XGBoost/Random Forest example](../advanced_examples/XGBClassifier.ipynb)
- [XGBoost/Random Forest example](../advanced_examples/XGBClassifier.ipynb)

This example shows how to train tree-ensemble models (either XGBoost or Random Forest), first on a synthetic data-set, and then on the [Diabetes](https://www.openml.org/d/37) data-set. Grid-search is used to find the best number of trees in the ensemble.

### 5. XGBoost regression

[![](../.gitbook/assets/jupyter_logo.png) XGBoost Regression example](../advanced_examples/XGBRegressor.ipynb)
- [XGBoost Regression example](../advanced_examples/XGBRegressor.ipynb)

Privacy-preserving prediction of house prices is shown in this example, using the [House Prices](https://www.openml.org/d/43926) data-set. Using 50 trees in the ensemble, with 5 bits of precision for the input features, the FHE regressor obtains an $$R^2$$ score of 0.90 and an execution time of 7-8 seconds.

### 6. Fully connected neural network

[![](../.gitbook/assets/jupyter_logo.png) NN Iris example](../advanced_examples/FullyConnectedNeuralNetwork.ipynb) [![](../.gitbook/assets/jupyter_logo.png) NN MNIST example](../advanced_examples/FullyConnectedNeuralNetworkOnMNIST.ipynb)
- [NN Iris example](../advanced_examples/FullyConnectedNeuralNetwork.ipynb)
- [NN MNIST example](../advanced_examples/FullyConnectedNeuralNetworkOnMNIST.ipynb)

Two different configurations of the built-in, fully-connected neural networks are shown. First, a small bit-width accumulator network is trained on [Iris](https://www.openml.org/d/61) and compared to a PyTorch floating point network. Second, a larger accumulator (>8 bits) is demonstrated on [MNIST](http://yann.lecun.com/exdb/mnist/).

### 7. Comparison of models

[![](../.gitbook/assets/jupyter_logo.png) Classifier comparison](../advanced_examples/ClassifierComparison.ipynb) [![](../.gitbook/assets/jupyter_logo.png) Regressor comparison](../advanced_examples/RegressorComparison.ipynb)
- [Classifier comparison](../advanced_examples/ClassifierComparison.ipynb)
- [Regressor comparison](../advanced_examples/RegressorComparison.ipynb)

Based on three different synthetic data-sets, all the built-in classifiers are demonstrated in this notebook, showing accuracies, inference times, accumulator bit-widths, and decision boundaries.

0 comments on commit 18628fd

Please sign in to comment.