HeContext#

class HeContext#

An abstract main class representing an underlying HE library & scheme, configured, initialized, and ready to start working.

Upon initaliation, use on of the inheriting concrete classes such as HelibCkksContext. Then continue with a generic reference to HeContext to allow scheme obliviousness

This class bundles together all the data structures required for performing HE operations, including the keys. It either contains a public/private key pair, allowing all operations including decryption, or just the public key allowing everything but decryption.

It is used as input in constructor of many other classes in this library. For example, to create a ciphertext using the library represent by an HeContext, write: CTile c(he);

It can be further used to query various properties of the underlying scheme and library.

clone(self: pyhelayers.HeContext) → pyhelayers.HeContext#: Returns an uninitialized context of the same type.

static create(*args, **kwargs)#

Overloaded function.

create(context_name: str, req: pyhelayers.HeConfigRequirement) -> pyhelayers.HeContext

Creates and returns an initialized HE context given a context name and config requirement.

param context_name:

The context name.

type context_name:

string

param req:

The config requirement.

type req:

pyhelayers.HeConfigRequirement
create(prioritized_context_names: List[str]) -> pyhelayers.HeContext

Creates an HE context instance from the first available context name.

param prioritized_context_names:

Prioritized list of contexts names (highest priority first).

raise ValueError:

If no matching context is found.

get_automatic_bootstrapping(self: pyhelayers.HeContext) → bool#

Returns the value of the automaticBootstrapping flag

Return type:: boolean

get_context_id(self: pyhelayers.HeContext) → int#

Returns the context id that identifies the specific key set used by this context.

Return type:: int

get_default_device(self: pyhelayers.HeContext) → pyhelayers.DeviceType#

Returns the default device of the ciphertexts and plaintexts generated using this HeContext.

Return type:: DeviceType

get_default_scale(self: pyhelayers.HeContext) → float#

Returns default scale used in encoding (where applicable).

Return type:: double

get_he_config_requirement(self: pyhelayers.HeContext) → pyhelayers.HeConfigRequirement#: Returns the actual HeConfigRequirement object used by this HeContext, obtained by applying getActualConfigRequirement over the HeConfigRequirement object provided when initializing this HeContext.

get_library_name(self: pyhelayers.HeContext) → str#

Returns the name of the underlying library.

Return type:: string

get_modulus_chain(self: pyhelayers.HeContext) → numpy.ndarray[numpy.uint64]#

Returns the modulus chain: the value of each prime in the chain (where applicable).

Return type:: pyarrayuint64

get_public_functions(self: pyhelayers.HeContext) → pyhelayers.PublicFunctions#: Returns a PublicFunctions object specifying the functionalities that are supported by the public keys of this HeContext

get_scheme_name(self: pyhelayers.HeContext) → str#

Returns the name of the underlying scheme.

Return type:: string

get_security_level(self: pyhelayers.HeContext) → int#

Returns the security level supplied by this context.

Return type:: int

get_signature(self: pyhelayers.HeContext) → str#

Returns a signature of the context that distinguishes it enough to be able to load previously stored contexts based on their signatures.

Return type:: string

get_top_chain_index(self: pyhelayers.HeContext) → int#

Returns the highest available chain index. (for schemes where it is applicable).

Return type:: int

get_traits(self: pyhelayers.HeContext) → pyhelayers.HeTraits#: Returns an HeTraits object containing various properties of the underlying scheme.

has_secret_key(self: pyhelayers.HeContext) → bool#

Returns whether this context contains a secret key. If not, decryption and other operations relying on decryption will not be available (will throw an exception).

Return type:: bool

init_for_generic_packing(self: pyhelayers.HeContext, light: bool = False) → None#

Initializes HE context to be used for generic packing.

Parameters:: light – Whether to use a lighter HE context with smaller

multiplication depth (default: false).

static is_registered_context(context_name: str) → bool#

Returns indication to whether a registered context exists under a given context name.

Parameters:: context_name – The context name.

load_from_buffer(self: pyhelayers.HeContext, buf: bytes) → None#

Loads this HeContext from a buffer.

Parameters:: buf – a memory buffer to load the object from.

load_from_file(self: pyhelayers.HeContext, file_name: str) → int#

