The threshold Paillier scheme offers the same properties as the Paillier scheme, with the extra security that decryption is split performed between a number of parties instead of just a single trusted party. More...

#include <gmp.h>
#include "hcs_random.h"
#include "hcs_shares.h"

Include dependency graph for pcs_t.h:

Go to the source code of this file.

Data Structures
struct	pcs_t_proof
	Stores data pertaining to the usage of proof computation and verification. More...

struct	pcs_t_polynomial
	Details of the polynomial used to compute values for decryption servers. More...

struct	pcs_t_auth_server
	Details that a decryption server is required to keep track of. More...

struct	pcs_t_public_key
	Public key for use in the Threshold Paillier system. More...

struct	pcs_t_private_key
	Private key for use in the Threshold Paillier system. More...

Functions
pcs_t_public_key *	pcs_t_init_public_key (void)
	Initialise a pcs_t_public_key and return a pointer to the newly created structure. More...

pcs_t_private_key *	pcs_t_init_private_key (void)
	Initialise a pcs_t_private_key and return a pointer to the newly created structure. More...

int	pcs_t_generate_key_pair (pcs_t_public_key pk, pcs_t_private_key vk, hcs_random *hr, const unsigned long bits, const unsigned long l, const unsigned long w)
	Initialise a key pair with modulus size `bits`. More...

void	pcs_t_encrypt_r (pcs_t_public_key *pk, mpz_t rop, mpz_t r, mpz_t plain1)
	Encrypt a value `plain1`, and set `rop` to the encryted result. More...

void	pcs_t_r_encrypt (pcs_t_public_key pk, hcs_random hr, mpz_t r, mpz_t rop, mpz_t plain1)
	Encrypt a value `plain1`, and set `rop` to the encrypted result. More...

void	pcs_t_encrypt (pcs_t_public_key pk, hcs_random hr, mpz_t rop, mpz_t plain1)
	Encrypt a value `plain1`, and set `rop` to the encrypted result. More...

void	pcs_t_reencrypt (pcs_t_public_key pk, hcs_random hr, mpz_t rop, mpz_t op)
	Reencrypt an encrypted value `cipher1`. More...

void	pcs_t_ep_add (pcs_t_public_key *pk, mpz_t rop, mpz_t cipher1, mpz_t plain1)
	Add a plaintext value `plain1` to an encrypted value `cipher1`, storing the result in `rop`. More...

void	pcs_t_ee_add (pcs_t_public_key *pk, mpz_t rop, mpz_t cipher1, mpz_t cipher2)
	Add an encrypted value `cipher2` to an encrypted value `cipher1`, storing the result in `rop`. More...

void	pcs_t_ep_mul (pcs_t_public_key *pk, mpz_t rop, mpz_t cipher1, mpz_t plain1)
	Multiply a plaintext value `plain1` with an encrypted value `cipher1`, storing the result in `rop`. More...

pcs_t_proof *	pcs_t_init_proof (void)
	Allocate and initialise the values in a pcs_t_proof object. More...

void	pcs_t_set_proof (pcs_t_proof *pf, mpz_t generator, unsigned long m1, unsigned long m2)
	Set a proof object's value to check for. More...

void	pcs_t_compute_1of2_ns_protocol (pcs_t_public_key pk, hcs_random hr, pcs_t_proof *pf, mpz_t cipher_m, mpz_t cipher_r, unsigned long nth_power, unsigned long id)
	Compute a proof for a particular value `ciper_m`, and an `id`. More...

int	pcs_t_verify_ns_protocol (pcs_t_public_key pk, pcs_t_proof pf, unsigned long id)
	Verify a proof and return whether it is an n'th power. More...

int	pcs_t_verify_1of2_ns_protocol (pcs_t_public_key pk, pcs_t_proof pf, mpz_t cipher, unsigned long id)
	Compute the value for an n^s protocol, limited to 1 of 2 values. More...

void	pcs_t_free_proof (pcs_t_proof *pf)
	Frees a pcs_t proof object and all values associated with it. More...

pcs_t_polynomial *	pcs_t_init_polynomial (pcs_t_private_key vk, hcs_random hr)
	Allocate and initialise the values in a random polynomial. More...

void	pcs_t_compute_polynomial (pcs_t_private_key vk, pcs_t_polynomial px, mpz_t rop, const unsigned long x)
	Compute a polynomial P(x) for a given x value in the required finite field. More...

void	pcs_t_free_polynomial (pcs_t_polynomial *px)
	Frees a given polynomial (array of mpz_t values) and all associated data. More...

