cryptool.cryptool.Cryptool Class Reference

Public Member Functions
def	__init__ (self)
def	msgToBytes (self, msg, enc=None)
def	getKDF (self, salt, length=None)
def	getCipherAlgorithm (self, key)
def	getHash (self, msg)
def	getCredentialsFromPassword (self, password, length=None, salt=None)
def	signMsg (self, msg, password)
def	validateSgnature (self, signed_data, password)
def	encryptMsg (self, msg, password, source="bytes")
def	decryptMsg (self, enc_card, password)
def	encryptFile (self, password, input_path, output_name=None, source="file")
def	encryptDir (self, password, input_path, output_name=None)
def	decryptFile (self, password, input_path, output_path=None)

Public Attributes
	encoding
	hash_algorithm
	key_length
	kdf_iterations
	salt
	extension

Detailed Description

Class to simplify the encryption and decryption of data presented either in raw bytes, text strings, files or directories.

Member Function Documentation

decryptFile()

def cryptool.cryptool.Cryptool.decryptFile	(		self,
			password,
			input_path,
			output_path = None
	)

Decripts the file given in 'input_path' and saves the resulting decrypted data
to the file with path name given in 'output_path'. If the encrypted data corresponds
to a directory, then its content will be placed in the directory 'output_path'.
If no output path is given, then it is necessary that the input file has extension
'self.extension' in order to take the input path as the output path without such 
extension. If the output path/directory already exists, it will be replaced.
Parameters:
- password [bytes/str]: the password to use for the decryption.
- input_path [str]: the absolute/relative path to the target file.
- output_path [str]: the path of the output file.
Return:
[dict]: relevant data about the procedure, in the form of a dictionray with the entries:
- "status" [str]: "OK" if everyhing went well, otherwise an error message.
Usage:
- res = self.decryptFile(password, "input/file", "output/file")

decryptMsg()

def cryptool.cryptool.Cryptool.decryptMsg	(		self,
			enc_card,
			password
	)

Attempts to decrypt the data given in the encryption card, with the given password.
If the encryted data is corrupted or the password is wrong, then an "invalid or 
corrupted data" error will be returned. An encryption card is generated with the 
'self.encryptMsg' method. Message authentication will be verified. The result will 
be given in the form of a decryption card containing relevant information about the 
decryption procedure and the result.
Parameters:
- enc_card [dict]: the card with the encrypted data, must have at least the entry
  "coded_data" mapping to the raw bytes string to decrypt.
- password [bytes/str]: the password to use in the decryption.
Return:
[dict]: The decryption card in the form of a dictionary, with the following entries:
- "status" [str]: "OK" if everyhing went well, otherwise an error message.
- "msg" [bytes]: the dectypted message.
- "source" [str]: the 'source' where the data comes from, one of "bytes", "str", 
  "file" or "dir". See the documentation of 'self.encryptMsg' for more information.
- "enc_time" [struct_time]: the time when the message was encrypted.

encryptDir()

def cryptool.cryptool.Cryptool.encryptDir	(		self,
			password,
			input_path,
			output_name = None
	)

Encripts the directory (with all its content) given in 'input_path' and saves 
the resulting encrypted data to the file with path name given in 'output_name'
but appending the extension 'self.extension'.
Parameters:
- password [bytes/str]: the password to use for the encryption.
- input_path [str]: the absolute/relative path to the target directory.
- output_name [str]: the extension 'self.extension' will be appended to this path name.
  The default output name is equal to 'input_path'.
Return:
[dict]: relevant data about the procedure, in the form of a dictionray with the entries:
- "status" [str]: "OK" if everyhing went well, otherwise an error message.
Usage:
- res = self.encryptFile(password, "input/file", "output/name")

encryptFile()

def cryptool.cryptool.Cryptool.encryptFile	(		self,
			password,
			input_path,
			output_name = None,
			source = "file"
	)

Encripts the file given in 'input_path' and saves the resulting encrypted data
to the file with path name given in 'output_name' but appending the extension
'self.extension'. Is not output name is given then 'input_path' will be used.
We can change the tag of the 'source' of the data, in case we want to use files
as intermediate steps during encryption of other type of sources.
Parameters:
- password [bytes/str]: the password to use for the encryption.
- input_path [str]: the absolute/relative path to the target file.
- output_name [str]: the extension 'self.extension' will be appended to this path name.
  The default output name is equal to 'input_path'.
- source [str]: "bytes", "str", "file" or "dir". The default is "file". See the 
  documentation of 'self.encryptMsg' for more information.
Return:
[dict]: relevant data about the procedure, in the form of a dictionray with the entries:
- "status" [str]: "OK" if everyhing went well, otherwise an error message.
Usage:
- res = self.encryptFile(password, "input/file", "output/name")

encryptMsg()

def cryptool.cryptool.Cryptool.encryptMsg	(		self,
			msg,
			password,
			source = "bytes"
	)

