pillowncase package¶

pillowncase.pncase module¶

class pillowncase.pncase.ManipulateImage(channels='RGB', granularity=4, magic_header='XYZZY', verbose=0, custom_channels='', encrypt_data=False, key='')[source]¶

Store any file in any image as a png file.

Parameters:

Parameters:	channels (str) – takes any combination of RGBA this defines what channels you want to store the file data in, if the source image does not have an alpha channel (A) one is created. granularity (int) – a value between 1 and 8, 1 is fine (large file size but little visual difference to original image) 8 is complete replacement with the data to be hidden. magic_header (str) – header used internal to see where the data starts, in most cases you wont ever need to change this. if you do change it you will have to supply it to decode. See decode function. verbose (int) – set to 1 for general command line usage and feedback, higher for debugging leave at default 0 which is no sys out for class usage unless you are having issues. custom_channels (str) – overrides the channels parameter here you can specify exactly what bit distribution you want in the image expects text string in the format 1111 e.g. 2034 means 2 px in R, none in G, 3 in B and 4 in A encrypt_data (bool) – default False, change to True if you want to encrypt the lead in header and data, uses a combination of XOR and Fernet, do some research look at the code see if that meets your needs, you will need the key to decrypt, a key is auto generated if not supplied. Don’t forget you can encrypt your data to hide however you like outside of this code, it will just do a like for like binary read and store of whatever file you point it at. key (str) – if you have a key and want to encrypt using it put it here as a string e.g. you want to encode a lot of images with the same key, if it’s left blank one will get generated if encrypt_data=True. See `decode()` for an example using encryption.
Raises:	ValueError – If input values provided are out of range

channels (str) – takes any combination of RGBA this defines what channels you want to store the file data in, if the source image does not have an alpha channel (A) one is created.
granularity (int) – a value between 1 and 8, 1 is fine (large file size but little visual difference to original image) 8 is complete replacement with the data to be hidden.
magic_header (str) – header used internal to see where the data starts, in most cases you wont ever need to change this. if you do change it you will have to supply it to decode. See decode function.
verbose (int) – set to 1 for general command line usage and feedback, higher for debugging leave at default 0 which is no sys out for class usage unless you are having issues.
custom_channels (str) – overrides the channels parameter here you can specify exactly what bit distribution you want in the image expects text string in the format 1111 e.g. 2034 means 2 px in R, none in G, 3 in B and 4 in A
encrypt_data (bool) – default False, change to True if you want to encrypt the lead in header and data, uses a combination of XOR and Fernet, do some research look at the code see if that meets your needs, you will need the key to decrypt, a key is auto generated if not supplied. Don’t forget you can encrypt your data to hide however you like outside of this code, it will just do a like for like binary read and store of whatever file you point it at.
key (str) – if you have a key and want to encrypt using it put it here as a string e.g. you want to encode a lot of images with the same key, if it’s left blank one will get generated if encrypt_data=True. See decode() for an example using encryption.

Raises:

ValueError – If input values provided are out of range

Example usage:

>>> from pillowncase import pncase
>>> pnc = pncase.ManipulateImage(verbose=1)
>>> pnc.encode()
::encode::
::Reading Datafile: pillowncase/pillowncase/files/pNcase_test.txt
::Resizing Image to fit to data
::Writing data to Image
::Progress: 100%
::Image 'pNcase.png' created and saved
>>> pnc.decode(image_file='pNcase.png')
::Decode::
::Opened Image-file: pNcase.png
::Reading data from Image
::Progress: 100%
::Found hidden file: pNcase_test.txt
::Successfully read data
::All done Data Written to file: pNcase_test.txt

decode(image_file, key='', output_file='', magic_header='XYZZY')[source]¶

Store any file in any image as a png file.

Parameters:

Parameters:	image_file (str) – the image file you want to try and decode, needs to be PNG, will error if it can’t find any hidden data. key (str) – if the file was encrypted supply the key as a text string here output_file (str) – this is the output file path, by default the code will extract to the same path as it is run and won’t warn if theres an overwrite, if you want to extract somewhere else put the path here. magic_header (str) – if the magic header had been changed you need to put it here, default will suffice in most cases.
Raises:	IOError – if it can’t read or write any of the files successfully.

image_file (str) – the image file you want to try and decode, needs to be PNG, will error if it can’t find any hidden data.
key (str) – if the file was encrypted supply the key as a text string here
output_file (str) – this is the output file path, by default the code will extract to the same path as it is run and won’t warn if theres an overwrite, if you want to extract somewhere else put the path here.
magic_header (str) – if the magic header had been changed you need to put it here, default will suffice in most cases.

Raises:

IOError – if it can’t read or write any of the files successfully.

Example usage see encode() for an example not using encryption:

>>> pnc = pncase.ManipulateImage(verbose=1,encrypt_data=True)
>>> pnc.encode(input_file='medium_test')
::encode::
::Reading Datafile: pillowncase/pillowncase/files/pg29809.txt
::Encrypting Data
::Resizing Image to fit to data
::Writing data to Image
::Progress: 100%
::Image 'pNcase.png' created and saved

***KEEP THIS KEY SAFE YOU CANT DECRYPT WITHOUT IT***

***if your key starts with a - and you are using the example main class explicitly
        reference it in the command line with -k='-your key starting with a -'***

::
::Decrypt Key: 89DWqGN5wX_5-g7QBO8egn2sBqd2Ii4DifHngnF43ZQ=
::
>>> pnc.decode(image_file='pNcase.png',key='89DWqGN5wX_5-g7QBO8egn2sBqd2Ii4DifHngnF43ZQ=')
::Decode::
::Opened Image-file: pNcase.png
::Reading data from Image
::Progress: 100%
::Decrypting Data
::Using Key: 89DWqGN5wX_5-g7QBO8egn2sBqd2Ii4DifHngnF43ZQ=
::Found hidden file: pg29809.txt
::Successfully read data
::All done Data Written to file: pg29809.txt

encode(input_file='small_test', image_file='', output_file='pNcase.png', resize_image=True, key='')[source]¶

Store any file in any image as a png file.

Parameters:

Parameters:	input_file (str) – a string with the path to the file you want to hide, there are 4 test scenarios included. All examples are royalty free and include licenses as required passing one of the strings below will create example image files of varying sizes. Example: input_file='small_test' input_file='medium_test' nput_file='medium_raw_test' input_file='large_test' image_file (str) – a string containing the path to the image file you would like to hide the file in, if no file is passed an empty square image is produced and just the data is written, this is the most optimal way to store the data but it is not hidden (but looks cool), there are 5 images included as defaults if you want to use them instead of your own images. All included images are created and owned by me and released under the same licensing as this project. Example: image_file='FLOWERS' image_file='HORSE' image_file='PNCASE' image_file='KITTEN' image_file='KATIE' output_file (str) – the output image file name, will always be png, if none is passed it defaults to pNcase.png this is the image file with the data hidden in it. resize_image (bool) – by default is an image is supplied it will be resized up or down to the optimum size to fit the data, if you only have a small amount of data to hide sometimes it will be better to keep the image at it’s initial size. If the data would then exceed this size an error will be thrown. key (str) – if you have a key and want to encrypt using it put it here as a string e.g. you want to encode a lot of images with the same key, if it’s left blank and you did not set encrypt_data=True in the class initiator it will not be encrypted.
Raises:	IOError – if it can’t read or write any of the files successfully.

input_file (str) –
a string with the path to the file you want to hide, there are 4 test scenarios included.

All examples are royalty free and include licenses as required passing one of the strings below will create example image files of varying sizes.

Example:
```
input_file='small_test'
input_file='medium_test'
nput_file='medium_raw_test'
input_file='large_test'
```
image_file (str) –
a string containing the path to the image file you would like to hide the file in, if no file is passed an empty square image is produced and just the data is written, this is the most optimal way to store the data but it is not hidden (but looks cool), there are 5 images included as defaults if you want to use them instead of your own images.

All included images are created and owned by me and released under the same licensing as this project.

Example:
```
image_file='FLOWERS'
image_file='HORSE'
image_file='PNCASE'
image_file='KITTEN'
image_file='KATIE'
```
output_file (str) – the output image file name, will always be png, if none is passed it defaults to pNcase.png this is the image file with the data hidden in it.
resize_image (bool) – by default is an image is supplied it will be resized up or down to the optimum size to fit the data, if you only have a small amount of data to hide sometimes it will be better to keep the image at it’s initial size. If the data would then exceed this size an error will be thrown.
key (str) – if you have a key and want to encrypt using it put it here as a string e.g. you want to encode a lot of images with the same key, if it’s left blank and you did not set encrypt_data=True in the class initiator it will not be encrypted.

Raises:

IOError – if it can’t read or write any of the files successfully.

Example usage see decode() for an example using encryption:

>>> from pillowncase import pncase
>>> pnc = pncase.ManipulateImage(verbose=1,granularity=2)
>>> pnc.encode(image_file='KATIE',input_file='medium_test',output_file='katie_test.png')
::encode::
::Reading Datafile: pillowncase/pillowncase/files/pg29809.txt
::Resizing Image to fit to data
::Writing data to Image
::Progress: 100%
::Image 'katie_test.png' created and saved
>>> pnc.decode(image_file='katie_test.png')
::Decode::
::Opened Image-file: katie_test.png
::Reading data from Image
::Progress: 100%  Found File Name: pg29809.txt
::Found hidden file: pg29809.txt
::Successfully read data
::All done Data Written to file: pg29809.txt

