facade::PNGPayload Class Reference

A PNG-based payload helper class. More...

#include <payload.hpp>

Inheritance diagram for facade::PNGPayload:

Public Member Functions
	PNGPayload ()
	PNGPayload (const void *ptr, std::size_t size)
	PNGPayload (const std::vector< std::uint8_t > &vec)
	PNGPayload (const std::string &filename)
	PNGPayload (const PNGPayload &other)
png::Text &	add_text_payload (const std::string &keyword, const void *ptr, std::size_t size)
	Add a tEXt section payload to the PNG file.
png::Text &	add_text_payload (const std::string &keyword, const std::vector< std::uint8_t > &data)
	Add a tEXt section payload to the PNG file.
void	remove_text_payload (const png::Text &payload)
	Remove the given tEXt payload from the PNG image.
std::vector< png::Text >	get_text_payloads (const std::string &keyword) const
	Get all corresponding tEXt payloads that match the given keyword.
std::vector< std::vector< std::uint8_t > >	extract_text_payloads (const std::string &keyword) const
	Extract the binary data from the tEXt payloads corresponding to a given keyword.
png::ZText &	add_ztext_payload (const std::string &keyword, const void *ptr, std::size_t size)
	Add a zTXt section payload to the PNG file.
png::ZText &	add_ztext_payload (const std::string &keyword, const std::vector< std::uint8_t > &data)
	Add a zTXt section payload to the PNG file.
void	remove_ztext_payload (const png::ZText &payload)
	Remove the given tEXt payload from the PNG image.
std::vector< png::ZText >	get_ztext_payloads (const std::string &keyword) const
	Get all corresponding zTXt payloads that match the given keyword.
std::vector< std::vector< std::uint8_t > >	extract_ztext_payloads (const std::string &keyword) const
	Extract the binary data from the zTXt payloads corresponding to a given keyword.
std::vector< std::uint8_t >	read_stego_data (std::size_t bit_offset, std::size_t size) const
	Read steganographically-encoded data at an arbitrary bit offset in the image.
void	write_stego_data (const void *ptr, std::size_t size, std::size_t bit_offset)
	Write steganographically-encoded data at the given bit offset in the image.
void	write_stego_data (const std::vector< std::uint8_t > &data, std::size_t bit_offset)
	Write steganographically-encoded data at the given bit offset in the image.
bool	has_stego_payload () const
	Check if the image has a steganographically-encoded payload.
PNGPayload	create_stego_payload (const void *ptr, std::size_t size) const
	Create a copy of the payload with a steganographically-encoded payload within the image data.
PNGPayload	create_stego_payload (const std::vector< std::uint8_t > &data) const
	Create a copy of the payload with a steganographically-encoded payload within the image data.
std::vector< std::uint8_t >	extract_stego_payload () const
	Return the steganographically-encoded data from the image.
Public Member Functions inherited from facade::png::Image
	Image ()
	Image (const void *ptr, std::size_t size, bool validate=true)
	Image (const std::vector< std::uint8_t > &data, bool validate=true)
	Image (const std::string &filename, bool validate=true)
	Image (const Image &other)
Image &	operator= (const Image &other)
	Syntatic sugar for assigning to an image object.
Scanline &	operator[] (std::size_t index)
	Syntactic sugar for getting a scanline from the loaded image.
const Scanline &	operator[] (std::size_t index) const
	Syntactic sugar for getting a const scanline from the loaded image.
bool	has_chunk (const std::string &tag) const
	Check for the presence of a given chunk tag.
std::vector< ChunkVec >	get_chunks (const std::string &tag) const
	Get the chunk data for the corresponding tag.
void	add_chunk (const ChunkVec &chunk)
	Add a given chunk to the underlying image.
bool	has_trailing_data () const
	Return whether or not this PNG image has trailing data.
std::vector< std::uint8_t > &	get_trailing_data ()
	Get the trailing data in the image.
const std::vector< std::uint8_t > &	get_trailing_data () const
	Get the const trailing data in the image.
void	set_trailing_data (const std::vector< std::uint8_t > &data)
	Set the trailing data of the PNG image.
void	clear_trailing_data ()
	Clear the trailing data in the PNG image.
void	parse (const void *ptr, std::size_t size, bool validate=true)
	Parse a given data buffer into its individual chunks for further processing.
void	parse (const std::vector< std::uint8_t > &data, bool validate=true)
	Parse a given data vector for a PNG image.
