Eet Data Serialization using A Ciphers

Most of the Eet Data Serialization have alternative versions that accounts for ciphers to protect their content. More...

Functions
EAPI void *	eet_data_read_cipher (Eet_File *ef, Eet_Data_Descriptor *edd, const char *name, const char *cipher_key)
	Reads a data structure from an eet file and decodes it using a cipher. More...
EAPI void *	eet_data_read_cipher_buffer (Eet_File *ef, Eet_Data_Descriptor *edd, const char *name, const char *cipher_key, char *buffer, int buffer_size)
	Reads a data structure from an eet file and decodes it into a buffer using a cipher. More...
EAPI void *	eet_data_xattr_cipher_get (const char *filename, const char *attribute, Eet_Data_Descriptor *edd, const char *cipher_key)
	Reads a data structure from an eet extended attribute and decodes it using a cipher. More...
EAPI int	eet_data_write_cipher (Eet_File *ef, Eet_Data_Descriptor *edd, const char *name, const char *cipher_key, const void *data, int compress)
	Writes a data structure from memory and store in an eet file using a cipher. More...
EAPI Eina_Bool	eet_data_xattr_cipher_set (const char *filename, const char *attribute, Eet_Data_Descriptor *edd, const char *cipher_key, const void *data, Eina_Xattr_Flags flags)
	Writes a data structure from memory and store in an eet extended attribute using a cipher. More...
EAPI int	eet_data_text_dump_cipher (const void *data_in, const char *cipher_key, int size_in, Eet_Dump_Callback dumpfunc, void *dumpdata)
	Dumps an eet encoded data structure into ascii text using a cipher. More...
EAPI void *	eet_data_text_undump_cipher (const char *text, const char *cipher_key, int textlen, int *size_ret)
	Takes an ascii encoding from eet_data_text_dump() and re-encode in binary using a cipher. More...
EAPI int	eet_data_dump_cipher (Eet_File *ef, const char *name, const char *cipher_key, Eet_Dump_Callback dumpfunc, void *dumpdata)
	Dumps an eet encoded data structure from an eet file into ascii text using a cipher. More...
EAPI int	eet_data_undump_cipher (Eet_File *ef, const char *name, const char *cipher_key, const char *text, int textlen, int compress)
	Takes an ascii encoding from eet_data_dump() and re-encode in binary using a cipher. More...
EAPI void *	eet_data_descriptor_decode_cipher (Eet_Data_Descriptor *edd, const void *data_in, const char *cipher_key, int size_in)
	Decodes a data structure from an arbitrary location in memory using a cipher. More...
EAPI void *	eet_data_descriptor_encode_cipher (Eet_Data_Descriptor *edd, const void *data_in, const char *cipher_key, int *size_ret)
	Encodes a data struct to memory and return that encoded data using a cipher. More...

Detailed Description

Most of the Eet Data Serialization have alternative versions that accounts for ciphers to protect their content.

See also

Cipher, Identity and Protection Mechanisms

Function Documentation

eet_data_read_cipher()

EAPI void * eet_data_read_cipher	(	Eet_File *	ef,
		Eet_Data_Descriptor *	edd,
		const char *	name,
		const char *	cipher_key
	)

Reads a data structure from an eet file and decodes it using a cipher.

Parameters

ef	The eet file handle to read from.
edd	The data descriptor handle to use when decoding.
name	The key the data is stored under in the eet file.
cipher_key	The key to use as cipher.

Returns

A pointer to the decoded data structure.

This function decodes a data structure stored in an eet file, returning a pointer to it if it decoded successfully, or NULL on failure. This can save a programmer dozens of hours of work in writing configuration file parsing and writing code, as eet does all that work for the program and presents a program-friendly data structure, just as the programmer likes. Eet can handle members being added or deleted from the data in storage and safely zero-fills unfilled members if they were not found in the data. It checks sizes and headers whenever it reads data, allowing the programmer to not worry about corrupt data.