Loads this HeContext from a file saved by save_to_file().

Parameters:: file_name (string) – File to load from.

load_secret_key(self: pyhelayers.HeContext, buf: bytes, seed_only: bool = False) → None#

Load secret key from a buffer.

Parameters:

buf (A memory buffer) – A memory buffer to load the HeContext from.
seed_only – If True, the seed of the secret key will be loaded from the given buffer and the secret key will be generated using this seed. Defaults to False.

Raises:

RuntimeError – If this HeContext already has a secret key.
RuntimeError – If seed_only is True but the underlying HeContext does not support secret key I/O using seeds.

load_secret_key_from_file(self: pyhelayers.HeContext, file_name: str, seed_only: bool = False) → None#

Loads context saved by the saveToFile() method.

Parameters:

file_name (string) – File to load from.
seed_only (bool) – If True, the seed of the secret key will be loaded from the given file and the secret key will be generated using this seed. Defaults to False.

Raises:

RuntimeError – If this HeContext already has a secret key.

print_signature(self: pyhelayers.HeContext) → str#: Prints a summary of library details and configuration params.

public_functions_supported(self: pyhelayers.HeContext, public_functions: pyhelayers.PublicFunctions) → bool#

Returns whether the given PublicFunctions object is supported by this HeContext.

Parameters:: public_functions – The PublicFunctions object.

save_secret_key(self: pyhelayers.HeContext, seed_only: bool = False) → bytes#

Save secret key into a buffer.

Parameters:

seed_only (bool) – If True, only the seed used to control the secret key’s randomness will be saved, rather than the whole secret key. Defaults to False.

Raises:

RuntimeError – If this HeContext doesn’t have a secret key.
RuntimeError – If seed_only is True but the underlying HeContext does not support secret key I/O using seeds.

Returns:

a memory buffer containing the saved secret key.

save_secret_key_to_file(self: pyhelayers.HeContext, file_name: str, seed_only: bool = False) → None#

Save secret key to the given file.

Parameters:

file_name (string) – File to write to.
seed_only (bool) – If True, only the seed used to control the secret key’s randomness will be saved, rather than the whole secret key. Defaults to False.

Raises:

RuntimeError – If this HeContext does not have a secret key.

save_to_buffer(*args, **kwargs)#

Overloaded function.

save_to_buffer(self: pyhelayers.HeContext) -> bytes

Saves this HeContext into a buffer.

return:

a memory buffer containing the saved object.
save_to_buffer(self: pyhelayers.HeContext, public_functions: pyhelayers.PublicFunctions) -> bytes

Saves this HeContext into a buffer.

param public_functions:

determines which of the public keys should be saved.

type public_functions:

pyhelayers.PublicFunctions

return:

a memory buffer containing the saved object.

save_to_file(*args, **kwargs)#

Overloaded function.

save_to_file(self: pyhelayers.HeContext, file_name: str) -> int

Saves this HeContext to a file in binary form.

param file_name:

File to write to.

type file_name:

string
save_to_file(self: pyhelayers.HeContext, file_name: str, public_fuctions: pyhelayers.PublicFunctions) -> int

Saves this HeContext to a file in binary form.

param file_name:

File to write to.

type file_name:

string

param public_functions:

determines which of the public keys should be saved.

type public_functions:

pyhelayers.PublicFunctions

set_automatic_bootstrapping(self: pyhelayers.HeContext, v: bool) → None#

Sets the automaticBootstrapping flag to the given v. When automaticBootstrapping is set to true, ciphertexts created using this HeContext will be bootstrapped automatically when needed.

Parameters:: v – The value to set.

set_default_device(self: pyhelayers.HeContext, device: pyhelayers.DeviceType) → None#

Sets the default device of the ciphertexts and plaintexts generated using this HeContext.

Parameters:: device – the new default device

set_default_scale(self: pyhelayers.HeContext, v: float) → None#

Sets the default scale to be used in encoding (where applicable)..

Parameters:: v – The default scale.

slot_count(self: pyhelayers.HeContext) → int#

The number of slots in each CTile (ciphertext) or PTile (plaintext) created over this context.

Return type:: int

class HeContext : public helayers::Printable#

