Core API¶
zksk.expr
– DL Expressions¶
Tiny expression language suitable for expressing statements on discrete logarithm representations
>>> from petlib.ec import EcGroup
>>> group = EcGroup()
>>> g = group.hash_to_point(b"1")
>>> h = group.hash_to_point(b"2")
>>> a = Secret()
>>> b = Secret()
>>> expr = a * g + b * h

class
zksk.expr.
Expression
(secret, base)¶ Arithmetic expression of secrets and group elements.
It is an abstraction for \(x_0 g_0 + x_1 g_2 + ... + x_n g_n\), where \(x_i\)s are declared secrets.
Implementationwise, parses the sum into an ordered list of Secrets and an ordered list of generators.
 Parameters
secret (Secret) – Secret object.
base – Base point on an elliptic curve.

__add__
(other)¶ Merge Expression objects along addition.
 Parameters
other (Expression) – Another expression
 Returns
New expression
 Return type

eval
()¶ Evaluate the expression, if all secret values are available.

class
zksk.expr.
Secret
(value=None, name=None)¶ A secret value in a zeroknowledge proof.
 Args
name: String to enforce as name of the Secret. Useful for debugging. value: Optional secret value.

__eq__
(other)¶ Return self==value.

__hash__
()¶ Return hash(self).

__mul__
(base)¶ Construct an expression that represents this secrets multiplied by the base.
 Parameters
base – Base point on an elliptic curve.
 Returns
Expression that corresponds to \(x G\)
 Return type

__rmul__
(base)¶ Construct an expression that represents this secrets multiplied by the base.
 Parameters
base – Base point on an elliptic curve.
 Returns
Expression that corresponds to \(x G\)
 Return type

zksk.expr.
update_secret_values
(secrets_dict)¶ Update values of secrets according to the given mapping.
>>> x, y = Secret(), Secret() >>> secrets_dict = {x: 1, y: 2} >>> update_secret_values(secrets_dict) >>> x.value 1 >>> y.value 2
 Parameters
secrets_dict – A mapping from
Secret
objects to their expected values.

zksk.expr.
wsum_secrets
(secrets, bases)¶ Build expression representing a dot product of given secrets and bases.
>>> from zksk.utils import make_generators >>> x, y = Secret(), Secret() >>> g, h = make_generators(2) >>> expr = wsum_secrets([x, y], [g, h]) >>> expr.bases == (g, h) True >>> expr.secrets == (x, y) True
 Parameters
secrets –
Secret
objects :math`x_i`bases – Elliptic curve points \(G_i\)
 Returns
Expression that corresponds to \(x_0 G_0 + x_1 G_1 + ... + x_n G_n\)
 Return type
zksk.base
– Base Classes¶
Common clases, including subclassable basic provers and verifiers.

class
zksk.base.
NIZK
(challenge, responses, precommitment=None, stmt_hash=None)¶ Noninteractive zeroknowledge proof.

classmethod
deserialize
(nizk_raw)¶ Deserialize a noninteractive zeroknowledge proof.

serialize
()¶ Serialize a noninteractive zeroknowledge proof.

classmethod

class
zksk.base.
Prover
(stmt, secret_values)¶ Abstract interface representing Prover used in sigma protocols.
 Parameters
stmt – The Proof instance from which we draw the Prover.
secret_values – The values of the secrets as a dict.

commit
(randomizers_dict=None)¶ Constuct the proof commitment.
 Parameters
randomizers_dict – Optional dictionary of random values. Each random values is assigned to a secret.

abstract
compute_response
(challenge)¶ Computes the responses associated to each Secret object in the statement.
Returns a list of responses.

get_nizk_proof
(message='')¶ Construct a noninteractive proof transcript using FiatShamir heuristic.
The transcript contains only the challenge and the responses, as the commitment can be deterministically recomputed.
The challenge is a hash of the commitment, the stmt statement and all the bases in the statement (including the lefthandside).
 Parameters
message (str) – Optional message to make a signature stmt of knowledge.

precommit
()¶ Generate a precommitment.

class
zksk.base.
SimulationTranscript
(commitment, challenge, responses, precommitment=None, stmt_hash=None)¶ Simulated proof transcript.