Encrypts the given message using the given password. The encrypted data is autenticated via a MAC
signature. We can tell the 'source' where the data comes from, so that we can determine 
when we decrypt data if a special post-processing is needed. The diferent sources are:
"bytes":raw bytes string | "str":text string | "file":a file | "dir":a directory
The result will be given in the form of an encryption card containing relevant information about 
the encryption procedure and the result.
Prameters:
- msg [bytes/str]: the message to encrypt.
- password [bytes/str]: the password to use for the encryption.
- source [str]: "bytes", "str", "file" or "dir". The default is "bytes".
Return:
[dict]: The encryption card in the form of a dictionary, with the following entries:
- "status" [str]: "OK" if everyhing went well, otherwise an error message.
- "coded_data" [bytes]: the encrypted message.
Usage:
- enc_card = self.encryptMsg(msg, password)
  if enc_card["status"] == "OK": ... do something with enc_card["coded_data"] ...

getCipherAlgorithm()

def cryptool.cryptool.Cryptool.getCipherAlgorithm	(		self,
			key
	)

Defines a cipher algorithm used in a Cipher Object to encrypt data using the given key.
This function is used in all the functions that use an encryption algorithm.
Parameters:
- key [bytes]: raw bytes string of size 'self.key_length' bytes used to encrypt the data.
Return:
- The encryption algorithm.
Usage:
- alg = self.getCipherAlgorithm(key)
  cipher = Cipher(alg, mode, backend=default_backend()).encryptor()
  decipher = Cipher(alg, mode, backend=default_backend()).decryptor()

getCredentialsFromPassword()

def cryptool.cryptool.Cryptool.getCredentialsFromPassword	(		self,
			password,
			length = None,
			salt = None
	)

Creates a credentials card derived from the given 'password'. The credentials include a 
cryptograhic key of the given 'length' and the salt used to generate the key from the 
password. An optional 'salt' will can be provided to recover previously generated credentials.
Remember that in order to generate the same password we need the same pair password-salt.
Parameters:
- password [bytes/str]: the password to derive the key.
- length [int]: the lenght of the derived key, in bytes. The default is 'self.key_length'.
- salt [bytes]: the salt used to generate the key. If not give, a new one will be generated.
Return:
[dict]: the credentials in the form of a dictionary with entries:
- "key" [bytes]: the derived cryptographic key.
- "salt" [bytes]: the salt used in combination with the password to generatet the key.
Usage:
- cred = self.getCredentialsFromPassword(password)
  old_cred = self.getCredentialsFromPassword(password, cred["salt"])

getHash()

def cryptool.cryptool.Cryptool.getHash	(		self,
			msg
	)

Generate a secure hash (no key used) of the given message. The hash algorithm is defined
in 'self.hash_algorithm'. The resulting hash will have size 'self.hash_algorithm.digest_size'
in bytes.
Parameters:
msg [bytes/str]: message to hash.
Return:
[bytes]: the raw bytes hash.
Usage:
- hash = self.getHash(msg)

getKDF()

def cryptool.cryptool.Cryptool.getKDF	(		self,
			salt,
			length = None
	)

Defines a Key Derivation Function (KDF). This is useful to generate secure cryptographic keys from
a simpler phrase like a password. The same pair password-salt always generates the same password of
the given length. This function is used in all the functions that use a KDF.
Parameters:
- salt [bytes]: raw bytes string of size 'self.key_length', use 'self.salt()' to obtain a secure salt.
- length [int]: the key generated with the returned KDF will have this size in Bytes.
Return:
- A key derivation function.
Usage:
 - kdf = self.getKDF(salt, length)
   key = kdf.derive(password)

msgToBytes()

def cryptool.cryptool.Cryptool.msgToBytes	(		self,
			msg,
			enc = None
	)

The cryptographic methods work on raw bytes. In order to simplify the usage of
text strings, this function checks if the message is already in raw bytes and
if not, then it is assumed to be a text string and encodes to raw bytes.
Parameters:
- msg [byes/str]: the message to safely convert to raw bytes.
- enc [srt]: the encoding used to encode string objects, de default is 'self.encoding'.
Return:
- [bytes]: The raw bytes string.
Usage:
- msg = msgToBytes(msg)
- msg = msgToBytes(msg, "cp1252")

signMsg()

def cryptool.cryptool.Cryptool.signMsg	(		self,
			msg,
			password
	)

Signs the given message. This procedure ensures that a message can not be altered without
detecting it.
Parameters:
- msg [bytes/str]: the message to sign.
- password [bytes/str]: the password to use for signing the message.
Return:
[bytes]: the raw bytes string that contains both the messsage and the signature.
Usage:
- signed_msg = self.signMsg("my message", "my password")

validateSgnature()

def cryptool.cryptool.Cryptool.validateSgnature	(		self,
			signed_data,
			password
	)

Validates a signature created by 'self.signMsg'.
Prameters:
- signed_data [bytes]: the signed message to authenticate.
- password [bytes/str]: the password used for signing the message.
Return:
[dict]: relevant data about the validation, in the form of a dictionray with the entries:
- "status" [str]: "OK" if the message got successfully authenticated, otherwise an error message.
- "msg" [bytes]: the raw bytes string containing the original message.
Usage:
- validation = self.validateSgnature(signed_data, "my password")
  if validation["status"] == "OK": ... do something with validation["msg"] ...

---

The documentation for this class was generated from the following file:

• cryptool.py