Class for storing and retrieving encrypted data to and from disk. More...

#include <file.h>

Collaboration diagram for YAPET::File:

Classes
union	ENDIAN
Public Member Functions
	File (const std::string &fn, const Key &key, bool create=false, bool secure=true) throw (YAPETException)
	Constructor.
	File (const File &f) throw (YAPETException)
bool	filesecurityEnabled () const
	Returns whether or not file security is enabled.
std::string	getFilename () const
	Returns the file name of the current file.
FILE_VERSION	getFileVersion (const Key &key) const throw (YAPETException, YAPETInvalidPasswordException)
	Return the file version.
int64_t	getMasterPWSet (const Key &key) const throw (YAPETException, YAPETInvalidPasswordException)
const File &	operator= (const File &f) throw (YAPETException)
	Returns the time the master password was set.
std::list< PartDec >	read (const Key &key) const throw (YAPETException)
	Reads the stored password records from the file.
void	save (std::list< PartDec > &records) throw (YAPETException)
	Saves a password record list.
void	setFilesecurity (bool secure)
	Sets file security.
void	setNewKey (const Key &oldkey, const Key &newkey) throw (YAPETException)
	Sets a new encryption key for the current file.
	~File ()
Protected Member Functions
void	initFile (const Key &key) throw (YAPETException)
	Initializes an empty file.
template<class t >
t	int_from_disk (t i) const
	The given integer will be converted to the endianess of the host.
template<class t >
t	int_from_disk (t i) const
	The given integer will be converted to the endianess of the host.
template<class t >
t	int_to_disk (t le) const
	The given integer will be converted to big endian format.
template<class t >
t	int_to_disk (t i) const
	The given integer will be converted to big endian format.
bool	isempty () const throw (YAPETException)
	Indicates whether or not the file is empty.
BDBuffer *	read () const throw (YAPETException)
	Reads from the current offset in the file.
BDBuffer *	readHeader () const throw (YAPETException)
	Reads the encrypted header.
void	readHeader (const Key &key, Record< FileHeader_32 > ptr32, Record< FileHeader_64 > ptr64) const throw (YAPETException)
	Reads the encrypted header and return it decrypted.
void	seekDataSection () const throw (YAPETException)
	Seeks to the first password record length indicator in //! the file.
void	validateKey (const Key &key) throw (YAPETException, YAPETInvalidPasswordException)
	Validates the given key.
void	write (const BDBuffer &buff, bool forceappend=false, bool forcewrite=false) throw (YAPETException, YAPETRetryException)
	Writes at the current offset in the file.
void	writeHeader (const BDBuffer &enc_header) throw (YAPETException)
	Writes the given encrypted header to the file.
void	writeHeader (const Record< FileHeader_64 > &header, const Key &key) throw (YAPETException)
	Writes the given header encrypted to the file.
Private Member Functions
void	checkFileSecurity () throw (YAPETException)
	Checks the permissions and owner of a file for security.
int64_t	lastModified () const throw (YAPETException)
	Returns the last modification time of the open file.
void	openCreate () throw (YAPETException)
	Creates and opens a new file.
void	openNoCreate () throw (YAPETException)
	Opens an existing file.
void	preparePWSave () throw (YAPETException)
	Prepare the file for saving the password records.
void	seekAbs (off_t offset) const throw (YAPETException)
	Seek to an absolute offset.
void	seekCurr (off_t offset) const throw (YAPETException)
	Seek to a position relative to the current offset.
void	setFileSecurity () throw (YAPETException)
	Sets the owner and permissions on a file.
Private Attributes
int	fd
std::string	filename
int64_t	mtime
	The modification time of the file.
bool	usefsecurity
	Flag for enabling file security.

Detailed Description

This class takes care of storing and retrieving encrypted password records to and from disk.