pcs_t_auth_server *	pcs_t_init_auth_server (void)
	Initialise a pcs_t_auth_server and return a pointer to the newly created structure. More...

void	pcs_t_set_auth_server (pcs_t_auth_server *au, mpz_t si, unsigned long i)
	Set the internal values for the server `au`. More...

void	pcs_t_share_decrypt (pcs_t_public_key vk, pcs_t_auth_server au, mpz_t rop, mpz_t cipher1)
	For a given ciphertext `cipher1`, compute the server `au's` share and store the result in the variable `rop`. More...

int	pcs_t_share_combine (pcs_t_public_key vk, mpz_t rop, hcs_shares hs)
	Combine an array of shares `c`, storing the result in `rop`. More...

void	pcs_t_free_auth_server (pcs_t_auth_server *au)
	Frees a pcs_t_auth_server and all associated memory. More...

void	pcs_t_clear_public_key (pcs_t_public_key *pk)
	Clears all data in a pcs_t_public_key. More...

void	pcs_t_clear_private_key (pcs_t_private_key *vk)
	Clears all data in a pcs_t_private_key. More...

void	pcs_t_free_public_key (pcs_t_public_key *pk)
	Frees a pcs_t_public_key and all associated memory. More...

void	pcs_t_free_private_key (pcs_t_private_key *vk)
	Frees a pcs_t_private_key and all associated memory. More...

int	pcs_t_verify_key_pair (pcs_t_public_key pk, pcs_t_private_key vk)
	Sanity check to quickly determine if pk and vk refer to the same values and are compatible. More...

int	pcs_t_import_public_key (pcs_t_public_key pk, const char json)
	Import a public key from a json string. More...

char *	pcs_t_export_public_key (pcs_t_public_key *pk)
	Export a public key from as a json string. More...

char *	pcs_t_export_auth_server (pcs_t_auth_server *au)
	Export an auth server as a json string. More...

int	pcs_t_import_auth_server (pcs_t_auth_server au, const char json)
	Import an auth server from a json string. More...

char *	pcs_t_export_verify_values (pcs_t_private_key *vk)
	Export an array of verification values corresponding to each server as a json array. More...

int	pcs_t_import_verify_values (pcs_t_private_key vk, const char json)
	Import an array of verification values stored in a json string. More...

Detailed Description

The threshold Paillier scheme offers the same properties as the Paillier scheme, with the extra security that decryption is split performed between a number of parties instead of just a single trusted party.

It is much more complex to set up a system which provides this, so determine if you actually require this before using.

All mpz_t values can be aliases unless otherwise stated.

Warning: All indexing for the servers and polynomial functions should be zero-indexed, as is usual when working with c arrays. The functions themselves correct for this internally, and 1-indexing servers may result in incorrect results.

Function Documentation

pcs_t_public_key* pcs_t_init_public_key ( void )

Initialise a pcs_t_public_key and return a pointer to the newly created structure.

Returns: A pointer to an initialised pcs_t_public_key, NULL on allocation failure

pcs_t_private_key* pcs_t_init_private_key ( void )

Initialise a pcs_t_private_key and return a pointer to the newly created structure.

Returns: A pointer to an initialised pcs_t_private_key, NULL on allocation failure

int pcs_t_generate_key_pair	(	pcs_t_public_key *	pk,
		pcs_t_private_key *	vk,
		hcs_random *	hr,
		const unsigned long	bits,
		const unsigned long	l,
		const unsigned long	w
	)

Initialise a key pair with modulus size bits.

It is required that pk and vk are initialised before calling this function. pk and vk are expected to not be NULL. w is the number of servers total to be used with the resulting keys. l is the number of servers required to succesfully decrypt a given message.

In practice the bits value should usually be greater than 2048 to ensure sufficient security.

Warning: This function attempts to allocate memory, so calling this twice in succession with the same keys will cause your program to lose a pointer to this allocated memory, resulting in a memory leak. If you wish to call this function in this manner, ensure pcs_t_clear_public_key and/or pcs_t_clear_private_key are called prior.

Precondition: 0 < l <= w

 pcs_t_public_key *pk = pcs_t_init_public_key();
 pcs_t_private_key *vk = pcs_t_init_private_key();
 hcs_random = hcs_random_init();
 pcs_t_generate_key(pk, vk, hr, 2048, 5, 7);

Parameters

pk	A pointer to an initialised pcs_t_public_key
vk	A pointer to an initialised pcs_t_private_key
hr	A pointer to an initialised hcs_random type
bits	The number of bits for the modulus of the key
l	The number of servers required to succesfully decrypt
w	The number of servers in total

