Package: cipher-engine
CipherEngineWelcome toCipherEngine, a powerful Python library dedicated to symmetric key cryptography. This documentation offers a detailed exploration of the library, highlighting key features, and practical usage examples. Please refer to the table of contents below to navigate through the documentation.Table of ContentsRequirementsInstallationPrimary FeaturesData Encryption and DecryptionText Encryption and DecryptionPassphrase Generation and Key DerivationBackup ManagementExport Passkey Configuration FileQuick File EncryptionQuick Text EncryptionBasic File EncryptionBasic Text EncryptionAES Text EncryptionData Integrity Assurance MechanismEnhanced Security MeasuresUnique Encryption IdentifiersMultiple Fernet Keys wit MultiFernetKey GenerationOverviewCode BaseAll Available CharactersCharacter Set Exclusion OptionsExclusion ChartExclusion ExamplesCipherEngine ClassOverviewAttributesMethodsExampleDecipherEngine ClassOverviewAttributesMethodsExampleClass Engine Return StateCipherTupleUsage ExamplesGenerate a Secure Cryptographic KeyEncrypt Text using encrypt_textDecrypt Text using decrypt_textEncrypt a File using encrypt_fileDecrypt a File using decrypt_fileQuickly Encrypt Files using quick_encryptQuickly Decrypt Files using quick_decryptQuickly Encrypt Text using quick_encryptQuickly Decrypt Text using quick_decryptCommand-Line Interface (CLI)RoadmapUpcoming FeaturesProgress TableContributors and FeedbackContributingFeedbackContact-InformationImportant NotesMaximum Number of Fernet KeysBeta Release StatusCritical Considerations for Optimal UsageRisk DisclaimerChange-logConclusionRequirementsPython: ~=3.10cryptography: ~=41.0.4pycryptodome: ~=3.20.0numpy: ~=1.26.3psutil: ~=5.9.7pytest: ~=7.4.3setuptools: ~=68.2.2This project mandates the use ofPython 3.10or later versions. Compatibility issues have been identified withPython 3.9due to the utilization of thekw_onlyparameter in dataclasses, a critical component for the project. It is important to note that the project may undergo a more stringent backward compatibility structure in the near future.InstallationTo useCipherEnginein your Python project, you can install it via pip. Open your terminal or command prompt and run the following command:pipinstallcipher-engine
pipinstall-rrequirements.txtPrimary FeaturesData Encryption and DecryptionSecurely encrypt and decrypt data (files/strings) using symmetric key cryptography, incorporating advanced security measures.Text Encryption and DecryptionEffortlessly encrypt and decrypt text data, ensuring confidentiality with robust cryptographic techniques.<class-engine>.(en/de)crypt_text- Rapidly encrypts and decrypts text data while providing essential information for seamless on-the-go operations.Passphrase Generation and Key DerivationGenerate highly secure passphrases with customizable options to strengthen the foundation of your cryptographic keys.Utilizes advanced key derivation functions, including PBKDF2, to enhance the security of your cryptographic keys and protect against brute-force attacks.Refer toKey Generationfor additional details.Backup ManagementOpt for optional creation of backups for original files before encryption, offering a safety net for data preservation.Efficiently restore files to their original state during the decryption process ifoverwrite_fileparameter is set to True.Export Passkey Configuration FileFacilitates the exportation of the passkey configuration file into a distinct file, ensuring that sensitive information is handled with the utmost care.Offers the flexibility to choose any serialization formats for the exported passkey file.Default serialization is .cfgThe exported passkey file contains essential cryptographic details, including the passkey, hash value, and encryption identifiers, ensuring the secure management of cryptographic operations.The exported passkey file can be used for subsequent cryptographic operations, offering a convenient means to manage and transmit cryptographic details.The file can be easily shared with authorized personnel to facilitate secure decryption operations.The following encryption details are included in the exported passkey file:original_file: The original file to be encrypted.encrypted_file: The encrypted file.original_text: The original text to be encrypted.encrypted_text: The encrypted text.decipher_keys: The Fernet keys used for decryption.(file_)hash_value: The cryptographic hash value of the data.id1andid2: The unique encryption identifiers.iterations: The number of iterations for key derivation.passkey: The passphrase used for encryption.r_and_p: The number of rounds and parallelism for key derivation.salt_bytes_size: The size of the salt bytes.salt_values: The salt values used for key derivation.aes_iv: The initialization vector for AES encryption.aes_passkey: The passphrase used for AES encryption.Quick File Encryption[CIPHER_INFO]
original_file = /Python/Projects/CipherEngine/tests/test_files/test_quick_engines.txt
encrypted_file = /Python/Projects/CipherEngine/tests/test_files/test_quick_engines.txt