class
zksk.base.
Verifier
(stmt)¶ An abstract interface representing Prover used in sigma protocols

abstract
check_responses_consistency
(response, response_dict=None)¶ Verify that for two identical secrets, the responses are also the same.

process_precommitment
(precommitment)¶ Receive a precommitment and process it.

send_challenge
(commitment)¶ Store the received commitment and generate a challenge.
The challenge is chosen at random between 0 and
CHALLENGE_LENGTH
(excluded). Parameters
commitment – A tuple containing a hash of the stmt statement, to be compared against the local statement, and the commmitment as a (potentially multilevel list of) base(s) of the group.

verify
(response, *args, **kwargs)¶ Verify the responses of an interactive sigma protocol.
To do so, generates a pseudocommitment based on the stored challenge and the received responses, and compares it against the stored commitment.
 Parameters
response – The response given by the prover
 Returns
True if verification succeeded, False otherwise.
 Return type
bool

verify_nizk
(nizk, message='', *args, **kwargs)¶ Verify a noninteractive proof.
Unpacks the attributes and checks their consistency by computing a pseudocommitment and drawing from a pseudochallenge. Compares the pseudochallenge with the nizk challenge.
 Parameters
nizk (
NIZK
) – Noninteractive proofmessage – A message if a signature proof.
 Returns
True of verification succeeded, False otherwise.
 Return type
bool

abstract

zksk.base.
build_fiat_shamir_challenge
(stmt_prehash, *args, message='')¶ Generate a FiatShamir challenge.
>>> prehash = sha256(b"statement id") >>> commitment = 42 * EcGroup().generator() >>> isinstance(build_fiat_shamir_challenge(prehash, commitment), Bn) True
 Parameters
prehash – Hash object seeded with the proof statement ID.
args – Items to hash (e.g., commitments)
message – Message to make it a signature PK.
zksk.composition
– Compositions¶
Composable proof statements, provers, and verifiers.

class
zksk.composition.
AndProofStmt
(*subproofs)¶ 
get_prover
(secrets_dict=None)¶ Get the
base.Prover
for the current proof.

get_randomizers
()¶ Create a dictionary of randomizers by querying the subproofs’ maps and merging them.

get_verifier
()¶ Constructs a Verifier for the andproof, based on a list of the Verifiers of each subproof.

prepare_simulate_proof
()¶ Additional steps to prepare before simulating the proof. Override if needed.

recompute_commitment
(challenge, responses)¶ Compute a pseudocommitment.
A pseudocommitment is the commitment a verifier should have received if the proof was correct. It should be compared to the actual commitment.
Reoccuring secrets yield identical responses.
 Parameters
challenge – the challenge used in the proof
response – a list of responses, ordered as the list of secret names, i.e., with as many elements as there are secrets in the proof claim.

simulate_proof
(responses_dict=None, challenge=None)¶ Simulate the And proof
To do so, draw a global challenge, a global dictionary of responses (for consistency) and simulate each subproof.
Gathers the commitments, and pack everything into a
base.SimulationTranscript
. Parameters
responses_dict – A dictionary of responses to override (could come from an upper And Proof, for example). Draw randomly if None.
challenge – The challenge to use in the proof. Draw one if None.

validate_composition
(*args, **kwargs)¶ Validate that composition is done correctly.

validate_secrets_reoccurence
(forbidden_secrets=None)¶ Check reoccuring secrets both inside and outside an orproof.
This method gets the list of all secrets in the tree and triggers a depthfirst search for orproofs
 Parameters
forbidden_secrets – A list of all the secrets in the mother proof.
 Raises
exceptions.InvalidSecretsError – If any secrets reoccur in an unsupported way.


class
zksk.composition.
AndProver
(proof, subprovers)¶ 
compute_response
(challenge)¶ Return a list of responses of each subprover.

internal_commit
(randomizers_dict=None)¶ Compute the internal commitment.
 Parameters
randomizers_dict – Mapping from secrets to randomizers.

precommit
()¶ Computes the precommitment for an andproof.
This precommitment is the list of precommitments of the subprovers.
If not applicable (no subprover outputs a precommitment), returns None.