void	parse (const std::string &filename, bool validate=true)
	Read a file and parse it as a PNG file.
void	load ()
	Load the image data from the IDAT chunks.
Scanline &	scanline (std::size_t index)
	Get the scanline at the given y index.
const Scanline &	scanline (std::size_t index) const
	Get the const scanline at the given y index.
bool	has_header () const
	Check if this PNG image has a header present.
Header &	header ()
	Get the header present in the PNG image.
const Header &	header () const
	Get the const header present in the PNG image.
Header &	new_header ()
	Create and return a new blank header in the PNG image.
std::size_t	width () const
	Get the width, in pixels, of this image.
std::size_t	height () const
	Get the height, in pixels, of this image.
bool	has_image_data () const
	Return if the image has any IDAT chunks present.
bool	is_loaded () const
	Check if the image data has been extracted from the IDAT chunks.
void	decompress ()
	Decompress the IDAT chunks in the image.
void	compress (std::optional< std::size_t > chunk_size=8192, int level=-1)
	Compress the image data into IDAT chunks.
void	reconstruct ()
	Reconstruct the filtered image data into their raw, unfiltered form.
void	filter ()
	Filter the image data to prepare it for compression.
std::vector< std::uint8_t >	to_file () const
	Convert this object into an image buffer fit for saving to a .png file.
void	save (const std::string &filename) const
	Call facade::png::Image::to_file and save that file to disk.
bool	has_text () const
	Return whether or not the image contains a tEXt chunk.
Text &	add_text (const std::string &keyword, const std::string &text)
	Add a text chunk to the PNG image.
void	remove_text (const Text &text)
	Remove the given tEXt section from the image.
void	remove_text (const std::string &keyword, const std::string &text)
	Remove a tEXt section by keyword and text.
std::vector< Text >	get_text (const std::string &keyword) const
	Get the tEXt sections with the following keyword.
bool	has_ztext () const
	Return whether or not the image contains a zTXt chunk.
ZText &	add_ztext (const std::string &keyword, const std::string &text)
	Add a zTXt chunk to the PNG image.
void	remove_ztext (const ZText &ztext)
	Remove the given zTXt section from the image.
void	remove_ztext (const std::string &keyword, const std::string &text)
	Remove a zTXt section by keyword and text.
std::vector< ZText >	get_ztext (const std::string &keyword) const
	Get the zTXt sections with the following keyword.

Additional Inherited Members
Static Public Attributes inherited from facade::png::Image
static const std::uint8_t	Signature [8] = { 0x89, 'P', 'N', 'G', '\r', '\n', 0x1a, '\n' }
	The header signature of a valid PNG file.
Protected Attributes inherited from facade::png::Image
std::map< std::string, std::vector< ChunkVec > >	chunk_map
	A map of chunk tags to their corresponding facade::png::ChunkVec types.
std::optional< std::vector< std::uint8_t > >	trailing_data
	A container for trailing data, if present when parsing or when writing afterward.
std::optional< std::vector< Scanline > >	image_data
	The loaded image data from the compressed IDAT chunks.

Detailed Description

A PNG-based payload helper class.

There are four main ways to add payloads to images:

• Trailing data: data appended to the very end of a PNG image. This is the "quick and dirty" solution to adding arbitrary payload data to a PNG image. See facade::png::Image::set_trailing_data.
• tEXt section: a tEXt chunk with base64-encoded binary data. See facade::PNGPayload::add_text_payload.
• zTXt section: a zTXt chunk where the base64-encoded data is compressed. See facade::PNGPayload::add_ztext_payload.
• Steganography: a steganographic payload across the raw PNG image data. See facade::PNGPayload::create_stego_payload.

Here is an example of encoding payloads into a PNG image:

#include <facade.hpp>
 
using namespace facade;
 
int main(int argc, char *argv[]) {
   PNGPayload image("../test/art.png");
   std::string payload_string("Just an arbitrary payload, nothing suspicious here!");
   std::vector<std::uint8_t> payload_data(payload_string.begin(), payload_string.end());
 
   // we can add a payload to the end of the file
   image.set_trailing_data(payload_data);
 
   // or a text section
   image.add_text_payload("tEXt payload", payload_data);
 
   // or a ztxt section
   image.add_ztext_payload("zTXt payload", payload_data);
 
   // or a stego-encoded payload
   auto final_payload = image.create_stego_payload(payload_data);
 
   // finally, we can save our payload to a new file.
   final_payload.save("art.payload.png");
 
   return 0;
}
   