get_data_output_file()[source]¶

Gets the created hidden data file as a string

Returns:	extracted hidden data file name
Return type:	str

Example usage:

>>> from pillowncase import pncase
>>> pnc = pncase.ManipulateImage(verbose=1)
>>> pnc.encode(image_file='small_test')
::encode::
::Reading Datafile: pillowncase/pillowncase/files/pNcase_test.txt
::Resizing Image to fit to data
::Writing data to Image
::Progress: 100%
::Image 'pNcase.png' created and saved
>>> pnc.decode(image_file='pNcase.png')
::Decode::
::Opened Image-file: pNcase.png
::Reading data from Image
::Progress: 100%  Found File Name: pNcase_test.txt
::Found hidden file: pNcase_test.txt
::Successfully read data
::All done Data Written to file: pNcase_test.txt
>>> print (pnc.get_data_output_file())
pNcase_test.txt

get_input_file()[source]¶

Gets the data input file as a string

Returns:	input file name
Return type:	str

Example usage:

>>> from pillowncase import pncase
>>> pnc = pncase.ManipulateImage()
>>> pnc.encode(image_file='small_test')
>>> print (pnc.get_input_file())
pillowncase/pillowncase/files/pNcase_test.txt

get_key()[source]¶

Gets the encryption key if there is one.

Returns: the encryption key as a decoded UTF-8 string if no key is set it will return a string containing “not encrypted”

Return type:

Returns:	the encryption key as a decoded UTF-8 string if no key is set it will return a string containing “not encrypted”
Return type:	str Example usage: >>> from pillowncase import pncase >>> pnc = pncase.ManipulateImage(verbose=1,encrypt_data=True) >>> pnc.encode() ::encode:: ::Reading Datafile: pillowncase/pillowncase/files/pNcase_test.txt ::Encrypting Data ::Resizing Image to fit to data ::Writing data to Image ::Progress: 100% ::Image 'pNcase.png' created and saved *KEEP THIS KEY SAFE YOU CANT DECRYPT WITHOUT IT* *if your key starts with a - and you are using the example main class explicitly reference it in the command line with -k='-your key starting with a -'* :: ::Decrypt Key: VVXeB8qWM1YYiQSud2vE0o0JZqRzwNUFjcBCGjI5rhs= :: >>> print (pnc.get_key()) VVXeB8qWM1YYiQSud2vE0o0JZqRzwNUFjcBCGjI5rhs=

str

Example usage:

>>> from pillowncase import pncase
>>> pnc = pncase.ManipulateImage(verbose=1,encrypt_data=True)
>>> pnc.encode()
::encode::
::Reading Datafile: pillowncase/pillowncase/files/pNcase_test.txt
::Encrypting Data
::Resizing Image to fit to data
::Writing data to Image
::Progress: 100%
::Image 'pNcase.png' created and saved

***KEEP THIS KEY SAFE YOU CANT DECRYPT WITHOUT IT***

***if your key starts with a - and you are using the example main class explicitly 
        reference it in the command line with -k='-your key starting with a -'***

::
::Decrypt Key: VVXeB8qWM1YYiQSud2vE0o0JZqRzwNUFjcBCGjI5rhs=
::
>>> print (pnc.get_key())
VVXeB8qWM1YYiQSud2vE0o0JZqRzwNUFjcBCGjI5rhs=

get_magic_header()[source]¶

Gets the magic header as a string

Returns:	magic header
Return type:	str

Example usage:

>>> from pillowncase import pncase
>>> pnc = pncase.ManipulateImage()
>>> print (pnc.get_magic_header())
XYZZY

get_output_file()[source]¶

Gets the created output file as a string

Returns:	output file name
Return type:	str

Example usage:

>>> from pillowncase import pncase
>>> pnc = pncase.ManipulateImage()
>>> pnc.encode(image_file='small_test')
>>> print (pnc.get_output_file())
pNcase.png

set_key(key)[source]¶

Sets the encryption key to a specific string, note the key must be compatible with Fernet if you are not sure, let the initial encode process generate a key for you on first run and use that going forward if you want to encrypt a lot of files with the same key. This will not raise an error until the key is used by decode() or encode()

Parameters:	key (str) – the encryption key.

Example usage:

>>> from pillowncase import pncase
>>> pnc = pncase.ManipulateImage(verbose=1)
>>> pnc.set_key('VVXeB8qWM1YYiQSud2vE0o0JZqRzwNUFjcBCGjI5rhs=')
>>> pnc.encode(image_file='small_test')
::encode::
::Reading Datafile: pillowncase/pillowncase/files/pNcase_test.txt
::Encrypting Data
::Resizing Image to fit to data
::Writing data to Image
::Progress: 100%
::Image 'pNcase.png' created and saved

***KEEP THIS KEY SAFE YOU CANT DECRYPT WITHOUT IT***

