Pixseal 0.1.5

Encrypted Image Watermark Injector / Validator

Pixseal

Encrypted image watermark injector/validator that hides text (optionally RSA encrypted) inside 24-bit PNG or BMP files by modulating the parity of carefully selected color channels.

• GitHub: https://github.com/kyj9447/Pixseal
• Changelog: https://github.com/kyj9447/Pixseal/blob/main/CHANGELOG.md

Features

• Noise-resistant embedding: Chooses the RGB component whose value is farthest from 127 and nudges it ±1 to match each payload bit, keeping noise visually imperceptible.
• Sentinel-based framing: Automatically prefixes/suffixes payloads with START-VALIDATION / END-VALIDATION markers so the validator knows where to look.
• Optional RSA envelope: When you pass a public key, both the sentinels and payload are encrypted with OAEP (SHA-256). Validation decrypts with the matching private key before building a verdict.
• Pure Python image I/O: SimpleImage reads/writes uncompressed BMPs as well as 8-bit RGB/RGBA PNGs without third-party imaging libraries.

Installation

pip install Pixseal
# or for local development
pip install -e ./pip_package

Python 3.8+ is required. The only runtime dependency is cryptography>=41.0.0.

Usage

Sign an image

from Pixseal import signImage

result = signImage(
    imageInput="original.png",  # accepts a file path or raw PNG/BMP bytes
    hiddenString="!Validation:[e-mail]",
    publicKeyPath="SSL/public_key.pem",  # omit for plain-text embedding
)
result.save("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.
• When publicKeyPath is omitted, the payload remains plain text.

Validate and (optionally) decrypt

from Pixseal import validateImage

report = validateImage(
    imageInput="signed_original.png",  # accepts a file path or raw PNG/BMP bytes
    privKeyPath="SSL/private_key.pem",  # omit for plain-text payloads
)

print(report["extractedString1"])
print(report["validationReport"])

validateImage returns:

{
    "extractedString1": "<payload or encrypted blob>",
    "extractedString2": "<truncated payload or encrypted blob>",
    "validationReport": {
        "arrayLength": 4,
        "lengthCheck": True,
        "startCheck": True,
        "endCheck": True,
        "isDecrypted": True,
        "tailCheckResult": True,
        "verdict": True,
        # decryptSkipMessage when a decrypt request was skipped
    }
}

CLI demo script

python testRun.py offers an interactive flow:

1. Choose 1 to sign an image. It reads original.png, asks for a payload (default !Validation:[e-mail]), optionally encrypts with SSL/public_key.pem, and writes signed_<name>.png.
2. Choose 2 to validate. It reads signed_original.png, optionally decrypts with SSL/private_key.pem, and prints both the extracted string and verdict.
3. Choose 3 to benchmark performance. It reads original.png, encrypts it with SSL/public_key.pem, and writes signed_original.png, printing the elapsed signing time. Then it reads signed_original.png, performs extraction/decryption/validation, and prints the elapsed validation time along with the total elapsed time.
4. Choose 4 to test signing and validation with file-path input option.
5. Choose 5 to test signing and validation with byte-stream input option.

Key management

Generate a test RSA pair (PKCS#8) with OpenSSL:

openssl genpkey -algorithm RSA -out SSL/private_key.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -pubout -in SSL/private_key.pem -out SSL/public_key.pem

Point publicKeyPath / privKeyPath to these files.

API reference

Function	Description
signImage(imageInput, hiddenString, publicKeyPath=None)	Loads a PNG/BMP from a filesystem path or raw bytes, injects hiddenString plus sentinels, encrypting each chunk when publicKeyPath is provided. Returns a SimpleImage that you can save() or saveBmp().
validateImage(imageInput, privKeyPath=None)	Reads the hidden bit stream from a path or raw bytes, splits by newlines, deduplicates, optionally decrypts each chunk (Base64 indicates ciphertext), and returns the payload plus a validation report.

Examples

Original	Signed (!Validation:[e-mail])

Validation output excerpt:

[Validate] verdict: True
[Validate] extracted string: !Validation:[e-mail]
[Validate] decrypted with private key: SSL/private_key.pem

Validation Report

{'extractedString1': '!Validation:[e-mail]',
 'extractedString2': 'DMnWAzbd6NFycGAxcPkzzmGjL33WXovG...',
 'validationReport': {'arrayLength': 4,
                      'endCheck': True,
                      'isDecrypted': True,
                      'lengthCheck': True,
                      'startCheck': True,
                      'tailCheckResult': True,
                      'verdict': True}}

(When encrypted, each line appears as Base64 until decrypted with the RSA private key.)

Corrupted after signing

Validation output excerpt:

...
string argument should contain only ASCII characters
string argument should contain only ASCII characters
string argument should contain only ASCII characters
[Validate] verdict: False
[Validate] extracted string: !Validation:[e-mail]
[Validate] decrypted with private key: SSL/private_key.pem

Validation Report

{'extractedString1': '!Validation:[e-mail]',
 'extractedString2': 'hh78IWEsRgfTWMw3Rg02hTnCdErjx0O4...',
 'validationReport': {'arrayLength': 400,
                      'decryptSkipMessage': 'Skip decrypt: payload was plain '
                                            'or corrupted text despite decrypt '
                                            'request.',
                      'endCheck': True,
                      'isDecrypted': True,
                      'lengthCheck': False,
                      'startCheck': True,
                      'tailCheckResult': 'Not Required',
                      'verdict': False}}

Related projects

https://github.com/kyj9447/imageSignerCamera

• Mobile camera that signs images on capture:
• Server-side validator that decrypts and verifies payloads.