Base classes

Base classes for pyflocker.

class pyflocker.ciphers.base.BaseSymmetricCipher[source]

Bases: object

abstract is_encrypting() → bool[source]

Whether the cipher is encrypting or not.

Returns:

True if encrypting, else False.

abstract update(data: bytes) → bytes[source]

Takes bytes-like object and returns encrypted/decrypted bytes object.

Parameters:

data – The bytes-like object to pass to the cipher.

Returns:

Encrypted/decrypted data as bytes.

abstract update_into(data: bytes, out: bytearray | memoryview) → None[source]

Encrypt or decrypt the data and store it in a preallocated buffer out.

Parameters:

  • data – The bytes-like object to pass to the cipher.

  • out – The buffer interface where the encrypted/decrypted data must be written into.

class pyflocker.ciphers.base.BaseNonAEADCipher[source]

Bases: BaseSymmetricCipher

Abstract Base Class for ciphers that have no authentication support.

These ciphers can be wrapped by classes that implement BaseAEADCipher and the wrappers must provide authentication support.

abstract finalize() → None[source]

Finalizes and closes the cipher.

Raises:

AlreadyFinalized – If the cipher was already finalized.

class pyflocker.ciphers.base.BaseAEADCipher[source]

Bases: BaseSymmetricCipher

Abstract base class for AEAD ciphers.

Custom cipher wrappers that provide AEAD functionality to NonAEAD ciphers must derive from this.

abstract authenticate(data: bytes) → None[source]

Authenticates part of the message that get delivered as is, without any encryption.

Parameters:

data – The bytes-like object that must be authenticated.

Raises:

TypeError – if this method is called after calling update().

abstract finalize(tag: bytes | None = None) → None[source]

Finalizes and ends the cipher state.

Parameters:

tag – The associated tag that authenticates the decryption. Tag is required for decryption only.

Raises:
abstract calculate_tag() → bytes | None[source]

Calculates and returns the associated tag.

Returns:

Returns None if decrypting, otherwise the associated authentication tag.

class pyflocker.ciphers.base.BaseAEADOneShotCipher[source]

Bases: BaseAEADCipher

abstract update(data: bytes, tag: bytes | None = None) → bytes[source]

Encrypt or decrypt data.

Tag is required only for decryption. The cipher is finalized after calling this method.

Parameters:

  • data – A bytes-like object to pass to the cipher.

  • tag – The associated tag that authenticates the decryption. Tag is required for decryption only.

Returns:

Encrypted/decrypted data as bytes object.

abstract update_into(data: bytes, out: bytearray | memoryview, tag: bytes | None = None) → None[source]

Encrypt or decrypt data and write it to out.

If decrypting, the MAC tag must be provided. The cipher is finalized after calling this method.

Parameters:

  • data – The bytes-like oject to pass to the cipher.

  • out – The buffer interface where the encrypted/decrypted data must be written into.

  • tag – The associated tag that authenticates the decryption. Tag is required for decryption only.

class pyflocker.ciphers.base.BaseHash[source]

Bases: object

Abstract base class for hash functions. Follows PEP-0452.

Custom MACs must use this interface.

abstract property digest_size: int

The size of the digest produced by the hashing object, measured in bytes. If the hash has a variable output size, this output size must be chosen when the hashing object is created, and this attribute must contain the selected size. Therefore, None is not a legal value for this attribute.

Returns:

Digest size as integer.

abstract property block_size: int

An integer value or NotImplemented; the internal block size of the hash algorithm in bytes. The block size is used by the HMAC module to pad the secret key to digest_size or to hash the secret key if it is longer than digest_size. If no HMAC algorithm is standardized for the hash algorithm, returns NotImplemented instead.

Returns:

An integer if block size is available, otherwise NotImplemented.

See also

PEP 452 – API for Cryptographic Hash Functions v2.0, https://www.python.org/dev/peps/pep-0452

abstract update(data: bytes) → None[source]

Hash string into the current state of the hashing object. update() can be called any number of times during a hashing object’s lifetime.

Parameters:

data – The chunk of message being hashed.

Raises:

AlreadyFinalized – Raised if digest() or hexdigest() has been called.

abstract digest() → bytes[source]

Return the hash value of this hashing object as a string containing 8-bit data. The object is not altered in any way by this function; you can continue updating the object after calling this function.

Returns:

Digest as binary form.

hexdigest() → str[source]

Return the hash value of this hashing object as a string containing hexadecimal digits.

Returns:

Digest, as a hexadecimal form.

abstract copy() → BaseHash[source]