Returns: non-zero on success, zero on allocation failure

void pcs_t_encrypt_r	(	pcs_t_public_key *	pk,
		mpz_t	rop,
		mpz_t	r,
		mpz_t	plain1
	)

Encrypt a value plain1, and set rop to the encryted result.

This function uses the random value r, passed as a parameter by the caller instead of generating a value with an hcs_random object.

r should be in the field Z_{n^2}*.

Parameters

pk	A pointer to an initialised pcs_t_public_key
r	mpz_t where the random value to use is stored
rop	mpz_t where the encrypted result is stored
plain1	mpz_t to be encrypted

void pcs_t_r_encrypt	(	pcs_t_public_key *	pk,
		hcs_random *	hr,
		mpz_t	r,
		mpz_t	rop,
		mpz_t	plain1
	)

Encrypt a value plain1, and set rop to the encrypted result.

This only differs from pcs_t_encrypt in that the random value generated for use in this encryption is stored in the mpz_t variable, r.

Parameters

pk	A pointer to an initialised pcs_t_public_key
hr	A pointer to an initialised hcs_random type
r	mpz_t where the random value generated is stored
rop	mpz_t where the encrypted result is stored
plain1	mpz_t to be encrypted

void pcs_t_encrypt	(	pcs_t_public_key *	pk,
		hcs_random *	hr,
		mpz_t	rop,
		mpz_t	plain1
	)

Encrypt a value plain1, and set rop to the encrypted result.

Parameters

pk	A pointer to an initialised pcs_t_public_key
hr	A pointer to an initialised hcs_random type
rop	mpz_t where the encrypted result is stored
plain1	mpz_t to be encrypted

void pcs_t_reencrypt	(	pcs_t_public_key *	pk,
		hcs_random *	hr,
		mpz_t	rop,
		mpz_t	op
	)

Reencrypt an encrypted value cipher1.

Upon decryption, this newly encrypted value, rop, will retain the same value as op.

Parameters

pk	A pointer to an initialised pcs_t_public_key
hr	A pointer to an initialised hcs_random type
rop	mpz_t where the newly encrypted value is stored
op	mpz_t to be reencrypted

void pcs_t_ep_add	(	pcs_t_public_key *	pk,
		mpz_t	rop,
		mpz_t	cipher1,
		mpz_t	plain1
	)

Add a plaintext value plain1 to an encrypted value cipher1, storing the result in rop.

Parameters

pk	A pointer to an initialised pcs_t_public_key
rop	mpz_t where the newly encrypted value is stored
cipher1	mpz_t to be added together
plain1	mpz_t to be added together

void pcs_t_ee_add	(	pcs_t_public_key *	pk,
		mpz_t	rop,
		mpz_t	cipher1,
		mpz_t	cipher2
	)

Add an encrypted value cipher2 to an encrypted value cipher1, storing the result in rop.

Parameters

pk	A pointer to an initialised pcs_t_public_key.
rop	mpz_t where the newly encrypted value is stored
cipher1	mpz_t to be added together
cipher2	mpz_t to be added together

void pcs_t_ep_mul	(	pcs_t_public_key *	pk,
		mpz_t	rop,
		mpz_t	cipher1,
		mpz_t	plain1
	)

Multiply a plaintext value plain1 with an encrypted value cipher1, storing the result in rop.

Parameters

pk	A pointer to an initialised pcs_t_public_key
rop	Where the new encrypted result is stored
cipher1	The encrypted value which is to be multipled to
plain1	The plaintext value which is to be multipled

pcs_t_proof* pcs_t_init_proof ( void )

Allocate and initialise the values in a pcs_t_proof object.

This is used in all verification and computation involving proofs.

Returns: A zero-initialised pcs_t_proof object

void pcs_t_set_proof	(	pcs_t_proof *	pf,
		mpz_t	generator,
		unsigned long	m1,
		unsigned long	m2
	)

Set a proof object's value to check for.

Parameters

pf	A pointer to an initialised pcs_t_proof object
generator	Value to set the generator of the proof
m1	First power that this proof will allow
m2	Second power that this proof will allow

void pcs_t_compute_1of2_ns_protocol	(	pcs_t_public_key *	pk,
		hcs_random *	hr,
		pcs_t_proof *	pf,
		mpz_t	cipher_m,
		mpz_t	cipher_r,
		unsigned long	nth_power,
		unsigned long	id
	)

Compute a proof for a particular value ciper_m, and an id.

cipher_m is the encrypted value for which the proof is generated for, with cipher_r being the random value used to generate it. cipher_m and cipher_r can be generated using the pcs_t_r_encrypt function.

The result of this function is a proof result stored in pf, which can be queried to determine if cipher_m is an encryption of an n'th power.

Parameters

pk	A pointer to an initialised pcs_t_public_key
hr	A pointer to an initialised hcs_random object
pf	A pointer to an initialised pcs_t_proof object
cipher_m	The encrypted value
cipher_r	The random r value used for this cipher text
nth_power	The power that this encrypted value represents
id	User id in the system. This can be discarded by using the value 0

int pcs_t_verify_ns_protocol	(	pcs_t_public_key *	pk,
		pcs_t_proof *	pf,
		unsigned long	id
	)

Verify a proof and return whether it is an n'th power.

Parameters

pk	A pointer to an initialised pcs_t_public_key
pf	A pointer to an initialised hcs_random object
id	User id in the system.

Returns: 0 if not an n'th power, non-zero if it is an n'th power

int pcs_t_verify_1of2_ns_protocol	(	pcs_t_public_key *	pk,
		pcs_t_proof *	pf,
		mpz_t	cipher,
		unsigned long	id
	)

Compute the value for an n^s protocol, limited to 1 of 2 values.

Parameters

pk	A pointer to an initialised pcs_t_public_key
pf	A pointer to an initialised pcs_t_proof
cipher	Encrypted value that this proof is meant to verify
id	of the owner of this cipher text

void pcs_t_free_proof ( pcs_t_proof * pf )

Frees a pcs_t proof object and all values associated with it.

Parameters

pf	An initialised pcs_t_proof object

pcs_t_polynomial* pcs_t_init_polynomial	(	pcs_t_private_key *	vk,
		hcs_random *	hr
	)

Allocate and initialise the values in a random polynomial.

The length of this polynomial is taken from values in vk, specifically it will be of length vk->w. The polynomial functions are to be used by a single trusted party, for which once the required computation is completed, the polynomial can be discarded.

 mpz_t *poly = pcs_t_init_polynomial(vk, hr);
 for (int i = 0; i < decrypt_server_count; ++i) {
     pcs_t_compute_polynomial(vk, poly, result, i);
     network_send(result); // Send the computed value to a decryption server
 }
 pcs_t_free_polynomial(vk, poly);

Parameters

vk	A pointer to an initialised pcs_t_private_key
hr	A pointer to an initialised hcs_random type

Returns: A polynomial coefficient list on success, else NULL

void pcs_t_compute_polynomial	(	pcs_t_private_key *	vk,
		pcs_t_polynomial *	px,
		mpz_t	rop,
		const unsigned long	x
	)

Compute a polynomial P(x) for a given x value in the required finite field.

The coefficients should be given as a list of mpz_t values, computed via the pcs_t_init_polynomial function.

Parameters

vk	A pointer to an initialised pcs_t_private_key
px	A pointer to a list of coefficients of a polynomial
rop	mpz_t where the result is stored
x	The value to calculate the polynomial at

void pcs_t_free_polynomial ( pcs_t_polynomial * px )

Frees a given polynomial (array of mpz_t values) and all associated data.

The same private key which was used to generate these values should be used as an argument.

Parameters

px	A pointer to a pcs_t_polynomial

pcs_t_auth_server* pcs_t_init_auth_server ( void )

Initialise a pcs_t_auth_server and return a pointer to the newly created structure.

Returns: A pointer to an initialised pcs_t_auth_server, NULL on allocation failure

void pcs_t_set_auth_server	(	pcs_t_auth_server *	au,
		mpz_t	si,
		unsigned long	i
	)

Set the internal values for the server au.

si is the secret polynomial share for the given value, i. These values should be shared in a secret and secure way and not given out publicly. The index given to each server should be unique.

Parameters

au	A pointer to an initialised pcs_t_auth_server
si	The value of a secret polynomial evaluated at `i`
i	The servers given index

void pcs_t_share_decrypt	(	pcs_t_public_key *	vk,
		pcs_t_auth_server *	au,
		mpz_t	rop,
		mpz_t	cipher1
	)

For a given ciphertext cipher1, compute the server au's share and store the result in the variable rop.

These shares can be managed, and then combined when sufficient shares have been accumulated using the pcs_t_share_combine function.

Parameters

vk	A pointer to an initialised pcs_t_private_key
au	A pointer to an initialised pcs_t_auth_server
rop	mpz_t where the calculated share is stored
cipher1	mpz_t which stores the ciphertext to decrypt

int pcs_t_share_combine	(	pcs_t_public_key *	vk,
		mpz_t	rop,
		hcs_shares *	hs
	)

Combine an array of shares c, storing the result in rop.

The array c must be managed by the caller, and is expected to be at least of length vk->l. If it is greater, only the first vk->l values are scanned. If a share is not present, then the value is expected to be 0. If reusing the same array for a number of decryptions, ensure that the array is zeroed between each combination.

Todo:: Potentially construct a proper type for storing a list of shares to ensure these functions are called in the correct way.

Precondition: vk->l <= length(c)

Parameters

vk	A pointer to an initialised pcs_t_private_key
rop	mpz_t where the combined decrypted result is stored
hs	A pointer to an initialised hcs_shares

void pcs_t_free_auth_server ( pcs_t_auth_server * au )

Frees a pcs_t_auth_server and all associated memory.

Parameters

au	A pointer to an initialised pcs_t_auth_server

void pcs_t_clear_public_key ( pcs_t_public_key * pk )

Clears all data in a pcs_t_public_key.

This does not free memory in the keys, only putting it into a state whereby they can be safely used to generate new key values.

Parameters

pk	A pointer to an initialised pcs_t_public_key

void pcs_t_clear_private_key ( pcs_t_private_key * vk )

Clears all data in a pcs_t_private_key.

This does not free memory in the keys, only putting it into a state whereby they can be safely used to generate new key values.

Parameters

vk	A pointer to an initialised pcs_t_private_key

void pcs_t_free_public_key ( pcs_t_public_key * pk )

Frees a pcs_t_public_key and all associated memory.

The key memory is not zeroed, so one must call pcs_t_clear_public_key if it is required. one does not need to call pcs_t_clear_public_key before using this function.

Parameters

pk	A pointer to an initialised pcs_t_public_key

void pcs_t_free_private_key ( pcs_t_private_key * vk )

Frees a pcs_t_private_key and all associated memory.

The key memory is not zeroed, so one must call pcs_t_clear_private_key if it is required. one does not need to call pcs_t_clear_private_key before using this function.

Parameters

vk	A pointer to an initialised pcs_t_private_key

int pcs_t_verify_key_pair	(	pcs_t_public_key *	pk,
		pcs_t_private_key *	vk
	)

Sanity check to quickly determine if pk and vk refer to the same values and are compatible.

Parameters

pk	A pointer to an initialised pcs_t_public_key
vk	A pointer to an initialised pcs_t_private_key

Returns: non-zero if keys match, zero if they do not

int pcs_t_import_public_key	(	pcs_t_public_key *	pk,
		const char *	json
	)

Import a public key from a json string.

The format of the json string must match those of the export functions, and is described more in-depth at @(refer to description of serialization).

Parameters

pk	A pointer to an initialised pcs_t_public_key
json	A null-terminated json string containing public key data

Returns: 0 on success, non-zero on parse failure

char* pcs_t_export_public_key ( pcs_t_public_key * pk )

Export a public key from as a json string.

This function allocates memory and it is up to the caller to free it accordingly.

Parameters

pk	A pointer to an initialised pcs_t_public_key

Returns: A null-terminated json string

char* pcs_t_export_auth_server ( pcs_t_auth_server * au )

Export an auth server as a json string.

This function allocates memory and it is up to the caller to free it accordingly.

Parameters

au	A pointer to an initialised pcs_t_auth_server

Returns: A null-terminated json string

int pcs_t_import_auth_server	(	pcs_t_auth_server *	au,
		const char *	json
	)

Import an auth server from a json string.

The format of the json string must match that of the corresponding import function.

Parameters

au	A pointer to an initialised pcs_t_auth_server
json	A null-terminated json string containing auth server data

Returns: 0 on success, non-zero on parse failure

char* pcs_t_export_verify_values ( pcs_t_private_key * vk )

Export an array of verification values corresponding to each server as a json array.

This is seperate from the private key export function as it may not always be wanted.

Warning: Unimplemented

Todo:: This function will eventually be altered so that the verification values are stored in a pcs_t_public_key.

Parameters

vk	A pointer to an initialised pcs_t_private_key

Returns: json A null-terminated json string containing all server verification data. NULL is returned on case of parse error.

int pcs_t_import_verify_values	(	pcs_t_private_key *	vk,
		const char *	json
	)

Import an array of verification values stored in a json string.

The format should matched that produced by pcs_t_export_verify_values.

Warning: Unimplemented

Todo:: As with the export function

Parameters

vk	A pointer to an initialised pcs_t_private_key
json	A null-terminated json string containing verification values

Returns: non-zero on success and 0 on failure

Data Structures

Functions

Detailed Description

Function Documentation