templates.encryption_scheme module

Generic classes used for creating an encryption scheme.

class templates.encryption_scheme.Ciphertext(raw_value, scheme, **_kwargs)[source]

Bases: Generic[KM, PT, RP, CV]

Object that contains the ciphertext value for a particular EncryptionScheme. Also includes functionality for arithmetic operations on ciphertexts.

__add__(other)[source]

Add other to the underlying plaintext of this ciphertext.

Parameters:: other (Union[Self, TypeVar(PT)]) – Plaintext value or other ciphertext. If Plaintext value we add the plaintext value to the underlying ciphertext. If ciphertext we add the both underlying ciphertexts.
Return type:: Self
Returns:: Addition of other to this ciphertext.

__init__(raw_value, scheme, **_kwargs)[source]

Constructs a Ciphertext with the given ciphertext value encrypted using the specified scheme.

Parameters:

raw_value (TypeVar(CV)) – value of the ciphertext
scheme (EncryptionScheme[TypeVar(KM), TypeVar(PT), TypeVar(RP), TypeVar(CV), Self]) – encryption scheme used for creating this ciphertext
**_kwargs (Any) – Optional extra keyword arguments for the constructor.

__mul__(other)[source]

Multiply other with the underlying plaintext of this ciphertext.

Parameters:: other (Union[Self, TypeVar(PT)]) – Plaintext value or other ciphertext. If Plaintext value we multiply the plaintext value with the underlying ciphertext. If ciphertext we multiply the both underlying ciphertexts.
Return type:: Self
Returns:: Multiplication of other with this ciphertext.

__neg__()[source]

Negate the underlying plaintext of this ciphertext.

Return type:: Self
Returns:: Negated ciphertext.

__pow__(power)[source]

Exponentiate underlying plaintext of this ciphertext with the given exponent.

Parameters:: power (int) – Exponent to which the underlying plaintext should be exponentiated.
Return type:: Self
Returns:: Exponentiation of ciphertext to the given power.

__radd__(other)[source]

Add other to the underlying plaintext of this ciphertext.

Parameters:: other (Union[Self, TypeVar(PT)]) – Plaintext value or other ciphertext. If Plaintext value we add the plaintext value to the underlying ciphertext. If ciphertext we add the both underlying ciphertexts.
Return type:: Self
Returns:: Addition of other to this ciphertext.

__rmul__(other)[source]

Multiply other with the underlying plaintext of this ciphertext.

Parameters:: other (Union[Self, TypeVar(PT)]) – Plaintext value or other ciphertext. If Plaintext value we multiply the plaintext value with the underlying ciphertext. If ciphertext we multiply the both underlying ciphertexts.
Return type:: Self
Returns:: Multiplication of other with this ciphertext.

__rsub__(other)[source]

Subtract other from the underlying plaintext of this ciphertext.

Parameters:: other (Union[Self, TypeVar(PT)]) – Plaintext value or other ciphertext. If Plaintext value we subtract the plaintext value from the underlying ciphertext. If ciphertext we subtract the both underlying ciphertexts.
Return type:: Self
Returns:: Subtraction of other from this ciphertext.

__str__()[source]

Return type:: str
Returns:: String representation of Ciphertext.

__sub__(other)[source]

Subtract other from the underlying plaintext of this ciphertext.

Parameters:: other (Union[Self, TypeVar(PT)]) – Plaintext value or other ciphertext. If Plaintext value we subtract the plaintext value from the underlying ciphertext. If ciphertext we subtract the both underlying ciphertexts.
Raises:: TypeError – When the other object has an unsupported type for subtraction from this ciphertext.
Return type:: Self
Returns:: Subtraction of other from this ciphertext.

property value: CV

Raw value of the ciphertext.

Returns:: Value of the ciphertext

class templates.encryption_scheme.EncodedPlaintext(value, scheme)[source]

Bases: Generic[RP]

Class that contains the encoding of a plaintext for a particular scheme.

__eq__(other)[source]

Compare equality of two ciphertexts.

Parameters:: other (object) – The other object to compare with.
Raises:: TypeError – When other object has the incorrect type.
Return type:: bool
Returns:: Boolean value representing (in)equality of self and other.

__init__(value, scheme)[source]

Constructs an EncodedPlaintext with the given value and encoding as specified in the scheme.

Parameters:

value (TypeVar(RP)) – value of the plaintext after encoding
scheme (EncryptionScheme[TypeVar(KM), TypeVar(PT), TypeVar(RP), TypeVar(CV), TypeVar(CT, bound= Ciphertext[Any, Any, Any, Any])]) – encryption scheme that specifies the used encoding

Raises:

TypeError – When scheme has the incorrect type.

class templates.encryption_scheme.EncryptionScheme(*_args, **_kwargs)[source]

Bases: ABC, Generic[KM, PT, RP, CV, CT]

Abstract base class to define generic EncryptionScheme functionality. Can be used for all kinds of encryption scheme (e.g. Asymmetric, Symmetric).

Most easily constructed using the from_security_parameter method.

All abstract methods should be implemented by subclasses.

abstract __eq__(other)[source]

Method that determines whether two EncryptionSchemes are the same

Parameters:: other (object) – EncryptionScheme to be compared to self
Return type:: bool
Returns:: whether they are the same scheme

__init__(*_args, **_kwargs)[source]

Construct a new EncryptionScheme.

Parameters:

*_args (Any) – Optional extra arguments for the constructor of a concrete implementation.
**_kwargs (Any) – Optional extra keyword arguments for the constructor of a concrete implementation.

classmethod __init_subclass__()[source]

Constructor for subclasses.

Return type:: None

add(ciphertext_1, ciphertext_2)[source]

Add the underlying plaintext value of ciphertext_1 with the (underlying) plaintext value of ciphertext_2. Where ciphertext_2 can either be another ciphertext or a plaintext, depending on the scheme.

Parameters:

ciphertext_1 (TypeVar(CT, bound= Ciphertext[Any, Any, Any, Any])) – First Ciphertext of which the underlying plaintext is added.
ciphertext_2 (Union[TypeVar(CT, bound= Ciphertext[Any, Any, Any, Any]), TypeVar(PT)]) – Either a second Ciphertext of which the underlying plaintext is multiplied with the first, or a Plaintext that is added with the underlying plaintext of the first Ciphertext.

Raises:

NotImplementedError – Raised when addition is not supported by this scheme.

Return type:

TypeVar(CT, bound= Ciphertext[Any, Any, Any, Any])

Returns:

A Ciphertext containing the encryption of the addition of both values.

classmethod clear_instances(all_types=False)[source]

Clear the list of globally saved instances of the current derived EncryptionScheme class.

Parameters:: all_types (bool) – also clear instances of other derived EncryptionSchemes.
Return type:: None

abstract decode(encoded_plaintext)[source]

Decode an EncodedPlaintext using the specified encoding scheme.

Parameters:: encoded_plaintext (EncodedPlaintext[TypeVar(RP)]) – Plaintext to be decoded.
Return type:: TypeVar(PT)
Returns:: Decoded Plaintext value

decrypt(ciphertext, apply_encoding=True)[source]

Decrypts the input ciphertext.

Parameters:

ciphertext (TypeVar(CT, bound= Ciphertext[Any, Any, Any, Any])) – Ciphertext to be decrypted.
apply_encoding (bool) – Boolean indicating whether the decrypted ciphertext is decoded before it is returned.

Return type:

TypeVar(PT)

Returns:

Plaintext decrypted value.

decrypt_sequence(ciphertext_sequence, apply_encoding=True)[source]

Decrypts the list of input ciphertext.

Parameters:

ciphertext_sequence (Iterable[TypeVar(CT, bound= Ciphertext[Any, Any, Any, Any])]) – Sequence of Ciphertext to be decrypted.
apply_encoding (bool) – Boolean indicating whether the decrypted ciphertext is decoded before it is returned.

Return type:

Iterator[TypeVar(PT)]

Returns:

A list of Plaintext decrypted values.

abstract encode(plaintext)[source]

Encode a supported Plaintext using the specified encoding scheme.

Parameters:: plaintext (TypeVar(PT)) – Plaintext to be encoded.
Return type:: EncodedPlaintext[TypeVar(RP)]
Returns:: EncodedPlaintext object containing the encoded value.

encrypt(plaintext, apply_encoding=True)[source]

Encrypts the entered (encoded) Plaintext. Also encodes the Plaintext when this is required.

Parameters:

plaintext (Union[TypeVar(PT), EncodedPlaintext[TypeVar(RP)]]) – Plaintext or EncodedPlaintext to be encrypted.
apply_encoding (bool) – Boolean indicating whether a non-encoded plaintext should be encoded. If False, the plaintext is encrypted in raw form.

Return type:

TypeVar(CT, bound= Ciphertext[Any, Any, Any, Any])

Returns:

Ciphertext object containing the encrypted value of the plaintext.

encrypt_sequence(plaintext_sequence, apply_encoding=True)[source]

Encrypts the entered sequence of (encoded) Plaintext. Also encodes a Plaintext when this is required.

Parameters:

plaintext_sequence (Union[Iterable[TypeVar(PT)], Iterable[EncodedPlaintext[TypeVar(RP)]]]) – Sequence of Plaintext or EncodedPlaintext to be encrypted.
apply_encoding (bool) – Boolean indicating whether a non-encoded plaintext should be encoded. If False, the plaintext is encrypted in raw form.

Return type:

Iterator[TypeVar(CT, bound= Ciphertext[Any, Any, Any, Any])]

Returns:

Ciphertext object containing the encrypted value of the plaintext.

classmethod from_id(identifier)[source]

Return the EncryptionScheme with this identifier that is stored in the global list.

