pysubcipher 2.1.0

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

pysubcipher==2.1.0

pysubcipher is a python module built on Python 3.10 which allows users to encrypt and decrypt strings of text using a substitution cipher algorithm.

Installation

Tested on Python 3.9 and above.
No requirements apart from the standard module.

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: Any | 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 (Any | 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 InvalidTokenFoundError 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 before storing the keys. Defaults to False.
"""

from pysubcipher import SubstitutionCipher

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

Loading keys into a SubstitutionCipher instance

"""Loads cipher keys into the instance

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

Raises:
    InvalidTokenFoundError: If the keys are not valid, an InvalidTokenFoundError will be raised
"""

from pysubcipher import SubstitutionCipher

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

Setting a custom seed

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. Seeds will always be generated upon creating a new instance of the SubstitutionCipher class and will be set to os.urandom(1024).

from pysubcipher import SubstitutionCipher

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

Encrypting and decrypting a file

The FileSubstitutionCipher class can be used to encrypt and decrypt files easily.

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.

Note: pysubcipher==2.1.0 currently only supports the following characters:
0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~ \t\n\r\x0b\x0c

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.