Each file created by this class starts with a unencrypted recognition string which currently consists of the 8 bytes "YAPET1.0" as depicted below.

    +--------+--------+--------+--------+--------+--------+--------+--------+
    |   Y    |   A    |   P    |   E    |   T    |   1    |   .    |   0    |
    | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte |
    +--------+--------+--------+--------+--------+--------+--------+--------+

After the recognition string a 4 byte unsigned integer which is stored in big-endian order follows. This indicator is read to determine how many bytes to read in order to get the encrypted header.

    +--------+--------+--------+--------+
    |   Length indicator in big-endian  |
    |         order (4 bytes)           |
    +--------+--------+--------+--------+--...---+
    |  Encrypted header exactly as many bytes    |
    |        indicated by the prefix             |
    +--------+--------+--------+--------+--...---+

The decrypted header is 25 bytes in size (pre version 0.6). The first byte indicates the version of the file. The next 20 bytes are used as control string. After decryption, the control string is compared to the predefined clear text control string, in order to find out whether or not the key used to decrypt was the same used to encrypt.

    +--------+
    |Version |
    | 1 byte |
    +--------+--------+--------+--...---+
    |          Control String           |
    |             20 bytes              |
    +--------+--------+--------+--...---+
    |  Time when the Password  |
    |    was set (4 bytes)     |
    +--------+--------+--------+

As of version 0.6, it File reads headers using a time_t value of 32 or 64 bits (see above for 32 bits header). It writes always a header with 64 bits as shown below. The header size is 29 bytes.

    +--------+
    |Version |
    | 1 byte |
    +--------+--------+--------+--...---+
    |          Control String           |
    |             20 bytes              |
    +--------+--------+--------+--...---+--------+--------+--------+--------+
    |             Time when the Password was set (8 bytes)                  |
    |                                                                       |
    +--------+--------+--------+--------+--------+--------+--------+--------+

Each encrypted password record is prefixed by a 4 byte unsigned integer which is stored in big-endian order. The methods take care returning them in the appropriate order of the host system. That integer is used to indicate the length of the following encrypted data chunk.

    +--------+--------+--------+--------+
    |   Length indicator in big-endian  |
    |         order (4 bytes)           |
    +--------+--------+--------+--------+--...---+
    |  Encrypted password record of exactly as   |
    |   many bytes as indicated by the prefix    |
    +--------+--------+--------+--------+--...---+
    |   Length indicator in big-endian  |
    |         order (4 bytes)           |
    +--------+--------+--------+--------+--...---+
    |  Encrypted password record of exactly as   |
    |   many bytes as indicated by the prefix    |
    +--------+--------+--------+--------+--...---+
          [ . . . ]

Putting this together, an encrypted file created by this class looks like this

    +--------+--------+--------+--------+--------+--------+--------+--------+
    |   Y    |   A    |   P    |   E    |   T    |   1    |   .    |   0    |
    | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte | 1 byte |
    +--------+--------+--------+--------+--------+--------+--------+--------+
    |   Length indicator in big-endian  |
    |         order (4 bytes)           |
    +--------+--------+--------+--------+--...---+
    |  Encrypted header exactly as many bytes    |
    |        indicated by the prefix             |
    +--------+--------+--------+--------+--...---+
    |   Length indicator in big-endian  |
    |         order (4 bytes)           |
    +--------+--------+--------+--------+--...---+
    |  Encrypted password record of exactly as   |
    |   many bytes as indicated by the prefix    |
    +--------+--------+--------+--------+--...---+
    |   Length indicator in big-endian  |
    |         order (4 bytes)           |
    +--------+--------+--------+--------+--...---+
    |  Encrypted password record of exactly as   |
    |   many bytes as indicated by the prefix    |
    +--------+--------+--------+--------+--...---+
          [ . . . ]

Instances of this class keeps the file open for the lifetime of the instance.

When saving a password record list, the file is reopened with the O_TRUNC specified. The recognition string and header are copied over from the former version of the file.

The term 32bit header refers to the FileHeader_32 struct, because of the use of int32_t for storing the time the password was set.