Parameters:: identifier (int) – Identifier of the encryption scheme.
Raises:: KeyError – If no scheme with this ID was found in the global list.
Return type:: Self
Returns:: EncryptionScheme belonging to this identifier.

classmethod from_id_arguments(*args, **kwargs)[source]

Function that calls id_from_arguments to obtain an identifier for this scheme and then retrieves a scheme from the global list of saved schemes using from_id.

Parameters:

*args (Any) – regular arguments that would normally go into the constructor
**kwargs (Any) – regular keyword arguments that would normally go into the constructor

Return type:

Self

Returns:

An EncryptionScheme with the same ID if one has been saved globally

abstract classmethod from_security_parameter(*args, **kwargs)[source]

Generate a new EncryptionScheme from a security parameter.

Parameters:

*args (Any) – Security parameter(s) and optional extra arguments for the EncryptionScheme constructor.
**kwargs (Any) – Security parameter(s) and optional extra arguments for the EncryptionScheme constructor.

Return type:

Self

Returns:

A new EncryptionScheme.

abstract static generate_key_material(*args, **kwargs)[source]

Method to generate key material (format depending on the type of scheme) for this scheme.

Parameters:

*args (Any) – Required arguments to generate said key material.
**kwargs (Any) – Required keyword arguments to generate said key material.

Return type:

TypeVar(KM)

abstract classmethod id_from_arguments(*args, **kwargs)[source]

Method that turns the arguments for the constructor into an identifier. This identifier is used to find constructor calls that would result in identical schemes.

Parameters:

*args (Any) – regular arguments
**kwargs (Any) – regular keyword arguments

Return type:

int

Returns:

identifier of type int

property identifier: int

Property that returns an identifier for the scheme. It calls id_from_arguments and inspects id_from_arguments to see which parameter names are required. It then searches for these parameter names in the attributes and properties of self and uses their values as input to the function. Note that this requires the parameter names to id_from_arguments to have the same name as their respective attributes/properties in the scheme.

Raises:

KeyError – In cast there is a mismatch between the argument names in id_from_arguments and the parameter names and properties of the class.
TypeError – At least one argument name from id_from_arguments correponds with a callable rather than an attribute or property.

Returns:

An identifier of type int

mul(ciphertext_1, ciphertext_2)[source]

Multiply the underlying plaintext value of ciphertext_1 with the (underlying) plaintext value of ciphertext_2. Where ciphertext_2 can either be another ciphertext or a plaintext, depending on the scheme.

Parameters:

ciphertext_1 (TypeVar(CT, bound= Ciphertext[Any, Any, Any, Any])) – First Ciphertext of which the underlying plaintext is multiplied.
ciphertext_2 (Union[TypeVar(CT, bound= Ciphertext[Any, Any, Any, Any]), TypeVar(PT)]) – Either a second Ciphertext of which the underlying plaintext is multiplied with the first, or a Plaintext that is multiplied with the underlying plaintext of the first Ciphertext.

Raises:

NotImplementedError – Raised when multiplication is not supported by this scheme.

Return type:

TypeVar(CT, bound= Ciphertext[Any, Any, Any, Any])

Returns:

A Ciphertext containing the encryption of the product of both values.

neg(ciphertext)[source]

Negate the underlying plaintext of this ciphertext. I.e. if the original plaintext of this ciphertext was 5 this method returns the ciphertext that has -5 as underlying plaintext.

Parameters:: ciphertext (TypeVar(CT, bound= Ciphertext[Any, Any, Any, Any])) – Ciphertext of which the underlying plaintext should be negated.
Raises:: NotImplementedError – Raised when negation is not supported by this scheme.
Return type:: TypeVar(CT, bound= Ciphertext[Any, Any, Any, Any])
Returns:: Ciphertext object corresponding to the negated plaintext.

pow(ciphertext, power)[source]

Raise the underlying plaintext value of ciph with the exponent power.

Parameters:

ciphertext (TypeVar(CT, bound= Ciphertext[Any, Any, Any, Any])) – Ciphertext containing the plaintext base.
power (int) – Exponent to which the base should be raised.

Raises:

NotImplementedError – Raised when exponentiation is not supported by this scheme.

Return type:

TypeVar(CT, bound= Ciphertext[Any, Any, Any, Any])

Returns:

Ciphertext containing the value of the underlying plaintext of ciph raised to the given power.

remove_from_global_list()[source]

If this instance is saved in the global list, remove it.

Return type:: None

save_globally(overwrite=False)[source]

Save this instance in a global list for accessibility using its identifier.

Parameters:: overwrite (bool) – overwrite an entry in the global list of the IDs coincide
Raises:: KeyError – If the ID already exists in the global list and overwrite is False
Return type:: None

exception templates.encryption_scheme.EncryptionSchemeWarning[source]

Bases: UserWarning

Issued to suggest cryptographic best practises.

class templates.encryption_scheme.SupportsNeg(*args, **kwargs)[source]

Bases: Protocol[T_co]

An ABC with one abstract method __neg__.