Return a separate copy of this hashing object. An update to this copy won’t affect the original object.

Returns:

A copy of hash function.

Raises:

AlreadyFinalized – This is raised if the method is called after calling digest() method.

abstract property name: str

Name of the hash function.

abstract new(data: bytes | None = None) → BaseHash[source]

Create a fresh hash object.

class pyflocker.ciphers.base.BaseRSAPrivateKey[source]

Bases: object

abstract property n: int

RSA public modulus.

The number n is such that n == p * q.

abstract property e: int

RSA public exponent.

abstract property p: int

First factor of RSA modulus.

abstract property q: int

Second factor of RSA modulus.

abstract property d: int

RSA private exponent.

abstract property key_size: int

Size of the key, in bits.

abstract decryptor(padding: BaseAsymmetricPadding | None = None) → BaseDecryptorContext[source]

Creates a decryption context.

Parameters:

padding – The padding to use. Default is OAEP.

Returns:

object for decrypting ciphertexts.

abstract signer(padding: BaseAsymmetricPadding | None = None) → BaseSignerContext[source]

Create a signer context.

Parameters:

padding – The padding to use. Default is PSS.

Returns:

Signer object for signing messages.

Note

If the padding is PSS and salt_length is None, the salt length will be maximized, as in OpenSSL.

abstract public_key() → BaseRSAPublicKey[source]

Creates a public key from the private key.

Returns:

The RSA public key.

abstract serialize(encoding: str, format: str, passphrase: bytes | None = None) → bytes[source]

Serialize the private key.

Parameters:

  • encoding – The encoding to use.

  • format – The format to use.

  • passphrase – A bytes object to use for encrypting the private key. If passphrase is None, the private key will be exported in the clear!

Returns:

Serialized key as a bytes object.

Raises:

ValueError – If the encoding or format is incorrect.

Important

The encoding and format supported by one backend may not be supported by the other. You should check the documentation of the implementation of the method for supported options.

abstract classmethod load(data: bytes, passphrase: bytes | None = None) → BaseRSAPrivateKey[source]

Loads the private key as bytes object and returns the Key interface.

Parameters:

  • data – The key as bytes object.

  • passphrase – The passphrase that deserializes the private key. It must be a bytes-like object if the key was encrypted while serialization, otherwise None.

Returns:

RSA private key.

Raises:

ValueError – if the key could not be deserialized.

class pyflocker.ciphers.base.BaseRSAPublicKey[source]

Bases: object

abstract property n: int

RSA public modulus.

The number n is such that n = p * q.

abstract property e: int

RSA public exponent.

abstract property key_size: int

Size of the key, in bits.

abstract encryptor(padding: BaseAsymmetricPadding | None = None) → BaseEncryptorContext[source]

Creates a encryption context.

Parameters:

padding – The padding to use. Defaults to OAEP.

Returns:

object for encrypting plaintexts.

abstract verifier(padding: BaseAsymmetricPadding | None = None) → BaseVerifierContext[source]

Creates a verifier context.

Parameters:

padding – The padding to use. Defaults to PSS.

Returns:

verifier object for verification.

abstract serialize(encoding: str, format: str) → bytes[source]

Serialize the public key.

Parameters:

  • encoding – The encoding to use.

  • format – The format to use.

Returns:

Serialized public key as bytes object.

Raises:

ValueError – if the encoding or format is incorrect or unsupported.

Important

The encoding and format supported by one backend may not be supported by the other. You should check the documentation of the implementation of this method for supported options.

abstract classmethod load(data: bytes) → BaseRSAPublicKey[source]

Loads the public key as bytes object and returns the Key interface.

Parameters:

data – The key as bytes object.

Returns:

The RSA public key.

Raises:

ValueError – if the key could not be deserialized.

class pyflocker.ciphers.base.BaseAsymmetricPadding[source]

Bases: object

Base class for padding schemes used by asymmetric algorithms.

abstract property name: str

Name of the padding scheme.

class pyflocker.ciphers.base.BaseMGF[source]

Bases: object

Base class for mask generation functions used by padding algorithms.

class pyflocker.ciphers.base.BaseEllepticCurveExchangeAlgorithm[source]

Bases: object

Base class for exchange algorithm for elleptic keys.

class pyflocker.ciphers.base.BaseEllepticCurveSignatureAlgorithm[source]

Bases: object

Base class for signing algorithm for elleptic keys.

class pyflocker.ciphers.base.BaseECCPrivateKey[source]

Bases: object

abstract property key_size: int

Size of ECC key, in bits.

