README.md

ciphers

About The Project

Script gives an opportunity, with Caesar, Vigenère, Bacon, Atbash, Simple Substitution, Columnar Transposition, Autokey, Rail-Fence, Bifid, Beaufort, Porta, Running key, Homophonic substitution, Hill, Playfair, Straddle checkerboard ciphers and Morse, Fractionated morse codes, to encode and decode messages.

PyPi

Package is available at Test PyPi at ciphers · TestPyPI

Built with

Python 3.9.10

Supported by

Python: 3.8, 3.9, 3.10, 3.11, 3.12

Platforms: Windows, Ubuntu, MacOS

Getting started

Requirements for running cipher/decipher functions:

All required packages in requirements.txt file. To install all required packages, type:

pip install -r requirements.txt

in the terminal.

Working with ciphers:

IMPORTANT

As a first step, it is recommended to run test from tests/test_project.py file. This can be done in two ways:

• with your current version of python with pytest
• with 5 versions of python from the tox.ini file (currently py38, py39, py310, py311, py312)

If you choose the first option, you should follow the 1st instruction, is second - 2nd instruction.

Instruction 1 (pytest, faster, current python version):

1. Install requirements from requirements_dev.txt file in the terminal like so:

pip install -r requirements_dev.txt

2. Run tests using the terminal command:

pytest

Instruction 2 (tox, slower, multiple versions of python):

1. Make sure you have installed versions of python specified in the tox.ini file (or modify the file accordingly).
2. Install tox with following command:

pip install tox

3. Run tox in the project directory using the terminal command:

tox --skip-missing-interpreters

Currently, there should be 334 tests passed.
If all tests are passing, you can use the module safely.

USING CIPHERS:

1. Use one of the ciphers below to cipher or decipher messages. Reference to every cipher can be found below under References tab.

2. caesar_cipher accepts 3 arguments and 1 optional argument:

   • Required arguments:
     • text - text to cipher (input from the user or from itself after encoding),
     • shift - shift of the ciphered alphabet,
     • alphabet - kind of alphabet you work with (latin, polish, etc.) - all are variables in the script,
   • Optional argument:
     • include_digits - specifies whether numbers contained in the text should be shifted (True/False variable with False being default option).

   Function can be used either to cipher or decipher messages.

3. vigenere_cipher accepts 3 arguments and 2 optional arguments:

   • Required arguments:
     • text - text to cipher (input from the user or from itself after encoding),
     • keyword - word used as a key to cipher/decipher a message,
     • alphabet - kind of alphabet you work with (latin, polish, etc.) - all are variables in the script,
   • Optional arguments:
     • mode - optional argument used to determine the operation mode of the function (CIPHER_MODE and DECIPHER_MODE - these are variables in the script) - cipher mode is a default mode.
     • keyword_shift - int variable, that specifies, what shift should the keyword have. Default value is 0.

   Function can be used either to cipher or decipher messages.

4. bacon_cipher_encoding accepts 2 arguments and 2 optional arguments:

   • Required arguments:
     • text - text to cipher (input from the user),
     • alphabet - kind of alphabet you work with (latin, polish, etc.) - all are variables in the script,
   • Optional argument:
     • letters_to_code_with - list of 2 characters to encode the message with. Default value is ["a", "b"],
     • unique_coding - bool variable, that specifies whether to use unique encoding on bacon ciphering. Default value is False.

5. bacon_cipher_decoding accepts 2 arguments and 2 optional arguments:

   • Required arguments:
     • text - text to decipher (from bacon_cipher_encoding function),
     • alphabet - kind of alphabet you work with (latin, polish, etc.) - all are variables in the script,
   • Optional argument:
     • letters_to_code_with - list of 2 characters to decode the message with. Default value is ["a", "b"],
     • unique_coding - bool variable, that specifies whether to use unique encoding on bacon deciphering. Default value is False.

6. atbash_cipher accepts 2 arguments and 1 optional argument:

   • Required arguments:
     • text - text to cipher (input from the user or from itself after encoding),
     • alphabet - kind of alphabet you work with (latin, polish, etc.) - all are variables in the script,
   • Optional argument:
     • include_digits - specifies whether numbers contained in the text should be ciphered (True/False variable with False being default option).

   Function can be used either to cipher or decipher messages.

7. simple_substitution_generate_random_key accepts 1 argument - alphabet and 1 optional argument - save_to_file - and returns shuffled version (mainly used for simple substitution ciphering) and optionally saves the key to a file as a default.

