cipher-engine 0.2.2

Versatile cryptographic utility designed for secure encryption and decryption operations. It supports various cryptographic algorithms, implements key derivation functions, and facilitates secure storage using INI/JSON serializations.

CipherEngine

Welcome to CipherEngine, a powerful Python library dedicated to symmetric key cryptography. This README offers a detailed exploration of the library, highlighting key features, enhanced security measures, and practical usage examples. Please refer to the table of contents below to navigate through the document.

Table of Contents

• Requirements
• Primary Features
• Enhanced Security Measures
• Key Generation
  • All Available Characters
  • Character Set Exclusion Options
    • Exclusion Chart
    • Exclusion Examples
• CipherEngine Class
  • Overview
  • Attributes
  • Methods
  • Example
• DecipherEngine Class
  • Overview
  • Attributes
  • Methods
  • Example
• Class Engine Return State
• Installation
• Usage Examples
  • Generate a Secure Cryptographic Key
  • Quickly Encrypt/Decrypt Text With Ease
  • Encrypt Text using CipherEngine.encrypt_text
  • Encrypt a file using CipherEngine.encrypt_file
• Roadmap
  • Features
  • Progress Table
• Contributors and Feedback
  • Contributing
  • Feedback
• Important Notes
• Risk Disclaimer
• Conclusion

---

Requirements

• Python: 3.10 or above

  This project specifically requires Python 3.10. Compatibility issues have been identified when using Python 3.9 due to the usage of the kw_only parameter for dataclasses, which is crucial for this project.

• cryptography: ~=41.0.4

• numpy: ~=1.26.3

• psutil: ~=5.9.7

• pytest: ~=7.4.3

• setuptools: ~=68.2.2

---

Primary Features

• Data Encryption and Decryption: Securely encrypt and decrypt data (files/strings) using symmetric key cryptography, incorporating advanced security measures.

• Text Encryption and Decryption: Effortlessly encrypt and decrypt text data, ensuring confidentiality with robust cryptographic techniques.

  quick_(encrypt/decrypt) - Rapidly encrypts and decrypts text data while providing essential information for seamless on-the-go operations.

• Passphrase Generation: Generate highly secure passphrases with customizable options to strengthen the foundation of your cryptographic keys.

• Key Derivation: Implement advanced key derivation functions, including PBKDF2, to enhance the security of your cryptographic keys and protect against brute-force attacks.

• Backup and Restore: Opt 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.

• Export Passphrase: Export passphrases to separate files for convenient and secure storage, ensuring that sensitive information is handled with the utmost care.

Enhanced Security Measures

• PBKDF2 (Password-Based Key Derivation Function 2): Strengthen cryptographic keys by making key derivation computationally intensive, thwarting potential brute-force attacks.

• Unique Encryption Identifiers: Introduce a unique identifier during encryption to enhance security and protect against potential vulnerabilities.

• Initialization Vectors (IV) and Salts: Enhance security further by incorporating Initialization Vectors (IV) and salts. IVs add unpredictability to the encryption process, preventing patterns in ciphertexts, while salts contribute to unique key derivation, preventing rainbow table attacks.

• Cipher Feedback (CFB8): Employs the Cipher Feedback (CFB8) mode from the Cipher algorithm, adding an extra layer of security to the encryption process. This mode enhances the unpredictability of ciphertexts, further fortifying the cryptographic operations performed by the CipherEngine.

The CipherEngine is designed to offer a comprehensive and secure method for cryptographic operations, leveraging industry-standard techniques to safeguard your sensitive data.

---

Key Generation

When generating cryptographic keys using the generate_crypto_key method, you have the flexibility to customize the key based on specific character sets. This allows you to tailor the keys to your security requirements and preferences.

Can also be accessed through any class engines using _generate_key

All Available Characters

• ASCII letters: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
• Digits: 0123456789
• Punctuation: !"#$%&'()*+,-./:;<=>?@[]^_`{|}~
• Whitespace: '(space)\t\n\r\v\f'
  • ' ' (space), '\t' (tab), '\n' (newline), '\r' (carriage return), '\x0b' (vertical tab), '\x0c' (form feed)

  Please note that Whitespace is automatically excluded from all available options, as it can interfere with the encryption process and is not necessary or useful for cryptographic operations.