An abstract main class representing an underlying HE library & scheme, configured, initialized, and ready to start working.

Upon initaliation, use on of the inheriting concrete classes such as HelibCkksContext. Then continue with a generic reference to HeContext to allow scheme obliviousness

It is used as input in constructor of many other classes in this library. For example, to create a ciphertext using the library represent by an HeContext, write: CTile c(he);

It can be further used to query various properties of the underlying scheme and library.

Subclassed by helayers::CircuitContext, helayers::DebugContext, helayers::HeaanContext, helayers::HelibContext, helayers::LattigoContext, helayers::OpenFheContext, helayers::PalisadeCkksContext, helayers::PalisadeTfheContext, helayers::SealCkksContext, helayers::TrackingContext

Public Functions

HeContext()#: Constructs an empty object.

virtual ~HeContext()#

HeContext(const HeContext &src) = delete#

Copy constructor.

Parameters:: src – [in] Object to copy.

HeContext &operator=(const HeContext &src) = delete#

Copy from another object.

Parameters:: src – [in] Object to copy.

virtual void init(const HeConfigRequirement &req = HeConfigRequirement())#: Internal use.

void initForGenericPacking(bool light = false)#

Initializes HE context to be used for generic packing.

Parameters:: light – Whether to use a lighter HE context with smaller multiplication depth (default: false).

virtual HeConfigRequirement getConfigRequirementForGenericPacking(bool light) const#

Returns HE config requirement to be used for generic packing.

Parameters:: light – Whether to use a lighter HE context with smaller multiplication depth.

virtual bool isConfigRequirementFeasible(const HeConfigRequirement &req) const = 0#: Internal use.

std::string getContextFileHeaderCode() const#: Returns a string that identifies a concrete HeContext class for the purpose of dynamic loading.

virtual HeConfigRequirement getActualConfigRequirement(const HeConfigRequirement &req) const#

Returns the actual config requirement that will be enabled by the HE context when provided with the given config requirement.

Some parameters may differ from the original object and be “better”, e.g. higher multiplication depth.

Parameters:: req – The given config requirement.

virtual int getBestFeasibleFractionalPartPrecision(const HeConfigRequirement &req) const#

Returns the best feasible fractional part precision under the given configuration requirement.

If there is no such a fractional part precision, returns -1. All the fields of the given requirement other than req.fractionalPartPrecision are expected to be present, while any value in req.fractionalPartPrecision will be ignored.

Parameters:: req – The requirement to get best fractional part precision for.

virtual int getBestFeasibleMulDepth(const HeConfigRequirement &req) const#

Returns the best feasible multiplication depth under the given configuration requirement.

If there is no such a multiplication depth, returns -1. All the fields of the given requirement other than req.multiplicationDepth are expected to be present, while any value in req.multiplicationDepth will be ignored.

Parameters:: req – The requirement to get best multiplication depth for.

virtual int getMinFeasibleNumSlots(const HeConfigRequirement &req) const#

Returns the smallest number of slots that guarantees the other requirements in the given HeConfigRequirement.

If there is not such a number of slots, returns -1. All the fields of the given requirement other than req.numSlots are expected to be present, while any value in numSlots will be ignored.

Parameters:: req – The HeConfigrequirement.
Throws:: invalid_argument – If one of the fields of req other than req.numSlots is not present.

virtual std::shared_ptr<AbstractCiphertext> createAbstractCipher() const = 0#: Do not use. Should be made private.

virtual std::shared_ptr<AbstractPlaintext> createAbstractPlain() const = 0#: Do not use. Should be made private.

virtual std::shared_ptr<AbstractEncoder> getEncoder() const = 0#: Do not use. Should be made private.

virtual std::shared_ptr<AbstractFunctionEvaluator> getFunctionEvaluator()#: Do not use. Should be made private.

inline virtual std::shared_ptr<AbstractBitwiseEvaluator> getBitwiseEvaluator() const#: Do not use. Should be made private.

bool isMultiParty() const#: Returns indication to whether this HE context is set to be multi-party.

inline virtual std::shared_ptr<MultiPartyUtils> getMultiPartyUtils()#: Do not use. Should be made private.