The term 64bit header refers to the FileHeader_64 struct, because of the use of int64_t for storing the time the password was set.

See also:: Record, FileHeader, PasswordRecord

Definition at line 193 of file file.h.

Constructor & Destructor Documentation

File::File	(	const std::string &	fn,
		const Key &	key,
		bool	create = `false`,
		bool	secure = `true`
	)			throw (YAPETException)

Opens the file specified. Optionally creates the file if it does not exist and create is set true.

When opening an existing file, the key provided is validated. When creating a new file, the key is used to encrypt the header.

The file opened or created will stay open as long as the instance of this class exists. There is no method for closing the file. Only the destructor closes the file.

Parameters:

	fn	string holding the file name
	key	the key used for verification or encrypting the file header
	create	flag indicating whether the file should be created (`true`) or just opened (`false`). Be aware that passing `true` to this flag always causes the file to be created. Even if it already exists. Existing files will be truncated and the data stored will be lost.
	secure	if `true`, the functions checks whether or not the file permissions are secure. If `false`, file permissions are not checked for security. When creating a file and the value is `true`, the file is created using secure file permissions meaning only the owner has write and read access. Else, the owner has read and write access, the group and world has read access.

Definition at line 739 of file file.cc.

File::File ( const File & f ) throw (YAPETException)

Duplicates the file descriptor by calling dup().

Definition at line 756 of file file.cc.

File::~File ( )

Closes the file.

Definition at line 770 of file file.cc.

References fd.

Member Function Documentation

void File::checkFileSecurity ( ) throw (YAPETException) [private]

Checks the permission and owner of a file for security.

It throws a YAPETRetryException if the owner of the file does not match the uid of the owner of the process, or if the mode is not (S_IRUSR|S_IWUSR).

Definition at line 111 of file file.cc.

References fd, and filename.

Referenced by openCreate(), and openNoCreate().

Here is the caller graph for this function:

bool YAPET::File::filesecurityEnabled ( ) const [inline]

Definition at line 389 of file file.h.

References usefsecurity.

std::string YAPET::File::getFilename ( ) const [inline]

Definition at line 377 of file file.h.

References filename.

Referenced by MainWindow::changePassword(), MainWindow::lockScreen(), MainWindow::printTitle(), MainWindow::run(), and MainWindow::saveFile().

Here is the caller graph for this function:

FILE_VERSION File::getFileVersion ( const Key & key ) const throw (YAPETException, YAPETInvalidPasswordException)

New since version 0.6.

Return the file version.

Definition at line 956 of file file.cc.

References YAPET::FileHeader_64::version, and YAPET::FileHeader_32::version.

Referenced by MainWindow::bottomRightWinContent().

Here is the caller graph for this function:

int64_t File::getMasterPWSet ( const Key & key ) const throw (YAPETException, YAPETInvalidPasswordException)

Modified in version 0.6.

Returns the time as a uint64_t when the master password was set.

Parameters:

key

the key used to decrypt the header.

Returns:: a uint64_t representing the time the master password was set.

Definition at line 920 of file file.cc.

References YAPET::FileHeader_64::pwset, and YAPET::FileHeader_32::pwset.

Referenced by MainWindow::bottomRightWinContent().

Here is the caller graph for this function:

void File::initFile ( const Key & key ) throw (YAPETException) [protected]

Modified in version 0.6.

As of version 0.6, creates a header struct FileHeader_64 and calls writeHeader. It then reads and decrypts the header in order to verify.

Parameters:

key

reference to the key used to encrypt the header.

Definition at line 433 of file file.cc.

References YAPET::FileHeader_64::control, CONTROL_STR, YAPET::Crypt::decrypt(), YAPET::HEADER_CONTROL_SIZE, YAPET::FileHeader_64::pwset, and YAPET::FileHeader_64::version.

Here is the call graph for this function:

template<class t >

t YAPET::File::int_from_disk ( t i ) const [inline, protected]

Converts the length indicator read from the file to the host byte order. The length indicator is always stored in big endian order.

