pysubcipher 2.3.3

pysubcipher allows for simple encryption and decryption of text using a basic substitution cipher algorithm.

Installation

Built and tested on Python 3.10 and above.
No requirements other than the module itself.

pip install pysubcipher

python3 -m pip install pysubcipher

Example Usage

Encrypting and decrypting a short string of text

def encrypt(self, s: str, /) -> bytes:
    ...
def decrypt(self, s: bytes, /) -> bytes:
    ...

from pysubcipher import SubstitutionCipher

subcipher = SubstitutionCipher()

my_text = "Hello, World!"
encrypted_text = subcipher.encrypt(my_text)
decrypted_text = subcipher.decrypt(encrypted_text)

print(encrypted_text)
print(decrypted_text)

Output

b'e41BF3d8ebD5c0F34D2ce0caC5FCD2fbFAc576aB91bFAc576aB91E38cD3Da83deCEa8eeafc5AD23FC63Bacc983cBBFe02D4eAb46DeCaabd4E5Dda1E38cD3Da83deCEa8eeaDa487daD01Afe0abFAc576aB91F557edbaBe4e6052F0B41C11184'
b'Hello, World!'

SubstitutionCipher

def __init__(self, min_key_length: int = 10, max_key_length: int = 20, *, seed: int | float | str | bytes | bytearray | None = os.urandom(1024), charset: str = HEXDIGITS) -> None:
    ...

"""A simple substitution cipher encryption tool to encode strings of text.

Args:
    min_key_length (int): The minimum length of a cipher key
    max_key_length (int): The maximum length of a cipher key
    seed (int | float | str | bytes | bytearray | None, optional): The seed that cipher keys will be generated with. Defaults to os.urandom(1024).
    charset (str, optional): The character set that cipher keys will be generated with. Defaults to HEXDIGITS.
"""

Using built-in character sets

• BASE_2
• HEXDIGITS
• OCTDIGITS
• ALPHANUMERIC

Base 2 Example

from pysubcipher import SubstitutionCipher, BASE_2

subcipher = SubstitutionCipher(charset = BASE_2)

my_text = "Hello, World!"
encrypted_text = subcipher.encrypt(my_text)
decrypted_text = subcipher.decrypt(encrypted_text)

print(encrypted_text)
print(decrypted_text)

Output

b'100001111110110000010100001011011110101010100010110111101010101001111001011010110111000110100100000011110100010010001000001001111001011000001111001111101010110111101010101001111101101101001111001001010'
b'Hello, World!'

Using a custom character set

Character sets are provided as strings of text, and will be used to generate cipher keys.

Note: if the character set is not unique enough, an exception will be raised as there would not be enough possible combinations to encrypt that string of text. For example, if you wanted to use BASE_2 as your character set, but only allowed for the minimum key length to be 3 and the maximum key length to be 4, there would not be enough combinations to account for the entirety of the string.

from pysubcipher import SubstitutionCipher

subcipher = SubstitutionCipher(charset = "abcde1234")

my_text = "Hello, World!"
encrypted_text = subcipher.encrypt(my_text)
decrypted_text = subcipher.decrypt(encrypted_text)

print(encrypted_text)
print(decrypted_text)

Output

b'accddb422a4bcc32bdaa2dd3b1beda34ecc32ed12134ecc32ed121cab4341d13d4b1dd32dbd1edebc2aac1b3cde1b1cedace3c1bcdacab4341d13d4b12ed3dcae1c2dbe4312ee34ecc32ed121bc4ab14112b2bb4a23e4c44c34bcdc12243e4'
b'Hello, World!'

Saving keys to a file

Saving keys can be useful if you intend on using the same cipher keys in different instances of your program.

"""Saves the current cipher keys to a file

Args:
    file (str): The path to the file
    truncate (bool, optional): If True, the file will be truncated prematurely before storing the keys. Defaults to False.
"""

from pysubcipher import SubstitutionCipher

subcipher = SubstitutionCipher()
subcipher.save_keys("cipher_keys.dat")

Loading saved keys from a file

"""Loads cipher keys into the instance

Args:
    file (str): The path to the file where the keys are stored

Raises:
    InvalidKeysError: Raised if the cipher keys are not valid.
"""