And here is an example of extracting payloads from a PNG image:

#include <facade.hpp>
#include <cassert>
 
using namespace facade;
 
int main(int argc, char *argv[]) {
   PNGPayload image("art.payload.png");
   std::string expected_string("Just an arbitrary payload, nothing suspicious here!");
   std::vector<std::uint8_t> expected_data(expected_string.begin(), expected_string.end());
 
   // we can then extract the payload from the end of the file
   assert(image.get_trailing_data() == expected_data);
 
   // or the text section
   assert(image.extract_text_payloads("tEXt payload")[0] == expected_data);
 
   // or the ztxt section
   assert(image.extract_ztext_payloads("zTXt payload")[0] == expected_data);
 
   // in order to get stego data, we need to load the image first, THEN extract it
   image.load();
   assert(image.extract_stego_payload() == expected_data);
 
   return 0;
}

Constructor & Destructor Documentation

PNGPayload() [1/5]

facade::PNGPayload::PNGPayload ( )

inline

PNGPayload() [2/5]

facade::PNGPayload::PNGPayload ( const void *  ptr, std::size_t  size  )

inline

PNGPayload() [3/5]

facade::PNGPayload::PNGPayload ( const std::vector< std::uint8_t > &  vec )

inline

PNGPayload() [4/5]

facade::PNGPayload::PNGPayload ( const std::string &  filename )

inline

PNGPayload() [5/5]

facade::PNGPayload::PNGPayload ( const PNGPayload &  other )

inline

Member Function Documentation

add_text_payload() [1/2]

png::Text & PNGPayload::add_text_payload	(	const std::string &	keyword,
		const std::vector< std::uint8_t > &	data
	)

Add a tEXt section payload to the PNG file.

The same keyword can be added multiple times.

Parameters

keyword	The keyword to give to the tEXt section payload.
data	The byte vector to add to the payload.

Returns

A facade::png::Text object representing the newly added section to the PNG image.

See also

facade::png::Text

add_text_payload() [2/2]

png::Text & PNGPayload::add_text_payload	(	const std::string &	keyword,
		const void *	ptr,
		std::size_t	size
	)

Add a tEXt section payload to the PNG file.

The same keyword can be added multiple times.

Parameters

keyword	The keyword to give to the tEXt section payload.
ptr	The pointer of data to add to the payload.
size	The size of the given data.

Returns

A facade::png::Text object representing the newly added section to the PNG image.

See also

facade::png::Text

add_ztext_payload() [1/2]

png::ZText & PNGPayload::add_ztext_payload	(	const std::string &	keyword,
		const std::vector< std::uint8_t > &	data
	)

Add a zTXt section payload to the PNG file.

The same keyword can be added multiple times.

Parameters

keyword	The keyword to give to the zTXt section payload.
data	The byte vector to add to the payload.

Returns

A facade::png::ZText object representing the newly added section to the PNG image.

See also

facade::png::ZText

add_ztext_payload() [2/2]

png::ZText & PNGPayload::add_ztext_payload	(	const std::string &	keyword,
		const void *	ptr,
		std::size_t	size
	)

Add a zTXt section payload to the PNG file.

The same keyword can be added multiple times.

Parameters

keyword	The keyword to give to the zTXt section payload.
ptr	The given data pointer.
size	The size of the data pointer, in bytes.

Returns

A facade::png::ZText object representing the newly added section to the PNG image.

See also

facade::png::ZText

create_stego_payload() [1/2]

PNGPayload PNGPayload::create_stego_payload

(

const std::vector< std::uint8_t > &

data

)

const

Create a copy of the payload with a steganographically-encoded payload within the image data.

Parameters

data	The vector of byte data to encode in the image.

Returns

A facade::PNGPayload object with a steganographic payload.

Exceptions

facade::exception::UnsupportedPixelType
facade::exception::ImageTooSmall

create_stego_payload() [2/2]

PNGPayload PNGPayload::create_stego_payload	(	const void *	ptr,
		std::size_t	size
	)		const

Create a copy of the payload with a steganographically-encoded payload within the image data.

Parameters

ptr	The buffer of data to encode in the image.
size	The size, in bytes, of the given pointer data.

Returns

A facade::PNGPayload object with a steganographic payload.

Exceptions

facade::exception::UnsupportedPixelType
facade::exception::ImageTooSmall

extract_stego_payload()

