API reference¶

High-level api¶

class nufhe.Context(rng=None, thread=None, device_id=None, api=None, interactive=False, include_devices=None, exclude_devices=None, include_platforms=None, exclude_platforms=None)¶

An object encapuslating an execution environment on a GPU.

If thread is given, it will be used to create the context; otherwise, if device_id is given, it will be used; if none of the above is given, the first device satisfying the given criteria will be used.

Parameters:

rng – a random number generator which will be used wherever randomness is required. Can be an instance of one of the Random number generators (DeterministicRNG by default).
thread – a Reikna Thread object to use internally for the context.
device_id (Optional[DeviceID]) – a GPGPU device (and API) to use for the context.
interactive – if True, an interactive dialogue will be shown allowing one to choose the GPGPU device to use. If False, the first device satisfying the filters (see below) will be chosen.
api –
include_devices –
exclude_devices –
include_platforms –
exclude_platforms – see find_devices().

decrypt(secret_key, ciphertext)¶

Decrypts a message.

The low-level analogue: decrypt().

Returns:	a `numpy.ndarray` object of the type `numpy.bool` and the same shape as `ciphertext`.

encrypt(secret_key, message)¶

Encrypts a message (a list or a numpy array treated as an array of booleans).

The low-level analogue: encrypt().

Returns:	an `LweSampleArray` object with the same shape as the given array.

load_ciphertext(file_or_bytestring)¶

Load a ciphertext (a LweSampleArray object) serialized with LweSampleArray.dump() or LweSampleArray.dumps() into the context memory space.

The low-level analogues: LweSampleArray.load() and LweSampleArray.loads().

Returns:	an `LweSampleArray` object

load_cloud_key(file_or_bytestring)¶

Load a secret key (a NuFHECloudKey object) serialized with NuFHECloudKey.dump() or NuFHECloudKey.dumps() into the context memory space.

The low-level analogues: NuFHECloudKey.load() and NuFHECloudKey.loads().

Returns:	a `NuFHECloudKey` object

load_secret_key(file_or_bytestring)¶

Load a secret key (a NuFHESecretKey object) serialized with NuFHESecretKey.dump() or NuFHESecretKey.dumps() into the context memory space.

The low-level analogues: NuFHESecretKey.load() and NuFHESecretKey.loads().

Returns:	a `NuFHESecretKey` object

make_cloud_key(secret_key)¶

Creates a cloud key matching the given secret key.

The low-level analogue: NuFHECloudKey.from_rng().

Returns:	a `NuFHECloudKey` object.

make_key_pair(**params)¶

Creates a pair of a secret key and a matching cloud key.

The low-level analogue: make_key_pair().

Returns:	a tuple of a `NuFHESecretKey` and a `NuFHECloudKey` objects.

make_secret_key(**params)¶

Creates a secret key, with params used to initialize a NuFHEParameters object.

The low-level analogue: NuFHESecretKey.from_rng().

Returns:	a `NuFHESecretKey` object.

make_virtual_machine(cloud_key, perf_params=None)¶

Creates an FHE “virtual machine” which can execute logical gates using the given cloud key. Optionally, one can pass a PerformanceParameters object which will be specialized for the GPU device of the context and used in all the gate calls.

Returns:	a `VirtualMachine` object.

nufhe.find_devices(api=None, include_devices=None, exclude_devices=None, include_platforms=None, exclude_platforms=None)¶

Returns a list of computation device identifiers for the given API and selection criteria. If there are several platforms with suitable devices, only the first one will be used (so if you need a specific platform, use the corresponding masks).

Parameters:

api – the GPGPU backend to use, one of None, "CUDA" and "OpenCL". If None is given, an arbitrary available backend will be chosen.
include_devices – a list of strings; only devices with one of the strings present in the name will be included.
exclude_devices – a list of strings; devices with one of the strings present in the name will be excluded.
include_platforms – a list of strings; only platforms with one of the strings present in the name will be included.
exclude_platforms – a list of strings; platforms with one of the strings present in the name will be excluded.

Returns:

a list of DeviceID objects.

class nufhe.api_high_level.DeviceID(api_id, platform_id, device_id)¶

