Usage
=====

This guide demonstrates the basic usage of DES PurePy.

Installation
------------

Install the package from PyPI.

.. code-block:: console

   pip install des_PurePy

Creating a DES Object
---------------------

Create a ``DES`` object by supplying an 8-byte key. The key may be provided
as either a hexadecimal string or a ``bytes`` object.

Using a hexadecimal string:

.. code-block:: python

   import des_PurePy

   des = des_PurePy.DES("0x133457799bbcdff1")

Using a ``bytes`` object:

.. code-block:: python

   import des_PurePy

   des = des_PurePy.DES(b"password")

Encrypting Data
---------------

Encrypt plaintext using the ``encrypt()`` method.

.. code-block:: python

   ciphertext = des.encrypt("0x0123456789abcdef")

The returned ciphertext is a hexadecimal string.

.. code-block:: text

   0x85e813540f0ab405fdf2e174492922f8

Decrypting Data
---------------

Decrypt ciphertext using the ``decrypt()`` method.

.. code-block:: python

   cleartext = des.decrypt(ciphertext)

The result is returned as a hexadecimal string.

.. code-block:: text

   0x0123456789abcdef

Working with Text
-----------------

Since the library accepts ``bytes`` objects, encrypting text is
straightforward.

.. code-block:: python

   import des_PurePy

   key = b"password"
   des = des_PurePy.DES(key)

   ciphertext = des.encrypt(b"secret message")

   cleartext = des.decrypt(ciphertext)

   message = bytes.fromhex(cleartext[2:]).decode("utf-8")

   print(message)

Output:

.. code-block:: text

   secret message

Padding
-------

DES operates on 64-bit (8-byte) blocks.

Plaintext is automatically padded using PKCS#5 padding before encryption.
After decryption, the padding is removed automatically.

Block Mode
----------

Messages longer than one block are encrypted using Electronic Codebook
(ECB) mode.

Input Validation
----------------

DES PurePy validates all user input before encryption or decryption.

Examples of validation include:

* Keys must be exactly 8 bytes (64 bits).
* Ciphertext must be a multiple of the DES block size.
* Hexadecimal strings must contain only valid hexadecimal characters.
* Inputs may be either hexadecimal strings or ``bytes`` objects.

Invalid input raises an appropriate Python exception describing the error.