Pixseal 1.0.0__pp39-pypy39_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

pixseal-1.0.0.dist-info/METADATA

@@ -0,0 +1,285 @@
+Metadata-Version: 2.4
+Name: Pixseal
+Version: 1.0.0
+Summary: Image integrity and authenticity verification tool
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=41.0.0
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/kyj9447/Pixseal/main/assets/logo/Pixseal.png" width="200px"/>
+</p>
+
+# Pixseal
+### Prove what you published — and what you didn’t.
+Pixseal is a Python-based **image integrity and authenticity verification tool**
+designed to **detect whether an image has been modified since signing.**
+
+Pixseal embeds a **cryptographically verifiable integrity seal** into an image in an
+invisible manner. During verification, **any modification** — including editing,
+filtering, cropping, resizing, re-encoding — will cause verification to **fail**.
+
+Pixseal signs the payload and image hash with an RSA private key. Verification uses
+the matching RSA public key or an X.509 certificate that contains it.
+
+Pixseal is not a visual watermarking or branding tool.
+The watermark exists solely as a **means to achieve strict, deterministic image
+tamper detection**.
+Pixseal prioritizes tamper sensitivity over robustness against intentional adversarial manipulation.
+
+- GitHub: https://github.com/kyj9447/Pixseal
+- Changelog: https://github.com/kyj9447/Pixseal/blob/main/CHANGELOG.md
+
+## Features
+- **Image Integrity Verification**
+  - Cryptographically proves that an image remains in its original, unmodified state
+  - Detects single-pixel changes with deterministic verification results
+
+- **Tamper Detection**
+  - Detects image modifications such as:
+    - editing
+    - filters and color adjustments
+    - cropping and resizing
+    - re-encoding and recompression
+    - pixel-level changes
+
+- **Invisible Integrity Seal**
+  - Embeds verification data without any visible watermark
+  - Preserves the original visual appearance of the image
+
+- **RSA Signatures + Certificate Support**
+  - Signs payloads and image hashes with an RSA private key
+  - Validates with RSA public keys or X.509 certificates (PEM/DER)
+
+- **Flexible Key Inputs**
+  - Accepts key/cert objects, PEM/DER bytes, or file paths
+
+- **Fully Local & Offline**
+  - No external servers or network dependencies
+  - Pure Python implementation
+
+- **Lossless Format Support**
+  - Supports PNG and BMP (24-bit) images
+  - Lossy formats (e.g., JPEG, WebP) are intentionally excluded to preserve integrity guarantees
+
+## Installation
+
+```bash
+pip install Pixseal
+# or for local development
+pip install -e ./pip_package
+```
+
+Python 3.8+ is required. Wheels published to PyPI already include the compiled
+Cython extension, so `pip install Pixseal` automatically selects the right build
+for your operating system and CPU.
+
+### Building the Cython extension
+
+If you cloned the repository (or downloaded the source), run the helper script
+to compile the `simpleImage_ext` extension for your environment:
+
+```bash
+git clone https://github.com/kyj9447/Pixseal.git
+cd Pixseal
+python3 -m pip install -r requirements.txt
+./compile_extension.sh
+```
+
+This command regenerates the C source via Cython and invokes your local C
+compiler (`clang` or `gcc`) to produce `pip_package/Pixseal/simpleImage_ext*.so`.
+You still need a working build toolchain (`gcc`/`clang` and Python headers)
+installed through your OS package manager. If you skip this step, Pixseal falls
+back to the pure Python implementation, which works but is significantly slower.
+
+## Quick start
+
+### Sign an image
+
+```python
+from Pixseal import signImage
+
+signed = signImage(
+    imageInput="assets/original.png",
+    payload="AutoTest123!",
+    private_key="assets/CA/pixseal-dev-final.key",
+)
+signed.save("assets/signed_original.png")
+```
+
+- The payload is looped if it runs out before the image ends, so even small files carry the full sentinel/payload/end pattern.
+
+### Validate a signed image
+
+```python
+from Pixseal import validateImage
+
+report = validateImage(
+    imageInput="assets/signed_original.png",
+    publicKey="assets/CA/pixseal-dev-final.crt",  # cert or public key
+)
+
+print(report["verdict"])
+```
+
+## Key and certificate inputs
+
+Pixseal accepts multiple input formats so you can keep the calling code minimal.
+
+- `signImage(..., private_key=...)` accepts:
+  - `RSAPrivateKey`
+  - PEM/DER bytes (`bytes`, `bytearray`, `memoryview`)
+  - file path (`str` or `Path`)
+
+- `validateImage(..., publicKey=...)` accepts:
+  - `RSAPublicKey`
+  - `x509.Certificate`
+  - PEM/DER bytes (`bytes`, `bytearray`, `memoryview`)
+  - file path (`str` or `Path`)
+
+If a certificate is provided, Pixseal extracts the embedded RSA public key and
+verifies the signatures. Certificate chain validation is the responsibility of
+the calling application.
+
+## Payload structure
+
+Pixseal embeds a compact JSON payload with the signed data and image hash:
+
+```json
+{
+  "payload": "AutoTest123!",
+  "payloadSig": "BASE64_SIGNATURE",
+  "imageHash": "SHA256_HEX",
+  "imageHashSig": "BASE64_SIGNATURE"
+}
+```
+
+- `payload`: user-provided text
+- `payloadSig`: RSA signature of `payload` (Base64)
+- `imageHash`: SHA256 hex digest computed over the signed image buffer.
+- `imageHashSig`: RSA signature of `imageHash` (Base64)
+
+## Embedded sequence layout
+
+Pixseal writes the following newline-delimited sequence into the image:
+
+```
+<START-VALIDATION signature>
+<payload JSON>
+<payload JSON>
+<payload JSON>
+<payload JSON>
+...(Repeated until it fills the entire image)...
+<payload JSON>   # truncated tail (prefix of payload JSON)
+<END-VALIDATION signature>
+```
+
+During extraction, Pixseal deduplicates the sequence and typically returns four
+lines in order: start signature, full payload JSON, truncated payload prefix,
+and end signature. 
+
+For a valid image, deduplication results in four extracted
+lines. 
+
+```
+<START-VALIDATION signature>
+<payload JSON>
+<payload JSON>   # truncated tail
+<END-VALIDATION signature>
+```
+<sub>※ In rare edge cases, the truncated payload prefix may be absent, in which
+case only three lines are returned.</sub>
+
+## Validation output
+
+Validation Report
+
+- `lengthCheck`
+  - `length` : Length of deduplication result array.
+  - `result` : True for 4 or 3 (valid deduplication cases).
+- `tailCheck`
+  - `full` : Full payload intact. (output truncated)
+  - `tail` : Truncated payload intact. (output truncated)
+  - `result` : True when the full and truncated payload portions match.
+- `startVerify` : Verification result of the first SIG against "START-VALIDATION"
+- `endtVerify` : Verification result of the last SIG against "END-VALIDATION"
+- `payloadVerify` : Verification result of the "payload" against "payloadSig"
+- `imageHashVerify` : Verification result of the "imageHash" against "imageHashSig"
+- `imageHashCompareCheck`
+  - `extractedHash` : Value of "imageHash" from extracted payload
+  - `computedHash` : Image hash computed directly from the image
+  - `result` : True when extractedHash and computedHash are identical
+- `verdict` : True when all validation checks pass.
+
+## CLI demo script
+
+`python testRun.py` offers an interactive flow:
+
+Before the menu, it prompts for the SimpleImage backend
+(Enter/1=cython, 2=python fallback) and sets `PIXSEAL_SIMPLEIMAGE_BACKEND`.
+
+1. Choose **1** to sign an image. It reads `assets/original.png` and writes `assets/signed_original.png`.
+2. Choose **2** to validate. It reads `assets/signed_original.png` and prints the validation report.
+3. Choose **3** to run the failure test. It reads `assets/currupted_signed_original.png`.
+4. Choose **4** to benchmark performance (sign + validate with timings).
+5. Choose **5** to test signing and validation using in-memory bytes.
+6. Choose **6** to run the optional line-profiler demo.
+7. Choose **7** to run validation multi-pass tests.
+
+Option **6** requires the optional dependency `line_profiler` and must be run via
+`kernprof -l testRun.py` so that `builtins.profile` is provided. Without
+`line_profiler` installed the script will continue to work, but the profiling
+option will display an informative message instead of running.
+
+## API reference
+
+| Function | Description |
+| --- | --- |
+| `signImage(imageInput, payload, private_key)` | Loads a PNG/BMP from a filesystem path or raw bytes, injects `payload` plus sentinels, and signs the payload/hash using the RSA private key. Returns a `SimpleImage` that you can `save()` or `saveBmp()`. |
+| `validateImage(imageInput, publicKey)` | Reads the hidden bit stream from a path or raw bytes, rebuilds the payload JSON, verifies signatures and the computed image hash, and returns a validation report. Accepts RSA public keys or X.509 certificates. |
+
+## Examples
+
+| Original | Signed (`AutoTest123!`) |
+| --- | --- |
+| <img src="https://raw.githubusercontent.com/kyj9447/Pixseal/main/assets/original.png" width="400px"/> | <img src="https://raw.githubusercontent.com/kyj9447/Pixseal/main/assets/signed_original.png" width="400px"/> |
+
+Validation output (success):
+
+```
+Validation Report
+
+{'lengthCheck': {'length': 4, 'result': True},
+ 'tailCheck': {'full': '{"payload":"AutoTest...lgu9lUM+s7OHUZywYqYYOYIFVTWCmq...',
+               'tail': '{"payload":"AutoTest...lgu9lUM+s7',
+               'result': True},
+ 'startVerify': True,
+ 'endtVerify': True,
+ 'payloadVerify': True,
+ 'imageHashVerify': True,
+ 'imageHashCompareCheck': {'extractedHash': '2129e43456029f39b20bbe96340dce6827c0ad2288107cb92c0b92136fec48d6',
+                           'computedHash': '2129e43456029f39b20bbe96340dce6827c0ad2288107cb92c0b92136fec48d6',
+                           'result': True},
+ 'verdict': True}
+```
+
+| Corrupted after signing |
+| --- |
+| <img src="https://raw.githubusercontent.com/kyj9447/Pixseal/main/assets/currupted_signed_original.png" width="400px"/> |
+
+Validation output (failure):
+
+```
+Validation Report
+
+{'lengthCheck': {'length': 31, 'result': False},
+ 'tailCheck': {'result': 'Not Required'},
+ 'startVerify': True,
+ 'endtVerify': True,
+ 'payloadVerify': True,
+ 'imageHashVerify': True,
+ 'imageHashCompareCheck': {'extractedHash': '68d500c751dfa298d55dfc1cd2ab5c9f43ec139f02f6a11027211c4d144c2870',
+                           'computedHash': '43fd2108f5aa16045f4b64d70a0ce05991043cba6878f66d82abd3e7edb9d51e',
+                           'result': False},
+ 'verdict': False}
+```

