ciphers.permutation_cipher
==========================

.. py:module:: ciphers.permutation_cipher

.. autoapi-nested-parse::

   The permutation cipher, also called the transposition cipher, is a simple encryption
   technique that rearranges the characters in a message based on a secret key. It
   divides the message into blocks and applies a permutation to the characters within
   each block according to the key. The key is a sequence of unique integers that
   determine the order of character rearrangement.

   For more info: https://www.nku.edu/~christensen/1402%20permutation%20ciphers.pdf



Functions
---------

.. autoapisummary::

   ciphers.permutation_cipher.decrypt
   ciphers.permutation_cipher.encrypt
   ciphers.permutation_cipher.generate_permutation_key
   ciphers.permutation_cipher.generate_valid_block_size
   ciphers.permutation_cipher.main


Module Contents
---------------

.. py:function:: decrypt(encrypted_message: str, key: list[int]) -> str

   Decrypt an encrypted message using a permutation cipher with block rearrangement.

   Args:
       encrypted_message (str): The encrypted message.
       key (list[int]): The permutation key for decryption.

   Returns:
       str: The decrypted plaintext message.

   Example:
       >>> encrypted_message, key = encrypt("HELLO WORLD")
       >>> decrypted_message = decrypt(encrypted_message, key)
       >>> decrypted_message
       'HELLO WORLD'


.. py:function:: encrypt(message: str, key: list[int] | None = None, block_size: int | None = None) -> tuple[str, list[int]]

   Encrypt a message using a permutation cipher with block rearrangement using a key.

   Args:
       message (str): The plaintext message to be encrypted.
       key (list[int]): The permutation key for decryption.
       block_size (int): The size of each permutation block.

   Returns:
       tuple: A tuple containing the encrypted message and the encryption key.

   Example:
       >>> encrypted_message, key = encrypt("HELLO WORLD")
       >>> decrypted_message = decrypt(encrypted_message, key)
       >>> decrypted_message
       'HELLO WORLD'


.. py:function:: generate_permutation_key(block_size: int) -> list[int]

   Generate a random permutation key of a specified block size.

   Args:
       block_size (int): The size of each permutation block.

   Returns:
       list[int]: A list containing a random permutation of digits.

   Example:
       >>> random.seed(0)
       >>> generate_permutation_key(4)
       [2, 0, 1, 3]


.. py:function:: generate_valid_block_size(message_length: int) -> int

   Generate a valid block size that is a factor of the message length.

   Args:
       message_length (int): The length of the message.

   Returns:
       int: A valid block size.

   Example:
       >>> random.seed(1)
       >>> generate_valid_block_size(12)
       3


.. py:function:: main() -> None

   Driver function to pass message to get encrypted, then decrypted.

   Example:
   >>> main()
   Decrypted message: HELLO WORLD