class
zksk.composition.
AndVerifier
(proof, subverifiers)¶ 
check_responses_consistency
(responses, responses_dict=None)¶ Check that the responses are consistent for reoccurring secret names.
Iterates through the subverifiers, gives them the responses related to them and constructs a response dictionary. If an inconsistency if found during this build, returns False.
 Parameters
responses – Rreceived list of responses for each subproof.
responses_dict – Dictionary to construct and use for comparison.

process_precommitment
(precommitment)¶ Distribute the list of precommitments to the subverifiers.

send_challenge
(commitment, ignore_statement_hash_checks=False)¶ Store the received commitment and generate a challenge.
Additionally checks the received hashed statement matches the one of the current proof. Only called at the highest level or in extended proofs.
 Parameters
commitment – A tuple (statement, actual_commitment) with actual_commitment a list of commitments, one for each subproof.
ignore_statement_hash_checks – Optional parameter to deactivate the statement check. In this case, the commitment parameter is simply the actual commitment. Useful in 2level proofs for which we don’t check the inner statements.


class
zksk.composition.
ComposableProofStmt
¶ A composable sigmaprotocol proof statement.
In the composed proof tree, these objects are the atoms/leafs.

__and__
(other)¶ Make a conjuction of proof statements using
AndProofStmt
.If called multiple times, subproofs are flattened so that only one
AndProofStmt
remains at the root.

__or__
(other)¶ Make a disjunction of proof statements using
OrProofStmt
.If called multiple times, subproofs are flattened so that only one
OrProofStmt
remains at the root.

check_statement
(statement_hash)¶ Verify the current proof corresponds to the hash passed as a parameter.
Returns a prehash of the current proof, e.g., to be used to verify NIZK proofs.

full_validate
(*args, **kwargs)¶ For or/andproofs, perform recursive validation of subproofs.

get_bases
()¶ Collect all base points in this subtree.
By default tries to get the
bases
attribute. Override if needed.

get_proof_id
(secret_id_map=None)¶ Identifier for the proof statement.
This identifier is used to check the proof statements on the prover and verifier sides are consistent, and to generate a challenge in noninteractive proofs.
 Parameters
secret_id_map – A map from secret names to consecutive identifiers.
 Returns
Objects that can be used for hashing.
 Return type
list

get_prover
(secrets_dict=None)¶ Get the
base.Prover
for the current proof.

get_secret_vars
()¶ Collect all secrets in this subtree.
By default tries to get the
secret_vars
attribute. Override if needed.

get_verifier
()¶ Return the
base.Verifier
for the current proof.

prehash_statement
()¶ Return a hash of the proof’s ID.

prepare_simulate_proof
()¶ Additional steps to prepare before simulating the proof. Override if needed.

prove
(secret_dict=None, message='')¶ Generate the transcript of a noninteractive proof.

recompute_commitment
(challenge, response)¶ Compute a pseudocommitment.
A pseudocommitment is the commitment a verifier should have received if the proof was correct. It should be compared to the actual commitment.
Reoccuring secrets yield identical responses.
 Parameters
challenge – the challenge used in the proof
response – a list of responses, ordered as the list of secret names, i.e., with as many elements as there are secrets in the proof claim.

set_simulated
(value=True)¶ Designate this proof statement as simulated in an orproof.
 Parameters
value (bool) – Whether to simulate this proof.

simulate
(challenge=None)¶ Generate the transcript of a simulated noninteractive proof.

property
simulated
¶ Tell if this proof is designated as to be simulated in an orproof.
By default is False.

update_randomizers
(randomizers_dict)¶ Construct a mapping of all secrets to randomizers.
Does so by copying the values of the passed
randomizers_dict
, and drawing the other values at random until all the secrets have a randomizer.These are used as a part of proofs and also as responses in simulations.
 Parameters
randomizers_dict – A dictionary to enforce

validate
(*args, **kwargs)¶ Validation criteria to be checked. Override if needed.
For example, a
primitives.DLNotEqual
statement should not validate if its proof components are in fact equal.Should raise an exceptions.ValidationError if does not validate.

validate_secrets_reoccurence
(forbidden_secrets=None)¶ Check if a secret appears both inside an outside an orproof.
Does nothing if not overriden.

verify
(nizk, message='')¶ Verify a noninteractive proof.

