Welcome to Coconut’s documentation!¶
Coconut is a novel selective disclosure credential scheme supporting distributed threshold issuance, public and private attributes, re-randomization, and multiple unlinkable selective attribute revelations. Coconut integrates with blockchains to ensure confidentiality, authenticity and availability even when a subset of credential issuing authorities are malicious or offline. Coconut uses short and computationally efficient credentials, and our evaluation shows that most Coconut cryptographic primitives take just a few milliseconds on average, with verification taking the longest time (10 milliseconds). We implement and evaluate a generic Coconut smart contract library for Chainspace and Ethereum.
A link to the full paper is available here.
Pre-requisites¶
Coconut is built on top of petlib and bplib, make sure to follow these instructions to install all the pre-requisites.
Install¶
If you have pip installed, you can install Coconut with the following command:
pip install coconut-lib
otherwise, you can build it manually as below:
git clone https://github.com/asonnino/coconut
cd coconut
pip install -e .
Coconut Modules¶
Coconut threshold credentials scheme. Example:
>>> q = 7 # maximum number of attributes
>>> private_m = [10] * 2 # private attributes
>>> public_m = [3] * 1 # public attributes
>>> t, n = 2, 3 # threshold parameter and number of authorities
>>> params = setup(q)
>>> (d, gamma) = elgamal_keygen(params) # El-Gamal keypair
>>> # generate commitment and encryption
>>> Lambda = prepare_blind_sign(params, gamma, private_m, public_m=public_m)
>>> # generate key
>>> (sk, vk) = ttp_keygen(params, t, n)
>>> # aggregate verification keys
>>> aggr_vk = agg_key(params, vk)
>>> # bind sign
>>> sigs_tilde = [blind_sign(params, ski, gamma, Lambda, public_m=public_m) for ski in sk]
>>> # unblind
>>> sigs = [unblind(params, sigma_tilde, d) for sigma_tilde in sigs_tilde]
>>> # aggregate credentials
>>> sigma = agg_cred(params, sigs)
>>> # randomize credentials and generate any cryptographic material to verify them
>>> Theta = prove_cred(params, aggr_vk, sigma, private_m)
>>> # verify credentials
>>> assert verify_cred(params, aggr_vk, Theta, public_m=public_m)
-
setup
(q=1)[source]¶ Generate the public parameters.
- Parameters:
- q (integer): the maximum number of attributes that can be embbed in the credentials
- Returns:
- params: the publc parameters
-
ttp_keygen
(params, t, n)[source]¶ - Generate keys for threshold credentials (executed by a TTP). This protocol can however be executed in a distributed way as illustrated by the following link: https://crysp.uwaterloo.ca/software/DKG/
- Parameters:
- params: public parameters generated by setup
- t (integer): the threshold parameter
- n (integer): the total number of authorities
- Returns:
- sk [(Bn, [Bn])]: array containing the secret key of each authority
- vk [(G2Elem, G2Elem, [G2Elem])]: array containing the verification key of each authority
-
keygen
(params)[source]¶ Generate the secret and verification keys for an authority. This protocol cannot be used for threshold setting.
Parameters: - params: public parameters generated by setup
Returns: - sk (Bn, [Bn]): secret key of the authority - vk (G2Elem, G2Elem, [G2Elem]): verification key of the authority
-
agg_key
(params, vks, threshold=True)[source]¶ Aggregate the verification keys.
- Parameters:
- params: public parameters generated by setup
- vks [(G2Elem, G2Elem, [G2Elem])]: array containing the verification key of each authority
- threshold (bool): optional, whether to use threshold cryptography or not
- Returns:
- aggr_vk: aggregated verification key
-
prepare_blind_sign
(params, gamma, private_m, public_m=[])[source]¶ Build cryptographic material for blind sign.
- Parameters:
- params: public parameters generated by setup
- gamma (G1Elem): the user’s El-Gamal public key
- private_m [Bn]: array containing the private attributes
- public_m [Bn]: optional, array containing the public attributes
- Returns:
- Lambda: commitments and encryptions to the attributes
-
blind_sign
(params, sk, gamma, Lambda, public_m=[])[source]¶ Blindly sign private attributes.
- Parameters:
- params: public parameters generated by setup
- sk (Bn, Bn): the secret key of the authority
- gamma (G1Elem): the user’s El-Gamal public key
- Lambda: commitments and encryptions to the attributes
- public_m [Bn]: optional, array containing the public attributes
- Returns:
- sigma_tilde: blinded credential
-
unblind
(params, sigma_tilde, d)[source]¶ Unblind the credentials.
- Parameters:
- params: public parameters generated by setup
- sigma_tilde: blinded credential
- d: user’s El-Gamal private key
- Returns:
- sigma: unblinded credential
-
agg_cred
(params, sigs, threshold=True)[source]¶ Aggregate partial credentials.
- Parameters:
- params: public parameters generated by setup
- sigs [(G1Elem, G1Elem)]: array of ordered partial credentials, include None if a partial credential is missing (in the threshold setting)
- threshold (bool): optional, whether to use threshold cryptography or not
- Returns:
- aggr_sigma: aggregated credential
-
prove_cred
(params, aggr_vk, sigma, private_m)[source]¶ Build cryptographic material for blind verify.
- Parameters:
- params: public parameters generated by setup
- aggr_vk: aggregated verification key
- sigma: credential
- private_m [Bn]: array containing the private attributes
- Returns:
- Theta: randomized credential and cryptographic material to verify them
-
verify_cred
(params, aggr_vk, Theta, public_m=[])[source]¶ Verify credentials.
- Parameters:
- params: public parameters generated by setup
- aggr_vk: aggregated verification key
- Theta: credential and cryptographic material to verify them
- public_m [Bn]: optional, array containing the public attributes
- Returns:
- ret (bool): whether the credential verifies