Parameters:

i

the length indicator as read from the file

Returns:: an unsigned 32 bits integer in host byte order.

Definition at line 296 of file file.h.

template<class t >

t YAPET::File::int_from_disk ( t i ) const [inline, protected]

Converts the length indicator read from the file to the host byte order. The length indicator is always stored in big endian order.

Parameters:

i

the length indicator as read from the file

Returns:: an unsigned integer in host byte order.

Definition at line 328 of file file.h.

template<class t >

t YAPET::File::int_to_disk ( t le ) const [inline, protected]

Converts the length indicator provided to the big endian byte order, suitable for writing to disk.

Parameters:

i

the length indicator in host byte order

Returns:: an unsigned integer in big-endian format.

Definition at line 276 of file file.h.

References YAPET::File::ENDIAN< t >::fields, and YAPET::File::ENDIAN< t >::value.

template<class t >

t YAPET::File::int_to_disk ( t i ) const [inline, protected]

Converts the length indicator provided to the big endian byte order, suitable for writing to disk.

Parameters:

i

the length indicator in host byte order

Returns:: an unsigned integer in big-endian format.

Definition at line 312 of file file.h.

bool File::isempty ( ) const throw (YAPETException) [protected]

Indicates whether or not the file specified by fd is empty.

Returns:: true if the file's size is zero, false otherwise.

Definition at line 411 of file file.cc.

References fd.

int64_t File::lastModified ( ) const throw (YAPETException) [private]

Returns the time of the last modification of the file specified by fd.

Returns:: a time_t holdign the last modification date.

Definition at line 210 of file file.cc.

References fd.

Referenced by preparePWSave().

Here is the caller graph for this function:

void File::openCreate ( ) throw (YAPETException) [private]

Creates a file with name specified in filename and sets fd to the obtained file descriptor. The file is opened for read-write.

Definition at line 175 of file file.cc.

References checkFileSecurity(), fd, filename, and usefsecurity.

Referenced by preparePWSave().

Here is the call graph for this function:

Here is the caller graph for this function:

void File::openNoCreate ( ) throw (YAPETException) [private]

Opens an existing file in read-write mode. If the file does not exist, the method throws an exception.

Definition at line 193 of file file.cc.

References checkFileSecurity(), fd, filename, and usefsecurity.

Here is the call graph for this function:

const File & File::operator= ( const File & f ) throw (YAPETException)

Definition at line 986 of file file.cc.

void File::preparePWSave ( ) throw (YAPETException) [private]

Truncates the file up to the header by creating a new empty file copying over the existing header.

Definition at line 257 of file file.cc.

References fd, lastModified(), mtime, openCreate(), readHeader(), and writeHeader().

Here is the call graph for this function:

std::list< PartDec > File::read ( const Key & key ) const throw (YAPETException)

Reads the stored records from the file using the key provided and returns a list holding the partially decrypted records. If the file has no records stored, it returns an empty list.

Parameters:

key

the key used to decrypt the records. It has to be same key that was used to encrypt the records, of course.

Returns:: a list holding the partially decrypted records. Or an empty list if no records are stored in the file

See also:: PartDec

Definition at line 809 of file file.cc.

BDBuffer * File::read ( ) const throw (YAPETException) [protected]

Reads from the current position in the file. The method expects the file pointer to point a record length indicator. In other words, it first reads four bytes from the current file position, which will give it a clue about the length of the encrypted record to read.

It then reads as many bytes as indicated from the file and returns the data read in a BDBuffer. The memory allocated by the BDBuffer has to be freed by the caller.

The record length indicator needs to be stored in big-endian order.

Returns:: a pointer to a BDBuffer holding the encrypted password record. The memory occupied by the buffer has to be freed by the caller of the method. It returns NULL when the end of file has been reached.

Definition at line 314 of file file.cc.

References fd, and filename.

Referenced by MainWindow::changePassword(), readHeader(), seekDataSection(), and setNewKey().