pixseal-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pixseal-1.0.0.dist-info/WHEEL,sha256=VbVV36H_sGWs2wDlSVuZCfrfUlk3NfehwD_wG4zKlug,162
+pixseal-1.0.0.dist-info/top_level.txt,sha256=q35ICL7vJyo5hOpL4YbL5t_g4297gwUPIuLy82kgL3s,8
+pixseal-1.0.0.dist-info/METADATA,sha256=HQJKCdanhScu8WEww9YeQLQFzyVxVyUiMQwHQjPDnCY,10214
+pixseal-1.0.0.dist-info/RECORD,,
+Pixseal/simpleImage_py.py,sha256=6U44kNUP-ygcf7Sz91fjG99CrVWcROIC4tneQXDdbOA,27583
+Pixseal/keyInput.py,sha256=p49Y_ZKRMxF8aU53eB6GGvos-AaI_m5d5z5z1reMgmU,3523
+Pixseal/imageValidator.py,sha256=aRBfEz6eHJlhExqMyw83mCnx_I05yTD217oeJzffPpo,11607
+Pixseal/simpleImage.py,sha256=dkpMEhkT1z0pZOgy-AbgYlF9GC73eM2WGaYb5FiGNpk,1234
+Pixseal/imageSigner.py,sha256=fWQ1o8MAOgRihT1rYKdht0W8eUoA8qJJ02YDcGpch-U,10636
+Pixseal/__init__.py,sha256=J66ptDDimT5fe8AZCqeJv2xLUl-rbPqLFGJlMTsuwA8,646
+Pixseal/simpleImage_ext.pypy39-pp73-x86_64-linux-gnu.so,sha256=i_L0LuOmWbhW-2HUVfmqX228jVEJt1RWwmgiHWmnJmw,320472

pixseal-1.0.0.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.1)
+Root-Is-Purelib: false
+Tag: pp39-pypy39_pp73-manylinux_2_17_x86_64
+Tag: pp39-pypy39_pp73-manylinux2014_x86_64
+

pixseal-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+Pixseal