abstract property curve: str

Name of the curve that this key is on.

abstract public_key() → BaseECCPublicKey[source]

Creates a public key from the private key.

Returns:

The public key.

abstract serialize(encoding: str, format: str, passphrase: bytes | None = None) → bytes[source]

Serialize the private key.

Parameters:

  • encoding – The encoding to use.

  • format – The format to use.

  • passphrase – A bytes object to use for encrypting the private key. If passphrase is None, the private key will be exported in the clear!

Returns:

Serialized key as a bytes object.

Raises:

ValueError – If the encoding or format is incorrect.

Important

The encoding and format supported by one backend may not be supported by the other. You should check the documentation of the implementation of the method for supported options.

abstract classmethod load(data: bytes, *, curve: str | None = None) → BaseECCPrivateKey[source]

Loads the private key as bytes object and returns the Key interface.

Parameters:

  • data – The key as bytes object.

  • passphrase – The passphrase that deserializes the private key. It must be a bytes-like object if the key was encrypted while serialization, otherwise None.

Keyword Arguments:

curve – The name of the curve as string. It is required only for Raw keys.

Returns:

RSA private key.

Raises:

ValueError – if the key could not be deserialized.

abstract exchange(peer_public_key: bytes | BaseECCPublicKey, algorithm: None | BaseEllepticCurveExchangeAlgorithm = None) → bytes[source]

Perform a key exchange.

Parameters:

  • peer_public_key – The peer public key can be a bytes or an ECC public key object.

  • algorithm – The algorithm to use for performing key exchange. Default is ECDH.

Returns:

A shared key.

Raises:

TypeError – if peer_public_key is not a bytes-like or ECC Public Key object.

abstract signer(algorithm: BaseEllepticCurveSignatureAlgorithm) → BaseSignerContext | BaseEdDSASignerContext[source]

Creates a signer context.

Parameters:

algorithm – The signing algorithm to use. Default is ECDSA for NIST curves and EdDSA for Edwards curves.

Returns:

signer object for signing.

class pyflocker.ciphers.base.BaseECCPublicKey[source]

Bases: object

abstract property key_size: int

Size of ECC key, in bits.

abstract property curve: str

Name of the curve that this key is on.

abstract serialize(encoding: str, format: str) → bytes[source]

Serialize the public key.

Parameters:

  • encoding – The encoding to use.

  • format – The format to use.

Returns:

Serialized public key as bytes object.

Raises:

ValueError – if the encoding or format is incorrect or unsupported.

Important

The encoding and format supported by one backend may not be supported by the other. You should check the documentation of the implementation of this method for supported options.

abstract classmethod load(data: bytes, *, curve: str | None = None) → BaseECCPublicKey[source]

Loads the public key as bytes object and returns the Key interface.

Parameters:

data – The key as bytes object.

Keyword Arguments:

curve – The name of the curve as a string. Required only for SEC1 and Raw keys.

Returns:

The ECC public key.

Raises:

ValueError – if the key could not be deserialized.

abstract verifier(algorithm: None | BaseEllepticCurveSignatureAlgorithm = None) → BaseVerifierContext | BaseEdDSAVerifierContext[source]

Creates a verifier context.

Parameters:

algorithm – The signing algorithm to use. Default is ECDSA for NIST curves and EdDSA for Edwards curves.

Returns:

verifier object for verification.

class pyflocker.ciphers.base.BaseSignerContext[source]

Bases: object

abstract sign(msghash: BaseHash) → bytes[source]

Return the signature of the message hash.

Parameters:

msghash – It must be a BaseHash object, used to digest the message to sign.

Returns:

signature of the message as bytes object.

class pyflocker.ciphers.base.BaseVerifierContext[source]

Bases: object

abstract verify(msghash: BaseHash, signature: bytes) → None[source]

Verifies the signature of the message hash.

Parameters:

  • msghash – It must be a BaseHash object, used to digest the message to sign.

  • signature – The signature of the message.

Raises:

SignatureError – if the signature was incorrect.

class pyflocker.ciphers.base.BaseEdDSASignerContext[source]

Bases: object

abstract sign(msghash: bytes) → bytes[source]

Return the signature of the message.

Parameters:

msghash – A bytes object.

Returns:

signature of the message as bytes object.

class pyflocker.ciphers.base.BaseEdDSAVerifierContext[source]

Bases: object

abstract verify(msghash: bytes, signature: bytes) → None[source]

Verifies the signature of the message.

Parameters:

  • msghash – A bytes object.

  • signature – The signature of the message.