Here is the caller graph for this function:

void File::readHeader	(	const Key &	key,
		Record< FileHeader_32 > **	ptr32,
		Record< FileHeader_64 > **	ptr64
	)			const throw (YAPETException) `[protected]`

New in version 0.6.

It returns the header decrypted. The caller have to check the pointers returned for null values in order to determine which header to use, e.g.

 if (ptr32 != NULL) {
    // do something
 } else if (ptr64 != NULL) {
    // do something
 } else {
    // error
 }

The memory allocated by the method for the records have to be freed by the caller.

Parameters:

	key	reference to a Key object used to decrypt the header.
	ptr32	the 32bit header record. If the yapet file does not contain a FileHeader_32, NULL is returned.
	ptr64	the 64bit header record. If the yapet file does not contain a FileHeader_64, NULL is returned.

Definition at line 582 of file file.cc.

References YAPET::Crypt::decrypt(), and YAPET::NULLPOINTER.

Here is the call graph for this function:

BDBuffer * File::readHeader ( ) const throw (YAPETException) [protected]

Reads the encrypted header from the file. It also checks whether or not the file is of the expected type by reading the recognition string. If the string read does not match the one predefined, it throws an YAPETException.

The memory occupied by the BDBuffer returned has to be freed by the caller.

Returns:: pointer to a BDBuffer holding the encrypted file header. The memory occupied has to be freed by the caller.

Definition at line 531 of file file.cc.

References fd, read(), RECOG_STR, and seekAbs().

Referenced by preparePWSave().

Here is the call graph for this function:

Here is the caller graph for this function:

void File::save ( std::list< PartDec > & records ) throw (YAPETException)

Stores the list of PartDec records in the file.

Parameters:

records list of PartDec records

See also:: PartDec

Definition at line 782 of file file.cc.

Referenced by CSVImport::import(), and MainWindow::saveFile().

Here is the caller graph for this function:

void File::seekAbs ( off_t offset ) const throw (YAPETException) [private]

Seeks offset bytes from the beginning of the file.

Parameters:

offset

the offset in bytes from the beginning.

Definition at line 241 of file file.cc.

Referenced by readHeader(), and seekDataSection().

Here is the caller graph for this function:

void File::seekCurr ( off_t offset ) const throw (YAPETException) [private]

Seeks offset bytes from the current position in the file specified by fd.

Parameters:

offset

the offset in bytes from the current position in the file.

Definition at line 228 of file file.cc.

Referenced by seekDataSection().

Here is the caller graph for this function:

void File::seekDataSection ( ) const throw (YAPETException) [protected]

Seeks to the first password record in the file. The file pointer is set to point to the record length indicator, so that a call to read() will return the first password record.

Definition at line 281 of file file.cc.

References fd, read(), RECOG_STR, seekAbs(), and seekCurr().

Here is the call graph for this function:

void File::setFileSecurity ( ) throw (YAPETException) [private]

Sets the owner and permissions on a file in a manner that File::checkFileSecurity does not complain.

If it cannot set the security permissions, it throws a YAPETRetryException if the error can be avoided using non-secure settings.

Definition at line 143 of file file.cc.

References fd, and filename.

void YAPET::File::setFilesecurity ( bool secure ) [inline]

Definition at line 393 of file file.h.

References usefsecurity.

void File::setNewKey	(	const Key &	oldkey,
		const Key &	newkey
	)			throw (YAPETException)

Uses a new key to encrypt the records in the file. The records stored in the file are decrypted using the old key and then encrypted using the new key.

Before performing this operation, it renames the file encrypted with the old key to 'filename + ".bak"'. It then reads the data from this file and writes it to the newly created file named 'filename'.

Parameters:

	oldkey	the old key used to encrypt the records
	newkey	the new key used to encrypt the records

Definition at line 847 of file file.cc.

References YAPET::Crypt::decrypt(), YAPET::Crypt::encrypt(), and read().

