The Paillier scheme is a scheme which provides homormorphic addition, and limited multiplication on encrypted data. More...

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

Include dependency graph for pcs.h:

Go to the source code of this file.

Data Structures
struct	pcs_public_key
	Public key for use in the Paillier system. More...

struct	pcs_private_key
	Private key for use in the Paillier system. More...

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

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

void	pcs_generate_key_pair (pcs_public_key pk, pcs_private_key vk, hcs_random *hr, const unsigned long bits)
	Initialise a key pair with modulus size `bits`. More...

void	pcs_encrypt (pcs_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_encrypt_r (pcs_public_key *pk, mpz_t rop, mpz_t plain1, mpz_t r)
	Encrypt a value `plain1`, and set `rop` to the encrypted result. More...

void	pcs_reencrypt (pcs_public_key pk, hcs_random hr, mpz_t rop, mpz_t op)
	Reencrypt an encrypted value `op`. More...

void	pcs_ep_add (pcs_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_ee_add (pcs_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_ep_mul (pcs_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...

void	pcs_decrypt (pcs_private_key *vk, mpz_t rop, mpz_t cipher1)
	Decrypt a value `cipher1`, and set `rop` to the decrypted result. More...

void	pcs_clear_public_key (pcs_public_key *pk)
	This function zeros all data in `pk`. More...

void	pcs_clear_private_key (pcs_private_key *vk)
	This function zeros all data in `pk`. More...

void	pcs_free_public_key (pcs_public_key *pk)
	Frees a pcs_public_key and all associated memory. More...

void	pcs_free_private_key (pcs_private_key *vk)
	Frees a pcs_private_key and all associated memory. More...

int	pcs_verify_key_pair (pcs_public_key pk, pcs_private_key vk)
	Check certain values shared between public and private keys to ensure they indeed are pairs. More...

char *	pcs_export_public_key (pcs_public_key *pk)
	Export a public key as a string. More...

char *	pcs_export_private_key (pcs_private_key *vk)
	Export a private key as a string. More...

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

int	pcs_import_private_key (pcs_private_key vk, const char json)
	Import a private key from a string. More...

Detailed Description

The Paillier scheme is a scheme which provides homormorphic addition, and limited multiplication on encrypted data.

These can be summarised as:

E(a + b) = pcs_ee_add(E(a), E(b));
E(a + b) = pcs_ep_add(E(a), b);
E(a * b) = pcs_ep_mul(E(a), b);

All mpz_t values can be aliases unless otherwise stated.

Function Documentation

pcs_public_key* pcs_init_public_key ( void )

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

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

pcs_private_key* pcs_init_private_key ( void )

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

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

void pcs_generate_key_pair	(	pcs_public_key *	pk,
		pcs_private_key *	vk,
		hcs_random *	hr,
		const unsigned long	bits
	)

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.

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

 pcs_public_key *pk = pcs_init_public_key();
 pcs_private_key *vk = pcs_init_private_key();
 hcs_random = hcs_random_init();
 pcs_generate_key(pk, vk, hr, 2048);

Parameters

pk	A pointer to an initialised pcs_public_key
vk	A pointer to an initialised pcs_private_key
hr	A pointer to an initialised hcs_random type
bits	The number of bits for the modulus of the key

void pcs_encrypt	(	pcs_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_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_encrypt_r	(	pcs_public_key *	pk,
		mpz_t	rop,
		mpz_t	plain1,
		mpz_t	r
	)

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

Do not randomly generate an r value, instead, use the given r. This is largely useless to a user, but is important for some zero-knowledge proofs.

Parameters

pk	A pointer to an initialised pcs_public_key
rop	mpz_t where the encrypted result is stored
plain1	mpz_t to be encrypted
r	random mpz_t value to be used during encryption

void pcs_reencrypt	(	pcs_public_key *	pk,
		hcs_random *	hr,
		mpz_t	rop,
		mpz_t	op
	)

Reencrypt an encrypted value op.

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

Parameters

pk	A pointer to an initialised pcs_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_ep_add	(	pcs_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_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_ee_add	(	pcs_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_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_ep_mul	(	pcs_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.

All the parameters can be aliased, however, usually only rop and cipher1 will be.

Parameters

pk	A pointer to an initialised pcs_public_key.
rop	mpz_t where the newly encrypted value is stored
cipher1	mpz_t to be multiplied together
plain1	mpz_t to be multiplied together

void pcs_decrypt	(	pcs_private_key *	vk,
		mpz_t	rop,
		mpz_t	cipher1
	)

Decrypt a value cipher1, and set rop to the decrypted result.

rop and cipher1 can aliases for the same mpz_t.

Parameters

vk	A pointer to an initialised pcs_private_key
rop	mpz_t where the decrypted result is stored
cipher1	mpz_t to be decrypted

void pcs_clear_public_key ( pcs_public_key * pk )

This function zeros all data in pk.

It is useful to use if we wish to generate or import a new value for the given pcs_public_key and want to safely ensure the old values are removed.

 // ... Initialised a key pk and done some work with it
 
 pcs_clear_public_key(pk); // All data from old key is now gone
 pcs_import_public_key(pk, "public.key"); // Safe to reuse this key

Parameters

pk	A pointer to an initialised pcs_public_key

void pcs_clear_private_key ( pcs_private_key * vk )

This function zeros all data in pk.

It is useful to use if we wish to generate or import a new value for the given pcs_private_key and want to safely ensure the old values are removed.

Parameters

vk	A pointer to an initialised pcs_private_key

void pcs_free_public_key ( pcs_public_key * pk )

Frees a pcs_public_key and all associated memory.

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

Parameters

pk	A pointer to an initialised pcs_public_key

void pcs_free_private_key ( pcs_private_key * vk )

Frees a pcs_private_key and all associated memory.

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

Parameters

vk	v pointer to an initialised pcs_private_key

int pcs_verify_key_pair	(	pcs_public_key *	pk,
		pcs_private_key *	vk
	)

Check certain values shared between public and private keys to ensure they indeed are pairs.

This checks only the n values, and assumes that the caller has not altered other internal values. If the caller has only interacted with the keys through the usual functions, then this should guarantee the keys are pairs.

Parameters

pk	A pointer to an initialised pcs_public_key
vk	A pointer to an initialised pcs_private_key

Returns: non-zero if keys are valid, else zero

char* pcs_export_public_key ( pcs_public_key * pk )

Export a public key as a string.

We only store the minimum required values to restore the key. In this case, this is only the n value.

The format these strings export as is as a JSON object.

Parameters

pk	A pointer to an initialised pcs_public_key

Returns: A string representing the given key, else NULL on error

char* pcs_export_private_key ( pcs_private_key * vk )

Export a private key as a string.

We only store the minimum required values to restore the key. In this case, these are the p and q values. The remaining values are then computed from these on import.

Parameters

vk	A pointer to an initialised pcs_private_key

Returns: A string representing the given key, else NULL on error

int pcs_import_public_key	(	pcs_public_key *	pk,
		const char *	json
	)

Import a public key from a string.

The input string is expected to match the format given by the export functions.

Parameters

pk	A pointer to an initialised pcs_public_key
json	A string storing the contents of a public key

Returns: non-zero if success, else zero on format error

int pcs_import_private_key	(	pcs_private_key *	vk,
		const char *	json
	)

Import a private key from a string.

The input string is expected to match the format given by the export functions.

Parameters

vk	A pointer to an initialised pcs_private_key
json	A string storing the contents of a private key

Returns: non-zero if success, else zero on format error

Data Structures

Functions

Detailed Description

Function Documentation