Character Set Exclusion Options

Exclusion Chart

{
    'digits': digits
    'punct': punctuation
    'ascii': ascii_letters
    'digits_punct': digits + punctuation,
    'ascii_punct': ascii_letters + punctuation,
    'digits_ascii': digits + ascii_letters,
    'digits_ascii_lower': digits + ascii_letters.lower(),
    'digits_ascii_upper': digits + ascii_letters.upper(),
    'punct_ascii_lower': punctuation + ascii_letters.lower(),
    'punct_ascii_upper': punctuation + ascii_letters.upper(),
    'ascii_lower_punct': ascii_letters.lower() + punctuation,
    'ascii_upper_punct': ascii_letters.upper() + punctuation,
    'digits_ascii_lower_punct': digits + ascii_letters.lower() + punctuation,
    'digits_ascii_upper_punct': digits + ascii_letters.upper() + punctuation
}

Exclusion Examples

crypto_key = generate_crypto_key(exclude=<str>)
crypto_key = (De)CipherEngine._generate_key(exclude=<str>)

• digits: Excludes digits (0-9).

  .@->htEqNvSv/`a.+E-lJ)mzL("#~q

• punct: Excludes punctuation characters.

  xXLyv16WONtWW1s8ri1lfF8suJzzHqSf

• ascii: Excludes ASCII letters (both uppercase and lowercase).

  _$9{92|66!6+)0<69{>},<*[/{97'

• digits_punct: Excludes both digits and punctuation characters.

  NsLkBkXWlQgUQLsVYQeksbWKJqtOmxqZ

• ascii_punct: Excludes both ASCII letters and punctuation characters.

  14341403286159451993389011857514

• digits_ascii: Excludes both digits and ASCII letters.

  {[[:=#,{_(-%#:)](&.^@.~:_@

• digits_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@~(w

• punct_ascii_lower: Excludes both punctuation characters and lowercase ASCII letters.

  UVME559NRTZKT3P7DEHS8ROOPTYA35BF

• punct_ascii_upper: Excludes both punctuation characters and uppercase ASCII letters.

  ck05mdhi9a4csf1f4ejvru7p9kc5xpix

• ascii_lower_punct: Excludes both lowercase ASCII letters and punctuation characters.

  Y2UJIEDBUO2AXD2SAET2QJL7LR6P776N

• ascii_upper_punct: Excludes both uppercase ASCII letters and punctuation characters.

  f1021qygcqbzd6bfaac9ng9nitpehozy

• digits_ascii_lower_punct: Excludes digits, lowercase ASCII letters, and punctuation characters.

  UHSTDQQZWVAHBFLMZYKUXIDXSTTPLQXE

• digits_ascii_upper_punct: Excludes digits, uppercase ASCII letters, and punctuation characters.

  dhwzxoqzubwmrieyerpxrfttfeohacxl

---

CipherEngine Class

Overview

CipherEngine is a comprehensive Python library designed for encrypting and decrypting files and text data using symmetric key cryptography. It employs secure algorithms and encompasses features such as PBKDF2 key derivation, salt and iv generation, encryption header, and file integrity checks.

Attributes

• passkey: The passphrase or key used for encryption (optional).
• key_length: The length of the cryptographic decipher key (default: 32).
• iterations: The number of iterations for key derivation.
• exclude_chars: Characters to exclude during passphrase generation (default: punctuation).
• backup_file: Flag indicating whether to create a backup of the original file (default: True).
• export_passkey: Flag indicating whether to export the passphrase to a separate file (default: True).
• include_all_chars: Flag indicating whether to include all characters during passphrase generation (default: False).
• min_power: Flag indicating whether to use the minimum power for key derivation (default: False).
• max_power: Flag indicating whether to use the maximum power for key derivation (default: False).
• hash_type: The hash type used in encryption.
• algorithm_type: The type of algorithm used in encryption.
• serializer: The type of serialization for exporting the passkey file ('json' or 'ini').
• gui_passphrase: Flag indicating whether to use a GUI for passphrase input (default: False).
• bypass_keylength: Flag indicating whether to bypass the minimum key length requirement (default: False).

Methods

• encrypt_file(): Encrypts a specified file.
• encrypt_text(): Encrypts a specified text.
• quick_encrypt(): Quickly encrypts text data and exports necessary information on-the-go.

  Back-bone for quick_ciphertext

Example

cipher = CipherEngine(passkey='my_secret_key', iterations=1000)
cipher.encrypt_file()

---

DecipherEngine Class

Overview

The DecipherEngine class, 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.

Attributes

• ciphertuple (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.
• text (Any | None): The encrypted text to be decrypted. This parameter represents the ciphertext obtained from the encryption process.
• decipher_key (Any | None): The decryption passphrase or key required to decrypt the encrypted text. It is crucial for the successful decryption of the provided ciphertext.
• hash_value (Any | None): The hash value of the original data. This value is used for integrity checking during the decryption process. It ensures that the decrypted text matches the original data, providing data integrity verification.
• 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).
• verbose: bool | None: Flag indicating whether to print verbose messages (default: False).

Methods

• decrypt_file(): Decrypts an encrypted file.
• decrypt_text(): Decrypts encrypted text.
• quick_decrypt(): Quickly decrypts text data and exports necessary information on-the-go.

  Back-bone for quick_deciphertext

Example

decipher = DecipherEngine(passkey_file='encrypted_file_passkey.ini')
decipher.decrypt_file()

Class Engine Return State

• Each method within the CipherEngine and DecipherEngine classes returns a NamedTuple instance, providing a convenient way to handle and pass around the results of cryptographic operations.
• This NamedTuple (ciphertuple) can be seamlessly utilized within the respective classes, eliminating the need for manual specification of each attribute during subsequent cryptographic operations.

---

Installation

To use CipherEngine in your Python project, you can install it via pip. Open your terminal or command prompt and run the following command:

pip install cipher-engine

---

Usage Examples

Import Module

from cipher_engine import *
# __all__ = (
# 'CipherEngine', 'DecipherEngine',
# 'encrypt_file', 'decrypt_file',
# 'encrypt_text', 'decrypt_text',
# 'quick_ciphertext', 'quick_deciphertext',
# 'CipherException', 'generate_crypto_key',
# )

Generate a Secure Cryptographic Key

# Generate a cryptographic key using specified parameters
crypto_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$xfI

crypto_key = generate_crypto_key(exclude='digits_punct')
# Output: wmsjRLFxnVmXJfHGzjVNgWtRogZZQeGs

Quickly Encrypt/Decrypt Text With Ease

# Quick encryption of text data using CipherEngine.quick_encrypt
result_quick_ciphertext = quick_ciphertext(text='Hello, World!', export_passkey=False)
# Output: (NamedTuple)
# CipherTuple(algorithm_type='AES', decipher_key='546d746a556d746965555a464e6b4a5256553568563035584e466c4D62553172635735536355316e4D456f3d', encrypted_text='-----BEGIN CIPHERENGINE CRYPTOGRAPHIC ENCRYPTED KEY-----gAAAAABlnW67n3zkDLzoLzpTtpOVdrzKwXI5qNsqXOV8bFL34sYekvRwxAH4WciesqC3UPUBB8H7Gklm5GQdV12ZzElZrCEtEg==', hash_type='SHA512', hash_value='dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f', iterations=139239, iv_value=None, original_text='Hello, World!', salt_value=None)

# Quick decryption of text data
result_quick_deciphertext = quick_deciphertext(
    text=result_quick_ciphertext.encrypted_text,
    decipher_key='my_secret_key',
    hash_value='...'
)
# Output: (NamedTuple)
# DecipherTuple(decrypted_text='Hello, World!', hash_value='dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f')

# Preferably can pass in the NamedTuple instead.
quick_deciphertext(ciphertuple=result_quick_ciphertext)

Encrypt Text using CipherEngine.encrypt_text

# Encrypt text using CipherEngine.encrypt_text
result_encrypt_text = encrypt_text(text='Hello, World!', key_length=32, export_path='output')
# Output: (NamedTuple)
# CipherTuple(algorithm_type='AES', decipher_key='4p8keHiYD5snme5DVUU8UuxKY2A9aFTc', encrypted_text='QKZrhffcL1TWS2J2fg==', hash_type='SHA512', hash_value='dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f', iterations=139239, iv_value='bbaf9031f11a2a7ac1a8e6384d73a874', original_text='Hello, World!', salt_value='ad12ab5e72028b16a77e03a0d4f7fce0')

# Decrypt text using DecipherEngine.decrypt_text
result_decrypt_text = decrypt_text(
    ciphertuple=result_encrypt_text,
    passkey_file='output/info.ini',
    export_path='output/decrypted')
# Output: (NamedTuple)
# DecipherTuple(decrypted_text='Hello, World!', hash_value='dffd6021bb2bd5b0af676290809ec3a53191dd81c7f70a4b28688a362182986f')
# or NamedTuple
decrypt_text(ciphertuple=result_encrypt_text)

Encrypt a File using CipherEngine.encrypt_file

# Encrypt a file using CipherEngine.encrypt_file
result_encrypt_file = encrypt_file(
    file='test.txt',
    passkey=crypto_key,
    iterations=int(1e6),
    export_path='output')
# Output: (NamedTuple)
# CipherTuple(algorithm_type='AES', decipher_key='J]TTE~:vGzQ]E*?i;0br&!0,tY+zxSN^', encrypted_file='test.aes', hash_type='SHA512', hash_value='01e675506785122a5055d79a9e8fcb919c1b7838bd1d1209cd42ac67730d1f90', iterations=69619, iv_value='b26516ae7a074299bed53bbb92ebc34f', original_file='test.aes', salt_value='8cd661ff966f42fc8174623ff51e8bdd')

# Decrypt a file using DecipherEngine.decrypt_file
result_decrypt_file = decrypt_file(
    passkey_file='output/test_passkey.ini')
# Output: (NamedTuple)
# DecipherTuple(decrypted_file=PosixPath('test.aes'), hash_value='5c0c10f62a2798b8f4f2cbb3d677fc9330d87250d3a1b27830ab050ba21c87ab')

---

Roadmap

Features

• Algorithm Selection: Empower users with the ability to choose their preferred encryption algorithm, tailoring the cryptographic process to their specific security preferences.
• Personal 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.

This project is continuously evolving, and these features are anticipated to be implemented in future releases

Progress Table

• Algorithm Selection
• Personal Unique Encryption Identifier
• Performance Optimization

The 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 Feedback

The CipherEngine project welcomes contributions from the community to enhance its features and reliability. If you are interested in contributing, please follow the guidelines below:

Contributing

Step	Action
1.	Fork the repository on GitHub and clone it to your local machine.
2.	Create a new branch for your feature or bug fix: git checkout -b feature/your-feature or git 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 the main repository with a detailed description of your changes.

Feedback

Feedback is crucial for the improvement of the CipherEngine project. If you encounter any issues, have suggestions, or want to share your experience, please consider the following channels:

1. GitHub Issues: Open an issue on the GitHub repository to report bugs or suggest enhancements.

2. Contact: Reach out to the project maintainer via the following:

   • Discord
   • Gmail

Your feedback and contributions play a significant role in making the CipherEngine project more robust and valuable for the community. Thank you for being part of this endeavor!

---

Important Notes

1. Maximum Iterations and Key Length:

   • The maximum capacity for the number of iterations in encryption cycles for PBKDF2 and the key length is set to 1e8 (100 million).

     Caution is advised when utilizing this feature, as it may demand significant computational resources despite the code's efficiency.

2. Beta Release Status:

   • This 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 for encrypt/decrypt files at the moment.

3. Critical Considerations for Optimal Usage:

   • After 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 Disclaimer

Ensuring the proper and secure handling of data is of paramount importance when employing the CipherEngine library. To minimize the risk of potential data loss, consider the following guidelines:

• Backup File Parameter: Always make use of the backup_file parameter 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 the CipherEngine library 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 the CipherEngine offers powerful encryption and decryption capabilities, it is not exempt from potential risks associated with the broader landscape of data security.

---

Conclusion

In summary, the CipherEngine project 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.