Referenced by MainWindow::changePassword().

Here is the call graph for this function:

Here is the caller graph for this function:

void File::validateKey ( const Key & key ) throw (YAPETException, YAPETInvalidPasswordException) [protected]

Modified in version 0.6

Validates the key provided by reading the file header, decrypting it and comparing the control string of the file header with the string RECOG_STR. If those operations succeed, the key is considered valid. In case of an error, an exception is thrown.

Since this method relies on readHeader(), the file type is checked automatically.

Parameters:

key

the key to validate against the file.

Definition at line 676 of file file.cc.

References YAPET::FileHeader_64::control, YAPET::FileHeader_32::control, CONTROL_STR, and YAPET::HEADER_CONTROL_SIZE.

void File::write	(	const BDBuffer &	buff,
		bool	forceappend = `false`,
		bool	forcewrite = `false`
	)			throw (YAPETException, YAPETRetryException) `[protected]`

Writes the supplied BDBuffer to disk. It writes in front of the BDBuffer its length. The length is stored in big-endian order.

Parameters:

	buff	reference to a `BDBuffer` holding the encrypted data to write
	forceappend	if this flag is set to `true`, the method first seeks to the end of the file, if set to `false`, it writes at the position the file pointer points to.
	forcewrite	before writing any data, the method checks whether the last modification date stored in `mtime` matches the date returned by `lastModified()`. If they differ, and this flag is set to `false`, the write operation will fail and an exception is thrown. If the flag is set to `true`, it writes the data to the file regardless of the last modification date.

Exceptions:

YAPETRetryException if the file has been externally modified (outside of this class), and forcewrite is not true, this exception is thrown.

Definition at line 371 of file file.cc.

void File::writeHeader	(	const Record< FileHeader_64 > &	header,
		const Key &	key
	)			throw (YAPETException) `[protected]`

Modified in version 0.6.

Encrypts and writes the file header provided to the file.

Since version 0.6 it expects by default a FileHeader_64 header.

Parameters:

	header	a reference to the header. It will be encrypted using the key provided.
	key	the key used to encrypt the header provided.

Definition at line 472 of file file.cc.

References YAPET::Crypt::encrypt().

Referenced by preparePWSave().

Here is the call graph for this function:

Here is the caller graph for this function:

void File::writeHeader ( const BDBuffer & enc_header ) throw (YAPETException) [protected]

Writes the recognition string at the beginning of the file and eventually the provided header enc_header

Parameters:

enc_header

reference to a BDBuffer holding the encrypted header

Definition at line 503 of file file.cc.

References RECOG_STR.

Member Data Documentation

int YAPET::File::fd [private]

The file descriptor of the password file.

Definition at line 200 of file file.h.

Referenced by checkFileSecurity(), isempty(), lastModified(), openCreate(), openNoCreate(), preparePWSave(), read(), readHeader(), seekDataSection(), setFileSecurity(), and ~File().

std::string YAPET::File::filename [private]

The file name of the file.

Definition at line 206 of file file.h.

Referenced by checkFileSecurity(), getFilename(), openCreate(), openNoCreate(), read(), and setFileSecurity().

int64_t YAPET::File::mtime [private]

Holds the modification time of the file. It has to be updated each time a write occurs.

This is used to detect file modification made outside this class.

As of version 0.6, a 64 bit variable is used

Definition at line 218 of file file.h.

Referenced by preparePWSave().

bool YAPET::File::usefsecurity [private]

In this context "file security" means tight access restrictions on the files created, or refusing to read a file that has not tight access restriction set.

If this flag is true, reading a file not having the mode 0600 is not allowed and files created will have the mode 0600. Setting this to false, will disable the checks and not enforce the mode 0600 when writing files.

Definition at line 232 of file file.h.

Referenced by filesecurityEnabled(), openCreate(), openNoCreate(), and setFilesecurity().

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

crypt/file.h
crypt/file.cc

YAPET::File Class Reference

Classes

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation