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, ifdevice_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. IfFalse
, 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 typenumpy.bool
and the same shape asciphertext
.
-
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 withLweSampleArray.dump()
orLweSampleArray.dumps()
into the context memory space.The low-level analogues:
LweSampleArray.load()
andLweSampleArray.loads()
.Returns: an LweSampleArray
object
-
load_cloud_key
(file_or_bytestring)¶ Load a secret key (a
NuFHECloudKey
object) serialized withNuFHECloudKey.dump()
orNuFHECloudKey.dumps()
into the context memory space.The low-level analogues:
NuFHECloudKey.load()
andNuFHECloudKey.loads()
.Returns: a NuFHECloudKey
object
-
load_secret_key
(file_or_bytestring)¶ Load a secret key (a
NuFHESecretKey
object) serialized withNuFHESecretKey.dump()
orNuFHESecretKey.dumps()
into the context memory space.The low-level analogues:
NuFHESecretKey.load()
andNuFHESecretKey.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 aNuFHECloudKey
objects.
-
make_secret_key
(**params)¶ Creates a secret key, with
params
used to initialize aNuFHEParameters
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.
- rng – a random number generator which will be used wherever randomness is required.
Can be an instance of one of the Random number generators
(
-
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"
. IfNone
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.- api – the GPGPU backend to use, one of
-
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 aContext
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
isNone
, creates a new ciphertext and uses it to store the output of the gate; otherwisedest
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 withLweSampleArray.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.
- thr – a
-
classmethod
load
(file_obj, thr)¶ Deserialize from the given
file_obj
, a readable file-like object, using thereikna
threadthr
to store arrays.
-
classmethod
loads
(s, thr)¶ Deserialize from the given bytestring using the
reikna
threadthr
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.
- thr – a
-
classmethod
load
(file_obj, thr)¶ Deserialize from the given
file_obj
, a readable file-like object, using thereikna
threadthr
to store arrays.
-
classmethod
loads
(s, thr)¶ Deserialize from the given bytestring using the
reikna
threadthr
to store arrays.
-
-
nufhe.
make_key_pair
(thr, rng, **params)¶ Creates a pair of
NuFHESecretKey
andNuFHECloudKey
corresponding toNuFHEParameters
created with keywordsparams
.
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 thedtype
is notnumpy.bool
, it will be converted tonumpy.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 typenumpy.bool
and the same shape asciphertext
.- key (
-
nufhe.
empty_ciphertext
(thr, params, shape)¶ Creates an uninitialized
LweSampleArray
with the shapeshape
.
-
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 regularnumpy
array with the shapeshape
.
-
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 thereikna
threadthr
to store arrays.
-
classmethod
loads
(s, thr)¶ Deserialize from the given bytestring using the
reikna
threadthr
to store arrays.
-
roll
(shift, axis=-1)¶ Cyclically shifts encrypted bits of the cyphertext inplace by
shift
positions to the right alongaxis
.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
(exceptaxis=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 fromvals
(which will be converted tobool
).vals
should be an array or a list with a shape broadcastable to the shape ofresult
, 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 thevals
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.
- thr – a
-
nufhe.
gate_copy
(thr, cloud_key, result, a, perf_params=None)¶ Copy the contents of the ciphertext
a
toresult
.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 ofresult
.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.
- thr – a
-
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 ofresult
.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.
- thr – a
Binary gates¶
-
nufhe.
gate_and
(thr, cloud_key, result, a, b, perf_params=None)¶ Homomorphic bootstrapped AND gate. Applied elementwise on two encrypted arrays of bits.
The shapes of
a
andb
should be broadcastable to the shape ofresult
.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 ciphertext with the first argument. - b (
LweSampleArray
) – the ciphertext with the second argument. - perf_params (
Optional
[PerformanceParametersForDevice
]) – an override for performance parameters.
- thr – a
-
nufhe.
gate_or
(thr, cloud_key, result, a, b, perf_params=None)¶ Homomorphic bootstrapped OR gate. Applied elementwise on two encrypted arrays of bits.
The shapes of
a
andb
should be broadcastable to the shape ofresult
.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 ciphertext with the first argument. - b (
LweSampleArray
) – the ciphertext with the second argument. - perf_params (
Optional
[PerformanceParametersForDevice
]) – an override for performance parameters.
- thr – a
-
nufhe.
gate_xor
(thr, cloud_key, result, a, b, perf_params=None)¶ Homomorphic bootstrapped XOR gate. Applied elementwise on two encrypted arrays of bits.
The shapes of
a
andb
should be broadcastable to the shape ofresult
.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 ciphertext with the first argument. - b (
LweSampleArray
) – the ciphertext with the second argument. - perf_params (
Optional
[PerformanceParametersForDevice
]) – an override for performance parameters.
- thr – a
-
nufhe.
gate_nand
(thr, cloud_key, result, a, b, perf_params=None)¶ Homomorphic bootstrapped NAND gate. Applied elementwise on two encrypted arrays of bits.
The shapes of
a
andb
should be broadcastable to the shape ofresult
.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 ciphertext with the first argument. - b (
LweSampleArray
) – the ciphertext with the second argument. - perf_params (
Optional
[PerformanceParametersForDevice
]) – an override for performance parameters.
- thr – a
-
nufhe.
gate_nor
(thr, cloud_key, result, a, b, perf_params=None)¶ Homomorphic bootstrapped NOR gate. Applied elementwise on two encrypted arrays of bits.
The shapes of
a
andb
should be broadcastable to the shape ofresult
.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 ciphertext with the first argument. - b (
LweSampleArray
) – the ciphertext with the second argument. - perf_params (
Optional
[PerformanceParametersForDevice
]) – an override for performance parameters.
- thr – a
-
nufhe.
gate_xnor
(thr, cloud_key, result, a, b, perf_params=None)¶ Homomorphic bootstrapped XNOR gate. Applied elementwise on two encrypted arrays of bits.
The shapes of
a
andb
should be broadcastable to the shape ofresult
.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 ciphertext with the first argument. - b (
LweSampleArray
) – the ciphertext with the second argument. - perf_params (
Optional
[PerformanceParametersForDevice
]) – an override for performance parameters.
- thr – a
-
nufhe.
gate_andny
(thr, cloud_key, result, a, b, perf_params=None)¶ Homomorphic bootstrapped ANDNY ((not a) and b) gate. Applied elementwise on two encrypted arrays of bits.
The shapes of
a
andb
should be broadcastable to the shape ofresult
.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 ciphertext with the first argument. - b (
LweSampleArray
) – the ciphertext with the second argument. - perf_params (
Optional
[PerformanceParametersForDevice
]) – an override for performance parameters.
- thr – a
-
nufhe.
gate_andyn
(thr, cloud_key, result, a, b, perf_params=None)¶ Homomorphic bootstrapped ANDYN (a and (not b)) gate. Applied elementwise on two encrypted arrays of bits.
The shapes of
a
andb
should be broadcastable to the shape ofresult
.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 ciphertext with the first argument. - b (
LweSampleArray
) – the ciphertext with the second argument. - perf_params (
Optional
[PerformanceParametersForDevice
]) – an override for performance parameters.
- thr – a
-
nufhe.
gate_orny
(thr, cloud_key, result, a, b, perf_params=None)¶ Homomorphic bootstrapped ORNY ((not a) or b) gate. Applied elementwise on two encrypted arrays of bits.
The shapes of
a
andb
should be broadcastable to the shape ofresult
.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 ciphertext with the first argument. - b (
LweSampleArray
) – the ciphertext with the second argument. - perf_params (
Optional
[PerformanceParametersForDevice
]) – an override for performance parameters.
- thr – a
-
nufhe.
gate_oryn
(thr, cloud_key, result, a, b, perf_params=None)¶ Homomorphic bootstrapped ORYN (a or (not b)) gate. Applied elementwise on two encrypted arrays of bits.
The shapes of
a
andb
should be broadcastable to the shape ofresult
.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 ciphertext with the first argument. - b (
LweSampleArray
) – the ciphertext with the second argument. - perf_params (
Optional
[PerformanceParametersForDevice
]) – an override for performance parameters.
- thr – a
Ternary gates¶
-
nufhe.
gate_mux
(thr, cloud_key, result, a, b, c, perf_params=None)¶ Homomorphic bootstrapped MUX (b if a else c, or, equivalently, (a and b) or ((not a) and c)) gate. Applied elementwise on three encrypted arrays of bits.
The shapes of
a
,b
andc
should be broadcastable to the shape ofresult
.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 ciphertext with the first argument. - b (
LweSampleArray
) – the ciphertext with the second argument. - c (
LweSampleArray
) – the ciphertext with the third argument. - perf_params (
Optional
[PerformanceParametersForDevice
]) – an override for performance parameters.
- thr – a
Performance parameters¶
-
class
nufhe.
PerformanceParameters
(nufhe_params, ntt_base_method=None, ntt_mul_method=None, ntt_lsh_method=None, use_constant_memory_multi_iter=None, use_constant_memory_single_iter=None, transforms_per_block=None, single_kernel_bootstrap=None, low_end_device=None)¶ Advanced performance settings for bootstrapping.
For all the optional parameters below, if
None
is given, the library will attempt to select the best performing variant, given the available information.Parameters: - nufhe_params – a
NuFHEParameters
object. - ntt_base_method –
'cuda_asm'
or'c'
; An algorithm used in NTT for modulo addition, modulo subtraction, and modulus. - ntt_mul_method – one of
'cuda_asm'
,'c_from_asm'
and'c'
; An algorithm used in NTT for modulo multiplication. - ntt_lsh_method – one of
'cuda_asm'
,'c_from_asm'
and'c'
; An algorithm used in NTT for modulo bitshift.
Note
'cuda_asm'
is only available for CUDA backend. When available, it is usually the fastest variant, or close to it.Parameters: - use_constant_memory_multi_iter – use constant GPU memory (as opposed to global memory) for precalculated coefficients in NTT/FFT in kernels where one of these transformations is executed multiple times per kernel call.
- use_constant_memory_single_iter – use constant GPU memory (as opposed to global memory) for precalculated coefficients in NTT/FFT in kernels where one of these transformations is executed once per kernel call.
Note
Using constant memory is usually beneficial on fast videocards if the transformation is executed many times per kernel call.
Parameters: transforms_per_block – a positive integer value, denoting how many separate transforms to execute in parallel on a single GPU multiprocessor (compute unit). Note
On most videocards 1 to 4 transforms is supported for NTT, and 1 to 8 for FFT. More transforms does not necessarily mean better performance, since parallel threads on the same compute unit compete for resources.
Since it is not trivial to determine the maximum in advance, if the requested number is greater than that, it will be dynamically reduced to the maximum possible value.
Parameters: single_kernel_bootstrap – if True
, execute bootstrap in a single kernel, instead of many separate kernel calls in a loop.Note
Single kernel bootstrap is only supported for default FHE parameters, and needs the videocard to support a certain amount of parallel threads on a compute unit (256 for FFT, 512 for NTT). If available, it is usually significantly faster, partially due to lower kernel call overhead.
Parameters: low_end_device – if True
, the optimal values for low-end videocards will be picked. IfNone
, the decision will be made based on the number of compute units the device has.-
for_device
(device_params)¶ Specialize performance parameters for the given device (using a Reikna
DeviceParams
object).Returns: a PerformanceParametersForDevice
object.
- nufhe_params – a
-
class
nufhe.performance.
PerformanceParametersForDevice
(perf_params, device_params)¶
Utility functions¶
-
nufhe.
clear_computation_cache
(thr)¶ Clear the cache of computation objects compiled for the given
reikna
threadthr
. This will help ensure a correct realease of the thread’s resources when the other references to it go out of scope (which is especially important for multi-threading applications using CUDA).Note
Context
objects call this function automatically on destruction.