inline virtual std::shared_ptr<MultiPartyUtils> getMultiPartyUtils() const#

virtual std::shared_ptr<AbstractBootstrapEvaluator> createAbstractBootstrapEvaluator(const BootstrapConfig &bsConfig = BootstrapConfig()) const#: Do not use. Should be made private.

bool getBootstrappable() const#: Returns indication to whether this HE context is bootstrappable.

const BootstrapConfig &getBootstrapConfig() const#: Returns the internal bootstrap configuration object.

const BootstrapEvaluator &getBootstrapEvaluator() const#: Returns the internal bootstrap evaluator object.

inline const HeTraits &getTraits() const#: Returns an HeTraits object containing various properties of the underlying scheme.

virtual bool hasSecretKey() const = 0#

Returns whether this context contains a secret key.

If not, decryption and other operations relying on decryption will not be available (will throw an exception).

virtual int slotCount() const = 0#: The number of slots in each CTile (ciphertext) or PTile (plaintext) created over this context.

virtual int getTopChainIndex() const = 0#: Returns the highest available chain index (for schemes where it is applicable).

virtual int getSecurityLevel() const = 0#: Returns the security level supplied by this context.

virtual void printSignature(std::ostream &out = std::cout) const#

Prints a summary of library details and configuration params.

Parameters:: out – [in] output stream to write to

virtual void debugPrint(const std::string &title = "", Verbosity verbosity = VERBOSITY_REGULAR, std::ostream &out = std::cout) const override#

Prints the content of this object.

Parameters:

title – Text to add to the print
verbosity – Verbosity level
out – Output stream

inline virtual std::shared_ptr<std::vector<uint64_t>> getModulusChain() const#: Returns the modulus chain: the value of each prime in the chain (where applicable).

inline virtual void setModulusChain(const std::shared_ptr<std::vector<uint64_t>> &modChain)#: Sets the modulus chain: the value of each prime in the chain (where applicable).

virtual void saveSecretKey(std::ostream &out, bool seedOnly = false)#

Save secret key to the given ostream.

Parameters:

out – The binary stream to save to.
seedOnly – If true, only the seed used to control the secret key’s randomness will be saved, rather than the whole secret key.

Throws:

runtime_error – If this HeContext doesn’t have a secret key. i.e. hasSecretKey() is false.
runtime_error – If seedOnly is true but the underlying HeContext does not support secret key I/O using seeds.

virtual void loadSecretKey(std::istream &in, bool seedOnly = false)#

Load secret key from the given istream.

Parameters:

in – The binary stream to load from.
seedOnly – If true, the seed of the secret key will be loaded from the given binary stream and the secret key will be generated using this seed.

Throws:

runtime_error – If this HeContext already has a secret key. i.e. hasSecretKey() is ture.
runtime_error – If seedOnly is true but the underlying HeContext does not support secret key I/O using seeds.

void saveSecretKeyToFile(const std::string &fileName, bool seedOnly = false)#

save secret key to the given file.

Parameters:

fileName – The path of the file to save to.
seedOnly – If true, only the seed used to control the secret key’s randomness will be saved, rather than the whole secret key.

Throws:

runtime_error – If this HeContext doesn’t have a secret key. i.e. hasSecretKey() is false.
runtime_error – If seedOnly is true but the underlying HeContext does not support secret key I/O using seeds.

void loadSecretKeyFromFile(const std::string &fileName, bool seedOnly = false)#

load secret key from the given file.

Parameters:

fileName – The path of the file to load from.
seedOnly – If true, the seed of the secret key will be loaded from the given file and the secret key will be generated using this seed.

Throws:

runtime_error – if this HeContext already has a secret key. i.e. hasSecretKey() is ture.
runtime_error – If seedOnly is true but the underlying HeContext does not support secret key I/O using seeds.

inline virtual DeviceType getDefaultDevice() const#: Returns the default device of the ciphertexts and plaintexts generated using this HeContext.

inline virtual void setDefaultDevice(DeviceType device)#

Sets the default device of the ciphertexts and plaintexts generated using this HeContext.

Parameters:: device – [in] the new default device

inline virtual double getDefaultScale() const#: Returns default scale used in encoding (where applicable).