An identifier of a computation device suitable to run NuFHE. Obtained from find_devices(). Can be passed to another thread/process and used to create a Context object.

api_name¶: The name of the API ("CUDA" or "OpenCL").

platform_name¶: The name of the platform.

device_name¶: The name of the device.

class nufhe.api_high_level.VirtualMachine(thread, cloud_key, perf_params=None)¶

A fully encrypted virtual machine capable of executing gates on ciphertexts (LweSampleArray objects) using an encapsulated cloud key.

gate_<operator>(*args, dest: LweSampleArray=None)

Calls one of Logical gates, using the context, the cloud key, and the performance parameters of the virtual machine.

If dest is None, creates a new ciphertext and uses it to store the output of the gate; otherwise dest is used for that purpose.

Returns:	an `LweSampleArray` object with the result of the gate application.

empty_ciphertext(shape)¶

Returns an unitialized ciphertext (an LweSampleArray object).

The low-level analogue: empty_ciphertext().

load_ciphertext(file)¶

Load a ciphertext (a LweSampleArray object) serialized with LweSampleArray.dump into the context memory space.

The low-level analogue: LweSampleArray.load.

Returns:	an `LweSampleArray` object

Parameters and keys¶

class nufhe.NuFHEParameters(transform_type='NTT', tlwe_mask_size=1)¶

Parameters of the FHE scheme.

Parameters:	transform_type – `'NTT'` or `'FFT'`, specifying the transform to be used for internal purposes. `'FFT'` is generally faster, but may not be supported on some videocards (since it requires double precision floating point numbers).

Note

The default parameters correspond to about 128 bits of security.

class nufhe.NuFHESecretKey(params, lwe_key)¶

A secret key for the FHE scheme.

params¶

A NuFHEParameters object.

dump(file_obj)¶: Serialize into the given file_obj, a writeable file-like object.

dumps()¶: Serialize into a bytestring.

classmethod from_rng(thr, params, rng)¶

Generate a new secret key.

Parameters:	thr – a `reikna` `Thread` object. params (`NuFHEParameters`) – FHE scheme parameters. rng – an RNG object, one of Random number generators.

classmethod load(file_obj, thr)¶: Deserialize from the given file_obj, a readable file-like object, using the reikna thread thr to store arrays.

classmethod loads(s, thr)¶: Deserialize from the given bytestring using the reikna thread thr to store arrays.

class nufhe.NuFHECloudKey(params, bootstrap_key, keyswitch_key)¶

A cloud key for the FHE scheme.

params¶

A NuFHEParameters object.

dump(file_obj)¶: Serialize into the given file_obj, a writeable file-like object.

dumps()¶: Serialize into a bytestring.

classmethod from_rng(thr, params, rng, secret_key, perf_params=None)¶

Generate a new cloud key based on the given secret key.

Parameters:	thr – a `reikna` `Thread` object. params (`NuFHEParameters`) – FHE scheme parameters. rng – an RNG object, one of Random number generators. secret_key (`NuFHESecretKey`) – the secret key object. perf_params (`Optional`[`PerformanceParametersForDevice`]) – an override for performance parameters.

classmethod load(file_obj, thr)¶: Deserialize from the given file_obj, a readable file-like object, using the reikna thread thr to store arrays.

classmethod loads(s, thr)¶: Deserialize from the given bytestring using the reikna thread thr to store arrays.

nufhe.make_key_pair(thr, rng, **params)¶: Creates a pair of NuFHESecretKey and NuFHECloudKey corresponding to NuFHEParameters created with keywords params.

Random number generators¶

class nufhe.DeterministicRNG(seed=None)¶: A fast, but not cryptographically secure RNG. Useful for testing, since it allows seeding the initial state.

class nufhe.SecureRNG¶: A cryptographically secure RNG provided by the OS.

Note

This RNG can be very slow, leading to cloud key creation times of the order of minutes. Encryption is not affected too much (the required amount of random numbers is much lower).

Encryption/decryption¶

nufhe.encrypt(thr, rng, key, message)¶

Encrypts a message.

