YAPET::File Class Reference

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

#include <file.h>

List of all members.

Classes

struct  DWORD
 A 32 bits double word. More...
union  ENDIAN
 Used for little-big endian conversion. More...
struct  WORD
 A 16 bits word. More...

Public Member Functions

 File (const File &f) throw (YAPETException)
 File (const std::string &fn, const Key &key, bool create=false) throw (YAPETException)
 Constructor.
std::string getFilename () const
 Returns the file name of the current file.
time_t getMasterPWSet (const Key &key) const throw (YAPETException,YAPETInvalidPasswordException)
const Fileoperator= (const File &f) throw (YAPETException)
 Returns the time the master password was set.
std::list< PartDecread (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 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.
bool isempty () const throw (YAPETException)
 Indicates whether or not the file is empty.
BDBufferread () const throw (YAPETException)
 Reads from the current offset in the file.
BDBufferreadHeader () const throw (YAPETException)
 Reads the encrypted header.
void seekDataSection () const throw (YAPETException)
 Seeks to the first password record length indicator in the file.
uint32_t uint32_from_disk (uint32_t i) const
 The given integer will be converted to the endianess of the host.
uint32_t uint32_from_disk (uint32_t i) const
 The given integer will be converted to the endianess of the host.
uint32_t uint32_to_disk (uint32_t i) const
 The given integer will be converted to big endian format.
uint32_t uint32_to_disk (uint32_t i) const
 The given integer will be converted to big endian format.
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 > &header, const Key &key) throw (YAPETException)
 Writes the given header encrypted to the file.

Private Member Functions

time_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.

Private Attributes

int fd
 The file descriptor of the password file.
std::string filename
 The file name of the file.
time_t mtime
 The modification time of the file.


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. 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)     |
+--------+--------+--------+

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.

See also:
Record, FileHeader, PasswordRecord

Definition at line 159 of file file.h.


Constructor & Destructor Documentation

File::File ( const std::string &  fn,
const Key key,
bool  create = false 
) 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.

Definition at line 566 of file file.cc.

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

Duplicates the file descriptor by calling dup().

Definition at line 583 of file file.cc.

File::~File (  ) 

Closes the file.

Definition at line 595 of file file.cc.

References fd.


Member Function Documentation

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

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

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

Parameters:
key the key used to decrypt the header.
Returns:
a time_t representing the time the master password was set.

Definition at line 731 of file file.cc.

References YAPET::Crypt::decrypt(), and YAPET::FileHeader::pwset.

Referenced by MainWindow::bottomRightWinContent().

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

Creates a header struct FileHeader 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 382 of file file.cc.

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

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 363 of file file.cc.

References fd.

time_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 132 of file file.cc.

References fd.

Referenced by preparePWSave().

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. It is created with only the user having read-write access.

Definition at line 107 of file file.cc.

References fd, and filename.

Referenced by preparePWSave().

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 119 of file file.cc.

References fd, and filename.

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

Definition at line 761 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 175 of file file.cc.

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

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 630 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 270 of file file.cc.

References fd, filename, and uint32_from_disk().

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

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 480 of file file.cc.

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

Referenced by preparePWSave().

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 607 of file file.cc.

Referenced by MainWindow::saveFile().

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 161 of file file.cc.

Referenced by readHeader(), and seekDataSection().

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 149 of file file.cc.

Referenced by seekDataSection().

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 198 of file file.cc.

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

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 667 of file file.cc.

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

Referenced by MainWindow::changePassword().

uint32_t YAPET::File::uint32_from_disk ( uint32_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 269 of file file.h.

uint32_t File::uint32_from_disk ( uint32_t  i  )  const [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 247 of file file.cc.

References uint32_to_disk().

Referenced by read(), and seekDataSection().

uint32_t YAPET::File::uint32_to_disk ( uint32_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 32 bits integer in big-endian format.

Definition at line 256 of file file.h.

uint32_t File::uint32_to_disk ( uint32_t  i  )  const [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 32 bits integer in big-endian format.

Definition at line 223 of file file.cc.

References YAPET::File::File::WORD::a, YAPET::File::File::DWORD::a, YAPET::File::File::ENDIAN::abcd, YAPET::File::File::WORD::b, YAPET::File::File::DWORD::b, and YAPET::File::File::ENDIAN::dword.

Referenced by uint32_from_disk().

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

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 513 of file file.cc.

References YAPET::FileHeader::control, CONTROL_STR, YAPET::Crypt::decrypt(), 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 326 of file file.cc.

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 451 of file file.cc.

References RECOG_STR.

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

Encrypts and writes the file header provided to the file.

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 421 of file file.cc.

References YAPET::Crypt::encrypt().

Referenced by preparePWSave().


Member Data Documentation

int YAPET::File::fd [private]

The file descriptor of the password file.

Definition at line 166 of file file.h.

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

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

The file name of the file.

Definition at line 172 of file file.h.

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

time_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.

Definition at line 182 of file file.h.

Referenced by preparePWSave().


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

Generated on Mon Apr 13 17:29:48 2009 for YAPET by  doxygen 1.5.8