inline virtual void setDefaultScale(double v)#

Sets the default scale to be used in encoding (where applicable).

Parameters:: v – [in] the default scale

virtual std::string getLibraryName() const = 0#: Returns the name of the underlying library.

virtual std::string getSchemeName() const = 0#: Returns the name of the underlying scheme.

inline virtual std::string getSignature() const#: Returns a signature of the context that distinguishes it enough to be able to load previously stored contexts based on their signatures.

inline virtual std::map<std::string, int64_t> getEstimatedMeasures() const#: For internal use.

virtual std::vector<double> getMaxAllowedValues() const#

Returns the maximal absolute value allowed for each chain index.

Values lower than the threshold are guaranteed to not preduce overflows. The value in position i corresponds to the limit for chain index i.

virtual double getMaxAllowedValueByRange(int high, int low) const#

Returns the maximal absolute value allowed for values that may be in any chain index within a range that’s defined between a given low and high chain indexes.

Parameters:

high – The higher chain index in the range.
low – The lower chain index in the range.

virtual double getMaxAllowedValue(int chainIndex) const#

Returns the maximal absolute value allowed for values in a given chain index.

Parameters:: chainIndex – The given chain index.

virtual double getMaxAllowedBsValue() const#: Returns the maximal absolute value allowed for values going through a bootstrap operation.

virtual std::shared_ptr<HeContext> clone() const#

Returns an uninitialized context of the same type.

Used for dynamic type loading among others.

virtual double getAccurateScale(int chainIndex) const#

Returns the accurate scale to be used for a given chain index.

Only supported when accurate scaling mode is enabled. Cannot be called before the context is initialized.

Parameters:

chainIndex – the chain index to get the scale of.

Throws:

runtime_error – If this SealCkksContext is not initialized.
runtime_error – If accurate scaling is not enabled.

inline int32_t getContextId() const#: Returns the context id that identifies the specific key set used by this context.

inline void setAutomaticBootstrapping(bool val)#

Sets the automaticBootstrapping flag to the given val.

When automaticBootstrapping is set to true, ciphertexts created using this HeContext will be bootstrapped automatically when needed.

Parameters:: val – The value to set

inline bool getAutomaticBootstrapping() const#: Returns the value of the automaticBootstrapping flag.

virtual int getMinChainIndexForBootstrapping() const#: Assuming this HeContext is bootstrappable, returns the minimum level in which ciphertexts can be bootstrapped.

virtual int getChainIndexAfterBootstrapping() const#: Assuming this HeContext is bootstrappable, returns the level of ciphertexts after bootstrapping.

virtual BootstrapConfig getBootstrapChainIndexes(const HeConfigRequirement &req) const#

Returns a bootstrap config object with two chain index values: the minimum level in which ciphertexts can be bootstrapped and the level of ciphertexts after bootstrapping.

Parameters:: req – The requirement, must indicate a bootstrappable object.

virtual int getMinSupportedNumSlots() const#: Returns the minimal number of slots supported by this HE context.

virtual int getMaxSupportedNumSlots() const#: Returns the maximal number of slots supported by this HE context.

inline const HeConfigRequirement &getHeConfigRequirement() const#: Returns the actual HeConfigRequirement object used by this HeContext, obtained by applying getActualConfigRequirement over the HeConfigRequirement object provided when initializing this HeContext.

inline const PublicFunctions &getPublicFunctions() const#: Returns a PublicFunctions object specifying the functionalities that are supported by the public keys of this HeContext.

bool composeRotate(int targetRotate, std::vector<int> &rotations) const#

Computes a minimal list of supported rotations that sum up to the targetRotate, if such a list exists.

Returns true if it is possible to construct such a list using the supported rotations, and false otherwise.

Parameters:

targetRotate – The required rotate, to be composed from several supported rotations.
rotations – The resulting set of rotations will be stored here. If no such a list exist, this vector will be empty.

Throws:

runtime_error – if the HeContext was not initialized with a custom rotations set.

bool canComposeRotate(int targetRotate) const#

Returns true if it is possible to construct such a list using the supported rotations, and false otherwise.

Parameters:: targetRotate – The required rotate, to be composed from several supported rotations.
Throws:: runtime_error – if the HeContext was not initialized with a custom rotations set.