***if your key starts with a - and you are using the example main class explicitly 
        reference it in the command line with -k='-your key starting with a -'***

::
::Decrypt Key: VVXeB8qWM1YYiQSud2vE0o0JZqRzwNUFjcBCGjI5rhs=
::

pillowncase.main module¶

pillowncase.__main__.main()[source]¶

you can run pillowncase from the command line where it invokes this main function you can run it as python -m pillowncase but for convenience it is aliased to pNcase when installed.

Example:

$ pNcase
::encode::
::Reading Datafile: pillowncase/pillowncase/files/pNcase_test.txt
::Resizing Image to fit to data
::Writing data to Image
::Progress: 100%
::Image 'pNcase_small_test.png' created and saved

$ pNcase -a decode -i pNcase_small_test.png
::Decode::
::Opened Image-file: pNcase_small_test.png
::Reading data from Image
::Progress: 100%::Found hidden file: pNcase_test.txt
::Successfully read data
::All done Data Written to file: pNcase_test.txt

`-h, --help`	Show help message text
`-f, --input_file filename`
	File to hide in image, if not supplied test data is used and a test image created
`-i, --image_file filename`
	Image file to hide input file in, if not there for encode a square data image is created with raw image data
`-o, --output_file filename`
	Output file name for created image (.png only) if not specified pNcase_(input_file).png used
`-c, --channels rgba`
	default ‘RGB’ channel letter(s) to store data in (RGBA) alpha will be added for output if not present and specified
`-g gggggggg`	Fine -g (larger file) -gggggggg (smaller file) default (-gggg) unless creating only data image when its (-gggggggg)
`-a, --action selection`
	‘encode’ or ‘decode’, default encode, decode with no image file will error and exit
`-v, --verbose vvvvvvvv`
	default v basic output, the more v’s the more output
`-m, --magic_header header`
	Magic header that pNcase looks for to start decoding defaults to XYZZY if you change it you’ll need to remember what it was to decode or be good reading binary, beware!
`-j, --custom_channels channels`
	Overrides granularity specify RGBA bit distribution manually 0 means no bits in that channel e.g. 1240 means R=1, G=2, B=4, A=0
`--do_not_resize_image`
	By default this will resize any image provided image to hide in to match data to be hidden, if you only have a small amount of data to hide you might not want to resize, use -g in this case to hide it well
`--encrypt_data`	default False, change to True if you want to encrypt the lead in header and data, uses a combination of XOR and Fernet, do some research look at the code see if that meets your needs, you will need the key to decrypt, a key is auto generated if not supplied. Don’t forget you can encrypt your data to hide however you like outside of this code, it will just do a like for like binary read and store of whatever file you point it at.
`-k, --key key`	Required to decrypt header, optional for encrypting, one will get generated if you don’t supply one when encrypting, you can then reuse if you want to use the same key to encrypt multiple files

Other Examples

Encrypt and Decrypt:

$ pNcase -i kitten -f medium_test -j 2240 --encrypt_data
::encode::
::Reading Datafile: pillowncase/pillowncase/files/pg29809.txt
::Encrypting Data
::Resizing Image to fit to data
::Writing data to Image
::Progress: 100%
::Image 'pNcase_medium_test.png' created and saved

***KEEP THIS KEY SAFE YOU CANT DECRYPT WITHOUT IT***

***if your key starts with a - and you are using the example main class explicitly
        reference it in the command line with -k='-your key starting with a -'***

::
::Decrypt Key: PaNmvZ4y3pmOcdDlHak0c393XR5FpIn2SKfZZ0WA52o=
::

$ pNcase -i pNcase_medium_test.png -k PaNmvZ4y3pmOcdDlHak0c393XR5FpIn2SKfZZ0WA52o= -a decode
::Decode::
::Opened Image-file: pNcase_medium_test.png
::Reading data from Image
::Progress: 100%
::Decrypting Data
::Using Key: PaNmvZ4y3pmOcdDlHak0c393XR5FpIn2SKfZZ0WA52o=
::Found hidden file: pg29809.txt
::Successfully read data
::All done Data Written to file: pg29809.txt

Create raw data image:

$ pNcase -f medium_raw_test
::encode::
::Reading Datafile: pillowncase/pillowncase/files/pg29809.txt
::Creating Image to put data in
::Writing data to Image
::Progress: 100%
::Image 'pNcase_medium_raw_test.png' created and saved

$ pNcase -a decode -i pNcase_medium_raw_test.png
::Decode::
::Opened Image-file: pNcase_medium_raw_test.png
::Reading data from Image
::Progress: 100%::Found hidden file: pg29809.txt
::Successfully read data
::All done Data Written to file: pg29809.txt

pillowncase package¶

pillowncase.pncase module¶

pillowncase.__main__ module¶

pillowncase.main module¶