[SECURITY_PARAMS]
hash_value = db740f4d0a400f6320b9af9efc30204c96b3b605ec68a41bb95efab93d755b1a882e1ddced0f48190153bf694fc43829ea58754ade52905ba17ae9ea78e5433f
passkey = ('quick_password', 'NjBjNGNiMjIzYjZkNDE2YWVlNTE0OGRhYzdhMjk5MjI=')Quick Text Encryption[CIPHER_INFO]
original_text = testing quick engines.
encrypted_text = gAAAAABlwa-GqjyR5v1B2g1ukvlLM_aenXrLqeuyeRhVsBxjUtvqIsx6IMD7O-HmDvnvBOC4Z0nZJlS2kXaQX3vTqWjO53FT4_DyPzvW44o68RoJmCsC9j0=

[SECURITY_PARAMS]
hash_value = e77579463f45f559ca59f1ab19fdd62afd3fc9e261a2badd6e6a3c830df9e94468186407cbbdef4cae69941c16050e8dee7cc7425c4e5c2f5aec85033dca9030
passkey = ('quick_password', 'NjBjNGNiMjIzYjZkNDE2YWVlNTE0OGRhYzdhMjk5MjI=')Basic File Encryption[CIPHER_INFO]
original_file = /Python/Projects/CipherEngine/tests/test_files/test_unencrypted_file.txt
encrypted_file = /Python/Projects/CipherEngine/tests/test_files/encrypted_test_unencrypted_file.aes

[SECURITY_PARAMS]
file_hash_value = 7be22ca40f8ebd9495e53d7951aaa0377a63239acfd071f0eaef34a1e4f7dc8879928c198b4c806ac5bcd93e6b67d6cba995b31fc4851b7eadc59682712f1acd
decipher_keys = ('500H3iVB-9YQVthE4yNaOGPG6KsreJw7RVYP0z74TfU=', 'fh4VSiKW8M8NlqU8Ty0Ba_WJakMNZdPlj9Bl0cuXU4c=')
hash_value = 7be22ca40f8ebd9495e53d7951aaa0377a63239acfd071f0eaef34a1e4f7dc8879928c198b4c806ac5bcd93e6b67d6cba995b31fc4851b7eadc59682712f1acd
id1 = -----BEGIN CIPHERENGINE ENCRYPTED KEY-----
id2 = -----END CIPHERENGINE ENCRYPTED KEY-----
iterations = 1024
passkey = ('cg284LfecTpV1cnK6kzz2ieIqZlHbADZ', '593263794f44524d5a6d566a564842574d574e75537a5a72656e6f796157564a6356707353474a4252466f3d')
r_and_p = (8, 1)
salt_bytes_size = 32
salt_values = ('732c5e2ea527a51e62adcddaac8cecb28befdf1e54f4919a2a8515f308dee97f', '732c5e2ea527a51e62adcddaac8cecb28befdf1e54f4919a2a8515f308dee97f')Basic Text Encryption[CIPHER_INFO]
original_text = plaintext
encrypted_text = -----BEGIN CIPHERENGINE ENCRYPTED KEY-----gAAAAABlwVYhwuPX4KfRxjlN8a-_CQ-07mKvcB8pkUcZZNxD9BvBg0gIDsHtzYo5wq0aDGNba2X20sEzjUjeoZZyRE6_yuDDoQ==-----END CIPHERENGINE ENCRYPTED KEY-----

[SECURITY_PARAMS]
decipher_keys = ('zugxkADC_5-JGcXNX4gcK54bAjqWf3oCA6HuaEPolFY=', 'MXgml8ajCw_Lv_cmlw2ifNWKnEhHBmUt0O_PI_0-l9s=')
hash_value = d1b9457d6b063e86a2d85215f36fc98a301086adcd3c2a46748c8aad105a32939c0a203f4e67bafbf9a9b090db883d08f411297504b5625a3432b8876640c46a
id1 = -----BEGIN CIPHERENGINE ENCRYPTED KEY-----
id2 = -----END CIPHERENGINE ENCRYPTED KEY-----
iterations = 1024
passkey = ('133wCh1r6zxYJzKwugZgxVlKj48ITQ1u', '4d544d7a64304e6f4d584932656e685a536e704c6433566e576d6434566d784c616a5134535652524d58553d')
r_and_p = (8, 1)
salt_bytes_size = 32
salt_values = ('62eb790e2881edc5ba2b109e7f1ce1776ade245de62682373075d944f87f0536', '62eb790e2881edc5ba2b109e7f1ce1776ade245de62682373075d944f87f0536')AES Text Encryption[CIPHER_INFO]
original_text = plaintext
encrypted_text = beginning_headergAAAAABlwa7J7ox_a2zllVoy_H_9ddqbZNVCzy9hF8_rDMD5zRDT8bwd9TWD6ljyNkBvPFvGN40dkwEze3YCN822mGvrk_0IT-dLZVDoZtF0Gd32FuInSag=ending_header