inline bool isInitialized() const#: Returns whether this HeContext is initialized.

virtual bool publicFunctionsSupported(const PublicFunctions &publicFunctions) const = 0#

Returns whether the given PublicFunctions object is supported by this HeContext.

The given PublicFunctions object is assumed to be valid (see also PublicFunctions::validate()).

Parameters:: publicFunctions – The PublicFunctions object.

virtual void assertSavePublicFunctionsSupported(const PublicFunctions &publicFunctions) const#

Verifies that this HeContext supports calling save() method with the given PublicFunctions object.

Parameters:: publicFunctions – The PublicFunctions object.
Throws:: invalid_argument – If saving the given PublicFunctions object is not supported by this HeContext.

std::streamoff saveToFile(const std::string &fileName) const#

Saves this HeContext object to a file in binary form.

Returns the number of bytes written to the saved file.

Parameters:: fileName – name of file to write to
Throws:: runtime_error – If this Hecontext is not initialized.

std::streamoff saveToFile(const std::string &fileName, const PublicFunctions &publicFunctions) const#

Saves this HeContext to a file in binary form.

Returns the number of bytes written to the saved file. publicFunctions determines which of the public keys should be saved. Upon loading the saved HeContext, only the public functionalities specified in the given PublicFunctions object will be supported. This function assumes that this HeContext supports saving with the given PublicFunctions object (see also savePublicFunctionsSupported()).

Parameters:

fileName – Name of file to write to
publicFunctions – Determines which of the public keys should be saved.

Throws:

invalid_arguemnt – If this HeContext does not support saving with the given publicFunctions argument.
runtime_error – If this Hecontext is not initialized.

std::streamoff loadFromFile(const std::string &fileName)#

Loads this Saveable object from a file saved by saveToFile().

Returns the number of bytes read from the loaded file.

Parameters:: fileName – [in] name of file to read from

std::streamoff save(std::ostream &stream) const#

Saves this HeContext to a stream in binary form.

Returns the number of bytes written to the output stream.

Parameters:: stream – [in] output stream to write to

std::streamoff save(std::ostream &stream, const PublicFunctions &publicFunctions) const#

Saves this HeContext to a stream in binary form.

publicFunctions determines which of the public keys should be saved. Upon loading the saved HeContext, only the public functionalities specified in the given PublicFunctions object will be supported. This function assumes that this HeContext supports saving with the given PublicFunctions object (see also savePublicFunctionsSupported()).

Parameters:

stream – output stream to write to.
publicFunctions – Determines which of the public keys should be saved.

Throws:

invalid_arguemnt – If this HeContext does not support saving with the given publicFunctions argument.
runtime_error – If this Hecontext is not initialized.

std::streamoff load(std::istream &stream)#

Loads this object from the given stream.

Returns the number of bytes read from the input stream.

Parameters:: stream – [in] input stream to read from

void raiseAbortFlag() const#: Truns on the “abort” flag, see documentation of this flag for more details.

bool wasAbortFlagRaised() const#: Returns the value of the “abort” flag, see documentation of this flag for more details.

Public Static Functions

static std::shared_ptr<HeContext> create(const std::string &contextName, const HeConfigRequirement &req)#

Creates and returns an initialized HE context given a context name and config requirement.

Parameters:

contextName – The context name.
req – The config requirement.

static std::shared_ptr<HeContext> create(const std::vector<std::string> &prioritizedContextNames)#

Creates an HE context instance from the first available context name.

Parameters:: prioritizedContextNames – Prioritized list of contexts names (highest priority first).
Throws:: invalid_argument – If no matching context is found.

static bool internalRegisterContext(const HeContext *context)#

Registers a context object for the purpose of dynamic loading.

Don’t call this directly. Use REGISTER_CONTEXT (see above)

static std::shared_ptr<HeContext> getRegisteredHeContext(const std::string &contextName)#

Returns registered context given a context name.

Parameters:: contextName – The context name (library + scheme).

static bool isRegisteredHeContext(const std::string &contextName)#

Returns indication to whether a registered context exists under a given context name.

Parameters:: contextName – The context name (library + scheme).