verify_simulation_consistency
(transcript)¶ Check if the fields of a transcript satisfy the verification equation.
Useful for debugging purposes.
Warning
This is NOT an alternative to the full proof verification, as this function accepts simulated proofs.


class
zksk.composition.
OrProofStmt
(*subproofs)¶ An disjunction of several subproofs.
 Parameters
suproofs – Proof statements.
 Raise:
ValueError: If less than two subproofs given.

get_prover
(secrets_dict=None)¶ Get the
base.Prover
for the current proof.

get_verifier
()¶ Return the
base.Verifier
for the current proof.

prepare_simulate_proof
()¶ Additional steps to prepare before simulating the proof. Override if needed.

recompute_commitment
(challenge, responses)¶ Compute a pseudocommitment.
A pseudocommitment is the commitment a verifier should have received if the proof was correct. It should be compared to the actual commitment.
Reoccuring secrets yield identical responses.
 Parameters
challenge – the challenge used in the proof
response – a list of responses, ordered as the list of secret names, i.e., with as many elements as there are secrets in the proof claim.

validate_composition
()¶ Validate that composition is done correctly.

validate_secrets_reoccurence
(forbidden_secrets=None)¶ Check for reoccurence of secrets both inside and outside an orproof.
Method is called from
AndProofStmt.validate_secrets_reoccurence()
. Parameters
forbidden_secrets – A list of all the secrets in the mother proof.
 Raises
exceptions.InvalidSecretsError – If any secrets reoccur in an unsupported way.

class
zksk.composition.
OrProver
(stmt, subprover)¶ Prover for the orproof.
This prover is built with only one subprover, and needs to have access to the index of the corresponding subproof in its mother proof. Runs all the simulations for the other proofs and stores them.

compute_response
(challenge)¶ Compute complementary challenges and responses.
Computes the complementary challenge with respect to the received global challenge and the list of challenges used in the stored simulations. Computes the responses of the subprover using this auxiliary challenge, gathers the responses from the stored simulations. Returns both the complete list of subchallenges (including the auxiliary challenge) and the list of responses, both ordered.
 Parameters
challenge – The global challenge to use. All subchallenges must add to this one.

internal_commit
(randomizers_dict=None)¶ Gather the commitments from the stored simulations.
 Parameters
randomizers_dict – A dictionary of randomizers to use for responses consistency. Not used in this proof. Parameter kept so all internal_commit methods have the same prototype.

precommit
()¶ Generate a precommitment.

setup_simulations
()¶ Run all the required simulations and stores them.


class
zksk.composition.
OrVerifier
(stmt, subverifiers)¶ Verifier for the orproof.
The verifier is built on a list of subverifiers, which will unpack the received attributes.

check_responses_consistency
(responses, responses_dict=None)¶ Checks that for a same secret, response are actually the same.
Since every member is run with its own challenge, it is enough that one member is consistent within itself.
 Parameters
responses – a tuple (subchallenges, actual_responses) from which we extract only the actual responses for each subverifier.

process_precommitment
(precommitment)¶ Reads the received list of precommitments (or None if non applicable) and distributes them to the subverifiers so they can finalize their proof construction if necessary.
 Parameters
precommitment – A list of all required precommitments, ordered.

zksk.extended
– Extended Proofs¶
Extended proofs are proofs that deal with internal precommitments.
This is a convenient building block that is useful for defining complex primitives.
Precommitments are parameters that are not known at the proof instantiation time and are computed by the proving side. Therefore, they have to be sent explicitly in a preliminary round for interactive protocols, and as an additional attribute in noninteractive or simulated transcripts.
The protocol of an extended proof is as follows:
A proof statement (
ExtendedProofStmt
) is instantiated and its attributes are set, but cannot run most methods.Upon processing of the precommitment (
ExtendedProofProver.process_precommitment()
), a separate and complete regular proof statement (zksk.base.ComposableProofStmt
) is constructed inside the extended proof (:py:attr`ExtendedProofStmt.constructed_stmt`)ExtendedProofStmt.get_bases()
,ExtendedProofStmt.get_secret_vars()
delegate to the internalconstructed_stmt
. TheExtendedProver
andExtendedVerifier
work in the same way, embedding aconstructed_prover
(resp.,constructed_verifier
).