[SECURITY_PARAMS]
decipher_keys = ('zZs4QClkE0sdMLjdbecfR3s_jQ1DyYWUrwwg_0f7XCo=', 'WVnlnwA47R_LzC6DqccJ9dvX5r1FeV8dLX_2320DUaU=', 'Jp6vQZZYE2QEYiUv-7OrjG4kqjCV8BDCitKxqAFim4c=')
hash_value = d1b9457d6b063e86a2d85215f36fc98a301086adcd3c2a46748c8aad105a32939c0a203f4e67bafbf9a9b090db883d08f411297504b5625a3432b8876640c46a
id1 = beginning_header
id2 = ending_header
iterations = 1024
passkey = ('password123', '70617373776f7264313233')
r_and_p = (8, 1)
salt_bytes_size = 32
salt_values = ('44e42ea54cba9d473b51a3c6ce5a3768be6ecabc9a2088f6ea70af9d3632922f', '44e42ea54cba9d473b51a3c6ce5a3768be6ecabc9a2088f6ea70af9d3632922f', '44e42ea54cba9d473b51a3c6ce5a3768be6ecabc9a2088f6ea70af9d3632922f')
aes_iv = ab9e7e504095d382baf9f4d31e2b52ae
aes_passkey = ('AESpassword123', '3464663135303362623666613338656434626138616261306334633637653038')Data Integrity Assurance MechanismCryptographic Hash Generation: Upon the initial processing of a file or text string, the CipherEngine generates a unique cryptographic hash value for that specific data. This hash serves as a tamper-evident representation of the content, as any alterations to the data will result in a distinct hash value.@classmethoddef_calc_file_hash(cls,fp:P)->str:file=cls._validate_file(fp)sha512_hash=SHA512.new()withopen(fp,"rb")asfile:forchunkiniter(lambda:file.read(4096),b""):sha512_hash.update(chunk)returnsha512_hash.hexdigest()@classmethoddef_calc_str_hash(cls,string:str=None,encode=True)->str:s=stringifnotencodeelsestring.encode()returnSHA512.new(data=s).hexdigest()Cryptographic Hash Comparison: The current hash value of the data is compared to the stored hash value in the passkey configuration file. Any disparities between these values indicate potential unauthorized changes to the data.Additionally checks if the encrypted data starts and ends with the designated encryption identifier. This step ensures the correct application of encryption and further validates the data's integrity.Enhanced Security MeasuresOverviewTheCipherEnginelibrary incorporates a wide range of security measures to ensure the confidentiality and integrity of your data. These measures include:Unique Encryption IdentifiersIntroduce a uniqueidentifiersduring encryption to enhance security and protect against potential vulnerabilities.This unique identifier that is generated during the encryption process and is appended to the beginning of the encrypted file. It is used to verify the integrity of the encrypted file during the decryption process, ensuring that the file has not been tampered with.The defaultidentifiersis as follows:-----BEGIN CIPHERENGINE ENCRYPTED KEY----------END CIPHERENGINE ENCRYPTED KEY-----Multiple Fernet Keys with MultiFernetMultiFernetis a class that allows for the combination of multipleFernetkeys into a single key. This class is used to generate a unique key for each encryption process, ensuring that the same key is not used for multiple encryption processes.Fernetis a class that offers symmetric encryption based on the AES algorithm in CBC mode with a 128-bit key for encryption and HMAC for authentication. It is used to encrypt and decrypt data, ensuring confidentiality and integrity.Scrypt Key Derivation FunctionTheCipherEnginelibrary employs the scrypt Key Derivation Function (KDF) for secure key derivation. This enhances the security of cryptographic operations by deriving a key from a passphrase.The scrypt KDF is a key derivation function designed to be secure against hardware attacks and is well-suited for password-based key derivation.Advanced Encryption AlgorithmsTheCipherEnginelibrary provides support for advanced encryption algorithms, including:SHA512 Hashing: The SHA512 algorithm is employed for secure cryptographic hashing.AES Encryption: Utilizes the AES algorithm for strong encryption.Padding and Unpadding: Implements padding and unpadding techniques to ensure data integrity.TheCipherEngineis designed to offer a comprehensive and on-the-go secure method for cryptographic operations, leveraging industry-standard techniques to safeguard your sensitive data.Key GenerationOverviewgenerate_crypto_keyis a comprehensive method that provides a robust and flexible key generation mechanism, allowing you to create keys tailored to your specific security needs.When generating cryptographic keys using thegenerate_crypto_keymethod, you have the flexibility to customize the key based on specific character sets. (Refer toCharacter Set Exclusion Optionsfor additional details and reference.)Can also be accessed through any class engines using<class engine>._generate_keyThe<class engine>._generate_keymethod serves as the foundational backbone for thegenerate_crypto_keyfunctionality.Code Base@classmethoddef_generate_key(cls,*,key_length:int=32,exclude:str="",# Defaults to punctuationinclude_all_chars:bool=False,bypass_keylength:bool=False,repeat:int=None,urlsafe_encoding:bool=False)->str:Method Signature:_generate_keyis a class method, allowing it to be accessed through any class engines. It takes parameters such askey_length,exclude,include_all_chars,bypass_keylength,repeat, andurlsafe_encodingproviding customization options for key generation.ifall((exclude,include_all_chars)):raiseCipherException("Cannot specify both 'exclude' and 'include_all_chars' arguments.")Conflict Check: The method checks for conflicting arguments. If bothexcludeandinclude_all_charsare specified, it raises aCipherExceptionto ensure proper usage.ifnotbypass_keylengthandkey_length<cls._MAX_KEYLENGTH:raiseCipherException(f"For security reasons, the passkey must have a length of at least{cls._MAX_KEYLENGTH}characters. ""If a shorter key is desired, provide a 'bypass_keylength' parameter.")too_large=any((repeat_val>cls._MAX_CAPACITY,key_length>cls._MAX_CAPACITY))iftoo_large:ifnotbypass_keylength:raiseCipherException(f"The specified counts surpasses the computational capacity required for{cls.__name__!r}. ""It is recommended to use a count of 32 <= x <= 512, considering the specified 'key_length'."f"\nMax Capacity:{cls._MAX_CAPACITY:_}"f"\nCharacter Repeat Count:{repeat_val:_}")elifbypass_keylength:CipherException("The specified count(s) indicate a potentially high magnitude. ""Please take into account the substantial computational resources that may be required to process such large values.",log_method=logger.info,)Key Length Range Check: Ensures thatkey_lengthfalls within the specified range unlessbypass_keylengthis set toTrue.slicer=lambda*args:''.join(islice(*args,cls._MAX_TOKENS))all_chars=slicer(cycle(cls._ALL_CHARS))filtered_chars=cls._filter_chars(all_chars,exclude=punctuation)Character Slicing: Utilizes theislicefunction to slice characters based on the calculatedMAX_TOKENS. Generates all available characters and filters them based on the exclusion list.ifinclude_all_chars:filtered_chars=all_charsInclude All Characters: Ifinclude_all_charsis specified, the filtered characters are set to include all available characters.Exclude Characters: Ifexcludeis specified, it validates and filters characters based on the exclusion criteria.ifexclude:exclude_obj=cls._validate_object(exclude,type_is=str,arg='exclude_chars')filter_char=partial(cls._filter_chars,all_chars)exclude_type=cls._exclude_type(exclude_obj)filtered_chars=filter_char(exclude=exclude)ifnotexclude_typeelse\filter_char(exclude=exclude_type)Cryptographically Secure Randomized Key Generation: Harnesses the cryptographic strength ofSystemRandomto sample characters randomly from the filtered set, ensuring a secure and unpredictable key. The sampling is based on the minimum ofkey_lenand the available characters, providing a robust foundation for cryptographic key generation.passkey=SystemRandom().sample(population=filtered_chars,k=min(key_len,len(filtered_chars)))encryption_key=''.join(passkey)All Available CharactersASCII letters: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZDigits: 0123456789Hexdigits: 0123456789abcdefABCDEFPunctuation: !"#$%&'()*+,-./:;<=>?@[]^_`{|}~Whitespace: '(space)\t\n\r\v\f'' ' (space), '\t' (tab), '\n' (newline), '\r' (carriage return), '\x0b' (vertical tab), '\x0c' (form feed)Please note thatWhitespaceis automatically excluded from all available options. Its inclusion could disrupt the encryption process when exporting data to a configuration file and is unnecessary for cryptographic operations.*Character Set Exclusion OptionsExclusion Chart{"punct":punctuation,"ascii":ascii_letters,"ascii_lower":ascii_lowercase,"ascii_upper":ascii_uppercase,"ascii_punct":ascii_letters+punctuation,"ascii_lower_punct":ascii_lowercase+punctuation,"ascii_upper_punct":ascii_uppercase+punctuation,"digits":digits,"digits_ascii":digits+ascii_letters,"digits_punct":digits+punctuation,"digits_ascii_lower":digits+ascii_lowercase,"digits_ascii_upper":digits+ascii_uppercase,"digits_ascii_lower_punct":digits+ascii_lowercase+punctuation,"digits_ascii_upper_punct":digits+ascii_uppercase+punctuation,"hexdigits":hexdigits,"hexdigits_punct":hexdigits+punctuation,"hexdigits_ascii":hexdigits+ascii_letters,"hexdigits_ascii_lower":hexdigits+ascii_lowercase,"hexdigits_ascii_upper":hexdigits+ascii_uppercase,"hexdigits_ascii_punct":hexdigits+punctuation,"hexdigits_ascii_lower_punct":hexdigits+ascii_lowercase+punctuation,"hexdigits_ascii_upper_punct":hexdigits+ascii_uppercase+punctuation,}Exclusion Examplescrypto_key=generate_crypto_key(exclude=<str>)# Alternatively, generate a key using any of the class engines.crypto_key=<class-engine>._generate_key(exclude=<str>)punct:Excludes punctuation characters.xXLyv16WONtWW1s8ri1lfF8suJzzHqSfascii:Excludes ASCII letters (both uppercase and lowercase)._$9{92|66!6+)0<69{>},<*[/{97'ascii_lower:Excludes lowercase ASCII letters.B#F+=KE<9(DPDQ|)~5ALP,V//*4S>=ascii_upper:Excludes uppercase ASCII letters.guzgs5[6(9["(8d8k[g,7=$8?-9i{^*)ascii_punct:Excludes all ASCII letters and punctuations.22947751028796725748955353648359ascii_lower_punct:Excludes both lowercase ASCII letters and punctuation characters.Y2UJIEDBUO2AXD2SAET2QJL7LR6P776Nascii_upper_punct:Excludes both uppercase ASCII letters and punctuation characters.f1021qygcqbzd6bfaac9ng9nitpehozydigits:Excludes all digits..@->htEqNvSv/`a.+E-lJ)mzL("#~qdigits_ascii:Excludes both digits and ASCII letters.{[[:=#,{_(-%#:)](&.^@.~:_@digits_punct:Excludes both digits and punctuation characters.NsLkBkXWlQgUQLsVYQeksbWKJqtOmxqZdigits_ascii_lower:Excludes both digits and lowercase ASCII letters.|UH[E&JF"HIIS#,,-|B#S)D/+H|_(?\digits_ascii_upper:Excludes both digits and uppercase ASCII letters.w$=q.:_&,vvm<'s?++'i\$o!|d@~(wdigits_ascii_lower_punct:Excludes digits, lowercase ASCII letters, and punctuation characters.UHSTDQQZWVAHBFLMZYKUXIDXSTTPLQXEdigits_ascii_upper_punct:Excludes digits, uppercase ASCII letters, and punctuation characters.dhwzxoqzubwmrieyerpxrfttfeohacxlhexdigits:Excludes hexdigit characters|;gMWX;P\UuuN^\k{m|x=~hMOR}<[H=-hexdigits_punct:Excludes hexdigits and punctuation characters.jXnVVJxHtPSlTHytKiNYGslRisrypIoohexdigits_ascii:Excludes hexdigits and ASCII letters..":"&.&`!.@]'+-<}+<<,!~,~>hexdigits_ascii_lower:Excludes hexdigits and lowercase ASCII characters.#OW_R>R;UJ;J@U#X'=:+>TIQ+}{K@S|Uhexdigits_ascii_upper:Excludes hexdigits and uppercaseASCII characters.[+y/.]*?ls$jh\r!gy<^or%j)l~:w!'hexdigits_ascii_lower_punct:Excludes hexdigits and lowercase ASCII letters and punctuation characters.XHYMPXJLPXOOMYSYYGWRYYNUXYPTZRRThexdigits_ascii_upper_punct:Excludes hexdigits and uppercase ASCII letters and punctuation characters.xjhvyqswzjoopqnnghwzntioryothxilCipherEngine ClassOverviewCipherEngineis a comprehensive Python library designed for encrypting and decrypting files and text data using symmetric key cryptography. It employs secure algorithms and encompasses featuresFernetandMultiFernet, encryption headers, and file/text integrity checks.Attributesfile: str | Path | None: The file to be processed and encrypted.text: str | None: The text to be processed and encrypted.file_name: str | None: The name of the file containing the encryption details.passkey: str | int | None: The passphrase or integer to be used for encryption (default: None).gui_passphrase: bool: Flag indicating whether to use GUI for passphrase entry (default: False).num_of_salts: int: Number ofFernetkeys to be generated and processed withMultiFernet.export_path: Path | None: The path where exported files will be stored (default: None).export_passkey: bool: Flag indicating whether to export the passphrase to a separate file (default: True).serializer: str | None: The type of serialization to be used for exporting the passkey file ('json' or 'ini').iterations: int | None: The number of iterations for key derivation (default: None).min_power: bool: Flag indicating whether to enforce minimum passphrase strength (default: False).max_power: bool: Flag indicating whether to enforce maximum passphrase strength (default: False).advanced_encryption: bool: Flag indicating whether to use advanced encryption features (default: False).special_keys: bool | None: If True, uses CipherEngine's custom cryptographic key generation, otherwise uses default keys generated fromFernet(default: None).Cryptographic Attributes:key_length: int: The desired key length for Fernet encryption (default: 32).bypass_keylength: bool: Flag indicating whether to bypass key length validation (default: False).include_all_chars: bool: Flag indicating whether to include all characters during passphrase generation (default: False).exclude_chars: str | None: Characters to exclude during passphrase generation (default: None).Methodsencrypt_file(): Encrypts a specified file.encrypt_text(): Encrypts a specified text.quick_encrypt(): Encrypts a specified text using onlyFernet.Examplecipher=CipherEngine(passkey='my_secret_key',num_of_keys=50)cipher.encrypt_file()DecipherEngine ClassOverviewTheDecipherEngineclass, an extension of the CipherEngine, is dedicated to decrypting data encrypted through the CipherEngine. It seamlessly operates with configuration files or NamedTuples generated by the CipherEngine during the encryption process.Attributesciphertuple(NamedTuple): A NamedTuple containing details generated during the quick encryption process. It includes information such as the algorithm type, passkey, encrypted text, hash type, hash value, CPU power, original text, and salt value.passkey_file: str | Path: The path to the file containing the encryption details.overwrite_file: bool | None: Flag indicating whether to overwrite the original file during decryption (default: False).manual_kwgs: dict: Dictionary containing encryption data to be used for decryption.Methodsdecrypt_file(): Decrypts an encrypted file.decrypt_text(): Decrypts encrypted text.quick_decrypt(): Quickly decrypts text data and exports necessary information on-the-go.Exampledecipher=DecipherEngine(passkey_file='encrypted_file_passkey.ini')decipher.decrypt_file()Class Engine Return StateCipherTupleEvery method in theCipherEngineandDecipherEngineclasses yields aNamedTupleinstance identified asCipherTuple. This intentional design choice simplifies referencing, offering a convenient means to manage and transmit the outcomes of cryptographic operations.This NamedTuple (ciphertuple) can be effortlessly employed within the corresponding classes, alleviating the requirement for explicit attribute specifications in subsequent cryptographic procedures. This design enhances usability and promotes a more streamlined cryptographic workflow.Usage ExamplesImport Modulefromcipher_engineimport*# __all__ = (# "METADATA",# "CipherEngine",# "DecipherEngine",# "CipherException",# "generate_crypto_key",# "encrypt_file",# "decrypt_file",# "encrypt_text",# "decrypt_text",# "quick_encrypt",# "quick_decrypt",)Generate a Secure Cryptographic Key# Generate a cryptographic key using specified parameterscrypto_key=generate_crypto_key(key_length=int(1e5))# Output: Mc2nTJ2zosmNxEu6cXF99lapaEEgWxjt....crypto_key=generate_crypto_key(include_all_chars=True)# Output: YGWm;2]-vLT*YS;My/mm5e\B[db$xfIcrypto_key=generate_crypto_key(exclude='digits_punct')# Output: wmsjRLFxnVmXJfHGzjVNgWtRogZZQeGsEncrypt Text using encrypt_text# Encrypt text using CipherEngine.encrypt_textresult_encrypt_text=encrypt_text(text='Hello, World!',num_of_keys=20,export_path='output')# Output: (NamedTuple)CipherTuple(original_text='hello',encrypted_text='-----BEGIN CIPHERENGINE ENCRYPTED KEY-----gAAAAABlwcnmXXDioh1crkkbEwmY5qBe6Qun0_qzXZefWcAwxhqbAsw8giX0m6Tx4LXcv9fFOhILuwX9ROFeQD_4zgXToU72jw==-----END CIPHERENGINE ENCRYPTED KEY-----',decipher_keys=('6jzNzRksHQnv3MzzoLADhtHppSPK2WCQd420mlirsEw=','M8nD8Z9gHs5Qug15GIws09bP2zi18c_XWdwx5DlOKvg='),hash_value='9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043',id1='-----BEGIN CIPHERENGINE ENCRYPTED KEY-----',id2='-----END CIPHERENGINE ENCRYPTED KEY-----',iterations=1048576,passkey=('R5yQK8BwvNWEsDRsxMuN8zuooVryjLxk','556a563555557334516e6432546c6446633052536333684e64553434656e567662315a796557704d6547733d'),r_and_p=(8,1),salt_bytes_size=32,salt_values=('bf0318472989375bdcc6ee565f488a81c44b0bc2d9466e33a4412872d49b89c0','bf0318472989375bdcc6ee565f488a81c44b0bc2d9466e33a4412872d49b89c0'))Decrypt text using decrypt_text# Decrypt text using DecipherEngine.decrypt_textdecrypt_text(ciphertuple=result_encrypt_text)# Alternatively, can pass in the attributes manuallyresult_decrypt_text=decrypt_text(passkey_file='output/info.ini',export_path='output/decrypted',overwrite_file=True)# Output: (NamedTuple)DecipherTuple(decrypted_text='unencrypted-text',hash_value='9deabffbf5b50efd1f9b75133edf33d00372599babfef5dd9d1fa5425610ad6643c03b4f5ea6c32b7d8ec5f1891de6c297f1a04a3344f7e16c497354ce7736a6')Encrypt a file using encrypt_file# Encrypt a file using CipherEngine.encrypt_fileresult_encrypt_file=encrypt_file(file='test.txt',overwrite_file=False,export_path='output')# Output: (NamedTuple)CipherTuple(original_file=PosixPath('test.txt'),encrypted_file=PosixPath('encrypted_test.aes'),file_hash_value='04ca92b5d6deaae50d209010ed4bd2a5299b527b2a878218bde3ee5bbf782b38471df2db2822b18a768af8d65cb93428ff2a4312da8e8339a5f0272d67e2e191',decipher_keys=('kY7w1vAXB8RJ_4FpfymtSP1u5LPhBFk-FNHtv_7RYgM=','awH-KMrjB47xinZ3hd_QsKe80vU1hwIivNNYQYbuXdQ='),hash_value='04ca92b5d6deaae50d209010ed4bd2a5299b527b2a878218bde3ee5bbf782b38471df2db2822b18a768af8d65cb93428ff2a4312da8e8339a5f0272d67e2e191',id1='-----BEGIN CIPHERENGINE ENCRYPTED KEY-----',id2='-----END CIPHERENGINE ENCRYPTED KEY-----',iterations=1024,passkey=('ozoGWjOqDxQ55qcV5J1VUOFMLrVQiMOS','623370765231647154334645654645314e58466a566a564b4d565a5654305a4e54484a5755576c4e54314d3d'),r_and_p=(8,1),salt_bytes_size=32,salt_values=('8333f1ef6079337e3c60c2aff72fc544ad2efc9349c17b891484dabc9b3501cf','8333f1ef6079337e3c60c2aff72fc544ad2efc9349c17b891484dabc9b3501cf'))Decrypt a file using decrypt_file# Decrypt a file using DecipherEngine.decrypt_fileresult_decrypt_file=decrypt_file(passkey_file='output/test_passkey.ini',overwrite_file=False)# Output: (NamedTuple)DecipherTuple(decrypted_file=PosixPath('decrypted_encrypted_test.dec'),hash_value='04ca92b5d6deaae50d209010ed4bd2a5299b527b2a878218bde3ee5bbf782b38471df2db2822b18a768af8d65cb93428ff2a4312da8e8339a5f0272d67e2e191')Quickly Encrypt Files using quick_encryptquick_encrypt(file="test.aes")# Output: (NamedTuple)QCipherTuple(original_file=PosixPath('test.aes'),encrypted_file=PosixPath('encrypted_test.aes'),hash_value='04ca92b5d6deaae50d209010ed4bd2a5299b527b2a878218bde3ee5bbf782b38471df2db2822b18a768af8d65cb93428ff2a4312da8e8339a5f0272d67e2e191',passkey=('yuQYlxGuDSG97YSdzDOZvOrjq88gfOnb','OWIxN2RkOThhM2I1ZjVhMzA2MTVlYzlhYTA3NDA3NDM='))Quickly Decrypt Files using quick_decryptquick_decrypt(ciphertuple=a)# Output: (NamedTuple)QDecipherTuple(decrypted_file=PosixPath('encrypted_test.aes'),hash_value='04ca92b5d6deaae50d209010ed4bd2a5299b527b2a878218bde3ee5bbf782b38471df2db2822b18a768af8d65cb93428ff2a4312da8e8339a5f0272d67e2e191')Quickly Encrypt Text using quick_encryptquick_encrypt(text="unencrypted-text")# Output: (NamedTuple)QCipherTuple(original_text='unencrypted-text',encrypted_text='gAAAAABlwcvyACkfYqf3Zw1ShY2MpNwnAA9eZSa0phLlOuFYy1F-26ExIRuCowaSnbFxIr9TKCnSAnYccO9TH2595ez0sGboS57XP4AFAU9xh5gDtac7UOU=',hash_value='9deabffbf5b50efd1f9b75133edf33d00372599babfef5dd9d1fa5425610ad6643c03b4f5ea6c32b7d8ec5f1891de6c297f1a04a3344f7e16c497354ce7736a6',passkey=('AzgV81oCpXe8G9apFs3PqY9vCgBAwacu','ZjFkOWUyYmNkOTYyMjFhZWIwZTQwZmQ0OWNmMWU3NGU='))Quickly Decrypt Text using quick_decryptquick_decrypt(ciphertuple=a)# Output: (NamedTuple)QDecipherTuple(decrypted_text='unencrypted-text',hash_value='9deabffbf5b50efd1f9b75133edf33d00372599babfef5dd9d1fa5425610ad6643c03b4f5ea6c32b7d8ec5f1891de6c297f1a04a3344f7e16c497354ce7736a6')Command-Line Interface (CLI)TheCipherEnginelibrary offers a comprehensive CLI tool for seamless encryption and decryption of files and text data. This tool is designed to provide a user-friendly interface for theCipherEnginelibrary, allowing users to leverage the library's powerful features with ease.The CLI tool is no longer in development and is readily accessible for utilization. For a comprehensive understanding of its functionalities, kindly refer to theCLI-OPTIONSdocumentation for additional details.RoadmapUpcoming FeaturesPersonal Unique Encryption Identifier: Provide users with the option to specify a personalized encryption header, allowing them to define a unique identifier according to their preferences, rather than relying on the default setting.Performance Optimization: Focus on optimizing performance to reduce computational overhead, particularly during encryption and decryption processes with higher iteration counts. These enhancements aim to streamline and expedite cryptographic operations for improved efficiency.CLI-Implementation: Integrate all cipher engine methods and features into a comprehensive CLI tool, allowing users to seamlessly encrypt and decrypt data from the command line.This project is continuously evolving, and these features are anticipated to be implemented in future releasesProgress TableImplement quick ciphers using only FernetImplement AES encryptionPersonal Unique Encryption IdentifierPerformance OptimizationCLI-ImplementationThe forthcoming features are crafted to enhance user flexibility and customization within the class engines, offering a personalized and tailored experience to accommodate diverse encryption needs. This tool prioritizes granting users autonomy over their encryption tools, guaranteeing effortless usage.Contributors and FeedbackTheCipherEngineproject welcomes contributions from the community to enhance its features and reliability. If you are interested in contributing, please follow the guidelines below:ContributingStepAction1.Fork the repository onGitHuband clone it to your local machine.2.Create a new branch for your feature or bug fix:git checkout -b feature/your-featureorgit checkout -b bugfix/your-bug-fix.3.Make your modifications and ensure that the code follows the project's coding standards.4.Test your changes thoroughly to ensure they do not introduce any issues.5.Commit your changes with clear and concise messages:git commit -m "Your informative commit message".6.Push your branch to your fork on GitHub:git push origin feature/your-feature.7.Open a pull request on themain repositorywith a detailed description of your changes.FeedbackFeedback is crucial for the improvement of theCipherEngineproject. If you encounter any issues, have suggestions, or want to share your experience, please consider the following channels:GitHub Issues: Open an issue on theGitHub repositoryto report bugs or suggest enhancements.Contact: Reach out to the project maintainer via the following:Contact Information- [Discord](https://discord.com/users/581590351165259793)
- [Gmail](yousefzahrieh17@gmail.com)Your feedback and contributions play a significant role in making theCipherEngineproject more robust and valuable for the community. Thank you for being part of this endeavor!Important NotesMaximum Number of Fernet KeysThe maximum number of Fernet keys that can be generated is unrestristed. However, it is important to note that the number of keys generated is directly proportional to the time required for encryption and decryption processes. Therefore, it is recommended to generate a reasonable number of keys to ensure optimal performance.Caution is advised when utilizing this feature, as it may demand significant computational resources despite the code's efficiency.Beta Release StatusThis project is currently in beta release, demonstrating efficient functionality and consistent success in all conducted tests (pytest).A comprehensive algorithm to guarantee the non-existence of specific files with default or specified names has not been extensively developed. This pertains to both encryption and decryption processes, contingent on parameters such as overwrite_file and file_name.The verification of specified data for all methods incorporates an encryption identifier checking tool has only been implemented forencrypt/decryptfiles at the moment.Critical Considerations for Optimal UsageAfter extensive testing and experimentation, this project can prove to be an invaluable tool when certain precautions are observed:Properly storing the encrypted data's passkey files.Refraining from making alterations on any files, including the passkey file, which is vital for the integrity of the encryption process.It is important to note that encrypting the same file multiple times and decrypting it based on the number of times was achieved. However, it is pertinent to highlight that a bypass method to do so will not be implemented. It is essential to recognize that such practices may not enhance the security of the encryption and could potentially lead to severe data loss if not used correctly, particularly when employing identical encryption modes for relevant decryption processes.In the event that an encryption identifier is detected at the beginning of the encrypted file during an encryption attempt, an error will be raised prior to further processing.Risk DisclaimerEnsuring the proper and secure handling of data is of paramount importance when employing theCipherEnginelibrary. To minimize the risk of potential data loss, consider the following guidelines:Backup File Parameter: Always make use of thebackup_fileparameter to generate backups of your original files before initiating the encryption process. This provides an added layer of safety, allowing you to restore data in case of unexpected issues.Imperfect Encryption: It's essential to recognize that, despite robust encryption measures, no encryption method can be deemed entirely infallible. Under specific circumstances, encrypted data may still be susceptible to decryption. Be cognizant of the inherent limitations and complexities involved in cryptographic processes.USE AT YOUR OWN RISK: The author of theCipherEnginelibrary holds no responsibility for any data loss that may occur during the usage of the library. Users are advised to exercise caution, adhere to best practices, and implement proper backup procedures to mitigate potential risks.Exercise responsibility and vigilance in your usage of the library, keeping these considerations in mind. Understand that while theCipherEngineoffers powerful encryption and decryption capabilities, it is not exempt from potential risks associated with the broader landscape of data security.ConclusionIn summary, theCipherEngineproject presents a versatile and robust framework for symmetric key cryptography. Discover the available classes and methods to seamlessly incorporate secure encryption and decryption functionality into your Python projects.