8. simple_substitution_cipher accepts 2 arguments and 1 optional argument:

   • Required arguments:
     • text - text to cipher (input from the user or from itself after encoding),
     • key - shuffled alphabet (generated by simple_substitution_generate_random_key function),
   • Optional arguments:
     • mode - optional argument used to determine the operation mode of the function (CIPHER_MODE and DECIPHER_MODE - these are variables in the script) - cipher mode is a default mode.

   Function can be used either to cipher or decipher messages.

9. columnar_transposition_cipher_encoding accepts 2 arguments and 1 optional argument:

   • Required arguments:
     • text - text to cipher (input from the user),
     • keyword - word used as a key to cipher/decipher a message (not longer than text to cipher),
   • Optional arguments:
     • ending - A character to fill the missing spaces when they appear with x being the default value.

10. columnar_transposition_cipher_decoding accepts 2 arguments and 1 optional argument:

    • Required arguments:
      • text - text to decipher (from columnar_transposition_cipher_encoding function),
      • keyword - word used as a key to cipher/decipher a message (not longer than text to cipher),
    • Optional arguments:
      • ending - A character to fill the missing spaces when they appear with x being the default value.

11. autokey_cipher_encoding accepts 3 arguments and no optional arguments:

    • Required arguments:
      • text - text to cipher (input from the user),
      • keyword - word used as a key to cipher a message (not longer than text to cipher),
      • alphabet - kind of alphabet you work with (latin, polish, etc.) - all are variables in the script.

12. autokey_cipher_decoding accepts 3 arguments and no optional arguments:

    • Required arguments:
      • text - text to decipher (from autokey_cipher_encoding function),
      • keyword - word used as a key to cipher a message (not longer than text to cipher),
      • alphabet - kind of alphabet you work with (latin, polish, etc.) - all are variables in the script.

13. rail_fence_cipher_encoding accepts 2 arguments and 1 optional argument:

    • Required arguments:
      • text - text to cipher (input from the user),
      • number_of_rails - number of rails the text should be split to,
    • Optional arguments:
      • remove_spaces - optional argument, that specifies, whether to remove all spaces from the input text with False as a default value.

14. rail_fence_cipher_decoding accepts 2 arguments:

    • Required arguments:
      • text - text to decipher (from rail_fence_cipher_encoding function),
      • number_of_rails - number of rails the text should be split to,

15. bifid_cipher_generate_random_key accepts 2 optional arguments - character_to_remove and save_to_file - and returns shuffled alphabet with specified letter removed and optionally saves the key to a file as a default.

16. bifid_cipher_encoding accepts 3 arguments and 2 optional arguments:

    • Required arguments:
      • text - text to cipher (input from the user),
      • period - period of shuffling the letters,
      • key - shuffled Latin alphabet with one of the letters removed (generated by bifid_cipher_generate_random_key function),
    • Optional arguments:
      • character_to_replace - character to be replaced, with "J" value as a default,
      • character_to_replace_with - character, that replaces the character from above, with "I" value as a default.

17. bifid_cipher_decoding accepts 3 arguments and 2 optional arguments:

    • Required arguments:
      • text - text to decipher (from bifid_cipher_encoding function),
      • period - period of shuffling the letters,
      • key - shuffled Latin alphabet with one of the letters removed (generated by bifid_cipher_generate_random_key function),
    • Optional arguments:
      • character_that_was_replaced - character, that was replaced in encoding function, with "J" value as a default,
      • character_that_was_replaced_with - character, that replaced the character from above, with "I" value as a default.

18. beaufort_cipher accepts 3 arguments and no optional arguments:

    • Required arguments:
      • text - text to cipher (input from the user or from itself after encoding),
      • keyword - word used as a key to cipher a message (not longer than text to cipher),
      • alphabet - kind of alphabet you work with (latin, polish, etc.) - all are variables in the script.

    Function can be used either to cipher or decipher messages.

19. porta_cipher accepts 3 arguments and no optional arguments:

    • Required arguments:
      • text - text to cipher (input from the user or from itself after encoding),
      • keyword - word used as a key to cipher a message (not longer than text to cipher),
      • alphabet - kind of alphabet you work with (latin, polish, etc.) - all are variables in the script.

    Function can be used either to cipher or decipher messages.