class
zksk.extended.
ExtendedProofStmt
¶ Proof that deals with precommitments.

abstract
construct_stmt
()¶ Build internal proof statement for this class
This function must be overridden. The function should return a constructed proof statement. It can use the values that were computed by internal_precommit to do so.

full_validate
(*args, **kwargs)¶ For or/andproofs, perform recursive validation of subproofs.

get_bases
()¶ Collect all base points in this subtree.
By default tries to get the
bases
attribute. Override if needed.

get_proof_id
(secret_id_map=None)¶ Identifier for the proof statement.

get_prover
(secrets_dict=None)¶ Get a prover object.
 Returns
Prover object if all secret values are known, None otherwise.

get_secret_vars
()¶ Collect all secrets in this subtree.
By default tries to get the
secret_vars
attribute. Override if needed.

precommit
()¶ Compute precommitments. Override if needed.
Override this function to compute precommitments and set corresponding secrets that must be computed before the ZK proof itself can be constructed and proven.
 Returns
Precommitment

prepare_simulate_proof
()¶ Additional steps to prepare before simulating the proof. Override if needed.

recompute_commitment
(challenge, responses)¶ Compute a pseudocommitment.
A pseudocommitment is the commitment a verifier should have received if the proof was correct. It should be compared to the actual commitment.
Reoccuring secrets yield identical responses.
 Parameters
challenge – the challenge used in the proof
response – a list of responses, ordered as the list of secret names, i.e., with as many elements as there are secrets in the proof claim.

simulate_precommit
()¶ Simulate a precommitment. Override if needed.
Override this method to enable using this proof in orproofs.
It should compute the same output as generated by precommit, but without relying on any secrets.

simulate_proof
(responses_dict=None, challenge=None)¶ Simulate the proof.
 Parameters
responses_dict – Mapping from secrets to responses
challenge – Challenge

validate
(precommitment, *args, **kwargs)¶ Validate proof’s construction. Override if needed.

abstract

class
zksk.extended.
ExtendedProver
(stmt, secret_values)¶ Prover dealing with precommitments.
This prover will create a constructed Prover object and delegate to its methods.

compute_response
(challenge)¶ Wrap the response computation for the inner proof.

internal_commit
(randomizers_dict=None)¶ Trigger the internal prover commit.
Transfers the randomizer_dict if passed. It might be used if the binding of the proof is set True.

precommit
()¶ Generate a precommitment.

process_precommitment
()¶ Trigger the innerproof construction and extract a prover given the secrets.


class
zksk.extended.
ExtendedVerifier
(stmt)¶ Verifier that deals with precommitments.

check_responses_consistency
(responses, responses_dict)¶ Wrap the consistency check of the innter proof.

process_precommitment
(precommitment)¶ Receive the precommitment and trigger the innerverifier construction.

send_challenge
(com)¶ Transfer the commitment to the inner proof, and compute the challenge.

zksk.pairings
– Pairings¶
Wrapper around bplib
points that ensures additive notation for all points.

class
zksk.pairings.
AdditivePoint
(pt, bp)¶ A wrapper for GT points that uses additive notation.
 Parameters
pt (
bplib.bp.GTElem
) – Wrapped point.bp (
BilinearGroupPair
) – Group pair.

__add__
(other)¶ Replace the multiplicative syntax between two points by an additive one.

__eq__
(other)¶ Return self==value.

__mul__
(nb)¶ Overrides the multiplicative syntax by an additive one.
Special case in 0 as the underlying
bplib
function is broken for this value.

__rmul__
(nb)¶ Overrides the multiplicative syntax by an additive one.
Special case in 0 as the underlying
bplib
function is broken for this value.

class
zksk.pairings.
BilinearGroupPair
(bp_group=None)¶ A bilinear group pair.
Contains two origin groups G1, G2 and the image group GT. The underlying
bplib.bp.BpGroup
object is also embedded.
groups
()¶ Returns the three groups in the following order : G1, G2, GT.


class
zksk.pairings.
G1Group
(bp)¶ Wrapper for G1 that behaves like normal
petlib.ec.EcGroup
. Parameters
bp (
BilinearGroupPair
) – Group pair.