Once a data structure has been described by the programmer with the fields they wish to save or load, storing or retrieving a data structure from an eet file, or from a chunk of memory is as simple as a single function call.

See also

eet_data_read()

Since

1.0.0

References eet_dictionary_get(), eet_read_cipher(), eet_read_direct(), and EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by eet_data_read().

eet_data_read_cipher_buffer()

EAPI void * eet_data_read_cipher_buffer	(	Eet_File *	ef,
		Eet_Data_Descriptor *	edd,
		const char *	name,
		const char *	cipher_key,
		char *	buffer,
		int	buffer_size
	)

Reads a data structure from an eet file and decodes it into a buffer using a cipher.

Parameters

ef	The eet file handle to read from.
edd	The data descriptor handle to use when decoding.
name	The key the data is stored under in the eet file.
cipher_key	The key to use as cipher.
buffer	Buffer.
buffer_size	The buffer size.

Returns

A pointer to buffer if successful, and NULL on error.

This function decodes a data structure stored in an eet file, returning a pointer to it if it decoded successfully, or NULL on failure. This can save a programmer dozens of hours of work in writing configuration file parsing and writing code, as eet does all that work for the program and presents a program-friendly data structure, just as the programmer likes. Eet can handle members being added or deleted from the data in storage and safely zero-fills unfilled members if they were not found in the data. It checks sizes and headers whenever it reads data, allowing the programmer to not worry about corrupt data.

Once a data structure has been described by the programmer with the fields they wish to save or load, storing or retrieving a data structure from an eet file, or from a chunk of memory is as simple as a single function call.

See also

eet_data_read_cipher()

Since

1.10.0

References eet_dictionary_get(), eet_read_cipher(), eet_read_direct(), and EINA_SAFETY_ON_NULL_RETURN_VAL.

eet_data_xattr_cipher_get()

EAPI void * eet_data_xattr_cipher_get	(	const char *	filename,
		const char *	attribute,
		Eet_Data_Descriptor *	edd,
		const char *	cipher_key
	)

Reads a data structure from an eet extended attribute and decodes it using a cipher.

Parameters

filename	The file to extract the extended attribute from.
attribute	The attribute to get the data from.
edd	The data descriptor handle to use when decoding.
cipher_key	The key to use as cipher.

Returns

A pointer to the decoded data structure.

This function decodes a data structure stored in an eet extended attribute, returning a pointer to it if it decoded successfully, or NULL on failure. Eet can handle members being added or deleted from the data in storage and safely zero-fills unfilled members if they were not found in the data. It checks sizes and headers whenever it reads data, allowing the programmer to not worry about corrupt data.

Once a data structure has been described by the programmer with the fields they wish to save or load, storing or retrieving a data structure from an eet file, from a chunk of memory or from an extended attribute is as simple as a single function call.

Since

1.5.0

References eet_data_descriptor_decode_cipher(), EINA_SAFETY_ON_NULL_RETURN_VAL, and eina_xattr_get().

eet_data_write_cipher()

EAPI int eet_data_write_cipher	(	Eet_File *	ef,
		Eet_Data_Descriptor *	edd,
		const char *	name,
		const char *	cipher_key,
		const void *	data,
		int	compress
	)

Writes a data structure from memory and store in an eet file using a cipher.

Parameters

ef	The eet file handle to write to.
edd	The data descriptor to use when encoding.
name	The key to store the data under in the eet file.
cipher_key	The key to use as cipher.
data	A pointer to the data structure to save and encode.
compress	Compression flags for storage.

Returns

bytes written on successful write, 0 on failure.

This function is the reverse of eet_data_read_cipher(), saving a data structure to an eet file.

Since

1.0.0

References eet_dictionary_get(), eet_write_cipher(), and EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by eet_data_write().

eet_data_xattr_cipher_set()