Raises:

SignatureError – if the signature was incorrect.

class pyflocker.ciphers.base.BaseEncryptorContext[source]

Bases: object

abstract encrypt(plaintext: bytes) → bytes[source]

Encrypts the plaintext and returns the ciphertext.

Parameters:

plaintext – The data to encrypt.

Returns:

encrypted bytes object.

class pyflocker.ciphers.base.BaseDecryptorContext[source]

Bases: object

abstract decrypt(ciphertext: bytes) → bytes[source]

Decrypts the ciphertext and returns the plaintext.

Parameters:

ciphertext – The ciphertext to decrypt.

Returns:

The plaintext.

Raises:

DecryptionError – if the decryption was not successful.

class pyflocker.ciphers.base.BaseDHParameters[source]

Bases: object

abstract property g: int

The generator value.

abstract property p: int

The prime modulus value.

abstract property q: int | None

The p subgroup order value.

abstract private_key() → BaseDHPrivateKey[source]

Create a DH private key from the parameters.

Returns:

A private key object.

abstract serialize(encoding: str, format: str) → bytes[source]

Serialize the DH parameters.

Parameters:

  • encoding – The encoding to use.

  • format – The format to use.

Returns:

The parameters encoded as bytes object.

Raises:

ValueError – if the encoding of format is invalid.

Important

The encoding and format supported by one backend may not be supported by the other. You should check the documentation of the implementation of this method for supported options.

abstract classmethod load(data: bytes) → BaseDHParameters[source]

Deserialize the encoded DH parameters.

Parameters:

data – The parameters as an encoded bytes object.

Returns:

DH parameter object.

abstract classmethod load_from_parameters(p: int, g: int = 2, q: int | None = None) → BaseDHParameters[source]

Generates a DH parameter group from the parameters.

Parameters:

  • p – The prime modulus value.

  • g – The generator value. Must be 2 or 5. Default is 2.

  • q – p subgroup order value. Defaults to None.

Returns:

DH Parameter object.

class pyflocker.ciphers.base.BaseDHPrivateKey[source]

Bases: object

abstract parameters() → BaseDHParameters[source]

Creates a new DH Parameters object from the key.

Returns:

The DH parameter object.

abstract property key_size: int

Size of the key, in bytes.

abstract public_key() → BaseDHPublicKey[source]

Create a public key from the private key.

Returns:

A public key object.

abstract exchange(peer_public_key: bytes | BaseDHPublicKey) → bytes[source]

Perform a key exchange.

Parameters:

peer_public_key – The peer public key can be a bytes or a BaseDHPublicKey object.

Returns:

A shared key.

Raises:

TypeError – if peer_public_key is not a bytes-like or DH Public Key object.

abstract serialize(encoding: str, format: str, passphrase: bytes | None) → bytes[source]

Serialize the private key.

Parameters:

  • encoding – The encoding to use.

  • format – The format to use.

  • passphrase – The passphrase to use to protect the private key. None if the private key is not encrypted.

Returns:

The private key as bytes object.

Raises:

  • ValueError – if the encoding or format is invalid.

  • TypeError – if the passphrase is not a bytes-like object.

Important

The encoding and format supported by one backend may not be supported by the other. You should check the documentation of the implementation of this method for supported options.

abstract property x: int

The private value.

abstract classmethod load(data: bytes, passphrase: bytes | None = None) → BaseDHPrivateKey[source]

Deserialize and load the the private key.

Parameters:

  • data – The serialized private key as bytes-like object.

  • passphrase – The passphrase that was used to protect the private key. If key is not protected, passphrase is None.

Returns:

A private key.

Raises:

  • ValueError – If the key could not be deserialized.

  • TypeError – If passphrase is not a bytes-like object.

class pyflocker.ciphers.base.BaseDHPublicKey[source]

Bases: object

abstract parameters() → BaseDHParameters[source]

Creates a new DH parameters object from the key.

Returns:

The DH parameter object.

abstract property key_size: int

Size of the key, in bytes.

abstract serialize(encoding: str, format: str) → bytes[source]

Serialize the public key.

Parameters:

  • encoding – The encoding to use.

  • format – The format to use.

Returns:

The public key as bytes object.

Raises:

ValueError – if the encoding or format is invalid.

abstract property y: int

The public value.

abstract classmethod load(data: bytes) → BaseDHPublicKey[source]

Deserialize and load the public key.

Parameters:

data – The serialized public key as bytes-like object.

Returns:

A public key object.

Raises:

ValueError – If the key could not be deserialized.