CiFEr (prounounced as cipher) is a cryptographic library offering different state-of-the-art implementations of functional encryption schemes, specifically FE schemes for linear polynomials (e.g. inner products). It is implemented in C. A Go version named GoFE of the library also exists.
To quickly get familiar with FE, read a short and very high-level introduction on our Introductory Wiki page.
The documentation for CiFEr is available on GitHub Pages.
CiFEr is distributed under the Apache 2 license. It uses GMP, which is distributed under the dual licenses, GNU LGPL v3 and GNU GPL v2.
Please note that the library is a work in progress and has not yet reached a stable release. Code organization and APIs are not stable. You can expect them to change at any point.
The purpose of CiFEr is to support research and proof-of-concept implementations. It should not be used in production.
The requirements have to be installed manually (via package manager or building the source code).
CiFEr relies on GMP for all big integer arithmetic. We recommend familiarizing yourself with it before using CiFEr.
To be able to build CiFEr as described below, AMCL must be compiled with BN254
curve. This can be done manually, but for convenience, we provide a Bash script
that runs a modified AMCL setup (a Python script) and installs a minimal version
of AMCL in the standard directory /usr/local/lib and header files in
/usr/local/include. These default values can be changed in
external/amcl/setup_amcl.sh. To use the script, run:
cd external/amcl
sudo ./setup_amcl.sh
cd ../..
Alternatively, if you do not like to pollute /usr/local/ with unmanaged
files, you can use a locally compiled AMCL through a submodule:
external/amcl/setup_local_amcl.sh
The above script takes care of compiling AMCL, and places it where cmake can
find it later.
To build and install, first download it, then run the following commands in the source code directory:
mkdir build
cd build
cmake ..
make
sudo make install
This builds the shared library (libcifer.so) and installs it.
By default, it places the shared library in /usr/local/lib and the header
files in /usr/local/include (For this, you will need to run the command as
superuser). To set a custom install directory (e.g. an install directory
in the root of the repo) instead of /usr/local, pass it to the cmake
command, e.g.:
cmake .. -DCMAKE_INSTALL_PREFIX=../install
The build commands also create an executable which runs all unit tests. To make sure the library works as expected, run
make test
Note that this command also builds the library and test executable if they have not been built yet.
We provide a simple Docker build for trying out the library without worrying about the installation and the dependencies. You can build a Docker image yourself by running (possibly with sudo)
docker build . -t fentec/cifer
or downloading it from Docker Hub
docker pull fentec/cifer
In the file example/example.c you will find a dummy code using CiFEr library.
Modify it as you wish and then run
docker run -v $PATHTOCIFER/example:/CiFEr/example fentec/cifer
where $PATHTOCIFER is your absolute path to CiFEr library (something like /home/username/CiFEr).
This will link the example folder in your repository with the one in the Docker image.
Then it will compile example.c code and execute it. See the instructions bellow
on how to use schemes implemented in CiFEr or check out any of the tests implemented
in test folder.
After you have successfuly built and installed the library, you can use it in your project. Instructions below provide a brief introduction to the most important parts of the library, and guide you through a sequence of steps that will quickly get your FE example up and running.
To use the library, you must #include its headers in your source code and
link it with the -lcifer flag when building your code.
You can choose from the following set of schemes:
You will need to include headers from innerprod directory.
We organized implementations in two categories based on their security assumptions:
-
Schemes with selective security under chosen-plaintext attacks (s-IND-CPA security):
- Schemes by Abdalla, Bourse, De Caro, Pointcheval (paper).
The scheme can be instantiated from DDH (
cfe_ddh) and LWE (cfe_lwe). - Experimental Ring-LWE scheme whose security will be argued in a future paper (
cfe_ring_LWE). - Multi-input scheme based on paper by Abdalla, Catalano, Fiore, Gay, Ursu
(paper) and instantiated from
the scheme in the first point (
cfe_ddh_multi).
- Schemes by Abdalla, Bourse, De Caro, Pointcheval (paper).
The scheme can be instantiated from DDH (
-
Schemes with stronger adaptive security under chosen-plaintext attacks (IND-CPA security) or simulation based security (SIM-Security for IPE):
- Scheme based on paper by Agrawal, Libert and Stehlé
(paper). It can be instantiated
from Damgard DDH (
cfe_damgard- similar tocfe_ddh, but uses one more group element to achieve full security, similar to how Damgård's encryption scheme is obtained from ElGamal scheme (paper)), LWE (cfe_lwe_fs) and Paillier (cfe_paillier) primitives. - Multi-input scheme based on paper by Abdalla, Catalano, Fiore, Gay, Ursu
(paper) and instantiated from the
scheme in the first point (
cfe_damgard_multi). - Decentralized scheme based on paper by Chotard, Dufour Sans, Gay, Phan and Pointcheval
(paper). This scheme does not require a trusted
party to generate keys. It is built on pairings (
cfe_dmcfe). - Decentralized scheme based on paper by Abdalla, Benhamouda, Kohlweiss, Waldner
(paper). Similarly as above this scheme
this scheme does not require a trusted party to generate keys and is based on a general
procedure for decentralization of an inner product scheme, in particular the
decentralization of a Damgard DDH scheme (
cfe_damgard_dec_multi). - Function hiding inner product scheme by Kim, Lewi, Mandal, Montgomery, Roy, Wu
(paper). The scheme allows the decryptor to
decrypt the inner product of x and y without reveling (ciphertext) x or (function) y (
cfe_fhipe). - Function hiding multi-input scheme based on paper by Datta, Okamoto, Tomida
(paper). This scheme allows clients to encrypt vectors and derive
functional key that allows a decrytor to decrypt an inner product without revealing the ciphertext or the function (
cfe_fh_multi_ipe).
- Scheme based on paper by Agrawal, Libert and Stehlé
(paper). It can be instantiated
from Damgard DDH (
You will need to include headers from quadratic directory.
It contains an implementation of an efficient FE scheme for quadratic multi-variate polynomials by Sans, Gay and Pointcheval (paper) which is based on bilinear pairings, and offers adaptive security under chosen-plaintext attacks (IND-CPA security).
You will need to include headers from abe directory. There are three implemented
schemes:
-
A ciphertext policy (CP) ABE scheme named FAME by Agrawal and Chase (paper) allowing encrypting a message based on a boolean expression defining a policy which attributes are needed for the decryption. The functions needed in this scheme have prefix
cfe_fame. -
A key policy (KP) ABE scheme by Goyal, Pandey, Sahai, and Waters (paper) allowing a distribution of keys following a boolean expression defining a policy which attributes are needed for the decryption. The functions needed in this scheme have prefix
cfe_gpsw. -
A decentralized inner product predicate scheme by Michalevsky, Joye (paper) allowing encryption with policy described as a vector, and a decentralized distribution of keys based on users' vectors so that only users with vectors orthogonal to the encryption vector posses a key that can decrypt the ciphertext. The functions needed in this scheme have prefix
cfe_dippe.
These schemes allow to specify a decryption policy defining which attributes are needed to be able to decrypt. For the latter we implemented a policy converter which accepts a boolean expression defining the policy and outputs a monotone span program (MSP) which can be used as an input for the ABE schemes.
All CiFEr schemes are implemented as C structs + functions which operate on them with (at least logically) similar APIs. So the first thing we need to do is to create a scheme instance by initializing the appropriate struct. For this step, we need to pass in some configuration, e.g. values of parameters for the selected scheme.
Let's say we selected a cfe_ddh scheme. We create a new scheme instance with:
mpz_t bound;
mpz_init_set_ui(bound, 2 << 14);
cfe_ddh s;
cfe_ddh_init(&s, 3, 128, bound);In the last line above, the first argument is length of input vectors x and y, the second argument is bit length of prime modulus p (because this particular scheme operates in the ℤp group), and the last argument represents the upper bound for elements of input vectors.
However, configuration parameters for different FE schemes vary quite a bit. Please refer to library documentation regarding the meaning of parameters for specific schemes. For now, examples and reasonable defaults can be found in the test code.
After you successfully created a FE scheme instance, you can call the relevant functions for:
- generation of (secret and public) master keys,
- derivation of functional encryption key,
- encryption, and
- decryption.
All CiFEr chemes rely on vectors (or matrices) of big integer (mpz_t)
components.
CiFEr schemes use the library's own vector (cfe_vec) and matrix (cfe_mat)
types. They are available in the data directory. A cfe_vec is basically a
wrapper around an array of mpz_t integers, while a cfe_mat is a wrapper
around an array of cfe_vec vectors.
In general, you only have to worry about providing input data (usually
vectors x and y). Each element in a vector or matrix can be set by
calling their respective _set function, for example:
cfe_vec x, y;
cfe_vec_init(&x, 3);
cfe_vec_init(&y, 3);
mpz_t el;
mpz_init(el);
for (size_t i = 0; i < 3; i++) {
mpz_set_ui(el, i+1);
cfe_vec_set(&x, el, i);
cfe_vec_set(&y, el, 2-i);
}
// x is [1, 2, 3], y is [3, 2, 1]For matrices, you can set whole rows to contain the same values as a vector.
cfe_mat A;
cfe_mat_init(&A, 2, 3);
cfe_mat_set_vec(&A, &x, 0);
cfe_mat_set_vec(&A, &y, 1);
// A is [[1, 2, 3], [3, 2, 1]]To generate random mpz_t values from different probability distributions,
you can use one of our several implementations of random samplers. The samplers
are provided in the sample directory. Note that the uniform sampler does not
require special initialization while other samplers do. Before performing any
random sampling, the function cfe_init needs to be called to ensure that the
system's random number generator has been properly seeded.
You can quickly construct random vectors and matrices by:
- Configuring the sampler of your choice, for example:
cfe_init(); mpf_t sigma; mpf_init_set_ui(sigma, 10); cfe_normal_cumulative s; // samples the cumulative normal (Gaussian) probability distribution, centered on 0 cfe_normal_cumulative_init(&s, sigma, 256, true);
- Providing the data structure and sampler as an argument to the relevant
_sample_vecor_sample_matfunctions.cfe_vec v; cfe_mat m; cfe_vec_init(&v, 5); cfe_mat_init(&m, 2, 3); cfe_normal_cumulative_sample_vec(&v, &s); // sets all elements of the vector to random elements cfe_normal_cumulative_sample_mat(&m, &s); // sets all elements of the matrix to random elements // Uniform sampler (does not need to be initialized) mpz_t max; mpz_init_set_ui(max, 10); cfe_uniform_sample_vec(&v, max);
In the following we give some examples how to use the schemes. Note that every
scheme has an implemented test in the folder test, in which you can see how
to use the scheme and modify it to your needs.
Please remember that all the examples below omit error handling. All functions
which can fail return a cfe_error (its definition is in errors.h header,
located in the internal directory) which is non-zero if the function
encountered an error.
Additionally, all examples also omit memory freeing. In CiFEr, all functions
which allocate memory for their results (passed as input parameters) have the
suffix _init and have a corresponding function with the suffix _free.
All other functions expect their inputs to be already initialized and do not
allocate any memory the user would need to free manually.
The example below demonstrates how to use single input scheme instances.
Although the example shows how to use the cfe_ddh scheme from directory
simple, the usage is similar for all single input schemes, regardless
of their security properties (s-IND-CPA or IND-CPA) and instantiation
(DDH or LWE).
You will see that three cfe_ddh structs are instantiated to simulate the
real-world scenarios where each of the three entities involved in FE
are on separate machines.
// Instantiation of a trusted entity that
// will generate master keys and FE key
size_t l = 2; // length of input vectors
mpz_t bound, fe_key, xy, el;
mpz_inits(bound, fe_key, xy, el, NULL);
mpz_set_ui(bound, 10); // upper bound for input vector coordinates
modulus_len = 1024; // bit length of prime modulus p
cfe_ddh s, encryptor, decryptor;
cfe_ddh_init(&s, l, modulus_len, bound);
cfe_vec msk, mpk, ciphertext, x, y;
cfe_ddh_master_keys_init(&msk, &mpk, &s);
cfe_ddh_generate_master_keys(&msk, &mpk, &s);
cfe_vec_init(&y, 2);
mpz_set_ui(el, 1);
cfe_vec_set(&y, el, 0);
mpz_set_ui(el, 2);
cfe_vec_set(&y, el, 1); // y is [1, 2]
cfe_ddh_derive_fe_key(fe_key, &s, &msk, &y);
// Simulate instantiation of encryptor
// Encryptor wants to hide x and should be given
// master public key by the trusted entity
cfe_vec_init(&x, 2);
mpz_set_ui(el, 3);
cfe_vec_set(&x, el, 0);
mpz_set_ui(el, 4);
cfe_vec_set(&x, el, 1); // x is [3, 4]
cfe_ddh_copy(&encryptor, &s);
cfe_ddh_ciphertext_init(&ciphertext, &encryptor);
cfe_ddh_encrypt(&ciphertext, &encryptor, &x, &mpk);
// Simulate instantiation of decryptor that decrypts the cipher
// generated by encryptor.
cfe_ddh_copy(&decryptor, &s);
// decrypt to obtain the result: inner prod of x and y
// we expect xy to be 11 (e.g. <[1,2],[3,4]>)
cfe_ddh_decrypt(xy, &decryptor, &ciphertext, fe_key, &y);This example demonstrates how multi input FE schemes can be used.
Here we assume that there are numClients encryptors (ei), each with
their corresponding input vector xi. A trusted entity generates all
the master keys needed for encryption and distributes appropriate keys to
appropriate encryptor. Then, encryptor ei uses their keys to encrypt
their data xi. The decryptor collects ciphers from all the
encryptors. It then relies on the trusted entity to derive a decryption key
based on its own set of vectors yi. With the derived key, the
decryptor is able to compute the result - inner product over all vectors, as
Σ <xi,yi>.
size_t numClients = 2; // number of encryptors
size_t l = 3; // length of input vectors
mpz_t bound, prod;
mpz_init(prod);
mpz_init_set_ui(bound, 1000); // upper bound for input vectors
// Simulate collection of input data.
// X and Y represent matrices of input vectors, where X are collected
// from numClients encryptors (ommitted), and Y is only known by a single decryptor.
// Encryptor i only knows its own input vector X[i].
cfe_mat X, Y;
cfe_mat_inits(numClients, l, &X, &Y, NULL);
cfe_uniform_sample_mat(&X, bound);
cfe_uniform_sample_mat(&Y, bound);
// Trusted entity instantiates scheme instance and generates
// master keys for all the encryptors. It also derives the FE
// key derivedKey for the decryptor.
size_t modulus_len = 1024;
cfe_ddh_multi m, decryptor;
cfe_ddh_multi_init(&m, numClients, l, modulus_len, bound);
cfe_mat mpk;
cfe_ddh_multi_sec_key msk;
cfe_ddh_multi_master_keys_init(&mpk, &msk, &m);
cfe_ddh_multi_generate_master_keys(&mpk, &msk, &m);
cfe_ddh_multi_fe_key fe_key;
cfe_ddh_multi_fe_key_init(&fe_key, &m);
cfe_ddh_multi_derive_fe_key(&fe_key, &m, &msk, &Y);
// Different encryptors may reside on different machines.
// We simulate this with the for loop below, where numClients
// encryptors are generated.
cfe_ddh_multi_enc encryptors[numClients];
for (size_t i = 0; i < numClients; i++) {
cfe_ddh_multi_enc_init(&encryptors[i], &m);
}
// Each encryptor encrypts its own input vector X[i] with the
// keys given to it by the trusted entity.
cfe_mat ciphertext;
cfe_mat_init(&ciphertext, numClients, l + 1);
for (size_t i = 0; i < numClients; i++) {
cfe_vec ct;
cfe_vec *pub_key = cfe_mat_get_row_ptr(&mpk, i);
cfe_vec *otp = cfe_mat_get_row_ptr(&msk.otp_key, i);
cfe_vec *x_vec = cfe_mat_get_row_ptr(&X, i);
cfe_ddh_multi_ciphertext_init(&ct, &encryptors[i]);
cfe_ddh_multi_encrypt(&ct, &encryptors[i], x_vec, pub_key, otp);
cfe_mat_set_vec(&ciphertext, &ct, i);
cfe_vec_free(&ct);
}
// Ciphers are collected by decryptor, who then computes
// inner product over vectors from all encryptors.
cfe_ddh_multi_copy(&decryptor, &m);
cfe_ddh_multi_decrypt(prod, &decryptor, &ciphertext, &fe_key, &Y);Note that above we instantiate multiple encryptors - in reality, different encryptors will be instantiated on different machines.
In the example below, we omit instantiation of different entities (encryptor and decryptor).
// set the parameters
size_t l = 5;
mpz_t b;
mpz_set_si(b, 8);
// create a scheme
cfe_sgp s;
err = cfe_sgp_init(&s, l, b);
// create a master secret key
cfe_sgp_sec_key msk;
cfe_sgp_sec_key_init(&msk, &s);
cfe_sgp_generate_sec_key(&msk, &s);
// take random vectors x, y
cfe_vec x, y;
cfe_vec_inits(s.l, &x, &y, NULL);
cfe_uniform_sample_vec(&x, b);
cfe_uniform_sample_vec(&y, b);
// encrypt the vectors
cfe_sgp_cipher cipher;
cfe_sgp_cipher_init(&cipher, &s);
cfe_sgp_encrypt(&cipher, &s, &x, &y, &msk);
// derive keys and decrypt the value x*m*y for a
// random matrix m
cfe_mat m;
cfe_mat_init(&m, l, l);
cfe_uniform_sample_mat(&m, b);
ECP2_BN254 key;
cfe_sgp_derive_fe_key(&key, &s, &msk, &m);
mpz_t dec;
mpz_init(dec);
cfe_sgp_decrypt(dec, &s, &cipher, &key, &m);In the example below we demonstrate a usage of ABE scheme FAME. We omit instantiation of different entities (encryptor and decryptor). We want to encrypt the following message msg so that only those who own the attributes satisfying a boolean expression 'policy' can decrypt.
// create a new FAME struct
cfe_fame fame;
cfe_fame_init(&fame);
// initialize and generate a public key and a secret key for the scheme
cfe_fame_pub_key pk;
cfe_fame_sec_key sk;
cfe_fame_sec_key_init(&sk);
cfe_fame_generate_master_keys(&pk, &sk, &fame);
// create a message to be encrypted
FP12_BN254 msg;
FP12_BN254_one(&msg);
// create a msp structure out of a boolean expression representing the
// policy specifying which attributes are needed to decrypt the ciphertext
char bool_exp[] = "(5 OR 3) AND ((2 OR 4) OR (1 AND 6))";
cfe_msp msp;
cfe_boolean_to_msp(&msp, bool_exp, false);
// initialize a ciphertext and encrypt the message based on the msp structure
// describing the policy
cfe_fame_cipher cipher;
cfe_fame_cipher_init(&cipher, &msp);
cfe_fame_encrypt(&cipher, &msg, &msp, &pk, &fame);
// produce keys that are given to an entity with a set
// of attributes in owned_attrib
int owned_attrib[] = {1, 3, 6};
cfe_fame_attrib_keys keys;
cfe_fame_attrib_keys_init(&keys, 3); // the number of attributes needs to be specified
cfe_fame_generate_attrib_keys(&keys, owned_attrib, 3, &sk, &fame);
// decrypt the message with owned keys
FP12_BN254 decryption;
cfe_fame_decrypt(&decryption, &cipher, &keys, &fame);