Parameters:	rng – an RNG object, one of Random number generators. key (`NuFHESecretKey`) – the secret key. message – a `numpy` array of bit values to encrypt; if the `dtype` is not `numpy.bool`, it will be converted to `numpy.bool`.
Returns:	an `LweSampleArray` object with the same shape as the given array.

nufhe.decrypt(thr, key, ciphertext)¶

Decrypts a message.

Parameters:	key (`NuFHESecretKey`) – the secret key. ciphertext (`LweSampleArray`) – an encrypted message.
Returns:	a `numpy.ndarray` object of the type `numpy.bool` and the same shape as `ciphertext`.

nufhe.empty_ciphertext(thr, params, shape)¶: Creates an uninitialized LweSampleArray with the shape shape.

class nufhe.LweSampleArray(params, a, b, current_variances)¶

A ciphertext object.

shape¶: The shape of the encrypted plaintext message.

__getitem__(index)¶: Returns a view over the ciphertext (still a LweSampleArray object). The indexing works in the same way as if it was a regular numpy array with the shape shape.

copy()¶: Returns a copy of the ciphertext.

dump(file_obj)¶: Serialize into the given file_obj, a writeable file-like object.

dumps()¶: Serialize into a bytestring.

classmethod load(file_obj, thr)¶: Deserialize from the given file_obj, a readable file-like object, using the reikna thread thr to store arrays.

classmethod loads(s, thr)¶: Deserialize from the given bytestring using the reikna thread thr to store arrays.

roll(shift, axis=-1)¶

Cyclically shifts encrypted bits of the cyphertext inplace by shift positions to the right along axis. shift can be negative (in which case the elements are shifted to the left). Elements that are shifted beyond the last position are re-introduced at the first (and vice versa).

Works equivalently to numpy.roll (except axis=None is not supported).

nufhe.concatenate(lwe_sample_arrays, axis=0, out=None)¶: Concatenates several ciphertext arrays along axis.

Logical gates¶

Unary gates¶

nufhe.gate_constant(thr, cloud_key, result, vals, perf_params=None)¶

Fill each bit of the ciphertext result with the trivial encryption of the plaintext values from vals (which will be converted to bool).

vals should be an array or a list with a shape broadcastable to the shape of result, or a scalar value.

Note

“Trivial encryption” means that the result of this gate does not require a secret key for decryption, and cannot be used to implement public key encryption. Its intended purpose is to initialize constants in bootstrapped circuits.

Not bootstrapped; perf_params does not have any effect and is only present for the sake of API uniformity.

Parameters:

thr – a reikna Thread object.
cloud_key (NuFHECloudKey) – the cloud key.
result (LweSampleArray) – an empty ciphertext where the result will be stored. Must be the same shape as the vals array.
vals – a numpy.bool array (or anything castable to it) used to fill the ciphertext.
perf_params (Optional[PerformanceParametersForDevice]) – an override for performance parameters.

nufhe.gate_copy(thr, cloud_key, result, a, perf_params=None)¶

Copy the contents of the ciphertext a to result.

Not bootstrapped; perf_params does not have any effect and is only present for the sake of API uniformity.

The shape of a should be broadcastable to the shape of result.

Parameters:	thr – a `reikna` `Thread` object. cloud_key (`NuFHECloudKey`) – the cloud key. result (`LweSampleArray`) – an empty ciphertext where the result will be stored. a (`LweSampleArray`) – the source ciphertext. perf_params (`Optional`[`PerformanceParametersForDevice`]) – an override for performance parameters.

nufhe.gate_not(thr, cloud_key, result, a, perf_params=None)¶

Homomorphic NOT gate. Applied elementwise on an encrypted array of bits.

Not bootstrapped; perf_params does not have any effect and is only present for the sake of API uniformity.

The shape of a should be broadcastable to the shape of result.

Parameters:	thr – a `reikna` `Thread` object. cloud_key (`NuFHECloudKey`) – the cloud key. result (`LweSampleArray`) – an empty ciphertext where the result will be stored. a (`LweSampleArray`) – the source ciphertext. perf_params (`Optional`[`PerformanceParametersForDevice`]) – an override for performance parameters.