EAPI Eina_Bool eet_data_xattr_cipher_set	(	const char *	filename,
		const char *	attribute,
		Eet_Data_Descriptor *	edd,
		const char *	cipher_key,
		const void *	data,
		Eina_Xattr_Flags	flags
	)

Writes a data structure from memory and store in an eet extended attribute using a cipher.

Parameters

filename	The file to write the extended attribute to.
attribute	The attribute to store the data to.
edd	The data descriptor to use when encoding.
cipher_key	The key to use as cipher.
data	A pointer to the data structure to save and encode.
flags	The policy to use when setting the data.

Returns

EINA_TRUE on success, EINA_FALSE on failure.

This function is the reverse of eet_data_xattr_cipher_get(), saving a data structure to an eet extended attribute.

Since

1.5.0

References eet_data_descriptor_encode_cipher(), EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, and eina_xattr_set().

eet_data_text_dump_cipher()

EAPI int eet_data_text_dump_cipher	(	const void *	data_in,
		const char *	cipher_key,
		int	size_in,
		Eet_Dump_Callback	dumpfunc,
		void *	dumpdata
	)

Dumps an eet encoded data structure into ascii text using a cipher.

Parameters

data_in	The pointer to the data to decode into a struct.
cipher_key	The key to use as cipher.
size_in	The size of the data pointed to in bytes.
dumpfunc	The function to call passed a string when new data is converted to text
dumpdata	The data to pass to the dumpfunc callback.

Returns

1 on success, 0 on failure

This function will take a chunk of data encoded by eet_data_descriptor_encode() and convert it into human readable ascii text. It does this by calling the dumpfunc callback for all new text that is generated. This callback should append to any existing text buffer and will be passed the pointer dumpdata as a parameter as well as a string with new text to be appended.

Example:

void output(void *data, const char *string)
{
  printf("%s", string);
}
 
void dump(const char *file)
{
  FILE *f;
  int len;
  void *data;
 
  f = fopen(file, "rb");
  fseek(f, 0, SEEK_END);
  len = ftell(f);
  rewind(f);
  data = malloc(len);
  fread(data, len, 1, f);
  fclose(f);
  eet_data_text_dump_cipher(data, cipher_key, len, output, NULL);
}

See also

eet_data_text_dump()

Since

1.0.0

eet_data_text_undump_cipher()

EAPI void * eet_data_text_undump_cipher	(	const char *	text,
		const char *	cipher_key,
		int	textlen,
		int *	size_ret
	)

Takes an ascii encoding from eet_data_text_dump() and re-encode in binary using a cipher.

Parameters

text	The pointer to the string data to parse and encode.
cipher_key	The key to use as cipher.
textlen	The size of the string in bytes (not including 0 byte terminator).
size_ret	This gets filled in with the encoded data blob size in bytes.

Returns

The encoded data on success, NULL on failure.

This function will parse the string pointed to by text and return an encoded data lump the same way eet_data_descriptor_encode() takes an in-memory data struct and encodes into a binary blob. text is a normal C string.

See also

eet_data_text_undump()

Since

1.0.0

Referenced by eet_data_text_undump().

eet_data_dump_cipher()

EAPI int eet_data_dump_cipher	(	Eet_File *	ef,
		const char *	name,
		const char *	cipher_key,
		Eet_Dump_Callback	dumpfunc,
		void *	dumpdata
	)

Dumps an eet encoded data structure from an eet file into ascii text using a cipher.

Parameters

ef	A valid eet file handle.
name	Name of the entry. eg: "/base/file_i_want".
cipher_key	The key to use as cipher.
dumpfunc	The function to call passed a string when new data is converted to text
dumpdata	The data to pass to the dumpfunc callback.

Returns

1 on success, 0 on failure