__eq__
(other)¶ Return self==value.

class
zksk.pairings.
G1Point
(pt, bp)¶ Wrapper for G1 points so they can be paired with a G2 point.
 Parameters
pt (
bplib.bp.G1Point
) – Point.bp (
BilinearGroupPair
) – Group pair.

__eq__
(other)¶ Return self==value.

class
zksk.pairings.
G2Group
(bp)¶ Wrapper for the G2 group.
 Parameters
bp (
BilinearGroupPair
) – Group pair.

class
zksk.pairings.
G2Point
(pt, bp)¶ Wrapper for G2 points.
 Parameters
pt (
bplib.bp.G2Point
) – Point.bp (
BilinearGroupPair
) – Group pair.

__eq__
(other)¶ Return self==value.

class
zksk.pairings.
GTGroup
(bp)¶ Wrapper for the GT group with additive points.
Allows to retrieve groups G1 and G2.
The group ID is set to 0 to allow comparisons between groups of different types to raise an explicit Exception.
 Parameters
bp (
BilinearGroupPair
) – Group pair.

zksk.pairings.
pt_dec
(bptype, xtype)¶ Decoder for the wrapped points.

zksk.pairings.
pt_enc
(obj)¶ Encoder for the wrapped points.
zksk.exceptions
– Builtin Exceptions¶
Common exception classes.

exception
zksk.exceptions.
GroupMismatchError
¶ Generator groups mismatch.

exception
zksk.exceptions.
IncompleteValuesError
¶ Cannot evaluate a proof as not all secret values are set.

exception
zksk.exceptions.
InconsistentChallengeError
¶ Recomputed and global challenge values do not match.

exception
zksk.exceptions.
InvalidExpression
¶

exception
zksk.exceptions.
InvalidSecretsError
¶ Secrets reoccur in an unsupported manner.

exception
zksk.exceptions.
StatementMismatch
¶ Proof statements mismatch, impossible to verify.

exception
zksk.exceptions.
StatementSpecError
¶ Statement not fully specified.

exception
zksk.exceptions.
ValidationError
¶ Error during validation.

exception
zksk.exceptions.
VerificationError
¶ Error during verification.
zksk.utils
– Utilities¶
zksk.utils.groups
– Utils for Elliptic Curves and Big Numbers¶

zksk.utils.groups.
ensure_bn
(x)¶ Ensure that value is big number.
>>> isinstance(ensure_bn(42), Bn) True >>> isinstance(ensure_bn(Bn(42)), Bn) True

zksk.utils.groups.
get_random_num
(bits)¶ Draw a random number of given bitlength.
>>> x = get_random_num(6) >>> x < 2**6 True

zksk.utils.groups.
get_random_point
(group=None, random_bits=256, seed=None)¶ Generate some random group generators.
 Parameters
num – Number of generators to generate.
group – Group
random_bits – Number of bits of a random string to create a point.
>>> from petlib.ec import EcPt >>> a = get_random_point() >>> b = get_random_point() >>> isinstance(a, EcPt) True >>> isinstance(b, EcPt) True >>> a != b True >>> get_random_point(seed=1) EcPt(037697679766c26bb7b76c65d2639fb983dea7c859c63b3047168dbc1b)

zksk.utils.groups.
make_generators
(num, group=None, random_bits=256, seed=42)¶ Create some random group generators.
Warning
There is a negligible chance that some generators will be the same.
 Parameters
num – Number of generators to generate.
group – Group
random_bits – Number of bits of a random number used to create a generator.
>>> from petlib.ec import EcPt >>> generators = make_generators(3) >>> len(generators) == 3 True >>> isinstance(generators[0], EcPt) True

zksk.utils.groups.
sum_bn_array
(arr, modulus)¶ Sum an array of big numbers under a modulus.
>>> a = [Bn(5), Bn(7)] >>> m = 10 >>> sum_bn_array(a, m) 2
zksk.utils.misc
– Miscellany¶

zksk.utils.misc.
get_default_attr
(obj, attr, default_value=None)¶ Get attribute by name. If does not exist, set it.
>>> class Klass: pass >>> a = Klass() >>> hasattr(a, "answer") False >>> get_default_attr(a, "answer", 42) 42 >>> a.answer 42