20. running_key_cipher accepts 3 arguments and 1 optional argument:

    • Required arguments:
      • text - text to cipher (input from the user or from itself after encoding),
      • keyphrase - phrase used as a key to cipher a message (equal in length or longer than text to cipher),
      • alphabet - kind of alphabet you work with (latin, polish, etc.) - all are variables in the script.
    • Optional arguments:
      • mode - optional argument used to determine the operation mode of the function (CIPHER_MODE and DECIPHER_MODE - these are variables in the script) - cipher mode is a default mode.

    Function can be used either to cipher or decipher messages.

21. homophonic_substitution_generate_letter_connection_dictionary accepts 1 argument - alphabet - and returns a dictionary of matched letters to the distribution of letters in texts (gets the data from wikipedia) - if a letter is more common, then it has more options to be replaced.

22. homophonic_substitution_cipher accepts 1 argument and 1 optional argument:

    • Required arguments:
      • text - text to cipher (input from the user or from itself after encoding),
    • Optional arguments:
      • mode - optional argument used to determine the operation mode of the function (CIPHER_MODE and DECIPHER_MODE - these are variables in the script) - cipher mode is a default mode.

23. trifid_cipher_generate_random_key accepts 2 optional arguments - additional_character and save_to_file - and returns shuffled alphabet with specified character added and optionaly saves the key to a file as a default.

24. trifid_cipher_encoding accepts 3 arguments and no optional arguments:

    • Required arguments:
      • text - text to cipher (input from the user),
      • key - shuffled Latin alphabet with one character added (generated by trifid_cipher_generate_random_key function),
      • period - period of shuffling the letters.

25. trifid_cipher_decoding accepts 3 arguments and no optional arguments:

    • Required arguments:
      • text - text to decipher (from trifid_cipher_encoding function),
      • key - shuffled Latin alphabet with one character added (generated by trifid_cipher_generate_random_key function),
      • period - period of shuffling the letters.

26. hill_cipher accepts 3 arguments and 2 optional arguments:

    • Required arguments:
      • text - text to cipher (input from the user or from itself after encoding),
      • alphabet - kind of alphabet you work with (latin, polish, etc.) - all are variables in the script,
      • key_matrix - matrix used as a key to cipher/decipher a message, such that the determinant is not zero and is relatively prime with the length of the alphabet,
    • Optional arguments:
      • mode - optional argument used to determine the operation mode of the function (CIPHER_MODE and DECIPHER_MODE - these are variables in the script) - cipher mode is a default mode,
      • character_to_fill - A character to fill the missing spaces when they appear, with "x" as a default value.

    Function can be used either to cipher or decipher messages.

27. playfair_cipher_generate_key_square accepts 1 argument - keyword and 2 optional arguments - character_to_remove with "J" as a default value and save_to_file - and returns a key phrase composed of specified keyword added up front and shuffled latin alphabet (with specified character removed) as a rest of the keyword (total length - 25) and optionally saves the key to a file as a default.

28. playfair_cipher_encoding accepts 2 arguments and 3 optional arguments:

    • Required arguments:
      • text - text to cipher (input from the user),
      • key_square - key square out of keyword and shuffled alphabet (generated by playfair_cipher_generate_key_square function),
    • Optional arguments:
      • character_to_replace - character to be replaced. Default character is "J",
      • character_to_replace_with - character, that replaces the character from above. Default character is "I"
      • swap_letter - character, that replaces a character, if a pair of the same letters is found in the text. Default is "X".

29. playfair_cipher_decoding accepts 2 arguments and 3 optional arguments:

    • Required arguments:
      • text - text to decipher (from playfair_cipher_encoding function),
      • key_square - key square out of keyword and shuffled alphabet (generated by playfair_cipher_generate_key_square function),
    • Optional arguments:
      • character_that_was_replace - character that was replaced in encoding. Default character is "J",
      • character_that_was_replace_with - character, that replaces the character from above. Default character is "I"
      • swap_letter - character, that replaced a character, if a pair of the same letters is found in the text. Default is "X".

30. morse_code accepts 1 argument and 2 optional arguments:

    • Required arguments:
      • text - text to cipher (input from the user or from itself after encoding),
    • Optional arguments:
      • gap_fill - A character to fill the missing spaces between words and/or characters, with a space as a default value,
      • mode - optional argument used to determine the operation mode of the function (CIPHER_MODE and DECIPHER_MODE - these are variables in the script) - cipher mode is a default mode.

    Function can be used either to cipher or decipher messages.

31. fractionated_morse_code_generate_key_table accepts 1 argument - keyword and 1 optional argument - save_to_file - and returns a key table composed of specified keyword added up front and shuffled latin alphabet as a rest of the keyword (total length - 26) and optionaly saves the key to a file as a default.