from pysubcipher import SubstitutionCipher

subcipher = SubstitutionCipher()
subcipher.load_keys("cipher_keys.dat")

Setting a custom seed

def set_seed(self, seed: int | float | str | bytes | bytearray | None, /) -> None:
    ...

If you don't intend on storing cipher keys in a file, you can always use a set seed so the cipher keys are the same every time you run your program.

from pysubcipher import SubstitutionCipher

subcipher = SubstitutionCipher()
subcipher.set_seed("my_amazing_seed")

Regenerating cipher keys

def regenerate_keys(self, seed: int | float | str | bytes | bytearray | None | None = None, /) -> None:
    ...

"""Regenerates encryption and decryption keys.

Args:
    seed (int | float | str | bytes | bytearray | None, optional): The seed to generate cipher keys with. Defaults to os.urandom(1024).
"""

Encrypting and decrypting files

class FileSubstitutionCipher(SubstitutionCipher):
    def __init__(self, min_key_length: int = 10, max_key_length: int = 20, *, seed: int | float | str | bytes | bytearray | None = os.urandom(1024), charset: str = HEXDIGITS) -> None:

"""A simple substitution cipher encryption tool to encrypt file's and their contents.

Args:
    min_key_length (int): The minimum length of a cipher key.
    max_key_length (int): The maximum length of a cipher key.
    seed (int | float | str | bytes | bytearray | None, optional): The seed that cipher keys will be generated with. Defaults to os.urandom(1024).
    charset (str, optional): The character set that cipher keys will be generated with. Defaults to HEXDIGITS.
"""

Encrypting

def encrypt(self, filepath: str, /, *, write: bool = False) -> bytes | None:
    ...

"""Encrypts the contents of a file and returns the encrypted contents or None

Args:
    filepath (str): The path to the file that will be encrypted
    write (bool, optional): Whether the program will write to that file, overriding it's original contents. Defaults to False.

Returns:
    bytes | None: Returns the encrypted contents if write is False, otherwise returns None
"""

Decrypting

def decrypt(self, filepath: str, /, *, write: bool = False) -> bytes | None:
    ...

"""Decrypts the contents of a file and returns the decrypted contents or None

Args:
    filepath (str): The path to the file that will be decrypted
    write (bool, optional): Whether the program will write to that file, overriding it's original contents. Defaults to False.

Returns:
    bytes | None: Returns the decrypted contents if write is False, otherwise returns None
"""

Example Usage

from pysubcipher import FileSubstitutionCipher

filepath: str = "my_file.txt"

subcipher = FileSubstitutionCipher()

# Override the file's contents with the encrypted contents
subcipher.encrypt(filepath, write = True)

# Get the decrypted contents without modifying the file
decrypted_file_contents = subcipher.decrypt(filepath) # write is defaulted to False
print(decrypted_file_contents)

Output

my_file.txt

b'D2d3F1Db7eEdE28A34Df31975e98a7Bfb0cfd21c89DB168FACbe7eDE9bb98f5cfADFff093771B08093b8daC56e1A3Df0DF8Bedeebf1268FACbe7eDE9bb95CF51C2C9c06Dc9C8f5cfADFff093768FACbe7eDE9bb914734bB8AAaAD8ef71B08093b8daC56e1A3D5CF51C2C9c06Dc9C2baB2eB530Cd88322A731F9d1DC00Ddfe814734bB8AAaAD8ef68FACbe7eDE9bb9322A731F9d1DC00Ddfe814734bB8AAaAD8eff0DF8Bedeebf12'

Console Output

b'Super secret contents'

Exceptions and error handling

InvalidCharacterError

def __init__(self, character: str, /) -> None:
    ...

Raised if an invalid token is present within a string of text while encrypting or decrypting a value.

EncryptedStringInvalidError

def __init__(self, token: str) -> None:
    ...

Raised while decrypting a string of text if the encrypted string is not valid or does not match any decryption keys.

InvalidKeysError

def __init__(self) -> None:
    ...

Raised inside of the load_keys() function of the SubstitutionCipher class if the cipher keys fail validation.