std::vector< std::uint8_t > PNGPayload::extract_stego_payload

(

)

const

Return the steganographically-encoded data from the image.

Returns

A byte vector of the encoded data.

Exceptions

facade::exception::NoImageData
facade::exception::NoStegoData

extract_text_payloads()

std::vector< std::vector< std::uint8_t > > PNGPayload::extract_text_payloads

(

const std::string &

keyword

)

const

Extract the binary data from the tEXt payloads corresponding to a given keyword.

Parameters

keyword

The keyword of the given payloads.

Returns

A vector of byte vectors corresponding to the payloads matching the keyword argument.

Exceptions

facade::exception::InvalidBase64String
facade::exception::InvalidBase64Character

extract_ztext_payloads()

std::vector< std::vector< std::uint8_t > > PNGPayload::extract_ztext_payloads

(

const std::string &

keyword

)

const

Extract the binary data from the zTXt payloads corresponding to a given keyword.

Parameters

keyword

The keyword of the given payloads.

Returns

A vector of byte vectors corresponding to the payloads matching the keyword argument.

Exceptions

facade::exception::InvalidBase64String
facade::exception::InvalidBase64Character
facade::exception::ZLibError

get_text_payloads()

std::vector< png::Text > PNGPayload::get_text_payloads

(

const std::string &

keyword

)

const

Get all corresponding tEXt payloads that match the given keyword.

Parameters

keyword

The keyword to retrieve payloads from.

Returns

A vector of facade::png::Text objects corresponding

Exceptions

facade::exception::InvalidBase64String

get_ztext_payloads()

std::vector< png::ZText > PNGPayload::get_ztext_payloads

(

const std::string &

keyword

)

const

Get all corresponding zTXt payloads that match the given keyword.

Parameters

keyword

The keyword to retrieve payloads from.

Returns

A vector of facade::png::Text objects corresponding

Exceptions

facade::exception::InvalidBase64String
facade::exception::ZLibError

has_stego_payload()

bool PNGPayload::has_stego_payload

(

)

const

Check if the image has a steganographically-encoded payload.

Returns

Whether or not this image has steganographically-encoded data.

Exceptions

facade::exception::NoImageData

read_stego_data()

std::vector< std::uint8_t > PNGPayload::read_stego_data	(	std::size_t	bit_offset,
		std::size_t	size
	)		const

Read steganographically-encoded data at an arbitrary bit offset in the image.

Note that the bit offset must be a multiple of 4.

Parameters

bit_offset	The offset, in bits, to start reading the data.
size	The size, in bytes, of the data to read.

Returns

The stego-encoded data slice from the image.

Exceptions

facade::exception::NoImageData
facade::exception::OutOfBounds
facade::exception::PixelMismatch
facade::exception::InvalidBitOffset

remove_text_payload()

void PNGPayload::remove_text_payload

(

const png::Text &

payload

)

Remove the given tEXt payload from the PNG image.

Parameters

payload

The payload section to remove.

Exceptions

facade::exception::TextNotFound

remove_ztext_payload()

void PNGPayload::remove_ztext_payload

(

const png::ZText &

payload

)

Remove the given tEXt payload from the PNG image.

Parameters

payload

The payload section to remove.

Exceptions

facade::exception::TextNotFound

write_stego_data() [1/2]

void PNGPayload::write_stego_data	(	const std::vector< std::uint8_t > &	data,
		std::size_t	bit_offset
	)

Write steganographically-encoded data at the given bit offset in the image.

Note that the bit offset must be a multiple of 4.

Parameters

data	The byte vector to write into the image.
bit_offset	The offset, in bits, to start writing to.

Exceptions

facade::exception::NoImageData
facade::exception::OutOfBounds
facade::exception::PixelMismatch
facade::exception::InvalidBitOffset

write_stego_data() [2/2]

void PNGPayload::write_stego_data	(	const void *	ptr,
		std::size_t	size,
		std::size_t	bit_offset
	)

Write steganographically-encoded data at the given bit offset in the image.

Note that the bit offset must be a multiple of 4.

Parameters

ptr	The buffer pointer to write.
size	The size of the buffer, in bytes.
bit_offset	The offset, in bits, to start writing to.

Exceptions

facade::exception::NoImageData
facade::exception::OutOfBounds
facade::exception::PixelMismatch
facade::exception::InvalidBitOffset

---

The documentation for this class was generated from the following files:

• include/facade/payload.hpp
• src/payload.cpp