This function will take an open and valid eet file from eet_open() request the data encoded by eet_data_descriptor_encode() corresponding to the key name and convert it into human readable ascii text. It does this by calling the dumpfunc callback for all new text that is generated. This callback should append to any existing text buffer and will be passed the pointer dumpdata as a parameter as well as a string with new text to be appended.

See also

eet_data_dump()

Since

1.0.0

eet_data_undump_cipher()

EAPI int eet_data_undump_cipher	(	Eet_File *	ef,
		const char *	name,
		const char *	cipher_key,
		const char *	text,
		int	textlen,
		int	compress
	)

Takes an ascii encoding from eet_data_dump() and re-encode in binary using a cipher.

Parameters

ef	A valid eet file handle.
name	Name of the entry. eg: "/base/file_i_want".
cipher_key	The key to use as cipher.
text	The pointer to the string data to parse and encode.
textlen	The size of the string in bytes (not including 0 byte terminator).
compress	Compression flags (1 == compress, 0 = don't compress).

Returns

1 on success, 0 on failure

This function will parse the string pointed to by text, encode it the same way eet_data_descriptor_encode() takes an in-memory data struct and encodes into a binary blob.

The data (optionally compressed) will be in ram, pending a flush to disk (it will stay in ram till the eet file handle is closed though).

See also

eet_data_undump()

Since

1.0.0

References eet_dictionary_get(), and eet_write_cipher().

Referenced by eet_data_undump().

eet_data_descriptor_decode_cipher()

EAPI void * eet_data_descriptor_decode_cipher	(	Eet_Data_Descriptor *	edd,
		const void *	data_in,
		const char *	cipher_key,
		int	size_in
	)

Decodes a data structure from an arbitrary location in memory using a cipher.

Parameters

edd	The data descriptor to use when decoding.
data_in	The pointer to the data to decode into a struct.
cipher_key	The key to use as cipher.
size_in	The size of the data pointed to in bytes.

Returns

NULL on failure, or a valid decoded struct pointer on success.

This function will decode a data structure that has been encoded using eet_data_descriptor_encode(), and return a data structure with all its elements filled out, if successful, or NULL on failure.

The data to be decoded is stored at the memory pointed to by data_in, and is described by the descriptor pointed to by edd. The data size is passed in as the value to size_in, and must be greater than 0 to succeed.

This function is useful for decoding data structures delivered to the application by means other than an eet file, such as an IPC or socket connection, raw files, shared memory etc.

Please see eet_data_read() for more information.

See also

eet_data_descriptor_decode()

Since

1.0.0

References EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by eet_data_descriptor_decode(), and eet_data_xattr_cipher_get().

eet_data_descriptor_encode_cipher()

EAPI void * eet_data_descriptor_encode_cipher	(	Eet_Data_Descriptor *	edd,
		const void *	data_in,
		const char *	cipher_key,
		int *	size_ret
	)

Encodes a data struct to memory and return that encoded data using a cipher.

Parameters

edd	The data descriptor to use when encoding.
data_in	The pointer to the struct to encode into data.
cipher_key	The key to use as cipher.
size_ret	pointer to the an int to be filled with the decoded size.

Returns

NULL on failure, or a valid encoded data chunk on success.

This function takes a data structure in memory and encodes it into a serialised chunk of data that can be decoded again by eet_data_descriptor_decode(). This is useful for being able to transmit data structures across sockets, pipes, IPC or shared file mechanisms, without having to worry about memory space, machine type, endianness etc.

The parameter edd must point to a valid data descriptor, and data_in must point to the right data structure to encode. If not, the encoding may fail.

On success a non NULL valid pointer is returned and what size_ret points to is set to the size of this decoded data, in bytes. When the encoded data is no longer needed, call free() on it. On failure NULL is returned and what size_ret points to is set to 0.

Please see eet_data_write() for more information.

See also

eet_data_descriptor_encode()

Since

1.0.0

References EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by eet_connection_send(), eet_data_descriptor_encode(), and eet_data_xattr_cipher_set().