32. fractionated_morse_code accepts 2 arguments and 2 optional arguments:

    • Required arguments:
      • text - text to cipher (input from the user or from itself after encoding),
      • key_table - key table out of keyword and shuffled alphabet (generated by fractionated_morse_code_generate_key_table function),
    • Optional arguments:
      • gap_fill - A character to fill the missing spaces between words and/or characters, with a space as a default value,
      • mode - optional argument used to determine the operation mode of the function (CIPHER_MODE and DECIPHER_MODE - these are variables in the script) - cipher mode is a default mode.

    Function can be used either to cipher or decipher messages.

33. straddle_checkerboard_cipher_generate_random_key accepts 1 optional argument - save_to_file - and returns shuffled alphabet and optionaly saves the key to a file as a default.

34. straddle_checkerboard_cipher_encoding accepts 2 arguments and 2 optional arguments:

    • Required arguments:
      • text - text to cipher (input from the user),
      • key - shuffled alphabet (generated by straddle_checkerboard_cipher_generate_random_key function),
    • Optional arguments:
      • key_number - a number, that enciphers provided text even more (default value - 0 - makes this function return only the enciphered number string. Read References[20] for more information),
      • spare_positions - list of 2 integers with values between 1 and 9 including, that specifies where the bland spots should be (Read References[20] for more information).

35. straddle_checkerboard_cipher_decoding accepts 2 arguments and 2 optional arguments:

    • Required arguments:
      • text - text to decipher (from straddle_checkerboard_cipher_encoding function),
      • key - shuffled alphabet (generated by straddle_checkerboard_cipher_generate_random_key function),
    • Optional arguments:
      • key_number - a number, that enciphers provided text even more (default value - 0 - makes this function return only the enciphered number string. Read References[20] for more information),
      • spare_positions - list of 2 integers with values between 1 and 9 including, that specifies where the bland spots should be (Read References[20] for more information).

36. The result is returned after the execution is complete.

Other useful functions from the module:

• print_available_alphabets - accepts no arguments, prints all available alphabet names with corresponding values.

To Do:

• Change tests, that test generating keys to include saving to file
• Make a package out of this project
• Add more tests to check homophonic_substitution_cipher
• Check if rail_fence_cipher_decoding needs to cover removed spaces from the encoding function
• Investigate, whether straddle_checkerboard_cipher_encoding with specific values really can't encode them or this is a bug on implementation

Usage

Use it to play with ciphering and deciphering messages as you wish.
Script can be used to brute force some messages in order to decipher them.
Project also contains basic examples of ciphering and deciphering as test cases.

References

[1] Ciphers - Practical Cryptography
[2] Caesar Cipher - Practical Cryptography, Wikipedia
[3] Vigenère Cipher - Practical Cryptography, Wikipedia
[4] Bacon Cipher - Practical Cryptography, Wikipedia
[5] Atbash Cipher - Practical Cryptography, Wikipedia
[6] Simple Substitution Cipher - Practical Cryptography, Wikipedia
[7] Columnar Transposition Cipher - Practical Cryptography, Wikipedia
[8] Autokey Cipher - Practical Cryptography, Wikipedia
[9] Rail-fence Cipher - Practical Cryptography, Wikipedia
[10] Bifid Cipher - Practical Cryptography, Wikipedia
[11] Beaufort Cipher - Practical Cryptography, Wikipedia
[12] Porta Cipher - Practical Cryptography
[13] Running key cipher - Practical Cryptography, Wikipedia
[14] Homophonic substitution cipher - Practical Cryptography, Wikipedia
[15] Trifid cipher - Practical Cryptography, Wikipedia
[16] Hill cipher - Practical Cryptography, Wikipedia
[17] Playfair cipher - Practical Cryptography, Wikipedia
[18] Morse code - Wikipedia
[19] Fractionated morse code - Practical Cryptography
[20] Straddle checkerboard cipher - Practical Cryptography, Wikipedia
[21] Letter frequency - Wikipedia
[22] Russian alphabet - Wikipedia
[22] Ternary system - Wikipedia
[23] Quotes from "Moving Pictures" by Terry Pratchet - Chris Jones Writing
[24] Quotes from Stanisław Lem's books - Lubimy czytać

Packaging:
Packaging Python Projects - Python Packaging User Guide
Using TestPyPi - Python Packaging User Guide
Core metadata specifications - Python Packaging User Guide
PEP 301 – Package Index and Metadata for Distutils | peps.python.org
Classifiers · PyPI

Licence

Distributed under the MIT License. See LICENSE file for more information.